devc-amctap, devc-tamctap

Serial communications manager through the AMC WireTAP/PowerTAP JTAG (QNX Neutrino)


Note: You must be root to start this driver.

Syntax:

devc-amctap [options] phys_addr,mem_size &
devc-tamctap [options] phys_addr,mem_size &

Runs on:

PowerPC and MIPS hardware configured with the AMC WireTAP or PowerTAP JTAG

Options:

-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). A polling timer is required because there are no interrupts associated with this communication channel. The timer rate is limited by the ticksize of the system's clock.
-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. This option is not available in devc-tamctap.
-I number
The size of the IO-Char input buffer in bytes (the default is 2048 bytes).
-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
-u unit
Set the serial unit number (default 1).

You must always specify the following parameters:

phys_addr
The physical location in RAM memory on the target board to be used as a communication channel, specified in hexadecimal notation.
mem_size
The size of the RAM memory in bytes reserved for the communication channel.

Note: The phys_addr and mem_size values should exactly match the values of the parameters used for the -r option of the startup library in the target buildfile.

Description:

The AMC WireTAP and PowerTAP development tools are hardware debuggers for embedded hardware. They enable you to control the target CPU and read from and write to target memory and registers. The devc-amctap manager provides a serial communication gateway through a JTAG connector to a target system that lacks free debugging serial or Ethernet communication ports, or for which no drivers are yet written.

The communication port consists of two components:

These two components communicate using a protocol mapped to use a particular region of reserved RAM memory (using the startup -r option). The virtual serial driver running on the target system appears and behaves as a standard serial port to target applications, enabling them to invisibly communicate with the host. The host server associates an IP address and PORT to this communication channel, enabling host applications (such as telnet for console, gdb for debugging) to seamlessly communicate with the target.


Note: This communication link is slow, about 9600 baud or less, and should be used only if there are no other communication options available (e.g. in deeply embedded systems).

The devc-amctap 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 JTAG hardware and AMCTAP software properly before you can use this VUART, see the AMC documentation for details.

The devc-tamctap manager is a "tiny" version of devc-amctap 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/seratx, where x defaults to 1 (unless you change it using the -u option). Thus, the default VUART is located at /dev/serat1 (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/seratx by adding a line like this to the buildfile used by mkifs:
[type=link] /dev/console = /dev/serat1

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-amctap inherits all of the usual functionality such as edit and raw mode (devc-tamctap doesn't support edit mode). Interrupts and hardware flow control are not supported due to the limitations of the JTAG connection. 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-amctap 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 server maps an IP and PORT to the virtual serial port. You can use the virtual serial driver in several ways, including the following:

Examples:

Here's how to configure the devc-amctap driver for the Sandpoint evaluation board (PPC):

  1. Reserve memory using the -r startup option.

    Note: Choose the location address and size of RAM memory so that it falls within a valid address range for the target and does not overlap crucial system memory (such as the image or the exception tables).

    For example, if you want to create a 2000 byte communication channel at address 0x700000 in RAM, edit the startup options of your target buildfile to look like this:

    startup-sandpoint -r0x700000,2000
  2. Specify the options to invoke devc-amctap from the build target buildfile or command line using the same RAM location and size:
    devc-amctap 0x700000,2000
  3. Change the device pathname in the buildfile from this:
    [type=link] /dev/console=/dev/serX

    to this (for the default VUART):

    [type=link] /dev/console=/dev/serat1
  4. Invoke the host server (on the host Windows system).

    For PowerTAP, you first have to configure the PowerTAP IP address (to find out how to do this, see the AMC documentation). Let's say you have configured the PowerTAP IP address to 10.30.30.95, this is how you would invoke the host server:

    devc_amctap_host -p10.30.30.95 -sc:\amctap\support \
    -a0x700000 -m2000

    For WireTAP, invoke the host server like this:

    devc_amctap_host -w1 -sc:\amctap\support -a0x700000 -m2000

    The above examples create a virtual communication channel of 2000 bytes at 0x700000 in RAM. On the target, this channel will appear as the serial driver at /dev/serat1.

    On the host, the default IP and PORT are used (i.e. the host's IP address and PORT 3490). If you don't want to use these defaults, you can explicitly specify the host server's IP and PORT associated with /dev/serat1. For example, say you wanted to specify an IP address of 10.2.3.4 and a port of 3500, you could invoke the host server like this for PowerTAP:

    devc_amctap_host -p10.30.30.95 -sc:\amctap\support \
    -a0x700000 -m2000 -i10.2.3.4 -o3500

    or like this for WireTAP:

    devc_amctap_host -w1 -sc:\amctap\support -a0x700000 -m2000 \
    -i10.2.3.4 -o3500

    For more information on host server options, see devc_amctap_host.

  5. Once the target board is booted up, you can open a console to the target from the Windows host, like this:

    telnet host IP address 3490

See also:

devc_amctap_host

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