drv: sa: Add USE_DKEK flag support
[keystone-rtos/sa-lld.git] / salld.h
1 #ifndef _SALLD_H
2 #define _SALLD_H
4 /* ========================================================================== */
5 /**
6  *  @file   salld.h
7  *
8  *  path    ti/drv/sa/salld.h
9  *
10  *  @brief  SA LLD Interface Unit API and Data Definitions
11  *
12  *  ============================================================================
13  *  Copyright (c) Texas Instruments Incorporated 2009-2018
14  * 
15  *  Redistribution and use in source and binary forms, with or without 
16  *  modification, are permitted provided that the following conditions 
17  *  are met:
18  *
19  *    Redistributions of source code must retain the above copyright 
20  *    notice, this list of conditions and the following disclaimer.
21  *
22  *    Redistributions in binary form must reproduce the above copyright
23  *    notice, this list of conditions and the following disclaimer in the 
24  *    documentation and/or other materials provided with the   
25  *    distribution.
26  *
27  *    Neither the name of Texas Instruments Incorporated nor the names of
28  *    its contributors may be used to endorse or promote products derived
29  *    from this software without specific prior written permission.
30  *
31  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
32  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
33  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
34  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
35  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
36  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
37  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
38  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
39  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
40  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
41  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42  *
43 */
44  
45 /**  @mainpage Security Accelerator Low Level Driver
46  *
47  *   @section intro  Introduction
48  *
49  *   The Security Accelerator (SA) also known as cp_ace (Adaptive Cryptographic Engine) is designed to 
50  *   provide packet security as part of IPSEC, SRTP, and 3GPP industry standards. The security accelerator 
51  *   low level driver (referred to as the module) provides APIs for the configuration and control of 
52  *   the security accelerator sub-system. The SA low level driver provides an abstraction layer between 
53  *   the application and the Security Accelerator Sub System (SASS). It provides both the system level 
54  *   interface and the channel-level interface with a set of APIs defined here.
55  *
56  *   The common interface maintains the system-level resources and needs to be coordinated among multiple 
57  *   CGEM cores. All the data access provided by the common interface will invoke the SA CSL layer. 
58  *   The common interface performs the following tasks:
59  *    - Reset, download and update the SA PDSP images.
60  *    - Query SA states and statistics.
61  *    - Read a 64-bit true random number.
62  *    - Perform the large integer arithmetic through the PKA module.
63  *    - Monitor and report SA system errors.
64  *
65  *   The channel interface performs protocol-specific pre-processing for all the packets to be passed to 
66  *   the SA and protocol-specific post-processing of all the packets received from the SA. The channel interface 
67  *   performs the following tasks:
68  *   - Convert the channel configuration information into the security contexts defined by the SA.
69  *   - Perform protocol-specific packet operations such as insertion of the ESP header, padding and ESP tail.
70  *   - Decrypt and authenticate the received SRTP packet when the SA is not able to perform the operations 
71  *     due to the key validation failure.
72  *   - Generate the SA operation control command labels in data mode operation.
73  *   - Maintain the protocol-specific channel statistics.
74  *
75  *   With the exception of some initial setup functions, the module does not communicate directly with
76  *   the sub-system. The driver does not contain a transport layer and is always non-blocking.  The 
77  *   software layers above the SA LLD must call the appropriate SA LLD APIs, and then call the appropriate 
78  *   PA and/or CPPI and QMSS APIs to actually send the data to the SA sub-system.
79  *
80  */
81  
82 #ifdef __cplusplus
83 extern "C" {
84 #endif
86 /* System level header files */
87 #include <stdint.h>
88 #include <stdlib.h> 
89 #include <string.h>    
91 #include <ti/drv/sa/saver.h>
93 /* 
94  * Shut off: remark #880-D: parameter "descType" was never referenced
95  *
96  * This is better than removing the argument since removal would break
97  * backwards compatibility
98  */
99 #ifdef _TMS320C6X
100 #pragma diag_suppress 880
101 #pragma diag_suppress 681
102 #elif defined(__GNUC__)
103 /* Same for GCC:
104  * warning: unused parameter descType [-Wunused-parameter]
105  * expectation is all these catch up with some other intelligent 
106  * tools like coverity, Klocwork etc, instead of dump GNU 
107  * warnings
108  */
109 #pragma GCC diagnostic push
110 #pragma GCC diagnostic ignored "-Wunused-parameter"
111 #pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
112 #endif
115 /* Define SALLD Module as a master group in Doxygen format and add all SA LLD API 
116    definitions to this group. */
117 /** @defgroup salld_module SA LLD Module API
118  *  @{
119  */
120 /** @} */
121    
122 /** @defgroup salld_api_functions SA LLD Functions
123  *  @ingroup salld_module
124  */
125  
126 /** @defgroup salld_api_macros SA LLD Macros
127  *  @ingroup salld_module
128  */
130 /** @defgroup salld_api_structures SA LLD Data Structures
131  *  @ingroup salld_module
132  */
134 /** @defgroup salld_api_constants SA LLD Constants (enums and defines)
135  *  @ingroup salld_module
136  */
137  
139 /**
140  *  @defgroup salldDebugMessageTypes SALLD Debug message types
141  *  @ingroup salld_api_constants
142  *  @{
143  *
144  *  @name SALLD Debug message types
145  *
146  *  Debug message types used by debugInfo().
147  */
148 /*@{*/
149 /**
150  *  @def  sa_DBG_INFORMATIONAL
151  *        SALLD Debug Message Type -- SA LLD general debug information message.
152  */
153 #define sa_DBG_INFORMATIONAL   0
154 /**
155  *  @def  sa_DBG_WARNING
156  *        SALLD Debug Message Type -- SA LLD warning debug information message.
157  */
158 #define sa_DBG_WARNING         1 
160 /**
161  *  @def  sa_DBG_FATAL_ERROR
162  *        SALLD Debug Message Type -- SA LLD critical debug information message.
163  */
164 #define sa_DBG_FATAL_ERROR     2
165 /*@}*/
166 /** @} */
168 /**
169  *  @defgroup salldDebugMessageCodes SALLD Debug message codes
170  *  @ingroup salld_api_constants
171  *  @{
172  *
173  *  @name SALLD Debug message codes
174  *
175  *  Debug message codes used by debugInfo().
176  */
177 /*@{*/
178 /**
179  *  @def  sa_MSG_NO_MKI_LEN_CHANGE_ON_FLY
180  *        SALLD Debug Message Code -- One-the-fly MKI change is not supported.
181  */
182 #define sa_MSG_NO_MKI_LEN_CHANGE_ON_FLY    1
183 /**
184  *  @def  sa_MSG_MKI_LEN_IS_ZERO
185  *        SALLD Debug Message Code -- MKI length is zero.
186  */
187 #define sa_MSG_MKI_LEN_IS_ZERO             2 
188 /*@}*/
189 /** @} */
191 /**
192  *  @defgroup  salldSubSysStates SALLD Sub-System Queries and States
193  *  @ingroup salld_api_constants
194  *  @{
195  *
196  *  @name SALLD Sub-System Queries and States
197  *
198  *  SA Sub-System reset state and query arguments used by API function @ref Sa_resetControl
199  */
200 /*@{*/
201 /**
202  *  @def  sa_STATE_RESET  
203  *        The Sub-System is in reset.
204  */
205 #define sa_STATE_RESET            0  /**< Sub-System state reset */
207 /**
208  *  @def  sa_STATE_ENABLE
209  *        The Sub-System state is enabled.
210  */
211 #define sa_STATE_ENABLE           1  /**< Sub-System state enable  */
213 /**
214  *  @def  sa_STATE_QUERY
215  *        Query the Sub-System state.
216  */
217 #define sa_STATE_QUERY            2  /**< Query the Sub-System state */
219 /**
220  *  @def  sa_STATE_INCONSISTENT
221  *        The Sub-System state is partially enabled.
222  */
223 #define sa_STATE_INCONSISTENT     3  /**< Sub-System is partially enabled */
225 /**
226  *  @def  sa_STATE_INVALID_REQUEST
227  *        Invalid state command to the Sub-System.
228  */
229 #define sa_STATE_INVALID_REQUEST  4  /**< Invalid state command to the Sub-System */
231 /**
232  *  @def  sa_STATE_ENABLE_FAILED
233  *        The Sub-System do not respond after restart.
234  */
235 #define sa_STATE_ENABLE_FAILED    5   /**<  The Sub-System did not respond after restart */
236 /**
237  *  @def  sa_STATE_INVALID
238  *        The Sub-System is at an invalid state for requested operation.
239  */
240 #define sa_STATE_INVALID          6   /**<  The Sub-System  at an invalid state for requested operation */
242 /*@}*/
243 /** @} */
245 /**
246  *  @ingroup salld_api_structures
247  *  @brief  Sa_State_t defines the operating state of the security accelerator sub-system
248  *
249  *  @details  The values in @ref salldSubSysStates are used both to set the state of the security accelerator
250  *            sub-system (sa_STATE_RESET and sa_STATE_ENABLE) as well as show the current state
251  *            of the system (all values).
252  */
253 typedef int Sa_State_t;
255 /**
256  *  @defgroup salldRetCodes SALLD Function Return Codes
257  *  @ingroup salld_api_constants
258  *  @{
259  *
260  *  @name SALLD Function Return Codes
261  *
262  *  Error codes returned by SALLD API functions.
263  */
264 /*@{*/
265 /**
266  *  @def  sa_ERR_OK
267  *        SALLD Return Codes -- No Error.
268  */
269 #define sa_ERR_OK                0  
270 /**
271  *  @def  sa_ERR_GEN
272  *        SALLD Return Codes -- General Error.
273  */
274 #define sa_ERR_GEN              -1 
275 /**
276  *  @def  sa_ERR_PARAMS
277  *        SALLD Return Codes -- Incorrect Input parameters.
278  */
279 #define sa_ERR_PARAMS           -2   
280 /**
281  *  @def  sa_ERR_NOMEM
282  *        SALLD Return Codes -- Memory buffers not avialable.
283  */
284 #define sa_ERR_NOMEM            -3   
286 /**
287  *  @def  sa_ERR_INV_BUF (deprecated)
288  *        SALLD Return Codes -- Invalid buffers.
289  */                                                         
290 #define sa_ERR_INV_BUF          -4   
291 /**
292  *  @def  sa_ERR_INV_PROTO_TYPE
293  *        SALLD Return Codes -- Unsupported security protocol type.
294  */
295 #define sa_ERR_INV_PROTO_TYPE   -5
296 /**
297  *  @def  sa_ERR_NO_CTX_BUF
298  *        SALLD Return Codes -- Required Context Buffer not available.
299  */
300 #define sa_ERR_NO_CTX_BUF       -6 
301 /**
302  *  @def  sa_ERR_KEY_EXPIRED
303  *        SALLD Return Codes -- Security Key is expired.
304  */
305 #define sa_ERR_KEY_EXPIRED      -7 
306 /**
307  *  @def  sa_ERR_REPLAY_OLD
308  *        SALLD Return Codes -- Receive Packet is out of replay window range.
309  */
310 #define sa_ERR_REPLAY_OLD       -8 
311 /**
312  *  @def  sa_ERR_REPLAY_DUP
313  *        SALLD Return Codes -- Duplicated Packet is received.
314  */
315 #define sa_ERR_REPLAY_DUP       -9 
316 /**
317  *  @def  sa_ERR_AUTH_FAIL
318  *        SALLD Return Codes -- Authentication Failure.
319  */
320 #define sa_ERR_AUTH_FAIL        -10 
321 /**
322  *  @def  sa_ERR_PADDING_FAIL
323  *        SALLD Return Codes -- ESP Padding Verification Failure.
324  */
325 #define sa_ERR_PADDING_FAIL     -11 
326 /**
327  *  @def  sa_ERR_CLOSE_PENDING
328  *        SALLD Return Codes -- Close still pending, wait for Security context to be freed.
329  */
330 #define sa_ERR_CLOSE_PENDING    -12 
331 /**
332  *  @def  sa_ERR_UNSUPPORTED
333  *        SALLD Return Codes -- API is not supported.
334  */
335 #define sa_ERR_UNSUPPORTED      -13 
336 /**
337  *  @def  sa_ERR_STATS_UNAVAIL
338  *        SALLD Return Codes -- Statistics is not available yet.
339  */
340 #define sa_ERR_STATS_UNAVAIL    -14 
341 /**
342  *  @def  sa_ERR_MODULE_BUSY
343  *        SALLD Return Codes -- Module (RNG or PKA) is busy serving pending request.
344  */
345 #define sa_ERR_MODULE_BUSY      -15
346 /**
347  *  @def  sa_ERR_MODULE_UNAVAIL
348  *        SALLD Return Codes -- Module (RNG or PKA) is not available (initialized) yet.
349  */
350 #define sa_ERR_MODULE_UNAVAIL   -16 
351 /**
352  *  @def  sa_ERR_PKA_TIMEOUT
353  *        SALLD Return Codes -- PKA operation timeout.
354  */
355 #define sa_ERR_PKA_TIMEOUT      -17 
356 /**
357  *  @def  sa_ERR_SWINFO_UNAVAIL
358  *        SALLD Return Codes -- Software Information is not available yet.
359  */
360 #define sa_ERR_SWINFO_UNAVAIL   -18
361 /**
362  *  @def  sa_ERR_INV_HANDLE
363  *        SALLD Return Codes -- Invalid system or channel handles.
364  */                                                         
365 #define sa_ERR_INV_HANDLE       -19
366 /**
367  *  @def  sa_ERR_INV_ENDIAN_MODE
368  *        SALLD Return Codes -- System or Channel instance using the different endian mode than the processor.
369  */                                                         
370 #define sa_ERR_INV_ENDIAN_MODE  -20   
371 /**
372  *  @def  sa_ERR_SCRATCH_MEMORY_FULL
373  *        SALLD Return Codes -- No avail scratch memory for key storage
374  */
375 #define sa_ERR_SCRATCH_MEMORY_FULL      -21
376 /**
377  *  @def  sa_ERR_PACKET
378  *        SALLD Return Codes -- Error in the input packet such that SALLD is not able to process this packet.
379  */
380 #define sa_ERR_PACKET                   -22   
382 /**
383  *  @def  sa_ERR_INV_INT_MEM
384  *        SALLD Return Codes -- Invalid internal memory buffer for key storage
385  */
386 #define sa_ERR_INV_INT_MEM              -23
388 /** 
389   *  @def sa_ERR_API_UNSUPPORTED
390   *       The API is not supported by this generation of SASS
391   */
392 #define sa_ERR_API_UNSUPPORTED          -24
394 /** 
395   *  @def sa_ERR_PKA_OP_UNSUPPORTED
396   *       The required PKA operation  is not supported by this generation of PKA module
397   */
398 #define sa_ERR_PKA_OP_UNSUPPORTED       -25
400 /**
401  *  @def  sa_ERR_PKA_NOT_READY
402  *        Some PKA operation in in progress and it is not ready for new operation.
403  */
404 #define sa_ERR_PKA_NOT_READY            -26 
406 /**
407  *  @def  sa_ERR_PKA_OP_ERROR
408  *        The PKA operation return error.
409  */
410 #define sa_ERR_PKA_OP_ERROR             -27
412 /**
413  *  @def  sa_ERR_PKA_INVALID_STATE
414  *        PKA API is invoked at inavlid state.
415  */
416 #define sa_ERR_PKA_INVALID_STATE        -28 
418 /**
419  *  @def  sa_ERR_PKA_WORKSPACE_ERROR
420  *        There is no enough workspace to execute the PKA complex operaion.
421  */
422 #define sa_ERR_PKA_WORKSPACE_ERROR      -29
424 /**
425  *  @def  sa_ERR_PKA_DOWNLOAD_FAIL
426  *        The PKA Firmware download failure.
427  */
428 #define sa_ERR_PKA_DOWNLOAD_FAIL        -30
430 /**
431  *  @def  sa_ERR_ENGINE_STATE
432  *        The SA2UL engines are in an unexpected state
433  */
434 #define sa_ERR_ENGINE_STATE             -31
436 /**
437  *  @def  sa_PKA_OP_IN_PROGRESS
438  *        The current PKA operation is still in progress.
439  */
440 #define sa_PKA_OP_IN_PROGRESS           1
441  
442 /**
443  *  @def  sa_PKA_OP_CONTINUE
444  *        The current PKA operation is completed and it has started the next operation in sequence.
445  */
446 #define sa_PKA_OP_CONTINUE              2
448 /**
449  *  @def  sa_PKA_OP_COMPLETE
450  *        All PKA operations in sequence are completed and the final results are ready.
451  */
452 #define sa_PKA_OP_COMPLETE              sa_ERR_OK
454 /**
455  *  @def  sa_MAX_PS_AI_WORD_COUNT
456  *        upto 12 32-bit words of 'personalizatoin string' and 'additional input' used for
457  *        SP-800-90A AES-256 DRBG
458  */
460 #define sa_MAX_PS_AI_WORD_COUNT         12
463 /*@}*/
464 /** @} */
466 /**
467  *  @defgroup SecurityProtocolTypes Security Protocol Types
468  *  @ingroup salld_api_constants
469  *  @{
470  *
471  *  @name Security Protocol Types
472  *
473  *  Definition of Security Protocol Types of the packets to
474  *  be processed in the SALLD channel
475  *  
476  */ 
477 /*@{*/
478 typedef enum {
479   sa_PT_NULL = 0,        /**< No protocol: Data mode */
480   sa_PT_SRTP,            /**< Security RTP */
481   sa_PT_SRTCP,           /**< Security RTCP */
482   sa_PT_IPSEC_AH,        /**< IPSEC AH mode */
483   sa_PT_IPSEC_ESP,       /**< IPSEC ESP mode */
484   sa_PT_3GPP_AC          /**< 3GPP Air Ciphering */
485 } Sa_SecProto_e;
486 /*@}*/
487 /** @} */
489 /**
490  *  @defgroup CipherModes Cipher Modes
491  *  @ingroup salld_api_constants
492  *  @{
493  *
494  *  @name Cipher Modes
495  *
496  *  Definition of Cipher Modes used by the SA sub-engines 
497  *  
498  */ 
499 /*@{*/
500 typedef enum {
501   sa_CipherMode_NULL = 0,        /**< No encryption */
502   sa_CipherMode_AES_CTR,         /**< AES Counter mode */
503   sa_CipherMode_AES_F8,          /**< AES F8 mode */
504   sa_CipherMode_AES_CBC,         /**< AES CBC mode */
505   sa_CipherMode_DES_CBC,         /**< DES CBC mode */
506   sa_CipherMode_3DES_CBC,        /**< 3DES CBC mode */
507   sa_CipherMode_CCM,             /**< Counter with CBC-MAC mode */
508   sa_CipherMode_GCM,             /**< Galois Counter mode */
509   sa_CipherMode_GSM_A53,         /**< 3GPP GSM A5/3 encryption: Key stream generation */
510   sa_CipherMode_ECSD_A53,        /**< 3GPP ECSD A5/3 encryption: Key stream generation */
511   sa_CipherMode_GEA3,            /**< 3GPP GPRA encryption: Key stream generation */
512   sa_CipherMode_KASUMI_F8,       /**< 3GPP Kasumi F8 mode */
513   sa_CipherMode_SNOW3G_F8,       /**< 3GPP Snow3G F8 mode */
514   sa_CipherMode_ZUC_F8,          /**< 3GPP ZUC F8 mode (SASS_GEN2 only)*/
515   sa_CipherMode_LAST
516 } Sa_CipherMode_e;
517 /*@}*/
518 /** @} */
520 /**
521  *  @defgroup AuthModes Authentication Modes
522  *  @ingroup salld_api_constants
523  *  @{
524  *
525  *  @name Authentication Modes
526  *  Definition of Authentication Modes used by the SA sub-engines 
527  */ 
528 /*@{*/
529 typedef enum {
530   sa_AuthMode_NULL = 0,          /**< No idviudal Authentication  */
531   sa_AuthMode_MD5 = sa_CipherMode_LAST, /**< MD5 mode */
532   sa_AuthMode_SHA1,              /**< SHA1 mode */
533   sa_AuthMode_SHA2_224,          /**< 224-bit SHA2 mode */
534   sa_AuthMode_SHA2_256,          /**< 256-bit SHA2 mode */
535   sa_AuthMode_SHA2_384,          /**< 384-bit SHA2 mode
536                                       @note: This mode is used at Data Mode only for SA2_UL */
537   sa_AuthMode_SHA2_512,          /**< 512-bit SHA2 mode
538                                       @note: This mode is used at Data Mode only for SA2_UL */
539   sa_AuthMode_HMAC_MD5,          /**< HMAC with MD5 mode */
540   sa_AuthMode_HMAC_SHA1,         /**< HMAC with SHA1 mode */
541   sa_AuthMode_HMAC_SHA2_224,     /**< HMAC with 224-bit SHA2 mode */
542   sa_AuthMode_HMAC_SHA2_256,     /**< HMAC with 256-bit SHA2 mode */
543   sa_AuthMode_HMAC_SHA2_384,      /**< HMAC with 224-bit SHA mode
544                                       @note: This mode is used at Data Mode only for SA2_UL */
545   sa_AuthMode_HMAC_SHA2_512,      /**< HMAC with 256-bit SHA mode
546                                       @note: This mode is used at Data Mode only for SA2_UL */
547   sa_AuthMode_GMAC,              /**< Galois Message Authentication Code mode */
548   sa_AuthMode_GMAC_AH,           /**< Galois Message Authentication Code mode for IPSEC AH operation 
549                                       @note: This mode is used at Data Mode only  */
550   sa_AuthMode_CMAC,              /**< Cipher-based Message Authentication Code mode */
551   sa_AuthMode_CBC_MAC,           /**< Cipher Block Chaining - Message Authentication Code mode */
552   sa_AuthMode_AES_XCBC,          /**< AES Extended Cipher Block Chaining - Message Authentication Code mode */
553   sa_AuthMode_KASUMI_F9,         /**< 3GPP Kasumi F9 mode */
554   sa_AuthMode_SNOW3G_F9,         /**< 3GPP Snow3G F9 mode (SASS_GEN2 only) */
555   sa_AuthMode_ZUC_F9             /**< 3GPP ZUC F9 mode (SASS_GEN2 only) */
556 } Sa_AuthMode_e;
557 /*@}*/
558 /** @} */
560 /**
561  * @ingroup salld_api_structures
562  * @brief Specification of Sa_ChanHandle 
563  * The Sa_ChanHandle is used to identify a SALLD channel instance
564  */
565 typedef void*   Sa_ChanHandle;
567 /**
568  *  @defgroup saSizeConfigCtrlBit SA Size Configuration Control Bit Definitions
569  *  @ingroup salld_api_constants
570  *  @{
571  *
572  *  @name SA Size Configuration Control Bit Definitions
573  *
574  *  Bitmap definition of the ctrlBitMap in Sa_ChanSizeCfg_t and Sa_SizeCfg_t. 
575  *  
576  */ 
577 /*@{*/
578 /**
579  *  @def  sa_SIZE_CONFIG_CREATE_SHADOW_INST
580  *        Control Info -- 0:Do not create shadow instance (refer to @ref appendix2)
581  *                        1:Create Shadow instance for mixed-endianness operation  
582  */
584 #define  sa_SIZE_CONFIG_CREATE_SHADOW_INST     0x0001
587 /**
588  *  @def  sa_SIZE_CONFIG_SASS_GEN2
589  *        Control Info -- 0:First generation Security Accelerator Sub-System (SASS)
590  *                        1:Second generattion SASS at more advanced keystone2 devices such as Lamarr and Edison 
591  *                          (TBD: to be replaced with part number) 
592  */
594 #define  sa_SIZE_CONFIG_SASS_GEN2              0x0002
596 /**
597  *  @def  sa_SIZE_CONFIG_SASS_UL_GEN2
598  *        Control Info -- 0:First generation Security Accelerator Ultra Lite Sub-System (SAUL)
599  *                        1:Second generattion Security Aaccelerator Ultra Lite Sub-System (SA2_UL)
600  *                          at more advanced keystone3 devices such as Maxwell
601  */
603 #define  sa_SIZE_CONFIG_SASS_UL_GEN2              0x0003
606 /*@}*/
607 /** @} */
609 /**
610  * @ingroup salld_api_structures
611  * @brief SALLD channel size configuration structure
612  *
613  * DESCRIPTION: Data structure that defines memory requirements for SALLD channel instance
614  *
615  */
616 typedef struct {
617   Sa_SecProto_e protocolType;   /**< Security protocol type as defined by @ref SecurityProtocolTypes */
618   int           cacheLineSize;  /**< Specify the size of cache line of the memory where the channel buffers will reside.
619                                      Set this variable to 0 if this channel is not shared among multiple cores 
620                                      @note cacheLineSize should be the larger of cache line sizes amoung mixed processors */
621   uint16_t      ctrlBitMap;     /**< Various configuration information as specified at @ref saSizeConfigCtrlBit */                                   
622 } Sa_ChanSizeCfg_t;
624 /**
625  * @ingroup salld_api_structures
626  * @brief SALLD Channel Configuration structure
627  *
628  * Data structure providing configuration information in Sa_chanInit()
629  *
630  */
631 typedef struct {
632   uint32_t          ID;             /**< User specified channel ID */
633   Sa_ChanSizeCfg_t  sizeConfig;     /**< SALLD memory allocation requirement structure */
634   uint16_t          engSelect;      /**< User selected encryption/authentication engine set number, 
635                                                                                  valid only when Sa_Config_t.engSelMode is sa_EngSelMode_USERSPECIFIED */
636 } Sa_ChanConfig_t;
638 /**
639  * @ingroup salld_api_structures
640  * @brief SRTP Configuration Parameters structure
641  *
642  * Data structure defines the SRTP specific configuration parameters excluding the keys
643  *
644  */
645 typedef struct {
646   uint16_t    masterKeySize;      /**< Specify the size of the master key in bytes */  
647   uint16_t    masterSaltSize;     /**< Specify the size of the master salt in bytes */  
648   uint16_t    sessionEncKeySize;  /**< Specify the size of the session encryption key in bytes */  
649   uint16_t    sessionMacKeySize;  /**< Specify the size of the session mac key in bytes */  
650   uint16_t    sessionSaltSize;    /**< Specify the size of the session salt in bytes */  
651   uint16_t    macSize;            /**< Specify the size of the authentication tag in bytes */  
652 } Sa_SrtpConfigParams_t;
654 /**
655  *  @defgroup saIpsecTransportTypes IPSEC Transport Types
656  *  @ingroup salld_api_constants
657  *  @{
658  *
659  *  @name IPSEC Transport Types
660  *
661  *  Parameter transportType of Sa_IpsecConfigParams_t should be set to
662  *  one of these transport types.
663  */ 
664 /*@{*/
665 typedef enum {
666   sa_IPSEC_TRANSPORT_TRANSPORT = 0,  /**< Trasport mode */
667   sa_IPSEC_TRANSPORT_TUNNEL          /**< Tunnel mode */
668 } Sa_IpsecTransportType_e;
669 /*@}*/
670 /** @} */
672 /**
673  *  @defgroup saIpsecConfigCtrlBit  IPSEC Configuration Control Bit Definitions
674  *  @ingroup salld_api_constants
675  *  @{
676  *
677  *  @name IPSEC Configuration Control Bit Definitions
678  *
679  *  Bitmap definition of the ctrlBitMap in salldInpsecConfigParams_t. 
680  *  
681  */ 
682 /*@{*/
683 /**
684  *  @def  sa_IPSEC_CONFIG_ESN
685  *        Control Info -- 0:Disable Extended Sequence Number
686  *                        1:Enable Extended Sequence Number  
687  */
688 #define sa_IPSEC_CONFIG_ESN                  0x0001 
689 /**
690  *  @def  sa_IPSEC_CONFIG_PERMANENT_SC
691  *        Control Info -- 0:The corresponding security context is marked as second tier
692  *                        1:The corresponding security context ia marked as first tier so that it will
693  *                          not be evicted automatically. 
694  */
695 #define sa_IPSEC_CONFIG_PERMANENT_SC         0x0002 
696 /*@}*/
697 /** @} */
699 /**
700  * @ingroup salld_api_structures
701  * @brief IPSEC Configuration Parameters structure
702  *
703  * Data structure defines the IPSEC specific configuration parameters excluding the keys
704  *
705  */
706 typedef struct {
707   uint16_t    transportType;       /**< Specify the transport Type as defined at @ref saIpsecTransportTypes */
708   uint16_t    ctrlBitMap;          /**< Various control information as specified at @ref saIpsecConfigCtrlBit */                                                                       
709   uint16_t    encryptionBlockSize; /**< Specify the encryption block size 
710                                       1: Stream encryption and no alignment requirement
711                                       4: AES-CTR or other stream-like encryption with 4-byte 
712                                          alignment
713                                       block size: block encryption algorithm */
714   uint16_t    sessionEncKeySize;   /**< Specify the size of the session encryption key in bytes */  
715   uint16_t    sessionMacKeySize;   /**< Specify the size of the session mac key in bytes */ 
716   uint16_t    sessionSaltSize;     /**< Specify the size of the session salt in bytes */  
717   uint16_t    ivSize;              /**< Specify the size of the initialization vector in bytes */  
718   uint16_t    macSize;             /**< Specify the size of the authentication tag in bytes */ 
719   uint16_t    nextHdr;             /**< Specify the next protocol header */
720                                    /**< @note: This parameter is no longer used. */ 
721   uint32_t    spi;                 /**< Specify the SPI (Security Parameter Index) */
722   uint32_t    esnLo;               /**< Specify the initial value of the (extended) sequence Number (lower 32-bit) */
723   uint32_t    esnHi;               /**< Specify the initial value of the extended sequence Number (upper 32-bit) */
724 } Sa_IpsecConfigParams_t;
726 /**
727  *  @defgroup AcPduTypes Air Ciphering PDU Types
728  *  @ingroup salld_api_constants
729  *  @{
730  *
731  *  @name Air Ciphering PDU Types
732  *
733  *  Definition of Air Ciphering PDU Types supported in SA 
734  *  Parameter pduType of Sa_AcConfigParams_t should be set to
735  *  one of these types. Refer to @ref appendix1 for detailed 
736  *  description 
737  *  
738  */ 
739 /*@{*/
740 typedef enum {
741   sa_AcPduType_GSM = 0,         /**< All GSM PDUs */
742   sa_AcPduType_WCDMA_TMD,       /**< WCDMA MAC TMD */
743   sa_AcPduType_WCDMA_UMD,       /**< WCDMA RLC UMD */
744   sa_AcPduType_WCDMA_AMD,       /**< WCDMA RLC AMD */
745   sa_AcPduType_LTE,             /**< LTE PDCP PDUs */
746   sa_AcPduType_LTE_CP           /**< PDCP Control Plane Data Uint for SRBs */
747 } Sa_AcPduType_e;
748 /*@}*/
749 /** @} */
751 /**
752  *  @defgroup SALLDAcConfigCtrlBit   AC Configuration Control Bit Definitions
753  *  @ingroup salld_api_constants
754  *  @{
755  *
756  *  @name AC Configuration Control Bit Definitions
757  *
758  *  Bitmap definition of the ctrlBitMap in Sa_AcConfigParams_t. 
759  *  
760  */ 
761 /*@{*/
762 /**
763  *  @def  sa_AC_CONFIG_BEARER_MASK
764  *        Control Info -- 5-bit or 8-bit Bearer mask
765  */
766 #define sa_AC_CONFIG_BEARER_MASK            0x00FF 
767 /**
768  *  @def  sa_AC_CONFIG_DIR
769  *        Control Info -- 0:UE to RNC(uplink)
770  *                        1:RNC to UE(downlink)  
771  */
772 #define sa_AC_CONFIG_DIR                    0x0100 
773 /**
774  *  @def  sa_AC_CONFIG_COPY_COUNTC
775  *        Control Info -- 1: Copy Count-C into the timestamp field within CPPI Descriptor for reference
776  *                        0: Otherwise  
777  */
778 #define sa_AC_CONFIG_COPY_COUNTC            0x0200 
780 /**
781  *  @def  sa_AC_CONFIG_COUNTC_BY_APP
782  *        Control Info -- 1: Count-C is provided by application.
783  *                        0: Count-C is incremented and stored at SASS
784  *
785  * @note: This flag is only applicable for the to-air traffic when PDU type is set to LTE 
786  *        where the count-C is maintained by SASS by default.
787  *        This flag may be used to inform SASS that the count-C will be provided by application 
788  *        for LTE data traffic in slow path.  
789  */
790 #define sa_AC_CONFIG_COUNTC_BY_APP          0x0400 
792 /**
793  *  @def  sa_AC_CONFIG_KEY_IN_SCRATCH
794  *        Control Info -- 0:key is copied into security context by lld
795  *                        1:key is copied into scratch memory by lld 
796  *  @note: This feature is not supported for KeyStone devices such as C6678
797  */
798 #define sa_AC_CONFIG_KEY_IN_SCRATCH         0x0800 
800 /*@}*/
801 /** @} */
803 /**
804  * @ingroup salld_api_structures
805  * @brief AC (Air Ciphering) Configuration Parameters structure
806  *
807  * Data structure defines the AC specific configuration parameters excluding the keys
808  *
809  */
810  
811 typedef struct {
812   uint32_t    countC;              /**< Specify the high bits, HFN, for the frame Counter 
813                                       WCDMA RLC AM: the high 20 bits are used
814                                       WCDMA RLC UM: the high 25 bits are used
815                                       WCDMA RLC TM: the high 25 bits are used
816                                       LTE: All 32-bit is used as Count-C
817                                       GSM: Not used */
818   uint32_t    fresh;               /**< Specify the 32-bit random number (fresh) required
819                                       for some integrity check algorithms */   
820   uint32_t    ivLow26;             /**< Specify the low 26-bit value of the initialization vector */   
821   uint16_t    pduType;             /**< Specify the Air Ciphering PDU Type as defined at @ref Sa_AcPduType_e */
822   uint16_t    ctrlBitMap;          /**< Various control information as specified at @ref SALLDAcConfigCtrlBit */                                                                       
823   uint16_t    sessionEncKeySize;   /**< Specify the size of the session encryption key (Kc) in bytes 
824                                         Note: The LLD may expand the key stream based on the encryption mode */  
825   uint16_t    sessionMacKeySize;   /**< Specify the size of the session mac key in bytes */ 
826   uint16_t    ivSize;              /**< Specify the size of the initialization vector in bytes */  
827   uint16_t    macSize;             /**< Specify the size of the authentication tag in bytes */ 
828 } Sa_AcConfigParams_t;
830 /**
831  *  @defgroup SALLDDmConfigCtrlBit   Data Mode Configuration Control Bit Definitions
832  *  @ingroup salld_api_constants
833  *  @{
834  *
835  *  @name Data Mode Configuration Control Bit Definitions
836  *
837  *  Bitmap definition of the ctrlBitMap in Sa_DmConfigParams_t. 
838  *  
839  */ 
840 /*@{*/
841 /**
842  *  @def  sa_DM_CONFIG_SELECT_AIR_CIPHER_ENG
843  *        Control Info -- 1: indicate selection of Air Cipher engine in data mode
844  *                        0: use Encryption engine (default)
845  *  @note: There are Encryption Engine and Air Cipher Engine in SASS. There are
846  *  certain types of algorithms such as AES_CTR which both of these engines are
847  *  capable of executing. By default the data mode selects to use the encryption
848  *  engine for the algorithms such as AES_CTR. To seperate the Air Cipher traffic
849  *  from the IPSec traffic, application may select the air cipher engine
850  *  for the encryption by setting this bit.
851  *
852  *  For devices such as K2G (NSS_LITE) which do not have air cipher engine
853  *  setting this bit would cause error during datamode channel control configuration.
854  *
855  *  This bit is supported for SA LLD releases version 3.0.0.15 or higher
856  */
857 #define sa_DM_CONFIG_SELECT_AIR_CIPHER_ENG  ((uint16_t) (0x0001U))
859 /**
860  *  @def  sa_DM_CONFIG_PROMOTE_NONSECURE
861  *        Control Info -- 1: promotion of normal world packet to secure packet
862  *                           intended to land in the secure memory (only for sa2ul)
863  *                        0: no promotion
864  *  @note: Promotion of non-secure packet to be secure packet also always requires
865  *         the 48-bit SCPTR that comes with the packet to be within the range
866  *         of 'SCPTR Promote Range' registers.
867  *
868  *  For devices that do not have SA2UL setting this bit would cause no action
869  *
870  */
871 #define sa_DM_CONFIG_PROMOTE_CHANNEL  ((uint16_t) (0x0002U))
873 /**
874  *  @def  sa_DM_CONFIG_DEMOTE_SECURE
875  *        Control Info -- 1: demotion of secure packet to normal world packet
876  *                           intended to land in the secure memory (only for sa2ul)
877  *                        0: no demotion
878  * 
879  *  For devices that do not have SA2UL setting this bit would cause no action
880  *
881  */
882 #define sa_DM_CONFIG_DEMOTE_CHANNEL  ((uint16_t) (0x0004U))
884 /**
885  *  @def  sa_DM_CONFIG_USE_SECURE_CTX_FOR_NON_SECURE_CHANNEL
886  *        Control Info -- 1: a normal world packet may use secure context
887  *                        0: non-secure packet for this context can't use secure context
888  * 
889  *  For devices that do not have SA2UL setting this bit would cause no action
890  *
891  */
892 #define sa_DM_CONFIG_USE_SECURE_CTX_FOR_NON_SECURE_CHANNEL  ((uint16_t) (0x0008U))
894 /**
895  *  @def  sa_DM_CONFIG_USE_DKEK
896  *        Control Info -- 1: Set the USE_DKEK flag in the security context so
897  *                           that DKEK programmed by DMSC is loaded in-band
898  *                           instead of user-supplied key
899  *                        0: Do not set USE_DKEK flag. User supplies a key
900  *                           directly.
901  *
902  *  For devices that do not have SA2UL setting this bit would cause no action
903  *
904  */
905 #define sa_DM_CONFIG_USE_DKEK  ((uint16_t) (0x0010U))
908 /*@}*/
909 /** @} */
911 /**
912  * @ingroup salld_api_structures
913  * @brief Data Mode Configuration Parameters structure
914  *
915  * Data structure defines the Data Mode specific configuration parameters excluding the keys.
916  *
917  * Due to hardware limiations in IP, below restrictions apply :
918  * 
919  @verbatim
920   ---------------------------------------------------------------------------
921   | Cipher Mode              | Restriction                                  |
922   ---------------------------------------------------------------------------
923   | - sa_CipherMode_CCM      | - (IV Size + Salt Size) should not exceed 13 | 
924   |                          | - AAD size should not exceed 14              |
925   |                          | - authentication mode should be null     |
926   ---------------------------------------------------------------------------
927   | - sa_CipherMode_GCM      | - (IV Size + Salt Size) should be 12         | 
928   |                          | - AAD size should not exceed 16              |
929   |                          | - authentication mode should be null     |
930   ---------------------------------------------------------------------------
931   | - sa_CipherMode_DES_CBC  | - (IV Size should be 8                       |
932   |                          | - Salt size should be 0                      | 
933   ---------------------------------------------------------------------------  
934   | - sa_CipherMode_3DES_CBC | - (IV Size should be 8                       |
935   |                          | - Salt size should be 0                      | 
936   ---------------------------------------------------------------------------  
937   | - sa_CipherMode_KASUMI_F8| - (IV Size should be 8                       |
938   |                          |                                              |
939   ---------------------------------------------------------------------------  
940   | - sa_CipherMode_SNOW3G_F8| - (IV Size should be 16                      |
941   |                          |                                              |
942   --------------------------------------------------------------------------- 
944   ---------------------------------------------------------------------------
945   | Auth Mode                | Restriction                                  |
946   ---------------------------------------------------------------------------
947   | - sa_AuthMode_GMAC       | - (IV Size + Salt Size) should be 12         | 
948   |                          | - AAD size should not exceed 16              |
949   |                          | - cipher mode should be null             |
950   ---------------------------------------------------------------------------
951   | - sa_AuthMode_GMAC_AH    | - (IV Size should be 8                       |
952   |                          | - Salt size should be 4                      | 
953   |                          | - cipher mode should be null             |
954   ---------------------------------------------------------------------------  
955   | - sa_AuthMode_KASUMI_F9  | - (IV Size should be 8                       |
956   |                          |                                              | 
957   ---------------------------------------------------------------------------
958  @endverbatim
959  */
960 typedef struct {
961   uint16_t    ctrlBitMap;         /**< Various control information as specified at @ref SALLDDmConfigCtrlBit */
962   uint16_t    sessionEncKeySize;  /**< Specify the size of the session encryption key in bytes */  
963   uint16_t    sessionMacKeySize;  /**< Specify the size of the session mac key in bytes */  
964   uint16_t    sessionSaltSize;    /**< Specify the size of the session salt used in the GCM/CCM operation in bytes */  
965   uint16_t    ivSize;             /**< Specify the size of the initialization vector in bytes */  
966   uint16_t    macSize;            /**< Specify the size of the authentication tag in bytes */  
967   uint16_t    aadSize;            /**< Specify the size of the additional authenticated data in bytes used in CCM and GCM modes */
968   uint16_t    enc;                /**< TRUE: Encryption(To-Air); FALSE: Decryption (From-Air)*/
969   uint16_t    enc1st;             /**< TRUE: Perform encryption first; FALSE: Perform authentication first */
970 #if defined(NSS_LITE2)
971   uint8_t     priv;               /**< Specify the priv for the security context creation */
972   uint8_t     privId;             /**< Specify the priv ID for the security context to checking with incoming packets to match */
973 #endif
974 } Sa_DataModeConfigParams_t;
976 /**
977  * @ingroup salld_api_structures
978  * @brief SALLD Protocol-specfic Configuration Parameters structure
979  *
980  * Data structure defines the security protocol specific configuration parameters
981  *
982  */
983 typedef union {
984   Sa_SrtpConfigParams_t      srtp;       /**< Specify the configuration parameters for SRTP */
985   Sa_IpsecConfigParams_t     ipsec;      /**< Specify the configuration parameters for IPSEC */
986   Sa_AcConfigParams_t        ac;         /**< Specify the configuration parameters for Air Ciphering */
987   Sa_DataModeConfigParams_t  data;       /**< Specify the configuration parameters for Data Mode */
988 } Sa_ProtocolConfigParams_t;   
990 /**
991  *  @defgroup SALLDDestInfoCtrlBit  SALLD Destination Info Control Bit Definitions
992  *  @ingroup salld_api_constants
993  *  @{
994  *
995  *  @name SALLD Destination Info Control Bit Definitions
996  *  Bitmap definition of the ctrlBitfield in Sa_DestInfo_t
997  *  It allows selective enabling/disabling of specific SALLD operations
998  *  
999  */ 
1000 /*@{*/
1001 /**
1002  *  @def  sa_DEST_INFO_CTRL_USE_LOC_DMA
1003  *        Control Info -- Set: Use Local DMA
1004  *                        Clear: Use Global DMA (defAult)
1005  *
1006  *  There are Network Sub-System (NSS) internal DMA resources including CPPI and QMSS which can be used to transfer packets within 
1007  *  the NSS such as     from PASS to SASS and vica versa. This control bit is used to enable local DMA tranfer from SASS to PASS. 
1008  *
1009  *  @note: This feature is only supported at the second generation NSS devices.
1010  */
1011 #define sa_DEST_INFO_CTRL_USE_LOC_DMA        0x01 
1012 /*@}*/
1013 /** @} */
1016 /**
1017  * @ingroup salld_api_structures
1018  * @brief SALLD Destination Info structure
1019  *
1020  * Data structure defines the destination parameters which are used
1021  * by SASS to deliver the processed packets to the desired destination
1022  *
1023  */
1024 typedef struct {
1025   uint8_t     ctrlBitfield; /**< Control Bit Map to specify destination related operations such as local DMA 
1026                                          as defined at @ref SALLDDestInfoCtrlBit */ 
1028   uint16_t    flowID;     /**< Specify the CPPI Flow ID */
1029   uint16_t    queueID;    /**< Specify the 16-bit destination Queue ID (OR Ring ID for SA2UL) */
1030   uint32_t    swInfo0;    /**< User-defined channel-specific parameter which will be placed in SwInfo0 for packets from SA */
1031   uint32_t    swInfo1;    /**< User-defined channel-specific parameter which will be placed in SwInfo1 for packets from SA */
1032 } Sa_DestInfo_t;
1034 /**
1035  * @ingroup salld_api_structures
1036  * @brief SALLD General Configuration Parameters structure
1037  *
1038  * Data structure defines the general configuration parameters excluding the keys and related 
1039  * re-key parameters
1040  *
1041  */
1042 typedef struct {
1043   Sa_CipherMode_e cipherMode;         /**< Specify the cipher mode as defined at @ref CipherModes */
1044   Sa_AuthMode_e   authMode;           /**< Specify the authentication mode as defined at @ref AuthModes */
1045   Sa_DestInfo_t   destInfo;           /**< Specify the post-SA destination information */
1046   Sa_ProtocolConfigParams_t   params; /**< Specify the protocol-specific configuration parameters */
1047 } Sa_GenConfigParams_t;
1049 /**
1050  *  @defgroup SALLDCtrlInfoValidBit  SALLD General Control Info Valid Bit Definitions
1051  *  @ingroup salld_api_constants
1052  *  @{
1053  *
1054  *  @name SALLD General Control Info Valid Bit Definitions
1055  *  Bitmap definition of the validBitfield in Sa_GenCtrlInfo_t. 
1056  *  It allows selective control parameters
1057  */ 
1058 /*@{*/
1059 /**
1060  *  @def  sa_CONTROLINFO_VALID_CTRL_BITMAP
1061  *        Control Info -- ctrlBitfield 
1062  */
1063 #define sa_CONTROLINFO_VALID_CTRL_BITMAP     0x0001 
1064 /**
1065  *  @def  sa_CONTROLINFO_VALID_TX_CTRL
1066  *        Control Info -- txCtrl
1067  */
1068 #define sa_CONTROLINFO_VALID_TX_CTRL         0x0002 
1069 /**
1070  *  @def  sa_CONTROLINFO_VALID_RX_CTRL
1071  *        Control Info -- rtxCtrl
1072  */
1073 #define sa_CONTROLINFO_VALID_RX_CTRL         0x0004 
1074 /**
1075  *  @def  sa_CONTROLINFO_VALID_REPLAY_WIN
1076  *        Control Info -- replayWindowSize 
1077  */
1078 #define sa_CONTROLINFO_VALID_REPLAY_WIN      0x0008 
1079 /*@}*/
1080 /** @} */
1082 /**
1083  *  @defgroup SALLDCtrlInfoCtrlBit  SALLD General Control Info Control Bit Definitions
1084  *  @ingroup salld_api_constants
1085  *  @{
1086  *
1087  *  @name SALLD General Control Info Control Bit Definitions
1088  *  Bitmap definition of the ctrlBitfield in Sa_GenCtrlInfo_t. 
1089  *  It allows selective enabling/disabling of specific SALLD operations
1090  *  
1091  */ 
1092 /*@{*/
1093 /**
1094  *  @def  sa_CONTROLINFO_CTRL_TX_ON
1095  *        Control Info -- Enable Tx
1096  */
1097 #define sa_CONTROLINFO_CTRL_TX_ON            0x0001 
1098 /**
1099  *  @def  sa_CONTROLINFO_CTRL_RX_ON
1100  *        Control Info -- Enable Rx
1101  */
1102 #define sa_CONTROLINFO_CTRL_RX_ON            0x0002 
1103 /**
1104  *  @def  sa_CONTROLINFO_CTRL_TX_RX_MASK
1105  *        Control Info -- Tx/Rx Control 
1106  *                        Bit Mask 
1107  */
1108 #define sa_CONTROLINFO_CTRL_TX_RX_MASK       0x0003 
1109 /**
1110  *  @def  sa_CONTROLINFO_CTRL_SW_ONLY
1111  *        Control Info -- Software support only.
1112  *        It is used for the protocols which are not supported by the SA 
1113  *        firmware such as SRTCP.                
1114  */
1115 #define sa_CONTROLINFO_CTRL_SW_ONLY          0x0008 
1116 /**
1117  *  @def  sa_CONTROLINFO_CTRL_OP_MASK
1118  *        Control Info -- Operation Control 
1119  *                        Bit Mask 
1120  */
1121 #define sa_CONTROLINFO_CTRL_OP_MASK          0x000b 
1122 /*@}*/
1123 /** @} */
1125 /**
1126  * @ingroup salld_api_structures
1127  * @brief SALLD General Control Information structure
1128  *
1129  * Data structure defines the general control information of the security channel excluding the keys 
1130  * and related re-key parameters
1131  *
1132  */
1133 typedef struct {
1134   uint16_t validBitfield;           /**< Specify valid parameters as defined at @ref SALLDCtrlInfoValidBit */
1135   uint16_t ctrlBitfield;            /**< Control Bit Map to specify tx/rx and other operations 
1136                                          as defined at @ref SALLDCtrlInfoCtrlBit */ 
1137   Sa_GenConfigParams_t txCtrl;      /**< Specify the general configuration parameters in Tx
1138                                          (to-network) direction */  
1139   Sa_GenConfigParams_t rxCtrl;      /**< Specify the general configuration parameters in Rx
1140                                          (from-network) direction */
1141   uint16_t replayWindowSize;        /**< Specify the size of the replay window
1142                                          (SRTP 64 IPSEC 64:128) */  
1143 } Sa_GenCtrlInfo_t;
1145 /**
1146  *  @defgroup SALLDSrtpKeyCtrlInfo  SALLD SRTP Key Control Info Bit Definitions
1147  *  @ingroup salld_api_constants
1148  *  @{
1149  *
1150  *  @name SRTP Key Control Info Bit Definitions
1151  *
1152  *  Bitmap definition of the ctrlBitfield in Sa_SrtpKeyParams_t. 
1153  */ 
1154 /*@{*/
1155 /**
1156  *  @def  sa_SRTP_KEY_CTRL_MASTER_KEY
1157  *        Control Info -- Set: MASTER_KEY available
1158  */
1159 #define sa_SRTP_KEY_CTRL_MASTER_KEY        0x0001 
1160 /**
1161  *  @def  sa_SRTP_KEY_CTRL_MASTER_SALT
1162  *        Control Info -- Set: MASTER_SALT available
1163  */
1164 #define sa_SRTP_KEY_CTRL_MASTER_SALT       0x0002 
1165 /**
1166  *  @def  sa_SRTP_KEY_CTRL_KEY_DERIVE_RATE
1167  *        Control Info -- Set: key derivation rate available
1168  */
1169 #define sa_SRTP_KEY_CTRL_KEY_DERIVE_RATE   0x0004 
1170 /**
1171  *  @def  sa_SRTP_KEY_CTRL_KEY_LIFETIME
1172  *        Control Info -- Set: key lifetime available
1173  */
1174 #define sa_SRTP_KEY_CTRL_KEY_LIFETIME      0x0008 
1175 /**
1176  *  @def  sa_SRTP_KEY_CTRL_ROC
1177  *        Control Info -- Set: Initial ROC is available
1178  */
1179 #define sa_SRTP_KEY_CTRL_ROC               0x0010 
1181 /**
1182  *  @def  sa_SRTP_KEY_CTRL_MKI
1183  *        Control Info -- Set: MKI available
1184  */
1185 #define sa_SRTP_KEY_CTRL_MKI               0x0020 
1186 /**
1187  *  @def  sa_SRTP_KEY_CTRL_KEY_TYPE_FROM_TO
1188  *        Control Info -- Set: From To Key 
1189  *                        Clear: MKI Key
1190  */
1191 #define sa_SRTP_KEY_CTRL_KEY_TYPE_FROM_TO  0x0040 
1192 /*@}*/
1193 /** @} */
1195 /**
1196  * @ingroup salld_api_structures
1197  * @brief SRTP Key Information structure
1198  *
1199  * Data structure defines the SRTP Key related parameters
1200  *
1201  */
1202 typedef struct {
1203   uint16_t    ctrlBitfield;    /**< Specify the Key types and other control information as defined at @ref SALLDSrtpKeyCtrlInfo */
1204   uint8_t*    masterKey;       /**< Specify the master key */
1205   uint8_t*    masterSalt;      /**< Specify the master Salt */
1206   uint16_t    derivRate;       /**< Specify the key derivation rate in n of 2^n format (where 0 <= n <= 24) 
1207                                     if not set then use default value, i.e no key derivation */
1208   uint16_t    keyLifeTimeMsw;  /**< Specify the maximum number of packets allowed for the master
1209                                   key combination */ 
1210   uint32_t    keyLifeTimeLsw;  /**< Specify the maximum number of packets allowed for the master
1211                                 key combination */ 
1212   uint32_t    roc;             /**< SRTP: Specify the initial value of the rollover counter 
1213                                     SRTCP: Specify the initial index at the tx packet */
1214   uint32_t    fromEsnMsw;      /**< Specify the starting 48-bit extended sequence number
1215                                 of the specified From-To keys */
1216   uint16_t    fromEsnLsw;      /**< Specify the starting 48-bit extended sequence number
1217                                 of the specified From-To keys */
1218   uint32_t    toEsnMsw;        /**< Specify the last 48-bit extended sequence number
1219                                 of the specified From-To keys */
1220   uint16_t    toEsnLsw;        /**< Specify the last 48-bit extended sequence number
1221                                 of the specified From-To keys */
1222   uint16_t    mkiSize;         /**< Specify the size of the MKI in bytes */
1223   uint32_t    mki;             /**< Specify the MKI value */                              
1224 } Sa_SrtpKeyParams_t;
1226 /**
1227  *  @ingroup salld_api_constants
1228  *  @brief   Define the maximum key size supported by SASS 
1229  */
1230 #if defined(NSS_LITE2)
1231 #define SALLD_MAX_KEY_SIZE      64
1232 #else
1233 #define SALLD_MAX_KEY_SIZE      32
1234 #endif
1236 /**
1237  *  @defgroup SALLDIpsecKeyCtrlInfo  SALLD IPSEC Key Control Info Bit Definitions
1238  *  @ingroup salld_api_constants
1239  *  @{
1240  *
1241  *  @name IPSEC Key Control Info Bit Definitions
1242  *
1243  *  Bitmap definition of the ctrlBitfield in Sa_IpsecKeyParams_t. 
1244  */ 
1245 /*@{*/
1246 /**
1247  *  @def  sa_IPSEC_KEY_CTRL_ENC_KEY
1248  *        Control Info -- Set: ENC_KEY available
1249  */
1250 #define sa_IPSEC_KEY_CTRL_ENC_KEY          0x0001 
1251 /**
1252  *  @def  sa_IPSEC_KEY_CTRL_MAC_KEY
1253  *        Control Info -- Set: MAC_KEY available
1254  */
1255 #define sa_IPSEC_KEY_CTRL_MAC_KEY          0x0002 
1256 /**
1257  *  @def  sa_IPSEC_KEY_CTRL_SALT
1258  *        Control Info -- Set: Session Salt available
1259  */
1260 #define sa_IPSEC_KEY_CTRL_SALT             0x0004 
1261 /*@}*/
1262 /** @} */
1264 /**
1265  * @ingroup salld_api_structures
1266  * @brief IPSEC Key Information structure
1267  *
1268  * Data structure defines the IPSEC Key related parameters
1269  *
1270  */
1271 typedef struct {
1272   uint16_t       ctrlBitfield;    /**< Specify the Key types and other control Information as defined at @ref SALLDIpsecKeyCtrlInfo */
1273   uint8_t*       sessionEncKey;   /**< Specify the session encryption key */
1274   uint8_t*       sessionAuthKey;  /**< Specify the session authentication key */
1275   uint8_t*       sessionSalt;     /**< Specify the session salt */
1276 } Sa_IpsecKeyParams_t;
1278 /**
1279  *  @defgroup SALLDAcKeyCtrlInfo  SALLD AC Key Control Info Bit Definitions
1280  *  @ingroup salld_api_constants
1281  *  @{
1282  *
1283  *  @name Air Ciphering Key Control Info Bit Definitions
1284  *
1285  *  Bitmap definition of the ctrlBitfield in Sa_AcKeyParams_t. 
1286  */ 
1287 /*@{*/
1288 /**
1289  *  @def  sa_AC_KEY_CTRL_ENC_KEY
1290  *        Control Info -- Set: ENC_KEY available
1291  */
1292 #define sa_AC_KEY_CTRL_ENC_KEY          0x0001 
1293 /**
1294  *  @def  sa_AC_KEY_CTRL_MAC_KEY
1295  *        Control Info -- Set: MAC_KEY available
1296  */
1297 #define sa_AC_KEY_CTRL_MAC_KEY          0x0002 
1298 /*@}*/
1299 /** @} */
1301 /**
1302  * @ingroup salld_api_structures
1303  * @brief Air Ciphering Key Information structure
1304  *
1305  * Data structure defines the Air Ciphering Key related parameters
1306  *
1307  */
1308 typedef struct {
1309   uint16_t     ctrlBitfield;    /**< Specify the Key types and other control Information as defined at @ref SALLDAcKeyCtrlInfo */
1310   uint8_t*     sessionEncKey;   /**< Specify the session encryption key */
1311   uint8_t*     sessionAuthKey;  /**< Specify the session authentication key */
1312 } Sa_AcKeyParams_t;
1314 /**
1315  *  @defgroup SALLDDataModeKeyCtrlInfo  SALLD Data Mode Key Control Info Bit Definitions
1316  *  @ingroup salld_api_constants
1317  *  @{
1318  *
1319  *  @name Data Mode Key Control Info Bit Definitions
1320  *
1321  *  Bitmap definition of the ctrlBitfield in Sa_DataModeKeyParams_t. 
1322  */ 
1323 /*@{*/
1324 /**
1325  *  @def  sa_DATA_MODE_KEY_CTRL_ENC_KEY
1326  *        Control Info -- Set: ENC_KEY available
1327  */
1328 #define sa_DATA_MODE_KEY_CTRL_ENC_KEY          0x0001 
1329 /**
1330  *  @def  sa_DATA_MODE_KEY_CTRL_MAC_KEY
1331  *        Control Info -- Set: MAC_KEY available
1332  */
1333 #define sa_DATA_MODE_KEY_CTRL_MAC_KEY          0x0002 
1334 /**
1335  *  @def  sa_DATA_MODE_KEY_CTRL_SALT
1336  *        Control Info -- Set: SALT available
1337  */
1338 #define sa_DATA_MODE_KEY_CTRL_SALT             0x0004 
1339 /**
1340  *  @def  sa_DATA_MODE_KEY_USE_DKEK
1341  *        Control Info -- Set: USE_DKEK field in security context
1342  */
1343 #define sa_DATA_MODE_KEY_USE_DKEK              0x0008
1344 /*@}*/
1345 /** @} */
1347 /**
1348  * @ingroup salld_api_structures
1349  * @brief Data Mode Key Information structure
1350  *
1351  * Data structure defines the Data Mode Key related parameters
1352  *
1353  */
1354 typedef struct {
1355   uint16_t     ctrlBitfield;    /**< Specify the Key types and other control Information as defined at @ref SALLDDataModeKeyCtrlInfo */
1356   uint8_t*     sessionEncKey;   /**< Specify the session encryption key */
1357   uint8_t*     sessionAuthKey;  /**< Specify the session authentication key */
1358   uint8_t*     sessionSalt;     /**< Specify the session salt in GCM/CCM only */
1359 } Sa_DataModeKeyParams_t;
1361 /**
1362  * @ingroup salld_api_structures
1363  * @brief Protocol-Specific Key Information structure
1364  *
1365  * Data structure defines the protocol-specific Key related parameters
1366  *
1367  */
1368 typedef union {
1369  Sa_SrtpKeyParams_t       srtp;    /**< Specify the key related parameters for SRTP/SRTCP */
1370  Sa_IpsecKeyParams_t      ipsec;   /**< Specify the key related parameters for IPSEC */
1371  Sa_AcKeyParams_t         ac;      /**< Specify the key related parameters for 3GPP Air Ciphering */
1372  Sa_DataModeKeyParams_t   data;    /**< Specify the key related parameters in Data Mode */
1373 } Sa_ProtocolKeyParams_t; 
1375 /**
1376  *  @defgroup SALLDKeyCtrlInfo SALLD Key Control Info Control Bit Definitions
1377  *  @ingroup salld_api_constants
1379  *  @{
1380  *
1381  *  @name SALLD Key Control Info Control Bit Definitions
1382  *
1383  *  Bitmap definition of the ctrlBitfield in Sa_KeyCtrlInfo_t. 
1384  */ 
1385 /*@{*/
1386 /**
1387  *  @def  sa_KEY_CONTROL_TX_KEY_VALID
1388  *        Control Info -- TX key is valid
1389  */
1390 #define sa_KEY_CONTROL_TX_KEY_VALID           0x0001 
1391 /**
1392  *  @def  sa_KEY_CONTROL_RX_KEY_VALID
1393  *        Control Info -- RX key is valid
1394  */
1395 #define sa_KEY_CONTROL_RX_KEY_VALID           0x0002 
1396 /* @} */ /* ingroup */
1397 /** @} */
1399 /**
1400  * @ingroup salld_api_structures
1401  * @brief SALLD Key Control Information structure
1402  *
1403  * Data structure defines the Key related information of the security channel.
1404  * It is used for initial channel configuration and re-key operation.
1405  *
1406  */
1407 typedef struct {
1408   uint16_t ctrlBitfield;           /**< Bit Map to specify tx/rx and other operations as 
1409                                         defined at @ref SALLDKeyCtrlInfo */ 
1410   Sa_ProtocolKeyParams_t txKey;    /**< Specify the security key parameters in Tx
1411                                        (to-network) direction */  
1412   Sa_ProtocolKeyParams_t rxKey;    /**< Specify the security key parameters in Rx
1413                                        (from-network) direction */
1414 } Sa_KeyCtrlInfo_t;
1416 /**
1417  *  @defgroup salldChanCtrlType SALLD Channel Control Type
1418  *  @ingroup salld_api_constants
1419  *  @{
1420  *
1421  *  @name Channel Control Type
1422  *  Definition of channel control types supported by SA LLD 
1423  *  Parameter ctrlType of Sa_ChanCtrlInfo_t should be set to
1424  *  one of these types.
1425  *
1426  */
1427 /*@{*/
1428 typedef enum {
1429   sa_CHAN_CTRL_GEN_CONFIG = 1,   /**<  Security Channel General Configuration */
1430   sa_CHAN_CTRL_KEY_CONFIG = 2    /**<  Security Channel Key Configuration */ 
1431 } Sa_ChanControlCode_e; 
1432 /*@}*/
1433 /** @} */
1435 /**
1436  * @ingroup salld_api_structures
1437  * @brief Channel Control Information structure
1438  *
1439  * Data structure providing control information in Sa_chanControl()
1440  *
1441  */
1442 typedef struct {
1443   uint16_t    ctrlType;    /**< Specify the channel control type as defined at @ref Sa_ChanControlCode_e */
1444   union {
1445     Sa_GenCtrlInfo_t  gen; /**< Specify the general control information */
1446     Sa_KeyCtrlInfo_t  key; /**< Specify the key control information */ 
1447   }ctrlInfo;                 /**< Contain the control-type specific control information */
1449 } Sa_ChanCtrlInfo_t;
1451 /**
1452  *  @defgroup PktErrorCodes SALLD PKT Error Codes 
1453  *  @ingroup salld_api_constants
1454  *  @{
1455  *
1456  *  @name SALLD PKT Error Codes
1457  *
1458  *  Definitions of the error codes for the packets received from SA
1459  */
1460 /*@{*/
1461 /**
1462  *  @def  sa_PKT_ERR_OK
1463  *        SALLD Packet Error code -- No Error.
1464  */
1465 #define sa_PKT_ERR_OK                0 
1466 /**
1467  *  @def  sa_PKT_ERR_REPLAY_OLD
1468  *        SALLD Packet Error code -- Packet rejected by SA because it is out of replay window range.
1469  */
1470 #define sa_PKT_ERR_REPLAY_OLD        1
1471 /**
1472  *  @def  sa_PKT_ERR_REPLAY_DUP
1473  *        SALLD Packet Error code -- Packet rejected by SA because it is duplicated.
1474  */
1475 #define sa_PKT_ERR_REPLAY_DUP        2  
1476 /**
1477  *  @def  sa_PKT_ERR_INVALID_KEY
1478  *        SALLD Packet Error code -- Packet rejected by SA because the key in the security
1479  *                                   context is out of date. 
1480  */
1481 #define sa_PKT_ERR_INVALID_KEY       3  
1482 /**
1483  *  @def  sa_PKT_ERR_INVALID_MKI
1484  *        SALLD Packet Error code -- Packet rejected by SA because the MKI in the security
1485  *                                   context does not match the one in the packet. 
1486  */
1487 #define sa_PKT_ERR_INVALID_MKI       4  
1488 /**
1489  *  @def  sa_PKT_ERR_AUTH_FAIL
1490  *        SALLD Packet Error code -- Packet rejected by SA because authentication failed.
1491  */
1492 #define sa_PKT_ERR_AUTH_FAIL         5
1493 /*@}*/
1494 /** @} */
1496 /**
1497  * @ingroup salld_api_structures
1498  * @brief SA Packet Error data type
1499  *
1500  * Data type defines the packet error type of all packets to be delivered to SA. 
1501  *
1502  */
1503 typedef uint16_t  Sa_PktErr_t;
1505 /**
1506  *  @defgroup SaPktDir SA Packet Directions
1507  *  @ingroup salld_api_constants
1508  *  @{
1509  *
1510  *  @name SA Packet Directions
1511  *
1512  *  Definition of SA Packet Directions used at API @ref Sa_chanGetSwInfo
1513  */ 
1514 /*@{*/
1515 typedef enum {
1516   sa_PKT_DIR_FROM_NETWORK = 0,   /**< Form-network (To-air) packet */
1517   sa_PKT_DIR_TO_NETWORK         /**< To-network (From-air) packet */
1518 } Sa_PktDir_t;
1519 /*@}*/
1520 /** @} */
1522 /**
1523  *  @ingroup salld_api_constants
1524  *  @brief   Define the maxmium number of software info parameters at @ref Sa_SWInfo_t. 
1525  */
1526 #define sa_MAX_SW_INFO_SIZE          3
1527  
1528 /**
1529  * @ingroup salld_api_structures
1530  * @brief SA Software Information structure
1531  *
1532  * Data structure defines the SA-specific software information required for all packets to 
1533  * be delivered to SA. It will be provided by the SA LLD based on the channel configuration 
1534  * parameters and the security protocols.The software information words should be copied
1535  * to the CPPI Software words area as provided through the CPPI LLD or equivalent component.
1536  *
1537  * for SA2_UL (Ultra Lite Generation 2) devices, size is always 4 and the swInfo[3] would 
1538  * hold the first 32 bits of Protocol Specific data of CPPI
1539  */
1540 typedef struct {
1541   uint16_t  size;   /**< Specify the software info size in 32-bit words */
1542   uint32_t  swInfo[sa_MAX_SW_INFO_SIZE]; /**< Specify the software information for SA */
1543 } Sa_SWInfo_t;
1546 /**
1547  *  @ingroup salld_api_macros
1548  *  @brief  sa_SWINFO_UPDATE_DEST_INFO is used to update the destination information within swInfo[2] at @ref Sa_SWInfo_t
1549  *
1550  *  @note   this macro is not applicable for socs such as AM65XX or J721E that have second generation SA Ultra Lite (SA2_UL)
1551  *
1552  *  @details  The application may want to deliver output packets to different queues for load balance.
1553  *            This macro is used to update the destination queue and CPPI flow number in the Sa_SWInfo_t data structure 
1554  *            provided by Sa_chanSendData()
1555  *
1556  */
1557 #define sa_SWINFO_UPDATE_DEST_INFO(info, queueID, flowIndex)                               \
1558 {                                                                                          \
1559     (info[0]) |= 0x40000000L;                                                              \
1560     (info[2])  = ((queueID)) | (((flowIndex) & 0xFF) << 16) | ((info[2]) & 0xFF000000L);   \
1561 }                                                                                          \
1563 /**
1564  * @ingroup salld_api_structures
1565  * @brief SA Command Label Parameter Information structure
1566  *
1567  * Data structure defines the updating information of parameters which may be updated within the 
1568  * command label per packet. 
1569  *
1570  */
1572 typedef struct {
1573   uint8_t index;   /**< Specify the index of the starting 32-bit command word */
1574   uint8_t offset;  /**< specify the offset to the parameter within the command word */  
1575   uint8_t size;    /**< Specify the size of parameter in bytes */
1577 } Sa_CmdLbParamInfo_t;
1579 /**
1580  *  @defgroup DataSubModes Data Sub Operation Modes
1581  *  @ingroup salld_api_constants
1582  *  @{
1583  *
1584  *  @name Data Sub Operation Modes
1585  *
1586  *  Definition of the sub operation modes in Data mode.
1587  *  Enhanced the sub modes to more general types of protocols such as WiMax.
1588  *  Pleae refer to @ref Sa_DataModeConfigParams_t restrictions table
1589  *  on supported IV, Salt and AAD sizes
1590  *  
1591  */ 
1592 /*@{*/
1593 typedef enum {
1594   sa_DM_GEN = 0,     /**< General operation mode */
1595   sa_DM_CCM,         /**< CCM IPSEC */
1596   sa_DM_CCM_GEN,     /**< CCM non IPSEC */
1597   sa_DM_GCM,         /**< GCM IPSEC */
1598   sa_DM_GCM_GEN,     /**< GCM non IPSEC */
1599   sa_DM_GMAC,        /**< GMAC IPSec */
1600   sa_DM_GMAC_GEN,    /**< GMAC non IPSec*/
1601   sa_DM_GMAC_AH      /**< GMAC for IPSEC AH */
1602 } Sa_DM_subMode_e;
1603 /*@}*/
1604 /** @} */
1607 /**
1608  *  @defgroup SALLDCmdLbUpdateVaildInfo  SALLD Command Label Update Vaild Bit Definitions
1609  *  @ingroup salld_api_constants
1610  *  @{
1611  *
1612  *  @name Command Label Update Valid Bit Definitions
1613  *
1614  *  Bitmap definition of the validBitfield in Sa_CmdLbUpdateInfo_t. 
1615  */ 
1616 /*@{*/
1617 /**
1618  *  @def  sa_CMDL_UPDATE_VALID_ENC
1619  *        Control Info -- Encryption related information is valid
1620  */
1621 #define sa_CMDL_UPDATE_VALID_ENC          0x0001 
1622 /**
1623  *  @def  sa_CMDL_UPDATE_VALID_AUTH
1624  *        Control Info -- Authentication related information is valid
1625  */
1626 #define sa_CMDL_UPDATE_VALID_AUTH         0x0002 
1627 /**
1628  *  @def  sa_CMDL_UPDATE_VALID_ENC_IV
1629  *        Control Info -- Encryption IV is valid
1630  */
1631 #define sa_CMDL_UPDATE_VALID_ENC_IV       0x0004 
1632 /**
1633  *  @def  sa_CMDL_UPDATE_VALID_AUTH_IV
1634  *        Control Info -- Authentication IV valid
1635  */
1636 #define sa_CMDL_UPDATE_VALID_AUTH_IV      0x0008 
1637 /**
1638  *  @def  sa_CMDL_UPDATE_VALID_AAD
1639  *        Control Info -- AAD is valid
1640  */
1641 #define sa_CMDL_UPDATE_VALID_AAD          0x0010 
1642 /**
1643  *  @def  sa_CMDL_UPDATE_VALID_AUX_KEY
1644  *        Control Info -- CMAC-type Auxiliary key is valid
1645  */
1646 #define sa_CMDL_UPDATE_VALID_AUX_KEY      0x0020 
1647 /**
1648  *  @def  sa_CMDL_UPDATE_VALID_PAYLOAD
1649  *        Control Info -- Payload pending is valid such as GMAC mode
1650  */
1651 #define sa_CMDL_UPDATE_VALID_PAYLOAD      0x0040 
1652 /**
1653  *  @def  sa_CMDL_UPDATE_VALID_ENC_SIZE
1654  *        Control Info -- Second encryption size update is required, such as CCM mode
1655  */
1656 #define sa_CMDL_UPDATE_VALID_ENC_SIZE     0x0080 
1657 /**
1658  *  @def  sa_CMDL_UPDATE_VALID_ENC_IV2
1659  *        Control Info -- Second encryption IV update is required, such as CCM mode
1660  */
1661 #define sa_CMDL_UPDATE_VALID_ENC_IV2      0x0100 
1662 /**
1663  *  @def  sa_CMDL_UPDATE_VALID_AUTH_SIZE
1664  *        Control Info -- Second authentication size update is required, such as GMAC mode
1665  */
1666 #define sa_CMDL_UPDATE_VALID_AUTH_SIZE    0x0200 
1668 /*@}*/
1669 /** @} */
1672 /**
1673  * @ingroup salld_api_structures
1674  * @brief SA Command Label Updating Information structure
1675  *
1676  * Data structure provides the information how to update the command label. The application can
1677  * use this information to update the command label per packet without invoking Sa_chanSendData() API.
1678  *
1679  */
1681 typedef struct {
1682   uint16_t  validBitfield;    /**< Specify the parameter valid Information as defined at @ref SALLDCmdLbUpdateVaildInfo */
1683   uint16_t  subMode;          /**< Specify the sub operation modes as defined at @ref DataSubModes */
1684   Sa_CmdLbParamInfo_t  encSizeInfo;    /**< Information used to update encryption size */
1685   Sa_CmdLbParamInfo_t  encSizeInfo2;   /**< Information used to update 2nd encryption size */
1686   Sa_CmdLbParamInfo_t  encOffsetInfo;  /**< Information used to update encryption offset */
1687   Sa_CmdLbParamInfo_t  encIvInfo;      /**< Information used to update encryption initialization vector */
1688   Sa_CmdLbParamInfo_t  encIvInfo2;     /**< Information used to update 2nd encryption initialization vector */
1689   Sa_CmdLbParamInfo_t  aadInfo;        /**< Information used to update AAD  */
1690   Sa_CmdLbParamInfo_t  payloadInfo;    /**< Information used to update payload padding information */
1691   Sa_CmdLbParamInfo_t  authSizeInfo;   /**< Information used to update authentication size */
1692   Sa_CmdLbParamInfo_t  authSizeInfo2;  /**< Information used to update 2nd authentication size */
1693   Sa_CmdLbParamInfo_t  authOffsetInfo; /**< Information used to update authentication offset */
1694   Sa_CmdLbParamInfo_t  authIvInfo;     /**< Information used to update authentication initialization vector */
1695   Sa_CmdLbParamInfo_t  auxKeyInfo;     /**< Information used to update auxiliary Key information */
1696   uint32_t             auxKey[8];      /**< Contain auxiliary key1/key2 */ 
1697 } Sa_CmdLbUpdateInfo_t;
1699 /**
1700  *  @ingroup salld_api_constants
1701  *   Note: For NSS_LITE2 the effective command label size is 4 bytes less than the maximum size
1702  *  @brief   Define the maxmium size of the command label stored at cmdLbBuf of @ref Sa_CmdLabelInfo_t.
1703  */
1704 #if defined (NSS_LITE2)
1705 #define sa_MAX_CMDLB_SIZE           ((uint32_t)(100U))
1706 #else
1707 #define sa_MAX_CMDLB_SIZE           ((uint32_t)(96U))
1708 #endif
1709 /**
1710  * @ingroup salld_api_structures
1711  * @brief SA Command Label Information structure
1712  *
1713  * Data structure defines the SA-specific command label information used by SA to route packet 
1714  * to sub-engines within SA. The command label information will be formatted by the SA LLD
1715  * based on the channel configuration parameters and the payload information as defined at 
1716  * @ref Sa_PayloadInfo_t. The command label should be copied to the protocol-specific section 
1717  * at the CPPI packet descriptor as provided through the CPPI LLD or equivalent component. 
1718  *
1719  * @note: This structure is only used in Data Mode and the cmdLbBuf should be provided by the
1720  *       caller.
1721  */
1722 typedef struct {
1723   uint16_t  cmdLbSize;   /**< Specify the command label size in bytes */
1724   uint8_t*  cmdLbBuf;    /**< Pointer to the buffer which contains the command labels 
1725                               The buffer should be allocated by the caller in Data
1726                               Mode opeation and 4-byte alignment is required*/
1727   Sa_CmdLbUpdateInfo_t* cmdLbUpdateInfo; /**< Pointer to command label updating data structure, the command 
1728                                               label updating information will be provided upon return if not 
1729                                               NLL pointer */                            
1730 } Sa_CmdLabelInfo_t;
1732 /**
1733  * @ingroup salld_api_structures
1734  * @brief SA Payload Information structure
1735  *
1736  * Data structure providing the payload related information used to construct the 
1737  * SA-specific command labels in data mode
1738  */
1739 typedef struct {
1740   uint8_t   encOffset;   /**< Specify the offset to the encrypted/decrypted data in the packet in bytes */
1741   uint8_t   authOffset;  /**< Specify the offset to the authenticated data in the packet in bytes */
1742   uint16_t  encSize;     /**< Specify the total number of bytes to be encrypted or decrypted */ 
1743   uint16_t  authSize;    /**< Specify the total number of bytes to be authenticated */ 
1744   uint8_t*  encIV;       /**< Contain the initialization vectors used in certain encryption modes. 
1745                             @note: IV should be specified here in GCM/GMAC/CCM mode */
1746   uint8_t*  authIV;      /**< Contain the initialization vectors used in certain authentication modes.*/
1747   uint8_t*  aad;         /**< Contain the additional authenticated data in GCM/GMAC/CCM modes */ 
1748 } Sa_PayloadInfo_t;
1750 /**
1751  * @ingroup salld_api_structures
1752  * @brief SA Rx Payload Information structure
1753  *
1754  * Data structure providing the miscellaneous header information of the received packets which is 
1755  * required for the IPSEC post-processing function to patch the outer IP header when the inner IP 
1756  * fragments have been reassembled by the hardware IP reassembly engine (RA) on the NSS Gen2 devices.
1757  *
1758  * @note: This structure should be provided at the Sa_chanReceiveData() call when the RA engine is enabled
1759  *        for inner IP. If it is not provided, the IPSEC post-processing function will not be able to handle
1760  *        inner IP reassembled packets correctly. 
1761  */
1762 typedef struct {
1763   uint8_t   ipOffset;    /**< Specify the offset to the outer IP in the packet in bytes */
1764   uint8_t   ipOffset2;   /**< Specify the offset to the inner IP in the packet in bytes 
1765                               (0: indicates there is no inner IP) */
1766 } Sa_RxPayloadInfo_t;
1769 /**
1770  * @ingroup salld_api_structures
1771  * @brief SA IPSEC NAT-T structure
1772  *
1773  * Data structure defines the IPSEC NAT-T parameters used by @ref Sa_chanSendData() API to
1774  * construct the IPSEC NAT-T (UDP) header which resides in front of IPSEC ESP header.
1775  */
1776 typedef struct {
1777   uint16_t  dstPort;   /**< Specify the destination UDP port number */
1778   uint16_t  srcPort;   /**< Specify the source UDP port number */
1779 } Sa_ipsecNatTInfo_t;
1781 /**
1782  *  @defgroup SALLDPktInfoValidBits  SALLD Packet Info Valid Bit Definitions
1783  *  @ingroup salld_api_constants
1784  *  @{
1785  *
1786  *  @name SALLD Packet Info Valid Bit Definitions
1787  *
1788  *  Bitmap definition of the validBitMap in Sa_PktInfo_t. 
1789  */ 
1790 /*@{*/
1791 /**
1792  *  @def  sa_PKT_INFO_VALID_PKT_ERR_CODE
1793  *        - pktErrorCode is present
1794  */
1795 #define sa_PKT_INFO_VALID_PKT_ERR_CODE           0x0001 
1796 /**
1797  *  @def  sa_PKT_INFO_VALID_SW_INFO
1798  *        - swInfo is present
1799  */
1800 #define sa_PKT_INFO_VALID_SW_INFO                0x0002 
1801 /**
1802  *  @def  sa_PKT_INFO_VALID_CMDLB_INFO
1803  *        - cmdlb is present
1804  */
1805 #define sa_PKT_INFO_VALID_CMDLB_INFO             0x0004 
1806 /**
1807  *  @def  sa_PKT_INFO_VALID_PAYLOAD_INFO
1808  *        - payloadInfo is present
1809  */
1810 #define sa_PKT_INFO_VALID_PAYLOAD_INFO           0x0008 
1811 /**
1812  *  @def  sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO
1813  *        - natTInfo is present
1814  */
1815 #define sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO       0x0010 
1816 /**
1817  *  @def  sa_PKT_INFO_VALID_RX_PAYLOAD_INFO
1818  *        - rxPayloadInfo is present
1819  */
1820 #define sa_PKT_INFO_VALID_RX_PAYLOAD_INFO        0x0020 
1823 /*@}*/
1824 /** @} */
1826 /**
1827 *  @defgroup SALLDEspInfoTxRxValidBits SALLD ESP TxRx Info Valid Bit Definitions
1828 *  @ingroup salld_api_constants
1829 *  @{
1831 *  @name SALLD ESP TxRx Valid Bit Definitions
1833 *  Bitmap definition of the validBitMap in salldIpsecEspTxRxInfo_t. 
1834  */ 
1835 /*@{*/
1836 /**
1837 *  @def  sa_ESP_TXRX_VALID_IPSEC_NAT_T_INFO      
1838  *        - espTxRx_natTInfo is present
1839 */
1840 #define sa_ESP_TXRX_VALID_IPSEC_NAT_T_INFO      sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO
1841 /**
1842  *  @def sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO
1843  *        - rxPayloadInfo is present
1844  */
1845 #define sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO       sa_PKT_INFO_VALID_RX_PAYLOAD_INFO 
1847 /*@}*/
1848 /** @} */
1851 /**
1852  * @ingroup salld_api_structures
1853  * @brief IpSec ESP Data send/receive info structure
1854  *
1855  */
1856 typedef struct salldIpsecEspTxRxInfo_s {
1857   uint16_t    validBitMap;                /**< Specify which parameters are vaild as defined at @ref SALLDEspInfoTxRxValidBits */
1858  uint16_t     ivSize;              /**< Specify the size of the initialization vector in bytes */  
1859   uint16_t    macSize;             /**< Specify the size of the authentication tag in bytes */
1860   uint16_t    encryptionBlockSize; /**< Specify the encryption block size 
1861                                       1: Stream encryption and no alignment requirement
1862                                       4: AES-CTR or other stream-like encryption with 4-byte 
1863                                          alignment
1864                                       block size: block encryption algorithm */
1865   Sa_ipsecNatTInfo_t natTInfo;     /**< Specify the IPSEC NAT-T parameters, if natTInfo is present*/
1866   Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
1867 } salldIpsecEspTxRxInfo_t;
1869 /**
1870  * @ingroup salld_api_structures
1871  * @brief Packet Descriptor structure
1872  *
1873  * The packet may consist of one or more segments.
1874  * Several assumptions regarding the data organization among these segment(s) were made, 
1875  * in compliance with requirements from the supported protocols. Below are a
1876  * list of assumptions imposed upon each packet with regard to their corresponding protocol. 
1877  *
1878  *  - IPSec
1879  *      -# [Transmit] Segment containing IP Header must reserve approx 32 bytes of buffer space at the 
1880  *          beginning of the segment, to allow insertion of ESP/AH header after the IP header. 
1881  *      -# [Transmit] Final segment containing IP Datagram must reserve approx 32 bytes of buffer space at the
1882  *          end of the segment, to allow insertion of ESP padding, ESP trailer and authentication tag. 
1883  *      -# [General] IP Header must be contiguous and in one segment. 
1884  *  - SRTP
1885  *      -# [Transmit] Final segment containing SRTP payload must reserve approx 16 bytes of buffer space at the
1886  *          end of the segment, to allow insertion of MKI and authentication tag. 
1887  *      -# [General] RTP Header must be contiguous in one segment. 
1888  *      -# [Receive] Total number of segments used to carry SRTP payload may not exceed 10.
1889  *  - Air Cipher
1890  *      -# No assumptions were made as data segments are untouched by the processing function. 
1891  *  - Data Mode
1892  *      -# No assumptions were made as data segments are untouched by the processing function. 
1893  *
1894  *  @note Elements in the packet descriptor structure may change, after each protocol specific processing. 
1895  */
1896 typedef struct {
1897   int32_t   size;             /**< packet length */
1898   uint16_t  payloadOffset;    /**< offset from base of the packet to the header
1899                                    of protocol per the following list:
1900                                    IPSEC ESP/AH: IP header
1901                                    IPSEC ESP(Output): ESP Header
1902                                    SRTP: RTP header
1903                                    SRTCP: RTCP header
1904                                    3GPP Air Ciphering: PDU header */
1905   uint16_t  payloadLen;       /**< length of the payload starting from payloadOffset to the end of the protocol */
1906   uint16_t  nSegments;        /**< number of segments */
1907   void**    segments;         /**< data segments */
1908   uint16_t *segUsedSizes;     /**< pointer to segment used size array */ 
1909   uint16_t *segAllocSizes;    /**< pointer to segment allocated size array */
1910 } Sa_PktDesc_t;               /* base class */
1912 /**
1913  * @ingroup salld_api_structures
1914  * @brief Packet Information structure
1915  *
1916  * Data structure defines the SALLD input/output packet formats  
1917  *
1918  */
1919 typedef struct {
1920   Sa_PktDesc_t pktDesc;         /**< Specify packet descriptor */
1921   uint16_t  validBitMap;        /**< Specify which parameters are vaild as defined at @ref SALLDPktInfoValidBits */
1922   uint16_t          pktErrCode; /**< Specify the error code of the received packet as defined at Sa_PktErr_t */
1923   Sa_SWInfo_t       swInfo;     /**< Specify the software information required by SA */
1924   Sa_CmdLabelInfo_t cmdlb;      /**< Specify the command label in data mode */
1925   Sa_PayloadInfo_t  payloadInfo;/**< Specify the payload information in data mode */
1926   Sa_ipsecNatTInfo_t natTInfo;  /**< Specify the IPSEC NAT-T parameters */
1927   Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
1928 } Sa_PktInfo_t;
1930 /**
1931  *  @defgroup SALLDSrtpKeyReqInfo  SALLD SRTP Key Request Info Control Bit Definitions
1932  *  @ingroup salld_api_constants
1933  *  @{
1934  *
1935  *  @name SRTP Key Request Info Control Bit Definitions
1936  *
1937  *  Bitmap definition of the ctrlBitfield in Sa_SrtpKeyRequest_t. 
1938  */ 
1939 /*@{*/
1940 /**
1941  *  @def  sa_SRTP_KEY_REQUEST_KEY_TYPE_MKI
1942  *        Control Info -- Set: MKI Key
1943  *                        Clear: From-To Key
1944  */
1945 #define sa_SRTP_KEY_REQUEST_KEY_TYPE_MKI      0x0001 
1946 /**
1947  *  @def  sa_SRTP_KEY_REQUEST_TX_KEY
1948  *        Control Info -- Request Tx key
1949  */
1950 #define sa_SRTP_KEY_REQUEST_TX_KEY            0x0002 
1951 /**
1952  *  @def  sa_SRTP_KEY_REQUEST_RX_KEY
1953  *        Control Info -- Request Rx key
1954  */
1955 #define sa_SRTP_KEY_REQUEST_RX_KEY            0x0004 
1956 /**
1957  *  @def  sa_SRTP_KEY_REQUEST_MKI_VALID
1958  *        Control Info -- MKI VALUE included
1959  */
1960 #define sa_SRTP_KEY_REQUEST_MKI_VALID         0x0008 
1962 /*@}*/
1963 /** @} */
1965 /**
1966  * @ingroup salld_api_structures
1967  * @brief SRTP Key Request structure
1968  *
1969  * Data structure defines the key request information for SRTP  
1970  *
1971  */
1972 typedef struct {
1973   uint16_t    ctrlBitfield;    /**< Specify the Key types and other control Information 
1974                                     as defined at @ref SALLDSrtpKeyReqInfo */
1975   uint32_t    mki;             /**< Specify the MKI value of the MKI keys */
1976 } Sa_SrtpKeyRequest_t;
1978 /**
1979  * @ingroup salld_api_structures
1980  * @brief Key Request structure
1981  *
1982  * Data structure defines the key request information for all supported protocols  
1983  *
1984  */
1985 typedef struct {
1986   union {
1987     Sa_SrtpKeyRequest_t   srtp;  /**< Specify the key request parameters for SRTP */
1988   } params;                      /**< Contain the protocol-specific key request information */
1989 } Sa_KeyRequest_t; 
1991 /**
1992  * @ingroup salld_api_structures
1993  * @brief Security Context Request Information structure
1994  *
1995  * SASS is equipped with context cache module to auto-fetch security context 
1996  * from external memory. This module is essential to allow any number of simultaneous 
1997  * security connections by caching only limited (64) contexts on-chip and fetching other 
1998  * contexts as and when required for processing.
1999  *
2000  * In order to facilitate fast retrieval for performance critical connections such as IPSEC channels, 
2001  * context cache module allows two tier of security connections. First tier has permanent 
2002  * residence within Context cache RAM for fast retrieval and is never evicted automatically 
2003  * by context cache module. Second tier connections are kept as long as space is available within 
2004  * context cache RAM; new fetch request may automatically evict the context of the second tier connections  
2005  * into external memory to allow free space.
2006  *
2007  * The following data structure defines the parameters for the security context request.
2008  * The 15-bit security context ID, of which LSB 4-bits act as cache set select, and 
2009  * its corresponding context buffer, which contains the protocol-specific security parameters 
2010  * used by the LLD and sub-engines within SA, should be maintained across multiple DSP cores. 
2011  * They are multi-core resources and should be managed by the application.   
2012  *
2013  * The security context IDs and buffers can be managed across mult-cores or be pre-allocated for 
2014  * each core or each security channel. The security context buffer should be 16-byte aligned at least 
2015  * and it should be cache-line aligned if it is allocated at cacheable memory. It is recommended to 
2016  * maintain the security context buffers in the following three lists:
2017  *
2018  *  @verbatim 
2019     Allocated: The buffer and its corresponding ID have been allocated to the SA
2020                LLD through *ScAlloc API and they are owned by SA.
2021     Pending Free: The buffer and its corresponding ID has been released from the 
2022                   SA LLD through *ScFree API. However, they are still owned by 
2023                   SA until the security context tear-down procedure is complete.
2024                   The API Sa_isScBufFree should be used to check 
2025                   whether the buffer is free
2026     Free: The buffer and its corresonding ID are owned by the application.
2027     @endverbatim
2028  *
2029  *  @note There are only up to three first tier contexts allowed for each cache set.
2030  * 
2031  *  @note It is highly recommended to place the security context buffers at non-cacheable memory 
2032  *        since they are accessed and maintained by the SA sub-system primarily
2033  *
2034  *  @note The application can manage the security context buffers and IDs as
2035  *        two seperate resources or a single resource pair. The only
2036  *        requirement is that the security context ID cannot be re-used until
2037  *        its corresponding security context buffer is free.
2038  *        The application may perform periodic checks to move buffers from the
2039  *        Pending Free list to the Free list or perform checks only when new
2040  *        buffers are requested by the SA LLD.    
2041  */
2042 typedef struct {
2043   uint16_t    scSize; /**< Specify the size of the required security context */                        
2044   uint16_t    scID;   /**< Security Context ID specified by the application */
2045   uintptr_t   scBuf;  /**< Security Context Buffer provided by the application
2046                           (16-byte alignment required) */
2047 } Sa_ScReqInfo_t;
2049 /**
2050  *  @def  sa_SC_ID_MASK
2051  *        Define security context ID mask.
2052  */
2053 #define sa_SC_ID_MASK                  0x7FFF
2055 /**
2056  *  @def  sa_SC_IND_PERMANENT
2057  *        Indicate that the corresponding security context is permanent
2058  */
2059 #define sa_SC_IND_PERMANENT            0x8000
2062 /**
2063  *  @defgroup  saScMaxSize Security Context maximum size requirements
2064  *  @ingroup salld_api_constants
2065  *  @{
2066  *
2067  *  @name Security Context maximum size
2068  *
2069  *  Define Security Context maximum size requirements.
2070  */
2071 /* @{ */
2073 /**
2074  *  @def  sa_IPSEC_TX_MAX_SC_SIZE
2075  *        The maximum security context size required for IPSEC Tx channel
2076  */
2077 #define sa_IPSEC_TX_MAX_SC_SIZE         288
2080 /**
2081  *  @def  sa_IPSEC_RX_MAX_SC_SIZE
2082  *        The maximum security context size required for IPSEC Rx channel
2083  *
2084  *  Note: The maxmium IPSEC Rx channel security context includes the extra 128 bytes used by 
2085  *        large replay window when the replay window size exceeds 128.
2086  */
2087 #define sa_IPSEC_RX_MAX_SC_SIZE         448
2088 #define sa_IPSEC_RX_MAX_SC_SIZE_SM_REPLAY_WINDOW         320
2090 /**
2091  *  @def  sa_SRTP_TX_MAX_SC_SIZE
2092  *        The maximum security context size required for SRTP Tx channel
2093  */
2094 #define sa_SRTP_TX_MAX_SC_SIZE          224
2097 /**
2098  *  @def  sa_SRTP_RX_MAX_SC_SIZE
2099  *        The maximum security context size required for SRTP Rx channel
2100  */
2101 #define sa_SRTP_RX_MAX_SC_SIZE          288
2103 /**
2104  *  @def  sa_AC_MAX_SC_SIZE
2105  *        The maximum security context size required for Air Ciphering channel
2106  */
2107 #define sa_AC_MAX_SC_SIZE               288
2109 /**
2110  *  @def  sa_DATA_MODE_MAX_SC_SIZE
2111  *        The maximum security context size required for Data Mode channel
2112  */
2113 #define sa_DATA_MODE_MAX_SC_SIZE        256
2115 /**
2116  *  @def  sa_MAX_SC_SIZE
2117  *        Define the maxmium size of the security context buffer defined at @ref Sa_ScReqInfo_t.
2118  */
2119 #define sa_MAX_SC_SIZE                  448   
2121 /* @} */  
2122 /** @} */
2124 /**
2125  *  @ingroup salld_api_constants
2126  *  @brief   Define the maxmium replay window size supported by SASS. 
2127  */
2128 #define sa_MAX_REPLAY_WINDOW_SIZE       1024
2129 #define sa_MAX_REPLAY_WINDOW_SIZE_GEN1  128      /* first generation SASS */
2130 #define sa_MAX_REPLAY_WINDOW_SIZE_GEN2  1024     /* second generation SASS */
2132 /**
2133  * @ingroup salld_api_structures
2134  * @brief SALLD Replay Window Context
2135  *
2136  * This structure defines the replay window context which reprenets the snapshot of
2137  * SASS replay windows.
2138  */
2140 typedef struct Sa_Replay_Cxt_tag
2142     uint32_t  winMask[sa_MAX_REPLAY_WINDOW_SIZE/32];    /**< Bitmask Array:w0.b0, w0.b1, ... w1.b0, w0.b2 ...
2143                                                              1:packet received  
2144                                                              0:packet not received*/
2145     uint32_t  winBaseHi;                                /**< Upper 32-bit of win_base when ESN is enabled */
2146     uint32_t  winBase;                                  /**< Lower 32-bit of win_base which represents the sequence number of
2147                                                              the oldest packet received */
2148 } Sa_Replay_Cxt_t; 
2150 /**
2151  *  @defgroup SALLDStatsCtrlBit  SALLD Statistics Query Control Bit Definitions
2152  *  @ingroup salld_api_constants
2153  *  @{
2154  *
2155  *  @name SALLD Statistics Query Control Bit Definitions
2156  *  Bitmap definition of the control flags in Sa_chanGetStats() API. 
2157  */ 
2158 /*@{*/
2159 /**
2160  *  @def  sa_STATS_QUERY_FLAG_CLEAR
2161  *        Control Info -- Clear some statistics after they are reported
2162  */
2163 #define sa_STATS_QUERY_FLAG_CLEAR           0x0001 
2164 /**
2165  *  @def  sa_STATS_QUERY_FLAG_TRIG
2166  *        Control Info -- Inform the SA Sub-system to provide statistics
2167  */
2168 #define sa_STATS_QUERY_FLAG_TRIG            0x0002 
2169 /**
2170  *  @def  sa_STATS_QUERY_FLAG_NOW
2171  *        Control Info -- Request the SA LLD to provide the latest available statistics
2172  *        If the bit is not set, the SA LLD will return sa_ERR_STATS_UNAVAIL if the 
2173  *        latest statistics is not available
2174  */
2175 #define sa_STATS_QUERY_FLAG_NOW             0x0004 
2176 /*@}*/
2177 /** @} */
2179 /**
2180  * @ingroup salld_api_structures
2181  * @brief SALLD SRTP Statistics Structure
2182  *
2183  * This structure defines the SRTP-specific statistics provided upon request
2184  * with salldChanStats().
2185  */
2186 typedef struct {
2187   uint32_t   replayOld;     /**< Number of replay failures with old packets */
2188   uint32_t   replayDup;     /**< Number of replay failures with duplicated packets */
2189   uint32_t   authFail;      /**< Number of Authentication failures */
2190   uint32_t   txROC;         /**< Tx Roll-over Counter (32-bits) */
2191   uint32_t   rxROC;         /**< RX Roll-Over Counter (32 bits) */
2192   uint16_t   txRekey;       /**< Number of times re-keying happened in Tx */
2193   uint16_t   rxRekey;       /**< Number of times re-keying happened in Rx */
2194   uint16_t   pktEncHi;      /**< Total Number of Packets encrypted with this key (48-bits) Upper 16 bits */
2195   uint32_t   pktEncLo;      /**< Total Number of Packets encrypted with this key (48-bits) Lower 32 bits */
2196   uint16_t   pktDecHi;      /**< Total Number of Packets decrypted with this key (48-bits) Upper 16 bits */
2197   uint32_t   pktDecLo;      /**< Total Number of Packets decrypted with this key (48-bits) Lower 32 bits */
2198 } Sa_SrtpStats_t;
2200 /**
2201  * @ingroup salld_api_structures
2202  * @brief SALLD SRTCP Statistics Structure
2203  *
2204  * This structure defines the SRTCP-specific statistics provided upon request
2205  * with salldChanStats().
2206  */
2207 typedef struct {
2208   uint32_t   replayOld;     /**< Number of replay failures with old packets */
2209   uint32_t   replayDup;     /**< Number of replay failures with duplicated packets */
2210   uint32_t   authFail;      /**< Number of Authentication failures */
2211   uint16_t   txRekey;       /**< Number of times re-keying happened in Tx */
2212   uint16_t   rxRekey;       /**< Number of times re-keying happened in Rx */
2213   uint32_t   pktEnc;        /**< Total Number of Packets encrypted with this key (32-bits) */
2214   uint32_t   pktDec;        /**< Total Number of Packets decrypted with this key (32-bits) */
2215 } Sa_SrtcpStats_t;
2217 /**
2218  * @ingroup salld_api_structures
2219  * @brief SALLD IPSEC Statistics Structure
2220  *
2221  * This structure defines the IPSEC-specific statistics provided upon request
2222  * with salldChanStats().
2223  */
2224 typedef struct {
2225   Sa_Replay_Cxt_t replayCxt;   /**< Snapshot of the replay context */ 
2226   uint32_t   replayOld;     /**< Number of replay failures with old packets */
2227   uint32_t   replayDup;     /**< Number of replay failures with duplicated packets */
2228   uint32_t   authFail;      /**< Number of Authentication failures */
2229   uint32_t   txRollover;    /**< Number of Tx packets dropped due to rollover error, i.e. the sequence number exceed its limit (0xFFFFFFFF) */
2230   uint32_t   txESN;         /**< Tx ESN (32-bits) */
2231   uint32_t   txSN;          /**< Sequence Number (32-bits) of the last transmitted packet */
2232   uint32_t   rxESN;         /**< RX ESN (32 bits) */
2233   uint32_t   pktEncHi;      /**< Total Number of Packets encrypted with this key (64-bits) Upper 32 bits */
2234   uint32_t   pktEncLo;      /**< Total Number of Packets encrypted with this key (64-bits) Lower 32 bits */
2235   uint32_t   pktDecHi;      /**< Total Number of Packets decrypted with this key (64-bits) Upper 32 bits */
2236   uint32_t   pktDecLo;      /**< Total Number of Packets decrypted with this key (64-bits) Lower 32 bits */
2237   uint32_t   txByteCountHi; /**< Total bytes processed by SA on TX (64-bits) Upper 32 bits */
2238   uint32_t   txByteCountLo; /**< Total bytes processed by SA on TX (64-bits) Lower 32 bits */
2239   uint32_t   rxByteCountHi; /**< Total bytes processed by SA on RX (64-bits) Upper 32 bits */
2240   uint32_t   rxByteCountLo; /**< Total bytes processed by SA on RX (64-bits) Lower 32 bits */
2241 } Sa_IpsecStats_t;
2243 /**
2244  * @ingroup salld_api_structures
2245  * @brief SALLD Air Ciphering Statistics Structure
2246  *
2247  * This structure defines the Air Ciphering-specific statistics provided upon request
2248  * with salldChanStats().
2249  */
2250 typedef struct {
2251   uint32_t   authFail;      /**< Number of Authentication failures */
2252   uint32_t   toAirCountC;   /**< To-Air Count-C (32-bits) */
2253   uint32_t   fromAirCountC; /**< From-Air Count-C (32-bits) */ 
2254   uint32_t   pktToAirHi;    /**< Total Number of To-Air Packets (64-bits) Upper 32 bits */
2255   uint32_t   pktToAirLo;    /**< Total Number of To-Air Packets (64-bits) Lower 32 bits */
2256   uint32_t   pktFromAirHi;  /**< Total Number of From-Air Packets (64-bits) Upper 32 bits */
2257   uint32_t   pktFromAirLo;  /**< Total Number of From-Air Packets (64-bits) Lower 32 bits */
2258 } Sa_AcStats_t;
2260 /**
2261  * @ingroup salld_api_structures
2262  * @brief SALLD Data Mode Statistics Structure
2263  *
2264  * This structure defines the Data Mode statistics provided upon request
2265  * with salldChanStats().
2266  */
2267 typedef struct {
2268   uint32_t   pktHi;         /**< Total Number of processed Packets (64-bits) Upper 32 bits */
2269   uint32_t   pktLo;         /**< Total Number of processed Packets (64-bits) Lower 32 bits */
2270 } Sa_DataModeStats_t;
2272 /**
2273  * @ingroup salld_api_structures
2274  * @brief SALLD Statistics Structure
2275  *
2276  * This structure defines the protocol-specific statistics provided upon request
2277  * with salld_chanGetStats().
2278  */
2279 typedef union {
2280   Sa_SrtpStats_t      srtp;   /**< SRTP-specific channel statistics */
2281   Sa_SrtcpStats_t     srtcp;  /**< SRTCP-specific channel statistics */
2282   Sa_IpsecStats_t     ipsec;  /**< IPSEC-specific channel statistics */
2283   Sa_AcStats_t        ac;     /**< 3GPP Air Ciphering-specific channel statistics */
2284   Sa_DataModeStats_t  data;   /**< Data Mode channel statistics */
2285 } Sa_Stats_t; 
2287 /**
2288  * @ingroup salld_api_structures
2289  * @brief Specification of Sa_Handle 
2290  * The Sa_Handle is used to identify a SALLD system instance
2291  */
2292 typedef void* Sa_Handle;
2294 /**
2295  *  @defgroup saConfigCtrlBit SA Configuration Control Bit Definitions
2296  *  @ingroup salld_api_constants
2297  *  @{
2298  *
2299  *  @name SA Configuration Control Bit Definitions
2300  *
2301  *  Bitmap definition of the ctrlBitMap in Sa_Config_t. 
2302  *  
2303  */ 
2304 /*@{*/
2305 /**
2306  *  @def  sa_CONFIG_CTRL_BITMAP_TRIGGER_SYS_ERR_HALT
2307  *        Control Info -- 0:Disable trigger PDSP halt during system errors  (refer to @ref appendix3)
2308  *                        1:Enables trigger PDSP halt during system errors  (for Debug Purpose only).  
2309  */
2311 #define  sa_CONFIG_CTRL_BITMAP_TRIGGER_SYS_ERR_HALT            0x0001
2313 /**
2314  *  @def  sa_CONFIG_CTRL_BITMAP_TRIGGER_PKT_INFO_LOG
2315  *        Control Info -- 0:Disable internal internal packet information data collection (refer to @ref appendix3) 
2316  *                        1:Enables internal internal packet information data collection (for Debug Purpose only)
2317  *
2318  *  @note This control bit is applicable to Air Cipher channels only. This fetaure should not be enabled if there might be
2319  *        both Air Cipher and SRTP channels. This feature bit is not supported for C6678 device.
2320  */
2322 #define  sa_CONFIG_CTRL_BITMAP_TRIGGER_PKT_INFO_LOG           0x0002
2324 /**
2325  *  @def  sa_CONFIG_CTRL_BITMAP_SET_SCPTR_RANGE
2326  *        Control Info -- 0:Disable setting of security context pointer range limit set
2327  *                        1:Enables security context pointer range limit set
2328  *
2329  *  @note This control bit is applicable to SA2UL only (for other generations it is don't care). 
2330  *        For SA2UL promote (packet from non secure to secure operations), the security context range needs to be
2331  *        set in SCPTR_Promote_Range registers
2332  */
2334 #define  sa_CONFIG_CTRL_BITMAP_SET_SCPTR_RANGE                0x0004
2336 /**
2337  *  @def  sa_CONFIG_CTRL_BITMAP_LIMIT_ACCESS
2338  *        Control Info -- 0: All SA2UL registers may be accessed
2339  *                        1: Limit access to SA2UL registers which are reserved
2340  *                           for use by DMSC firmware
2341  *
2342  *  @note This control bit is applicable to SA2UL only (for other generations it is don't care).
2343  *        It is furthermore only necessary on High Secure (HS) device variants
2344  *        when an application wishes to share access to the SA2UL instance which
2345  *        is owned by DMSC firmware. DMSC prohibits read/write access to MMRA
2346  *        region on this instance, so this bit has the following effect:
2347  *
2348  *        * Bypasses programming ENGINE_ENABLE register. DMSC sets all engines
2349  *          to enabled at device boot. The driver can confirm engine status
2350  *          through the ENGINE_STATUS register.
2351  *
2352  *        * Ignores the SET_SCPTR_RANGE control flag and bypasses any attempt to
2353  *          access the SCPTR promote registers
2354  */
2356 #define  sa_CONFIG_CTRL_BITMAP_LIMIT_ACCESS                   0x0008
2360 /*@}*/
2361 /** @} */
2363 /**
2364  *  @ingroup salld_api_structures
2365  *  @brief   The SALLD Call-out function table
2366  *
2367  *  The SALLD software module requires a set of call-out functions to report debug information,
2368  *  request and free system resources, and etc. All the call-out functions should be implemented
2369  *  by the application and provided to the SALLD at @ref Sa_create
2370  *          
2371  */
2372 typedef struct Sa_CallOutFuns_s {
2374 /**
2375  *  @brief  A callout to the system code's debug and exception handling function.  This is a function
2376  *  pointer and must point to a valid function which meets the API requirements.    
2377  *
2378  *  @param[in]   handle       SALLD channel instance identifier.
2379  *  @param[in]   msgType      Specify how serious the debug message is as defined at @ref salldDebugMessageTypes.
2380  *  @param[in]   msgCode      Specify the message code as defined at @ref salldDebugMessageCodes.
2381  *  @param[in]   msgLength    Specify the length of the message supporting data.
2382  *  @param[in]   msgData      Pointer to the message supporting data.
2383  */
2384    void  (*DebugTrace) (Sa_ChanHandle handle, uint16_t msgType, uint16_t msgCode, 
2385                         uint16_t msgLength, uint16_t *msgData);
2386 /**                      
2387  *  @brief  Callout to externally supplied system to request a new security key. This function may be triggered
2388  *  by either the Sa_chanSendData() or Sa_chanReceiveData() APIs. The application should call the 
2389  *  Sa_chanControl() API to pass the new key when it is available.
2390  *  This is a function pointer and must point to a valid function which meets the API requirements.
2391  *
2392  *  @param[in]   handle       SALLD channel instance identifier.
2393  *  @param[in]   keyReq       Pointer to SALLD key Request structure.
2394  *
2395  *  @sa Sa_KeyRequest_t
2396  *
2397  */
2398    void (*ChanKeyRequest) (Sa_ChanHandle handle, Sa_KeyRequest_t* keyReq);
2399    
2400 /**
2401  *  @brief  Callout to externally supplied system to allocate the security context with the specified size.
2402  *  This function must be implemented as a simple non-blocking function.
2403  *  This is a function pointer and must point to a valid function which meets the API requirements.
2404  *
2405  *  @param[in]   handle       SALLD channel instance identifier.
2406  *  @param[in]   scReqInfo    Pointer to SALLD security context Request Information structure.
2407  *
2408  *  @sa Sa_ScReqInfo_t
2409  *
2410  *  @note:Both the base address and size of the security context buffer should be cache-line and csche-line size 
2411  *        aligned if it is allocated at cacheable memory, otherwise, the base address should be 16-byte aligned.
2412  *        It is highly recommended to place the security context buffers at non-cacheable memory 
2413  *        since they are accessed and maintained by the SA sub-system primarily
2414  */
2415    void (*ScAlloc) (Sa_ChanHandle handle, Sa_ScReqInfo_t* scReqInfo);
2416    
2417 /**
2418  *  @brief  Callout to externally supplied system to release the security context with the specified ID.
2419  *  This function must be implemented as a simple non-blocking function.
2420  *  This is a function pointer and must point to a valid function which meets the API requirements.
2421  *
2422  *  @param[in]   handle       SALLD channel instance identifier.
2423  *  @param[in]   scID         Security Context ID
2424  *
2425  *  @note The security context buffer is only released from the SA LLD and is still owned by SA.
2426  *        It should be maintained at the Pending Free list until it is freed by SA.
2427  *        Use API @ref Sa_isScBufFree() to check its status.
2428  *
2429  */
2430    void (*ScFree) (Sa_ChanHandle handle, uint16_t scID);
2431    
2432 /**
2433  *  @brief  Callout to externally supplied system to register the security channel with its software
2434  *  routing information to be programmed into the PASS lookup table in the from-Network direction. 
2435  *  It may be triggered by the Sa_chanControl(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2436  *  This is a function pointer and must point to a valid function which meets the API requirements.
2437  *
2438  *  @param[in]   handle       SALLD channel instance identifier.
2439  *  @param[in]   chanSwInfo   Pointer to SALLD software routing information structure.
2440  *
2441  *  @sa Sa_SWInfo_t
2442  *
2443  */
2444    void (*ChanRegister) (Sa_ChanHandle handle, Sa_SWInfo_t* chanSwInfo);
2446 /**
2447  *  @brief  Callout to externally supplied system to un-register the security channel with its software
2448  *  routing information to be removed from the PASS lookup tables. It may be triggered by 
2449  *  the sSa_chanClose(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2450  *  This is a function pointer and must point to a valid function which meets the API requirements.
2451  *
2452  *  @param[in]   handle       SALLD channel instance identifier.
2453  *  @param[in]   chanSwInfo   Pointer to SALLD software routing information structure.
2454  *
2455  *  @sa Sa_SWInfo_t
2456  *
2457  */
2458    void (*ChanUnRegister) (Sa_ChanHandle handle, Sa_SWInfo_t* chanSwInfo);
2459    
2460 /**
2461  *  @brief  Callout to externally supplied system to send an Null packet to the SA sub-system.
2462  *  The null packet is used to evict and/or tear down the security context associated with the channel. 
2463  *  It may be triggered by the Sa_chanClose(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2464  *  This is a function pointer and must point to a valid function which meets the API requirements.
2465  *
2466  *  @param[in]   handle       SALLD channel instance identifier.
2467  *  @param[in]   pktInfo      Pointer to the packet info structure.
2468  *
2469  *  @sa Sa_PktInfo_t
2470  *
2471  */
2472    void (*ChanSendNullPkt) (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo);
2473    
2474 } Sa_CallOutFuncs_t;
2476 /**
2477  * @ingroup salld_api_structures
2478  * @brief  SA Size Configuration Structure
2479  *
2480  * @details The module is configured at run time with a maximum number of channels supported. 
2481  */
2482 typedef struct  {
2483   uint16_t nMaxChan;       /**< Maximum number of channels supported */
2484   int      cacheLineSize;  /**< Specify the size of cache line of the memory where the system buffer will reside 
2485                                 @note cacheLineSize should be the larger of cache line sizes amoung mixed processors */
2486   uint16_t ctrlBitMap;     /**< Various configuration information as specified at @ref saSizeConfigCtrlBit */                                   
2487 } Sa_SizeCfg_t;
2489 /**
2490  * @ingroup salld_api_structures
2491  * @brief  SA Security Context Range Structure for promote operations
2492  *
2493  * @details for SA2UL promote operations, the range register needs to be set with correct address ranges 
2494  */
2495 typedef struct  {
2496   uint32_t           scPtrPromoteLowRangeL; /**< The lower 32-bits of SCPTR lower limit (must be 4KB aligned) */
2497   uint32_t           scPtrPromoteLowRangeH; /**< The upper 16-bits of SCPTR lower limit */
2498   uint32_t           scPtrPromoteHighRangeL; /**< The lower 32-bits of SCPTR upper limit (must be 4KB aligned) */
2499   uint32_t           scPtrPromoteHighRangeH; /**< The upper 16-bits of SCPTR upper limit */
2500 } Sa_ScPtrRangeCfg_t;
2502 /**
2503  *      @defgroup saEngSelMode SA Engine Selector Algorithms
2504  *      @ingroup        salld_api_constants
2505  *      @{
2506  *
2507  *      @name   SA Engine Selector Algorithms
2508  *      
2509  *      There are two sets of IPSEC processing engines at the second generation SASS. 
2510  *  During SA initialization, user may configure IPSEC processing engine set
2511  *      selection algorithm to be used during channel creation by setting the variable 
2512  *      engSelMode to the following values:
2513  *
2514  * - 0 (Load balanced)
2515  *  -# SA will select the set of engines with lower channel utility
2516  * - 1 (Channel-based Round Robin selection)
2517  *  -# SA will use each set of engines interleaved in order for each channel created 
2518  * - 2 (User Select)
2519  *  -# User will specify engine set to use when creating new channel
2520  */
2521  /*@{*/
2523 typedef enum {
2524     sa_EngSelMode_LOADBALANCED = 0,
2525     sa_EngSelMode_ROUNDROBIN,
2526     sa_EngSelMode_USERSPECIFIED
2527 } Sa_EngSelMode_e;
2528 /*@}*/
2529 /** @} */
2531 /**
2532  * @ingroup salld_api_structures
2533  * @brief SALLD Configuration structure
2534  *
2535  * Data structure providing configuration information in @ref Sa_create()
2536  * 
2537  */
2538 typedef struct {
2539   uint32_t           ID;          /**< User specified module ID */
2540   uint32_t           baseAddr;    /**< Specify the SASS base address */
2541   Sa_CallOutFuncs_t  *callTable;  /**< Pointer to call-out function Table */
2542   Sa_EngSelMode_e    engSelMode;  /**< User specified authentication/encryption 
2543                                        engine set selection mode */
2544   void*              intBuf;      /**< Pointer to an arbitrary internal buffer of at least @ref sa_MAX_SC_SIZE bytes 
2545                                        for temporary key storage during air ciphering security 
2546                                        context construction, The buffer needs an alignment of 4 bytes */
2547   Sa_SizeCfg_t      *sizeConfig;  /**< SALLD memory allocation requirement structure */
2548   void              *instPoolBaseAddr; /**< Base address of the global shared memory pool from which global 
2549                                             LLD instance & channel instance memory is allocated.*/ 
2550   void              *scPoolBaseAddr;   /**< Base address of the global shared memory pool from which SA
2551                                              security context memory is allocated. This is a DMA-able memory */
2552   Sa_ScPtrRangeCfg_t scPtrRange;      /**< Security Context Buffer Range low and high address configuration */
2553   uint32_t           ctrlBitMap;      /**< Various configuration information as specified at @ref saConfigCtrlBit */                                                
2554 } Sa_Config_t;
2556 /** 
2557 * @ingroup salld_api_structures 
2558 * @brief SALLD SRTP System Statistics Structure 
2559
2560 * This structure defines the SRTP-specific system statistics provided upon request 
2561 * with Sa_getSysStats(). 
2562 */ 
2563 typedef struct { 
2564   uint32_t  replayOld;          /**< Number of replay failures with old packets */ 
2565   uint32_t  replayDup;          /**< Number of replay failures with duplicated packets */ 
2566   uint32_t  authFail;           /**< Number of Authentication failures */ 
2567   uint32_t  pktEncHi;           /**< Total Number of Packets encrypted Upper 32 bits */ 
2568   uint32_t  pktEncLo;           /**< Total Number of Packets encrypted Lower 32 bits */ 
2569   uint32_t  pktDecHi;           /**< Total Number of Packets decrypted Upper 32 bits */ 
2570   uint32_t  pktDecLo;           /**< Total Number of Packets decrypted Lower 32 bits */ 
2571 } Sa_SrtpSysStats_t; 
2573 /** 
2574 * @ingroup salld_api_structures 
2575 * @brief SALLD IPSEC System Statistics Structure 
2576
2577 * This structure defines the IPSEC-specific system statistics provided upon request 
2578 * with Sa_getSysStats(). 
2579 */ 
2580 typedef struct { 
2581   uint32_t  replayOld;          /**< Number of replay failures with old packets */ 
2582   uint32_t  replayDup;          /**< Number of replay failures with duplicated packets */ 
2583   uint32_t  authFail;           /**< Number of Authentication failures */ 
2584   uint32_t  pktEncHi;           /**< Total Number of Packets encrypted Upper 32 bits */ 
2585   uint32_t  pktEncLo;           /**< Total Number of Packets encrypted Lower 32 bits */ 
2586   uint32_t  pktDecHi;           /**< Total Number of Packets decrypted Upper 32 bits */ 
2587   uint32_t  pktDecLo;           /**< Total Number of Packets decrypted Lower 32 bits */ 
2588 } Sa_IpsecSysStats_t; 
2590 /** 
2591 * @ingroup salld_api_structures 
2592 * @brief SALLD Air Ciphering System Statistics Structure 
2593
2594 * This structure defines the Air Ciphering-specific systrem statistics provided upon request 
2595 * with Sa_getSysStats(). 
2596 */ 
2597 typedef struct { 
2598   uint32_t  authFail;           /**< Number of Authentication failures */ 
2599   uint32_t  pktToAirHi;         /**< Total Number of To-Air Packets Upper 32 bits */ 
2600   uint32_t  pktToAirLo;         /**< Total Number of To-Air Packets Lower 32 bits */ 
2601   uint32_t  pktFromAirHi;       /**< Total Number of From-Air Packets Upper 32 bits */ 
2602   uint32_t  pktFromAirLo;       /**< Total Number of From-Air Packets Lower 32 bits */ 
2603 } Sa_AcSysStats_t; 
2605 /** 
2606 * @ingroup salld_api_structures 
2607 * @brief SALLD Error System Statistics Structure 
2608
2609 * This structure defines the SA error system statistics provided upon request 
2610 * with Sa_getSysStats(). 
2611  */
2612 typedef struct {
2613   uint32_t   errNoMem;      /**< Number of packets dropped due to lack of PDSP instance memory */
2614   uint32_t   errCtx;        /**< Number of packets dropped due to security context error */
2615   uint32_t   errEngine;     /**< Number of packets dropped due to SA processing engine error */
2616   uint32_t   errProto;      /**< Number of packets dropped due to protocol error such as inavlid IP version */
2617 } Sa_ErrorSysStats_t; 
2619 /** 
2620 * @ingroup salld_api_structures 
2621 * @brief SALLD Statistics Structure 
2622
2623 * This structure defines the system statistics provided upon request 
2624 * with @ref Sa_getSysStats(). 
2625 */ 
2626 typedef struct Sa_SysStats_s { 
2627   Sa_ErrorSysStats_t    err;    /**< System Error statistics */ 
2628   Sa_IpsecSysStats_t    esp;    /**< IPSEC(ESP)-specific system statistics */ 
2629   Sa_IpsecSysStats_t    ah;     /**< IPSEC(AH)-specific system statistics */ 
2630   Sa_SrtpSysStats_t     srtp;   /**< SRTP-specific system statistics */ 
2631   Sa_AcSysStats_t       ac;     /**< 3GPP Air Ciphering-specific system statistics */ 
2632 } Sa_SysStats_t; 
2634 /**
2635  *  @defgroup PkaOpTypes PKA Arithmetic Operation Types
2636  *  @ingroup salld_api_constants
2637  *  @{
2638  *
2639  *  @name PKA Arithmetic Operation Types
2640  *
2641  *  Definition of PKA Arithmetic Operation Types
2642  *  Parameter operation of @ref Sa_PkaReqInfo_t and @ref Sa_PkaReqInfo2_t should be set 
2643  *  to one of these types.
2644  */ 
2645 /*@{*/
2646 typedef enum {
2647   /**
2648    * List of PKA basic operations supported by both NSS PKA Gen1 and Gen2 devices.
2649    */
2650   sa_PKA_OP_ADD = 0,     /**< Large Vector Addition (A+B)*/
2651   sa_PKA_OP_SUB,         /**< Large Vector Subtraction (A-B)*/
2652   sa_PKA_OP_MUL,         /**< Large Vector Mutiplication (A*B)*/
2653   sa_PKA_OP_DIV,         /**< Large Vector Division (A/B)*/
2654   sa_PKA_OP_RSHIFT,      /**< Large Vector Shift Right (A>>shiftval) */
2655   sa_PKA_OP_LSHIFT,      /**< Large Vector Shift Left (A<<shiftval)*/
2656   sa_PKA_OP_COMP,        /**< Large Vector Comparison (A?B)*/
2657   sa_PKA_OP_COPY,        /**< Large Vector Copy (A->C)*/
2658   sa_PKA_OP_EXP2,        /**< Large Vector Exponentiation (Cexp(A)mod(B))(2-bit ACT) (NSS PKA Gen1 only) */
2659   sa_PKA_OP_EXP4,        /**< Large Vector Exponentiation (Cexp(A)mod(B))(4-bit ACT) (NSS PKA Gen1 only) */
2660   sa_PKA_OP_ADD_SUB,     /**< Large Vector Addition plus Substraction (A+C-B) (NSS PKA Gen2 only) */
2661   sa_PKA_OP_MOD,         /**< Large Vector Modulo (A%B) (NSS PKA Gen2 only) */
2662   /**
2663    * List of PKA complex operations supported by NSS PKA Gen2 devices only.
2664    */
2665   sa_PKA_OP_MODEXP,         /**< Large Vector Modular Exponentiation: M**E(mod N) */
2666   sa_PKA_OP_MODEXP_CRT,     /**< Large Vector Modular Exponentiation: CRT CRTpq(Mp**Dp (mod p), Mq**Dq (mod q), qInv) */
2667   sa_PKA_OP_MODINVp,        /**< Large Vector Modular Inversion (prime): (1/Z) (mod N) */
2668   sa_PKA_OP_MODINV2m,       /**< Large Vector Modular Inversion (binary): (1/Z) (mod N) */
2669   sa_PKA_OP_ECp_ADD,        /**< Large Vector Point Add on a Prime Field Curve: 
2670                              *   P1_xyx + P2_xyx ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) */ 
2671   sa_PKA_OP_ECp_MUL,        /**< Large Vector Point Multiply on a Prime Field Curve: 
2672                              *   k*P1_xyx ==> P0_xyz  with P1_z = 1, on prime curve y**2=x**3+ax+b (mod p) */
2673   sa_PKA_OP_ECp_SCALE,      /**< Large Vector Point Scale on a Prime Field Curve: 
2674                              *   P1_xyx ==> P0_xyz with P0_z = 1, on prime curve y**2=x**3+ax+b (mod p) */
2675   sa_PKA_OP_ECp_MUL_SACLE,  /**< Large Vector Point Multiply following by Scale on a Prime Field Curve: 
2676                              *   k*P1_xyx ==> P0_xyz  with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p) */
2677   sa_PKA_OP_EC2m_ADD,       /**< Large Vector Point Add on a Binary Field Curve: 
2678                              *   P1_xyx + P2_xyx ==> P0_xyz, on binary curve y**2=x**3 + ax + b (mod p) */ 
2679   sa_PKA_OP_EC2m_MUL,       /**< Large Vector Point Multiply on a Binary Field Curve: 
2680                              *   k*P1_xyx ==> P0_xyz  with P1_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
2681   sa_PKA_OP_EC2m_SCALE,     /**< Large Vector Point Scale on a Binary Field Curve: 
2682                              *   P1_xyx ==> P0_xyz with P0_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
2683   sa_PKA_OP_EC2m_MUL_SACLE, /**< Large Vector Point Multiply following by Scale on a Binary Field Curve: 
2684                              *   k*P1_xyx ==> P0_xyz  with P1_z = 1 and P0_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
2685   sa_PKA_OP_ECp_DSA_SIGN,   /**< Large Vector ECDSA sign operation on a Prime Field Curve: 
2686                              *   k*P1_xyx ==> P0_xyz  with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p)
2687                              *   r = P0x mod N, s = 1/k * (h + rd) mod N where h = hash(m)n, d = private key 
2688                              */
2689   sa_PKA_OP_ECp_DSA_VERIFY   /**< Large Vector ECDSA verify operation on a Prime Field Curve:
2690                              *   u1*P1_xyx + u2 * Y ==> P0_xyz  with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p)
2691                              *   u1 = h * w(mod N) and u2 = r * w mod N where where w = 1/s * mod N, h = hash(m)n, Y = public key
2692                              */
2693 } Sa_PkaOpTypes_t;
2694 /*@}*/
2695 /** @} */
2697 /**
2698  *  @defgroup PkaOpStatusCodes PKA Complex Operation Status Codes
2699  *  @ingroup salld_api_constants
2700  *  @{
2701  *
2702  *  @name PKA Complex Operation Status Codes
2703  *
2704  *  Status codes returned by PKA module for complex operation.
2705  */
2706 /*@{*/
2707 /**
2708  *  @def  sa_PKA_OP_STATUS_SUCCESS
2709  *        PKA Complex Operation executed successfully
2710  */
2711 #define sa_PKA_OP_STATUS_SUCCESS                0x01  
2712 /**
2713  *  @def  sa_PKA_OP_STATUS_PARAM_EVEN
2714  *        Error: Modulus or Prime polynomial is even
2715  */
2716 #define sa_PKA_OP_STATUS_PARAM_EVEN             0x03 
2717 /**
2718  *  @def  sa_PKA_OP_STATUS_PARAM_ZERO
2719  *        Error: Exponent or Multiplier k is zero
2720  */
2721 #define sa_PKA_OP_STATUS_PARAM_ZERO             0x05 
2722 /**
2723  *  @def  sa_PKA_OP_STATUS_PARAM_SHORT
2724  *        Error: Modulus is too short
2725  */
2726 #define sa_PKA_OP_STATUS_PARAM_SHORT            0x07
2727 /**
2728  *  @def  sa_PKA_OP_STATUS_PARAM_ONE
2729  *        Error: Exponent or Multiplier k is one
2730  */
2731 #define sa_PKA_OP_STATUS_PARAM_ONE              0x09 
2732 /**
2733  *  @def  sa_PKA_OP_STATUS_INFINITY
2734  *        Result is "at-infinity" (Z=0, not an error if 
2735  *         the scalar 'k' was the curve's order)
2736  */
2737 #define sa_PKA_OP_STATUS_INFINITY               0x0D 
2738 /**
2739  *  @def  sa_PKA_OP_STATUS_ERR_INFINITY
2740  *        Error: An intermediate result of ECpMUL was "at-infinity"
2741  */
2742 #define sa_PKA_OP_STATUS_ERR_INFINITY           0x0F 
2743 /**
2744  *  @def  sa_PKA_OP_STATUS_NO_INVERSE
2745  *        Error: No inverse exist
2746  */
2747 #define sa_PKA_OP_STATUS_NO_INVERSE             0x17
2749 /*@}*/
2750 /** @} */
2753 /**
2754  *  @defgroup PkaCompResults PKA Comparison Results
2755  *  @ingroup salld_api_constants
2756  *  @{
2757  *
2758  *  @name PKA Comparison Results
2759  *
2760  *  Definition of PKA Comparsion Result from SALLD API @ref Sa_pkaOperation
2761  */ 
2762 /*@{*/
2763 typedef enum {
2764   sa_PKA_COMP_AEQB  = 1,     /**< A=B */
2765   sa_PKA_COMP_AINFB = 2,     /**< A<B */
2766   sa_PKA_COMP_ASUPB = 4      /**< A>B */
2767 } Sa_PkaCompResults_t;
2768 /*@}*/
2769 /** @} */
2771 /*
2772  *  @ingroup salld_api_constants
2773  *  @brief   Define the maxmium sizes of the PKA operands in 32-bit words.
2774  */
2775 #define sa_MAX_PKA_OPERAND_SIZE_GEN1      128  /**< General Operations 4k-bits or 128 32-bit words */ 
2776 #define sa_MAX_PKA_OPERAND_SIZE_EXP4       64  /**< EXP4 operation: 2k-bits or 64 32-bit words */ 
2778 #define sa_MAX_PKA_OPERAND_SIZE_GEN2      130  /**< General operations 4160 bits or 130 32-bit words */
2779 #define sa_MAX_PKA_OPERAND_SIZE_ECp        24  /**< Prime Curve related operations: 24 32-bit words */ 
2780 #define sa_MAX_PKA_OPERAND_SIZE_EC2m       18  /**< Binary Curve related operations:18 32-bit words */ 
2782 #ifdef NSS_PKA_GEN2
2783 #define sa_MAX_PKA_OPERAND_SIZE     sa_MAX_PKA_OPERAND_SIZE_GEN2
2784 #else
2785 #define sa_MAX_PKA_OPERAND_SIZE     sa_MAX_PKA_OPERAND_SIZE_GEN1
2786 #endif
2787  
2788 /**
2789  * @ingroup salld_api_structures
2790  * @brief SALLD PKA Operation Request Structure
2791  *
2792  * This structure defines PKA request information which is used to perform the large 
2793  * vector arithmetic operations.
2794  *
2795  * @par  
2796  *        
2797  * Restrictions of input parameters:
2798  *  - Add: 0 < Alength, Blength <= Max Len (128)
2799  *  - Subtract:0 < Alength, Blength <= Max Len (128); Aoperand >= Boperand
2800  *  - Multiply: 0 < Alength, Blength <= Max Len (128)
2801  *  - Divide:
2802  *    - Alength, Blength > 1
2803  *    - Alength >= Blength
2804  *    - Most significant word of Boperand can not be zero
2805  *  - Right/Left Shift: 0 < Alength <= Max Len (128)
2806  *  - Compare:  0 < Alength, Blength <= Max Len (128); Alength = Blength
2807  *  - Copy:  0 < Alength <= Max Len (128)
2808  *  - Exponentitation (2-bit/4-bit ACT):
2809  *    - Alength > 0
2810  *    - Blength > 1
2811  *    - Blength >= Alength
2812  *    - Aoperand cannot be zero
2813  *    - Coperand cannot be zero
2814  *    - Boperand is odd (least significant bit set to 1)
2815  *    - Most significant word of Boperand can not be zero
2816  *    - Boperand > Coperand
2817  */
2818 typedef struct {
2819   Sa_PkaOpTypes_t     operation;     /**< Specify the arithmetic operation as defined at salldPkaOpTypes_t */
2820   Sa_PkaCompResults_t cmpResult;     /**< Store the comparsion result  */
2821   uint16_t            numShiftBits;  /**< Specify number of bits in shift operation */
2822   uint16_t            oprandSize[2]; /**< Specify the size of operands (A, B(C))in 32-bit words */
2823   uint16_t            resultSize;    /**< Specify the size of result in 32-bit words */
2824   uint16_t            remSize;       /**< Specify the size of reminder in 32-bit words */
2825   uint32_t*           oprandPtr[3];  /**< Pointers to up to 3 operand (A,B and C) buffers*/
2826   uint32_t*           remPtr;        /**< Pointer to the buffer to store the reminder */
2827   uint32_t*           resultPtr;     /**< Pointer to the buffer to store the operation result */
2828 } Sa_PkaReqInfo_t; 
2830 /**
2831  * @ingroup salld_api_structures
2832  * @brief SALLD PKA Basic Operation Parameters Structure
2833  *
2834  * This structure defines the input and output parameters for PKA basic operations
2835  *
2836  * @par  
2837  *        
2838  * Restrictions of input parameters:
2839  *  - Add: 0 < ALen, BLen <= Max Len (130)
2840  *  - Subtract: 0 < ALen, BLen <= Max Len (130); A >= B
2841  *  - AddSub: 0 < ALen <= Max Len (130); (A+C) >= B; A, B, C all use ALen and BLen is ignored.
2842  *  - Multiply: 0 < ALen, BLen <= Max Len (130)
2843  *  - Divide and Modulo:
2844  *    - ALen, BLen > 1
2845  *    - ALen >= BLen
2846  *    - Most significant 32-bit word of B operand cannot be zero
2847  *  - Right/Left Shift: 0 < ALen <= Max Len (130)
2848  *  - Compare: 0 < ALen <= Max Len (130); Both A and B use ALen and BLen is ignored.
2849  *  - Copy: 0 < ALen <= Max Len (130)
2850  */
2851 typedef struct {
2852   uint32_t*           pA;            /**< Pointers to Aoperand in 32-bit word array */
2853   uint32_t*           pB;            /**< Pointers to Boperand in 32-bit word array */
2854   uint32_t*           pC;            /**< Pointers to Coperand in 32-bit word array */
2855   uint32_t            numShiftBits;  /**< Specify number of bits in shift operation */
2856   uint32_t*           pRem;          /**< Pointer to the 32-bit word buffer to store the reminder */
2857   uint32_t*           pResult;       /**< Pointer to the 32-bit word buffer to store the operation result */
2858   uint16_t            resultSize;    /**< Store the size of operation result in 32-bit words */
2859   uint16_t            remSize;       /**< Store the size of reminder in 32-bit words of Divide/Modulo operations*/
2860   Sa_PkaCompResults_t cmpResult;     /**< Store the comparison result  */
2861 } Sa_PkaBasicOpParams_t; 
2863 /**
2864  * @ingroup salld_api_structures
2865  * @brief SALLD PKA Modular Exponentiation Operation Parameters Structure
2866  *
2867  * This structure defines the input and output parameters of PKA Modular Exponentiation operation as
2868  * described with the following formula:
2869  *
2870  *      M**E(mod N) ==> R
2871  *      
2872  *      E: ALen
2873  *      M, N, R: BLen
2874  *
2875  * @par  
2876  *        
2877  * Restrictions of input parameters:
2878  *  - 0 < ALen <= Max Len (130)
2879  *  - 1 < BLen <= Max Len (130)
2880  *  - Modulus N must be odd (i.e. the least significant bit must be ONE)
2881  *  - Modulus N > 2**32
2882  *  - Base M < Modulus N
2883  *  - Number of pre-calculated odd powers to use >= 1
2884  *
2885  */
2886 typedef struct {
2887   uint32_t*           pE;            /**< Pointer to Exponent in 32-bit word array */
2888   uint32_t*           pN;            /**< Pointer to Modulus N in 32-bit word array */
2889   uint32_t*           pM;            /**< Pointer to Message (Base) M in 32-bit word array */
2890   uint32_t            numOddPowers;  /**< Specify number of pre-calculated odd powers to use */
2891   uint32_t*           pResult;       /**< Pointer to the 32-bit word buffer to store the operation result */
2892 } Sa_PkaModExpParams_t; 
2894 /**
2895  * @ingroup salld_api_structures
2896  * @brief SALLD PKA Modular Exponentiation CRT Operation Parameters Structure
2897  *
2898  * This structure defines the input and output parameters of PKA Modular Exponentiation CRT operation as
2899  * described with the following formula:
2900  *
2901  *      CRTpq(Mp**Dp mod p, Mq**Dq mod q, qInv) ==> R
2902  *      
2903  *      where Mp = M mod p, Mq = M mod q and CRTpq(a, b, qInv) = ((a-b)*qInv mod p)*q + b
2904  *      
2905  *      Dp, Dq: ALen
2906  *      p, q, qInv: BLen
2907  *      M, R: 2*Blen
2908  *
2909  * @par  
2910  *        
2911  * Restrictions of input parameters:
2912  *  - 0 < ALen <= Max Len (130)
2913  *  - 1 < BLen <= Max Len (130)
2914  *  - Modulus p and Modulus q must be odd (i.e. the least significant bit must be ONE)
2915  *  - Modulus p > Modulus q > 2**32
2916  *  - Modulus p and Modulus q must be co-prime (GCD(p,q) = 1)
2917  *  - TBD: 0 < Exp P < (Mod P - 1)
2918  *  - TBD: 0 < Exp Q < (Mod Q - 1)
2919  *  - (qInv * q) = 1 (mod p)
2920  *  - Base M < p*q
2921  *  - Number of pre-calculated odd powers to use >= 1
2922  *
2923  */
2924 typedef struct {
2925   uint32_t*           pDp;           /**< Pointer to Exponent mod p in 32-bit word array */
2926   uint32_t*           pDq;           /**< Pointer to Exponent mod q in 32-bit word array */
2927   uint32_t*           pModP;         /**< Pointer to Modulus p in 32-bit word array */
2928   uint32_t*           pModQ;         /**< Pointer to Modulus q in 32-bit word array */
2929   uint32_t*           pQInv;         /**< Pointer to Modulus qInv in 32-bit word array */
2930   uint32_t*           pM;            /**< Pointer to Message (Base) M in 32-bit word array */
2931   uint32_t            numOddPowers;  /**< Specify number of pre-calculated odd powers to use */
2932   uint32_t*           pResult;       /**< Pointer to the 32-bit word buffer to store the operation result */
2933 } Sa_PkaModExpCRTParams_t; 
2935 /**
2936  * @ingroup salld_api_structures
2937  * @brief SALLD PKA Modular Inversion Operation Parameters Structure
2938  *
2939  * This structure defines the input and output parameters of PKA Modular Inversion operation as
2940  * described with the following formula:
2941  *
2942  *      1/Z (mod N) ==> R
2943  *      
2944  *      Z: ALen
2945  *      N, R: BLen
2946  *
2947  * @par  
2948  *        
2949  * Restrictions of input parameters:
2950  *  - ModINVp: 0 < ALen <= Max Len (130)  
2951  *  - ModINVp: 0 < BLen <= Max Len (130)
2952  *  - ModINV2m: 0 < ALen <= 18
2953  *  - ModINV2m: 0 < BLen <= 18
2954  *  - ModINV2m: Z < Modulus N
2955  *  - Modulus N must be odd (i.e. the least significant bit must be ONE)
2956  *  - Modulus N should not be 1
2957  *  - The highest word of the modulus vector, as indicated by BLen, may not be zero.
2958  *
2959  */
2960 typedef struct {
2961   uint32_t*           pN;            /**< Pointer to Modulus N in 32-bit word array */
2962   uint32_t*           pZ;            /**< Pointer to operand Z in 32-bit word array */
2963   uint32_t*           pResult;       /**< Pointer to the 32-bit word buffer to store the operation result */
2964 } Sa_PkaModInvParams_t; 
2966 /**
2967  * @ingroup salld_api_structures
2968  * @brief SALLD PKA Field Curve Point Structure
2969  *
2970  * This structure specifies a point in projective format (X, Y, Z) on the Prime or Binary Field Curve used by 
2971  * ECp or EC2m related operations 
2972  *
2973  * Where the EC (Elliptic Curve) is represented as y**2=x**3 + ax + b (mod p) and 
2974  * point in affine format (x,y) = (X/Z, Y/Z).
2975  *       
2976  */
2977 typedef struct {
2978   uint32_t*           pX;       /**< Pointer to X in 32-bit word array */
2979   uint32_t*           pY;       /**< Pointer to Y in 32-bit word array */
2980   uint32_t*           pZ;       /**< Pointer to Z in 32-bit word array */
2981 } Sa_PkaECPoint_t; 
2983 /**
2984  * @ingroup salld_api_structures
2985  * @brief SALLD PKA Elliptic Curve (EC) Point Add Operation Parameters Structure
2986  *
2987  * This structure defines the input and output parameters of Point Add operation on a 
2988  * Prime (Binary) Field Curve as described below
2989  *
2990  *      P1_xyz + P2_xyz ==> P0_xyz, on prime  curve y**2=x**3+ax+b (mod p) or
2991  *                                     binary curve y**2+xy=x**3+ax**2+b (mod p)
2992  *      
2993  *      ALen: not used
2994  *      p, a, b, P1_x, P1_y, P1_z, P2_x, P2_y, P2_z, P0_x, P0_y, P0_z: BLen
2995  *
2996  * @par  
2997  *        
2998  * Restrictions of input parameters:
2999  *  - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3000  *  - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3001  *  - Binary Curve: Modulus p must be a prime
3002  *  - Prime Curve: Modulus p must be a prime > 2**63
3003  *  - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3004  *  - a < p and b < p
3005  *  - P1 and P2 must be on the curve
3006  */
3007 typedef struct {
3008   uint32_t*           pModP;    /**< Pointer to Modulus p in 32-bit word array */
3009   uint32_t*           pEcA;     /**< Pointer to EC curve parameter a in 32-bit word array */
3010   uint32_t*           pEcB;     /**< Pointer to EC curve parameter b in 32-bit word array */
3011   Sa_PkaECPoint_t     point1;   /**< Pointers to input point 1 (P1_xyz) */
3012   Sa_PkaECPoint_t     point2;   /**< Pointers to input point 2 (P2_xyz) */
3013   Sa_PkaECPoint_t     point0;   /**< Pointers to output point 0 (P0_xyz) */
3014 } Sa_PkaECAddParams_t; 
3016 /**
3017  * @ingroup salld_api_structures
3018  * @brief SALLD PKA Elliptic Curve (EC) Point Multiply Operation Parameters Structure
3019  *
3020  * This structure defines the input and output parameters of Point Multiply operation on a 
3021  * Prime (Binary) Field Curve as described below
3022  *
3023  *      k*P1_xyz ==> P0_xyz, on prime  curve y**2=x**3+ax+b (mod p) or     where P1_z = 1
3024  *                              binary curve y**2+xy=x**3+ax**2+b (mod p)
3025  *      k: Alen
3026  *      p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
3027  *
3028  *      c**2 = b (md p) on the binary curve
3029  *
3030  * @par  
3031  *        
3032  * Restrictions of input parameters:
3033  *  - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
3034  *  - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3035  *  - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
3036  *  - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3037  *  - Binary Curve: Modulus p must be a prime
3038  *  - Prime Curve: Modulus p must be a prime > 2**63
3039  *  - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3040  *  - a < p and b < p
3041  *  - P1 must be on the curve
3042  *  - 1 < k <= n, where n is the curve's order.
3043  */
3044 typedef struct {
3045   uint32_t*           pK;       /**< Pointer to parameter k in 32-bit word array */
3046   uint32_t*           pModP;    /**< Pointer to Modulus p in 32-bit word array */
3047   uint32_t*           pEcA;     /**< Pointer to EC curve parameter a in 32-bit word array */
3048   uint32_t*           pEcBC;    /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
3049   Sa_PkaECPoint_t     point1;   /**< Pointers to input point 1 (P1_xyz) */
3050   Sa_PkaECPoint_t     point0;   /**< Pointers to output point 0 (P0_xyz) */
3051 } Sa_PkaECMulParams_t; 
3053 /**
3054  * @ingroup salld_api_structures
3055  * @brief SALLD PKA Elliptic Curve (EC) Point Scale Operation Parameters Structure
3056  *
3057  * This structure defines the input and output parameters of Point Scale operation on a 
3058  * Prime (Binary) Field Curve as described below
3059  *
3060  *      P1_xyz ==> P0_xyz, on prime  curve y**2=x**3+ax+b (mod p) or     where P0_z = 1
3061  *                            binary curve y**2+xy=x**3+ax**2+b (mod p)
3062  *      Alen (not used)
3063  *      p, a, b, P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
3064  *
3065  * @par  
3066  *        
3067  * Restrictions of input parameters:
3068  *  - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3069  *  - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3070  *  - Binary Curve: Modulus p must be a prime
3071  *  - Prime Curve: Modulus p must be a prime > 2**63
3072  *  - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3073  *  - a < p and b < p
3074  *  - P1 must be on the curve
3075  */
3076 typedef struct {
3077   uint32_t*           pModP;        /**< Pointer to Modulus p in 32-bit word array */
3078   uint32_t*           pEcA;         /**< Pointer to equation parameter a in 32-bit word array */
3079   uint32_t*           pEcB;         /**< Pointer to equation parameter b in 32-bit word array */
3080   Sa_PkaECPoint_t     point1;       /**< Pointers to input point 1 (P1_xyz) */
3081   Sa_PkaECPoint_t     point0;       /**< Pointers to output point 0 (P0_xyz) */
3082 } Sa_PkaECScaleParams_t; 
3084 /**
3085  * @ingroup salld_api_structures
3086  * @brief SALLD PKA Elliptic Curve (EC) DSA Sign Operation Parameters Structure
3087  *
3088  * This structure defines the input and output parameters of DSA Sign operation on a 
3089  * Prime (Binary) Field Curve as described below
3090  *
3091  *      k*P1_xyz ==> P0_xyz, on prime  curve y**2=x**3+ax+b (mod p) or     where P1_z = 1
3092  *                              binary curve y**2+xy=x**3+ax**2+b (mod p)
3093  *      k: Alen
3094  *      p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
3095  *
3096  *      c**2 = b (md p) on the binary curve
3097  *
3098  *      N: multiplicative (integer) order of the point P1 means that n times P1 = O
3099  *      h: messgae hash truncated to n bit Hash(m)n
3100  *      d: private key
3101  *
3102  *      Output:
3103  *      r = P0x mod n;
3104  *      s = (1/k)(h + dr) mod N
3105  *
3106  * @par  
3107  *        
3108  * Restrictions of input parameters:
3109  *  - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
3110  *  - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3111  *  - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
3112  *  - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3113  *  - Binary Curve: Modulus p must be a prime
3114  *  - Prime Curve: Modulus p must be a prime > 2**63
3115  *  - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3116  *  - a < p and b < p
3117  *  - P1 must be on the curve
3118  *  - 1 < k <= n, where n is the curve's order.
3119  */
3120 typedef struct {
3121   uint32_t*           pK;       /**< Pointer to parameter k in 32-bit word array */
3122   uint32_t*           pModP;    /**< Pointer to Modulus p in 32-bit word array */
3123   uint32_t*           pEcA;     /**< Pointer to EC curve parameter a in 32-bit word array */
3124   uint32_t*           pEcBC;    /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
3125   uint32_t*           pN;       /**< Pointer to multiplicative (integer) order N in 32-bit word array */
3126   uint32_t*           pH;       /**< Pointer to hash data (h) in 32-bit word array */
3127   uint32_t*           pD;       /**< Pointer to private key (d) in 32-bit word array */
3128   Sa_PkaECPoint_t     point1;   /**< Pointers to input point 1 (P1_xyz) */
3129   uint32_t*           pR;       /**< Pointer to output parameter r in 32-bit word array */
3130   uint32_t*           pS;       /**< Pointer to output parameter s in 32-bit word array */
3131 } Sa_PkaECDSASignParams_t; 
3133 /**
3134  * @ingroup salld_api_structures
3135  * @brief SALLD PKA Elliptic Curve (EC) DSA Verify Operation Parameters Structure
3136  *
3137  * This structure defines the input and output parameters of ECDSA Verify operation on a
3138  * Prime (Binary) Field Curve as described below
3139  *
3140  *      k*P1_xyz ==> P0_xyz, on prime  curve y**2=x**3+ax+b (mod p) or     where P1_z = 1
3141  *                              binary curve y**2+xy=x**3+ax**2+b (mod p)
3142  *      k: Alen
3143  *      p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
3144  *
3145  *      c**2 = b (md p) on the binary curve
3146  *
3147  *      N: multiplicative (integer) order of the point P1 means that n times P1 = O
3148  *      h: messgae hash truncated to n bit Hash(m)n
3149  *      d: private key
3150  *
3151  *      Output:
3152  *      r = P0x mod n;
3153  *      s = (1/k)(h + dr) mod N
3154  *
3155  * @par
3156  *
3157  * Restrictions of input parameters:
3158  *  - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
3159  *  - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3160  *  - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
3161  *  - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3162  *  - Binary Curve: Modulus p must be a prime
3163  *  - Prime Curve: Modulus p must be a prime > 2**63
3164  *  - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3165  *  - a < p and b < p
3166  *  - P1 must be on the curve
3167  *  - 1 < k <= n, where n is the curve's order.
3168  */
3169 typedef struct {
3170   uint32_t*           pModP;    /**< Pointer to Modulus p in 32-bit word array */
3171   uint32_t*           pEcA;     /**< Pointer to EC curve parameter a in 32-bit word array */
3172   uint32_t*           pEcBC;    /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
3173   uint32_t*           pN;       /**< Pointer to multiplicative (integer) order N in 32-bit word array */
3174   uint32_t*           pH;       /**< Pointer to hash data (h) in 32-bit word array */
3175   Sa_PkaECPoint_t     pY;       /**< Pointer to public key (y) in 32-bit word array */
3176   Sa_PkaECPoint_t     point1;   /**< Pointers to input point 1 (P1_xyz) */
3177   uint32_t*           pR;       /**< Pointer to signature parameter r in 32-bit word array */
3178   uint32_t*           pS;       /**< Pointer to signature parameter s in 32-bit word array */
3179   uint32_t*           pRes;     /**< Pointer to output parameter Result (res) in 32-bit word array */
3180 } Sa_PkaECDSAVerifyParams_t;
3182 /**
3183  *  @defgroup PkaOpModes PKA Operation Modes
3184  *  @ingroup salld_api_constants
3185  *  @{
3186  *
3187  *  @name PKA Operation Modes
3188  *
3189  *  Definition of PKA Operation Modes
3190  *  Parameter mode of @ref Sa_PkaReqInfo2_t should be set to one of these modes.
3191  */ 
3192 /*@{*/
3193 typedef enum {
3194   /**
3195    *  The API Sa_pkaOperation2() operates in blocking mode. The API call will not return until all specified operations
3196    *  are completed or some error occurs.
3197    */
3198   sa_PKA_MODE_WAIT = 0,  
3199   
3200   /**
3201    *  The API Sa_pkaOperation2() operates in non-blocking mode. The API call will return immediately when the first PKA
3202    *  operation is triggered or some input error occurs. The application should invoke API @ref Sa_pkaPoll() periodically 
3203    *  until all specified PKA operations are completed or PKA error occurs. 
3204    * 
3205    */
3206   sa_PKA_MODE_POLL,      
3207   
3208   /**
3209    *  The API Sa_pkaOperation2 operates in non-blocking mode. The API call will return immediately when the first PKA
3210    *  operation is triggered or some input error occurs. The application should invoke API @ref Sa_pkaPoll() when
3211    *  PKA interrupt occurs until all specified PKA operations are completed or PKA error occurs. 
3212    * 
3213    */
3214   sa_PKA_MODE_INT      
3215   
3216 } Sa_PkaOpModes_t;
3217 /*@}*/
3218 /** @} */
3220 /**
3221  * @ingroup salld_api_structures
3222  * @brief SALLD PKA Operation Request Structure for second generation PKA module
3223  *
3224  * This structure defines PKA request information which is used to perform the basic 
3225  * and complex large vector arithmetic operations on the second generation PKA.
3226  *
3227  */
3228 typedef struct {
3229   Sa_PkaOpTypes_t     operation;        /**< Specify the arithmetic operation as defined at salldPkaOpTypes_t */
3230   Sa_PkaOpModes_t     mode;             /**< Specify the operation mode as defined at salldPkaOpModes_t */
3231   uint16_t            aLen;             /**< Specify the parameter ALen in 32-bit words */
3232   uint16_t            bLen;             /**< Specify the parameter BLen in 32-bit words */
3233   int                 statusCode;       /**< Status code of the complex operation as defined at PkaOpStatusCodes */
3234   union {
3235     Sa_PkaBasicOpParams_t   basicOp;    /**< Specify the input/output parameters for all basic PKA operations */
3236     Sa_PkaModExpParams_t    modExp;     /**< Specify the input/output parameters for modular exponentitation operation */
3237     Sa_PkaModExpCRTParams_t modExpCRT;  /**< Specify the input/output parameters for modular exponentitation CRT operation */
3238     Sa_PkaModInvParams_t    modInv;     /**< Specify the input/output parameters for modular inversion operation */
3239     Sa_PkaECAddParams_t     ecAdd;      /**< Specify the input/output parameters for EC point add operation */
3240     Sa_PkaECMulParams_t     ecMul;      /**< Specify the input/output parameters for EC point multiply operation */
3241     Sa_PkaECScaleParams_t   ecScale;    /**< Specify the input/output parameters for EC point scale operation */
3242     Sa_PkaECDSASignParams_t ecDSASign;  /**< Specify the input/output parameters for ECDSA Sign operation */
3243     Sa_PkaECDSAVerifyParams_t ecDSAVerify; /**< Specify the input/output parameters for ECDSA Sign operation */
3244   } params;                             /**< Specify the operation specific input/output parameters */
3245 } Sa_PkaReqInfo2_t; 
3247 /**
3248  *  @defgroup SALLDRngConfigCtrlInfo  SALLD RNG Configuration Control Info Bit Definitions
3249  *  @ingroup salld_api_constants
3250  *  @{
3251  *
3252  *  @name RNG Configuration Control Info Bit Definitions
3253  *
3254  *  Bitmap definition of the ctrlBitfield in @ref Sa_RngConfigParams_t. 
3255  */ 
3256 /*@{*/
3257 /**
3258  *  @def  sa_RNG_CTRL_REINIT
3259  *        Control Info -- Set: Force re-initialization
3260  *                        Clear: Perform initialization only if not actived
3261  */
3262 #define sa_RNG_CTRL_REINIT        0x0001 
3263 /**
3264  *  @def  sa_RNG_CTRL_ENABLE_INT
3265  *        Control Info -- Set: Interrupt mode
3266  *                        Clear: Poll mode 
3267  */
3268 #define sa_RNG_CTRL_ENABLE_INT    0x0002 
3269 /**
3270  *  @def  sa_RNG_CTRL_RESET
3271  *        Control Info -- Set: RNG reset
3272  */
3273 #define sa_RNG_CTRL_RESET         0x0004 
3275 /*@}*/
3278 /**
3279  *  @defgroup SALLDRng2ConfigCtrlInfo  SALLD RNG2 Configuration Control Info Bit Definitions
3280  *  @ingroup salld_api_constants
3281  *  @{
3282  *
3283  *  @name RNG2 Configuration Control Info Bit Definitions
3284  *
3285  *  Bitmap definition of the ctrlBitfield in @ref Sa_Rng2ConfigParams_t. 
3286  */ 
3287 /*@{*/
3288 /**
3289  *  @def  sa_RNG2_CTRL_REINIT
3290  *        Control Info -- Set: Force re-initialization
3291  *                        Clear: Perform initialization only if not actived
3292  */
3293 #define sa_RNG2_CTRL_REINIT        0x0001
3295 /**
3296  *  @def  sa_RNG_CTRL_RESET
3297  *        Control Info -- Set: RNG2 reset
3298  */
3299 #define sa_RNG2_CTRL_RESET         0x0002
3301 /**
3302  *  @def  sa_RNG2_CTRL_DRBG_USE
3303  *        Control Info -- Set: DRBG use for SA2UL
3304  *                        Clear: No DRBG for SA2UL
3305  */
3306 #define sa_RNG2_CTRL_DRBG_USE      0x0004
3308 /**
3309  *  @def  sa_RNG2_CTRL_DRBG_KNOWN_TESTS
3310  *        Control Info -- Set: DRBG use for SA2UL
3311  *                        Clear: No DRBG for SA2UL
3312  */
3313 #define sa_RNG2_CTRL_DRBG_KNOWN_TESTS      0x0008
3316 /*@}*/
3318 /** @} */
3320 /**
3321  * @ingroup salld_api_structures
3322  * @brief SALLD RNG Configuration Structure
3323  *
3324  * Data structure defines the RNG configuration related parameters
3325  *
3326  */
3327 typedef struct {
3328   uint16_t    ctrlBitfield;    /**< Specify the initialization mode and other control information as defined 
3329                                     at @ref SALLDRngConfigCtrlInfo */
3330   uint16_t    clockDiv;        /**< Specify the clock divider (1, 16) 0: default */                                  
3331   uint32_t    startupCycles;   /**< Specify the number of clock cycles (2**8, 2**24) to start up
3332                                     the random number generator initially(0:default) */ 
3333   uint32_t    minRefillCycles; /**< Specify the minimum number of clock cycles (2**6, 2**14) to generate
3334                                     the next random number (0:default) */ 
3335   uint32_t    maxRefillCycles; /**< Specify the maximum number of clock cycles (2**8, 2**24) to generate
3336                                     the next random number (0:default) */
3337 } Sa_RngConfigParams_t;
3339 /**
3340  * @ingroup salld_api_structures
3341  * @brief SALLD RNG2 Configuration Structure
3342  *
3343  * Data structure defines the RNG2 configuration related parameters
3344  *
3345  */
3346 typedef struct {
3347     uint16_t    ctrlBitfield;    /**< Specify the initialization mode and other control information as defined 
3348                                       at @ref SALLDRng2ConfigCtrlInfo */
3349     uint16_t    clockDiv;        /**< Specify the clock divider (1, 16) 0: default */
3350     uint32_t    sampleCycles;    /**< Sets the number of FRO samples that are XOR-ed together into one bit 
3351                                       to be shifted into the main shift register.
3352                                       This value must be such that there is at least one bit of entropy (in total)
3353                                       in each 8 bits that are shifted. 
3354                                       Note: Value 0 in this field selects 65536 FRO samples to be XOR-ed together */
3355     uint32_t   pStringLen;            /** < Personalization string length in 32-bit words (valid values 1 thorugh 12) */
3356     uint32_t   pStringData[sa_MAX_PS_AI_WORD_COUNT]; /** < Personalization String and Additional Input for SP-800-90A
3357                                                      AES-256 DRBG (valid when DRBG is enabled */
3359 } Sa_Rng2ConfigParams_t;
3361 /**
3362  * @ingroup salld_api_structures
3363  * @brief SALLD RNG Output Structure
3364  *
3365  * This structure defines the random number output provided upon request
3366  * with @ref Sa_getRandomNum().
3367  */
3368 typedef struct {
3369   uint32_t   hi;         /**< Upper 32 bits of the lower 64-bit Random Number output */
3370   uint32_t   lo;         /**< Lower 32 bits of the lower 64-bit Random Number output */
3371 } Sa_RngData_t;
3373 /**
3374  * @ingroup salld_api_structures
3375  * @brief SALLD RNG2 Output Structure
3376  *
3377  * This structure defines the random number output provided upon request
3378  * with @ref Sa_getRandomNum2().
3379  */
3380 typedef struct {
3381   uint32_t   hihi;       /**< Upper 32 bits of the higher 64-bit Random Number output */
3382   uint32_t   hilo;       /**< Lower 32 bits of the higher 64-bit Random Number output */
3383   uint32_t   hi;         /**< Upper 32 bits of the lower 64-bit Random Number output */
3384   uint32_t   lo;         /**< Lower 32 bits of the lower 64-bit Random Number output */
3385 } Sa_Rng2Data_t;
3388 /**
3389  *  @ingroup salld_api_constants
3390  *  @brief   Define the maximum number of buffers the module (SALLD) can request
3391  *
3392  */
3393 #define sa_N_BUFS           1 
3394                           
3395 /**
3396  *  @defgroup  saBufIndex SA System Memory Buffer Index
3397  *  @ingroup salld_api_constants
3398  *  @{
3399  *
3400  *  @name   SA System Memory Buffer Index
3401  *  @brief  Define the buffer index of the SA system memory blocks.
3402  *
3403  */
3404 /* @{ */
3405 /**
3406  *  @def  sa_SYS_BUF_INST
3407  *        SA LLD system instance buffer
3408  */
3409 #define sa_SYS_BUF_INST         0
3411 /*  @}  */  
3412 /** @} */
3414 /** @name COMMON (Common Interface) APIs
3415  *  
3416  */
3417 /*@{*/
3418                            
3419 /**
3420  *  @ingroup salld_api_functions
3421  *  @brief Sa_getBufferReq returns the memory requirements for the SALLD instance.
3422  *
3423  *  @details This function returns the memory buffer requirements in terms of the size and 
3424  *           alignment array. The SA LLD requires only one memory block as described below:
3425  *           - SA Instance: SA instance data
3426  *
3427  *  @param[in]   sizeCfg     Size configuration information
3428  *  @param[out]  sizes       Array of size requirements
3429  *  @param[out]  aligns      Array of alignment requirements
3430  *  @retval                  Value @ref salldRetCodes
3431  *
3432  *  @sa Sa_SizeCfg_t
3433  */
3434 int16_t  Sa_getBufferReq (Sa_SizeCfg_t *sizeCfg, int sizes[], int aligns[]);
3436 /**
3437  *  @ingroup salld_api_functions
3438  *  @brief  Sa_create creates the SA LLD instance. It initializes the SALLD instance 
3439  *          and its corresponding instance structure based on channel configuration data
3440  *          such as the call-out table, and etc.
3441  *
3442  *  @param[in]  cfg     Configuration information
3443  *  @param[in]  bases   Array of the memory buffer base addresses 
3444  *  @param[out] pHandle Instance handle. This is a pointer to an initialized
3445  *                      instance structure. 
3446  *  @retval             Value @ref salldRetCodes
3447  *
3448  *  @sa Sa_Config_t
3449  *
3450  *  @note The system buffers should be allocated from global accessible memory blocks and global
3451  *        addresses should be used if the LLD instance is expected to be shared among multiple cores. 
3452  *
3453  */
3454 int16_t Sa_create (Sa_Config_t *cfg, void* bases[], Sa_Handle *pHandle);