From cbc983f85ca28188a8b7086b50e3895d388682d2 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 23 Sep 2015 14:15:08 +0200 Subject: [PATCH] pinctrl: sh-pfc: Improve pinmux macros documentation Signed-off-by: Geert Uytterhoeven Acked-by: Linus Walleij Reviewed-by: Laurent Pinchart --- drivers/pinctrl/sh-pfc/sh_pfc.h | 96 ++++++++++++++++++++++++++++++--- 1 file changed, 88 insertions(+), 8 deletions(-) diff --git a/drivers/pinctrl/sh-pfc/sh_pfc.h b/drivers/pinctrl/sh-pfc/sh_pfc.h index 2123ab49d6a5..f945c4408015 100644 --- a/drivers/pinctrl/sh-pfc/sh_pfc.h +++ b/drivers/pinctrl/sh-pfc/sh_pfc.h @@ -100,10 +100,31 @@ struct pinmux_cfg_reg { const u8 *var_field_width; }; +/* + * Describe a config register consisting of several fields of the same width + * - name: Register name (unused, for documentation purposes only) + * - r: Physical register address + * - r_width: Width of the register (in bits) + * - f_width: Width of the fixed-width register fields (in bits) + * This macro must be followed by initialization data: For each register field + * (from left to right, i.e. MSB to LSB), 2^f_width enum IDs must be specified, + * one for each possible combination of the register field bit values. + */ #define PINMUX_CFG_REG(name, r, r_width, f_width) \ .reg = r, .reg_width = r_width, .field_width = f_width, \ .enum_ids = (const u16 [(r_width / f_width) * (1 << f_width)]) +/* + * Describe a config register consisting of several fields of different widths + * - name: Register name (unused, for documentation purposes only) + * - r: Physical register address + * - r_width: Width of the register (in bits) + * - var_fw0, var_fwn...: List of widths of the register fields (in bits), + * From left to right (i.e. MSB to LSB) + * This macro must be followed by initialization data: For each register field + * (from left to right, i.e. MSB to LSB), 2^var_fwi enum IDs must be specified, + * one for each possible combination of the register field bit values. + */ #define PINMUX_CFG_REG_VAR(name, r, r_width, var_fw0, var_fwn...) \ .reg = r, .reg_width = r_width, \ .var_field_width = (const u8 [r_width]) \ @@ -116,6 +137,14 @@ struct pinmux_data_reg { const u16 *enum_ids; }; +/* + * Describe a data register + * - name: Register name (unused, for documentation purposes only) + * - r: Physical register address + * - r_width: Width of the register (in bits) + * This macro must be followed by initialization data: For each register bit + * (from left to right, i.e. MSB to LSB), one enum ID must be specified. + */ #define PINMUX_DATA_REG(name, r, r_width) \ .reg = r, .reg_width = r_width, \ .enum_ids = (const u16 [r_width]) \ @@ -124,6 +153,10 @@ struct pinmux_irq { const short *gpios; }; +/* + * Describe the mapping from GPIOs to a single IRQ + * - ids...: List of GPIOs that are mapped to the same IRQ + */ #define PINMUX_IRQ(ids...) \ { .gpios = (const short []) { ids, -1 } } @@ -185,18 +218,65 @@ struct sh_pfc_soc_info { * sh_pfc_soc_info pinmux_data array macros */ +/* + * Describe generic pinmux data + * - data_or_mark: *_DATA or *_MARK enum ID + * - ids...: List of enum IDs to associate with data_or_mark + */ #define PINMUX_DATA(data_or_mark, ids...) data_or_mark, ids, 0 -#define PINMUX_IPSR_NOGP(ispr, fn) \ +/* + * Describe a pinmux configuration without GPIO function that needs + * configuration in a Peripheral Function Select Register (IPSR) + * - ipsr: IPSR field (unused, for documentation purposes only) + * - fn: Function name, referring to a field in the IPSR + */ +#define PINMUX_IPSR_NOGP(ipsr, fn) \ PINMUX_DATA(fn##_MARK, FN_##fn) + +/* + * Describe a pinmux configuration with GPIO function that needs configuration + * in both a Peripheral Function Select Register (IPSR) and in a + * GPIO/Peripheral Function Select Register (GPSR) + * - ipsr: IPSR field + * - fn: Function name, also referring to the IPSR field + */ #define PINMUX_IPSR_DATA(ipsr, fn) \ PINMUX_DATA(fn##_MARK, FN_##fn, FN_##ipsr) -#define PINMUX_IPSR_NOGM(ispr, fn, ms) \ - PINMUX_DATA(fn##_MARK, FN_##fn, FN_##ms) -#define PINMUX_IPSR_NOFN(ipsr, fn, ms) \ - PINMUX_DATA(fn##_MARK, FN_##ipsr, FN_##ms) -#define PINMUX_IPSR_MSEL(ipsr, fn, ms) \ - PINMUX_DATA(fn##_MARK, FN_##ms, FN_##ipsr, FN_##fn) + +/* + * Describe a pinmux configuration without GPIO function that needs + * configuration in a Peripheral Function Select Register (IPSR), and where the + * pinmux function has a representation in a Module Select Register (MOD_SEL). + * - ipsr: IPSR field (unused, for documentation purposes only) + * - fn: Function name, also referring to the IPSR field + * - msel: Module selector + */ +#define PINMUX_IPSR_NOGM(ipsr, fn, msel) \ + PINMUX_DATA(fn##_MARK, FN_##fn, FN_##msel) + +/* + * Describe a pinmux configuration with GPIO function where the pinmux function + * has no representation in a Peripheral Function Select Register (IPSR), but + * instead solely depends on a group selection. + * - gpsr: GPSR field + * - fn: Function name, also referring to the GPSR field + * - gsel: Group selector + */ +#define PINMUX_IPSR_NOFN(gpsr, fn, gsel) \ + PINMUX_DATA(fn##_MARK, FN_##gpsr, FN_##gsel) + +/* + * Describe a pinmux configuration with GPIO function that needs configuration + * in both a Peripheral Function Select Register (IPSR) and a GPIO/Peripheral + * Function Select Register (GPSR), and where the pinmux function has a + * representation in a Module Select Register (MOD_SEL). + * - ipsr: IPSR field + * - fn: Function name, also referring to the IPSR field + * - msel: Module selector + */ +#define PINMUX_IPSR_MSEL(ipsr, fn, msel) \ + PINMUX_DATA(fn##_MARK, FN_##msel, FN_##ipsr, FN_##fn) /* * Describe a pinmux configuration for a single-function pin with GPIO @@ -381,7 +461,7 @@ struct sh_pfc_soc_info { PINMUX_GPIO_FN(GPIO_FN_##str, PINMUX_FN_BASE, str##_MARK) /* - * PORTnCR macro + * PORTnCR helper macro for SH-Mobile/R-Mobile */ #define PORTCR(nr, reg) \ { \ -- 2.20.1