www.beck-ipc.com

@CHIP-RTOS - Fossil API


    IPC@CHIP® Documentation Index

FOSSIL

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

Fossil Interrupt 0x14 Services

Service is selected by index in AH register.
  • 0x00:_Set baud rate
  • 0x01:_Put byte in output buffer, wait if needed.
  • 0x02:_Get a byte from the serial port, wait if none available.
  • 0x03:_Status request
  • 0x04:_Initialize fossil driver
  • 0x05:_Deinitialize fossil driver
  • 0x08:_Flush output buffer waiting until done.
  • 0x09:_Purge output buffer.
  • 0x0A:_Purge receive buffer.
  • 0x0B:_Transmit byte, do not wait.
  • 0x0C:_Peek if next byte is available.
  • 0x0F:_Enable/disable flow control.
  • 0x18:_Read block of data
  • 0x19:_Write a block of data
  • 0x1B:_Get driver info
  • 0x1E:_Extended set baud rate
  • 0x80:_Enable/Disable RS485 mode
  • 0x81:_Extended line control initialization
  • 0x82:_Select RS485 pin
  • 0x83:_Send break
  • 0x84:_Enable/disable UART receiver
  • 0x85:_Enable/disable UART transmitter
  • 0x86:_Force RTS#
  • 0x87:_Read CTS#
  • 0xA0:_Get number of Tx bytes in UART
  • 0xA1:_Install a Fossil User Callback Function
  • 0xA2:_Register an external device driver port
  • 0xA3:_Unregister an external device driver port
  • 0xA4:_Set arbitrary baud rate
  • 0xA5:_Check if output buffer and transmitter are empty
  • 0xA6:_Check if serial data bytes are available


  • Interrupt 0x14 service 0x00:     Set baud rate

    Set the baud rate of the serial port

    Parameters

    AH
    0x00

    AL
    Configuration parameter:
    This bitmap field specifies the communication parameters.

    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

    Bits 1-0: Word length
      10      7 bits
      11      8 bits

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AH: Status code (see service 0x03)

    Comments

    For higher baud rates use service 0xA4 "Set arbitrary baud rate"

    SC1x Comments

    Two stop bits are only available if no parity is set.

    SC1x3/SC2x Comments

    Two stop bits are only available if no parity is set or word length is equal to 7 bits.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AH: Status code (see service 0x03)

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AL: The byte received

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0x14 service 0x04:     Initialize fossil driver

    Initialize the fossil driver for specified port.

    Parameters

    AH
    0x04

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    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.

    If the DMA mode (send or receive mode) is enabled in CHIP.INI, the following port settings are not allowed:
      1. 8N2 (this limitation applies only on SC1x systems)
      2. 8S1
      3. 8M1

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0x14 service 0x05:     Deinitialize fossil driver

    Deinitialize the fossil driver for specified port.

    Parameters

    AH
    0x05

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AX=0 if byte was not accepted (no space in buffer)
    AX=1 if byte was placed in buffer

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AX=0xFFFF if no byte was available
    AH=0x00 and AL=next byte, if a byte was available.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    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 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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    ES:DI
    Pointer to user buffer.

    Return Value

    AX= Number of bytes transferred.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    ES:DI
    Pointer to user buffer.

    Return Value

    AX= Number of bytes actually transferred.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AH: Status code (see service 0x03)

    SC1x Comments

    Two stop bits are only available if no parity is set.

    SC1x3/SC2x Comments

    Two stop bits are only available if no parity is set or word length is equal to 7 bits.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    Comments

    By default the RTS signals (pins) are used to enable/disable the respective serial port transmitter. (TxEnable)

    SC1x Comments

    Note that RS485 is not available with serial send DMA!

    SC1x3/SC2x Comments

    Note that RS485 is only available with serial send DMA when the TxEnable hardware function is used! See Select RS485 pin function.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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

    CX
    Baud rate divider
        (for maximum baud rate see HAL function 0x8A)

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    Comments

    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 (this limitation applies only on SC1x systems)
      2. 8S1
      3. 8M1

    SC1x Comments

    Two stop bits are only available if no parity is set.

    SC1x3/SC2x Comments

    Two stop bits are only available if no parity is set or word length is equal to 7 bits.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0x14 service 0x82:     Select RS485 pin

    Select the RS485 TxEnable pin

    Parameters

    AH
    0x82

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    SC1x Parameters

    AL
    No of PIO pin [0..13]

    SC1x3 Parameters

    AL
    No of PIO pin [0..24, 26..31]
    Use -1 to select the RTS pin (hardware functionality / default)

    Return Value

    none

    Comments

    By default the RTS signals (pins) are used to enable/disable the respective transmitter. (TxEnable)   This function lets you select any PIO as TxEnable, but not all make sense.   To change the default, call this function before you call the RS485 Enable function.  

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    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.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    Comments

    By default the transmitter is enabled.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.10V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0x14 service 0x86:     Force RTS#

    Force RTS# to low, high or reset to normal activity

    Parameters

    AH
    0x86

    AL
    Mode:
      0: force RTS to low
      1: force RTS to high
      2: reset to normal activity

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    none

    SC1x Comments

    RTS/CTS flow control must be enabled to use this function.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0x14 service 0x87:     Read CTS#

    Read level on CTS# pin

    Parameters

    AH
    0x87

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AL=0, CTS# is low
    AL=1, CTS# is high

    Comments

    RTS/CTS flow control must be enabled to use this function.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AX= Number of bytes in the UART transmitter hardware
    -1 if UART transmitter is disabled (since SC1x version V1.20 and SC1x3 version V1.05)

    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).

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    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 the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    ES:DI
    Pointer to the User Callback function

    Comments

    This service installs a user callback function for the specified serial port. The callback function must be very short! Long fossil callback functions could lead to character losing. To use the fossil callback functions you have to switch the corresponding serial port into the IRQ Mode (see CHIP.INI). In DMA Mode the callback functions do not work!

    The callback function must be declared like the function below:
    fossil_event_t far *(huge my_fossil_callback)(
        fossil_event_t far *e )



    The fossil_event_t structure e contains the event which has occurred.
    Following events are possible:

    #define FE_DATA_AVAIL     0x01  // New data received
    #define FE_DATA_SENT      0x02  // New character placed to the UART shift register
    #define FE_DATA_AVAIL9    0x03  // New data received with 9. data bit set
    #define FE_DATA_SENT9     0x04  // New character with 9. data bit set placed to the
                                                                     UART shift register
    #define FE_SENDQ_EMPTY    0x05  // Data send queue is empty
    #define FE_ERROR_DETECTED 0x10  // Data contains status information

    Newly received data_length bytes can be found at location referenced by data pointer in structure e.

    In case of event FE_ERROR_DETECTED the first two bytes of the data buffer should be interpreted as an unsigned short int (16 bit) that contains status information. The third byte will hold the received char. The following bit positions are defined in the status information:

      Bit3=1   - Parity Error Detected
      Bit5=1   - Framing Error Detected
      Bit9=1   - Short Break Detected
      Bit10=1  - Long Break Detected

    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  // Don't copy the received data into the receive queue.

    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 (e.g. 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).

    Note that only one user callback function can be installed per port. To uninstall a user callback function, simply call this service again with another function pointer or with a NULL pointer.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.25V1.25V1.25V1.81V1.81

    Top of list
    Index page
    Interrupt 0x14 service 0xA2:     Register an external device driver port

    This function registers an additional serial port with the RTOS, which is handled by an external device driver.

    Parameters

    AH
    0xA2

    DX
    Designated port number; If a special port number is to be assigned to the external device driver it can be specified here. If the external device driver doesn't care about its port number, a value < 0 should be handed. The RTOS will assign the next free port number in this case.

    ES:DI
    Pointer to the external device driver's callback function. The signature of this callback function must be as follows:
    unsigned huge callback(unsigned ax, unsigned bx, unsigned cx,
                           unsigned dx, unsigned es, unsigned di);

    Return Value

    AX == Assigned port number: The external port has been successfully registered.
    AX == -1: The designated port number is already in use.
    AX == -2: The maximum number of external ports is already registered.

    Comments

    After an external port has been installed via this function the RTOS will forward all fossil software interrupts regarding the corresponding port to the callback function of the device driver program. It is the driver program's duty to parse the parameters.

    Developer Notes

    This API service is intended to be used by the RTOS C-Library exclusively.
    It should not be used within user applications.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.17V1.17

    Top of list
    Index page
    Interrupt 0x14 service 0xA3:     Unregister an external device driver port

    This function unregisters an additional serial port.

    Parameters

    AH
    0xA3

    DX
    Port number of the external device driver port

    Return Value

    AX == 0: The external port has been successfully unregistered.
    AX == -1: Illegal port number

    Developer Notes

    This API service is intended to be used by the RTOS C-Library exclusively.
    It should not be used within user applications.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.17V1.17

    Top of list
    Index page
    Interrupt 0x14 service 0xA4:     Set arbitrary baud rate

    Sets the baud rate and other parameters of a serial port

    Parameters

    AH
    0xA4

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    BX, CX
    Desired baud rate (bits per second). BX holds high word.

    AL
    This bitmap field holds the desired parity, word length and number of stop bits:

    Bits 0..3: Parity
        FOSSIL_PARITY_NO - No parity
        FOSSIL_PARITY_ODD - Odd parity
        FOSSIL_PARITY_EVEN - Even parity
        FOSSIL_PARITY_MARK - Mark parity
        FOSSIL_PARITY_SPACE - Space parity

    Bits 4..5: Word Length
        0 - 7 bits
        1 - 8 bits

    Bits 6..7: Stop bits
        0 - 1 bit
        1 - 2 bits

    Return Value

    AX == -1: Illegal argument
    AL: Status code (see service 0x03)

    SC1x3/SC2x Comments

    Two stop bits are only available if no parity is set or word length is 7 bits.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.30V1.30

    Top of list
    Index page
    Interrupt 0x14 service 0xA5:     Check if output buffer and transmitter are empty

    Check if output buffer and transmitter are empty.

    Parameters

    AH
    0xA5

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AX = 0, output buffer or transmitter is not empty
    AX = 1, output buffer and transmitter are empty

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.27V1.27V1.27V1.45V1.45

    Top of list
    Index page
    Interrupt 0x14 service 0xA6:     Check if serial data bytes are available

    Check if serial data bytes are available.

    Parameters

    AH
    0xA6

    DX
    Port number:
      0 for the EXT (COM0) port (SC1x, SC1x3)
      1 for the COM (COM1) port (SC1x, SC1x3, SC2x)
      2 for the COM2 port (SC1x3, SC2x)
      3 for the COM3 port (SC1x3, SC2x)

    Besides the numbers for the IPC@CHIP®'s internal ports, a number of an external serial port can be passed if such a port is installed (see service 0xA2).

    Return Value

    AX = 0, no data available
    AX = 1, data is available

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.27V1.27V1.27V1.45V1.45

    Top of list
    Index page


    End of document