int HAL_UARTPorts(void)

  Return number of UART ports

void HAL_UARTStartUp(int port)

  Initialise the indicated port. Must be called before any of the other
  control or data operations for that port.

void HAL_UARTShutdown(int port)

  Shutdown the indicated port

int HAL_UARTFeatures(int port)

  Bit 0:  FIFOs available
  Bit 1:  DMA available
  Bit 2:  Modem lines available
  Bit 3:  Hardware RTS/CTS available
  Bit 4:  Transmitter empty IRQ is actually "TX FIFO under threshold" IRQ, and
          may only change state once level is crossed (so on startup IRQ may
          not be firing). Use line status bit 8 to work out when to stop
          filling the FIFO.

int HAL_UARTReceiveByte(int port, int *status)

  Returns the next byte from the FIFO (if enabled) or the holding register.
  If status is non-NULL, the line status associated with the byte is
  read (see LineStatus). The return value is only meaningful if a
  received byte is available (bit 0 of *status will be set).

void HAL_UARTTransmitByte(int port, int byte)

  Sends a byte. The routine is not expected to wait for FIFO space to become
  available; instead it should silently fail.

int HAL_UARTLineStatus(int port)

     Bit 0: Receiver Data Ready
     Bit 1: Overrun Error
     Bit 2: Parity Error
     Bit 3: Framing Error
     Bit 4: Break Error
     Bit 5: Transmitter FIFO Empty
     Bit 6: Transmitter FIFO + hold/shift register empty
     Bit 7: FIFO contains a Parity, Framing or Break error
     Bit 8: TX FIFO full (may only be reported if Features bit 4 set)

  Parity, Framing and Break errors are associated with each byte received.
  Whether the values reported here are associated with the last byte
  read using ReceiveByte or with the next byte to be read is undefined.
  You should request the status using ReceiveByte to ensure accurate
  identification of bytes with errors.

  Error bits are cleared whenever status is read, using either LineStatus
  or ReceiveByte with status non-NULL.

int HAL_UARTInterruptEnable(int port, int eor, int mask)

  Enables interrupts. Bits are:
 
     Bit 0: Received Data Available (and Character Timeout)
     Bit 1: Transmitter Holding Register Empty
     Bit 2: Received Line Status
     Bit 3: Modem Status

  new_state = (old_state AND mask) EOR eor

  Returns previous state.

int HAL_UARTRate(int port, int baud16)

  Sets the rate, in units of 1/16 of a baud. Returns the previous rate.
  Use -1 to read.

int HAL_UARTFormat(int port, int format)

  Bits 0-1: Bits per word  0=>5, 1=>6, 2=>7, 3=>8
  Bit 2:    Stop length 0=>1, 1=>2 (1.5 if 5 bits)
  Bit 3:    Parity enabled
  Bits 4-5: Parity:  0 => Odd (or disabled)
                     1 => Even
                     2 => Mark (parity bit = 1)
                     3 => Space (parity bit = 0)

  Returns previous format. -1 to read.

void HAL_UARTFIFOSize(int *rx, int *tx)

  Returns the size of the RX and TX FIFOs. Either parameter may be NULL.
  Note that the size of the TX FIFO is the total amount of data that can
  be sent immediately when the Transmitter Holding Register Empty/FIFO under
  threshold IRQ holds. (So an unusual UART that had a transmit threshold
  should return total FIFO size minus threshold).

void HAL_UARTFIFOClear(int port, int flags)

  Clears the input FIFO (if bit 0 set) and the output FIFO (if bit 1 set).

int HAL_UARTFIFOEnable(int port, int enable)

  Enables or disables the RX and TX FIFOs: 0 => disable, 1 => enable
  -1 => read status. Returns previous status.

int HAL_UARTFIFOThreshold(int port, int threshold)

  Sets the receive threshold level for the FIFO RX interrupt. Returns previous
  value. -1 to read.
  
int HAL_UARTInterruptID(int port)

  Returns the highest priority interrupt currently asserted. In order
  of priority:

  3 => Receiver Line Status (Cleared by ReceiveByte/LineStatus)
  2 => Received Data Available (Cleared by reading enough data)
  6 => Character Timeout (received data waiting)
  1 => TX Holding Register Empty (Cleared by this call)/FIFO under threshould
       (cleared by sending enough chars)
  0 => Modem Status (Cleared by ModemStatus)
  -1 => No Interrupt

  The Modem Status interrupt occurs when the CTS, DSR or DCD inputs
  change, or when RI goes from high to low (ie bits 0 to 3 of ModemStatus
  are set).
 
int HAL_UARTBreak(int port, int enable)

  Activates (1) or deactivates (0) a break condition. -1 to read,
  returns previous state.
                               
int HAL_UARTModemControl(int port, int eor, int mask)

  Modifies the modem control outputs.

  Bit 0: DTR
  Bit 1: RTS
  Bit 5: Use hardware RTS/CTS

  new_state = (old_state AND mask) EOR eor

  Note that these are logical outputs, although the physical pins may be
  inverted. So 1 indicates a request to send. Returns previous state.

int HAL_UARTModemStatus(int port)

  Reads the modem status inputs.

  Bit 0: CTS changed since last call
  Bit 1: DSR changed since last call
  Bit 2: RI changed from high to low since last call
  Bit 3: DCD changed since last call
  Bit 4: CTS
  Bit 5: DSR
  Bit 6: RI
  Bit 7: DCD

  Note that these are logical inputs, although the physical pins may be
  inverted. So 1 indicates a Clear To Send condition. This must also clear
  the modem interrupt status.

int HAL_UARTDevice(int port)

  Return the device number allocated to the UART port

int HAL_UARTDefault(void)

  Return the UART number that should be used for OS_SerialOp, or -1 for none