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.

3 files changed, 73 insertions, 0 deletions

diff --git a/app/dts/bindings/zmk,key-physical-attrs.yaml b/app/dts/bindings/zmk,key-physical-attrs.yaml
new file mode 100644
index 0000000000..9ea070f8ce
--- /dev/null
+++ b/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
diff --git a/app/dts/bindings/zmk,physical-layout-position-map.yaml b/app/dts/bindings/zmk,physical-layout-position-map.yaml
new file mode 100644
index 0000000000..8647404b99
--- /dev/null
+++ b/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.
diff --git a/app/dts/bindings/zmk,physical-layout.yaml b/app/dts/bindings/zmk,physical-layout.yaml
new file mode 100644
index 0000000000..3f9b8c244b
--- /dev/null
+++ b/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.