feat: Add keyboard physical layout system.

* Add bindings to allow creating multiple physical layouts that specify
  their key's physical attributes, and the matching matrix transform
  and dependant kscan to use.
* Synthesize a basic physical layout if none specified, for backwards
  compatibility.
* Update matrix transform API to explicitly pass in the selected transform
  to the API instead of using a fixed chosen transform.
* Move kscan subscription and handling into the physical layout code, so
  that selecting a different physical layout at runtime can also use the
  correct kscan instance.
* Add `physical_layouts.dtsi` file to include so you can use the
  pre-configured `&key_physical_attrs` for adding you layout keys.

app/CMakeLists.txt

@@ -24,9 +24,9 @@ target_include_directories(app PRIVATE include)
 target_sources(app PRIVATE src/stdlib.c)
 target_sources(app PRIVATE src/activity.c)
 target_sources(app PRIVATE src/behavior.c)
-target_sources(app PRIVATE src/kscan.c)
 target_sources_ifdef(CONFIG_ZMK_KSCAN_SIDEBAND_BEHAVIORS app PRIVATE src/kscan_sideband_behaviors.c)
 target_sources(app PRIVATE src/matrix_transform.c)
+target_sources(app PRIVATE src/physical_layouts.c)
 target_sources(app PRIVATE src/sensors.c)
 target_sources_ifdef(CONFIG_ZMK_WPM app PRIVATE src/wpm.c)
 target_sources(app PRIVATE src/event_manager.c)

app/dts/bindings/zmk,key-physical-attrs.yaml

@@ -0,0 +1,24 @@
+#
+# Copyright (c) 2024 The ZMK Contributors
+#
+# SPDX-License-Identifier: MIT
+
+description: |
+  The physical attributes of a key, including size, location, and rotation
+
+compatible: "zmk,key-physical-attrs"
+
+properties:
+  "#key-cells":
+    type: int
+    required: true
+    const: 7
+
+key-cells:
+  - width
+  - height
+  - x
+  - y
+  - r
+  - rx
+  - ry

app/dts/bindings/zmk,physical-layout-position-map.yaml

@@ -0,0 +1,23 @@
+#
+# Copyright (c) 2024 The ZMK Contributors
+#
+# SPDX-License-Identifier: MIT
+
+description: |
+  Describes how to correlate equivalent keys between layouts that don't have the exact same X,Y location.
+
+compatible: "zmk,physical-layout-position-map"
+
+properties:
+  complete:
+    type: boolean
+    description: If the mapping complete describes the key mapping, and no position based mapping should be used.
+
+child-binding:
+  properties:
+    physical-layout:
+      type: phandle
+      description: The physical layout that corresponds to this mapping entry.
+    positions:
+      type: array
+      description: Array of key positions that match the same array entry in the other sibling nodes.

app/dts/bindings/zmk,physical-layout.yaml

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2024 The ZMK Contributors
+#
+# SPDX-License-Identifier: MIT
+
+description: |
+  Describe the physical layout of a keyboard, including deps like the transform and kscan
+  that are needed for that layout to work.
+
+compatible: "zmk,physical-layout"
+
+properties:
+  display-name:
+    type: string
+    required: true
+    description: The name of this layout to display in the UI
+  transform:
+    type: phandle
+    required: true
+    description: The matrix transform to use along with this layout.
+  kscan:
+    type: phandle
+    description: The kscan to use along with this layout. The `zmk,kscan` chosen will be used as a fallback if this property is omitted.
+  keys:
+    type: phandle-array
+    description: Array of key physical attributes.

app/dts/physical_layouts.dtsi

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2024 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+/ {
+    key_physical_attrs: key_physical_attrs {
+        compatible = "zmk,key-physical-attrs";
+
+        #key-cells = <7>;
+    };
+};

app/include/zmk/matrix.h

@@ -9,15 +9,25 @@
 #include <zephyr/devicetree.h>
 
 #define ZMK_MATRIX_NODE_ID DT_CHOSEN(zmk_kscan)
+#define ZMK_MATRIX_HAS_TRANSFORM DT_HAS_CHOSEN(zmk_matrix_transform)
 
-#if DT_HAS_CHOSEN(zmk_matrix_transform)
+#if DT_HAS_COMPAT_STATUS_OKAY(zmk_physical_layout)
+
+#if ZMK_MATRIX_HAS_TRANSFORM
+#error "To use physical layouts, remove the chosen `zmk,matrix-transform` value."
+#endif
+
+#define ZMK_PHYSICAL_LAYOUT_BYTE_ARRAY(node_id)                                                    \
+    uint8_t _CONCAT(prop_, node_id)[DT_PROP_LEN(DT_PHANDLE(node_id, transform), map)];
+
+#define ZMK_KEYMAP_LEN                                                                             \
+    sizeof(union {DT_FOREACH_STATUS_OKAY(zmk_physical_layout, ZMK_PHYSICAL_LAYOUT_BYTE_ARRAY)})
+
+#elif ZMK_MATRIX_HAS_TRANSFORM
 
 #define ZMK_KEYMAP_TRANSFORM_NODE DT_CHOSEN(zmk_matrix_transform)
 #define ZMK_KEYMAP_LEN DT_PROP_LEN(ZMK_KEYMAP_TRANSFORM_NODE, map)
 
-#define ZMK_MATRIX_ROWS DT_PROP(ZMK_KEYMAP_TRANSFORM_NODE, rows)
-#define ZMK_MATRIX_COLS DT_PROP(ZMK_KEYMAP_TRANSFORM_NODE, columns)
-
 #else /* DT_HAS_CHOSEN(zmk_matrix_transform) */
 
 #if DT_NODE_HAS_PROP(ZMK_MATRIX_NODE_ID, row_gpios)

app/include/zmk/matrix_transform.h

@@ -6,4 +6,16 @@
 
 #pragma once
 
-int32_t zmk_matrix_transform_row_column_to_position(uint32_t row, uint32_t column);
+#include <zephyr/sys/util.h>
+
+typedef const struct zmk_matrix_transform *zmk_matrix_transform_t;
+
+#define ZMK_MATRIX_TRANSFORM_DEFAULT_EXTERN()                                                      \
+    extern const struct zmk_matrix_transform zmk_matrix_transform_default
+#define ZMK_MATRIX_TRANSFORM_EXTERN(node_id)                                                       \
+    extern const struct zmk_matrix_transform _CONCAT(zmk_matrix_transform_, node_id)
+
+#define ZMK_MATRIX_TRANSFORM_T_FOR_NODE(node_id) &_CONCAT(zmk_matrix_transform_, node_id)
+
+int32_t zmk_matrix_transform_row_column_to_position(zmk_matrix_transform_t mt, uint32_t row,
+                                                    uint32_t column);

app/include/zmk/physical_layouts.h

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2024 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <zephyr/kernel.h>
+#include <zmk/matrix_transform.h>
+
+struct zmk_key_physical_attrs {
+    int16_t width;
+    int16_t height;
+    int16_t x;
+    int16_t y;
+    int16_t rx;
+    int16_t ry;
+    int16_t r;
+};
+
+struct zmk_physical_layout {
+    const char *display_name;
+
+    zmk_matrix_transform_t matrix_transform;
+    const struct device *kscan;
+
+    const struct zmk_key_physical_attrs *keys;
+    size_t keys_len;
+};
+
+#define ZMK_PHYS_LAYOUTS_FOREACH(_ref) STRUCT_SECTION_FOREACH(zmk_physical_layout, _ref)
+
+size_t zmk_physical_layouts_get_list(struct zmk_physical_layout const *const **phys_layouts);
+
+int zmk_physical_layouts_select(uint8_t index);
+int zmk_physical_layouts_get_selected(void);
+
+int zmk_physical_layouts_check_unsaved_selection(void);
+int zmk_physical_layouts_save_selected(void);
+int zmk_physical_layouts_revert_selected(void);
+
+int zmk_physical_layouts_get_position_map(uint8_t source, uint8_t dest, uint32_t *map);

app/src/main.c

@@ -12,18 +12,11 @@
 #include <zephyr/logging/log.h>
 LOG_MODULE_REGISTER(zmk, CONFIG_ZMK_LOG_LEVEL);
 
-#include <zmk/matrix.h>
-#include <zmk/kscan.h>
 #include <zmk/display.h>
-#include <drivers/ext_power.h>
 
 int main(void) {
     LOG_INF("Welcome to ZMK!\n");
 
-    if (zmk_kscan_init(DEVICE_DT_GET(ZMK_MATRIX_NODE_ID)) != 0) {
-        return -ENOTSUP;
-    }
-
 #if IS_ENABLED(CONFIG_SETTINGS)
     settings_subsys_init();
     settings_load();