1 /* SPDX-License-Identifier: GPL-2.0-or-later */
12  * basis where a given pin can provide a number of different signal types.
14  * The signal active on a pin is described by both a priority level and
18  * change from a high to low priority signal), or even in the same register.
21  * read-only).
23  * SoC Multi-function Pin Expression Examples
24  * ------------------------------------------
28  * corner. The signal priorities are in decending order from P0 (highest).
30  * D6 is a pin with a single function (beside GPIO); a high priority signal
33  * Ball | Default | P0 Signal | P0 Expression               | P1 Signal | P1 Expression | Other
34  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
36  * -----+---------+-----------+-----------------------------+-----------+---------------+----------
38  * C5 is a multi-signal pin (high and low priority signals). Here we touch
39  * different registers for the different functions that enable each signal:
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
60 …* Ball | Default | P0 Signal | P0 Expression                           | P1 Signal | P1 Expression…
61 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
63 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
66  * pin's active signal:
72 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
74 …* -----+---------+-----------+-----------------------------------------+-----------+--------------…
79  * Pin T5 is a multi-signal pin with a more complex configuration:
81  * Ball | Default | P0 Signal | P0 Expression                | P1 Signal | P1 Expression | Other
82  * -----+---------+-----------+------------------------------+-----------+---------------+----------
84  * -----+---------+-----------+------------------------------+-----------+---------------+----------
86  * The high priority signal configuration is best thought of in terms of its
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  * -----+---------+-----------+------------------------------+-----------+---------------+----------
115  * that despite operating as part of the video input bus each signal needs to
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
127  * signal's expressions with the function they participate in, rather than
133  * Ball |  Default   | P0 Signal | P0 Expression             | P1 Signal | P1 Expression | Other
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
143  * GPIOT1's signal descriptor bits are distinct, therefore we must iterate all
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.
157  * * Pins provide up to five signal types in a priority order
159  * * For priorities levels defined on a pin, each priority provides one signal
170  * * A function is described by an expression of one or more signal
173  * * A signal expression is the smallest set of signal descriptors whose
174  *   comparisons must evaluate 'true' for a signal to be enabled on a pin.
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
180  * * A signal at a given priority on a given pin is active if any of the
181  *   functions in which the signal participates are active, and no higher
182  *   priority signal on the pin is active
184  * * GPIO is configured per-pin
188  * * To disable a signal, any function(s) activating the signal must be
191  * * Each pin must know the signal expressions of functions in which it
200  * * The VPIDE signal participates in 3 functions: VPI18, VPI24 and VPI30
202  * * The NDCD1 signal participates in just its own NDCD1 function
207  * * The prerequisit for activating the NDCD1 signal is that the VPI18, VPI24
214  * --------------
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
243  * properties associated with a given mux configuration: The pin, the signal,
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
269  *     .signal = "MAC1LINK",
283  *     .signal = "GPIOA0",
364  *     .signal = "EXTRST",
372  * For ball E19, we have multiple functions enabling a single signal, LPCRST#.
386  *     .signal = "LPCRST",
403  *     .signal = "LPCRST",
428   * A signal descriptor, which describes the register, bits and the
450  * Describes a signal expression. The expression is evaluated by ANDing the
453  * @signal: The signal name for the priority level on the pin. If the signal
454  *          type is GPIO, then the signal name must begin with the
456  * @function: The name of the function the signal participates in for the
457  *            associated expression. For pin-specific GPIO, the function
458  *            name must match the signal name.
459  * @ndescs: The number of signal descriptors in the expression
460  * @descs: Pointer to an array of signal descriptors that comprise the
464 	const char *signal;  member
472  * for a given pin. The signal configuration for a priority level is evaluated
473  * by ORing the evaluation of the signal expressions in the respective
491  * Short-hand macro for describing an SCU descriptor enabled by the state of
494  * @reg: The signal's associated register, offset from base
495  * @idx: The signal's bit index in the register
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) = \
522 		.signal = #sig, \
524 		.ndescs = ARRAY_SIZE(SIG_DESC_LIST_SYM(sig, group)), \
525 		.descs = &(SIG_DESC_LIST_SYM(sig, group))[0], \
529  * Declare a signal expression.
531  * @sig: A macro symbol name for the signal (is subjected to stringification
533  * @func: The function in which the signal is participating
534  * @...: Signal descriptors that define the signal expression
536  * For example, the following declares the ROMD8 signal for the ROM16 function:
540  * And with multiple signal descriptors:
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)
550  * Declare a pointer to a signal expression
552  * @sig: The macro symbol name for the signal (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
560  * Declare a signal expression list for reference in a struct aspeed_pin_prio.
562  * @sig: A macro symbol name for the signal (is subjected to token pasting)
563  * @...: Signal expression structure pointers (use SIG_EXPR_PTR())
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).
585  * @sig: The signal name
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.
603  * @pin: The pin the signal will be routed to
604  * @sig: The signal that will be routed to the pin for the function
608  * For example, signal NCTS6 participates in its own function with one group:
622  * @pin: The pin the signal will be routed to
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
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.
638  * @pin: The pin the signal will be routed to
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
650 #define SIG_EXPR_LIST_PTR(sig, group) SIG_EXPR_LIST_SYM(sig, group)  argument
663  * Declare a single signal pin
667  * @sig: Macro name for the signal (subjected to stringification)
681  * Single signal, single function pin declaration
685  * @sig: Macro name for the signal (subjected to stringification)
686  * @...: Signal descriptors that define the function expression
699  * Declare a two-signal pin
703  * @high: Macro name for the highest priority signal functions
704  * @low: Macro name for the low signal functions
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()