1 /* 2 * Copyright (c) 2015-2018, ARM Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /*! 8 * Header file containing the public API for the System Controller (SC) 9 * Pad Control (PAD) function. 10 * 11 * @addtogroup PAD_SVC (SVC) Pad Service 12 * 13 * Module for the Pad Control (PAD) service. 14 * 15 * @details 16 * 17 * Pad configuration is managed by SC firmware. The pad configuration 18 * features supported by the SC firmware include: 19 * 20 * - Configuring the mux, input/output connection, and low-power isolation 21 mode. 22 * - Configuring the technology-specific pad setting such as drive strength, 23 * pullup/pulldown, etc. 24 * - Configuring compensation for pad groups with dual voltage capability. 25 * 26 * Pad functions fall into one of three categories. Generic functions are 27 * common to all SoCs and all process technologies. SoC functions are raw 28 * low-level functions. Technology-specific functions are specific to the 29 * process technology. 30 * 31 * The list of pads is SoC specific. Refer to the SoC [Pad List](@ref PADS) 32 * for valid pad values. Note that all pads exist on a die but may or 33 * may not be brought out by the specific package. Mapping of pads to 34 * package pins/balls is documented in the associated Data Sheet. Some pads 35 * may not be brought out because the part (die+package) is defeatured and 36 * some pads may connect to the substrate in the package. 37 * 38 * Some pads (SC_P_COMP_*) that can be specified are not individual pads 39 * but are in fact pad groups. These groups have additional configuration 40 * that can be done using the sc_pad_set_gp_28fdsoi_comp() function. More 41 * info on these can be found in the associated Reference Manual. 42 * 43 * Pads are managed as a resource by the Resource Manager (RM). They have 44 * assigned owners and only the owners can configure the pads. Some of the 45 * pads are reserved for use by the SCFW itself and this can be overriden 46 * with the implementation of board_config_sc(). Additionally, pads may 47 * be assigned to various other partitions via the implementation of 48 * board_system_config(). 49 * 50 * Note muxing two input pads to the same IP functional signal will 51 * result in undefined behavior. 52 * @{ 53 */ 54 55 #ifndef SCI_PAD_API_H 56 #define SCI_PAD_API_H 57 58 /* Includes */ 59 60 #include <sci/sci_types.h> 61 #include <sci/svc/rm/sci_rm_api.h> 62 63 /* Defines */ 64 65 /*! 66 * @name Defines for type widths 67 */ 68 /*@{*/ 69 #define SC_PAD_MUX_W 3 /* Width of mux parameter */ 70 /*@}*/ 71 72 /*! 73 * @name Defines for sc_pad_config_t 74 */ 75 /*@{*/ 76 #define SC_PAD_CONFIG_NORMAL 0U /* Normal */ 77 #define SC_PAD_CONFIG_OD 1U /* Open Drain */ 78 #define SC_PAD_CONFIG_OD_IN 2U /* Open Drain and input */ 79 #define SC_PAD_CONFIG_OUT_IN 3U /* Output and input */ 80 /*@}*/ 81 82 /*! 83 * @name Defines for sc_pad_iso_t 84 */ 85 /*@{*/ 86 #define SC_PAD_ISO_OFF 0U /* ISO latch is transparent */ 87 #define SC_PAD_ISO_EARLY 1U /* Follow EARLY_ISO */ 88 #define SC_PAD_ISO_LATE 2U /* Follow LATE_ISO */ 89 #define SC_PAD_ISO_ON 3U /* ISO latched data is held */ 90 /*@}*/ 91 92 /*! 93 * @name Defines for sc_pad_28fdsoi_dse_t 94 */ 95 /*@{*/ 96 #define SC_PAD_28FDSOI_DSE_18V_1MA 0U /* Drive strength of 1mA for 1.8v */ 97 #define SC_PAD_28FDSOI_DSE_18V_2MA 1U /* Drive strength of 2mA for 1.8v */ 98 #define SC_PAD_28FDSOI_DSE_18V_4MA 2U /* Drive strength of 4mA for 1.8v */ 99 #define SC_PAD_28FDSOI_DSE_18V_6MA 3U /* Drive strength of 6mA for 1.8v */ 100 #define SC_PAD_28FDSOI_DSE_18V_8MA 4U /* Drive strength of 8mA for 1.8v */ 101 #define SC_PAD_28FDSOI_DSE_18V_10MA 5U /* Drive strength of 10mA for 1.8v */ 102 #define SC_PAD_28FDSOI_DSE_18V_12MA 6U /* Drive strength of 12mA for 1.8v */ 103 #define SC_PAD_28FDSOI_DSE_18V_HS 7U /* High-speed drive strength for 1.8v */ 104 #define SC_PAD_28FDSOI_DSE_33V_2MA 0U /* Drive strength of 2mA for 3.3v */ 105 #define SC_PAD_28FDSOI_DSE_33V_4MA 1U /* Drive strength of 4mA for 3.3v */ 106 #define SC_PAD_28FDSOI_DSE_33V_8MA 2U /* Drive strength of 8mA for 3.3v */ 107 #define SC_PAD_28FDSOI_DSE_33V_12MA 3U /* Drive strength of 12mA for 3.3v */ 108 #define SC_PAD_28FDSOI_DSE_DV_HIGH 0U /* High drive strength for dual volt */ 109 #define SC_PAD_28FDSOI_DSE_DV_LOW 1U /* Low drive strength for dual volt */ 110 /*@}*/ 111 112 /*! 113 * @name Defines for sc_pad_28fdsoi_ps_t 114 */ 115 /*@{*/ 116 #define SC_PAD_28FDSOI_PS_KEEPER 0U /* Bus-keeper (only valid for 1.8v) */ 117 #define SC_PAD_28FDSOI_PS_PU 1U /* Pull-up */ 118 #define SC_PAD_28FDSOI_PS_PD 2U /* Pull-down */ 119 #define SC_PAD_28FDSOI_PS_NONE 3U /* No pull (disabled) */ 120 /*@}*/ 121 122 /*! 123 * @name Defines for sc_pad_28fdsoi_pus_t 124 */ 125 /*@{*/ 126 #define SC_PAD_28FDSOI_PUS_30K_PD 0U /* 30K pull-down */ 127 #define SC_PAD_28FDSOI_PUS_100K_PU 1U /* 100K pull-up */ 128 #define SC_PAD_28FDSOI_PUS_3K_PU 2U /* 3K pull-up */ 129 #define SC_PAD_28FDSOI_PUS_30K_PU 3U /* 30K pull-up */ 130 /*@}*/ 131 132 /*! 133 * @name Defines for sc_pad_wakeup_t 134 */ 135 /*@{*/ 136 #define SC_PAD_WAKEUP_OFF 0U /* Off */ 137 #define SC_PAD_WAKEUP_CLEAR 1U /* Clears pending flag */ 138 #define SC_PAD_WAKEUP_LOW_LVL 4U /* Low level */ 139 #define SC_PAD_WAKEUP_FALL_EDGE 5U /* Falling edge */ 140 #define SC_PAD_WAKEUP_RISE_EDGE 6U /* Rising edge */ 141 #define SC_PAD_WAKEUP_HIGH_LVL 7U /* High-level */ 142 /*@}*/ 143 144 /* Types */ 145 146 /*! 147 * This type is used to declare a pad config. It determines how the 148 * output data is driven, pull-up is controlled, and input signal is 149 * connected. Normal and OD are typical and only connect the input 150 * when the output is not driven. The IN options are less common and 151 * force an input connection even when driving the output. 152 */ 153 typedef uint8_t sc_pad_config_t; 154 155 /*! 156 * This type is used to declare a pad low-power isolation config. 157 * ISO_LATE is the most common setting. ISO_EARLY is only used when 158 * an output pad is directly determined by another input pad. The 159 * other two are only used when SW wants to directly contol isolation. 160 */ 161 typedef uint8_t sc_pad_iso_t; 162 163 /*! 164 * This type is used to declare a drive strength. Note it is specific 165 * to 28FDSOI. Also note that valid values depend on the pad type. 166 */ 167 typedef uint8_t sc_pad_28fdsoi_dse_t; 168 169 /*! 170 * This type is used to declare a pull select. Note it is specific 171 * to 28FDSOI. 172 */ 173 typedef uint8_t sc_pad_28fdsoi_ps_t; 174 175 /*! 176 * This type is used to declare a pull-up select. Note it is specific 177 * to 28FDSOI HSIC pads. 178 */ 179 typedef uint8_t sc_pad_28fdsoi_pus_t; 180 181 /*! 182 * This type is used to declare a wakeup mode of a pad. 183 */ 184 typedef uint8_t sc_pad_wakeup_t; 185 186 /* Functions */ 187 188 /*! 189 * @name Generic Functions 190 * @{ 191 */ 192 193 /*! 194 * This function configures the mux settings for a pad. This includes 195 * the signal mux, pad config, and low-power isolation mode. 196 * 197 * @param[in] ipc IPC handle 198 * @param[in] pad pad to configure 199 * @param[in] mux mux setting 200 * @param[in] config pad config 201 * @param[in] iso low-power isolation mode 202 * 203 * @return Returns an error code (SC_ERR_NONE = success). 204 * 205 * Return errors: 206 * - SC_PARM if arguments out of range or invalid, 207 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 208 * 209 * Note muxing two input pads to the same IP functional signal will 210 * result in undefined behavior. 211 * 212 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 213 */ 214 sc_err_t sc_pad_set_mux(sc_ipc_t ipc, sc_pad_t pad, 215 uint8_t mux, sc_pad_config_t config, sc_pad_iso_t iso); 216 217 /*! 218 * This function gets the mux settings for a pad. This includes 219 * the signal mux, pad config, and low-power isolation mode. 220 * 221 * @param[in] ipc IPC handle 222 * @param[in] pad pad to query 223 * @param[out] mux pointer to return mux setting 224 * @param[out] config pointer to return pad config 225 * @param[out] iso pointer to return low-power isolation mode 226 * 227 * @return Returns an error code (SC_ERR_NONE = success). 228 * 229 * Return errors: 230 * - SC_PARM if arguments out of range or invalid, 231 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 232 * 233 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 234 */ 235 sc_err_t sc_pad_get_mux(sc_ipc_t ipc, sc_pad_t pad, 236 uint8_t *mux, sc_pad_config_t *config, 237 sc_pad_iso_t *iso); 238 239 /*! 240 * This function configures the general purpose pad control. This 241 * is technology dependent and includes things like drive strength, 242 * slew rate, pull up/down, etc. Refer to the SoC Reference Manual 243 * for bit field details. 244 * 245 * @param[in] ipc IPC handle 246 * @param[in] pad pad to configure 247 * @param[in] ctrl control value to set 248 * 249 * @return Returns an error code (SC_ERR_NONE = success). 250 * 251 * Return errors: 252 * - SC_PARM if arguments out of range or invalid, 253 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 254 * 255 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 256 */ 257 sc_err_t sc_pad_set_gp(sc_ipc_t ipc, sc_pad_t pad, uint32_t ctrl); 258 259 /*! 260 * This function gets the general purpose pad control. This 261 * is technology dependent and includes things like drive strength, 262 * slew rate, pull up/down, etc. Refer to the SoC Reference Manual 263 * for bit field details. 264 * 265 * @param[in] ipc IPC handle 266 * @param[in] pad pad to query 267 * @param[out] ctrl pointer to return control value 268 * 269 * @return Returns an error code (SC_ERR_NONE = success). 270 * 271 * Return errors: 272 * - SC_PARM if arguments out of range or invalid, 273 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 274 * 275 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 276 */ 277 sc_err_t sc_pad_get_gp(sc_ipc_t ipc, sc_pad_t pad, uint32_t *ctrl); 278 279 /*! 280 * This function configures the wakeup mode of the pad. 281 * 282 * @param[in] ipc IPC handle 283 * @param[in] pad pad to configure 284 * @param[in] wakeup wakeup to set 285 * 286 * @return Returns an error code (SC_ERR_NONE = success). 287 * 288 * Return errors: 289 * - SC_PARM if arguments out of range or invalid, 290 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 291 * 292 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 293 */ 294 sc_err_t sc_pad_set_wakeup(sc_ipc_t ipc, sc_pad_t pad, sc_pad_wakeup_t wakeup); 295 296 /*! 297 * This function gets the wakeup mode of a pad. 298 * 299 * @param[in] ipc IPC handle 300 * @param[in] pad pad to query 301 * @param[out] wakeup pointer to return wakeup 302 * 303 * @return Returns an error code (SC_ERR_NONE = success). 304 * 305 * Return errors: 306 * - SC_PARM if arguments out of range or invalid, 307 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 308 * 309 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 310 */ 311 sc_err_t sc_pad_get_wakeup(sc_ipc_t ipc, sc_pad_t pad, sc_pad_wakeup_t *wakeup); 312 313 /*! 314 * This function configures a pad. 315 * 316 * @param[in] ipc IPC handle 317 * @param[in] pad pad to configure 318 * @param[in] mux mux setting 319 * @param[in] config pad config 320 * @param[in] iso low-power isolation mode 321 * @param[in] ctrl control value 322 * @param[in] wakeup wakeup to set 323 * 324 * @see sc_pad_set_mux(). 325 * @see sc_pad_set_gp(). 326 * 327 * Return errors: 328 * - SC_PARM if arguments out of range or invalid, 329 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 330 * 331 * @return Returns an error code (SC_ERR_NONE = success). 332 * 333 * Note muxing two input pads to the same IP functional signal will 334 * result in undefined behavior. 335 * 336 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 337 */ 338 sc_err_t sc_pad_set_all(sc_ipc_t ipc, sc_pad_t pad, uint8_t mux, 339 sc_pad_config_t config, sc_pad_iso_t iso, uint32_t ctrl, 340 sc_pad_wakeup_t wakeup); 341 342 /*! 343 * This function gets a pad's config. 344 * 345 * @param[in] ipc IPC handle 346 * @param[in] pad pad to query 347 * @param[out] mux pointer to return mux setting 348 * @param[out] config pointer to return pad config 349 * @param[out] iso pointer to return low-power isolation mode 350 * @param[out] ctrl pointer to return control value 351 * @param[out] wakeup pointer to return wakeup to set 352 * 353 * @see sc_pad_set_mux(). 354 * @see sc_pad_set_gp(). 355 * 356 * Return errors: 357 * - SC_PARM if arguments out of range or invalid, 358 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 359 * 360 * @return Returns an error code (SC_ERR_NONE = success). 361 * 362 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 363 */ 364 sc_err_t sc_pad_get_all(sc_ipc_t ipc, sc_pad_t pad, uint8_t *mux, 365 sc_pad_config_t *config, sc_pad_iso_t *iso, 366 uint32_t *ctrl, sc_pad_wakeup_t *wakeup); 367 368 /* @} */ 369 370 /*! 371 * @name SoC Specific Functions 372 * @{ 373 */ 374 375 /*! 376 * This function configures the settings for a pad. This setting is SoC 377 * specific. 378 * 379 * @param[in] ipc IPC handle 380 * @param[in] pad pad to configure 381 * @param[in] val value to set 382 * 383 * @return Returns an error code (SC_ERR_NONE = success). 384 * 385 * Return errors: 386 * - SC_PARM if arguments out of range or invalid, 387 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 388 * 389 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 390 */ 391 sc_err_t sc_pad_set(sc_ipc_t ipc, sc_pad_t pad, uint32_t val); 392 393 /*! 394 * This function gets the settings for a pad. This setting is SoC 395 * specific. 396 * 397 * @param[in] ipc IPC handle 398 * @param[in] pad pad to query 399 * @param[out] val pointer to return setting 400 * 401 * @return Returns an error code (SC_ERR_NONE = success). 402 * 403 * Return errors: 404 * - SC_PARM if arguments out of range or invalid, 405 * - SC_ERR_NOACCESS if caller's partition is not the pad owner 406 * 407 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 408 */ 409 sc_err_t sc_pad_get(sc_ipc_t ipc, sc_pad_t pad, uint32_t *val); 410 411 /* @} */ 412 413 /*! 414 * @name Technology Specific Functions 415 * @{ 416 */ 417 418 /*! 419 * This function configures the pad control specific to 28FDSOI. 420 * 421 * @param[in] ipc IPC handle 422 * @param[in] pad pad to configure 423 * @param[in] dse drive strength 424 * @param[in] ps pull select 425 * 426 * @return Returns an error code (SC_ERR_NONE = success). 427 * 428 * Return errors: 429 * - SC_PARM if arguments out of range or invalid, 430 * - SC_ERR_NOACCESS if caller's partition is not the pad owner, 431 * - SC_ERR_UNAVAILABLE if process not applicable 432 * 433 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 434 */ 435 sc_err_t sc_pad_set_gp_28fdsoi(sc_ipc_t ipc, sc_pad_t pad, 436 sc_pad_28fdsoi_dse_t dse, 437 sc_pad_28fdsoi_ps_t ps); 438 439 /*! 440 * This function gets the pad control specific to 28FDSOI. 441 * 442 * @param[in] ipc IPC handle 443 * @param[in] pad pad to query 444 * @param[out] dse pointer to return drive strength 445 * @param[out] ps pointer to return pull select 446 * 447 * @return Returns an error code (SC_ERR_NONE = success). 448 * 449 * Return errors: 450 * - SC_PARM if arguments out of range or invalid, 451 * - SC_ERR_NOACCESS if caller's partition is not the pad owner, 452 * - SC_ERR_UNAVAILABLE if process not applicable 453 * 454 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 455 */ 456 sc_err_t sc_pad_get_gp_28fdsoi(sc_ipc_t ipc, sc_pad_t pad, 457 sc_pad_28fdsoi_dse_t *dse, 458 sc_pad_28fdsoi_ps_t *ps); 459 460 /*! 461 * This function configures the pad control specific to 28FDSOI. 462 * 463 * @param[in] ipc IPC handle 464 * @param[in] pad pad to configure 465 * @param[in] dse drive strength 466 * @param[in] hys hysteresis 467 * @param[in] pus pull-up select 468 * @param[in] pke pull keeper enable 469 * @param[in] pue pull-up enable 470 * 471 * @return Returns an error code (SC_ERR_NONE = success). 472 * 473 * Return errors: 474 * - SC_PARM if arguments out of range or invalid, 475 * - SC_ERR_NOACCESS if caller's partition is not the pad owner, 476 * - SC_ERR_UNAVAILABLE if process not applicable 477 * 478 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 479 */ 480 sc_err_t sc_pad_set_gp_28fdsoi_hsic(sc_ipc_t ipc, sc_pad_t pad, 481 sc_pad_28fdsoi_dse_t dse, sc_bool_t hys, 482 sc_pad_28fdsoi_pus_t pus, sc_bool_t pke, 483 sc_bool_t pue); 484 485 /*! 486 * This function gets the pad control specific to 28FDSOI. 487 * 488 * @param[in] ipc IPC handle 489 * @param[in] pad pad to query 490 * @param[out] dse pointer to return drive strength 491 * @param[out] hys pointer to return hysteresis 492 * @param[out] pus pointer to return pull-up select 493 * @param[out] pke pointer to return pull keeper enable 494 * @param[out] pue pointer to return pull-up enable 495 * 496 * @return Returns an error code (SC_ERR_NONE = success). 497 * 498 * Return errors: 499 * - SC_PARM if arguments out of range or invalid, 500 * - SC_ERR_NOACCESS if caller's partition is not the pad owner, 501 * - SC_ERR_UNAVAILABLE if process not applicable 502 * 503 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 504 */ 505 sc_err_t sc_pad_get_gp_28fdsoi_hsic(sc_ipc_t ipc, sc_pad_t pad, 506 sc_pad_28fdsoi_dse_t *dse, sc_bool_t *hys, 507 sc_pad_28fdsoi_pus_t *pus, sc_bool_t *pke, 508 sc_bool_t *pue); 509 510 /*! 511 * This function configures the compensation control specific to 28FDSOI. 512 * 513 * @param[in] ipc IPC handle 514 * @param[in] pad pad to configure 515 * @param[in] compen compensation/freeze mode 516 * @param[in] fastfrz fast freeze 517 * @param[in] rasrcp compensation code for PMOS 518 * @param[in] rasrcn compensation code for NMOS 519 * @param[in] nasrc_sel NASRC read select 520 * @param[in] psw_ovr 2.5v override 521 * 522 * @return Returns an error code (SC_ERR_NONE = success). 523 * 524 * Return errors: 525 * - SC_PARM if arguments out of range or invalid, 526 * - SC_ERR_NOACCESS if caller's partition is not the pad owner, 527 * - SC_ERR_UNAVAILABLE if process not applicable 528 * 529 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 530 * 531 * Note \a psw_ovr is only applicable to pads supporting 2.5 volt 532 * operation (e.g. some Ethernet pads). 533 */ 534 sc_err_t sc_pad_set_gp_28fdsoi_comp(sc_ipc_t ipc, sc_pad_t pad, 535 uint8_t compen, sc_bool_t fastfrz, 536 uint8_t rasrcp, uint8_t rasrcn, 537 sc_bool_t nasrc_sel, sc_bool_t psw_ovr); 538 539 /*! 540 * This function gets the compensation control specific to 28FDSOI. 541 * 542 * @param[in] ipc IPC handle 543 * @param[in] pad pad to query 544 * @param[out] compen pointer to return compensation/freeze mode 545 * @param[out] fastfrz pointer to return fast freeze 546 * @param[out] rasrcp pointer to return compensation code for PMOS 547 * @param[out] rasrcn pointer to return compensation code for NMOS 548 * @param[out] nasrc_sel pointer to return NASRC read select 549 * @param[out] compok pointer to return compensation status 550 * @param[out] nasrc pointer to return NASRCP/NASRCN 551 * @param[out] psw_ovr pointer to return the 2.5v override 552 * 553 * @return Returns an error code (SC_ERR_NONE = success). 554 * 555 * Return errors: 556 * - SC_PARM if arguments out of range or invalid, 557 * - SC_ERR_NOACCESS if caller's partition is not the pad owner, 558 * - SC_ERR_UNAVAILABLE if process not applicable 559 * 560 * Refer to the SoC [Pad List](@ref PADS) for valid pad values. 561 */ 562 sc_err_t sc_pad_get_gp_28fdsoi_comp(sc_ipc_t ipc, sc_pad_t pad, 563 uint8_t *compen, sc_bool_t *fastfrz, 564 uint8_t *rasrcp, uint8_t *rasrcn, 565 sc_bool_t *nasrc_sel, sc_bool_t *compok, 566 uint8_t *nasrc, sc_bool_t *psw_ovr); 567 568 /* @} */ 569 570 #endif /* SCI_PAD_API_H */ 571 572 /**@}*/ 573