![]() |
![]() |
![]() |
![]() |
![]() |
Encoding and Decoding Functionality
Encoding and Decoding Functions
An encoding function encodes an SDL variable or signal parameter into a bit-pattern according to BER or PER. A decoding function decodes from a PER or BER bit-pattern to an SDL variable or signal parameter. You can access the encoding and decoding functions either from the C code (see C Encoding and Decoding Interface) or from SDL diagrams (see SDL Encoding and Decoding Interfaces).
C Encoding and Decoding Interface
The most common example of implementing coders in C is in the environment file. The SDL to C Compiler automatically generates an environment file with all needed calls. The coders can be accessed from any function or module implemented in C code.
There is one set of functions for BER and one set of functions for PER. The functions are accessed by using macros BER_ENCODE and BER_DECODE, respectively PER_ENCODE and PER_DECODE.
There is also a set of common functions which choose encoding rules dynamically according to the parameter written to the buffer by function BufSetRule(buffer, rule), see Buffer Management Functions. The functions are accessed by using macros ASN1_ENCODE and ASN1_DECODE.
Example 471 Dynamic encoding rules configuration
BufInitWriteMode(buf);BufSetRule(buf, er_PER | er_Aligned);/* PER Aligned will be applied */
ASN1_ENCODE( buf, (tASN1TypeInfo *)&yASN1_MyType1,
(void *)&((yPDP_Sig1)(*S))->Param1));BufSetRule(buf, er_BER | er_Definite);/* BER Definite will be applied */
ASN1_ENCODE( buf, (tASN1TypeInfo *)&yASN1_MyType2,
(void *)&((yPDP_Sig2)(*S))->Param1));BufCloseWriteMode(buf);All the encode and decode macros, ASN1_ENCODE,ASN1_DECODE, BER_ENCODE, BER_DECODE, PER_ENCODE and PER_DECODE have three parameters:
- First parameter:
- The first parameter is a reference to a buffer of type tBuffer (see Types and definitions). During encoding the resulting bit pattern will be stored in a memory section associated with the buffer. The buffer must be in the write mode when the encode function is called, because it writes bytes to the buffer. During decoding a bit pattern will be read from a memory section associated with the buffer. The buffer must be in read mode when the decode function is called, because it reads bytes from the buffer. For more information about buffer handling see Buffer Management System.
- Second parameter:
- Pointer to ASN.1 type information (see ASN.1 Type Information Generated by ASN.1 Utilities). All information that is needed about the type in the ASN.1 specification is represented in this type information. The reference to type information is of type tASN1TypeInfo*. The type information structure is a global variable with a name yASN1_<type name>. The reference to the type information structure is then (tASN1TypeInfo*)&yASN1_<type name>.
- Third parameter:
The buffer macro returns an error code which is a literal from an enumerated type (see Error codes). The return value indicates whether the encoding or decoding procedure was successful or not. If this value is ec_SUCCESS, then procedure was successful.
Example 472 : BER encoding of signal parameter
Message ::= SEQUENCE {id INTEGER,info INFOTYPE}SIGNAL Sig2(Message);BufInitWriteMode(buf);BER_ENCODE( buf,(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(*S))->Param1));BufCloseWriteMode(buf);Example 473 : PER encoding of signal parameters
BufInitWriteMode(buf);PER_ENCODE( buf,(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(*S))->Param1));BufCloseWriteMode(buf);Example 474 : BER decoding of signal parameters
BufInitReadMode(buf);BER_DECODE( buf,(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(S))->Param1));Example 475 : PER decoding of signal parameters
BufInitReadMode(buf);PER_DECODE( buf,(tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(S))->Param1));ASN.1 Type Information Generated by ASN.1 Utilities
The encoder and decoder functions need information about the types from the ASN.1 specifications. This information is stored in type information structures, called type information nodes or simply type nodes. Almost all information about the types that you can find in the ASN.1 specifications is stored in the type information nodes.
The internal structure of the type information nodes is important in an implementation of encoding and decoding functions, but not from the application that calls the functions. There, it is only important to find a reference to a node. The internal details of the type nodes are not described in this section.
The type information nodes are represented in C code as a set of global read-only variables. The information in a node cannot be changed during execution. The nodes are linked to each other by using memory references. The type nodes can be declared as const variables by defining a macro, which means that in some application they can be moved to program memory or read only memory. For more information, see Compilation switches.
The name of a node is yASN1_<type name>. A reference to a type node is simply a memory pointer to the type node cast to a basic type node declaration.
Example 476 : Reference to a type node
- If the type name is Pdu1 in the ASN.1 specification, the reference to the type node is:
- (tASN1TypeInfo*)&yASN1_Pdu1.
The nodes reflect the information in ASN.1 specifications and must be generated by ASN.1 Utilities. ASN.1 Utilities parses and analyzes the ASN.1 information and generates C code containing type nodes. One .c-file and one .h file per ASN.1 module is generated and the files are named <module name>_asn1coder.c and <module name>_asn1coder.h.
SDL Type and Operator Information Generated by the SDL to C Compiler
The encoder and decoder functions also need information generated by the SDL to C compiler, for example declarations of operators and literals for manipulating the translated ASN.1 types. This information is also stored in the type nodes.
ASN.1 utilities generates one SDL package for each ASN.1 module. The SDL to C Compiler generates one .c and .h file for each package, with type and operator information, together with one .ifc file for an external view of the types and operators. For more detailed information about the C code generation see System Interface Header File.
The ASN.1 type information files includes the <package>.ifc files. All relationships are resolved during compile and link time and the information is read-only at execution time.
SDL Encoding and Decoding Interfaces
In the SDL interface, the ASN.1 type information pointer is not seen. It is implicit and derived from the type of the memory pointer.
There are two types of coder interfaces available from within an SDL system: SDL basic interface (see Encoding/decoding the SDL Basic Interface) and SDL extended interface (see Encoding/decoding the SDL Extended Interface). In the SDL basic interface, the buffer reference is replaced with an octet_ string and the encoded bit-pattern is put directly in a variable of octet_string type. In the SDL extended interface, the buffer reference is CoderBuf or CustomCoderBuf.
Encoding/decoding the SDL Basic Interface
You can encode and decode directly from the SDL diagram by using the operators encode and decode.
The syntax of the encode function is:
result:= encode(encoded_octet_string, ASN1_variable)The two parameters of the encode function are defined as:
- encoded_octet_string is an Octet_string that contains the encoded value of the ASN1_variable if the encoding was successful.
- ASN1_variable is the ASN.1 variable to be encoded.
The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see SDL error interface.
The encoded value in the octet string could then be used in a signal sent to an other part of the system or to the environment.
The syntax of the decode function is:
result:= decode(octet_string_to_decode, ASN1_variable)The two parameters of the decode function are defined as:
- octet_string_to_decode is an Octet_string that contains the encoded value to decode.
- ASN1_variable is the ASN.1 variable that will contain the result after the decoding was performed.
The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see SDL error interface.
Encoding/decoding the SDL Extended Interface
As with the Basic SDL Interface you can encode and decode directly from the SDL diagram by using the operators encode and decode.
The syntax of the encode function is:
result:= encode(CoderBuf, ASN1_variable)The two parameters of the encode function are defined as:
- CoderBuf is a type defined in the file CoderBuf.sdl . It is a mapping of the buffer management C-interface (see C interface to buffer management system). For more information about operations at CoderBuf see SDL CoderBuf interface.
- ASN1_variable is the ASN.1 variable to be encoded.
The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see SDL error interface.
The syntax of the decode function is:
result:= decode(CoderBuf, ASN1_variable)The two parameters of the decode function are defined as:
- CoderBuf is a type defined in the file CoderBuf.sdl. It is a mapping of the buffer management C-interface (see C interface to buffer management system). For more information about operations at CoderBuf see SDL CoderBuf interface.
- ASN1_variable is the ASN.1 variable that will contain the result after the decoding was performed.
The function returns an integer, result. If the value is equal to ec_SUCCESS the encoding was successful. For more information about return status see SDL error interface.
How to Include the Extended SDL Interface in Your System
Add the package in the Organizer. In the directory <installation_directory>/sdt/include/ADT/ there are two versions of the BufferInterface package. One for C, CoderBuf.sun, and one for C++, CoderBufCPP.sun . When the package is included in the Organizer, add a use statement of the BufferInterface in your system.
The Extended SDL Interface in the Simulator
You can display the value of a CoderBuf and change it when running the Simulator by using the commands examine-variable and assign-variable. If you have written your own buffer you can add information in the provided files to be able to use them in the Simulator, see below.
Examine CoderBuf
encode_buffer (CoderBuf) = bms_UserBuffer(NM)3'020102'H
bms_UserBuffer is the buffer type, (NM) shows the current mode of the coderbuffer(NoMode, ReadMode or WriteMode), 3 is the length of the coder buffer value in bytes and '020102'H is the value of the coder buffer in octet string form
Limitations:
Examining the value when the coder buffer is in Write Mode is not possible.
If the user has defined a new buffer type other than Small Buffer and User buffer the buffer type will not be displayed.
encode_buffer (CoderBuf) = BufferType(NM)3'020102'H
To display the right buffer type the user has to do some modifications in the write function (yWri_CoderBuf) in the file CoderBuf.sdl.
Only the first 100 bytes of a coder buffer value are displayed during simulation.
Assign new values to a coder buffer:
Command: ass-va encode_buffer 2 '0101'H ReadMode(RM)
encode_buffer (CoderBuf) = bms_UserBuffer(RM)2'0101'H
When you assign value to a coder buffer:
Command: ass-va <length> <value> <Mode>
Length is the length of the value in bytes. Value is the new value (octet string). Mode, the user sets the mode of the coder buffer (Read, Write and No).
In order for the assignment to be successful the user has to give the two first parameters; otherwise the command will not be executed. An error message will be displayed to the user.
If the length of the value passed as parameter is less than the length passed as parameter, extra zeros (0) are added to the octet string to match the length passed by the user. If the length of the value passed as parameter is greater than the length passed as parameter, then the octet string to be assigned will be cut to match the length.
If the user does not choose the buffer mode, the buffer mode will be set to No Mode (default).
Limitations:
If the user has defined a new buffer type other than Small Buffer and User buffer, the user has to do some modifications in the read function (yRead_CoderBuf) in CoderBuf.sdl in order to initiate the new coder buffer to be assigned to the old coder buffer with right coder buffer type.
The maximum size of the coder buffer is assumed to be 128 Mega bytes.
http://www.ibm.com/rational |
![]() |
![]() |
![]() |
![]() |