1. Definitions
  • BOLD: refers to files that need to be modified or generated by IOC developer
  • Italics: symbolic link

References  (documents need to be updated)

How-To setup the CPU and IOC boot directories

The instructions differ between production and development due to permission restrictions in production.

Production:   lcls, facet, spear, acctest

  1. Send email to Ken Brobeck requesting:
    1. Which facility the CPU will boot (e.g. facet, lcls, spear, acctest). This indicates the path to the startup.cmd  script and the DHCP server.
    2.  MAC Address of the CPU
    3. The CPU EPICS target architecture  (e.g. llinuxRT-x86, linuxRT-i686,linuxRT-x86_64,rhel7-x86_64,etc)
    4. create controls infrastructure for a new linuxRT CPU and / or IOC to a specific facility production server.
      1. includes $EPICS_IOCS/<cpu,ioc>  directories
      2. includes $IOC_DATA/<ioc>/<autosave, autosave-req, restore, iocInfo, archive, yaml>  directories
    5. add CPU boot information to the DHCP configuration file, and reboot the DHCP server. The DHCP Configuration file is at $TFTPBOOT/dhcpd.conf,   Ken, Arjun or Charlie will need the following details to update DHCP.
      • CPU Node name
      • CPU MAC Address
      • LinuxRT or Centos7

Example Development DHCP snipped

host cpu-b024-pm01 {                        
                          hardware ethernet 74:FE:48:16:3D:D5;
                          fixed-address   134.79.217.162;
                          option host-name "cpu-b024-pm01"
                          if ( substring( option vendor-class-identifier, 0, 5 ) = "udhcp" ) {
                           filename         "/afs/slac.stanford.edu/g/lcls/epics/iocCommon/cpu-b024-pm01/startup.cmd";
                           option root-path "afsnfs:/afs/slac.stanford.edu:/afs/slac.stanford.edu";
                          }
                }

  1. Proceed to Development Step #4

Development:   

  1. .  Create the $IOC_DATA directory for your cpu and iocs as follows:
    1. cd $IOC_DATA
    2. mkdir  iocInfo archive restore autosave autosave-req yaml
  2.  Create the $EPICS_IOCS cpu and ioc boot directories
      1. cd $EPICS_IOCS
      2. mkdir cpu-<area>-<subsystem-prefix><2-digit#>  
      3. mkdir  sioc-<area>-<subsystem-prefix><2-digit#>
      4. Modify your application to add the cpu boot scripts.  If your IOC runs on a Shared Platform cpu then modify the SharedPlatform IOC Application  :
        1. add  cpuBoot/<faciilty>/<cpu node>/st.cmd
        2. add any dhcp.config or ethercat xml scripts
        3. tag and push shared the SharedPlatform  tag to production  using cram.
  3. Setup DHCP Server
    1. Add cpu boot information to the DHCP configuration.   Contact Ken to update the DHCP file and provide the following information:
      • CPU Nodename
      • CPU MAC Address
      • LinuxRT or Centos7

Example LCLS DHCP snippet:

          host cpu-li10-pm01 {
                       hardware ethernet 74:FE:48:55:1D:A9;
                       fixed-address 172.27.72.103;
                       option host-name "cpu-li10-pm01";
                       if ( substring( option vendor-class-identifier, 0, 5 ) = "udhcp" ) {
                        filename "/usr/local/facet/epics/iocCommon/cpu-li10-pm01/startup.cmd";
                        option root-path "mccfs2:/export/mccfs/usr/local:/usr/local";
                        }
          }
    4.Create the <cpu>.ipxe file at:
          for LinuxRT:   $TFTPBOOT/linuxRT/boot/ipxe/<cpu>.ipxe
          for Centos7:   $TFTPBOOT/boot/ipxe/<cpu>.ipxe
             
          for 64-bit cpu:   cp example.ipxe       <cpu>.ipxe  
          for 32-bit cpu:   cp example-32bit.ipxe <cpu>.ipxe

Note: the buildroot version in the IPXE file must match the IOC Application buildroot version defined in configure/CONFIG_SITE

5.  Setup CPU  Boot directory files:

Original Method: (steps 3b and 3c)

    1. cd $EPICS_IOCS/cpu-<area>-<subsystem-prefix><2-digit#>
    2. Setup relative symbolic links to the common startup script and EPICS version:.
      • ln -s ../common/st.cmd.<type>cpu  startup.cmd            where type is soft or linuxRT
      • ln -s ../common/bin/<epics base version>  epicsSpecificRelease
    3. Generate the file kernel-module.cmd. This file load kernels modules and drivers: kernel-modules.cmd
      for examples click  here.
      New Method: (steps 3d and 3e) - must be base release R7.0.3.1-1.0 or greater
    4. Automatic:     
      • createLinuxRTCpu --help
    2. Manual:
      1. cd $EPICS_IOCS/cpu-<area>-<subsystem-prefix><2-digit#> 
      2. Setup relative symbolic like to the TOP of the IOC Application  first time only, thereafter use cram to upgrade link.
        • ln -s ../../iocTop/<app> iocSpecificRelease
        • for linuxRT:     cp ../template/startup.cmd.linuxRT.cpu.<facility>   startup.cmd
        • for centos7:    cp ../template/startup.cmd.soft.cpu.<facility>       startup.cmd 
          • replace <cpu> with your cpu name
          • replace <full path> with the full path to the boot directory in $EPICS_IOCS

         6..  Setup ioc directory files

    1. for linuxRT running iocsh:    cp ../template/startup.cmd.linuxRT           startup.cmd
    2. for  linuxRT running cexp:     cp ../template/startup.cmd.linuxRT.cexp  startup.cm
    3. for centos7:                            cp ../template/startup.cmd.soft.ioc          startup.cmd 
    4. cd sioc-<area>-<subsystem-prefix><2-digit# 
    5. copy the ioc startup.cmd script from  $EPICS_IOCS/template
    6. edit startup.cmd
      1. replace <ioc>  with your ioc name and for cexp replace <facility>
      2. change path of the EPICS_IOC_APP if your st.cmd file is in a non-standard location.
    7. cp ../template/screenrc   screenrc
    8. edit screenrc and replace <ioc> with your ioc name
    9. Setup a relative symbolic link to the TOP of the IOC Application release.
      1. ln -s ../../iocTop/<app>/<version> iocSpecificRelease

      6. Modify $EPICS_IOCS/screeniocs    – Please note that this is a symbolic link to a CVS:

    1. cd
    2. cd <work>
      cvs co epics/iocCommon/All/<facility>   , where facility is dev,prod,facet,acctest
      1. add line for cpu
        format:  cpu-<area>-<subsystem-prefix><2-digit #>      <ts>   <ts port #t>   <screen  host>   [ # comment]
      2. add line for each ioc
        format:  sioc-<area>-<subsystem prefix><2-digit #>  cpu-<area>-<subsystem-prefix><2-digit #>    <account>   [ # comment]
      3. The "comment" field in  screeeniocs  is optional and must be precede but  "#".
      4. cd epics/iocCommon/All/<facility>/screeniocs
      5. edit screeniocs
    3. verify that the file in use has not been modified without being committed.
      1. cd $EPICS_IOCS/All/<facility>   , where facility is Dev,Prod,facet,acctest
      2. cvs diff -r HEAD screeniocs
      3. if there are issues, then send email to whoever made the change or to controls-software that you are about to update this file and uncommitted edits will be lost, so please commit your changes to CVS.  If you don't get a response,  you can either add the changes to CVS in addition to yours or just add yours.
    4. check out screeniocs from CVS into your work area
    5. commit your changes of screeniocs to CVS  as follows:
      1.  cvs commit  -m "added cpu and ioc blah" screeniocs
    6. update the screeniocs file in use
      1. cd $EPICS_IOCS/All/<facility>
      2.  rm -f screeniocs
      3. cvs update screeniocs
         

 

 IOC Applications Specific  RT constraints:

  1. Create script <app>/iocBoot/<facility>/<ioc>/rtPrioritySetup.cmd to set real-time priorities for threads
  2. Load rtPrioritySetup.cmd from <app>/iocBoot/<facility>/<ioc>/st.cmd 

How-to Release a LinuxRT IOC Application:


How-to boot a linuxRT IOC from a Linux Host :

  1.  Log onto the host machine for example softegr@lcls-srv01 type the following:
    siocRestart <ioc>

How-to boot an IOC from the linuxRT host

The following scripts are located under the directory $IOC/common and should be in PATH on the CPU.

  1. siocStart.sh <ioc>   - starts a specific ioc. However, if the ioc is up nothing will be done, if no ioc is specified all iocs on cpu not already up will be started.
  2. siocStart.sh    -  starts all iocs not already running
  3. iocConsole.sh <ioc> -d   (starts the specified ioc, but does not attache to the screen session)
  4. iocConsole.sh <ioc> -R  (graceful reset)
  5. iocConsole.sh <ioc> -r  (fast restart)
  6. iocConsole.sh --help

How to connect to CPU from a Linux host:

Use either iocConsole or ssh to CPU as follows:

  1. iocConsole  <cpu>
  2. Using ssh
    • from  lcls or dev: ssh laci@<cpu>  
    • from facet: ssh flaci@<cpu

How to check if IOC is running on the linuxRT CPU:

  • from laci or flaci type:  screen -ls 
     

How-to use screen program:

  • ctrl a d : detach from the screen session
  • ctrl a [ : scroll up through the start-up messages.
  • View all vioc's on host  cpu:
    • logged in as laci  or flaci for FACET iocs
    • screen -ls  
  • Attach to vioc: screen -r <ioc>
  • Attaching to a linuxRT screen session multiple times with  "laci"concurrently:  (Note: from FACET use flaci)
    screen  -x <ioc>

  • Note: The "screen" program supports multi-display mode. When you attach an existing screen session, you can use "-x". It allows an user to attach to "a not detached screen session." The -r option allows a user to attach to a "detached screen session".


Additional References: