| Jamie Fox | 278c038 | 2024-10-01 18:01:46 +0100 | [diff] [blame^] | 1 | #################### |
| 2 | SCMI Comms Partition |
| 3 | #################### |
| 4 | |
| 5 | The SCMI Comms partition provides a minimal implementation of the SCMI [1]_ |
| 6 | protocol for the purpose of subscribing to system power state notifications from |
| 7 | SCP. |
| 8 | |
| 9 | It currently supports only the shared memory based transport protocol. |
| 10 | |
| 11 | *********************** |
| 12 | Supported message types |
| 13 | *********************** |
| 14 | |
| 15 | The partition supports the System power management protocol [1]_. It can send |
| 16 | the following message types: |
| 17 | |
| 18 | - SYSTEM_POWER_STATE_NOTIFY |
| 19 | |
| 20 | It can receive the following message types: |
| 21 | |
| 22 | - SYSTEM_POWER_STATE_SET |
| 23 | - SYSTEM_POWER_STATE_NOTIFIER |
| 24 | |
| 25 | ************** |
| 26 | Code structure |
| 27 | ************** |
| 28 | |
| 29 | Partition source files: |
| 30 | |
| 31 | - ``scmi_comms.c``: Implements the core SCMI message handling. |
| 32 | - ``scmi_comms.h``: Common definitions used within the partition. |
| 33 | - ``scmi_hal.h``: Hardware abstraction layer that must be implemented by the |
| 34 | platform to support the SCMI Comms partition. |
| 35 | - ``scmi_protocol.h``: Defines values from the SCMI spec. |
| 36 | |
| 37 | Build options for out of tree build |
| 38 | =================================== |
| 39 | |
| 40 | - ``TFM_PARTITION_SCMI_COMMS``: To build the SCMI Comms secure partition its |
| 41 | value should be ``ON``. By default, it is switched ``OFF``. |
| 42 | |
| 43 | - ``TFM_EXTRA_MANIFEST_LIST_FILES``: ``<tf-m-extras-repo>/partitions/scmi/scmi_comms_manifest_list.yaml`` |
| 44 | |
| 45 | - ``TFM_EXTRA_PARTITION_PATHS``: ``<tf-m-extras-repo>/partitions/scmi`` |
| 46 | |
| 47 | **************** |
| 48 | Platform porting |
| 49 | **************** |
| 50 | |
| 51 | To use the SCMI Comms partition, a platform must supply an interface library |
| 52 | called ``scmi_hal`` for the partition to link against. The library must contain |
| 53 | implementations of all of the functions declared in ``scmi_hal.h``. It must also |
| 54 | contain a header called ``scmi_hal_defs.h``, with the following definitions: |
| 55 | |
| 56 | - ``SCP_SHARED_MEMORY_BASE``: The base address of a memory area shared between |
| 57 | SCP and the CPU running TF-M, which is used to pass messages via the SCMI |
| 58 | shared memory transport protocol. |
| 59 | - ``SCP_SHARED_MEMORY_SIZE``: The size of the SCP shared memory area. The |
| 60 | maximum SCMI message length that can be transported is the size of this area |
| 61 | minus the ``24`` bytes used by the transport protocol. |
| 62 | |
| 63 | Additionally, the platform must define ``SCP_DOORBELL_IRQ`` to be the IRQ number |
| 64 | triggered by the SCP doorbell in its ``config_tfm_target.h`` header. It must |
| 65 | also implement that IRQ's handler function to route the request to the SCMI |
| 66 | comms partition (see |
| 67 | :doc:`TF-M Secure IRQ integration guide<TF-M:integration_guide/tfm_secure_irq_integration_guide>` |
| 68 | for more details). |
| 69 | |
| 70 | ********** |
| 71 | References |
| 72 | ********** |
| 73 | |
| 74 | .. [1] `Arm System Control and Management Interface (SCMI) <https://developer.arm.com/documentation/den0056/latest/>`_ |
| 75 | |
| 76 | -------------- |
| 77 | |
| 78 | *SPDX-License-Identifier: BSD-3-Clause* |
| 79 | |
| 80 | *SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors* |