FEC2RORC Library Documentation

FEC2RORC Version 2.1

The fec2rorc library is a set of APIs that allow users to create applications that interact with front end electronics via the DDL. This library provides easy access to the underlying power of the rorc libraries and drivers that have been part of DATE for a long time.

Fec2rorc has been designed to be as flexible and simple as possible. It has a number of generic functions (fec2rorc_lib.h) and some specific ones to control the TPC-RCU device (fec2rorc_rcu.h). The generic functions allow the control of front end electronics in an embedded manner, not available in the FeC2 script based system. Since this is a C API, the control of the front end electronics can be managed with simple structures and controlled by error handling.

It abstracts physmem usage and segmentation meaning that the end user need only be concerned with the operation and management of their own resources and no longer has to consider setting up areas of physmem to use. This physmem management allows a program using the C API to open more than one RORC channel and perform all of the various functions available. Simultaneous access for forked processes is possible.

Description of the API routines

Abstraction of the rorc libraries to allow easy implementation of user applications to configure front end electronics. Internally handles device locking and per device physmem segmentation.
Paradigm:
- Get a channel_key
- Use that channel_key for library functions
- Release the channel_key

Only return codes are delivered by the APIs without any standard output.

Channel Keys

The fec2rorc library I/O functions take *chan_key as an argument. Each "key" is actually a C struct which can be found in fec2rorc_lib_structs.h. These keys give fec2rorc the information about which rorc device and channel to use, where physmem has been allocated for the use of this device and other important information.

#include <fec2rorc_lib_structs.h>
Note that this header is included by fec2rorc_lib.h and fec2rorc_rcu.h

Only the user-relevant data members are listed:

`int minor`	The minor number of the rorc device
`int channel`	The channel of the rorc device
`int physmem_fd`	rorc library specifics
`int err`	Error status of the rorc device
`int status`	The current status of the key: R_OPEN: rorc device opened by user and ready R_CLOSED: rorc device was closed by the user) R_NOT_OPEN_ERR: rorc device could not be opened due to error

get_channel

Synopsis:

Return a chan_key pointer for use in I/O functions

#include <fec2rorc_lib.h> chan_key* get_channel (int revision, int serial, int chan)

Description:

The get_channel() function returns a pointer to a chan_key. This pointer is then used as an argument for the other functions in the fec2rorc library. It allows multiple devices / channels to be used by one program by providing corresponding keys for each channel. The chan_key struct has a number of data members (refer to channel keys documentation) to check if the key is valid or if an error occured the value of the status and err members should be checked by the client application.

Parameters:

`int revision`	The revision number of the rorc device to be used (option: if paramter `revision` = -1 then parameter `serial` is interpreted as minor device number of the rorc device)
`int serial`	The serial number of the rorc device to be used
`int chan`	The channel number [0-1] of the rorc device to be used
Return value:	This function will always return a chan_key pointer

release_channel

Synopsis:

Release a rorc device for re-use.

#include <fec2rorc_lib.h> int release_channel (chan_key *ptr)

Description:

Use this function when you no longer have use for the rorc device described by chan_key *ptr. This will mark the device as free for use.

Parameters:

`chan_key *ptr`	A pointer to a valid channel key.
Return value:	0 on success other values mean error

ddl_writeBlock

Synopsis:

A general function for writing to front end electronics.

#include <fec2rorc_lib.h> int ddl_writeBlock (chan_key *ptr, u_long *array_ptr, int num_words, u_long fee_address)

Description:

Write num_words of data from array_ptr to fee_address using the rorc device identifed by chan_key *ptr. This function is capable of writing to any addressable and writeable space in the front end electronics.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long *array_ptr`	Pointer to the word or block to be written
`int num_words`	The number of words to be written starting from the array_ptr
`u_long fee_address`	The FEE address to be written
Return value:	0 on success other values mean error

ddl_readBlock

Synopsis:

A general function for reading from front end electronics.

#include <fec2rorc_lib.h> int ddl_readBlock (chan_key *ptr, u_long fee_address, u_long *buffer, u_long buffer_size)

Description:

Read back buffer_size number of words from the fee_address using the rorc device identified by chan_key *ptr and copy up to buffer_size words into buffer.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long fee_address`	The FEE address to read from
`u_long *buffer`	Memory location to write data to
`u_long buffer_size`	The size of the buffer
Return value:	Number of words read on success other values mean error

ddl_sendCommand

Synopsis:

Send a command instruction to the front end electronics.

#include <fec2rorc_lib.h> int ddl_sendCommand (chan_key *ptr, u_long fee_address)

Description:

Send a FECTRL command to the fee_address using the rorc device identified by the chan_key *ptr.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long fee_address`	The FEE address to send the command to
Return value:	0 on success other values mean error

ddl_statusReadout

Synopsis:

Send a command instruction to the front end electronics and return the response.

#include <fec2rorc_lib.h> int ddl_statusReadout (chan_key *ptr, u_long fee_address);

Description:

Send a FESTRD command to the fee_address using the rorc device identified by the chan_key *ptr.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long fee_address`	The FEE address to send the command to
Return value:	19bit word <0 on rorc error [DDL error codes]

RCU Specific Functionality

rcu_resetFEC

Synopsis:

Reset active Front End Cards

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_resetFEC (chan_key *ptr)

Description:

Send a FEC_RESET command to the RCU via the rorc device identified by the chan_key *ptr .

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
Return value:	0 on success other values mean error

rcu_resetRCU

Synopsis:

Reset RCU

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_resetFEC (chan_key *ptr)

Description:

Send a RCU_RESET command to the RCU via the rorc device identified by the chan_key *ptr .

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
Return value:	0 on success other value mean error

rcu_resetALL

Synopsis:

Reset active Front End Cards and RCU

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_resetFEC (chan_key *ptr)

Description:

Send a GLB_RESET command to the RCU via the rorc device identified by the chan_key *ptr .

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
Return value:	0 on success other values mean error

rcu_powerOnFEC

Synopsis:

Activate a Front End Card

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_powerOnFEC (chan_key *ptr, int branch, int fec)

Description:

Activate the FEC at position fec in branch branch. For this operation a number of functions are called within the rcu_powerOnFEC function:

Send a (WRD_RD + 1) command
Read the AFL locally
Combine the existing AFL status with the instruction to turn on the requested FEC
Write the new data to the AFL

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`int branch`	0 for branch A, 1 for branch B
`int fec`	0 to 32
Return Value:	0 on success other values mean error

rcu_powerOffFEC

Synopsis:

Deactivate a Front End Card

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_powerOffFEC (chan_key *ptr, int branch, int fec)

Description:

Deactivate the FEC at position fec in branch branch. For this operation a number of functions are called within the rcu_powerOffFEC function:

Send a (WRD_RD + 1) command
Read the AFL locally
Combine the existing AFL status with the instruction to turn off the requested FEC
Write the new data to the AFL

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`int branch`	0 for branch A, 1 for branch B
`int fec`	0 to 32
Return Value:	0 on success other values mean error

rcu_readReg

Synopsis:

Read a register value from RCU

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_readReg (chan_key *ptr, u_long fee_add, u_long *buffer)

Description:

Read data from a RCU register fee_add into the user created *buffer.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long fee_add`	address of the register you want to read
`u_long *buffer`	Memory location to write data to
Return Value:	1 on success other values mean error

rcu_writeReg

Synopsis:

Write a value into a RCU register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_writeReg (chan_key *ptr, u_long fee_add, u_long value)

Description:

Load a value into a RCU register fee_add.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long fee_add`	address of the register you want to write
`u_long value`	value to load into a RCU register
Return Value:	0 on success other values mean error

rcu_readMem

Synopsis:

Read back the values in one memory of the RCU

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_readMem (chan_key *ptr, u_long fee_add, u_long *buffer, u_long size)

Description:

Read back size number of words from the fee_address, and copy up to size words into buffer.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long fee_add`	address of the register you want to read
`u_long *buffer`	Memory location to write data to
`u_long size`	number of words you want to read
Return Value:	number of words read on success other values mean error

rcu_writeMem

Synopsis:

Write data into a RCU memory

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_writeMem (chan_key *ptr, u_long fee_add, u_long *buffer, int size)

Description:

Write size number of words from buffer to fee_add RCU register.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long fee_add`	address of the MEMORY you want to write
`u_long *buffer`	Memory location to read data
`u_long size`	number of words you want to write
Return Value:	0 on success other values mean error

fec_readAltroReg

Synopsis:

Read data from an ALTRO register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int fec_readAltroReg (chan_key *ptr, int branch, int fec, int chip, int channel, int reg, u_long *buffer);

Description:

Read data from an ALTRO register reg on channel channel, chip number chipon front end card fec at branch branch into the user created buffer *buffer. As ALTRO registers cannot be directly manipulated this function writes to the RCU instruction memory, this function sends the command to execute and then reads the result memory of the RCU.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long *buffer`	The buffer to write the data to
`int reg`	ALTRO register address
`int channel`	ALTRO channel
`int chip`	ALTRO chip
`int fec`	0 to 32
`int branch`	0 for branch A, 1 for branch B
Return Value:	number of words (1) read on success other values mean error

fec_writeAltroReg

Synopsis:

Write data into an ALTRO register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int fec_writeAltroReg (chan_key *ptr, int bcast, int branch, int fec, int chip, int channel, int reg, int data);

Description:

Write data to the ALTRO register reg on channel channel, chip number chip on front end card fec at branch branch. As ALTRO registers cannot be directly manipulated, this function writes to the RCU instruction memory and then sends the command to execute.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`int data`	Data to be written
`int reg`	ALTRO register address
`int channel`	ALTRO channel
`int chip`	ALTRO chip
`int fec`	0 to 32
`int branch`	0 for branch A, 1 for branch B
`int bcast`	broadcast bit
Return Value:	0 on success other values mean error

fec_buildAltroReg (NEW)

Synopsis:

Function used to prepare a buffer containing the instruction to configure the ALTRO chip

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int fec_buildAltroReg (chan_key *ptr, int bcast, int branch, int fec, int chip, int channel, int reg, int data,unsigned int instruction_index,u_long *imem);

Description:

It writes data into the buffer imem on channel channel, chip number chip on front end card fec at branch branch. This function builds the buffer to be uploaded into the IMEM without writing it into that memory. It is used to prepare the full buffer and to write it later in one shot.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`int data`	Data to be written
`int reg`	ALTRO register address
`int channel`	ALTRO channel
`int chip`	ALTRO chip
`int fec`	0 to 32
`int branch`	0 for branch A, 1 for branch B
`int bcast`	broadcast bit
`unsigned int instruction_index`	instruction index (number of words in the buffer = instruction_index*2)
`u_long *imem`	buffer containing the instructions
Return Value:	0 on success other values mean error

fec_writeENDSEQ (NEW)

Synopsis:

This functiona adds to a buffer the ENDSEQ word and writes the buffer into IMEM

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int fec_endSeqIMEM (chan_key *ptr,u_long *imem,unsigned int instruction_index);

Description:

This function writes at the end of the buffer imem containing instruction_index instruction, the word ENDSEQ and it uploads the buffer into IMEM.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long *imem`	buffer
`unsigned int instruction_index`	instruction index (number of words in the buffer = instruction_index*2)
Return Value:	0 on success other values mean error

fec_execIMEM (NEW)

Synopsis:

This function executes the content of the IMEM

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int fec_execIMEM (chan_key *ptr);

Description:

This function executes the IMEM.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
Return Value:	0 on success other values mean error

fec_readBcReg

Synopsis:

Read data from a Board Controller register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int fec_readBcReg (chan_key *ptr, t branch, int fec, int reg, u_long *reg_data);

Description:

Read data from a register reg on the Board Controller on front end card fec at branch branch into the user created buffer *reg_data. As the Board Controller registers cannot be directly manipulated, this function writes to the RCU instruction memory, sends the command to execute and then reads the result memory of the RCU.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long *reg_data`	The buffer to write the data to
`int reg`	BC register address
`int fec`	0 to 32
`int branch`	0 for branch A, 1 for branch B
Return Value:	number of words (1) read on success <0 on rorc error [DDL error codes] or FEC_OFF, BAD_PARAMETER, R_NOT_OPEN_ERR, ERR_SMALL_BUFFER

fec_writeBcReg

Synopsis:

Write data to a Board Controller register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int fec_writeBcReg (chan_key *ptr, int branch, int fec, int reg, int data);

Description:

Write data from data to a register reg on the Board Controller on front end card fec at branch branch. As the Board Controller registers cannot be directly manipulated, this function writes to the RCU instruction memory and sends the command to execute.

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`int data`	The buffer to write the data to
`int reg`	BC register address
`int fec`	0 to 32
`int branch`	0 for branch A, 1 for branch B
Return Value:	0 on success <0 on rorc error [DDL error codes] or FEC_OFF, BAD_PARAMETER, R_NOT_OPEN_ERR, ERR_SMALL_BUFFER

checkSibSobSt

Synopsis:

Check the value of this particular register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int checkSibSobSt (chan_key *ptr, u_long *buffer){

Description:

Check the value of the status for the SIBSOB register

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long *buffer`	Return the value of this register (useful to check in case of error)
Return Value:	0 on success other values mean error

checkSibSobEr

Synopsis:

Check the value of this particular register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int checkSibSobSt (chan_key *ptr, u_long *buffer){

Description:

Check the value of the error for the SIBSOB register

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long *buffer`	Return the value of this register (useful to check in case of error)
Return Value:	0 on success other values mean error

rcu_Inst

Synopsis:

Execute an instruction code

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_INST(chan_key *ptr,u_long inst_code) {

Description:

Execute an instruction comand

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
`u_long inst_code`	Code of the instruction
Return Value:	0 on success other values mean error

rcu_clearCLERRREG

Synopsis:

Clear a register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_clearCLERRREG(chan_key *ptr) {

Description:

Execute a Clear Error Registers

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
Return Value:	0 on success other values mean error

rcu_clearRDRXREG

Synopsis:

Clear a register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_clearCLERRREG(chan_key *ptr) {

Description:

Execute a Clear rd_rx error register

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
Return Value:	0 on success other values mean error

rcu_clearCTRLCNT

Synopsis:

Clear a register

#include <fec2rorc_rcu.h> #include <fec2rorc_lib.h> int rcu_clearCTRLCNT(chan_key *ptr) {

Description:

Execute a execute a Clear trigger counters

Parameters:

`chan_key *ptr`	Pointer to a valid channel key
Return Value:	0 on success other values mean error

Sample Applications

Two simple standanlone applications are includes in the /date/fec package. They consist of the following files:

rcu_example.c and rcu_Makefile
feic_example.c and feic_Makefile

To compile them use the command make -f rcu_Makefile and make -f feic_Makefile.

Back to the RORC Documentation Page

FEC2RORC Version 2.1

Description of the API routines

Channel Keys

get_channel

Synopsis:

Description:

Parameters:

release_channel

Synopsis:

Description:

Parameters:

ddl_writeBlock

Synopsis:

Description:

Parameters:

ddl_readBlock

Synopsis:

Description:

Parameters:

ddl_sendCommand

Synopsis:

Description:

Parameters:

ddl_statusReadout

Synopsis:

Description:

Parameters:

RCU Specific Functionality

rcu_resetFEC

Synopsis:

Description:

Parameters:

rcu_resetRCU

Synopsis:

Description:

Parameters:

rcu_resetALL

Synopsis:

Description:

Parameters:

rcu_powerOnFEC

Synopsis:

Description:

Parameters:

rcu_powerOffFEC

Synopsis:

Description:

Parameters:

rcu_readReg

Synopsis:

Description:

Parameters:

rcu_writeReg

Synopsis:

Description:

Parameters:

rcu_readMem

Synopsis:

Description:

Parameters:

rcu_writeMem

Synopsis:

Description:

Parameters:

fec_readAltroReg

Synopsis:

Description:

Parameters:

fec_writeAltroReg

Synopsis:

Description:

Parameters:

fec_buildAltroReg (*NEW*)

Synopsis:

Description:

Parameters:

fec_writeENDSEQ (*NEW*)

Synopsis:

Description:

Parameters:

fec_buildAltroReg (NEW)

fec_writeENDSEQ (NEW)

fec_execIMEM (NEW)