Lines Matching +full:created +full:- +full:for
5 design in Trusted Firmware-M (`TF-M`).
8 - The FF-M in this document refers to the accumulated result of two
10 `FF-M v1.1 Update <https://developer.arm.com/documentation/aes0039/latest>`_
12 `FF-M v1.0 <https://developer.arm.com/documentation/den0063/latest/>`_.
13 - The words marked as `interpreted` are defined terms. Find the terms in
19 The service access process of FF-M:
23 :name: fig-tfmdev
26 FF-M service access process
34 - Contains services with the same purpose.
35 - Provides implementation required isolation boundaries.
36 - Is a software development unit.
38 Each service exposes its `Service ID` (`SID`) and `Handle` for client access
39 usage. Clients access services by `SID` or `Handle` through FF-M `Client API`.
40 Partitions use FF-M `Secure Partition API` when it needs to operate on client
43 `SPM` is the centre of an FF-M compliant implementation, which sets up and
46 - Implements `Client API` and `Secure Partition API`.
47 - Manages partition runtime to follow FF-M.
48 - Involves necessary implementation-defined items to support the
53 - FF-M defined API.
54 - Extended API to support the implementation.
56 Both API categories are compliant with FF-M concepts and guidelines. The core
57 concept of TF-M SPM surrounds the FF-M defined service management and access
64 `Inter-process communication` (`IPC`) model or `Secure Function` (`SFN`)
68 There is `ONE` thread inside the partition keeps waiting for signals. SPM
74 - It provides better isolation by limiting the interfaces on data interactive.
76 - It provides a mechanism for handling multiple service access. There is no
78 multiple function call contexts when serving multiple-threaded clients if
79 the service access is implemented in a function-call based mechanism. This
88 - Saves the workloads spent on `IPC` scheduling.
90 Meanwhile, it relaxes the data interactive mechanism, for example, allow
91 direct memory access (MMIOVEC). And it is hard to enable multiple-threaded
92 clients service access because of multiple call context-maintenance
96 resource-constrained devices, it is called an `SFN model implementation`. And
105 There are `THREE` isolation levels defined in `FF-M`. These levels can
111 :name: fig-modelisolation
117 Concept `ARoT`, `PRoT`, `domain`, and boundaries are in the `FF-M`
123 :numref:`fig-modelisolation` represents `NSPE` clients after they crossed
128 `NS Agent` is a necessary implementation-defined component out of FF-M
130 non-secure can not share the stack. It also has dedicated execution bodies.
131 For example, RPC-based `NS Agent` has a while loop that keeps waiting for
132 messages; and Trustzone-based `NS Agent` has veneer code to take over `NSPE`
141 Check `NS Agent`_ for details.
145 The principles for TF-M SPM implementation:
148 - SPM can treat these components as the client: NS Agent, SFN Partition,
150 - These components can provide services: SFN Partition, IPC partition, and
151 built-in services. A built-in service is built up with SPM together.
152 - All partition services must be accessed by `Client API`.
153 - Partitions interact with client data by `Secure Partition API`.
154 - Built-in services are strongly recommended to be accessed by `Client API`.
156 - Built-in services can call SPM internal interfaces directly.
164 - `Initializing` state, to set up the SPM runtime environment after system
166 - `IDLE` state, when SPM runtime environment is set up and partitions are
167 ready for service access.
168 - `Serving` state, when partition is under initializing or service access
170 - `Background` state, such as the arrival of secure interrupt or unexpected
178 :name: fig-spestate
185 The goal of TF-M initializing is to perform necessary initialization and
186 move to the `Serving`_ state. This state starts with platform-specific power
195 These procedures and their sub-routines are recommended to be applied with
200 --------------------------
201 The purpose of this preparation initialization is to provide a chance for
202 performing those security required but generic platform power-on skipped
205 - Restrict `SPM` execution, for example, set up memory overflow settings for
206 SPM runtime memory, or set code out of SPM as un-executable, even though
210 The ``logging``-related peripheral can be set up **AT THIS STEP**, if
212 initializing HAL API proposed for logging, so here is an ideal place for
216 are implemented as its sub-routines for reference:
218 - Architecture extensions initialization, Check chapter
219 `Architecture security settings`_ for detailed information.
220 - Isolation and lifecycle initialization.
226 of SPM initializing, SPM double-checks the lifecycle set up status (following
231 Double-check debugger settings when performing a product release.
234 --------------------------
236 allocator, loading partitions and partition-specific initialization
245 * Allocate runtime objects for this partition.
252 partitions' initialization routines have not run yet - the partition runtime
253 context is initialized for the routine call.
258 - SPM needs to call the initialization routine, just like it calls into
260 - The partition initialization routine can access its depending services.
264 Hence a `Partition initialization client` needs to be created to initialize
267 - `SPM runtime initialization` happen inside a special runtime environment
270 - IPC partitions are initialized by the scheduler and dependencies are
274 The `Partition initialization client` is created differently based on the
277 - A SFN client is created under the SFN model implementation.
278 - A IPC client is created under the IPC model implementation. This client
281 As the other partitions, the client is created with context standby, and it
285 -------------------
294 - `Partition initialization routine execution`_.
295 - `Secure service access`_.
302 (Such as `Secure service access`_) is abstracted from the FF-M
303 specification. Reference the FF-M specification for the details of each
307 ------------------------------------------
318 ---------------------
321 #. A `client` calls an FF-M Client API.
322 #. `SPM` validates inputs and looks up for the targeted service.
326 access depending services to prepare the response. It also can wait for
328 #. The target service calls FF-M Secure Partition API to request a reply to
336 - Access to a service in an SFN partition is a function call, which does not
338 - Access to a service in an IPC partition leads to scheduling, which switches
340 - When the execution roams between components because of a function call or
346 :name: fig-hybridruntime
350 called firstly as it is the interface for service access. There are two ABI
351 types when calling SPM API: Cross-boundary or No-cross-boundary.
354 ---------------
356 particular isolation levels. For example:
358 - There are boundaries between ARoT components and SPM under isolation level 2
362 switching) and cross-boundary call. A direct call reaches the API entrance
363 directly, while a cross-boundary call needs a mechanism (Supervisor call e.g.)
368 :name: fig-twocalltypes
374 ---------------------------
379 :name: fig-abi_scheduler
386 - PSA API gets called by one of the ABI mentioned in the last chapter as
388 - The unified API Handler calls FF-M and backend subroutines in sequence.
389 - The `FF-M` subroutine performs `FF-M` defined operations.
390 - The backend operations perform target partition runtime model decided
391 operations. For example, enqueue message into the target partition under
394 - API Handler triggers different ABI based on the result of the backends.
398 - Can process the `PROGRAMMER_ERROR` in a unified place.
399 - Can see the prepared caller and callee context, with exited SPM context. It
400 is an ideal place for subsequent operations such as context switching.
404 .. code-block:: c
424 Some FF-M API runs as a generic thread to prevent long time exclusive
431 - Set a scheduler lock.
432 - Set SPM API thread priority as the highest.
435 -------------------------
436 A message to service is created after the target service is found and the
440 - The message is pushed into partition memory under a specific ABI mechanism
444 - The target service routine is called with the message parameter if
447 - The message is queued into the partition message list if the target
449 - IPC partition replies to the client by `psa_reply`, which is another SPM API
451 - SFN partition return triggers an implied `psa_reply`, which is also another
458 ---------------------
459 FF-M API allows multiple sessions for a service if the service is classic
460 connection-based. The service can maintain multiple local session data and use
465 another service access request can get a chance for new access. This is
466 because of the limited context storage - supporting multiple contexts in a
468 re-location). Limited the context content in the stack only can mitigate the
469 effort, but this requirement requires too much for the service development.
471 The implementation-decisions are:
473 - IPC partitions handles messages one by one, the client gets blocked before
475 - The client is blocked when accessing services are handling a service
479 ----------------
481 Hence PSA API has two types of ABI: `Cross-boundary ABI` and
488 :name: fig-spmabi
501 - Launching NSPE software (Trustzone case, e.g.), or send a signal to NSPE
514 - The background state has a higher execution priority than other states -
516 - Background execution can be nested. For example, an
518 - Particular partition code can be involved in the background state, for
520 - Background state MUST return to the state it preempts.
524 design document for details.
532 Arm M-profile architecture is the default hardware architecture when
533 describing architecture-specific items.
535 The general M-profile programming is not involved in this document. The
536 following chapters introduce the mandatory settings for security
541 When an `Armv8m Security Extension` (Aka `Trustzone-M`) is available in the
544 - The MSPLIM needs to be set correctly to prevent stack overflow.
545 - The exception handler priority needs to be decided.
546 - Boost the secure handler mode priority to prevent NSPE from preempting SPE
548 - Disable NSPE hardware faults when a secure fault is happening. Trap in the
550 - Push seals on the stack top when a stack is allocated (`TFMV-1`). Also
551 check `Stack seal`_ chapter for details.
554 `Floatpoint Extension` is enabled for partition usage:
556 - `FPCCR.TS`, `FPCCR.CLRONRET` and `FPCCR.CLRONRETS` need to be set when
558 - `CPACR.CP10` and `CPACR.CP11` need to be set when booting.
564 ----------
565 When Trustzone-M is applied, the architecture specification recommends sealing
568 - Push two `SEAL` values (`0xFEF5EDA5`) at the stack bottom, when a stack is
570 - Push two `SEAL` values on the stack pointer which is going to be switched
573 Check architecture specification and vulnerability `TFMV-1` for details.
575 Trustzone-M reentrant
576 ---------------------
577 The Trustzone-M has characteristics that:
579 - SPE keeps the last assigned stack pointer value when execution leaves SPE.
580 - SPE execution can be preempted by NSPE which causes an execution left.
583 re-uses the secure stack contains the first thread's context, which obviously
586 Armv8.1-M provides the hardware setting `CCR_S.TRD` to prevent the reentrant.
587 On an Armv8.0-M architecture, extra software logic needs to be added at the
590 - Check if the local stack points to a `SEAL` when veneer code get executed.
592 .. code-block:: c
606 ----------
609 `Trustzone-M` is present, the priority is set as the lowest just above NS
612 PendSV is an ideal place for scheduling logic, because:
614 - An interrupt triggered scheduling during PendSV execution lead to another
616 the latest run-able thread.
619 -----------------
620 In the diagram :numref:`fig-abi_scheduler`, the ABI can have two basic
621 types: cross-boundary and direct call (No-cross-boundary).
623 When applying `SVCall` (`SVC`) as the cross-boundary mechanism, the
626 - The SVC handler calls SPM internal routines, and eventually back to the
629 Under the IPC model implementation, to re-use `ABI 2` in `No-cross-boundary`,
640 - It does not provide FF-M aligned secure services.
641 - It runs with the second-lowest priority under `IPC model implementation`
643 - It has isolation boundaries and an individual stack.
644 - It requires specific services and mechanisms compared to common partitions.
646 There are two known types for NS Agent:
648 - Trustzone-M based.
649 - Remote Procedure Call (RPC) based.
654 Trustzone-M specific
655 --------------------
656 The functionalities of a Trustzone-M specific NSA is:
658 - Launch NSPE when booting.
659 - Wait in the veneer code, and get executed when NSPE accesses services.
663 Check specific NS ID client ID or context related documents for details.
667 :name: fig-tzcontext
673 ------------
674 Compared to Trustzone-M NSA, RPC NSA looks closer to a generic partition:
676 - It has a message loop, keep waiting for RPC events.
677 - It converts received RPC events into FF-M API call to target services.
681 - It parses RPC messages to know which NSPE thread is accessing services.
683 - It needs to check NSPE client memory and map to local before calling SPM API.
684 - It cannot be blocked during API calls, which affects handling the RPC
695 - A partition load information, used by SPM.
696 - A partition program containing service interface and logic, typically a
698 - An optional service API set for easier client usage, by encapsulating
699 the low-level `FF-M` Client API. These API needs to be integrated
703 -----------------
713 elements in a dedicated section, for SPM enumerating while loading.
719 .. code-block:: c
734 And the example for a specific partition load info:
742 ------------------
746 - The tooling references symbols in a fixed pattern in the partition load
748 - The HAL implementation needs to provide the symbols being referenced.
749 - SPM calls HAL API to bind the partition info with devices when the partition
751 - The platform HAL acknowledges the binding if validation pass on SPM given
760 .. list-table:: Object level modularization
761 :header-rows: 1
764 * - Name
765 - Description
766 * - SPM
767 - All SPM related modules such as SPM, system, and so on.
768 * - Platform
769 - Platform sources are switchable.
770 * - Services and Secure Partition
771 - These items should be standalone.
772 * - Service Runtime Library
773 - This is a shared runtime library.
781 Check the `HAL` design document for details.
785 The same TF-M code base is flexible to address different implementation
797 .. list-table:: Revision
798 :header-rows: 1
801 * - Date
802 - Description
803 * - 2021 Apr-Sep
804 - Updated to cover the implementation for `FF-M v1.1` features.
805 * - 2018
806 - Created as 'TF-M Inter-Process Communication' which is deprecated as
809 --------------