1 /*
2  * Copyright 2020-2021 NXP
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef _FSL_SENTINEL_H_
9 #define _FSL_SENTINEL_H_
10 
11 #include "fsl_common.h"
12 
13 /*!
14  * @addtogroup sentinel
15  * @{
16  */
17 
18 /*******************************************************************************
19  * Definitions
20  ******************************************************************************/
21 /*! @brief sentinel command definition. */
22 /* baseline apis command */
23 #define SENTINEL_BASELINE_API_CMD_PING              (0x01U)
24 #define SENTINEL_BASELINE_API_CMD_DUMP_DEBUG_BUFFER (0x21U)
25 #define SENTINEL_BASELINE_API_CMD_OEM_CNTN_AUTH     (0x87U)
26 #define SENTINEL_BASELINE_API_CMD_VERIFY_IMAGE      (0x88U)
27 #define SENTINEL_BASELINE_API_CMD_RELEASE_CONTAINER (0x89U)
28 #define SENTINEL_BASELINE_API_CMD_GET_FW_VERSION    (0x9DU)
29 #define SENTINEL_BASELINE_API_CMD_RELEASE_RDC       (0xC4U)
30 #define SENTINEL_BASELINE_API_CMD_GET_FW_STATUS     (0xC5U)
31 #define SENTINEL_BASELINE_API_CMD_POWER_DOWN        (0xD1U)
32 #define SENTINEL_BASELINE_API_CMD_GET_INFO          (0xDAU)
33 /* bridge apis command */
34 #define SENTINEL_BRIDGE_API_CMD_SESSION_OPEN   (0x10U)
35 #define SENTINEL_BRIDGE_API_CMD_SESSION_CLOSE  (0x11U)
36 #define SENTINEL_BRIDGE_API_CMD_RNG_OPEN       (0x20U)
37 #define SENTINEL_BRIDGE_API_CMD_RNG_CLOSE      (0x21U)
38 #define SENTINEL_BRIDGE_API_CMD_RNG_GET_RANDOM (0x22U)
39 
40 #define SENTINEL_MSG_HDR_CMD_TAG     (0x17U)
41 #define SENTINEL_MSG_HDR_CMD_RSP_TAG (0xe1U)
42 #define SENTINEL_BASELINE_API_VER    (0x06U)
43 #define SENTINEL_BRIDGE_API_VER      (0x07U)
44 
45 /* SENTINEL Receive Register Count */
46 #define SENTINEL_RR_CNT (0x4U)
47 
48 /* SENTINEL Transmit Register Count */
49 #define SENTINEL_TR_CNT (0x8U)
50 
51 /* MU ID */
52 #define RTC_MU_ID (0x01U)
53 #define AP_MU_ID  (0x02U)
54 
55 /* Domain ID */
56 #define CM33_DOMAIN_ID (0x06)
57 
58 #define BASELINE_SUCCESS_IND (0xD6U)
59 #define BASELINE_FAILURE_IND (0x29U)
60 
61 #define BRIDGE_SUCCESS_STATUS (0xD6U)
62 #define BRIDGE_FAILURE_STATUS (0x29U)
63 
64 /* Align size for sentinel to access address */
65 #define SENTINEL_ACCESS_ADDR_ALIGN_SIZE (8U)
66 
67 /* Core Identifier */
68 #define RTD_CORE_ID (0x01U)
69 #define APD_CORE_ID (0x02U)
70 
71 /* Resource Domain Control Identifier */
72 #define TRDC_ID (0x74U)
73 #define XRDC_ID (0x78U)
74 
75 struct msg_hdr
76 {
77     uint8_t ver;
78     uint8_t size;
79     uint8_t cmd;
80     uint8_t tag;
81 };
82 
83 struct baseline_api_rsp_code
84 {
85     uint8_t status;
86     uint8_t indication;
87     uint16_t abort_code;
88 };
89 
90 struct bridge_api_rsp_code
91 {
92     uint8_t status;
93     uint8_t rating;
94     uint16_t rating_ext;
95 };
96 
97 union response_code
98 {
99     uint32_t code;
100     struct baseline_api_rsp_code baseline_rsp_code;
101     struct bridge_api_rsp_code bridge_rsp_code;
102 };
103 
104 struct common_rsp
105 {
106     struct msg_hdr hdr;
107     union response_code rsp_code;
108 };
109 
110 struct get_fw_version_msg_cmd
111 {
112     struct msg_hdr hdr;
113 };
114 
115 struct get_fw_version_msg_cmd_rsp
116 {
117     struct common_rsp rsp;
118     uint32_t fw_version;
119     uint32_t commit_id;
120 };
121 
122 struct get_fw_status_msg_cmd
123 {
124     struct msg_hdr hdr;
125 };
126 
127 struct get_fw_status_msg_cmd_rsp
128 {
129     struct common_rsp rsp;
130     uint8_t status;
131     uint8_t rsv[3];
132 };
133 
134 struct open_session_msg_cmd
135 {
136     struct msg_hdr hdr;
137     uint8_t mu_id;
138     uint8_t interrupt_num;
139     uint8_t tz;
140     uint8_t did;
141     uint8_t priority;
142     uint8_t op_mode;
143     uint16_t reserved;
144 };
145 
146 struct open_session_msg_cmd_rsp
147 {
148     struct common_rsp rsp;
149     uint32_t session_handle;
150 };
151 
152 struct power_down_cmd
153 {
154     struct msg_hdr hdr;
155     uint32_t size;
156     uint32_t resume_addr;
157 };
158 
159 struct power_down_cmd_rsp
160 {
161     struct common_rsp rsp;
162 };
163 
164 struct close_session_msg_cmd
165 {
166     struct msg_hdr hdr;
167     uint32_t session_handle;
168 };
169 
170 struct close_session_msg_cmd_rsp
171 {
172     struct common_rsp rsp;
173 };
174 
175 struct rng_open_msg_cmd
176 {
177     struct msg_hdr hdr;
178     uint32_t session_handle;
179     uint32_t input_address_ext;
180     uint32_t output_address_ext;
181     uint8_t flags;
182     uint8_t rsv[3];
183     uint32_t crc;
184 };
185 
186 struct rng_open_msg_cmd_rsp
187 {
188     struct common_rsp rsp;
189     uint32_t rng_handle;
190 };
191 
192 struct rng_close_msg_cmd
193 {
194     struct msg_hdr hdr;
195     uint32_t rng_handle;
196 };
197 
198 struct rng_close_msg_cmd_rsp
199 {
200     struct common_rsp rsp;
201 };
202 
203 struct rng_get_rnd_msg_cmd
204 {
205     struct msg_hdr hdr;
206     uint32_t rng_handle;
207     uint32_t out_addr;
208     uint32_t out_size;
209 };
210 
211 struct rng_get_rnd_msg_cmd_rsp
212 {
213     struct common_rsp rsp;
214 };
215 
216 struct dump_debug_buffer_msg_cmd
217 {
218     struct msg_hdr hdr;
219 };
220 
221 struct dump_debug_buffer_msg_cmd_rsp
222 {
223     struct common_rsp rsp;
224     uint32_t debug_words[20];
225     uint32_t crc;
226 };
227 
228 struct release_rdc_msg_cmd
229 {
230     struct msg_hdr hdr;
231     uint8_t core_id;
232     uint8_t rdc_id;
233     uint8_t rsv[2];
234 };
235 
236 struct release_rdc_msg_cmd_rsp
237 {
238     struct common_rsp rsp;
239 };
240 
241 struct get_info_msg_cmd
242 {
243     struct msg_hdr hdr;
244     uint32_t rsp_msb;
245     uint32_t rsp_lsb;
246     uint16_t buf_size;
247     uint16_t rsv;
248 };
249 struct sentinel_get_info_data
250 {
251     uint8_t cmd;
252     uint8_t ver;
253     uint16_t len;
254     uint16_t soc_id;
255     uint16_t soc_rev;
256     uint16_t lc;
257     uint8_t sssm;
258     uint8_t rsv;
259     uint32_t uid[4];
260     uint32_t sha256_rom_patch[8];
261     uint32_t sha_fw[8];
262 };
263 
264 enum rdc_type
265 {
266     TRDC_TYPE,
267     XRDC_TYPE,
268 };
269 
270 /*! @name Driver version */
271 /*@{*/
272 /*! @brief sentinel driver version 2.0.3. */
273 #define FSL_SENTINEL_DRIVER_VERSION (MAKE_VERSION(2, 0, 3))
274 /*@}*/
275 
276 /*******************************************************************************
277  * API
278  ******************************************************************************/
279 #if defined(__cplusplus)
280 extern "C" {
281 #endif /*__cplusplus */
282 
283 /*!
284  * @brief Initialize MU interface for Sentinel access.
285  */
286 void SENTINEL_Init(void);
287 
288 /*!
289  * @brief Deinitialize MU interface for Sentinel access.
290  */
291 void SENTINEL_Deinit(void);
292 
293 /*!
294  * @brief Send message to Sentinel.
295  *
296  * @param param Command parameters pointer. Each parameter is a 32bit word.
297  * @param paramCount Command parameter count.
298  */
299 void SENTINEL_SendMessage(uint32_t *param, uint32_t paramCount);
300 
301 /*!
302  * @brief Receive message from Sentinel.
303  *
304  * @param pParam Pointer to save command parameters. Each parameter is a 32bit word.
305  * @param pParamCount Inout pointer to command parameter count.
306  */
307 void SENTINEL_ReceiveMessage(uint32_t *pParam, uint32_t *pParamCount);
308 
309 /*!
310  * @brief Send command to Sentinel and receive response.
311  *
312  * @param cmdParam Command parameters pointer. Each parameter is a 32bit word.
313  * @param cmdParamCount Command parameter count.
314  * @param pRespParam Pointer to save response parameters. Each parameter is a 32bit word.
315  * @param pRespParamCount Inout pointer to response parameter count.
316  * @return 0 for success, otherwise return error code.
317  */
318 uint32_t SENTINEL_Command(uint32_t *cmdParam, uint32_t cmdParamCount, uint32_t *pRespParam, uint32_t *pRespParamCount);
319 
320 /*!
321  * @brief Ping Sentinel to see if it is alive.
322  *
323  * @return 0 for success, otherwise return error code.
324  */
325 uint32_t SENTINEL_Ping(void);
326 
327 /*!
328  * @brief Get Sentinel firmware version.
329  *
330  * @param pVersion Pointer to save firmware version.
331  * @param pCommitSha Pointer to save first 4 bytes of the git commit ID.
332  * @return 0 for success, otherwise return error code.
333  */
334 uint32_t SENTINEL_GetFirmwareVersion(uint32_t *pVersion, uint32_t *pCommitSha);
335 
336 /*!
337  * @brief Get Sentinel firmware status.
338  *
339  * @param pStatus Pointer to save firmware status. 0: No firmware in place. 1: Firmware authenticated and operational.
340  * @return 0 for success, otherwise return error code.
341  */
342 uint32_t SENTINEL_GetFirmwareStatus(uint8_t *pStatus);
343 
344 /*!
345  * @brief Request Sentinel to enter power down.
346  *
347  * @param resumeAddr Base address in memory for resume code
348  * @param size Length of resume code in memory
349  * @return 0 for success, otherwise return error code.
350  */
351 uint32_t SENTINEL_SetPowerDown(uint32_t resumeAddr, uint32_t size);
352 
353 uint32_t SENTINEL_SessionOpen(uint32_t *pSessionHandle,
354                               uint8_t muId,
355                               uint8_t interruptId,
356                               uint8_t tz,
357                               uint8_t did,
358                               uint8_t priority,
359                               uint8_t operatingMode);
360 
361 uint32_t SENTINEL_SessionClose(uint32_t *pSessionHandle);
362 
363 uint32_t SENTINEL_RngOpen(uint32_t *pRngHandle, uint32_t sessionHandle, uint8_t flags);
364 
365 uint32_t SENTINEL_RngClose(uint32_t *pRngHandle);
366 
367 uint32_t SENTINEL_RngGetRandom(uint32_t *pRngHandle, uint32_t outAddr, uint32_t outSize);
368 
369 uint32_t SENTINEL_DumpDebugBuffer(void);
370 
371 status_t SENTINEL_RNG_GetRandomData(uint32_t output, uint32_t len);
372 
373 uint32_t SENTINEL_ReleaseRDC(enum rdc_type type);
374 
375 /*!
376  * @brief Get Sentinel cpu version.
377  *
378  * @param pSoc_id Pointer to soc id.
379  * @param pSoc_rev Pointer to soc revision number.
380  * @return 0 for success, otherwise return error code.
381  */
382 uint32_t SENTINEL_GetSocInfo(uint16_t *pSoc_id, uint16_t *pSoc_rev);
383 
384 #if defined(__cplusplus)
385 }
386 #endif /*__cplusplus */
387 
388 /*! @} */
389 
390 #endif /* _FSL_SENTINEL_H_ */
391