Return to bsctr.4 CVS log

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

Annotation of cci/usr/src/usr.bin/bsc/doc/bsctr.4, revision 1.1

1.1     ! root        1: .TH BSCTR 4 DLBA 1.2
        !             2: .SH NAME 
        !             3: bsctr \- BISYNC trace device
        !             4: .SH DESCRIPTION 
        !             5: A prerequisite to fully understanding this section of the manual is a general
        !             6: background in binary synchronous communications, which may be had by reading
        !             7: the IBM General Information on Binary Synchronous Communications document,
        !             8: mentioned in SEE ALSO, to follow.  As well, understanding the data
        !             9: returned by this pseudo-device requires an overall understanding
        !            10: of the protocol state machine diagrams appended to this document.
        !            11: An explanation of those diagrams appears in the PROTOCOL STATE MACHINE
        !            12: section to follow.
        !            13: .P
        !            14: Opening the 
        !            15: .I bsctr 
        !            16: device will cause a process to wait until the corresponding 
        !            17: .I bsc 
        !            18: device is
        !            19: opened. Only one process may have the trace device open at a time.
        !            20: The device can only be opened for reading.
        !            21: .P
        !            22: When a port being controlled by the 
        !            23: .I bsc 
        !            24: driver is opened,
        !            25: presumably by another process, the process opening the trace device
        !            26: (the tracing process) will return from the open. The 
        !            27: .I bsc
        !            28: device driver will place information on state transitions
        !            29: in the protocol state machine (and optionally, the actual data being
        !            30: sent and received) into a circular buffer. Reads to the trace device
        !            31: result in information being transferred from this circular buffer
        !            32: to the tracing process.  It is easily possible to lose information
        !            33: being placed into the buffer if it is not read before it becomes
        !            34: full; to minimize risk of data loss, it is recommended that the tracing
        !            35: program merely copy information from the trace device to a file,
        !            36: with little if any processing.
        !            37: .P
        !            38: A read request for N bytes will be satisfied when (1) N bytes are
        !            39: available in the trace buffer, (2) the trace buffer becomes over
        !            40: half full, or (3) a transmit or receive operation has just completed.
        !            41: End of file will be indicated
        !            42: .I (read 
        !            43: returns a value of zero) when the corresponding 
        !            44: .I bsc 
        !            45: driver is closed.
        !            46: .P
        !            47: The data read consists of one or more trace records, of a form
        !            48: defined in 
        !            49: .I <bsctr.h>. 
        !            50: Basically, there are two
        !            51: overall types of trace information, the aforementioned state transition
        !            52: information and the actual data packets being transmitted and received.
        !            53: .P
        !            54: .nf
        !            55: .ta 0.8i 2.5i
        !            56: struct bsctr {
        !            57:        long tr_time;   /* time stamp */
        !            58:        char tr_state;  /* state number */
        !            59:        char tr_type;   /* type of record */
        !            60:        short tr_val;   /* if type=X or Y, length of data */
        !            61:        char tr_data[512];      /* data packet of tr_val bytes */
        !            62:        };
        !            63: .fi
        !            64: .P
        !            65: The time stamp is in 
        !            66: .I time(2) 
        !            67: form. The state number is one of those on the protocol state machine diagrams.
        !            68: The type of record can be S for sending data, R for waiting to receive
        !            69: date, C for completion of receive where tr_val gives the packet type,
        !            70: F for a function state, D for a decision state, E for an error state
        !            71: where tr_val gives the error code, and X or Y for actual data transmitted
        !            72: or received, respectively, where tr_val gives the length of the data
        !            73: packet immediately following.
        !            74: .P
        !            75: One 
        !            76: .I ioctl(2) 
        !            77: call is available to indicate to
        !            78: the trace device that data is to be recorded in the trace buffer
        !            79: as well as the default state transition information:
        !            80: .IP
        !            81:         ioctl (fildes, 1, 0)
        !            82: .SH "PROTOCOL STATE MACHINE"
        !            83: .P
        !            84: The protocol state machine consists of five types of states: Send,
        !            85: Receive, Decision, Function, and Error.  The Send state is denoted
        !            86: by a rectangule, with annotations regarding state number and data
        !            87: to be sent. A transition line indicates the next state to follow.
        !            88: .P
        !            89: The Receive state is denoted by a circle, and is annoted with the
        !            90: state number. At the completion of the receive operation, transition
        !            91: is made to another state depending on the type of packet received;
        !            92: there is also a transition marked with a dotted line indicating the
        !            93: state to receive control if nothing is received within the timeout
        !            94: interval. Packet types include ENQ, STX...ETB, STX...ETX, EOT, DLE-EOT,
        !            95: ACK-0, ACK-1, TTD (STX...ENQ), WACK, and RVI.
        !            96: .P
        !            97: A Function state is indicated by a single line, annoted with state
        !            98: number. A Decision state is indicated by a triangle. The difference
        !            99: between the two states is that a Function has only one successor
        !           100: state, where a Decision may have several. The two states are represented
        !           101: differently for clarity.
        !           102: .P
        !           103: An Error state is shown as a five-sided object, and is annotated
        !           104: with the state number and with the error type. This state always
        !           105: results in a transition to state zero.
        !           106: .SH "SEE ALSO"
        !           107: .br
        !           108: bscmon(8) \- monitoring and tracing utilities
        !           109: .br
        !           110: .I
        !           111: General Information \- Binary Synchronous Communications,
        !           112: IBM document GA27-3004.
        !           113: .SH FILES
        !           114: /dev/bsc?tr

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