1 2# Porting Guide: PSA Certified APIs Architecture Test Suite 3----------------------------------------------------------- 4 5## Introduction 6The architecture test suite contains the *Platform Abstraction Layer* (PAL) which abstracts platform-specific information from the tests. You must implement and port the PAL interface functions to your target platform. Create and update the target configuration file to match the details of this target platform. 7 8This document provides the porting steps and the list of PAL APIs. 9 10## Porting steps 11 12### Target configuration 13 14You must populate your system configuration and provide it as an input to the test suite. The system configuration is captured in a single static input configuration file called **target.cfg**, available at **api-tests/platform/targets/<platform_name>/**. <br /> 15 16An example input configuration file is as shown. 17 18 // UART device info 19 uart.num=1; 20 uart.0.base = 0x40004000; 21 uart.0.size = 0xFFF; 22 uart.0.intr_id = 0xFF; 23 uart.0.permission = TYPE_READ_WRITE; 24 25 // Watchdog device info 26 watchdog.num = 1; 27 watchdog.0.base = 0x40008000; 28 watchdog.0.size = 0xFFF; 29 watchdog.0.intr_id = 0xFF; 30 watchdog.0.permission = TYPE_READ_WRITE; 31 32 For details on the structure of the input, refer to **val/common/val_target.h**. 33 34### Adding a new target 35 36 1. Create a new directory in **platform/targets/<platform_name>**. For reference, see the existing platform **tgt_dev_apis_tfm_an521** directory. 37 2. Execute `cp -rf platform/targets/tgt_dev_apis_tfm_an521/ platform/targets/<platform_name>/`. 38 3. Update **platform/targets/<platform_name>/target.cfg** with your platform details. Refer to **val/common/val_target.h** for structure details. 39 4. Update **platform/targets/<platform_name>/target.cmake** appropriately to select the correct instances of PAL files for compilation. 40 5. Refer to the **List of PAL APIs** section to view the list of PAL APIs that must be ported for your target platform. These API definitions are available in **nspe/<suite_name>/pal_\*\_intf.c**. These APIs are written for tgt_dev_apis_tfm_an521 platform. You can reuse the code if it works for your platform. Otherwise, you must port them for your platform-specific peripherals. 41 6. Update Crypto configuration file **nspe/crypto/pal_crypto_config.h** to enable or disable Crypto features selectively for the Crypto test suite. 42 43**Note**: 44The test suite requires access to the following peripherals: 45 - One UART to print Test NSPE messages 46 - One Watchdog timer to help recover from any fatal error conditions 47 - Non-volatile memory support to preserve test status over watchdog timer reset. Each byte of this region must be initialised to FF at power on reset. 48 49 50## List of PAL APIs 51Since the test suite is agnostic to various system targets, you must port the following PAL NSPE APIs before building the tests. Implement these functions for your target platform. <br /> 52 53| No | Prototype | Description | Parameters | 54|----|-----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|----------------------------------------------------------| 55| 01 | int pal_uart_init_ns(uint32_t uart_base_addr); | Initializes the UART | UART base address<br/> | 56| 02 | int pal_print_ns(char *str, int32_t data); | Parses the input string and writes bytes into UART TX FIFO| str : Input String<br/>data : Value for format specifier<br/> | 57| 03 | int pal_wd_timer_init_ns(addr_t base_addr, uint32_t time_us, uint32_t timer_tick_us); | Initializes a hardware watchdog timer | base_addr : Base address of the watchdog module<br/>time_us : Time in micro seconds<br/>timer_tick_us : Number of ticks per micro second<br/>| 58| 04 | int pal_wd_timer_enable_ns(addr_t base_addr); | Enables a hardware watchdog timer | base_addr : Base address of the watchdog module<br/>| 59| 05 | int pal_wd_timer_disable_ns(addr_t base_addr); | Disables a hardware watchdog timer | base_addr : Base address of the watchdog module<br/> | 60| 06 | int pal_nvmem_read_ns(addr_t base, uint32_t offset, void *buffer, int size); | Reads from the given non-volatile address. | base : Base address of nvmem<br/>offset : Offset<br/>buffer : Pointer to source address<br/>size : Number of bytes<br/> | 61| 07 | int pal_nvmem_write_ns(addr_t base, uint32_t offset, void *buffer, int size); | Writes into given non-volatile address. | base : Base address of nvmem<br/>offset : Offset<br/>buffer : Pointer to source address<br/>size : Number of bytes<br/> | 62| 08 | int32_t pal_crypto_function(int type, va_list valist); | Calls the requested Crypto function | type : Function code<br/>valist : variable argument list<br/> | 63| 09 | uint32_t pal_its_function(int type, va_list valist); | Calls the requested Internal Trusted Storage function | type : Function code<br/>valist : Variable argument list<br/> | 64| 10 | uint32_t pal_ps_function(int type, va_list valist); | Calls the requested Protected Storage function | type : Function code<br/>valist : Variable argument list<br/> | 65| 11 | int32_t pal_attestation_function(int type, va_list valist); | Calls the requested Initial Attestation function | type : Function code<br/>valist : Variable argument list<br/> | 66| 12 | uint32_t pal_compute_hash(int32_t cose_alg_id, struct q_useful_buf buffer_for_hash, struct q_useful_buf_c *hash, struct q_useful_buf_c protected_headers, struct q_useful_buf_c payload); | Computes hash for the requested data | cose_alg_id : Algorithm ID<br/>buffer_for_hash : Temp buffer for calculating hash<br/><br/>hash : Pointer to store the hash<br/> buffer_for_hash : Temp buffer for calculating hash<br/>protected_headers : data to be hashed<br/>payload : Payload data<br/> | 67| 13 | uint32_t pal_crypto_pub_key_verify(int32_t cose_algorithm_id, struct q_useful_buf_c token_hash, struct q_useful_buf_c signature); | Function call to verify the signature using the public key | cose_algorithm_id : Algorithm ID<br/>token_hash : Data that needs to be verified<br/>signature : Signature to be verified against<br/> | 68| 14 | int pal_system_reset(void) | Resets the system | None | 69 70## License 71Arm PSA test suite is distributed under Apache v2.0 License. 72 73-------------- 74 75*Copyright (c) 2019-2022, Arm Limited and Contributors. All rights reserved.* 76
