LinuxRT Boot - Quick Start-up

1. 1. 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)

• Block Diagram 
• FAQ
• Setup EtherCat  
   

How-To setup the CPU and IOC boot directories

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

Production:   lcls, lcls2, facet, testfac

1. Send email to Ken Brobeck requesting:
1. 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>  directories
2. add CPU boot information to the DHCP configuration file, and reboot the DHCP server. Ken will need the following details:
1. Which facility the CPU will boot (e.g. facet, lcls, lcls2, testfac). 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. linuxRT-x86,linuxRT-x86_64,etc)
2. Proceed to Development Step #3

Development:    dev

1. Create the $IOC_DATA directory for your cpu and iocs as follows:
1. cd $IOC_DATA
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#>
3. Setup cpu directory files
   1. cd cpu-<area>-<subsystem-prefix><2-digit#>
      Original Method: (steps 3b and 3c)
   2. Setup relative symbolic links to the common startup script and EPICS version:.
      1. ln -s ../common/st.cmd.linuxRT.cpu  startup.cmd
      2. 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. Setup relative symbolic like to the TOP of the IOC Application  first time only, thereafter use cram to upgrade link.
      1. ln -s ../../iocTop/<app> iocSpecificRelease
   5.  cp ../template/startup.cmd.linuxRT.cpu startup.cmd
      1. replace <cpu> with your cpu name
      2. replace <full path> with the full path to the directory with the cpu boot st.cmd file
4. Setup ioc directory files
1. cd sioc-<area>-<subsystem-prefix><2-digit# 
2. copy the ioc startup.cmd script from  $EPICS_IOCS/templat
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. edit startup.cmd
1. 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.
2. cp ../template/screenrc   screenrc
3. edit screenrc and replace <ioc> with your ioc name
4. Setup a relative symbolic link to the TOP of the IOC Application release.

1. 1. ln -s ../../iocTop/<app>/<version> iocSpecificRelease
2. Modify $EPICS_IOCS/screeniocs    – Please note that this is a symbolic link to a CVS file
1. 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.
      
2. check out screeniocs from CVS into your work area
1. cd
2. cd <work>
   cvs co epics/iocCommon/All/<facility>   , where facility is Dev,Prod,facet,acctest
1. cd epics/iocCommon/All/<facility>/screeniocs
2. edit screeniocs
   
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  "#".
3. commit your changes of screeniocs to CVS  as follows:
   1.  cvs commit  -m "added cpu and ioc blah" screeniocs
4. 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/<ioc>/rtPrioritySetup.cmd to set real-time priorities for threads
2. Load rtPrioritySetup.cmd from <app>/iocBoot/<ioc>/st.cmd 

How-to Release a LinuxRT IOC Application:

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

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

How-to boot an IOC from the linuxRT hostT

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

1. siocStart <ioc>   - starts a specific ioc. However, if the ioc is up nothing will be done
2. siocStart    -  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:

• Additional Information on Cross-compiling EPICS Applications:
• LinuxRT Startup Script:
• How the initial boot-up process works: