![]() |
![]() |
![]() |
![]() |
![]() |
Structure and Configuration
An application with ASN.1 encoding or decoding support contains the following:
- Encoding and decoding functions. One set of functions for BER encoding and decoding and one set of functions for PER encoding and decoding.
ASCII encoding and decoding, which is based on SDL Suite internal encoding rules is also available. ASCII encoding and decoding is described in SDL Data Encoding and Decoding, ASCII coder.
- Buffer management functions.
- Error management functions (optional).
- Print functions (optional).
- ASN.1 type information generated by the ASN.1 Utilities.
- SDL type and operator information generated by the SDL C code generators.
Files and File Descriptions
This section describes the static file structure of the coder directories in the installation.
The coder directory contains five sub-directories which correspond to the functional modules in the coder library:
- coder/er - this directory contains three sub-directories which correspond to different encoding rules supported by the coder library.
- coder/bms - Buffer Management System files.
- coder/ems - Error Management System files.
- coder/mms - Memory Management System files.
- coder/vms - Value Management System files.
There are also several files included to the root coder directory:
- cucf.h - main header file of the coder library. It includes all useful header files from the library functional modules.
- cucf_cfg.h - standard C library includes, like <stdio.h>, <sdtlib.h> and others.
- cucf_er.h - declarations of main encode and decode coder interface functions.
- cucf_er.c - definition of main encode and decode coder interface functions.
- cucf_er_sdt.h - declarations of SDL Suite specific encode and decode interface functions which are used for encode and decode within SDL support.
- cucf_er_sdt.c - definition of SDL Suite specific encode and decode interface functions which are used for encode and decode within SDL support.
- cucf_er_ttcn.h - declarations of TTCN Suite specific encode and decode interface functions which are used for encode and decode within TTCN support.
- cucf_er_ttcn.c - definition of TTCN Suite specific encode and decode interface functions which are used for encode and decode within TTCN support.
- coderascii.h, coderber.h, coderper.h, coderucf.h - these files are not used inside the library, but provide backwards compatibility solutions for the SDL systems created with the previous versions of SDL coder support.
Encoding rules sub-directory
Sub-directory coder/er contains three sub-directories corresponding to different types of encoding rules supported by the coder library:
- ascii
- This directory contains files with encoding and decoding function according to internal rules of the SDL Suite. The ASCII coders are described in SDL Data Encoding and Decoding, ASCII coder.
- ber
- This directory contains files with encoding and decoding functions according to BER (Basic Encoding Rules), see BER sub-directory.
- per
- This directory contains files with encoding and decoding functions according to PER (Basic Encoding Rules), see PER sub-directory.
BER sub-directory
Sub-directory coder/er/ber contains the following files:
- ber.h - header file with declaration of BEREncode and BERDecode functions.
- ber_base.h - contains declarations of basic functions needed by the encode and decode functions.
- ber_base.c - contains implementation of basic functions needed by encode and decode functions.
- ber_content.h - contains declarations of functions that encode and decode ASN.1 predefined types.
- ber_content.c - contains implementation of functions that encode and decode ASN.1 predefined types.
- ber_decode.c - definition of main outermost function BERDecode which references functions from ber_base and ber_content modules.
- ber_encode.c - definition of main outermost function BEREncode which references functions from ber_base and ber_content modules.
PER sub-directory
Sub-directory coder/er/per contains the following files:
- per.h - header file with declaration of PEREncode and PERDecode functions.
- per_base.h - contains declarations of basic functions needed by the encode and decode functions.
- per_base.c - contains implementation of basic functions needed by encode and decode functions.
- per_content.h - contains declarations of functions that encode and decode ASN.1 predefined types.
- per_content.c - contains implementation of functions that encode and decode ASN.1 predefined types.
- per_decode.c - definition of main outermost function PERDecode which references functions from per_base and per_content modules.
- per_encode.c - definition of main outermost function PEREncode which references functions from per_base and per_content modules.
Buffer Management System sub-directory
Sub-directory coder/bms contains the following files:
- bms.h - base buffer management declarations, this header contains base buffer control structure definitions. This is the main header file for buffer management.
- bms.c - implementation of base buffer functions which are common for all types of buffers.
- bms_small.h - small buffer management specific declarations.
- bms_small.c - implementation of small buffer management.
Error Management System sub-directory
Sub-directory coder/ems contains the following files:
- ems.h - error management declarations. This is the main header file for coder error handling.
- ems.c - implementation of common error management functions.
- ems_eo_sdt.h - SDT specific error management declarations and includes.
- ems_eo_sdt.c - implementation of SDT specific error handling functions.
- errors.h - declaration of error codes and error information.
Memory Management System sub-directory
Sub-directory coder/mms contains the following files:
- mms.h - declarations of pure memory handling macros CUCF_ALLOC and CUCF_FREE and safe memory management functions CUCFAlloc and CUCFFree (see Memory Management System). This is the main header file for coder memory handling.
- mms.c - implementation of safe memory handling functions.
Value Management System sub-directory
Sub-directory coder/vms contains the following files:
- vms.h - this is the main header file for value management system, it contains includes of all other useful header files from this folder.
- vms_type.h - definitions of types used in ASN.1 type nodes.
- vms_macro.h - definitions of macros which are used for declaration and filling ASN.1 type structure nodes. Calls to these macros are generated by ASN.1 coder generator.
- vms_vr_sdt.h - definitions of macros which are used for inserting SDL Suite specific information to ASN.1 type structure nodes. Calls to these macros are generated by ASN.1 coder generator only for SDL Suite coder generation.
- vms_vr_ttcn.h - definitions of macros which are used for inserting TTCN Suite specific information to ASN.1 type structure nodes. Calls to these macros are generated by ASN.1 coder generator only for TTCN Suite coder generation.
- vms_export.h - type node declarations for predefined ASN.1 types, such as BOOLEAN, INTEGER, BIT STRING, OCTET_STRING, NULL, OBJECT IDENTIFIER, REAL, string types.
- vms_export.c - type node definitions for predefined ASN.1 types.
- vms_internal.h - internal value representation type and macro definitions.
- vms_base.h - declarations of internal value representation access procedures.
- vms_base.c - implementation of internal value representation access procedures.
- vms_check.h - declarations of check procedures.
- vms_check.c - implementation of procedures that perform error checking of type nodes and values.
- vms_print.h - declarations of print procedures used for test and debug purposes.
- vms_print.c - implementation of print procedures used for test and debug purposes.
Compilation switches
You can change the default properties and configure the BER and PER coders by setting the compilation switches. Some of these switches can be set by choosing options in the Targeting Expert, see The Targeting Expert.
Available compile switches can be separated onto several groups. Below there are descriptions of compile switches that can be used to configure the behavior of coder functions.
Encoding rules configuration
Removing runtime encoding rules availability
- CODER_REMOVE_ASCII - compile coding library without ascii encoding rules available at runtime
- CODER_REMOVE_BER - compile coding library without BER encoding rules available at runtime
- CODER_REMOVE_PER - compile coding library without PER encoding rules available at runtime
- CODER_USE_UER - add user defined encoding and decoding functions to be available at runtime (file "uer.h" will be used during library compilation)
By default all the library included ascii, ber and per encoding rules to be present in the compiled object library.
Choosing default encoding rules
This compilation switches influence on which encoding rules will be applied when the coder function is called without specifying which type of encoding rules should be applied
- CODER_ER_DEFAULT_PER - use PER as default encoding rules
- CODER_ER_DEFAULT_BER - use BER as default encoding rules
- CODER_ER_DEFAULT_UER - apply USER encoding rules by default
The default setting is CODER_ER_DEFAULT_BER.
- CODER_BER_DEFINITE - use definite length form encoding for BER by default
- CODER_BER_INDEFINITE - use indefinite length form encoding for BER by default
The default setting is CODER_BER_INDEFINITE.
- CODER_PER_NO_ENDPAD - use PER unaligned without end padding as default encoding rules
- CODER_PER_ALIGNED - use PER aligned as default encoding rules
- CODER_PER_UNALIGNED - use PER unaligned as default encoding rules
The default setting is CODER_PER_UNALIGNED.
- CODER_BER_CONSTRUCTED - use constructed form of BER by default
- CODER_BER_PRIMITIVE - use primitive form of BER by default
The default setting is CODER_BER_PRIMITIVE.
- CODER_BER_CONSTRUCTED_LENGTH=<number> - use <number> as length of constructed sequence of bytes for BER
The default setting is CODER_BER_CONSTRUCTED_LENGTH=1000.
- CODER_BER_CANONICAL_ON - restrict BER decode for SET type by canonical order.
- CODER_BER_CANONICAL_OFF - BER decode for SET type as defined in ITU X.690.
The default setting is CODER_BER_CANONICAL_ON.
Real values encoding
For encoding real values are divided into the following number values: (sign * 2^factor * number * base^exponent). It is the user option to choose which factor and which base should be used when encoding.
- CODER_BER_REAL_FACTOR_0 - use real factor 0 for coding
- CODER_BER_REAL_FACTOR_1 - use real factor 1 for coding
- CODER_BER_REAL_FACTOR_2 - use real factor 2 for coding
- CODER_BER_REAL_FACTOR_3 - use real factor 3 for coding
- CODER_REAL_BASE_2 - use real base 2 for encoding
- CODER_REAL_BASE_8 - use real base 8 for encoding
- CODER_REAL_BASE_16 - use real base 16 for encoding
The default setting is CODER_BER_REAL_FACTOR_0 and CODER_REAL_BASE_2.
Error checking configuration
- CODER_CHECK_NONE - remove all error checks from compiled library
- CODER_CHECK_NONE_VALUE - remove error checks of input values to encoding and decoding function from the compiled library
- CODER_CHECK_NONE_BUFFER - remove error checks in buffer management from the compiled library
- CODER_CHECK_NONE_DECODING - remove error checks in decoding functions from the compiled library
- CODER_CHECK_NONE_INNER - remove internal error checks in encoding and decoding functions from the compiled library
By default all checks are switched ON.
Encoding configuration
You can use the following switches to remove code for ASN.1 type from the compilation:
- CODER_NOUSE_BOOLEAN
- CODER_NOUSE_INTEGER
- CODER_NOUSE_NULL
- CODER_NOUSE_OBJECT_IDENTIFIER
- CODER_NOUSE_REAL
- CODER_NOUSE_BIT_STRING
- CODER_NOUSE_OCTET_STRING
- CODER_NOUSE_CHARACTER_STRING - NumericString, PrintableString, IA5String, VisibleString, UTCTime, GeneralizedTime
- CODER_NOUSE_ENUMERATED
- CODER_NOUSE_ENUMERTAED_ITEMS - ENUMERATED items if they are 0 1 2 3 etc
- CODER_NOUSE_SEQUENCE
- CODER_NOUSE_SET
- CODER_NOUSE_SET_OF
- CODER_NOUSE_SEQUENCE_OF
- CODER_NOUSE_CHOICE
- CODER_NOUSE_OPEN
- CODER_NOUSE_EXT - extension marker in ASN.1 sequence and set
You can use the following switches to redefine C type for ASN.1 type information field:
- CODER_ENUMERATED_TYPE=<type> - enumerated value. Default is "long"
- CODER_TagNumber_TYPE=<type> - ASN.1 tag class number. Default is "unsigned long"
- CODER_NumOf_TYPE=<type> - number of components. Default is "unsigned long"
- CODER_INTEGER_LBOUND_TYPE=<type> - low bound in integer constraint. Default is "long"
- CODER_INTEGER_UBOUND_TYPE=<type> - upper bound in integer constraint. Default is "long"
- CODER_SIZE_LBOUND_TYPE=<type> - low bound in size constraint. Default is "unsigned long"
- CODER_SIZE_UBOUND_TYPE=<type> - upper bound in size constraint. Default is "unsigned long"
These compile switches can be set automatically. asn1util generates asn1_cfg.h file for the -c option where the above compile switches are included after #define directives to minimize coder library code size automatically, see also Configuration file generation. To be able to use this asn1_cfg.h automatic configuration you should define the following compile switch:
- CODER_AUTOMATIC_CONFIG - enables automatic configuration generated to the asn1_cfg.h file. This switch can be set by choosing the corresponding option in the Targeting Expert.
Buffers configuration
- CODER_BMS_SMALLBUF - uses small buffer implementation. The second argument of BufInitBuf interface - type of the buffer (see tBMSBufType) will not be in use for this case.
- CODER_REMOVE_SMALLBUF - removes small buffer code from the compiled library
The default is including only small buffers to the library. When all buffers are absent, then only a null buffer will be available (a null buffer is a stub buffer without any functionality).
- CODER_USE_USERBUF - includes the user buffer into the library to be available at runtime
- CODER_BMS_USERBUF - uses the user buffer implementation if it is made available by previous switch
- CODER_BMS_TINY - uses a minimum set of bms interfaces. Interfaces to operate with buffer mode, character segment, bytes, bits also copy buffer interface are not available for this switch. It is allowed to use both buffer access types tBuffer and tCoder in this mode.
Example 487 : Encoding in tiny mode
tCoder coder;tBMSUserMemory UserMemory;BufInitBuf(&coder, bms_SmallBuffer);ASN1_ENCODE(&coder,(tASN1TypeInfo *)&yASN1_Message,encValue);BufCloseBufToMemory(&coder, &UserMemory);...BufInitBufWithMemory(&coder, &UserMemory);ASN1_DECODE(&coder,(tASN1TypeInfo *)&yASN1_Message,decValue);BufCloseBuf(&coder);CUCF_FREE(UserMemory.MemPtr, UserMemory.MemSize, 0);Example 488 : tBuffer access type in tiny mode
tBuffer buf = NULL;BufInitBuf(buf, bms_SmallBuffer);
The buffer value for this mode must be initialized by NULL before being used in buffer management. The behavior will otherwise be unpredictable.
Following buffer interfaces are not available in this mode:
- BufGetMode, BufInNoMode, BufInReadMode, BufInWriteMode
- BufCopyBuf
- BufInitWriteMode, BufCloseWriteMode
- BufInitReadMode, BufCloseReadMode, BufCloseDeleteReadMode
- BufGetByte, BufPeekByte, BufPutByte
- BufGetSeg, BufSkipSeg, BufPeekSeg, BufPutSeg
- BufPutBit, BufGetBit, BufPutBits, BufGetBits
The default setting for the size is CODER_SMALLBUF_SIZE=0x1000.
Memory management configuration
- CODER_MMS_SDT - use SDT alloc/free procedures when working with memory in the coder library functions
- CODER_MMS_USER - apply user defined alloc/free functions when working with memory in the coder library functions (file "mms_user.h" will be added for library compilation)
By default standard malloc and free functions from <stdlib.h> are used.
Error output configuration
- CODER_EO_SDT - use SDT error output functions (when this switch is turned on, SDT error output switch XECODER can influence error output functionality)
- CODER_EO_USER - apply user defined error output procedures to the library and use them for error output (file "ems_eo_user.h" will be added for library compilation)
- CODER_EO_DEBUG - use internal library functions for printing error messages
- CODER_EO_NONE - do not output error messages text
The default setting is CODER_EO_SDT.
Error handling configuration
- CODER_PATH_DEEP=<number> - nesting coefficient. It depends on the ASN.1 specification. The nesting coefficient is the maximum number of nested SEQUENCE, SET, CHOICE, SEQUENCE OF, SET OF or open types. By default CODER_PATH_DEEP is defined to 16. If the nesting coefficient in the ASN.1 specification is greater then 16 then you should define the CODER_PATH_DEEP compile switch with this value yourself, otherwise "segmentation fault" error will occur. The nesting coefficient for the following example is 4:
MySeq ::= SEQUENCE { -- NC=4a MyChoice,b NULL}MySet ::= SET { -- NC=1a INTEGER,b BOOLEAN}MyChoice ::= CHOICE { -- NC=3a MySeqOf,b MySetOf}MySeqOf ::= SEQUENCE OF MySet -- NC=2MySetOf ::= SET OF BOOLEAN -- NC=1- CODER_REMOVE_PATH - do not use detailed error messages (see Detailed error messages) and user error handling (see User defined Error Handling)
User data configuration
- CODER_USER_DATA - include tUserData defined in the user_data.h into the coder buffer, see User Data
Value management configuration
- CODER_VMS_SDT - use SDT value interface when accessing external values from the encoding and decoding functions (this switch comes together with SDT switch XUSE_GENERIC_FUNC, which chooses generic value representation out of two available value representations for SDT/C values, by default it is turned off and old (backwards compatible) value representation is used)
- CODER_VMS_TTCN - use TTCN value interface when accessing external values from the encoding and decoding functions
- CODER_VMS_USER - choose user value interface for accessing external values from the encoding and decoding functions (file "vms_vr_user.h" must be edited to configure user value access, it is included for library compilation)
By default CODER_VMS_SDT is chosen.
Printing configuration
- CODER_VMS_PRINT - enable debug printing opportunities (see Printing Opportunities)
By default the coder library is compiled without debug printing functionality.
Generating Environment Files with Coding
You can call the encoding and decoding functions from the environment functions if you do not want to manipulate the encoded bit pattern explicitly in your SDL system.
The SDL Suite tools generate templates for the environment files that contains all necessary calls to buffer management functions, encoding functions and decoding functions. You can, of course, adapt this template to your needs or even write all the calls yourself. See Building an Application or The Cmicro SDL to C Compiler.
The template solution in the environment files has the following properties:
- One global buffer reference created at start-up of system. This buffer reference is used in all calls for all signals and for both encoding and decoding.
- All signals out from the system are encoded into bit-patterns. All parameters of the signals are encoded.
- All signals into the system decodes bit-patterns.
Compiling and Linking
The instructions you must perform in order to compile and link are listed in Tutorial: Using ASN.1 Data Types.
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |