4 DRIVER IOCTL COMMANDS

This section describes all control commands which can be invoked by use of the VxWorks ioctl function. The parameter command specifies which operation has to be performed by the driver while the parameter argument passes the address of an argument to the command handler. In cases where multiple arguments are needed the address of a structure which contains those is passed.

All command literals and argument data structures are defined in the include file rmnCommands.h.

A pointer to the argument is passed in the ioctl call, never the argument value itself. The ioctl function returns values through this pointer.

All ioctl calls return lcudrvOK on successful completion, otherwise one of the stated error-codes.

4.1 Access to the User Memory

The board's User Memory, which is the DPRAM available to the user to store data, can be directly accessed via VME R/W cycles, but only after getting from the device driver the corresponding VME addresses (addresses of the first and the last byte location) as seen from the CPU, e.g. in the CPU local address space. Two commands are available to get the base and the top addresses of the user memory. The user is responsible not to exceed the address space defined within the two boundaries during a direct R/W, otherwise a VME bus error will probably occur.

· Get User Memory Base Address
Description - Returns the base address (CPU local address-space) of the user memory area; it is equal to the <board base address> + 0x40.
Literal: rmnCMD_ADDR_GET_USER_MEM_BASE
Argument: pointer to a generic address (void *)
Return Value: user memory base-address
Errors: none (always lcudrvOK)

· Get User Memory Top Address
Description - Returns the top address (CPU local address-space) of the user memory, that is the address of the last byte of the user memory area. The actual value returned depends on the memory option of the board, according to the following table:


memory option	top address
256 KB	<board base address> + 0x03FFFF
512 KB	<board base address> + 0x07FFFF
1 MB	<board base address> + 0x0FFFFF

Literal: rmnCMD_ADDR_GET_USER_MEM_TOP
Argument: pointer to a generic address (void *)
Return Value: user memory top-address
Errors: none (always lcudrvOK)

Normally the user should not be interested in getting the base address of the board, which is also the base address of the Register Memory. Only for engineering purposes the following command is provided:

· Get Register Memory Base Address
Description - Returns the base address (CPU local address-space) of the register memory area; it is equal to the <board base address>.
Literal: rmnCMD_ADDR_GET_REGS_MEM_BASE
Argument: pointer to a generic address (void *)
Return Value: register memory base-address
Errors: none (always lcudrvOK)

4.2 Access to the Register Memory

No direct user access is foreseen to the board's Register Memory. All accesses to this area shall be handled within the driver.

4.2.1 Board Control and Status

The user can access the Control and Status Register (CSR) or one of its bit by calling the commands described below.

· Get Control and Status Register
Description - Reads the CSR register (8 bits).
Literal: rmnCMD_GET_STATUS
Argument: pointer to a byte (unsigned char)
Return Value: CSR value (unsigned char)
Errors: none (always lcudrvOK)

· Set Control and Status Register
Description - Sets the CSR register (only the user-writable bits: failLED, badData, ownData)¹.
Literal: rmnCMD_SET_STATUS
Argument: pointer to a byte (unsigned char), which contains the CSR value
Return Value: -
Errors: none (always lcudrvOK)

· Get Fail LED Bit
Description - Reads the Fail LED bit of the CSR (bit 7). The bit value corresponds to the status of the LED on the board's front panel (0='OFF', 1='ON').
Literal: rmnCMD_GET_FAIL_LED
Argument: pointer to an integer (int)
Return Value: Fail LED bit value (int)
Errors: none (always lcudrvOK)

· Set Fail LED Bit
Description - Sets the Fail LED bit of the CSR (0='switch OFF', 1='switch ON').
Literal: rmnCMD_SET_FAIL_LED
Argument: pointer to an integer (int), which contains the Fail LED bit value
Return Value: -
Errors: none (always lcudrvOK)

4.2.2 Node Identification

The user can access the Node ID Register by calling the command described below.

· Get Node ID Register
Description - Reads the Node ID register, which contains the node number associated to the board within the reflective memory network. The value (must be in the range [0..255]) depends on the Board Node ID Field jumpers J9 configuration.
Literal: rmnCMD_GET_NODE_ID
Argument: pointer to an integer (int)
Return Value: board's node ID (int)
Errors: none (always lcudrvOK)

4.2.3 Interrupt Commands

The user can access the four Interrupt Control Registers (ICRs), the three Interrupt Sender ID registers and the Interrupt Command Register by calling the commands described below.

· Enable Interrupt Source
Description - Enables an interrupt source by setting the Interrupt Enable bit (bit 4 of the ICR). At the completion of this routine, every interrupt of the selected source will be detected and served, e.g. the associated ISR will be called, if attached.
Literal: rmnCMD_ENABLE_INTERRUPT
Argument: pointer to an integer, which contains the interrupt source number [0..3]
Return Value: -
Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

· Disable Interrupt Source
Description - Disables an interrupt source by resetting the Interrupt Enable bit. At the completion of this routine, every interrupt received will not be detected by the driver (it will actually be stored in the Interrupt FIFO of the board).
Literal: rmnCMD_DISABLE_INTERRUPT
Argument: pointer to an integer, which contains the interrupt source number [0..3]
Return Value: -
Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

· Enable Interrupt Autoclear
Description - Enables the interrupt-autoclear feature of the board by setting the Interrupt Autoclear bit (bit 3 of the ICR), so that the selected interrupt source will be automatically disabled, after every interrupt detection. Then an explicit call to the interrupt enabling routine must be performed in order to receive the next interrupt.
Literal: rmnCMD_ENABLE_INT_AUTOCLEAR
Argument: pointer to an integer, which contains the interrupt source number [0..3]
Return Value: -
Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

· Disable Interrupt Autoclear
Description - Disables the interrupt-autoclear feature of the board by resetting the Interrupt Autoclear bit.
Literal: rmnCMD_DISABLE_INT_AUTOCLEAR
Argument: pointer to an integer, which contains the interrupt source number [0..3]
Return Value: -
Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

· Clean Interrupt FIFO
Description - Cleans the network interrupt receiving FIFO by writing any data to the Interrupt Sender ID register. All the interrupt previously stored and blocked in the FIFO will be cancelled. This command is valid only for network interrupt sources [INT1-3].
Literal: rmnCMD_CLEAN_INT_FIFO
Argument: pointer to an integer, which contains the interrupt source number [1..3]
Return Value: -
Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

· Configure Interrupt Source
Description - Sets the configuration of an interrupt source and enables it. There are 2 possible ways of configuring an interrupt source:

2. obtaining the ID of the interrupt synchronization semaphore, which will be "given" when the interrupt occurs; in this case the user defined ISR will run in a normal task context and has to "take" the interrupt synchronization semaphore in order to remain blocked until the interrupt occurs.

An interrupt source is considered successfully configured when it is enabled and a user-provided ISR is attached or the synchronization semaphore ID has been returned to the configuring task.

semaphore pointer (meaningful only if mode is rmnTASK_CONTEXT)
Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

· Get Interrupt Configuration
Description - Gets the current configuration of an interrupt source.
Literal: rmnCMD_GET_INT_CONFIG
Argument: pointer to the rmnINT_GET_CONFIG_DATA structure, with the input argument:

· Send Interrupt
Description - Sends an interrupt to the selected remote node or to every node (broadcast interrupt) through the reflective memory board and the fiber-optic reflective memory network. This command is valid only for network interrupt sources [INT1-3].
Literal: rmnCMD_SEND_INTERRUPT
Argument: pointer to the rmnINT_SEND_DATA structure, which contains:

· Reset Interrupt Source
Description - Resets an interrupt source. The user-defined ISR will be detached (if configured), the interrupt autoclear will be disabled, the interrupt FIFO will be cleaned (in case of network interrupt source [1..3]) and the interrupt source will be disabled. This routine must be called before re-configuring an interrupt source.
Literal: rmnCMD_RESET_INTERRUPT
Argument: pointer to an integer, which contains the interrupt source number [0..3]
Return Value: -
Errors: wrong parameter-value: lcudrvERROR_INVALID_ARGUMENT

4.3 Test Command

· Test Board and Link
Description - This command performs the most comprehensive test of the board and the link, computing also the link round trip time, that is the time spent by a data item (1, 2 or 4 bytes) to travel through all the nodes of the reflective memory network. The detailed test procedure is as below:

2. verifies that the board is properly installed at the given VME address, by reading and checking the value of the Board ID register

3. tests the user memory, by writing and reading back to/from a set of memory locations all over the user memory area

4. checks the optical link's integrity, verifying the receiving back of the data originated by the local node itself within a certain timeout

5. if no errors, reset (switch off) the Fail LED on the front panel to give a visual feedback that the device has been tested successfully

Literal: rmnCMD_TEST_BOARD
Argument: pointer to an unsigned long
Return Value: link round trip time (unsigned long) in nanoseconds

Errors: no reflective memory board found at the specified VME address (Board ID register value not valid): rmnERROR_INVALID_BOARD_ID
no HW found at the specified VME address: rmnERROR_INVALID_VME_ADDR
test of the board's user memory failed: rmnERROR_BAD_DATA
test of the link integrity failed: rmnERROR_LINK_BROKEN

4.4 Reset Command

· Reset Device
Description - This routine reset all the network interrupt sources and resets the writable bits of the CSR register (badData, ownData and failLED).
Literal: rmnCMD_RESET_DEVICE
Argument: -
Return Value: -
Errors: none (always lcudrvOK)

4.5 Driver-Related Commands

The following ioctl-commands are handled completely within the driver and not forwarded to the board.

· Get Driver Version
Description - Returns an integer value derived from the module's version. Bits 31..16 contain the major version number, bits 15..0 contain the minor version number.
Literal: rmnCMD_GET_DRIVER_VERSION
Argument: pointer to an integer (int)
Return Value: version (integer)
Errors: none (always lcudrvOK)

· Set Timeout Value
Description - Modifies the timeout-value to be used for device access semaphore-waits.
Literal: rmnCMD_SET_TIMEOUT
Argument: pointer to an integer, which contains the timeout value in ticks
Return Value: -
Errors: timeout value is not valid: lcudrvERROR_INVALID_ARGUMENT

· Get Timeout Value
Description - Reads the timeout-value of the device access semaphore-waits.
Literal: rmnCMD_GET_TIMEOUT
Argument: pointer to an integer
Return Value: timeout value in ticks
Errors: none (always lcudrvOK)

· Free Device
Description - Forces a close of a channel opened in exclusive mode.
Literal: rmnCMD_FREE_DEVICE
Argument: -
Return Value: -
Errors: there is no channel in exclusive mode: rmnERROR_NO_EXCLUSIVE:

4.6 Simulation Mode

The simulation mode allows to run the driver without the reflective memory board. The device can be created in simulation mode by specifying 0xffffffff as the base address in the rmnDevCreate call. In this case the driver maps in the CPU RAM the register and the user memory of the reflective memory board. The usage of ioctl commands result simply in changes to the content of the simulated board's registers.