devc-netrom540, devc-tnetrom540

Serial communications manager for the AMC NetROM 5xx ROM emulator (QNX Neutrino)


Note: You must be root to start this driver.

Syntax:

devc-netrom540 [options]
               phys_rom_addr,romwordwidth,romsize &
devc-tnetrom540 [options]
                phys_rom_addr,romwordwidth,romsize &

Runs on:

x86, PowerPC, MIPS, ARM, and SH hardware configured with the AMC NetROM 5xx ROM emulator

Options:

The devc-netrom540 options depend on the NetROM configuration for the particular target board you are using. See the documentation provided with the NetROM and the target board to determine configuration details.

-a addr
Specify the physical memory location (in hexadecimal notation) of the dualport communication channel.

Note: We recommend that you locate the dualport at the end of Pod 0 (the default location). If you use this option to specify a different location, make sure that the address specified by addr falls within Pod 0 and does not overlap the location of the Neutrino image in the emulated memory.

Calculate the value for addr like this:

addr = phys_rom_addr + (dprbase * romwordwidth)

where dprbase is the NetROM environment variable that you use to set the base address in emulation Pod 0 to map dualport RAM. To locate the dualport at the end of Pod 0 as recommended, you would calculate dprbase by deducting the size of the dualport from the size of the emulated memory in bytes, thus:

dprbase = (romsize * 1024) - 8192

(The 8Kb size of the dualport is given by the DUALPORT_SIZE constant in the AMC source code.)

If you don't specify the -a option, the dualport communication channel will be located at the end of Pod 0 by default.

-C number
Size in bytes of the canonical input buffer. The default is 256.
-c number
Set the poll timer rate in nanoseconds (default 1000000). The NetROM requires a polling timer because its generic setup does not provide interrupts for the communication channel. Selecting a slower poll rate reduces the throughput of the VUART communication channel and the load on the system CPU. The timer rate is limited by the system's clock ticksize.

The -c and -t options control the driver's effective baud rate.

-d number
Specify the dualport channel number corresponding to the ports associated with the NetROM environment variables debugpath and chanpath, as follows:
0
Debug path (the default).
1
Channel 1.
2
Channel 2.
3
Channel 3.
-E
Start in raw mode (the default). Software flow control is disabled by default.
-e
Start in edited mode (the default is raw mode). Software flow control is enabled by default.
-g number
If the memory write line is enabled, set number to 0 (the default); if it is disabled, set number to 1. This option relates to the NetROM groupwrite environment variable and READONLY_TARGET in the NetROM driver source code.

Note: NetROM provides an external write line that can be connected to the target processor for use in target systems that do not provide a write signal to the ROM space (see the NetROM docs for more information). If writes are enabled, set number to 0, if not, set number to 1.

-I number
The size of the IO-Char input buffer in bytes (the default is 2048 bytes).
-i number
Set the value of POD_0_INDEX in the NetROM driver source code. Possible values are 0-3 (the default is 0).
-O number
Set the size of the IO-Char output buffer in bytes (the default is 2048 bytes).
-P number
Set the priority of the driver process itself. The default is the same as the spawning process's priority.

Note: This option is generally required only when other processes are running at higher, non-default, priorities, or when this driver's polling interferes with other processes on the system.

-p number
Set the priority of driver events (the default is 24). This value is used for the priority of events sent from the driver to the IO-Char resource manager as well as the priority of the polling timer events.

Note: This option is generally required only when other processes are running at higher, non-default, priorities, or when this driver's polling interferes with other processes on the system.

-S|s
Disable / enable software flow control. The default depends on the mode: in raw mode (-E, the default), it's disabled; in edited mode (-e), it's enabled.

The order in which you specify the -E or -e, and -S or -s options matters:

Options Mode Software flow control
-e Edited Enabled
-S -e Edited Enabled
-e -S Edited Disabled
-E Raw Disabled
-s -E Raw Disabled
-E -s Raw Enabled
-t number
Set the virtual RX/TX FIFO size in bytes (default 50). The FIFO size determines how many characters are read from the dualport channel and written to the dualport channel at each polling timer event.

The -t and -c options control the driver's effective baud rate.

-u unit
Set the serial unit number (default 1).
-v
Be verbose during dualport initialization.
-X num,endian
Run a test routine (the driver includes the nr_TestComm routine from the NetROM sample source code). This routine conducts a number of tests in a fixed testing sequence to check for dualport communications problems (there are 7 low-level tests). Set num to the number of tests to conduct. Set endian to 0 (little-endian) or 1 (big-endian); the default is 1.

A failure in the first seven tests indicates a NetROM configuration problem (see the NetROM User's Manual for details).


Note: The VUART driver is not started after the test is complete.

You must always specify the following parameters:

phys_rom_addr
The physical location of the emulated memory on the target board, specified in hexadecimal notation.
romwordwidth
The number of bytes making up a word in emulated memory, corresponding to the NetROM wordsize environment variable.
For a word of: Set romwordwidth to:
8 bits 1
16 bits 2
32 bits 4
romsize
The size of the emulated memory in kilobytes.

Description:

The AMC NetROM 5xx is a ROM emulator used to replace ROM or FLASH memory devices on a target board, allowing for the easy downloading of Neutrino images. It provides a communication gateway that connects a target system to an Ethernet network without using any target resources. For targets that lack free debugging serial or Ethernet communication ports, or for which no drivers are yet written, a communication channel is available from the target to the NetROM via the emulated memory. A virtual serial driver running on the target system appears and behaves as a standard serial port to target applications, allowing them to invisibly communicate with the host via the NetROM. See the NetROM 5xx User's Manual for more information.

The devc-netrom540 serial device manager is a virtual UART (VUART) that acts like a standard serial port on the target. This manager supports both raw and edited modes, making it a real tty device.


Note: You have to install and configure the NetROM properly before you can use this VUART, see the NetROM documentation for details.

Each instance of the devc-netrom540 manager supports only one of the four possible communication channels through the NetROM communication dualport. This means that if you want to use two dualport channels (e.g. dualport 0 and dualport 1) you will have to invoke the manager twice.

The devc-tnetrom540 manager is a "tiny" version of devc-netrom540 that's intended for memory-constrained systems. It supports only raw made, it doesn't support special character editing (e.g. toggling insert mode and special erase characters).

Device pathnames

Each device is given a name in the pathname space of /dev/sernrx, where x defaults to 1 (unless you change it using the -u option). Thus, the default VUART is located at /dev/sernr1 (whereas a real UART would be located at /dev/ser1).


Note: If your application uses /dev/console, you can create a link from it to /dev/sernrx by adding a line like this to the buildfile used by mkifs:
[type=link] /dev/console = /dev/sernr1 

I/O-Char library functions

The VUART driver is based on the standard IO-Char library used by all character devices (serial, parallel, console, and pty) and devc-netrom540 inherits all of the usual functionality such as edit and raw mode (devc-tnetrom540 doesn't support edit mode). Interrupts and hardware flow control are not supported due to the limitations of the NetROM dualport. Like a serial port, options for the device can be accessed and modified using the stty utility.


Note: Hardware-related stty line control parameters such as ihflow, ohflow, par, bits, stopb, and baud have no effect.

By default, a read request is returned when at least one character is available but to increase efficiency, you can set the following three qualifiers to control when a read is satisfied:

Set this qualifier: To return:
TIME After a specified amount of time has elapsed
MIN When a specified number of characters are in the input buffer
FORWARD When a specified forwarding character is in the input buffer

For a fuller explanation of these three qualifiers, see readcond() in the Library Reference)


Note: If the value specified by MIN is greater than the size of the input buffer, the MIN value will be clipped to the size of the buffer. To avoid this, change the size of the input buffer using the -I option.

You set these parameters using library routines (see tcgetattr(), tcsetattr(), readcond(), and TimerTimeout() in the Library Reference).

The following fields and flags are supported in the termios structure:

Field Supported flags
c_cc All characters
c_iflag BRKINT ICRNL IGNBRK IXON
c_oflag OPOST
c_cflag CLOCAL CSIZE CSTOPB PARENB PARODD
c_lflag ECHO ECHOE ECHOK ECHONL ICANON IEXTEN ISIG NOFLSH

Connections and uses

On the target side, the devc-netrom540 driver appears and functions like any serial driver, and applications running on the target side access the virtual serial port like a normal serial port.

On the host side, the channel port of the NetROM corresponds to the channel path that the virtual serial port was started on (see option -d). You can use the virtual serial driver in several ways, including the following:

  1. Telnet into NetROM's IP and PORT (corresponding to the virtual serial driver port) for a simple connection between host and target.
  2. Open a socket to the NetROM's IP and PORT corresponding to the virtual serial driver for a simple communication channel between host and target.
  3. Set the virtual serial driver as the target's console (done in the target build file) and obtain a console shell to the target using a Telnet session instead of the usual terminal communication program (qtalk, hyperterminal).
  4. Remote target debugging using pdebug/gdb:
  5. Integrated debugging from the QNX IDE using any of the communications channels (debug, 0, 1, or 2) to communicate with the target (instead of using a dedicated serial or Ethernet channel for debugging).

Sample NetROM 540 configuration

This is a sample NetROM 540 configuration for the Motorola 860 FADS eval board (PPC). It shows you how to download a QNX Neutrino image (srec) built using the 800 FADS board support package (BSP). The image is downloaded using the NetROM download utility, and assumes that 10.7.0.227 is a free IP address to assign to the NetROM.

Script

setenv fillpattern none
setenv groupaddr 0x2800000
setenv groupwrite readwrite
setenv debugpath dualport
setenv consolepath serial
setenv chanpath 1 dualport
setenv chanpath 2 dualport
setenv chanpath 3 dualport
setenv filetype srecord
setenv romgroup 0
setenv podorder 0
setenv romcount 1
setenv romtype 1M_by_32
setenv writemode flash
setenv wordsize 32
setenv verify on
setenv vether off
setenv dprbase 0xFE000
tgtreset

ifconfig le0 10.7.0.227 netmask 255.255.0.0
setenv bootflags storage
save
set prompt NetromQNX>
printenv

Download image

download 800fadsflash.srec 10.7.0.227

Examples:

For the Motorola 860 FADS eval board (PPC):

Start devc-netrom540 on the 860 FADS, emulating 1 MByte of 32bit memory located at address 0x2800000 on the FADS board, with the dualport channel located at the end of ROM:

devc-netrom540 0x2800000,4,1024

Start devc-netrom540 on the 860 FADS, with the dualport channel located at a user specified location in ROM. This example manually specifies the location at the end of ROM (same as the above case):

devc-netrom540 -a0x2bf8000 0x2800000,4,1024


Note: You can locate the dualport elsewhere, but make sure it does not overlap the location of the downloaded Neutrino image.

Create two virtual UART devices on the 860 FADS: (channel 0 at /dev/sernr1 and channel 1 at /dev/sernr2):

devc-netrom540 -d0 -u1 0x2800000,4,1024
devc-netrom540 -d1 -u2 0x2800000,4,1024


Note: As an example of where you might want to set up two ports like this, you could configure one serial port as the console to avoid having to use a standard serial port, and another port for debugging using pdebug/gdb.

Test the NetROM dualport communication channel configuration by calling the nr_TestComm test routine (does not create a virtual driver at /dev/sernr1):

devc-netrom540 -X13,1 0x2800000,4,1024

Caveats:

Although interrupts may be possible with special wiring of the target board to the NetROM unit, the generic installation of the NetROM ROM emulator does not provide interrupts for the dualport communication channel. A polling method based on a user programmable timer is used instead.

Due to the implementation of the readonly communication mode (groupwrite environment variable), the NetROM may not be able to keep up with the driver's default communication rate and may therefore drop characters. If this is the case, reduce the driver's effective baud rate by adjusting the values of the -C and -t options.

If the OS is running XIP (execute-in-place), the standard Read-Write case will work, but the Read-Read (Readonly) mode will not. The driver assumes it is executing out of RAM memory.

If the devc-netrom540 driver hangs during startup, the NetROM may be misconfigured. Run devc-netrom540 with the -v option; if the driver appears to hang on the nr_ChanReady or nr_Resync routines, try this:

  1. Run a tgtreset command on the NetROM.
  2. Check that the groupwrite environment variable matches the -g option value.
  3. Check that the groupwrite environment variable is set to readwrite, and that the board is wired for read/write access to this memory. If the board does not allow read/write memory access, configure NetROM for Readonly.
  4. Check that the chanpath environment variables (serial/dualport) are configured properly. This driver assumes that all channels from channel 0 to the channel number specified by the -d option are dualport channels, not serial channels. For instance, if you specify -d2, the driver expects the NetROM chanpath value for channels 0-2 to be set to dualport.
  5. If you have a serial channel connecting the NetROM target serial port to the target serial port, locate it on a channel higher than the channels used by the devc-netrom540 driver.

See also:

Character I/O drivers (devc-*) in the Utilities Summary