cleanup: Add warning comment to gpio.inc files

With commit e9883124ff16, a GPIO_INT macro was added. That change
also required that all instances of GPIO_INT in a board's
gpio.inc file come before any GPIO macros, or the interrupt
handler wouldn't work properly.

This CL just adds a warning comment about requirement to all
gpio.inc files.

BUG=chromium:471331
BRANCH=none
TEST=make buildall, test image on Cr50

This is a change to comments only. There is no new behavior to
verify, although I did run try out one new image just to be sure
nothing stupid happened.

Change-Id: I83f7819929a53bce3a8bae04d15b3ee3bda11738
Signed-off-by: Bill Richardson <wfrichar@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/329334
Reviewed-by: Vadim Bendebury <vbendeb@chromium.org>

40 files changed, 122 insertions, 19 deletions

diff --git a/board/auron/gpio.inc b/board/auron/gpio.inc
index d27cc66230..359c755b9f 100644
--- a/board/auron/gpio.inc
+++ b/board/auron/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(POWER_BUTTON_L, PIN(A, 2), GPIO_INT_BOTH_DSLEEP,                power_button_interrupt)   /* Power button */
 GPIO_INT(LID_OPEN,       PIN(A, 3), GPIO_INT_BOTH_DSLEEP,                lid_interrupt)            /* Lid switch */
 GPIO_INT(AC_PRESENT,     PIN(H, 3), GPIO_INT_BOTH_DSLEEP,                extpower_interrupt)       /* AC power present */
diff --git a/board/bds/gpio.inc b/board/bds/gpio.inc
index 7de4fb6ca7..424fde7f6d 100644
--- a/board/bds/gpio.inc
+++ b/board/bds/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* Recovery signal from DOWN button */
 GPIO(RECOVERY_L, PIN(D, 1), GPIO_PULL_UP)
 GPIO(DEBUG_LED,  PIN(A, 7), GPIO_OUT_LOW)
diff --git a/board/big/gpio.inc b/board/big/gpio.inc
index 2ee4f16c06..56d65312b1 100644
--- a/board/big/gpio.inc
+++ b/board/big/gpio.inc
@@ -5,10 +5,12 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 #define GPIO_KB_INPUT  (GPIO_INPUT | GPIO_PULL_UP | GPIO_INT_BOTH)
 #define GPIO_KB_OUTPUT GPIO_ODR_HIGH
 
-/* Inputs with interrupt handlers are first for efficiency */
 GPIO_INT(POWER_BUTTON_L, PIN(B, 5),  GPIO_INT_BOTH,                power_button_interrupt)
 GPIO_INT(SOC1V8_XPSHOLD, PIN(A, 3),  GPIO_INT_BOTH,                power_signal_interrupt)
 GPIO_INT(LID_OPEN,       PIN(C, 13), GPIO_INT_BOTH,                lid_interrupt)
diff --git a/board/chell/gpio.inc b/board/chell/gpio.inc
index 4805b20496..f547080708 100644
--- a/board/chell/gpio.inc
+++ b/board/chell/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(LID_OPEN,          PIN(27), GPIO_INT_BOTH, lid_interrupt)
 GPIO_INT(AC_PRESENT,        PIN(30), GPIO_INT_BOTH, extpower_interrupt)
 GPIO_INT(WP_L,              PIN(33), GPIO_INT_BOTH, switch_interrupt)
diff --git a/board/chell/lfw/gpio.inc b/board/chell/lfw/gpio.inc
index b7743916bc..e00a4a90ef 100644
--- a/board/chell/lfw/gpio.inc
+++ b/board/chell/lfw/gpio.inc
@@ -7,6 +7,9 @@
  * Minimal set of GPIOs needed for LFW loader
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* SPI PVT chip select */
 GPIO(PVT_CS0, PIN(146), GPIO_ODR_HIGH)
 
diff --git a/board/cr50/gpio.inc b/board/cr50/gpio.inc
index 88f0ae1418..fa478686b2 100644
--- a/board/cr50/gpio.inc
+++ b/board/cr50/gpio.inc
@@ -4,9 +4,8 @@
  * found in the LICENSE file.
  */
 
-/* Declare symbolic names for all the GPIOs that we care about */
-/* Inputs with interrupt handlers are first for efficiency */
-
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
 
 /* Unimplemented signals which we need to emulate for now */
 /* TODO(wfrichar): Half the boards don't use this signal. Take it out. */
diff --git a/board/dingdong/gpio.inc b/board/dingdong/gpio.inc
index c6ba602448..1545ca7859 100644
--- a/board/dingdong/gpio.inc
+++ b/board/dingdong/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(DP_HPD,        PIN(A, 0), GPIO_INT_BOTH, hpd_event)
 
 GPIO(USB_C_CC1_PD,      PIN(A, 1), GPIO_ANALOG)
diff --git a/board/discovery-stm32f072/gpio.inc b/board/discovery-stm32f072/gpio.inc
index 14272dcadd..a6dbf063de 100644
--- a/board/discovery-stm32f072/gpio.inc
+++ b/board/discovery-stm32f072/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(USER_BUTTON, PIN(A, 0), GPIO_INT_FALLING, button_event)
 
 /* Outputs */
diff --git a/board/discovery/gpio.inc b/board/discovery/gpio.inc
index 619b4396a0..92e835be54 100644
--- a/board/discovery/gpio.inc
+++ b/board/discovery/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(USER_BUTTON, PIN(A, 0), GPIO_INT_BOTH, button_event)
 
 /* Outputs */
diff --git a/board/glados/gpio.inc b/board/glados/gpio.inc
index a30f185764..0dd48835a5 100644
--- a/board/glados/gpio.inc
+++ b/board/glados/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(LID_OPEN,          PIN(27), GPIO_INT_BOTH | GPIO_PULL_UP, lid_interrupt)
 GPIO_INT(AC_PRESENT,        PIN(30), GPIO_INT_BOTH, extpower_interrupt)
 GPIO_INT(WP_L,              PIN(33), GPIO_INT_BOTH,        switch_interrupt)
diff --git a/board/glados/lfw/gpio.inc b/board/glados/lfw/gpio.inc
index b7743916bc..e00a4a90ef 100644
--- a/board/glados/lfw/gpio.inc
+++ b/board/glados/lfw/gpio.inc
@@ -7,6 +7,9 @@
  * Minimal set of GPIOs needed for LFW loader
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* SPI PVT chip select */
 GPIO(PVT_CS0, PIN(146), GPIO_ODR_HIGH)
 
diff --git a/board/glados_pd/gpio.inc b/board/glados_pd/gpio.inc
index 4b6db61891..df0020e958 100644
--- a/board/glados_pd/gpio.inc
+++ b/board/glados_pd/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* Interrupts */
 GPIO_INT(USB_C0_VBUS_WAKE_L,     PIN(C, 14),  GPIO_INT_BOTH,    pd_vbus_evt_p0)
 GPIO_INT(USB_C1_VBUS_WAKE_L,     PIN(C, 15),  GPIO_INT_BOTH,    pd_vbus_evt_p1)
diff --git a/board/hadoken/gpio.inc b/board/hadoken/gpio.inc
index eb8be3d3f4..33e6ab6a7a 100644
--- a/board/hadoken/gpio.inc
+++ b/board/hadoken/gpio.inc
@@ -5,11 +5,12 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 #define GPIO_KB_INPUT  (GPIO_INPUT | GPIO_PULL_UP | GPIO_INT_BOTH)
 #define GPIO_KB_OUTPUT GPIO_ODR_HIGH
 
-/* Inputs with interrupt handlers are first for efficiency */
-
 /* Keyboard inputs */
 /*
  * TODO(yjlou): call keyboard_raw_gpio_interrupt() in chip/nrf51/keyboard_raw.c
diff --git a/board/hoho/gpio.inc b/board/hoho/gpio.inc
index 787eaf7e90..421a1bf94d 100644
--- a/board/hoho/gpio.inc
+++ b/board/hoho/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(DP_HPD,       PIN(A, 0),  GPIO_INT_BOTH, hpd_event)
 
 GPIO(USB_C_CC1_PD,     PIN(A, 1),  GPIO_ANALOG)
diff --git a/board/honeybuns/gpio.inc b/board/honeybuns/gpio.inc
index a2a8f23e79..ebea3c61f5 100644
--- a/board/honeybuns/gpio.inc
+++ b/board/honeybuns/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(DP_HPD,        PIN(A, 0),  GPIO_INT_BOTH, hpd_event)
 
 /* PD RX/TX */
diff --git a/board/host/gpio.inc b/board/host/gpio.inc
index 0b9fa47dba..5ffb9ae944 100644
--- a/board/host/gpio.inc
+++ b/board/host/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(LID_OPEN,             PIN(0, 0), GPIO_INT_BOTH, lid_interrupt)
 GPIO_INT(POWER_BUTTON_L,       PIN(0, 0), GPIO_INT_BOTH, power_button_interrupt)
 GPIO_INT(AC_PRESENT,           PIN(0, 0), GPIO_INT_BOTH, extpower_interrupt)
diff --git a/board/it8380dev/gpio.inc b/board/it8380dev/gpio.inc
index 84a3bef164..a76527e0c3 100644
--- a/board/it8380dev/gpio.inc
+++ b/board/it8380dev/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(POWER_BUTTON_L, PIN(E, 4), GPIO_INT_BOTH | GPIO_PULL_UP,   power_button_interrupt)
 GPIO_INT(PCH_PLTRST_L,   PIN(E, 3), GPIO_INT_BOTH | GPIO_PULL_UP,   lpcrst_interrupt)
 GPIO_INT(LID_OPEN,       PIN(E, 2), GPIO_INT_BOTH | GPIO_PULL_DOWN, lid_interrupt)
diff --git a/board/jerry/gpio.inc b/board/jerry/gpio.inc
index 8d4581a461..0574e0d512 100644
--- a/board/jerry/gpio.inc
+++ b/board/jerry/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(POWER_BUTTON_L, PIN(B, 5),  GPIO_INT_BOTH,                power_button_interrupt) /* wk6 */ /* active high, the name is for compatibility with existing code */
 GPIO_INT(SOC_POWER_GOOD, PIN(A, 3),  GPIO_INT_BOTH,                power_signal_interrupt)
 GPIO_INT(LID_OPEN,       PIN(C, 13), GPIO_INT_BOTH,                lid_interrupt)
diff --git a/board/kunimitsu/gpio.inc b/board/kunimitsu/gpio.inc
index 531abc67ab..9e42a10dc9 100644
--- a/board/kunimitsu/gpio.inc
+++ b/board/kunimitsu/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(LID_OPEN,          PIN(27), GPIO_INT_BOTH | GPIO_PULL_UP, lid_interrupt)
 GPIO_INT(AC_PRESENT,        PIN(30), GPIO_INT_BOTH, extpower_interrupt)
 GPIO_INT(WP_L,              PIN(33), GPIO_INT_BOTH,        switch_interrupt)
diff --git a/board/kunimitsu/lfw/gpio.inc b/board/kunimitsu/lfw/gpio.inc
index b7743916bc..e00a4a90ef 100644
--- a/board/kunimitsu/lfw/gpio.inc
+++ b/board/kunimitsu/lfw/gpio.inc
@@ -7,6 +7,9 @@
  * Minimal set of GPIOs needed for LFW loader
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* SPI PVT chip select */
 GPIO(PVT_CS0, PIN(146), GPIO_ODR_HIGH)
 
diff --git a/board/lars/gpio.inc b/board/lars/gpio.inc
index 00f28bd79b..0410d18e61 100644
--- a/board/lars/gpio.inc
+++ b/board/lars/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(PCH_SLP_SUS_L,		PIN(12), GPIO_INT_BOTH | GPIO_PULL_UP, power_signal_interrupt)
 /* RSMRST from PMIC */
 GPIO_INT(RSMRST_L_PGOOD,	PIN(63), GPIO_INT_BOTH, power_signal_interrupt)
diff --git a/board/lars/lfw/gpio.inc b/board/lars/lfw/gpio.inc
index b7743916bc..e00a4a90ef 100644
--- a/board/lars/lfw/gpio.inc
+++ b/board/lars/lfw/gpio.inc
@@ -7,6 +7,9 @@
  * Minimal set of GPIOs needed for LFW loader
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* SPI PVT chip select */
 GPIO(PVT_CS0, PIN(146), GPIO_ODR_HIGH)
 
diff --git a/board/lars_pd/gpio.inc b/board/lars_pd/gpio.inc
index 277f059d72..f07bca419f 100644
--- a/board/lars_pd/gpio.inc
+++ b/board/lars_pd/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* Interrupts */
 GPIO_INT(USB_C0_VBUS_WAKE_L,     PIN(C, 14),  GPIO_INT_BOTH,    pd_vbus_evt_p0)
 
diff --git a/board/llama/gpio.inc b/board/llama/gpio.inc
index 12e400c916..96cf7652b3 100644
--- a/board/llama/gpio.inc
+++ b/board/llama/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(AC_PRESENT,       PIN(A, 0),  GPIO_INT_BOTH,                extpower_interrupt)     /* AC power present: PA 0 */
 GPIO_INT(POWER_BUTTON_L,   PIN(B, 5),  GPIO_INT_BOTH | GPIO_PULL_UP, power_button_interrupt) /* Keyboard power button: PB 5 */
 GPIO_INT(SOC_POWER_GOOD_L, PIN(A, 3),  GPIO_INT_BOTH,                power_signal_interrupt)
diff --git a/board/lucid/gpio.inc b/board/lucid/gpio.inc
index 72fb4acfa8..90fa4d2c16 100644
--- a/board/lucid/gpio.inc
+++ b/board/lucid/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* Interrupts */
 GPIO_INT(AC_PRESENT,         PIN(C, 13), GPIO_INT_BOTH, vbus_evt)       /* AC power present */
 GPIO_INT(CHARGE_STATUS,      PIN(F, 1),  GPIO_INT_BOTH, charge_state_interrupt)
diff --git a/board/npcx_evb/gpio.inc b/board/npcx_evb/gpio.inc
index 526960ca1b..ee6013e2bd 100644
--- a/board/npcx_evb/gpio.inc
+++ b/board/npcx_evb/gpio.inc
@@ -5,7 +5,10 @@
  * found in the LICENSE file.
  */
 
-/********************** Inputs with interrupt handlers are first for efficiency **********************/
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
+/********************** Inputs with interrupt handlers  **********************/
 /* TODO: Redefine debug 2 inputs */
 GPIO_INT(RECOVERY_L,       PIN(0, 0), GPIO_PULL_UP   | GPIO_INT_BOTH, switch_interrupt)       /* Recovery signal from servo */
 GPIO_INT(WP_L,             PIN(9, 3), GPIO_PULL_UP   | GPIO_INT_BOTH, switch_interrupt)       /* Write protect input */
diff --git a/board/npcx_evb_arm/gpio.inc b/board/npcx_evb_arm/gpio.inc
index 323edb916e..dd169a1806 100644
--- a/board/npcx_evb_arm/gpio.inc
+++ b/board/npcx_evb_arm/gpio.inc
@@ -5,7 +5,10 @@
  * found in the LICENSE file.
  */
 
-/********************** Inputs with interrupt handlers are first for efficiency **********************/
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
+/********************** Inputs with interrupt handlers  **********************/
 /* TODO: Redefine debug 2 inputs */
 GPIO_INT(RECOVERY_L,       PIN(0, 0), GPIO_PULL_UP   | GPIO_INT_BOTH, switch_interrupt)       /* Recovery signal from servo */
 GPIO_INT(WP_L,             PIN(9, 3), GPIO_PULL_UP   | GPIO_INT_BOTH, switch_interrupt)       /* Write protect input */
diff --git a/board/oak/gpio.inc b/board/oak/gpio.inc
index 5c5ebfd810..9bef78d8c1 100644
--- a/board/oak/gpio.inc
+++ b/board/oak/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(AC_PRESENT,     PIN(C, 6),  GPIO_INT_BOTH,                     extpower_interrupt)
 GPIO_INT(POWER_BUTTON_L, PIN(B, 5),  GPIO_INT_BOTH | GPIO_PULL_UP,      power_button_interrupt)
 GPIO_INT(LID_OPEN,       PIN(C, 13), GPIO_INT_BOTH,                     lid_interrupt)          /* LID switch detection */
diff --git a/board/pdeval-stm32f072/gpio.inc b/board/pdeval-stm32f072/gpio.inc
index 052ed47d66..cd3c601a0a 100644
--- a/board/pdeval-stm32f072/gpio.inc
+++ b/board/pdeval-stm32f072/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(USER_BUTTON, PIN(A, 0), GPIO_INT_FALLING, button_event)
 GPIO_INT(PD_MCU_INT,  PIN(A, 1), GPIO_INT_FALLING, alert_event)
 
diff --git a/board/pit/gpio.inc b/board/pit/gpio.inc
index 28d9df97e4..e9e92e90c8 100644
--- a/board/pit/gpio.inc
+++ b/board/pit/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(KB_PWR_ON_L,    PIN(B, 5),  GPIO_INT_BOTH,                power_signal_interrupt)
 GPIO_INT(PP1800_LDO2,    PIN(A, 1),  GPIO_INT_BOTH,                power_signal_interrupt)
 GPIO_INT(SOC1V8_XPSHOLD, PIN(A, 3),  GPIO_INT_RISING,              power_signal_interrupt)
diff --git a/board/plankton/gpio.inc b/board/plankton/gpio.inc
index 1f97b63fed..b090f4154f 100644
--- a/board/plankton/gpio.inc
+++ b/board/plankton/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(VBUS_WAKE,           PIN(B, 5),  GPIO_INT_BOTH,    vbus_event)
 GPIO_INT(DPSRC_HPD,           PIN(B, 13), GPIO_INT_BOTH,    hpd_event)
 GPIO_INT(DBG_12V_TO_DUT_L,    PIN(B, 14), GPIO_INT_FALLING, button_event)
diff --git a/board/rambi/gpio.inc b/board/rambi/gpio.inc
index 190c2a9374..c6914e0a50 100644
--- a/board/rambi/gpio.inc
+++ b/board/rambi/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(POWER_BUTTON_L,   PIN(A, 2), GPIO_INT_BOTH_DSLEEP,                power_button_interrupt)
 GPIO_INT(LID_OPEN,         PIN(A, 3), GPIO_INT_BOTH_DSLEEP,                lid_interrupt)
 GPIO_INT(AC_PRESENT,       PIN(H, 3), GPIO_INT_BOTH_DSLEEP,                extpower_interrupt)
diff --git a/board/ryu/gpio.inc b/board/ryu/gpio.inc
index ae59c63c24..41df8b85b1 100644
--- a/board/ryu/gpio.inc
+++ b/board/ryu/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* Interrupts */
 GPIO_INT(CHGR_ACOK,            PIN(D, 4),  GPIO_INT_BOTH,    vbus_evt)
 GPIO_INT(POWER_BUTTON_L,       PIN(C, 13), GPIO_INT_BOTH,                   power_button_interrupt) /* active high, the name is for compatibility with existing code */
diff --git a/board/samus/gpio.inc b/board/samus/gpio.inc
index ade6967437..fbd9f46223 100644
--- a/board/samus/gpio.inc
+++ b/board/samus/gpio.inc
@@ -5,7 +5,9 @@
  * found in the LICENSE file.
  */
 
-/* Inputs with interrupt handlers are first for efficiency */
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(POWER_BUTTON_L, PIN(A, 2), GPIO_INT_BOTH_DSLEEP,                power_button_interrupt)   /* Power button */
 GPIO_INT(LID_OPEN,       PIN(A, 3), GPIO_INT_BOTH_DSLEEP,                lid_interrupt)            /* Lid switch */
 GPIO_INT(AC_PRESENT,     PIN(H, 3), GPIO_INT_BOTH_DSLEEP,                extpower_interrupt)       /* AC power present */
diff --git a/board/samus_pd/gpio.inc b/board/samus_pd/gpio.inc
index 779519fe5c..380a248788 100644
--- a/board/samus_pd/gpio.inc
+++ b/board/samus_pd/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* Interrupts */
 GPIO_INT(USB_C0_VBUS_WAKE,       PIN(E, 6),  GPIO_INT_BOTH,    vbus0_evt)
 GPIO_INT(USB_C1_VBUS_WAKE,       PIN(F, 2),  GPIO_INT_BOTH,    vbus1_evt)
diff --git a/board/snoball/gpio.inc b/board/snoball/gpio.inc
index c2512e3d9d..d9c925a336 100644
--- a/board/snoball/gpio.inc
+++ b/board/snoball/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 /* TCPC alert / interrupt inputs */
 GPIO_INT(TCPC1_INT,	PIN(A, 11),	GPIO_INT_FALLING, tcpc_alert_event)
 GPIO_INT(TCPC2_INT,	PIN(A, 12),	GPIO_INT_FALLING, tcpc_alert_event)
diff --git a/board/strago/gpio.inc b/board/strago/gpio.inc
index 2ca293e6be..74ea40af80 100644
--- a/board/strago/gpio.inc
+++ b/board/strago/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(PD_MCU_INT,        PIN(47),  GPIO_INT_FALLING | GPIO_INT_DSLEEP, pd_mcu_interrupt)
 GPIO_INT(USB_C0_VBUS_WAKE_L,PIN(12),  GPIO_INT_BOTH,                      vbus0_evt)
 GPIO_INT(USB_C0_BC12_INT_L, PIN(155), GPIO_INT_FALLING,                   usb0_evt)
diff --git a/board/strago/lfw/gpio.inc b/board/strago/lfw/gpio.inc
index 122aff0cdf..c8199550c4 100644
--- a/board/strago/lfw/gpio.inc
+++ b/board/strago/lfw/gpio.inc
@@ -7,6 +7,9 @@
  * Minimal set of GPIOs needed for LFW loader
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO(PVT_CS0,           PIN(146), GPIO_ODR_HIGH)                 /* SPI PVT Chip select */
 
 /* Alternate functions GPIO definition */
diff --git a/board/twinkie/gpio.inc b/board/twinkie/gpio.inc
index 07b935fceb..3d8253e6cc 100644
--- a/board/twinkie/gpio.inc
+++ b/board/twinkie/gpio.inc
@@ -4,6 +4,10 @@
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
+
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(CC2_ALERT_L,  PIN(A, 7),  GPIO_INT_BOTH | GPIO_PULL_UP, cc2_event)
 GPIO_INT(VBUS_ALERT_L, PIN(B, 2),  GPIO_INT_BOTH | GPIO_PULL_UP, vbus_event)
 
diff --git a/board/wheatley/gpio.inc b/board/wheatley/gpio.inc
index c0037ae5b0..c3b9db8cff 100644
--- a/board/wheatley/gpio.inc
+++ b/board/wheatley/gpio.inc
@@ -5,6 +5,9 @@
  * found in the LICENSE file.
  */
 
+/* Declare symbolic names for all the GPIOs that we care about.
+ * Note: Those with interrupt handlers must be declared first. */
+
 GPIO_INT(LID_OPEN,           PIN(9,  5), GPIO_INT_BOTH | GPIO_PULL_UP,    lid_interrupt)           /* A47 - SPIP_MISO for LID_OPEN_EC */
 GPIO_INT(AC_PRESENT,         PIN(B,  0), GPIO_INT_BOTH,                   extpower_interrupt)      /* B57 - GPIOB0 for EC_PCH_ACPRESENT */
 GPIO_INT(WP_L,               PIN(7,  1), GPIO_INT_BOTH,                   switch_interrupt)        /* B38 - PS2_DAT3/TB2 for EC_WP_L */