This chapter describes the utilities associated with SunHSI/S interface driver, and it introduces the SunVTS sunlink diagnostic software.

The SunHSI/S software includes its own serial port utilities. These utilities provide a superset of the features described in this chapter.

The port naming conventions are used by initialization and serial port diagnostic commands. Software port names for SunHSI/S ports are of the form hih N , where N is a number in a range starting with 0 and ending at one fewer than the number of serial ports on your machine. For example, on a system with one SunHSI/S adapter installed, the serial ports are named hih0 , hih1 , hih2 , and hih3 .

SunHSI/S port names have the format: hih y , where y represents the port number. Initially, the port numbers 0 , 1 , 2 , or 3 are reserved for the first SunHSI/S adapter, and 4 , 5 , 6 , or 7 are reserved for the second adapter, and so on. For example, hih1 would be the name for port 1 (the second port) on the first SunHSI/S adapter. Table 2-2 displays the relationship between the software port numbers (as used in SunHSI/S port names) and the hardware port numbers used on each adapter.

For example, when you initially install two SunHSI/S adapters on a system, the port numbers will range from 0 to 7. If you remove an adapter and install a new adapter, the new adapter's software port numbers will range from 8 to 11, and the new software port names will be: hih8 , hih9 , hih10 , and hih11 . If you continue to remove and replace SunHSI/S adapters, the software port numbers and port names will continue to be incremented up to a maximum of 159.

Use the hsi_stat -a command to display all the valid SunHSI/S ports on the system. See The hsi_stat Command for more information about this command.

The hsi_init command enables you to display and modify some of the hardware operating modes common to high-speed serial lines. These features make the hsi_init command valuable when troubleshooting and repairing problematic serial link lines.

Other applications also use the hsi_init command. For example, some applications use the hsi_init command to initialize serial ports, and the hsi_loop command (described in The hsi_loop Command ) uses the command in a number of loopback tests.

When using hsi_init at the command line, the first argument required by the command is always the port name of the link being displayed or modified (for example, hih0 ). With no further arguments, hsi_init displays the parameter values as presently set on the selected link:

# hsi_init hih0 

port=hih0 speed=1536000, mode=fdx, loopback=no, nrzi=no, mtu=1600, mru=1600,

	txc=txc, rxc=rxc, txd=txd, rxd=rxd, signal=no.

You can set all of the hsi_init parameters shown in the Usage statement below.

# hsi_init

Usage: hsi_init ifname \

	[baudrate] [loopback=[no|yes]] [nrzi=[yes|no]] \

	[txc=[txc|-txc|baud|rxc]] [rxc=[rxc|-rxc|baud]] \

	[mode=[fdx|ibm-fdx|ibm-hdx|ibm-mpt]] [signal=[yes|no]] \

	[external|sender|stop|reset] \

	[mtu=<mtu_size>] [mru=<mru_size>] \

	[txd=[txd|-txd]] [rxd=[rxd|-rxd]]

To set these parameters, use the syntax hsi_init portname keyword = value . For example, to set the maximum transmission unit ( mtu ) parameter of port hih2 to 1000 bytes, you would type:

# hsi_init hih2 mtu=1000

TABLE 2-3 displays the possible values for each of these hsi_init parameters and lists the default values as initialized by the SunHSI/S driver for each port. The parameter values are described in greater detail after this table.

The speed parameter sets the line speed, or baud rate, of the serial line in bits per second. You can set this parameter to be from 0 to 2048000 bps.

In most situations, the actual line speed is determined by the modems in use, not by the Sun hardware, so the speed set by hsi_init is used only for compiling performance statistics for the hsi_stat command (see The hsi_stat Command ). The speed parameter is significant when you are using the internal (workstation or server) baud generator to generate clocking. You invoke the internal baud generator when you use the txc=baud or rxc=baud settings with the hsi_init command (these parameters are described below).

This parameter sets and reports the internal loopback state of the serial chip. Setting a link to an internal loopback state ( loopback=yes ) is useful for testing serial ports that are not attached to external loopback equipment.

After testing a port, you can disable the internal loopback state on the port by setting the parameter to no :

# hsi_init portname loopback=no

This parameter is set to loopback=yes transparently by the hsi_loop command when you run the hsi_loop -t 1 portname test. (See The hsi_loop Command for more information.)

This parameter sets the port to operate with NRZI ( Non-Return to Zero, Inverted) data encoding. This parameter can be yes for NRZI encoding or no for NRZ encoding.

NRZ data encoding maintains a constant voltage level when data is present and does not return to a zero voltage until data is absent. The data is decoded as an absolute value based on the voltage level, which is 1 when data is present and 0 when data is absent.

NRZI data encoding does a voltage transition when data is absent (voltage level 0), and it does not do a voltage transition (no return to 0) when data is present (voltage level 0). With NRZI, the data is decoded using relational decoding.

Sets the origin of the clocking for the transmitted data. For transmitted data, you can set the clock origin to:

• txc - Incoming transmit clock (TxCI signal)

• -txc - Inverted incoming transmit clock

• rxc - Incoming receive clock (RxC signal)

• baud - Internal (workstation) baud rate generator

The default for SunHSI/S ports is txc=txc . When txc=baud , the speed argument of the hsi_init command, not the modem clocking, controls the data rate. To accommodate the requirements of T1 or CEPT transmission equipment, this signal can be inverted ( txc=-txc ). See Appendix A for more information.

Sets the origin of the clocking for the received data. You can set the clock origin to:

• rxc - Incoming receive clock (RxC signal)

• -rxc - Inverted incoming receive clock

• baud - Internal (workstation) baud rate generator

The default for SunHSI/S ports is rxc=rxc . To accommodate the requirements of T1 or CEPT transmission equipment, this signal can be inverted ( rxc=-rxc ). See Appendix A for more information.

The mode parameter sets the operating mode of the serial link. The two main operating modes used by the SunHSI/S software are high-level data link control ( HDLC) mode and IBM ( SDLC) mode.

The values mode are:

• fdx - HDLC compatible full-duplex

• ibm-fdx - IBM compatible full-duplex

• ibm-hdx - IBM compatible half-duplex

• ibm-mpt - IBM compatible multi-point multi-drop

The default mode value is fdx . See Appendix A for more information about operating modes.

Controls whether modem signal (RTS and CTS) changes are reported back by the driver to the application. When this parameter is set to yes , these changes are reported.

The mtu parameter sets the packet size of the maximum transmission unit, and the mru parameter sets the packet size of the maximum receive unit. By adjusting these parameters, you may achieve better performance out of the link. Both of these parameters can be set between 1 and 1600 bytes.

These flags are used for inverting transmit ( txd ) and receive ( rxd ) data on serial lines. You can switch the polarity of a link by setting these flags to be negative (for example, -txd and -rxd ). When txd=txd , the transmit data is not inverted, and when txd=-txd , the transmit data is inverted. Likewise, when rxd=rxd , the receive data is not inverted, and when rxd=-rxd , the data is inverted. These flags are useful when you run SunHSI/S over T1 and CEPT lines (see Appendix A for more information).

You can also use the following set of one-word commands to specify useful combinations of hsi_init parameters.

One clocking arrangement, called sender clocking, is useful for testing because it requires cabling only between the two systems under test, without intervening modems or modem eliminators. To configure sender clocking, use the sender command ( txc=baud , rxc=rxc , loopback=no ). This causes the transmitting side to generate a clock signal, which can then be routed to the receive clock on the receiving side. In fact, since each direction of data flow has independent clocking, the two directions can have different speeds, each determined by the speed option on the transmitting system.

Configuring Internal or External Clocking

To configure an RS-449 port to provide transmit clocking for itself as well as receive clocking for the other end of the link, set the txc (transmit clock) and rxc (receive clock) parameters in hsi_init to baud and rxc , respectively. For example, the following hsi_init command sets the data rate of the first CPU serial port to 9600 bps and sets the clocking as just described:

# hsi_init hih0 9600 txc=baud rxc=rxc 

You enter such a command at both ends of a link if both sides are supplying clocking.

If you have Sun systems at both ends of a link and one machine supplies clocking for both sides, you would type the following on the machine that is not supplying clocking:

# hsi_init hih0 9600 txc=txc rxc=rxc 

The hsi_loop Command

The hsi_loop command performs a loopback test that checks the following components of your communications link:

• Port-driver software layering

• CPU-to-port communication

• Correct operation of the serial port

• Cable from port to modem (or modem equivalent)

• Local and remote modems (or modem equivalents)

• Transmission line

When you invoke hsi_loop , it runs the hsi_init command to initialize the serial port and send out packets. hsi_loop then reads the incoming packets to verify that they were received. It also verifies the packet length and checks that the data is correct.

To stop an active port (in this example, hih0 ), type the following hsi_init command:

# hsi_init hih0 0 

port=hih0 speed=0, mode=fdx, loopback=no, nrzi=no, mtu=1600, mru=1600,

	txc=txc, rxc=rxc, txd=txd, rxd=rxd, signal=no

As an alternative to specifying a speed of 0 , you can use the stop or reset commands (see TABLE 2-5 ). After you finish with hsi_loop testing, you must restart your link to reinitialize your serial port.

An hsi_loop command takes the following general form:

# hsi_loop[options] portname

where portname is, for example, hih2 .

The options for hsi_loop are described in TABLE 2-5 .

Enter all numeric options except -d (hex data byte) as decimal numbers (for example, -t 3 ). If you do not provide the test type option, hsi_loop prompts for it, as in the following example:

# hsi_loop hih1 

[ Using /dev/hih1 ]

Enter test type:

1: Internal Test

            (internal data loop, internal clocking)

2: Test using loopback plugs

            (external data loop, internal clocking)

3: Test using local or remote modem loopback

            (external data loop, external clocking)

4: Other, previously set, special mode

> 2

An alternative to the preceding command is to specify the test type on the command line:

# hsi_loop -t 2 hih1 

In the preceding command line, note that hsi_loop requires a space between the option switch ( -t ) and the number.

Test Type Options

This section contains descriptions of the available test type options. You specify test type options with the -t option, as described in TABLE 2-5 .

Test Option 1 - Internal Test

This option uses the internal clocking and internal loopback and runs the following hsi_init command:

hsi_init portname speed loopback=yes txc=baud rxc=baud

The test data packets (100 by default) are sent to the specified serial port and looped back internally. You do not need a loopback plug for this option.

Test Option 2 - Test Using Loopback Plugs

This option uses the internal clocking and requires a loopback plug. Option 2 runs the following hsi_init command:

hsi_init portname speed loopback=no txc=baud rxc=rxc

The test data packet will loop between the CPU and serial port through the loopback plug. Before using this option, install an RS-449 loopback plug (part number 530-1430-01) on the specified port or the 96-pin loopback plug (part number 370-1381-01) into the back of the SunHSI/S adapter.

Test Option 3 - Test Using Local or Remote Modem Loopback

This option uses the external clocking set by the modem and runs the following hsi_init command:

hsi_init portname speed loopback=no txc=txc rxc=rxc 

Testing with a modem in local loopback mode verifies proper operation of the serial port, the external cable, and the local modem. Testing with the modem in remote loopback mode checks the components just mentioned, as well as verifying the operation of the communications link.

With test type option 3, hsi_loop treats both local and remote modem loopback testing the same, since clocking is provided by the modem in both cases. Whether the data is looped back through the local or remote modem depends on how the modems are set up.

If the test fails on remote modem loopback but succeeds on local modem loopback, carefully check the transmission line and the setup of both modems.

Test Option 4 - Use Previously Set Mode

There is no automatic hsi_init execution with this option. This enables you to use hsi_init before running hsi_loop to specify clocking and loopback options that are not possible with the other hsi_loop test options.

For example, you can make the local side supply transmit clock at a desired speed (for example, 19200 bps: hsi_init hih N speed=19200 txc=baud rxc=rxc ), and run the hsi_loop command on the local side with test option 4.

To run the test for the hsi_loop command, enter:

# hsi_loop -t4 hihN 

hsi_loop Output

When the loopback test runs successfully using any of the test type options, hsi_loop reports the statistics shown in the following sample output and then terminates.

# hsi_loop hih1 

Enter test type:

1: Internal Test

            (internal data loop, internal clocking)

2: Test using loopback plugs

            (external data loop, internal clocking)

3: Test using local or remote modem loopback

            (external data loop, external clocking)

4: Other, previously set, special mode

> 2

speed=9600, loopback=no, nrzi=no, txc=baud, rxc=rxc

[ checking for quiet line ]

[ Trying first packet ]

[ Trying many packets ]

100 

100 packets sent, 100 received

Port    CRC errors     Aborts   Overruns  Underruns     In <-Drops-> Out

hih1:            0          0          0          0      0             0

hih1:   estimated line speed = 9480 bps

#

The hsi_stat Command

The hsi_stat command provides information about the packets transmitted and received on a synchronous serial line. The hsi_stat command is a valuable tool for monitoring your serial link.

The syntax for hsi_stat depends on whether you want to display the statistics of a single port or a number of ports.

Displaying Statistics for a Single Port

If you want to display the statistics for a single port, the hsi_stat syntax is:

# hsi_stat [-c] [-f] device [period] 

The device is the device name of the port ( hih0 , hih1 , hih3 , and so on), which is required to display the statistics from one port (see TABLE 2-6 for a description of the hsi_stat statistics). You can use the period option to display a series of port statistics at a specified interval of seconds.

By default, hsi_stat reports the cumulative statistics of the port since the system boot time. However, you can clear the statistics of a port using the -c flag. This flag resets the port statistics to zero.

With the -f flag you can display the full set of statistics of a serial port. This option is useful for debugging purposes.

Displaying Statistics for a Number of Ports

If you want to display the statistics of a number of ports, the hsi_stat syntax is:

# hsi_stat [-c] [-f] -a | number_of_ports

Replace the number_of_ports variable with a decimal number. The hsi_stat command displays the statistics of the specified number of ports. For example, if you type the command hsi_stat 3 , hsi_stat displays the statistics of the first three valid ports.

The -c and -f flag can also be used on a number of ports. For example,
hsi_stat -c 2 clears the statistics of the first two valid ports. Use the -a flag to specify all the valid SunHSI/S ports on the system.

hsi_stat Output Description and Examples

TABLE 2-6 describes the statistics in the hsi_stat output.

The example below shows the hsi_stat command displaying the statistics of the hih1 port:

# hsi_stat hih1 

speed   ipkts   opkts  undrun  ovrrun   abort    crc   isize   osize

1536000  101     101      0       0       0       0     100     100

If you do not enter the optional interval parameter, hsi_stat terminates after printing the one-line cumulative total of the line statistics.

If you enter a time interval (expressed in seconds), hsi_stat operates in an iterative sampling mode, sampling and then displaying line use data for the period specified. In this mode, hsi_stat does not output cumulative totals, but displays the incremental changes in the totals between iterations. For example, the command:

# hsi_stat hih1 10 

would produce output similar to the following. Note that in this example, the display is updated every ten seconds, until you press Control-C to stop the output.

ipkts opkts undrun ovrrun abort crc iutil outil 

12    10    0      0      0     0     5%    4% 

22    60    0      0      0     0     3%   90% 

36    14    0      0      0     1    51%    2% 

Using the hsi_stat command with an interval adds two fields to the report: iutil and outil . These two fields report the level of use for the serial line, as a percentage of incoming bandwidth ( iutil ) and outgoing bandwidth ( outil ). These percentages may occasionally be reported as slightly greater than 100% because of inexact sampling times and differences in the accuracy between the system clock and the modem clock. If the percentage of use greatly exceeds 100%, or never exceeds 50%, then the speed value of the hsi_init command probably varies greatly from the speed of the modem.

In the following example, the -a option is used to display all of the valid ports on the system.

# hsi_stat -a

 port     speed   ipkts   opkts  undrun  ovrrun   abort     crc   isize  osize

 hih8   1536000       0       0       0       0       0       0       0       0

 hih9   1536000       0       0       0       0       0       0       0       0

 hih10  1536000       0       0       0       0       0       0       0       0

 hih11  1536000       0       0       0       0       0       0       0       0

If you are experiencing communications problems, leave an hsi_stat command running on the console of the machine running an upper-level protocol so that you can see at a glance the recent history of loads and errors. For example, you can run hsi_stat hih0 60 to get one-minute samples of activity on port 0.

If hsi_stat reports that line use is consistently near 100%, you may need a faster line. Also, watch for errors on the line, especially CRC errors in input packets. A small percentage of such errors can cause severe throughput reduction. These errors are almost always caused by troubles in the communication facilities.

If you see output packets but no input packets, either the remote system is not initialized or the line is not properly connected to the remote system.

If you see neither input nor output packets, the physical layer was not successfully initialized.

SunVTS Diagnostic Testing

The SunVTS software executes multiple diagnostic hardware tests from a single user interface. It is used to verify the configuration and the functionality of most hardware controllers and devices. You operate the SunVTS diagnostic primarily from a user interface that enables you to control all aspects of the diagnostic test operation.

The sunlink diagnostic test, which is shipped with the SunVTS software, checks the functionality of SunHSI/S adapters. This test can be run from the SunVTS user interface or from the command line. Refer to the SunVTS documentation for more information about the sunlink test.

Platform Notes: The SunHSI/S Device Driver

816-2347-10

Copyright © 2002, Sun Microsystems, Inc. All rights reserved.