1 /*
2 * Copyright (c) 2018-2020, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
33 /**
34 * \defgroup DRV_SCICLIENT_MODULE SCIClient Driver
35 *
36 * @{
37 *
38 * System Controller Interface (SCI) Client
39 *
40 * \par IMPORTANT NOTE
41 * <b> The interfaces defined in this package are bound to change.
42 * Release notes/user guide list the additional limitation/restriction
43 * of this module/interfaces. </b> \n
44 * <b> Refer to top level user guide for detailed features,
45 * limitations and usage description.
46 * </b>
47 *
48 * ## Introduction to SCICLIENT
49 * The SCIClient is an interface to the TI-SCI protocol for RTOS and non-OS
50 * based applications. It exposes the core message details, valid module/clock
51 * IDs to the higher level software and abstracts the communication with the
52 * firmware based on the TI-SCI protocol. These APIs can be called by power,
53 * resource and security RTOS drivers or any other non-OS or RTOS based higher
54 * level software to be able to communicate with DMSC for its services. The
55 * higher level software is expected to populate the necessary message core
56 * parameters. The SCIClient would wrap the core message with the necessary
57 * protocol header and forward this to the DMSC. The SCIClient relies on the
58 * CSL-FL layer to program and interact with the Secure Proxy Threads. The
59 * SCIClient's goal is to ensure there is no duplication of the interface to
60 * the DMSC from different software components which need to interact with
61 * the DMSC or other System Control Entities in future devices.
62 * The Sciclient contains
63 * - \ref SCICLIENT_HAL
64 * - \ref SCICLIENT_FMW_PM_IF
65 * - \ref SCICLIENT_FMW_RM_IF
66 * - \ref SCICLIENT_FMW_PROCBOOT_IF
67 * - \ref SCICLIENT_ROM_HAL
68 *
69 * ## Introduction to DMSC
70 * Traditional Texas Instruments SoCs have implemented system control
71 * functions such as power management within operating systems on each of
72 * the processing units (ARM/DSP). However, such a traditional approach
73 * has had tremendous challenges to ensure system stability. Few of the
74 * challenges faced include:
75 *
76 * - Complex interactions between Operating Systems on heterogeneous SoCs for
77 * generic features.
78 * - Lack of centralized knowledge of system state.
79 * - Consistency in SoC feature entitlement in all OSes for the SoC for
80 * complex SoC features and system quirks.
81 *
82 * Device Management and Security control (DMSC) attempts to resolve
83 * these issues by being a consistent component of Keystone 3 SoC
84 * architecture performing the role of a centralized SoC power, security
85 * and device management controller.
86 *
87 * In effect, this is a microcontroller and runs a safety and security
88 * certified firmware that provides services to the rest of the
89 * OSes/Software running on various other processors on the SoC.
90 *
91 * ### DMSC Power Management
92 * DMSC controls the power management of the device, hence is responsible for
93 * bringing the device out of reset, enforce clock and reset rules. DMSC power
94 * management functions are critical to bring device to low power modes, for
95 * example DeepSleep, and sense wake-up events to bring device back online to
96 * active state.
97 *
98 * ### DMSC Security Management
99 * The DMSC firmware Security Management manages SoC central security
100 * resources. The security subsystem provides APIs to other software entities to
101 * avail these features in a controlled and secure way.
102 * The security management firmware is subdivided into modules listed below:
103 * - Firewall management
104 * - ISC management
105 * - Boot authentication
106 * - SA2UL context management (for encryption and authentication)
107 * - Crypto APIs (to access common SA2UL functions such as PKA, RNG)
108 * - Secure keys management
109 * - Secure debug
110 *
111 * ### DMSC Resource Management
112 * The DMSC firmware Resource Management (RM) (sub) system manages SoC shared
113 * resources. RM manages access and configuration of shared resources amongst
114 * SoC processing entities. RM provides a set of interfaces over which SoC
115 * processing entities can allocate and free access to shared resources.
116 *
117 * The resource management firmware is subdivided into modules listed below:
118 * - Core database
119 * - IRQ management
120 * - Ring accelerator management
121 * - UDMA-P management
122 * - PSI-L management
123 * - Non-secure proxy management
124 *
125 * ### Communication with DMSC
126 * DMSC is a "black box" with respect to the other processing
127 * entities (ARM/DSP) on the SoC. Communication with DMSC occurs over
128 * a messaging protocol called the Texas Instruments System Control
129 * Interface (TI-SCI). TI-SCI is a predefined request-response protocol
130 * that provides access to the various services provided by DMSC.
131 *
132 * The actual messaging hardware block varies depending on SoC, but
133 * typical examples include "Proxy over message manager" and
134 * "Secure Proxy over Ring Accellerator". These communication
135 * mechanisms are standardized and secured by DMSC firmware prior to
136 * operation.
137 *
138 * The request/response format is described overall as in Figure 2 . The
139 * message type describes the service to be performed and is operated
140 * on depending on few attributes including privileges allowed and
141 * operational state of the SoC.
142 *
143 * |Type | Byte Index| Data Type| Header
144 * |:----|:---------:|:--------:|:------
145 * |TISCI Header| [0:1]| U16| Message_type
146 * || [2]| uint8_t| Host
147 * || [3]| uint8_t| Sequence_id
148 * || [4:7]| U32| Flags
149 * |Payload | Depends on type of message||Payload Fields|
150 */
151 /* @} */
153 /**
154 * \ingroup DRV_SCICLIENT_MODULE
155 * \defgroup SCICLIENT_HAL System Controller Interface (SCI) Client HAL
156 *
157 * The SCIClient has two major functions:
158 * - Interact with DMSC ROM and load the DMSC Firmware.
159 * - Pass on service requests from higher level software to the DMSC firmware
160 * and forward the response from DMSC firmware to the higher level software.
161 *
162 * The #Sciclient_loadFirmware API is used to cater to the first requirement
163 * and the #Sciclient_service is used to cater to the second. The SCIClient
164 * library requires initialization of the a handle which is used by the
165 * subsequent API calls. This handle is initialized by the #Sciclient_init
166 * function. Once the application/higher level software is being torn down or
167 * exiting the #Sciclient_deinit can be used to de-initialize this handle.
168 *
169 * The SCIClient can operate in the following combinations:
170 *
171 * 1. Non-OS, Polling based message completion.
172 * 2. Non-OS, Interrupt Based message completion.
173 * 3. RTOS, Polling based message completion.
174 * 4. RTOS, Interrupt based message completion.
175 *
176 * The SCIClient depends on the OSAL layer to differentiate between the
177 * Non-OS and the RTOS implementation of Semaphores and Interrupts (HWIs).
178 * The build parameter of the OSAL library would determine if the application
179 * is bare metal or RTOS based. The polling versus interrupt based wait for
180 * message completion is a run time configuration passed during the
181 * #Sciclient_init initialization.
182 *
183 * All the APIs for interacting with the firmware are blocking with a
184 * specified timeout . A common API #Sciclient_service is implemented for
185 * all types of calls to the firmware which takes 2 arguments :
186 * - #Sciclient_ReqPrm_t
187 * - #Sciclient_RespPrm_t
188 *
189 * The API serves a particular request, based on the value of messageType
190 * parameter in #Sciclient_ReqPrm_t, whose response is given to the higher
191 * level API through #Sciclient_RespPrm_t. The #Sciclient_ReqPrm_t contains
192 * the required inputs from the higher level software corresponding to the
193 * message_type, timeout value and the core message as a byte stream.
194 * A pointer #Sciclient_RespPrm_t has to be passed to the sciclient, which
195 * shall be modified by sciclient.
196 *
197 * The Sciclient shall be responsible for abstracting all interaction with the
198 * secure proxy and the ring accelerator.
199 *
200 * @{
201 */
203 /**
204 * \file sciclient.h
205 *
206 * \brief This file contains prototypes for APIs contained
207 * as a part of SCICLIENT as well as the structures
208 * of their arguments.
209 */
211 #ifndef SCICLIENT_H_
212 #define SCICLIENT_H_
214 /* ========================================================================== */
215 /* Include Files */
216 /* ========================================================================== */
218 #include <stdint.h>
219 #include <stddef.h>
221 /* Windows Visual Studio build doesn't __attribute__ indentifier, so forcing it be to dummy for getting build working */
222 #ifdef _MSC_VER
223 #ifndef __attribute__
224 #define __attribute__()
225 #endif
226 #endif
228 /* TISCI Include */
229 #define TISCI_BIT(n) (1UL << (n))
231 /**
232 * \brief Defines the sysfw DOMGRP type. This is meant to be used in code
233 * or data structures that require distinction of domgrps.
234 */
235 typedef uint8_t domgrp_t;
237 #ifndef SYSFW_DEVGRPS_H
238 /**
239 * \brief Defines the sysfw DEVGRP type. This is meant to be used in code
240 * or data structures that require distinction of devgrps.
241 */
242 typedef uint8_t devgrp_t;
244 /* External definitions */
246 /**
247 * SoC SYSFW devgrp any: NOT TO BE used for SoC data.
248 * This implies that specific sequenced devgrp is NOT used
249 */
250 #define DEVGRP_ALL (0x00U)
252 /** SoC defined SYSFW devgrp 00 */
253 #define DEVGRP_00 ((0x01U) << 0U)
254 /** SoC defined SYSFW devgrp 01 */
255 #define DEVGRP_01 ((0x01U) << 1U)
256 /** SoC defined SYSFW devgrp 02 */
257 #define DEVGRP_02 ((0x01U) << 2U)
258 /** SoC defined SYSFW devgrp 03 */
259 #define DEVGRP_03 ((0x01U) << 3U)
260 /** SoC defined SYSFW devgrp 04 */
261 #define DEVGRP_04 ((0x01U) << 4U)
262 /** SoC defined SYSFW devgrp 05 */
263 #define DEVGRP_05 ((0x01U) << 5U)
264 /** SoC defined SYSFW devgrp 06 */
265 #define DEVGRP_06 ((0x01U) << 6U)
267 /** SYSFW internal usage ONLY */
269 /** Module belonging solely to DMSC operations */
270 #define DEVGRP_DMSC ((0x01U) << 7U)
271 /** Match everything - STRICTLY INTERNAL USAGE ONLY */
272 #define DEVGRP_DMSC_ALL (0xFFU)
274 #endif
276 /**
277 * Maximum number of devgrps that are supported by SYSFW.
278 * Derived from the above definitions
279 */
280 #define MAX_NUM_DEVGRPS (8U)
282 #include <ti/drv/sciclient/soc/sysfw/include/tisci/tisci_protocol.h>
283 #include <ti/drv/sciclient/soc/sysfw/include/tisci/tisci_boardcfg_macros.h>
284 #include <ti/drv/sciclient/soc/sysfw/include/tisci/tisci_boardcfg.h>
285 #include <ti/drv/sciclient/soc/sysfw/include/tisci/tisci_boardcfg_rm.h>
286 #include <ti/drv/sciclient/soc/sysfw/include/tisci/tisci_core.h>
287 #if defined (SOC_AM65XX)
288 #include <ti/drv/sciclient/soc/sysfw/include/am65x/tisci_resasg_types.h>
289 #include <ti/drv/sciclient/soc/sysfw/include/am65x/tisci_hosts.h>
290 #include <ti/drv/sciclient/soc/sysfw/include/am65x/tisci_sec_proxy.h>
291 #include <ti/drv/sciclient/soc/sysfw/include/am65x/tisci_boardcfg_constraints.h>
292 #include <ti/drv/sciclient/soc/sysfw/include/am65x/tisci_clocks.h>
293 #include <ti/drv/sciclient/soc/sysfw/include/am65x_sr2/tisci_clocks.h>
294 #endif
295 #if defined (SOC_J721E)
296 #include <ti/drv/sciclient/soc/sysfw/include/j721e/tisci_resasg_types.h>
297 #include <ti/drv/sciclient/soc/sysfw/include/j721e/tisci_hosts.h>
298 #include <ti/drv/sciclient/soc/sysfw/include/j721e/tisci_sec_proxy.h>
299 #include <ti/drv/sciclient/soc/sysfw/include/j721e/tisci_boardcfg_constraints.h>
300 #endif
301 #if defined (SOC_J7200)
302 #include <ti/drv/sciclient/soc/sysfw/include/j7200/tisci_resasg_types.h>
303 #include <ti/drv/sciclient/soc/sysfw/include/j7200/tisci_hosts.h>
304 #include <ti/drv/sciclient/soc/sysfw/include/j7200/tisci_sec_proxy.h>
305 #include <ti/drv/sciclient/soc/sysfw/include/j7200/tisci_boardcfg_constraints.h>
306 #endif
307 #if defined (SOC_AM64X)
308 #include <ti/drv/sciclient/soc/sysfw/include/am64x/tisci_resasg_types.h>
309 #include <ti/drv/sciclient/soc/sysfw/include/am64x/tisci_hosts.h>
310 #include <ti/drv/sciclient/soc/sysfw/include/am64x/tisci_sec_proxy.h>
311 #include <ti/drv/sciclient/soc/sysfw/include/am64x/tisci_boardcfg_constraints.h>
312 #endif
314 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_sec_macros.h>
315 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_dkek.h>
316 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_ext_otp.h>
317 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_firewall.h>
318 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_keystore.h>
319 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_procboot.h>
320 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_sa2ul_rm.h>
321 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_sec_handover.h>
322 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_secure_jtag.h>
323 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_soc_uid.h>
324 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_keywriter.h>
325 #include <ti/drv/sciclient/soc/sysfw/include/tisci/security/tisci_dkek.h>
326 #include <ti/drv/sciclient/soc/sysfw/include/tisci/pm/tisci_pm_clock.h>
327 #include <ti/drv/sciclient/soc/sysfw/include/tisci/pm/tisci_pm_device.h>
328 #include <ti/drv/sciclient/soc/sysfw/include/tisci/pm/tisci_pm_core.h>
329 #include <ti/drv/sciclient/soc/sysfw/include/tisci/rm/tisci_rm_ra.h>
330 #include <ti/drv/sciclient/soc/sysfw/include/tisci/rm/tisci_rm_irq.h>
331 #include <ti/drv/sciclient/soc/sysfw/include/tisci/rm/tisci_rm_udmap.h>
332 #include <ti/drv/sciclient/soc/sysfw/include/tisci/rm/tisci_rm_psil.h>
333 #include <ti/drv/sciclient/soc/sysfw/include/tisci/rm/tisci_rm_shared.h>
334 #include <ti/drv/sciclient/soc/sysfw/include/tisci/rm/tisci_rm_core.h>
335 #include <ti/drv/sciclient/soc/sysfw/include/tisci/rm/tisci_rm_proxy.h>
336 #include <ti/drv/sciclient/soc/sciclient_soc_priv.h>
337 #include <ti/drv/sciclient/include/sciclient_soc.h>
338 #include <ti/drv/sciclient/include/sciclient_pm.h>
339 #include <ti/drv/sciclient/include/sciclient_rm.h>
340 #include <ti/drv/sciclient/include/sciclient_firewall.h>
341 #include <ti/drv/sciclient/include/sciclient_dkek.h>
342 #include <ti/drv/sciclient/include/sciclient_genericMsgs.h>
343 #include <ti/drv/sciclient/include/sciclient_procboot.h>
344 #include <ti/drv/sciclient/include/sciclient_boardcfg.h>
345 #include <ti/drv/sciclient/include/sciclient_keywriter.h>
347 #ifdef __cplusplus
348 extern "C" {
349 #endif
351 /* ========================================================================== */
352 /* Macros & Typedefs */
353 /* ========================================================================== */
355 /**
356 * \anchor Sciclient_ServiceOperationMode
357 * \name Sciclient Service API Operation Mode
358 * @{
359 * Sciclient Service API Operation Mode. The different types of modes supported
360 * are:\n
361 * (1) Polled Mode : no interrupts are registered. The completion of a message
362 * is via polling on the Proxy registers.\n
363 * (2) Interrupt Mode : Interrupt are registered and the response message would
364 * be via a interrupt routine.
365 * Default mode in case #Sciclient_ConfigPrms_t is NULL is interrupt.
366 */
367 #define SCICLIENT_SERVICE_OPERATION_MODE_POLLED (0U)
368 #define SCICLIENT_SERVICE_OPERATION_MODE_INTERRUPT (1U)
369 /* @} */
371 /**
372 * \anchor Sciclient_ServiceOperationTimeout
373 * \name Sciclient Service API Operation Timeout
374 * @{
375 * Sciclient Service API Timeout Values. The different types are:\n
376 * (1) Wait forever for an operation to complete. \n
377 * (2) Do not wait for the operation to complete. \n
378 * (3) Wait for a given time interface for the operation to complete.
379 */
380 #define SCICLIENT_SERVICE_WAIT_FOREVER (0xFFFFFFFFU)
381 #define SCICLIENT_SERVICE_NO_WAIT (0x0U)
382 /* @} */
384 /** Fault tolerant Pass */
385 #define SCICLIENT_FT_PASS (0xA5A5U)
386 /** Fault tolerant Fail */
387 #define SCICLIENT_FT_FAIL (0x5A5AU)
390 /* ========================================================================== */
391 /* Structure Declarations */
392 /* ========================================================================== */
394 /**
395 * \brief Initialization parameters for sciclient.
396 * Pointer to this is passed to #Sciclient_init.
397 */
398 typedef struct
399 {
400 uint32_t opModeFlag;
401 /**< Operation mode for the Sciclient Service API. Refer to
402 * \ref Sciclient_ServiceOperationMode for valid values.
403 */
404 Sciclient_BoardCfgPrms_t * pBoardCfgPrms;
405 /**< NULL will result in using default board configuration.
406 * Refer #Sciclient_BoardCfgPrms_t
407 */
408 uint32_t isSecureMode;
409 /**< Variable to check whether Core context is secure/non-secure. This has
410 * to be given by the user via configParams. Default value is 0.
411 */
412 uint32_t c66xRatRegion;
413 /**< C66x Rat region to use for mapping the IR */
414 uint8_t skipLocalBoardCfgProcess;
415 /**< Skip processing of local RM/PM board configurations during
416 * initialization */
417 Sciclient_BoardCfgPrms_t inPmPrms;
418 /**< Power Management Board Config Input Parameters */
419 Sciclient_BoardCfgPrms_t inRmPrms;
420 /**< Resource Management Board Config Input Parameters */
421 } Sciclient_ConfigPrms_t;
423 /**
424 * \brief Input parameters for #Sciclient_service function.
425 */
426 typedef struct
427 {
428 uint16_t messageType;
429 /**< [IN] Type of message. */
430 uint32_t flags;
431 /**< [IN] Flags for messages that are being transmitted.
432 *
433 */
434 const uint8_t *pReqPayload;
435 /**< [IN] Pointer to the payload to be transmitted */
436 uint32_t reqPayloadSize;
437 /**< [IN] Size of the payload to be transmitted (in bytes)*/
438 uint32_t timeout;
439 /**< [IN] Timeout(number of iterations) for receiving response
440 * (Refer \ref Sciclient_ServiceOperationTimeout) */
441 uint8_t forwardStatus;
442 /**< [IN] Indicates whether the request is being forwarded to another
443 * service provider. Only to be set internally by sciserver, if
444 * integrated into this build. Unused otherwise. */
445 } Sciclient_ReqPrm_t;
447 /**
448 * \brief Output parameters for #Sciclient_service function.
449 */
450 typedef struct
451 {
452 uint32_t flags;
453 /**< [OUT] Flags of response to messages. */
454 uint8_t *pRespPayload;
455 /**< [IN] Pointer to the received payload. The pointer is an input. The
456 * API will populate this with the firmware response upto the
457 * size mentioned in respPayloadSize. Please ensure respPayloadSize
458 * bytes are allocated.
459 */
460 uint32_t respPayloadSize;
461 /**< [IN] Size of the response payload(in bytes) */
462 } Sciclient_RespPrm_t;
464 /**
465 * \brief Input parameters for #Sciclient_service function.
466 */
467 typedef struct
468 {
469 const uint32_t *boardCfgLow;
470 /**< [OUT] Pointer to default board config */
471 const uint32_t *boardCfgLowRm;
472 /**< [OUT] Pointer to default board config for RM */
473 const uint32_t *boardCfgLowSec;
474 /**< [OUT] Pointer to default board config for Security */
475 const uint32_t *boardCfgLowPm;
476 /**< [OUT] Pointer to default board config for PM */
477 uint32_t boardCfgLowSize;
478 /**< [OUT] Size in bytes for default board config */
479 uint32_t boardCfgLowRmSize;
480 /**< [OUT] Size in bytes for default board config for RM */
481 uint32_t boardCfgLowSecSize;
482 /**< [OUT] Size in bytes for default board config for Security */
483 uint32_t boardCfgLowPmSize;
484 /**< [OUT] Size in bytes for default board config for PM */
485 } Sciclient_DefaultBoardCfgInfo_t;
487 /* ========================================================================== */
488 /* Function Declarations */
489 /* ========================================================================== */
491 /**
492 * \brief Loads the DMSC firmware. This is typically called by SBL. Load
493 * firmware does not require calling the #Sciclient_init function.
494 *
495 * Requirement: DOX_REQ_TAG(PDK-2137), DOX_REQ_TAG(PDK-2138)
496 *
497 * \param pSciclient_firmware [IN] Pointer to signed SYSFW binary
498 *
499 * \return CSL_PASS on success, else failure
500 *
501 */
502 int32_t Sciclient_loadFirmware(const uint32_t *pSciclient_firmware);
504 /**
505 * \brief This API is called once for registering interrupts and creating
506 * semaphore handles to be able to talk to the firmware.
507 * The application should assume that the firmware is pre-loaded while
508 * calling the #Sciclient_init API.
509 * The firmware should have been loaded either via GEL or via the SBL
510 * prior to the application calling the #Sciclient_init.
511 * If a void pointer is passed, default values will be used, else
512 * the values passed will be used.
513 *
514 * Requirement: DOX_REQ_TAG(PDK-2146)
515 *
516 * \param pCfgPrms [IN] Pointer to #Sciclient_ConfigPrms_t
517 *
518 * \return CSL_PASS on success, else failure
519 *
520 */
521 int32_t Sciclient_init(const Sciclient_ConfigPrms_t *pCfgPrms);
523 /**
524 * \brief This API allows communicating with the System firmware which can be
525 * called to perform various functions in the system.
526 * Core sciclient function for transmitting payload and recieving
527 * the response.
528 * The caller is expected to allocate memory for the input request
529 * parameter (Refer #Sciclient_ReqPrm_t). This involves setting the
530 * message type being communicated to the firmware, the response flags,
531 * populate the payload of the message based on the inputs in the
532 * files sciclient_fmwPmMessages.h,sciclient_fmwRmMessages.h,
533 * sciclient_fmwSecMessages.h and sciclient_fmwCommonMessages.h.
534 * Since the payload in considered a stream of bytes in this API,
535 * the caller should also populate the size of this stream in
536 * reqPayloadSize. The timeout is used to determine for what amount
537 * of iterations the API would wait for their operation to complete.
538 *
539 * To make sure the response is captured correctly the caller should
540 * also allocate the space for #Sciclient_RespPrm_t parameters. The
541 * caller should populate the pointer to the pRespPayload and the size
542 * respPayloadSize. The API would populate the response flags to
543 * indicate any firmware specific errors and also populate the memory
544 * pointed by pRespPayload till the size given in respPayloadSize.
545 *
546 *
547 * Requirement: DOX_REQ_TAG(PDK-2142), DOX_REQ_TAG(PDK-2141),
548 * DOX_REQ_TAG(PDK-2140), DOX_REQ_TAG(PDK-2139)
549 *
550 * \param pReqPrm [IN] Pointer to #Sciclient_ReqPrm_t
551 * \param pRespPrm [OUT] Pointer to #Sciclient_RespPrm_t
552 *
553 * \return CSL_PASS on success, else failure
554 *
555 */
556 int32_t Sciclient_service(const Sciclient_ReqPrm_t *pReqPrm,
557 Sciclient_RespPrm_t *pRespPrm);
559 /**
560 * \brief De-initialization of sciclient. This de-initialization is specific
561 * to the application. It only de-initializes the semaphores,
562 * interrupts etc. which are initialized in #Sciclient_init. It does
563 * not de-initialize the system firmware.
564 *
565 * Requirement: DOX_REQ_TAG(PDK-2146)
566 *
567 * \return CSL_PASS on success, else failure
568 *
569 */
571 int32_t Sciclient_deinit(void);
573 /**<
574 * \brief API to verify that firmware ABI matches the supported ABI.
575 *
576 * \return CSL_PASS on success, else failure
577 */
578 int32_t Sciclient_abiCheck(void);
580 /**
581 * \brief API to get the default board config info.
582 *
583 * \return CSL_PASS on success, else failure
584 */
585 int32_t Sciclient_getDefaultBoardCfgInfo(Sciclient_DefaultBoardCfgInfo_t *pBoardCfgInfo);
587 /*
588 * Structure Init functions
589 *
590 * Requirement: DOX_REQ_TAG(PDK-2936)
591 */
592 /**
593 * \brief Sciclient_ConfigPrms_t structure init function.
594 *
595 * \param pCfgPrms [IN] Pointer to #Sciclient_ConfigPrms_t structure.
596 *
597 */
598 int32_t Sciclient_configPrmsInit(Sciclient_ConfigPrms_t *pCfgPrms);
600 /**
601 * \brief Send the Response in Ack. Used only with Sciserver or
602 * Sciclient Direct
603 *
604 * \param hdr [IN] Pointer to #tisci_header structure.
605 *
606 */
607 void Sciclient_TisciMsgSetAckResp(struct tisci_header *hdr);
609 /**
610 * \brief Send the Response in NAK. Used only with Sciserver or
611 * Sciclient Direct
612 *
613 * \param hdr [IN] Pointer to #tisci_header structure.
614 *
615 */
616 void Sciclient_TisciMsgSetNakResp(struct tisci_header *hdr);
618 /**
619 * \brief Prepare the header for the board configuration. This API is typically
620 * only used by SBL where it will prepare the headers for the
621 * sciserver to come and then read the board configurations for PM and
622 * RM. This will set up the headers which Sciserver will look to read
623 * the board configuration which the SBL leaves behind after boot.
624 * The Sciserver app will then send the configs for board configuration
625 * based on this.
626 * \param pCommonHeader Pointer to the common header which corresponds to the
627 * format for the component left behind.
628 * \param pBoardCfgHeader Pointer to the board configuration header which
629 * corresponds to the table which defines the board
630 * config params.
631 * \param pInPmPrms Pointer to the PM parameters.
632 * \param pInRmPrms Pointer to the RM parameters.
633 * \return ret CSL_PASS if the paramters are populated correctly in the header.
634 * Fail otherwise.
635 */
636 int32_t Sciclient_boardCfgPrepHeader (
637 uint8_t * pCommonHeader, uint8_t * pBoardCfgHeader,
638 const Sciclient_BoardCfgPrms_t * pInPmPrms,
639 const Sciclient_BoardCfgPrms_t * pInRmPrms);
641 /**
642 * \brief Parse the header left behind by the SBL in the SCISERVER. This is
643 * used in the SCISERVER App to read the left behind header and
644 * configuration paramter.
645 * \param pCommonHeader Pointer to the common header which corresponds to the
646 * format for the component left behind.
647 * \param pInPmPrms Pointer to the PM parameters popolated by the API.
648 * \param pInRmPrms Pointer to the RM parameters popolated by the API.
649 * \return ret CSL_PASS if the paramters are populated correctly.
650 * Fail otherwise.
651 */
652 int32_t Sciclient_boardCfgParseHeader (
653 uint8_t * pCommonHeader,
654 Sciclient_BoardCfgPrms_t * pInPmPrms,
655 Sciclient_BoardCfgPrms_t * pInRmPrms);
657 /* ========================================================================== */
658 /* Static Function Definitions */
659 /* ========================================================================== */
661 #ifdef __cplusplus
662 }
663 #endif
665 #endif /* #ifndef SCICLIENT_H_ */
667 /* @} */
669 /**
670 * \ingroup DRV_SCICLIENT_MODULE
671 * \defgroup TISCI Texas Instruments System Controller Interface
672 *
673 * @{
674 *
675 * ##Power and Clock Management Features
676 * Public APIs are provided to:
677 *
678 * - Enable and release a module, such as a UART or a core
679 * - This configures both power and clock details for the module and keeps track of its usage.
680 * - Configure the lowest/deepest low-power (sleep) mode allowed as well as EMIF details to enable self-refresh
681 * - Query thermal sensors
682 *
683 * ##Resource Management Features
684 * Public APIs are provided to:
685 *
686 * - Manage DMA/Navigator Resources
687 * - UDMAP
688 * - Ring Accelerator
689 * - PSI-L
690 * - Proxy
691 * - Program interrupts (interrupt aggregators and routers) both at SoC and subsystem (DMA/Navigator) level
692 *
693 * ##Security Features
694 * Public APIs are provided to directly configure these features following polices and root of trust:
695 *
696 * - ISC
697 * - Present at originator/master interfaces to control credentials from master
698 * - Firewall
699 * - Additional layer of access control beyond MMU/MPU located at each destination/slave interface to control memory and register access
700 * - SA2-UL Security Contexts
701 * - Contains actual keys for crypto accelerator
702 * - APIs are also provided to authenticate and/or decrypt blobs in memory.
703 */
704 /* @} */