git.sur5r.net Git - freertos/blob

   1 /*******************************************************************************\r
   2  * (c) Copyright 2012 Microsemi SoC Products Group.  All rights reserved.\r
   3  *\r
   4  * SmartFusion2 MSS System Services bare metal software driver public API.\r
   5  *\r
   6  * SVN $Revision: 5591 $\r
   7  * SVN $Date: 2013-04-04 15:55:11 +0100 (Thu, 04 Apr 2013) $\r
   8  */\r
   9 \r
  10 /*=========================================================================*//**\r
  11   @mainpage SmartFusion2 MSS System Services Bare Metal Driver.\r
  12 \r
  13   @section intro_sec Introduction\r
  14   The SmartFusion2 microcontroller subsystem (MSS) includes a communication\r
  15   block (COMM_BLK) allowing it to communicate with the SmartFusion2 System\r
  16   Controller. The SmartFusion2 System Controller performs a variety of system\r
  17   wide services. This software driver provides a set of functions to access\r
  18   these System Services. The driver can be adapted for use as part of an\r
  19   operating system, but the implementation of the adaptation layer between the\r
  20   driver and the operating system's driver model is outside the scope of the\r
  21   driver.\r
  22   \r
  23   @section hw_dependencies Hardware Flow Dependencies\r
  24   The MSS System Services driver does not require any configuration. It relies\r
  25   on the SmartFusion2 communication block (MSS_COMM_BLK) to communicate with the\r
  26   System Controller. The MSS_COMM_BLK is always enabled.\r
  27   The base address, register addresses and interrupt number assignment for the\r
  28   MSS_COMM_BLK are defined as constants in the SmartFusion2 CMSIS HAL. You must\r
  29   ensure that the latest SmartFusion2 CMSIS HAL is included in the project\r
  30   settings of the software tool chain used to build your project and that it is\r
  31   generated into your project.\r
  32   \r
  33   @section theory_op Theory of Operation\r
  34   The System Services driver provides access to the SmartFusion2 System\r
  35   Controller services. These system services are loosely grouped into the\r
  36   following features:\r
  37     - Reading system information\r
  38     - Cryptography\r
  39     - Non-deterministic random bit generator\r
  40     - Flash*Freeze\r
  41   Note: Refer to the function descriptions for further details about the\r
  42         features of each individual service.\r
  43 \r
  44   Reading System Information\r
  45   The System Services driver can be used to read information about the\r
  46   SmartFusion2 device and the design programmed into it using the following\r
  47   functions:\r
  48     - MSS_SYS_get_serial_number()\r
  49     - MSS_SYS_get_user_code()\r
  50     - MSS_SYS_get_design_version()\r
  51     - MSS_SYS_get_device_certificate()\r
  52     \r
  53   Cryptography Services\r
  54   The System Services driver provides cryptographic services using the following\r
  55   functions:\r
  56     - MSS_SYS_128bit_aes()\r
  57     - MSS_SYS_256bit_aes()\r
  58     - MSS_SYS_sha256()\r
  59     - MSS_SYS_hmac()\r
  60     \r
  61   Non-Deterministic Random Bit Generator\r
  62   The System Services driver provides random number generation services using\r
  63   the following functions:\r
  64     - MSS_SYS_nrbg_instantiate()\r
  65     - MSS_SYS_nrbg_self_test()\r
  66     - MSS_SYS_nrbg_generate()\r
  67     - MSS_SYS_nrbg_reseed()\r
  68     - MSS_SYS_nrbg_uninstantiate()\r
  69     \r
  70   Flash*Freeze\r
  71   The System Services driver can be used to request the system to enter\r
  72   Flash*Freeze mode using the following function:\r
  73     - MSS_SYS_flash_freeze()\r
  74     \r
  75  *//*=========================================================================*/\r
  76 \r
  77 #ifndef __MSS_SYS_SERVICES_H_\r
  78 #define __MSS_SYS_SERVICES_H_ 1\r
  79 \r
  80 #include "../../CMSIS/m2sxxx.h"\r
  81 \r
  82 #ifdef __cplusplus\r
  83 extern "C" {\r
  84 #endif\r
  85 \r
  86 /*==============================================================================\r
  87  * Status codes:\r
  88  */\r
  89 /*-------------------------------------------------------------------------*//**\r
  90   These constants are used by multiple services to communicate the outcome of a\r
  91   system services request. These status codes are used across all types of\r
  92   services.\r
  93   \r
  94   - MSS_SYS_SUCCESS:\r
  95       Indicates that the system services completed successfully. \r
  96       \r
  97   - MSS_SYS_UNEXPECTED_ERROR:\r
  98       Indicates that the system failed in an unexpected way.\r
  99       \r
 100   - MSS_SYS_MEM_ACCESS_ERROR:\r
 101       Indicates that the System Controller could not access the memory used to\r
 102       pass parameters to the System Controller or to return a service result to\r
 103       the Cortex-M3.\r
 104       \r
 105   - MSS_SYS_SERVICE_DISABLED_BY_FACTORY:\r
 106       Indicates that the requested system service is not available on the\r
 107       SmartFusion2 device.\r
 108       \r
 109   - MSS_SYS_SERVICE_DISABLED_BY_USER:\r
 110       Indicates that the requested system service has been disabled as part of\r
 111       the hardware design.\r
 112  */\r
 113 #define MSS_SYS_SUCCESS                         0u\r
 114 #define MSS_SYS_UNEXPECTED_ERROR                200u\r
 115 \r
 116 #define MSS_SYS_MEM_ACCESS_ERROR                127u\r
 117 #define MSS_SYS_SERVICE_DISABLED_BY_FACTORY     254u\r
 118 #define MSS_SYS_SERVICE_DISABLED_BY_USER        255u\r
 119 \r
 120 /*-------------------------------------------------------------------------*//**\r
 121  * Programming services specific status codes:\r
 122  */\r
 123 #define MSS_SYS_CHAINING_MISMATCH                   1u\r
 124 #define MSS_SYS_UNEXPECTED_DATA_RECEIVED            2u\r
 125 #define MSS_SYS_INVALID_ENCRYPTION_KEY              3u\r
 126 #define MSS_SYS_INVALID_COMPONENT_HEADER            4u\r
 127 #define MSS_SYS_BACK_LEVEL_NOT_SATISFIED            5u\r
 128 #define MSS_SYS_DSN_BINDING_MISMATCH                7u\r
 129 #define MSS_SYS_ILLEGAL_COMPONENT_SEQUENCE          8u\r
 130 #define MSS_SYS_INSUFFICIENT_DEV_CAPABILITIES       9u\r
 131 #define MSS_SYS_INCORRECT_DEVICE_ID                 10u\r
 132 #define MSS_SYS_UNSUPPORTED_BITSTREAM_PROT_VER      11u\r
 133 #define MSS_SYS_VERIFY_NOT_PERMITTED_ON_BITSTR      12u\r
 134 #define MSS_SYS_ABORT                               127u\r
 135 #define MSS_SYS_NVM_VERIFY_FAILED                   129u\r
 136 #define MSS_SYS_DEVICE_SECURITY_PROTECTED           130u\r
 137 #define MSS_SYS_PROGRAMMING_MODE_NOT_ENABLED        131u\r
 138 \r
 139 /*-------------------------------------------------------------------------*//**\r
 140   These constants are used to specify the event_opcode parameter for the\r
 141   event_handler() function registered with the MSS_SYS_init() function. They are\r
 142   used to specify which asynchronous event is notified to the Cortex-M3 software\r
 143   by the System Controller. Asynchronous events are sent by the System\r
 144   Controller to the Cortex-M3 when some system events of interest occur.\r
 145   \r
 146   - FLASH_FREEZE_SHUTDOWN_OPCODE:\r
 147       Indicates that the system is being shutdown as a result of entering the\r
 148       Flash*Freeze mode.\r
 149       \r
 150   - FLASH_FREEZE_EXIT_OPCODE:\r
 151       Indicates that the system is exiting Flash*Freeze mode.\r
 152  */\r
 153 #define FLASH_FREEZE_SHUTDOWN_OPCODE    0xE0u\r
 154 #define FLASH_FREEZE_EXIT_OPCODE        0xE1u\r
 155 \r
 156 /*-------------------------------------------------------------------------*//**\r
 157   These constants are used to specify the options parameter for the\r
 158   MSS_SYS_flash_freeze() function.\r
 159   \r
 160   - MSS_SYS_FPGA_POWER_DOWN:\r
 161       Indicates that the MSS_SYS_flash_freeze() function should request the FPGA\r
 162       fabric to enter Flash*Freeze mode.\r
 163       \r
 164   - MSS_SYS_ENVM0_POWER_DOWN:\r
 165       Indicates that the MSS_SYS_flash_freeze() function should request eNVM0 to\r
 166       enter Flash*Freeze mode.\r
 167       \r
 168   - MSS_SYS_ENVM1_POWER_DOWN:\r
 169       Indicates that the MSS_SYS_flash_freeze() function should request eNVM1 to\r
 170       enter Flash*Freeze mode.\r
 171       \r
 172   - MSS_SYS_MPLL_POWER_DOWN:\r
 173       Indicates that the MSS_SYS_flash_freeze() function should request the MSS\r
 174       PLL to enter Flash*Freeze mode.\r
 175  */\r
 176 #define MSS_SYS_FPGA_POWER_DOWN     0x00u\r
 177 #define MSS_SYS_ENVM0_POWER_DOWN    0x01u\r
 178 #define MSS_SYS_ENVM1_POWER_DOWN    0x02u\r
 179 #define MSS_SYS_MPLL_POWER_DOWN     0x04u\r
 180 \r
 181 /*-------------------------------------------------------------------------*//**\r
 182   These constants are used to specify the mode parameter for the\r
 183   MSS_SYS_128aes() and MSS_SYS_256bit_aes() functions.\r
 184   \r
 185   - MSS_SYS_ECB_ENCRYPT:\r
 186       Indicates that the cryptography function should perform encryption using\r
 187       the Electronic Codebook (ECB) mode.\r
 188       \r
 189   - MSS_SYS_ECB_DECRYPT:\r
 190       Indicates that the cryptography function should perform decryption using\r
 191       the Electronic Codebook (ECB) mode.\r
 192       \r
 193   - MSS_SYS_CBC_ENCRYPT:\r
 194       Indicates that the cryptography function should perform encryption using\r
 195       the Cipher-Block Chaining (CBC) mode.\r
 196       \r
 197   - MSS_SYS_CBC_DECRYPT:\r
 198       Indicates that the cryptography function should perform decryption using\r
 199       the Cipher-Block Chaining (CBC) mode.\r
 200       \r
 201   - MSS_SYS_OFB_ENCRYPT:\r
 202       Indicates that the cryptography function should perform encryption using\r
 203       the Output Feedback (OFB) mode.\r
 204       \r
 205   - MSS_SYS_OFB_DECRYPT:\r
 206       Indicates that the cryptography function should perform decryption using\r
 207       the Output Feedback (OFB) mode.\r
 208       \r
 209   - MSS_SYS_CTR_ENCRYPT:\r
 210       Indicates that the cryptography function should perform encryption using\r
 211       the Counter (CTR) mode.\r
 212       \r
 213   - MSS_SYS_CTR_DECRYPT:\r
 214       Indicates that the cryptography function should perform decryption using\r
 215       the Counter (CTR) mode.\r
 216  */\r
 217 #define MSS_SYS_ECB_ENCRYPT     0x00u\r
 218 #define MSS_SYS_ECB_DECRYPT     0x80u\r
 219 #define MSS_SYS_CBC_ENCRYPT     0x01u\r
 220 #define MSS_SYS_CBC_DECRYPT     0x81u\r
 221 #define MSS_SYS_OFB_ENCRYPT     0x02u\r
 222 #define MSS_SYS_OFB_DECRYPT     0x82u\r
 223 #define MSS_SYS_CTR_ENCRYPT     0x03u\r
 224 #define MSS_SYS_CTR_DECRYPT     0x83u\r
 225 \r
 226 /*------------------------------------------------------------------------------\r
 227   These constants are used by non deterministic random bit generator (NDRBG)\r
 228   services to communicate the outcome of a system services request. These status\r
 229   codes are only used by NDRBG services.\r
 230   \r
 231   - MSS_SYS_NRBG_CATASTROPHIC_ERROR:\r
 232       Indicates that a catastrophic error occurred. \r
 233       \r
 234   - MSS_SYS_NRBG_MAX_INST_EXCEEDED:\r
 235       Indicates that the maximum number of NDRBG instances has been exceeded.\r
 236       You need to release already instantiated NDRBG instances using the\r
 237       MSS_SYS_ndrbg_uninstantiate() function.\r
 238       \r
 239   - MSS_SYS_NRBG_INVALID_HANDLE:\r
 240       Indicates that the handle parameter has an invalid value.\r
 241       \r
 242   - MSS_SYS_NRBG_GEN_REQ_TOO_BIG:\r
 243       Indicates that the requested random number is too long. The requested\r
 244       length is larger than the maximum number of digits that can be generated.\r
 245       \r
 246   - MSS_SYS_NRBG_MAX_LENGTH_EXCEEDED:\r
 247       Indicates that the supplied additional data length is exceeded.\r
 248  */\r
 249 #define MSS_SYS_NRBG_CATASTROPHIC_ERROR     1u\r
 250 #define MSS_SYS_NRBG_MAX_INST_EXCEEDED      2u\r
 251 #define MSS_SYS_NRBG_INVALID_HANDLE         3u\r
 252 #define MSS_SYS_NRBG_GEN_REQ_TOO_BIG        4u\r
 253 #define MSS_SYS_NRBG_MAX_LENGTH_EXCEEDED    5u\r
 254 \r
 255 \r
 256 /*-------------------------------------------------------------------------*//**\r
 257   The sys_serv_async_event_handler_t typedef specifies the function prototype of\r
 258   an asynchronous event handler that can be registered with the System Services\r
 259   driver to handle asynchronous events. This is the prototype of a function can\r
 260   be optionally implemented by the application to handle asynchronous events\r
 261   such as Flash*Freeze shutdown and Flash*Freeze exit.\r
 262  */\r
 263 typedef void (*sys_serv_async_event_handler_t)(uint8_t event_opcode);\r
 264  \r
 265 /*-------------------------------------------------------------------------*//**\r
 266   This constant is used as parameter to the MSS_SYS_init() function to indicate\r
 267   that the application code does not supply an asynchronous event handler\r
 268   function.\r
 269  */\r
 270 #define MSS_SYS_NO_EVENT_HANDLER    ((sys_serv_async_event_handler_t)0)\r
 271 \r
 272 /*-------------------------------------------------------------------------*//**\r
 273   The MSS_SYS_init function initializes the system services communication with\r
 274   the System Controller.\r
 275    \r
 276   @param\r
 277     The event_handler parameter specifies an optional asynchronous event\r
 278     handler function. This event handler function is provided by the\r
 279     application. It will be called by the System Services driver whenever an\r
 280     asynchronous event is received from the SmartFusion2 System controller.\r
 281     This event handler is typically used to handle entry and exit of\r
 282     Flash*Freeze mode.\r
 283     \r
 284   @return\r
 285     This function does not return a value.\r
 286  */\r
 287 void MSS_SYS_init(sys_serv_async_event_handler_t event_handler);\r
 288 \r
 289 /*==============================================================================\r
 290  * Device and Design Information Services.\r
 291  */\r
 292  \r
 293 /*-------------------------------------------------------------------------*//**\r
 294   The MSS_SYS_get_serial_number function fetches the 128-bit Device Serial\r
 295   Number (DSN).\r
 296   \r
 297   @param p_serial_number\r
 298     The p_serial_number parameter is a pointer to the 16-bytes buffer where the\r
 299     serial number will be written by this system service.\r
 300   \r
 301   @return\r
 302     The MSS_SYS_get_serial_number function returns one of following status codes:\r
 303         - MSS_SYS_SUCCESS\r
 304         - MSS_SYS_MEM_ACCESS_ERROR\r
 305         - MSS_SYS_UNEXPECTED_ERROR\r
 306  */\r
 307 uint8_t MSS_SYS_get_serial_number\r
 308 (\r
 309     uint8_t * p_serial_number\r
 310 );\r
 311 \r
 312 /*-------------------------------------------------------------------------*//**\r
 313    The MSS_SYS_get_user_code functions fetches the 32-bit USERCODE.\r
 314   \r
 315   @param p_user_code\r
 316     The p_user_code parameter is a pointer to the 4-bytes buffer where the\r
 317     USERCODE will be written by this system service.\r
 318   \r
 319   @return\r
 320     The MSS_SYS_get_user_code function returns one of following status codes:\r
 321         - MSS_SYS_SUCCESS\r
 322         - MSS_SYS_MEM_ACCESS_ERROR\r
 323         - MSS_SYS_UNEXPECTED_ERROR\r
 324  */\r
 325 uint8_t MSS_SYS_get_user_code\r
 326 (\r
 327     uint8_t * p_user_code\r
 328 );\r
 329 \r
 330 /*-------------------------------------------------------------------------*//**\r
 331   The MSS_SYS_get_design_version function fetches the design version.\r
 332   \r
 333   @param p_design_version\r
 334     The p_design_version parameter is a pointer to the 2-bytes buffer where the\r
 335     design version will be written by this system service.\r
 336   \r
 337   @return\r
 338     The MSS_SYS_get_design_version function returns one of following status codes:\r
 339         - MSS_SYS_SUCCESS\r
 340         - MSS_SYS_MEM_ACCESS_ERROR\r
 341         - MSS_SYS_UNEXPECTED_ERROR\r
 342  */\r
 343 uint8_t MSS_SYS_get_design_version\r
 344 (\r
 345     uint8_t * p_design_version\r
 346 );\r
 347 \r
 348 /*-------------------------------------------------------------------------*//**\r
 349   The MSS_SYS_get_device_certificate function fetches the device certificate.\r
 350   \r
 351   @param p_device_certificate\r
 352     The p_device_certificate parameter is a pointer to the 512-bytes buffer\r
 353     where the device certificate will be written by this system service.\r
 354   \r
 355   @return\r
 356     The MSS_SYS_get_device_certificate function returns one of following status\r
 357     codes:\r
 358         - MSS_SYS_SUCCESS\r
 359         - MSS_SYS_MEM_ACCESS_ERROR\r
 360         - MSS_SYS_UNEXPECTED_ERROR\r
 361  */\r
 362 uint8_t MSS_SYS_get_device_certificate\r
 363 (\r
 364     uint8_t * p_device_certificate\r
 365 );\r
 366 \r
 367 /*-------------------------------------------------------------------------*//**\r
 368   The MSS_SYS_flash_freeze function requests the FPGA to enter the Flash*Freeze\r
 369   mode.\r
 370   \r
 371   @param options\r
 372     The options parameter can be used to power down additional parts of\r
 373     SmartFusion2 when the FPGA fabric enters Flash*Freeze mode. This parameter\r
 374     is a bit mask of the following options:\r
 375         - MSS_SYS_FPGA_POWER_DOWN\r
 376         - MSS_SYS_ENVM0_POWER_DOWN\r
 377         - MSS_SYS_ENVM1_POWER_DOWN\r
 378         - MSS_SYS_MPLL_POWER_DOWN\r
 379     MSS_SYS_FPGA_POWER_DOWN on its own will only power down the FPGA fabric.\r
 380     MSS_SYS_ENVM0_POWER_DOWN and MSS_SYS_ENVM1_POWER_DOWN specify that eNVM\r
 381     blocks 0 and 1 respectively should enter the deep power down state during\r
 382     Flash*Freeze.\r
 383     MSS_SYS_MPLL_POWER_DOWN specifies that the MSS PLL is powered down during\r
 384     the Flash*Freeze period.\r
 385     \r
 386   @return\r
 387     The MSS_SYS_flash_freeze function returns one of following status codes:\r
 388         - MSS_SYS_SUCCESS\r
 389         - MSS_SYS_MEM_ACCESS_ERROR\r
 390         - MSS_SYS_UNEXPECTED_ERROR\r
 391         \r
 392   The following example demonstrates how to request the FPGA fabric and both\r
 393   eNVM0 and eNVM1 to enter the Flash*Freeze mode:\r
 394   @code\r
 395     MSS_SYS_flash_freeze(MSS_SYS_FPGA_POWER_DOWN | MSS_SYS_ENVM0_POWER_DOWN | MSS_SYS_MPLL_POWER_DOWN);\r
 396   @endcode\r
 397  */\r
 398 uint8_t MSS_SYS_flash_freeze(uint8_t options);\r
 399 \r
 400 /*==============================================================================\r
 401  * Cryptographic Services.\r
 402  */\r
 403 \r
 404 /*-------------------------------------------------------------------------*//**\r
 405   The MSS_SYS_128bit_aes function provides access to the SmartFusion2 AES-128\r
 406   cryptography service.\r
 407   \r
 408   @param key\r
 409     The key parameter is a pointer to a 16-bytes array containing the key to use\r
 410     for the requested encryption/decryption operation.\r
 411   \r
 412   @param iv\r
 413     The iv parameter is a pointer to a 16-bytes array containing the\r
 414     intialization vector that will be used as part of the requested \r
 415     encryption/decryption operation. Its use is different depending on the mode.\r
 416         -----------------------------------------\r
 417         | Mode |             Usage              |\r
 418         -----------------------------------------\r
 419         | ECB  | Ignored.                       |\r
 420         -----------------------------------------\r
 421         | CBC  | Randomization.                 |\r
 422         -----------------------------------------\r
 423         | OFB  | Randomization.                 |\r
 424         -----------------------------------------\r
 425         | CTR  | Used as initial counter value. |\r
 426         -----------------------------------------\r
 427   \r
 428   @param nb_blocks\r
 429     The nb_blocks parameter specifies the number of 128-bit blocks of\r
 430     plaintext/ciphertext to be processed by the AES-128 system service.\r
 431   \r
 432   @param mode\r
 433     The mode parameter specifies the cipher mode of operation and whether the\r
 434     source text must be encrypted or decrypted. The modes of operation are:\r
 435         - Electronic Codebook (ECB)\r
 436         - Cipher-Block Chaining (CBC)\r
 437         - Output Feedback (OFB)\r
 438         - Counter (CTR)\r
 439     The CTR mode uses the content of the initialization vector as its intial\r
 440     counter value. The counter increment is 2^64.\r
 441     Allowed values for the mode parameter are:\r
 442         - MSS_SYS_ECB_ENCRYPT\r
 443         - MSS_SYS_ECB_DECRYPT\r
 444         - MSS_SYS_CBC_ENCRYPT\r
 445         - MSS_SYS_CBC_DECRYPT\r
 446         - MSS_SYS_OFB_ENCRYPT\r
 447         - MSS_SYS_OFB_DECRYPT\r
 448         - MSS_SYS_CTR_ENCRYPT\r
 449         - MSS_SYS_CTR_DECRYPT\r
 450     \r
 451   @param dest_addr\r
 452     The dest_addr parameter is a pointer to the memory buffer where the result\r
 453     of the encryption/decryption operation will be stored.\r
 454   \r
 455   @param src_addr\r
 456     The src_addr parameter is a pointer to the memory buffer containg the source\r
 457     plaintext/ciphertext to be encrypted/decrypted.\r
 458   \r
 459   @return\r
 460     The MSS_SYS_128bit_aes function returns one of following status codes:\r
 461         - MSS_SYS_SUCCESS\r
 462         - MSS_SYS_MEM_ACCESS_ERROR\r
 463         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 464  */\r
 465 uint8_t MSS_SYS_128bit_aes\r
 466 (\r
 467     const uint8_t * key,\r
 468     const uint8_t * iv,\r
 469     uint16_t nb_blocks,\r
 470     uint8_t mode,\r
 471     uint8_t * dest_addr,\r
 472     const uint8_t * src_addr\r
 473 );\r
 474 \r
 475 /*-------------------------------------------------------------------------*//**\r
 476   The MSS_SYS_256bit_aes function provides access to the SmartFusion2 AES-256\r
 477   cryptography service.\r
 478   \r
 479   @param key\r
 480     The key parameter is a pointer to a 32-bytes array containing the key to use\r
 481     for the requested encryption/decryption operation.\r
 482   \r
 483   @param iv\r
 484     The iv parameter is a pointer to a 16-bytes array containing the\r
 485     intialization vector that will be used as part of the requested \r
 486     encryption/decryption operation. Its use is different depending on the mode.\r
 487         -----------------------------------------\r
 488         | Mode |             Usage              |\r
 489         -----------------------------------------\r
 490         | ECB  | Ignored.                       |\r
 491         -----------------------------------------\r
 492         | CBC  | Randomization.                 |\r
 493         -----------------------------------------\r
 494         | OFB  | Randomization.                 |\r
 495         -----------------------------------------\r
 496         | CTR  | Used as initial counter value. |\r
 497         -----------------------------------------\r
 498   \r
 499   @param nb_blocks\r
 500     The nb_blocks parameter specifies the number of 128-bit blocks of\r
 501     plaintext/ciphertext requested to be processed by the AES-128 system service.\r
 502   \r
 503   @param mode\r
 504     The mode parameter specifies the cipher mode of operation and whether the\r
 505     source text must be encrypted or decrypted. The modes of operation are:\r
 506         - Electronic Codebook (ECB)\r
 507         - Cypher-Block Chaining (CBC)\r
 508         - Output Feedback (OFB)\r
 509         - Counter (CTR)\r
 510     The CTR mode uses the content of the initialization vector as its intial\r
 511     counter value. The counter increment is 2^64.\r
 512     Allowed values for the mode parameter are:\r
 513         - MSS_SYS_ECB_ENCRYPT\r
 514         - MSS_SYS_ECB_DECRYPT\r
 515         - MSS_SYS_CBC_ENCRYPT\r
 516         - MSS_SYS_CBC_DECRYPT\r
 517         - MSS_SYS_OFB_ENCRYPT\r
 518         - MSS_SYS_OFB_DECRYPT\r
 519         - MSS_SYS_CTR_ENCRYPT\r
 520         - MSS_SYS_CTR_DECRYPT\r
 521     \r
 522   @param dest_addr\r
 523     The dest_addr parameter is a pointer to the memory buffer where the result\r
 524     of the encryption/decryption operation will be stored.\r
 525   \r
 526   @param src_addr\r
 527     The src_addr parameter is a pointer to the memory buffer containg the source\r
 528     plaintext/ciphertext to be encrypted/decrypted.\r
 529   \r
 530   @return\r
 531     The MSS_SYS_256bit_aes function returns one of following status codes:\r
 532         - MSS_SYS_SUCCESS\r
 533         - MSS_SYS_MEM_ACCESS_ERROR\r
 534         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 535  */\r
 536 uint8_t MSS_SYS_256bit_aes\r
 537 ( \r
 538     const uint8_t * key,\r
 539     const uint8_t * iv,\r
 540     uint16_t nb_blocks,\r
 541     uint8_t mode,\r
 542     uint8_t * dest_addr,\r
 543     const uint8_t * src_addr\r
 544 );\r
 545 \r
 546 /*-------------------------------------------------------------------------*//**\r
 547   The MSS_SYS_sha256 function provides access to the SmartFusion2 SHA-256\r
 548   cryptography service.\r
 549   \r
 550   @param p_data_in\r
 551     The p_data_in parameter is a pointer to the memory location containing the\r
 552     data that will be hashed using the SHA-256 system service.\r
 553   \r
 554   @param length\r
 555     The length parameter specifies the length in bits of the data to hash.\r
 556   \r
 557   @param result\r
 558     The result parameter is a pointer to a 32 bytes buffer where the hash result\r
 559     will be stored.\r
 560   \r
 561   @return\r
 562     The MSS_SYS_sha256 function returns one of following status codes:\r
 563         - MSS_SYS_SUCCESS\r
 564         - MSS_SYS_MEM_ACCESS_ERROR\r
 565         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 566  */\r
 567 uint8_t MSS_SYS_sha256\r
 568 (\r
 569     const uint8_t * p_data_in,\r
 570     uint32_t length,\r
 571     uint8_t * result\r
 572 );\r
 573 \r
 574 /*-------------------------------------------------------------------------*//**\r
 575   The MSS_SYS_hmac function provides access to the SmartFusion2 HMAC\r
 576   cryptography service. The HMAC system service generates message authentication\r
 577   codes using the SHA-256 hash function.\r
 578   \r
 579   @param key\r
 580     The key parameter is a pointer to a 32 bytes array containing the key used\r
 581     to generate the message authentication code.\r
 582   \r
 583   @param p_data_in\r
 584     The p_data_in parameter is a pointer to the data to be authenticated.\r
 585   \r
 586   @param length\r
 587     The length parameter specifies the number of data bytes for which to generate\r
 588     the authentication code. It is the size of the data pointed to by the\r
 589     p_data_in parameter.\r
 590   \r
 591   @param p_result\r
 592     The p_result parameter is a pointer to a 32 bytes buffer where the\r
 593     authentication code generated by the HMAC system service will be stored.\r
 594   \r
 595   @return\r
 596     The MSS_SYS_hmac function returns one of following status codes:\r
 597         - MSS_SYS_SUCCESS\r
 598         - MSS_SYS_MEM_ACCESS_ERROR\r
 599         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 600  */\r
 601 uint8_t MSS_SYS_hmac\r
 602 (\r
 603     const uint8_t * key,\r
 604     const uint8_t * p_data_in,\r
 605     uint32_t length,\r
 606     uint8_t * p_result\r
 607 );\r
 608 \r
 609 /*==============================================================================\r
 610  * CRI Licensed Services.\r
 611  */\r
 612 #define SYS_SERVICE_NOT_LICENCED        243u\r
 613 \r
 614 /*==============================================================================\r
 615  * Non Deterministic Random Bit Generator Services.\r
 616  */\r
 617 /*-------------------------------------------------------------------------*//**\r
 618   The MSS_SYS_nrbg_self_test() function performs a self test of the\r
 619   non-deterministic random bit generator (NRBG).\r
 620   \r
 621   @return\r
 622     The MSS_SYS_nrbg_self_test function returns one of following status codes:\r
 623         - MSS_SYS_SUCCESS\r
 624         - MSS_SYS_NRBG_CATASTROPHIC_ERROR\r
 625         - MSS_SYS_NRBG_MAX_INST_EXCEEDED\r
 626         - MSS_SYS_NRBG_INVALID_HANDLE\r
 627         - MSS_SYS_NRBG_GEN_REQ_TOO_BIG\r
 628         - MSS_SYS_NRBG_MAX_LENGTH_EXCEEDED\r
 629         - MSS_SYS_SERVICE_DISABLED_BY_FACTORY\r
 630         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 631  */\r
 632 uint8_t MSS_SYS_nrbg_self_test(void);\r
 633 \r
 634 /*-------------------------------------------------------------------------*//**\r
 635   The MSS_SYS_nrbg_instantiate() function instantiates a non-deterministic\r
 636   random bit generator (NRBG) instance. A maximum of two concurrent instances\r
 637   are available.\r
 638   \r
 639   @param personalization_str\r
 640     The personalization_str parameter is a pointer to a buffer containing a\r
 641     random bit generator personalization string. The personalization string\r
 642     can be up to 128 bytes long.\r
 643   \r
 644   @param personalization_str_length\r
 645     The personalization_str_length parameter specifies the byte length of the\r
 646     personalization string pointed to by personalization_str.\r
 647   \r
 648   @param p_nrbg_handle\r
 649     The p_nrbg_handle parameter is a pointer to a byte that will contain the\r
 650     handle of the instantiated NRBG if this function call suceeds.\r
 651   \r
 652   @return\r
 653     The MSS_SYS_nrbg_instantiate function returns one of following status codes:\r
 654         - MSS_SYS_SUCCESS\r
 655         - MSS_SYS_NRBG_CATASTROPHIC_ERROR\r
 656         - MSS_SYS_NRBG_MAX_INST_EXCEEDED\r
 657         - MSS_SYS_NRBG_INVALID_HANDLE\r
 658         - MSS_SYS_NRBG_GEN_REQ_TOO_BIG\r
 659         - MSS_SYS_NRBG_MAX_LENGTH_EXCEEDED\r
 660         - MSS_SYS_SERVICE_DISABLED_BY_FACTORY\r
 661         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 662  */\r
 663 uint8_t MSS_SYS_nrbg_instantiate\r
 664 (\r
 665     const uint8_t * personalization_str,\r
 666     uint16_t personalization_str_length,\r
 667     uint8_t * p_nrbg_handle\r
 668 );\r
 669 \r
 670 /*-------------------------------------------------------------------------*//**\r
 671   The MSS_SYS_nrbg_generate function generates a random bit sequence up to\r
 672   128 bytes long.\r
 673   \r
 674   @param p_requested_data\r
 675     The p_requested_data parameter is a pointer to the buffer where the requested\r
 676     random data will be stored on completion of this system servide.\r
 677   \r
 678   @param p_additional_input\r
 679     The p_additional_input parameter is a pointer to the buffer containing\r
 680     additional input data for the random bit generation.\r
 681   \r
 682   @param requested_length\r
 683     The requested_length parameter specifies the number of random data bytes\r
 684     requested to be generated. The maximum generated data length is 128 bytes.\r
 685   \r
 686   @param additional_input_length\r
 687     The additional_input_length parameter specifies the number of addditonal\r
 688     input bytes to use in the random data generation.\r
 689   \r
 690   @param pr_req\r
 691     The pr_req parameter specifies if prediction resistance is requested.\r
 692   \r
 693   @param nrbg_handle\r
 694     The nrbg_handle parameter specifies which non-deterministic random bit\r
 695     generator (NRBG) instance will be used to generate the random data. The\r
 696     value of nrbg_handle is obtained as a result of a previous call to the\r
 697     MSS_SYS_nrbg_instantiate() function.\r
 698   \r
 699   @return\r
 700     The MSS_SYS_nrbg_generate function returns one of following status codes:\r
 701         - MSS_SYS_SUCCESS\r
 702         - MSS_SYS_NRBG_CATASTROPHIC_ERROR\r
 703         - MSS_SYS_NRBG_MAX_INST_EXCEEDED\r
 704         - MSS_SYS_NRBG_INVALID_HANDLE\r
 705         - MSS_SYS_NRBG_GEN_REQ_TOO_BIG\r
 706         - MSS_SYS_NRBG_MAX_LENGTH_EXCEEDED\r
 707         - MSS_SYS_SERVICE_DISABLED_BY_FACTORY\r
 708         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 709    \r
 710  */\r
 711 uint8_t MSS_SYS_nrbg_generate\r
 712 (\r
 713     const uint8_t * p_requested_data,\r
 714     const uint8_t * p_additional_input,\r
 715     uint8_t requested_length,\r
 716     uint8_t additional_input_length,\r
 717     uint8_t pr_req,\r
 718     uint8_t nrbg_handle\r
 719 );\r
 720 \r
 721 /*-------------------------------------------------------------------------*//**\r
 722   The MSS_SYS_nrbg_reseed() function is used to reseed the non-deterministic\r
 723   random bit generator (NRBG) identified by the nrbg_handle parameter.\r
 724   \r
 725   @param p_additional_input\r
 726     The additional_input_length parameter specifies the number of additional\r
 727     input bytes used to reseed the NRBG identified by the nrbg_handle parameter.\r
 728   \r
 729   @param additional_input_length\r
 730     The additional_input_length parameter specifies the number of additional\r
 731     input bytes used to reseed the NRBG.\r
 732   \r
 733   @param nrbg_handle\r
 734     The nrbg_handle parameter specifies which NRBG instance to reseed. The value\r
 735     of nrbg_handle is obtained as a result of a previous call to the\r
 736     MSS_SYS_nrbg_instantiate() function.\r
 737   \r
 738   @return\r
 739     The MSS_SYS_nrbg_reseed function returns one of following status codes:\r
 740         - MSS_SYS_SUCCESS\r
 741         - MSS_SYS_NRBG_CATASTROPHIC_ERROR\r
 742         - MSS_SYS_NRBG_MAX_INST_EXCEEDED\r
 743         - MSS_SYS_NRBG_INVALID_HANDLE\r
 744         - MSS_SYS_NRBG_GEN_REQ_TOO_BIG\r
 745         - MSS_SYS_NRBG_MAX_LENGTH_EXCEEDED\r
 746         - MSS_SYS_SERVICE_DISABLED_BY_FACTORY\r
 747         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 748    \r
 749  */\r
 750 uint8_t MSS_SYS_nrbg_reseed\r
 751 (\r
 752     const uint8_t * p_additional_input,\r
 753     uint8_t additional_input_length,\r
 754     uint8_t nrbg_handle\r
 755 );\r
 756 \r
 757 /*-------------------------------------------------------------------------*//**\r
 758   The MSS_SYS_nrbg_uninstantiate() function releases the non-deterministic\r
 759   random bit generator (NRBG) identified by the nrbg_handle parameter.\r
 760   \r
 761   @param nrbg_handle\r
 762     The nrbg_handle parameter specifies which NRBG instance will be released.\r
 763     The value of nrbg_handle is obtained as a result of a previous call to the\r
 764     MSS_SYS_nrbg_instantiate() function.\r
 765   \r
 766   @return\r
 767     The MSS_SYS_nrbg_uninstantiate function returns one of following status codes:\r
 768         - MSS_SYS_SUCCESS\r
 769         - MSS_SYS_NRBG_CATASTROPHIC_ERROR\r
 770         - MSS_SYS_NRBG_MAX_INST_EXCEEDED\r
 771         - MSS_SYS_NRBG_INVALID_HANDLE\r
 772         - MSS_SYS_NRBG_GEN_REQ_TOO_BIG\r
 773         - MSS_SYS_NRBG_MAX_LENGTH_EXCEEDED\r
 774         - MSS_SYS_SERVICE_DISABLED_BY_FACTORY\r
 775         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 776    \r
 777  */\r
 778 uint8_t MSS_SYS_nrbg_uninstantiate\r
 779 (\r
 780     uint8_t nrbg_handle\r
 781 );\r
 782 \r
 783 /*==============================================================================\r
 784  * Programming Services.\r
 785  */\r
 786 \r
 787 #define MSS_SYS_PROG_AUTHENTICATE    0u\r
 788 #define MSS_SYS_PROG_PROGRAM         1u\r
 789 #define MSS_SYS_PROG_VERIFY          2u\r
 790    \r
 791 /*-------------------------------------------------------------------------*//**\r
 792   The ISP Service allows the MSS Cortex-M3 processor to directly provide a\r
 793   bitstream for programming. The ISP Service is initiated by a call to\r
 794   MSS_SYS_start_isp(). The ISP Service can:\r
 795     - authenticate a programming bitstream\r
 796     - program a bitstream\r
 797     - verify that a programming bitstream has been correctly programmed\r
 798 \r
 799   The application must provide two functions as parameter to the\r
 800   MSS_SYS_start_isp() function. The first function will be used by the ISP\r
 801   Service to read the programming bitstream. The second function will be used by\r
 802   the ISP Service to notify the application that the ISP Service completed.\r
 803   \r
 804   @param mode\r
 805     The mode parameter specifies ISP service to perform. It can be one of:\r
 806         - MSS_SYS_PROG_AUTHENTICATE\r
 807         - MSS_SYS_PROG_PROGRAM\r
 808         - MSS_SYS_PROG_VERIFY\r
 809  \r
 810   @param page_read_handler\r
 811     The page_read_handler parameter is a pointer to a function with the\r
 812     following prototype:\r
 813         uint32_t page_read_handler(uint8 const ** pp_next_page);\r
 814  \r
 815   @param isp_completion_handler\r
 816     The isp_completion_handler parameter is a pointer to a function with the\r
 817     following prototype. This function will be called when the ISP service\r
 818     completes.\r
 819  \r
 820     The isp_completion_handler function will receive one of the following status\r
 821     codes:\r
 822         - MSS_SYS_SUCCESS\r
 823         - MSS_SYS_CHAINING_MISMATCH\r
 824         - MSS_SYS_UNEXPECTED_DATA_RECEIVED\r
 825         - MSS_SYS_INVALID_ENCRYPTION_KEY\r
 826         - MSS_SYS_INVALID_COMPONENT_HEADER\r
 827         - MSS_SYS_BACK_LEVEL_NOT_SATISFIED\r
 828         - MSS_SYS_DSN_BINDING_MISMATCH\r
 829         - MSS_SYS_ILLEGAL_COMPONENT_SEQUENCE\r
 830         - MSS_SYS_INSUFFICIENT_DEV_CAPABILITIES\r
 831         - MSS_SYS_INCORRECT_DEVICE_ID\r
 832         - MSS_SYS_UNSUPPORTED_BITSTREAM_PROT_VER\r
 833         - MSS_SYS_VERIFY_NOT_PERMITTED_ON_BITSTR\r
 834         - MSS_SYS_ABORT\r
 835         - MSS_SYS_NVM_VERIFY_FAILED\r
 836         - MSS_SYS_DEVICE_SECURITY_PROTECTED\r
 837         - MSS_SYS_PROGRAMMING_MODE_NOT_ENABLED\r
 838         - MSS_SYS_SERVICE_DISABLED_BY_USER\r
 839         \r
 840   @return\r
 841     This function does not return a value.\r
 842  */\r
 843 void MSS_SYS_start_isp\r
 844 (\r
 845     uint8_t mode,\r
 846     uint32_t (*page_read_handler)(uint8_t const **),\r
 847     void (*isp_completion_handler)(uint32_t)\r
 848 );\r
 849 \r
 850 /*-------------------------------------------------------------------------*//**\r
 851   Recalculates and compares digests of selected components.\r
 852   \r
 853   @param options\r
 854     The options parameter specifies which components' digest will be recalculated\r
 855     and checked. Each bit is used to identify a componetn as follows:\r
 856         - bit 0: FPGA fabric\r
 857         - bit 1: eNVM0\r
 858         - bit 2: eNVM1\r
 859     Note: The FPGA fabric will enter the FlashFreeze state if powered up when\r
 860           its digest is checked.\r
 861  \r
 862   @return\r
 863     The MSS_SYS_check_digest function returns the result of the digest check. The\r
 864     meaning of the digest check return value is as follows:\r
 865         bit 0: Fabric digest error\r
 866         bit 1: ENVM0 digest error\r
 867         bit 2: ENVM1 digest error\r
 868     A '1' in one of the above bits indicates a digest mismatch.\r
 869  */\r
 870 #define MSS_SYS_DIGEST_CHECK_FABRIC     0x01u\r
 871 #define MSS_SYS_DIGEST_CHECK_ENVM0      0x02u\r
 872 #define MSS_SYS_DIGEST_CHECK_ENVM1      0x04u\r
 873 \r
 874 uint8_t MSS_SYS_check_digest\r
 875 (\r
 876     uint8_t options\r
 877 );\r
 878 \r
 879 #ifdef __cplusplus\r
 880 }\r
 881 #endif\r
 882 \r
 883 #endif /* __MSS_SYS_SERVICES_H_ */\r