 |
Retarget IO
|
|
Retarget IO
|
Redirects standard input/output (printf / scanf) to a UART port or any custom I/O backend.
The library selects the appropriate initialization function based on the active build configuration. Only one interface mode can be active at a time. The HAL mode is determined automatically by the device package in the BSP: HAL v3 sets COMPONENT_MTB_HAL; HAL v2 sets CY_USING_HAL. These are not manually configurable.
| Function | Available When | Description |
|---|---|---|
| cy_retarget_io_init(mtb_hal_uart_t*) | HAL v3 (COMPONENT_MTB_HAL) | Initialize with a pre-initialized HAL UART object |
| cy_retarget_io_init(tx, rx, baud) | HAL v2 (CY_USING_HAL) | Macro: calls cy_retarget_io_init_fc with NC for CTS/RTS |
| cy_retarget_io_init_fc | HAL v2 (CY_USING_HAL) | Initialize with optional flow control pins |
| cy_retarget_io_init_hal | HAL v2 (CY_USING_HAL) | Initialize using pre-set cy_retarget_io_uart_obj |
| cy_retarget_io_init(CySCB_Type*) | PDL-only | Initialize with a pre-initialized SCB UART peripheral |
| cy_retarget_io_deinit | All | Release the retarget-io interface |
| cy_retarget_io_is_tx_active | All | Check whether TX is pending |
| cy_retarget_io_change_baud_rate | HAL v3 (COMPONENT_MTB_HAL) | Change baud rate at runtime |
| cy_retarget_io_getchar | COMPONENT_RETARGET_IO_CUSTOM | Application-provided: read a character |
| cy_retarget_io_putchar | COMPONENT_RETARGET_IO_CUSTOM | Application-provided: write a character |
| #define CY_RETARGET_IO_RSLT_NULL_UART_PTR (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_RETARGET_IO, 0)) |
Error code returned when a null pointer is passed as a UART parameter.
This result code is returned by the initialization functions when a NULL pointer is supplied where a valid UART object pointer is required.
| #define CY_RETARGET_IO_BAUDRATE (115200) |
Default UART baud rate used by the retarget-io library (115200).
This value can be passed directly to the initialization functions as the baudrate parameter when the default baud rate is acceptable.
| #define cy_retarget_io_init | ( | tx, | |
| rx, | |||
| baudrate ) |
Convenience wrapper macro for simplified UART initialization without flow control.
Available in: HAL v2 mode (CY_USING_HAL, set automatically by the device package)
This macro calls cy_retarget_io_init_fc() with NC (not connected) values for CTS and RTS pins, providing a simpler interface when flow control is not needed.
| tx | UART TX pin, if no TX pin use NC |
| rx | UART RX pin, if no RX pin use NC |
| baudrate | UART baudrate |
| #define CY_RETARGET_IO_CONVERT_LF_TO_CRLF |
Defining this macro enables conversion of line feed (LF) into carriage return followed by line feed (CR & LF) on the output direction (STDOUT).
You can define this macro through the DEFINES variable in the application Makefile.
| cy_rslt_t cy_retarget_io_init | ( | mtb_hal_uart_t * | obj | ) |
UART HAL object used by this library.
defined(COMPONENT_MTB_HAL)
Initialization function for redirecting low level IO commands to allow sending messages over a UART interface. This will setup the communication interface to allow using printf and related functions.
Available in: HAL v3 mode (COMPONENT_MTB_HAL, set automatically by the device package)
Users of the library must do the following before invoking the init function
In an RTOS environment, this function must be called after the RTOS has been initialized.
| obj | Pointer to the pre-initialized HAL UART object |
| cy_rslt_t cy_retarget_io_init_fc | ( | cyhal_gpio_t | tx, |
| cyhal_gpio_t | rx, | ||
| cyhal_gpio_t | cts, | ||
| cyhal_gpio_t | rts, | ||
| uint32_t | baudrate ) |
Initialization function for redirecting low level IO commands to allow sending messages over a UART interface with flow control.
This will setup the communication interface to allow using printf and related functions.
Available in: HAL v2 mode (CY_USING_HAL, set automatically by the device package)
In an RTOS environment, this function must be called after the RTOS has been initialized.
| tx | UART TX pin, if no TX pin use NC |
| rx | UART RX pin, if no RX pin use NC |
| cts | UART CTS pin, if no CTS pin use NC |
| rts | UART RTS pin, if no RTS pin use NC |
| baudrate | UART baudrate |
| cy_rslt_t cy_retarget_io_init_hal | ( | void | ) |
Initialization function for redirecting low level IO commands to allow sending messages over a UART interface with a configurator generated configuration struct.
This will setup the communication interface to allow using printf and related functions.
Available in: HAL v2 mode (CY_USING_HAL, set automatically by the device package)
This function assumes that you've already initialized cy_retarget_io_uart_obj using some other mechanism.
In an RTOS environment, this function must be called after the RTOS has been initialized.
| cy_rslt_t cy_retarget_io_init | ( | CySCB_Type * | uart | ) |
Initialization function for redirecting low level IO commands to allow sending messages over a UART interface with a configurator generated configuration struct.
This will setup the communication interface to allow using printf and related functions.
Available in: PDL-only mode (when neither COMPONENT_MTB_HAL (HAL v3), nor CY_USING_HAL (HAL v2) is defined)
This function assumes that you've already 1) initialized, and 2) enabled the UART instance using PDL function calls.
When not using the HAL, retarget-io is not thread safe. Consider using printf from a single thread or using a mutex to protect the printf calls.
| uart | Pointer to UART object, usually named and defined in device-configurator. |
| bool cy_retarget_io_is_tx_active | ( | void | ) |
| void cy_retarget_io_deinit | ( | void | ) |
| cy_rslt_t cy_retarget_io_getchar | ( | char * | c | ) |
Provide custom implementation for reading characters via stdin. When retarget-io is configured to use a custom interface, this function must be implemented by the application. Blocks indefinitely until a character is available.
| c | Character received from input stream |
| cy_rslt_t cy_retarget_io_putchar | ( | char | c | ) |
Provide custom implementation for writing characters via stdout. When retarget-io is configured to use a custom interface, this function must be implemented by the application. Blocks indefinitely until the character is able to be sent.
| c | Character from printf to be written to output stream |
| cy_rslt_t cy_retarget_io_change_baud_rate | ( | uint32_t | baud_rate, |
| uint32_t * | actual_baud ) |
Changes the UART baud rate for the retarget-io interface.
This function allows dynamic baud rate changes during runtime using the HAL v3 (MTB-HAL) framework. It operates on the UART object that was previously initialized with cy_retarget_io_init(), so no UART object parameter is needed.
The function uses the HAL v3 (MTB-HAL) baud rate setting capability to automatically determine and configure the optimal peripheral clock divider and oversample values required to achieve the target baud rate with minimal error. This leverages the HAL's built-in expertise for accurate baud rate configuration across different hardware platforms.
COMPONENT_MTB_HAL to be defined (HAL v3, set automatically by the device package). It is not available when using HAL v2 (CY-HAL) or PDL-only configurations. | baud_rate | Desired baud rate (e.g., 9600, 115200, 230400) |
| actual_baud | Pointer to store the actual baud rate achieved by the hardware, or NULL if the actual baud rate is not needed |