1 /* SPDX-License-Identifier: GPL-2.0-or-later */
11  * functions. The SoC function enabled on a pin is determined on a priority
16  * bits. Some difficulty arises as the pin's function bit masks for each
21  * read-only).
23  * SoC Multi-function Pin Expression Examples
24  * ------------------------------------------
30  * D6 is a pin with a single function (beside GPIO); a high priority signal
31  * that participates in one function:
34  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
36  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
38  * C5 is a multi-signal pin (high and low priority signals). Here we touch
41  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
43  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
45  * E19 is a single-signal pin with two functions that influence the active
46  * signal. In this case both bits have the same meaning - enable a dedicated
48  * OR-relationship have the same meaning.
50  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
52  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
54  * For example, pin B19 has a low-priority signal that's enabled by two
58  * priority function must be disabled for GPIOF1 to be used.
61 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
63 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
68  * * SCU3C[3]: Enable external SOC reset function
69  * * SCU80[15]: Enable SPICS1# or EXTRST# function pin
72 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
74 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
79  * Pin T5 is a multi-signal pin with a more complex configuration:
82  * -----+---------+-----------+------------------------------+-----------+---------------+----------
84  * -----+---------+-----------+------------------------------+-----------+---------------+----------
94  * Re-writing:
96  * -----+---------+-----------+------------------------------+-----------+---------------+----------
100  * -----+---------+-----------+------------------------------+-----------+---------------+----------
103  * function pin", where the signal itself is determined by whether SCU94[5:4]
106  * Other video-input-related pins require an explicit state in SCU90[5:4], e.g.
109  * -----+---------+-----------+------------------------------+-----------+---------------+----------
112  * -----+---------+-----------+------------------------------+-----------+---------------+----------
119  * signals are required. However, this isn't done consistently - UART1 is
120  * enabled on a per-pin basis, and by contrast, all signals for UART6 are
125  * function, but the UART signals should retain the ability to be configured
127  * signal's expressions with the function they participate in, rather than
128  * defining masks affecting multiple signals per function. The latter approach
134 …* -----+------------+-----------+---------------------------+-----------+---------------+---------…
137 …* -----+------------+-----------+---------------------------+-----------+---------------+---------…
139  * A12 demonstrates that the "Other" signal isn't always GPIO - in this case
140  * GPIOT0 is a high-priority signal and RGMII1TXCK is Other. Thus, GPIO
141  * should be treated like any other signal type with full function expression
144  * pins in the function's group to disable the higher-priority signals such
145  * that the signal for the function of interest is correctly enabled.
164  * * A function represents a set of signals; functions are distinct if they
170  * * A function is described by an expression of one or more signal
176  * * A signal participating in a function is active on a pin if evaluating all
177  *   signal descriptors in the pin's signal expression for the function yields
184  * * GPIO is configured per-pin
188  * * To disable a signal, any function(s) activating the signal must be
192  *   participates, for the purpose of enabling the Other function. This is done
202  * * The NDCD1 signal participates in just its own NDCD1 function
214  * --------------
216  * If pinctrl allows us to allocate a pin we can configure a function without
217  * concern for the function of already allocated pins, if pin groups are
221  * Conversely, failing to allocate all pins in a group indicates some bits (as
222  * well as pins) required for the group's configuration will already be in use,
224  * group.
227  * --------------
238  * 1. Use a data-driven solution rather than embedding state into code
244  * the group and the function. In this way copy/paste errors cause duplicate
248  * no override errors in the pin, group and function arrays.
254  * Here's a complete, concrete "pre-processed" example of the table structures
270  *     .function = "MAC1LINK",
284  *     .function = "GPIOA0",
335  * Ball E18 demonstrates a function, EXTRST, that requires multiple descriptors
365  *     .function = "EXTRST",
387  *     .function = "LPCRST",
404  *     .function = "LPCRSTS",
436   * @enable: The value that enables the function. Value should be in the LSBs,
438   * @disable: The value that disables the function. Value should be in the
456  * @function: The name of the function the signal participates in for the
457  *            associated expression. For pin-specific GPIO, the function
461  *         function expression
465 	const char *function;  member
491  * Short-hand macro for describing an SCU descriptor enabled by the state of
496  * @val: The value (0 or 1) that enables the function
504  * A further short-hand macro expanding to an SCU descriptor enabled by a set
513 #define SIG_DESC_LIST_SYM(sig, group) sig_descs_ ## sig ## _ ## group  argument
514 #define SIG_DESC_LIST_DECL(sig, group, ...) \  argument
515 	static const struct aspeed_sig_desc SIG_DESC_LIST_SYM(sig, group)[] = \
518 #define SIG_EXPR_SYM(sig, group) sig_expr_ ## sig ## _ ## group  argument
519 #define SIG_EXPR_DECL_(sig, group, func) \  argument
520 	static const struct aspeed_sig_expr SIG_EXPR_SYM(sig, group) = \
523 		.function = #func, \
524 		.ndescs = ARRAY_SIZE(SIG_DESC_LIST_SYM(sig, group)), \
525 		.descs = &(SIG_DESC_LIST_SYM(sig, group))[0], \
533  * @func: The function in which the signal is participating
536  * For example, the following declares the ROMD8 signal for the ROM16 function:
545 #define SIG_EXPR_DECL(sig, group, func, ...) \  argument
546 	SIG_DESC_LIST_DECL(sig, group, __VA_ARGS__); \
547 	SIG_EXPR_DECL_(sig, group, func)
553  * @func: The macro symbol name for the function (subjected to token pasting)
555 #define SIG_EXPR_PTR(sig, group) (&SIG_EXPR_SYM(sig, group))  argument
557 #define SIG_EXPR_LIST_SYM(sig, group) sig_exprs_ ## sig ## _ ## group  argument
565  * For example, the 16-bit ROM bus can be enabled by one of two possible signal
574 #define SIG_EXPR_LIST_DECL(sig, group, ...) \  argument
575 	static const struct aspeed_sig_expr *SIG_EXPR_LIST_SYM(sig, group)[] =\
582  * Create an expression symbol alias from (signal, group) to (pin, signal).
586  * @group: The name of the group of which the pin is a member that is
587  *         associated with the function's signal
590  * the signal for a group multiple times) whilst enabling multiple pin groups
591  * to exist for a signal without intrusive side-effects on defining the list of
594 #define SIG_EXPR_LIST_ALIAS(pin, sig, group) \  argument
596 		SIG_EXPR_LIST_SYM(pin, sig)[ARRAY_SIZE(SIG_EXPR_LIST_SYM(sig, group))] \
597 		__attribute__((alias(istringify(SIG_EXPR_LIST_SYM(sig, group)))))
600  * A short-hand macro for declaring a function expression and an expression
601  * list with a single expression (SE) and a single group (SG) of pins.
604  * @sig: The signal that will be routed to the pin for the function
605  * @func: A macro symbol name for the function
606  * @...: Function descriptors that define the function expression
608  * For example, signal NCTS6 participates in its own function with one group:
623  * @sig: The signal that will be routed to the pin for the function
624  * @group: The name of the function's pin group in which the pin participates
625  * @func: A macro symbol name for the function
626  * @...: Function descriptors that define the function expression
628 #define SIG_EXPR_LIST_DECL_SEMG(pin, sig, group, func, ...) \  argument
629 	SIG_DESC_LIST_DECL(sig, group, __VA_ARGS__); \
630 	SIG_EXPR_DECL_(sig, group, func); \
631 	SIG_EXPR_LIST_DECL(sig, group, SIG_EXPR_PTR(sig, group)); \
632 	SIG_EXPR_LIST_ALIAS(pin, sig, group)
636  * and a single group (SG) of pins.
639  * @sig: The signal that will be routed to the pin for the function
640  * @group: The name of the function's pin group in which the pin participates
641  * @func: A macro symbol name for the function
642  * @...: Function descriptors that define the function expression
650 #define SIG_EXPR_LIST_PTR(sig, group) SIG_EXPR_LIST_SYM(sig, group)  argument
681  * Single signal, single function pin declaration
686  * @...: Signal descriptors that define the function expression
699  * Declare a two-signal pin
741 #define GROUP_SYM(group) group_pins_ ## group  argument
742 #define GROUP_DECL(group, ...) \  argument
743 	static const int GROUP_SYM(group)[] = { __VA_ARGS__ }
749 #define FUNC_DECL_1(func, group) FUNC_DECL_(func, #group)  argument
818 	return ctx->ops->set(ctx, expr, enabled);  in aspeed_sig_expr_set()