1 /* 2 * Copyright (c) 2017 Linaro Limited 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef ZEPHYR_INCLUDE_CONSOLE_CONSOLE_H_ 8 #define ZEPHYR_INCLUDE_CONSOLE_CONSOLE_H_ 9 10 #include <sys/types.h> 11 #include <zephyr/types.h> 12 #include <zephyr/kernel.h> 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** 19 * @brief Console API 20 * @defgroup console_api Console API 21 * @ingroup os_services 22 * @{ 23 */ 24 25 /** @brief Initialize console device. 26 * 27 * This function should be called once to initialize pull-style 28 * access to console via console_getchar() function and buffered 29 * output using console_putchar() function. This function supersedes, 30 * and incompatible with, callback (push-style) console handling 31 * (via console_input_fn callback, etc.). 32 * 33 * @return 0 on success, error code (<0) otherwise 34 */ 35 int console_init(void); 36 37 /** 38 * @brief Read data from console. 39 * 40 * @param dummy ignored, present to follow read() prototype 41 * @param buf buffer to read data to 42 * @param size maximum number of bytes to read 43 * @return >0, number of actually read bytes (can be less than size param) 44 * =0, in case of EOF 45 * <0, in case of error (e.g. -EAGAIN if timeout expired). errno 46 * variable is also set. 47 */ 48 ssize_t console_read(void *dummy, void *buf, size_t size); 49 50 /** 51 * @brief Write data to console. 52 * 53 * @param dummy ignored, present to follow write() prototype 54 * @param buf buffer to write data to 55 * @param size maximum number of bytes to write 56 * @return =>0, number of actually written bytes (can be less than size param) 57 * <0, in case of error (e.g. -EAGAIN if timeout expired). errno 58 * variable is also set. 59 */ 60 ssize_t console_write(void *dummy, const void *buf, size_t size); 61 62 /** @brief Get next char from console input buffer. 63 * 64 * Return next input character from console. If no characters available, 65 * this function will block. This function is similar to ANSI C 66 * getchar() function and is intended to ease porting of existing 67 * software. Before this function can be used, console_init() 68 * should be called once. This function is incompatible with native 69 * Zephyr callback-based console input processing, shell subsystem, 70 * or console_getline(). 71 * 72 * @return 0-255: a character read, including control characters. 73 * <0: error occurred. 74 */ 75 int console_getchar(void); 76 77 /** @brief Output a char to console (buffered). 78 * 79 * Puts a character into console output buffer. It will be sent 80 * to a console asynchronously, e.g. using an IRQ handler. 81 * 82 * @return <0 on error, otherwise 0. 83 */ 84 int console_putchar(char c); 85 86 /** @brief Initialize console_getline() call. 87 * 88 * This function should be called once to initialize pull-style 89 * access to console via console_getline() function. This function 90 * supersedes, and incompatible with, callback (push-style) console 91 * handling (via console_input_fn callback, etc.). 92 */ 93 void console_getline_init(void); 94 95 /** @brief Get next line from console input buffer. 96 * 97 * Return next input line from console. Until full line is available, 98 * this function will block. This function is similar to ANSI C 99 * gets() function (except a line is returned in system-owned buffer, 100 * and system takes care of the buffer overflow checks) and is 101 * intended to ease porting of existing software. Before this function 102 * can be used, console_getline_init() should be called once. This 103 * function is incompatible with native Zephyr callback-based console 104 * input processing, shell subsystem, or console_getchar(). 105 * 106 * @return A pointer to a line read, not including EOL character(s). 107 * A line resides in a system-owned buffer, so an application 108 * should finish any processing of this line immediately 109 * after console_getline() call, or the buffer can be reused. 110 */ 111 char *console_getline(void); 112 113 #ifdef __cplusplus 114 } 115 #endif 116 117 /** 118 * @} 119 */ 120 121 #endif /* ZEPHYR_INCLUDE_CONSOLE_CONSOLE_H_ */ 122
