1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2017-2019 NXP 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 * 7 * Redistribution and use in source and binary forms, with or without modification, 8 * are permitted provided that the following conditions are met: 9 * 10 * o Redistributions of source code must retain the above copyright notice, this list 11 * of conditions and the following disclaimer. 12 * 13 * o Redistributions in binary form must reproduce the above copyright notice, this 14 * list of conditions and the following disclaimer in the documentation and/or 15 * other materials provided with the distribution. 16 * 17 * o Neither the name of the copyright holder nor the names of its 18 * contributors may be used to endorse or promote products derived from this 19 * software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 22 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 25 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON 28 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*! 34 * Header file containing the public API for the System Controller (SC) 35 * Miscellaneous (MISC) function. 36 * 37 * @addtogroup MISC_SVC MISC: Miscellaneous Service 38 * 39 * Module for the Miscellaneous (MISC) service. 40 * 41 * @{ 42 */ 43 44 #ifndef SC_MISC_API_H 45 #define SC_MISC_API_H 46 47 /* Includes */ 48 49 #include "main/types.h" 50 #include "svc/rm/rm_api.h" 51 52 /* Defines */ 53 54 /*! 55 * @name Defines for type widths 56 */ 57 /*@{*/ 58 #define SC_MISC_DMA_GRP_W 5U /*!< Width of sc_misc_dma_group_t */ 59 /*@}*/ 60 61 /*! Max DMA channel priority group */ 62 #define SC_MISC_DMA_GRP_MAX 31U 63 64 /*! 65 * @name Defines for sc_misc_boot_status_t 66 */ 67 /*@{*/ 68 #define SC_MISC_BOOT_STATUS_SUCCESS 0U /*!< Success */ 69 #define SC_MISC_BOOT_STATUS_SECURITY 1U /*!< Security violation */ 70 /*@}*/ 71 72 /*! 73 * @name Defines for sc_misc_temp_t 74 */ 75 /*@{*/ 76 #define SC_MISC_TEMP 0U /*!< Temp sensor */ 77 #define SC_MISC_TEMP_HIGH 1U /*!< Temp high alarm */ 78 #define SC_MISC_TEMP_LOW 2U /*!< Temp low alarm */ 79 /*@}*/ 80 81 /*! 82 * @name Defines for sc_misc_bt_t 83 */ 84 /*@{*/ 85 #define SC_MISC_BT_PRIMARY 0U /*!< Primary boot */ 86 #define SC_MISC_BT_SECONDARY 1U /*!< Secondary boot */ 87 #define SC_MISC_BT_RECOVERY 2U /*!< Recovery boot */ 88 #define SC_MISC_BT_MANUFACTURE 3U /*!< Manufacture boot */ 89 #define SC_MISC_BT_SERIAL 4U /*!< Serial boot */ 90 /*@}*/ 91 92 /* Types */ 93 94 /*! 95 * This type is used to store a DMA channel priority group. 96 */ 97 typedef uint8_t sc_misc_dma_group_t; 98 99 /*! 100 * This type is used report boot status. 101 */ 102 typedef uint8_t sc_misc_boot_status_t; 103 104 /*! 105 * This type is used report boot status. 106 */ 107 typedef uint8_t sc_misc_temp_t; 108 109 /*! 110 * This type is used report the boot type. 111 */ 112 typedef uint8_t sc_misc_bt_t; 113 114 /* Functions */ 115 116 /*! 117 * @name Control Functions 118 * @{ 119 */ 120 121 /*! 122 * This function sets a miscellaneous control value. 123 * 124 * @param[in] ipc IPC handle 125 * @param[in] resource resource the control is associated with 126 * @param[in] ctrl control to change 127 * @param[in] val value to apply to the control 128 * 129 * @return Returns an error code (SC_ERR_NONE = success). 130 * 131 * Return errors: 132 * - SC_PARM if arguments out of range or invalid, 133 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 134 * of the owner 135 * 136 * Refer to the [Control List](@ref CONTROLS) for valid control values. 137 */ 138 sc_err_t sc_misc_set_control(sc_ipc_t ipc, sc_rsrc_t resource, 139 sc_ctrl_t ctrl, uint32_t val); 140 141 /*! 142 * This function gets a miscellaneous control value. 143 * 144 * @param[in] ipc IPC handle 145 * @param[in] resource resource the control is associated with 146 * @param[in] ctrl control to get 147 * @param[out] val pointer to return the control value 148 * 149 * @return Returns an error code (SC_ERR_NONE = success). 150 * 151 * Return errors: 152 * - SC_PARM if arguments out of range or invalid, 153 * - SC_ERR_NOACCESS if caller's partition is not the resource owner or parent 154 * of the owner 155 * 156 * Refer to the [Control List](@ref CONTROLS) for valid control values. 157 */ 158 sc_err_t sc_misc_get_control(sc_ipc_t ipc, sc_rsrc_t resource, 159 sc_ctrl_t ctrl, uint32_t *val); 160 161 /* @} */ 162 163 /*! 164 * @name DMA Functions 165 * @{ 166 */ 167 168 /*! 169 * This function configures the max DMA channel priority group for a 170 * partition. 171 * 172 * @param[in] ipc IPC handle 173 * @param[in] pt handle of partition to assign \a max 174 * @param[in] max max priority group (0-31) 175 * 176 * @return Returns an error code (SC_ERR_NONE = success). 177 * 178 * Return errors: 179 * - SC_PARM if arguments out of range or invalid, 180 * - SC_ERR_NOACCESS if caller's partition is not the parent 181 * of the affected partition 182 * 183 * Valid \a max range is 0-31 with 0 being the lowest and 31 the highest. 184 * Default is the max priority group for the parent partition of \a pt. 185 */ 186 sc_err_t sc_misc_set_max_dma_group(sc_ipc_t ipc, sc_rm_pt_t pt, 187 sc_misc_dma_group_t max); 188 189 /*! 190 * This function configures the priority group for a DMA channel. 191 * 192 * @param[in] ipc IPC handle 193 * @param[in] resource DMA channel resource 194 * @param[in] group priority group (0-31) 195 * 196 * @return Returns an error code (SC_ERR_NONE = success). 197 * 198 * Return errors: 199 * - SC_PARM if arguments out of range or invalid, 200 * - SC_ERR_NOACCESS if caller's partition is not the owner or parent 201 * of the owner of the DMA channel 202 * 203 * Valid \a group range is 0-31 with 0 being the lowest and 31 the highest. 204 * The max value of \a group is limited by the partition max set using 205 * sc_misc_set_max_dma_group(). 206 */ 207 sc_err_t sc_misc_set_dma_group(sc_ipc_t ipc, sc_rsrc_t resource, 208 sc_misc_dma_group_t group); 209 210 /* @} */ 211 212 /*! 213 * @name Debug Functions 214 * @{ 215 */ 216 217 /*! 218 * This function is used output a debug character from the SCU UART. 219 * 220 * @param[in] ipc IPC handle 221 * @param[in] ch character to output 222 */ 223 void sc_misc_debug_out(sc_ipc_t ipc, uint8_t ch); 224 225 /*! 226 * This function starts/stops emulation waveform capture. 227 * 228 * @param[in] ipc IPC handle 229 * @param[in] enable flag to enable/disable capture 230 * 231 * @return Returns an error code (SC_ERR_NONE = success). 232 * 233 * Return errors: 234 * - SC_ERR_UNAVAILABLE if not running on emulation 235 */ 236 sc_err_t sc_misc_waveform_capture(sc_ipc_t ipc, sc_bool_t enable); 237 238 /*! 239 * This function is used to return the SCFW build info. 240 * 241 * @param[in] ipc IPC handle 242 * @param[out] build pointer to return build number 243 * @param[out] commit pointer to return commit ID (git SHA-1) 244 */ 245 void sc_misc_build_info(sc_ipc_t ipc, uint32_t *build, 246 uint32_t *commit); 247 248 /*! 249 * This function is used to return the SCFW API versions. 250 * 251 * @param[in] ipc IPC handle 252 * @param[out] cl_maj pointer to return major part of client version 253 * @param[out] cl_min pointer to return minor part of client version 254 * @param[out] sv_maj pointer to return major part of SCFW version 255 * @param[out] sv_min pointer to return minor part of SCFW version 256 * 257 * Client version is the version of the API ported to and used by the caller. 258 * SCFW version is the version of the SCFW binary running on the CPU. 259 * 260 * Note a major version difference indicates a break in compatibility. 261 */ 262 void sc_misc_api_ver(sc_ipc_t ipc, uint16_t *cl_maj, 263 uint16_t *cl_min, uint16_t *sv_maj, uint16_t *sv_min); 264 265 /*! 266 * This function is used to return the device's unique ID. 267 * 268 * @param[in] ipc IPC handle 269 * @param[out] id_l pointer to return lower 32-bit of ID [31:0] 270 * @param[out] id_h pointer to return upper 32-bits of ID [63:32] 271 */ 272 void sc_misc_unique_id(sc_ipc_t ipc, uint32_t *id_l, 273 uint32_t *id_h); 274 275 /* @} */ 276 277 /*! 278 * @name Other Functions 279 * @{ 280 */ 281 282 /*! 283 * This function configures the ARI match value for PCIe/SATA resources. 284 * 285 * @param[in] ipc IPC handle 286 * @param[in] resource match resource 287 * @param[in] resource_mst PCIe/SATA master to match 288 * @param[in] ari ARI to match 289 * @param[in] enable enable match or not 290 * 291 * @return Returns an error code (SC_ERR_NONE = success). 292 * 293 * Return errors: 294 * - SC_PARM if arguments out of range or invalid, 295 * - SC_ERR_NOACCESS if caller's partition is not the owner or parent 296 * of the owner of the resource and translation 297 * 298 * For PCIe, the ARI is the 16-bit value that includes the bus number, 299 * device number, and function number. For SATA, this value includes the 300 * FISType and PM_Port. 301 */ 302 sc_err_t sc_misc_set_ari(sc_ipc_t ipc, sc_rsrc_t resource, 303 sc_rsrc_t resource_mst, uint16_t ari, sc_bool_t enable); 304 305 /*! 306 * This function reports boot status. 307 * 308 * @param[in] ipc IPC handle 309 * @param[in] status boot status 310 * 311 * This is used by SW partitions to report status of boot. This is 312 * normally used to report a boot failure. 313 */ 314 void sc_misc_boot_status(sc_ipc_t ipc, sc_misc_boot_status_t status); 315 316 /*! 317 * This function tells the SCFW that a CPU is done booting. 318 * 319 * @param[in] ipc IPC handle 320 * @param[in] cpu CPU that is done booting 321 * 322 * This is called by early booting CPUs to report they are done with 323 * initialization. After starting early CPUs, the SCFW halts the 324 * booting process until they are done. During this time, early 325 * CPUs can call the SCFW with lower latency as the SCFW is idle. 326 * 327 * @return Returns an error code (SC_ERR_NONE = success). 328 * 329 * Return errors: 330 * - SC_PARM if arguments out of range or invalid, 331 * - SC_ERR_NOACCESS if caller's partition is not the CPU owner 332 */ 333 sc_err_t sc_misc_boot_done(sc_ipc_t ipc, sc_rsrc_t cpu); 334 335 /*! 336 * This function reads a given fuse word index. 337 * 338 * @param[in] ipc IPC handle 339 * @param[in] word fuse word index 340 * @param[out] val fuse read value 341 * 342 * @return Returns and error code (SC_ERR_NONE = success). 343 * 344 * Return errors codes: 345 * - SC_ERR_PARM if word fuse index param out of range or invalid 346 * - SC_ERR_NOACCESS if read operation failed 347 * - SC_ERR_LOCKED if read operation is locked 348 */ 349 sc_err_t sc_misc_otp_fuse_read(sc_ipc_t ipc, uint32_t word, uint32_t *val); 350 351 /*! 352 * This function writes a given fuse word index. Only the owner of the 353 * SC_R_SYSTEM resource or a partition with access permissions to 354 * SC_R_SYSTEM can do this. 355 * 356 * @param[in] ipc IPC handle 357 * @param[in] word fuse word index 358 * @param[in] val fuse write value 359 * 360 * The command is passed as is to SECO. SECO uses part of the 361 * \a word parameter to indicate if the fuse should be locked 362 * after programming. See the "Write common fuse" section of 363 * the SECO API Reference Guide for more info. 364 * 365 * @return Returns and error code (SC_ERR_NONE = success). 366 * 367 * Return errors codes: 368 * - SC_ERR_PARM if word fuse index param out of range or invalid 369 * - SC_ERR_NOACCESS if caller does not have SC_R_SYSTEM access 370 * - SC_ERR_NOACCESS if write operation failed 371 * - SC_ERR_LOCKED if write operation is locked 372 */ 373 sc_err_t sc_misc_otp_fuse_write(sc_ipc_t ipc, uint32_t word, uint32_t val); 374 375 /*! 376 * This function sets a temp sensor alarm. 377 * 378 * @param[in] ipc IPC handle 379 * @param[in] resource resource with sensor 380 * @param[in] temp alarm to set 381 * @param[in] celsius whole part of temp to set 382 * @param[in] tenths fractional part of temp to set 383 * 384 * @return Returns and error code (SC_ERR_NONE = success). 385 * 386 * This function will enable the alarm interrupt if the temp requested is 387 * not the min/max temp. This enable automatically clears when the alarm 388 * occurs and this function has to be called again to re-enable. 389 * 390 * Return errors codes: 391 * - SC_ERR_PARM if parameters invalid 392 * - SC_ERR_NOACCESS if caller does not own the resource 393 * - SC_ERR_NOPOWER if power domain of resource not powered 394 */ 395 sc_err_t sc_misc_set_temp(sc_ipc_t ipc, sc_rsrc_t resource, 396 sc_misc_temp_t temp, int16_t celsius, int8_t tenths); 397 398 /*! 399 * This function gets a temp sensor value. 400 * 401 * @param[in] ipc IPC handle 402 * @param[in] resource resource with sensor 403 * @param[in] temp value to get (sensor or alarm) 404 * @param[out] celsius whole part of temp to get 405 * @param[out] tenths fractional part of temp to get 406 * 407 * @return Returns and error code (SC_ERR_NONE = success). 408 * 409 * Return errors codes: 410 * - SC_ERR_PARM if parameters invalid 411 * - SC_ERR_BUSY if temp not ready yet (time delay after power on) 412 * - SC_ERR_NOPOWER if power domain of resource not powered 413 */ 414 sc_err_t sc_misc_get_temp(sc_ipc_t ipc, sc_rsrc_t resource, 415 sc_misc_temp_t temp, int16_t *celsius, int8_t *tenths); 416 417 /*! 418 * This function returns the boot device. 419 * 420 * @param[in] ipc IPC handle 421 * @param[out] dev pointer to return boot device 422 */ 423 void sc_misc_get_boot_dev(sc_ipc_t ipc, sc_rsrc_t *dev); 424 425 /*! 426 * This function returns the boot type. 427 * 428 * @param[in] ipc IPC handle 429 * @param[out] type pointer to return boot type 430 * 431 * @return Returns and error code (SC_ERR_NONE = success). 432 * 433 * Return errors code: 434 * - SC_ERR_UNAVAILABLE if type not passed by ROM 435 */ 436 sc_err_t sc_misc_get_boot_type(sc_ipc_t ipc, sc_misc_bt_t *type); 437 438 /*! 439 * This function returns the boot container index. 440 * 441 * @param[in] ipc IPC handle 442 * @param[out] idx pointer to return index 443 * 444 * Return \a idx = 1 for first container, 2 for second. 445 * 446 * @return Returns and error code (SC_ERR_NONE = success). 447 * 448 * Return errors code: 449 * - SC_ERR_UNAVAILABLE if index not passed by ROM 450 */ 451 sc_err_t sc_misc_get_boot_container(sc_ipc_t ipc, uint8_t *idx); 452 453 /*! 454 * This function returns the current status of the ON/OFF button. 455 * 456 * @param[in] ipc IPC handle 457 * @param[out] status pointer to return button status 458 */ 459 void sc_misc_get_button_status(sc_ipc_t ipc, sc_bool_t *status); 460 461 /*! 462 * This function returns the ROM patch checksum. 463 * 464 * @param[in] ipc IPC handle 465 * @param[out] checksum pointer to return checksum 466 * 467 * @return Returns and error code (SC_ERR_NONE = success). 468 */ 469 sc_err_t sc_misc_rompatch_checksum(sc_ipc_t ipc, uint32_t *checksum); 470 471 /*! 472 * This function calls the board IOCTL function. 473 * 474 * @param[in] ipc IPC handle 475 * @param[in,out] parm1 pointer to pass parameter 1 476 * @param[in,out] parm2 pointer to pass parameter 2 477 * @param[in,out] parm3 pointer to pass parameter 3 478 * 479 * @return Returns and error code (SC_ERR_NONE = success). 480 */ 481 sc_err_t sc_misc_board_ioctl(sc_ipc_t ipc, uint32_t *parm1, 482 uint32_t *parm2, uint32_t *parm3); 483 484 /* @} */ 485 486 #endif /* SC_MISC_API_H */ 487 488 /**@}*/ 489 490
