1 /*
2  * Copyright 2022 NXP
3  * All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 #ifndef __S3MU_DRIVER_H__
8 #define __S3MU_DRIVER_H__
9 
10 #include "fsl_common.h"
11 #include "fsl_device_registers.h"
12 
13 /*!
14  * @addtogroup s3mu
15  * @{
16  */
17 
18 /*******************************************************************************
19  * Definitions
20  *******************************************************************************/
21 /*! @name Driver version */
22 /*! @{ */
23 /*! @brief Defines S3MU driver version 2.0.1.
24  *
25  * Change log:
26  * - Version 2.0.1
27  *   - Update kStatusGroup_SNT to kStatusGroup_ELEMU
28  *
29  * - Version 2.0.0
30  *   - initial version
31  */
32 #define FSL_S3MU_DRIVER_VERSION (MAKE_VERSION(2, 0, 1))
33 /*! @} */
34 
35 #define MU_MSG_HEADER_SIZE (1U)
36 
37 #define MESSAGING_TAG_COMMAND (0x17u)
38 #define MESSAGING_TAG_REPLY   (0xE1u)
39 
40 enum
41 {
42     kStatus_S3MU_AgumentOutOfRange = MAKE_STATUS(kStatusGroup_ELEMU, 0x1u), /*!< S3MU status for out of range access. */
43     kStatus_S3MU_InvalidArgument = MAKE_STATUS(kStatusGroup_ELEMU, 0x2u), /*!< S3MU status for invalid argument check. */
44     kStatus_S3MU_RequestTimeout  = MAKE_STATUS(kStatusGroup_ELEMU, 0x3u), /*!< S3MU status for timeout. */
45     kStatus_S3MU_Busy = MAKE_STATUS(kStatusGroup_ELEMU, 0x4u), /*!< S3MU status for reservation by other core. */
46 };
47 
48 typedef struct
49 {
50     union
51     {
52         uint32_t value;
53         struct
54         {
55             uint8_t ver;
56             uint8_t size;
57             uint8_t command;
58             uint8_t tag;
59         } hdr_byte;
60     };
61 } mu_hdr_t;
62 
63 /*******************************************************************************
64  * API
65  *******************************************************************************/
66 #if defined(__cplusplus)
67 extern "C" {
68 #endif
69 
70 /*!
71  * @brief Send message to MU
72  *
73  * This function writes messgae into MU regsters and send message to EdgeLock Enclave.
74  *
75  * @param base MU peripheral base address
76  * @param buf buffer to store read data
77  * @param wordCount size of data in words
78  *
79  * @return Status kStatus_Success if success, kStatus_Fail if fail
80  * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange
81  */
82 status_t S3MU_SendMessage(S3MU_Type *mu, void *buf, size_t wordCount);
83 
84 /*!
85  * @brief Get response from MU
86  *
87  * This function reads response data from EdgeLock Enclave if available.
88  *
89  * @param base MU peripheral base address
90  * @param buf buffer to store read data
91  *
92  * Note: number of read response word is obtained by header,
93  * so user need to prepare buffer with enough space for expected response
94  *
95  * @return Status kStatus_Success if success, kStatus_Fail if fail
96  * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange
97  */
98 status_t S3MU_GetResponse(S3MU_Type *mu, void *buf);
99 
100 /*!
101  * @brief Wait and Read data from MU
102  *
103  * This function waits limited time (ticks) and tests if data are ready to be read.
104  * When data are ready, reads them into buffer, timeout otherwise.
105  *
106  * @param base MU peripheral base address
107  * @param buf buffer to store read data
108  * @param wordCount size of data in words
109  * @param wait number of iterations to wait
110  *
111  * @return Status kStatus_Success if success, kStatus_S3MU_RequestTimeout if timeout
112  * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange
113  */
114 status_t S3MU_WaitForData(S3MU_Type *mu, uint32_t *buf, size_t wordCount, uint32_t wait);
115 
116 /*!
117  * @brief Read message from MU
118  *
119  * This function reads message date from EdgeLock Enclave if available.
120  *
121  * @param base MU peripheral base address
122  * @param buf buffer to store read data
123  * @param size lenght of data in words. If read_header equal MU_READ_HEADER, size is read from response header.
124  * @param read_header specifies if size is obtained by response header or provided in parameter.
125  *
126  * @return Status kStatus_Success if success, kStatus_Fail if fail
127  * Possible errors: kStatus_S3MU_InvalidArgument, kStatus_S3MU_AgumentOutOfRange
128  */
129 status_t S3MU_ReadMessage(S3MU_Type *mu, uint32_t *buf, size_t *size, uint8_t read_header);
130 
131 /*!
132  * @brief Init MU
133  *
134  * This function does nothing. MU is initialized after leaving ROM.
135  *
136  * @param base MU peripheral base address
137  */
138 void S3MU_Init(S3MU_Type *mu);
139 
140 /*!
141  * @brief Computes CRC
142  *
143  * This function computes CRC of input message.
144  *
145  * @param msg pointer to message
146  * @param msg_len size of message in words
147  *
148  * @return CRC32 checksum value
149  */
150 uint32_t S3MU_ComputeMsgCrc(uint32_t *msg, uint32_t msg_len);
151 
152 #if defined(__cplusplus)
153 }
154 #endif
155 
156 /*! @} */ /* end of group s3mu */
157 
158 #endif /* __S3MU_DRIVER_H__ */
159