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     uint32_t oem_srkh[16];
263     uint8_t trng;
264     uint8_t csal;
265     uint8_t imem;
266     uint8_t rsv2;
267 };
268 
269 enum rdc_type
270 {
271     TRDC_TYPE,
272     XRDC_TYPE,
273 };
274 
275 /*! @name Driver version */
276 /*@{*/
277 /*! @brief sentinel driver version 2.0.3. */
278 #define FSL_SENTINEL_DRIVER_VERSION (MAKE_VERSION(2, 0, 3))
279 /*@}*/
280 
281 /*******************************************************************************
282  * API
283  ******************************************************************************/
284 #if defined(__cplusplus)
285 extern "C" {
286 #endif /*__cplusplus */
287 
288 /*!
289  * @brief Initialize MU interface for Sentinel access.
290  */
291 void SENTINEL_Init(void);
292 
293 /*!
294  * @brief Deinitialize MU interface for Sentinel access.
295  */
296 void SENTINEL_Deinit(void);
297 
298 /*!
299  * @brief Send message to Sentinel.
300  *
301  * @param param Command parameters pointer. Each parameter is a 32bit word.
302  * @param paramCount Command parameter count.
303  */
304 void SENTINEL_SendMessage(uint32_t *param, uint32_t paramCount);
305 
306 /*!
307  * @brief Receive message from Sentinel.
308  *
309  * @param pParam Pointer to save command parameters. Each parameter is a 32bit word.
310  * @param pParamCount Inout pointer to command parameter count.
311  */
312 void SENTINEL_ReceiveMessage(uint32_t *pParam, uint32_t *pParamCount);
313 
314 /*!
315  * @brief Send command to Sentinel and receive response.
316  *
317  * @param cmdParam Command parameters pointer. Each parameter is a 32bit word.
318  * @param cmdParamCount Command parameter count.
319  * @param pRespParam Pointer to save response parameters. Each parameter is a 32bit word.
320  * @param pRespParamCount Inout pointer to response parameter count.
321  * @return 0 for success, otherwise return error code.
322  */
323 uint32_t SENTINEL_Command(uint32_t *cmdParam, uint32_t cmdParamCount, uint32_t *pRespParam, uint32_t *pRespParamCount);
324 
325 /*!
326  * @brief Ping Sentinel to see if it is alive.
327  *
328  * @return 0 for success, otherwise return error code.
329  */
330 uint32_t SENTINEL_Ping(void);
331 
332 /*!
333  * @brief Get Sentinel firmware version.
334  *
335  * @param pVersion Pointer to save firmware version.
336  * @param pCommitSha Pointer to save first 4 bytes of the git commit ID.
337  * @return 0 for success, otherwise return error code.
338  */
339 uint32_t SENTINEL_GetFirmwareVersion(uint32_t *pVersion, uint32_t *pCommitSha);
340 
341 /*!
342  * @brief Get Sentinel firmware status.
343  *
344  * @param pStatus Pointer to save firmware status. 0: No firmware in place. 1: Firmware authenticated and operational.
345  * @return 0 for success, otherwise return error code.
346  */
347 uint32_t SENTINEL_GetFirmwareStatus(uint8_t *pStatus);
348 
349 /*!
350  * @brief Request Sentinel to enter power down.
351  *
352  * @param resumeAddr Base address in memory for resume code
353  * @param size Length of resume code in memory
354  * @return 0 for success, otherwise return error code.
355  */
356 uint32_t SENTINEL_SetPowerDown(uint32_t resumeAddr, uint32_t size);
357 
358 uint32_t SENTINEL_SessionOpen(uint32_t *pSessionHandle,
359                               uint8_t muId,
360                               uint8_t interruptId,
361                               uint8_t tz,
362                               uint8_t did,
363                               uint8_t priority,
364                               uint8_t operatingMode);
365 
366 uint32_t SENTINEL_SessionClose(uint32_t *pSessionHandle);
367 
368 uint32_t SENTINEL_RngOpen(uint32_t *pRngHandle, uint32_t sessionHandle, uint8_t flags);
369 
370 uint32_t SENTINEL_RngClose(uint32_t *pRngHandle);
371 
372 uint32_t SENTINEL_RngGetRandom(uint32_t *pRngHandle, uint32_t outAddr, uint32_t outSize);
373 
374 uint32_t SENTINEL_DumpDebugBuffer(void);
375 
376 status_t SENTINEL_RNG_GetRandomData(uint32_t output, uint32_t len);
377 
378 uint32_t SENTINEL_ReleaseRDC(enum rdc_type type);
379 
380 /*!
381  * @brief Get Sentinel cpu version.
382  *
383  * @param pSoc_id Pointer to soc id.
384  * @param pSoc_rev Pointer to soc revision number.
385  * @return 0 for success, otherwise return error code.
386  */
387 uint32_t SENTINEL_GetSocInfo(uint16_t *pSoc_id, uint16_t *pSoc_rev);
388 
389 #if defined(__cplusplus)
390 }
391 #endif /*__cplusplus */
392 
393 /*! @} */
394 
395 #endif /* _FSL_SENTINEL_H_ */
396