Common UARTs include the 16550 and antique 8250. Both at a minimal level allow the input and output of characters across a serial line. However, debuggers may require the use of the only serial port on some hardware, and so hence a UART driver module may indirect console i/o through the debugger.

Also, hardware like an ethernet controller or a parallel port can function as a UART, so these driver modules are not restricted to merely serial hardware. You could even drive an LCD panel or VGA display as a UART.

Furthermore, as there may be more than one UART controller of the same type in your hardware (often there are two serial controllers in development hardware), the driver keeps its internal data within a context block. This allows the same code to drive multiple controllers of the same type easily.

The first four letters of the module name should be some four letter mnemonic representing the chosen name of the driver.

Prefixes can be anything you want, but it is good form to maintain some sort of convention. We suggest <acronym>UARTDriver_<API postfix> eg; 16550UARTDriver_Initialise.

It is expected that most UART driver modules will be written entirely in C to aid portability (hence one can change the processor but retain the remainder of the hardware). However, if the module is written in C, calls may only be made when the C run-time system is operational (ie; main memory and C library working and initialised). Hence, one may wish to write the driver partly or wholly in assembler to prevent these limitations - this can be especially relevent when debugging early boot code.

Interrupt driven i/o is not expected to be implemented within the NedHAL API framework, but DMA driven i/o is permitted and encouraged. This is because interrupt driven i/o requires substantial support from other areas of NedHAL which are non-portable, and hence the UART code would become unportable. You can by all means add your own API's to do interrupt driven i/o to the same module source, or else have an internal switch to interrupt driven i/o after the operating system is ready to handle it - but the driver module must start up in a fashion which does not require interrupt support. Remember that debug i/o is best done in a polled fashion in case the operating system is too screwed up to do it via interrupts.

To initialise and finalise the operation of this module, the usual calls <name>_Initialise and <name>_Finalise are provided. The API <name>_Set sets the future operation of the UART. The API's <name>_WriteN and <name>_ReadN perform output and input to the UART. The optional API <name>_GetIOStatus returns the current buffer status of the UART.

You will need to keep the context block set up by this call valid at all times until you have finalised its operation as DMA driven i/o may need to use the block to perform its task.

The only parameter which should need further explanation is parity. This can take one of the following values:

• 0: use no parity
• 1: use odd parity
• 2: use even parity

Note that this call may or may not return before all or part of the actual write takes place. Use <name>_GetIOStatus to determine current input and output status. If the write does take place asynchronously, the buffer passed to this call is copied to an internal buffer and hence you may dispose of the local buffer upon return of this call.

This call will always wait until all the characters have been read. Use <name>_GetIOStatus to determine how many characters are awaiting to be read.

If either the pointer's txsize or rxsize are null on entry, those values are not set. If the values returned are -1, this indicates a value which is not zero (ie; the driver does not know how many bytes there are but it does know that it isn't none).