SNIP_CLASSIC_OS_SECTION_8_4_4_CallTrustedFunction

8.4.4 CallTrustedFunction [SWS_Os_00097] Definition of API function CallTrustedFunction Upstream requirements: SRS_Os_11001 ⌈ Service Name CallTrustedFunction Syntax StatusType CallTrustedFunction ( TrustedFunctionIndexType FunctionIndex, TrustedFunctionParameterRefType FunctionParams ) Service ID [hex] 0x02 Sync/Async Synchronous Reentrancy Reentrant FunctionIndex Index of the function to be called. Parameters (in) FunctionParams Pointer to the parameters for the function - specified by the FunctionIndex - to be called. If no parameters are provided, a NULL_PTR has to be passed. Parameters (inout) None Parameters (out) None Return value StatusType E_OK: No Error E_OS_SERVICEID: No function defined for this index Description A (trusted or non-trusted) OS-Application uses this service to call a trusted function Available via Os.h ⌋ [SWS_Os_00265] Upstream requirements: SRS_Os_11001 ⌈If <FunctionIndex> is a defined function index, CallTrustedFunction shall call the function <FunctionIndex> out of a list of implementation specific trusted functions with the protection settings of the OS-Application which provides the trusted function AND shall return E_OK after completion.⌋ [SWS_Os_00312] Upstream requirements: SRS_Os_11001 ⌈Caveats of CallTrustedFunction: • The called trusted function must conform to the following C prototype: void TRUSTED_<name_of_the_trusted_service>( TrustedFunctionIndex Type,TrustedFunctionParameterRefType); (The arguments are the same as the arguments of CallTrustedFunction). • Normally, a user will not directly call this service, but it will be part of some standard interface, e.g. a standard I/O interface. • It is the duty of the called trusted function to check rights of passed parameters, especially if parameters are interpreted as out parameters. • It should be noted that the CallTrustedFunction does not disable timing protection for the Task which called the service. This may lead to timing faults (calls of the ProtectionHook) even inside of a trusted OS-Application. It is therefore recommended to use CallTrustedFunction only for stateless functions (e.g. functions which do not write or do not have internal states) ⌋ [SWS_Os_00266] Upstream requirements: SRS_Os_11001 ⌈When CallTrustedFunction calls the function <FunctionIndex>, that function shall be executed with the same processor mode, memory protection boundaries and the service protection limitations of the OS-Application to which it belongs. The notion of "current application" shall remain that of the calling Task or Category 2 ISR.⌋ Reaction to timing protection can be defined to terminate the OS-Application. If a Task is inside CallTrustedFunction and Task rescheduling takes place within the same OS-Application, the newly running higher priority Task may cause timing protection and terminate the OS-Application, thus indirectly aborting the trusted function. To avoid this, the scheduling of other Tasks which belong to the same OS-Application as the caller can be restricted, as well as the availability of interrupts of the same OS-Application. [SWS_Os_00565] ⌈When CallTrustedFunction is called and the caller of CallTrustedFunction is supervised with timing protection, the Operating System shall delay any timing protection errors until the CallTrustedFunction returns to a OsApplication with OsTrustedApplicationDelayTimingViolationCall == FALSE.⌋ [SWS_Os_00563] ⌈ If OsLockTrustedFunctionCall == TRUE the OperatingSystem shall not schedule any other Tasks which belong to the same OS-Application as the non-trusted caller of the service. Also interrupts of Category 2 which belong to the same OS-Application shall be disabled during the execution of the service.⌋ The lock/disabling in [SWS_Os_00563] is required to support timing supervision. Since the caller of a trusted function can be any Task or Category 2 ISR the Operating System has to make sure that no other calls can preempt/interrupt the ongoing trusted function. [SWS_Os_00364] Upstream requirements: SRS_Os_11001 ⌈If CallTrustedFunction calls the trusted function, that function shall continue to run on the same interrupt/task priority and be allowed to call system services defined for inside trusted functions.⌋ See also table in chapter 7.7.3.3. [SWS_Os_00292] Upstream requirements: SRS_BSW_00323 ⌈If the function index <FunctionIndex> in a call of CallTrustedFunction is undefined, CallTrustedFunction shall return E_OS_SERVICEID.⌋ [SWS_Os_00516] Upstream requirements: SRS_Os_11016 ⌈Availability of CallTrustedFunction: Available in Scalability Classes 3 and 4.⌋