PN-85.2 A CAMAC DRIVER FOR RSX-11M Daniel B. Curtis 22-May-78 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. | | 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. | | BIT 3 Reserved RSX-11M CAMAC DRIVER Page 9 | BIT 4 Reserved | | BIT 5 This bit is set to allow unknown length transfers to be | specified. It will cause the word count part of the COP to | be overwritten if the specified word count would cause the | operation to overflow the end of the data buffer. This | modified 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. You must reset the COP word | count on subsequent operations as it may have been modified. | | 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