OASIS-CC VERSION V02.05.05 RELEASE NOTES 10/12/92 These release notes describe version V02.05.05 of OASIS-CC. A copy of these notes can be found in $ODIST/release_notes/oasis_v2.0505. This release only concerns the SunOS version of OASIS-CC. OASIS-CC v02.05.05 implements a first level of support for IEEE 488 (GPIB) and for 1553 EOS am1 platform low rate science bus. 1 Compatibility Information This release of OASIS-CC has been tested under the following conditions: Sparcstation IPC and 2 SunOS 4.1.1 and 4.1.3 X MIT X11R4 with fixes 1 to 18 MOTIF 1.1 TAE+ 5.1 The Ada distributions require Sun Ada 1.1 The IEEE 488 code requires a National Instruments (NI) GPIB interface board and its associated driver. The board used during the development and test of the software is GPIB-SPARC1-B (SB-GPIB interface board). The IEEE 488 software was tested on a Sparcstation IPC running SunOS 4.1.1 The 1553 low rate science code requires an Engineering Design Team (EDT) 1553 interface board and its associated driver. The board used during the development and test of the software is the S53B1 (Sbus to Mil-std 1553b interface). The 1553 low rate science software was tested on a Sparcstation 2 running SunOS 4.1.3. The tests have been conducted using an in-house developed software-simulated instrument. It is therefore recommended that further testing be accomplished. Several problems have been encountered while testing, such as numerous board-level timeouts or OASIS-CC often going into an I/O infinite wait state after several minutes of testing. We are still investigating the problem with EDT. Our understanding is that EDT is suspecting an interface board embedded code problem. Note that this release of OASIS-CC is not compatible with SOLARIS 2.0 (aka SunOS 5.0) and X11R5. 2 Installation Procedure Refer to the OASIS-CC Unix Version Installation Guide (there is an updated version of this document available). 3 Setup Changes For V02.05.04 Applications There are changes in the OASIS-CC V02.05.05 code that makes this release incompatible with applications running version V02.05.04. The changes are: (1) The bus_decompositions table has been suppressed; (2) The ieee_device_descriptions table has been redesigned; (3) The parser table has been modified to support the enhanced CSTOL make directive; (4) Because OASIS-CC is compiled with a new version of the SunAda compiler, the file formats of all the database tables (.dat files) have changed; and (5) The way the offset field in the decomposition table is interpreted has changed for atoms that are not on byte boundary. The distribution tape contains a command procedure (v020504to05) that will make a v02.05.04 application compatible with this release. In particular, this command procedure tries to update the offset field in the decomposition table by reading and updating the $OASIS_DATABASE/decomposition.dat file. Any application that defines or updates the decomposition table at runtime via CSTOL procedures needs to modify the procedures manually. There are cases where the V020504to05 command procedure is unable to modify the offset field in some records of a decomposition table (this will happen when an atom spans a byte boundary and at the same time does not begin and end on a byte boundary). The error log of the command procedure can be found in $OASIS_DATABASE/offset.change and should be carefully examined after the procedure is executed. The previous decomposition table contents are kept in a load format in $OASIS_DATABASE/decomposition.v020504. The conversion is done by executing the following steps: (1) log in the application account (2) set up all the environment variables (3) execute the command procedure by typing: $ODIST/bin/v020504to05.csh 4 New Features Or Code Fixes The following new features and major code fixes are included in this release. New features and code fixes have associated Change Request Numbers (CRNs) that provide a means of tracking changes to the OASIS-CC code. CRNs are generated by LASP and the general OASIS-CC user community. The pertinent CRNs are shown for each enhancement or correction included in this new version of OASIS-CC. 4.1 New interpretation of the offset field of the decomposition table (CRN 239) The previous release numbered the bits in a DEC/Ada fashion, wherein a byte's least significant bit (lsb) is 1 and most significant bit (msb) is 8. This convention made the expression of the offset field difficult and confusing as many people are used to the reverse convention. This also made the interpretation of the offset value difficult in the OASIS-CC SunOS code. In particular, the code was unable to extract atoms that were not starting and ending on byte boundaries and spanned over several bytes. With this release, for the decomposition table, the offset field interpretation assumes that in an N-bit data field, the first bit transmitted is bit 1 and is the most significant bit. +---------------------------------------+ | N-bit data field | +---------------------------------------+ ^ ^ | | Bit 1 Bit n First bit transmitted Examples: To extract the 2-bit atom marked X in the figure below, in the previous release the offset would have had to be 6. With this release the offset must be 2. +----+----+----+----+----+----+----+----+ | | X | X | | | | | | +----+----+----+----+----+----+----+----+ ^ ^ | | Bit 1 Bit 8 Extracting the 11-bit atom marked by X in the figure below was impossible in the previous release (where the offset of the first bit would have had to be 1). With this release this is possible with an offset of 5. +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ | | | | | X | X | X | X | X | X | X | X | X | X | X | X | +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ ^ ^ ^ | | | Bit 1 Bit 8 Bit 16 4.2 Updated Code For The Generic Communication Protocols ASYN_CHAR and IP (CRN 239) The ASYNC_CHAR and IP protocols can now handle packets where the packet id and the packet size are not on byte boundaries. With this release, if the dn_low field of the latest_data table entry external_element = and item_name = IS_PACKETIZED is equal to 2, then the contents of dn_low fields for the latest_data table entries external_element = and item_name = ID_OFFSET, ID_SIZE, LENGTH_OFFSET and LENGTH_SIZE is interpreted as bit value rather than byte value. As in the previous release, if the dn_low field of the IS_PACKETIZED entry contains 1, the contents dn_low fields of the ID_OFFSET, ID_SIZE, LENGTH_OFFSET and LENGTH_SIZE entries is interpreted as byte value. A new latest_data table entry can be used to debug the processing and the interpretation of the packet id and of the packet size. If the dn_low field of the latest_data table record external_element = , item_name = DEBUG_LEVEL contains 1, then debug messages are output in the event message log every time a new packet is recognized. If the dn_low field contains 0 or if the latest_data table record is not present, no debug messages are output. The previous release code is still accessible by using the protocols TEST_1 (instead of IP) or TEST_2 (instead of ASYNC_CHAR). The stack space for the IP and the ASYNC_CHAR protocol (and for the TEST_1 and the TEST_2 protocols) has been doubled to support the processing of large telemetry frame or packet (1200 16-bit word long packets or telemetry frames is the current limitation). 4.3 Query window control (CRN 228) In V02.05.04, the query window was basically unreadable, because of poor choice of background and foreground colors. With this release, OASIS-CC uses the ASK_WINDOW definition in the display_descriptions table for the query window. 4.4 Problem Inserting Records In Commands Database Table (CRN 230) As noted in the release notes of the V02.05.04, inserting record in the commands table from the CSTOL prompt or from a CSTOL procedure used to require the explicit specification of all the record fields. Default field values are now correctly inserted. 4.5 IEEE 488 Support (CRN 231) See appendix A for a short description and a user's guide. 4.6 1553 Low Rate Science Support (CRN 236) See appendix B for a short description and a user's guide. 5 Change Requests Or Test Reports Closed With This Release Change Requests Number: 207 (partial), 225 (partial), 227, 228, 230, 231, 234, 236, 237, 238 and 239. 6 Principal Known Problems And Limitations 6.1 Process Size Increases While Solving Equations (CRN 229) There is a memory trashing problem when equations are solved via the equations clp. This problem eventually leads to OASIS-CC running of virtual memory. 6.2 OASIS-CC Terminates With X Error (CRN 235) This problem has been noted while doing long formal tests of OASIS-CC, with data being displayed at high rate. After several hours of testing OASIS-CC terminates with a X error. 6.3 Filename Length Limitation In OASIS-CC filenames can be up to 60 characters long. In the SunOS version, the length of the pathname (not the length of the environment variable that translates into the pathname) is included in the filename length. Therefore, the 60 characters limit can be easily reached. A way around this limitation is to use an alias for the pathname. 7 Anomaly Or Enhancement Request Reporting The mechanism previously used with the VMS version since 1988 to report OASIS-CC anomalies or to suggest enhancements to the OASIS-CC functionality has been extended to the SunOS version. The report generated using this mechanism can be sent to the OASIS project office by electronic mail (the preferred way) or by regular mail. Each report is assigned a Change Request Number (CRN) and is acknowledged to the originator. The CRN can be used to track progress on the report. To report an anomaly enter: $ODIST/bin/report.csh 8 New Documentation Set Three documents have been updated and re-released:(1) The OASIS-CC Database Guide; (2) The CSTOL Reference Manual; and (3) The Unix Installation Guide. APPENDIX A This appendix provides a short user's guide for the current IEEE-488 implementation. 1 - General Notes This implementation allows a user to (1) Execute IEEE-488 control commands; (2) Send device specific commands to IEEE-488 listener devices; and (3) Poll IEEE-488 talker devices at a user-defined frequency. A subsequent implementation will provide support for serial polling and service request modes. The implementation uses a National Instruments IEEE-488 interface and its associated SunOS driver. This OASIS-CC implementation for IEEE-488 differs in many ways from the one used in the VMS version of OASIS-CC (and described in the current version of the System Manager's Guide). The bus_decompositions table has been removed. Decomposition of the IEEE-488 data are now defined by decomposition table. The ieee_device_descriptions table has been redesigned. The CSTOL make statement has also been redesigned. The basic application set up matches more closely a regular application set up: the bus to which the IEEE-488 devices are attached is mapped to an OASIS-CC primary stream and each devices output is mapped to a secondary stream that can be decomposed and/or routed using the information contained in the decomposition table. The implementation has been tested with several IEEE-488 devices, including a Keithly Model 195a Digital Multimeter, a Keithly Model 775a Programmable Counter/Timer and a Klinger CC-1 Programmable Stepper Motor Controller. There is one instance in the code where it is assumed that the board index of the interface is 0 (i.e, the interface is /dev/gpib0). 2 - Database Set Up The following paragraphs give an overview of the specific database set up for the IEEE-488 implementation. 2 - 1 Streams Table 2 - 1 - 1 Primary Stream : one record per IEEE-4888 bus The primary stream provides the mechanism by which a IEEE-488 process can be started. This is controlled by the user via the CSTOL switch on/off or retrieve on/off directives. The primary stream can recorded via the record on/off CSTOL directives. STREAM_NAME => name of the stream DESCRIPTION => PROCESSOR => BUS_SUBSYSTEM LINK_NAME => pointer to the links record DIRECTION => not used PROTOCOL => IEEE STREAM_TYPE => PRIMARY PARENT => not used STREAM_IS_ON => system used TIME_OUT => not used ARECORD_IS_ON => system used RECORD_FILE_NAME => system used ASSOCIATED_FORWARD_NAME => not used RETRIEVE_IS_ON => system used FRAME_LENGTH => maximum size of the output of all the talker devices SECONDARY_OFFSET => not used ID_VALUE => not used INCREMENTAL => not used SYNC_PATTERN_LENGTH => not used SYNC_PATTERN => not used EXTERNAL_ELEMENT => currently not used FRAME_COUNT_NAME => currently not used SYNC_ERR_COUNT_NAME => currently not used 2 - 1 - 2 Secondary Stream : One record per talker device on an IEEE-488 bus Each device output stream is mapped to a secondary stream. So one record is needed per device that will be read and whose output needs to be decomposed or routed. The decomposition of each secondary stream is defined by the decomposition table and is controlled by the user via the switch on/off CSTOL directives. Routing is controlled by the route/stop routing CSTOL directives. STREAM_NAME => name that will be used to identify this IEEE-488 device DESCRIPTION => PROCESSOR => BUS_SUBSYSTEM LINK_NAME => not used DIRECTION => not used PROTOCOL => IEEE STREAM_TYPE => SECONDARY PARENT => name of the primary streams STREAM_IS_ON => system used TIME_OUT => not used RECORD_IS_ON => not used RECORD_FILE_NAME => not used ASSOCIATED_FORWARD_NAME => not used RETRIEVE_IS_ON => not used FRAME_LENGTH => greater than the length of the data stream output by the device SECONDARY_OFFSET => as needed ID_VALUE => not used INCREMENTAL => not used SYNC_PATTERN_LENGTH => not used SYNC_PATTERN => not used EXTERNAL_ELEMENT => not used FRAME_COUNT_NAME => not used SYNC_ERR_COUNT_NAME => not used 2 - 2 Links Table : one record per primary IEEE-488 stream LINK_NAME => as defined in the primary stream table DATA_LINE => Should contain the driver name. Example: /dev/gpib0 EXTERNAL_ELEMENT => not used BLOCK_COUNT_NAME => not used CRC_ERROR_COUNT_NAME => not used TEST_COUNT_NAME => not used RETRY_COUNT_NAME => not used 2 - 3 Element Characteristics Table One record is needed per IEEE-488 device attached to an IEEE-488 bus. NAME => name that will be used to identify this IEEE-488 device DESCRIPTION => LATENCY => not used BANDWIDTH => not used COMMAND_CODING => as needed by the device command set up STREAM_NAME => name of the primary stream All the other fields are "as needed by the device command set up". 2 - 4 IEEE Device Descriptions Table One record is needed per IEEE-488 device attached to the bus. EXTERNAL_ELEMENT => name that will be used to identify this IEEE-488 device PRIMARY_ADDRESS => primary address of the device SECONDARY_ADDRESS => secondary address of the device WRITE_TERMINATION_MODE => as defined for the device READ_TERMINATION_MODE => as defined for the device MATCHING_CHARACTER => as defined for the device TIME_OUT => maximum amount of time OASIS-CC should wait for the device to answer a sample request. Note: This table is used to override the contents of the device special files defined using the ibconf software supplied with the National Instrument gpib board and driver. 3 - Other Set Up The decomposition table is set up the regular way. The command-related tables are set up the regular way. 4 - CSTOL Directives 4 - 1 Polling Directive (see the CSTOL reference manual) SAMPLE device_list EVERY sample rate SAMPLE device_list STOP SAMPLING device_list STOP SAMPLING ON stream_list 4 - 2 Bus Control (see the CSTOL reference manual) To have devices go to remote mode: MAKE DEVICE device_list BE REMOTE MAKE ALL DEVICES ON stream_list BE REMOTE To have devices go to local mode: MAKE DEVICE device_list BE LOCAL To place devices in local lockout state: MAKE DEVICE device_list BE LOCAL_LOCK MAKE ALL DEVICES ON stream_list be LOCAL_LOCK To trigger devices: MAKE DEVICE device_list DO TRIGGER To reset devices: MAKE DEVICE device_list BE RESET MAKE ALL DEVICES ON stream_list BE RESET To initialize a bus: INITIALIZE stream_name APPENDIX B This appendix provides a short user's guide for the 1553 low rate science implementation. 1 - General Notes This first implementation is based on the requirements defined in the EOS General Instrument Interface Specification (GIIS) dated April 15, 1992. It supports the mode codes valid for the low rate science bus (i.e. transmit status word, synchronize, initiate self-test, transmitter shutdown, override transmitter shutdown, reset remote terminal, transmit vector word, transmit last command and transmit BIT word). It supports data transfers using the transmit vector word protocol defined in the GIIS. The implementation provides for the decomposition of the primary stream and for the decomposition and the routing of multiple secondary streams as defined in the streams table. By default, the secondary streams are identified on the basis of the CCSDS application process ID field of the CCSDS data source packets. However this default can be override by the user (see below). The user can select the interval between two successive sequences of poll of the remote terminal (aka, the instrument). For example the CSTOL statement SAMPLE MISER EVERY 00:00:01.5 instructs OASIS-CC to poll the miser instrument every 1.5 second. Once OASIS-CC starts polling the instrument, it sends a "transmit vector word" mode code every 0.025 seconds until either the instrument sets the service request bit in its status word or a user-defined time out has expired. If the service request bit is set, OASIS-CC initiates the data transfer. For the most part, this is a board level transfer. The next sequence of instrument poll then starts 1.5 second after the beginning of the previous one. Tests of the implementation have been conducted by using a software-simulated instrument running on one workstation and OASIS-CC running on another workstation. As the software-simulated instrument was coded using the same interpretation of the GIIS as the one used in coding OASIS-CC, it is recommended that further testing be accomplished. The implementation is based on the use of an Engineering Design Team (EDT) interface board and its associated SunOS driver. Note that (1) CCSDS segmented source packets are not currently supported and (2) The transfer of packets whose length is greater than 8192 bits is supported, but has not been tested. 2 - Database Set up The following paragraphs give an overview of the specific database set up for the 1553 low science protocol. 2 - 1 Streams table 2 - 1 - 1 Primary Stream The primary stream provides the mechanism by which the 1553 process can be started. This is controlled by the user via the CSTOL switch on/off or retrieve on/off directives. The primary stream can be recorded using the record on/off CSTOL directives. STREAM_NAME => name of the stream DESCRIPTION => PROCESSOR => BUS_SUBSYSTEM LINK_NAME => pointer to the links record DIRECTION => not used PROTOCOL => FIFTEEN_53_LRS STREAM_TYPE => PRIMARY PARENT => not used STREAM_IS_ON => system used TIME_OUT => time out value to be used to exit a pool sequence RECORD_IS_ON => system used RECORD_FILE_NAME => system used ASSOCIATED_FORWARD_NAME => not used RETRIEVE_IS_ON => system used FRAME_LENGTH => maximum size of the packets to be received SECONDARY_OFFSET => not used ID_VALUE => not used INCREMENTAL => not used SYNC_PATTERN_LENGTH => not used SYNC_PATTERN => not used EXTERNAL_ELEMENT => currently not used FRAME_COUNT_NAME => currently not used SYNC_ERR_COUNT_NAME => currently not used 2 - 1 - 2 Secondary Streams Secondary stream can be defined, so decomposition and routing can be controlled by the user via the CSTOL switch on/off and route/ stop routing directives. The implementation assumes that the telemetry stream is packetized. STREAM_NAME => name of the secondary stream DESCRIPTION => PROCESSOR => BUS_SUBSYSTEM LINK_NAME => not used DIRECTION => not used PROTOCOL => FIFTEEN_53_LRS STREAM_TYPE => SECONDARY PARENT => name of the primary streams STREAM_IS_ON => system used TIME_OUT => not used RECORD_IS_ON => not used RECORD_FILE_NAME => not used ASSOCIATED_FORWARD_NAME => not used RETRIEVE_IS_ON => not used FRAME_LENGTH => not used SECONDARY_OFFSET => as needed ID_VALUE => as needed to identify the packet associated with this secondary stream INCREMENTAL => not used SYNC_PATTERN_LENGTH => not used SYNC_PATTERN => not used EXTERNAL_ELEMENT => not used FRAME_COUNT_NAME => not used SYNC_ERR_COUNT_NAME => not used 2 - 2 Links Table LINK_NAME => as defined in the primary stream table DATA_LINE => should contain the driver name and the rt address separated by a blank. Example: /dev/s53bi0 10 EXTERNAL_ELEMENT => not used BLOCK_COUNT_NAME => not used CRC_ERROR_COUNT_NAME => not used TEST_COUNT_NAME => not used RETRY_COUNT_NAME => not used 2 - 3 Element Characteristics table One record is needed to name the instrument and to associate it with the primary stream. NAME => name given to the instrument in sample and the make cstol directive DESCRIPTION => LATENCY => not used BANDWIDTH => not used COMMAND_CODING => not used STREAM_NAME => name of the primary stream All other fields are not used. 3 - Other Set up As indicated above, by default each packet is identified via its CCSDS packet id. This default mechanism can be overriden by defining two records in the latest_data table. For each record the external_element is the primary stream name. The first record (item_name = ID_OFFSET) defines in the dn_low field the offset (in bits) of the new packet identification field. The second record (item_name = ID_SIZE) defines in the dn_low field the size (in bits) of the new packet identification field. Some level of debugging can be done by defining a latest_data table record (external_element = primary stream name and item_name= DEBUG_LEVEL). When dn_low = 0 or if the record is not present, no debugging messages are output in the event messages log. Dn_low = 1 or 2 provides two different, increasing levels of debugging messages in the event messages log. 4 - CSTOL Directives 4 - 1 Polling Directive (see the CSTOL reference manual) SAMPLE instrument name EVERY sample-rate STOP SAMPLING instrument name STOP SAMPLING ON stream name 4 - 2 Mode Code (see the CSTOL reference manual) Transmit status word => MAKE INSTRUMENT instrument_name DO TRANSMIT_STATUS Synchronize => MAKE INSTRUMENT instrument_name DO SYNCHRONIZE Initiate self-test => MAKE INSTRUMENT instrument_name DO SELF_TEST Transmitter shutdown => MAKE INSTRUMENT instrument_name DO SHUTDOWN_XMITTER Override transmitter shutdown => MAKE INSTRUMENT instrument_name DO OVERRDE_SHUTDOWN Reset remote terminal => MAKE INSTRUMENT instrument_name DO RESET Transmit last command => MAKE INSTRUMENT instrument_name DO XMIT_LAST_CMD Transmit BIT word => MAKE INSTRUMENT instrument_name DO XMIT_BITE_WORD