Difference between revisions of "IOC 101"

From Beam Line Controls
Jump to navigation Jump to search
 
(54 intermediate revisions by the same user not shown)
Line 14: Line 14:
=== The EPICS base approach ===
=== The EPICS base approach ===


It creates a bare bones IOC but requires more knowledge of the EPICS build system to get started:
Not recommended: it creates a bare bones IOC but requires more knowledge of the EPICS build system to get started:
::'''<code>makeBaseApp.pl</code>'''
::'''<code>makeBaseApp.pl</code>'''
* Must be run multiple times
* Must be run multiple times
* Creates IOC contents in the current directory
* Creates IOC contents in the current directory
* synApps support needs to be added manually
* synApps support needs to be added manually


=== The synApps approach ===
=== The synApps approach ===


It is based on the ''xxx'' module and designed to give you a usable IOC with as little effort as possible:
It is based on the ''xxx'' module and designed to give you a usable IOC with as little effort as possible:
:::'''<code>mkioc</code>'''
:::'''<code>/APSshare/bin/mkioc</code>'''
   
   
* A single command leaves you with an IOC you can build:
* A single command leaves you with an IOC you can build:
Line 39: Line 38:


* Creates a top-level IOC directory in the current directory
* Creates a top-level IOC directory in the current directory
* Common synApps support is included by default
* Common synApps support is included by default (common records/modules such as '''alive''', '''sscan''', '''calc'''...)
* '''<code>mkioc</code>''' will ask you questions if you run it without options
* '''<code>mkioc</code>''' will ask you questions if you run it without options


Line 53: Line 52:


The IOC layout can be overwhelming and confusing to those who aren’t yet familiar with it. The EPICS build system creates many directories, making it harder to find the important directories.
The IOC layout can be overwhelming and confusing to those who aren’t yet familiar with it. The EPICS build system creates many directories, making it harder to find the important directories.
Important files are often buried multiple directories down from the top-level. It is helpful to look at subsets of the IOC directory. <br>
Important files are often buried multiple directories down from the top-level. It is helpful to look at subsets of the IOC directory.  
 
<br>
<u>Note</u>:  
<u>Note</u>:  
* '''build''': building an IOC is the action generating the binary <code>bin/rhel#-x86_64/xxxApp</code> (plus other build products as described below) by using the command '''<code>make</code>'''.
* '''build''': building an IOC is the action of compiling i.e. generating the binary <code>bin/rhel#-x86_64/xxxApp</code> (plus other build products as described below) by using the command '''<code>make</code>'''.
* '''run''': running an IOC is the action of running the binary along with a startup script of iocsh commands (usually called '''<code>st.cmd</code>''')
* '''run''': running an IOC is the action of running the binary along with a startup script of iocsh commands (usually called '''<code>st.cmd</code>''')
<br>
<u>Note</u>:
* Any change in the build configuration ('''<span style="color: orange">Orange folders</span>''') requires to recompile the IOC by issuing a '''<code>make</code>'''.
* Any change in the runtime configuration ('''<span style="color: green">Green folders</span>''') requires to reboot the IOC.




Line 73: Line 79:
=== Intermediate build directories ===
=== Intermediate build directories ===


'''<span style="color: grey">Grey folders:</span> <br>''' The EPICS build system will generate '''<code>O.</code>''' files (Common, EPICS HOST and TARGET architectures) in the configure, Db, and src directory.  These directories are not needed after the IOC is built and can be removed with the '''<code>make clean</code>''' command. If they are not removed, they can be safely ignored.  It is highly unlikely that you will ever need to look at any of the files in them.
'''<span style="color: lightgrey">Grey folders:</span> <br>''' The EPICS build system will generate '''<code>O.</code>''' files (Common, EPICS HOST and TARGET architectures) in the configure, Db, and src directories (orange directories).  These directories are not needed after the IOC is built and can be removed with the '''<code>make clean</code>''' command. If they are not removed, they can be safely ignored.  It is highly unlikely that you will ever need to look at any of the files in them.


=== Build products ===
=== Build products ===
Line 92: Line 98:


'''<span style="color: green">Green folders:</span>'''  <br>
'''<span style="color: green">Green folders:</span>'''  <br>
The '''<code>iocxxx</code>''' directory is referred to as the '''startup''' directory.  It contains the '''<code>st.cmd</code>''' file, which is the runtime configuration for the IOC (i.e. what the IOC needs to know to start).
The '''<code>iocxxx</code>''' directory is referred to as the '''startup''' directory.  It contains the '''<code>st.cmd</code>''' file, which is the '''runtime configuration''' for the IOC (i.e. all the files the IOC needs to load to run/start).
The IOC’s config is often broken into separate '''<code>.iocsh</code>''' (or '''<code>.cmd</code>''') files so that support can be more easily commented out and to improve readability; '''<code>substitutions</code>''' and '''<code>iocsh</code>''' files usually reside in subdirectories to reduce clutter in the startup directory.
The IOC’s config is often broken into separate '''<code>.iocsh</code>''' (or '''<code>.cmd</code>''') files so that support can be more easily commented out and to improve readability; '''<code>substitutions</code>''' and '''<code>iocsh</code>''' files usually reside in subdirectories to reduce clutter in the startup directory.


Line 99: Line 105:
'''<span style="color: blue">Blue folders:</span>'''  <br>
'''<span style="color: blue">Blue folders:</span>'''  <br>
The top-level IOC directory '''<code>xxx</code>''' contains scripts that start medm & caQtDM.
The top-level IOC directory '''<code>xxx</code>''' contains scripts that start medm & caQtDM.
The <code>'''softioc'''</code> subdirectory of the startup dir contains a bash script which simplifies managing the IOC on Linux.
The startup directory <code>'''softioc'''</code> subdirectory contains a bash script which simplifies managing the IOC on Linux.
Windows IOCs: the startup directory contains batch files to start the IOC.
Windows IOCs: the startup directory contains batch files to start the IOC.


<u>Note</u>: The startup directory can reside elsewhere.
<u>Note</u>: The startup directory can reside elsewhere.


<br>
<br>
Line 115: Line 122:
** Defines the locations of EPICS base and EPICS modules
** Defines the locations of EPICS base and EPICS modules
** Often includes other RELEASE files
** Often includes other RELEASE files
** '''<u>Note</u>: already included when using <code>mkioc</code>'''
* '''<code>xxxApp/src/Makefile</code>''':
* '''<code>xxxApp/src/Makefile</code>''':
** Specifies which database definitions (dbd) to include
** Specifies which database definitions ('''<code>dbd</code>''') to include
** Specifies which libraries should be included in the IOC binary
** Specifies which libraries should be included in the IOC binary
** Specifies which local code should be included in the IOC binary
** Specifies which local code should be included in the IOC binary
** Libraries will not be included unless an associated dbd file is included
** Libraries will not be included unless an associated '''<code>dbd</code>''' file is included
** The order of the libraries is important (single-pass linker)
** The order of the libraries is important (single-pass linker)
** '''<u>Note</u>: unless you are adding a non-synApps module or an uncommon motor driver, you should not need to modify the <code>Makefile</code>'''
* '''<code>iocBoot/iocxxx/st.cmd</code>''':
* '''<code>iocBoot/iocxxx/st.cmd</code>''':
** The primary IOC config file that is sourced when the IOC is started
** That is the runtime configuration file, i.e. the primary IOC config file that is sourced when the IOC is started: determines all the things that gets loaded (e.g. ''I want 7 motor records, with these names, and this resolution, etc...'')
** Name can vary slightly based on how the IOC was created
** Name can vary slightly based on how the IOC was created
 
** '''<u>Note</u>: this is the file that you will very likely modify'''
<br><br>


=== Startup script <code>st.cmd</code> ===
=== Startup script <code>st.cmd</code> ===
Line 147: Line 157:


We can break it up into 3 functional zones:
We can break it up into 3 functional zones:
* Zone 1: before '''<code>dbLoadDatabase</code>'''. Usually this is where environment variables and paths are defined.
* '''Zone 1''' - before '''<code>dbLoadDatabase</code>''': it is usually dedicated to setting-up the environment (e.g. defines environment variables and paths to EPICS modules).
* Zone 2: after '''<code>dbLoadDatabase</code>''' & before '''<code>iocInit</code>'''. Databases can are loaded here (and can only be loaded here).
* '''Zone 2''' - after '''<code>dbLoadDatabase</code>''' & before '''<code>iocInit</code>''': this is were most of the software is loaded (e.g. databases and substitutions template are loaded here, drivers are initialized and configured).
* Zone 3: after '''<code>iocInit</code>'''.  This zone is mostly empty thanks to '''<code>doAfterIocInit</code>''' from the '''<code>std</code>''' module (sequence programs and autosave get initialized here, but the calls that do the initializing appear much earlier in the startup)
* '''Zone 3''' - after '''<code>iocInit</code>''': this zone is mostly empty thanks to '''<code>doAfterIocInit</code>''' from the '''<code>std</code>''' module (sequence programs and autosave get initialized here, but the calls that do the initializing appear much earlier in the startup)


<u>Note</u>: PVs are available during '''<code>iocInit</code>''', even though the IOC is still starting up.
<u>Note</u>: PVs are available during '''<code>iocInit</code>''', even though the IOC is still starting up.
<br><br>


=== Autosave ===
=== Autosave ===


'''<code>autosave</code>''' is a synApps module that provides seamless reboot functionality. It is mostly automatic when '''mkioc''' is used.  
'''autosave''' is a synApps module that provides seamless reboot functionality. It is mostly automatic when '''<code>mkioc</code>''' is used.  
PVs are saved while the IOC is running and loaded during '''<code>iocInit</code>'''.   
PVs are saved while the IOC is running and loaded during '''<code>iocInit</code>'''.   
Autosaved values overwrite database defaults.
Autosaved values overwrite database defaults.


Databases with associated req files ('''<code>_settings.req</code>''') are automatically added to '''<code>built_*.req</code>''' by autosaveBuild.<br>
 
[[File:IOC_autosave.jpg|right|thumb|300px]]
 
In ''xxx''-based IOCs, created using '''<code>mkioc</code>''', autosave is included by default: '''<code>common.iocsh</code>''' contains all the necessary configuration, and you will only need to modify it if you want to customize something. It also includes an '''autosaveBuild''' feature: every loaded database with associated req files ('''<code>_settings.req</code>''') are automatically added to '''<code>autosave/built_position.req</code>''' and '''<code>autosave/built_settings.req</code>''', so long as they use the correct naming convention, i.e. the '''<code>_settings.req</code>''' uses the same prefix as the database.<br>
The legacy request files, '''<code>autosave_position.req</code>''' and '''<code>autosave_settings.req</code>''' (that live outside the '''<code>autosave</code>''' directory) are reserved for things added manually (often empty).
Multiple '''<code>.sav</code>''' files can be created:
Multiple '''<code>.sav</code>''' files can be created:
* Default:
* Default:
** '''<code>.sav</code>''' & '''<code>.savB</code>'''
** '''<code>.sav</code>''' & '''<code>.savB</code>'''
** actually restored
** actually restored when the IOC restarts
* Periodic:
* Periodic:
** '''<code>.sav0</code>''', '''<code>.sav1</code>''', '''<code>.sav2</code>''', …
** '''<code>.sav0</code>''', '''<code>.sav1</code>''', '''<code>.sav2</code>''', …
** overwritten cyclically
** overwritten cyclically; if the default one do not exist, those ones get restored.
* Dated:
* Dated:
** '''<code>.sav-230109-134502</code>'''
** '''<code>.sav-230109-134502</code>'''
Line 173: Line 188:
The 1st half of '''<code>common.iocsh</code>''' sets up autosave:
The 1st half of '''<code>common.iocsh</code>''' sets up autosave:
[https://github.com/epics-modules/xxx/blob/master/iocBoot/iocxxx/common.iocsh#L1-L46 https://github.com/epics-modules/xxx/blob/master/iocBoot/iocxxx/common.iocsh#L1-L46]
[https://github.com/epics-modules/xxx/blob/master/iocBoot/iocxxx/common.iocsh#L1-L46 https://github.com/epics-modules/xxx/blob/master/iocBoot/iocxxx/common.iocsh#L1-L46]
<br><br>


=== How to build & clean a Linux IOC ===
=== How to build & clean a Linux IOC ===
Line 182: Line 198:
** bash: <code>'''export EPICS_HOST_ARCH=rhel7-x86_64'''</code>
** bash: <code>'''export EPICS_HOST_ARCH=rhel7-x86_64'''</code>
** tcsh: <code>'''setenv EPICS_HOST_ARCH rhel7-x86_64'''</code>
** tcsh: <code>'''setenv EPICS_HOST_ARCH rhel7-x86_64'''</code>
* Initiate the build in the top-level IOC directory
* Initiate the build in the top-level IOC directory:
** <code>'''make'''</code>
** <code>'''make'''</code>


* Remove intermediate build dirs (for the current <code> EPICS_HOST_ARCH</code> )
* Remove intermediate build dirs (for the current <code> EPICS_HOST_ARCH</code>):
** <code>'''make clean'''</code>  
** <code>'''make clean'''</code>  
* Remove all intermediate build dirs and top-level build directories
* Remove all intermediate build dirs and top-level build directories to start fresh:
** <code>'''make distclean'''</code>
** <code>'''make distclean'''</code>
* Show all make options
* Show all make options:
** <code>'''make help'''</code>
** <code>'''make help'''</code>


<br>
 
 
== Running an IOC ==
== Running an IOC ==
<br>
<br>
Line 279: Line 296:


See [https://wiki-ext.aps.anl.gov/blc/index.php?title=EPICS_Cheat_Sheet EPICS Cheat Sheet]
See [https://wiki-ext.aps.anl.gov/blc/index.php?title=EPICS_Cheat_Sheet EPICS Cheat Sheet]
<br>
== Where does EPICS support reside at the APS ==
<br><br>
[[File:IOC_Support.jpg|center|thumb|500px]]<br><br>
== What's next? ==
For step by step instructions to create your own IOC, go to [https://git.aps.anl.gov/practical_beamline_controls_training/session_2/instructions IOC Deployment & Troubleshooting].

Latest revision as of 22:54, 8 December 2023


What is an IOC

For a basic description, see Epics 101

EPICS basics PV diagram.png


How does one create an IOC?

There are multiple ways to create an IOC, but no one does it from scratch:


The EPICS base approach

Not recommended: it creates a bare bones IOC but requires more knowledge of the EPICS build system to get started:

makeBaseApp.pl
  • Must be run multiple times
  • Creates IOC contents in the current directory
  • synApps support needs to be added manually

The synApps approach

It is based on the xxx module and designed to give you a usable IOC with as little effort as possible:

/APSshare/bin/mkioc
  • A single command leaves you with an IOC you can build:
$/APSshare/bin/mkioc -n -f -s 6-2-1 kmp

Usage: mkioc [options] ioc_name
-h            print this message
-v            print the version
-f            create a fresh git repo without an xxx remote
-g            default to creating gitlab repo and pushing ioc
-n            default to not creating gitlab repo and pushing ioc
-s <version>  use a specific synApps version
  • Creates a top-level IOC directory in the current directory
  • Common synApps support is included by default (common records/modules such as alive, sscan, calc...)
  • mkioc will ask you questions if you run it without options

Note: The BCDA convention is to name development IOCs using the developer's initials (here we will use either xxx or kmp).


IOC Layout

Overview

The IOC layout can be overwhelming and confusing to those who aren’t yet familiar with it. The EPICS build system creates many directories, making it harder to find the important directories. Important files are often buried multiple directories down from the top-level. It is helpful to look at subsets of the IOC directory.


Note:

  • build: building an IOC is the action of compiling i.e. generating the binary bin/rhel#-x86_64/xxxApp (plus other build products as described below) by using the command make.
  • run: running an IOC is the action of running the binary along with a startup script of iocsh commands (usually called st.cmd)


Note:

  • Any change in the build configuration (Orange folders) requires to recompile the IOC by issuing a make.
  • Any change in the runtime configuration (Green folders) requires to reboot the IOC.


xxx IOC tree

Build configuration

Orange folders:

  • xxx/configure:
contains the files that specify which versions of EPICS base and EPICS modules should be used when building the IOC.
  • xxx/xxxApp/Db:
contains local databases (and associated autosave files) and protocol files used by the IOC.
  • xxx/xxxApp/src:
contains the Makefile that determines all of the software that gets built into the IOC binary. ; local sequence programs and other EPICS support that needs to be compiled go here.

Intermediate build directories

Grey folders:
The EPICS build system will generate O. files (Common, EPICS HOST and TARGET architectures) in the configure, Db, and src directories (orange directories). These directories are not needed after the IOC is built and can be removed with the make clean command. If they are not removed, they can be safely ignored. It is highly unlikely that you will ever need to look at any of the files in them.

Build products

Red folders:
The EPICS build system creates top level bin, db, dbd, and lib directories:

  • xxx/bin/rehl8-x86_64:
contains the architecture-specific IOC binary (or munch file for VxWorks IOCs).
  • xxx/db:
contains installed database files which may or may not be used, since many IOCs reference the databases in the Db directory instead.
  • xxx/dbd:
contains a single database definition file to be loaded by the IOC.
  • xxx/lib/rehl8-x86_64:
contains architecture-specific files for EPICS modules, but should be empty for the IOC.

The build system creates an envPaths file in the startup directory iocBoot/iocxxx, which contains the locations of the modules defined in the RELEASE file.

Startup directory

Green folders:
The iocxxx directory is referred to as the startup directory. It contains the st.cmd file, which is the runtime configuration for the IOC (i.e. all the files the IOC needs to load to run/start). The IOC’s config is often broken into separate .iocsh (or .cmd) files so that support can be more easily commented out and to improve readability; substitutions and iocsh files usually reside in subdirectories to reduce clutter in the startup directory.

Startup scripts

Blue folders:
The top-level IOC directory xxx contains scripts that start medm & caQtDM. The startup directory softioc subdirectory contains a bash script which simplifies managing the IOC on Linux. Windows IOCs: the startup directory contains batch files to start the IOC.

Note: The startup directory can reside elsewhere.



How does support get into an IOC?

Quick overview

EPICS basics linking diagrams.png
  • configure/RELEASE:
    • Defines the locations of EPICS base and EPICS modules
    • Often includes other RELEASE files
    • Note: already included when using mkioc
  • xxxApp/src/Makefile:
    • Specifies which database definitions (dbd) to include
    • Specifies which libraries should be included in the IOC binary
    • Specifies which local code should be included in the IOC binary
    • Libraries will not be included unless an associated dbd file is included
    • The order of the libraries is important (single-pass linker)
    • Note: unless you are adding a non-synApps module or an uncommon motor driver, you should not need to modify the Makefile
  • iocBoot/iocxxx/st.cmd:
    • That is the runtime configuration file, i.e. the primary IOC config file that is sourced when the IOC is started: determines all the things that gets loaded (e.g. I want 7 motor records, with these names, and this resolution, etc...)
    • Name can vary slightly based on how the IOC was created
    • Note: this is the file that you will very likely modify



Startup script st.cmd

Legacy IOCs often have monolithic st.cmd files. Newer IOCs source more .iocsh files from EPICS modules, which makes it easier to keep an IOC's config up-to-date.

< envPaths

dbLoadDatabase("../../dbd/iocxxxLinux.dbd")
iocxxxLinux_registerRecordDeviceDriver(pdbbase)

### Databases are loaded
### Drivers are initialized/configured here

iocInit

### Sequence programs & autosave are started here

dbl > dbl-all.txt

date

We can break it up into 3 functional zones:

  • Zone 1 - before dbLoadDatabase: it is usually dedicated to setting-up the environment (e.g. defines environment variables and paths to EPICS modules).
  • Zone 2 - after dbLoadDatabase & before iocInit: this is were most of the software is loaded (e.g. databases and substitutions template are loaded here, drivers are initialized and configured).
  • Zone 3 - after iocInit: this zone is mostly empty thanks to doAfterIocInit from the std module (sequence programs and autosave get initialized here, but the calls that do the initializing appear much earlier in the startup)

Note: PVs are available during iocInit, even though the IOC is still starting up.

Autosave

autosave is a synApps module that provides seamless reboot functionality. It is mostly automatic when mkioc is used. PVs are saved while the IOC is running and loaded during iocInit. Autosaved values overwrite database defaults.


IOC autosave.jpg

In xxx-based IOCs, created using mkioc, autosave is included by default: common.iocsh contains all the necessary configuration, and you will only need to modify it if you want to customize something. It also includes an autosaveBuild feature: every loaded database with associated req files (_settings.req) are automatically added to autosave/built_position.req and autosave/built_settings.req, so long as they use the correct naming convention, i.e. the _settings.req uses the same prefix as the database.
The legacy request files, autosave_position.req and autosave_settings.req (that live outside the autosave directory) are reserved for things added manually (often empty). Multiple .sav files can be created:

  • Default:
    • .sav & .savB
    • actually restored when the IOC restarts
  • Periodic:
    • .sav0, .sav1, .sav2, …
    • overwritten cyclically; if the default one do not exist, those ones get restored.
  • Dated:
    • .sav-230109-134502
    • written once at boot time

The 1st half of common.iocsh sets up autosave: https://github.com/epics-modules/xxx/blob/master/iocBoot/iocxxx/common.iocsh#L1-L46

How to build & clean a Linux IOC

  • Confirm the RHEL version
    • uname -r → 3.10.0-1160.62.1.el7.x86_64
    • cat /etc/redhat-release → Red Hat Enterprise Linux Server release 7.9
  • Set EPICS_HOST_ARCH environment variable
    • bash: export EPICS_HOST_ARCH=rhel7-x86_64
    • tcsh: setenv EPICS_HOST_ARCH rhel7-x86_64
  • Initiate the build in the top-level IOC directory:
    • make
  • Remove intermediate build dirs (for the current EPICS_HOST_ARCH):
    • make clean
  • Remove all intermediate build dirs and top-level build directories to start fresh:
    • make distclean
  • Show all make options:
    • make help


Running an IOC


Use the script


Create an alias

Create an alias for the script (assuming PWD = IOC’s top-level dir)

$ alias kmp=${PWD}/iocBoot/iockmp/softioc/kmp.sh
$ kmp
Usage: kmp.sh {console|restart|run|start|caqtdm|medm|status|stop|usage}

Noteworthy arguments:

  • run: Runs the IOC in the current terminal (doesn't return the command prompt). Useful for troubleshooting. Problematic for normal operation.
  • start: Runs the IOC in the background (returns the command prompt) using screen or procServ.
  • status: Tells you if the IOC is running and refuses to start if it is.

Note:

  • Use the full path to the IOC’s start script so the alias can be run from any directory (bash syntax shown).
  • EPICS_HOST_ARCH needs to still be set otherwise the IOC will not start (unless the EPICS_HOST_ARCH is hard-coded in the start script).


Start caQtDM

kmp caqtdm &

Note: the ampersand is needed for synApps_6_2_1 IOCs, but it won’t be needed in the future because it was added to the start_caQtDM_xxx script.


Start the IOC

Starts the IOC in the background (using screen or procServ):

kmp start

IOCs are usually run in screen or procServ so that:

  • the window in which they’re started can be closed
  • multiple people can connect to them
  • [procServ] allows other user accounts to restart an IOC
  • [procServ] allows users to connect to Windows IOCs


Confirm the IOC is running

kmp status
kmp is running (pid=1281733) in a screen session (pid=1281732)

Note: bugs in the deployed copy of xxx.sh may prevent it from detecting an IOC is running.


Connecting to an IOC’s shell

There are many ways to do it:

  • Manually connect to an IOC running in screen from the IOC’s host
$ screen -x kmp
The -x option will connect even if someone is already connected to the screen session.
The -r option only succeeds if no one is connected to the session.
  • Connect to an IOC running in screen or procServ from the IOC’s host
$ kmp console
  • Connect to an IOC running in screen or procServ with logging from any host
$ /APSshare/bin/iocConsole.py iockmp
Note: iocConsole.py requires ssh access which beamline accounts don't have by default
  • Manually connect to an IOC running in procServ from the IOC’s subnet
$ telnet s100bcda 53127


Disconnecting from an IOC’s shell

  • Close the terminal that is connected to the screen or procServ session
    • Disconnects from both screen & procServ
    • Kills an IOC running outside of screen & procServ
  • Ctrl+a, Ctrl+d
    • Disconnects from both screen & procServ
    • Kills an IOC running outside of screen & procServ
  • Ctrl+a, d
    • Only disconnects from screen


IOC shell commands

See EPICS Cheat Sheet


Where does EPICS support reside at the APS



IOC Support.jpg




What's next?

For step by step instructions to create your own IOC, go to IOC Deployment & Troubleshooting.