IO_Expander: introduce the common interface of IO expander

Implement the common code to provide a friendly interface to control the
IOs of IO expander. It adopts a similar concept to GPIO.

1. Define the IO expander IO in gpio.inc by the format:
    IOEX(name, EXPIN(ioex, port, offset), flags)
    - name: the name of this IO pin
    - EXPIN(ioex, port, offset)
        - ioex: the IO expander port (defined in board.c) this IO
                     pin belongs to.
        - port: the port number in the IO expander chip.
	- offset: the bit offset in the port above.
    - flags: the same as the flags of GPIO.

2. The following APIs are supported:
    1. ioex_get_flags_by_mask
    2. ioex_set_flags_by_mask
    3. ioex_get_flags
    4. ioex_set_flags
    5. ioex_get_level
    6. ioex_set_level
    7. ioex_init

3. The following console commands are supported:
    1. ioexget [IO_EXPANDER_PIN_NAME]
    2. ioexset IO_EXPANDER_PIN_NAME 0/1

BRANCH=none
BUG=none
TEST=No error for "make buildall"
TEST=Apply this and related CLs, manually test each API, make sure each
function works correctly with IO expander chip (NCT3807/NCT3808.)

Change-Id: I79c9813abccc67d5554e2ceb5c119dcf549b7dce
Signed-off-by: CHLin <CHLIN56@nuvoton.com>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1657858
Reviewed-by: Daisuke Nojiri <dnojiri@chromium.org>
Reviewed-by: Aseda Aboagye <aaboagye@chromium.org>
Commit-Queue: CH Lin <chlin56@nuvoton.com>
Commit-Queue: Aseda Aboagye <aaboagye@chromium.org>
Tested-by: CH Lin <chlin56@nuvoton.com>

5 files changed, 205 insertions, 0 deletions

diff --git a/include/config.h b/include/config.h
index d1a4dfc8d0..1eae83dc1a 100644
--- a/include/config.h
+++ b/include/config.h
@@ -1260,6 +1260,22 @@
 #undef CONFIG_COMMON_GPIO_SHORTNAMES
 
 /*
+ * Control the IO pins of IO expander via IO Expander APIs
+ *
+ * If defined, declare the IOEX pin with macro IOEX. For example:
+ *     IOEX(IO_NAME, EXPIN(0, 0, 0), GPIO_OUT_HIGH)
+ * For more details, see gpio_list.h.
+ *
+ * WARNING: make sure none of IOEX IOs are accessed at interrupt level / with
+ * interrupts disabled. Doing so may hang the EC because IO expanders may rely
+ * on I2C interrupts.
+ *
+ * Some reasons that not unify the GPIO and IOEX APIs have been disscussed and
+ * filed in the crbug.com/985540.
+ */
+#undef CONFIG_IO_EXPANDER
+
+/*
  * EC's supporting powering down GPIO pins.
  * Add flag GPIO_POWER_DOWN and additional API's.
  */
@@ -2259,6 +2275,9 @@
 /* Support NXP PCA9534 I/O expander. */
 #undef CONFIG_IO_EXPANDER_PCA9534
 
+/* Number of IO Expander ports */
+#undef CONFIG_IO_EXPANDER_PORT_COUNT
+
 /*****************************************************************************/
 
 /* Number of IRQs supported on the EC chip */
diff --git a/include/gpio.wrap b/include/gpio.wrap
index e2bdabda7b..1e018f2ed2 100644
--- a/include/gpio.wrap
+++ b/include/gpio.wrap
@@ -114,6 +114,10 @@
 #define UNIMPLEMENTED_RW(name) UNIMPLEMENTED(name)
 #endif
 
+#ifndef IOEX
+#define IOEX(name, expin, flags)
+#endif
+
 #include "gpio.inc"
 
 /*
@@ -131,3 +135,5 @@
 #undef UNIMPLEMENTED
 #undef UNIMPLEMENTED_RO
 #undef UNIMPLEMENTED_RW
+
+#undef IOEX
diff --git a/include/gpio_list.h b/include/gpio_list.h
index 70d7bfc4b2..4fed0d60d6 100644
--- a/include/gpio_list.h
+++ b/include/gpio_list.h
@@ -52,3 +52,39 @@ const int gpio_ih_count = ARRAY_SIZE(gpio_irq_handlers);
 #define PIN(a, b...) static const int _pin_ ## a ## _ ## b \
 	__attribute__((unused, section(".unused"))) = __LINE__;
 #include "gpio.wrap"
+
+#include "ioexpander.h"
+/*
+ *  Define the IO expander IO in gpio.inc by the format:
+ *    IOEX(name, EXPIN(ioex_port, port, offset), flags)
+ *      - name: the name of this IO pin
+ *      - EXPIN(ioex, port, offset)
+ *         - ioex: the IO expander port (defined in board.c) this IO
+ *                 pin belongs to.
+ *         - port: the port number in the IO expander chip.
+ *         - offset: the bit offset in the port above.
+ *      - flags: the same as the flags of GPIO.
+ *
+ */
+#define IOEX_EXPIN(ioex, port, index) (ioex), (port), BIT(index)
+
+#define IOEX(name, expin, flags) {#name, IOEX_##expin, flags},
+
+/* IO expander signal list. */
+const struct ioex_info ioex_list[] = {
+	#include "gpio.wrap"
+};
+BUILD_ASSERT(ARRAY_SIZE(ioex_list) == IOEX_COUNT);
+
+#define IOEX(name, expin, flags) expin
+
+/* The compiler will complain if we use the same name twice or the controller
+ * number declared is greater or equal to CONFIG_IO_EXPANDER_PORT_COUNT.
+ * The linker ignores anything that gets by.
+ */
+#define EXPIN(a, b, c...) \
+	static const int _expin_ ## a ## _ ## b ## _ ## c \
+	__attribute__((unused, section(".unused"))) = __LINE__; \
+	BUILD_ASSERT(a < CONFIG_IO_EXPANDER_PORT_COUNT);
+
+#include "gpio.wrap"
diff --git a/include/gpio_signal.h b/include/gpio_signal.h
index 776e84fdae..da34f07b33 100644
--- a/include/gpio_signal.h
+++ b/include/gpio_signal.h
@@ -15,4 +15,11 @@ enum gpio_signal {
 	GPIO_COUNT
 };
 
+#define IOEX(name, expin, flags) IOEX_##name,
+
+enum ioex_signal {
+	#include "gpio.wrap"
+	IOEX_COUNT
+};
+
 #endif /* __CROS_EC_GPIO_SIGNAL_H */
diff --git a/include/ioexpander.h b/include/ioexpander.h
new file mode 100644
index 0000000000..2a31eb6aaa
--- /dev/null
+++ b/include/ioexpander.h
@@ -0,0 +1,137 @@
+/*
+ * Copyright 2019 The Chromium OS Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef __CROS_EC_IOEXPANDER_H
+#define __CROS_EC_IOEXPANDER_H
+
+/* IO expander signal definition structure */
+struct ioex_info {
+	/* Signal name */
+	const char *name;
+
+	/* IO expander port number */
+	uint16_t ioex;
+
+	/* IO port number in IO expander */
+	uint16_t port;
+
+	/* Bitmask on that port (1 << N) */
+	uint32_t mask;
+
+	/* Flags - the same as the GPIO flags */
+	uint32_t flags;
+};
+
+/* Signal information from board.c.  Must match order from enum ioex_signal. */
+extern const struct ioex_info ioex_list[];
+
+struct ioexpander_drv {
+	/* Initialize IO expander chip/driver */
+	int (*init)(int ioex);
+	/* Get the current level of the IOEX pin */
+	int (*get_level)(int ioex, int port, int mask, int *val);
+	/* Set the level of the IOEX pin */
+	int (*set_level)(int ioex, int port, int mask, int val);
+	/* Get flags for the IOEX pin */
+	int (*get_flags_by_mask)(int ioex, int port, int mask, int *flags);
+	/* Set flags for the IOEX pin */
+	int (*set_flags_by_mask)(int ioex, int port, int mask, int flags);
+};
+
+struct ioexpander_config_t {
+	/* Physical I2C port connects to the IO expander chip. */
+	int i2c_host_port;
+	/* I2C slave address */
+	int i2c_slave_addr;
+	/*
+	 * The extra variable used to store information which may be required
+	 * by the IO expander chip.
+	 */
+	int chip_info;
+	/*
+	 * Pointer to the specific IO expander chip's ops defined in
+	 * the struct ioexpander_drv.
+	 */
+	const struct ioexpander_drv *drv;
+};
+
+extern struct ioexpander_config_t ioex_config[];
+
+/*
+ * Get flags for the IOEX pin by mask
+ *
+ * @param ioex		IO expander chip's port number
+ * @param port		IO port in the IO expander chip
+ * @param mask		Bitmask of the pin on the port above
+ * @param flags		Pointer to the keep the flags read
+ * @return			EC_SUCCESS if successful, non-zero if error.
+ */
+int ioex_get_flags_by_mask(int ioex, int port, int mask, int *flags);
+
+/*
+ * Set flags for the IOEX pin by mask
+ *
+ * @param ioex		IO expander chip's port number
+ * @param port		IO port in the IO expander chip
+ * @param mask		Bitmask of the pin on the port above
+ * @param flags		flags to set
+ * @return			EC_SUCCESS if successful, non-zero if error.
+ */
+int ioex_set_flags_by_mask(int ioex, int port, int mask, int flags);
+
+/*
+ * Get flags for the IOEX signal
+ *
+ * @param signal	IOEX signal to get flags for
+ * @param flags		Pointer to the keep the flags read
+ * @return			EC_SUCCESS if successful, non-zero if error.
+ */
+int ioex_get_flags(enum ioex_signal signal, int *flags);
+
+/*
+ * Set flags for the IOEX signal
+ *
+ * @param signal	IOEX signal to set flags for
+ * @param flags		New flags for the IOEX signal
+ * @return			EC_SUCCESS if successful, non-zero if error.
+ */
+int ioex_set_flags(enum ioex_signal signal, int flags);
+
+/*
+ * Get the current level of the IOEX signal
+ *
+ * @param signal	IOEX signal to get the level
+ * @param val		Pointer to the keep the level read
+ * @return			EC_SUCCESS if successful, non-zero if error.
+ */
+int ioex_get_level(enum ioex_signal signal, int *val);
+
+/*
+ * Set the level of the IOEX signal
+ *
+ * @param signal	IOEX signal to set the level
+ * @param value		New level for the IOEX signal
+ * @return			EC_SUCCESS if successful, non-zero if error.
+ */
+int ioex_set_level(enum ioex_signal signal, int value);
+
+/*
+ * Initialize IO expander chip/driver
+ *
+ * @param ioex		IO expander chip's port number
+ * @return			EC_SUCCESS if successful, non-zero if error.
+ */
+int ioex_init(int ioex);
+
+/*
+ * Get the name for the IOEX signal
+ *
+ * @param signal	IOEX signal to get the name
+ * @returns name of the given IOEX signal
+ */
+const char *ioex_get_name(enum ioex_signal signal);
+#endif /* __CROS_EC_IOEXPANDER_H */
+