View source for DCS board tools

[[Category:DCS]]
[[Detector Control System (DCS) for ALICE Front-end electronics | Detector Control System]]

== Overview ==
This sections covers the DCS board software for the TPC-like detectors (so far TPC, PHOS, most likely FMD and EMCAL). Apart from the mentioned FeeServer there are some low level tools and interfaces. In fact, the FeeServer uses them.


[[Image:DCSboard software components.png|thumb|none|600px|DCS board Software Components]] 


The DCS board communicates via two interfaces to the RCU board:
# The Message Buffer Interface: used for most of the data tranfer between software and memory on the RCU
# The Direct Bus Access: programming of RCU Flash Memory and FPGA Configuration Memory

A driver (rcubus_driver) provides the access to the interfaces via the following devices.
A C-interface (RCU interface) implements basic functionality for the Message Buffer Interface. It is used by both the RCU shell (low level tool) and the FeeServer

== Access to the RCU ==
The figure illustrates the the available hardware interfaces: Message Buffer Interface and Direct Bus Access.

[[Image:DCSboard-RCU interface.png|frame|none|Hardware interfaces between DCS board and RCU]]

The data flow is controlled by lines in the Control Register:
* Bit 7		Start Command
* Bit 6		MIB multiplexer, read enable 
* Bit 0		Ready
* Bit 5		Direct mode select

The idea behind the Message Buffer Interface:
* the interface moves some of the complexity to the firmware
* decouples cpu from the communication task
* block by block transfer
* 2 Buffers for communication and one Control Register
** Message Input Buffer (MIB)
** Message Result Buffer (MRB)
** Control Register
* basic sequence from software view
** write command sequence to MIB
** set 'execute' flag
** wait for the 'ready' flag
** read result and status

In Direct Bus Access mode the driver (or a specific subdriver) takes control over the bus lines.

== RCU bus driver ==
The following devices are available resp. are planned to be that: 
*/dev/rcu/msgbuf	message buffer interface
*/dev/rcu/fpga		fpga configuration (under development)
*/dev/rcu/flash		general flash memory access (under development)
*/dev/rcu/flash0	flash memory bank 0 (under development)
*/dev/rcu/flash1	flash memory bank 1 (under development)
*/dev/rcu/flash2	flash memory bank 2 (under development)
*/dev/rcu/flash3	flash memory bank 3 (under development)

== Message Buffer access (RCU interface) ==
The Message Buffer interface is a memory mapped interface. A certain command sequence has to be written to the Message Input Buffer (MIB).

A command sequence constists of a 32-bit '''header word''', the command words and a 32-bit '''marker word''' which terminates one ''sequence block''. Several ''sequence blocks'' can be grouped and are finally terminated by the '''End marker word'''. The structure is outlined in the following figure.

[[Image:MsgBufferFormat.png|frame|none|Format of the Message Buffer input]]


=== Command ids ===
* Bit 5-0 of the header word

{| border="1" cellpadding="5" cellspacing="0"
|-
! style="background:#ffdead;" | Command Name
! style="background:#ffdead;" | Command Code
! style="background:#ffdead;" | Description
! style="background:#ffdead;" | Command words
! style="background:#ffdead;" | # command words

|-
| align="center" valign="top" | SINGLE_READ
| valign="top" | 0x1
| valign="top" | a single read operation
| align="center" |
{| border="1" style="width:100px"
|address
|}
| valign="top" | 1

|-
| align="center"  valign="top" | SINGLE_WRITE
| valign="top" | 0x2
| valign="top" | a single write operation
| align="center" |
{| border="1" style="width:100px"
|address
|-
|data
|}
| valign="top" | 2

|-
| align="center"  valign="top" | MULTI_READ
| valign="top" | 0x3
| valign="top" | block read operation <br> The ''count'' parameter indicates the number of words of a certain format <br>(see [[DCS_board_tools#Control_bits_and_block_number | control bits]])
| align="center" |
{| border="1" style="width:100px"
|address
|-
|count
|}
| valign="top" | 2

|-
| align="center"  valign="top" | MULT_WRITE
| valign="top" | 0x4
| valign="top" | block write operation <br> The ''count'' parameter indicates the number of words of a certain format <br>(see [[DCS_board_tools#Control_bits_and_block_number | control bits]])
| align="center" |
{| border="1" style="width:100px"
|address
|-
|count
|-
|data #1
|-
|  ...
|-
|data #n
|}
| valign="top" | 2 + # data words

|-
| align="center"  valign="top" | RANDOM_READ
| valign="top" | 0x5
| valign="top" | random read operation
| align="center" |
{| border="1" style="width:100px"
|address #1
|-
|address #2
|-
|  ...
|-
|address #n
|}
| valign="top" | number of addresses

|-
| align="center"  valign="top" | RANDOM_WRITE
| valign="top" | 0x6
| valign="top" | random write operation
| align="center" |
{| border="1" style="width:100px"
|address #1
|-
|data #1
|-
|address #2
|-
|data #2
|-
|  ...
|-
|address #n
|-
|data #n
|}
| valign="top" | 2 x number of addresses

|-
| align="center"  valign="top" | FLASH_ERASEALL
| valign="top" | 0x21
| valign="top" | erase the flash completely
| align="center" |
{| border="1" style="width:100px"
|}
| valign="top" | 0


|-
| align="center"  valign="top" | FLASH_ERASE_SEC
| valign="top" | 0x22
| valign="top" | erase one sector of the flash
| align="center" |
{| border="1" style="width:100px"
|address
|}
| valign="top" | 1


|-
| align="center"  valign="top" | FLASH_MULTI_ERASE
| valign="top" | 0x24
| valign="top" | erase multiple sectors of the flash
| align="center" |
{| border="1" style="width:100px"
|address
|-
|count
|}
| valign="top" | 2


|-
| align="center"  valign="top" | FLASH_READID
| valign="top" | 0x28
| valign="top" | read the ID of the flash <br> 0 = Manufacturer ID / 1 = Device ID
| align="center" |
{| border="1" style="width:100px"
|'0' or '1'
|}
| valign="top" | 1

|-
| align="center"  valign="top" | FLASH_RESET
| valign="top" | 0x30
| valign="top" | reset the flash
| align="center" |
{| border="1" style="width:100px"
|}
| valign="top" | 0

|}

=== Word count ===
* Bit 15-6 of the header word <br> must contain the number of words between the '''Header''' end the '''Marker'''.

=== Block number ===
* Bit 23-16 of the header word <br> number of the current ''sequence block'' <br> The first block has number '''n-1''', the block number is decremented for the following blocks. The last block has block no '''0'''. If there is only one ''sequence block'', the block no bits are just zero.  

=== Control bits and block number ===
* Bits 25-24 Data Format

{| border="1" cellpadding="5" cellspacing="0"
|-
! style="background:#ffdead;" | 25 - 25
! style="background:#ffdead;" | Description
! style="background:#ffdead;" | Data Format

|-
| align="center" valign="top" | 0 0
| valign="top" | no compression
| align="center" |
{| border="1" style="width:400px"
| style="border:0px" align="left" | 31
| style="border:0px" align="right" | 0
|-
| colspan=2 align="center" | address 
|}

|-
| align="center" valign="top" | 0 1
| valign="top" | 2 x 16 bit words
| align="center" |
{| border="1" style="width:400px"
| style="border:0px" align="left" | 31 
| style="border:0px" align="right" | 16 
| style="border:0px" align="left" | 15 
| style="border:0px" align="right" | 0
|-
| colspan=2 align="center" | address + 1 
| colspan=2 align="center" | address
|}

|-
| align="center" valign="top" | 1 0
| valign="top" | 3 x 10 bit words
| align="center" |
{| border="1" style="width:400px"
| style="border:0px" align="left" | 29
| style="border:0px" align="right" | 20
| style="border:0px" align="left" | 19
| style="border:0px" align="right" | 10
| style="border:0px" align="left" | 9
| style="border:0px" align="right" | 0
|-
| colspan=2 align="center" | address + 2
| colspan=2 align="center" | address + 1
| colspan=2 align="center" | address
|}

|-
| align="center" valign="top" | 1 1
| valign="top" | 4 x 8 bit words
| align="center" |
{| border="1" style="width:400px"
| style="border:0px" align="left" | 31
| style="border:0px" align="right" | 24
| style="border:0px" align="left" | 23
| style="border:0px" align="right" | 16
| style="border:0px" align="left" | 15
| style="border:0px" align="right" | 8
| style="border:0px" align="left" | 7
| style="border:0px" align="right" | 0
|-
| colspan=2 align="center" | address + 3 
| colspan=2 align="center" | address + 2
| colspan=2 align="center" | address + 1
| colspan=2 align="center" | address
|}
|}

=== Version ===
* Bit 31 - 28 of header word <br> version of Message Buffer specification

{| border="1" cellpadding="5" cellspacing="0"
|-
! style="background:#ffdead;" | 31 - 28
! style="background:#ffdead;" | 

|-
| align="center" valign="top" | 0 x x x
| version 1 (bit 31==0, other bits arbitrary)
|-
| align="center" valign="top" | 1 0 1 0
| version 2
|-
| align="center" valign="top" | 1 0 1 1
| version 2.2
|-
| align="center" valign="top" | 1 1 1 1
| FeeServer command (used outside the message buffer interface)
|}

=== Result Format ===

{| border="1" cellpadding="5" cellspacing="0"

|-
! style="background:#ffdead;" | Word #
! style="background:#ffdead;" | Description


|-
| align="center" valign="top" | 1
| align="center" |
{| border="1" style="width:400px"
| style="border:0px" align="left" | 31 
| style="border:0px" align="right" | 16 
| style="border:0px" align="left" | 15 
| style="border:0px" align="right" | 0
|-
| colspan=2 align="center" | 
| colspan=2 align="center" | Number of words
|-
| style="border:0px" colspan=4 align="center" valign="top" | Information Word
|}


|-
| align="center" valign="top" | 2
| align="center" |
{| border="1" style="width:400px"
| style="border:0px" align="left" | 31
| style="border:0px" align="right" | 0
|-
| colspan=2 align="center" | Status word
|}

|-
| align="center" valign="top" | 3 - n
| align="center" |
{| border="1" style="width:400px"
| style="border:0px" align="left" | 31
| style="border:0px" align="right" | 0
|-
| colspan=2 align="center" | Data
|}

|}

<pre>
Status word:
0 - if no error
Bit 15 set if any error

Bit 0: missing marker
Bit 1: missing end marker
Bit 2: no target answer (something wrong with the RCU or not connected)
Bit 3: no bus grant (no access to the bus on dcs board)
Bit 5: old message buffer format (prior to v2 with rcu-sh version v1.0)
</pre>

=== Examples ===

==== Single read ====

from address 0x7000

{| border="1" cellpadding="5" cellspacing="0"
| 0xA0000041	|| Information word
|-
| 0x00007000	|| address 0x7000
|-
| 0xAA550000	|| Block marker without Checksum
|-
| 0xDD330000	|| End marker
|}

==== Multiple write ====

4 words starting at address 0x6800 

{| border="1" cellpadding="5" cellspacing="0"
|-
| 0xA0000184 || Information word
|-
| 0x00006800 || address 0x6800
|-
| 0x00000004 || 4 words to write
|-
| 0x0000AFFE || data word 1
|-
| 0x0000D00F || data word 2
|-
| 0x00001234 || data word 3
|-
| 0x00005678 || data word 4
|-
| 0xAA550000 || Block marker without Checksum
|-
| 0xDD330000 || End marker
|}

==== Multiple write with 3x10 bit compress ====

3x3 10bit words starting at address 0x7000 and finishing at 0x7008

{| border="1" cellpadding="5" cellspacing="0"
|-
| 0xA2000144 || Information word
|-
| 0x00007000 || address 0x6800
|-
| 0x00000003 || 4 words to write
|-
| 0x2A995566 || data word 1
|-
| 0x1EADBEEF || data word 2
|-
| 0x01020202 || data word 3
|-
| 0xAA550000 || Block marker without Checksum
|-
| 0xDD330000 || End marker
|}



==== Flash Erase all ====

Erasing the complete content on the RCU Flash Memory

{| border="1" cellpadding="5" cellspacing="0"
|-
| 0xA4000021 || Information word
|-
| 0xAA550000 || Block marker without Checksum
|-
| 0xDD330000 || End marker
|}

==== Flash Erase Multiple Sectors ====

Erasing multiple subsequent sectors on the RCU Flash Memory

{| border="1" cellpadding="5" cellspacing="0"
|-
| 0xA40000E4 || Information word 
|-
| 0x003E8000 || Address of first sector (Word Address)
|-
| 0x00000004 || Number of sectors to Erase
|-
| 0xAA550000 || Block marker without Checksum
|-
| 0xDD330000 || End marker
|}

== RCU shell ==
The RCU Shell is a small command-line software for communcating with the firmware on the RCU motherboard. It is started by simply typing 'rcu-sh' at the command-line. This will bring you to the shell mode, where different types of commands can be executed.<br>

The RCU motherboard can be operated in three different modes. 
# Memory mapped mode
# Selectmap mode
# Flash mode

The default mode is memorymapped mode, which gives you direct memory access of the registers in the FPGAs on the RCU motherboard. <br>

Flash mode gives the dcs board direct control of the flash memory on the RCU motherboard, while selectmap mode gives the dcs board direct control over the selectmap interface of the Xilinx Virtex-II on the RCU motherboard. 


=== Memory mapped mode ===


=== Selectmap mode ===
The Selectmap mode is enabled by typing:
 enter operation (h/i/q/r/w): selectmap enable
or
 enter operation (h/i/q/r/w): sm e

The following options is available:
1. Get help on commands:
 sm help

2. write to single address via the selectmap interface:
 sm w 0x[address] 0x[data]

3. read from single address via the selectmap interface:
 sm r 0x[address]

4. Abort ongoing operation on the Xilinx FPGA:
 sm abort

=== Flash mode ===


The flash mode is enabled by typing:<br>

 enter operation (h/i/q/r/w): flash enable

The following options is available: <br>
1. Get help on commands: 
 flash help
2. Write to single address in flash: 
 flash write 0x[address] 0x[data] [num]
 num = number of sequental addresses to write the given data to
3. Write a file from a start address in the flash: 
 flash write [-s] 0x[address] file [size]
 -s = byteswap enabled
 size = number of 16 bit words to write to the flash from beginning of file.
4. Erase complete flash:
 flash erase all
5. Erase sector:
 flash erase sec 0x[sector address]
6. Read single address from flash:
 flash read 0x[address] [num]
 num = number of sequental address to read from the given address. 
7 Verify content of the flash memory:
 flash verify 0x[address] file
 Verifies that the content of the flash from the given address matches the content of the given file.

== Connection to FeeServer ==

[[Image:DCSboard TPC-ControlEngine connection.png|frame|none|Connection of the FeeServer Control Engine (TPC version) to the Hardware interfaces]]