OASIS-CC VERSION V02.05.08 RELEASE NOTES 6/1/93 These release notes describe version V02.05.08 of OASIS-CC. A copy of these notes can be found in $ODIST/release_notes/oasis_v2.0508. A copy of the notes from previous releases can also be found in the $ODIST/release_notes directory. This release only applies to the SunOS version of OASIS-CC. OASIS-CC V02.05.08 allows the control of the display rate of individual measurement. It provides the user with the capability of displaying, in the cstol_procedure window, source code lines that follow the line being executed. It also allows the routing of cstol statements generated by remote nodes to any sub_clps. 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.4 TAE+ 5.2 Note that: (1) the Ada distributions require SunAda 1.1; (2) All the distributions require the MOTIF developer's kit; (3) OASIS-CC cannot be linked with shareable libraries. For example, OASIS-CC needs the libXm.a motif library. It cannot be linked with the libXm.so motif library; (4) This release of OASIS-CC is not compatible with SOLARIS 2.0 (aka SunOS 5.0), X11R5 or TAE+ 5.1.; (5) The prototype S11W implementation includes a SunOs patch which is included in the release (in $ODIST/common_distrib/objects/aiolib.a. See appendix D); and (6) The prototype S11W implementation uses an EDT S11W (SBus to DR11W parallel interface) board. 2 OASIS-CC Installation Procedure ---------------------------------- Refer to the Unix OASIS-CC V02.05.08 Installation Guide for instructions on how to install the OASIS-CC software from the tar tape. Sites that require the ability to maintain applications running under previous release must install V02.05.08 in a new directory. 3 Upgrading V02.05.07 Applications to V02.05.08 ------------------------------------------------ There are changes in the OASIS-CC V02.05.08 code that makes this release incompatible with applications running version V02.05.07. The changes are: (1) The display_descriptions and display_definitions tables format has been modified (See Appendix A for a description of the new layout of the tables). Sites that require the ability to maintain version V02.05.07 or earlier release applications will need new accounts for their associated V02.05.08 applications. The paragraph "Creating OASIS-CC Accounts" in the Unix OASIS-CC V02.05.08 Installation Guide provides details on the requirements for application accounts. The OASIS-CC Application Environment Reference Manual describes how to create the appropriate application environment. The minimum set of files that users need to transfer from existing applications to the areas for developing applications with the new release are: OASIS Database files OASIS Procedure files OASIS Macro files TAE+ resource and graphics files The distribution tape contains a command procedure (v020507to08) that will make a v02.05.07 application compatible with V02.05.08. To upgrade to V02.05.08, perform the following. (1) Log in the application account intended for V02.05.08 development. This account should be populated with V02.05.07 files (the minimum set is listed above). (2) Set up all the environment variables. Make sure that ODIST points to the OASIS-CC V02.05.08 distribution and that TAE points to the TAE+ 5.2 distribution. (3) Execute the OASIS-CC upgrade by typing: $ODIST/bin/v020507to08.csh (5) Re-create your application. To update from a version prior to V02.05.07, you must first upgrade to V02.05.07. Refer to the release notes in $ODIST/release_notes. 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 Display Of The Next Lines In A Cstol Procedure (CRN 280/OSCAR 1) In previous OASIS-CC releases, the last line displayed in the CSTOL_PROCEDURE window was the line being executed. With this release, the user can also display lines sequentially following the line being executed. In that case, the line being executed is highlighted. This is controlled by a new field (NUMBER_OF_NEXT_LINE) in the display_descriptions table (see Appendix A). When the value of this field is 0, then OASIS-CC acts as in the v02.05.07 release. Note that it is necessary that the Y_DIMENSION of the window be greater or equal to the NUMBER_OF_NEXT_LINE + 3. OASIS-CC enforces this rule when the window is displayed by computing, if necessary, its own NUMBER_OF_NEXT_LINE field value. However, if the user changes the Y_DIMENSION of the window using the mouse, and shrinks the Y_DIMENSION to a value lower than NUMBER_OF_NEXT_LINE + 3, the result is unpredictable. Also note that using this new capability considerably slows down the execution of a procedure. 4.2 Display Rate Independent Of The Telemetry Rate (CRN 275/OSCAR 3) In previous releases, OASIS-CC would try to display items as fast as they were received, discarding values when no time was available to display. In V02.05.06, an algorithm was introduced to limit the cpu usage of the display subsystem. With this release, the user can control the maximum time between two updates of the same tae item. If this time is set to 0.0, then OASIS-CC behaves like the V02.05.07 release. This new feature has introduced changes in the display_definitions table layout, with two new fields added (UPDATE_RATE and GROUP_NAME. see Appendix A). Note that when the UPDATE_RATE field for a tae item is updated, it is taken into account as soon as any panel with this tae item is displayed. If the item is displayed on several panels, all will reflect the new update rate. Note that purpose of the new GROUP_NAME field is to allow the user to logically group tae items. This can be used to do "one shot" updates of the UPDATE_RATE of logically grouped tae items. 4.3 Display Of The Procedure Line Executed By A Sub Clp (CRN 280/OSCAR 42) Sub clps can now display procedure lines in their own "FOR_CLP_PROCEDURE" window. To avoid confusion when many clps display the same window (for example the same "FOR_CLP_PROCEDURE" window), the title in the window banner of a "FOR_CLP_PROCEDURE" window or of a "FOR_CLP_MESSAGE" window or for a "FOR_COMMAND" window now reads: U xx (where xx is the sub clp number) followed by up to 14 characters from the page_name field of the display_descriptions record that defines the window. Also, OASIS-CC does not predefine a "FOR_CLP_PROCEDURE" window named CSTOL_PROC anymore. 4.5 Ingesting data in OASIS-CC via a user created file (CRN 288/OSCAR 11) It is now possible to have OASIS-CC read, synchronize, decompose and route data from a user provided file. See Appendix F for a short user's guide for this new capability. 4.6 CSTOL Statements Can Be Routed To Any Sub Clp (CRN 281/OSCAR 43) Secondary streams can now be routed at any of the 20 sub clps (See Appendix B for the updated cstol ROUTE statement). To protect an application from having a remote user send commands to an external element for which he/she does not have command privilege, privileges can be assigned to any of the 20 sub clps. At startup time OASIS-CC looks for records in the user_privileges table with USER_CLASS equals to CLP_xx, where xx = 1 to 20 (i.e., CLP_1 to CLP_20) and uses them to set each sub clps privileges. If a record of a sub clp is not present, then the following default privilege record is used: EXTERNAL_ELEMENT all blank COMMAND_PRIVILEGE FALSEOB EXTCOMM_PRIVILEGE FALSE PROC_PRIVILEGE TRUE 4.7 Bridge Improvements (CRN 279/OSCAR 40) The bridge subsystem has been overhauled and now provides the following additional functionalities: (1) There is no limit the size of a bridge. The size of a bridge is computed when the bridge is recorded or switched on. (2) A bridge can be either binary or ascii. The determination is done when the bridge is recorded or switched on. If the formats of the items in a bridge are all of the type TB[w], then the bridge is said to be binary. If none of the formats of the items in a bridge are of the type TB[w], then the bridge is said to be ascii. TB[w], where TB stands for True Binary, is a format descriptor that is used only in a bridge description to indicate that the data is to be written in a binary format. Binary formats and non-binary formats cannot be mixed. (3) A binary bridge can be recorded and/or transmitted. An ascii bridge can be recorded and/or transmitted. Previously, a recorded bridge was always ascii and transmitted bridge was always binary. (4) In the format TB[w], w is rounded to the next multiple of 8 bit when the data is of the type dn_data. If the data is of the type eu_data, trend_data or smooth data, w is ignored and 32 bits are used to hold the data. If the data is of the type data_time, 12 bytes are used (4 for year, 4 for day of year and 4 for milliseconds of day. All are expressed as integer). (5) In a binary bridge the overall quality field uses 1 byte and the quality bits associated with each data also use 1 byte. Please refer to the System Manager's Guide for a detailed description of the bridge capability. 4.8 Prototype Implementation For S11W Communications (CRN 253/OSCAR 24) This release contains a prototype implementation for high rate data transfer using a DR11-compatible 16-bit parallel interface from EDT. Appendix F contains the user's guide for this implementation. Appendix G lists the performances obtained with this implementation. 4.9 OASIS-CC Terminates With X Error (CRN 235) This problem was been noted while doing very long formal tests of OASIS-CC V02.05.05, with data being displayed at high rate. After several hours of testing OASIS-CC terminates with a X error. The problem has been traced to a Motif 1.1.4 problem which occurs when the attribute "static label" is used for displaying data. In v02.05.06 we have introduced the capability of using "dynamic text" instead of "static label" (or "text label"). This has several advantages: (a) the problem mentioned above does not exist; (b) updates look a lot smoother (no blinking); (c) the X server requires a lot less cpu cycles to update. WE RECOMMEND THAT YOU CHANGE ALL THE TAE ITEMS THAT REPRESENT DATA THAT IS UPDATED FROM STATIC LABEL (TEXT LABEL) TO DYNAMIC TEXT. The procedure to accomplish this update is: 1) From the AWB, check each existing TEXT LABEL used to display OASIS telemetry items. (True labels can remain as they are.) 2) Set the item to STRING if it is not already. 3) Change the item to TEXT/DYNAMIC TEXT from TEXT/LABEL. 4) Adjust justification etc., as desired. 5) Repeat as necessary for all items. 5 Change Requests Closed With This Release -------------------------------------------- Change Requests Number: 149, 235, 253, 268, 275, 276, 277, 279, 280, 281, 282, 284, 285, 287, 288, and 289. 6 Main Known Problems And Limitations --------------------------------------- 6.1 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 softlink the directories to directories with shorter names and define the environment variables relative to the new directories. 6.2 Limited thruput while using a generic communication protocol with a TDM frame (CRN 259) The current implementation of the generic communication protocol provides the user with some flexibility in controlling the load put on the host machine by the data acquisition if the data comes as packets. Ideally, it would be nice to choose the time_out and frame_length parameters (in the streams table record describing the primary stream) such as frame_length/time_out >> bit rate. If the stream is packetized the only requirement on the frame_length is that it has to be greater than the largest of the packets. The larger the frame_length, the greater the time_out value can be and therefore the lower the load on the machine. Currently in the case of a TDM frame, the frame_length has to be equal to the length of the frame, which limits the possible values for the time_out parameter. 6.3 Badly formatted internet address hangs OASIS-CC (CRN 258) Putting a badly formatted internet address (such as "/128.32.33.34" instead of "128.32.33.34") in the data_line field of the links table for stream that uses the IP protocol causes OASIS-CC to hang. 6.4 Clearing a panel with a selection list presentation type with a scrolling bar can cause OASIS-CC to crash (CRN 252) When clearing a panel with a selection list presentation type with a scrolling bar, seven error messages ("Warning: Cannot find callback list in XtRemoveAllCallbacks") are output in the startup window. Our analysis of the problem is that it may cause OASIS-CC to crash. A workaround is to hide the panel rather than clear it. 6.5 When an IP server stream is switched on, OASIS-CC keyboard or procedure input processing locks up until a client process connects if any CSTOL statements relating to that stream are executed (CRN 294) When a server stream is started using the IP protocol, it first waits for a client process to connect. It is only after a connection has been established with a client process that task handling the stream is able to execute processing directives, such as route or record. 6.6 OASIS-CC unable to retrieve data recorded using a pre-V02.05.05 version (CRN 278) The format of file recorded via the cstol record statement is currently compiler dependent. This makes OASIS-CC unable to retrieve data recorded using a pre-v02.05.05 version. We have developed a small utility that can be used to convert the recorded file into a format compatible with OASIS-CC version V02.05.05 and later. This utility is available by contacting LASP. 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 Documentation Set Status ---------------------------- The following list reflects the currency of the OASIS-CC Documents with the June 1, 1993 delivery of OASIS-CC v020508. (*) Indicates updated copy for V020508. New pagination will allow future documentation modifications to be delivered on a -by chapter- basis. *OASIS-CC System Manager's Guide, June 1993 Describes the approach required to tailor OASIS-CC to your application *OASIS-CC CSTOL Reference Manual, June 1993 Describes the OASIS-CC Colorado Systems Test and Operations Language *OASIS-CC Database Guide, June 1993 Describes the OASIS-CC Database table connections and record formats *OASIS-CC Application Environment Reference Manual, June 1993 Describes the directory, logical and compilation environment required to tailor and execute OASIS-CC *OASIS-CC Generic Communications User's Guide, June 1993 Describes the generic communication protocols delivered with OASIS-CC, and the database content they require *OASIS-CC Quick Reference Manual, June 1993 Provides a 'how to' approach, demonstrating examples of the database implementation behind common OASIS-CC features *AWB User's Guide, June 1993 Describes the functionality of the Actions Workbench Graph Presentation Type Supplement to the TAE+ User Interface Developers Guide, March 1993 Describes how to create a graph on the TAE+ interface Graph Presentation Type Supplement to the TAE+ Presentation Types Reference Manual, March 1993 Describes the TAE+ graph's resources Spectrometer Data Generator Reference Manual, March 1993 Describes the structure and content of data and commands sent and received by a software data generator used to demonstrate OASIS-CC 9 Upgrades To The Spectrometer Application --------------------------------------------- The spectrometer application has been enhanced: (a) All alpha-numeric displays are now Tae+ Text/Dynamic_text items. In previous releases, they were Text/Label (b) Bridges added (BINARY_BRIDGE and ASCII_BRIDGE) for recording only. (c) Generic implementation of IP OASIS-CC to OASIS-CC communications dialogue. Local OASIS-CC routes packets containing CSTOL statements (issued from remote OASIS-CC commands) to sub_clps for processing. (d) The Actions behind tae selections use the new "Cstolq" macro. This workbench macro is new with V020508. The Cstolq macro looks for single quotes imbedded in the macro string passed, and translates them to double quotes before passing the string to OASIS-CC. Refer to the new AWB User's Guide delivered with this release. Appendix A This Appendix describes the layout changes of the display_definitions, display_descriptions table. It also describes a change in the default value for the analog_conversions table. **************** DISPLAY_DEFINITIONS Two new fields (UPDATE_RATE and GROUP_NAME) have been added at the end of the table: UPDATE_RATE This field indicates the minimum time between two displays of the TAE_BASE/INDEX tae item NON KEY Protection class: DB_MANAGER Data type: DURATION Default value: 1.0 GROUP_NAME The field can be used to group together TAE_BASE/INDEX tae items, so that (for example) the UPDATE_RATE field can be updated in one query statement. NON KEY Protection class: DB_MANAGER Data type: NAME_TYPE Default value: **************** DISPLAY_DECRIPTIONS Several unused fields have been removed from the display_descriptions table (SCROLL_LL_XX_OFFSET, SCROLL_LL_YY_OFFSET, SCROLL_X_DIMENSION, SCROLL_Y_DIMENSION and UPDATE_INTERVAL) as they have become useless. A new field (NUMBER_OF_NEXT_LINE) has been added where the user can specify (for a window of the page_kind FOR_CLP_PROCEDURE) the number of line he/she wants to be displayed after the cstol procedure line being executed. The new layout is: PAGE_NAME as in v02.05.07 PAGE_KIND as in v02.05.07 WORKSTATION_TYPE as in v02.05.07 IS_INOUT as in v02.05.07 BACKGROUND_COLOR as in v02.05.07 TEXT_COLOR as in v02.05.07 BORDER as in v02.05.07 TITLE_FLAG currently unused TITLE currently unused LOWER_LEFT_CORNER_X as in v02.05.07 LOWER_LEFT_CORNER_Y as in v02.05.07 X_DIMENSION as in v02.05.07 Y_DIMENSION as in v02.05.07 NUMBER_OF_NEXT_LINE If the PAGE_KIND is FOR_CLP_PROCEDURE, this represents the number of lines after the current cstol procedure line that will be displayed. NON KEY Protection class: DB_MANAGER Data type: NATURAL Default value: 0 DISCRIMINATOR as in v02.05.07 TAE_PANEL_NAME as in v02.05.07 **************** ANALOG_CONVERSIONS The default values for the field DN_IS_SIGNED and DN_LENGTH have been changed respectively from FALSE and 0 to TRUE and 32. Appendix B The CSTOL ROUTE statement has been updated to allow the routing of a secondary stream to a sub clp. The new updated syntax is: Format ROUTE secondary-stream TO forward_stream ROUTE secondary-stream TO CLP_xx Arguments secondary-stream (identifier): The secondary data stream from the STREAMS table. forward-stream (identifier): The forward data stream. CLP_xx (where xx represents a sub clp number, such as 01, 1 or 19, between 1 and 20) indicates that the secondary stream has to be routed to the named sub clp (to allow execution of CSTOL statement generated by an outside process) Notes 1 to 3: see OASIS-CC CSTOL Reference Manual. 4. No stream should be named CLP_xx, where xx is number between 1 to 20. 5. As far as the CSTOL language is concerned CLP_01, CLP_1 or CLP_00001 indicate the same sub clp (CLP_1). 6. ROUTE secondary-stream to TRIGGER_CLP is now an illegal statement (unless TRIGGER_CLP is the name of a forward stream). Appendix C THRUPUT MEASUREMENTS OASIS-CC thruput was measured under the following conditions: Computer : Sparcstation 2, 32 Mbyte of main memory SunOs : 4.1.3 OASIS-CC : - Release of v02.05.08. Compiled with run-time checks ON - Application set up to decompose 128 measurements per packet. Measurements are converted to engineering unit using the analog conversion table and are limit checked. - Protocol used is Ip - OASIS verifies the sync pattern of each packet Simulator: - Packet size set to 128 bytes - Running on a remote workstation measured measured # measurements # measurements Limits measured packet bit decomposed changing status % of cpu rate rate per second per second 16/s 16kbps 0 n/a n/a << 1 16/s 16kbps 2048 0 n/a 16 16/s 16kbps 2048 1984 off 46 16/s 16kbps 2048 1984 on 53 24/s 24kbps 0 n/a n/a << 1 24/s 24kbps 3072 0 n/a 24 24/s 24kbps 3072 240 on 29 24/s 24kbps 3072 480 on 33 24/s 24kbps 3072 1200 on 48 32/s 32kbps 0 n/a n/a << 1 32/s 32kbps 4096 0 n/a 32 32/s 32kbps 4096 320 on 40 32/s 32kbps 4096 640 on 47 For all measurement, the primary stream was set up with a frame_length of 4096 and a time_out of 0.05. Appendix D SUNOS PATCH README NOTE (NEEDED BY S11W CODE) This patch is provided in $ODIST/common_distrib/objects. Patch-ID# 100672-01 Keywords: libc, static, libc.a, i/o, _aiocancel, _aioread, _aiowait, _aiowrite Synopsis: 4.1.1, 4.1.2: static libc.a missing asynchronous I/O _aiocancel _aioread _aiowait Date: 08/Jul/92 SunOS release: 4.1.1, 4.1.2 Unbundled Product: Unbundled Release: Topic: libc.a missing asynchronous I/O _aiocancel _aioread _aiowait BugId's fixed with this patch: 1044886, 1086417 Architectures for which this patch is available: sun3, sun4 Patches which may conflict with this patch: Obsoleted by: SYS_V Rel 4 Files included with this patch: aiolib.a Problem Description: The static version of libc (/lib/libc.a) doesn't include the aio system calls. There are several workarounds for this that *don't* require this patch: (1) extract the aio*.o modules from /usr/lib/shlib.etc/libc_pic.a and link with these statically if you must link statically. (2) link with shlib.etc/libc_pic.a: cc p.c -Bstatic -lc /usr/lib/shlib.etc/libc_pic.a If, for some reason, these workarounds don't do the trick (e.g., using a non-Sun linker), this patch provides a static library that includes non-PIC versions of aioread(), aiowrite(), aiocancel(), and aiowait(). The library can be statically linked into any application that uses these system calls: cc -Bstatic -o app app.c ... aiolib.a Install Instructions: Put the aiolib.a file for the appropriate architecture (sun3 or sun4) where ever an applications Makefile expects to find it. The same versions of the library will work for all 4.x SunOS releases. Appendix E Simulation File Protocol User's Guide This Appendix provides a short user's guide for the OASIS-CC capability that allows a user to read data from a file. 1 - General Notes This release provides a receiver task that expects its input to be file instead of an I/O port. The receiver provides the following capabilities: (a) The input stream can be either in the form of a TDM frame or in the form of a packetized stream; (b) The input stream can be decomposed in its atoms, like any other stream; and (3) Secondary streams can be routed. The receiver cannot record data and therefore cannot retrieve data. 2 - Limitations The implementation presents the same limitations as the IP or the ASYNC_CHAR protocols (see OASIS-CC Generic Communications User's Guide) 3 - Database Set Up The database set up is very much the same as the common set up shared by the generic communication protocols (IP and ASYNC_CHAR) provided with OASIS-CC. 3 - 1 Streams Table 3 - 1 - 1 Primary Stream The following fields need to be defined in the streams table STREAM_NAME => Name of the stream PROCESSOR => EXTCOMM_SUBSYSTEM DIRECTION => RETURN_STREAM PROTOCOL => TEST_4 TIME_OUT => Indicates the time between two transfer of data to the data_handling subsystem. A transfer occurs after a frame or a packet has been processed. FRAME_LENGTH => For a TDM frame, the frame size in bits. For a packetized system, at least the size, in bits, of the largest packet. STREAM_TYPE => PRIMARY 3 - 1 - 2 Secondary and Sub Streams They are defined as needed the same way they are be defined for the IP or the ASYNC_CHAR protocol. 3 - 2 Links Table This table is not used. 3 - 3 Latest_Data Table As in the IP or the ASYNC_CHAR protocol, the implementation expects the some information to be stored in the latest_data table EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => IS_PACKETIZED DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 0 : TDM frames 1 : Packets 2 : Packets with ID and size not on byte boundary EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => FILENAME DATA_CLASS => CHARACTER_STRING CHAR_STRING => name of the input file EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => DEBUG_LEVEL DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 0 : (or if this record is not present) no debug messages are generated 1 : debug messages are generated The following latest_data records are necessary only for packetized data streams. EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => ID_OFFSET DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Offset of the packet ID field EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => IS_SIZE DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Size of the packet ID field EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => LENGTH_OFFSET DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Offset of the packet lenght field EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => LENGTH_SIZE DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Size of the packet length field EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => LENGHT_UNIT DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Number of bytes per unit length EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => LENGTH_CORRECTIO DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Number of bytes to add to packet size * LENGTH_UNIT to get the full packet length Refer to the OASIS-CC Generic Communications User's Guide for more details on those last latest_data table records. Appendix F S11W Prototype Implementation User's Guide This Appendix provides a short user's guide for the current S11W support. 1 - General Notes The implementation allows the user to (1) Define the S11W board configuration at start up; (2) Modify (in a limited way) the board configuration at run time; (3) Transfer "data" to a DR11W compatible device (where "data" can be in the form of data routed from a receiver task or commands generated by the OASIS-CC command subsystem; (4) Read data from a DR11W compatible device; (5) Decompose and route part or all of the incoming blocks; and (6) Record and retrieve data for a recorded file. The transfers to and from OASIS are in fixed block sizes. When sending data, OASIS-CC will pad a block with 0 when the amount of data to be transfered is less than the block size). The implementation assumes that the transfers to and from OASIS-CC are unidirectional. The implementation used an EDT S11W interface (SBUS to DR11W parallel interface) and its associated SunOs driver. 2 - Database Set Up For Transmitter Task The following paragraphs give an overview of the specific database set up for an S11W forward stream. 2 - 1 Streams Table STREAM_NAME => Name of the stream PROCESSOR => EXTCOMM_SUBSYSTEM DESCRIPTION => LINK_NAME => pointer to the links table record DIRECTION => FORWARD_STREAM PROTOCOL => S11W_1 STREAM_TYPE => PRIMARY PARENT => not used STREAM_IS_ON => used by system TIME_OUT => Controls when OASIS-CC declares a time-out on a transfer. RECORD_IS_ON => used by system RECORD_FILE_NAME => used by system ASSOCIATED_FORWARD_NAME => not used FRAME_LENGTH => size of the transfer, in bits 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 - 2 Links Table LINK_NAME => As defined in the primary stream record DATA_LINE => Should contain the driver name. Example: /dev/s11w0 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 Required Latest_Data Table entries The set up of the S11W interface is controlled by records defined in the latest_data table. The set up is read when the receiver task is "switched on" and can only be modified changing the contents of the latest_data table record, "switching off" the receiver task and "switching" it on again. Exception to this rule is the bits FNCT1, FCNT2 and FCNT3 of the command register that are read from the latest_data table and reset every time a transfer out of OASIS-CC is initiated. The name used in each item_name field conforms to the S11W documentation (see the S11W User's Guide published by EDT). 2 - 3 - 1 Configuration Register Set Up EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_BSYP DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_CYCP DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_ENBB DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_OUTSK0 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_OUTSK1 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_INSK0 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_INSK1 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_RDYT DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_SWAP DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_SFIFO DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_BONRDY DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_NCOA DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_PFCT2 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_IA00 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 2 - 3 - 2 Command Register Set Up EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FNCT3 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FNCT2 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FNCT1 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FCYC DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 2 - 3 - 3 Others Required Records EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => DEBUG_LEVEL DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 0 or 1. If 0 no debug messages are printed. Default is 0. EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => MAX_FRAME_XMIT DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Controls the maximum amount of data that can be transfered in one request. Default value is 10 (i.e, 10 times the size of block). 3 - Database Set up For Receiver Task The following paragraphs give an overview of the specific database set up for an S11W return stream. 3 - 1 Streams Table 3 - 1 - 1 Primary Stream STREAM_NAME => Name of the stream PROCESSOR => EXTCOMM_SUBSYSTEM DESCRIPTION => LINK_NAME => pointer to the links table record DIRECTION => RETURN_STREAM PROTOCOL => S11W_1 STREAM_TYPE => PRIMARY PARENT => not used STREAM_IS_ON => used by system TIME_OUT => indicates the maximun rate at which OASIS-CC should poll the S11W driver RECORD_IS_ON => used by system RECORD_FILE_NAME => used by system ASSOCIATED_FORWARD_NAME => not used FRAME_LENGTH => size of the transfer in bits 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 3 - 1 - 2 Secondary And Sub Streams The streams table should be set up as needed when decomposition or routing of the incoming blocks is needed. As far as decomposition is concerned, the implementation assumes that each block represents a frame of data and that each frame is transfered in sync. 3 - 2 Links Table LINK_NAME => As defined in the primary stream record DATA_LINE => Should contain the driver name. Example: /dev/s11w0 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 3 - 3 Required Latest_Data Table entries The set up of the S11W interface is controlled by records defined in the latest_data table. The set up is read when the reciever task is "switched on" and can only be modified changing the contents of the latest_data table record, "switching off" the receiver task and "switching" it on again The name used in each item_name field conforms to the S11W documentation (see the S11W User's Guide published by EDT). 3 - 3 - 1 Configuration Register Set Up EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_BSYP DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_CYCP DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_ENBB DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_OUTSK0 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_OUTSK1 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_INSK0 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_INSK1 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_RDYT DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_SWAP DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_SFIFO DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_BONRDY DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_NCOA DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_PFCT2 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_IA00 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 1 3 - 3 - 2 Command Register Set Up EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FNCT3 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FNCT2 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FNCT1 DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => S11W_FCYC DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 1 : the bit is set to 1 other : the bit is set to 0 default: the bit is set to 0 3 - 3 - 3 Others Required Records EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => TIME_OUT DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Board time out in hundreth of seconds. Needed to avoid having to CNTRL-C to exit of OASIS-CC. This is the amount of time a user will have to wait for a switch off statement to take effect. Recommended value ~ 500. Default is twice the time_out value from the streams table. EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => QUEUE_SIZE DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => Indicates the number of i/o request that can be pre-queued by OASIS-CC. This number should not be greater than 20. Default is 10. EXTERNAL_ELEMENT => Name of the stream ITEM_NAME => DEBUG_LEVEL DATA_CLASS => NUMERIC EU_UNITS => DN DN_LOW => 0, 1 or 2. If 0 no debug messages are printed. Default is 0. 4 - Miscellaneous 4 - 1 Stack Space Limitation The current stack space of an S11W reciever task is such, that frame_size * queue_size should be limited to about 20000 bytes. 4 - 2 Switching Off An S11W Stream Because there is no way to cancel an asynchronous I/O in progress, switching off an S11W stream blocks OASIS-CC until a board-level timeout occurs or all the current pending I/Os are completed. Appendix G Preliminary S11W prototype performances These performances were measured using a block size of 1000 bytes. They were obtained by transfering large number of blocks (up to 50000 per measurement). OASIS-CC was running on a SparcStation 2, under SunOs 1.4.3. Measured rate Measured rate Decomposition Recording Approximate Data Loss bps block/s cpu usage 1.4 Mbit/s 177 no no <8 % no 1.0 Mbit/s 125 no yes ? no 1.0 Mbit/s 125 yes(*) no ~20% no (*) 2 changing items per block (i.e 250 measurements/s), display at a display update rate of 1/s Notes: (1) The fact the cpu usage is low does not imply that OASIS-CC can ingest data at a higher rate with no loss of data. Data will be lost if the system (i.e the combination of the Ada Runtime Scheduler and of the SunOs Scheduler) is unable to start the next i/o request within 1/(block rate) of the preceeding block. In the test above a 177 block/s, the interval between two blocks is 5 milliseconds. (2) Mainly because of the lack of real-time scheduling of SunOs 4.1.x these performances can only be achieved on a "clean" system.