RCU ControlEngine
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.