gpio: Add UNUSED declaration for gpio.inc

This new gpio.inc macro is intended to mark pins that are unused
on a given board. This allows the chip implementation to configure them
for the lowest power configuration.

This CL brings immediate functional change.

A reference implementation is provided for the STM32F4 chip family
in crrev.com/c/1894242.

BRANCH=nocturne,hatch
BUG=b:130561737
TEST=make buildall -j

Change-Id: I0bc0a63401ae8f3bba4108b5b9f9ced26785f2bc
Signed-off-by: Craig Hesling <hesling@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1898796
Reviewed-by: Daisuke Nojiri <dnojiri@chromium.org>

3 files changed, 48 insertions, 0 deletions

diff --git a/include/gpio.h b/include/gpio.h
index 3b1763ae9d..61329ad758 100644
--- a/include/gpio.h
+++ b/include/gpio.h
@@ -99,6 +99,19 @@ struct gpio_info {
 /* Signal information from board.c.  Must match order from enum gpio_signal. */
 extern const struct gpio_info gpio_list[];
 
+/* Unused pin definition structure. */
+struct unused_pin_info {
+	/* Port base address */
+	uint32_t port;
+
+	/* Bitmask on that port (1 << N) */
+	uint32_t mask;
+};
+
+/* Unused pin information. */
+extern const struct unused_pin_info unused_pin_list[];
+extern const int unused_pin_count;
+
 /* Interrupt handler table for those GPIOs which have IRQ handlers.
  *
  * If the signal's interrupt is enabled, this will be called in the
diff --git a/include/gpio.wrap b/include/gpio.wrap
index bc0b47f989..0244b957b7 100644
--- a/include/gpio.wrap
+++ b/include/gpio.wrap
@@ -91,6 +91,20 @@
 #define UNIMPLEMENTED(name)
 #endif
 
+/**
+ * @def UNUSED
+ * @brief The UNUSED macro is used to define a pin as unused.
+ *
+ * This allows the chip specific code to provision these pins for
+ * the lowest power state.
+ * We don't want to automatically provision all unreferenced pins/ports
+ * as unused, since this may alter the behavior of existing firmwares in
+ * ways that may not be obvious to the developer.
+ */
+#ifndef UNUSED
+#define UNUSED(pin)
+#endif
+
 /*
  * RO/RW pin macro.
  *
@@ -109,6 +123,8 @@
 #define ALTERNATE_RW(pinmask, function, module, flags)
 #define UNIMPLEMENTED_RO(name) UNIMPLEMENTED(name)
 #define UNIMPLEMENTED_RW(name)
+#define UNUSED_RO(name) UNUSED(name)
+#define UNUSED_RW(name)
 #elif defined(SECTION_IS_RW)
 #define GPIO_RO(name, pin, flags)
 #define GPIO_RW(name, pin, flags) GPIO(name, pin, flags)
@@ -119,6 +135,8 @@
 		ALTERNATE(pinmask, function, module, flags)
 #define UNIMPLEMENTED_RO(name)
 #define UNIMPLEMENTED_RW(name) UNIMPLEMENTED(name)
+#define UNUSED_RO(name)
+#define UNUSED_RW(name) UNUSED(name)
 #else
 #define GPIO_RO(name, pin, flags) GPIO(name, pin, flags)
 #define GPIO_RW(name, pin, flags) GPIO(name, pin, flags)
@@ -130,6 +148,8 @@
 		ALTERNATE(pinmask, function, module, flags)
 #define UNIMPLEMENTED_RO(name) UNIMPLEMENTED(name)
 #define UNIMPLEMENTED_RW(name) UNIMPLEMENTED(name)
+#define UNUSED_RO(name) UNUSED(name)
+#define UNUSED_RW(name) UNUSED(name)
 #endif
 
 #ifndef IOEX
@@ -144,6 +164,8 @@
 
 /*
  * Once the gpio.inc file has been included these macros are no longer needed.
+ * This allows the includer to redefine these macros and include this file
+ * again, within the same file.
  */
 #undef GPIO
 #undef GPIO_RO
@@ -157,6 +179,9 @@
 #undef UNIMPLEMENTED
 #undef UNIMPLEMENTED_RO
 #undef UNIMPLEMENTED_RW
+#undef UNUSED
+#undef UNUSED_RO
+#undef UNUSED_RW
 
 #undef IOEX
 #undef IOEX_INT
diff --git a/include/gpio_list.h b/include/gpio_list.h
index 180841bb9b..37d49a6f97 100644
--- a/include/gpio_list.h
+++ b/include/gpio_list.h
@@ -23,6 +23,14 @@ const struct gpio_info gpio_list[] = {
 
 BUILD_ASSERT(ARRAY_SIZE(gpio_list) == GPIO_COUNT);
 
+#define UNUSED(pin) {GPIO_##pin},
+/* Unconnected pin list. */
+const struct unused_pin_info unused_pin_list[] = {
+	#include "gpio.wrap"
+};
+
+const int unused_pin_count = ARRAY_SIZE(unused_pin_list);
+
 /* GPIO Interrupt Handlers */
 #define GPIO_INT(name, pin, flags, signal) signal,
 void (* const gpio_irq_handlers[])(enum gpio_signal signal) = {
@@ -45,7 +53,9 @@ const int gpio_ih_count = ARRAY_SIZE(gpio_irq_handlers);
  */
 #define GPIO(name, pin, flags) pin
 #define GPIO_INT(name, pin, flags, signal) pin
+#define UNUSED(pin) pin
 /*
+ * Check at build time that pin/ports are only defined once.
  * The compiler will complain if we use the same name twice. The linker ignores
  * anything that gets by.
  */