Merge commit 'c5bab7026b8e0ac44b25ee08507ea360f177d844' into merges

[unleashed.git] / share / man / man8 / syncloop.8

'\" te
.\" Copyright (c) 1993, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SYNCLOOP 8 "Mar 9, 1993"
.SH NAME
syncloop \- synchronous serial loopback test program
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/syncloop\fR [\fB-cdlstv\fR] \fIdevice\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsyncloop\fR command performs several loopback tests that are useful in
exercising the various components of a serial communications link.
.sp
.LP
Before running a test, \fBsyncloop\fR opens the designated port and configures
it according to command line options and the specified test type. It announces
the names of the devices being used to control the hardware channel, the
channel number (ppa) corresponding to the \fIdevice\fR argument, and the
parameters  it has set for that channel. It then runs the loopback test in
three phases.
.sp
.LP
The first phase is to listen on the port for any activity.  If no activity is
seen for at least four seconds, \fBsyncloop\fR proceeds to the next phase.
Otherwise, the user is informed that the line is active and that the test
cannot proceed, and the program exits.
.sp
.LP
In the second phase, called the "first-packet" phase, \fBsyncloop\fR attempts
to send and receive one packet. The program will wait for up to four seconds
for the returned packet. If no packets are seen after five attempts, the test
fails with an excoriating message. If a packet is returned, the result is
compared with the original. If the length and content do not match exactly, the
test fails.
.sp
.LP
The final phase, known as the "multiple-packet" phase, attempts to send many
packets through the loop. Because the program has verified the integrity of the
link in the first-packet phase, the test will not fail after a particular
number of timeouts. If a packet is not seen after four seconds, a message is
displayed. Otherwise, a count of the number of packets received is updated on
the display once per second. If it becomes obvious that the test is not
receiving packets during this phase, the user may wish to stop the program
manually. The number and size of the packets sent during this phase is
determined by default values, or by command line options. Each returned packet
is compared with its original for length and content. If a mismatch is
detected, the test fails.  The test completes when the required number of
packets have been sent, regardless of errors.
.sp
.LP
After the multiple-packet phase has completed, the program displays a summary
of the hardware event statistics for the channel that was tested. The display
takes the following form:
.sp
.in +2
.nf
CRC errors   Aborts   Overruns   Underruns   In<-Drops-> Out
        0         0          0           0   0             0
.fi
.in -2
.sp

.sp
.LP
This is followed by an estimated line speed, which is an approximation of the
bit rate of the line, based on the number of bytes sent and the actual time
that it took to send them.
.SH OPTIONS
.sp
.LP
The options for \fBsyncloop\fR are described in the following table:
.sp

.sp
.TS
c c c c
l l l l .
\fBOption\fR    \fBParameter\fR \fBDefault\fR   \fBDescription\fR
\fB-c\fR        \fIpacket_count\fR      100     T{
Specifies the number of packets to be sent in the multiple-packet phase.
T}
\fB-d\fR        \fIhex_data_byte\fR     \fIrandom\fR    T{
Specifies that each packet will be filled with bytes with the value of \fIhex_data_byte\fR.
T}
\fB-l\fR        \fIpacket_length\fR     100     T{
Specifies the length of each packet in bytes.
T}
\fB-s\fR        \fIline_speed\fR        9600    Bit rate in bits per second.
\fB-v\fR                        T{
Sets verbose mode.  If data errors occur, the expected and received data is displayed.
T}
\fB-t\fR        \fItest_type\fR \fInone\fR      T{
A number, from 1 to 4, that specifies which test to perform.  The values for \fItest_type\fR are as follows: \fB1\fR: Internal loopback test.  Port loopback is on.  Transmit and receive clock sources are internal (baud rate generator). \fB2\fR: External loopback test.  Port loopback is off.  Transmit and receive clock sources are internal.  Requires a loopback plug suitable to the port under test. \fB3\fR: External loopback test.  Port loopback is off.  Transmit and receive clock sources are external (modem).  Requires that one of the local modem, the remote modem, or the remote system be set in a loopback configuration. \fB4\fR: Test using predefined parameters.  User defines hardware configuration and may select port parameters using the \fBsyncinit\fR(8) command.
T}
.TE

.sp
.LP
All numeric options except \fB-d\fR are entered as decimal numbers (for
example, \fB\fR\fB-s\fR\fB 19200\fR). If you do not provide the \fB-t\fR\fI
test_type\fR option, \fBsyncloop\fR prompts for it.
.SH EXAMPLES
.LP
\fBExample 1 \fRA sample display of using the \fBsyncloop\fR command.
.sp
.LP
In the following command \fBsyncloop\fR uses a packet length of 512 bytes over
the first CPU port:

.sp
.in +2
.nf
\fBexample# syncloop \fR\fB-l\fR\fB 512 zsh0\fR
.fi
.in -2
.sp

.sp
.LP
In response to the above command, \fBsyncloop\fR prompts you for the test
option you want.

.sp
.LP
The following command performs an internal loopback test on the first CPU port,
using 5000 packets and a bit rate of 56Kbps:

.sp
.in +2
.nf
\fBexample# syncloop \fR\fB-t\fR\fB 1 \fR\fB-s\fR\fB 56000 \fR\fB-c\fR\fB 5000 zsh0\fR
.fi
.in -2
.sp

.SH SEE ALSO
.sp
.LP
\fBsyncinit\fR(8), \fBsyncstat\fR(8), \fBattributes\fR(5), \fBzsh\fR(7D)
.SH DIAGNOSTICS
.sp
.ne 2
.na
\fB\fIdevice\fR\fB missing minor device number\fR\fR
.ad
.sp .6
.RS 4n
The name \fIdevice\fR does not end in a decimal number that can be used as a
minor device number.
.RE

.sp
.ne 2
.na
\fB\fBinvalid packet length: \fR\fInnn\fR\fR
.ad
.sp .6
.RS 4n
The packet length was specified to be less than zero or greater than 4096.
.RE

.sp
.ne 2
.na
\fB\fBpoll: nothing to read\fR\fR
.ad
.sp .6
.RS 4n

.RE

.sp
.ne 2
.na
\fB\fBpoll: nothing to read or write.\fR\fR
.ad
.sp .6
.RS 4n
The \fBpoll\fR(2) system call indicates that there is no input pending and/or
that output would be blocked if attempted.
.RE

.sp
.ne 2
.na
\fB\fBlen \fR\fIxxx\fR\fB should be \fR\fIyyy\fR\fR
.ad
.sp .6
.RS 4n
The packet that was sent had a length of \fIyyy\fR, but was received with a
length of \fIxxx\fR.
.RE

.sp
.ne 2
.na
\fB\fInnn\fR\fB packets lost in outbound queueing\fR\fR
.ad
.sp .6
.RS 4n

.RE

.sp
.ne 2
.na
\fB\fInnn\fR\fB packets lost in inbound queueing\fR\fR
.ad
.sp .6
.RS 4n
A discrepancy has been found between the number of packets sent by
\fBsyncloop\fR and the number of packets the driver counted as transmitted, or
between the number counted as received and the number read by the program.
.RE

.SH WARNINGS
.sp
.LP
To allow its tests to run properly, as well as prevent disturbance of normal
operations, \fBsyncloop\fR should only be run on a port that is not being used
for any other purpose at that time.