source: rtems/cpukit/include/rtems/printer.h @ 7e86e00

5
Last change on this file since 7e86e00 was c56721c, checked in by Sebastian Huber <sebastian.huber@…>, on 09/27/18 at 05:21:27

printer: Fix Doxygen comments

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