User Manual ASAP2 Lib. Version 4.5 English

Transcription

1 User Manual ASAP2 Lib Version 4.5 English

2 Imprint Vector Informatik GmbH Ingersheimer Straße 24 D Stuttgart Vector reserves the right to change the information and data in this document at any time without prior notice. This document may not be duplicated or transmitted, in whole or in part, in any manner or by any means, without the express written permission of Vector. To the extent permitted by law, all technical information, text, images, and graphics, including their layout, are subject to the applicable laws for protection of intellectual property and, in particular, to protection of copyright. Any unauthorized use may constitute a violation of these provisions. Copyright 2018, Vector Informatik GmbH. Printed in Germany. All rights reserved.

3 Contents Contents 1 Introduction ASAP2 Lib Overview About This User Manual Certification Warranty Support Trademarks Activation Reading in ASAP2 Files Callback Methods DLL Methods for Writing of ASAP2 Files Data Types/Structures Predefined Data Types Data Structures IF_DATA Handling Structure of BLOBs Data Structure of BLOBs Deviations from the ASAP2 Standard 20 3 Addresses 24 Vector Informatik GmbH Version II -

4 Introduction 1 Introduction In this chapter you will find the following information: 1.1 ASAP2 Lib Overview page About This User Manual page 4 Certification Warranty Support Trademarks Vector Informatik GmbH Version

5 Introduction 1.1 ASAP2 Lib Overview This documentation describes the functionality and application of the ASAP2 Parser library, or ASAP2 Lib for short. Function library for reading in ASAP2 files Programming language Support Objective Prior knowledge The ASAP2 Lib is a function library that can be used to read in ASAP2 files of version 1.x including current version The section that is defined by the ASAP2 specification as well as the ASAP2 meta language and the resulting variable IF_DATA sections are all read in. The library was developed for the C/C++ programming language and can be integrated into C/C++ projects. Supported platforms are Windows XP, Windows 7, and Windows 8.x. The Microsoft Visual C++ development environment is supported. The function library can be linked to the application statically or dynamically as a DLL. This document is oriented to software developers who want to integrate the library into their own applications. Knowledge of the ASAP2 specification is required for understanding this document. The ASAP2 data structures are not explained in detail here. 1.2 About This User Manual To Find information quickly Conventions This user manual provides you with the following access help: > At the beginning of each chapter you will find a summary of the contents. > The header shows in which chapter of the manual you are. > The footer shows the version of the manual. In the two tables below you will find the notation and icon conventions used throughout the manual. Style ASAP2 Lib Source code Hyperlink Symbol Utilization Legally protected proper names and marginal notes. File and directory names, source code, class and object names, object attributes and values Hyperlinks and references Utilization This icon indicates notes and tips that facilitate your work. This icon warns of dangers that could lead to damage. This icon indicates examples. Vector Informatik GmbH Version

6 Introduction Certification Quality Management System Vector Informatik GmbH has ISO 9001:2008 certification. The ISO standard is a globally recognized standard Warranty Restriction of warranty We reserve the right to modify the contents of the documentation or the software without notice. Vector disclaims all liabilities for the completeness or correctness of the contents and for damages which may result from the use of this documentation Support Need help? You can reach our hotline by telephone at +49 (0) or by at canape-support@vector.com Trademarks Protected trademarks All brand names in this documentation are either registered or non-registered trademarks of their respective owners. > Windows XP, Windows 7, Windows 8 und Microsoft Visual C++ are trademarks of Microsoft Corporation. Vector Informatik GmbH Version

7 2 This chapter contains the following information: 2.1 Activation page Reading in ASAP2 Files page Callback Methods page DLL Methods for Writing of ASAP2 Files page Data Types/Structures page 12 Predefined Data Types Data Structures 2.6 IF_DATA Handling page 14 Structure of BLOBs Data Structure of BLOBs 2.7 Deviations from the ASAP2 Standard page 20 Vector Informatik GmbH Version

8 2.1 Activation Initialization DLL method Return value The first step in initializing the DLL license is to call the following DLL method: ASAP2LIB_API VErrorCode SetLicenseKey( const char *customername, const char *serialnumber, const char *registrationkey ); The information supplied with the delivered DLL must be assigned as parameters. Only after this method delivers the return value kerrorcodeok, further DLL methods can be used successfully. 2.2 Reading in ASAP2 Files Callback method for each object type Reading in an ASAP2 file In order to read in an ASAP2 file using the ASAP2 Lib, the application must define a so-called callback method for each object type of the ASAP2 language. During reading by the parser, C structures for the read-in objects are passed to these callback methods where they can be further processed as desired. The following DLL method is available for reading in an ASAP2 file. ASAP2LIB_API VErrorCode ParseFile( void *userdata, char *filename, bool onlyaml, char *directorylist[], VASAP2ToleranceSettings *tolerancesettings, VASAP2CallbackMethods callbackmethods, bool createtokenlist, int language ); Parameters of DLL Method ASAP2ParseFile userdata filename onlyaml directorylist tolerancesettings This parameter can be used to pass a pointer to any data of the application, which is forwarded by the parser to the callback methods. As a result of this, it can be ensured, for example, that multiple ASAP2 files can be read in parallel in a multithread architecture. File path of the ASAP2 file to be read in. If this parameter has the value true, it signals to the parser that not a complete ASAP2 file but rather only an AML description is to be read in. Accordingly, the file to be read in may then only contain an A2ML block. This parameter can be used to specify a list of directories in which the parser is to search for include files when these cannot be located in the current directory. These settings can be used to configure a certain error tolerance for the parser (see section Deviations from the ASAP2 Standard on page 20). Vector Informatik GmbH Version

9 Parameters of DLL Method ASAP2ParseFile callbackmethods createtokenlist language Parsing the ASAP2 file Parsing of ASAP2 code This parameter is used to communicate to the parser the callback methods that must be notified about new objects during reading (see section Callback Methods on page 9). This parameter is used to specify how the parser is to handle IF_DATA information. If the parameter has the value true, a token list is generated for each IF_DATA description, which contains the original texts and formatting from the ASAP2 file and which has not undergone a syntax check against the AML. If necessary, the application itself must carry this out in a subsequent step. If the parameter has the value false, the syntax of the IF_DATA descriptions is checked against the existing AML. If syntactically correct, binary BLOBs are generated from this (see section IF_DATA Handling on page 14). This parameter specifies the language for error messages, warnings, and other information that the parser forwards to the application. The following languages are currently supported: > 01 for English > 49 for German If the parser finds an object in the ASAP2 file a callback method is defined for, a C structure is created, initialized according to the content of the ASAP2 file, and passed to the callback method. These data can then be used as desired in the callback method of the application. Alternatively, it is possible to parse ASAP2 code from a string. An easily modified DLL method is available for this: ASAP2LIB_API VErrorCode ParseString( void *userdata, char *buffer, int length, bool onlyaml, char *directorylist[], VASAP2ToleranceSettings *tolerancesettings, VASAP2CallbackMethods callbackmethods, bool createtokenlist, int language ); Additional Parameters of DLL Method ASAP2ParseString buffer length String to be parsed that contains the ASAP2 code String length of the buffer All other parameters correspond to those of the above-described DLL method ASAP2ParseFile on page 7. Vector Informatik GmbH Version

10 2.3 Callback Methods Implementation C structure Exceptions Status messages Parameter for synchronization Collection in a structure Dedicated callback methods are available for all ASAP2 objects within a module (e.g., MEASUREMENT or CHARACTERISTIC objects). These must be implemented in the application program and made known to the parser. If individual object types are not of interest to an application, the associated callback methods do not need to be implemented. The callback methods are always called up during reading by the parser when a corresponding object has been found in the ASAP2 file. A C structure is defined for each object type containing the corresponding object attributes. This C structure is built by the parser after reading in an object and passed to the corresponding callback method, provided this is configured. The structure can then be further processed as desired in the callback method. Exceptions are the callback methods for the ASAP2 objects PROJECT and MODULE. To generate these structures, practically the complete file would have to be read in and transferred to the structure. For this reason, the callback methods for these two structures are called up once at the beginning of the object and once at the end of the object. At the call at the beginning of the object, the data from the mandatory fields such as module name and project header are passed to the callback method. When the parser reaches the end of the structure, it calls up the corresponding callback method a second time. This time, however, a null pointer is used in order to inform the application about the change of context. Besides the callback methods for the individual ASAP2 objects, there are also other callback methods for diagnostic purposes, such as: > Communication of error messages and warnings to the application > Status information regarding the current position of the parser during reading (source file and line number) All callback methods have, in addition to the actual ASAP2 data, an additional parameter that can be used by the application for synchronization. In this parameter, the ASAP2 parser forwards the data that were specified by the application at the parser call to the callback methods (see userdata on page 7). The callback methods are collected in a structure and must be passed at the parser call. typedef struct { int (*callbackerrordetailed)(void*, int, char*, long, char*, char*); int (*callbackwarning)(void*, int, char*); int (*callbackinformation)(void*, char*); int (*callbackerror)(void*, int, char*); int (*callbacklineinformation)(void*, A2L_LINEINFO*); int (*callbackasap2version)(void*, A2L_ASAP2_VERSION*); int (*callbackifdatablob)(void*, A2L_IF_DATA_BLOB*); int (*callbackifdatatokenlist)(void*, A2L_TOKEN*); int (*callbackmodule)(void*, A2L_MODULE*); int (*callbackproject)(void*, A2L_PROJECT*); int (*callbackheader)(void*, A2L_HEADER*); int (*callbackmodpar)(void*, A2L_MOD_PAR*); int (*callbackmodcommon)(void*, A2L_MOD_COMMON*); Vector Informatik GmbH Version

11 int (*callbackcharacteristic)(void*, A2L_CHARACTERISTIC*); int (*callbackblob)(void*, A2L_BLOB*); int (*callbackaxispts)(void*, A2L_AXIS_PTS*); int (*callbackmeasurement)(void*, A2L_MEASUREMENT*); int (*callbackcompumethod)(void*, A2L_COMPU_METHOD*); int (*callbackcomputab)(void*, A2L_COMPU_TAB*); int (*callbackcompuvtab)(void*, A2L_COMPU_VTAB*); int (*callbackfunction)(void*, A2L_FUNCTION*); int (*callbacktransformer)(void*, A2L_TRANSFORMER*); int (*callbackrecordlayout)(void*, A2L_RECORD_LAYOUT*); int (*callbackframe)(void*, A2L_FRAME*); int (*callbackgroup)(void*, A2L_GROUP*); int (*callbackcompuvtabrange)(void*, A2L_COMPU_VTAB_RANGE*); int (*callbackuserrights)(void*, A2L_USER_RIGHTS*); int (*callbackvariantcoding)(void*, A2L_VARIANT_CODING*); int (*callbackunit)(void*, A2L_UNIT*); int (*callbackinclude)(void*, const char*, const char*); int (*callbacka2ml)(void*, bool); int (*callbacka2mlversion)(void*, A2L_A2ML_VERSION*); int (*callbackcomment)(void*, const char*, const char*, long); int (*callbackamltree)(void*, AML_MEMBER *aml); } VASAP2CallbackMethods; Callback method NULL Return value for further action Retaining structures Canceling the parsing For information that is not relevant in an application, the corresponding callback method can be NULL. All callback methods must communicate to the parser via the return value whether the structures it created can be released or whether these are continuing to be used by the application. If the A2L_CB_NO_DELETE flag is set in the return value, the structures are retained and must be released later by the application. Corresponding DLL methods are available for this. Otherwise, the parser destroys the structure after call up of the callback method. Furthermore, the return value of the callback methods can be used to control whether the ASAP2 file is to continue to be parsed or (e.g., after an error message) the parsing is to be canceled. The A2L_CB_CANCEL flag must be set in the return value for this. 2.4 DLL Methods for Writing of ASAP2 Files Defining a class The ASAP2 Lib also provides methods for writing the C structures defined by the parser to an ASAP2 file. To make use of these write methods, the application must define a class that implements the IFileWriter interface. From this interface the DLL write methods call the following method that must implement the actual output to a file. virtual void Printf(const char *string); Vector Informatik GmbH Version

12 Write methods A simple sample implementation is included in the supplied demo program. The following write methods are available in the DLL: ASAP2LIB_API void WriteAmlTree(IFileWriter *fp, AML_MEMBER *tree); ASAP2LIB_API void WriteIfDataBlob(IFileWriter *fp, AML_MEMBER *amltree, A2L_IF_DATA_BLOB *bloblist, int insertlevel); ASAP2LIB_API void WriteAsap2Version(IFileWriter *fp, A2L_ASAP2_VERSION *version); ASAP2LIB_API void WriteA2mlVersion(IFileWriter *fp, A2L_A2ML_VERSION *version); ASAP2LIB_API void WriteHeader(IFileWriter *fp, A2L_HEADER *header); ASAP2LIB_API void WriteProjectStart(IFileWriter *fp, A2L_PROJECT *project); ASAP2LIB_API void WriteProjectEnd(IFileWriter *fp); ASAP2LIB_API void WriteModuleStart(IFileWriter *fp, A2L_MODULE *module); ASAP2LIB_API void WriteModuleEnd(IFileWriter *fp); ASAP2LIB_API void WriteIfDataTokenList(IFileWriter *fp, A2L_IF_DATA_TOKEN *head, int insertlevel); ASAP2LIB_API void WriteModPar(IFileWriter *fp, A2L_MOD_PAR *modpar, AML_MEMBER *amltree); ASAP2LIB_API void WriteModCommon(IFileWriter *fp, A2L_MOD_COMMON *modcommon); ASAP2LIB_API void WriteMeasurement(IFileWriter *fp, A2L_MEASUREMENT *measure, AML_MEMBER *amltree); ASAP2LIB_API void WriteTypedefMeasurement(IFileWriter *fp, A2L_TYPEDEF_MEASUREMENT *measure); ASAP2LIB_API void WriteAxisPts(IFileWriter *fp, A2L_AXIS_PTS *axis, AML_MEMBER *amltree); ASAP2LIB_API void WriteTypedefAxis(IFileWriter *fp, A2L_TYPEDEF_AXIS *axis); ASAP2LIB_API void WriteTypedefStructure(IFileWriter *fp, A2L_TYPEDEF_STRUCTURE *structure); ASAP2LIB_API void WriteInstance(IFileWriter *fp, A2L_INSTANCE *instance, AML_MEMBER *amltree); ASAP2LIB_API void WriteCompuTab(IFileWriter *fp, A2L_COMPU_TAB *table); ASAP2LIB_API void WriteCompuVtab(IFileWriter *fp, A2L_COMPU_VTAB *table); ASAP2LIB_API void WriteCompuVtabRange(IFileWriter *fp, A2L_COMPU_VTAB_RANGE *table); ASAP2LIB_API void WriteFunction(IFileWriter *fp, A2L_FUNCTION *function, AML_MEMBER *amltree); ASAP2LIB_API void WriteTransformer(IFileWriter *fp, A2L_TRANSFORMER *transformer); ASAP2LIB_API void WriteCompuMethod(IFileWriter *fp, A2L_COMPU_METHOD *conversion); ASAP2LIB_API void WriteCharacteristic(IFileWriter *fp, A2L_CHARACTERISTIC *characteristic, AML_MEMBER *amltree); ASAP2LIB_API void WriteTypedefCharacteristic(IFileWriter *fp, A2L_TYPEDEF_CHARACTERISTIC *characteristic); ASAP2LIB_API void WriteBlob(IFileWriter *fp, A2L_BLOB *blob, AML_MEMBER *amltree); ASAP2LIB_API void WriteTypedefBlob(IFileWriter *fp, A2L_TYPEDEF_BLOB *blob); ASAP2LIB_API void WriteGroup(IFileWriter *fp, A2L_GROUP *group, AML_MEMBER *amltree); ASAP2LIB_API void WriteRecordLayout(IFileWriter *fp, A2L_RECORD_LAYOUT *layout); ASAP2LIB_API void WriteFrame(IFileWriter *fp, A2L_FRAME *frame, AML_MEMBER Vector Informatik GmbH Version

13 *amltree); ASAP2LIB_API void WriteUserRights(IFileWriter *fp, A2L_USER_RIGHTS *user); ASAP2LIB_API void WriteVariantCoding(IFileWriter *fp, A2L_VARIANT_CODING *varcoding); ASAP2LIB_API void WriteUnit(IFileWriter *fp, A2L_UNIT *unit); 2.5 Data Types/Structures Definitions All data objects from the ASAP2 specification are mapped onto data structures of the C programming language. The corresponding definition is located in the ASAP2.H file. The names from the ASAP2 specification have been largely adopted for this, whereby all names are written in uppercase and preceded by A2L_ Predefined Data Types Predefined The predefined data types in the ASAP2 specification are mapped onto the following data structures: ASAP2 Definition string ident float int long Datatype Datasize Addrtype Byteorder Indexorder Data Structure of ASAP2 Parser A2L_STRING A2L_IDENT A2L_FLOAT A2L_INT A2L_LONG A2L_DATATYPE A2L_DATASIZE A2L_ADDRTYP A2L_BYTE_ORDER A2L_INDEXORDER Data Structures Prefixed A2L_ For most other keywords of the ASAP2 specification, a C structure with the same name and prefixed A2L_ is defined. Example: For the ASAP2 keyword MEASUREMENT, a C structure A2L_MEASUREMENT is defined as follows: struct { A2L_DIDENT A2L_DSTRING A2L_DATATYPE A2L_DIDENT A2L_UINT name; long_identifier; data_type; conversion; resolution; Vector Informatik GmbH Version

14 A2L_FLOAT A2L_FLOAT A2L_FLOAT A2L_BYTE_ORDER A2L_MAX_REFRESH A2L_ID_LIST A2L_ID_LIST A2L_UINT A2L_BOOL A2L_DSTRING A2L_DSTRING A2L_DIDENT A2L_INT64 A2L_INT64 A2L_DIDENT A2L_ANNOTATION A2L_ULONG A2L_INT A2L_BIT_OPERATION A2L_MATRIX_DIM A2L_SYMBOL_LINK A2L_DSTRING A2L_BOOL A2L_INDEX_MODE A2L_IF_DATA_BLOB A2L_IF_DATA_TOKEN_LIST A2L_DDDRTYP }; accuracy; lower_limit; upper_limit; *byte_order; *max_refresh; *virt; *function_list; *array_size; read_write; format; phys_unit; display_identifier; *bit_mask; *error_mask; ref_memory_segment; *annotation; *ecu_address; *ecu_address_extension; *bit_operation; *matrix_dim; *symbol_link; model_link; discrete; *layout; *if_data_blob; *if_data_token_lists; *address_type; Attributes Pointer The first section up to and including upper_limit contains the fixed attributes from the ASAP2 specification. These must be present for each measurement object in the ASAP2 file. The remaining structure components starting from byte_order represent optional attributes. A pointer only refers to a corresponding substructure if the attribute in the ASAP2 file has also actually been defined. Otherwise it is NULL. Definition of callback methods Callback methods can be defined for the following C structures: > A2L_IF_DATA_BLOB > A2L_IF_DATA_TOKEN > A2L_ASAP2_VERSION > A2L_PROJECT > A2L_HEADER > A2L_MODULE > A2L_MOD_PAR > A2L_MOD_COMMON > A2L_BLOB Vector Informatik GmbH Version

15 Substructures > A2L_CHARACTERISTIC > A2L_AXIS_PTS > A2L_MEASUREMENT > A2L_COMPU_METHOD > A2L_COMPU_TAB > A2L_COMPU_VTAB > A2L_FUNCTION > A2L_RECORD_LAYOUT > A2L_COMPU_VTAB_RANGE > A2L_GROUP > A2L_FRAME > A2L_USER_RIGHTS > A2L_VARIANT_CODING > A2L_UNIT > A2L_TRANSFORMER > A2L_INSTANCE > A2L_TYPEDEF_STRUCTURE > A2L_TYPEDEF_MEASUREMENT > A2L_TYPEDEF_BLOB > A2L_TYPEDEF_CHARACTERISTIC > A2L_TYPEDEF_AXIS All other objects are substructures that are generally referred to from the higher-level structures using pointers. Substructures that can occur multiple times are stored as chained lists. They contain a next pointer that refers to the next object. Example: Chained list with next pointer typedef struct id_list { A2L_IDENT name; struct id_list *next; } A2L_ID_LIST; 2.6 IF_DATA Handling No fixed structure Information communication Specification Because the syntax and semantics of the IF_DATA structures are not specified in the ASAP2 specification but rather are defined dynamically using the AML contained in the ASAP2 file, there is no fixed predefined structure for the IF_DATA information. The application has two basic ways of receiving the IF_DATA information from the parser: > Using binary BLOB objects or > Using so-called token lists When the parse method is called (see above), the form the application would like to have the IF_DATA information must be specified. Depending on that, there are also Vector Informatik GmbH Version

16 two different callback methods: > int (*callbackifdatablob)(void*, A2L_IF_DATA_BLOB*); Token list Binary BLOBs > int (*callbackifdatatokenlist)(void*, A2L_IF_DATA_TOKEN*); When token lists are used, the parser collects the original texts and formatting from the ASAP2 file in so-called tokens (= words) and passes them to the application in a chained list. In so doing, no syntax check is made against the AML contained in the ASAP2 file. If necessary, the application itself must carry this out in a subsequent step. When binary BLOBs are used, the syntax of the IF_DATA information is checked against the AML and the data with correct syntax are coded in a binary BLOB having a fixed generic structure. The application must know the syntax and semantics of the corresponding AML exactly, in order to correctly interpret this BLOB. If the syntax of the IF_DATA description is incorrect, no binary BLOB is generated. A reconstruction of the original formatting from the binary BLOB is not possible Structure of BLOBs Binary Large Object Language Structure A BLOB (Binary Large Object) is a block made up of binary data. The arrangement of the binary data within the BLOB is specified by the definition of the object involved in the ASAP2 meta language AML. The BLOBs are structured in such a way that the objects are stored in a fixed order if possible. However, because there are data types having a variable size, e.g. unions or lists with variable number, these variable objects in the BLOB receive a header with a fixed length. Information on the object and a reference to the actual object data are stored in this header. The following applies generally: > All multibyte values are stored in the Intel convention. > The size of a BLOB is generally limited to 64 kbytes Storage of structs Objects of fixed size A struct contains objects with a fixed size. These are objects with predefined data types such as CHAR, INT, FLOAT, or DOUBLE and objects assembled from these such as arrays or structures. They are stored in the BLOB in the order of their definition in the AML. Example: AML definition: struct { int; char; int; } ASAP2 data for this object 0x x9876 Vector Informatik GmbH Version

17 BLOB resulting from this: ff Storage of taggedstructs Objects with tag Objects with tag prefix are optional. So that the evaluator of the BLOB can recognize whether an object with a certain tag has been defined, a reference to the actual object data is used. This reference is two bytes long, is stored in Intel format in the BLOB, and is located at the position in the BLOB where the object would be if objects without tag were being used. The reference points to the byte position within the BLOB where the actual object data are located. If the reference is a null pointer, the optional object has not been defined in the IF_DATA. Objects with tag prefix can only be used in a taggedunion or taggedstruct. Example: AML definition: taggedstruct { "T1" int; "T2" int; } ASAP2 data for this object: T1: 0x1122 BLOB resulting from this: Explanation For the fields marked with T1 and T2, two bytes each are reserved for the references. Because T1 is in the data area, the actual data (0x1122) are appended to the end of the BLOB (byte position 4). This byte position of the data is entered as a reference. Because no data are present for T2, Null is entered as the reference Storage of taggedunions Objects with tag and index Because unions can have a variable size (similar to objects with tag), a reference to the actual data is also used here. An index with a size of two bytes is additionally added as a prefix to the tag to indicate which component of the union was instantiated in IF_DATA. The counting for this starts with one. The fixed content of a taggedunion is always four bytes long. Example: AML definition: taggedunion { "U1" int; "U2" char; } Vector Informatik GmbH Version

18 ASAP2 data for this object: U2 0x55 BLOB resulting from this: Explanation The first two bytes in the BLOB indicate which variant of the taggedunion was selected, in this case, 2 for U2. The next two bytes refer to the beginning of the data area, which in this example directly follows (byte position 4). In a more complex environment, however, the data area does not have to directly follow the end of the fixed section Storage of enums Enumeration types Enumeration types are stored in the BLOB as two-byte values (such as int). The numerical value corresponds to the definition in the AML section Storage of Lists With Variable Number Lists with variable number Lists with variable number are stored similarly to objects with tag. First there is a reference to the data area. The number of list elements found is located in the data area before the actual payload data. The number is coded with two bytes Complex Example Example: A more complex example shows the interpretation of the binary BLOBs: AML definition: /begin A2ML block "IF_DATA" taggedunion { "U1" taggedstruct { ( "PART1" struct { char; } )*; block "PART2" struct { uint; char; taggedstruct { "OPT1" uint; "OPT2" uint; }; }; }; }; /end A2ML Vector Informatik GmbH Version

19 ASAP2 data: /begin IF_DATA U1 PART1 0x11 PART1 0x22 PART1 0x33 PART1 0x44 /begin PART2 0xaabb 0xcc OPT2 0xffee /end PART2 /end IF_DATA BLOB resulting from this: 0000: e bb aa 0010: cc ee ff Vector Informatik GmbH Version

20 Address/Byte Position (hex) Value Meaning 2 bytes (integer value 1): Instantiated taggedunion component (1 for U1) byte pointer (integer value 4): Reference to BLOB position 04 at which the actual data of U1 are saved Data for the taggedstruct components of U1: 2-byte pointer (integer value ): Reference to BLOB position 08 at which the data of the PART1 component are saved 06 0e Data for the taggedstruct components of U1: 2-byte pointer (integer value xE): Reference to BLOB position 0E at which the data of the PART2 component are saved Data for PART1: The first 2 bytes (integer value 4) give the number of PART elements found, because PART1 may occur multiple times. 0A 11 0B 22 0C 33 0D 44 4 data bytes for 4 PART1 elements 0E bb 2-byte value: First attribute (uint) of PART2 0F aa 10 cc 1-byte value: Second attribute (char) of PART byte pointer (value 0): Reference to the BLOB position for the OPT1 data (the value 0 signals that OPT1 data are not present) byte pointer (value 0x15): Reference to the BLOB position for the OPT2 data 15 ee 16 ff 2-byte value: Payload data of OPT2 Fixed size or header All data objects within a BLOB thus have either a fixed size or a fixed header. This allows applications to easily skip reading parts that are not of interest to them. For example, in the example above it is not necessary to determine the length of PART1 in order to be able to access the data of PART2. Vector Informatik GmbH Version

21 2.6.2 Data Structure of BLOBs Representation For the representation of binary BLOBs, the following data structure is used in the ASAP2 Lib: typedef struct s_a2l_if_data_blob A2L_IF_DATA_BLOB; struct s_a2l_if_data_blob { char *name1; char *name2; A2L_IF_DATA_BLOB_DATA *blob, A2L_IF_DATA_BLOB_DATA *qp_blob, A2L_IF_DATA_BLOB_DATA *tp_blob, A2L_IF_DATA_BLOB_DATA *dp_blob, A2L_IF_DATA_BLOB_DATA *pa_blob, A2L_IF_DATA_BLOB_DATA *kp_blob, A2L_IF_DATA_BLOB_DATA *source_blob; A2L_IF_DATA_BLOB *next; }; typedef struct s_a2l_blob_data A2L_IF_DATA_BLOB_DATA; struct s_a2l_blob_data { unsigned int len; unsigned char *data; A2L_IF_DATA_BLOB_DATA *next; } Names Parameter blob Data In the A2L_IF_DATA_BLOB structure, the parameters name1 and name2 receive the names that were used to define the object in the ASAP2 file. In the case of IF_DATA objects, name1 always contains the character string IF_DATA and name2 the character string that follows that, which is generally the tag for the taggedunion. The parameter blob refers to the entire binary data of the BLOB. In order to simplify the evaluation for the application, the IF_DATA objects can also be read in according to the ASAP1b specification. The pointers to a subset of the binary data are additionally available for this: QP_BLOB, KP_BLOB, TP_BLOB, DP_BLOB, and PA_BLOB. These structures are only generated by the parser if the name of the BLOB is IF_DATA, the structure is a taggedunion, and lower-level structures with the corresponding names exist. Otherwise these pointers are initialized with null. The actual data are always stored in an object of type A2L_IF_DATA_BLOB_DATA. len describes the length of the data, data points to a field with the data bytes. The next pointer can point to a next block. This is the case when substructures were evaluated according to ASAP1b specification and there are multiple objects of one type. 2.7 Deviations from the ASAP2 Standard Correct syntax The ASAP2 parser is able to read in ASAP2 files with correct syntax, i.e., files that conform to ASAP2 standard 1.70 or earlier. Vector Informatik GmbH Version

22 Tolerance for syntax errors Expansion of the tolerance Structure with tolerance setting For ASAP2 files that contain syntax errors, a corresponding error message is normally generated. However, since many ASAP2 files in circulation are not correct and these have to be read in nevertheless, the parser tolerates small errors and can be made to tolerate even larger errors through a special configuration. The following errors are always tolerated by the parser: > Semicolons are often incorrectly set in the ASAP2 meta language. For this reason, missing or extra semicolons are accepted by the parser whenever possible. > The block bracketing with /begin and /end in the fixed section specified in the ASAP2 standard has been mandatory since ASAP2 V1.20. To allow older files without bracketing to be read, the old notation is tolerated whenever possible. The option also exists to configure the parser in such a way that it tolerates additional syntax errors in an ASAP2 file to be read in and thereby outputs only a warning if necessary. When the parse method is called, the following structure with tolerance settings must be passed: typedef struct { int allowspecialsyntax; char specialidentcharacters[128]; char specialidentcharactersforbegin[128]; bool suppresslongidentifier; bool ignoreunknownifdata; bool ignoreaml; bool supportnestedcomments; int predefinedasap2version; } VASAP2ToleranceSettings; Meaning of parameters in combination with flags allowspecialsyntax Certain flags for tolerating syntax errors can be combined in this parameter: > kallowspecialformatsyntax If this flag is set, missing quotation marks in the following string are tolerated in case of ASAP2 keyword FORMAT. > kallowidentsstartwithdigit If this flag is set, it is accepted that identifiers begin with a digit. However this only applies outside the AML area. > knocasesensitivityinifdata If this flag is set, upper and lower case spelling is ignored for the keywords defined in the AML. > kallowkeywordsassymbol If this flag is set, the majority of the ASAP2 keywords are also accepted as identifiers. > kallowsymbolasstring If this flag is set, identifiers are accepted as strings, i.e., missing quotation marks in strings are tolerated provided the string contains no blank spaces or consists only of characters that conform to requirements for identifiers. Vector Informatik GmbH Version

23 Meaning of parameters in combination with flags > kallowdifferentblockbrackets If this flag is set, inconsistencies in the block bracketing between AML and associated IF_DATA (i.e., missing or additional /begin /end bracketing) are tolerated. > kallowspecialprojectnosyntax If this flag is set, numbers are accepted in addition to identifiers after the ASAP2 keyword PROJECT_NO. > kallowreservedwithdatatype If this flag is set, the Datatype values UBYTE, SBYTE, UWORD, SWORD, ULONG, and SLONG are accepted in addition to the Datasize values BYTE, WORD, and LONG after the ASAP2 keyword RESERVED within a RECORD_LAYOUT. > kallowkeywordsofnewerversion If this flag is set, the parser outputs no warnings when keywords of a higher ASAP2 version are used than under ASAP2_VERSION. Meaning of the specialident Parameters specialidentcharacters This parameter can be used to allow additional characters within ASAP2 identifiers. According to the ASAP2 standard, only letters, digits, underscores, dots, and square brackets are permitted in identifiers. However, the parser attempts to tolerate all additional characters within an identifier that are contained in the specialidentcharacters string. specialidentcharactersforbegin This parameter can be used to allow additional characters for the beginning of an ASAP2 identifier. According to the ASAP2 standard, identifiers may only begin with letters or underscores. However, the parser attempts to tolerate all characters as the first character of an identifier that are contained in this string. Caution: Extreme caution must be exercised when using these two parameters. Only specify those additional characters here that are absolutely necessary. If the character strings contain blank spaces, for example, the entire parser no longer works. Meaning of Other Parameters suppresslongidentifier Up to ASAP2 version 1.51 the length of identifiers was limited to 255 characters. Starting from version 1.60, identifiers with a length of up to 1024 characters are also permitted. If this parameter has the value true, all identifiers are limited to a maximum length of 255 characters, regardless of the ASAP2 version. ignoreunknownifdata ignoreaml If this parameter has the value true, the parser skips reading IF_DATA blocks for which no AML description is present without an error message. If this parameter has the value true, the parser skips reading the complete AML description as well as all IF_DATA blocks. Vector Informatik GmbH Version

24 Meaning of Other Parameters supportnestedcomments According to the ASAP2 specification, multi-line comments must not occur as nested comments. If you set this parameter to true, the parser accepts nested comments in the file to be read in nevertheless. predefinedasap2version You can use this parameter to specify the ASAP2 version that is to be used as the basis for the syntax check if the file to be read in contains no information about the ASAP2 version. If the file contains version information, this information always takes precedence. Caution: If the parser is configured in this way, it no longer conforms to the ASAP2 standard! Spillover effects (e.g., incomprehensible messages about follow-on syntax errors) cannot be ruled out! Vector Informatik GmbH Version

25 Addresses 3 Addresses Addresses on Vector homepage Please find the contacts of Vector Informatik GmbH and all subsidiaries worldwide via: Vector Informatik GmbH Version

26 More Information > News > Products > Demo Software > Support > Training Classes > Addresses