/* * Copyright (c) 2018, Texas Instruments Incorporated * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * * Neither the name of Texas Instruments Incorporated nor the names of * its contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /** * \defgroup DRV_SCICLIENT_MODULE SCIClient Driver * * @{ * * System Controller Interface (SCI) Client * * \par IMPORTANT NOTE * The interfaces defined in this package are bound to change. * Release notes/user guide list the additional limitation/restriction * of this module/interfaces. See also \ref TI_DISCLAIMER. \n * Refer to top level user guide for detailed features, * limitations and usage description. * * * ## Introduction to SCICLIENT * The SCIClient is an interface to the TI-SCI protocol for RTOS and non-OS * based applications. It exposes the core message details, valid module/clock * IDs to the higher level software and abstracts the communication with the * firmware based on the TI-SCI protocol. These APIs can be called by power, * resource and security RTOS drivers or any other non-OS or RTOS based higher * level software to be able to communicate with DMSC for its services. The * higher level software is expected to populate the necessary message core * parameters. The SCIClient would wrap the core message with the necessary * protocol header and forward this to the DMSC. The SCIClient relies on the * CSL-FL layer to program and interact with the Secure Proxy Threads. The * SCIClient's goal is to ensure there is no duplication of the interface to * the DMSC from different software components which need to interact with * the DMSC or other System Control Entities in future devices. * The Sciclient contains * - \ref SCICLIENT_HAL * - \ref SCICLIENT_FMW_PM_IF * - \ref SCICLIENT_FMW_RM_IF * - \ref SCICLIENT_FMW_PROCBOOT_IF * - \ref SCICLIENT_ROM_HAL * * ## Introduction to DMSC * Traditional Texas Instruments SoCs have implemented system control * functions such as power management within operating systems on each of * the processing units (ARM/DSP). However, such a traditional approach * has had tremendous challenges to ensure system stability. Few of the * challenges faced include: * * - Complex interactions between Operating Systems on heterogeneous SoCs for * generic features. * - Lack of centralized knowledge of system state. * - Consistency in SoC feature entitlement in all OSes for the SoC for * complex SoC features and system quirks. * * Device Management and Security control (DMSC) attempts to resolve * these issues by being a consistent component of Keystone 3 SoC * architecture performing the role of a centralized SoC power, security * and device management controller. * * In effect, this is a microcontroller and runs a safety and security * certified firmware that provides services to the rest of the * OSes/Software running on various other processors on the SoC. * * ### DMSC Power Management * DMSC controls the power management of the device, hence is responsible for * bringing the device out of reset, enforce clock and reset rules. DMSC power * management functions are critical to bring device to low power modes, for * example DeepSleep, and sense wake-up events to bring device back online to * active state. * * ### DMSC Security Management * The DMSC firmware Security Management manages SoC central security * resources. The security subsystem provides APIs to other software entities to * avail these features in a controlled and secure way. * The security management firmware is subdivided into modules listed below: * - Firewall management * - ISC management * - Boot authentication * - SA2UL context management (for encryption and authentication) * - Crypto APIs (to access common SA2UL functions such as PKA, RNG) * - Secure keys management * - Secure debug * * ### DMSC Resource Management * The DMSC firmware Resource Management (RM) (sub) system manages SoC shared * resources. RM manages access and configuration of shared resources amongst * SoC processing entities. RM provides a set of interfaces over which SoC * processing entities can allocate and free access to shared resources. * * The resource management firmware is subdivided into modules listed below: * - Core database * - IRQ management * - Ring accelerator management * - UDMA-P management * - PSI-L management * - Non-secure proxy management * * ### Communication with DMSC * DMSC is a "black box" with respect to the other processing * entities (ARM/DSP) on the SoC. Communication with DMSC occurs over * a messaging protocol called the Texas Instruments System Control * Interface (TI-SCI). TI-SCI is a predefined request-response protocol * that provides access to the various services provided by DMSC. * * The actual messaging hardware block varies depending on SoC, but * typical examples include "Proxy over message manager" and * "Secure Proxy over Ring Accellerator". These communication * mechanisms are standardized and secured by DMSC firmware prior to * operation. * * The request/response format is described overall as in Figure 2 . The * message type describes the service to be performed and is operated * on depending on few attributes including privileges allowed and * operational state of the SoC. * * |Type | Byte Index| Data Type| Header * |:----|:---------:|:--------:|:------ * |TISCI Header| [0:1]| U16| Message_type * || [2]| U8| Host * || [3]| U8| Sequence_id * || [4:7]| U32| Flags * |Payload | Depends on type of message||Payload Fields| */ /* @} */ /** * \ingroup DRV_SCICLIENT_MODULE * \defgroup SCICLIENT_HAL System Controller Interface (SCI) Client HAL * * The SCIClient has two major functions: * - Interact with DMSC ROM and load the DMSC Firmware. * - Pass on service requests from higher level software to the DMSC firmware * and forward the response from DMSC firmware to the higher level software. * * The #Sciclient_loadFirmware API is used to cater to the first requirement * and the #Sciclient_service is used to cater to the second. The SCIClient * library requires initialization of the a handle which is used by the * subsequent API calls. This handle is initialized by the #Sciclient_init * function. Once the application/higher level software is being torn down or * exiting the #Sciclient_deinit can be used to de-initialize this handle. * * The SCIClient can operate in the following combinations: * * 1. Non-OS, Polling based message completion. * 2. Non-OS, Interrupt Based message completion. * 3. RTOS, Polling based message completion. * 4. RTOS, Interrupt based message completion. * * The SCIClient depends on the OSAL layer to differentiate between the * Non-OS and the RTOS implementation of Semaphores and Interrupts (HWIs). * The build parameter of the OSAL library would determine if the application * is bare metal or RTOS based. The polling versus interrupt based wait for * message completion is a run time configuration passed during the * #Sciclient_init initialization. * * All the APIs for interacting with the firmware are blocking with a * specified timeout . A common API #Sciclient_service is implemented for * all types of calls to the firmware which takes 2 arguments : * - #Sciclient_ReqPrm_t * - #Sciclient_RespPrm_t * * The API serves a particular request, based on the value of messageType * parameter in #Sciclient_ReqPrm_t, whose response is given to the higher * level API through #Sciclient_RespPrm_t. The #Sciclient_ReqPrm_t contains * the required inputs from the higher level software corresponding to the * message_type, timeout value and the core message as a byte stream. * A pointer #Sciclient_RespPrm_t has to be passed to the sciclient, which * shall be modified by sciclient. * * The Sciclient shall be responsible for abstracting all interaction with the * secure proxy and the ring accelerator. * * @{ */ /** * \file sciclient.h * * \brief This file contains prototypes for APIs contained * as a part of SCICLIENT as well as the structures * of their arguments. */ #ifndef SCICLIENT_H_ #define SCICLIENT_H_ /* ========================================================================== */ /* Include Files */ /* ========================================================================== */ #include #include #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /* ========================================================================== */ /* Macros & Typedefs */ /* ========================================================================== */ /** * \anchor Sciclient_ServiceOperationMode * \name Sciclient Service API Operation Mode * @{ * Sciclient Service API Operation Mode. The different types of modes supported * are:\n * (1) Polled Mode : no interrupts are registered. The completion of a message * is via polling on the Proxy registers.\n * (2) Interrupt Mode : Interrupt are registered and the response message would * be via a interrupt routine. * Default mode in case #Sciclient_ConfigPrms_t is NULL is interrupt. */ #define SCICLIENT_SERVICE_OPERATION_MODE_POLLED (0U) #define SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT (1U) /* @} */ /** * \anchor Sciclient_ServiceOperationTimeout * \name Sciclient Service API Operation Timeout * @{ * Sciclient Service API Timeout Values. The different types are:\n * (1) Wait forever for an operation to complete. \n * (2) Do not wait for the operation to complete. \n * (3) Wait for a given time interface for the operation to complete. */ #define SCICLIENT_SERVICE_WAIT_FOREVER (0xFFFFFFFFU) #define SCICLIENT_SERVICE_NO_WAIT (0x0U) /* @} */ /* ========================================================================== */ /* Structure Declarations */ /* ========================================================================== */ /** * \brief Initialization parameters for sciclient. * Pointer to this is passed to #Sciclient_init. */ typedef struct { uint32_t opModeFlag; /**< Operation mode for the Sciclient Service API. Refer to * \ref Sciclient_ServiceOperationMode for valid values. */ Sciclient_BoardCfgPrms_t * pBoardCfgPrms; /**< NULL will result in using default board configuration. * Refer #Sciclient_BoardCfgPrms_t */ uint32_t isSecureMode; /**< Variable to check whether Core context is secure/non-secure. This has * to be given by the user via configParams. Default value is 0. */ } Sciclient_ConfigPrms_t; /** * \brief Input parameters for #Sciclient_service function. */ typedef struct { uint16_t messageType; /**< [IN] Type of message. */ uint32_t flags; /**< [IN] Flags for messages that are being transmitted. * */ const uint8_t *pReqPayload; /**< [IN] Pointer to the payload to be transmitted */ uint32_t reqPayloadSize; /**< [IN] Size of the payload to be transmitted (in bytes)*/ uint32_t timeout; /**< [IN] Timeout(number of iterations) for receiving response * (Refer \ref Sciclient_ServiceOperationTimeout) */ } Sciclient_ReqPrm_t; /** * \brief Output parameters for #Sciclient_service function. */ typedef struct { uint32_t flags; /**< [OUT] Flags of response to messages. */ uint8_t *pRespPayload; /**< [IN] Pointer to the received payload. The pointer is an input. The * API will populate this with the firmware response upto the * size mentioned in respPayloadSize. Please ensure respPayloadSize * bytes are allocated. */ uint32_t respPayloadSize; /**< [IN] Size of the response payload(in bytes) */ } Sciclient_RespPrm_t; /* ========================================================================== */ /* Function Declarations */ /* ========================================================================== */ /** * \brief Loads the DMSC firmware. This is typically called by SBL. Load * firmware does not require calling the #Sciclient_init function. * * Requirement: DOX_REQ_TAG(PDK-2137), DOX_REQ_TAG(PDK-2138) * * \param pSciclient_firmware [IN] Pointer to signed SYSFW binary * * \return CSL_PASS on success, else failure * */ int32_t Sciclient_loadFirmware(const uint32_t *pSciclient_firmware); /** * \brief This API is called once for registering interrupts and creating * semaphore handles to be able to talk to the firmware. * The application should assume that the firmware is pre-loaded while * calling the #Sciclient_init API. * The firmware should have been loaded either via GEL or via the SBL * prior to the application calling the #Sciclient_init. * If a void pointer is passed, default values will be used, else * the values passed will be used. * * Requirement: DOX_REQ_TAG(PDK-2146) * * \param pCfgPrms [IN] Pointer to #Sciclient_ConfigPrms_t * * \return CSL_PASS on success, else failure * */ int32_t Sciclient_init(const Sciclient_ConfigPrms_t *pCfgPrms); /** * \brief This API allows communicating with the System firmware which can be * called to perform various functions in the system. * Core sciclient function for transmitting payload and recieving * the response. * The caller is expected to allocate memory for the input request * parameter (Refer #Sciclient_ReqPrm_t). This involves setting the * message type being communicated to the firmware, the response flags, * populate the payload of the message based on the inputs in the * files sciclient_fmwPmMessages.h,sciclient_fmwRmMessages.h, * sciclient_fmwSecMessages.h and sciclient_fmwCommonMessages.h. * Since the payload in considered a stream of bytes in this API, * the caller should also populate the size of this stream in * reqPayloadSize. The timeout is used to determine for what amount * of iterations the API would wait for their operation to complete. * * To make sure the response is captured correctly the caller should * also allocate the space for #Sciclient_RespPrm_t parameters. The * caller should populate the pointer to the pRespPayload and the size * respPayloadSize. The API would populate the response flags to * indicate any firmware specific errors and also populate the memory * pointed by pRespPayload till the size given in respPayloadSize. * * * Requirement: DOX_REQ_TAG(PDK-2142), DOX_REQ_TAG(PDK-2141), * DOX_REQ_TAG(PDK-2140), DOX_REQ_TAG(PDK-2139) * * \param pReqPrm [IN] Pointer to #Sciclient_ReqPrm_t * \param pRespPrm [OUT] Pointer to #Sciclient_RespPrm_t * * \return CSL_PASS on success, else failure * */ int32_t Sciclient_service(const Sciclient_ReqPrm_t *pReqPrm, Sciclient_RespPrm_t *pRespPrm); /** * \brief De-initialization of sciclient. This de-initialization is specific * to the application. It only de-initializes the semaphores, * interrupts etc. which are initialized in #Sciclient_init. It does * not de-initialize the system firmware. * * Requirement: DOX_REQ_TAG(PDK-2146) * * \return CSL_PASS on success, else failure * */ int32_t Sciclient_deinit(void); /**< * \brief API to verify that firmware ABI matches the supported ABI. * * \return CSL_PASS on success, else failure */ int32_t Sciclient_abiCheck(void); /* * Structure Init functions * * Requirement: DOX_REQ_TAG(PDK-2936) */ /** * \brief Sciclient_ConfigPrms_t structure init function. * * \param pCfgPrms [IN] Pointer to #Sciclient_ConfigPrms_t structure. * */ static inline void Sciclient_configPrmsInit(Sciclient_ConfigPrms_t *pCfgPrms); /* ========================================================================== */ /* Static Function Definitions */ /* ========================================================================== */ static inline void Sciclient_configPrmsInit(Sciclient_ConfigPrms_t *pCfgPrms) { if(NULL != pCfgPrms) { pCfgPrms->opModeFlag = SCICLIENT_SERVICE_OPERATION_MODE_POLLED; pCfgPrms->pBoardCfgPrms = NULL; pCfgPrms->isSecureMode = 0U; } } #ifdef __cplusplus } #endif #endif /* #ifndef SCICLIENT_H_ */ /* @} */