Add EL3 runtime services and SPD documentation

1. Add design information on EL3 runtime services and
Secure-EL1 Payload Dispatchers (SPD) to
firmware-design.md.

2. Create new EL3 runtime service writer's guide
(rt-svc-writers-guide.md) to ease creation of new
runtime services.

Change-Id: I670aeb5fc246e25c6e599a15139aac886a0074fd

3 files changed, 633 insertions, 48 deletions

diff --git a/docs/diagrams/rt-svc-descs-layout.png b/docs/diagrams/rt-svc-descs-layout.png
new file mode 100644
index 0000000..1a9fa5b
--- /dev/null
+++ b/docs/diagrams/rt-svc-descs-layout.png
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 89dd45f..4e7890e 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -4,11 +4,14 @@ ARM Trusted Firmware Design
 Contents :
 
 1.  Introduction
-2.  Cold Boot
-3.  Memory layout on FVP platforms
-4.  Firmware Image Package (FIP)
-5.  Code Structure
-6.  References
+2.  Cold boot
+3.  EL3 runtime services framework
+4.  Power State Coordination Interface
+5.  Secure-EL1 Payloads and Dispatchers
+6.  Memory layout on FVP platforms
+7.  Firmware Image Package (FIP)
+8.  Code Structure
+9.  References
 
 
 1.  Introduction
@@ -29,7 +32,7 @@ instruction. The SMC instruction must be used as mandated by the [SMC Calling
 Convention PDD][SMCCC] [3].
 
 
-2.  Cold Boot
+2.  Cold boot
 -------------
 
 The cold boot path starts when the platform is physically turned on. One of
@@ -334,59 +337,330 @@ memory address populated by BL2.
 
 *   Runtime services initialization:
 
-    The only runtime service implemented by BL3-1 is PSCI. The complete PSCI API
-    is not yet implemented. The following functions are currently implemented:
+    The runtime service framework and its initialization is described in the
+    "EL3 runtime services framework" section below.
 
-    -   `PSCI_VERSION`
-    -   `CPU_OFF`
-    -   `CPU_ON`
-    -   `CPU_SUSPEND`
-    -   `AFFINITY_INFO`
+    Details about the PSCI service are provided in the "Power State Coordination
+    Interface" section below.
 
-    The `CPU_ON`, `CPU_OFF` and `CPU_SUSPEND` functions implement the warm boot
-    path in ARM Trusted Firmware. `CPU_ON` and `CPU_OFF` have undergone testing
-    on all the supported FVPs. `CPU_SUSPEND` & `AFFINITY_INFO` have undergone
-    testing only on the AEM v8 Base FVP. Support for `AFFINITY_INFO` is still
-    experimental. Support for `CPU_SUSPEND` is stable for entry into power down
-    states. Standby states are currently not supported. `PSCI_VERSION` is
-    present but completely untested in this version of the software.
+*   BL3-2 (Secure-EL1 Payload) image initialization
 
-    Unsupported PSCI functions can be divided into ones that can return
-    execution to the caller and ones that cannot. The following functions
-    return with a error code as documented in the [Power State Coordination
-    Interface PDD] [PSCI].
+    If a BL3-2 image is present then there must be a matching Secure-EL1 Payload
+    Dispatcher (SPD) service (see later for details). During initialization
+    that service  must register a function to carry out initialization of BL3-2
+    once the runtime services are fully initialized. BL3-1 invokes such a
+    registered function to initialize BL3-2 before running BL3-3.
 
-    -   `MIGRATE` : -1 (NOT_SUPPORTED)
-    -   `MIGRATE_INFO_TYPE` : 2 (Trusted OS is either not present or does not
-         require migration)
-    -   `MIGRATE_INFO_UP_CPU` : 0 (Return value is UNDEFINED)
+    Details on BL3-2 initialization and the SPD's role are described in the
+    "Secure-EL1 Payloads and Dispatchers" section below.
 
-    The following unsupported functions do not return and signal an assertion
-    failure if invoked.
+*   BL3-3 (Non-trusted Firmware) execution
 
-    -   `SYSTEM_OFF`
-    -   `SYSTEM_RESET`
+    BL3-1 initializes the EL2 or EL1 processor context for normal-world cold
+    boot, ensuring that no secure state information finds its way into the
+    non-secure execution state. BL3-1 uses the entrypoint information provided
+    by BL2 to jump to the Non-trusted firmware image (BL3-3) at the highest
+    available Exception Level (EL2 if available, otherwise EL1).
 
-    BL3-1 returns the error code `-1` if an SMC is raised for any other runtime
-    service. This behavior is mandated by the [SMC calling convention PDD]
-    [SMCCC].
 
+3.  EL3 runtime services framework
+----------------------------------
+
+Software executing in the non-secure state and in the secure state at exception
+levels lower than EL3 will request runtime services using the Secure Monitor
+Call (SMC) instruction. These requests will follow the convention described in
+the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function
+identifiers to each SMC request and describes how arguments are passed and
+returned.
+
+The EL3 runtime services framework enables the development of services by
+different providers that can be easily integrated into final product firmware.
+The following sections describe the framework which facilitates the
+registration, initialization and use of runtime services in EL3 Runtime
+Firmware (BL3-1).
+
+The design of the runtime services depends heavily on the concepts and
+definitions described in the [SMCCC], in particular SMC Function IDs, Owning
+Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and SMC64 calling
+conventions. Please refer to that document for more detailed explanation of
+these terms.
+
+The following runtime services are expected to be implemented first. They have
+not all been instantiated in the current implementation.
+
+1.  Standard service calls
+
+    This service is for management of the entire system. The Power State
+    Coordination Interface ([PSCI]) is the first set of standard service calls
+    defined by ARM (see PSCI section later).
+
+    NOTE: Currently this service is called PSCI since there are no other
+    defined standard service calls.
+
+2.  Secure-EL1 Payload Dispatcher service
+
+    If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then
+    it also requires a _Secure Monitor_ at EL3 to switch the EL1 processor
+    context between the normal world (EL1/EL2) and trusted world (Secure-EL1).
+    The Secure Monitor will make these world switches in response to SMCs. The
+    [SMCCC] provides for such SMCs with the Trusted OS Call and Trusted
+    Application Call OEN ranges.
+
+    The interface between the EL3 Runtime Firmware and the Secure-EL1 Payload is
+    not defined by the [SMCCC] or any other standard. As a result, each
+    Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime
+    service - within ARM Trusted Firmware this service is referred to as the
+    Secure-EL1 Payload Dispatcher (SPD).
+
+    ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and its
+    associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation
+    are described in the "Secure-EL1 Payloads and Dispatchers" section below.
+
+3.  CPU implementation service
+
+    This service will provide an interface to CPU implementation specific
+    services for a given platform e.g. access to processor errata workarounds.
+    This service is currently unimplemented.
+
+Additional services for ARM Architecture, SiP and OEM calls can be implemented.
+Each implemented service handles a range of SMC function identifiers as
+described in the [SMCCC].
+
+
+### Registration
+
+A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying
+the name of the service, the range of OENs covered, the type of service and
+initialization and call handler functions. This macro instantiates a `const
+struct rt_svc_desc` for the service with these details (see `runtime_svc.h`).
+This structure is allocated in a special ELF section `rt_svc_descs`, enabling
+the framework to find all service descriptors included into BL3-1.
+
+The specific service for a SMC Function is selected based on the OEN and call
+type of the Function ID, and the framework uses that information in the service
+descriptor to identify the handler for the SMC Call.
+
+The service descriptors do not include information to identify the precise set
+of SMC function identifiers supported by this service implementation, the
+security state from which such calls are valid nor the capability to support
+64-bit and/or 32-bit callers (using SMC32 or SMC64). Responding appropriately
+to these aspects of a SMC call is the responsibility of the service
+implementation, the framework is focused on integration of services from
+different providers and minimizing the time taken by the framework before the
+service handler is invoked.
+
+Details of the parameters, requirements and behavior of the initialization and
+call handling functions are provided in the following sections.
+
+
+### Initialization
+
+`runtime_svc_init()` in `runtime_svc.c` initializes the runtime services
+framework running on the primary CPU during cold boot as part of the BL3-1
+initialization. This happens prior to initializing a Trusted OS and running
+Normal world boot firmware that might in turn use these services.
+Initialization involves validating each of the declared runtime service
+descriptors, calling the service initialization function and populating the
+index used for runtime lookup of the service.
+
+The BL3-1 linker script collects all of the declared service descriptors into a
+single array and defines symbols that allow the framework to locate and traverse
+the array, and determine its size.
+
+The framework does basic validation of each descriptor to halt firmware
+initialization if service declaration errors are detected. The framework does
+not check descriptors for the following error conditions, and may behave in an
+unpredictable manner under such scenarios:
+
+1.  Overlapping OEN ranges
+2.  Multiple descriptors for the same range of OENs and `call_type`
+3.  Incorrect range of owning entity numbers for a given `call_type`
+
+Once validated, the service `init()` callback is invoked. This function carries
+out any essential EL3 initialization before servicing requests. The `init()`
+function is only invoked on the primary CPU during cold boot. If the service
+uses per-CPU data this must either be initialized for all CPUs during this call,
+or be done lazily when a CPU first issues an SMC call to that service. If
+`init()` returns anything other than `0`, this is treated as an initialization
+error and the service is ignored: this does not cause the firmware to halt.
+
+The OEN and call type fields present in the SMC Function ID cover a total of
+128 distinct services, but in practice a single descriptor can cover a range of
+OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a
+service handler, the framework uses an array of 128 indices that map every
+distinct OEN/call-type combination either to one of the declared services or to
+indicate the service is not handled. This `rt_svc_descs_indices[]` array is
+populated for all of the OENs covered by a service after the service `init()`
+function has reported success. So a service that fails to initialize will never
+have it's `handle()` function invoked.
+
+The following figure shows how the `rt_svc_descs_indices[]` index maps the SMC
+Function ID call type and OEN onto a specific service handler in the
+`rt_svc_descs[]` array.
+
+![Image 1](diagrams/rt-svc-descs-layout.png?raw=true)
+
+
+### Handling an SMC
+
+When the EL3 runtime services framework receives a Secure Monitor Call, the SMC
+Function ID is passed in W0 from the lower exception level (as per the
+[SMCCC]). If the calling register width is AArch32, it is invalid to invoke an
+SMC Function which indicates the SMC64 calling convention: such calls are
+ignored and return the Unknown SMC Function Identifier result code `0xFFFFFFFF`
+in R0/X0.
+
+Bit[31] (fast/standard call) and bits[29:24] (owning entity number) of the SMC
+Function ID are combined to index into the `rt_svc_descs_indices[]` array. The
+resulting value might indicate a service that has no handler, in this case the
+framework will also report an Unknown SMC Function ID. Otherwise, the value is
+used as a further index into the `rt_svc_descs[]` array to locate the required
+service and handler.
+
+The service's `handle()` callback is provided with five of the SMC parameters
+directly, the others are saved into memory for retrieval (if needed) by the
+handler. The handler is also provided with an opaque `handle` for use with the
+supporting library for parameter retrieval, setting return values and context
+manipulation; and with `flags` indicating the security state of the caller. The
+framework finally sets up the execution stack for the handler, and invokes the
+services `handle()` function.
+
+On return from the handler the result registers are populated in X0-X3 before
+restoring the stack and CPU state and returning from the original SMC.
+
+
+4.  Power State Coordination Interface
+--------------------------------------
+
+TODO: Provide design walkthrough of PSCI implementation.
+
+The complete PSCI API is not yet implemented. The following functions are
+currently implemented:
+
+-   `PSCI_VERSION`
+-   `CPU_OFF`
+-   `CPU_ON`
+-   `CPU_SUSPEND`
+-   `AFFINITY_INFO`
+
+The `CPU_ON`, `CPU_OFF` and `CPU_SUSPEND` functions implement the warm boot
+path in ARM Trusted Firmware. `CPU_ON` and `CPU_OFF` have undergone testing
+on all the supported FVPs. `CPU_SUSPEND` & `AFFINITY_INFO` have undergone
+testing only on the AEM v8 Base FVP. Support for `AFFINITY_INFO` is still
+experimental. Support for `CPU_SUSPEND` is stable for entry into power down
+states. Standby states are currently not supported. `PSCI_VERSION` is
+present but completely untested in this version of the software.
+
+Unsupported PSCI functions can be divided into ones that can return
+execution to the caller and ones that cannot. The following functions
+return with a error code as documented in the [Power State Coordination
+Interface PDD] [PSCI].
+
+-   `MIGRATE` : -1 (NOT_SUPPORTED)
+-   `MIGRATE_INFO_TYPE` : 2 (Trusted OS is either not present or does not
+     require migration)
+-   `MIGRATE_INFO_UP_CPU` : 0 (Return value is UNDEFINED)
+
+The following unsupported functions do not return and signal an assertion
+failure if invoked.
+
+-   `SYSTEM_OFF`
+-   `SYSTEM_RESET`
+
+
+5.  Secure-EL1 Payloads and Dispatchers
+---------------------------------------
+
+On a production system that includes a Trusted OS running in Secure-EL1/EL0,
+the Trusted OS is coupled with a companion runtime service in the BL3-1
+firmware. This service is responsible for the initialisation of the Trusted
+OS and all communications with it. The Trusted OS is the BL3-2 stage of the
+boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load
+and execute a BL3-2 image.
+
+ARM Trusted Firmware uses a more general term for the BL3-2 software that runs
+at Secure-EL1 - the _Secure-EL1 Payload_ - as it is not always a Trusted OS.
+
+The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test
+Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS
+is supported on a production system using the Runtime Services Framework. On
+such a system, the Test BL3-2 image and service are replaced by the Trusted OS
+and its dispatcher service.
+
+The TSP runs in Secure-EL1. It is designed to demonstrate synchronous
+communication with the normal-world software running in EL1/EL2. Communication
+is initiated by the normal-world software
+
+*   either directly through a Fast SMC (as defined in the [SMCCC])
+
+*   or indirectly through a [PSCI] SMC. The [PSCI] implementation in turn
+    informs the TSPD about the requested power management operation. This allows
+    the TSP to prepare for or respond to the power state change
+
+The TSPD service is responsible for.
+
+*   Initializing the TSP
+
+*   Routing requests and responses between the secure and the non-secure
+    states during the two types of communications just described
+
+### Initializing a BL3-2 Image
+
+The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing
+the BL3-2 image. It needs access to the information passed by BL2 to BL3-1 to do
+so. Hence BL3-1 implements:
+
+1.  `bl31_plat_get_bl32_mem_layout()` to return the extents of memory
+    available for BL3-2's use as communicated by BL2.
+
+2.  `bl31_get_next_image_info(uint32_t security_state)` to return a reference
+    to the `el_change_info` structure corresponding to the next image which will
+    be run in the specified security state. The SPD uses this api with the
+    secure security state as the parameter to get entry related information about
+    BL3-2.
+
+In the absence of a BL3-2 image, BL3-1 passes control to the normal world
+bootloader image (BL3-3). When the BL3-2 image is present, it is typical
+that the SPD wants control to be passed to BL3-2 first and then later to BL3-3.
+
+To do this the SPD has to register a BL3-2 initialization function during
+initialization of the SPD service. The BL3-2 initialization function has this
+prototype:
+
+    int32_t init(meminfo *bl32_meminfo);
+
+and is registered using the `bl31_register_bl32_init()` function.
 
-### BL3-2 (Secure Payload) image initialization
+Trusted Firmware supports two approaches for the SPD to pass control to BL3-2
+before returning through EL3 and running the non-trusted firmware (BL3-3):
 
-BL2 is responsible for loading a BL3-2 image in memory specified by the platform.
-BL3-1 provides an api that uses the entrypoint and memory layout information for
-the BL3-2 image provided by BL2 to initialise BL3-2 in S-EL1.
+1.  In the BL3-2 initialization function, set up a secure context (see below
+    for more details of CPU context support) for this CPU and use
+    `bl31_set_next_image_type()` to request that the exit from `bl31_main()` is
+    to the BL3-2 entrypoint in Secure-EL1.
 
+    When the BL3-2 has completed initialization at Secure-EL1, it returns to
+    BL3-1 by issuing an SMC, using a Function ID allocated to the SPD. On
+    receipt of this SMC, the SPD service handler should switch the CPU context
+    from trusted to normal world and use the `bl31_set_next_image_type()` and
+    `bl31_prepare_next_image_entry()` functions to set up the initial return to
+    the normal world firmware BL3-3. On return from the handler the framework
+    will exit to EL2 and run BL3-3.
 
-### Normal world software execution
+2.  In the BL3-2 initialization function, use an SPD-defined mechanism to
+    invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL3-2
+    entrypoint.
+    NOTE: The Test SPD service included with the Trusted Firmware provides one
+    implementation of such a mechanism.
 
-BL3-1 uses the entrypoint information provided by BL2 to jump to the normal
-world software image (BL3-3) at the highest available Exception Level (EL2 if
-available, otherwise EL1).
+    On completion BL3-2 returns control to BL3-1 via a SMC, and on receipt the
+    SPD service handler invokes the synchronous call return mechanism to return
+    to the BL3-2 initialization function. On return from this function,
+    `bl31_main()` will set up the return to the normal world firmware BL3-3 and
+    continue the boot process in the normal world.
 
 
-3.  Memory layout on FVP platforms
+6.  Memory layout on FVP platforms
 ----------------------------------
 
 On FVP platforms, we use the Trusted ROM and Trusted SRAM to store the trusted
@@ -659,7 +933,7 @@ following view:
     ------------ 0x04000000
 
 
-4.  Firmware Image Package (FIP)
+7.  Firmware Image Package (FIP)
 --------------------------------
 
 Using a Firmware Image Package (FIP) allows for packing bootloader images (and
@@ -739,7 +1013,7 @@ Currently the FVPs policy only allows for loading of known images. The platform
 policy can be modified to add additional images.
 
 
-5.  Code Structure
+8.  Code Structure
 ------------------
 
 Trusted Firmware code is logically divided between the three boot loader
@@ -754,11 +1028,13 @@ following categories (present as directories in the source code):
     other code.
 *   **Stage specific.** Code specific to a boot stage.
 *   **Drivers.**
+*   **Services.** EL3 runtime services, e.g. PSCI or SPD. Specific SPD services
+    reside in the `services/spd` directory (e.g. `services/spd/tspd`).
 
 Each boot loader stage uses code from one or more of the above mentioned
 categories. Based upon the above, the code layout looks like this:
 
-    Directory    Used by BL1?    Used by BL2?    Used by BL3?
+    Directory    Used by BL1?    Used by BL2?    Used by BL3-1?
     bl1          Yes             No              No
     bl2          No              Yes             No
     bl31         No              No              Yes
@@ -767,6 +1043,7 @@ categories. Based upon the above, the code layout looks like this:
     drivers      Yes             No              Yes
     common       Yes             Yes             Yes
     lib          Yes             Yes             Yes
+    services     No              No              Yes
 
 All assembler files have the `.S` extension. The linker source files for each
 boot stage have the extension `.ld.S`. These are processed by GCC to create the
@@ -776,7 +1053,7 @@ FDTs provide a description of the hardware platform and are used by the Linux
 kernel at boot time. These can be found in the `fdts` directory.
 
 
-6.  References
+9.  References
 --------------
 
 1.  Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available
diff --git a/docs/rt-svc-writers-guide.md b/docs/rt-svc-writers-guide.md
new file mode 100644
index 0000000..07394b0
--- /dev/null
+++ b/docs/rt-svc-writers-guide.md
@@ -0,0 +1,308 @@
+EL3 Runtime Service Writers Guide for ARM Trusted Firmware
+==========================================================
+
+Contents
+--------
+
+1.  Introduction
+2.  Owning Entities, Call Types and Function IDs
+3.  Getting started
+4.  Registering a runtime service
+5.  Initializing a runtime service
+6.  Handling runtime service requests
+7.  Services that contain multiple sub-services
+8.  Secure-EL1 Payload Dispatcher service (SPD)
+
+- - - - - - - - - - - - - - - - - -
+
+1.  Introduction
+----------------
+
+This document describes how to add a runtime service to the EL3 Runtime
+Firmware component of ARM Trusted Firmware (BL3-1).
+
+Software executing in the normal world and in the trusted world at exception
+levels lower than EL3 will request runtime services using the Secure Monitor
+Call (SMC) instruction. These requests will follow the convention described in
+the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function
+identifiers to each SMC request and describes how arguments are passed and
+results are returned.
+
+SMC Functions are grouped together based on the implementor of the service, for
+example a subset of the Function IDs are designated as "OEM Calls" (see [SMCCC]
+for full details). The EL3 runtime services framework in BL3-1 enables the
+independent implementation of services for each group, which are then compiled
+into the BL3-1 image. This simplifies the integration of common software from
+ARM to support [PSCI], Secure Monitor for a Trusted OS and SoC specific
+software. The common runtime services framework ensures that SMC Functions are
+dispatched to their respective service implementation - the [Firmware Design]
+provides details of how this is achieved.
+
+The interface and operation of the runtime services depends heavily on the
+concepts and definitions described in the [SMCCC], in particular SMC Function
+IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and
+SMC64 calling conventions. Please refer to that document for a full explanation
+of these terms.
+
+
+2.  Owning Entities, Call Types and Function IDs
+------------------------------------------------
+
+The SMC Function Identifier includes a OEN field. These values and their
+meaning are described in [SMCCC] and summarized in table 1 below. Some entities
+are allocated a range of of OENs. The OEN must be interpreted in conjunction
+with the SMC call type, which is either _Fast_ or _Standard_. Fast calls are
+uninterruptible whereas Standard calls can be pre-empted. The majority of
+Owning Entities only have allocated ranges for Fast calls: Standard calls are
+reserved exclusively for Trusted OS providers or for interoperability with
+legacy 32-bit software that predates the [SMCCC].
+
+    Type    OEN     Service
+    Fast     0      ARM Architecture calls
+    Fast     1      CPU Service calls
+    Fast     2      SiP Service calls
+    Fast     3      OEM Service calls
+    Fast     4      Standard Service calls
+    Fast    5-47    Reserved for future use
+    Fast   48-49    Trusted Application calls
+    Fast   50-63    Trusted OS calls
+
+    Std     0- 1    Reserved for existing ARMv7 calls
+    Std     2-63    Trusted OS Standard Calls
+
+_Table 1: Service types and their corresponding Owning Entity Numbers_
+
+Each individual entity can allocate the valid identifiers within the entity
+range as they need - it is not necessary to coordinate with other entities of
+the same type. For example, two SoC providers can use the same Function ID
+within the SiP Service calls OEN range to mean different things - as these
+calls should be specific to the SoC. The Standard Runtime Calls OEN is used for
+services defined by ARM standards, such as [PSCI].
+
+The SMC Function ID also indicates whether the call has followed the SMC32
+calling convention, where all parameters are 32-bit, or the SMC64 calling
+convention, where the parameters are 64-bit. The framework identifies and
+rejects invalid calls that use the SMC64 calling convention but that originate
+from an AArch32 caller.
+
+The EL3 runtime services framework uses the call type and OEN to identify a
+specific handler for each SMC call, but it is expected that an individual
+handler will be responsible for all SMC Functions within a given service type.
+
+
+3.  Getting started
+-------------------
+
+ARM Trusted Firmware has a [`services`] directory in the source tree under
+which each owning entity can place the implementation of its runtime service.
+The [PSCI] implementation is located here in the [`services/psci`] directory.
+
+Runtime service sources will need to include the [`runtime_svc.h`] header file.
+
+
+4.  Registering a runtime service
+---------------------------------
+
+A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying
+the name of the service, the range of OENs covered, the type of service and
+initialization and call handler functions.
+
+    #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch)
+
+*   `_name` is used to identify the data structure declared by this macro, and
+    is also used for diagnostic purposes
+
+*   `_start` and `_end` values must be based on the `OEN_*` values defined in
+    [`runtime_svc.h`]
+
+*   `_type` must be one of `SMC_TYPE_FAST` or `SMC_TYPE_STD`
+
+*   `_setup` is the initialization function with the `rt_svc_init` signature:
+
+        typedef int32_t (*rt_svc_init)(void);
+
+*   `_smch` is the SMC handler function with the `rt_svc_handle` signature:
+
+        typedef uint64_t (*rt_svc_handle)(uint32_t smc_fid,
+                                          uint64_t x1, uint64_t x2,
+                                          uint64_t x3, uint64_t x4,
+                                          void *reserved,
+                                          void *handle,
+                                          uint64_t flags);
+
+Details of the requirements and behavior of the two callbacks is provided in
+the following sections.
+
+During initialization the services framework validates each declared service
+to ensure that the following conditions are met:
+
+1.  The `_start` OEN is not greater than the `_end` OEN
+2.  The `_end` OEN does not exceed the maximum OEN value (63)
+3.  The `_type` is one of `SMC_TYPE_FAST` or `SMC_TYPE_STD`
+4.  `_setup` and `_smch` routines have been specified
+
+[`psci_steup.c`] provides an example of registering a runtime service:
+
+    /* Register PSCI as a run time service */
+    DECLARE_RT_SVC(
+            psci,
+            OEN_STD_START,
+            OEN_STD_END,
+            SMC_TYPE_FAST,
+            psci_setup,
+            psci_smc_handler
+    );
+
+
+5. Initializing a runtime service
+---------------------------------
+
+Runtime services are initialized once, during cold boot, by the primary CPU
+after platform and architectural initialization is complete. The framework
+performs basic validation of the declared service before calling
+the service initialization function (`_setup` in the declaration). This
+function must carry out any essential EL3 initialization prior to receiving a
+SMC Function call via the handler function.
+
+On success, the initialization function must return `0`. Any other return value
+will cause the framework to issue a diagnostic:
+
+    Error initializing runtime service <name of the service>
+
+and then ignore the service - the system will continue to boot but SMC calls
+will not be passed to the service handler and instead return the _Unknown SMC
+Function ID_ result `0xFFFFFFFF`.
+
+If the system must not be allowed to proceed without the service, the
+initialization function must itself cause the firmware boot to be halted.
+
+If the service uses per-CPU data this must either be initialized for all CPUs
+during this call, or be done lazily when a CPU first issues an SMC call to that
+service.
+
+
+6.  Handling runtime service requests
+-------------------------------------
+
+SMC calls for a service are forwarded by the framework to the service's SMC
+handler function (`_smch` in the service declaration). This function must have
+the following signature:
+
+    typedef uint64_t (*rt_svc_handle)(uint32_t smc_fid,
+                                      uint64_t x1, uint64_t x2,
+                                      uint64_t x3, uint64_t x4,
+                                      void *reserved,
+                                      void *handle,
+                                      uint64_t flags);
+
+The handler is responsible for:
+
+1.  Determining that `smc_fid` is a valid and supported SMC Function ID,
+    otherwise completing the request with the _Unknown SMC Function ID_:
+
+        SMC_RET1(handle, SMC_UNK);
+
+2.  Determining if the requested function is valid for the calling security
+    state. SMC Calls can be made from both the normal and trusted worlds and
+    the framework will forward all calls to the service handler.
+
+    The `flags` parameter to this function indicates the caller security state
+    in bit[0], where a value of `1` indicates  a non-secure caller. The
+    `is_caller_secure(flags)` and `is_caller_non_secure(flags)` can be used to
+    test this condition.
+
+    If invalid, the request should be completed with:
+
+        SMC_RET1(handle, SMC_UNK);
+
+3.  Truncating parameters for calls made using the SMC32 calling convention.
+    Such calls can be determined by checking the CC field in bit[30] of the
+    `smc_fid` parameter, for example by using:
+
+        if (GET_SMC_CC(smc_fid) == SMC_32) ...
+
+    For such calls, the upper bits of the parameters x1-x4 and the saved
+    parameters X5-X7 are UNDEFINED and must be explicitly ignored by the
+    handler. This can be done by truncating the values to a suitable 32-bit
+    integer type before use, for example by ensuring that functions defined
+    to handle individual SMC Functions use appropriate 32-bit parameters.
+
+4.  Providing the service requested by the SMC Function, utilizing the
+    immediate parameters x1-x4 and/or the additional saved parameters X5-X7.
+    The latter can be retrieved using the `SMC_GET_GP(handle, ref)` function,
+    supplying the appropriate `CTX_GPREG_Xn` reference, e.g.
+
+        uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6);
+
+5.  Implementing the standard SMC32 Functions that provide information about
+    the implementation of the service. These are the Call Count, Implementor
+    UID and Revision Details for each service documented in section 6 of the
+    [SMCCC].
+
+    The ARM Trusted Firmware expects owning entities to follow this
+    recommendation.
+
+5.  Returning the result to the caller. The [SMCCC] allows for up to 256 bits
+    of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The
+    framework provides a family of macros to set the multi-register return
+    value and complete the handler:
+
+        SMC_RET1(handle, x0);
+        SMC_RET2(handle, x0, x1);
+        SMC_RET3(handle, x0, x1, x2);
+        SMC_RET4(handle, x0, x1, x2, x3);
+
+The `reserved` parameter to the handler is reserved for future use and can be
+ignored. The value returned by a SMC handler is also reserved for future use -
+completion of the handler function must always be via one of the `SMC_RETn()`
+macros.
+
+NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
+all of the above requirements yet.
+
+
+7.  Services that contain multiple sub-services
+-----------------------------------------------
+
+It is possible that a single owning entity implements multiple sub-services. For
+example, the Standard calls service handles `0x84000000`-`0x8400FFFF` and
+`0xC4000000`-`0xC400FFFF` functions. Within that range, the [PSCI] service
+handles the `0x84000000`-`0x8400001F` and `0xC4000000`-`0xC400001F` functions.
+In that respect, [PSCI] is a 'sub-service' of the Standard calls service. In
+future, there could be additional such sub-services in the Standard calls
+service which perform independent functions.
+
+In this situation it may be valuable to introduce a second level framework to
+enable independent implementation of sub-services. Such a framework might look
+very similar to the current runtime services framework, but using a different
+part of the SMC Function ID to identify the sub-service. Trusted Firmware does
+not provide such a framework at present.
+
+
+8.  Secure-EL1 Payload Dispatcher service (SPD)
+-----------------------------------------------
+
+Services that handle SMC Functions targeting a Trusted OS, Trusted Application,
+or other Secure-EL1 Payload are special. These services need to manage the
+Secure-EL1 context, provide the _Secure Monitor_ functionality of switching
+between the normal and secure worlds, deliver SMC Calls through to Secure-EL1
+and generally manage the Secure-EL1 Payload through CPU power-state transitions.
+
+TODO: Provide details of the additional work required to implement a SPD and
+the BL3-1 support for these services. Or a reference to the document that will
+provide this information....
+
+
+- - - - - - - - - - - - - - - - - - - - - - - - - -
+
+_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
+
+
+[Firmware Design]:  ./firmware-design.md
+
+[`services`]:       ../services
+[`services/psci`]:  ../services/psci
+[`psci_steup.c`]:   ../services/psci/psci_setup.c
+[`runtime_svc.h`]:  ../include/runtime_svc.h
+[PSCI]:             http://infocenter.arm.com/help/topic/com.arm.doc.den0022b/index.html "Power State Coordination Interface PDD (ARM DEN 0022B.b)"
+[SMCCC]:            http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"