I. HOW TO USE THE DIAGNOSTIC MONITOR The ethernet diagnostic monitor package for the APMs provides the user with a facility to record data traffic on the ethernet and review this data. The data packets recorded can be interpreted up to the link level. I.1 Loading_The_Program To use an APM as a stand-alone diagnostic monitor on the ethernet an APM must be loaded with the Monitor Software Program. This program is held in the file 'e_mon:diagmon'. The 'e_mon' directory is protected by a password so that only authorised users have access to it. If the user wishes to make use of the APM's buffered output facility then the program in the file 'pub:decriter' should be loaded into the APM prior to loading the Monitor Software Program. The following sequence of commands will load the above mentioned programs. } l e_mon pass: xxxx } pub:decriter } diagmon I.2 Monitor_Input/Output All output from the monitor is sent to the VDU. The user provides input to the monitor from the keyboard. All control characters sent from the keyboard provoke the normal responses from the APM. The following control characters are particularly useful. abort program freeze output to VDU unfreeze output to VDU The monitor is always in one of two states;the dialogue state or the operational state. In the dialogue state the user is asked questions concerning the operation of the monitor. After posing a question the monitor presents the selection of possible answers or a range of values in which the answer must lie. A prompt is then given to indicate that input is required from the user. If the user returns an invalid answer the prompt will reappear. If the user returns a valid answer the monitor will ask another question of give an instruction. After the user has provided enough input to fully specify the selected mode of operation the monitor either enters the operational state,re-enters the dialogue state at a higher level or exits the program depending on the mode selected. In the operational state the monitor performs its specified task and outputs information to the VDU. When the task is complete the monitor is returned to the dialogue state upon a command from the user where questions are asked concerning the next operation to be performed. I.3 Monitor_Initialisation The top level of the dialogue state is monitor initialisation. Before the APM can be initialised (or re-initialised) as a diagnostic monitor the user must specify some details concerning the reception of packets from the ether. The user is first asked to specify the maximum number of bytes in a packet that are to be recorded. The packet header is always recorded but the user may select how much of the rest of the packet (the data and trailer) is also required. The user must supply a value in the range 14 (packet header only) to 548 (maximum sized packet less its checksum field). The user is then asked which receive mode the monitor station is to operate in. Each mode uses different criteria for selecting which packets received by the station are to be recorded. The basis of selection is the contents of the packets' address fields. The user may specify that all packets received should be recorded or that only packets being transmitted and/or received by specified hosts should be recorded. If the latter is the case then the host's station address will be asked for and if the user is only interested in traffic using a particular port in the host then the port number will also be requested. Details of the address selection modes are given below. Mode 00 N select All packets selected Mode 10 S select: user specifies 1 station address Packet selected if dest. station field=specified station address or srce. station field= ----------"------------- Mode 11 SP select: user specifies 1 station-port pair Packet selected if dest. station-port field=specified station-port or srce. station-port field= ---------"----------- Mode 20 S-S select: user specifies 2 station addresses Packet selected if dest. station field=one of the specified station addresses and srce. station field=other station address Mode 21 S-SP select: user specifies 1 station address and 1 station-port pair Packet selected if dest. station field=specified station address and srce. station-port field=specified station-port or if dest. station-port field= ---------"--------- and srce. station field=specified station address Mode 22 SP-SP select: user specifies 2 station-port pairs Packet selected if dest. station-port field=one of the specified station-ports and srce. station-port field=other specified station-port After all these questions have been answered the monitor is initialised. The parameters supplied by the user in this section cannot be changed during the following session. To change any of the parameters requires the monitor to be reinitialised causing all previously recorded data to be lost. I.4 Specifying_The_Operating_Mode After the monitor has been initialised or when the monitor returns to the dialogue state from the operational state the user is asked to select the next operation mode. There are four operating modes to choose from: recording mode, playback mode, reinitialise mode, exit mode. Recording Mode -------------- In this mode a trace of any current activity of interest on the ether is recorded in the monitor's main buffer. On selecting this mode the monitor first asks the user when the recording operation is to be stopped. The following options are available. - 'Stp Rec Mode 1': recording stopped when the user hits any key. - 'Stp Rec Mode 2': recording stopped after a specified number of packets have been received or when the user hits any key. The user is then asked whether or not the 'display' option is required. If the 'display'option is selected then recorded data is presented on the VDU during the recording operation. The user must select one of the three levels of data interpretation that are provided by the monitor. When the recording operation has been fully specified the user is instructed to hit the key to start the recording operation. When this happens the monitor enters the operational state in the recording mode (see section INTERP). Playback Mode ------------- In this mode previously recorded data from the current session can be reviewed if it has not been overwritten by more recent data. If this mode is selected before any data has been recorded in the current session the user is asked to reselect the operation mode. If there is data recorded the user is first asked to select where abouts in the monitor's main buffer the playback operation is to start. The following options are available. - 'Strt Pb Mode 1': playback starts from where the last playback operation in the current session was stopped. - 'Strt Pb Mode 2': playback starts from a location specified by the user. - 'Strt Pb Mode 3': playback starts from the beginning of the most recently recorded trace. The user is then asked when the playback operation is to be stopped. The following options are available. - 'Stp Pb Mode 1': playback is stopped when the user hits any key. - 'Stp Pb Mode 2': playback is stopped after a specified number of packets have been reviewed. - 'Stp Pb Mode 3': playback is stopped after a specified location has been reviewed. - 'Stp Pb Mode 4': playback is stopped when the end of the most recently recorded trace has been reached. Finally the user must select one of the three levels of data interpretation that are provided by the monitor (see section INTERP) When the playback operation has been fully specified the user is instructed to hit the key to start the playback operation. When this happens the monitor enters the operational state in the playback mode. Reinitialisation Mode --------------------- This mode returns the monitor to the monitor initialisation level of the dialogue state. No further specification is required. All data recorded to date is lost because the buffer gets reinitialised. Exit_Mode --------- This mode is selected when use of the monitor is no longer required. No more specification is required. The APM is reset for normal use and the Software Monitor Program is exited. I.5 The_Monitor_In_The_Operational_State In the operational state the monitor is either in recording mode or playback mode. In recording mode blocks of data received from the ether station are stored in the main buffer. A block usually contains a packet captured from the ether with some data concerning the status of the packet and the recording operation. Sometimes a block just contains status information and is then called an empty block. The buffer is circular and segmented. Each segment is numbered and may hold one block. Fig. SEG shows the arrangement of a block in a segment and Fig. PACH shows the format of the packet header used. Figure I-1: Figure I-1: Figure I-1: Buffer Segment Containing A Block Figure I-2: Figure I-2: Figure I-2: Format Of The EUCSD 2 Mbps Ethernet Packet Header In the playback mode, and in the recording mode if the display option has been selected, blocks in the buffer are reviewed. Data is read from the buffer,interpreted and then presented to the user. The monitor uses a two window arrangement on the VDU in the operational state. The top window presents information about the progress of the current operation. The bottom window presents interpreted data from the buffer and messages; it operates in a scolling manner. When the current operation is stopped the user is instructed to hit to re-enter the dialogue state at the operation mode selection level. Data Interpretation ------------------- When recorded data (in block units) is reviewed it appears in one of three formats. Each format presents a block interpreted to a different level. The user selects which interpretation level is to be used before the operational mode is entered. The three available levels of interpretation are: Level_0 All bytes in a block are represented in hexadecimal form. The block's segment number field and block header fields appear on the first line; fields are separated by spaces. The packet header appears on the second line; its fields are separated by spaces. The specified amount of the packet's data and length fields appears on the remaining lines; each byte is separated by a space. Level_1 This is similar to Level 0 except that the first line (segment number and block header) is interpreted instead of being presented as a byte stream. The segment number is displayed and the following significant events recorded in the block header are flagged. - ** T=xx ** The block contains timing information. The value xx is the cumulative value of the time fields of the blocks reviewed so far in the current operation. The difference between two values of T gives the time (in 0.1 sec units) that elapsed between the creation of the two blocks when the trace was recorded. - ** D(t) ** Data discontinuity. This block seperates the beginning of one trace from the end of another. - ** D(f) ** Data discontinuity. Data has been lost in the ether station receiver FIFO. - ** D(b) ** Data discontinuity. Data has been lost in the ether station buffer. - * CRCE * This packet contains a CRC errorr. - * COLL * This packet was involved in a collision. - * LONG * This packet is longer than the maximum packet size. - * RECE * This packet has been corrupted by the ether station receiver. The error is detected by the presence of an invalid address field in conjunction with a clear CRC flag. Level_2 This is similar to Level 1 except that the second line (the packet header) is interpreted instead of being presented as a byte stream. The packet header is presented in the following format. Srce Stat No:Srce Port No -> Dest Stat No:Dest Port No Type(Seq No) If any of the redundent bytes in an address field are not zero then these bytes are presented after the port number. The type field is presented as 'data' if its value is 1 and as 'ack' if its value is 81(H). If the type field has any other value it is invalid and its value is presented in hexadecimal. Fig. INT1 and Fig. INT2 show examples of the three formats available for presenting recorded date. Recording Mode -------------- In the recording mode the top window on the VDU appears as in Fig. RECWIN. The information provided consists of: - current number of packets recorded, - length of time the operation has been running, - count of the number of times each status bit has been set in a recorded block. If any set 'fifo o/f' bits are reported the monitor should be reinitialised with a more selective packet selection mode. This would allow the ether receiver to be re-enabled more quickly after irrelevent packets are received. If any set 'buff o/f' bits are reported the monitor should be reinitialised with a smaller maximum data requirement specified. This would increase the number of blocks that could be accommodated in the ether station buffer giving the ether station more time to process and transfer a block to the APM. If the display option has been selected the bottom window presents received blocks as soon as possible after they have been recorded. If data that has not yet been displayed is overwritten Figure I-3: Figure I-3: Figure I-3: Example 1 Of Data Interpretation Formats Figure I-4: Figure I-4: Figure I-4: Example 2 Of Data Interpretation Formats Figure I-5: Figure I-5: Figure I-5: Top Window Format In Recording Mode by more recent data received from the ether station then the display process is stopped but recording continues. The length of time that the display process will run for depends on the rate at which data is being recorded and on the level of data interpretation selected. Display will run longest with Level 0 selected and shortest with Level 2 selected. Playback Mode In the playback mode the top window on the VDU appears as in Fig. PBWIN. Figure I-6: Figure I-6: Figure I-6: Top Window Format In Playback Mode The information provided consists of: - segment number of first block reviewed (in hex), - number of blocks currently reviewed (in hex) - count of the number of times certain events have been recorded in the reviewed block headers. The bottom window of the VDU presents the reviewed blocks.