1 /* 2 * Copyright (C) 2016 Freescale Semiconductor, Inc. 3 * Copyright 2017-2019 NXP 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 /*! 9 * Header file containing the public API for the System Controller (SC) 10 * Miscellaneous (MISC) function. 11 * 12 * @addtogroup MISC_SVC (SVC) Miscellaneous Service 13 * 14 * Module for the Miscellaneous (MISC) service. 15 * 16 * @{ 17 */ 18 19 #ifndef SC_MISC_API_H 20 #define SC_MISC_API_H 21 22 /* Includes */ 23 24 #include <sci/svc/rm/sci_rm_api.h> 25 #include <sci/sci_types.h> 26 27 /* Defines */ 28 29 /*! 30 * @name Defines for type widths 31 */ 32 /*@{*/ 33 #define SC_MISC_DMA_GRP_W 5U /* Width of sc_misc_dma_group_t */ 34 /*@}*/ 35 36 /*! Max DMA channel priority group */ 37 #define SC_MISC_DMA_GRP_MAX 31U 38 39 /*! 40 * @name Defines for sc_misc_boot_status_t 41 */ 42 /*@{*/ 43 #define SC_MISC_BOOT_STATUS_SUCCESS 0U /* Success */ 44 #define SC_MISC_BOOT_STATUS_SECURITY 1U /* Security violation */ 45 /*@}*/ 46 47 /*! 48 * @name Defines for sc_misc_seco_auth_cmd_t 49 */ 50 /*@{*/ 51 #define SC_MISC_SECO_AUTH_SECO_FW 0U /* SECO Firmware */ 52 #define SC_MISC_SECO_AUTH_HDMI_TX_FW 1U /* HDMI TX Firmware */ 53 #define SC_MISC_SECO_AUTH_HDMI_RX_FW 2U /* HDMI RX Firmware */ 54 /*@}*/ 55 56 /*! 57 * @name Defines for sc_misc_temp_t 58 */ 59 /*@{*/ 60 #define SC_MISC_TEMP 0U /* Temp sensor */ 61 #define SC_MISC_TEMP_HIGH 1U /* Temp high alarm */ 62 #define SC_MISC_TEMP_LOW 2U /* Temp low alarm */ 63 /*@}*/ 64 65 /*! 66 * @name Defines for sc_misc_seco_auth_cmd_t 67 */ 68 /*@{*/ 69 #define SC_MISC_AUTH_CONTAINER 0U /* Authenticate container */ 70 #define SC_MISC_VERIFY_IMAGE 1U /* Verify image */ 71 #define SC_MISC_REL_CONTAINER 2U /* Release container */ 72 /*@}*/ 73 74 /* Types */ 75 76 /*! 77 * This type is used to store a DMA channel priority group. 78 */ 79 typedef uint8_t sc_misc_dma_group_t; 80 81 /*! 82 * This type is used report boot status. 83 */ 84 typedef uint8_t sc_misc_boot_status_t; 85 86 /*! 87 * This type is used to issue SECO authenticate commands. 88 */ 89 typedef uint8_t sc_misc_seco_auth_cmd_t; 90 91 /*! 92 * This type is used report boot status. 93 */ 94 typedef uint8_t sc_misc_temp_t; 95 96 /* Functions */ 97 98 /*! 99 * @name Control Functions 100 * @{ 101 */ 102 103 /*! 104 * This function sets a miscellaneous control value. 105 * 106 * @param[in] ipc IPC handle 107 * @param[in] resource resource the control is associated with 108 * @param[in] ctrl control to change 109 * @param[in] val value to apply to the control 110 * 111 * @return Returns an error code (SC_ERR_NONE = success). 112 * 113 * Return errors: 114 * - SC_PARM if arguments out of range or invalid, 115 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 116 * of the owner 117 * 118 * Refer to the [Control List](@ref CONTROLS) for valid control values. 119 */ 120 sc_err_t sc_misc_set_control(sc_ipc_t ipc, sc_rsrc_t resource, 121 sc_ctrl_t ctrl, uint32_t val); 122 123 /*! 124 * This function gets a miscellaneous control value. 125 * 126 * @param[in] ipc IPC handle 127 * @param[in] resource resource the control is associated with 128 * @param[in] ctrl control to get 129 * @param[out] val pointer to return the control value 130 * 131 * @return Returns an error code (SC_ERR_NONE = success). 132 * 133 * Return errors: 134 * - SC_PARM if arguments out of range or invalid, 135 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 136 * of the owner 137 * 138 * Refer to the [Control List](@ref CONTROLS) for valid control values. 139 */ 140 sc_err_t sc_misc_get_control(sc_ipc_t ipc, sc_rsrc_t resource, 141 sc_ctrl_t ctrl, uint32_t *val); 142 143 /* @} */ 144 145 /*! 146 * @name DMA Functions 147 * @{ 148 */ 149 150 /*! 151 * This function configures the max DMA channel priority group for a 152 * partition. 153 * 154 * @param[in] ipc IPC handle 155 * @param[in] pt handle of partition to assign \a max 156 * @param[in] max max priority group (0-31) 157 * 158 * @return Returns an error code (SC_ERR_NONE = success). 159 * 160 * Return errors: 161 * - SC_PARM if arguments out of range or invalid, 162 * - SC_ERR_NOACCESS if caller's partition is not the parent 163 * of the affected partition 164 * 165 * Valid \a max range is 0-31 with 0 being the lowest and 31 the highest. 166 * Default is the max priority group for the parent partition of \a pt. 167 */ 168 sc_err_t sc_misc_set_max_dma_group(sc_ipc_t ipc, sc_rm_pt_t pt, 169 sc_misc_dma_group_t max); 170 171 /*! 172 * This function configures the priority group for a DMA channel. 173 * 174 * @param[in] ipc IPC handle 175 * @param[in] resource DMA channel resource 176 * @param[in] group priority group (0-31) 177 * 178 * @return Returns an error code (SC_ERR_NONE = success). 179 * 180 * Return errors: 181 * - SC_PARM if arguments out of range or invalid, 182 * - SC_ERR_NOACCESS if caller's partition is not the owner or parent 183 * of the owner of the DMA channel 184 * 185 * Valid \a group range is 0-31 with 0 being the lowest and 31 the highest. 186 * The max value of \a group is limited by the partition max set using 187 * sc_misc_set_max_dma_group(). 188 */ 189 sc_err_t sc_misc_set_dma_group(sc_ipc_t ipc, sc_rsrc_t resource, 190 sc_misc_dma_group_t group); 191 192 /* @} */ 193 194 /*! 195 * @name Security Functions 196 * @{ 197 */ 198 199 /*! 200 * This function loads a SECO image. 201 * 202 * @param[in] ipc IPC handle 203 * @param[in] addr_src address of image source 204 * @param[in] addr_dst address of image destination 205 * @param[in] len length of image to load 206 * @param[in] fw SC_TRUE = firmware load 207 * 208 * @return Returns an error code (SC_ERR_NONE = success). 209 * 210 * Return errors codes: 211 * - SC_ERR_PARM if word fuse index param out of range or invalid 212 * - SC_ERR_UNAVAILABLE if SECO not available 213 * 214 * This is used to load images via the SECO. Examples include SECO 215 * Firmware and IVT/CSF data used for authentication. These are usually 216 * loaded into SECO TCM. \a addr_src is in secure memory. 217 * 218 * See the Security Reference Manual (SRM) for more info. 219 */ 220 sc_err_t sc_misc_seco_image_load(sc_ipc_t ipc, sc_faddr_t addr_src, 221 sc_faddr_t addr_dst, uint32_t len, 222 sc_bool_t fw); 223 224 /*! 225 * This function is used to authenticate a SECO image or command. 226 * 227 * @param[in] ipc IPC handle 228 * @param[in] cmd authenticate command 229 * @param[in] addr address of/or metadata 230 * 231 * @return Returns an error code (SC_ERR_NONE = success). 232 * 233 * Return errors codes: 234 * - SC_ERR_PARM if word fuse index param out of range or invalid 235 * - SC_ERR_UNAVAILABLE if SECO not available 236 * 237 * This is used to authenticate a SECO image or issue a security 238 * command. \a addr often points to an container. It is also 239 * just data (or even unused) for some commands. 240 * 241 * See the Security Reference Manual (SRM) for more info. 242 */ 243 sc_err_t sc_misc_seco_authenticate(sc_ipc_t ipc, 244 sc_misc_seco_auth_cmd_t cmd, 245 sc_faddr_t addr); 246 247 /*! 248 * This function securely writes a group of fuse words. 249 * 250 * @param[in] ipc IPC handle 251 * @param[in] addr address of message block 252 * 253 * @return Returns and error code (SC_ERR_NONE = success). 254 * 255 * Return errors codes: 256 * - SC_ERR_UNAVAILABLE if SECO not available 257 * 258 * Note \a addr must be a pointer to a signed message block. 259 * 260 * See the Security Reference Manual (SRM) for more info. 261 */ 262 sc_err_t sc_misc_seco_fuse_write(sc_ipc_t ipc, sc_faddr_t addr); 263 264 /*! 265 * This function securely enables debug. 266 * 267 * @param[in] ipc IPC handle 268 * @param[in] addr address of message block 269 * 270 * @return Returns and error code (SC_ERR_NONE = success). 271 * 272 * Return errors codes: 273 * - SC_ERR_UNAVAILABLE if SECO not available 274 * 275 * Note \a addr must be a pointer to a signed message block. 276 * 277 * See the Security Reference Manual (SRM) for more info. 278 */ 279 sc_err_t sc_misc_seco_enable_debug(sc_ipc_t ipc, sc_faddr_t addr); 280 281 /*! 282 * This function updates the lifecycle of the device. 283 * 284 * @param[in] ipc IPC handle 285 * @param[in] lifecycle new lifecycle 286 * 287 * @return Returns and error code (SC_ERR_NONE = success). 288 * 289 * Return errors codes: 290 * - SC_ERR_UNAVAILABLE if SECO not available 291 * 292 * This message is used for going from Open to NXP Closed to OEM Closed. 293 * 294 * See the Security Reference Manual (SRM) for more info. 295 */ 296 sc_err_t sc_misc_seco_forward_lifecycle(sc_ipc_t ipc, uint32_t lifecycle); 297 298 /*! 299 * This function updates the lifecycle to one of the return lifecycles. 300 * 301 * @param[in] ipc IPC handle 302 * @param[in] addr address of message block 303 * 304 * @return Returns and error code (SC_ERR_NONE = success). 305 * 306 * Return errors codes: 307 * - SC_ERR_UNAVAILABLE if SECO not available 308 * 309 * Note \a addr must be a pointer to a signed message block. 310 * 311 * To switch back to NXP states (Full Field Return), message must be signed 312 * by NXP SRK. For OEM States (Partial Field Return), must be signed by OEM 313 * SRK. 314 * 315 * See the Security Reference Manual (SRM) for more info. 316 */ 317 sc_err_t sc_misc_seco_return_lifecycle(sc_ipc_t ipc, sc_faddr_t addr); 318 319 /*! 320 * This function is used to return the SECO FW build info. 321 * 322 * @param[in] ipc IPC handle 323 * @param[out] version pointer to return build number 324 * @param[out] commit pointer to return commit ID (git SHA-1) 325 */ 326 void sc_misc_seco_build_info(sc_ipc_t ipc, uint32_t *version, uint32_t *commit); 327 328 /*! 329 * This function is used to return SECO chip info. 330 * 331 * @param[in] ipc IPC handle 332 * @param[out] lc pointer to return lifecycle 333 * @param[out] monotonic pointer to return monotonic counter 334 * @param[out] uid_l pointer to return UID (lower 32 bits) 335 * @param[out] uid_h pointer to return UID (upper 32 bits) 336 */ 337 sc_err_t sc_misc_seco_chip_info(sc_ipc_t ipc, uint16_t *lc, 338 uint16_t *monotonic, uint32_t *uid_l, 339 uint32_t *uid_h); 340 341 /* @} */ 342 343 /*! 344 * @name Debug Functions 345 * @{ 346 */ 347 348 /*! 349 * This function is used output a debug character from the SCU UART. 350 * 351 * @param[in] ipc IPC handle 352 * @param[in] ch character to output 353 */ 354 void sc_misc_debug_out(sc_ipc_t ipc, uint8_t ch); 355 356 /*! 357 * This function starts/stops emulation waveform capture. 358 * 359 * @param[in] ipc IPC handle 360 * @param[in] enable flag to enable/disable capture 361 * 362 * @return Returns an error code (SC_ERR_NONE = success). 363 * 364 * Return errors: 365 * - SC_ERR_UNAVAILABLE if not running on emulation 366 */ 367 sc_err_t sc_misc_waveform_capture(sc_ipc_t ipc, sc_bool_t enable); 368 369 /*! 370 * This function is used to return the SCFW build info. 371 * 372 * @param[in] ipc IPC handle 373 * @param[out] build pointer to return build number 374 * @param[out] commit pointer to return commit ID (git SHA-1) 375 */ 376 void sc_misc_build_info(sc_ipc_t ipc, uint32_t *build, uint32_t *commit); 377 378 /*! 379 * This function is used to return the device's unique ID. 380 * 381 * @param[in] ipc IPC handle 382 * @param[out] id_l pointer to return lower 32-bit of ID [31:0] 383 * @param[out] id_h pointer to return upper 32-bits of ID [63:32] 384 */ 385 void sc_misc_unique_id(sc_ipc_t ipc, uint32_t *id_l, uint32_t *id_h); 386 387 /* @} */ 388 389 /*! 390 * @name Other Functions 391 * @{ 392 */ 393 394 /*! 395 * This function configures the ARI match value for PCIe/SATA resources. 396 * 397 * @param[in] ipc IPC handle 398 * @param[in] resource match resource 399 * @param[in] resource_mst PCIe/SATA master to match 400 * @param[in] ari ARI to match 401 * @param[in] enable enable match or not 402 * 403 * @return Returns an error code (SC_ERR_NONE = success). 404 * 405 * Return errors: 406 * - SC_PARM if arguments out of range or invalid, 407 * - SC_ERR_NOACCESS if caller's partition is not the owner or parent 408 * of the owner of the resource and translation 409 * 410 * For PCIe, the ARI is the 16-bit value that includes the bus number, 411 * device number, and function number. For SATA, this value includes the 412 * FISType and PM_Port. 413 */ 414 sc_err_t sc_misc_set_ari(sc_ipc_t ipc, sc_rsrc_t resource, 415 sc_rsrc_t resource_mst, uint16_t ari, 416 sc_bool_t enable); 417 418 /*! 419 * This function reports boot status. 420 * 421 * @param[in] ipc IPC handle 422 * @param[in] status boot status 423 * 424 * This is used by SW partitions to report status of boot. This is 425 * normally used to report a boot failure. 426 */ 427 void sc_misc_boot_status(sc_ipc_t ipc, sc_misc_boot_status_t status); 428 429 /*! 430 * This function tells the SCFW that a CPU is done booting. 431 * 432 * @param[in] ipc IPC handle 433 * @param[in] cpu CPU that is done booting 434 * 435 * This is called by early booting CPUs to report they are done with 436 * initialization. After starting early CPUs, the SCFW halts the 437 * booting process until they are done. During this time, early 438 * CPUs can call the SCFW with lower latency as the SCFW is idle. 439 * 440 * @return Returns an error code (SC_ERR_NONE = success). 441 * 442 * Return errors: 443 * - SC_PARM if arguments out of range or invalid, 444 * - SC_ERR_NOACCESS if caller's partition is not the CPU owner 445 */ 446 sc_err_t sc_misc_boot_done(sc_ipc_t ipc, sc_rsrc_t cpu); 447 448 /*! 449 * This function reads a given fuse word index. 450 * 451 * @param[in] ipc IPC handle 452 * @param[in] word fuse word index 453 * @param[out] val fuse read value 454 * 455 * @return Returns and error code (SC_ERR_NONE = success). 456 * 457 * Return errors codes: 458 * - SC_ERR_PARM if word fuse index param out of range or invalid 459 * - SC_ERR_NOACCESS if read operation failed 460 * - SC_ERR_LOCKED if read operation is locked 461 */ 462 sc_err_t sc_misc_otp_fuse_read(sc_ipc_t ipc, uint32_t word, uint32_t *val); 463 464 /*! 465 * This function writes a given fuse word index. 466 * 467 * @param[in] ipc IPC handle 468 * @param[in] word fuse word index 469 * @param[in] val fuse write value 470 * 471 * @return Returns and error code (SC_ERR_NONE = success). 472 * 473 * Return errors codes: 474 * - SC_ERR_PARM if word fuse index param out of range or invalid 475 * - SC_ERR_NOACCESS if write operation failed 476 * - SC_ERR_LOCKED if write operation is locked 477 */ 478 sc_err_t sc_misc_otp_fuse_write(sc_ipc_t ipc, uint32_t word, uint32_t val); 479 480 /*! 481 * This function sets a temp sensor alarm. 482 * 483 * @param[in] ipc IPC handle 484 * @param[in] resource resource with sensor 485 * @param[in] temp alarm to set 486 * @param[in] celsius whole part of temp to set 487 * @param[in] tenths fractional part of temp to set 488 * 489 * @return Returns and error code (SC_ERR_NONE = success). 490 * 491 * This function will enable the alarm interrupt if the temp requested is 492 * not the min/max temp. This enable automatically clears when the alarm 493 * occurs and this function has to be called again to re-enable. 494 * 495 * Return errors codes: 496 * - SC_ERR_PARM if parameters invalid 497 */ 498 sc_err_t sc_misc_set_temp(sc_ipc_t ipc, sc_rsrc_t resource, 499 sc_misc_temp_t temp, int16_t celsius, int8_t tenths); 500 501 /*! 502 * This function gets a temp sensor value. 503 * 504 * @param[in] ipc IPC handle 505 * @param[in] resource resource with sensor 506 * @param[in] temp value to get (sensor or alarm) 507 * @param[out] celsius whole part of temp to get 508 * @param[out] tenths fractional part of temp to get 509 * 510 * @return Returns and error code (SC_ERR_NONE = success). 511 * 512 * Return errors codes: 513 * - SC_ERR_PARM if parameters invalid 514 */ 515 sc_err_t sc_misc_get_temp(sc_ipc_t ipc, sc_rsrc_t resource, 516 sc_misc_temp_t temp, int16_t *celsius, 517 int8_t *tenths); 518 519 /*! 520 * This function returns the boot device. 521 * 522 * @param[in] ipc IPC handle 523 * @param[out] dev pointer to return boot device 524 */ 525 void sc_misc_get_boot_dev(sc_ipc_t ipc, sc_rsrc_t *dev); 526 527 /*! 528 * This function returns the current status of the ON/OFF button. 529 * 530 * @param[in] ipc IPC handle 531 * @param[out] status pointer to return button status 532 */ 533 void sc_misc_get_button_status(sc_ipc_t ipc, sc_bool_t *status); 534 535 /* @} */ 536 537 #endif /* SC_MISC_API_H */ 538 539 /**@}*/ 540