eLua platform interface - UART

Overview

This part of the platform interface groups functions related to the UART interface(s) of the MCU.

Data structures, constants and types

// Parity
enum
{
  PLATFORM_UART_PARITY_EVEN,
  PLATFORM_UART_PARITY_ODD,
  PLATFORM_UART_PARITY_NONE
};

Constants used to specify the UART parity mode.

// Stop bits
enum
{
  PLATFORM_UART_STOPBITS_1,
  PLATFORM_UART_STOPBITS_1_5,
  PLATFORM_UART_STOPBITS_2
};

Constants used to specify the number of UART stop bits.

// "Infinite timeout" constant for recv
#define PLATFORM_UART_INFINITE_TIMEOUT        (-1)

This constant is used as a special timeout value (infinite timeout) in the UART functions that expect a timeout as argument.

// Virtual UART IDs
#define SERMUX_SERVICE_ID_FIRST  0xD0
#define SERMUX_SERVICE_ID_LAST   0xD7

If virtual UART support is enabled these constants define the IDs of the virtual UARTs in the system (defined in inc/sermux.h).

// Flow control type
#define PLATFORM_UART_FLOW_NONE               0
#define PLATFORM_UART_FLOW_RTS                1
#define PLATFORM_UART_FLOW_CTS                2

Used to set the flow control type on a serial interface. These constans can be ORed together (PLATFORM_UART_FLOW_RTS | PLATFORM_UART_FLOW_CTS)

Functions

platform_uart_exists platform_uart_setup platform_uart_send platform_s_uart_send platform_uart_recv platform_s_uart_recv platform_uart_set_buffer platform_uart_set_flow_control platform_s_uart_set_flow_control

int platform_uart_exists( unsigned id );

Checks if the platform has the hardware UART specified as argument. Implemented in src/common.c, it uses the NUM_UART macro that must be defined in the platform's platform_conf.h file (see here for details). For example:

#define NUM_UART   2      // The platform has 2 UART interfaces

Arguments: id - UART interface ID

Returns: 1 if the specified UART exists, 0 otherwise

u32 platform_uart_setup( unsigned id, u32 baud, int databits, int parity, int stopbits );

This function is used to initialize the parameters of the UART interface.

Arguments:

Returns: the actual baud rate. Depending on the hardware, this may have a different value than the baud argument.

void platform_uart_send( unsigned id, u8 data );

Send data to an UART interface. This is a blocking operation (it doesn't return until the data was sent).
This function is "split" in two parts: a platform-independent part that is implemented in src/common.c and a platform-dependent part that must be implemented by each platform in a function named platform_s_uart_send.

Arguments:

  • id - UART interface ID.
  • data - data to be sent.

Returns: nothing.

void platform_s_uart_send( unsigned id, u8 data );

This is the platform-dependent part of platform_uart_send. It doesn't need to take care of virtual UARTs or other system configuration parameters, it just needs to instruct the CPU to send the data on the specified ID. This function will always be called with a physical uart ID.

Arguments:

  • id - UART interface ID.
  • data - data to be sent.

Returns: nothing.

int platform_uart_recv( unsigned id, unsigned timer_id, s32 timeout );

Receive data from the UART interface (blocking/non blocking with timeout/immediate).
This function is "split" in two parts: a platform-independent part that is implemented in src/common.c and a platform-dependent part that must be implemented by each platform in a function named platform_s_uart_recv.

Arguments:

  • id - UART interface ID.
  • timer_id - the ID of the timer used in this operation (see here for details). See also the description of the timeout argument.
  • timeout - specifies a timeout for the receive operation as follows:
    • timeout > 0: the timer with the specified timer_id will be used to timeout the receive operation after timeout microseconds.
    • timeout = 0: the function returns immediately regardless of data being available or not. timer_id is ignored.
    • timeout = PLATFORM_UART_INFINITE_TIMEOUT: the function waits indefinitely for UART data to be available and returns it. In this mode the function doesn't time out, so timer_id is ignored.

Returns:

  • if timeout > 0 and data from the UART is available in timeout microseconds of less it is returned, otherwise -1 is returned
  • if timeout = 0 and data from the UART is available when the function is called it is returned, otherwise -1 is returned
  • if timeout = PLATFORM_UART_INIFINITE_TIMEOUT it returns the data read from the UART after it becomes available

int platform_s_uart_recv( unsigned id, s32 timeout );

This is the platform-dependent part of the UART receive function platform_uart_recv and is in fact a "subset" of the full function (thus being easier to implement by each platform in part). In particular, it never needs to deal with the timeout > 0 case, which is handled by platform_uart_recv.

Arguments:

  • id - UART interface ID.
  • timeout - specifies a timeout for the receive operation as follows:
    • timeout = 0: the function returns immediately regardless of data being available or not.
    • timeout = PLATFORM_UART_INFINITE_TIMEOUT: the function waits indefinitely for UART data to be available and returns it.

Returns:

  • if timeout = 0 and data from the UART is available when the function is called it is returned, otherwise -1 is returned
  • if timeout = PLATFORM_UART_INIFINITE_TIMEOUT it returns the data read from the UART after it becomes available

int platform_uart_set_buffer( unsigned id, unsigned log2size );

Sets the buffer for the specified UART. This function is fully implemented in src/common.c.

Arguments:

  • id - UART interface ID.
  • data - the base 2 logarithm of the buffer size or 0 to disable buffering on the UART. Note that disabling buffering on a virtual UART is an invalid operation.

Returns: PLATFORM_OK if the operation succeeded, PLATFORM_ERR otherwise.

int platform_uart_set_flow_control( unsigned id, int type );

Sets the flow control type.
This function is "split" in two parts: a platform independent part that is implemented in src/common.c and a platform-dependent part that must be implemented by each platform in a function named platform_s_uart_set_flow_control.

Arguments:

  • id - UART interface ID.
  • type - the desired flow control. It can be either PLATFORM_UART_FLOW_NONE, PLATFORM_UART_FLOW_RTS or PLATFORM_UART_FLOW_CTS or a bitwise combination of these constants (see here for details).

Returns: PLATFORM_OK if the operation succeeded, PLATFORM_ERR otherwise.

int platform_s_uart_set_flow_control( unsigned id, int type );

This is the platform-dependent part of the UART set flow control function platform_uart_set_flow_control and is in fact a "subset" of the full function (thus being easier to implement by each platform in part). In particular, it never needs to deal with virtual UARTs.

Arguments:

  • id - UART interface ID.
  • type - the desired flow control. It can be either PLATFORM_UART_FLOW_NONE, PLATFORM_UART_FLOW_RTS or PLATFORM_UART_FLOW_CTS or a bitwise combination of these constants (see here for details).

Returns: PLATFORM_OK if the operation succeeded, PLATFORM_ERR otherwise.