IBM
Contents Index Previous Next



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:

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

In ASN1:

Message ::= SEQUENCE {
                       id    INTEGER,
                       info  INFOTYPE
                     }

In SDL:

SIGNAL Sig2(Message); 

In xOutEnv:

BufInitWriteMode(buf);
BER_ENCODE( buf,
           (tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(*S))->Param1));
BufCloseWriteMode(buf);

Example 473 : PER encoding of signal parameters

In xOutEnv:

BufInitWriteMode(buf);
PER_ENCODE( buf,
            (tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(*S))->Param1));
BufCloseWriteMode(buf);

Example 474 : BER decoding of signal parameters

In xInEnv:

BufInitReadMode(buf);
BER_DECODE( buf,
           (tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(S))->Param1));

BufCloseReadMode(buf);

Example 475 : PER decoding of signal parameters

In xInEnv:

BufInitReadMode(buf);
PER_DECODE( buf,
           (tASN1TypeInfo *)&yASN1_Message,
(void *)&((yPDP_Sig2)(S))->Param1));

BufCloseReadMode(buf);

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:

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.

Figure 505 Example of a encode call in an SDL diagram

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:

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.

Figure 506 Example of a encode call (SDL Basic 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:

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.

Figure 507 : Example of en encode call (SDL Extended interface)

The syntax of the decode function is:

result:= decode(CoderBuf, ASN1_variable)

The two parameters of the decode function are defined as:

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.

Figure 508 : Example of decode call (SDL Extended 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.

Note: Types in the BufferInterface package

In the BufferInterface package BasicCTypes and CPointer or the corresponding C++ versions of those files are included. This must be considered when using cpp2sdl together with your system so that those files are included only once.

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

Command: ex-va encode_buffer

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.

Example:

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)

Value assigned:

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
Contents Index Previous Next