CYGPKG_DEVS_SERIAL_MIPS_PNX8310 -- eCos Support for the PNX8310 On-chip UARTs
Description
The PNX8310 comes with two on-chip UARTs for serial communication.
Other PNX83xx processors come with compatible devices. The
CYGPKG_DEVS_SERIAL_MIPS_PNX8310 package provides an
eCos serial device driver. It can support up to three UARTs, depending
on the processor and on which of the UARTs are connected on any given
platform. If the CTS and RTS lines are connected then hardware flow
control is supported. Line status is supported for line breaks and for
certain communication errors. The UARTs do not have any support for
DTR, DSR, DCD or RI lines. On some platforms these lines may be
emulated using GPIO pins, but the driver does not currently have any
support for this.
Once application code accesses a UART through the serial driver, for
example by opening a device /dev/ser0, the driver
assumes that it has sole access to the hardware. This means that the
UART should not be used for any other purpose, for example HAL
diagnostics or gdb debug traffic. Instead such traffic has to go via
another communication channel such as ethernet.
Configuration Options
The PNX8310 serial driver should be loaded automatically when
selecting a platform containing a suitable processor, and it should
never be necessary to load it explicitly. The driver as a whole is
inactive unless the generic serial support,
CYGPKG_IO_SERIAL_DEVICES, is enabled. Exactly which
UART or UARTs are accessible on a given platform is determined by the
platform because even if the processor contains a UART the platform
may not provide a connector. Support for a given UART, say uart0, is
controlled by a configuration option
CYGPKG_DEVS_SERIAL_PNX8310_SERIAL0, which will be
active only if the platform enables the device. If a given UART is of
no interest to an application developer then it is possible to save
some memory by disabling this option.
For every enabled UART there are a further four configuration options:
CYGDAT_DEVS_SERIAL_PNX8310_SERIAL0_NAME
Each serial device should have a unique name so that application code
can open it. The default device names are /dev/ser0,
/dev/ser1, and so on. It is only necessary to change
these if the platform contains additional off-chip UARTs with clashing
names.
CYGNUM_DEVS_SERIAL_PNX8310_SERIAL0_ISR_PRIORITY
By default the driver arranges for the UARTs to interrupt at a low
interrupt priority. Usually there will be no need to change this
because the driver does not actually do very much processing at ISR
level, and anyway UARTs are not especially fast devices so do not
require immediate attention.
CYGNUM_DEVS_SERIAL_PNX8310_SERIAL0_BAUD
Each UART will be initialized to a given baud rate. The default baud
rate is 38400 because in most scenarios this is fast enough yet
does not suffer from excess data corruption. Lower baud rates can be
used if the application will operate in an electrically noisy
environment, or higher baud rates up to 230400 can be used if
38400 does not provide sufficient throughput.
CYGNUM_DEVS_SERIAL_PNX8310_SERIAL0_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. 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.
There are additional 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.
This package also defines some configuration options related to
testing. Usually these options are of no interest to application
developers and can be ignored.
Porting
The generic driver needs some information from other packages about
the exact hardware, for example how many UARTs are available and
whether or not they are connected.
Another package, usually the platform HAL, should implement one or more
of the interfaces CYGINT_DEVS_SERIAL_PNX8310_UART0,
CYGINT_DEVS_SERIAL_PNX8310_UART1, or
CYGINT_DEVS_SERIAL_PNX8310_UART2. Typically this is
left to the platform HAL because even if the processor contains the
UART device it may not be accessible on a given platform because there
is no suitable connector.
If the RTS and CTS are connected for a given UART then the platform
HAL should also implement the appropriate interface, for example
CYGINT_DEVS_SERIAL_PNX8310_UART0_RS232_RTSCTS. This
will enable driver support for hardware handshaking.
If a given UART is supported then the generic driver will need to know
where it is mapped in the address space. Typically this is handled by
the processor or variant HAL package via a definition
HAL_PNX8310_UART0_BASE in cyg/hal/proc_io.h or
cyg/hal/var_io.h.
On some platforms or processors additional initialization may be
needed, for example to connect certain pins to the internal UART
rather than to other on-chip devices. The processor or platform HAL
can define a macro HAL_PNX8310_UART0_PROC_INIT
for this purpose.
