BSW Module Naming Convention and File Structure

Basic Software modules follow the same general specification. Sure, each of them will work in a different way, implementing their own unique functionality, but the basis for all of them is the same. In this article, we will discuss all the common elements to BSW modules, namely their naming convention and file strcuture, always keeping in mind that there can be exceptions, but this is the general rule.

BSW requirements are placed inside the requirements documents, and each of them contains a unique identifier, structured as [SRS_<Ma>_<number>], where Ma is the Module Abbreviation, and the number corresponds to the unique identifier of the requirement. Autosar specification documents contain specification items, defined as [SWS_<Ma>_<number>]. The Module Abbreviation can also be found completely capitalized, as MA.

The work products of a BSW module implementation, all the APIs, parameters, symbols, and file names are prefixed by a Module Implementation Prefix (Mip), which is comprised of the Module Abbreviation and optionally a Vendor ID (vi) and a Vendor API Infix (ai), as <Ma>[_<vi>_<ai>]. The optional elements become mandatory when there are multiple instances of the same BSW module. Both the optional elements can be found on the BSW Module Description (BSWMD) file.

Moreover, Complex Device Drivers and Transformers do not follow this rule, as their Module Implementation Prefix is derived from their apiServiceInfix element.

File Structure

The mandatory and optional files that are part of a BSW module are defined in the table below:

The optional Ie refers to an implementation-specific file name extension. It can be used to better separate each part of the module into smaller, more manageable files.

Keep in mind, your BSW provider is allowed to deliver you only part of the source code, such as the configuration sources, with the rest being provided as object files. This depends on agreements related to intellectual property and other bureaucracies.

The BSW module documentation includes some information relevant to the module, including the version number, date and history, a functional overview, a list of the source files with a brief description, the deviations from the requirements and specification, the microcontroller resources used, an integration description with the interactions / dependencies with other modules, a description of the configuration parameters and some examples relating to the correct API usage and module configuration. If the module depends on the microcontroller functionality, its information should be included in the documentation too. This includes the vendor, family, derivative, revision (if applicable), toolchain name, version, and options. The scheduling strategy of the module should also be present, documenting the execution order of the scheduled functions implemented by the BSW module.

Moreover, rules and constraints to the configuration that are used as plausibility checks while configuring the module should also be documented. Optionally, there can also be information about the memory footprint of the module and the configuration that lead to such a footprint result. This can also be present as a formula that associates the number of configuration elements to the amount of memory they consume, as they grow in number in the configuration.

The header files should only import the information from other modules needed to fulfill the functional requirements of the module. Upon generation, the Autosar toolchain needs to verify that such modules are present in the configuration. The same applies to the exported information, as this should also be limited to the information required by other modules. When the module has been configured, some of this information can become irrelevant, as it was not used within the configuration. As stated before, this can be spread across multiple files, depending on the implementation-specific file extension.

The implementation source files include the declaration of constants, global data types and functions used internally by the module, except for the pre-link time configuration parameters. Of course, these files include the header of the module, so that the compiler can assess module consistency. Within these files, we can see some module dependencies that are common across most, if not all the BSW modules:

• Starting with the Memory Mapping (MemMap), denoted by <Mip>_MemMap.h. These are generated for each BSW module.

• If the module requires the BSW Scheduler functionality or implements BswSchedulableEntitys, then it should include the Module Interlink Header file, SchM_<Mip>.h.

• If production error reporting is required, the Diagnostic Event Manager (Dem) should be included, via Dem.h. The same is valid for development errors, through the Development Error Tracer (Det) module, through Det.h.

• If access to callbacks from other modules is required, these module header files should be included, unless these callbacks come from the application layer, which in that case the RTE header file for the relevant application module is to be included.

Moreover, if the module implements Interrupt Service Routines, these should be provided in separate implementation files. This is necessary because of their microcontroller-dependent nature, making it easier to identify which files cannot be used in other microcontrollers and therefore be implemented again in such situations. If there are declarations for both CAT1 and CAT2 interrupts, the category must be selectable in the configuration of the BSW module. Interrupt frames are the microcontroller-specific code that prefixes and postfixes the execution of each ISR. Their implementation is separated from the ISRs, having their own interrupt frame implementation source files. This is done to allow for better flexibility. The implementation of interrupt frames for a BSW module are located within <Mip>[_<Ie>]_Irq.c. If callouts are used within a BSW module, these are placed in their specific header file, <Mip>_Externals.h. This header file is self-contained. This header is then included in the file that implements it, to check for consistency.

As for the pre-link time and post-build time configuration source files, these can be absent, depending on if configuration parameters exist in the respective configuration classes or not. Link time configuration parameters are defined as const, and the implementation source files can be called the same as pre-compile time configuration files (<Mip>[_<Ie>]_Cfg.c), if this configuration class is not present.

Moreover, there are a couple of reasons to set parameters that could have been of the pre-compile pre-link time configuration classes to post-build time parameters. Firstly, in case they need to be changed for a new post-build time configuration, and second if they take part in a structure that contains post-build time parameters, requiring the entire structure to be placed within a post-build time configuration source file.

The implementation header of the BSW module includes the APIs of it, and it is comprised of at least a single file, <Mip>.h, but, as stated before, there can be multiple header files, distinguished by the implementation-specific name extension, <Mip>[_<Ie>].h. These header files include at least the extern declarations of constants, global data, and services provided to other BSW modules.

The implementation header does not include the prototype declarations of MainFunctions and BswModuleClientServerEntrys that are invoked by both the RTE and BswScheduler modules.

To avoid inconsistencies regarding the data types of BSW modules and Software Components, the RTE_Type.h header file is used to declare the data types that are common to them. It is indirectly a dependency to the BSW modules, as it is included by the application types header file, Rte_<swc>_Type.h (where swc is the Software Component Type, Mip in the case of BSW modules), which can in turn is included by the BSW modules, for those that implement Autosar services. These header files are created by the RTE generator.

Another header file common to practically all the BSW modules is the Std_Types.h header file. It includes all the Autosar Standard Types. This file includes the Platform_Types.h header file, that includes the Platform-Specific Types. Moreover, the Std_Types.h file also defines the Std_ReturnType, along with the symbol pairs E_OK and E_NOT_OK and STD_ON and STD_OFF.

The Rte_<swc>.h header, known as the Application Header File, is generated by the RTE and includes the necessary interfaces for the interaction between the BSW module and the RTE. This header file must not be included in the BSW module files that are included by other modules (either BSW modules or services, directly or indirectly).

Moreover, some modules define a <Mip>_GeneralTypes.h header file, containing types that are to be shared through multiple modules or multiple instances of the same module.

Lastly, all the header files, except for those related to memory mapping, are protected from multiple inclusion (which is a good practice from C, not an Autosar-specific rule), using the same identifier (which the placeholder BSW_MODULE_HEADER_H is illustrating for this purpose), as seen in the code snippet below:

#ifndef BSW_MODULE_HEADER_H
#define BSW_MODULE_HEADER_H

/* module header file contents*/

#endif

As stated before, interoperability is ensured by versioning the Autosar standard. This versioning applies to every BSW module. The integration of BSW modules includes Inter-Module Checks, which are performed upon preprocessing, and consist of verifying that all the modules from which a BSW module depends upon belong to the same Autosar major and minor release as it. If they are not, the modules are deemed incompatible and therefore the integration cannot proceed.

This check relies on the header files included by the module that do not belong to it to find the BSW module dependencies, and the preprocessor macros <MIP>_AR_RELEASE_MAJOR_VERSION and <MIP>_AR_RELEASE_MINOR_VERSION (part of the Published Information of the BSW module) to perform these checks.

This is all for today! Fancy more reading? You can check out our other articles, or maybe get notified when our first ebook is ready, by joining our waiting list.

Author: Micael Coutinho (opens in a new tab)

References:

• General Specification of Basic Software Modules - Autosar (opens in a new tab)