From 169589221d994af2b301046ada72282187f445dd Mon Sep 17 00:00:00 2001 From: Anas Nashif Date: Tue, 25 Jun 2019 12:08:16 -0400 Subject: [PATCH] cleanup: include/: move console.h to console/console.h move console.h to console/console.h and create a shim for backward-compatibility. No functional changes to the headers. A warning in the shim can be controlled with CONFIG_COMPAT_INCLUDES. Related to #16539 Signed-off-by: Anas Nashif --- include/console.h | 125 +------------------- include/console/console.h | 132 ++++++++++++++++++++++ samples/subsys/console/echo/src/main.c | 2 +- samples/subsys/console/getchar/src/main.c | 2 +- samples/subsys/console/getline/src/main.c | 2 +- subsys/console/getchar.c | 2 +- subsys/console/line_fifo.c | 2 +- 7 files changed, 141 insertions(+), 126 deletions(-) create mode 100644 include/console/console.h diff --git a/include/console.h b/include/console.h index 16e04bda953..5a9d10c0353 100644 --- a/include/console.h +++ b/include/console.h @@ -1,132 +1,15 @@ /* - * Copyright (c) 2017 Linaro Limited + * Copyright (c) 2019 Intel Corporation * * SPDX-License-Identifier: Apache-2.0 */ - #ifndef ZEPHYR_INCLUDE_CONSOLE_H_ #define ZEPHYR_INCLUDE_CONSOLE_H_ -#include -#include -#include - -#ifdef __cplusplus -extern "C" { +#ifndef CONFIG_COMPAT_INCLUDES +#warning "This header file has moved, include instead." #endif -/** @brief Initialize console device. - * - * This function should be called once to initialize pull-style - * access to console via console_getchar() function and buffered - * output using console_putchar() function. This function supersedes, - * and incompatible with, callback (push-style) console handling - * (via console_input_fn callback, etc.). - * - * @return N/A - */ -void console_init(void); - -/** - * @brief Read data from console. - * - * @param dummy ignored, present to follow read() prototype - * @param buf buffer to read data to - * @param size maximum number of bytes to read - * @return >0, number of actually read bytes (can be less than size param) - * =0, in case of EOF - * <0, in case of error (e.g. -EAGAIN if timeout expired). errno - * variable is also set. - */ -ssize_t console_read(void *dummy, void *buf, size_t size); - -/** - * @brief Write data to console. - * - * @param dummy ignored, present to follow write() prototype - * @param buf buffer to write data to - * @param size maximum number of bytes to write - * @return =>0, number of actually written bytes (can be less than size param) - * <0, in case of error (e.g. -EAGAIN if timeout expired). errno - * variable is also set. - */ -ssize_t console_write(void *dummy, const void *buf, size_t size); - -/** @brief Get next char from console input buffer. - * - * Return next input character from console. If no characters available, - * this function will block. This function is similar to ANSI C - * getchar() function and is intended to ease porting of existing - * software. Before this function can be used, console_getchar_init() - * should be called once. This function is incompatible with native - * Zephyr callback-based console input processing, shell subsystem, - * or console_getline(). - * - * @return 0-255: a character read, including control characters. - * <0: error occurred. - */ -int console_getchar(void); - -/** @brief Output a char to console (buffered). - * - * Puts a character into console output buffer. It will be sent - * to a console asynchronously, e.g. using an IRQ handler. - * - * @return <0 on error, otherwise 0. - */ -int console_putchar(char c); - -/** @brief Initialize console_getline() call. - * - * This function should be called once to initialize pull-style - * access to console via console_getline() function. This function - * supersedes, and incompatible with, callback (push-style) console - * handling (via console_input_fn callback, etc.). - * - * @return N/A - */ -void console_getline_init(void); - -/** @brief Get next line from console input buffer. - * - * Return next input line from console. Until full line is available, - * this function will block. This function is similar to ANSI C - * gets() function (except a line is returned in system-owned buffer, - * and system takes care of the buffer overflow checks) and is - * intended to ease porting of existing software. Before this function - * can be used, console_getline_init() should be called once. This - * function is incompatible with native Zephyr callback-based console - * input processing, shell subsystem, or console_getchar(). - * - * @return A pointer to a line read, not including EOL character(s). - * A line resides in a system-owned buffer, so an application - * should finish any processing of this line immediately - * after console_getline() call, or the buffer can be reused. - */ -char *console_getline(void); - -/** @brief Initialize legacy fifo-based line input - * - * Input processing is started when string is typed in the console. - * Carriage return is translated to NULL making string always NULL - * terminated. Application before calling register function need to - * initialize two fifo queues mentioned below. - * - * This is a special-purpose function, it's recommended to use - * console_getchar() or console_getline() functions instead. - * - * @param avail_queue k_fifo queue keeping available line buffers - * @param out_queue k_fifo queue of entered lines which to be processed - * in the application code. - * @param completion callback for tab completion of entered commands - */ -__deprecated void console_register_line_input(struct k_fifo *avail_queue, - struct k_fifo *out_queue, - u8_t (*completion)(char *str, u8_t len)); - - -#ifdef __cplusplus -} -#endif +#include #endif /* ZEPHYR_INCLUDE_CONSOLE_H_ */ diff --git a/include/console/console.h b/include/console/console.h new file mode 100644 index 00000000000..05136ce7298 --- /dev/null +++ b/include/console/console.h @@ -0,0 +1,132 @@ +/* + * Copyright (c) 2017 Linaro Limited + * + * SPDX-License-Identifier: Apache-2.0 + */ + +#ifndef ZEPHYR_INCLUDE_CONSOLE_CONSOLE_H_ +#define ZEPHYR_INCLUDE_CONSOLE_CONSOLE_H_ + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** @brief Initialize console device. + * + * This function should be called once to initialize pull-style + * access to console via console_getchar() function and buffered + * output using console_putchar() function. This function supersedes, + * and incompatible with, callback (push-style) console handling + * (via console_input_fn callback, etc.). + * + * @return N/A + */ +void console_init(void); + +/** + * @brief Read data from console. + * + * @param dummy ignored, present to follow read() prototype + * @param buf buffer to read data to + * @param size maximum number of bytes to read + * @return >0, number of actually read bytes (can be less than size param) + * =0, in case of EOF + * <0, in case of error (e.g. -EAGAIN if timeout expired). errno + * variable is also set. + */ +ssize_t console_read(void *dummy, void *buf, size_t size); + +/** + * @brief Write data to console. + * + * @param dummy ignored, present to follow write() prototype + * @param buf buffer to write data to + * @param size maximum number of bytes to write + * @return =>0, number of actually written bytes (can be less than size param) + * <0, in case of error (e.g. -EAGAIN if timeout expired). errno + * variable is also set. + */ +ssize_t console_write(void *dummy, const void *buf, size_t size); + +/** @brief Get next char from console input buffer. + * + * Return next input character from console. If no characters available, + * this function will block. This function is similar to ANSI C + * getchar() function and is intended to ease porting of existing + * software. Before this function can be used, console_getchar_init() + * should be called once. This function is incompatible with native + * Zephyr callback-based console input processing, shell subsystem, + * or console_getline(). + * + * @return 0-255: a character read, including control characters. + * <0: error occurred. + */ +int console_getchar(void); + +/** @brief Output a char to console (buffered). + * + * Puts a character into console output buffer. It will be sent + * to a console asynchronously, e.g. using an IRQ handler. + * + * @return <0 on error, otherwise 0. + */ +int console_putchar(char c); + +/** @brief Initialize console_getline() call. + * + * This function should be called once to initialize pull-style + * access to console via console_getline() function. This function + * supersedes, and incompatible with, callback (push-style) console + * handling (via console_input_fn callback, etc.). + * + * @return N/A + */ +void console_getline_init(void); + +/** @brief Get next line from console input buffer. + * + * Return next input line from console. Until full line is available, + * this function will block. This function is similar to ANSI C + * gets() function (except a line is returned in system-owned buffer, + * and system takes care of the buffer overflow checks) and is + * intended to ease porting of existing software. Before this function + * can be used, console_getline_init() should be called once. This + * function is incompatible with native Zephyr callback-based console + * input processing, shell subsystem, or console_getchar(). + * + * @return A pointer to a line read, not including EOL character(s). + * A line resides in a system-owned buffer, so an application + * should finish any processing of this line immediately + * after console_getline() call, or the buffer can be reused. + */ +char *console_getline(void); + +/** @brief Initialize legacy fifo-based line input + * + * Input processing is started when string is typed in the console. + * Carriage return is translated to NULL making string always NULL + * terminated. Application before calling register function need to + * initialize two fifo queues mentioned below. + * + * This is a special-purpose function, it's recommended to use + * console_getchar() or console_getline() functions instead. + * + * @param avail_queue k_fifo queue keeping available line buffers + * @param out_queue k_fifo queue of entered lines which to be processed + * in the application code. + * @param completion callback for tab completion of entered commands + */ +__deprecated void console_register_line_input(struct k_fifo *avail_queue, + struct k_fifo *out_queue, + u8_t (*completion)(char *str, u8_t len)); + + +#ifdef __cplusplus +} +#endif + +#endif /* ZEPHYR_INCLUDE_CONSOLE_CONSOLE_H_ */ diff --git a/samples/subsys/console/echo/src/main.c b/samples/subsys/console/echo/src/main.c index d514f568b7a..8413909dac2 100644 --- a/samples/subsys/console/echo/src/main.c +++ b/samples/subsys/console/echo/src/main.c @@ -4,7 +4,7 @@ * SPDX-License-Identifier: Apache-2.0 */ #include -#include +#include static const char prompt[] = "Start typing characters to see them echoed back\r\n"; diff --git a/samples/subsys/console/getchar/src/main.c b/samples/subsys/console/getchar/src/main.c index c0d2397c70b..dac3709c081 100644 --- a/samples/subsys/console/getchar/src/main.c +++ b/samples/subsys/console/getchar/src/main.c @@ -6,7 +6,7 @@ #include #include -#include +#include void main(void) { diff --git a/samples/subsys/console/getline/src/main.c b/samples/subsys/console/getline/src/main.c index 8800481a797..25cfb95b287 100644 --- a/samples/subsys/console/getline/src/main.c +++ b/samples/subsys/console/getline/src/main.c @@ -7,7 +7,7 @@ #include #include #include -#include +#include void main(void) { diff --git a/subsys/console/getchar.c b/subsys/console/getchar.c index dfc771bf280..cc10a81f348 100644 --- a/subsys/console/getchar.c +++ b/subsys/console/getchar.c @@ -6,7 +6,7 @@ #include #include -#include +#include #include static struct tty_serial console_serial; diff --git a/subsys/console/line_fifo.c b/subsys/console/line_fifo.c index f75b2895fca..5146aa2d58c 100644 --- a/subsys/console/line_fifo.c +++ b/subsys/console/line_fifo.c @@ -10,7 +10,7 @@ */ #include -#include +#include #ifdef CONFIG_UART_CONSOLE #include