feat(behaviors): Add behavior metadata information.

* For upcoming ZMK studio work, make a set of rich metadata available to provide a friendly name for a behavior, and allow super flexible descriptions of the parameters the behaviors take.
petejohanson · Jun 5, 2024 · cd1c6d0 · cd1c6d0
1 parent 2ee76be
commit cd1c6d0
Show file tree

Hide file tree

Showing 36 changed files with 610 additions and 13 deletions.
diff --git a/app/Kconfig.behaviors b/app/Kconfig.behaviors
@@ -1,6 +1,12 @@
 # Copyright (c) 2023 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+config ZMK_BEHAVIOR_METADATA
+    bool "Metadata"
+    help
+      Enabling this option adds APIs for documenting and fetching
+      metadata describing a behaviors name, and supported parameters.
+
 config ZMK_BEHAVIOR_KEY_TOGGLE
     bool
     default y
@@ -35,4 +41,4 @@ config ZMK_BEHAVIOR_SENSOR_ROTATE_VAR
 config ZMK_BEHAVIOR_MACRO
     bool
     default y
-    depends on DT_HAS_ZMK_BEHAVIOR_MACRO_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_ONE_PARAM_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_TWO_PARAM_ENABLED
+    depends on DT_HAS_ZMK_BEHAVIOR_MACRO_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_ONE_PARAM_ENABLED || DT_HAS_ZMK_BEHAVIOR_MACRO_TWO_PARAM_ENABLED
diff --git a/app/dts/behaviors/backlight.dtsi b/app/dts/behaviors/backlight.dtsi
@@ -10,6 +10,7 @@
         /omit-if-no-ref/ bl: bcklight {
             compatible = "zmk,behavior-backlight";
             #binding-cells = <2>;
+            friendly-name = "Backlight";
         };
     };
 };
diff --git a/app/dts/behaviors/bluetooth.dtsi b/app/dts/behaviors/bluetooth.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ bt: bluetooth {
             compatible = "zmk,behavior-bluetooth";
             #binding-cells = <2>;
+            friendly-name = "Bluetooth";
         };
     };
 };
diff --git a/app/dts/behaviors/caps_word.dtsi b/app/dts/behaviors/caps_word.dtsi
@@ -12,6 +12,7 @@
             compatible = "zmk,behavior-caps-word";
             #binding-cells = <0>;
             continue-list = <UNDERSCORE BACKSPACE DELETE>;
+            friendly-name = "Caps Word";
         };
     };
 };

diff --git a/app/dts/behaviors/ext_power.dtsi b/app/dts/behaviors/ext_power.dtsi
@@ -10,6 +10,7 @@
         ext_power: extpower {
             compatible = "zmk,behavior-ext-power";
             #binding-cells = <1>;
+            friendly-name = "External Power";
         };
     };
 };
diff --git a/app/dts/behaviors/gresc.dtsi b/app/dts/behaviors/gresc.dtsi
@@ -13,6 +13,7 @@
             #binding-cells = <0>;
             bindings = <&kp ESC>, <&kp GRAVE>;
             mods = <(MOD_LGUI|MOD_LSFT|MOD_RGUI|MOD_RSFT)>;
+            friendly-name = "Grave/Escape";
         };
     };
 };
diff --git a/app/dts/behaviors/key_press.dtsi b/app/dts/behaviors/key_press.dtsi
@@ -10,6 +10,7 @@
         /omit-if-no-ref/ cp: kp: key_press {
             compatible = "zmk,behavior-key-press";
             #binding-cells = <1>;
+            friendly-name = "Key Press";
         };
     };
 };
diff --git a/app/dts/behaviors/key_repeat.dtsi b/app/dts/behaviors/key_repeat.dtsi
@@ -12,6 +12,7 @@
             compatible = "zmk,behavior-key-repeat";
             #binding-cells = <0>;
             usage-pages = <HID_USAGE_KEY>;
+            friendly-name = "Key Repeat";
         };
     };
 };

diff --git a/app/dts/behaviors/key_toggle.dtsi b/app/dts/behaviors/key_toggle.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ kt: key_toggle {
             compatible = "zmk,behavior-key-toggle";
             #binding-cells = <1>;
+            friendly-name = "Key Toggle";
         };
     };
 };
diff --git a/app/dts/behaviors/layer_tap.dtsi b/app/dts/behaviors/layer_tap.dtsi
@@ -12,6 +12,7 @@
             flavor = "tap-preferred";
             tapping-term-ms = <200>;
             bindings = <&mo>, <&kp>;
+            friendly-name = "Layer-Tap";
         };
     };
 };
diff --git a/app/dts/behaviors/mod_tap.dtsi b/app/dts/behaviors/mod_tap.dtsi
@@ -12,6 +12,7 @@
             flavor = "hold-preferred";
             tapping-term-ms = <200>;
             bindings = <&kp>, <&kp>;
+            friendly-name = "Mod-Tap";
         };
     };
 };
diff --git a/app/dts/behaviors/momentary_layer.dtsi b/app/dts/behaviors/momentary_layer.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ mo: momentary_layer {
             compatible = "zmk,behavior-momentary-layer";
             #binding-cells = <1>;
+            friendly-name = "Momentary Layer";
         };
     };
 };
diff --git a/app/dts/behaviors/none.dtsi b/app/dts/behaviors/none.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ none: none {
             compatible = "zmk,behavior-none";
             #binding-cells = <0>;
+            friendly-name = "None";
         };
     };
 };
diff --git a/app/dts/behaviors/outputs.dtsi b/app/dts/behaviors/outputs.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ out: outputs {
             compatible = "zmk,behavior-outputs";
             #binding-cells = <1>;
+            friendly-name = "Output Selection";
         };
     };
 };
diff --git a/app/dts/behaviors/reset.dtsi b/app/dts/behaviors/reset.dtsi
@@ -12,13 +12,15 @@
         sys_reset: sysreset {
             compatible = "zmk,behavior-reset";
             #binding-cells = <0>;
+            friendly-name = "Reset";
         };
 
         // Behavior can be invoked on peripherals, so name must be <= 8 characters.
         bootloader: bootload {
             compatible = "zmk,behavior-reset";
             type = <RST_UF2>;
             #binding-cells = <0>;
+            friendly-name = "Bootloader";
         };
     };
 };
diff --git a/app/dts/behaviors/rgb_underglow.dtsi b/app/dts/behaviors/rgb_underglow.dtsi
@@ -10,6 +10,7 @@
         rgb_ug: rgb_ug {
             compatible = "zmk,behavior-rgb-underglow";
             #binding-cells = <2>;
+            friendly-name = "Underglow";
         };
     };
 };
diff --git a/app/dts/behaviors/sticky_key.dtsi b/app/dts/behaviors/sticky_key.dtsi
@@ -12,13 +12,15 @@
             release-after-ms = <1000>;
             bindings = <&kp>;
             ignore-modifiers;
+            friendly-name = "Sticky Key";
         };
         /omit-if-no-ref/ sl: sticky_layer {
             compatible = "zmk,behavior-sticky-key";
             #binding-cells = <1>;
             release-after-ms = <1000>;
             bindings = <&mo>;
             quick-release;
+            friendly-name = "Sticky Layer";
         };
     };
 

diff --git a/app/dts/behaviors/to_layer.dtsi b/app/dts/behaviors/to_layer.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ to: to_layer {
             compatible = "zmk,behavior-to-layer";
             #binding-cells = <1>;
+            friendly-name = "To Layer";
         };
     };
 };
diff --git a/app/dts/behaviors/toggle_layer.dtsi b/app/dts/behaviors/toggle_layer.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ tog: toggle_layer {
             compatible = "zmk,behavior-toggle-layer";
             #binding-cells = <1>;
+            friendly-name = "Toggle Layer";
         };
     };
 };
diff --git a/app/dts/behaviors/transparent.dtsi b/app/dts/behaviors/transparent.dtsi
@@ -9,6 +9,7 @@
         /omit-if-no-ref/ trans: transparent {
             compatible = "zmk,behavior-transparent";
             #binding-cells = <0>;
+            friendly-name = "Transparent";
         };
     };
 };
diff --git a/app/dts/bindings/behaviors/behavior-metadata.yaml b/app/dts/bindings/behaviors/behavior-metadata.yaml
@@ -0,0 +1,6 @@
+# Copyright (c) 2024 The ZMK Contributors
+# SPDX-License-Identifier: MIT
+
+properties:
+  friendly-name:
+    type: string
diff --git a/app/dts/bindings/behaviors/one_param.yaml b/app/dts/bindings/behaviors/one_param.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2020 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+include: behavior-metadata.yaml
+
 properties:
   label:
     type: string

diff --git a/app/dts/bindings/behaviors/two_param.yaml b/app/dts/bindings/behaviors/two_param.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2020 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+include: behavior-metadata.yaml
+
 properties:
   label:
     type: string

diff --git a/app/dts/bindings/behaviors/zero_param.yaml b/app/dts/bindings/behaviors/zero_param.yaml
@@ -1,6 +1,8 @@
 # Copyright (c) 2020 The ZMK Contributors
 # SPDX-License-Identifier: MIT
 
+include: behavior-metadata.yaml
+
 properties:
   label:
     type: string

diff --git a/app/include/drivers/behavior.h b/app/include/drivers/behavior.h
@@ -23,6 +23,50 @@
  * (Internal use only.)
  */
 
+#if IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+
+enum behavior_parameter_standard_domain {
+    BEHAVIOR_PARAMETER_STANDARD_DOMAIN_NULL = 0,
+    BEHAVIOR_PARAMETER_STANDARD_DOMAIN_HID_USAGE = 1,
+    BEHAVIOR_PARAMETER_STANDARD_DOMAIN_LAYER_INDEX = 2,
+    BEHAVIOR_PARAMETER_STANDARD_DOMAIN_HSV = 3,
+};
+
+struct behavior_parameter_value_metadata {
+    char *friendly_name;
+
+    union {
+        uint32_t value;
+        struct {
+            int32_t min;
+            int32_t max;
+        } range;
+
+        enum behavior_parameter_standard_domain standard;
+    };
+
+    enum {
+        BEHAVIOR_PARAMETER_VALUE_METADATA_TYPE_VALUE = 0,
+        BEHAVIOR_PARAMETER_VALUE_METADATA_TYPE_RANGE = 1,
+        BEHAVIOR_PARAMETER_VALUE_METADATA_TYPE_STANDARD = 2,
+    } type;
+};
+
+struct behavior_parameter_metadata_set {
+    size_t param1_values_len;
+    const struct behavior_parameter_value_metadata *param1_values;
+
+    size_t param2_values_len;
+    const struct behavior_parameter_value_metadata *param2_values;
+};
+
+struct behavior_parameter_metadata {
+    size_t sets_len;
+    const struct behavior_parameter_metadata_set *sets;
+};
+
+#endif // IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+
 enum behavior_sensor_binding_process_mode {
     BEHAVIOR_SENSOR_BINDING_PROCESS_MODE_TRIGGER,
     BEHAVIOR_SENSOR_BINDING_PROCESS_MODE_DISCARD,
@@ -37,6 +81,10 @@ typedef int (*behavior_sensor_keymap_binding_accept_data_callback_t)(
     struct zmk_behavior_binding *binding, struct zmk_behavior_binding_event event,
     const struct zmk_sensor_config *sensor_config, size_t channel_data_size,
     const struct zmk_sensor_channel_data channel_data[channel_data_size]);
+#if IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+typedef int (*behavior_get_parameter_metadata_t)(
+    const struct device *behavior, struct behavior_parameter_metadata *param_metadata);
+#endif // IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
 
 enum behavior_locality {
     BEHAVIOR_LOCALITY_CENTRAL,
@@ -51,23 +99,59 @@ __subsystem struct behavior_driver_api {
     behavior_keymap_binding_callback_t binding_released;
     behavior_sensor_keymap_binding_accept_data_callback_t sensor_binding_accept_data;
     behavior_sensor_keymap_binding_process_callback_t sensor_binding_process;
+#if IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+    behavior_get_parameter_metadata_t get_parameter_metadata;
+    const struct behavior_parameter_metadata *parameter_metadata;
+#endif // IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
 };
 /**
  * @endcond
  */
 
+struct zmk_behavior_metadata {
+#if IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+    const char *friendly_name;
+#endif // IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+};
+
 struct zmk_behavior_ref {
     const struct device *device;
+    const struct zmk_behavior_metadata metadata;
 };
 
+#define ZMK_BEHAVIOR_REF_DT_NAME(node_id) _CONCAT(zmk_behavior_, DEVICE_DT_NAME_GET(node_id))
+
+#if IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+
+#define ZMK_BEHAVIOR_METADATA_INITIALIZER(node_id)                                                 \
+    {                                                                                              \
+        .friendly_name = DT_PROP_OR(node_id, friendly_name, DEVICE_DT_NAME(node_id)),              \
+    }
+
+#else
+
+#define ZMK_BEHAVIOR_METADATA_INITIALIZER(node_id)                                                 \
+    {}
+
+#endif // IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+
+#define ZMK_BEHAVIOR_REF_INITIALIZER(node_id, _dev)                                                \
+    {                                                                                              \
+        .device = _dev,                                                                            \
+        .metadata = ZMK_BEHAVIOR_METADATA_INITIALIZER(node_id),                                    \
+    }
+
+#define ZMK_BEHAVIOR_REF_DEFINE(name, node_id, _dev)                                               \
+    static const STRUCT_SECTION_ITERABLE(zmk_behavior_ref, name) =                                 \
+        ZMK_BEHAVIOR_REF_INITIALIZER(node_id, _dev)
+
+#define ZMK_BEHAVIOR_REF_DT_DEFINE(node_id)                                                        \
+    ZMK_BEHAVIOR_REF_DEFINE(ZMK_BEHAVIOR_REF_DT_NAME(node_id), node_id, DEVICE_DT_GET(node_id))
+
 /**
  * Registers @p node_id as a behavior.
  */
-#define BEHAVIOR_DEFINE(node_id)                                                                   \
-    static const STRUCT_SECTION_ITERABLE(zmk_behavior_ref,                                         \
-                                         _CONCAT(zmk_behavior_, DEVICE_DT_NAME_GET(node_id))) = {  \
-        .device = DEVICE_DT_GET(node_id),                                                          \
-    }
+#define BEHAVIOR_DEFINE(node_id) ZMK_BEHAVIOR_REF_DT_DEFINE(node_id)
 
 /**
  * @brief Like DEVICE_DT_DEFINE(), but also registers the device as a behavior.
@@ -120,6 +204,40 @@ static inline int z_impl_behavior_keymap_binding_convert_central_state_dependent
     return api->binding_convert_central_state_dependent_params(binding, event);
 }
 
+#if IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+
+/**
+ * @brief Determine where the behavior should be run
+ * @param behavior Pointer to the device structure for the driver instance.
+ *
+ * @retval Zero if successful.
+ * @retval Negative errno code if failure.
+ */
+__syscall int behavior_get_parameter_metadata(const struct device *behavior,
+                                              struct behavior_parameter_metadata *param_metadata);
+
+static inline int
+z_impl_behavior_get_parameter_metadata(const struct device *behavior,
+                                       struct behavior_parameter_metadata *param_metadata) {
+    if (behavior == NULL || param_metadata == NULL) {
+        return -EINVAL;
+    }
+
+    const struct behavior_driver_api *api = (const struct behavior_driver_api *)behavior->api;
+
+    if (api->get_parameter_metadata) {
+        return api->get_parameter_metadata(behavior, param_metadata);
+    } else if (api->parameter_metadata) {
+        memcpy(param_metadata, api->parameter_metadata, sizeof(struct behavior_parameter_metadata));
+    } else {
+        return -ENODEV;
+    }
+
+    return 0;
+}
+
+#endif // IS_ENABLED(CONFIG_ZMK_BEHAVIOR_METADATA)
+
 /**
  * @brief Determine where the behavior should be run
  * @param behavior Pointer to the device structure for the driver instance.