RCU ControlEngine

From ift

back to: Detector Control System :: FeeServer


This page describes the ControlEngine for the TPC Readout Control Unit. The RCU is also used for the PHOS detector. Later there will be dedicated pages for each detector as well which will contain the specialities.

Building a FeeServer

Please refer to the FeeServer page for help on building a FeeServer.

Command Handling: the Issue method

The CE API provides the method 'issue' to receive commands from a DIM client. The function gets a block of data, where the first 4 bytes represent a 32 bit header specifying the type of the command. Each command has to be terminated by a 32 bit tailer, containing an and marker and the version no of the command definition.

Note:The architecture of the ARM linux is little endian, which means the least significant byte comes first.

Command header format

The general structure of the header word is:

* Bit 32 - 28 | 27 - 24 | 23 - 16 | 15 -0
*     1 1 1 1   cmd id    sub id    parameter
*                                      ^------- 16 bit user parameter passed to the handler function
*                            ^-----------------  8 bit command sub id passed to the handler function
*                   ^--------------------------  4 bit command id switches to the handler function
*        ^-------------------------------------  4 bit code for FeeServer command

A FeeServer command always starts with 0xf in Bit 27 to 32. Everything else is interpreted as encoded in the Message Buffer Format. Bit 24 to 27 represent the command id. The sub id and the parameter are specific for each command group. So far the following command groups exist:

  • 0x1: Control Engine Commands
  • 0x2: Msg Buffer Interface Commands
  • 0x3: RCU access commands
  • 0x4: Command set for the RCU configuration
  • 0x5: Setting of values to data point in the Front-end electronics
  • 0x6: Data readout
  • 0x7: Shell command execution
  • 0xa: TPC commands
  • 0xb: PHOS commands

The global command scanning is handled by the function

/*******************************************************************************************
 * global switch to the corresponding handlers
 */
int translateCommand(char* buffer, int size)

The function is a switch to the specific handler functions, it extracts command id and the parameter from the header. The treatment of the parameter is up to the specific command.

The Message Buffer Format

The Message Buffer Interface is a memory mapped interface for the communication between DCSboard and RCU. The FeeServer treats all command blocks with Bits 28 to 31 of the Header word different from 0xf as encoded in the Message Buffer format and transferes them directly to the interface.

Message Buffer Interface specifications

Control Engine commands

/*******************************************************************************************
 * the commands concerning and explicitly handled by the CE 
 */
int translateCeCommand(__u32 cmd, __u32 parameter, const char* pData, int iDataSize)

The following ids are defined in rcu_issue.h

FEESERVER_CE_CMD  (0x01000000 | FEESERVER_CMD)


Command Name Command Code Description Parameter # words in data buffer
CEDBG_SET_BUF_PRINT_SIZE 0xf1010000 set the maximum size for the command buffer debug print, default 0 the maximum number of bytes for printout 0
CEDBG_USE_SINGLE_WRITE 0xf1020000 use single write/read for rcu memory writing 0 = off, 1 = on 0
CEDBG_EN_SERVICE_UPDATE 0xf1030000 turn on/off the update of the services 0 = off, 1 = on
CEDBG_SET_SERVICE_DATA 0xf1040000 set the data of a service bit 0-7 service no; bit 8-12 FEC no; bit 13=1 rcu register (FEC no not valid); parameter: 0x0 off, 0xffff all on, 0x<bitfield> selection on 0
CE_READ_DEFAULT_SERVICES 0xf1050000 returns a list of all possible services 0
CE_READ_VALID_FECS 0xf1060000 returns a list of the valid Frontend cards 0
CE_RELAX_CMD_VERS_CHECK 0xf1070000 relax the version checking for commands 0 = off, 1 = on 0


Message Buffer Interface commands

/*******************************************************************************************
 * the commands concerning the message buffer access library
 */
int translateDcscCommand(__u32 cmd, __u32 parameter, const char* pData, int iDataSize) {

The following ids are defined in rcu_issue.h

FEESVR_DCSC_CMD    (0x02000000 | FEESERVER_CMD)


Command Name Command Code Description Parameter # words in data buffer
DCSC_SET_OPTION_FLAG 0xf210000 set a debug option flag of the dcscRCUaccess library bitpattern, each bit=1 corresponds to an option flag to be set 0
DCSC_CLEAR_OPTION_FLAG 0xf220000 clear a debug option flag of the dcscRCUaccess library bitpattern, each bit=1 corresponds to an option flag to be cleared 0


RCU commands

Per default the RCU functionality is enabled. It can be disabled by the --enable-rcu=no option during package configuration.

int translateRcuCommand(__u32 cmd, __u32 parameter, const char* pData, int iDataSize) {

The following ids are defined in rcu_issue.h

FEESVR_CMD_RCU    (0x03000000 | FEESERVER_CMD)


Command Name Command Code Description Parameter Payload
RCU_EXEC 0xf3010000 send the execution command to run the sequence written to rcu instruction memory ignored 0
RCU_STOP_EXEC 0xf3020000 stop the execution ignored 0
RCU_WRITE_INSTRUCTION 0xf3030000 write to rcu instruction memory number of 32 bit words 32 bit data, count specified by parameter
RCU_EXEC_INSTRUCTION 0xf3040000 write to rcu instruction memory and send the execution command number of 32 bit words 32 bit data, count specified by parameter
RCU_WRITE_PATTERN8 0xf3050000 write 8 bit data to rcu pattern memory number of 8 bit words (parameter + 3)/4 (data block has to be aligned to 4)
RCU_WRITE_PATTERN16 0xf3060000 write 16 bit data to rcu pattern memory number of 16 bit words (parameter + 1)/2 (data block has to be aligned to 4)
RCU_WRITE_PATTERN32 0xf3070000 write 32 bit data to rcu pattern memory number of 32 bit words 32 bit data, count specified by parameter
RCU_WRITE_PATTERN10 0xf3080000 write 10 bit compressed data to rcu pattern memory, each 32-bit word of the data block contains 3 10-bit words number of 10 bit words (parameter + 2)/3 (data block has to be aligned to 4)
RCU_READ_INSTRUCTION 0xf3090000 read from rcu instruction memory number of 32-bit words to read 0
RCU_READ_PATTERN 0xf30a0000 read from rcu pattern memory number of 32-bit words to read 0
RCU_READ_MEMORY 0xf30b0000 read from rcu memory location address in the RCU memory space 0
RCU_WRITE_MEMORY 0xf30c0000 write to rcu memory location address in the RCU memory space one 32 bit word
RCU_WRITE_RESULT 0xf30d0000 write to rcu result memory number of 32-bit words to write 32 bit data, count specified by parameter
RCU_READ_RESULT 0xf30e0000 read from rcu result memory number of 32-bit words to read 0
RCU_WRITE_MEMBLOCK 0xf3100000 write to rcu memory - the first word specifies the address, data words are following number of 32-bit words to write one 32 bit address followd by 32 bit data, count specified by parameter
RCU_READ_MEMBLOCK 0xf3110000 read from rcu memory - the word in the data block is treated as address in RCU memory space number of 32-bit words to read one 32 bit address

Command set for the RCU configuration

This command set is intended to steer the firmware update and configuration for the RCU. So far not implemented.

FEESVR_CMD_RCUCONF  (0x04000000 | FEESERVER_CMD)


Command Name Command Code Description Parameter # words in data buffer
RCU_WRITE_FPGA_CONF 0xf4010000 write a configuration to the RCU FPGA 0
RCU_READ_FPGA_CONF 0xf4020000 read the configuration of the RCU FPGA 0
RCU_WRITE_FLASH 0xf4030000 write a file to the Flash 0
RCU_READ_FLASH 0xf4040000 write a file to the Flash 0


Setting of data points of the Front-end electronics

Set the data for a corresponding service, the handler function has to be specified during the registration of the service. The payload is expected to be a 8, 16, or 32 bit value followed by the name of the corresponding service. The length of the string is specified as parameter in the lower 16 bit of the command header. Currently, the command block must be aligned to 4, add some NULL bytes to the name string to comply with that rule.

FEESVR_SET_FERO_DATA  (0x05000000 | FEESERVER_CMD)


Command Name Command Code Description Parameter # words in data buffer
FEESVR_SET_FERO_DATA8 0xf5010000 set 8 bit value to data point length of zero terminated service name (1+parameter + 3)/4
FEESVR_SET_FERO_DATA16 0xf5020000 set 16 bit value to data point length of zero terminated service name (2+parameter + 3)/4
FEESVR_SET_FERO_DATA32 0xf5030000 set 16 bit value to data point length of zero terminated service name (4+parameter + 3)/4
FEESVR_SET_FERO_DFLOAT 0xf5040000 set float value to data point length of zero terminated service name (8+parameter + 3)/4

Data readout from the rcu data buffer

This provides a low rate access to the events in the RC data buffer.

FEESVR_CMD_DATA_RO    (0x06000000 | FEESERVER_CMD)
                                                                                                                                                                                                    

shell command execution

This group of commands allows the execution of shell commands on the DCS board. The parameter, the lower 16 bit, gives the size of that command buffer in BYTE

FEESVR_CMD_SHELL    (0x07000000 | FEESERVER_CMD)


Command Name Command Code Description Parameter # words in data buffer
FEESRV_EXECUTE_PGM 0xf7010000 execute a script/program on the DSC board the remaining data is interpreted as a char string containing shell command and arguments
FEESRV_EXECUTE_SCRIPT 0xf7020000 send a script down ans execute it the remaining data is interpreted as a char buffer containing the script
FEESRV_BINARY_PGM 0xf7030000 send a binary program to the DCS board and execute it the remaining data is interpreted as a char buffer which contains the binary program
FEESRV_RCUSH_SCRIPT 0xf7040000 send a script down and execute it with rcu-sh the remaining data is interpreted as a char buffer which contains the script


TPC commands

So far there are no specific commands for the TPC electronics. Everything is covered by the RCU functionality. A function call is forseen. The support has to be enabled by the configure option - -enable-tpc. Internally this is translated to the define TPC. All code has to be encapsulated by

#ifdef TPC 
...
#endif 

Files: ce_tpc.c, ce_tpc.h

int translateTpcCommand(__u32 cmd, __u32 parameter, const char* pData, int iDataSize) {


PHOS commands

The support has to be enabled by the configure option - -enable-phos. Internally this is translated to the define PHOS. All code has to be encapsulated by

#ifdef PHOS 
...
#endif 

Files: ce_phos.c, ce_phos.h
Specific commands for the PHOS detector are handled by the function:

int translatePhosCommand(__u32 cmd, __u32 parameter, const char* pData, int iDataSize) {

Command tailer

The upper two byte contain a 16 bit end marker (0xdd33) and the lower two byte a version number.

#define CE_CMD_EM_MASK   0xffff0000
#define CE_CMD_VS_MASK   0x0000ffff
#define CE_CMD_VERSION   0x0001
#define CE_CMD_ENDMARKER 0xdd330000
#define CE_CMD_TAILER    (CE_CMD_ENDMARKER | CE_CMD_VERSION)

Services

The default configuration of the RCU ControlEngine contains both services which publish data points of the FEC's and services for data points of the RCU, e.g. the Active Front-end card List. All services are published at startup. The configuration of FEC's is determined by the FEESERVER_FEC_MONITOR environment variable. The variable must be set appropriate to publish any data from FEC's. It contains a string of 0 and 1 describing subsequently the status of FEC's starting from no 1. Missing digits at the end are treated as 0. E.g. the following configuration enables the control of FEC #2 and #5

export FEESERVER_FEC_MONITOR=01001

Services without a link to the data point are set to -2000. This happens if a Front-end card is included into the CE but not active.

Service channels have always the type float. Even bitfields or hexadecimal numbers are sent as that type.


RCU data points

The complete list is still going to be defined.

Default configuration Name Description Deadband Bitwidth Type Implemented
on RCU_AFL active Front-end card list 0.5 32 hex --
on RCU_ERRST status and error 0.5 32 hex --
on RCU_TRCFG trigger configuration and status 0.5 32 hex --
on RCU_CNT trigger count 0.5 32 hex --
on RCU_RDO Read-out list 0.5 32 hex --


FEC data points

The following table shows the services which are published by default for one Front-end card. Each data point is identified by a unique name and can provide two functionalities:

  • publishing of data point via a DIM service channel, for that purpose an update method has to be implemented which can access the hardware.
  • set data point via the Command FEESVR_SET_FERO_DATA, the set method has to be implemented to access the hardware.

The environment variable FEESERVER_SRV_ENABLE is forseen to override the standard selection of service channels. The default configuration is given in the table. The variable can contain a comma separated list of service names.


Default configuration Name Description Deadband Bitwidth Conversion factor Unit Implemented
on T_TH temperature threshold 0.5 10 0.25 oC v0.2
on AC_TH analog current threshold 0.5 10 0.017 A v0.2
on AV_TH analog voltage threshold 0.5 10 0.0043 V v0.2
on DV_TH digital voltage threshold 0.5 10 0.0043 V v0.2
on DC_TH digital current threshold 0.5 10 0.03 A v0.2
on TEMP temperature 0.5 10 0.25 oC v0.2
on AV analog voltage 0.5 10 0.0043 V v0.2
on AC analog current 0.5 10 0.017 A v0.2
on DV digital voltage 0.5 10 0.0043 V v0.2
on DC digital current 0.5 10 0.03 A v0.2
off L1CNT level 1 trigger count 0.5 16 1.0 v0.2
off L2CNT level 2 trigger count 0.5 16 1.0 v0.2
off SCLKCNT 0.5 16 1.0 v0.2
off DSTBCNT 0.5 8 1.0 v0.2
off TSMWORD 0.5 9 1.0 v0.2
off USRATIO 0.5 16 1.0 v0.2
off CSR0 BC control & status register 0 0.5 11 1.0 v0.2
off CSR1 BC control & status register 1 0.5 14 1.0 v0.2
off CSR2 BC control & status register 2 0.5 16 1.0 v0.2
off CSR3 BC control & status register 3 0.5 16 1.0 v0.2

States

The CE exports the following state channels:

  • one channel CE state: CE_STATE
  • one channel RCU state: RCU_STATE
  • one channel for each valid FEC: FECxx_STATE

States of the RCU

Name Code Description
RCU_OFF 1 RCU is off
RCU_START 2 RCU has been switched on
RCU_RAMP_DOWN 3 ramping down
RCU_CONF-WAITING 10 the RCU could not configure automatically after power on and there is no configuration file on the DCS board avaiable -> waiting for configuration
RCU_CONFIGURING 11 the configuration is in progress
RCU_CONFIGURED 12 RCU is configured, after the RCU_CONFIGURING state the CE switches to state RCU_CONFIGURED and tries to connect to the RCU
RCU_NOT_ACCESSIBLE 20 configuration was finished but access could not be established
RCU_RUNNING 100 RCU is running
RCU_CORRUPTED 200 RCU corrupted; this state can have several reasons: the CE encounters some strange behaviour of the RCU and checks the configuration; the configuration watchdog encounters a configuration missmatch, the scrubbing process on the RCU encounters a non repairable malfunction

Note: The states are currently under discussion

States of FEC's

Name Code Description
FEC_UNDEFINED 1 FEC is invalid
FEC_OFF 2 FEC is off
FEC_START 3 FEC has been switched on
FEC_RAMP_DOWN 4 ramping down
FEC_CONF-WAITING 10 waiting for configuration
FEC_CONFIGURING 11 configuration in progress
FEC_CONFIGURED 12 FEC is configured
FEC_NOT_ACCESSIBLE 20 not accessable
FEC_RUNNING 100 FEC is running
FEC_CORRUPTED 200 FEC corrupted
FEC_FAIL 201 FEC failure reported from MSM
FEC_FATAL 202 FEC fatal failure reported from MSM

Note: The states are currently under discussion

The Actel software device in the FeeServer CE

The Actel softwaredevice has the task to control and monitor the operation of the Actel FPGA on the RCU. For more information visit the The Actel software device in the FeeServer CE page.

DCS Download