1########################## 2Hardware Abstraction Layer 3########################## 4 5:Organization: Arm Limited 6:Contact: tf-m@lists.trustedfirmware.org 7 8:API Version: 0.9 9 10************ 11Introduction 12************ 13:term:`TF-M` :term:`HAL` abstracts the hardware-oriented and platform specific 14operations on the :term:`SPE` side and provides a set of APIs to the upper 15layers such as :term:`SPM`, :term:`RoT Service`. 16The :term:`HAL` aims to cover the platform different aspects whereas common 17architecturally defined aspects are done generically within the common 18:term:`SPE`. 19In some cases, although the operations are defined architecturally, 20it may not be possible to generalize implementations because lots of information 21is only known to platforms. 22It is more efficient to define a :term:`HAL` API for those architectural 23operations as well. 24 25.. note:: 26 :term:`TBSA-M` provides the hardware requirements for security purposes. 27 :term:`TF-M` :term:`HAL` tries to reference :term:`TBSA-M` recommendations in 28 the interfaces from the software perspective only. Please reference 29 :term:`TBSA-M` for your security hardware design. 30 31Design Goals 32============ 33:term:`TF-M` :term:`HAL` is designed to simplify the integration efforts on 34different platforms. 35 36:term:`TF-M` :term:`HAL` is designed to make it easy to use the hardware and 37develop the :term:`SPM` and :term:`RoT Service` which need to access the 38devices. 39 40:term:`TF-M` :term:`HAL` is designed to make the structure clearer and let the 41:term:`TF-M` mainly focus on :term:`PSA` implementation. 42 43******** 44Overview 45******** 46This section provides an overview of the abstraction layer structure. 47 48.. figure:: /design_docs/media/hal_structure.png 49 50Here lists a minimal set of necessary functionalities: 51 52 - **Isolation API**: Provides the necessary isolation functionalities required 53 by the :term:`PSA-FF-M` and :term:`TBSA-M`, and provides APIs to :term:`SPM` 54 to check the permissions of memory access. 55 - **Platform API**: Provides the platform initialization, platform-specific 56 memory information, system reset, etc. 57 - **Log dev API**: Provides the log system functions. 58 - **Interrupt API**: Provides the interrupt functions. 59 60.. note:: 61 - There is a non-secure :term:`HAL` that focuses on the mailbox operation API 62 for Dual-core topology. For more information about it, please refer to 63 :doc:`Mailbox Design in TF-M on Dual-core System 64 </design_docs/dual-cpu/mailbox_design_on_dual_core_system>`. 65 - The minimal set of :term:`TF-M` :term:`HAL` is sufficient for Secure 66 Partitions by using customized peripheral interfaces. To provide easier 67 portability for the Secure Partitions, a Secure Partition :term:`HAL` is 68 provided in this design too. 69 - The debug mechanisms give the external entity the corresponding right to 70 access the system assets. :term:`TF-M` ensures that the external entity is 71 permitted access to those assets. Currently, :term:`TF-M` only needs the 72 debug authentication. The whole debug mechanism and related :term:`HAL` will 73 be enhanced in the future. Please refer to the :doc:`Debug authentication 74 settings section </integration_guide/source_structure/platform_folder>` 75 for more details. 76 77***************** 78Design Principles 79***************** 80As :term:`TF-M` runs on resource-constrained devices, the :term:`HAL` tries to 81avoid multiple level abstractions which cost more resources. 82 83Part of the :term:`HAL` interfaces does not focus on exact hardware operations 84such as power on/off or PIN manipulation. 85Instead, the :term:`HAL` abstracts higher-level interfaces to reserve the 86implementation flexibility for the platform vendors. 87 88The :term:`TF-M` :term:`HAL` should be easy to deprecate APIs and provide 89compatibilities. 90Any API incompatibility should be detected during building. 91 92:term:`TF-M` relies on the :term:`HAL` APIs to be implemented correctly and 93trusts the :term:`HAL` APIs. 94:term:`TFM` can provide assertions to detect common programming errors but 95essentially no further extensive checks will be provided. 96 97************ 98Source Files 99************ 100This section describes the source file of the :term:`TF-M` :term:`HAL`, 101including the header and c files. 102 103tfm_hal_defs.h 104============== 105This header file contains the definitions of common macros and types used by all 106:term:`HAL` APIs. Please refer to `Status Codes`_ for detailed definitions. 107 108tfm_hal_[module].[h/c] 109====================== 110All other headers and c files are classified by the modules, such as isolation, 111platform, interrupt, devices, etc. 112 113.. note:: 114 There are common files in the platform folder include the implemented 115 :term:`HAL` APIs. The platform vendors can use them directly but need to 116 implement all the sub APIs. 117 118************ 119Status Codes 120************ 121These are common status and error codes for all :term:`HAL` APIs. 122 123Types 124===== 125tfm_hal_status_t 126---------------- 127This is a status code to be used as the return type of :term:`HAL` APIs. 128 129.. code-block:: c 130 131 enum tfm_hal_status_t { 132 TFM_HAL_ERROR_MEM_FAULT = SCHAR_MIN, 133 TFM_HAL_ERROR_MAX_VALUE, 134 TFM_HAL_ERROR_BAD_STATE, 135 TFM_HAL_ERROR_NOT_SUPPORTED, 136 TFM_HAL_ERROR_INVALID_INPUT, 137 TFM_HAL_ERROR_NOT_INIT, 138 TFM_HAL_ERROR_GENERIC, 139 TFM_HAL_SUCCESS = 0 140 }; 141 142Error Codes 143=========== 144Negative values indicate an error. Zero and positive values indicate success. 145 146Here is the general list. The detailed usages for each error code are described 147in the API introduction sections. 148 149TFM_HAL_SUCCESS 150--------------- 151Status code to indicate general success. 152 153TFM_HAL_ERROR_GENERIC 154--------------------- 155Status code to indicate an error that does not correspond to any defined failure 156cause. 157 158TFM_HAL_ERROR_NOT_INIT 159---------------------- 160Status code to indicate that the module is not initialed. 161 162TFM_HAL_ERROR_INVALID_INPUT 163--------------------------- 164Status code to indicate that the input is invalid. 165 166TFM_HAL_ERROR_NOT_SUPPORTED 167--------------------------- 168Status code to indicate that the requested operation or a parameter is not 169supported. 170 171TFM_HAL_ERROR_BAD_STATE 172----------------------- 173Status code to indicate that the requested action cannot be performed in the 174current state. 175 176TFM_HAL_ERROR_MAX_VALUE 177----------------------- 178Status code to indicate that the current number has got the max value. 179 180TFM_HAL_ERROR_MEM_FAULT 181----------------------- 182Status code to indicate that the memory check failed. 183 184*************************** 185API Definition for TF-M SPM 186*************************** 187This section describes the APIs defined for :term:`TF-M` :term:`SPM`. 188 189Platform API 190============ 191The platform API is a higher-level abstraction layer of the platform, other than 192a dedicated API set for the special hardware devices. 193 194APIs 195---- 196tfm_hal_platform_init() 197^^^^^^^^^^^^^^^^^^^^^^^ 198**Prototype** 199 200.. code-block:: c 201 202 enum tfm_hal_status_t tfm_hal_platform_init(void) 203 204**Description** 205 206This API performs the platform initializations **before** the :term:`SPM` 207initialization. 208 209The initializations could include but not limited to: 210- Fault handlers 211- Reset configurations 212- Debug init 213- NVIC init 214 215**Parameter** 216 217- ``void`` - None. 218 219**Return Values** 220 221- ``TFM_HAL_SUCCESS`` - Init success. 222- ``TFM_HAL_ERROR_GENERIC`` - Generic errors. 223 224tfm_hal_system_reset() 225^^^^^^^^^^^^^^^^^^^^^^ 226**Prototype** 227 228.. code-block:: c 229 230 void tfm_hal_system_reset(void) 231 232**Description** 233 234This API performs a system reset. 235 236The platform can uninitialize some resources before reset. 237 238When ``CONFIG_TFM_HALT_ON_CORE_PANIC`` is disabled this function is called to reset 239the system when a fatal error occurs. 240 241**Parameter** 242 243- ``void`` - None 244 245**Return Values** 246 247- ``void`` - None 248 249**Note** 250 251This API should not return. 252 253tfm_hal_system_halt() 254^^^^^^^^^^^^^^^^^^^^^ 255**Prototype** 256 257.. code-block:: c 258 259 void tfm_hal_system_halt(void) 260 261**Description** 262 263This API enters the CPU into an infinite loop. 264 265The platform can uninitialize some resources before looping forever. 266 267When ``CONFIG_TFM_HALT_ON_CORE_PANIC`` is enabled this function is called to halt the 268system when a fatal error occurs. 269 270**Parameter** 271 272- ``void`` - None 273 274**Return Values** 275 276- ``void`` - None 277 278**Note** 279 280This API should not return. 281 282Isolation API 283============= 284The :term:`PSA-FF-M` defines three isolation levels and a memory access rule to 285provide diverse levels of security. The isolation API provides the functions to 286implement these requirements. 287 288The Isolation API operates on boundaries. A boundary represents a set of 289protection settings that isolates components and domains. Below are the 290boundary examples in the current implementation: 291 292 - Boundaries between SPM and Secure Partitions. 293 - Boundaries between ARoT domain and PRoT domain. 294 295There are two types of boundaries: 296 297 - Static boundaries: Set up when the system is initializing and 298 persistent after the initialization. This type of boundary needs the 299 set-up operations only. 300 - Partition boundaries: Keeps switching from one to another when the system 301 is running. This type of boundary needs both set-up and switching 302 operations. 303 304The boundary operations are abstracted as HAL interfaces because isolation 305hardwares can be different for platforms: 306 307 - The set-up HAL interface creates a partition boundary based on given 308 partition information. This created boundary is bound with the partition 309 for subsequent usage. The binding is done by storing the boundary into 310 partition runtime data. 311 - The activation HAL interface activates the partition boundary to secure 312 the execution for the partition to be switched. The target partition's 313 information and boundary are given to the activation HAL to accomplish 314 the operation. 315 316The data representing the partition boundary in runtime is defined with the 317opaque type ``uintptr_t``: 318 319 - It is required that one value represents one boundary. The different values 320 represent different boundaries. 321 - The value is created by HAL implementation with its own-defined encoding 322 scheme. 323 324The HAL implementation defined encoding scheme can be designed for 325implementation convenience. For example: 326 327 - The implementation scheme can encode attribute flags into integer bits. 328 This could help the activation HAL to extract the protection settings 329 quickly from this encoded value, or even write to hardware registers 330 directly in the most ideal case. The initial TF-M Isolation HAL reference 331 implementation applies this scheme. 332 - The implementation scheme can reference the addresses of isolation 333 hardware description data. This could help the activation HAL to reference 334 the protection settings directly by pointers. 335 336Multiple Secure Partitions can bind with the same boundary value. This 337flexibility is useful for specific configurations. Take Isolation Level 2 as 338an example, assigning PRoT and ARoT domain boundaries to respective partitions 339can make execution more efficient, because switching two partitions in the 340same domain does not need to change the activated boundary. 341 342The boundary contains the partition's memory accessibility information, hence 343memory access check shall be performed based on boundary. 344 345Memory Access Attributes 346------------------------ 347The memory access attributes are encoded as bit fields, you can logic OR them to 348have a combination of the atrributes, for example 349``TFM_HAL_ACCESS_UNPRIVILEGED | TFM_HAL_ACCESS_READABLE`` is unprivileged 350readable. The data type is `uint32_t`. 351 352TFM_HAL_ACCESS_EXECUTABLE 353^^^^^^^^^^^^^^^^^^^^^^^^^ 354The memory is executable. 355 356.. code-block:: c 357 358 #define TFM_HAL_ACCESS_EXECUTABLE (1UL << 0) 359 360TFM_HAL_ACCESS_READABLE 361^^^^^^^^^^^^^^^^^^^^^^^ 362The memory is readable. 363 364.. code-block:: c 365 366 #define TFM_HAL_ACCESS_READABLE (1UL << 1) 367 368TFM_HAL_ACCESS_WRITABLE 369^^^^^^^^^^^^^^^^^^^^^^^ 370The memory is writable. 371 372.. code-block:: c 373 374 #define TFM_HAL_ACCESS_WRITABLE (1UL << 2) 375 376TFM_HAL_ACCESS_UNPRIVILEGED 377^^^^^^^^^^^^^^^^^^^^^^^^^^^ 378The memory is unprivileged mode accessible. 379 380.. code-block:: c 381 382 #define TFM_HAL_ACCESS_UNPRIVILEGED (1UL << 3) 383 384TFM_HAL_ACCESS_DEVICE 385^^^^^^^^^^^^^^^^^^^^^ 386The memory is a MMIO device. 387 388.. code-block:: c 389 390 #define TFM_HAL_ACCESS_DEVICE (1UL << 4) 391 392TFM_HAL_ACCESS_NS 393^^^^^^^^^^^^^^^^^ 394The memory is accessible from :term:`NSPE` 395 396.. code-block:: c 397 398 #define TFM_HAL_ACCESS_NS (1UL << 5) 399 400APIs 401---- 402 403tfm_hal_verify_static_boundaries() 404^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 405**Prototype** 406 407.. code-block:: c 408 409 fih_int tfm_hal_verify_static_boundaries(void) 410 411**Description** 412 413This API verifies the static isolation boundaries. 414 415Refer to the :term:`PSA-FF-M` for the definitions of the isolation boundaries. 416 417**Parameter** 418 419- ``void`` - None 420 421**Return Values** 422 423- ``TFM_HAL_SUCCESS`` - Verification has been successful. 424- ``TFM_HAL_ERROR_GENERIC`` - Verification failed. 425 426tfm_hal_set_up_static_boundaries() 427^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 428**Prototype** 429 430.. code-block:: c 431 432 enum tfm_hal_status_t tfm_hal_set_up_static_boundaries(void) 433 434**Description** 435 436This API sets up the static isolation boundaries which are constant throughout 437the system runtime. 438 439These boundaries include: 440 441- The boundary between the :term:`SPE` and the :term:`NSPE` 442- The boundary to protect the SPM execution. For example, the PSA RoT 443 isolation boundary between the PSA Root of Trust and the Application Root of 444 Trust which is for isolation level 2 and 3 only. 445 446Refer to the :term:`PSA-FF-M` for the definitions of the isolation boundaries. 447 448**Parameter** 449 450- ``void`` - None 451 452**Return Values** 453 454- ``TFM_HAL_SUCCESS`` - Isolation boundaries have been set up. 455- ``TFM_HAL_ERROR_GENERIC`` - Failed to set up the static boundaries. 456 457tfm_hal_bind_boundary() 458^^^^^^^^^^^^^^^^^^^^^^^^^ 459**Prototype** 460 461.. code-block:: c 462 463 enum tfm_hal_status_t tfm_hal_bind_boundary( 464 const struct partition_load_info_t *p_ldinf, 465 uintptr_t *p_boundary); 466 467**Description** 468 469This API binds partition with a platform-generated boundary. The boundary is 470bound by writing the generated value into ``p_boundary``. And this bound 471boundary is used in subsequent calls to `tfm_hal_activate_boundary()`_ when 472boundary's owner partition get scheduled for running. 473 474**Parameter** 475 476- ``p_ldinf`` - Load information of the partition that is under loading. 477- ``p_boundary`` - Pointer for holding a partition's boundary. 478 479**Return Values** 480 481- ``TFM_HAL_SUCCESS`` - The boundary has been bound successfully. 482- ``TFM_HAL_ERROR_GENERIC`` - Failed to bind the handle. 483 484tfm_hal_activate_boundary() 485^^^^^^^^^^^^^^^^^^^^^^^^^^^ 486**Prototype** 487 488.. code-block:: c 489 490 enum tfm_hal_status_t tfm_hal_activate_boundary( 491 const struct partition_load_info_t *p_ldinf, 492 uintptr_t boundary); 493 494**Description** 495 496This API requires the platform to activate the boundary to ensure the given 497Secure Partition can run successfully. 498 499The access permissions outside the boundary is platform-dependent. 500 501**Parameter** 502 503- ``p_ldinf`` - The load information of the partition that is going to be run. 504- ``boundary`` - The boundary for the owner partition of ``p_ldinf``. This 505 value is bound in function ``tfm_hal_bind_boundary``. 506 507**Return Values** 508 509- ``TFM_HAL_SUCCESS`` - the isolation boundary has been set up. 510- ``TFM_HAL_ERROR_GENERIC`` - failed to set up the isolation boundary. 511 512tfm_hal_memory_check() 513^^^^^^^^^^^^^^^^^^^^^^ 514**Prototype** 515 516.. code-block:: c 517 518 tfm_hal_status_t tfm_hal_memory_check(uintptr_t boundary, 519 uintptr_t base, 520 size_t size, 521 uint32_t access_type) 522 523**Description** 524 525This API checks if a given range of memory can be accessed with specified 526access types in boundary. The boundary belongs to a partition which 527contains asset info. 528 529**Parameter** 530 531- ``boundary`` - Boundary of a Secure Partition. 532 Check `tfm_hal_bind_boundary` for details. 533- ``base`` - The base address of the region. 534- ``size`` - The size of the region. 535- ``access_type`` - The memory access types to be checked between given memory 536 and boundaries. The `Memory Access Attributes`_. 537 538**Return Values** 539 540- ``TFM_HAL_SUCCESS`` - The memory region has the access permissions. 541- ``TFM_HAL_ERROR_MEM_FAULT`` - The memory region does not have the access 542 permissions. 543- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs. 544- ``TFM_HAL_ERROR_GENERIC`` - An error occurred. 545 546**Note** 547 548If the implementation chooses to encode a pointer as the boundary, 549a platform-specific pointer validation needs to be considered before 550referencing the content in this pointer. 551 552tfm_hal_boundary_need_switch() 553^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 554**Prototype** 555 556.. code-block:: c 557 558 bool tfm_hal_boundary_need_switch(uintptr_t boundary_from, 559 uintptr_t boundary_to) 560 561**Description** 562 563This API let the platform decide if a boundary switch is needed. 564 565**Parameter** 566 567- ``boundary_from`` - Boundary to switch from. 568- ``boundary_to`` - Boundary to switch to. 569 570**Return Values** 571 572- ``true`` - A switching is needed 573- ``false`` - No need for a boundary switch 574 575Log API 576======= 577The log API is used by the :term:`TF-M` :doc:`log system </design_docs/tfm_log_system_design_document>`. 578The log device could be uart, memory, usb, etc. 579 580APIs 581---- 582tfm_hal_output_partition_log() 583^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 584**Prototype** 585 586.. code-block:: c 587 588 int32_t tfm_hal_output_partition_log(const unsigned char *str, uint32_t len) 589 590**Description** 591 592This API is called by Secure Partition to output logs. 593 594**Parameter** 595 596- ``str`` - The string to output. 597- ``len`` - Length of the string in bytes. 598 599**Return Values** 600 601- Positive values - Number of bytes output. 602- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized. 603- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` or 604 ``len`` is zero. 605 606**Note** 607 608None. 609 610tfm_hal_output_spm_log() 611^^^^^^^^^^^^^^^^^^^^^^^^ 612**Prototype** 613 614.. code-block:: c 615 616 int32_t tfm_hal_output_spm_log(const unsigned char *str, uint32_t len) 617 618**Description** 619 620This API is called by :term:`SPM` to output logs. 621 622**Parameter** 623 624- ``str`` - The string to output. 625- ``len`` - Length of the string in bytes. 626 627**Return Values** 628 629- Positive numbers - Number of bytes output. 630- ``TFM_HAL_ERROR_NOT_INIT`` - The log device has not been initialized. 631- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid inputs when ``str`` is ``NULL`` 632 or ``len`` is zero. 633 634**Note** 635 636Please check :doc:`TF-M log system </design_docs/tfm_log_system_design_document>` 637for more information. 638 639Interrupt APIs 640============== 641 642The SPM HAL interrupt APIs are intended for operations on Interrupt Controllers 643of platforms. 644 645APIs for control registers of interrupt sources are not in the scope of this set 646of APIs. 647Secure Partitions should define the APIs for managing interrupts with those MMIO 648registers. 649 650APIs 651---- 652 653tfm_hal_irq_enable() 654^^^^^^^^^^^^^^^^^^^^ 655 656**Prototype** 657 658.. code-block:: c 659 660 enum tfm_hal_status_t tfm_hal_irq_enable(uint32_t irq_num) 661 662**Description** 663 664This API enables an interrupt from the Interrupt Controller of the platform. 665 666**Parameter** 667 668- ``irq_num`` - the interrupt to be enabled with a number 669 670**Return Values** 671 672- ``TFM_HAL_ERROR_INVALID_INPUT`` - the ``irq_num`` exceeds The maximum 673 supported number of external interrupts. 674- ``TFM_HAL_ERROR_GENERIC`` - failed to enable the interrupt. 675- ``TFM_HAL_SUCCESS`` - the interrupt is successfully enabled. 676 677tfm_hal_irq_disable() 678^^^^^^^^^^^^^^^^^^^^^ 679 680**Prototype** 681 682.. code-block:: c 683 684 enum tfm_hal_status_t tfm_hal_irq_disable(uint32_t irq_num) 685 686**Description** 687 688This API disables an interrupt from the Interrupt Controller of the platform. 689 690**Parameter** 691 692- ``irq_num`` - the interrupt to be disabled with a number 693 694**Return Values** 695 696- ``TFM_HAL_ERROR_INVALID_INPUT`` - the ``irq_num`` exceeds The maximum 697 supported number of external interrupts. 698- ``TFM_HAL_ERROR_GENERIC`` - failed to disable the interrupt. 699- ``TFM_HAL_SUCCESS`` - the interrupt is successfully disabled. 700 701tfm_hal_irq_clear_pending() 702^^^^^^^^^^^^^^^^^^^^^^^^^^^ 703 704**Prototype** 705 706.. code-block:: c 707 708 enum tfm_hal_status_t tfm_hal_irq_clear_pending(uint32_t irq_num) 709 710**Description** 711 712This API clears an active and pending interrupt. 713 714**Parameter** 715 716- ``irq_num`` - the interrupt to be disabled with a number 717 718**Return Values** 719 720- ``TFM_HAL_ERROR_INVALID_INPUT`` - the ``irq_num`` exceeds The maximum 721 supported number of external interrupts. 722- ``TFM_HAL_ERROR_GENERIC`` - failed to clear the pending interrupt. 723- ``TFM_HAL_SUCCESS`` - the pending interrupt has been cleared. 724 725Initializations 726^^^^^^^^^^^^^^^ 727 728**Prototype** 729 730.. code-block:: c 731 732 enum tfm_hal_status_t {source_symbol}_init(void *p_pt, 733 const struct irq_load_info_t *p_ildi) 734 735The ``{source_symbol}`` is: 736 737- ``irq_{source}``, if the ``source`` attribute of the IRQ in Partition manifest 738 is a number 739- Lowercase of ``source`` attribute, if ``source`` is a symbolic name 740 741**Description** 742 743Each interrupt has an initialization function individually. 744The :term:`SPM` calls the functions while loading the Partitions. 745 746The following initializations are required for each interrupt: 747 748- Setting the priority. The value must between 0 to 0x80 exclusively. 749- Ensuring that the interrupt targets the Secure State. 750- Saving the input parameters for future use. 751 752Platforms can have extra initializations as well. 753 754**Parameter** 755 756- ``p_pt`` - pointer to Partition runtime struct of the owner Partition 757- ``p_ildi`` - pointer to ``irq_load_info_t`` struct of the interrupt 758 759**Note** 760 761Please refer to the 762:doc: `IRQ intergration guide<tfm_secure_irq_integration_guide>` 763for more information. 764 765************************************ 766API Definition for Secure Partitions 767************************************ 768The Secure Partition (SP) :term:`HAL` mainly focuses on two parts: 769 770 - Peripheral devices. The peripherals accessed by the :term:`TF-M` default 771 Secure Partitions. 772 - Secure Partition abstraction support. The Secure Partition data that must be 773 provided by the platform. 774 775The Secure Partition abstraction support will be introduced in the peripheral 776API definition. 777 778ITS and PS flash API 779==================== 780There are two kinds of flash: 781 782 - Internal flash. Accessed by the PSA Internal Trusted Storage (ITS) service. 783 - External flash. Accessed by the PSA Protected Storage (PS) service. 784 785The ITS HAL for the internal flash device is defined in the ``tfm_hal_its.h`` 786header and the PS HAL in the ``tfm_hal_ps.h`` header. 787 788Macros 789------ 790Internal Trusted Storage 791^^^^^^^^^^^^^^^^^^^^^^^^ 792TFM_HAL_ITS_FLASH_DRIVER 793~~~~~~~~~~~~~~~~~~~~~~~~ 794Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for 795ITS. It must have been allocated by the platform and will be declared extern in 796the HAL header. 797 798TFM_HAL_ITS_PROGRAM_UNIT 799~~~~~~~~~~~~~~~~~~~~~~~~ 800Defines the size of the ITS flash device's physical program unit (the smallest 801unit of data that can be individually programmed to flash). It must be equal to 802TFM_HAL_ITS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile 803time so that filesystem structures can be statically sized. 804 805TFM_HAL_ITS_FLASH_AREA_ADDR 806~~~~~~~~~~~~~~~~~~~~~~~~~~~ 807Defines the base address of the dedicated flash area for ITS. 808 809TFM_HAL_ITS_FLASH_AREA_SIZE 810~~~~~~~~~~~~~~~~~~~~~~~~~~~ 811Defines the size of the dedicated flash area for ITS in bytes. 812 813TFM_HAL_ITS_SECTORS_PER_BLOCK 814~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 815Defines the number of contiguous physical flash erase sectors that form a 816logical filesystem erase block. 817 818Protected Storage 819^^^^^^^^^^^^^^^^^ 820TFM_HAL_PS_FLASH_DRIVER 821~~~~~~~~~~~~~~~~~~~~~~~ 822Defines the identifier of the CMSIS Flash ARM_DRIVER_FLASH object to use for 823PS. It must have been allocated by the platform and will be declared extern in 824the HAL header. 825 826TFM_HAL_PS_PROGRAM_UNIT 827~~~~~~~~~~~~~~~~~~~~~~~~ 828Defines the size of the PS flash device's physical program unit (the smallest 829unit of data that can be individually programmed to flash). It must be equal to 830TFM_HAL_PS_FLASH_DRIVER.GetInfo()->program_unit, but made available at compile 831time so that filesystem structures can be statically sized. 832 833TFM_HAL_PS_FLASH_AREA_ADDR 834~~~~~~~~~~~~~~~~~~~~~~~~~~~ 835Defines the base address of the dedicated flash area for PS. 836 837TFM_HAL_PS_FLASH_AREA_SIZE 838~~~~~~~~~~~~~~~~~~~~~~~~~~~ 839Defines the size of the dedicated flash area for PS in bytes. 840 841TFM_HAL_PS_SECTORS_PER_BLOCK 842~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 843Defines the number of contiguous physical flash erase sectors that form a 844logical filesystem erase block. 845 846Optional definitions 847-------------------- 848The ``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` and 849``TFM_HAL_ITS_SECTORS_PER_BLOCK`` definitions are optional. If not defined, the 850platform must implement ``tfm_hal_its_fs_info()`` instead. 851 852Equivalently, ``tfm_hal_its_ps_info()`` must be implemented by the platform if 853``TFM_HAL_ITS_FLASH_AREA_ADDR``, ``TFM_HAL_ITS_FLASH_AREA_SIZE`` or 854``TFM_HAL_ITS_SECTORS_PER_BLOCK`` is not defined. 855 856Objects 857------- 858ARM_DRIVER_FLASH 859^^^^^^^^^^^^^^^^ 860The ITS and PS HAL headers each expose a CMSIS Flash Driver instance. 861 862.. code-block:: c 863 864 extern ARM_DRIVER_FLASH TFM_HAL_ITS_FLASH_DRIVER 865 866 extern ARM_DRIVER_FLASH TFM_HAL_PS_FLASH_DRIVER 867 868The CMSIS Flash Driver provides the flash primitives ReadData(), ProgramData() 869and EraseSector() as well as GetInfo() to access flash device properties such 870as the sector size. 871 872Types 873----- 874tfm_hal_its_fs_info_t 875^^^^^^^^^^^^^^^^^^^^^ 876Struct containing information required from the platform at runtime to configure 877the ITS filesystem. 878 879.. code-block:: c 880 881 struct tfm_hal_its_fs_info_t { 882 uint32_t flash_area_addr; 883 size_t flash_area_size; 884 uint8_t sectors_per_block; 885 }; 886 887Each attribute is described below: 888 889 - ``flash_area_addr`` - Location of the block of flash to use for ITS 890 - ``flash_area_size`` - Number of bytes of flash to use for ITS 891 - ``sectors_per_block`` - Number of erase sectors per logical FS block 892 893tfm_hal_ps_fs_info_t 894^^^^^^^^^^^^^^^^^^^^^ 895Struct containing information required from the platform at runtime to configure 896the PS filesystem. 897 898.. code-block:: c 899 900 struct tfm_hal_ps_fs_info_t { 901 uint32_t flash_area_addr; 902 size_t flash_area_size; 903 uint8_t sectors_per_block; 904 }; 905 906Each attribute is described below: 907 908 - ``flash_area_addr`` - Location of the block of flash to use for PS 909 - ``flash_area_size`` - Number of bytes of flash to use for PS 910 - ``sectors_per_block`` - Number of erase sectors per logical FS block 911 912Functions 913--------- 914tfm_hal_its_fs_info() 915^^^^^^^^^^^^^^^^^^^^^ 916**Prototype** 917 918.. code-block:: c 919 920 enum tfm_hal_status_t tfm_hal_its_fs_info(struct tfm_hal_its_fs_info_t *fs_info); 921 922**Description** 923 924Retrieves the filesystem configuration parameters for ITS. 925 926**Parameter** 927 928- ``fs_info`` - Filesystem config information 929 930**Return values** 931 932- ``TFM_HAL_SUCCESS`` - The operation completed successfully 933- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter 934 935**Note** 936 937This function should ensure that the values returned do not result in a security 938compromise. The block of flash supplied must meet the security requirements of 939Internal Trusted Storage. 940 941tfm_hal_ps_fs_info() 942^^^^^^^^^^^^^^^^^^^^ 943**Prototype** 944 945.. code-block:: c 946 947 enum tfm_hal_status_t tfm_hal_ps_fs_info(struct tfm_hal_ps_fs_info_t *fs_info); 948 949**Description** 950 951Retrieves the filesystem configuration parameters for PS. 952 953**Parameter** 954 955- ``fs_info`` - Filesystem config information 956 957**Return values** 958 959- ``TFM_HAL_SUCCESS`` - The operation completed successfully 960- ``TFM_HAL_ERROR_INVALID_INPUT`` - Invalid parameter 961 962**Note** 963 964This function should ensure that the values returned do not result in a security 965compromise. 966 967-------------- 968 969*Copyright (c) 2020-2024, Arm Limited. All rights reserved.* 970*Copyright (c) 2022 Cypress Semiconductor Corporation (an Infineon company) 971or an affiliate of Cypress Semiconductor Corporation. All rights reserved.* 972
