LSST Service Abstraction Layer (SAL) software SDK
Version 2.0 - June 2011 - Dave Mills ([email protected])
Introduction
All the services are built upon a framework of OpenSplice DDS. Code may be
autogenerated for a variety of compiled and scripting languages, as well as
template documentation, and descriptions appropriate for ingest by other
software engineering tools.
Prerequisites
The following packages should be installed before attempting to use the SAL
tools. (optional*)
cmake, g++, jdk, libboost-dev, libboost-thread-dev, libboolst-program-options
libboost-system, mysql*, OpenSplice, simd
This document briefly describes how to use the SAL SDK to generate application
level code to utilize the supported services (Commanding, Telemetry and Logging).
The SAL SDK should install on any modern Linux computer. Code can be
generated without any of the other components being present, but building
and testing will require a minimum of "make" and the GNU compiler suite.
Installation
Unpack the SAL tar archive in a location of choice (/opt is recommended),
and then add e.g.
source /opt/lsstsal/salenv.sh
to your login profile (bash shell)
Usage
The most common code generation process consists of simple steps :
1) Define a topic, command or Log activity (either using the SAL VM, or by hand
with a text editor) using the subset of IDL supported by SAL.
2) Run the required operation using 'salgenerator'
3) Modify the autogenerated sample code to fit the application required.
4) Build if necessary, and test
Topic Definition
A very simple version of IDL (Interface Definition Language) is used
to define a topic. The topic is the smallest unit of information which
can be exchanged using the SAL mechanisms.
e.g.
#
# Define the topic for the IR skycam Application level data
#
#
struct skycam_IR_Application {
string<16> site;
// none ; none ; Site where instrument is located
long
ref_time ;
// seconds ; none ; Reference time for this batch of images
string<32> gmt_time;
// none ; none ; GMT version of REF_TIME
float
del_t;
// seconds ; none ; Seconds after REF_TIME this image began
string<16> htchops;
// none ; open|closed|moving|fault ; Hatch position
float
encl_t1;
// degC ; -10,30 ; Enclosure internal temperature 1, Celsius
long
filpos;
// none ; none ; Filter Wheel position
string<16> fildes;
// none ; none ; Filter description
float
bb_temps[3]; // degC ; none ; Hatch Blackbody temperatures, Celsius
float
fpa_t;
// degC ; -60,0 ; IR camera FPA temperature, Celsius
float
duration;
// seconds ; none ; Nominal exposure time, sec.
string<128> imagefile;
// none ; none ; URL to FITS image
}
This example illustrates the major features :
- comment lines have # in the first column
- all topics are named in a hierarchical fashion intended to
describe their position within the LSST system.
- individual items in a topic are strongly "typed", and may be
of types : string, short, long, float or double. String length is
designated using <nnn> and arrays of other types are
denoted using [nnn].
- Optional comments can be used to define metadata about items,
the format is
// units ; min,max|enumeration ; Brief descriptive text
Command Definition
The process of defining supported commands is very simple. Commands
are listed (one per line) in a text .cmd file e.g. skycam.cmd
# Command definitions for skycam subsystem
skycam IR sequence start default
skycam IR sequence stop
skycam IR cpu reset
skycam IR filter select 3
skycam IR exposure set 20.0
skycam IR setpoint set -30.0
skycam VIS sequence start default
skycam VIS sequence stop
skycam VIS cpu reset
skycam VIS filter select 3
skycam VIS exposure set 20.0
skycam VIS setpoint set -30.0
The format for each command is :
subsystem device attribute action [value1] [value2] [value3]
where the [value]'s are optional and may be numbers, keywords ,or "" delimited strings of up to
128 characters. All subsystem , device, attribute, actions and keywords must be present in
the SAL System Dictionary (TBD).
Code Generation
Once a topic has been defined , either using the SAL VM or hand edited,
e.g. skycam_IR_Application.idl , interface code and usage samples can
be generated using the salgenerator tool. e.g.
salgenerator skycam_IR_Application code c++ debug testcode
would generate the communications libraries to be linked with any user code which needs to
publish or subscribe to the topic skycam_IR_Application.
The topic can be wildcarded, so for example
salgenerator skycam* c++ debug testcode
would generate a library appropriate for all skycam related items as well as test programs for
each skycam telemetry stream.
The "code" keyword indicates code generation is the required operation,
the selected language is c++ (GNU G++ compatible code is generated),
the debug switch for the compiler is to be used, and test program code
is requested.
Invoke salgenerator without any arguements to see the currently
available options e.g.
SAL generator tool - Usage :
salgenerator subsystems* keyword(s)
where keyword(s) may be
validate - check the IDL
c++ - generate c++ code
compile - compile a c++ module
java - generate JNI interface
tcl
- generate tcl interface
html - generate web form interfaces
link - link a SAL program
labview - generate Labview low-level interface
db
- generate telemetry database table
Arguments required are
db start-time end-time interval
where the times are formatted like “2011-11-12 16:20:01“
and the interval is in seconds
shmem - generate shared memory interface
sim - generate simulation configuration
icd
- generate ICD document
verbose - be more verbose ;-)
The salgenerator executes a variety of processes, depending upon the options
selectected.
validate - validate the idl
This will usually be the first option used. It will take the input IDL file(s)
and parse them to check for illegal syntax etc. A validated output version
is generated which is then used by the rest of the tools.
e.g.
Using the input file camera_TC_zone1.idl
struct camera_TC_zone1 {
float cold_plate[25];
float flow_rate[25];
float temperature[25];
float setpoint[25];
unsigned long
status[25];
};
salgenerator camera_TC_zone1 validate
Validating camera_TC_zone1.idl interface definition
Creating /home/saluser/test/idl-templates/validated/camera_TC_zone1.idl
---> struct camera_TC_zone1 {
---> float
cold_plate[25];
---> float
flow_rate[25];
---> float
temperature[25];
---> float
setpoint[25];
---> unsigned long status[25];
---> };
end of topic
Completed camera_TC_zone1.idl validation
This creates the file /home/saluser/test/idl-templates/validated/camera_TC_zone1.idl
and also an SQL table format description of the set of topic items and their extended properties
in /opt/lsstsal/scripts/code/sql/camera_TC_zone1_items.sql
Generating code
Once the validated IDL is available , code generation can proceed.
First create the c++ interface e.g.
salgenerator camera_TC_zone1 c++
Generating SAL low-level code for camera_TC_zone1
Generating DDS low-level code for camera_TC_zone1
Generating simd interface and sample programs
Generating SAL interface code for camera_TC_zone1
Updated topic camera_TC_zone1 in libsal_camera_simd
Updated topic camera_TC_zone1 in libsal_simd
Creating svcSAL.cpp.camera_topics
Creating svcSAL_camera_topics.h
Done camera_TC_zone1
....
Generating interface stubs for camera_TC_zone1
Inserting code for simpletest-camera_TC_zone1
Inserting code for simpleSHMtest-camera_TC_zone1
Inserting code for camera_TC_zone1-shmsub
Inserting code for camera_TC_zone1-shmpub
The output files for this example would be placed in a new directory based at
./ospl-camera_zone1
and contain
CMakeCache.txt
CMakeFiles
CMakeLists.txt
Makefile
camera_TC_zone1-asub
camera_TC_zone1-asub.cpp
camera_TC_zone1-pub
camera_TC_zone1-pub.cpp
camera_TC_zone1-shmpub.cpp
camera_TC_zone1-shmsub.cpp
camera_TC_zone1-sub
camera_TC_zone1-sub.cpp
camera_TC_zone1.idl
cmake_install.cmake
gen/camera_TC_zone1.cpp
gen/camera_TC_zone1.h
gen/camera_TC_zone1Dcps.cpp
gen/camera_TC_zone1Dcps.h
gen/camera_TC_zone1Dcps_impl.cpp
gen/camera_TC_zone1Dcps_impl.h
gen/camera_TC_zone1SplDcps.cpp
gen/camera_TC_zone1SplDcps.h
gen/ccpp_camera_TC_zone1.h
libdatamodel.a
simpleSHMtest-camera_TC_zone1.cpp
simpletest-camera_TC_zone1.cpp
svcSAL_camera_TC_zone1-onlyshm.cpp
svcSAL_camera_TC_zone1-onlyshm.h
svcSAL_camera_TC_zone1-onlyshm.i
svcSAL_camera_TC_zone1.cpp
svcSAL_camera_TC_zone1.h
svcSAL_camera_TC_zone1.i
svcSAL_camera_TC_zone1_shm.cpp
svcSAL_camera_TC_zone1_shm.h
Shared memory interface
The next recommended step i s to generate the shared memory interface
and tcl test code.
salgenerator camera_TC_zone1 shmem
Generating shmem tools for camera_TC_zone1
Generating tcl interface for subsystem camera_TC_zone1 /home/saluser/test
basedir = /home/saluser/test
Processing topic camera_TC_zone1
This interface is a temporary requirement until the official OpenSplice
version of the simd api is finalized.
The following are gen /home/saluser/test/idl-templates/validated/camera_TC_zone1.idlerated by
this step in directory shmem-camera_TC_zone1
camera_TC_zone1_cache.h
camera_TC_zone1_getstub.txt
camera_TC_zone1_lvgetstub.txt
camera_TC_zone1_lvprostub.txt
camera_TC_zone1_lvputstub.txt
camera_TC_zone1_putstub.txt
connect_camera_TC_zone1.tcl libshm_
camera_TC_zone1_server.so shm_tcl_
camera_TC_zone1.c shm_
test1 shmem_camera_TC_zone1.h shmem_
camera_TC_zone1_server.cpp
shmrd_tcl_camera_TC_zone1.c
startpubsub-camera_TC_zone1
test_camera_TC_zone1.tcl
test_shmem_camera_TC_zone1.cpp
Java interface
This option generates two types of Java interfaces. Firstly it uses the
OpenSplice provided too to create a low level interface. e,g,
salgenerator camera_TC_zone1 java
would create the following low level interface in the ospl-camera_TC_zone1 diretory
camera_TC_zone1Holder.java
camera_TC_zone1.java
A second interface is also generated based on a JNI interface to the c++ simd package.
The files generated for this interface are made using the SWIG package with the following
invocation (done automatically by salgenerator)
swig -c++ -java -w401 svcSAL_camera_TC_zone1-onlyshm.i
The following files would be generated
SWIGTYPE_p_shmMapper.java
SWIGTYPE_p_std__string.java
SWIGTYPE_p_svcCHAR.java
SWIGTYPE_p_svcDBL.java
SWIGTYPE_p_svcFLT.java
SWIGTYPE_p_svcIID.java
SWIGTYPE_p_svcINT.java
SWIGTYPE_p_svcRTN.java
SWIGTYPE_p_svcSHORT.java
SWIGTYPE_p_svcTID.java
SWIGTYPE_p_svcTIME.java
SWIGTYPE_p_svcUINT.java
SWIGTYPE_p_svcUSHORT.java
salcamera_TC_zone1.java
swigcamera_TC_zone1.java
swigcamera_TC_zone1JNI.java
Web interface pages
The generator can also be used to generate HTML format files which provide
the SAL website with the capability to create a web interface to the SAL tools.
Forms are generated to allow the IDL definition to be modified, database tables
created , simulation scripts created etc.
salgenerator camera_TC_zone1 html
creates the following files in the html directory
camera/camera-metadata.html
camera/camera-streamdef.html
camera.TC camera_TC-metadata.html
camera.TC camera_TC-streamdef.html
index-dbsimulate-camera.html
index-streamdef.html
sal-generator-camera.html
sal-generator.html
Facility Database simulation
This option is used to create simulated Facility Database tables corresponding
to the telemetry streams which you have defined.
This salgenerator option requires additional arguments to specify the temporal
parameters of the simulation e.g.
salgenerator camera_TC_zone1 db “2011-11-12 16:00:00“ “2011-11-13 17:00:00“ 60
would generate an sql file to create a table with camera_TC_zone1 data covering the
period requested with an interval between entries of 60 seconds. In this case the
file
/home/saluser/test/sql/camera_TC_zone1-2011-11-12-16:00:00_to_2011-11-13-17:00:00.sql
Labview interface
This option generates a Labview directory with the required include files
and simple C interface which interfaces to the SAL shared memory interface.
salgenerator camera_TC_zone1 labview
Generating Labview low level code for camera_TC_zone1
The subdirectory labview will contain
cvilvsb.h
extcode.h
fundtypes.h
hosttype.h
makefile.lvsal
platdefines.h
soar_lv.h
svcSAL_commLib.c
svcSAL_commLib.h
Appendix 1 - IDL Reserved words
The following words may not be used to names components in the IDL files processed
by the SAL tools.
bstract any attribute boolean case char component const consumes context custom default double
emits enum eventtype exception factory false finder fixed float getraises home import in inout
interface local long module multiple native object octet oneway out primarykey private provides public
publishes raises readonly sequence setraises short string struct supports switch true truncatable
typedef typeid typeprefix union unsigned uses valuebase valuetype void wchar wstring
Appendix 2 -Sample c++ invocation
The following illustrates a typical command line c++ sample, with all the components installed
in the default /opt directory tree.
/usr/bin/c++ -g -I. -I/opt/lsstsal/scripts/code/include/sal -I/opt/OpenSplice/HDE/x86.linux2.6/include/
dcps/C++/SACPP -I/opt/OpenSplice/include -I/opt/OpenSplice/include/sys -I/opt/simd/include -I../include
-pipe -Wall -c -std=c++0x SOURCEFILE.cpp
and to link with all the required libraries
/usr/bin/c++ -g -I. -I/opt/lsstsal/scripts/code/include/sal -I/opt/OpenSplice/HDE/x86.linux2.6/include/
dcps/C++/SACPP -I/opt/OpenSplice/include -I/opt/OpenSplice/include/sys -I/opt/simd/include -I../include
-pipe -Wall -std=c++0x -I../shmem-camera_TC_zone1 PROGRAMNAME.o svcSAL_camera_TC_zone1onlyshm.o -o PROGRAMNAME -L/opt/OpenSplice/HDE/x86.linux2.6/lib -ldcpsgapi -ldcpssacpp lddsdatabase -lddsos -lboost_thread -lboost_program_options -lboost_system -lddsutil -lddsserialization
-lddsserialization -lddskernel -lddsconf -lddsconfparser -lddsuser -L/opt/simd/lib -lSimD libdatamodel.a
Appendix 3 - Output directories
The following directories may be created by the salgenerator and associated tools
ospl-topic
ospl-topic/gen
shmem-topic
html
idl-templates
idl-tprintenv emplates/validated
include
labview
lib
sql
Appendix 4 - Shell environment
The following environment variable may be created by the salgenerator and associated
tools.
ACE_ROOT=/opt/tao161
CLASSPATH=/opt/openfusionV4/lib/idl.jar:/opt/openfusionV4/lib/endorsed/avalon-framework.jar:/opt/
openfusionV4/lib/endorsed/logkit.jar:/opt/openfusionV4/lib/endorsed/jacorb.jar:/opt/openfusionV4/lib/
idl.jar:/opt/openfusionV4/lib/endorsed/avalon-framework.jar:/opt/openfusionV4/lib/endorsed/logkit.jar:/
opt/openfusionV4/lib/endorsed/jacorb.jar:/opt/openfusionV4/lib/idl.jar:/opt/openfusionV4/lib/endorsed/
avalon-framework.jar:/opt/openfusionV4/lib/endorsed/logkit.jar:/opt/openfusionV4/lib/endorsed/
jacorb.jar:
DDS_CMCOMMON=cmcommon
DDS_CMXML=cmxml
DDS_COMMONSERV=commonserv
DDS_CONF=ddsconf
DDS_CONFPARSER=ddsconfparser
DDS_CPP=ddscpp
DDS_DATABASE=ddsdatabase
DDS_DCPSCCPP=dcpsccpp
DDS_DCPSGAPI=dcpsgapi
DDS_DCPSJNI=dcpsjni DDS_
DCPSSAC=dcpssac
DDS_DCPSSACPP=dcpssacpp
DDS_DCPSSACS=dcpssacs
DDS_DCPSSAJ=dcpssaj
DDS_KERNEL=ddskernel
DDS_OS=ddsos
DDS_OS_NET=ddsosnet
DDS_SERIALIZATION=ddsserialization
DDS_USER=ddsuser
DDS_UTIL=ddsutil
INCLUDE_API_DCPS=yes INCLUDE_API_
DCPS_CCPP=yes
INCLUDE_API_DCPS_CJ=yes
INCLUDE_API_DCPS_GAPI=yes
INCLUDE_API_DCPS_JAVA=yes
INCLUDE_API_DCPS_JNI=yes
INCLUDE_API_DCPS_SAC=yes
INCLUDE_API_DCPS_SACPP=yes
INCLUDE_API_DCPS_SACS=yes
INCLUDE_API_DCPS_SAJ=yes
INCLUDE_C=yes
INCLUDE_CS=yes
INCLUDE_CXX=yes
INCLUDE_DBT_ABSTRACTION=yes
INCLUDE_DBT_API=yes
INCLUDE_DBT_API_CM=yes
INCLUDE_DBT_API_DCPS=yes
INCLUDE_DBT_API_DCPS_CCPP=yes
INCLUDE_DBT_API_DCPS_CJ=yes
INCLUDE_DBT_API_DCPS_GAPI=yes
INCLUDE_DBT_API_DCPS_JAVA=yes
INCLUDE_DBT_API_DCPS_JNI=yes
INCLUDE_DBT_API_DCPS_SAC=yes
INCLUDE_DBT_API_DCPS_SACS=yes
INCLUDE_DBT_API_DCPS_SAJ=yes
INCLUDE_DBT_CONFIGURATION=yes
INCLUDE_DBT_CONSISTENCY=yes
INCLUDE_DBT_DATABASE=yes
INCLUDE_DBT_DLRL=yes
INCLUDE_DBT_INSTALLER=yes
INCLUDE_DBT_KERNEL=yes
INCLUDE_DBT_SERVICES=yes
INCLUDE_DBT_SERVICES_COMMON=yes
INCLUDE_DBT_SERVICES_DDSI=yes
INCLUDE_DBT_SERVICES_DURABILITY=yes
INCLUDE_DBT_SERVICES_NETWORKING=yes
INCLUDE_DBT_SERVICES_SERIALIZATION=yes
INCLUDE_DBT_SERVICES_SPLICED=yes
INCLUDE_DBT_TOOLS=yes
INCLUDE_DBT_TOOLS_IDLPP=yes
INCLUDE_DBT_TOOLS_SHMDUMP=yes
INCLUDE_DBT_TOOLS_TUNER=yes
INCLUDE_DBT_USER=yes
INCLUDE_DBT_UTILITIES=yes
INCLUDE_FILTERS=yes
INCLUDE_JAVA=yes
INCLUDE_ORB=yes
INCLUDE_PLUGGABLE_REPORTING=yes
INCLUDE_SERVICES=yes
INCLUDE_SERVICES_COMMON=yes
INCLUDE_SERVICES_DDSI=yes
INCLUDE_SERVICES_DURABILITY=yes
INCLUDE_SERVICES_NETWORKING=yes
INCLUDE_SERVICES_SPLICED=yes
INCLUDE_TESTENGINE=yes
INCLUDE_TOOLS=yes
INCLUDE_TOOLS_IDLPP=yes
INCLUDE_TOOLS_MMSTAT=yes
INCLUDE_TOOLS_OSPL=yes
INCLUDE_TOOLS_SHMDUMP=yes
INCLUDE_TOOLS_TUNER=yes
INCLUDE_UTILITIES=yes
JAVA_HOME=/usr/lib/jvm/java-6-openjdk LANG=en_US.utf8
LD_LIBRARY_PATH=/opt/OpenSplice/lib/x86.linux2.6-release:/opt/OpenSplice/lib/x86.linux2.6-release:/
opt/tao161/lib:/usr/lib/jvm/java-6-openjdk/lib:/opt/OpenSplice/lib/x86.linux2.6-release:/opt/tao161/lib:/
usr/lib/jvm/java-6-openjdk/lib:/opt/OpenSplice/lib/x86.linux2.6-release:/opt/tao161/lib:/usr/lib/jvm/
java-6-openjdk/lib:/opt/tao161/lib:/opt/openfusionV4/lib:/opt/tao161/lib:/opt/jacorb-2.3.1/lib:/opt/
tao161/lib:/opt/openfusionV4/lib:/opt/tao161/lib::/usr/lib/jvm/java-6-openjdk/jre/lib/i386:/usr/lib/jvm/
java-6-openjdk/jre/lib/i386/client:/usr/lib/jvm/java-6-openjdk/jre/lib/i386/native_threads:/usr/lib/jvm/
java-6-openjdk/jre/lib/i386:/usr/lib/jvm/java-6-openjdk/jre/lib/i386/client:/usr/lib/jvm/java-6-openjdk/jre/
lib/i386/native_threads:/usr/lib/jvm/java-6-openjdk/jre/lib/i386:/usr/lib/jvm/java-6-openjdk/jre/lib/i386/
client:/usr/lib/jvm/java-6-openjdk/jre/lib/i386/native_threads
PACKAGE_DATE=2011-05-12
PACKAGE_NAME=OpenSplice
PACKAGE_VERSION=V5.4.1
PATH=/opt/OpenSplice/exec/x86.linux2.6-release:/opt/OpenSplice/bin:/opt/tao161/bin:/usr/lib/jvm/
java-6-openjdk/bin:/opt/tao161/bin:/usr/lib/jvm/java-6-openjdk/bin:/opt/tao161/bin:/opt/tao161/bin:/opt/
openfusionV4/bin:/opt/tao161/bin:/opt/jacorb-2.3.1/bin:/opt/tao161/bin:/opt/openfusionV4/bin:/opt/
tao161/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/opt/lsstsal/scripts
SAL_DIR=/opt/lsstsal/scripts
SELECTED_TARGETS= x86_64.linux2.6-dev x86_64.linux2.6-release x86.linux2.6-debug x86.linux2.6dev x86.linux2.6-devdat x86.linux2.6-efence x86.linux2.6-release x86.linux2.6-shmt_dev x86.linux2.6test
SPLICE_BIN_PATH=/opt/OpenSplice/bin
SPLICE_EXEC_PATH=/opt/OpenSplice/exec/x86.linux2.6-release
SPLICE_HOST=x86.linux2.6-release
SPLICE_LIBRARY_PATH=/opt/OpenSplice/lib/x86.linux2.6-release
SPLICE_ORB=DDS_OpenFusion_1_6_1
SPLICE_TARGET=x86.linux2.6-release
TAO_ROOT=/opt/tao161
TARGET_DIR=/opt/OpenSplice