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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: can-api-generator
-Version: 2.3.0
+Version: 2.4.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
@@ -45,6 +45,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)
@@ -353,6 +354,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
@@ -643,6 +655,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

{can_api_generator-2.3.0 → can_api_generator-2.4.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)
@@ -328,6 +329,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
@@ -618,6 +630,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

{can_api_generator-2.3.0 → can_api_generator-2.4.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.4.0"

{can_api_generator-2.3.0 → can_api_generator-2.4.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.4.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()