The AMC13 register set (and associated uHAL address table) is complex. This page attempts (will attempt!) to document it. The address table files are used for access to the board in software, and also used to automatically control the display and format of status information in the text "status" command in AMC13Tool2 and the HyperDAQ display in xDAQ.

Address Table Format

The master address table is kept as two CSV files, one for the T1 board and one for the T2 board. Most registers of interest are on T1. The CSV files are here in SVN. The T1 top-level table is named AMC13XG_Kxxxx.csv with the firmware versions in the name. It "includes" using the XML "module" syntax the sub-file AMCCounters.xml.

The CSV file has the following columns:

Column Name	Required?	Description
Mode	Optional	access mode ("incremental" for block-transfer capable areas)
Size	Optional	required size for block-transfer capable areas
P_Status	Optional[1]	Status uHAL parameter. Integer display priority 1=always display
P_Table	Optional[1]	Table uHAL parameter. Name of table for status display
P_Row	Optional[1]	Row uHAL parameter. Name of row in table for status display
P_Column	Optional[1]	Column uHAL parameter. Name of column in table for status display
P_Show	Optional[2]	Show uHAL parameter. "nz" to suppress zero values, "z" to suppress non-zero values (see note below)
P_Format	Optional[2]	Format uHAL parameter. "d" to force decimal base for display (default is specified by user)
P_Repeat (new)	Optional[3]	Repeat uHAL parameter. Number of times this item is repeated
P_Offset (new)	Optional[3]	Offset uHAL parameter. Offset between repeats. Default to 1 if not specified
Address	Required	Register address
LoBit	Required	Low bit for mask
HiBit	Required	High bit for mask
Permission	Required	"r", "w" or "rw"
Name	Required	Delimited hierarchical name e.g. "STATUS.AMC01.ENABLE" (see naming convention below)
Description	Required	Text description. Must be quoted with "..."

All columns beginning with "P_" are concatenated into the XML attribute "parameters" which is processed as a semicolon-delimited keyword=value list by uHAL. No special characters are permitted in these columns (only letters, numbers and "_").

For an item to appear in the status displays, the P_Status, P_Table, P_Row and P_Column must be specified. P_Table, P_Row and P_Column are sorted alphabetically. Leading digits and "_" characters should be stripped before display so that e.g. "0_" can be used to force a sort order.

The P_Status item sets the display priority. 0 is used to mark configuration registers which may be optionally displayed or not according to user preference. Positive integers 1-9 indicate various levels of detail for status values, with value 1 indicating the highest priority items which should always be displayed.

In the P_Row and P_Column fields, the sequence _n where n is a digit 1-9 results in substituting the corresponding field from the delimited id, e.g. if a field is _2 and the id is STATUS.AMC01.ERRORS then the resulting value would be AMC01.

The P_Show parameter has several possible settings:

nz	Display this value only if non-zero
z	Display this value only if zero
nzr	Display the entire row in the corresponding table only if this value is non-zero

If P_Repeat is present, it must be an integer count of the number of times this entry is to be repeated in the status display. An offset of 1 is assumed for subsequent entries unless a different address offset is specified with P_Offset. If P_Repeat is specified, either the P_Row or P_Column may have a trailing _d which will be replaced with the decimal value of the repeat counter.

There are many 64-bit counters, which have otherwise identical ids ending in _LO and _HI. These should be treated as a single 64-bit value for purposes of display, if their Table, Row and Column parameters are identical.

The csv file is converted to XML by a perl script in the above directory named csv_to_xml.pl.

Updating the Address Table

Here are the steps to make a change to the address table:

1. Check out AMC13 software package and build:

    $  svn co svn+ssh://svnuser@svn.cern.ch/reps/cactus/trunk/cactusupgrades/boards/amc13/software/amc13   
    $  cd amc13
    $  source env.sh   # or possibly .csh
    $  make            # possibly needed twice first time

      (substitute your CERN user name for svnuser)

2. Identify the file which needs to be changed. There are several "source" CSV-format files. To identify the version number currently in use see the Makefile. The following files are used:

  AMC13XG_T1_version.csv       general Kintex/Virtex registers
  AMCCounters.csv              counters for each AMC
  AMCLinks.csv                 link status for each AMC
  AMC13XG_T2_version.csv       general Spartan registers

3. Edit the file using OpenOffice/LibreOffice spreadsheet (or in an emergency carefully use a text editor):

  $ soffice FileToEdit.csv

In the "Text Import" dialog box be certain to check "Comma" in Separated by and "Quoted field as text".

Edit the file, observing carefully the parameter use as documented at the top of this page.

4. Save the file. Select "Save using CSV Format".

5. Generate new XML files by typing "make"

  $ make
  perl csv_expand_repeat.pl AMCLinks.csv temp.csv
  perl csv_to_xml.pl temp.csv ../../../amc13/etc/amc13/AMCLinks.xml
  Loaded 32 rows, 12 columns from temp.csv
  $

-- EricHazen - 28 May 2015