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 * 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 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 49 typedef struct stdio_driver stdio_driver_t; 50 51 /*! \brief Initialize all of the present standard stdio types that are linked into the binary. 52 * \ingroup pico_stdio 53 * 54 * Call this method once you have set up your clocks to enable the stdio support for UART, USB 55 * and semihosting based on the presence of the respective libraries in the binary. 56 * 57 * When stdio_usb is configured, this method can be optionally made to block, waiting for a connection 58 * via the variables specified in \ref stdio_usb_init (i.e. \ref PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS) 59 * 60 * \return true if at least one output was successfully initialized, false otherwise. 61 * \see stdio_uart, stdio_usb, stdio_semihosting 62 */ 63 bool stdio_init_all(void); 64 65 /*! \brief Flushes any buffered output. 66 * \ingroup pico_stdio 67 */ 68 void stdio_flush(void); 69 70 /*! \brief Return a character from stdin if there is one available within a timeout 71 * \ingroup pico_stdio 72 * 73 * \param timeout_us the timeout in microseconds, or 0 to not wait for a character if none available. 74 * \return the character from 0-255 or PICO_ERROR_TIMEOUT if timeout occurs 75 */ 76 int getchar_timeout_us(uint32_t timeout_us); 77 78 /*! \brief Adds or removes a driver from the list of active drivers used for input/output 79 * \ingroup pico_stdio 80 * 81 * \note this method should always be called on an initialized driver and is not re-entrant 82 * \param driver the driver 83 * \param enabled true to add, false to remove 84 */ 85 void stdio_set_driver_enabled(stdio_driver_t *driver, bool enabled); 86 87 /*! \brief Control limiting of output to a single driver 88 * \ingroup pico_stdio 89 * 90 * \note this method should always be called on an initialized driver 91 * 92 * \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). 93 * if NULL then all enabled drivers will be used 94 */ 95 void stdio_filter_driver(stdio_driver_t *driver); 96 97 /*! \brief control conversion of line feeds to carriage return on transmissions 98 * \ingroup pico_stdio 99 * 100 * \note this method should always be called on an initialized driver 101 * 102 * \param driver the driver 103 * \param translate If true, convert line feeds to carriage return on transmissions 104 */ 105 void stdio_set_translate_crlf(stdio_driver_t *driver, bool translate); 106 107 /*! \brief putchar variant that skips any CR/LF conversion if enabled 108 * \ingroup pico_stdio 109 */ 110 int putchar_raw(int c); 111 112 /*! \brief puts variant that skips any CR/LF conversion if enabled 113 * \ingroup pico_stdio 114 */ 115 int puts_raw(const char *s); 116 117 /*! \brief get notified when there are input characters available 118 * \ingroup pico_stdio 119 * 120 * \param fn Callback function to be called when characters are available. Pass NULL to cancel any existing callback 121 * \param param Pointer to pass to the callback 122 */ 123 void stdio_set_chars_available_callback(void (*fn)(void*), void *param); 124 125 #ifdef __cplusplus 126 } 127 #endif 128 129 #endif 130