AoU: ETAS_RTACAR_SM_OS_183

This AoU checks that forbidden OS API calls are not made within a critical section protected by SuspendOSInterrupts()/ResumeOSInterrupts(), according to the ETAS_RTACAR_SM_OS_183 requirement and ISO 17356.

The validation procedure ensures that only the following OS API calls are permitted within a SuspendOSInterrupts/ResumeOSInterrupts critical section:

• SuspendAllInterrupts()

• ResumeAllInterrupts()

• SuspendOSInterrupts()

• ResumeOSInterrupts()

All other OS API calls are prohibited within this critical section.

Note

Os function names prefix

Function names generated by adding the “Os_” prefix to the names in the given list of allowed or disallowed OS API functions are also considered part of the original list.

Rationale for the validation

The validation process follows these steps:

1. Generation of the base code call graph

   1. Collection of source code files to be analyzed, as specified by the compile_commands.json file.

   2. Generation of the Abstract Syntax Tree (AST) for each source file.

   3. Processing of the AST to identify function implementations and related calls.

   4. Resolution of all the calls to the linkable target implementation.

2. Inspection of the complete call graph to detect restricted regions.

   1. Detect the start point of each restricted region.

   2. Detect the end point of each restricted region.

3. Inspection of the call graph contained within the restricted regions.

   1. Identify all function calls within the restricted regions.

   2. Check each function call against the list of prohibited calls.

Known Limitations

During the generation of the call graph and the collection of source code files to be analyzed, files with the following extensions are ignored:

• .cpp

• .hpp

• .s

• .S

• .asm

• .inc

The generation of the call graph is based on static analysis of the source code. This means that the tool analyzes the code without executing it, which can lead to certain limitations:

• It may not capture all dynamic behaviors, such as those resulting from runtime conditions or external inputs.

• It cannot account for all possible execution paths, especially in the presence of complex control flows.

• The accuracy of the call graph is dependent on the completeness and correctness of the source code being analyzed.

Important

Link Os as external library functions

This behavior is important for maintaining the integrity of the analysis process. The tool expects that the functions implementing the OS are linked as external library functions, and therefore does not expect the source code for these functions to be available within the analyzed base code.

The tool’s ability to detect function calls is limited by the information available from the source code, and it’s possible that the tool encounters limitations:

Important

Handling of External Functions

The tool may be unable to resolve function calls if their implementations are not available in the analyzed source code, such as functions provided by the OS, RTE, or external libraries.

Important

Analysis Limitations

The tool’s static analysis may not detect all function calls, particularly in cases involving complex code structures or the use of function pointers.

When the start or the end point of a restricted region is contained inside a conditional construct, it may lead to uncertainties in the identification of the restricted region due to the potential for the condition to affect the execution flow.

Example: Restricted region within a conditional construct

Consider the following C code snippet, where the start of a restricted region is inside an if statement:

void example_function(void)
{
    if (condition)
    {
        // Start of restricted region
        startRegion();
    }
    // End of restricted region
    endRegion();
}

This example illustrates how the static analysis tool may struggle to accurately identify the boundaries of restricted regions, when they are nested within conditional constructs.

The tool may not be able to determine all possible execution paths, leading to uncertainty in identifying the exact boundaries of the restricted region. A result indicating a human review may be reported if the analysis cannot definitively establish the boundaries.

Example: Restricted region within the same conditional construct

Consider the following C code snippet, where both the start and end points of a restricted region are inside the if statement:

void example_function(void)
{
    if (condition)
    {
        // Start of restricted region
        startRegion();
        // End of restricted region
        endRegion();
    }
}

In this case, the static analysis tool may have an easier time determining the boundaries of the restricted region, as both the start and end points are clearly defined within the same conditional construct.

The static analysis tool may leverage this information to more accurately identify the restricted region and its boundaries, potentially reducing the need for human review.

When the tool detects a limitation in its analysis, it shall report the issue to the user for manual review, indicating the specific code section that requires attention. Please refer to the OS reviews section for more information on how to handle such cases.

The tool analyzes the code to:

• Detect the boundaries of Suspend/ResumeOSInterrupts critical sections.

• Check that no prohibited OS API calls are made within these sections.

• Report issues if forbidden calls are found.

• Report warnings, as a result indicating human review need, if section identification is not possible due to conditional statements, tool limitations, or the call graph contains unsupported function calls (ie. call by pointer).

Important

Os API call region delimiters

The tool detects the start of a critical region when a call to the Os_SuspendOSInterrupts() function is made. The end of the critical region is detected when a corresponding call to Os_ResumeOSInterrupts() is made.

Function macro delimiters

The following couples of function macros are detected as critical region delimiters:

• SuspendOSInterrupts() / ResumeOSInterrupts()

• Rte_GetResource() / Rte_ReleaseResource()

When the region starts/ends due to a function macro call, the tool will consider the entire macro body as part of the region delimiter, so no further analysis will be performed within the expansion code of the macros.

Attention

The tool recognizes only the listed macros as critical region delimiters. In case of usage of unsupported macros, or new macros mapped to the supported ones, the detection process will be downgraded to the analysis of the call graph considering the full expansion of the macro.

Note

Macro Delimiters verification

Before considering a macro as region delimiter, a check to the macro expansion code is performed: only when, inside the body of the macro expansion, a call to the expected Os API delimiter functions is found, the macro itself is considered as region delimiter. This verification process helps to ensure that some macro definitions are not mistakenly identified as region delimiters, like the Rte_GetResource()/Rte_ReleaseResource() macros in some specific scenarios.

Rule Id	ETAS_RTACAR_SM_OS_183
Title	SuspendOSInterrupts/ResumeOSInterrupts critical section must not call prohibited OS API functions.
Description	This rule verifies that no prohibited OS API calls are made within a critical section protected by SuspendOSInterrupts/ResumeOSInterrupts.

Message Description

id_000

Id	id_000
Message	The rule cannot be evaluated due to an internal exception during the analysis execution. Please refer to the log file for more detailed information.
Kind	Open
Level	None
Description	An internal exception occurred during the execution. This can happen if there are insufficient resources available on the host machine. For more details, please consult the RTA-SQF log file.
How To Fix	Restart the command to exclude any internal exceptions. Alternatively, please contact ETAS GmbH support for assistance. When reporting the error, include a sample configuration and command line that reproduces the issue.

id_001

Id	id_001
Message	The SuspendOSInterrupts/ResumeOSInterrupts critical section was checked and no prohibited function calls were found.
Kind	Pass
Level	None
Description	No prohibited function calls were detected in the analyzed critical section.
How To Fix	Everything is in order. No action is required.

id_002

Id	id_002
Message	The SuspendOSInterrupts/ResumeOSInterrupts critical section was checked and prohibited function calls were found.
Kind	Fail
Level	Error
Description	Prohibited function calls were detected in the analyzed critical section.
How To Fix	Please review the critical section and remove any prohibited function calls, if present.

id_003

Id	id_003
Message	The SuspendOSInterrupts/ResumeOSInterrupts critical section could not be detected because the function is inside a conditional statement and data flow analysis is required.
Kind	Review
Level	None
Description	The tool could not determine the critical section due to conditional code. Manual review is required.
How To Fix	Please review the code to ensure the critical section is correctly implemented and free of prohibited function calls.

id_004

Id	id_004
Message	The SuspendOSInterrupts/ResumeOSInterrupts critical section was found but the check could not be performed due to a limitation of the tool.
Kind	Review
Level	None
Description	The tool could not complete the analysis due to a limitation. Manual review is required.
How To Fix	Please review the code to ensure the critical section is correctly implemented and free of prohibited function calls.

id_005

Id	id_005
Message	The SuspendOSInterrupts/ResumeOSInterrupts critical section was not found or the function is treated as trusted.
Kind	Pass
Level	None
Description	No critical sections were detected.
How To Fix	Everything is in order. No action is required.