Return to bsctr.4 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / usr.bin / bsc / doc

Power 6/32 Unix version 1.21

.TH BSCTR 4 DLBA 1.2
.SH NAME 
bsctr \- BISYNC trace device
.SH DESCRIPTION 
A prerequisite to fully understanding this section of the manual is a general
background in binary synchronous communications, which may be had by reading
the IBM General Information on Binary Synchronous Communications document,
mentioned in SEE ALSO, to follow.  As well, understanding the data
returned by this pseudo-device requires an overall understanding
of the protocol state machine diagrams appended to this document.
An explanation of those diagrams appears in the PROTOCOL STATE MACHINE
section to follow.
.P
Opening the 
.I bsctr 
device will cause a process to wait until the corresponding 
.I bsc 
device is
opened. Only one process may have the trace device open at a time.
The device can only be opened for reading.
.P
When a port being controlled by the 
.I bsc 
driver is opened,
presumably by another process, the process opening the trace device
(the tracing process) will return from the open. The 
.I bsc
device driver will place information on state transitions
in the protocol state machine (and optionally, the actual data being
sent and received) into a circular buffer. Reads to the trace device
result in information being transferred from this circular buffer
to the tracing process.  It is easily possible to lose information
being placed into the buffer if it is not read before it becomes
full; to minimize risk of data loss, it is recommended that the tracing
program merely copy information from the trace device to a file,
with little if any processing.
.P
A read request for N bytes will be satisfied when (1) N bytes are
available in the trace buffer, (2) the trace buffer becomes over
half full, or (3) a transmit or receive operation has just completed.
End of file will be indicated
.I (read 
returns a value of zero) when the corresponding 
.I bsc 
driver is closed.
.P
The data read consists of one or more trace records, of a form
defined in 
.I <bsctr.h>. 
Basically, there are two
overall types of trace information, the aforementioned state transition
information and the actual data packets being transmitted and received.
.P
.nf
.ta 0.8i 2.5i
struct bsctr {
	long tr_time;	/* time stamp */
	char tr_state;	/* state number */
	char tr_type;	/* type of record */
	short tr_val;	/* if type=X or Y, length of data */
	char tr_data[512];	/* data packet of tr_val bytes */
	};
.fi
.P
The time stamp is in 
.I time(2) 
form. The state number is one of those on the protocol state machine diagrams.
The type of record can be S for sending data, R for waiting to receive
date, C for completion of receive where tr_val gives the packet type,
F for a function state, D for a decision state, E for an error state
where tr_val gives the error code, and X or Y for actual data transmitted
or received, respectively, where tr_val gives the length of the data
packet immediately following.
.P
One 
.I ioctl(2) 
call is available to indicate to
the trace device that data is to be recorded in the trace buffer
as well as the default state transition information:
.IP
        ioctl (fildes, 1, 0)
.SH "PROTOCOL STATE MACHINE"
.P
The protocol state machine consists of five types of states: Send,
Receive, Decision, Function, and Error.  The Send state is denoted
by a rectangule, with annotations regarding state number and data
to be sent. A transition line indicates the next state to follow.
.P
The Receive state is denoted by a circle, and is annoted with the
state number. At the completion of the receive operation, transition
is made to another state depending on the type of packet received;
there is also a transition marked with a dotted line indicating the
state to receive control if nothing is received within the timeout
interval. Packet types include ENQ, STX...ETB, STX...ETX, EOT, DLE-EOT,
ACK-0, ACK-1, TTD (STX...ENQ), WACK, and RVI.
.P
A Function state is indicated by a single line, annoted with state
number. A Decision state is indicated by a triangle. The difference
between the two states is that a Function has only one successor
state, where a Decision may have several. The two states are represented
differently for clarity.
.P
An Error state is shown as a five-sided object, and is annotated
with the state number and with the error type. This state always
results in a transition to state zero.
.SH "SEE ALSO"
.br
bscmon(8) \- monitoring and tracing utilities
.br
.I
General Information \- Binary Synchronous Communications,
IBM document GA27-3004.
.SH FILES
/dev/bsc?tr

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.