1 /* SPDX-License-Identifier: GPL-2.0-or-later */
12  * functions. The SoC function enabled on a pin is determined on a priority
17  * bits. Some difficulty arises as the pin's function bit masks for each
22  * read-only).
24  * SoC Multi-function Pin Expression Examples
25  * ------------------------------------------
31  * D6 is a pin with a single function (beside GPIO); a high priority signal
32  * that participates in one function:
35  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
37  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
39  * C5 is a multi-signal pin (high and low priority signals). Here we touch
42  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
44  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
46  * E19 is a single-signal pin with two functions that influence the active
47  * signal. In this case both bits have the same meaning - enable a dedicated
49  * OR-relationship have the same meaning.
51  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
53  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
55  * For example, pin B19 has a low-priority signal that's enabled by two
59  * priority function must be disabled for GPIOF1 to be used.
62 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
64 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
69  * * SCU3C[3]: Enable external SOC reset function
70  * * SCU80[15]: Enable SPICS1# or EXTRST# function pin
73 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
75 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
80  * Pin T5 is a multi-signal pin with a more complex configuration:
83  * -----+---------+-----------+------------------------------+-----------+---------------+----------
85  * -----+---------+-----------+------------------------------+-----------+---------------+----------
95  * Re-writing:
97  * -----+---------+-----------+------------------------------+-----------+---------------+----------
101  * -----+---------+-----------+------------------------------+-----------+---------------+----------
104  * function pin", where the signal itself is determined by whether SCU94[5:4]
107  * Other video-input-related pins require an explicit state in SCU90[5:4], e.g.
110  * -----+---------+-----------+------------------------------+-----------+---------------+----------
113  * -----+---------+-----------+------------------------------+-----------+---------------+----------
120  * signals are required. However, this isn't done consistently - UART1 is
121  * enabled on a per-pin basis, and by contrast, all signals for UART6 are
126  * function, but the UART signals should retain the ability to be configured
128  * signal's expressions with the function they participate in, rather than
129  * defining masks affecting multiple signals per function. The latter approach
135 …* -----+------------+-----------+---------------------------+-----------+---------------+---------…
138 …* -----+------------+-----------+---------------------------+-----------+---------------+---------…
140  * A12 demonstrates that the "Other" signal isn't always GPIO - in this case
141  * GPIOT0 is a high-priority signal and RGMII1TXCK is Other. Thus, GPIO
142  * should be treated like any other signal type with full function expression
145  * pins in the function's group to disable the higher-priority signals such
146  * that the signal for the function of interest is correctly enabled.
165  * * A function represents a set of signals; functions are distinct if they
171  * * A function is described by an expression of one or more signal
177  * * A signal participating in a function is active on a pin if evaluating all
178  *   signal descriptors in the pin's signal expression for the function yields
185  * * GPIO is configured per-pin
189  * * To disable a signal, any function(s) activating the signal must be
193  *   participates, for the purpose of enabling the Other function. This is done
203  * * The NDCD1 signal participates in just its own NDCD1 function
215  * --------------
217  * If pinctrl allows us to allocate a pin we can configure a function without
218  * concern for the function of already allocated pins, if pin groups are
222  * Conversely, failing to allocate all pins in a group indicates some bits (as
223  * well as pins) required for the group's configuration will already be in use,
225  * group.
228  * --------------
239  * 1. Use a data-driven solution rather than embedding state into code
245  * the group and the function. In this way copy/paste errors cause duplicate
249  * no override errors in the pin, group and function arrays.
255  * Here's a complete, concrete "pre-processed" example of the table structures
271  *     .function = "MAC1LINK",
285  *     .function = "GPIOA0",
336  * Ball E18 demonstrates a function, EXTRST, that requires multiple descriptors
366  *     .function = "EXTRST",
388  *     .function = "LPCRST",
405  *     .function = "LPCRSTS",
437   * @enable: The value that enables the function. Value should be in the LSBs,
439   * @disable: The value that disables the function. Value should be in the
457  * @function: The name of the function the signal participates in for the
458  *            associated expression. For pin-specific GPIO, the function
462  *         function expression
466 	const char *function;  member
492  * Short-hand macro for describing an SCU descriptor enabled by the state of
497  * @val: The value (0 or 1) that enables the function
505  * A further short-hand macro expanding to an SCU descriptor enabled by a set
514 #define SIG_DESC_LIST_SYM(sig, group) sig_descs_ ## sig ## _ ## group  argument
515 #define SIG_DESC_LIST_DECL(sig, group, ...) \  argument
516 	static const struct aspeed_sig_desc SIG_DESC_LIST_SYM(sig, group)[] = \
519 #define SIG_EXPR_SYM(sig, group) sig_expr_ ## sig ## _ ## group  argument
520 #define SIG_EXPR_DECL_(sig, group, func) \  argument
521 	static const struct aspeed_sig_expr SIG_EXPR_SYM(sig, group) = \
524 		.function = #func, \
525 		.ndescs = ARRAY_SIZE(SIG_DESC_LIST_SYM(sig, group)), \
526 		.descs = &(SIG_DESC_LIST_SYM(sig, group))[0], \
534  * @func: The function in which the signal is participating
537  * For example, the following declares the ROMD8 signal for the ROM16 function:
546 #define SIG_EXPR_DECL(sig, group, func, ...) \  argument
547 	SIG_DESC_LIST_DECL(sig, group, __VA_ARGS__); \
548 	SIG_EXPR_DECL_(sig, group, func)
554  * @func: The macro symbol name for the function (subjected to token pasting)
556 #define SIG_EXPR_PTR(sig, group) (&SIG_EXPR_SYM(sig, group))  argument
558 #define SIG_EXPR_LIST_SYM(sig, group) sig_exprs_ ## sig ## _ ## group  argument
566  * For example, the 16-bit ROM bus can be enabled by one of two possible signal
575 #define SIG_EXPR_LIST_DECL(sig, group, ...) \  argument
576 	static const struct aspeed_sig_expr *SIG_EXPR_LIST_SYM(sig, group)[] =\
583  * Create an expression symbol alias from (signal, group) to (pin, signal).
587  * @group: The name of the group of which the pin is a member that is
588  *         associated with the function's signal
591  * the signal for a group multiple times) whilst enabling multiple pin groups
592  * to exist for a signal without intrusive side-effects on defining the list of
595 #define SIG_EXPR_LIST_ALIAS(pin, sig, group) \  argument
597 		SIG_EXPR_LIST_SYM(pin, sig)[ARRAY_SIZE(SIG_EXPR_LIST_SYM(sig, group))] \
598 		__attribute__((alias(istringify(SIG_EXPR_LIST_SYM(sig, group)))))
601  * A short-hand macro for declaring a function expression and an expression
602  * list with a single expression (SE) and a single group (SG) of pins.
605  * @sig: The signal that will be routed to the pin for the function
606  * @func: A macro symbol name for the function
607  * @...: Function descriptors that define the function expression
609  * For example, signal NCTS6 participates in its own function with one group:
624  * @sig: The signal that will be routed to the pin for the function
625  * @group: The name of the function's pin group in which the pin participates
626  * @func: A macro symbol name for the function
627  * @...: Function descriptors that define the function expression
629 #define SIG_EXPR_LIST_DECL_SEMG(pin, sig, group, func, ...) \  argument
630 	SIG_DESC_LIST_DECL(sig, group, __VA_ARGS__); \
631 	SIG_EXPR_DECL_(sig, group, func); \
632 	SIG_EXPR_LIST_DECL(sig, group, SIG_EXPR_PTR(sig, group)); \
633 	SIG_EXPR_LIST_ALIAS(pin, sig, group)
637  * and a single group (SG) of pins.
640  * @sig: The signal that will be routed to the pin for the function
641  * @group: The name of the function's pin group in which the pin participates
642  * @func: A macro symbol name for the function
643  * @...: Function descriptors that define the function expression
651 #define SIG_EXPR_LIST_PTR(sig, group) SIG_EXPR_LIST_SYM(sig, group)  argument
682  * Single signal, single function pin declaration
687  * @...: Signal descriptors that define the function expression
700  * Declare a two-signal pin
733 #define GROUP_SYM(group) group_pins_ ## group  argument
734 #define GROUP_DECL(group, ...) \  argument
735 	static const int GROUP_SYM(group)[] = { __VA_ARGS__ }
741 #define FUNC_DECL_1(func, group) FUNC_DECL_(func, #group)  argument
810 	return ctx->ops->set(ctx, expr, enabled);  in aspeed_sig_expr_set()