Defined behavior

Detailed Description

Defined behavior

• serial_init initializes the serial_t
• serial_init sets the default parameters for serial peripheral (9600 bps, 8N1 format)
• serial_init configures the specified pins
• serial_free releases the serial peripheral
• serial_baud configures the baud rate
• at least 9600 bps the baud rate must be supported
• serial_format configures the transmission format (number of bits, parity and the number of stop bits)
• at least 8N1 format must be supported
• serial_irq_handler registers the interrupt handler which will be invoked when the interrupt fires.
• serial_irq_set enables or disables the serial RX or TX IRQ.
• If RxIrq is enabled by serial_irq_set, serial_irq_handler will be invoked whenever Receive Data Register Full IRQ is generated.
• If TxIrq is enabled by serial_irq_set, serial_irq_handler will be invoked whenever Transmit Data Register Empty IRQ is generated.
• If the interrupt condition holds true, when the interrupt is enabled with serial_irq_set, the serial_irq_handler is called instantly.
• serial_getc returns the character from serial buffer.
• serial_getc is a blocking call (waits for the character).
• serial_putc sends a character.
• serial_putc is a blocking call (waits for a peripheral to be available).
• serial_readable returns non-zero value if a character can be read, 0 otherwise.
• serial_writable returns non-zero value if a character can be written, 0 otherwise.
• serial_clear clears the serial_t RX/TX buffers
• serial_break_set sets the break signal.
• serial_break_clear clears the break signal.
• serial_pinout_tx configures the TX pin as an output (to be used in half-duplex mode).
• serial_set_flow_control configures serial flow control.
• serial_set_flow_control sets flow control in the hardware if a serial peripheral supports it, otherwise software emulation is used.
• serial_tx_asynch starts the serial asynchronous transfer.
• serial_tx_asynch writes tx_length bytes from the tx to the bus.
• serial_tx_asynch must support 8 data bits
• The callback given to serial_tx_asynch is invoked when the transfer completes.
• serial_tx_asynch specifies the logical OR of events to be registered.
• The serial_tx_asynch function may use the DMAUsage hint to select the appropriate async algorithm.
• serial_rx_asynch starts the serial asynchronous transfer.
• serial_rx_asynch reads rx_length bytes to the rx buffer.
• serial_rx_asynch must support 8 data bits
• The callback given to serial_rx_asynch is invoked when the transfer completes.
• serial_rx_asynch specifies the logical OR of events to be registered.
• The serial_rx_asynch function may use the DMAUsage hint to select the appropriate async algorithm.
• serial_rx_asynch specifies a character in range 0-254 to be matched, 255 is a reserved value.
• If SERIAL_EVENT_RX_CHARACTER_MATCH event is not registered, the char_match is ignored.
• The SERIAL_EVENT_RX_CHARACTER_MATCH event is set in the callback when SERIAL_EVENT_RX_CHARACTER_MATCH event is registered AND char_match is present in the received data.
• serial_tx_active returns non-zero if the TX transaction is ongoing, 0 otherwise.
• serial_rx_active returns non-zero if the RX transaction is ongoing, 0 otherwise.
• serial_irq_handler_asynch returns event flags if a transfer termination condition was met, otherwise returns 0.
• serial_irq_handler_asynch takes no longer than one packet transfer time (packet_bits / baudrate) to execute.
• serial_tx_abort_asynch aborts the ongoing TX transaction.
• serial_tx_abort_asynch disables the enabled interupt for TX.
• serial_tx_abort_asynch flushes the TX hardware buffer if TX FIFO is used.
• serial_rx_abort_asynch aborts the ongoing RX transaction.
• serial_rx_abort_asynch disables the enabled interupt for RX.
• serial_rx_abort_asynch flushes the TX hardware buffer if RX FIFO is used.
• Correct operation guaranteed when interrupt latency is shorter than one packet transfer time (packet_bits / baudrate) if the flow control is not used.
• Correct operation guaranteed regardless of interrupt latency if the flow control is used.

Undefined behavior

• Calling serial_init multiple times on the same serial_t without serial_free.
• Passing invalid pin to serial_init, serial_pinout_tx.
• Calling any function other than serial_init on am uninitialized or freed serial_t.
• Passing an invalid pointer as obj to any function.
• Passing an invalid pointer as handler to serial_irq_handler, serial_tx_asynch, serial_rx_asynch.
• Calling ::serial_tx_abort while no async TX transfer is being processed.
• Calling ::serial_rx_abort while no async RX transfer is being processed.
• Devices behavior is undefined when the interrupt latency is longer than one packet transfer time (packet_bits / baudrate) if the flow control is not used.

Function Documentation