MAX32655 Peripheral Driver API
Peripheral Driver API for the MAX32655
tpu.h
1 
6 /* ****************************************************************************
7  * Copyright (C) 2018 Maxim Integrated Products, Inc., All Rights Reserved.
8  *
9  * Permission is hereby granted, free of charge, to any person obtaining a
10  * copy of this software and associated documentation files (the "Software"),
11  * to deal in the Software without restriction, including without limitation
12  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
13  * and/or sell copies of the Software, and to permit persons to whom the
14  * Software is furnished to do so, subject to the following conditions:
15  *
16  * The above copyright notice and this permission notice shall be included
17  * in all copies or substantial portions of the Software.
18  *
19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
20  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
22  * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
23  * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
24  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25  * OTHER DEALINGS IN THE SOFTWARE.
26  *
27  * Except as contained in this notice, the name of Maxim Integrated
28  * Products, Inc. shall not be used except as stated in the Maxim Integrated
29  * Products, Inc. Branding Policy.
30  *
31  * The mere transfer of this software does not imply any licenses
32  * of trade secrets, proprietary technology, copyrights, patents,
33  * trademarks, maskwork rights, or any other form of intellectual
34  * property whatsoever. Maxim Integrated Products, Inc. retains all
35  * ownership rights.
36  *
37  * $Date$
38  * $Revision$
39  *
40  *************************************************************************** */
41 
42 #ifndef _TPU_H_
43 #define _TPU_H_
44 
45 /***** Includes *****/
46 #include "tpu_regs.h"
47 
48 
49 /* IN ADDITION TO THIS HEADER, FCL WILL BE SUPPORTED AND PROVIDED IN BINARY FORM */
50 /***** Definitions *****/
51 
52 typedef void (*mxc_tpu_complete_t) (void* req, int result);
53 
54 typedef enum {
55  MXC_TPU_FEATURE_DMA = 1 << 0,
56  MXC_TPU_FEATURE_ECC = 1 << 1,
57  MXC_TPU_FEATURE_CRC = 1 << 2,
58  MXC_TPU_FEATURE_MAA = 1 << 3,
59  MXC_TPU_FEATURE_HASH = 1 << 4,
60  MXC_TPU_FEATURE_CIPHER = 1 << 5,
61  MXC_TPU_FEATURE_TRNG = 1 << 6
62 } mxc_tpu_features_t;
63 
64 
65 /* ************************************************************************* */
66 /* DMA Definitions */
67 /* ************************************************************************* */
68 
69 struct _mxc_tpu_dma_req_t {
70  uint8_t* sourceBuffer;
71  uint8_t* destBuffer;
72  uint32_t length;
73  mxc_tpu_complete_t callback; // Null callback indicates a blocking operation
74 } typedef mxc_tpu_dma_req_t;
75 
76 typedef enum {
77  MXC_TPU_DMA_READ_FIFO_DMA = MXC_V_TPU_CTRL_RDSRC_DMAORAPB,
78  MXC_TPU_DMA_READ_FIFO_RNG = MXC_V_TPU_CTRL_RDSRC_RNG
79 } mxc_tpu_dma_read_source_t;
80 
81 typedef enum {
82  MXC_TPU_DMA_WRITE_FIFO_CIPHER = MXC_V_TPU_CTRL_WRSRC_CIPHEROUTPUT,
83  MXC_TPU_DMA_WRITE_FIFO_READ_FIFO = MXC_V_TPU_CTRL_WRSRC_READFIFO,
84  MXC_TPU_DMA_WRITE_FIFO_NONE = MXC_V_TPU_CTRL_WRSRC_NONE
85 } mxc_tpu_dma_write_source_t;
86 
87 /* ************************************************************************* */
88 /* ECC Definitions */
89 /* ************************************************************************* */
90 
91 struct _mxc_tpu_ecc_req_t {
92  uint8_t* dataBuffer;
93  uint32_t dataLen;
94  uint32_t checksum;
95  mxc_tpu_complete_t callback;
96 } typedef mxc_tpu_ecc_req_t;
97 
98 struct _mxc_tpu_crc_req_t {
99  uint8_t* dataBuffer;
100  uint32_t dataLen;
101  uint32_t resultCRC;
102  mxc_tpu_complete_t callback;
103 } typedef mxc_tpu_crc_req_t;
104 
105 /* ************************************************************************* */
106 /* MAA Definitions */
107 /* ************************************************************************* */
108 
109 typedef enum {
110  MXC_TPU_MAA_EXP = MXC_V_TPU_MAA_CTRL_CLC_EXP, // Select exponentiation operation
111  MXC_TPU_MAA_SQ = MXC_V_TPU_MAA_CTRL_CLC_SQ, // Select square operation
112  MXC_TPU_MAA_MUL = MXC_V_TPU_MAA_CTRL_CLC_MUL, // Select multiplication operation
113  MXC_TPU_MAA_SQMUL = MXC_V_TPU_MAA_CTRL_CLC_SQMUL, // Select square followed by multiplication operation
114  MXC_TPU_MAA_ADD = MXC_V_TPU_MAA_CTRL_CLC_ADD, // Select add operation
115  MXC_TPU_MAA_SUB = MXC_V_TPU_MAA_CTRL_CLC_SUB, // Select subtract operation
116  MXC_TPU_MAA_INV // Composite operation, modular exponentiation
117 } mxc_tpu_maa_operation_t;
118 
119 struct _mxc_tpu_maa_req_t {
120  // All operand buffers must be as long as the word size
121  uint8_t* opA;
122  uint8_t* opB;
123  uint8_t* exponent;
124  uint8_t* modulus;
125  uint8_t* result;
126  mxc_tpu_maa_operation_t op;
127  mxc_tpu_complete_t callback;
128 } typedef mxc_tpu_maa_req_t;
129 
130 typedef enum {
131  MXC_TPU_MAA_REG_OPA = MXC_F_TPU_MAA_CTRL_AMS_POS,
132  MXC_TPU_MAA_REG_OPB = MXC_F_TPU_MAA_CTRL_BMS_POS,
133  MXC_TPU_MAA_REG_EXP = MXC_F_TPU_MAA_CTRL_EMS_POS,
134  MXC_TPU_MAA_REG_MOD = MXC_F_TPU_MAA_CTRL_MMS_POS
135 } mxc_tpu_maa_register_t;
136 
137 /* ************************************************************************* */
138 /* Hash Definitions */
139 /* ************************************************************************* */
140 
141 struct _mxc_tpu_hash_req_t {
142  uint8_t* msg;
143  uint32_t len;
144  uint8_t* hash;
145  mxc_tpu_complete_t callback;
146 } typedef mxc_tpu_hash_req_t;
147 
148 typedef enum {
149  MXC_TPU_HASH_DIS = MXC_V_TPU_HASH_CTRL_HASH_DIS, // Disable
150  MXC_TPU_HASH_SHA1 = MXC_V_TPU_HASH_CTRL_HASH_SHA1, // Select SHA1
151  MXC_TPU_HASH_SHA224 = MXC_V_TPU_HASH_CTRL_HASH_SHA224, // Select SHA224
152  MXC_TPU_HASH_SHA256 = MXC_V_TPU_HASH_CTRL_HASH_SHA256, // Select SHA256
153  MXC_TPU_HASH_SHA384 = MXC_V_TPU_HASH_CTRL_HASH_SHA384, // Select SHA384
154  MXC_TPU_HASH_SHA512 = MXC_V_TPU_HASH_CTRL_HASH_SHA512 // Select SHA384
155 } mxc_tpu_hash_func_t;
156 
157 typedef enum {
158  MXC_TPU_HASH_SOURCE_INFIFO = 0,
159  MXC_TPU_HASH_SOURCE_OUTFIFO = 1
160 } mxc_tpu_hash_source_t;
161 
162 /* ************************************************************************* */
163 /* Cipher Definitions */
164 /* ************************************************************************* */
165 
166 struct _mxc_tpu_cipher_req_t {
167  uint8_t* plaintext;
168  uint32_t ptLen;
169  uint8_t* iv;
170  uint8_t* ciphertext;
171  mxc_tpu_complete_t callback;
172 } typedef mxc_tpu_cipher_req_t;
173 
174 typedef enum {
175  MXC_TPU_MODE_ECB = MXC_V_TPU_CIPHER_CTRL_MODE_ECB, // Electronic Code Book
176  MXC_TPU_MODE_CBC = MXC_V_TPU_CIPHER_CTRL_MODE_CBC, // Cipher Block Chaining
177  MXC_TPU_MODE_CFB = MXC_V_TPU_CIPHER_CTRL_MODE_CFB, // Cipher Feedback
178  MXC_TPU_MODE_CTR = MXC_V_TPU_CIPHER_CTRL_MODE_CTR, // Counter
179  MXC_TPU_MODE_OFB = /*????*/ 0 // Output Feedback
180 } mxc_tpu_cipher_mode_t;
181 
182 typedef enum {
183  MXC_TPU_CIPHER_DIS = MXC_V_TPU_CIPHER_CTRL_CIPHER_DIS, // Disable
184  MXC_TPU_CIPHER_AES128 = MXC_V_TPU_CIPHER_CTRL_CIPHER_AES128, // Select AES-128
185  MXC_TPU_CIPHER_AES192 = MXC_V_TPU_CIPHER_CTRL_CIPHER_AES192, // Select AES-192
186  MXC_TPU_CIPHER_AES256 = MXC_V_TPU_CIPHER_CTRL_CIPHER_AES256, // Select AES-256
187  MXC_TPU_CIPHER_DES = MXC_V_TPU_CIPHER_CTRL_CIPHER_DES, // Select DES
188  MXC_TPU_CIPHER_TDES = MXC_V_TPU_CIPHER_CTRL_CIPHER_TDES // Select TDES
189 } mxc_tpu_cipher_t;
190 
191 typedef enum {
192  MXC_TPU_CIPHER_KEY_SOFTWARE = 0,
193  MXC_TPU_CIPHER_KEY_AES_KEY2 = 2,
194  MXC_TPU_CIPHER_KEY_AES_KEY3 = 3
195 } mxc_tpu_cipher_key_t;
196 
197 
198 /***** Function Prototypes *****/
199 
200 /* ************************************************************************* */
201 /* Global Control/Configuration functions */
202 /* ************************************************************************* */
203 
212 int MXC_TPU_Init (uint32_t features);
213 
219 uint32_t MXC_TPU_CheckFeatures (void);
220 
226 void MXC_TPU_IntEnable (int enable);
227 
233 int MXC_TPU_Ready (void);
234 
239 void MXC_TPU_DoneClear (uint32_t features);
240 
246 uint32_t MXC_TPU_Done (void);
247 
252 void MXC_TPU_Reset (uint32_t features);
253 
259 void MXC_TPU_CacheInvalidate (void);
260 
269 int MXC_TPU_Shutdown (uint32_t features);
270 
276 uint32_t MXC_TPU_GetEnabledFeatures (void);
277 
282 void MXC_TPU_Handler (void);
283 
284 /************************************/
285 /* TPU DMA - Used for all features */
286 /************************************/
287 
295 void MXC_TPU_DMA_SetReadSource (mxc_tpu_dma_read_source_t source);
296 
303 mxc_tpu_dma_read_source_t MXC_TPU_DMA_GetReadSource (void);
304 
311 void MXC_TPU_DMA_SetWriteSource (mxc_tpu_dma_write_source_t source);
312 
319 mxc_tpu_dma_write_source_t MXC_TPU_DMA_GetWriteSource (void);
320 
328 void MXC_TPU_DMA_SetSource (uint8_t* source);
329 
335 void MXC_TPU_DMA_SetDestination (uint8_t* dest);
336 
346 int MXC_TPU_DMA_SetupOperation (mxc_tpu_dma_req_t* req);
347 
358 int MXC_TPU_DMA_DoOperation (mxc_tpu_dma_req_t* req);
359 
366 void MXC_TPU_DMA_StartTransfer (uint32_t length);
367 
368 /* ************************************************************************* */
369 /* True Random Number Generator (TRNG) functions */
370 /* ************************************************************************* */
371 
377 int MXC_TPU_TRNG_RandomInt (void);
378 
387 int MXC_TPU_TRNG_Random (uint8_t* data, uint32_t len);
388 
398 void MXC_TPU_TRNG_RandomAsync (uint8_t* data, uint32_t len, mxc_tpu_complete_t callback);
399 
406 int MXC_TPU_TRNG_Generate_AES (void);
407 
414 int MXC_TPU_TRNG_HealthTest (void);
415 
422 void MXC_TPU_TRNG_HealthTestAsync (mxc_tpu_complete_t callback);
423 
424 /* ************************************************************************* */
425 /* Error Correction Code (ECC) functions */
426 /* ************************************************************************* */
427 
428 /*******************************/
429 /* Low Level Functions */
430 /*******************************/
431 
439 void MXC_TPU_ECC_Enable (int enable);
440 
446 uint32_t MXC_TPU_ECC_GetResult (void);
447 
448 /*******************************/
449 /* High Level Functions */
450 /*******************************/
451 
461 int MXC_TPU_ECC_Compute (mxc_tpu_ecc_req_t* req);
462 
472 int MXC_TPU_ECC_ErrorCheck (mxc_tpu_ecc_req_t* req);
473 
482 void MXC_TPU_ECC_ComputeAsync (mxc_tpu_ecc_req_t* req);
483 
491 void MXC_TPU_ECC_ErrorCheckAsync (mxc_tpu_ecc_req_t* req);
492 
493 /* ************************************************************************* */
494 /* Cyclic Redundancy Check (CRC) functions */
495 /* ************************************************************************* */
496 
497 /*******************************/
498 /* Low Level Functions */
499 /*******************************/
500 
506 void MXC_TPU_CRC_SetDirection (int msbFirst);
507 
513 int MXC_TPU_CRC_GetDirection (void);
514 
520 void MXC_TPU_CRC_SetPoly (uint32_t poly);
521 
527 uint32_t MXC_TPU_CRC_GetPoly (void);
528 
534 uint32_t MXC_TPU_CRC_GetResult (void);
535 
536 /*******************************/
537 /* High Level Functions */
538 /*******************************/
539 
549 int MXC_TPU_CRC_Compute (mxc_tpu_crc_req_t* req);
550 
559 void MXC_TPU_CRC_ComputeAsync (mxc_tpu_crc_req_t* req);
560 
561 /* ************************************************************************* */
562 /* Modular Arithmetic Accelerator (MAA) functions */
563 /* ************************************************************************* */
564 
565 /*******************************/
566 /* Low Level Functions */
567 /*******************************/
568 
576 uint32_t* MXC_TPU_MAA_GetAddress (int segment);
577 
583 void MXC_TPU_MAA_SetRAMTemporary (int segment);
584 
590 int MXC_TPU_MAA_GetRAMTemporary (void);
591 
597 void MXC_TPU_MAA_SetRAMResult (int segment);
598 
604 int MXC_TPU_MAA_GetRAMResult (void);
605 
611 void MXC_TPU_MAA_SetRAMOperandA (int segment);
612 
618 int MXC_TPU_MAA_GetRAMOperandA (void);
619 
625 void MXC_TPU_MAA_SetRAMOperandB (int segment);
626 
632 int MXC_TPU_MAA_GetRAMOperandB (void);
633 
640 void MXC_TPU_MAA_SetMemoryBlinding (mxc_tpu_maa_register_t reg, int blindIndex);
641 
649 int MXC_TPU_MAA_GetMemoryBlinding (mxc_tpu_maa_register_t reg);
650 
651 // Set secure vs speed
658 void MXC_TPU_MAA_SetSecureMode (int secureMode);
659 
666 int MXC_TPU_MAA_GetSecureMode (void);
667 
675 void MXC_TPU_MAA_SetCalculation (mxc_tpu_maa_operation_t operation);
676 
683 void MXC_TPU_MAA_Start (void);
684 
690 void MXC_TPU_MAA_StartBlocking (void);
691 
697 void MXC_TPU_MAA_SetWordSize (int size);
698 
704 int MXC_TPU_MAA_GetWordSize (void);
705 
706 /*******************************/
707 /* High Level Functions */
708 /*******************************/
709 
720 int MXC_TPU_MAA_Compute (mxc_tpu_maa_req_t* req);
721 
729 void MXC_TPU_MAA_ComputeAsync (mxc_tpu_maa_req_t* req);
730 
731 /* ************************************************************************* */
732 /* Hash functions */
733 /* ************************************************************************* */
734 
735 /***********************/
736 /* Low Level Functions */
737 /***********************/
738 
746 unsigned int MXC_TPU_Hash_GetBlockSize (mxc_tpu_hash_func_t function);
747 
755 unsigned int MXC_TPU_Hash_GetDigestSize (mxc_tpu_hash_func_t function);
756 
762 void MXC_TPU_Hash_SetFunction (mxc_tpu_hash_func_t function);
763 
769 mxc_tpu_hash_func_t MXC_TPU_Hash_GetFunction (void);
770 
777 void MXC_TPU_Hash_SetAutoPad (int pad);
778 
784 int MXC_TPU_Hash_GetAutoPad (void);
785 
792 void MXC_TPU_Hash_GetResult (uint8_t* digest, int* len);
793 
800 void MXC_TPU_Hash_SetMessageSize (uint32_t size);
801 
807 void MXC_TPU_Hash_SetSource (mxc_tpu_hash_source_t source);
808 
814 mxc_tpu_hash_source_t MXC_TPU_Hash_GetSource (void);
815 
822 void MXC_TPU_Hash_InitializeHash (void);
823 
824 /************************/
825 /* High Level Functions */
826 /************************/
827 
836 int MXC_TPU_Hash_Compute (mxc_tpu_hash_req_t* req);
837 
845 void MXC_TPU_Hash_ComputeAsync (mxc_tpu_hash_req_t* req);
846 
847 /* ************************************************************************* */
848 /* Cipher functions */
849 /* ************************************************************************* */
850 
851 /************************/
852 /* Low Level Functions */
853 /************************/
854 
862 unsigned int MXC_TPU_Cipher_GetKeySize (mxc_tpu_cipher_t cipher);
863 
871 unsigned int MXC_TPU_Cipher_GetBlockSize (mxc_tpu_cipher_t cipher);
872 
878 void MXC_TPU_Cipher_SetMode (mxc_tpu_cipher_mode_t mode);
879 
885 mxc_tpu_cipher_mode_t MXC_TPU_Cipher_GetMode (void);
886 
892 void MXC_TPU_Cipher_SetCipher (mxc_tpu_cipher_t cipher);
893 
899 mxc_tpu_cipher_t MXC_TPU_Cipher_GetCipher (void);
900 
906 void MXC_TPU_Cipher_SetKeySource (mxc_tpu_cipher_key_t source);
907 
913 mxc_tpu_cipher_key_t MXC_TPU_Cipher_GetKeySource (void);
914 
919 void MXC_TPU_Cipher_LoadKey (void);
920 
926 void MXC_TPU_Cipher_SetOperation (int encrypt);
927 
935 void MXC_TPU_Cipher_SetKey (uint8_t* key, int len);
936 
943 void MXC_TPU_Cipher_SetIV (uint8_t* iv, int len);
944 
951 void MXC_TPU_Cipher_GetIV (uint8_t* ivOut, int len);
952 
953 /************************/
954 /* High Level Functions */
955 /************************/
956 
965 int MXC_TPU_Cipher_Encrypt (mxc_tpu_cipher_req_t* req);
966 
975 int MXC_TPU_Cipher_Decrypt (mxc_tpu_cipher_req_t* req);
976 
984 void MXC_TPU_Cipher_EncryptAsync (mxc_tpu_cipher_req_t* req);
985 
993 void MXC_TPU_Cipher_DecryptAsync (mxc_tpu_cipher_req_t* req);
994 
995 #endif /* _TPU_H_ */
996