This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`devc-amctap`, `devc-tamctap`

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

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.

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.

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.

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:

the target virtual serial driver (devc-amctap)
the host-side communication server (devc_amctap_host).

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.

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.

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).

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.

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.

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:

Telnet into the host server IP and PORT (corresponding to the virtual serial driver port) for a simple connection between host and target.
Open a socket to the host server's IP and PORT corresponding to the virtual serial driver for a simple communication channel between host and target.
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 (e.g. qtalk or hyperterminal):
```
telnet IP PORT
```
Remote target debugging using pdebug/gdb:
- This is how you set up the target (you run pdebug on /dev/serat1 instead of /dev/ser1):
```
devc-amctap 0x700000,2000
devc-pty
pdebug /dev/serat1
```
- And this is the command line for the host (in gdb):
```
target qnx IP:PORT
```
  where IP and PORT correspond to the virtual serial driver port defined by the devc_amctap_host server.
Integrated debugging from the QNX IDE to communicate with the target (instead of using a dedicated serial or Ethernet channel for debugging), by specifying the host server's IP and PORT corresponding to the target's virtual serial driver.

Examples:

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

Reserve memory using the -r startup option.

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

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
```
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
```
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.
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
```