source: rtems/cpukit/include/rtems/printer.h @ b2ed712

5
Last change on this file since b2ed712 was b2ed712, checked in by Sebastian Huber <sebastian.huber@…>, on 08/25/17 at 08:58:58

Include missing <string.h>

Update #2133.

  • Property mode set to 100644
File size: 5.7 KB
Line 
1/**
2 * @file rtems/print.h
3 *
4 * @brief User print interface to the bspIO print plug in.
5 *
6 * This include file defines the user interface to kernel print methods.
7 */
8
9/*
10 *  Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
11 *  All rights reserved.
12 *
13 *  The license and distribution terms for this file may be
14 *  found in the file LICENSE in this distribution or at
15 *  http://www.rtems.org/license/LICENSE.
16 */
17
18#ifndef _RTEMS_PRINTER_H
19#define _RTEMS_PRINTER_H
20
21#include <rtems/print.h>
22#include <rtems/chain.h>
23#include <rtems/rtems/intr.h>
24#include <rtems/rtems/tasks.h>
25
26#include <stdio.h>
27#include <string.h>
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33/**
34 * @addtogroup XXX
35 *
36 * @{
37 */
38
39/**
40 * @defgroup RTEMSPrintSupport
41 */
42
43/**
44 * Type definition for function which can be plugged in to certain reporting
45 * routines to redirect the output.
46 *
47 * Use the RTEMS Print interface to call these functions. Do not directly use
48 * them.
49 *
50 * If the user provides their own printer, then they may redirect those reports
51 * as they see fit.
52 */
53typedef int (*rtems_print_printer)(void *, const char *format, va_list ap);
54
55/**
56 * Type definition for the printer structure used to access the kernel print
57 * support.
58 */
59struct rtems_printer {
60  void                *context;
61  rtems_print_printer  printer;
62};
63
64/**
65 * @brief check if the printer is valid.
66 *
67 * @param[in] printer Pointer to the printer structure.
68 *
69 * @return true The printer is valid else false is returned.
70 */
71static inline bool rtems_print_printer_valid(const rtems_printer *printer)
72{
73  return printer != NULL && printer->printer != NULL;
74}
75
76/**
77 * @brief Initializes the rtems_printer struct to empty.
78 *
79 * An empty printer prints nothing. You can use this to implement an enable and
80 * disable type print implementation.
81 *
82 * @param[in] printer Pointer to the printer structure.
83 */
84static inline void rtems_print_printer_empty(rtems_printer *printer)
85{
86  printer->context = NULL;
87  printer->printer = NULL;
88}
89
90/**
91 * @brief Initializes the rtems_printer struct to printk
92 *
93 * The printer will output to the kernel printk support.
94 *
95 * @param[in] printer Pointer to the printer structure.
96 */
97void rtems_print_printer_printk(rtems_printer *printer);
98
99/**
100 * @brief Initializes the rtems_printer struct to printf
101 *
102 * The printer will output to the libc printf support.
103 *
104 * @param[in] printer Pointer to the printer structure.
105 */
106extern void rtems_print_printer_printf(rtems_printer *printer);
107
108/**
109 * @brief Initializes the rtems_printer struct to a fprintf device.
110 *
111 * The printer will output to the libc fprintf file provided.
112 *
113 * @param[in] printer Pointer to the printer structure.
114 */
115extern void rtems_print_printer_fprintf(rtems_printer *printer, FILE *file);
116
117typedef struct {
118  rtems_id                     task;
119  RTEMS_INTERRUPT_LOCK_MEMBER( lock )
120  rtems_chain_control          free_buffers;
121  rtems_chain_control          todo_buffers;
122  size_t                       task_stack_size;
123  rtems_task_priority          task_priority;
124  int                          fd;
125  void                        *buffer_table;
126  size_t                       buffer_count;
127  size_t                       buffer_size;
128} rtems_printer_task_context;
129
130static inline void rtems_printer_task_initialize(
131  rtems_printer_task_context *context
132)
133{
134  memset( context, 0, sizeof( *context ) );
135}
136
137static inline void rtems_printer_task_set_stack_size(
138  rtems_printer_task_context *context,
139  size_t                    stack_size
140)
141{
142  context->task_stack_size = stack_size;
143}
144
145static inline void rtems_printer_task_set_priority(
146  rtems_printer_task_context *context,
147  rtems_task_priority       priority
148)
149{
150  context->task_priority = priority;
151}
152
153static inline void rtems_printer_task_set_file_descriptor(
154  rtems_printer_task_context *context,
155  int                       fd
156)
157{
158  context->fd = fd;
159}
160
161static inline void rtems_printer_task_set_buffer_table(
162  rtems_printer_task_context *context,
163  void                     *buffer_table
164)
165{
166  context->buffer_table = buffer_table;
167}
168
169static inline void rtems_printer_task_set_buffer_count(
170  rtems_printer_task_context *context,
171  size_t                    buffer_count
172)
173{
174  context->buffer_count = buffer_count;
175}
176
177static inline void rtems_printer_task_set_buffer_size(
178  rtems_printer_task_context *context,
179  size_t                    buffer_size
180)
181{
182  context->buffer_size = buffer_size;
183}
184
185/**
186 * @brief Creates a printer task.
187 *
188 * Print requests via rtems_printf() or rtems_vprintf() using a printer task
189 * printer are output to a buffer and then placed on a work queue in FIFO
190 * order.  The work queue is emptied by the printer task.  The printer task
191 * writes the buffer content to the file descriptor specified by the context.
192 * Buffers are allocated from a pool of buffers as specified by the context.
193 *
194 * @param[in] printer Pointer to the printer structure.
195 * @param[in] context The initialized printer task context.
196 *
197 * @retval 0 Successful operation.
198 * @retval EINVAL Invalid context parameters.
199 * @retval ENOMEM Not enough resources.
200 */
201int rtems_print_printer_task(
202  rtems_printer              *printer,
203  rtems_printer_task_context *context
204);
205
206/**
207 * @brief Drains the work queue of the printer task.
208 *
209 * Waits until all output buffers in the work queue at the time of this
210 * function call are written to the file descriptor and an fsync() completed.
211 *
212 * The printer task must be successfully started via rtems_print_printer_task()
213 * before this function can be used.  Otherwise, the behaviour is undefined.
214 *
215 * @param[in] context The printer task context of a successfully started
216 *   printer task.
217 */
218void rtems_printer_task_drain(rtems_printer_task_context *context);
219
220/** @} */
221
222#ifdef __cplusplus
223}
224#endif
225
226#endif /* _RTEMS_PRINTER_H */
Note: See TracBrowser for help on using the repository browser.