Technical topic: ASN1SCC - ESA's ASN.1 Compiler for safety-critical embedded platforms

From TASTE
Jump to: navigation, search

Overview

ASN1SCC is a free, open-source ASN.1 compiler, targeting safety-critical systems. If you've never heard of ASN.1 before, a clear and concise overview can be read here.

ASN1SCC implements a large subset of ASN.1 standards, generating code for C, SPARK Ada and Scala. The supported ASN.1 subset includes all the features that do not require the use of heap (dynamic memory). Everything is therefore statically allocated, enabling the use of ASN.1 in embedded, safety-critical platforms.

Unaligned Packed Encoding Rules (uPER) encoders and decoders are generated for each input grammar, providing efficient and compact binary encodings with low memory and CPU footprints. Additionally, ASN1SCC provides ACN, a companion language permitting the specification of legacy encodings. ACN is a (much) simplified version of ECN (Encoding Control Notation), and it very easy to use.

In order to support a certification process, for each input grammar, ASN1SCC generates automatically sets of test cases verifying that the encoding and decoding process work well, providing 100% coverage on all the encoding and decoding logic. The test cases used are automatically computed using the constraints placed on the data types.

In order to support the automatic generation of documentation, ASN1SCC produces ICDs (Interface Control Documents) - HTML formatted in a nice layout that shows how data is physically encoded when using uPER or ACN.

ASN1SCC is fully customizable. It relies on the StringTemplate templating engine, meaning that the every output of the tool can be changed - from type representation to encoding functions and ICD layout.

The tool is developed in a purely-functional manner (in F#) and is actively maintained and supported. ASN1SCC was originally developed by Semantix, now Neuropublic, and is fully funded by the European Space Agency.

Maintenance, commercial support and development is also available for ASN1SCC and it is provided by Lamdasoft.

Features

The ASN.1 compiler:

  • supports Unaligned PER (uPER), ACN (user-controlled) and XER encodings
  • creates C, Ada and Scala type declarations and encoders/decoders
  • esp. for Ada, it emits SPARK compatible code, that validates under the SPARK suite
  • for Scala, it emits code which can be formally verified with Stainless
    • Scala is currently limited to uPER and ACN encodings
  • generates HTML or LaTeX documentation
  • generates (in combination with TASTE) Python bindings
  • generates SQL table definitions (DDL) and fully-functional Python/SQLAlchemy interfaces

ASN.1 subset

Most of the usual ASN.1 types and features are supported:

  • INTEGER
  • REAL
  • BOOLEAN
  • ENUMERATED without extensibility marker
  • SEQUENCE without extensibility marker
  • SEQUENCE OF with a higher size limit
  • OCTET STRING with a higher size limit
  • OCTET STRING (CONTAINING Other-type)
  • BIT STRING with a higher size limit
  • IA5String with a higher size limit
  • CHOICE without extensibility marker
  • NULL
  • SET / SET OF (with size limit)
  • AUTOMATIC TAGS
  • OBJECT IDENTIFIERS
  • DATE-TIME with all configuration options
  • Parameterized types

Restrictions

The following features from ASN.1 are not supported, either because they are not compatible with embedded platforms, or because they are considered deprecated:

(Check here to see the best practice for using ASN.1 types in a new grammar)

  • Extensibility marker (implies the use of malloc), and the EXTENSIBILITY IMPLIED tag
  • UTF8String (use OCTET STRING or IA5String)
  • All "fancy" String types (TeletexString, etc.)
  • Anything but AUTOMATIC TAGs (needed by the BER family of encodings)
  • Object Information Classes

Download

Sources are on GitHub and can be built on Linux and Windows

Linux Binaries can be found there as well.

Usage

asn1scc can be used with the following options, but most importantly one need to define to target language (C, Ada, Scala), the type of encoding (uPER, XER, ACN), and the Input files. 

asn1scc [--help] [--c-lang] [--ada-lang] [--scala-lang] [--uper-enc] [--xer-enc] [--acn-enc] [--auto-test-cases]
        [--out <dir>] [--equal-func] [--xml-ast <xmlFilename>] [--type-prefix <prefix>] [--rename-policy <int>]
        [--field-prefix <prefix>] [--generate-test-grammar] [--custom-stg <custom stg colon outfilename>]
        [--custom-stg-ast-version <astver>] [--icduper <uper icd output file>]
        [--customicduper <custom stg colon out filename>] [--icdacn <acn icd output file>]
        [--customicdacn <custom stg colon out filename>] [--icdpdus [<asn1 type assignments list>...]] [--adauses]
        [--acnd] [--word-size <wordSize>] [--fp-word-size <fpWordSize>] [--slim] [--target <x86|stm32|msp430|allboards>]
        [--version] [--debug-asn1 [<string>]] [--mapping-functions-module <string>] [--debug] [--streaming-mode]
        [--init-globals] <files>...

FILES:
    <files>...            List of ASN.1 and ACN files to process.

OPTIONS:
    --c-lang, -c          generate code for the C/C++ programming language
    --ada-lang, -Ada      generate code for the Ada/SPARK programming language
    --scala-lang, -Scala  generate code for the Scala programming language
    --uper-enc, -uPER     generates encoding and decoding functions for unaligned Packed Encoding Rules (uPER)
    --xer-enc, -XER       generates encoding and decoding functions for XML Encoding Rules (XER)
    --acn-enc, -ACN       generates encoding and decoding functions using the ASSERT ASN.1 encoding Control Notation
    --auto-test-cases, -atc
                          create automatic test cases.
    --out, -o <dir>       directory where all files are produced.
    --equal-func, -equal  generate functions for testing type equality.
    --xml-ast, -x <xmlFilename>
                          dump internal AST in an xml file
    --type-prefix, -typePrefix <prefix>
                          adds 'prefix' to all generated C or Ada/SPARK data types.
    --rename-policy, -renamePolicy <int>
                          Specify rename policy for Enumerated values. Allowed values are:
                              0 perform no rename (Ada default).
                              1 rename only conflicting enumerants (C default). 
                                E.g. In a grammar that contains 
                                  RGB ::= ENUMERATED {red, green, blue} 
                                  FavColors = ENUMERATED {red, yellow} 
                                only the red enumerant will be renamed to 
                                RGB_red and FavColors_red. 
                              2 rename all enumerants of an enumerated type 
                                that has least one conflicting enumerant.
                              3 all enumerants of all of an enumerated types
                                are renamed.
    --field-prefix, -fp <prefix>
                            Apply <prefix> string to any component or alternative fields present in the grammar.
                            If <prefix> is AUTO (i.e. -fp AUTO) then only the conflicting component or alternative names will be
                          prefixed with the type name.
    --generate-test-grammar, -gtc
                          generate a sample grammar for testing purposes. Experimental ...
    --custom-stg, -customStg <custom stg colon outfilename>
                          custom_stg_colon_outfilename is expected as stgFile.stg:outputFile where stgFile.stg is an existing custom
                          stg file, while outputFile is the name of the generated file. Invokes the custom stg file 'stgFile.stg'
                          and produces the output file 'outputFile'
    --custom-stg-ast-version, -customStgAstVersion <astver>
                          1 = original AST, 4: like version of asn1scc where inner types are replaced with referenced types
    --icduper, -icdUper <uper icd output file>
                          Produces an Interface Control Document for the input ASN.1 grammar for uPER encoding
    --customicduper, -customIcdUper <custom stg colon out filename>
                          Invokes the custom stg file 'stgFile.stg' using the icdUper backend and produces the output file
                          'outputFile'
    --icdacn, -icdAcn <acn icd output file>
                          Produces an Interface Control Document for the input ASN.1 and ACN grammars for ACN encoding
    --customicdacn, -customIcdAcn <custom stg colon out filename>
                          Invokes the custom stg file 'stgFile.stg' using the icdAcn backend and produces the output file
                          'outputFile'
    --icdpdus, -icdPdus [<asn1 type assignments list>...]
                          A list of type assignments to be included in the generated ICD.
    --adauses, -AdaUses   Prints in the console all type Assignments of the input ASN.1 grammar
    --acnd, -ACND         creates ACN grammars for the input ASN.1 grammars using the default encoding properties
    --word-size, -wordSize <wordSize>
                          Defines the size of asn1SccSint and asn1SccUint types. Valid values are 8 bytes (default) and 4 bytes. If
                          you pass 4 then you should compile the C code -DWORD_SIZE=4. (Applicable only to C.)
    --fp-word-size, -fpWordSize <fpWordSize>
                          Defines the size of the REAL type. Valid values are 8 bytes (default) which corresponds to double and 4
                          bytes which corresponds to float. If you pass 4 then you should compile the C code -DFP_WORD_SIZE=4.
                          (Applicable only to C.)
    --slim, -slim         Generate Integer and Real types based on the ASN.1 range constraints and/or on ACN encoding properties.
                          E.g. MyInt ::=INTEGER (0..255) becomes a uint8_t instead of asn1SccUint.
    --target, -t <x86|stm32|msp430|allboards>
                          Specify Ada configuration profile. (Applicable only to Ada.)
    --version, -v         displays version information
    --debug-asn1, -asn1 [<string>]
                          Prints all input ASN.1 grammars in a single module/single file and with parameterized types removed. Used
                          for debugging purposes
    --mapping-functions-module, -mfm <string>
                          The name of Ada module or name of C header file (without extension) containing the definitions of mapping
                          functions
    --debug, -debug       Option used internally for debugging
    --streaming-mode, -sm Streaming mode support
    --init-globals, -ig   generate const globals for types initialization. Applicable only to C.
    --help                display this list of options.

Additional links and information

Read this article to get a detailed overview of ASN1SCC basic and advanced features.

Check this presentation of ASN1SCC showing the tool in a wider perspective (and introducing ACN)

Check the ACN User Manual to know more about ACN.

Check this detailed and documented example to learn in practice how to use ASN.1 and ACN to model satellite telecommands and telemetries (TM/TC) following ESA's Packet Utilization Standard (PUS)

And if you are using TASTE, check this system example that builds full TM/TCs including CRC and Length fields.

License

ASN1SCC is released under a GPL license with runtime exception. This means that the runtime (asn1crt.c, acn.c, etc.) is not subject to GPL restrictions and you can link it with your code. The automatically-generated code (types, encoders, decoders, etc.) is also not subject to any license.

Credits

The main author of ASN1SCC is George Mamais from LamdaSoft. Lamdasoft is providing commercial support to users.

Additional contributions and maintenance from Thanassis Tsiodras, Maxime Perrotin, Elias Chatzigeorgiou, Konrad Grochowski and others...

Retrieved from "https://taste.tuxfamily.org/wiki/index.php?title=Technical_topic:_ASN1SCC_-_ESA%27s_ASN.1_Compiler_for_safety-critical_embedded_platforms&oldid=1868"