CPSW: How To Update YAML Files and PV Names

Overview

There are two types of configuration files discussed in this document.  One defines the register architecture, and the other defines the register values.  In both cases YAML formatted text files are used.

For background information on defining CPSW Hierarchies with YAML, see: http://www.slac.stanford.edu/grp/lcls/controls/docs/cpsw/framework/with-at-support/README.yamlDefinition.html

In addition to register access, CPSW supports Beam Synhcronous Acquisition (BSA).

For background information on the CPSW BSA driver, see the README file in the bsaDriver EPICS module. A copy of the README file is also available here.

How to update the yaml architecture configuration in the IOC

 The YAML Architecture Configuration (YAC) is a set of text files that defines the registers supported by the hardware. It is typically delivered by the hardware engineer as a gzipped tar file containing one subdirectory.

To install a new YAC:

1. Remove the existing YAC subdirectory from ${TOP}/yaml, or arrange to use new subdirectory name.
2. Untar the YAC file under ${TOP}/yaml.
3. In the IOC startup script st.cmd, update the 1st parameter of cpswLoadYamlFile() to point to the 000TopLevel.yaml file within the YAC.
   For example, "yaml/AmcCarrierBcm_project.yaml/000TopLevel.yaml".
   Note: When YCPSWASYNConfig() is called after cpswLoadYamlFile(), the 2nd argument of YCPSWASYNConfig() – the YAML path – is ignored.

How to update the yaml defaults configuration in the IOC

The YAML Defaults Configuration (YDC) file is a single text file that defines a register initialization sequence.

Before installing a YDC file a couple of fixups are typically required.

1. Insert a new top-level hierarchy, "mmio", above "AmcCarrierCore".
2. Change the value of mmio:AmcCarrierCore:AxiVersion:ScratchPad to 0xfc067333.

Excerpt from an example YDC file with fixups applied:

# Config File Generated: 2017-03-07.13:29:59
- mmio:
  - AmcCarrierCore:
      - AxiVersion:
          - MasterReset: !<value> 0x0
          - FpgaReloadAddress: !<value> 0x00000000
          - FpgaReload: !<value> 0x0
          - FpgaReloadHalt: !<value> 0x0
          - ScratchPad: !<value> 0xfc067333

To install a new YDC file:

1. Copy the YDC file to the ${TOP}/yaml directory.
2. In in IOC startup script st.cmd, update the LOAD_FILE macro of the dbLoadRecords(dv/saveLoadConfig.db) command to point to the YDC file. For example, "LOAD_FILE=yaml/defaults_bcm.yaml".

How to add registers from firmware upgrade to map with the IOC

In order to map a CPSW register to an EPICS PV, entries in multiple configuration files are required.

1. YAML Architecture Configuration (YAC). This file is supplied by the hardware engineer, and it defines the full set of registers that can potentially be mapped.
2. Dictionary file. This text file defines the mapping from YAML register path to Asyn parameter name. The register paths in this file must appear in the YAC (above) as well.
3. Substitution files. These files generate EPICS PVs for Asyn parameters. The Asyn parameter names in these files must appear in the dictionary file (above) as well.

Instructions for updating the YAC appear earlier in this document.

The dictionary file is installed in the ${TOP}/yaml directory. In in IOC startup script st.cmd, the 8th argument of YCPSWASYNConfig() specifies the dictionary path.
For example, "yaml/bcm_01_20170313140632.dict".

Substitution files are processed by the EPICS make files. The file ${TOP}/bcmApp/Db/bcm.substitutions generates ${TOP}/db/bcm.db, and the file ${TOP}/bcmApp/Db/carrier.substitutions generates ${TOP}/db/carrier.db.

Finally, bcm.db and carrier.db are loaded by dbLoadRecords() in the IOC startup script st.cmd:

dbLoadRecords("db/bcm.db", "P=${AMC0_PREFIX}, PORT=${CPSW_PORT}, AMC=0")
dbLoadRecords("db/carrier.db", "P=${AMC_CARRIER_PREFIX}, PORT=${CPSW_PORT}")

How to update the list of BSA PVs served by the IOC