Skip to content

Commit a425688

Browse files
gilesknapgilesknap
committed
add autosave explanation
1 parent cc5c84d commit a425688

File tree

1 file changed

+117
-0
lines changed

1 file changed

+117
-0
lines changed

‎docs/explanations/autosave.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Autosave for IOCs
2+
3+
## Introduction
4+
5+
Autosave saves the state of an IOC to disk and restores it on restarts. epics-containers manages autosave configuration in a prescriptive fashion that is discussed here.
6+
7+
The official autosave documentation in [here](https://epics.anl.gov/bcda/synApps/autosave/autoSaveRestore_R5-6-1.html).
8+
9+
Different facilities have used different approaches to configuring autosave. epics-containers has settled on using `.req` files. These files simply list the set of PVs to save with autosave. The naming convention for these files is the same as that which the AreaDetector modules have adopted. EPICS Db info tags were also considered but rejected because supplying overrides to them would be problematic.
10+
11+
Because of this, AreaDetector Support modules can use autosave in epics-containers without any additional configuration (unless you disagree with the default choice of saved PVs). Many other support modules have adopted the same approach and will just work.
12+
13+
Other support modules can have their autosave configuration specified in ibek-support or in individual IOC instances.
14+
15+
## Configuring autosave for IOCs
16+
17+
To use autosave, the generic IOC being used must have compiled in the autosave module. The following snippet in the `Dockerfile` will do this:
18+
19+
```Dockerfile
20+
COPY ibek-support/autosave/ autosave
21+
RUN ansible.sh autosave
22+
```
23+
24+
To enable autosave in an IOC instance that uses the above generic IOC requires adding the following to the ioc.yaml instance configuration (our examples are for the motion IOC BL45P-MO-IOC-01):
25+
26+
```yaml
27+
- type: autosave.Autosave
28+
P: BL47P-MO-IOC-01 # a prefix for all autosave monitoring PVs
29+
```
30+
31+
## Startup Script
32+
33+
The startup script entries that handle autosave will look the similar for all IOC instances as follows.
34+
35+
First in pre init stage we have:
36+
```
37+
# Autosave pre iocInit
38+
set_requestfile_path("/epics", "autosave")
39+
set_savefile_path("/autosave")
40+
save_restoreSet_status_prefix BL47P-MO-IOC-01
41+
save_restoreSet_Debug 0
42+
save_restoreSet_NumSeqFiles 3
43+
save_restoreSet_SeqPeriodInSeconds 600
44+
save_restoreSet_DatedBackupFiles 1
45+
save_restoreSet_IncompleteSetsOk 1
46+
set_pass0_restoreFile autosave_positions.sav
47+
set_pass1_restoreFile autosave_settings.sav
48+
asSetFilename $(PVLOGGING)/src/access.acf
49+
```
50+
51+
save_restoreSet values can be adjusted with arguments in the yaml but the pass0 and pass1 save files are fixed for epics-containers. These files will be saved into `/autosave` inside the IOC instance's container filesystem. Along side them will be the sequence files and dated backup files.
52+
53+
`/autosave` will be mounted into the namespace's autosave Persistent Volume Claim with a subfolder named after the IOC instance. For our BL47P-MO-IOC-01 example we have:
54+
55+
- namespace: p47-beamline
56+
- PVC name: p47-autosave-claim
57+
- subPath in the PVC: bl47p-mo-ioc-01
58+
59+
Hence a pod that mounts the root of the PVC `p47-autosave-claim` will be able to browse the autosave files of all IOC instances in the namespace.
60+
61+
After iocInit we have
62+
```
63+
# Autosave post iocInit
64+
create_monitor_set autosave_positions.req, 5, ""
65+
create_monitor_set autosave_settings.req, 30, ""
66+
```
67+
68+
The two req files list the PVs and have fixed names in epics-containers:
69+
- autosave_positions.req: lists PVS to be restored at phase 0 before record processing starts (usually motor positions)
70+
- autosave_settings.req: lists PVS to be restored at phase 1 after record processing starts
71+
72+
These files are generated by ibek from the req files in the support modules included in the generic IOC but can be also overridden on an instance basis.
73+
74+
(req_sources)=
75+
## Sources of req files
76+
77+
There are 3 places ibek sources autosave req files from:
78+
79+
- The built support module may have req files in its `Db` database template folder alongside the Database templates
80+
- The ibek-support subfolder for the support module, these may override the above
81+
- The config folder for the ioc instance, these override both of the above
82+
83+
In all cases the filenames must follow a strict pattern to identify the template from which the referenced PVs are being sourced. (this is the Areadetector approach). Overriding is simply a matter of creating the same file name in ibek-support or instance config.
84+
85+
Pattern: <template_stem_name>_{positions|settings}.req
86+
87+
e.g.
88+
89+
- template: basic_asyn_motor.template
90+
- phase 0 .req file: basic_asyn_motor_positions.req
91+
- phase 1 .req file: basic_asyn_motor_settings.req
92+
93+
## Runtime behaviour
94+
95+
All of the `.req` files supplied by support modules include the same macros as the templates that their PVs come from. Hence these need to be substituted with values that the individual IOC instance is using before passing to autosave.
96+
97+
In addition the multiple `.req` files from multiple support modules need to be gathered into a single file for each of the autosave phases. These are to be called `autosave_positions.sav.req` and `autosave_setting.req` and passed to the `create_monitor_set` function as we saw above.
98+
99+
Both file gathering and substitution are handled by ibek in the `start.sh` script that all epics-containers IOC instances use. The command that performs this step is:
100+
101+
```bash
102+
ibek runtime generate-autosave
103+
```
104+
105+
This performs the following steps:
106+
107+
- symlinks all `.req` files found in the support modules of the generic IOC to `\epics\autosave`
108+
- symlinks all `.req` files found in `ibek-support` support module folders to `\epics\autosave` (overwriting provides override facility)
109+
- symlinks all `.req` files found in `\epics\ioc\config` to `\epics\autosave` (overwriting as provides override facility)
110+
- generates two substitution files
111+
- /epics/runtime/autosave_positions.subst
112+
- /epics/runtime/autosave_settings.subst
113+
- runs MSI over the above substitution files, with the path pointing to `\epics\autosave`
114+
115+
The substitution files are copies of `/epics/runtime/ioc.subst` except that the EPICS Db template file names are replaced with autosave req file names using the naming convention described in [](#req_sources).
116+
117+
The MSI output is two files `autosave_positions.sav.req` and `autosave_setting.req` which are in turn passed to `create_monitor_set` in the startup script.z

0 commit comments

Comments
 (0)