# serial_hw3_int_cts

Interrupt driven buffered serial interface for USART3 with flow control.

Author | Rob Jansen Copyright © 2021..2021, all rights reserved.
Adapted-by |
Compiler | 2.5r5

Description

    Serial communications for the third USART:
      - receive and transmit data transfer is interrupt driven
      - receive and transmit data transfer is buffered (circular buffers)
      - provides automatic CTS flow control with spare free space for FiFo buffer
    .
    This library supports:
      - Data format: 8 bits data, 1 start-bit, 1 stop bit
      - Acceptable baud rate depends on the oscillator frequency
        (see BAUD RATES tables in the datasheet).
      - Interrupt bits used: TXIE, RCIE, PEIE and GIE.
    .
    Available procedures/functions for application programs:
      - serial_hw3_init()                         -- initialise communications
      - serial_send3_byte(byte out )        -- send byte
                                                  -- returns the transmitted byte
      - serial_hw3_read(byte out ) return bit  -- receive byte
                                                  -- returns TRUE with data,
                                                  -- FALSE when no data available
      - serial_hw3_write(byte in )          -- send byte (wait if queue full)
      - serial_hw3_data =                   -- send byte, wait if queue full
      - serial_hw3_tx_buffer_free()               -- get free bytes in transmit buffer
                                                  -- returns number of free bytes
      -  = serial_hw3_data                  -- receive byte, wait if queue empty
    .
    Directions for use of this library in application programs (in this sequence):
    1. Declare the following constants:
         const  serial_hw3_baudrate = 115200        -- line speed must be declared (no default)
         const bit serial3_overflow_discard = FALSE -- Transmit buffer overflow:
                                                    -- -) FALSE: wait for free space (blocking)
                                                    -- -) TRUE: discard data (non-blocking)
                                                    -- This flag may be dynamically changed
                                                    -- but must then be declared as 'var bit'

Sources

    Based on the serial_hw_int_cts2.jal library by Rob Hamerling.

Notes

    See serial_hw_int_cts library for background information.

Dependencies

- usart3_common

## Summary

### Global variables/contants

- `var volatile byte _serial3_offsetxmthead`
- `var byte _serial3_rcvbuf[SERIAL3_RCVBUFSIZE]`
- `var volatile byte _serial3_offsetrcvhead`
- `var volatile byte _serial3_offsetxmttail`
- `var byte _serial3_xmtbuf[SERIAL3_XMTBUFSIZE]`
- `var volatile byte _serial3_offsetrcvtail`

### Procedures

- `serial_hw3_data'put(byte in data)`
- `serial_hw3_init()`
- `serial_hw3_write(byte in data)`

Private

- `_serial3_transmit_interrupt_handler()`
- `_serial3_receive_interrupt_handler()`

### Functions

- `serial_hw3_read(byte out data) return bit`
- `serial_hw3_data_available() return bit`
- `serial_hw3_data_ready() return bit`
- `serial_hw3_tx_buffer_free() return byte`
- `serial3_send_byte(byte in data) return byte`
- `serial_hw3_data'get() return byte`

## API details

### Global variables/contants

- `var volatile byte _serial3_offsetxmthead`

      variable keeping track of next free position in transmit buffer

- `var byte _serial3_rcvbuf[SERIAL3_RCVBUFSIZE]`

      Local circular receive buffer

- `var volatile byte _serial3_offsetrcvhead`

      variable keeping track of next free byte in receive buffer

- `var volatile byte _serial3_offsetxmttail`

      variable keeping track of next byte to be transmitted by interrupt handler

- `var byte _serial3_xmtbuf[SERIAL3_XMTBUFSIZE]`

      Local circular transmit buffer

- `var volatile byte _serial3_offsetrcvtail`

      variable keeping track of next byte available to application program

### Procedures

- `serial_hw3_data'put(byte in data)`

      Put byte in transmit buffer as pseudo variable

- `serial_hw3_init()`

      Title:     Initialize second serial port
      Arguments: (none)
      Returns:   (nothing)

- `serial_hw3_write(byte in data)`

      Title:     Put a single byte in transmit buffer
      Arguments: Data (byte) to transmit
      Returns    (nothing)
      Notes:     - This is a variant of serial2_send_byte() compatible with
      the procedure in the serial_hardware3 library.
       Spins when byte cannot be put in transmit buffer
      (buffer full condition).

Private

- `_serial3_transmit_interrupt_handler()`

      Title:     USART serial transmit interrupt handler
      Arguments: (none)
      Returns:   (nothing)

- `_serial3_receive_interrupt_handler()`

      Title:     USART serial receive interrupt handler
      Arguments: (none)
      Returns:   (nothing)
      Notes:     Sets CTS low when receive buffer has less than
       bytes free space.

### Functions

- `serial_hw3_read(byte out data) return bit`

      Title:     Return byte (if any) from circular receive buffer of USART
      Arguments: received byte (if any)
      Returns:   - TRUE  when byte returned
       FALSE if no byte available
      Notes:     Sets CTS high when receive buffer has more than
      bytes free space after delivering byte to caller.

- `serial_hw3_data_available() return bit`

      generic function to check if a byte is received

- `serial_hw3_data_ready() return bit`

      generic function to check if transmit buffer is empty

- `serial_hw3_tx_buffer_free() return byte`

      Title:     Get free space in transmit buffer
      Arguments: (none)
      Returns:   Number of free bytes in transmit buffer
      Notes:     - Useful to check in advance if a string will fit in the buffer
      or if transmitting the string will block.
       Never returns zero. If "1" is returned, regard buffer as full.

- `serial3_send_byte(byte in data) return byte`

      Title:     Put a single byte in transmit buffer
      Arguments: Data (byte) to transmit
      Returns:   transmitted byte (or 0x00 when data discarded)
      Notes:     - Activates transmit interrupt handler when data buffered
       When buffer full act as indicated in 'serial3_overflow_discard'
      * TRUE:  discard data (and return 0x00 as data byte)
      * FALSE: wait for free buffer space
      (returns only after data has been stored in buffer)

- `serial_hw3_data'get() return byte`

      Return next byte from receive buffer as pseudo variable
      Spin as long as no data available (buffer empty)

## Related samples

Here are the list of samples which use this library:

18f16q40 | 18f16q40_serial_hw3_int_cts.jal
18f47q43 | 18f47q43_serial_hw3_int_cts.jal