@CHIP-RTOS C Library - Fossil API

Header File: #include <FOSSIL.H>

Here is the API definition for access to the serial ports.

The @Chip-RTOS offers the Fossil API for serial port communication. The Fossil standard uses software interrupt 0x14. These functions provide access to the @Chip-RTOS internal serial port driver for receiving and sending data via the serial ports.

Here is a short description how the @Chip-RTOS internal serial port driver operates:

Each serial port has two software buffers (queues), one for data pending transmission and one for storing received data bytes. The default size of each queue is 1024 bytes. The size of these transmit and receive queues are configurable via CHIP.INI entries.

Transfers between these software queues and the serial port hardware are carried out by either Direct Memory Access (DMA) hardware or by hardware interrupt (IRQ) driven software. By default, the available DMA machines are applied to the serial port receivers. This configuration reduces the likelihood of character loss at the receiver. This leaves the serial port transmitters operating with hardware interrupt (IRQ) driven software. Alternately, receivers can be configured for interrupt driven mode (IRQ receive mode) with the CHIP.INI options, which frees up the DMA device for other usage. The DMA can be applied to transmitters with the SERIAL SEND_DMA option.

The serial port hardware issues a signal to either software (IRQ hardware interrupt) or to the DMA when ever the serial port transmit register is empty or a receiver byte is ready. This signal initiates the next byte transfer between the appropriate software queue and the hardware register, in or out. (This discussion is slightly over simplified. The driver actually uses an additional intermediate RAM buffer for DMA transfers.)

Note that the serial port hardware send/receive buffers are only one byte (four bytes) deep on the SC1x (SC1x3/SC2x). So interrupt driven receivers (as opposed to DMA driven) can easily lose characters, particularly at higher baud rates.

The serial ports may also be referred to as a UART (abbreviation for "Universal Asynchronous Receiver/Transmitter").

For some useful comments see Programming notes

Configuration Transmitter Receiver External Port

Configuration Functions

fossil_init Initialize the fossil driver
fossil_deinit Deinitialize fossil driver
fossil_setbaud Set baud rate
fossil_setbaud_std Set baud rate to standard rates
fossil_set_extctrl Deprecated! Extended line control initialization
fossil_set_flowcontrol Enable/disable flow control
fossil_force_rts Force RTS signal
fossil_read_cts Read CTS signal
fossil_user_callback Install a Fossil User Callback Function
-- Status Functions --
fossil_status_request
Get port status
fossil_get_driver_info Get driver info
fossil_get_bytes_in_uart Report number of bytes in UART transmit hardware buffers.
-- RS-485 Control --
fossil_set_rs485
Enable/Disable RS485 mode
fossil_set_rs485_txenable Select RS485 pin

Transmitter Functions

fossil_putbyte_wait Put byte in output buffer, wait if needed
fossil_putbyte Put byte in output buffer (without wait)
fossil_writeblock Write a block of data
fossil_flush_output Await empty transmit buffer
fossil_purge_output Purge output buffer
fossil_send_break Send break
fossil_enable_transmitter Enable/Disable transmitter

Receiver Functions

fossil_getbyte_wait Get byte from input buffer (with wait)
fossil_getbyte Get byte from input buffer (no wait)
fossil_peek_input Peek if next byte is available
fossil_readblock Read block of data
fossil_purge_input Purge input buffer
fossil_enable_receiver Enable/Disable receiver

External Port Functions

fossil_register_external_port Register an external port
fossil_unregister_external_port Unregister an external port

List of C Libraries
@CHIP-RTOS Main Index

End of document