add optional metadata generation for embedded

Author: yconst

avlos/generators/filters.py

@@ -2,6 +2,25 @@
 from copy import copy
 from typing import List
 
+from avlos.datatypes import DataType
+
+# Avlos_Dtype enum names for metadata (reduced set for UART/ASCII parsing)
+_AVLOS_DTYPE_MAP = {
+    DataType.VOID: "AVLOS_DTYPE_VOID",
+    DataType.BOOL: "AVLOS_DTYPE_BOOL",
+    DataType.UINT8: "AVLOS_DTYPE_UINT8",
+    DataType.INT8: "AVLOS_DTYPE_UINT8",
+    DataType.UINT16: "AVLOS_DTYPE_UINT32",
+    DataType.INT16: "AVLOS_DTYPE_INT32",
+    DataType.UINT32: "AVLOS_DTYPE_UINT32",
+    DataType.INT32: "AVLOS_DTYPE_INT32",
+    DataType.UINT64: "AVLOS_DTYPE_UINT32",
+    DataType.INT64: "AVLOS_DTYPE_INT32",
+    DataType.FLOAT: "AVLOS_DTYPE_FLOAT",
+    DataType.DOUBLE: "AVLOS_DTYPE_FLOAT",
+    DataType.STR: "AVLOS_DTYPE_STRING",
+}
+
 
 def avlos_endpoints(input) -> List:
     """
@@ -101,3 +120,50 @@ def capitalize_first(input: str) -> str:
         String with first character capitalized
     """
     return input[0].upper() + input[1:]
+
+
+def avlos_ep_kind(ep) -> str:
+    """
+    Return the Avlos_EndpointKind enum name for an endpoint (for metadata generation).
+
+    Args:
+        ep: Endpoint object (RemoteAttribute, RemoteFunction, RemoteEnum, or RemoteBitmask)
+
+    Returns:
+        String like AVLOS_EP_KIND_READ_ONLY, AVLOS_EP_KIND_CALL_WITH_ARGS, etc.
+    """
+    has_getter = getattr(ep, "getter_name", None) is not None
+    has_setter = getattr(ep, "setter_name", None) is not None
+    has_caller = getattr(ep, "caller_name", None) is not None
+    if has_caller:
+        num_args = len(getattr(ep, "arguments", None) or [])
+        if num_args == 0:
+            return "AVLOS_EP_KIND_CALL_NO_ARGS"
+        return "AVLOS_EP_KIND_CALL_WITH_ARGS"
+    if has_getter and has_setter:
+        return "AVLOS_EP_KIND_READ_WRITE"
+    if has_getter:
+        return "AVLOS_EP_KIND_READ_ONLY"
+    if has_setter:
+        return "AVLOS_EP_KIND_WRITE_ONLY"
+    return "AVLOS_EP_KIND_READ_ONLY"  # fallback
+
+
+def avlos_metadata_dtype(value) -> str:
+    """
+    Map a DataType or an object with .dtype (endpoint or argument) to Avlos_Dtype enum name.
+
+    Used for value_dtype and arg_dtypes in endpoint metadata. Narrowing (e.g. 64-bit to
+    32-bit) is applied where the metadata enum set is smaller than DataType.
+
+    Args:
+        value: Either a DataType enum member or an object with a .dtype attribute (endpoint, argument)
+
+    Returns:
+        String like AVLOS_DTYPE_UINT32, AVLOS_DTYPE_FLOAT, etc.
+    """
+    dtype = getattr(value, "dtype", value)
+    try:
+        return _AVLOS_DTYPE_MAP[dtype]
+    except KeyError:
+        return "AVLOS_DTYPE_UINT32"  # safe fallback

avlos/generators/generator_c.py

@@ -4,13 +4,60 @@
 from jinja2 import Environment, PackageLoader, select_autoescape
 
 from avlos.formatting import format_c_code, is_clang_format_available
-from avlos.generators.filters import as_include, avlos_bitmask_eps, avlos_endpoints, avlos_enum_eps
+from avlos.generators.filters import (
+    as_include,
+    avlos_bitmask_eps,
+    avlos_endpoints,
+    avlos_enum_eps,
+    avlos_ep_kind,
+    avlos_metadata_dtype,
+)
 from avlos.validation import ValidationError, validate_all
 
 env = Environment(loader=PackageLoader("avlos"), autoescape=select_autoescape())
 
 
+def _generate_metadata_if_requested(instance, config):
+    """Generate endpoint metadata .h/.c when both paths are in config. Returns extra paths or []."""
+    paths = config["paths"]
+    if "output_metadata_header" not in paths or "output_metadata_impl" not in paths:
+        return []
+    meta_header_path = paths["output_metadata_header"]
+    meta_impl_path = paths["output_metadata_impl"]
+    metadata_header_basename = os.path.basename(meta_header_path)
+    os.makedirs(os.path.dirname(meta_header_path), exist_ok=True)
+    template_meta_h = env.get_template("avlos_endpoint_metadata.h.jinja")
+    with open(meta_header_path, "w") as f:
+        print(template_meta_h.render(), file=f)
+    os.makedirs(os.path.dirname(meta_impl_path), exist_ok=True)
+    template_meta_c = env.get_template("avlos_endpoint_metadata.c.jinja")
+    with open(meta_impl_path, "w") as f:
+        print(
+            template_meta_c.render(
+                instance=instance,
+                metadata_header_basename=metadata_header_basename,
+            ),
+            file=f,
+        )
+    return [meta_header_path, meta_impl_path]
+
+
 def process(instance, config):
+    # Validate config has required paths
+    required_paths = ["output_enums", "output_header", "output_impl"]
+    if "paths" not in config:
+        raise ValidationError(
+            "Config validation failed: Missing 'paths' section in avlos config.\n"
+            "Please add a 'paths' section with: output_enums, output_header, output_impl"
+        )
+
+    missing_paths = [p for p in required_paths if p not in config["paths"]]
+    if missing_paths:
+        raise ValidationError(
+            f"Config validation failed: Missing required paths in avlos config: {', '.join(missing_paths)}\n"
+            f"Please add these paths to the 'paths' section of your avlos config file."
+        )
+
     # Validate before generation
     validation_errors = validate_all(instance)
     if validation_errors:
@@ -21,6 +68,8 @@ def process(instance, config):
     env.filters["enum_eps"] = avlos_enum_eps
     env.filters["bitmask_eps"] = avlos_bitmask_eps
     env.filters["as_include"] = as_include
+    env.filters["avlos_ep_kind"] = avlos_ep_kind
+    env.filters["avlos_metadata_dtype"] = avlos_metadata_dtype
 
     template = env.get_template("tm_enums.h.jinja")
     os.makedirs(os.path.dirname(config["paths"]["output_enums"]), exist_ok=True)
@@ -54,17 +103,16 @@ def process(instance, config):
             file=output_file,
         )
 
-    # Post-process with clang-format if available
-    format_style = config.get("format_style", "LLVM")
-
-    generated_files = [
+    base_files = [
         config["paths"]["output_enums"],
         config["paths"]["output_header"],
         config["paths"]["output_impl"],
     ]
+    generated_files = base_files + _generate_metadata_if_requested(instance, config)
 
+    # Post-process with clang-format if available
+    format_style = config.get("format_style", "LLVM")
     for file_path in generated_files:
         success = format_c_code(file_path, format_style)
         if not success and is_clang_format_available():
-            # Only warn if clang-format is installed but failed
             print(f"Warning: clang-format failed for {file_path}", file=sys.stderr)

avlos/generators/generator_cpp.py

@@ -12,6 +12,21 @@
 
 
 def process(instance, config):
+    # Validate config has required paths
+    required_paths = ["output_helpers", "output_header", "output_impl"]
+    if "paths" not in config:
+        raise ValidationError(
+            "Config validation failed: Missing 'paths' section in avlos config.\n"
+            "Please add a 'paths' section with: output_helpers, output_header, output_impl"
+        )
+
+    missing_paths = [p for p in required_paths if p not in config["paths"]]
+    if missing_paths:
+        raise ValidationError(
+            f"Config validation failed: Missing required paths in avlos config: {', '.join(missing_paths)}\n"
+            f"Please add these paths to the 'paths' section of your avlos config file."
+        )
+
     # Validate before generation
     validation_errors = validate_all(instance)
     if validation_errors:

avlos/templates/avlos_endpoint_metadata.c.jinja

@@ -0,0 +1,34 @@
+/*
+* This file was automatically generated using Avlos.
+* https://github.com/tinymovr/avlos
+*
+* Any changes to this file will be overwritten when
+* content is regenerated.
+*/
+
+#include "{{ metadata_header_basename }}"
+
+{% set eps = instance | endpoints %}
+const Avlos_EndpointMeta avlos_endpoint_meta[] = {
+{% for ep in eps %}
+    /* {{ ep.endpoint_function_name }} */
+    [{{ ep.ep_id }}] = {
+        .kind = {{ ep | avlos_ep_kind }},
+        .value_dtype = {{ ep | avlos_metadata_dtype }},
+        .num_args = {% if ep | avlos_ep_kind == "AVLOS_EP_KIND_CALL_WITH_ARGS" %}{{ ep.arguments | length }}{% else %}0{% endif %},
+        .arg_dtypes = {
+            {%- for i in range(4) %}
+            {%- if ep | avlos_ep_kind == "AVLOS_EP_KIND_CALL_WITH_ARGS" and i < (ep.arguments | length) %}
+            {{ ep.arguments[i] | avlos_metadata_dtype }}
+            {%- else %}
+            AVLOS_DTYPE_VOID
+            {%- endif %}
+            {%- if i < 3 %}, {% endif %}
+            {%- endfor %}
+        }
+    }{% if not loop.last %},{% endif %}
+
+{% endfor %}
+};
+
+const uint8_t avlos_endpoint_meta_count = sizeof(avlos_endpoint_meta) / sizeof(avlos_endpoint_meta[0]);

avlos/templates/avlos_endpoint_metadata.h.jinja

@@ -0,0 +1,43 @@
+/*
+* This file was automatically generated using Avlos.
+* https://github.com/tinymovr/avlos
+*
+* Any changes to this file will be overwritten when
+* content is regenerated.
+*
+* Endpoint type metadata for type-aware UART/ASCII parsing and formatting.
+* No dependency on UART; consumed by the firmware layer.
+*/
+
+#pragma once
+#include <stdint.h>
+
+typedef enum {
+    AVLOS_DTYPE_UINT8,
+    AVLOS_DTYPE_UINT32,
+    AVLOS_DTYPE_INT32,
+    AVLOS_DTYPE_FLOAT,
+    AVLOS_DTYPE_BOOL,
+    AVLOS_DTYPE_STRING,
+    AVLOS_DTYPE_VOID
+} Avlos_Dtype;
+
+typedef enum {
+    AVLOS_EP_KIND_READ_ONLY,
+    AVLOS_EP_KIND_WRITE_ONLY,
+    AVLOS_EP_KIND_READ_WRITE,
+    AVLOS_EP_KIND_CALL_NO_ARGS,
+    AVLOS_EP_KIND_CALL_WITH_ARGS
+} Avlos_EndpointKind;
+
+#define AVLOS_MAX_CALL_ARGS 4
+
+typedef struct {
+    Avlos_EndpointKind kind;
+    Avlos_Dtype value_dtype;
+    uint8_t num_args;
+    Avlos_Dtype arg_dtypes[AVLOS_MAX_CALL_ARGS];
+} Avlos_EndpointMeta;
+
+extern const Avlos_EndpointMeta avlos_endpoint_meta[];
+extern const uint8_t avlos_endpoint_meta_count;

docs/config.rst

@@ -74,6 +74,16 @@ The output config defines the output modules that will be used and their options
 
 There are three main generated files that are configured above: A header containing enums (`output_enums`), a header containing function declarations (`output_header`), and an implementation containing function definitions (`output_impl`).
 
+Optional: Endpoint metadata (for type-aware UART/ASCII parsing)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want the C generator to emit an endpoint type metadata table (so firmware can parse and format ASCII without a hand-maintained table), add both of these optional paths under ``paths``:
+
+- ``output_metadata_header``: Path for the generated metadata header (e.g. ``fw/avlos_endpoint_metadata.h``).
+- ``output_metadata_impl``: Path for the generated metadata implementation (e.g. ``fw/avlos_endpoint_metadata.c``).
+
+When both are present, Avlos generates ``Avlos_EndpointMeta avlos_endpoint_meta[]`` and ``avlos_endpoint_meta_count`` in the same order as ``avlos_endpoints[]``. Each entry describes the endpoint kind (read-only, read-write, call with/without args), value type, and for callables the argument types. If either path is omitted, no metadata files are generated (backward compatible).
+
 Of note is that no #include statements for the generated files are generated automatically. This is something that we decided in order to maximize compatibility to edge cases, but may be revised in future Avlos versions.
 
 CLI Usage

example/avlos_config.yaml

@@ -4,6 +4,9 @@ generators:
         paths:
             output_header: fw/protocol.h
             output_impl: fw/protocol.c
+            # Optional: emit endpoint type metadata for type-aware UART/ASCII (uncomment to enable)
+            # output_metadata_header: fw/avlos_endpoint_metadata.h
+            # output_metadata_impl: fw/avlos_endpoint_metadata.c
         header_includes:
         - header.h
         impl_includes: