alt_core_api: Add protoc plugin for generating IPC definitions

Add `protoc-gen-arduinoif`, a protobuf plugin that generates
IPC/interface headers from IDL `.proto` files.

The plugin treats protobuf services as the IDL source and emits
the current header surface used by `alt_core_api`.
Runtime IPC/RPC transport and stub implementations are intentionally
 out of scope for now.

Signed-off-by: TOKITA Hiroshi <tokita.hiroshi@gmail.com>

Author: soburi

alt_core_api/tools/protoc-gen-arduinoif

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2026 TOKITA Hiroshi
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+import pathlib
+
+SCRIPT_DIR = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from protoc_gen_arduinoif.core import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

alt_core_api/tools/protoc_gen_arduinoif/common.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2026 TOKITA Hiroshi
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import re
+import sys
+import types
+from functools import lru_cache
+from pathlib import Path
+from typing import List
+
+__all__ = [
+    "full_service_name",
+    "snake_case",
+    "uniq",
+    "get_arduino_opts_pb2",
+]
+
+
+def full_service_name(pkgname: str, servicename: str) -> str:
+    return f".{pkgname}.{servicename}" if pkgname else f".{servicename}"
+
+
+def snake_case(name: str) -> str:
+    word_edges = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", word_edges).lower()
+
+
+def uniq(values: List[str]) -> List[str]:
+    return list(dict.fromkeys(values))
+
+
+@lru_cache(maxsize=1)
+def get_arduino_opts_pb2() -> types.ModuleType:
+    module_name = "_protoc_gen_arduinoif_arduino_opts_pb2"
+    pb2_path = os.environ.get("PROTOC_GEN_ARDUINOIF_PB2")
+    if not pb2_path:
+        raise RuntimeError(
+            "PROTOC_GEN_ARDUINOIF_PB2 is not set; it must point to the "
+            "generated arduino_opts_pb2.py file before running "
+            "protoc-gen-arduinoif"
+        )
+
+    source_path = Path(pb2_path)
+    if not source_path.exists():
+        raise RuntimeError(
+            f"PROTOC_GEN_ARDUINOIF_PB2 points to a missing file: '{source_path}'"
+        )
+
+    spec = importlib.util.spec_from_file_location(module_name, source_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(
+            "failed to load arduino_opts_pb2 from "
+            f"PROTOC_GEN_ARDUINOIF_PB2='{source_path}'"
+        )
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module

alt_core_api/tools/protoc_gen_arduinoif/core.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2026 TOKITA Hiroshi
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import sys
+from typing import Iterator, Tuple
+
+from google.protobuf.compiler import plugin_pb2 as pb2
+
+from .common import get_arduino_opts_pb2
+from .enum_renderer import EnumRenderer
+from .service_renderer import ServiceRenderer
+from .service_model import ServiceModelBuilder
+from .request_context import RequestContext
+
+__all__ = [
+    "main",
+]
+
+
+def _iter_generated_files(
+    request: pb2.CodeGeneratorRequest,
+) -> Iterator[Tuple[str, str]]:
+    context = RequestContext.build(request)
+    proto_names = {proto_file.name: proto_file for proto_file in request.proto_file}
+    generated_files = [proto_names[name] for name in request.file_to_generate]
+
+    for proto_file in generated_files:
+        if proto_file.enum_type and not proto_file.service:
+            yield from EnumRenderer(proto_file.name, list(proto_file.enum_type))
+
+        for service in proto_file.service:
+            service_model = ServiceModelBuilder.build(
+                service,
+                proto_file.package,
+                list(proto_file.enum_type),
+                context,
+            )
+            yield from ServiceRenderer(service_model)
+
+
+def main() -> int:
+    # Extensions must be registered before parsing request payload.
+    get_arduino_opts_pb2()
+    req = pb2.CodeGeneratorRequest()
+    req.ParseFromString(sys.stdin.buffer.read())
+    resp = pb2.CodeGeneratorResponse()
+
+    try:
+        for name, content in _iter_generated_files(req):
+            output = resp.file.add()
+            output.name = name
+            output.content = content
+    except Exception as error:
+        resp.error = str(error)
+
+    if hasattr(pb2.CodeGeneratorResponse, "FEATURE_PROTO3_OPTIONAL"):
+        resp.supported_features = pb2.CodeGeneratorResponse.FEATURE_PROTO3_OPTIONAL
+
+    sys.stdout.buffer.write(resp.SerializeToString())
+    return 0

alt_core_api/tools/protoc_gen_arduinoif/enum_renderer.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2026 TOKITA Hiroshi
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from typing import Iterator, List, Tuple
+
+from google.protobuf.descriptor_pb2 import EnumDescriptorProto
+
+__all__ = [
+    "EnumRenderer",
+]
+
+
+class EnumRenderer:
+    """Renders top-level protobuf enums as a C-compatible type header."""
+
+    def __init__(self, proto_name: str, enums: List[EnumDescriptorProto]) -> None:
+        self._proto_name = proto_name
+        self._enums = enums
+
+    def __iter__(self) -> Iterator[Tuple[str, str]]:
+        yield self._header_name(), self._render_header_content()
+
+    def _header_name(self) -> str:
+        return f"{PurePosixPath(self._proto_name).stem}_types.h"
+
+    def _render_header_content(self) -> str:
+        lines = [
+            "// Generated by protoc-gen-arduinoif. DO NOT EDIT.",
+            "",
+            "#pragma once",
+            "",
+            "#include <stdint.h>",
+            "",
+        ]
+
+        for enum_desc in self._enums:
+            lines.extend([f"typedef enum {enum_desc.name} {{"])
+            lines.extend(f"  {v.name} = {v.number}," for v in enum_desc.value)
+            lines.extend([f"}} {enum_desc.name};", ""])
+
+        return "\n".join(lines)

alt_core_api/tools/protoc_gen_arduinoif/method_spec.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2026 TOKITA Hiroshi
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Dict, List, NamedTuple, Tuple
+
+from google.protobuf.descriptor_pb2 import DescriptorProto, FieldDescriptorProto
+
+__all__ = [
+    "MethodSpec",
+]
+
+_DEFAULT_FIELD_CPP_TYPES: Dict[int, str] = {
+    FieldDescriptorProto.TYPE_BOOL: "bool",
+    FieldDescriptorProto.TYPE_INT32: "int32_t",
+    FieldDescriptorProto.TYPE_INT64: "int64_t",
+    FieldDescriptorProto.TYPE_UINT32: "uint32_t",
+    FieldDescriptorProto.TYPE_UINT64: "uint64_t",
+    FieldDescriptorProto.TYPE_SINT32: "int32_t",
+    FieldDescriptorProto.TYPE_SINT64: "int64_t",
+    FieldDescriptorProto.TYPE_FIXED32: "uint32_t",
+    FieldDescriptorProto.TYPE_FIXED64: "uint64_t",
+    FieldDescriptorProto.TYPE_SFIXED32: "int32_t",
+    FieldDescriptorProto.TYPE_SFIXED64: "int64_t",
+    FieldDescriptorProto.TYPE_FLOAT: "float",
+    FieldDescriptorProto.TYPE_DOUBLE: "double",
+    FieldDescriptorProto.TYPE_STRING: "const char *",
+    FieldDescriptorProto.TYPE_BYTES: "const uint8_t *",
+    FieldDescriptorProto.TYPE_ENUM: "int32_t",
+}
+
+
+def _opt_str(options, extension) -> str:
+    try:
+        return str(options.Extensions[extension]).strip()
+    except (AttributeError, KeyError):
+        return ""
+
+
+class MethodSpec(NamedTuple):
+    """C++ method signature derived from one protobuf RPC method."""
+
+    decl: str
+    overload_key: Tuple[str, Tuple[str, ...]]
+    call_name: str
+    arg_names: List[str]
+    returns_void: bool
+    visibility: str
+
+    @classmethod
+    def build(
+        cls,
+        method,
+        opts_pb2,
+        message_map: Dict[str, DescriptorProto],
+    ) -> "MethodSpec":
+        def _resolve_field(field: FieldDescriptorProto) -> Tuple[str, str]:
+            field_opts = field.options
+            explicit_cpp_type = _opt_str(field_opts, opts_pb2.cpp_type)
+            if explicit_cpp_type:
+                field_type = explicit_cpp_type
+            else:
+                if field.label == FieldDescriptorProto.LABEL_REPEATED:
+                    raise ValueError(
+                        f"{method.name}: field '{field.name}' is repeated; "
+                        "C++ header generation requires an explicit "
+                        "(arduino.cpp_type) override"
+                    )
+                if field.type not in _DEFAULT_FIELD_CPP_TYPES:
+                    raise ValueError(
+                        f"{method.name}: field '{field.name}' has unsupported "
+                        f"protobuf type '{field.type}'; C++ header generation "
+                        "requires an explicit (arduino.cpp_type) override"
+                    )
+                field_type = _DEFAULT_FIELD_CPP_TYPES[field.type]
+            field_name = _opt_str(field_opts, opts_pb2.field_cpp_name) or field.name
+            return field_type, field_name
+
+        input_msg = message_map.get(method.input_type)
+        output_msg = message_map.get(method.output_type)
+
+        if input_msg is None:
+            raise ValueError(
+                f"{method.name}: unknown input type '{method.input_type}'; "
+                "use google.protobuf.Empty for methods without parameters"
+            )
+        if output_msg is None:
+            raise ValueError(
+                f"{method.name}: unknown output type '{method.output_type}'; "
+                "use google.protobuf.Empty for void methods"
+            )
+        if len(output_msg.field) > 1:
+            raise ValueError(
+                f"{method.name}: output type '{method.output_type}' has "
+                f"{len(output_msg.field)} fields; C++ header generation supports "
+                "void outputs or a single return-value field"
+            )
+
+        visibility = _opt_str(method.options, opts_pb2.method_visibility).lower()
+        if visibility not in {"public", "protected", "private", ""}:
+            raise ValueError(
+                f"{method.name}: unsupported method_visibility '{visibility}' "
+                "(expected: public, protected, private)"
+            )
+        if not visibility:
+            visibility = "public"
+
+        method_name = _opt_str(method.options, opts_pb2.cpp_name) or method.name
+        return_type = _opt_str(method.options, opts_pb2.cpp_return)
+        if not return_type:
+            return_type = (
+                "void"
+                if len(output_msg.field) == 0
+                else _resolve_field(output_msg.field[0])[0]
+            )
+
+        params = [_resolve_field(f) for f in input_msg.field]
+        arg_types = tuple(ftype for ftype, _ in params)
+        arg_names = [name for _, name in params]
+        params_blob = ", ".join(f"{ftype} {fname}" for ftype, fname in params)
+
+        decl = (
+            f"{method_name}({params_blob})"
+            if method_name.startswith("operator ")
+            else f"{return_type} {method_name}({params_blob})"
+        )
+
+        return cls(
+            decl=decl,
+            overload_key=(method_name, arg_types),
+            call_name=method_name,
+            arg_names=arg_names,
+            returns_void=(return_type == "void"),
+            visibility=visibility,
+        )