RTEMS: cpukit/include/rtems/stdio-redirect.h Source File

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
stdio-redirect.h
1/*
2 * Copyright (C) 2014 Chris Johns (chrisj@rtems.org)
3 *
4 * The license and distribution terms for this file may be
5 * found in the file LICENSE in this distribution.
6 *
7 * This software with is provided ``as is'' and with NO WARRANTY.
8 */
9
10/*
11 * @brief Redirect an stdio file decriptor.
12 *
13 * The is a helper module of code design to redirect an stdio file
14 * descriptor. You can optionally have the data buffered and/or you can provide
15 * a handler function that is called when data arrives.
16 *
17 * The module uses standard POSIX calls to implement the redirection and if the
18 * threading was POSIX based the code would be portable. Currently the code
19 * uses RTEMS threads.
20 *
21 * Redirecting stderr and stdout is useful in embedded system because you can
22 * transport the output off your device or create a web interface that can
23 * display the output. This can be a very powerful diagnostic and support tool.
24 *
25 * The implementation does:
26 *
27 * 1. Duplicate the file descriptor (fd) to redirect using the dup call. The
28 * duplicated desciptor is used to echo the output out the existing path.
29 *
30 * 2. Create a pipe using the pipe call.
31 *
32 * 3. Duplicate the pipe's writer file descriptor to user's file
33 * descriptor. This results in any writes to the user's fd being written to
34 * the pipe.
35 *
36 * 4. Create a reader task that blocks on the pipe. It optionally calls a
37 * handler and if configured buffers the data.
38 */
39
40#if !defined(RTEMS_STDIO_REDIRECT_H)
41#define RTEMS_STDIO_REDIRECT_H
42
43#include <stdbool.h>
44#include <rtems.h>
45#include <rtems/thread.h>
46
47#ifdef __cplusplus
48extern "C" {
49#endif /* __cplusplus */
50
51/*
52 * Handler called whenever redirected data arrives.
53 *
54 * @param buffer The data.
55 * @param length The amount of data in the buffer.
56 */
57typedef void (*rtems_stdio_redirect_handler)(const char* buffer,
58 ssize_t length);
59
60/*
61 * Redirector data.
62 */
63 typedef struct
64{
65 volatile uint32_t state;
66 rtems_id reader;
67 rtems_mutex lock;
68 int fd;
69 int fd_dup;
70 int pipe[2];
71 char* input;
72 ssize_t input_size;
73 char* buffer;
74 ssize_t buffer_size;
75 ssize_t in;
76 bool full;
77 bool echo;
78 rtems_stdio_redirect_handler handler;
79} rtems_stdio_redirect;
80
81/*
82 * Open a redirector returning the handle to it.
83 *
84 * @param fd The file descriptor to redirect.
85 * @param priority The priority of the reader thread.
86 */
87 rtems_stdio_redirect* rtems_stdio_redirect_open(int fd,
88 rtems_task_priority priority,
89 size_t stack_size,
90 ssize_t input_size,
91 ssize_t buffer_size,
92 bool echo,
93 rtems_stdio_redirect_handler handler);
94
95/*
96 * Close the redirector.
97 */
98void rtems_stdio_redirect_close(rtems_stdio_redirect* sr);
99
100/*
101 * Get data from the capture buffer. Data read is removed from the buffer.
102 *
103 * @param sr The stdio redirection handle.
104 * @param buffer The buffer data is written into.
105 * @param length The size of the buffer.
106 * @return ssize_t The amount of data written and -1 or an error.
107 */
108ssize_t rtems_stdio_redirect_read(rtems_stdio_redirect* sr,
109 char* buffer,
110 ssize_t length);
111
112#ifdef __cplusplus
113}
114#endif /* __cplusplus */
115
116#endif
rtems_task_priority
uint32_t rtems_task_priority
Definition: tasks.h:55
rtems_id
Objects_Id rtems_id
Used to manage and manipulate RTEMS object identifiers.
Definition: types.h:83
rtems.h
rtems_stdio_redirect
Definition: stdio-redirect.h:64
rtems_stdio_redirect::input
char * input
Definition: stdio-redirect.h:71
rtems_stdio_redirect::full
bool full
Definition: stdio-redirect.h:76
rtems_stdio_redirect::in
ssize_t in
Definition: stdio-redirect.h:75
rtems_stdio_redirect::echo
bool echo
Definition: stdio-redirect.h:77
rtems_stdio_redirect::lock
rtems_mutex lock
Definition: stdio-redirect.h:67
rtems_stdio_redirect::state
volatile uint32_t state
Definition: stdio-redirect.h:65
rtems_stdio_redirect::fd
int fd
Definition: stdio-redirect.h:68
rtems_stdio_redirect::input_size
ssize_t input_size
Definition: stdio-redirect.h:72
rtems_stdio_redirect::handler
rtems_stdio_redirect_handler handler
Definition: stdio-redirect.h:78
rtems_stdio_redirect::reader
rtems_id reader
Definition: stdio-redirect.h:66
rtems_stdio_redirect::fd_dup
int fd_dup
Definition: stdio-redirect.h:69
rtems_stdio_redirect::buffer
char * buffer
Definition: stdio-redirect.h:73
rtems_stdio_redirect::buffer_size
ssize_t buffer_size
Definition: stdio-redirect.h:74