ASN1C V7.2.x README

This file contains release notes on the latest release of the ASN1C compiler (version 7.2.x).

Contents

• Introduction
• Release Notes
• Compatibility
• Documentation
• UNIX Installation
• Contents of the Release
• Getting Started with C or C++
• Getting Started with Java
• Reporting Problems

Introduction

Thank you for downloading this release of the ASN1C software. ASN1C is an ASN.1 compiler (code generator) capable of parsing and generating C, C++, C#, or Java source code for the most advanced ASN.1 syntax.

This package contains the ASN1C compiler executables and run-time libraries. Documentation is available online at http://www.obj-sys.com/support/asn1c-manuals.php

Release Notes

This release of ASN1C adds the following new capabilities:

Added capability to generate client/server programs in C/C++

The capability to generate client and server programs in C/C++ has been added. This is done using the -client and -server command-line options. Generation of these programs is done using template files, so it is possible for users to modify the base code used in the generation procedure.

Added capability to do template-based code gen in C/C++

The -gen-from-template command-line option was added to support the general capability to generate code using a template file. A template file is a program with placeholders for generated code items which allows substitution to create complete application programs.

Improved PER encode/decode performance

The performance of encoding and decoding messages using PER (both aligned and unaligend) in C/C++ was improvied substatially in the release. This was achieved by doing a significant amount of processing that was being done at run-time to compile time. Improvement of greater than 100% were observed in some test cases.

Addition of simple static memory option

The option to use a simple static block of memory for decoding was added. This is a much simpler alternative to our standard nibble-based algorithm. This option has limited capabilities (free and realloc are not supported and the user must estimate what their maximum use will be up front as expansion of the total memory size is not supported). But it provides substantial performance improvement on decode because the block can be split up very quickly as memory s needed for decoded items.

Use of newer versions of Visual Studio for Windows

Visual Studio 2015 is now default C/C++ compiler used for the C/C++ run-time libraries on Windows and for the compiler itself (v7.1 used Visual Studion 2013). Run-time libraries build with Visual Studio 2017 have also been added. Also, generation of VS 2017 project files is now supported.

gcc 7.x libraries added to Linux distributions

Libraries built with gcc v7.x are now included in Linux distributions. The default libraries continue to use gcc 4.x and optional libraries built with gcc 5, 6, and 7 are included in the packages.

Addition of compiler option to generate COER code

A command-line option (-coer) and GUI option have been added for the generation of Canonical OER code. Previously, this option has to be enabled by setting a flag at run-time. Also, an option for generating unaligned PER code (UPER) has been added to the GUI.

Addition of C++ OER code generation

Generation of C++ code for OER is now possible in v7.2. Previously only C code could be generated for OER.

Elimination of memory leaks

In the past, memory leaks were not of great concern in the compiler because it ran as a command-line tool and exited thus freeing up the memory. But as the compiler engine began to be used in GUI's and other longer runing applications, the leaks became more of an issue. This release eliminates most, if not all, memory leaks that are present between compilations.

Addition of run-time floating license check

We have added support for doing floating license checking using our 3rd-party license manager to the run-time. Previously, this capability only existed for the compiler and temporary licenses were generated for the run-time. This makes it possible for users to build applications for limited use (and thus lower cost) that can be controlled in an environment that does not have Internet access as is needed for an Internet floating (ifloat) license.

Compatibility

• In the Windows SDK, the default version of the C/C++ libraries are now built with Visual Studio 2015. In version 7.1, visual Studio 2013 was the default. Users will need to ensure that they are using Visual Studio 2015 if working with the default version of the libraries, or use the libraries in the c_vs2013 and cpp_vs2013 subdirectories which is where the VS 2013 built libraries now reside.

Documentation

Documentation for this release is available online at the following URL:

http://www.obj-sys.com/support/asn1c-manuals.php

UNIX/Linux Installation

The steps to install ASN1C on a UNIX or Linux system are as follows:

1. Download the ASN1C package that is of interest to you. Packages are available online for Linux (x64 and x86), Solaris (x86), and Mac OSX operating systems. There are different C/C++ versions of these packages containing run-time libraries built with GNU gcc/g++ or native compilers. There is also a Java package available for each of these operating systems.
2. ASN1C for UNIX/Linux is packaged in a gzipped .tar file. To install, unzip the file (gunzip) and untar (tar xf) in any directory. Note that in order to run the sample programs, write access to the sample directories is required, so make sure that you have write access to the base directory where the compiler is installed.
3. After installation is complete, the license for the product must be installed. This can come in two forms - as a license file or a license key value:

   If a license file was provided either on the user's download page or as an E-mail attachment, this file should be copied to the same directory that the ASN1C compiler executable file is located in. This is in the bin subdirectory located under the top-level install directory.

   Alternately, a license key value may have been provided for product activation. This can be used either through the GUI interface by following the on-screen instructions, or by running ASN1C from the command-line using the -lickey switch.

   The compiler should now be operational. The following command can be executed:

   <rootdir>/bin/asn1c

   to verify operation.

Contents of the Release

The following subdirectories contain the following files (note: <installdir> refers to the installation directory that was specified during the installation process):

Base Compiler Package

<installdir>/bin/asn1c

The command-line compiler executable file. This is invoked on ASN.1 or XSD source files to generate C, C++, C#, or Java encode/decode classes and functions. It is recommended you modify your PATH environment variable to include <installdir>/bin to allow the compiler executable to be run from anywhere.

<installdir>/bin/acgui

The compiler graphic user interface (GUI) editor executable file. This GUI guides a user through the process of specifying ASN.1 or XSD source files and options. (Note: this binary is currently only available on Linux and Mac OSX systems).

<installdir>/bin/asn2xsd

ASN.1 to XML Schema (XSD) translation tool.

<installdir>/bin/berfdump
<installdir>/bin/ber2def
<installdir>/bin/ber2indef

Utility programs for operating on BER-encoded files. The first program allows a file to be dumped in a human-readable format. The other two utilities convert files from the use of indefinite to definite length encoding and vice-versa.

<installdir>/bin/dumpasn1

A public-domain ASN.1 BER/DER encoded data dump tool. Thanks to Peter Gutmann for making this available for public use. The full source code for this program can be found in the utils subdirectory of the installation.

<installdir>/bin/xsd2asn1

XSD-to-ASN.1 translation program executable file. This program translates an XSD file to its ASN.1 equivalent as per the ITU-T X.694 standard.

<installdir>/doc

This directory contains documentation files. Note that the bulk of the documentation items are now available online (see the Documentation section above).

<installdir>/scripts

This directory contains Perl script files for doing source code editing and other transformations. The rtport.pl script is included in this release to port existing C/C++ applications that use ASN1C generated code from version 5.8 or lower to be compatible with the latest release of the product.

<installdir>/specs

This directory contains ASN.1 specifications from many standards that have been pre-compiled and tested. In some cases, syntax errors that may have existed in the original standards were fixed.

<installdir>\templates

This directory contains template files for applications such as client and server code generation. It is possible for users to alter these files to customize code that is generated or to add new template files for use with -gen-from-template command-line option.

<installdir>/utils

This directory contains the source code and build makefile for some of the utility programs included in the bin subdirectory.

<installdir>/xsd/lib/asn1.xsd

This directory contains the common XML schema definitions (XSD) library. This contains type mappings for built-in ASN.1 types that do not have an equivalent types defined in XSD.

<installdir>/xsd/sample

This directory contains sample programs related to the conversion of ASN.1 to XML Schema. It also contains the XSD.asn ASN.1 specification which contains the XSD ASN.1 module that is sometimes referenced in ASN.1 files that are the result of an XSD-to-ASN.1 translation.

C/C++ run-time libraries and source files

<installdir>/c/lib/*.a

<installdir>/c/lib/*.so

<installdir>/cpp/lib/*.a

<installdir>/cpp/lib/*.so

The ASN1C run-time static libraries and shared object files. These contain the low-level run-time functions for the various encoding rules supported by ASN1C. Note that the evaluation and development libraries are not fully optimized (they contain diagnostic tracing and are not compiled with compiler optimization turned on). The deployment libraries are fully optimized. Also note that 'lib' is a soft link to a directory containing libraries built with a specific compiler version (for example, libgcc4). To switch libraries, all that needs to be done in to change this soft link and the equivalent soft link to the platform.mk file to point at a different version. See the README file within the c or cpp directory for futher details.

<installdir>/c/lib_opt/*.a

<installdir>/c/lib_opt/*.so

<installdir>/cpp/lib_opt/*.a

<installdir>/cpp/lib_opt/*.so

The optimized version of the ASN1C run-time libraries. This version has all diagnostic messages, error stack trace and text, and non-essential status checks removed. (Note: these libraries are only available in the licensed deployment version of the product). As was the case for the non-optimized libraries, the 'lib_opt' directories are soft links to directories containing libraries built with a specific compiler version (for example, lib_optgcc4).

<installdir>/c/sample_*

<installdir>/cpp/sample_*

The sample directories contain sample programs demonstrating the use of the compiler. There are a set of sample programs that correspond to each encoding rule set supported by ASN1C. Most sample programs are broken down into a writer and a reader. The writer encodes a sample data record and writes it to a disk file. The reader reads the encoded message from the file, decodes it, and then prints the results of the decode operation.

<installdir>/rtsrc/*

<installdir>/rtxsrc/*

Run-time source directories containing common type and class definitions used by all encoding rules. The installation run-time source directories contain the header files required to compile the compiler generated code. The C or C++ source files will also be located here if the run-time source code kit option was selected.

<installdir>/rt*ersrc/*

Run-time source directories for various ASN.1 encoding rules. These contain common code for encoding and decoding using the specific rules. Directories are currently present for BER/DER/CER, PER, MDER, OER, and XER rules.

<installdir>\rtjsonsrc\*

JSON specific run-time source directory. These contain common code for encoding/decoding JSON messages.

<installdir>/rtxmlsrc/*

XML specific run-time source directory. These contain common code for encoding/decoding XML messages.

<installdir>\expatsrc\*

The XML parser run-time source directories contain the source files for the Expat C XML parser. This is only maintained to provide backward compatibility with SAX-based XML code (-sax option). The default parser used is now our internally developed XML pull-parser.

<installdir>\libxml2src\*

The LibXML2 parser run-time source directories contain the source files for the GNOME libxml2 C XML parser. This is only maintained to provide backward compatibility with SAX-based XML code (-sax option). The default parser used is now our internally developed XML pull-parser.

Java run-time libraries

<installdir>/java/asn1rt.jar

ASN.1 Java run-time libraries. These contain the low-level encode/decode classes for the various encoding rules supported by ASN1C. The asn1rt.jar file contains classes compatible with the Java 5 JRE.

<installdir>/java/sample_*

Sample programs illustrating the use of the Java version of ASN1C. As was the case for C/C++, most have a writer and a reader. Some contain support code used by other samples (for example, SimpleROSE contains the ROSE headers used by CSTA).

<installdir>/java/doc/*

The ASN.1 Java run-time libraries documentation files. These are html files generated with the javadoc documentation tool. To view the documentation, open the index.html file with a web browser and follow the hyperlinks.

<installdir>\java\xmlpull\*

The kXML pull-parser implementation. This parser is used in the generated XER and XML decode classes.

<installdir>\java\xerces\*

The Apache Xerces Java XML parser implementation. This parser is used to support legacy SAX parsing in the generated XER and XML decode classes. Note that SAX parsing is a deprecated feature at thie time.

Getting Started with C or C++

The compiler must be run from a command shell prompt. The sample progams were developed using the bash shell and should be compatible with the sh and ksh shells. Users of the C-shell (csh) will probably need to make some modifications.

1. Open a terminal window.

• Change directory (cd) to one of the employee sample directories (for example, c/sample_ber/employee).

• Execute the make utility program:

  make

  This should cause the compiler to be invoked to compile the employee.asn sample file. It will then invoke the C or C++ compiler to compile the generated C file and the test drivers. The result should be a writer and reader program file which, when invoked, will encode and decode a sample employee record.

• Invoke writer from the command line:

  writer

  This will generate an encoded record and write it to a disk file. By default, the file generated is message.dat (in the case of XER, it is message.xml). The test program has a number of command line switches that control the encoding. To view the switches, enter writer ? and a usage display will be shown.

• Invoke reader from the command line:

  reader

  This will read the disk file that was just created by the writer program and decode its contents. The resulting decoded data will be written to standard output. The test program has a number of command line switches that control the encoding. To view the switches, enter reader ? and a usage display will be shown.

Getting Started with Java

To run a simple test from the command line, do the following:

1. Open a terminal window.
2. Change directory (cd) to one of the employee sample directories (for example, java/sample_ber/Employee).
3. Execute the makefile:

   make

   This will cause the ASN1C compiler to be invoked to compile the employee.asn sample file. It will then invoke the Java compiler (javac) to compile all generated java files and the reader and writer programs (Note: JDK 6 was used to build all the run-time library classes). It will also automatically execute the writer and reader programs. These programs will produce a writer.log and reader.log file respectively.

4. View the writer and reader log files. The writer.log file will contain a dump of the encoded message contents. The reader.log file will contain a printout of the decoded data.

Reporting Problems

Report problems you encounter by sending E-mail to support@obj-sys.com. The preferred format of example programs is the same as the sample programs. Please provide a writer and reader and indicate where in the code the problem occurs.

If you have any further questions or comments on what you would like to see in the product or what is difficult to use or understand, please communicate them to us. Your feedback is important to us. Please let us know how it works out for you - either good or bad.