@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_initInitialize the fossil driver
fossil_deinitDeinitialize fossil driver
fossil_setbaudSet baud rate
fossil_setbaud_stdSet baud rate to standard rates
fossil_set_extctrlDeprecated! Extended line control initialization
fossil_set_flowcontrolEnable/disable flow control
fossil_force_rtsForce RTS signal
fossil_read_ctsRead CTS signal
fossil_user_callbackInstall a Fossil User Callback Function
     -- Status Functions --

Get port status
fossil_get_driver_infoGet driver info
fossil_get_bytes_in_uartReport number of bytes in UART transmit hardware buffers.
     -- RS-485 Control --

Enable/Disable RS485 mode
fossil_set_rs485_txenableSelect RS485 pin

Transmitter Functions

fossil_putbyte_waitPut byte in output buffer, wait if needed
fossil_putbytePut byte in output buffer (without wait)
fossil_writeblockWrite a block of data
fossil_flush_outputAwait empty transmit buffer
fossil_purge_outputPurge output buffer
fossil_send_breakSend break
fossil_enable_transmitterEnable/Disable transmitter
fossil_output_doneCheck for empty transmitter

Receiver Functions

fossil_getbyte_waitGet byte from input buffer (with wait)
fossil_getbyteGet byte from input buffer (no wait)
fossil_peek_inputPeek if next byte is available
fossil_readblockRead block of data
fossil_purge_inputPurge input buffer
fossil_enable_receiverEnable/Disable receiver
fossil_data_availCheck for data available

External Port Functions

fossil_register_external_portRegister an external port
fossil_register_external_port_extRegister an external port (extended)
fossil_unregister_external_portUnregister an external port

List of C Libraries
@CHIP-RTOS Main Index

End of document