PN-85.3 A CAMAC DRIVER FOR RSX-11M Daniel B. Curtis 30-MAR-79 ABSTRACT ________ This program note describes a driver for RSX-11M. The driver allows a task to interface to a BD-011 or JY411 parallel CAMAC branch highway. This driver is not suitable for single purpose very fast data acquisition systems. The program note is written with the same format as a chapter in the RSX-11M I/O Drivers manual. Only RSX-11M is supported. RSX-11M CAMAC DRIVER Page 2 A CAMAC DRIVER FOR RSX11-M 1.0 INTRODUCTION ____________ The EG&G BD-011 and Jorway JY411 CAMAC branch interfaces supply RSX11M with the ability to access CAMAC modules on a parallel branch highway. This device driver is designed for use with many tasks accessing different CAMAC modules. Due to the I/O overhead necessary in RSX, it may not be suitable for extremely fast data acquisition from a single purpose CAMAC system. For fast data acquisition, use a privileged task or use COMMON and DEVICE partitions. The device driver is able to support multiple interfaces of the same type. It is not possible to mix JY411 and BD-011 interfaces with the same device driver. 2.0 QIO MACRO ___ _____ This section summarizes the valid functions of the QIO macro for the CAMAC driver. 2.1 Standard QIO Functions ________ ___ _________ Table 1 lists the standard functions of the QIO macro that are valid for the CAMAC driver. Table 1 Standard QIO Functions for CAMAC Format Function ______ ________ QIO$C IO.ATT,... Attach device QIO$C IO.DET,... Detach device QIO$C IO.KIL,... Cancel I/O requests RSX-11M CAMAC DRIVER Page 3 2.2 Device Specific QIO Functions For CAMAC ______ ________ ___ _________ ___ _____ Table 2 lists the device specific functions of the QIO macro that are supplied for the CAMAC driver. These functions may be modified by ORing a modifier, described in section 5, with the function. There are two units associated with each branch driver. The even numbered unit is used for non NPR type transfers, while the odd unit is used for NPR type transfers. Therefore, all IO.CDM and IO.LPR operations MUST be sent to odd numbered units, all others to even ____ numbered units. Table 2 Device Specific QIO Functions for CAMAC Format Function ______ ________ QIO$C IO.CPW,..., Programmed data write QIO$C IO.NDT,...,<0,0,0,cs,fna> Non-data transfer QIO$C IO.CPR,..., CAMAC programmed data read QIO$C IO.CRR,..., CAMAC register read QIO$C IO.CDM,..., CAMAC DMA transfer QIO$C IO.LPR,..., CAMAC list processing 2.2.1 IO.CRR - The IO.CRR QIO function is used to read the CAMAC registers. The registers are read out and put in the buffer in order. If a BD-011 is used, the last word will be zero. The second word will contain the "Selected Option" word (see section 5). For more information refer to the branch driver description (HN-15 or HN-2). Note that the status of the CAMAC registers will depend on the time that this function is dequeued by the driver. So, for some applications, it may be best to attach the driver to your task before using IO.CRR. The 'stadd' parameter is the starting address of a 14 (octal) byte buffer. The format of this buffer is shown in table 3. The 'size' parameter must be 14 (octal). The next 3 arguments must be zero or blank. RSX-11M CAMAC DRIVER Page 4 Table 3 Register Read Input Buffer from low to high address ********************************* * Control status register * N ********************************* * Selected Option Word * N+2 ********************************* * Memory Address Register * N+4 ********************************* * Crate select Register * N+6 ********************************* * Instruction Register * N+10 ********************************* * Extended Word Count (JY411) * N+12 ********************************* 2.2.2 IO.NDT - The IO.NDT QIO function is used to execute a CAMAC non-data transfer operation. The first three arguments must be blank or zero 'cs' is the crate select mask word and must be setup as in table 4 'fna' is the function, station, and address control word and must be setup as in table 5 Table 4 Crate Select Mask Word 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 * - - - - - - - - - - - - - - - * *C7 C6 C5 C4 C3 C2 C1 00 00 00 00 00 00 00 00 00* * - - - - - - - - - - - - - - - * Table 5 FNA Control Word 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 * - - - - - - - - - - - - - - - * *BB SZ F5 F4 F3 F2 F1 N5 N4 N3 N2 N1 A4 A3 A2 A1* * - - - - - - - - - - - - - - - * RSX-11M CAMAC DRIVER Page 5 2.2.3 IO.CPR - The IO.CPR QIO function is used to do a programmed data read. Refer to section 5 to find the interaction of the 24 bit mode request with the byte count. 'stadd' is the starting address to store the data. See table 6 for the buffer format. 'Size' is the size in bytes and must be a '2' or '4' 'cs' is the crate select mask 'fna' is the function, station, address word Table 6 Programmed Data Read Buffer Format ************************** * Low Order 16 bits * N ************************** * zero - High byte * N+2 ************************** 2.2.4 IO.CPW - The IO.CPW QIO function is used to do a programmed data write. 'low' is the low order 16 bits of the 24 bit transfer 'hiw' is the high order 8 bits of the 24 bit transfer The next parameter must be zero 'cs' is the crate select mask word 'fna' is the function, station, and address control word If a 16 bit transfer is to be done, the 'hiw' must still be specified. NOTE If a 16 bit write is done to a 24 bit module, the upper 8 bits of the module will be set to a random value. RSX-11M CAMAC DRIVER Page 6 2.2.5 IO.CDM - The IO.CDM QIO function is used to cause a NPR transfer to and from CAMAC. This function must be sent to an odd numbered unit; refer to the programming notes. 'stadd' is the starting address of the buffer 'size' is the size in bytes of the buffer to be used 'cs' is the crate select word 'fna' is the function, station, address control word 'bm' is the control word for the setting of the BM bit (bits 14&15 only) 2.2.6 IO.LPR - The IO.LPR QIO function is used to cause a list of NPR type functions to be sent to the driver. As such, the operation must be sent to an odd numbered unit. The QIO must indicate two buffers, one for data and another for the operation list. This QIO function is described in section 3. 'stadd' is the starting address of the data buffer 'size' is the size in bytes of the data buffer 'cstadd' is the starting address of the list buffer 'csize' is the size of the list buffer NOTE The list buffer must be terminated with a zero word. Currently there is no check for overflowing the control list. There is also no check for correct (odd number) unit. These will be considered for a future release. RSX-11M CAMAC DRIVER Page 7 3.0 LIST PROCESSING OPTION ____ __________ ______ As mentioned in section 2.2.6, the user may request the execution of a list of CAMAC operations by using a single QIO$ request. This greatly reduces the system overhead. The procedure to perform a list directed CAMAC I/O request is: 1. Set up a list describing the CAMAC operations to be performed 2. Reserve a buffer area for the storage of any data to be read from CAMAC modules 3. Issue an I/O request using the QIO$ MACRO and the IO.LPR function code (All requests for list processing CAMAC operations must be made to odd numbered units as in the case of normal CAMAC DMA transfers.) The exact format of the QIO$ MACRO parameters is described in section 2.2.6. The format of the COP list is described in section 3.1. Section 5 contains a discussion of driver error returns that may occur during list processing operations. 3.1 CAMAC Operations Packet (COP) List Format _____ __________ ______ _____ ____ ______ The CAMAC operations packet (COP) list is a list of CAMAC operations to be performed by the CAMAC driver. Each packet in the COP list has the following format: --------------------------------- | BYTE COUNT | OPTION FLAGS | --------------------------------- | CRATE SELECT | --------------------------------- | WORD COUNT | --------------------------------- | FNA | --------------------------------- | OPTIONAL DATA (0 TO 3 WORDS) | --------------------------------- | FIRST WORD OF THE NEXT PACKET | --------------------------------- Where: BYTE COUNT specifies the number of bytes in the COP list packet. This value will be between eight and fourteen depending on the number of optional data words. OPTION FLAGS is a bit mask used to request special operations to be performed. CRATE SELECT specifies the word to be loaded into the branch driver crate select/word count register when the operation RSX-11M CAMAC DRIVER Page 8 specified by this packet is performed. WORD COUNT specifies the value to be loaded into the branch driver extended word count register when the operation is performed. Only bits 15,14, and 11-0 may be set. Bits 13 and 12 are set by the driver. To set the BM bit, you set bit 15 in this register. FNA specifies the value to be loaded into the branch driver instruction register when the operation is performed. OPTIONAL DATA specifies the values to be used by any of the options selected by the OPTION FLAGS byte in the first word of the packet. The contents of this area is fully described below in section 3.1.1. The COP list is terminated by a packet whose first word is zero. 3.1.1 Description Of OPTION FLAGS - This section describes the function of the OPTION FLAGS field of the COP. This byte is used as a bit mask to select special operations. In the following discussion, bit 0 refers to the least significant bit of the byte. The option byte is interpreted as follows. The bits within the byte are examined one at a time starting with bit zero. A set bit indicates that the option associated with that bit has been selected. If the option selected requires a data word then the value stored in the next word of the OPTIONAL DATA area is used. The bit assignments and associated data word descriptions are listed below. BIT 0 If this bit is set, the next word in the OPTIONAL DATA area specifies the buffer offset at which the first word of CAMAC data read by this command is to be placed. If no buffer offset is specified, any data that is read will be placed in the next available buffer word (starting with the first word of the buffer if no offset is specified in the first packet in the COP list). BIT 1 If this bit is set, the next word in the OPTIONAL DATA area specifies the expected end CAMAC crate, station, and subaddress of this operation. The format of this data word is: bit 0 -> bit 3 = subaddress bit 4 -> bit 8 = station bit 9 -> bit 15 = crate mask BIT 2 If this bit is set the next word in the OPTIONAL DATA area specifies a repeat count for the operation requested in the packet. RSX-11M CAMAC DRIVER Page 9 BIT 3 Reserved BIT 4 Reserved BIT 5 This bit is set to allow unknown length transfers to be specified. It will cause the word count to be overwritten if the specified word count would cause the operation to overflow the end of the data buffer. The COP will execute just as normal but the maximum number of operations that it is allowed to execute is adjusted to fit into the buffer. BIT 6 If this bit is set the driver will ignore any CAMAC time out errors (T02 bit in the interface CSR) that may occur during the execution of the command. If not set, a time out condition will produce an error. BIT 7 If this bit is set the driver will ignore the CAMAC crate overflow error condition. If not, crate overflow will produce an error. 4.0 STATUS RETURNS ______ _______ The error and status conditions listed in table 7 are returned by the CAMAC driver in the first byte of the I/O status block. The next byte will contain a packed representation of the control status word of the branch driver (see table 8) for all functions except for IO.LPR. For the IO.LPR function, the byte will contain the number of the operation in the list ( the first operation is operation '0'). The second word of the I/O status block will contain the value selected from the function modifiers described in section 5. The default is the control status word of the branch interface after the operation completed. RSX-11M CAMAC DRIVER Page 10 Table 7 Status returns IS.SUC Successful Completion- The operation specified in the QIO directive was completed successfully. IE.VER Unrecoverable Error- The operation caused a CAMAC timeout. Typically this is due to an offline crate, the selection of an unoccupied station, or the lack of an 'X' response for the JY411. If the 'CM.NMS' modifier is not set, a 'SELECT ERROR' message will be printed on CO:. IE.BAD Bad Parameter- This occurs if an attempt was made to do a NPR transfer to an even numbered unit or a non-NPR transfer to an odd numbered unit. IE.ONP Illegal Subfunction- This is due only to programmer error. It is caused by attempting to do an illegal transfer function. Status Returns for List Operations IE.FHE Fatal Hardware Error- The expected 18 bit address of the last word of the list operation was not correct. This implies that the NPR function of the branch driver is malfunctioning and the system may be corrupted. A 'DEVICE NOT READY' message will be output at CO: and the NPR unit will be set offline. This will cause any other attempt to use that unit to return with an IE.OFL (device offline) error. IE.RCN Record Number Error-This error is returned if an unexpected CAMAC timeout (T02) occurs. IE.VER Should never happen when list processing. If it does, contact the RSX-11M maintanence person in the Computing Department. IE.RBG Illegal Record Size- An unexpected crate overflow was encountered. IE.SPC Illegal User Buffer- This is set if an attempt was made to write data outside of the data buffer. It will be set if the buffer offset is outside of the buffer or if a a COP attempts to do a transfer that could extend past the end of the data buffer (see section 3.1.1 for the description of BIT 5 of the option flag byte). IE.DAO Data Overrun- This is set if an end CNA check was requested in the list and it failed. RSX-11M CAMAC DRIVER Page 11 Table 8 Packed Status Byte Bit 0 Branch Q of operation Bit 1 Branch X of operation Bit 2 Abort bit Bit 3 Crate Overflow bit Bit 4 CAMAC Timeout Bit 5 PDP Timeout Bit 6-7 Zero The driver may produce a 'Device Not Ready' message at the console. This is due to programmer error or a bad interface. If this message occurs, a device display should be done. If only the odd unit but not the even unit is marked offline the branch driver is faulty and must be replaced<1>. <1> The hardware addressing of the Jorway is faulty and it is possible that the system has been corrupted. RSX-11M CAMAC DRIVER Page 12 5.0 PROGRAMMING HINTS ___________ _____ This section contains information on programming considerations that are relevant to the users of the CAMAC driver. 5.1 Function Modifier Actions ________ ________ _______ The function modifier is used to control the information returned to the I/O status block and to suppress SELECT ERROR messages. The possible modifiers follow: 1. Only one of this type of modifier may be used. Any of these modifiers may be used with the next set of modifiers. 1. CM.ASM- This will cause the Option Select word to be returned to the second word of the I/O status block. 2. CM.CS- This will cause the Crate Select register of the interface to be returned to the second word of the I/O status block. 3. CM.CSR- This (the default case) will cause the control status register of the interface to be returned to the second word of the I/O status block. 4. CM.EWC- This will cause the extended word count register of the interface to be returned to the second word of the I/O status block. 5. CM.FNA- This will cause the FNA register of the interface to be returned to the second word of the I/O status block. 6. CM.TOP- This may only be selected when doing list processing. It returns the index of the last byte transferred from the buffer. This index when added to the starting address of the buffer generates the address of the last word transferred. 2. CM.NMS- This modifier may be added with any one of the above ___ modifiers. It will suppress the generation of a SELECT ERROR message when a module does not respond or if the transfer falls off of the branch. RSX-11M CAMAC DRIVER Page 13 5.2 Selected Option Word ________ ______ ____ This word indicates which assembly options were selected for the driver. The word is bit encoded for the operations and the currently assigned bits are: 1. Bit 0- Indicates driver is able to generate SELECT ERROR messages. 2. Bit 1- Indicates able to do list processing. 3. Bit 2- Driver expects to use a Jorway Branch interface. 5.3 IO.CPR ______ If the byte count is '2' and a 24 bit transfer is requested, only the lower 16 bits are transferred. If the byte count is '4' and a 16 bit transfer is requested, the second word will be zero. 5.4 IE.VER ______ When a non list processing operation detects an IE.VER error return and CM.NMS was not selected, you should wait at least 15 seconds before attempting to do another CAMAC operation. This is due to the select error message printed out at the console. This message is printed by TKTN. If TKTN and the MCR reside in the same partition, MCR will never be able to get in to abort the task causing the select errors. This condition does not occur if TKTN and MCR reside in different partitions. 5.5 Unit Selection ____ _________ All non-NPR (non block transfer) operations to CAMAC must be sent to an even numbered unit. All NPR operations must be sent to an odd numbered unit. If this rule is violated an IE.BAD status will usually be returned. If the program attempted to do a NPR operation with a function that does not require a transfer, the driver will time out with a IE.ONP status return and a 'Device not ready' message will be printed at the console. The NPR functions are IO.CDM and IO.LPR. 5.6 FORTRAN Use _______ ___ When using the driver from a FORTRAN program some of the QIO directives require an address in the parameter array. These QIO functions are: RSX-11M CAMAC DRIVER Page 14 1. IO.CPR 2. IO.CRR 3. IO.CDM 4. IO.LPR 5.7 Function Code Definitions ________ ____ ___________ The following function codes may be defined in the user program, placed in the system macro library, or placed in the system default I/O definition module in the system object library. All values are in octal. 1. IO.CPW=400 2. IO.NDT=402 3. IO.CPR=1000 4. IO.CRR=1001 5. IO.CDM=3000 6. IO.LPR=3001 7. CM.CSR=00 8. CM.FNA=10 9. CM.CS= 20 10. CM.EWC=30 11. CM.ASM=40 12. CM.TOP=50 13. CM.NMS=200 6.0 INSTALLING THE DRIVER __________ ___ ______ The driver is usually installed during the sysgen procedure. If this was not done, obtain a copy of the current installation tape (DOS format), copy it to 'LB:[200,200]' and type 'HELP %' or 'PIP TI:=LB:[200,200]HELP.TXT'. RSX-11M CAMAC DRIVER Page 15 7.0 FOR MORE INFORMATION ___ ____ ___________ For more information obtain a copy of the CAMAC branch driver hardware specification (HN-2 or HN-15) or contact the FERMILAB Computing Department. Written by Daniel B. Curtis