CYGPKG_DEVS_SERIAL_NIOS2_AVALON_UART -- eCos Serial Driver for Nios II Avalon UARTs
Description
A Nios II hardware design can include one or more Avalon uart devices
for serial communication. On typical hardware each uart requires an
external transceiver chip on the board to convert between FGPA and
RS232 voltage levels, so the actual number of uarts is more a property
of the board than of the FPGA hardware design.
CYGPKG_DEVS_SERIAL_NIOS2_AVALON_UART provides an
RS232 serial device driver for up to eight Avalon uarts in the design.
It should be noted that in typical eCos configurations the first uart
will be used for the HAL diagnostics and debug channel, either
directly or via virtual vector calls to the RedBoot ROM monitor, so
that uart should not be accessed via the serial driver.
Configuration Options
The Nios II Avalon uart serial driver should be loaded automatically
when creating an eCos configuration for a hardware design which
includes a suitable device, and it should never be necessary to load
the package explicitly. The driver as a whole is inactive unless the
generic serial support CYGPKG_IO_SERIAL_DEVICES is
enabled.
For each uart in the h/w design the driver package provides a
component, for example,
CYGPKG_DEVS_SERIAL_NIOS2_AVALON_UART0, allowing
driver support for that uart to be enabled or disabled. When enabled
this component contains a number of options related to that uart:
CYGDAT_DEVS_SERIAL_NIOS2_AVALON_UART0_NAME
Each serial device should have a unique name so that application code
can open it. The default names may be provided by the h/w design HAL,
otherwise they are strings such as
/dev/ser0 and /dev/ser1.
Usually it is only necessary to change these names if the h/w design
involves different types of uarts and hence multiple serial device
drivers.
CYGDAT_DEVS_SERIAL_NIOS2_AVALON_UART0_BAUD
If the h/w design supports variable baud rates then this option can be
used to set the default baud rate. This may be different from the
default set in the h/w design. It will be installed when the device is
opened by application code. If the h/w design does not support
variable baud rates then this option will be inactive.
CYGDAT_DEVS_SERIAL_NIOS2_AVALON_UART0_BUFSIZE
The serial driver will maintain software buffers for incoming and
outgoing data. The former allows data to continue to arrive even if
the application is still busy processing the previous transfer, and
thus potentially improves throughput. Also since Avalon uarts
do not have fifos a software buffer reduces the risk of lost
data. The latter allows the application to transmit data without
immediately blocking until the transfer is complete, often eliminating
the need for a separate thread. The size of these buffers can be
controlled via this configuration option, or alternatively these
buffers can be disabled completely to save memory.
In addition the package provides control over the compiler flags used
to build the driver code and some support for serial testing. There
are further options in the generic serial I/O package
CYGPKG_IO_SERIAL which will affect this driver. For
example CYGPKG_IO_SERIAL_FLOW_CONTROL and its
sub-options determine what flow control mechanism (if any) should be
used. Hardware flow control will only be available if the h/w design
includes support for the RTS/CTS lines.
Porting
This serial driver package needs information from the h/w design HAL
about the number of Avalon uarts and how they have been configured.
Note that this information can also affect the implementation of the
HAL diagnostics and debug channel in the Nios II architectural HAL
package so the relevant CDL interfaces are provided there. Also note
that in accordance with eCos conventions uart numbering starts with 0.
The CDL interface CYGHWR_HAL_NIOS2_AVALON_UARTS
should be implemented once for every Avalon uart in the h/w design.
Avalon uarts can be designed with RTS/CTS support if desired. If a
given uart has this support enabled then the h/w design HAL should
implement the appropriate CDL interface, for example
CYGHWR_HAL_NIOS2_AVALON_UART0_RTSCTS. In the
absence of RTS/CTS support the serial driver will not attempt hardware
flow control on that uart.
Avalon uarts can be designed with either a fixed or a variable baud
rate. If the latter then the h/w design HAL should implement the
appropriate CDL interface, for example
CYGHWR_HAL_NIOS2_AVALON_UART0_VARIABLE_BAUD.
For each uart the h/w design HAL should define the base address, the
interrupt vector, the uart's input clock, the default baud rate, the
number of stop bits, the parity, and the word length. This information
should come from the cyg/hal/nios2_hwconfig.h header.
Default device names and baud rates can be provided using
configuration options such as
CYGDAT_DEVS_SERIAL_NIOS2_AVALON_UART0_DEFAULT_NAME
and
CYGNUM_DEVS_SERIAL_NIOS2_AVALON_UART0_DEFAULT_BAUD.
Unlike more conventional uarts, with an Avalon uart the number of bits
per word, the number of stop bits, and the parity support are all
fixed when the hardware is designed. Any attempt to change these
settings at run-time will fail. The baud rate may also be fixed in the
h/w design, or run-time changes may be supported. If the latter then
the baud rate will be constrained by the input clock and a 16-bit
divisor register, so for example with a 100MHz input clock the lowest
standard baud rate that can be supported is 1800.
The serial driver does not provide any support for DMA transfers so it
ignores any end-of-packet register that may have been included in the
h/w design. Only RS232 is supported, not RS485 networking. There is no
support for the DTR, DSR, DCD or RI lines. If these are needed then
the lines would have to be wired up to an Avalon GPIO unit and handled
by application code.
