added Creating an RTEMS IOC Instance

gilesknap · gilesknap · commit 3c63fb3d602b · 2023-04-20T10:11:43.000Z
diff --git a/docs/user/tutorials/epics_devcontainer.rst b/docs/user/tutorials/epics_devcontainer.rst
@@ -5,10 +5,13 @@ The EPICS Devcontainer
 Introduction
 ------------
 
-You can setup a single devcontainer for managing all of your IOCs. In
-`devcontainer` we launched a container for a single project. Here we
-will create a workspace that will allow
-you to manage multiple projects in a single devcontainer.
+For working with epics-containers we provide a developer container with
+all the tools you need to build and deploy EPICS IOCs already installed.
+In this tutorial we will install and configure this devcontainer.
+
+In `devcontainer` we demonstrated launching a container for a single project.
+Here we will create a workspace that will allow
+you to manage multiple projects within a single devcontainer.
 
 The base container is defined in https://github.com/epics-containers/dev-e7
 but we will use a customizable image derived from that. The customizable
diff --git a/docs/user/tutorials/rtems_ioc.rst b/docs/user/tutorials/rtems_ioc.rst
@@ -9,12 +9,18 @@ now will look at the differences for this architecture. Further
 architectures will be supported in future.
 
 Each beamline or accelerator domain will require a server for
-serving the IOC binaries and instance files. For details of how to set this
-up see `rtems_setup`.
+serving the IOC binaries and instance files to the RTEMS devices. This
+needs to be set up for your test beamline before proceeding,
+see `rtems_setup`.
 
 Once you have the file server set up, deploying an IOC instance that uses
 an RTEMS Generic IOC is very similar to `deploy_example`.
 
+We will be adding
+a new IOC instance to the ``bl01t`` beamline that we created in the previous
+tutorials. You will need to have worked through the previous tutorials in
+order to complete this one.
+
 Preparing the RTEMS Boot loader
 -------------------------------
 
@@ -33,6 +39,8 @@ using a terminal server or similar.
     :console: ts0001 7007
     :crate monitor: ts0001 7008
 
+    It is likely already set up as per the example below.
+
 Use telnet to connect to the console of your target IOC. e.g.
 ``telnet ts0001 7007``. We want to get to the MOTLoad prompt which should look
 like ``MVME5500>``. If you see an IOC Shell prompt instead hit ``Ctrl-D`` to
@@ -81,14 +89,126 @@ Meaning of the parameters:
 Note that the IP parameters to the tftpGet command are respectively:
 net mask, gateway, server address, client address.
 
-Once you have the correct configuration you can restart the IOC with
-the ``reset`` command. But you need the kubernetes pod for this IOC to be
-up and running first so that it places the necessary files on the file server.
-See the next section for setting up the kubernetes pod.
 
+Creating an RTEMS IOC Instance
+------------------------------
+
+We will be adding a new IOC instance to the ``bl01t`` beamline that we created in
+:doc:`create_beamline`. The first step is to make a copy of our existing IOC instance
+and make some modifications to it. We will call this new IOC instance
+``bl01t-ea-ioc-02``.
+
+.. code-block:: bash
+
+    cd bl01t
+    cp -r iocs/bl01t-ea-ioc-01 iocs/bl01t-ea-ioc-02
+    # don't need this file for the new IOC
+    rm iocs/bl01t-ea-ioc-02/config/extra.db
+
+We are going to make a very basic IOC with some hand coded database with
+a couple of simple records. Therefore the generic IOC that we use can just
+be ioc-template.
+
+Generic IOCs have multiple targets, they always have a
+``developer`` target which is used for building and debugging the generic IOC and
+a ``runtime`` target which is lightweight and usually used when running the IOC
+in the cluster. The matrix of targets also includes an architecture dimension,
+at present the ioc-template supports two architectures, ``linux`` and
+``rtems``, thus there are 4 targets in total as follows:
+
+- ghcr.io/epics-containers/ioc-template-linux-runtime
+- ghcr.io/epics-containers/ioc-template-linux-developer
+- ghcr.io/epics-containers/ioc-template-rtems-runtime
+- ghcr.io/epics-containers/ioc-template-rtems-developer
+
+We want to run the RTEMS runtime target on the cluster so this will appear
+at the top of the ``values.yaml`` file. In addition there are a number of
+environment variables required for the RTEMS target that we also specify in
+``values.yaml``.
+Edit the file
+``iocs/bl01t-ea-ioc-02/values.yaml`` to look like this:
+
+.. code-block:: yaml
+
+If you are not at DLS you will need to change the above to match the
+parameters of your RTEMS IOC. The environment variables are:
+
+:K8S_IOC_ADDRESS: The IP address of the IOC (mot-/dev/enet0-cipa above)
+:RTEMS_VME_CONSOLE_ADDR: Address of terminal server for console access
+:RTEMS_VME_CONSOLE_PORT: Port of terminal server for console access
+:RTEMS_VME_AUTO_REBOOT: true to reboot the hard IOC when the IOC container changes
+:RTEMS_VME_AUTO_PAUSE: true to pause/unpause when the IOC container stops/starts
+
+Edit the file ``iocs/bl01t-ea-ioc-02/Chart.yaml`` and change the 1st 4 lines
+to represent this new IOC (the rest of the file is boilerplate):
+
+.. code-block:: yaml
+
+    apiVersion: v2
+    name: bl01t-ea-ioc-02
+    description: |
+        example RTEMS IOC for bl01t
+
+For configuration we will create a simple database with a few of records and
+a basic startup script. Add the following files to the
+``iocs/bl01t-ea-ioc-02/config`` directory.
+
+.. code-block::  :caption: bl01t-ea-ioc-02.db
+
+    record(calc, "bl01t-ea-ioc-02:SUM") {
+        field(DESC, "Sum A and B")
+        field(CALC, "A+B")
+        field(SCAN, ".1 second")
+        field(INPA, "bl01t-ea-ioc-02:A")
+        field(INPB, "bl01t-ea-ioc-02:B")
+    }
+
+    record(ao, "bl01t-ea-ioc-02:A") {
+        field(DESC, "A voltage")
+        field(EGU,  "Volts")
+        field(VAL,  "0.0")
+    }
+
+    record(ao, "bl01t-ea-ioc-02:B") {
+        field(DESC, "B voltage")
+        field(EGU,  "Volts")
+        field(VAL,  "0.0")
+    }
+
+.. code-block::  :caption: st.cmd
+
+    # RTEMS Test IOC bl01t-ea-ioc-02
+
+    dbLoadDatabase "/iocs/bl01t/bl01t-ea-ioc-02/dbd/ioc.dbd"
+    ioc_registerRecordDeviceDriver(pdbbase)
+
+    # db files from the support modules are all held in this folder
+    epicsEnvSet(EPICS_DB_INCLUDE_PATH, "/iocs/bl01t/bl01t-ea-ioc-02/support/db")
+
+    # load our hand crafted database
+    dbLoadRecords("/iocs/bl01t/bl01t-ea-ioc-02/config/bl01t-ea-ioc-02.db")
+    # also make Database records for DEVIOCSTATS
+    dbLoadRecords(iocAdminSoft.db, "IOC=bl01t-ea-ioc-02")
+    dbLoadRecords(iocAdminScanMon.db, "IOC=bl01t-ea-ioc-02")
+
+    iocInit
+
+You now have a new helm chart in iocs/bl01t-ea-ioc-02 that describes an IOC
+instance for your RTEMS device. Recall that this is not literally where the IOC
+runs, it deploys a kubernetes pod that manages the RTEMS IOC. It does contain
+the IOC's configuration and the IOC's binary code, which it will copy to the
+file-server on startup.
+
+You are now ready to deploy the IOC instance to the cluster and test it out.
 
-Creating an RTEMS Generic IOC
------------------------------
 
 Deploying an RTEMS IOC Instance
--------------------------------
+-------------------------------
+
+TODO:
+
+Once you have the correct configuration in your RTEMS boot-loader and you have
+deployed the kubernetes IOC instance, you can restart the IOC with
+the ``reset`` command. This will cause it to reboot and it should pick
+up your binary from the network and start the IOC. You should see the
+iocShell fire up and run
diff --git a/docs/user/tutorials/rtems_setup.rst b/docs/user/tutorials/rtems_setup.rst
@@ -51,28 +51,25 @@ changes:
 .. note::
 
   **DLS Users** The load balancer IP range on Pollux is
-  ``172.23.168.201-172.23.168.222``. The IP address you choose must be free
-  and not already in use by another service. At the moment you have to try
-  deploying and see if it works. If it doesn't work then try another IP.
+  ``172.23.168.201-172.23.168.222``. Please use ``172.23.168.203``. The test
+  RTEMS crate is likely to already be set up to point at this address. There
+  are a limited number of addresses available, hence we have reserved a single
+  address for the training purposes.
 
   Also note that ``bl01t`` is a shared resource so if there is already a
-  ``bl01t-ioc-files`` service running then you will have to choose a different
-  IP address (or just use the existing service and don't bother with this step)
-
-  **Recommendation**: use ``172.23.168.203`` and if it is already in use and the
-  service is already running then just use that one. There are a limited number
-  of fixed IPs available so we should only use one for training purposes.
+  ``bl01t-ioc-files`` service running then you could just use the existing
+  service.
 
 You can verify if the service is already running using kubectl. The command
 shown below will list all the services in the ``bl01t`` namespace, and the
 example output shows that there is already a ``bl01t-ioc-files`` service
-using the IP address ``172.23.168.220``:
+using the IP address ``172.23.168.203``.
 
 .. code-block:: bash
 
   $ kubectl get services -n bl01t
   NAME                TYPE           CLUSTER-IP       EXTERNAL-IP      PORT(S)                                                                        AGE
-  bl01t-ioc-files     LoadBalancer   10.108.219.193   172.23.168.220   111:31491/UDP,2049:30944/UDP,20048:32277/UDP,69:32740/UDP                      32d
+  bl01t-ioc-files     LoadBalancer   10.108.219.193   172.23.168.203   111:31491/UDP,2049:30944/UDP,20048:32277/UDP,69:32740/UDP                      32d
 
 Once you have made the changes to the helm chart you can deploy it to the
 cluster using the following command:
diff --git a/docs/user/tutorials/setup_k8s.rst b/docs/user/tutorials/setup_k8s.rst
@@ -3,6 +3,33 @@
 Setup a Kubernetes Server
 =========================
 
+.. Note::
+
+    **DLS Users**: DLS already has the test cluster Pollux and further
+    beamline and machine clusters are coming soon.
+
+    To use the Pollux cluster, run ``module load pollux`` outside of the
+    devcontainer and then run the script ``.devcontainer/dls-copy-k8s-crt.sh``
+
+    The Pollux Cluster already has a beamline namespace ``bl01t``
+    for you to use as a training area. *You will need
+    to ask SciComp to add you as a user of this namespace.*
+    Please be aware that this is a shared resource so others might be using
+    it at the same time.
+
+    The Pollux Cluster already has the Kubernetes dashboard installed.
+    To access it go to http://pollux.diamond.ac.uk and click
+    ``Pollux K8S Dashboard``.
+
+    Then select ``bl01t`` from the namespace drop down menu in the top left,
+    to see the training namespace.
+
+Introduction
+------------
+This is a very easy set of instructions for setting up an experimental
+single-node Kubernetes cluster,
+ready to test deployment of EPICS IOCs.
+
 .. note::
 
     From this point onward the tutorials assume that you are using
@@ -19,12 +46,6 @@ Setup a Kubernetes Server
     take on Kubernetes then there are some hints as to how to achieve this
     here: `../how-to/run_iocs`.
 
-Introduction
-------------
-This is a very easy set of instructions for setting up an experimental
-single-node Kubernetes cluster,
-ready to test deployment of EPICS IOCs.
-
 Bring Your Own Cluster
 ----------------------
 
@@ -41,27 +62,6 @@ namespace and service account as long as it has network=host capability.
 Cloud based K8S offerings may not be appropriate because of the Channel Access
 routing requirement.
 
-.. Note::
-
-    **DLS Users**: DLS already has the test cluster Pollux and further
-    beamline and machine clusters are coming soon.
-
-    To use the Pollux cluster, run ``module load pollux`` outside of the
-    devcontainer and then run the script ``.devcontainer/dls-copy-k8s-crt.sh``
-
-    The Pollux Cluster already has a beamline namespace ``bl01t``
-    for you to use as a training area. *You will need
-    to ask SciComp to add you as a user of this namespace.*
-    Please be aware that this is a shared resource so others might be using
-    it at the same time.
-
-    The Pollux Cluster already has the Kubernetes dashboard installed.
-    To access it go to http://pollux.diamond.ac.uk and click
-    ``Pollux K8S Dashboard``.
-
-    Then select ``bl01t`` from the namespace drop down menu in the top left,
-    to see the training namespace.
-
 Platform Choice
 ---------------
 
