can-api-generator 2.3.0__tar.gz → 2.5.0__tar.gz

{can_api_generator-2.3.0 → can_api_generator-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: can-api-generator
-Version: 2.3.0
+Version: 2.5.0
 Summary: Program to generate a 'signal' style CAN API in C
 Project-URL: Documentation, https://sr.ht/~laplace/can-api-generator#readme
 Project-URL: Issues, https://sr.ht/~laplace/can-api-generator/issues
@@ -20,6 +20,7 @@ Requires-Dist: can-db-model>=0.1
 Requires-Dist: cantools
 Requires-Dist: click
 Requires-Dist: jinja2
+Requires-Dist: pyyaml
 Requires-Dist: rich
 Description-Content-Type: text/markdown
 
@@ -45,6 +46,7 @@ Description-Content-Type: text/markdown
   - [Double-buffered signal access](#double-buffered-signal-access)
   - [RX/TX callback context](#rxtx-callback-context)
   - [Message signals as RX callback argument](#message-signals-as-rx-callback-argument)
+  - [Current time as callback argument](#current-time-as-callback-argument)
   - [Using your own frame type](#using-your-own-frame-type)
 - [Example Use](#example-use)
 - [Dynamic decoding](#dynamic-decoding)
@@ -55,6 +57,7 @@ Description-Content-Type: text/markdown
   - [`api`](#api)
   - [`cbdb`](#cbdb)
   - [`dyndec`](#dyndec)
+  - [Config file](#config-file)
 
 ## Installation
 
@@ -353,6 +356,17 @@ Passing `--msg-as-rx-callback-arg` instead hands the callback a `void *` pointin
 
 `struct MsgRxContext` remains a single shared type, which is why the signal struct is passed as `void *` rather than a typed pointer.
 
+### Current time as callback argument
+
+The `now` handed to `<api>_process_received_frame` and `<api>_periodic_tx` can be forwarded to the callbacks, so a callback that timestamps, filters or rate-limits
+does not have to read the clock again (and sees exactly the time the API used for `last_rx` / `last_tx`). The two paths have separate flags:
+
+* `--time-as-rx-callback-arg` adds a `uint64_t now` parameter to the RX callback.
+* `--time-as-tx-callback-arg` adds a `uint64_t now` parameter to the TX callback.
+
+Arguments are always in the order message pointer, time, context pointer, each present only when its flag is set. With every RX flag the callback is
+`void (*rx_callback)(void *msg, uint64_t now, void *ctx)`; with only `--time-as-tx-callback-arg` it is `void *(*tx_callback)(uint64_t now)`.
+
 ### Using your own frame type
 
 By default every generated function takes a `CanFrame *`, and the generator writes a sibling `canframe.h` that defines `CanFrame`. If the application already has a
@@ -598,6 +612,7 @@ to a mux group. The message list is followed immediately by that message's signa
 ## Command-line reference
 
 All generation is done through subcommands of `can-api-gen`. Run `can-api-gen COMMAND --help` for the authoritative option list.
+Every command also accepts `--config FILE`; see [Config file](#config-file).
 
 ### `api`
 
@@ -643,6 +658,10 @@ Options:
   `--tx-signal-store` the pointer is the message's store struct, which the callback edits in place before encode; in callback-only mode `<api>_periodic_tx` stack-allocates
   the struct, and the callback fills it and returns it (or `NULL` to skip), so no application-provided storage is needed. See [Periodic TX](#periodic-tx). Only meaningful
   together with `-p`.
+* `--time-as-rx-callback-arg` — pass the `now` of `<api>_process_received_frame` to the RX callback as a `uint64_t`, after the message pointer and before the
+  context pointer. See [Current time as callback argument](#current-time-as-callback-argument). Only meaningful together with `-r`.
+* `--time-as-tx-callback-arg` — pass the `now` of `<api>_periodic_tx` to the TX callback as a `uint64_t`, after the message pointer and before the context
+  pointer. See [Current time as callback argument](#current-time-as-callback-argument). Only meaningful together with `-p`.
 * `--tx-function` — bind a `uint16_t (*tx_function)(void *, const <frame> *)` and its context to the periodic-TX API through `<api>_periodic_tx_init`;
   `<api>_periodic_tx(tx_signals, now)` then queues every due message through it in one pass and returns the number accepted. A 0 return leaves `last_tx` and
   `send_now` untouched so the message is retried. See [Queueing frames through a bound TX function](#queueing-frames-through-a-bound-tx-function). Only meaningful
@@ -699,3 +718,23 @@ Options:
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).
 * `-pm`, `--payload-member-name TEXT` — override the name of the `CanFrame` payload member (default `payload`).
 * `--help` — show the CLI help and exit.
+
+### Config file
+
+Instead of repeating a long flag list, put the options in a YAML file and pass it with `--config FILE` to any command. The file has one section per command, so
+one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` (dashes or
+underscores both work), and values are the option values (`true`/`false` for flags):
+
+```yaml
+api:
+  periodic-tx: true
+  tx-signal-store: true
+  time-as-tx-callback-arg: true
+  id-member-name: can_id
+dyndec:
+  id-member-name: can_id
+```
+
+Anything given on the command line overrides the file. Every flag has a `--no-` form for this, e.g.
+`can-api-gen api --config can.yaml --no-tx-signal-store db.kcd my_api DUT`. Positional arguments (`DB_FILE`, `LIBRARY_NAME`, `NODE_NAME`, …) always come from
+the command line. An unknown key or an invalid value is an error.

{can_api_generator-2.3.0 → can_api_generator-2.5.0}/README.md

@@ -20,6 +20,7 @@
   - [Double-buffered signal access](#double-buffered-signal-access)
   - [RX/TX callback context](#rxtx-callback-context)
   - [Message signals as RX callback argument](#message-signals-as-rx-callback-argument)
+  - [Current time as callback argument](#current-time-as-callback-argument)
   - [Using your own frame type](#using-your-own-frame-type)
 - [Example Use](#example-use)
 - [Dynamic decoding](#dynamic-decoding)
@@ -30,6 +31,7 @@
   - [`api`](#api)
   - [`cbdb`](#cbdb)
   - [`dyndec`](#dyndec)
+  - [Config file](#config-file)
 
 ## Installation
 
@@ -328,6 +330,17 @@ Passing `--msg-as-rx-callback-arg` instead hands the callback a `void *` pointin
 
 `struct MsgRxContext` remains a single shared type, which is why the signal struct is passed as `void *` rather than a typed pointer.
 
+### Current time as callback argument
+
+The `now` handed to `<api>_process_received_frame` and `<api>_periodic_tx` can be forwarded to the callbacks, so a callback that timestamps, filters or rate-limits
+does not have to read the clock again (and sees exactly the time the API used for `last_rx` / `last_tx`). The two paths have separate flags:
+
+* `--time-as-rx-callback-arg` adds a `uint64_t now` parameter to the RX callback.
+* `--time-as-tx-callback-arg` adds a `uint64_t now` parameter to the TX callback.
+
+Arguments are always in the order message pointer, time, context pointer, each present only when its flag is set. With every RX flag the callback is
+`void (*rx_callback)(void *msg, uint64_t now, void *ctx)`; with only `--time-as-tx-callback-arg` it is `void *(*tx_callback)(uint64_t now)`.
+
 ### Using your own frame type
 
 By default every generated function takes a `CanFrame *`, and the generator writes a sibling `canframe.h` that defines `CanFrame`. If the application already has a
@@ -573,6 +586,7 @@ to a mux group. The message list is followed immediately by that message's signa
 ## Command-line reference
 
 All generation is done through subcommands of `can-api-gen`. Run `can-api-gen COMMAND --help` for the authoritative option list.
+Every command also accepts `--config FILE`; see [Config file](#config-file).
 
 ### `api`
 
@@ -618,6 +632,10 @@ Options:
   `--tx-signal-store` the pointer is the message's store struct, which the callback edits in place before encode; in callback-only mode `<api>_periodic_tx` stack-allocates
   the struct, and the callback fills it and returns it (or `NULL` to skip), so no application-provided storage is needed. See [Periodic TX](#periodic-tx). Only meaningful
   together with `-p`.
+* `--time-as-rx-callback-arg` — pass the `now` of `<api>_process_received_frame` to the RX callback as a `uint64_t`, after the message pointer and before the
+  context pointer. See [Current time as callback argument](#current-time-as-callback-argument). Only meaningful together with `-r`.
+* `--time-as-tx-callback-arg` — pass the `now` of `<api>_periodic_tx` to the TX callback as a `uint64_t`, after the message pointer and before the context
+  pointer. See [Current time as callback argument](#current-time-as-callback-argument). Only meaningful together with `-p`.
 * `--tx-function` — bind a `uint16_t (*tx_function)(void *, const <frame> *)` and its context to the periodic-TX API through `<api>_periodic_tx_init`;
   `<api>_periodic_tx(tx_signals, now)` then queues every due message through it in one pass and returns the number accepted. A 0 return leaves `last_tx` and
   `send_now` untouched so the message is retried. See [Queueing frames through a bound TX function](#queueing-frames-through-a-bound-tx-function). Only meaningful
@@ -674,3 +692,23 @@ Options:
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).
 * `-pm`, `--payload-member-name TEXT` — override the name of the `CanFrame` payload member (default `payload`).
 * `--help` — show the CLI help and exit.
+
+### Config file
+
+Instead of repeating a long flag list, put the options in a YAML file and pass it with `--config FILE` to any command. The file has one section per command, so
+one file can serve `api`, `cbdb` and `dyndec`; a command reads only its own section. Keys are the long option names without the leading `--` (dashes or
+underscores both work), and values are the option values (`true`/`false` for flags):
+
+```yaml
+api:
+  periodic-tx: true
+  tx-signal-store: true
+  time-as-tx-callback-arg: true
+  id-member-name: can_id
+dyndec:
+  id-member-name: can_id
+```
+
+Anything given on the command line overrides the file. Every flag has a `--no-` form for this, e.g.
+`can-api-gen api --config can.yaml --no-tx-signal-store db.kcd my_api DUT`. Positional arguments (`DB_FILE`, `LIBRARY_NAME`, `NODE_NAME`, …) always come from
+the command line. An unknown key or an invalid value is an error.

{can_api_generator-2.3.0 → can_api_generator-2.5.0}/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
   'jinja2',
   'click',
   'rich',
+  'pyyaml',
 ]
 
 [project.urls]

{can_api_generator-2.3.0 → can_api_generator-2.5.0}/src/can_api_generator/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Alexande Becker <nabla.becker@mailbox.org>
 #
 # SPDX-License-Identifier: LGPL-3.0-only
-__version__ = "2.3.0"
+__version__ = "2.5.0"

{can_api_generator-2.3.0 → can_api_generator-2.5.0}/src/can_api_generator/main.py

@@ -12,6 +12,51 @@ from can_api_generator.cbdb_generator import generate_cbdb, build_sidecar, CbdbG
 from can_api_generator.utils import converrt_to_c_identifier
 from jinja2 import Environment, FileSystemLoader
 from pathlib import Path
+import yaml
+
+
+def _load_config(ctx, param, value):
+    """Turn the command's section of a YAML config file into click defaults.
+
+    The file maps command names to option tables, e.g. {"api": {"periodic-tx":
+    true}}. Keys are long option names (dashes or underscores). The values
+    become ctx.default_map, so every option given on the command line still
+    takes precedence over the file.
+    """
+    if value is None:
+        return
+    try:
+        with open(value) as config_file:
+            data = yaml.safe_load(config_file)
+    except (OSError, yaml.YAMLError) as e:
+        raise click.BadParameter(f"cannot read config file: {e}", ctx, param)
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise click.BadParameter(
+            "the config file must map command names to option tables", ctx, param)
+    section = data.get(ctx.info_name) or {}
+    if not isinstance(section, dict):
+        raise click.BadParameter(
+            f"section '{ctx.info_name}' must map option names to values", ctx, param)
+    known = {p.name for p in ctx.command.params
+             if isinstance(p, click.Option) and p.name != "config"}
+    defaults = {}
+    for key, option_value in section.items():
+        name = str(key).replace("-", "_")
+        if name not in known:
+            raise click.BadParameter(
+                f"unknown option '{key}' in section '{ctx.info_name}'", ctx, param)
+        defaults[name] = option_value
+    ctx.default_map = {**(ctx.default_map or {}), **defaults}
+
+
+config_option = click.option(
+    "--config", type=click.Path(exists=True, dir_okay=False),
+    is_eager=True, expose_value=False, callback=_load_config,
+    help="YAML file providing defaults for this command's options, under a "
+         "section named after the command (api, cbdb, dyndec). Options given "
+         "on the command line override the file.")
 
 
 @click.group()
@@ -23,13 +68,14 @@ def main():
 
 
 @main.command()
+@config_option
 @click.argument("DB_File", type=click.Path(exists=True, dir_okay=False),
                 required=True, nargs=1)
 @click.argument("Library_Name", type=str, required=True)
 @click.argument("Node_Name", type=str, required=True)
-@click.option("-f", "--force", is_flag=True, required=False, default=False,
+@click.option("-f", "--force/--no-force", required=False, default=False,
               help="Overwrite existing output files")
-@click.option("-a", "--encode-all-signals-func", is_flag=True, default=False,
+@click.option("-a", "--encode-all-signals-func/--no-encode-all-signals-func", default=False,
               help="Generate a function for each message that encodes every signal into frames at least once,"
                    " this is helpful when some signals are inside of a mux, but all signals need to be sent "
                    " regardless of how many frames need to be encoded to send the state of each signal at least"
@@ -50,74 +96,74 @@ def main():
 @click.option("-pm", "--payload-member-name", type=str, default="payload",
               help="The name of the CanFrame struct member that holds the "
                    "payload as uint64")
-@click.option("-r", "--global-rx", is_flag=True, default=False,
+@click.option("-r", "--global-rx/--no-global-rx", default=False,
               help="Generate a function and api-wide struct that updates an"
                    " api message struct upon reception of a matching frame")
-@click.option("-p", "--periodic-tx", is_flag=True, default=False,
+@click.option("-p", "--periodic-tx/--no-periodic-tx", default=False,
               help="Generate code that will define a TX struct as well as a function "
               "that periodically sends the messages according to their "
               "periodicity")
-@click.option("--ti-compatible", is_flag=True, default=False,
+@click.option("--ti-compatible/--no-ti-compatible", default=False,
               help="Generate C code that can be compiled using the TI C2000 compiler"
                    " The TI compiler does not handle variable declarations inside of case"
                    " blocks so the variable declaration is moved to the top of a switch")
-@click.option("--send-now", is_flag=True, default=False,
+@click.option("--send-now/--no-send-now", default=False,
               help="Add mechanism in to the periodic tx function that allows to immediately "
                    "send a message even if it is not enabled or has just been sent."
                    " This is useful for updating critical signals as early as possible after a change")
-@click.option("--double-buffered", is_flag=True, default=False,
+@click.option("--double-buffered/--no-double-buffered", default=False,
               help="Generate double-buffered signal storage so that an ISR can safely decode"
                    " RX frames without exposing a partially-decoded struct to readers, and so"
                    " that user code can stage TX signal updates without racing the periodic TX"
                    " encoder. Swaps are performed via per-message pointer swaps; an explicit"
                    " <api>_<msg>_commit call is required to publish staged TX values.")
-@click.option("--rx-callback-context", is_flag=True, default=False,
+@click.option("--rx-callback-context/--no-rx-callback-context", default=False,
               help="Add a void *rx_callback_context field to MsgRxContext and "
                    "pass it as the sole argument to the RX callback, widening "
                    "its signature to void (*rx_callback)(void *).")
-@click.option("--tx-callback-context", is_flag=True, default=False,
+@click.option("--tx-callback-context/--no-tx-callback-context", default=False,
               help="Add a void *tx_callback_context field to MsgTxContext and "
                    "pass it as the sole argument to the TX callback, widening "
                    "its signature to void (*tx_callback)(void *).")
-@click.option("--msg-as-rx-callback-arg", is_flag=True, default=False,
+@click.option("--msg-as-rx-callback-arg/--no-msg-as-rx-callback-arg", default=False,
               help="Pass a void * to the message's just-decoded signal struct "
                    "as the first argument to the RX callback. Composes with "
                    "--rx-callback-context, which appends the context pointer as "
                    "a second argument. Only meaningful together with -r.")
-@click.option("--rx-signal-store", is_flag=True, default=False,
+@click.option("--rx-signal-store/--no-rx-signal-store", default=False,
               help="Generate a permanent per-message RX signal store in the "
                    "global RX struct (the default before v2.0). Without it, "
                    "global RX is callback-only: decoded signals reach the "
                    "application solely through the per-message RX callback and "
                    "are never stored. Only meaningful together with -r.")
-@click.option("--with-rx-valid", is_flag=True, default=False,
+@click.option("--with-rx-valid/--no-with-rx-valid", default=False,
               help="In callback-only mode (no --rx-signal-store), add a valid "
                    "field to MsgRxContext and set it on each matched frame, for "
                    "struct-layout compatibility with store-based APIs. No effect "
                    "when --rx-signal-store is set.")
-@click.option("--msg-as-tx-callback-arg", is_flag=True, default=False,
+@click.option("--msg-as-tx-callback-arg/--no-msg-as-tx-callback-arg", default=False,
               help="Pass a void * to the message's store struct (the one about "
                    "to be encoded) as the first argument to the TX callback. "
                    "Composes with --tx-callback-context, which appends the "
                    "context pointer as a second argument. Only meaningful "
                    "together with -p.")
-@click.option("--tx-signal-store", is_flag=True, default=False,
+@click.option("--tx-signal-store/--no-tx-signal-store", default=False,
               help="Generate a permanent per-message TX signal store in the "
                    "periodic-TX struct (the default before v2.0). Without it, "
                    "periodic TX is callback-only: each scheduled message's "
                    "callback returns the struct to encode, and a NULL return or "
                    "missing callback sends nothing. Only meaningful with -p.")
-@click.option("--time-as-rx-callback-arg", is_flag=True, default=False,
+@click.option("--time-as-rx-callback-arg/--no-time-as-rx-callback-arg", default=False,
               help="Pass the current time (the now argument of "
                    "<api>_process_received_frame) to the RX callback as a "
                    "uint64_t, after the message pointer and before the context "
                    "pointer. Only meaningful together with -r.")
-@click.option("--time-as-tx-callback-arg", is_flag=True, default=False,
+@click.option("--time-as-tx-callback-arg/--no-time-as-tx-callback-arg", default=False,
               help="Pass the current time (the now argument of "
                    "<api>_periodic_tx) to the TX callback as a uint64_t, after "
                    "the message pointer and before the context pointer. Only "
                    "meaningful together with -p.")
-@click.option("--tx-function", is_flag=True, default=False,
+@click.option("--tx-function/--no-tx-function", default=False,
               help="Bind a frame sink to the periodic-TX API instead of "
                    "returning one frame per call. <api>_periodic_tx_init takes "
                    "a uint16_t (*tx_function)(void *, const <frame> *) and its "
@@ -125,18 +171,18 @@ def main():
                    "due message to it in a single pass and returns the number "
                    "accepted. A 0 return leaves last_tx and send_now untouched, "
                    "so the message is retried. Only meaningful with -p.")
-@click.option("--prefix-signal-struct-names", is_flag=True, default=False,
+@click.option("--prefix-signal-struct-names/--no-prefix-signal-struct-names", default=False,
               help="Prefix every per-message signal struct type name with the "
                    "CamelCase API prefix (the same prefix used for "
                    "<Prefix>RxSignals / <Prefix>TxSignals), so two similar APIs "
                    "(e.g. two versions of a database) can coexist in one "
                    "translation unit with distinct struct names.")
-@click.option("--prefix-context-struct-names", is_flag=True, default=False,
+@click.option("--prefix-context-struct-names/--no-prefix-context-struct-names", default=False,
               help="Prefix the MsgRxContext / MsgTxContext struct type names (and "
                    "their include-guard tokens) with the CamelCase API prefix, so "
                    "context structs from two coexisting APIs do not share one "
                    "definition.")
-@click.option("-v", "--verbose", is_flag=True, default=False,
+@click.option("-v", "--verbose/--no-verbose", default=False,
               help="Print the Data that is passed to the template that "
               "generates the code")
 def api(db_file, library_name, node_name, force, encode_all_signals_func,
@@ -228,10 +274,11 @@ def api(db_file, library_name, node_name, force, encode_all_signals_func,
 
 
 @main.command()
+@config_option
 @click.argument("DB_File", type=click.Path(exists=True, dir_okay=False),
                 required=True, nargs=1)
 @click.argument("Output_Base", type=str, required=True)
-@click.option("-f", "--force", is_flag=True, required=False, default=False,
+@click.option("-f", "--force/--no-force", required=False, default=False,
               help="Overwrite existing output files")
 def cbdb(db_file, output_base, force):
     """
@@ -267,8 +314,9 @@ def cbdb(db_file, output_base, force):
 
 
 @main.command()
+@config_option
 @click.argument("Library_Name", type=str, required=True)
-@click.option("-f", "--force", is_flag=True, required=False, default=False,
+@click.option("-f", "--force/--no-force", required=False, default=False,
               help="Overwrite existing output files")
 @click.option("-im", "--id-member-name", type=str, default="arbitration_id",
               help="The name of the CanFrame struct member that holds the "

{can_api_generator-2.3.0 → can_api_generator-2.5.0}/src/can_api_generator/templates/rx_macros.jinja

@@ -68,7 +68,7 @@ struct {{ api_struct_prefix }}RxSignals {{ var_name }};
 {% endmacro %}
 
 {% macro generate_global_rx_frame_process_function(messages, api_name, api_struct_prefix, can_frame_type, return_type, time_type, rx_callback, double_buffered=False, rx_callback_context=false, msg_as_rx_callback_arg=false, rx_signal_store=false, with_rx_valid=false, ctx_name='MsgRxContext', time_as_rx_callback_arg=false) -%}
-{%- set time_arg = 'now' if time_as_rx_callback_arg else '' %}
+{%- set time_arg = 'now' if time_as_rx_callback_arg else '' -%}
 {{ declare_global_rx_frame_process_function(api_name, api_struct_prefix, can_frame_type, return_type, time_type) }} {
 {%- for message in messages %}
 {%- if message.direction == 'rx' or message.direction == 'rt' %}

can_api_generator-2.5.0/tests/test_config_file.py

@@ -0,0 +1,68 @@
+"""--config: YAML defaults per command, overridden by the command line."""
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from src.can_api_generator.main import main
+
+CONFIG = """\
+api:
+  periodic-tx: true
+  tx_signal_store: true
+  time-as-tx-callback-arg: true
+  id-member-name: can_id
+"""
+
+
+def _run(tmp_path, monkeypatch, config, *args):
+    kcd = str(Path("tests/test_1.kcd").resolve())
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "cfg.yaml").write_text(config)
+    return CliRunner().invoke(
+        main, ["api", "--config", "cfg.yaml", kcd, "cf", "DUT", "-f", *args])
+
+
+def test_config_provides_options(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, CONFIG)
+    assert result.exit_code == 0, result.output
+    header = (tmp_path / "cf.h").read_text()
+    source = (tmp_path / "cf.c").read_text()
+    assert "struct Message2 message_2_signals;" in header
+    assert "void *(*tx_callback)(uint64_t);" in header
+    assert "output_frame->can_id = 0x1;" in source
+
+
+def test_command_line_overrides_config(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, CONFIG,
+                  "--no-tx-signal-store", "-im", "arb")
+    assert result.exit_code == 0, result.output
+    header = (tmp_path / "cf.h").read_text()
+    source = (tmp_path / "cf.c").read_text()
+    assert "message_2_signals" not in header
+    assert "output_frame->arb = 0x1;" in source
+    # untouched config values still apply
+    assert "(uint64_t)" in header
+
+
+def test_config_section_of_other_command_ignored(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "dyndec:\n  force: true\n", "-p")
+    assert result.exit_code == 0, result.output
+    assert "arbitration_id" in (tmp_path / "cf.c").read_text()
+
+
+def test_config_unknown_option_rejected(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "api:\n  bogus-flag: true\n")
+    assert result.exit_code == 2
+    assert "unknown option 'bogus-flag'" in result.output
+
+
+def test_config_invalid_value_rejected(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "api:\n  periodic-tx: maybe\n")
+    assert result.exit_code == 2
+    assert "periodic-tx" in result.output
+
+
+def test_config_not_a_mapping_rejected(tmp_path, monkeypatch):
+    result = _run(tmp_path, monkeypatch, "- 1\n")
+    assert result.exit_code == 2
+    assert "must map command names" in result.output

can_api_generator-2.5.0/tests/test_time_callback_arg.py

@@ -0,0 +1,107 @@
+"""Runtime checks for --time-as-rx-callback-arg / --time-as-tx-callback-arg.
+
+Generates the test_1.kcd API with the flag, links it against a C harness and
+asserts that the callback receives the now passed to the API entry point, in
+the documented argument order (message, now, context).
+"""
+import subprocess
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from src.can_api_generator.main import main
+
+RX_HARNESS = r"""
+#include <assert.h>
+#include <stdio.h>
+#include "tc.h"
+
+static uint64_t seen_now;
+static int ctx_token;
+
+static void rx_cb(void *msg, uint64_t now, void *ctx) {
+    assert(msg != 0);
+    assert(ctx == &ctx_token);
+    seen_now = now;
+}
+
+int main(void) {
+    struct TcRxSignals rx = {0};
+    CanFrame frame = {.length = 4, .arbitration_id = 0x1, .payload = 0};
+    rx.message_2_context.rx_callback = rx_cb;
+    rx.message_2_context.rx_callback_context = &ctx_token;
+    assert(tc_process_received_frame(&rx, &frame, 12345) == 1);
+    assert(seen_now == 12345);
+    puts("ok");
+    return 0;
+}
+"""
+
+TX_HARNESS = r"""
+#include <assert.h>
+#include <stdio.h>
+#include "tc.h"
+
+static struct Message2 m2;
+static uint64_t seen_now;
+static int ctx_token;
+
+static void *tx_cb(void *msg, uint64_t now, void *ctx) {
+    assert(msg != 0);
+    assert(ctx == &ctx_token);
+    seen_now = now;
+    return &m2;
+}
+
+int main(void) {
+    struct TcTxSignals tx;
+    CanFrame frame;
+    tc_periodic_tx_init(&tx, 0);
+    tx.message_2_context.tx_callback = tx_cb;
+    tx.message_2_context.tx_callback_context = &ctx_token;
+    tx.message_2_context.send_now = 1;
+    assert(tc_periodic_tx(&tx, &frame, 777) == 1);
+    assert(seen_now == 777);
+    puts("ok");
+    return 0;
+}
+"""
+
+
+@pytest.mark.parametrize("path", ["rx", "tx"])
+def test_callback_receives_now(tmp_path, monkeypatch, path):
+    kcd = str(Path("tests/test_1.kcd").resolve())
+    monkeypatch.chdir(tmp_path)
+    if path == "rx":
+        flags = ["-r", "--time-as-rx-callback-arg", "--rx-callback-context"]
+        harness = RX_HARNESS
+        node = "other"
+    else:
+        flags = ["-p", "--time-as-tx-callback-arg", "--tx-callback-context",
+                 "--msg-as-tx-callback-arg", "--send-now"]
+        harness = TX_HARNESS
+        node = "DUT"
+    result = CliRunner().invoke(main, ["api", kcd, "tc", node, *flags])
+    assert result.exit_code == 0, result.output
+    (tmp_path / "harness.c").write_text(harness)
+    build = subprocess.run(
+        ["gcc", "-Wall", "-Werror", "-o", "harness", "harness.c", "tc.c"],
+        capture_output=True, text=True)
+    assert build.returncode == 0, build.stderr
+    run = subprocess.run(["./harness"], capture_output=True, text=True)
+    assert run.returncode == 0, run.stdout + run.stderr
+    assert run.stdout.strip() == "ok"
+
+
+@pytest.mark.parametrize("flag,cb", [
+    ("-r", "void (*rx_callback)(void *);"),
+    ("-p", "void *(*tx_callback)(void);"),
+])
+def test_time_arg_absent_by_default(tmp_path, monkeypatch, flag, cb):
+    kcd = str(Path("tests/test_1.kcd").resolve())
+    monkeypatch.chdir(tmp_path)
+    node = "other" if flag == "-r" else "DUT"
+    result = CliRunner().invoke(main, ["api", kcd, "tc", node, flag])
+    assert result.exit_code == 0, result.output
+    assert cb in (tmp_path / "tc.h").read_text()