Line data    Source code

       1            0 : /*
       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            1 : 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            1 : 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            1 : 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            1 : 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            1 : 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            1 : 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            1 : char *console_getline(void);
     112              : 
     113              : #ifdef __cplusplus
     114              : }
     115              : #endif
     116              : 
     117              : /**
     118              :  * @}
     119              :  */
     120              : 
     121              : #endif /* ZEPHYR_INCLUDE_CONSOLE_CONSOLE_H_ */