IOC is Born (cram init)

by Murali Shankar, with additions by An Le

August 30, 2019

Introduction

cram init is a tool used to initialize IOCs in $EPICS_IOCS and $IOC_DATA. It generates the following directories, files, and links:

In addition, it adds entries to screeniocs, cvs commits it, and cvs updates it on the destination host. Finally, an email is sent to the requester and the controls team containing all the IOCs initialized, any CPUs that do not have DHCP entries, and any SIOC that do not have auto-restart scripts.

To initialize IOCs in a single application, cd into a release directory (e.g., Magnet-R7-1-7), enter cram init and follow the instructions in the wizard that appears.

cram init --batch

A new feature of cram init is the --batch (-b) option. It creates directories and links for multiple IOCs using information from a CSV file. A similar feature (--silent) was implemented a few years ago, but it required a JSON file with the following format (see sample file):


[
 {
    "facility": "cdlx27",
    "pushCurrentRelease": "Yes",
    "IOCsToInitialize": [ "vioc-mstest-003" ],
    "iocType": "VIOC",
    "description": "This is a VIOC",
    "executable": "bin/linux-x86/mstest",
    "user": "user01",
    "CPU": "cpu01",
    "cpuDescription": "This is a CPU description",
    "screenHost": "CPUScreenHost",
    "terminalPort": "9000",
    "terminalServer": "CPUTermServ",
    "sendEmail": "No",
    "updateScreenIOCsForCPU": true
 }
]

Batch mode internally generates this data from a CSV, simplifying the process for users. To run cram init in batch mode, enter cram init -b <csvfile> -f <facility>

It is possible to make incremental changes to your CSV input and run cram init over and over again. cram init will rewrite files in $EPICS_IOCS and adjust screeniocs as necessary.

CSV file format

A sample CSV file is provided here.

Every IOC in the CSV file must be one of the following types:

The proper CSV columns and sample entries are provided below. Blank cells indicate where data should not be provided.

Name Type Description Terminal Server Port Screen Host CPU User Executable Use cexp? Application Name Application Version
cpu-bsy0-mg01 CPU A LinuxRT CPU ts-bsy0-nw01 2001 lcls-dev1 Magnet Magnet-R7-1-7
ioc-bsy0-mg01 HIOC An RTEMS IOC ts-bsy0-nw01 2002 lcls-dev1 Magnet Magnet-R7-1-7
sioc-bsy0-mg01 SIOC An SIOC on a Linux server lcls-dev1 bin/linux-x86/mgntSoft no Magnet Magnet-R7-1-7
vioc-bsy0-mg01 VIOC An SIOC on a LinuxRT CPU cpu-bsy0-mg01 laci bin/linuxRT-x86/mgntSoft yes Magnet Magnet-R7-1-7

The requirements for each IOC type are as follows:

Additional options

Testing cram init --batch

As cram init --batch is an experimental feature, it is important to test it in a sandbox environment. Here are the steps to activate cram init's test mode:

  1. Create a temporary directory containing iocCommon, iocTop, and iocData.
  2. Inside iocCommon, create a symbolic link common that points to $EPICS_IOCS/common.
  3. Inside iocCommon, create a symbolic link screenrc that points to common/screenrc.
  4. Next, copy $IOC_SCREEN/screeniocs to iocCommon.
  5. Then, in iocTop, create a symbolic link to your application (the topmost directory that contains the versions).
  6. Finally, run cram init -b csvFile -f Dev -i -T testDir where csvFile is your CSV input and testDir is your test directory.

Notes

More details

This was taken from the original proposal for cram init and modified to reflect the correct directories.


What do we need to do as part of "IOC is born" aka "cram init"?
  1. We assume that cram describe has been run and we know what kind of software package this is.
  2. First have the user pick a facility from a list of facilities.
  3. Create the release folder in the facility if it does not exist.
    • For IOCs, we create a folder in $EPICS_IOC_TOP of the facility if it does not exist.
    • For HLAs, we create a folder in $PHYSICS_TOP/release of the facility if it does not exist.
    • For tools, we create a folder in $TOOLS/script/release of the facility if it does not exist.
  4. cram push and cram ls should work at this point.
  5. If the release softlink does not exist, create a dummy release and a release softlink to the dummy release.
    • Alternatively, we can cram push the current release; this assumes that we are running cram init from a tagged release.
  6. cram upgrade should work at this point.
  7. For HLAs and tools, run the post_initialization script if any to create additional softlinks. After this step, we are done for these software package types.
  8. For IOC's, ask for the IOC's that we'd want to initialize in this facility. Use folders in iocBoot that begin with ioc/eioc/sioc/vioc to determine the list of IOC's. For each IOC chosen.
    1. If the folder $EPICS_IOCS/iocName does not exist, create it.
      1. For any directory created under $EPICS_IOCS, it also needs to be owned by $IOC_OWNER but make it writeable by the user only.
    2. If the file $EPICS_IOCS/iocName/screenrc does not exist, create it as a softlink to a template.
    3. If the file $EPICS_IOCS/iocName/startup.cmd does not exist, create it using a template.
      • These templates are to be found in ${EPICS_IOCS}/templates and depend on the type of the IOC (HIOC/SIOC/VIOC). We ask the user for the type of the IOC; the default is computed based on the prefix of the IOC.
        • ioc and eioc's default to startup.cmd.rtems
        • sioc's default to startup.cmd.soft
        • vioc's default to startup.cmd.linuxRT
    4. If the softlink $EPICS_IOCS/iocName/startup.cmd does not exist, create it.
    5. If the softlink $EPICS_IOCS/iocName/iocSpecificRelease does not exist, create it and point to the current release softlink for this package.
    6. If the folder $IOC_DATA/iocName does not exist, create it.
      1. For any directory created under $IOC_DATA, please make sure it's owned by laci or spear (owned by $IOC_OWNER) and make it writeable by all (u,g,o).
    7. If the folder $IOC_DATA/iocName/autosave does not exist, create it.
    8. If the folder $IOC_DATA/iocName/autosave-req does not exist, create it.
    9. If the folder $IOC_DATA/iocName/iocInfo does not exist, create it.
    10. If the folder $IOC_DATA/iocName/yaml does not exist, create it.
    11. Ask the user for screenioc parameters. For all of these IOC types, we also ask for a description that gets added as a comment after the screenioc spec.
      1. For HIOCs, we ask for the terminal server, port and the host where screen is run (This should have a default based on facility).
      2. For SIOCs, we ask for the executable and the server where the softIOC is run.
        • There is a possibility that we can use Garth's scheme to determine the executable automatically and avoid asking for the executable. This will be investigated.
      3. For VIOCs, we ask for the executable, user (defaults to laci) and the CPU where the VIOC is run. Create the files needed for the CPU if these are not present. Create these in $EPICS_CPUS; if this environment variable is not defined, use $EPICS_IOCS
        1. If the folder $EPICS_CPUS/cpuName does not exist, create it.
          1. For any directory created under $EPICS_CPUS, it also needs to be owned by $IOC_OWNER but make it writeable by the user only.
          2. When creating CPU directories for a VIOC, also create $IOC_DATA/cpuName for the CPU console screenlog file and $IOC_DATA/cpuName/scanner for the ethercat scanner screenlog file
        2. If the file $EPICS_CPUS/cpuName/startup.cmd does not exist, create it as a softlink to ../skel/startup_cpu.cmd
        3. If the file $EPICS_CPUS/cpuName/screenrc does not exist, create it as a softlink to a template.
        4. If the file $EPICS_CPUS/cpuName/kernel-modules.cmd does not exist, create it using a template.
        5. If the CPU does not have an entry in screenioc's, add one. We ask for the terminal server, port and the host where screen is run (This should have a default based on facility).
    12. iocConsole should work at this point for this IOC.
    13. Prepare an email for the systems group for /etc/init.d or DHCP configuration.
    14. TODO - Add button to the network EDM panel.
    15. TODO - Add ioc to IOCManager, tag, release and reboot ioc.
    16. TODO - Add ioc alarms to AlarmConfigs-ntwk tag, release reboot alarm ioc, restart alarm gui.
    17. TODO - Automate the crate and ipmi things that have to be added and the other things to set up linuxRT
    18. Archive IOC pvs from INFO tags in the db files.

References

  1. Alisha/Carolina's LinuxRT Quick Start-up For New Users