1 /*
2  * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef _PICO_STDIO_H
8 #define _PICO_STDIO_H
9 
10 /** \file stdio.h
11 *  \defgroup pico_stdio pico_stdio
12 * \brief Customized stdio support allowing for input and output from UART, USB, semi-hosting etc
13 *
14 * Note the API for adding additional input output devices is not yet considered stable
15 */
16 
17 #include "pico.h"
18 
19 // PICO_CONFIG: PICO_STDOUT_MUTEX, Enable/disable mutex around stdout, type=bool, default=1, group=pico_stdio
20 #ifndef PICO_STDOUT_MUTEX
21 #define PICO_STDOUT_MUTEX 1
22 #endif
23 
24 // PICO_CONFIG: PICO_STDIO_ENABLE_CRLF_SUPPORT, Enable/disable CR/LF output conversion support, type=bool, default=1, group=pico_stdio
25 #ifndef PICO_STDIO_ENABLE_CRLF_SUPPORT
26 #define PICO_STDIO_ENABLE_CRLF_SUPPORT 1
27 #endif
28 
29 // PICO_CONFIG: PICO_STDIO_DEFAULT_CRLF, Default for CR/LF conversion enabled on all stdio outputs, type=bool, default=1, depends=PICO_STDIO_ENABLE_CRLF_SUPPORT, group=pico_stdio
30 #ifndef PICO_STDIO_DEFAULT_CRLF
31 #define PICO_STDIO_DEFAULT_CRLF 1
32 #endif
33 
34 // PICO_CONFIG: PICO_STDIO_STACK_BUFFER_SIZE, Define printf buffer size (on stack)... this is just a working buffer not a max output size, min=0, max=512, default=128, group=pico_stdio
35 #ifndef PICO_STDIO_STACK_BUFFER_SIZE
36 #define PICO_STDIO_STACK_BUFFER_SIZE 128
37 #endif
38 
39 // PICO_CONFIG: PICO_STDIO_DEADLOCK_TIMEOUT_MS, Time after which to assume stdio_usb is deadlocked by use in IRQ and give up, type=int, default=1000, group=pico_stdio
40 #ifndef PICO_STDIO_DEADLOCK_TIMEOUT_MS
41 #define PICO_STDIO_DEADLOCK_TIMEOUT_MS 1000
42 #endif
43 
44 // PICO_CONFIG: PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS, Directly replace common stdio functions such as putchar from the C-library to avoid pulling in lots of c library code for simple output, type=bool, default=1, advanced=true, group=pico_stdio
45 #ifndef PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS
46 #define PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS 1
47 #endif
48 
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52 
53 #include <stdarg.h>
54 
55 typedef struct stdio_driver stdio_driver_t;
56 
57 /*! \brief Initialize all of the present standard stdio types that are linked into the binary.
58  * \ingroup pico_stdio
59  *
60  * Call this method once you have set up your clocks to enable the stdio support for UART, USB,
61  * semihosting, and RTT based on the presence of the respective libraries in the binary.
62  *
63  * When stdio_usb is configured, this method can be optionally made to block, waiting for a connection
64  * via the variables specified in \ref stdio_usb_init (i.e. \ref PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS)
65  *
66  * \return true if at least one output was successfully initialized, false otherwise.
67  * \see stdio_uart, stdio_usb, stdio_semihosting, stdio_rtt
68  */
69 bool stdio_init_all(void);
70 
71 /*! \brief Deinitialize all of the present standard stdio types that are linked into the binary.
72  * \ingroup pico_stdio
73  *
74  * This method currently only supports stdio_uart and stdio_semihosting
75  *
76  * \return true if all outputs was successfully deinitialized, false otherwise.
77  * \see stdio_uart, stdio_usb, stdio_semihosting, stdio_rtt
78  */
79 bool stdio_deinit_all(void);
80 
81 /*! \brief Flushes any buffered output.
82  * \ingroup pico_stdio
83  */
84 void stdio_flush(void);
85 
86 /*! \brief Return a character from stdin if there is one available within a timeout
87  * \ingroup pico_stdio
88  *
89  * \param timeout_us the timeout in microseconds, or 0 to not wait for a character if none available.
90  * \return the character from 0-255 or PICO_ERROR_TIMEOUT if timeout occurs
91  */
92 int stdio_getchar_timeout_us(uint32_t timeout_us);
93 
94 /*! \brief Alias for \ref stdio_getchar_timeout_us for backwards compatibility
95  * \ingroup pico_stdio
96  */
getchar_timeout_us(uint32_t timeout_us)97 static inline int getchar_timeout_us(uint32_t timeout_us) {
98     return stdio_getchar_timeout_us(timeout_us);
99 }
100 
101 /*! \brief Adds or removes a driver from the list of active drivers used for input/output
102  * \ingroup pico_stdio
103  *
104  * \note this method should always be called on an initialized driver and is not re-entrant
105  * \param driver the driver
106  * \param enabled true to add, false to remove
107  */
108 void stdio_set_driver_enabled(stdio_driver_t *driver, bool enabled);
109 
110 /*! \brief Control limiting of output to a single driver
111  * \ingroup pico_stdio
112  *
113  * \note this method should always be called on an initialized driver
114  *
115  * \param driver if non-null then output only that driver will be used for input/output (assuming it is in the list of enabled drivers).
116  *               if NULL then all enabled drivers will be used
117  */
118 void stdio_filter_driver(stdio_driver_t *driver);
119 
120 /*! \brief control conversion of line feeds to carriage return on transmissions
121  * \ingroup pico_stdio
122  *
123  * \note this method should always be called on an initialized driver
124  *
125  * \param driver the driver
126  * \param translate If true, convert line feeds to carriage return on transmissions
127  */
128 void stdio_set_translate_crlf(stdio_driver_t *driver, bool translate);
129 
130 /*! \brief putchar variant that skips any CR/LF conversion if enabled
131  * \ingroup pico_stdio
132  */
133 int stdio_putchar_raw(int c);
134 
135 /*! \brief Alias for \ref stdio_putchar_raw for backwards compatibility
136  * \ingroup pico_stdio
137  */
putchar_raw(int c)138 static inline int putchar_raw(int c) {
139     return stdio_putchar_raw(c);
140 }
141 
142 /*! \brief puts variant that skips any CR/LF conversion if enabled
143  * \ingroup pico_stdio
144  */
145 int stdio_puts_raw(const char *s);
146 
147 /*! \brief Alias for \ref stdio_puts_raw for backwards compatibility
148  * \ingroup pico_stdio
149  */
puts_raw(const char * s)150 static inline int puts_raw(const char *s) {
151     return stdio_puts_raw(s);
152 }
153 
154 /*! \brief get notified when there are input characters available
155  * \ingroup pico_stdio
156  *
157  * \param fn Callback function to be called when characters are available. Pass NULL to cancel any existing callback
158  * \param param Pointer to pass to the callback
159  */
160 void stdio_set_chars_available_callback(void (*fn)(void*), void *param);
161 
162 /*! \brief Waits until a timeout to reard at least one character into a buffer
163  * \ingroup pico_stdio
164  *
165  * This method returns as soon as input is available, but more characters may
166  * be returned up to the end of the buffer.
167  *
168  * \param buf the buffer to read into
169  * \param len the length of the buffer
170  * \return the number of characters read or PICO_ERROR_TIMEOUT
171  * \param until the time after which to return PICO_ERROR_TIMEOUT if no characters are available
172  */
173 int stdio_get_until(char *buf, int len, absolute_time_t until);
174 
175 /*! \brief Prints a buffer to stdout with optional newline and carriage return insertion
176  * \ingroup pico_stdio
177  *
178  * This method returns as soon as input is available, but more characters may
179  * be returned up to the end of the buffer.
180  *
181  * \param s the characters to print
182  * \param len the length of s
183  * \param newline true if a newline should be added after the string
184  * \param cr_translation true if line feed to carriage return translation should be performed
185  * \return the number of characters written
186  */
187 int stdio_put_string(const char *s, int len, bool newline, bool cr_translation);
188 
189 /*! \brief stdio_getchar Alias for \ref getchar that definitely does not go thru the implementation
190  * in the standard C library even when \ref PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0
191  *
192  * \ingroup pico_stdio
193  */
194 int stdio_getchar(void);
195 
196 /*! \brief stdio_getchar Alias for \ref putchar that definitely does not go thru the implementation
197  * in the standard C library even when \ref PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0
198  *
199  * \ingroup pico_stdio
200  */
201 int stdio_putchar(int);
202 
203 /*! \brief stdio_getchar Alias for \ref puts that definitely does not go thru the implementation
204  * in the standard C library even when \ref PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0
205  *
206  * \ingroup pico_stdio
207  */
208 int stdio_puts(const char *s);
209 
210 /*! \brief stdio_getchar Alias for \ref vprintf that definitely does not go thru the implementation
211  * in the standard C library even when \ref PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0
212  *
213  * \ingroup pico_stdio
214  */
215 int stdio_vprintf(const char *format, va_list va);
216 
217 /*! \brief stdio_getchar Alias for \ref printf that definitely does not go thru the implementation
218  * in the standard C library even when \ref PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0
219  *
220  * \ingroup pico_stdio
221  */
222 int __printflike(1, 0) stdio_printf(const char* format, ...);
223 
224 #ifdef __cplusplus
225 }
226 #endif
227 
228 #endif
229