![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to bsctr.4 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / usr.bin / bsc / doc|
Return to bsctr.4 CVS log | Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / usr.bin / bsc / doc |
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.