Debian Codegraph @

plat/imx/common/include/sci/svc/pad/sci_pad_api.h

raw
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 overridden
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 control 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 /**@}*/