Introduction

About

This project is a component of the Experimental Physics and Industrial Control System (EPICS), a set of tools, libraries and applications developed collaboratively and used worldwide to create distributed soft real-time control systems for large scale scientific instruments.

The State Notation Language (SNL), is a domain specific programming language that smoothly integrates with and depends and builds on EPICS base. This project defines SNL and provides an implementation, consisting of the SNL compiler and runtime system.

The Sequencer is free software, licensed under the EPICS Open License.

For further information

This page describes version 2.2 and the documentation, in particular the language reference, has been updated to reflect the changes between 2.1 and 2.2. For older versions, please refer to the old version of this page.

Overview

In SNL you structure your program as a set of concurrently running finite state machines, called state_sets. State sets are declared by listing their states, which in turn define under which condition (when) the state set reaches another state and what the program should do once the transition is triggered.

SNL allows you to bind program variables to externally defined process variables (PVs), such as provided by an EPICS runtime database. This can be done in such a way that the value of the program variable gets continuously updated whenever the value of the acssociated PV changes. Such variables can then be used inside the state transition conditions, and the runtime system takes care that the conditions are evaluated when and only when changes to the associated PV occur.

In the code that gets executed when a state transition takes place, you can explicitly read the value of the PV into the associated program variable (pvGet), or to send the value of the variable to update the PV (pvPut). (These are just the two most important of many more Built-in Functions.)

The mechanism behind all this PV magic is the EPICS Channel Access network protocol with its support for subscriptions. However, when programming in SNL you need not concern yourself with the details of the mechanism. The SNL compiler and runtime system manage all this behind the scenes, and also take care that the integrity of your variables is maintained, even in the presence of multiple concurrent state sets inside a single program (at least in Safe Mode). Programming in SNL is free of locks and therefore also free of deadlocks.

Despite all this, SNL is emphatically not a high-level language: most of its syntax and semantics are directly inherited from C. The language is designed for seamless integration with C code; for instance, you can directly call C procedures in SNL action blocks and state transition conditions, and the types of variables you can declare in SNL map directly to C types. The compiler for SNL (called snc, see Compiling SNL Programs) takes a very minimalistic approach to compilation by generating portable standard C89/90 code that works on all platforms supported by EPICS. In fact, most of the SNL action code is compiled almost verbatim to C, and the generated code is quite human readable. The SNL compiler also delegates all type checking to the C compiler (and some care has been taken to generate the code in such a way that the C type checker has actually enough information to do useful type checking).

Compilation of the generated code and linking to the SNL runtime system is also not done by snc. Instead this task is delegated to the EPICS build system by making the Sequencer an EPICS support module that automatically adds appropriate build rules for SNL source files.

Acknowledgements

The sequencer was originally developed by Andy Kozubal at Los Alamos National Laboratory (LANL). It was subsequently modified by William Lupton, formerly at the W. M. Keck Observatory (Keck), with contributions by Greg White of the Stanford Linear Accelerator Center National Accelerator Laboratory (SLAC-NAL).

Eric Norum, Janet Anderson, and Marty Kraimer (APS) made the initial port to EPICS 3.14 that led to the 2.0.x series. Eric Norum and Andrew Johnson (APS) provided lots of patches up to release 2.0.12.

Mark Rivers made a number of useful suggestions and tested version 2.1 with several sets of existing programs on various platforms. J. Lewis Muir provided documentation patches.

Special thanks go to the people who develop and maintain re2c, the ultimate tool to generate versatile and extremely fast lexers for C and C++.

Copying and Distribution

The EPICS Sequencer is distributed subject to a Software License Agreement found in the file LICENSE that is included with this distribution.

Copyright (c) 1989-1994 The Regents of the University of California

and the University of Chicago Board of Governors. Los Alamos National Laboratory

Copyright (c) 2010-2015 Helmholtz-Zentrum Berlin f. Materialien

und Energie GmbH, Germany (HZB)

All rights reserved.

The EPICS Sequencer is distributed subject to the following license conditions:

SOFTWARE LICENSE AGREEMENT Software: EPICS Sequencer

  1. The “Software”, below, refers to EPICS Sequencer (in either source code, or binary form and accompanying documentation). Each licensee is addressed as “you” or “Licensee.”

  2. The copyright holders shown above and their third-party licensors hereby grant Licensee a royalty-free nonexclusive license, subject to the limitations stated herein and U.S. Government license rights.

  3. You may modify and make a copy or copies of the Software for use within your organization, if you meet the following conditions:

    1. Copies in source code must include the copyright notice and this Software License Agreement.

    2. Copies in binary form must include the copyright notice and this Software License Agreement in the documentation and/or other materials provided with the copy.

  4. You may modify a copy or copies of the Software or any portion of it, thus forming a work based on the Software, and distribute copies of such work outside your organization, if you meet all of the following conditions:

    1. Copies in source code must include the copyright notice and this Software License Agreement;

    2. Copies in binary form must include the copyright notice and this Software License Agreement in the documentation and/or other materials provided with the copy;

    3. Modified copies and works based on the Software must carry prominent notices stating that you changed specified portions of the Software.

  5. Portions of the Software resulted from work developed under a U.S. Government contract and are subject to the following license: the Government is granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable worldwide license in this computer software to reproduce, prepare derivative works, and perform publicly and display publicly.

  6. WARRANTY DISCLAIMER. THE SOFTWARE IS SUPPLIED “AS IS” WITHOUT WARRANTY OF ANY KIND. THE COPYRIGHT HOLDERS, THEIR THIRD PARTY LICENSORS, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, (2) DO NOT ASSUME ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE OR THAT ANY ERRORS WILL BE CORRECTED.

  7. LIMITATION OF LIABILITY. IN NO EVENT WILL THE COPYRIGHT HOLDERS, THEIR THIRD PARTY LICENSORS, THE UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE, INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES.

Note on Versions

This manual describes version 2.2 of the sequencer. This version adds support for declaring variables of almost all types expressible in C. It also adds support for defining functions and struct types in SNL. The backend of the compiler was changed so that generated names follow a consistent naming convention. The interface between compiler and runtime system has been separated from the public API available to escaped C code.

Version 2.1 added support for local definitions (including variable declarations) at all levels, a significantly improved compiler that employs new lexer and parser generators, lots of bug fixes, and a new safe mode to avoid variable corruption due to race conditions.

Version 2.0 differs from version 1.9 mainly in that sequencer run-time code can run under any operating system for which an EPICS OSI (Operating System Independent) layer is available, and message systems other than channel access can be used. It depends on libraries which are available only with EPICS R3.14.

An interim version 1.9.4 was made available to the EPICS community; all new developments apart from major bug fixes will be based on version 2.0.

Version 1.9 was written by Andy Kozubal, the original author of this software. This version of the manual describes version 2.0, for which the changes have been implemented by William Lupton of W. M. Keck Observatory and Greg White of Stanford Linear Accelerator Center (SLAC).

Versioning Policy

Starting with release 2.0.0, the third digit is the patch level and will be incremented each time a new version is released, no matter how minor the changes (except if it is zero). The second digit is the minor release number and will be incremented each time functional changes are made. The first digit is the major release number and will be incremented only when major changes are made.

Starting with version 2.1, the following refined rules apply:

  • Changes in the major (first) number indicate disruptive changes that may break backward compatibility. When upgrading to a new major version, existing programs may need to be reviewed and possibly adapted to changes in syntax or semantics.

  • An increase of the minor (second) release number indicates the availability of new features, while source code compatibility for existing programs is preserved. However, such changes may involve major re-organizations of the implementation, und therefore introduce new bugs. Care should be taken when upgrading to a new minor release, especially if the new patch-level number is zero: these should be used in production systems only after testing that everything still works as expected.

    Major and minor release number together are referred to as the sequencer’s version.

  • Changes in the patch-level (third) release number are strictly reserved for bug-fixes, including fixes and extensions to the documentation and the tests. No new features will appear, except where unavoidable to cleanly fix a bug. It should always be safe (and is recommended) to upgrade to the latest patch level release.

  • A patch-level release number of zero indicates a pre-release. Such releases are still in the process of stabilizing and thus might receive significant changes if it turns out that this would be better in the long run. A fourth number may indicate progress toward the first stable release, indicated by a patch-level release number of one.