Fossil API - SC12 @CHIP-RTOS V1.10
IPC@CHIP Documentation Index
Here is the API definition for access to the COM and EXT 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 two available DMA machines are applied to the two serial port receivers. This configuration reduces the likelihood of character loss at the receiver. This leaves the two 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
deep. So interrupt driven receivers (as opposed to DMA driven) can easily
lose characters, particularly at higher baud rates.
The COM / EXT serial ports may also be referred to as a UART (abbreviation for
"Universal Asynchronous Receiver/Transmitter").
For some useful comments see
Programming notes
New in version 1.10B: Install a user callback function
New in version 1.10B: Enable/Disable UART receiver
New in version 1.10B: Enable/Disable UART transmitter
Interrupt 0x14 service 0x00: Set baud rate
- Set the baud rate of the serial port
Parameters
- AH
- 0x00
- AL
- Configuration parameter.
Bits 7--5: Baud rate, 4--3: Parity, 2: Stop bits, 1--0 Word length.
Bits 7--5: Baud rate
000 19200
001 38400
010 300
011 600
100 1200
101 2400
110 4800
111 9600
Bits 4--3: Parity
00 None
01 Odd
11 Even
Bit 2: Stop bits
0: 1 Stop bit
1: 2 Stop bits (available only when no parity is set)
Bits 1--0: Word length
1 0: 7 bits
1 1: 8 bits - DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AH: Status code (see service 0x03)
Comments
- For higher baud rates use service 0x81
"Extended line control initialization"
Two stop bits are only available if no parity is set.
Top of list
Index page
Interrupt 0x14 service 0x01: Put byte in output buffer, wait if needed.
- Character is queued for transmission. If there is space in the transmitter buffer when this call is made, the character will be stored and control returned to caller. If the buffer is full, the driver will wait for space. (This can be dangerous when used in combination with flow control.)
Parameters
- AH
- 0x01
- AL
- Byte to be written
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AH: Status code (see service 0x03)
Top of list
Index page
Interrupt 0x14 service 0x02: Get a byte from the serial port, wait if none available.
- Reads a byte from the receiver buffer. Wait for a byte to arrive if none is available.
Parameters
- AH
- 0x02
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AL: The byte received
Top of list
Index page
Interrupt 0x14 service 0x03: Status request
- Return the status of the serial port.
Parameters
- AH
- 0x03
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AH: Status code (bit field):
-
bit 6: Set if output buffer is empty.
bit 5: Set if output buffer is not full.
bit 4: Line break detected
bit 3: Framing error detected
bit 2: Parity error detected
bit 1: Set if overrun occurred on receiver.
bit 0: Set if data is available in receiver buffer.
Comments
- Any reported UART error flags are cleared by hardware after the read is made for this call.
Top of list
Index page
Interrupt 0x14 service 0x04: Initialize fossil driver
- Initialize the fossil driver for specified port.
Parameters
- AH
- 0x04
- DX
- Port specifier: 0 for EXT, 1 for COM
Return Value
- AX: 0x1954 if success
Comments
- Use this function to detect if the fossil driver is available for this port. The user must make sure that only one process opens a port. If this port is used for standard input or output (console), then stdin/stdout will be disabled for this port.
Developer Notes
If the DMA mode (send or receive mode) is enabled in
chip.ini,
the following port settings are not allowed:1. 8N2
2. 8S2
3. 8M2
Interrupt 0x14 service 0x05: Deinitialize fossil driver
- Deinitialize the fossil driver for specified port.
Parameters
- AH
- 0x05
- DX
- Port specifier: 0 for EXT, 1 for COM
Return Value
- none
Top of list
Index page
Interrupt 0x14 service 0x08: Flush output buffer waiting until done.
- Wait for all output in the output buffer to be transmitted.
Parameters
- AH
- 0x08
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Top of list
Index page
Interrupt 0x14 service 0x09: Purge output buffer.
- Remove all data from the output buffer.
Parameters
- AH
- 0x09
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Top of list
Index page
Interrupt 0x14 service 0x0A: Purge receive buffer.
- Remove all data from the receive buffer.
Parameters
- AH
- 0x0A
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Top of list
Index page
Interrupt 0x14 service 0x0B: Transmit byte, do not wait.
- Place a byte into the transmit buffer if there is space available. Otherwise simply return with AX=0, without handling the transmit byte.
Parameters
- AH
- 0x0B
- AL
- Byte to transmit
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AX=0 if byte was not accepted (no space in buffer)
AX=1 if byte was placed in buffer
Top of list
Index page
Interrupt 0x14 service 0x0C: Peek if next byte is available.
- Returns the next byte available in the receive buffer, without removing it from the buffer.
Parameters
- AH
- 0x0C
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AX=0xFFFF if no byte was available
AH=0x00 and AL=next byte, if a byte was available.
Top of list
Index page
Interrupt 0x14 service 0x0F: Enable/disable flow control.
- Configure the flow control for a port.
Parameters
- AH
- 0x0F
- AL
- Bit mask describing requested flow control.
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Comments
- Bit fields for FOSSIL data flow control:
-
B0:
XON/XOFF on transmit (watch for XOFF while sending)
B1: CTS/RTS (CTS on transmit/RTS on receive)
B2: reserved
B3: XON/XOFF on receive (send XOFF when buffer near full)
B4-B7: Ignored
Notes:
- XON/XOFF and CTS/RTS are not allowed at the same time.
- XON/XOFF and CTS/RTS are not allowed at the same time.
Developer Notes
XON/XOFF mode is also available if the DMA
mode for the serial port is enabled but because of the internal functionality of DMA it is not
possible to detect an XON or XOFF of the peer immediately. It is possible that
an overrun situation at the connected peer (e.g. GSM modem) could occur.
We now provide this mode because GSM modems (any??)
support only XON/XOFF flow ctrl.Interrupt 0x14 service 0x18: Read block of data
- Read up to a specified number of bytes from a serial port.
Parameters
- AH
- 0x18
- CX
- Maximum number of bytes to transfer.
- DX
- Port number: 0 for EXT, 1 for COM
- ES:DI
- Pointer to user buffer.
Return Value
- AX= Number of bytes transferred.
Top of list
Index page
Interrupt 0x14 service 0x19: Write a block of data
- Write a block of data to the serial port output buffer.
Parameters
- AH
- 0x19
- CX
- Maximum number of bytes to transfer.
- DX
- Port number: 0 for EXT, 1 for COM
- ES:DI
- Pointer to user buffer.
Return Value
- AX= Number of bytes actually transferred.
Top of list
Index page
Interrupt 0x14 service 0x1B: Get driver info
- Get information about a serial port and driver
Parameters
- AH
- 0x1B
- CX
- Size of buffer
- DX
- Port number: 0 for EXT, 1 for COM
- ES:DI
- Pointer to user buffer.
Return Value
- AX=Number of bytes actually transferred.
Comments
- Offset 0 (word) = Structure size
Offset 2 (byte) = FOSSIL spec version (not used)
Offset 3 (byte) = Driver rev level (not used)
Offset 4 (dword) = Pointer to ASCII ID (not used)
Offset 8 (word) = Input buffer size
Offset 0A (word) = Bytes available (input)
Offset 0C (word) = Output buffer size
Offset 0E (word) = Bytes available (output)
Offset 10 (byte) = Screen width, chars (not used)
Offset 11 (byte) = Screen height, chars (not used)
Offset 12 (byte) = Baud rate mask (not used)
This function was provided for compatibility with older Fossil applications.
Top of list
Index page
Interrupt 0x14 service 0x1E: Extended set baud rate
- Set the baud rate of the serial port
Parameters
- AH
- 0x1E
- BH
- Parity
00h None
01h Odd
02h Even
03h Mark
04h Space - BL
- Stop bits
00h: 1 Stop bit
01h: 2 Stop bits (available only when no parity is set) - CH
- Word length
02h: 7 bits
03h: 8 bits - CL
- Baud rate
00h: 110
01h: 150
02h: 300
03h: 600
04h: 1200
05h: 2400
06h: 4800
07h: 9600
08h: 19200
80h: 28800
81h: 38400
82h: 57600
83h: 76800
84h: 115200
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AH: Status code (see service 0x03)
Comments
- Two stop bits are only available if no parity is set.
Top of list
Index page
Interrupt 0x14 service 0x80: Enable/Disable RS485 mode
- Enable the RS485 mode.
Parameters
- AH
- 0x80
- AL
- 0=TxEnable low active
1=TxEnable high active
2=Disable RS485 mode - DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Comments
- By default the RTS0 and RTS1 signals (pins) are used to enable/disable
the respective (EXT or COM) transmitter. (TxEnable)
Note that RS485 is not available with serial send DMA!
Top of list
Index page
Interrupt 0x14 service 0x81: Extended line control initialization
- Extended line control initialization.
Parameters
- AH
- 0x81
- AL
- UART character data bits
2: 7 bits
3: 8 bits - BH
- Parity
0: no parity
1: odd parity
2: even parity
3: mark parity (always 1)
4: space parity (always 0) - BL
- Stop bits
0: 1 Stop bit
1: 2 Stop bits (only available when no parity is selected) - CX
- Baud rate divider
(for maximum baud rate see HAL function 0x8A) - DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Comments
- Two stop bits are only available if no parity is set.
Developer Notes
Parity settings "Mark" and "Space", and two stop bits
are not checked on received data by the @Chip (UART) or the API.
This is due to these modes are not available in hardware. These
modes are provided to communicate with hardware
that can operate only in these modes.
If the DMA mode (send or receive mode) is enabled in
chip.ini,
the following port settings are not allowed:
1. 8N2
2. 8S2
3. 8M2
Interrupt 0x14 service 0x82: Select RS485 pin
- Select the RS485 TxEnable pin
Parameters
- AH
- 0x82
- AL
- No of PIO pin [0..13]
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Comments
- By default the RTS0 and RTS1 signals (pins) are used to enable/disable the respective transmitter. (TxEnable) This function lets you select any PIO from 0-13 as TxEnable, but not all make sense. To change the default, call this function before you call the RS485 Enable function.
Top of list
Index page
Interrupt 0x14 service 0x83: Send break
- Send long or short break
Parameters
- AH
- 0x83
- AL
- 1: long break (2,5 frames)
2: short break (1 frame)
3: extra long break (3 frames) - DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Comments
- A short break is a continuous Low on the TXD output for a duration of more than one frame
transmission time M, where:
M = startbit + data bits (+ parity bit) + stop bit
A long break is a continuous Low on the TXD output for a duration of more than two frame transmission times plus the transmission time for three additional bits (2M+3).
A extra long break is a continuous Low on the TXD output for a duration of more than three frame transmission times.
Top of list
Index page
Interrupt 0x14 service 0x84: Enable/disable UART receiver
- Enable/Disable UART receiver
Parameters
- AH
- 0x84
- AL
- 0: disable receiver 1: enable receiver
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Comments
- This function is useful when using the SM35 as RS485 adapter.
Use this function to disable the receiver before transmitting data.
Wait until all data is sent and then reenable the receiver.
This prevents receiving your own transmitted data.
By default the receiver is enabled.
Top of list
Index page
Interrupt 0x14 service 0x85: Enable/disable UART transmitter
- Enable/Disable UART transmitter
Parameters
- AH
- 0x85
- AL
- 0: disable transmitter 1: enable transmitter
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- none
Comments
- By default the transmitter is enabled.
Top of list
Index page
Interrupt 0x14 service 0xA0: Get number of Tx bytes in UART
- Returns the number of bytes which are currently in the UART transmitter hardware.
Parameters
- AH
- 0xA0
- DX
- Port number: 0 for EXT, 1 for COM
Return Value
- AX= Number of bytes in the UART transmitter hardware
Comments
- With this function you can check how many bytes are currently in the
UART. This could be necessary to know if your communication
pauses because of a handshake problem.
The GetDriverInfo API (0x1B) reports the number of bytes remaining in the serial port driver's software send queue.
This function reports the number of bytes currently in the UART transmit hardware. By adding this function's return value to the software transmit buffer byte count reported by the GetDriverInfo API, you can determine the total number of transmit data bytes still pending output.
The maximum count returned here will be 2 bytes, accounting for the UART's transmit shift register (1 byte) and transmit holding register (1 byte).
Top of list
Index page
Interrupt 0x14 service 0xA1: Install a Fossil User Callback Function
- The user callback function will be called when a Fossil serial port event occurs.
Parameters
- AH
- 0xA1
- DX
- Port number: 0 for EXT, 1 for COM
- ES:DI
- Pointer to the User Callback function
Comments
- This call installs an user callback function for the specified serial port.
The callback function must be very short! Long Fossil callback functions can
lead to character loss.
To use the Fossil callback functions, you have to switch the serial port into the IRQ Mode (see CHIP.INI). In DMA mode the callback functions will not work!
The callback function must conform to this prototype:
fossil_event_t far *(huge my_fossil_callback)(
fossil_event_t far *e ) ;
The fossil_event_t structure e passed in contains the event which has occurred. Following events are possible:
#define FE_DATA_AVAIL 0x01 // New Data Received
#define FE_READY_FOR_SEND 0x02 // (currently not supported)
#define FE_ERROR_DETECTED 0x10 // (currently not supported)
Newly received data_length bytes can be found at location referenced by data pointer in structure e.The callback function can also return a fossil_event_t structure. The returned structure contains an action event which the Fossil serial port driver will respond to as follows:
#define FE_IGNORE_DATA 0x01 // Do not copy the received data
// into the receive queue.
#define FE_DATA_TO_SEND 0x02 // (currently not supported)
If the callback does not return any event, the return value must be a null pointer (=0L).
The definition of the fossil_event_t structure is as follows:
typedef struct
{
int size; // size of the structure
int port; // serial port (0=EXT, 1=COM)
int event; // event (see above)
void far *data; // data pointer
unsigned data_length; // data length
} fossil_event_t;
The size element should be set to sizeof(fossil_event_t).
Top of list
Index page
End of document