input: add some initial keyboard matrix library stubs

We currently have three keyboard scanning drivers in the code base
(npcx, it8xxx2 and mchp_xec, last two yet to be converted to input).
These have been largely copy pasted from each other and share a lot of
the same structure and code.

This PR lays a foundation to start decoupling feature from those drivers
into a common code base, and it is heavily inspired by the current
regulator common data/config one.

Feature wise this only moves the thread struct, stack and initialization
to the common code and declares the thread callback as the only API, but
the intent is to move as much code as possible in there an only abstract
device specific callbacks in the api structures.

Signed-off-by: Fabio Baltieri <[email protected]>

drivers/input/CMakeLists.txt

@@ -9,6 +9,7 @@ zephyr_library_sources_ifdef(CONFIG_INPUT_FT5336 input_ft5336.c)
 zephyr_library_sources_ifdef(CONFIG_INPUT_GPIO_KEYS input_gpio_keys.c)
 zephyr_library_sources_ifdef(CONFIG_INPUT_GPIO_QDEC input_gpio_qdec.c)
 zephyr_library_sources_ifdef(CONFIG_INPUT_GT911 input_gt911.c)
+zephyr_library_sources_ifdef(CONFIG_INPUT_KBD_MATRIX input_kbd_matrix.c)
 zephyr_library_sources_ifdef(CONFIG_INPUT_NPCX_KBD input_npcx_kbd.c)
 zephyr_library_sources_ifdef(CONFIG_INPUT_STMPE811 input_stmpe811.c)
 zephyr_library_sources_ifdef(CONFIG_INPUT_XPT2046 input_xpt2046.c)

drivers/input/Kconfig

@@ -11,6 +11,7 @@ source "drivers/input/Kconfig.ft5336"
 source "drivers/input/Kconfig.gpio_keys"
 source "drivers/input/Kconfig.gpio_qdec"
 source "drivers/input/Kconfig.gt911"
+source "drivers/input/Kconfig.kbd_matrix"
 source "drivers/input/Kconfig.npcx"
 source "drivers/input/Kconfig.sdl"
 source "drivers/input/Kconfig.stmpe811"

drivers/input/Kconfig.kbd_matrix

@@ -0,0 +1,17 @@
+# Copyright 2023 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+
+config INPUT_KBD_MATRIX
+	bool
+	help
+	  Enable library used for keyboard matrix drivers.
+
+if INPUT_KBD_MATRIX
+
+config INPUT_KBD_THREAD_STACK_SIZE
+	int "Stack size for the keyboard matrix thread"
+	default 1024
+	help
+	  Size of the stack used for the keyboard matrix thread.
+
+endif # INPUT_KBD_MATRIX

drivers/input/Kconfig.npcx

@@ -7,6 +7,7 @@ menuconfig INPUT_NPCX_KBD
 	bool "Nuvoton NPCX embedded controller (EC) keyboard scan driver"
 	default y
 	depends on DT_HAS_NUVOTON_NPCX_KBD_ENABLED
+	select INPUT_KBD_MATRIX
 	select MULTITHREADING
 	help
 	  This option enables the keyboard scan driver for NPCX family of
@@ -34,10 +35,4 @@ config INPUT_NPCX_KBD_POLL_COL_OUTPUT_SETTLE_TIME_US
 	  Delay (us) between setting column output and waiting for it
 	  to settle
 
-config INPUT_NPCX_KBD_THREAD_STACK_SIZE
-	int "Stack size for the kscan thread"
-	default 1024
-	help
-	  Size of the stack used for the kscan thread.
-
 endif # INPUT_NPCX_KBD

drivers/input/input_kbd_matrix.c

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/device.h>
+#include <zephyr/kernel.h>
+
+#include "input_kbd_matrix.h"
+
+int input_kbd_matrix_common_init(const struct device *dev)
+{
+	const struct input_kbd_matrix_common_config *cfg = dev->config;
+	const struct input_kbd_matrix_api *api = &cfg->api;
+	struct input_kbd_matrix_common_data *const data = dev->data;
+
+	k_thread_create(&data->thread, data->thread_stack,
+			CONFIG_INPUT_KBD_THREAD_STACK_SIZE,
+			api->polling_thread, (void *)dev, NULL, NULL,
+			K_PRIO_COOP(4), 0, K_NO_WAIT);
+
+	k_thread_name_set(&data->thread, dev->name);
+
+	return 0;
+}

drivers/input/input_kbd_matrix.h

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/device.h>
+#include <zephyr/kernel.h>
+#include <zephyr/toolchain.h>
+
+/**
+ * @brief Keyboard matrix internal APIs.
+ */
+struct input_kbd_matrix_api {
+	k_thread_entry_t polling_thread;
+};
+
+/**
+ * @brief Common keyboard matrix config.
+ *
+ * This structure **must** be placed first in the driver's config structure.
+ */
+struct input_kbd_matrix_common_config {
+	struct input_kbd_matrix_api api;
+};
+
+/**
+ * @brief Initialize common keyboard matrix config from devicetree.
+ *
+ * @param api Pointer to a :c:struct:`input_kbd_matrix_api` structure.
+ */
+#define INPUT_KBD_MATRIX_DT_COMMON_CONFIG_INIT(node_id, _api) \
+	{ \
+		.api = _api, \
+	}
+
+/**
+ * @brief Initialize common keyboard matrix config from devicetree instance.
+ *
+ * @param inst Instance.
+ * @param api Pointer to a :c:struct:`input_kbd_matrix_api` structure.
+ */
+#define INPUT_KBD_MATRIX_DT_INST_COMMON_CONFIG_INIT(inst, api) \
+	INPUT_KBD_MATRIX_DT_COMMON_CONFIG_INIT(DT_DRV_INST(inst), api)
+
+/**
+ * @brief Common keyboard matrix data.
+ *
+ * This structure **must** be placed first in the driver's data structure.
+ */
+struct input_kbd_matrix_common_data {
+	struct k_thread thread;
+
+	K_KERNEL_STACK_MEMBER(thread_stack, CONFIG_INPUT_KBD_THREAD_STACK_SIZE);
+};
+
+/**
+ * @brief Validate the offset of the common data structures.
+ *
+ * @param config Name of the config structure.
+ * @param data Name of the data structure.
+ */
+#define INPUT_KBD_STRUCT_CHECK(config, data) \
+	BUILD_ASSERT(offsetof(config, common) == 0, \
+		     "struct input_kbd_matrix_common_config must be placed first"); \
+	BUILD_ASSERT(offsetof(data, common) == 0, \
+		     "struct input_kbd_matrix_common_data must be placed first")
+
+/**
+ * @brief Common function to initialize a keyboard matrix device at init time.
+ *
+ * This function must be called at the end of the device init function.
+ *
+ * @param dev Keyboard matrix device instance.
+ *
+ * @retval 0 If initialized successfully.
+ * @retval -errno Negative errno in case of failure.
+ */
+int input_kbd_matrix_common_init(const struct device *dev);

drivers/input/input_npcx_kbd.c

@@ -8,6 +8,7 @@
 #define DT_DRV_COMPAT nuvoton_npcx_kbd
 
 #include "soc_miwu.h"
+#include "input_kbd_matrix.h"
 
 #include <zephyr/drivers/clock_control.h>
 #include <zephyr/drivers/pinctrl.h>
@@ -32,6 +33,7 @@ LOG_MODULE_REGISTER(input_npcx_kbd);
 
 /* Driver config */
 struct input_npcx_kbd_config {
+	struct input_kbd_matrix_common_config common;
 	/* Keyboard scan controller base address */
 	struct kbs_reg *base;
 	/* Clock configuration */
@@ -51,6 +53,7 @@ struct input_npcx_kbd_config {
 };
 
 struct input_npcx_kbd_data {
+	struct input_kbd_matrix_common_data common;
 	int64_t poll_timeout_us;
 	uint32_t poll_period_us;
 	uint8_t matrix_stable_state[KSCAN_COL_SIZE];
@@ -66,11 +69,10 @@ struct input_npcx_kbd_data {
 	uint8_t scan_clk_cycle[SCAN_OCURRENCES];
 	struct k_sem poll_lock;
 	uint8_t scan_cycles_idx;
-	struct k_thread thread;
-
-	K_KERNEL_STACK_MEMBER(thread_stack, CONFIG_INPUT_NPCX_KBD_THREAD_STACK_SIZE);
 };
 
+INPUT_KBD_STRUCT_CHECK(struct input_npcx_kbd_config, struct input_npcx_kbd_data);
+
 /* Keyboard scan local functions */
 static void input_npcx_kbd_ksi_isr(const struct device *dev, struct npcx_wui *wui)
 {
@@ -473,19 +475,17 @@ static int input_npcx_kbd_init(const struct device *dev)
 	data->poll_period_us = (uint32_t)(CONFIG_INPUT_NPCX_KBD_POLL_PERIOD_MS * USEC_PER_MSEC);
 	data->poll_timeout_us = 100 * USEC_PER_MSEC;
 
-	k_thread_create(&data->thread, data->thread_stack,
-			CONFIG_INPUT_NPCX_KBD_THREAD_STACK_SIZE,
-			(k_thread_entry_t)kbd_matrix_polling_thread, (void *)dev, NULL, NULL,
-			K_PRIO_COOP(4), 0, K_NO_WAIT);
-
-	k_thread_name_set(&data->thread, "npcx-kbd");
-
-	return 0;
+	return input_kbd_matrix_common_init(dev);
 }
 
 PINCTRL_DT_INST_DEFINE(0);
 
+static const struct input_kbd_matrix_api npcx_kbd_api = {
+	.polling_thread = (k_thread_entry_t)kbd_matrix_polling_thread,
+};
+
 static const struct input_npcx_kbd_config npcx_kbd_cfg = {
+	.common = INPUT_KBD_MATRIX_DT_INST_COMMON_CONFIG_INIT(0, npcx_kbd_api),
 	.base = (struct kbs_reg *)DT_INST_REG_ADDR(0),
 	.pcfg = PINCTRL_DT_INST_DEV_CONFIG_GET(0),
 	.clk_cfg = NPCX_DT_CLK_CFG_ITEM(0),

dts/bindings/input/kbd-matrix-common.yaml

@@ -0,0 +1,6 @@
+# Copyright 2023 Google LLC
+# SPDX-License-Identifier: Apache-2.0
+
+description: Keyboard matrix device
+
+include: base.yaml

dts/bindings/input/nuvoton,npcx-kbd.yaml

@@ -5,7 +5,7 @@ description: Nuvoton NPCX keyboard scan controller
 
 compatible: "nuvoton,npcx-kbd"
 
-include: [base.yaml, pinctrl-device.yaml]
+include: [kbd-matrix-common.yaml, pinctrl-device.yaml]
 
 properties:
   reg: