ASNSDK TCE-C
Version 2.1 enhancements
This section presents the new services and the improvements added to the TCE-C v2.0 release.
Runtime performances optimizations
The runtime has been enhanced to improve the performances (both space and time).Some of these improvements have to be explicitly enabled by the user:
- The choice of the memory management,
- The removal of code unused in the user configuration.
The other improvements do not need any user action.
New optional memory managements
The v2.1 release introduces two new optional memory management features:- A basic memory management,
- A memory management with memory-leak survey.
These optional memory management features can be used alone or together.
Usual memory management
This memory management is used for all objects created and destroyed with the asnCtxAlloc and asnCtxFree functions.
This memory management is straightforward but it can produce a large number of memory requests when complex values are encoded or decoded.
In some cases, to reduce the number of memory requests, the runtime asks for a large memory block in which it can satisfy several smaller memory requests. The size of this large memory block is configurable using the asnCAD10_TMPALLOCSIZE macro definition (2000 bytes by default).
Basic memory management
Instead of calling the asnllalloc macro for each small memory request, the runtime calls the asnllalloc macro only for large memory blocks in which it can satisfy several smaller memory requests. Furthermore, the large blocks are only freed when the context is destroyed.
The basic memory management has several advantages:
- It reduces largely the time used to allocate memory,
- It reduces to almost 0 the time used to free the memory,
- It saves the code of the destructors of the values.
But it has also some drawbacks:
- When the context used to allocate the memory is destroyed, the memory is freed. So, when the context is destroyed, the user must not keep references to data stored in this memory.
- Space can be wasted when the size of the large memory blocks is badly configured.
This feature is enabled by defining the asnCodBalloc macro in the ascupdef.h file.
The size of the large memory blocks is configurable using the asnCAD12_BALLOCSIZE macro definition (10200 bytes by default).
Memory management with memory-leak survey
When this feature is enabled, the context keeps track of all memory allocations and memory releases that go through the ASNSDK memory management. When the context is destroyed, all unreleased memory blocks are released.
Depending on the trace configuration, it is possible to:
- Trace the number of unreleased memory blocks,
- Trace each memory allocation and memory release,
- Dump the content of the unreleased memory blocks.
This feature has some requirements:
- When the context used to allocate the memory is destroyed, the memory is freed. So, when the context is destroyed, the user must not keep references to data stored in this memory.
This feature is a debug feature that is CPU time and memory space consuming. Its use should be avoided when high performances are required.
This feature is enabled by defining the asnCodXalloc macro in the ascupdef.h file.
New features removable from the runtime
The ascupdef.h file contains the definition of preprocessor flags governing the features of the runtime. By removing some definitions of this file, it is possible to reduce the size of the runtime.It is now possible to remove the source code used for the encoding trace (asnCodETRA flag).
It is now possible to remove the source code used for the REAL type (asnREAL flag).
Putting the runtime into ROM
On embedded systems, the use of ROM (Read-Only Memory) is preferred over the use of RAM (Read-Write Memory).The runtime uses read-only initialized data (can be put in ROM) and dynamically allocated read-write memory (needs RAM).
The sole exception to this rule is the asnTraceMask global variable. Note that the runtime does never modify the value of this variable.
The v2.1 runtime uses the asnConst macro (mapped to the const keyword) for read-only initialized data.
New debugging trace feature
The v2.1 introduces a debugging trace feature.Several traces are available:
- Trace of the number of unreleased memory blocks,
- Trace of each memory allocation and memory release,
- Dump the content of the unreleased memory blocks,
- Trace of each error returned on the user API.
The enabled traces are defined by the asnTraceMask global variable in the asccstz.c file. By default, only the trace of the number of unreleased memory blocks is enabled (but the memory management with memory-leak survey is disabled by default).
By default, the trace functions write on the standard error file stderr. It is possible to customize these trace functions to adapt them to the user needs. They are located in the asccstz.c file and the aiccstz.c file.
Better support of the REAL type
The support of the REAL type has been enhanced on several points:- ASN.1:2002 new features are supported (floating-point notation in the abstract syntax, MINUS-ZERO value and NOT-A-NUMBER value),
- If a base constraint is applied to a REAL type, the runtime produces an encoding satisfying the base constraint whenever possible, that is, the runtime may change the base of a REAL value during the encoding (for example, a REAL value using base 2 is converted to base 10 during PER encoding if the type is constrained to the base 10),
- A REAL value can be expressed in floating-point format on the API,
- The runtime rounds a REAL value to the nearest value supported by the API function used to get it.
Enhancement of the encoding trace
The encoding trace dumps an encoded value:- In binary or hexadecimal format (existing feature, in hexadecimal by default),
- And optionally in ASCII format (new feature enabled by calling casnSetAsciiEncodingTrace(context,asnTRUE)).
For XER, the encoding trace has now the same output as for BER and PER. If an error occurs during the decoding, the encoding trace now traces the encoded value up to the point where the decoding stopped.
HTML documentation
The runtime contains now comments using the Javadoc convention defined by the Java language (see http://java.sun.com/j2se/javadoc/).Thus any tool that can recognize Javadoc comments in a C source code using macros can be used to generate an HTML documentation of the C API.
We recommended the use of the Doxygen tool. If this tool is not yet installed on your computer, you can obtain it from http://www.stack.nl/~dimitri/doxygen/.
The runtime is delivered with an HTML documentation of its API generated using the Doxygen tool. This HTML documentation replaces the annexes of the Runtime Programmer’s Guide.
The code generated by the compiler contains also these Javadoc comments. Thus it is possible to obtain an HTML documentation of the generated API.