SETPCISCC(8)

NAME
setpciscc - communicate with PCISCC-4 device driver

SYNOPSIS
setpciscc [ -i device ] -g [ rxbuf=buffers ] [ txbuf=buffers ] [ iqlen=entries ] [ pchan=0..3 ] [ rfifo=dwords ] [ lbi=conf ] [ oscp=bool ] setpciscc [ -i device ] -d [ code=NRZ | NRZI | FM0 | FM1 | MANCH ] [ clk=DF9IC | G3RUH | TCM3105 | HS ] [ duplex=HALF | FULL | FULLPTT ] [ pll=FAST | SLOW ] [ brg=divisor ] [ txclk=bool ] [ rtsclk=bool ] [ dinv=bool ] [ txdata=TP | OD ] [ cdinv=bool ] [ loop=bool ] [ txdmode=SOFT | HARD ] [ txd=txdelay_bits ] [ txt=txtail_bits ] [ shflg=bool ] [ crc=CRC-16 | CRC-32 ] [ crcinit=FFFF | 0000 ] [ crcrx=bool ] [ crctx=bool ] [ pamb=preamble ] [ prep=0 | 1 | 2 | 4 | 8 ] [ oneins=bool ] [ fill=FLAGS | ONE ] setpciscc [ -i device ] -l [ led=0..3 ] setpciscc [ -i device ] -b [ -r|-w ] [ addr=address ] [ data=data ] setpciscc [ -i device ] -s setpciscc [ -i device ] -c [ time=cal_bits ] setpciscc [ -i device ] -k setpciscc -h

DESCRIPTION
The program setpciscc is a configuration tool designed to communicate with the PCISCC-4 board driver in system kernel. It can be used to get or set parameters, display status of the board and connected modems as well as to invoke diagnostic functions.

OPTIONS
In addition to the -i switch, which sets the interface the command is to be applied to, the following options are accepted by setpciscc:

-g  The -g switch allows for the display/setting of global (i.e. board-wide) parameters. The device specified with the -i option must be one of its four interfaces. If no interface is specified the first board is selected. If a parameter change is committed old and new values are displayed, otherwise setpciscc only shows the current parameters. When setting global parameters all interfaces of the board in question must be down!

-d  With the -d switch, setpciscc shows/sets the local parameters of the interface specified with the -i option. If no device is specified, setpciscc assumes interface dscc0. If parameter change is requested, old and new values are printed, otherwise setpciscc just prints the current parameter set.

-l  By means of the -l switch, the LEDs of the interface specified with the -i option can be controlled. If no interface is specified, dscc0 is assumed. Every interface has two light emittimg diodes, a green and a red one. These are meant to yield current high-level status of the interface and really should be controlled by the MAC layer. However, currently the MAC implementation is not capable of doing so. If somebody writes a user space daemon or a script and does not want to call the SIOCPCISCCSLED ioctl() directly this command can be used to turn the diodes on and off. The device may be up or down for this to work.

-b  The -b switch implements a means to access the local bus (LBI, Local Bus Interface) of the PCISCC-4 board. Whoever wants to use this feature knows what this means, so explaining it here is pointless anyway. Be careful with this switch, because otherwise you will most probably crash your machine! Configure the LBI mode at global settings first if you want to go on and know what you are doing.

-s  The status of the interface specified with the -i option or - if none specified dscc0 - can be shown using the -s switch. The status report consists of the PLL state (locked/unlocked), the RX line state (active/inactive), the DCD state (active/inactive), the CTS state (active/inactive), the RTS state (active/inactive) and the transmitter state. The latter one can be one of RESET (transmitter is not initialized), IDLE (not active), TXDELAY (transmitting the TX-delay bit sequence), TRANSMIT (transmitting data), TXTAIL (transmitting the closing TX-tail sequence), PROBE (probing transmitter clock rate) or CALIBRATE (transmitting calibration signal).

-c  The -c switch can be used to put the specified interface (or dscc0 respectively) into calibrate mode. This means, it will start to transmit interframe fill data. Depending on how it was configured this can be flags or all ones. For this to work the interface must be up and its transmitter must be in the idle state. During calibration no frames are sent out. They are kept in buffer space until the interface operation comes back to normal again or all transmitter buffers are filled up. Note that the time parameter must be given in bits (e.g. 19200 at 9600 bps means 2 seconds), see PARAMETERS section of this manual.

-k  The -k switch allows the user to restart the transmitter of the specified interface (to kick it) if it appears to be hung. Use with care, and only if TX is really locked up. Otherwise all sorts of strange things will happen including crashs.

-h  The -h switch prints the help text.

PARAMETERS
Most options accept or even require parameters to be appended at the end of the command line. All parameters have the syntax parameter=value where the type of value depends on the requirements of the parameter. There are, however, a few standard types: A bool type recognizes yes, true, enable, on and 1, case insensitive, as true, everything else as false. Numbers can be entered in decimal, octal or hexadecimal notation. To distinguish between the radixes, octal numbers must be preceded by 0, hexadecimal ones by 0x, decimals can be entered as-is. To specify a multiplicator, one of the following (case insensitive) characters can be appended: W (words, *2), K (kilo, *1024), M (mega, *1024*1024), G (giga, *1024*1024*1024). Global Parameters

rxbuf
    The rxbuf parameter specifies the number of receiver buffers and descriptors in the receiver buffer pool of each interface. Higher values cost a lot of memory, lower values causes packet loss at high system/interrupt load and high link speeds.

txbuf
    The txbuf parameter specifies the number of descriptors in the transmitter desciptor chain. Higher numbers mean a lot of memory is needed, lower values may cause TX overrun, which leads to loss of frames.

iqlen
    This parameter specifies the interrupt queue length in multiples of 32 dwords. Use larger queues with really high speed links only. This will make sure no interrupt gets lost.

pchan
    With this parameter one of the four channels of a board can be selected as priority channel. This means that on DMA transfers from and to host memory the specified interface has prioritiy over each other interface. This makes sense for example if one interface is much faster than the others. -1 turns this feature off (i.e. all interfaces get the same priority).

rfifo
    This parameter sets the DMA receiver threshold in dwords. If the specified setting is exceeded receiver DMA transfer from the on-chip main FIFO to host memory starts. During the DMA PCI burst transfers are carried out, which means that only the lead-off cycles and bus arbiting is expensive. A high threshold value here will increase the time between consecutive transfers thus reducing PCI bus load. On the other hand it makes data loss caused by FIFO overflow more likely to occur.

lbi This parameter takes a dword as parameter. The dword is written as-is into the DSCC-4 LBI configuration register. Do not change if you dont know what you are doing.

oscp
    This parameter enables or disabled the on-board crystal oscillator. This might come in handy if power consumption is a concern, or harmonics of the oscillator frequency cause receiver interference. The oscillator is only needed for internal clocking modes like G3RUH.

Local Parameters

code
    The channel coding type can be specified with this parameter. Possible values are NRZ (non-return to zero), NRZI (non-return to zero inverted, FM0, FM1 and MANCH (manchester). Most modems want NRZ and do conversion themselves. G3RUH and old TCM-3105 style AFSK modems like NRZI.

clk The clocking mode of each channel can be specified here. Valid modes are DF9IC (external RX and TX clock, no oversampling), G3RUH (external RX clock, internal TX clock from baud rate generator, no oversampling), TCM3105 (internal RX clock, derived from internal DPLL, internal TX clock from baud rate generator), HS (High Speed, external RX and TX clock like DF9IC, but with clock gapping on handshake lines, reserved for future purposes). Note that with internal timing you may want to put signals through to the clock lines with the txclk and rtsclk parameters. If you need a clocking mode not contained herein, please contact me.

duplex
    This parameter sets the channel type, possible values are HALF for half duplex operation, FULL for full duplex operation and FULLPTT for full duplex operation with RTS line always asserted. In full duplex operation channel arbiting does not take place, instead if some frame arrives from the MAC layer, RTS signal is asserted (if not already is) and it is sent out immediately. Note that in FULLPTT-mode there is no TX-delay and no TX-tail. In old versions of this driver this is also true for the standard "FULL" duplex mode. It was changed in driver version 1.84. Old behaviour can be emulated by setting TX-delay and TX-tail parameters to zero manually. In half duplex operation mode the standard channel access methods (namely CSMA or DAMA) are performed by the MAC layer and TX-delay and TX-tail timing is active (see txdmode).

pll This parameter only has effect in modes with internal receive clock (when the internal DPLL is used for clock regeneration). It enables/disables the 180 degree phase shift algorithm. This allows for a very quick lock on the RX clock when enabled. Unfortunately the DPLL not only locks very quick but also unlocks pretty fast again in case of noise on the signal. Thus in these cases the SLOW setting is recommended and an increase in TX-delay on the other side of the link is neccessary.

brg For internal timing modes the internal clock is derived from the on-board crystal oscillator using the baud rate generator (BRG). This is nothing else but a programmable divider. The value by which the crystal clock is divided can be programmed here. For example, if the onboard oscillator is a 7.3728 MHz type and you want to generate a 9600 bps signal you have to specify 768 here. Note that setpciscc can not do this work for you since it does not know what oscillator you placed on the board. Also note, that there has to be an oscillator or other clock source on board and it has to be enabled (see oscp setting). Not all division ratios are possible, setpciscc selects automagically the one which is next to what you specified. You can easily find out whether the ratio setpciscc selected for you meets your requirements by looking at the old/new parameter display.

txclk
    This parameter allows to enable or disable the clock driver on the TxClk line. If disabled, this line is input or High-Z. If enabled the internal transmit clock can be monitored. This might be of interest for G3RUH modems. Enabling this setting makes only sense in clocking modes with internal TX clock. Be careful not to evaporate the TxClk driver! This is a totem pole!

rtsclk
    This parameter allows to monitor the transmit clock on the RTS line. Here the same applies as for the txclk parameter. Be careful not to roast the RTS driver! This is a totem pole, too!

dinv
    This parameter allows to invert the TxData line. Disable it for normal operation.

txdata
    This parameter allows to select the TxData driver type. Valid modes are TP (totem pole, default) and OD (open drain). Be careful with this one, it, too, can deliver a lot of current.

cdinv
    With this parameter you can invert the function of the carrier detect line (DCD). This needs to be turned off for all modems I am aware of.

loop
    This parameter can be used to activate an on-chip loopback function. If enabled, the TxData and RxData ports are disconnected from the internal lines and those are tied together. That way, the SCC cores and local software can be tested. Set to off for normal operation. Note that the loopback only applies to the data lines. In order for this to work you may also want to enable a clocking mode with internal receive clock generation and synchronize receive and transmit clock.

txdmode
    This parameter can take two values: HARD and SOFT. It tells the channel control whether TX-delay and TX-tail are hardware generated using the RTS/CTS handshake lines or needs to be software generated using the on-board timers. This is only relevant in half duplex and "normal" full duplex modes. In FULLPTT mode no TX-delay or TX-tail takes place. Currently there is - to my knowledge - no modem out there implementing hardware TX-delay as would be the RightThing (TM). Leave this in SOFT mode. Note that we are wasting four high-resolution timers here for this stupid thing - which - fortunately - is not too bad since we have them on-chip.

txd This parameter represents the TX-delay in bits. This one is only of interest in SOFT TX-delay mode (see txdmode parameter). At a link speed of 9600 bps for example 20 ms would be 192. Note that this must be specified in bits not only due to my laziness, but also since there is no way (ioctl) for setpciscc of knowing the bit rate, which is due to my laziness.

txt This parameter specifies the TX-tail in bits like txd does for TX-delay. Note that TX-tail should not be set to zero for G3RUH and DF9IC-alike modems since the last data bit takes some time to propagate through the scrambler and FIR-Filter.

shflg
    This boolean parameter enables or disables shared flag transmission. A shared flag is a flag sequence between two frames which for the first frame is the closing flag and for the second frame is the opening frame. This is provided as an option since there is some buggy hardware out there which cannot cope with shared flags. If you need to communicate with such hardware, set this to off. Otherwise leave it on since it speeds up the link and - in addition to this - is quiet cool. Note that reception of shared flags is always possible. Even the reception of two flags with shared zeros works correctly.

crc This parameter specifies the type of CRC polynom to use. Two options are possible: CRC-32 and CRC-16 (default). HDLC defines only CRC-16, so this is the option used on most amateur radio (and commercial) links. However, error-detection is not very reliable with CRC-16. Thus, this parameter was created. Both link partners have to agree on it for this to work. Note that CRC-32 makes especially sense when stupid and/or Layer 3/4-less protocol stacks are used.

crcinit
    This parameter specifies the CRC initialization value. It can be chosen from 0000 and FFFF (which of cause mean 00000000 and FFFFFFFF in CRC-32 mode). Both stations have to agree on one value. HDLC standard is FFFF.

crcrx
    This parameter tells the driver whether it should check the CRC of every received frame. Due to high error probability on radio links I can imagine no situation where it makes sense to turn this off other than for testing purposes.

crctx
    This parameter tells the SCC core whether it should generate the CRC sequence and append it to every frame being sent. See crcrx for more comments.

pamb
    This parameter specifies a preamble byte which can be sent before the opening flag of every frame. During this period no bit stuffing or one insertion takes place. This preamble could theoretically be used for exact clock regeneration or data aid to channel equalization. However, currently no modem hardware makes use of this feature.

prep
    This variable specifies the amount of repeats of the preamble byte specified with the pamb option. It can take the discrete values 0, 1, 2, 4 or 8. A 0 disables this feature.

oneins
    This parameter enables or disables a HDLC extension commonly referred to as one insertion. This is quiet similar to zero bit insertion (bit stuffing). After seven consecutive zeros in the data stream a one gets inserted, which ensures DPLL operation even with NRZ channel coding. Of cause both link partners have to agree on using this feature to make communication possible.

fill
    This parameter allows for the specification of what bit sequence to use for interframe fill as well as for TX-delay and TX-tail. It can take two values: ONE and FLAGS with the latter being the default. The advantage of using ones as TX-delay bit sequence is that the resulting NRZI data stream yields more transients, which makes clock recovery easy. Note that PICPAR modems and other half-duplex-only modems which tie RxData and TxData lines together require a setting of ONE here because otherwise receive data will be corrupted.

LED Parameter

led The led parameter tells the board which channel LEDs to switch on. 0 means both off, 1 means only red one is on, 2 means the green one is on, 3 means both diodes are on.

LBI Access Parameters

-r  Specifies that a read cycle is to be performed. Only 32-bit accesses (dword) are supported.

-w  Specifies that a write cycle is to be performed. Only 32-bit accesses (dword) are supported.

addr
    Specifies the address for the read or write cycle. This setting is mandatory.

data
    Specifies the data dword to be written. This is only possible when a write access is carried out.

Calibration Parameter

time
    The time parameter specifies, how long to put the transmitter into calibration mode. The value is expressed in bits. For example, a value of 12000 at a bit rate of 1200 bps means 10 seconds. A value of 0 immediately stops any calibration.

HOW TO SET UP A SCC PORT
This paragraph does not neccessarily belong into this manual page, but I do not know where to put it. After the modem is connected to the PCISCC-4 board, the card is inserted into the PCI slot, the system is turned on an Linux booted up successfully, use the lspci utility or take a look at the file /proc/pci to find out if the board was initialized successfully by the PCI driver. For each PCISCC-4 board in the system a PCI device 110a:2102 should have been identified. Per board one IRQ and two address regions should have been assigned. Previously you should have compiled a new Linux kernel with PCISCC-4 driver (see Amateur Radio Support section) either in the main kernel or as module. AX.25 support has to be enabled, too. Only the new AX.25 network stack is supported, see http://www.afthd.tu-darmstadt.de/~dg1kjd/linux-ax25 . When the module is inserted (or at kernel bootup respectively) the PCISCC-4 boards are recognized and for each board four interfaces are created, the first board gets the interfaces dscc0 to dscc3 which represent the connectors SCC0 through SCC3. The default interface configuration (suitable for DF9IC modem at 9600 bps with pretty conservative TX-delay and -tail settings) is copied to the interfaces. The configuration can be changed using the setpciscc command with the -g and -d switches. After this step is finished a MAC address can be assigned to the interface in question and the interface can be upped: ifconfig dscc0 hw ax25 dg1kjd-8 mtu 256 up The transmitter will be keyed for a short time while the transmit bit rate is probed. When this was not successful, a message will be printed telling you so. The interface will be up in any case, but later if you try to send something a TX hang will be detected and the driver will down the interface again. The configured interface is ready for operation in principle now. You can check that by adding an AX.25 route axparms -route add dscc0 db0dar and connecting that node: call dscc0 db0dar Of cause I assume you got the ax25-utils compiled and working by now. If you want to go into TCP/IP, configure the IP coupling interface: ifconfig ipax0 44.130.24.229 hw ax25 dg1kjd-9 mtu 1200 up Add host route to one of your neighbours and default route: route add -host 44.130.25.80 ipax0 route add default gw 44.130.25.80 Add ARP table entry for your neighbour: arp -H ax25 -s 44.130.25.80 db0ais-10 Of cause an AX.25 route is also mandatory... axparms -route add dscc0 db0ais-10 db0dar And you should be ready to go... ping -i 20 44.130.42.3

CAUTION
Be careful when enabling txclk and rtsclk. This makes these ports totem pole outputs while they are normally supposed to be inputs. This can lead to hardware defects if another driver drives the line, too. Do not use the LBI transaction stuff unless you know what you are doing. It will lock up your machine. The TX kick (-k) option is only a last-resort means (right before trying to configure the interface down and up again). If TX lockup reoccurs in a regular manner, exchange mainboard, cache and/or RAM. Check if system is overclocked. Overclocking also risks cache inconsistencies.

BUGS
None known, otherwise they would have been nailed down. The synopsis paragraph is ugly. In July 2001 the manual page was updated to reflect modified behaviour of the pciscc4 driver (1.84) as far as the full duplex mode and TX-delay/TX-tail is concerned. Also a note about handling of PICPAR modems was added in the fill-parameter description.

SEE ALSO
ifconfig(8), axparms(8), route(8), arp(8), ping(8), call(1),
linux/drivers/net/hamradio/pciscc4.c,
linux/include/linux/pciscc4.h

AUTHOR
This manual page, the setpciscc tool, PCISCC-4 board and device driver were written by Jens David, DG1KJD <dg1kjd@afthd.tu-darmstadt.de> in Summer/Fall 1999. The setpciscc tool uses command line parsing code by Joerg Schilling, <js@cs.tu-berlin.de> for your convenience.