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

can_api_generator-2.3.0/Advantics_Bootloader.kcd

@@ -0,0 +1,384 @@
+<?xml version="1.0" ?>
+<NetworkDefinition xmlns="http://kayak.2codeornot2code.org/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="KCD_Definition.xsd">
+  <Document name="Advantics_Bootloader" version="1" author="[...]" company="Advantics" date="2019-11-19"/>
+  <Node id="0" name="User"/>
+  <Node id="5" name="Bootloader"/>
+  <Bus name="Bootloader" baudrate="500000">
+    <Message id="0x8000" length="8" name="Bootloader_Identification" interval="1000" format="extended">
+      <Notes>Identification of the device</Notes>
+      <Producer> <NodeRef id="5"/> </Producer>
+      <Signal name="Device_type" offset="0" length="8">
+        <Notes> The device identification field, uniquely identifies the sender in the network </Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="HW_revision" offset="8" length="8">
+        <Notes>The hardware revision number</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="HW_variant" offset="16" length="8">
+        <Notes>The DSP firmware revision number</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="Stack_position" offset="24" length="8">
+        <Notes>Position of the module within the stack</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="SN_number" offset="32" length="32">
+        <Notes>Unique module serial number</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+    </Message>
+
+    <Message id="0x8001" length="8" name="Bootloader_Fwinfo" interval="1000" format="extended">
+      <Notes>Git revision of the DSP firmware</Notes>
+      <Producer> <NodeRef id="5"/> </Producer>
+      <Multiplex name="FW_info_mux" offset="56" length="8">
+        <MuxGroup count="0">
+          <Signal name="FW_revision_0" offset="0" length="8">
+            <Notes>Character 0</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_1" offset="8" length="8">
+            <Notes>Character 1</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_2" offset="16" length="8">
+            <Notes>Character 2</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_3" offset="24" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_4" offset="32" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_5" offset="40" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_6" offset="48" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="1">
+          <Signal name="FW_revision_7" offset="0" length="8">
+            <Notes>Character 7</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_8" offset="8" length="8">
+            <Notes>Character 8</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_9" offset="16" length="8">
+            <Notes>Character 9</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_10" offset="24" length="8">
+            <Notes>Character 10</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_11" offset="32" length="8">
+            <Notes>Character 11</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_12" offset="40" length="8">
+            <Notes>Character 12</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_revision_13" offset="48" length="8">
+            <Notes>Character 13</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="2">
+          <Signal name="FW_datecode_0" offset="0" length="8">
+            <Notes>Character 0</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_1" offset="8" length="8">
+            <Notes>Character 1</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_2" offset="16" length="8">
+            <Notes>Character 2</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_3" offset="24" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_4" offset="32" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_5" offset="40" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_6" offset="48" length="8">
+            <Notes>Character 3</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="3">
+          <Signal name="FW_datecode_7" offset="0" length="8">
+            <Notes>Character 7</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_8" offset="8" length="8">
+            <Notes>Character 8</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_9" offset="16" length="8">
+            <Notes>Character 9</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_10" offset="24" length="8">
+            <Notes>Character 10</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_11" offset="32" length="8">
+            <Notes>Character 11</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_12" offset="40" length="8">
+            <Notes>Character 12</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+          <Signal name="FW_datecode_13" offset="48" length="8">
+            <Notes>Character 13</Notes>
+            <Consumer> <NodeRef id="0"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+      </Multiplex>
+    </Message>
+
+    <Message id="0x8002" length="8" name="Bootloader_Debug" interval="1000" format="extended">
+      <Notes>Values for debugging of HW/SW problems</Notes>
+      <Producer> <NodeRef id="5"/> </Producer>
+      <Signal name="Status_Error_Code" offset="0" length="16">
+        <Notes>Main status / error code as defined in errno/errno.h</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="Data_1" offset="16" length="16">
+        <Notes>Additional information for the error/status</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="Data_2" offset="32" length="16">
+        <Notes>Additional information for the error/status</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="Data_3" offset="48" length="16">
+        <Notes>Additional information for the error/status</Notes>
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+    </Message>
+
+    <Message id="0x80A5" length="5" name="Bootloader_Info" interval="5" format="extended">
+      <Producer> <NodeRef id="5"/> </Producer>
+      <Signal name="Status" offset="0" length="8">
+        <Consumer> <NodeRef id="0"/> </Consumer>
+        <LabelSet>
+            <Label name="Bootloader_Idle" value="0"/>
+            <Label name="Bootloader_Prog" value="1"/>
+            <Label name="Bootloader_Get_Len" value="2"/>
+            <Label name="Bootloader_Flash" value="3"/>
+            <Label name="Bootloader_Erase" value="4"/>
+            <Label name="Bootloader_Flash_Error" value="5"/>
+            <Label name="Bootloader_Erase_Error" value="6"/>
+            <Label name="Bootloader_Download" value="7"/>
+            <Label name="Bootloader_Download_Start" value="8"/>
+            <Label name="Bootloader_Flash_End" value="9"/>
+            <Label name="Bootloader_Prog_Erased" value="10"/>
+            <Label name="Bootloader_Write_Module" value="11"/>
+            <Label name="Bootloader_Module_Written" value="12"/>
+            <Label name="Bootloader_Module_Write_Error" value="13"/>
+            <Label name="Bootloader_Make_Virgin_Done" value="14"/>
+            <Label name="Bootloader_Make_Virgin_Error" value="15"/>
+        </LabelSet>
+      </Signal>
+      <Signal name="Error" offset="8" length="16">
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+      <Signal name="Seq_num" offset="24" length="16">
+        <Consumer> <NodeRef id="0"/> </Consumer>
+      </Signal>
+    </Message>
+
+    <Message id="0x00A5" length="8" name="Bootloader_Command" format="extended">
+      <Notes>Single message is used for all Bootloader commands</Notes>
+      <Producer> <NodeRef id="0"/> </Producer>
+      <Multiplex name="Bootloader_command_id" offset="0" length="8">
+        <MuxGroup count="85">
+          <Signal name="Flash_address" offset="8" length="32">
+            <Notes> Start address of sector to FLASH. </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="Flash_Request" offset="40" length="1">
+            <Notes>
+                This is not required by bootloader to execute,
+                put here to validate KCD.
+                (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="165">
+          <Signal name="Stop_Boot" offset="8" length="1">
+            <Notes>
+              This is not required by bootloader to execute,
+              put here to validate KCD.
+              (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="170">
+          <Signal name="Clear_Errors" offset="8" length="1">
+            <Notes>
+              This is not required by bootloader to execute,
+              put here to validate KCD.
+              (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="90">
+          <Signal name="Resume_Boot" offset="8" length="1">
+            <Notes>
+              This is not required by bootloader to execute,
+              put here to validate KCD.
+              (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="17">
+          <Signal name="Flash_sector" offset="8" length="32">
+            <Notes> Start address of sector to ERASE. </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="Erase_Sector" offset="40" length="1">
+            <Notes>
+              This is not required by bootloader to execute,
+              put here to validate KCD.
+              (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="18">
+          <Signal name="Flash_len" offset="8" length="32">
+              <Notes> Length of the data to flash. </Notes>
+              <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="Set_Flash_Length" offset="40" length="1">
+            <Notes>
+              This is not required by bootloader to execute,
+              put here to validate KCD.
+              (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="19">
+          <Signal name="Device_type" offset="8" length="8">
+            <Notes>The hardware id</Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="HW_variant" offset="16" length="8">
+            <Notes>The hardware variant number</Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="HW_revision" offset="24" length="8">
+            <Notes>The hardware revision number</Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="Stack_position" offset="32" length="8">
+            <Notes>Position of the module within the stack</Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="Stack_size" offset="40" length="16">
+            <Notes>Stack module count</Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="Init_Module" offset="56" length="1">
+            <Notes>
+              This is not required by bootloader to execute,
+              put here to validate KCD.
+              (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="20">
+          <Signal name="Make_Virgin" offset="8" length="1">
+            <Notes>
+                This is not required by bootloader to execute,
+                put here to validate KCD.
+                (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <MuxGroup count="21">
+          <Signal name="Serial_Number" offset="8" length="32">
+            <Notes>
+              This is the serial number to be programmed into the EEPROM. This
+              will only work in those units whose EEPROM does not come with a 
+              preprogrammed serial number.
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+          <Signal name="Program_SN" offset="40" length="1">
+            <Notes>
+              This is not required by bootloader to execute,
+              put here to validate KCD.
+              (I.e. value is _DON'T CARE_)
+            </Notes>
+            <Consumer> <NodeRef id="5"/> </Consumer>
+          </Signal>
+        </MuxGroup>
+        <LabelSet>
+          <Label name="Flash_Request" value="85"/>
+          <Label name="Stop_Boot" value="165"/>
+          <Label name="Clear_Errors" value="170"/>
+          <Label name="Resume_Boot" value="90"/>
+          <Label name="Flash_Erase" value="17"/>
+          <Label name="Flash_Length" value="18"/>
+          <Label name="Init_Module" value="19"/>
+          <Label name="Make_Virgin" value="20"/>
+          <Label name="Program_SN" value="21"/>
+        </LabelSet>
+      </Multiplex>
+    </Message>
+
+    <Message id="0x00A6" length="8" name="Bootloader_Download" format="extended">
+      <Producer> <NodeRef id="0"/> </Producer>
+      <Signal name="Seq_num" length="16" offset="48">
+        <Consumer> <NodeRef id="5"/> </Consumer>
+      </Signal>
+      <Signal name="Data_0" length="16" offset="0">
+        <Consumer> <NodeRef id="5"/> </Consumer>
+      </Signal>
+      <Signal name="Data_1" length="16" offset="16">
+        <Consumer> <NodeRef id="5"/> </Consumer>
+      </Signal>
+      <Signal name="Data_2" length="16" offset="32">
+        <Consumer> <NodeRef id="5"/> </Consumer>
+      </Signal>
+    </Message>
+
+    <Message id="0x0050" length="1" name="Bootloader_Fault_Control" format="extended">
+      <Notes>Fault Control: actions to clear faults and reset the system</Notes>
+      <Producer> <NodeRef id="0"/> </Producer>
+      <Signal name="Reset_Processor" offset="1" length="1" endianess="little">
+        <Notes>Reset the filter DSP</Notes>
+        <Consumer> <NodeRef id="5"/> </Consumer>
+      </Signal>
+    </Message>
+  </Bus>
+</NetworkDefinition>

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: can-api-generator
-Version: 2.1.0
+Version: 2.3.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)
+  - [Using your own frame type](#using-your-own-frame-type)
 - [Example Use](#example-use)
 - [Dynamic decoding](#dynamic-decoding)
   - [Preparing a database (`cbdb`)](#preparing-a-database-cbdb)
@@ -200,9 +201,10 @@ struct MsgTxContext {
   critical signal has just changed and you want it on the bus on the very next tick instead of waiting out the remainder of the period.
 
 By default (with `-p` alone) periodic TX is **callback-only**: `TxSignals` holds only a `MsgTxContext` per message (no `_signals` storage), and each scheduled message's
-`tx_callback` produces the frame. When a message's schedule fires, `<api>_periodic_tx` clears `send_now` and updates `last_tx` (so the slot is consumed and does not
-busy-retry), then calls the callback only if it is registered; it encodes and reports the frame only if the callback returns a non-`NULL` struct pointer. A missing
-callback or a `NULL` return sends nothing for that message and falls through, so another scheduled message whose callback returns data can still be sent on the same call.
+`tx_callback` produces the frame. When a message's schedule fires, `<api>_periodic_tx` clears `send_now`, then calls the callback only if it is registered; it
+encodes and reports the frame, and updates `last_tx`, only if the callback returns a non-`NULL` struct pointer. A missing callback or a `NULL` return sends nothing for
+that message and leaves `last_tx` untouched, so the message is offered again at its next slot; the call falls through, so another scheduled message whose callback
+returns data can still be sent on the same call.
 Multiplex variant scheduling is the application's responsibility in this mode (the callback returns whichever variant it wants to send).
 
 In plain callback-only mode (no `--msg-as-tx-callback-arg`) the callback returns a pointer to the signal struct to be encoded, so **the application must provide the
@@ -219,6 +221,26 @@ value ignored), the generator handles multiplex rotation, and (with `--double-bu
 `--msg-as-tx-callback-arg` passes a `void *` to that message's store struct as the callback's first argument (context second, if `--tx-callback-context`), so the callback
 need not look the struct up before editing it in place.
 
+#### Queueing frames through a bound TX function
+By default `<api>_periodic_tx` returns at most one frame per call, so it has to be called often enough to drain every due message. Passing `--tx-function` binds a frame
+sink to the API instead, so a single call hands every due message to it:
+```c
+struct <Prefix>TxSignals {
+    ...
+    uint16_t (*tx_function)(void *tx_function_context, const CanFrame *frame);
+    void *tx_function_context;
+};
+void <api>_periodic_tx_init(struct <Prefix>TxSignals *tx_signals, uint64_t now,
+                            uint16_t (*tx_function)(void *, const CanFrame *), void *tx_function_context);
+uint16_t <api>_periodic_tx(struct <Prefix>TxSignals *tx_signals, uint64_t now); // returns the number of frames accepted
+```
+`<api>_periodic_tx` encodes each due message into a frame on its stack and calls `tx_function(tx_function_context, &frame)`, in the caller's context. The frame is only
+valid during that call, so the function copies it (typically into a TX queue or mailbox). It returns nonzero if it accepted the frame; only then are `send_now` cleared,
+`last_tx` updated and (with `--tx-signal-store`) the multiplex variant rotated. On a 0 return (queue full) nothing changes: a pending `send_now` is retried on the next call, a periodic message waits for its next
+slot (`now % period == offset`); the missed slot is skipped, not caught up.
+The `tx_callback` rules are unchanged: in callback-only mode a `NULL` return queues nothing, and `send_now` stays set as well. Works with and without
+`--tx-signal-store`.
+
 ### Encode All Signals
 Some messages use multiplexes combining many signals in to a single message. This may be particularly true for configuration messages that have many related parameters and use
 multiplexes to fit all parameters in to a single message using many mux groups. If the entire config should be read out and the read back happens periodically, the supervisory controller
@@ -331,6 +353,45 @@ 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.
 
+### 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
+frame struct (for example the one its CAN driver fills), the API can use that type directly instead, so no copy between two frame structs is needed:
+
+* `-ct`, `--canframe-type` sets the type name used in every generated signature. Include the `struct` keyword if the type is not a typedef, e.g.
+  `-ct "struct DriverFrame"`.
+* `-ch`, `--canframe-header` sets the header the generated `.h` includes to get that type, e.g. `-ch driver_frame.h`.
+* `-im` / `-lm` / `-pm` rename the members the API reads and writes, so they match your struct (see the [command-line reference](#api)).
+
+If either `-ct` or `-ch` is given, **`canframe.h` is not generated**. Giving either option means the application provides the frame definition, and writing our
+`canframe.h` would at best go unused and at worst overwrite the application's own `canframe.h`. This holds even if the value passed equals the default (e.g.
+`-ch canframe.h`), so supply your own header whenever you pass either flag.
+
+Your type must provide three members, accessed as plain scalars:
+
+| Member (default name) | Use | Requirement |
+|---|---|---|
+| `arbitration_id` (`-im`) | compared against / set to the message id | integer wide enough for the id (`uint32_t` for extended ids) |
+| `length` (`-lm`) | compared against / set to the message DLC | integer |
+| `payload` (`-pm`) | the whole 8-byte payload in one access | a single `uint64_t`, **not** a byte array |
+
+The payload requirement rules out structs such as Linux's `struct can_frame`, whose data is a `__u8 data[8]` array. Wrap such frames in a struct with a `uint64_t`
+payload (or a union with one) instead.
+
+```bash
+can-api-gen api bus.kcd my_api DUT -r -p -ct DriverFrame -ch driver_frame.h -im id -lm dlc -pm data
+```
+
+```c
+/* driver_frame.h — supplied by the application */
+#include <stdint.h>
+typedef struct DriverFrame {
+    uint32_t id;
+    uint8_t  dlc;
+    uint64_t data;
+} DriverFrame;
+```
+
 ## Example Use
 
 As an example the following KCD definition of all messages on a CAN bus is converted:
@@ -547,7 +608,8 @@ Generate the static, per-node C API (see [Example Use](#example-use)).
 
 Positional arguments:
 * `DB_FILE` — path to the bus description, either a KCD (XML) or a `can-db-model` YAML file.
-* `LIBRARY_NAME` — stem of the generated library. The output files are `<LIBRARY_NAME>.c`, `<LIBRARY_NAME>.h`, and a sibling `canframe.h`. The stem is also used as
+* `LIBRARY_NAME` — stem of the generated library. The output files are `<LIBRARY_NAME>.c`, `<LIBRARY_NAME>.h`, and a sibling `canframe.h` (omitted when `-ct` or
+  `-ch` is given). The stem is also used as
   the prefix for every generated function so multiple APIs can coexist in the same project.
 * `NODE_NAME` — name of the node the API is being generated for. Only messages that this node produces or consumes are emitted, so the binary size stays small for
   embedded targets.
@@ -581,6 +643,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`.
+* `--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
+  together with `-p`.
 * `--rx-signal-store` — generate the permanent per-message RX signal store (the pre-2.0 default). Without it, global RX is callback-only: no store is
   generated and decoded signals reach the application only through the RX callback. See [Global RX](#global-rx). Only meaningful together with `-r`.
 * `--with-rx-valid` — in callback-only mode, add a `valid` field to `MsgRxContext` and set it on each matched frame, for struct-layout compatibility with
@@ -589,6 +655,10 @@ Options:
   `<Prefix>TxSignals`). Lets two similar APIs (e.g. two versions of one database) coexist in a single translation unit with distinct struct names. Off by default.
 * `--prefix-context-struct-names` — prefix the `MsgRxContext` / `MsgTxContext` type names and their include-guard tokens with the CamelCase API prefix, so the
   context structs of two coexisting APIs do not share a single definition. Off by default.
+* `-ct`, `--canframe-type TEXT` — the frame type used in every generated signature (default `CanFrame`). Include `struct` if it is not a typedef. Giving this
+  or `-ch` suppresses `canframe.h`. See [Using your own frame type](#using-your-own-frame-type).
+* `-ch`, `--canframe-header TEXT` — the header the generated `.h` includes for the frame type (default `canframe.h`). Giving this or `-ct` suppresses
+  `canframe.h`. See [Using your own frame type](#using-your-own-frame-type).
 * `-im`, `--id-member-name TEXT` — override the name of the `CanFrame` member that carries the arbitration id (default `arbitration_id`). Used to adapt the API
   to an existing project's frame struct naming.
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).

{can_api_generator-2.1.0 → can_api_generator-2.3.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)
+  - [Using your own frame type](#using-your-own-frame-type)
 - [Example Use](#example-use)
 - [Dynamic decoding](#dynamic-decoding)
   - [Preparing a database (`cbdb`)](#preparing-a-database-cbdb)
@@ -175,9 +176,10 @@ struct MsgTxContext {
   critical signal has just changed and you want it on the bus on the very next tick instead of waiting out the remainder of the period.
 
 By default (with `-p` alone) periodic TX is **callback-only**: `TxSignals` holds only a `MsgTxContext` per message (no `_signals` storage), and each scheduled message's
-`tx_callback` produces the frame. When a message's schedule fires, `<api>_periodic_tx` clears `send_now` and updates `last_tx` (so the slot is consumed and does not
-busy-retry), then calls the callback only if it is registered; it encodes and reports the frame only if the callback returns a non-`NULL` struct pointer. A missing
-callback or a `NULL` return sends nothing for that message and falls through, so another scheduled message whose callback returns data can still be sent on the same call.
+`tx_callback` produces the frame. When a message's schedule fires, `<api>_periodic_tx` clears `send_now`, then calls the callback only if it is registered; it
+encodes and reports the frame, and updates `last_tx`, only if the callback returns a non-`NULL` struct pointer. A missing callback or a `NULL` return sends nothing for
+that message and leaves `last_tx` untouched, so the message is offered again at its next slot; the call falls through, so another scheduled message whose callback
+returns data can still be sent on the same call.
 Multiplex variant scheduling is the application's responsibility in this mode (the callback returns whichever variant it wants to send).
 
 In plain callback-only mode (no `--msg-as-tx-callback-arg`) the callback returns a pointer to the signal struct to be encoded, so **the application must provide the
@@ -194,6 +196,26 @@ value ignored), the generator handles multiplex rotation, and (with `--double-bu
 `--msg-as-tx-callback-arg` passes a `void *` to that message's store struct as the callback's first argument (context second, if `--tx-callback-context`), so the callback
 need not look the struct up before editing it in place.
 
+#### Queueing frames through a bound TX function
+By default `<api>_periodic_tx` returns at most one frame per call, so it has to be called often enough to drain every due message. Passing `--tx-function` binds a frame
+sink to the API instead, so a single call hands every due message to it:
+```c
+struct <Prefix>TxSignals {
+    ...
+    uint16_t (*tx_function)(void *tx_function_context, const CanFrame *frame);
+    void *tx_function_context;
+};
+void <api>_periodic_tx_init(struct <Prefix>TxSignals *tx_signals, uint64_t now,
+                            uint16_t (*tx_function)(void *, const CanFrame *), void *tx_function_context);
+uint16_t <api>_periodic_tx(struct <Prefix>TxSignals *tx_signals, uint64_t now); // returns the number of frames accepted
+```
+`<api>_periodic_tx` encodes each due message into a frame on its stack and calls `tx_function(tx_function_context, &frame)`, in the caller's context. The frame is only
+valid during that call, so the function copies it (typically into a TX queue or mailbox). It returns nonzero if it accepted the frame; only then are `send_now` cleared,
+`last_tx` updated and (with `--tx-signal-store`) the multiplex variant rotated. On a 0 return (queue full) nothing changes: a pending `send_now` is retried on the next call, a periodic message waits for its next
+slot (`now % period == offset`); the missed slot is skipped, not caught up.
+The `tx_callback` rules are unchanged: in callback-only mode a `NULL` return queues nothing, and `send_now` stays set as well. Works with and without
+`--tx-signal-store`.
+
 ### Encode All Signals
 Some messages use multiplexes combining many signals in to a single message. This may be particularly true for configuration messages that have many related parameters and use
 multiplexes to fit all parameters in to a single message using many mux groups. If the entire config should be read out and the read back happens periodically, the supervisory controller
@@ -306,6 +328,45 @@ 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.
 
+### 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
+frame struct (for example the one its CAN driver fills), the API can use that type directly instead, so no copy between two frame structs is needed:
+
+* `-ct`, `--canframe-type` sets the type name used in every generated signature. Include the `struct` keyword if the type is not a typedef, e.g.
+  `-ct "struct DriverFrame"`.
+* `-ch`, `--canframe-header` sets the header the generated `.h` includes to get that type, e.g. `-ch driver_frame.h`.
+* `-im` / `-lm` / `-pm` rename the members the API reads and writes, so they match your struct (see the [command-line reference](#api)).
+
+If either `-ct` or `-ch` is given, **`canframe.h` is not generated**. Giving either option means the application provides the frame definition, and writing our
+`canframe.h` would at best go unused and at worst overwrite the application's own `canframe.h`. This holds even if the value passed equals the default (e.g.
+`-ch canframe.h`), so supply your own header whenever you pass either flag.
+
+Your type must provide three members, accessed as plain scalars:
+
+| Member (default name) | Use | Requirement |
+|---|---|---|
+| `arbitration_id` (`-im`) | compared against / set to the message id | integer wide enough for the id (`uint32_t` for extended ids) |
+| `length` (`-lm`) | compared against / set to the message DLC | integer |
+| `payload` (`-pm`) | the whole 8-byte payload in one access | a single `uint64_t`, **not** a byte array |
+
+The payload requirement rules out structs such as Linux's `struct can_frame`, whose data is a `__u8 data[8]` array. Wrap such frames in a struct with a `uint64_t`
+payload (or a union with one) instead.
+
+```bash
+can-api-gen api bus.kcd my_api DUT -r -p -ct DriverFrame -ch driver_frame.h -im id -lm dlc -pm data
+```
+
+```c
+/* driver_frame.h — supplied by the application */
+#include <stdint.h>
+typedef struct DriverFrame {
+    uint32_t id;
+    uint8_t  dlc;
+    uint64_t data;
+} DriverFrame;
+```
+
 ## Example Use
 
 As an example the following KCD definition of all messages on a CAN bus is converted:
@@ -522,7 +583,8 @@ Generate the static, per-node C API (see [Example Use](#example-use)).
 
 Positional arguments:
 * `DB_FILE` — path to the bus description, either a KCD (XML) or a `can-db-model` YAML file.
-* `LIBRARY_NAME` — stem of the generated library. The output files are `<LIBRARY_NAME>.c`, `<LIBRARY_NAME>.h`, and a sibling `canframe.h`. The stem is also used as
+* `LIBRARY_NAME` — stem of the generated library. The output files are `<LIBRARY_NAME>.c`, `<LIBRARY_NAME>.h`, and a sibling `canframe.h` (omitted when `-ct` or
+  `-ch` is given). The stem is also used as
   the prefix for every generated function so multiple APIs can coexist in the same project.
 * `NODE_NAME` — name of the node the API is being generated for. Only messages that this node produces or consumes are emitted, so the binary size stays small for
   embedded targets.
@@ -556,6 +618,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`.
+* `--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
+  together with `-p`.
 * `--rx-signal-store` — generate the permanent per-message RX signal store (the pre-2.0 default). Without it, global RX is callback-only: no store is
   generated and decoded signals reach the application only through the RX callback. See [Global RX](#global-rx). Only meaningful together with `-r`.
 * `--with-rx-valid` — in callback-only mode, add a `valid` field to `MsgRxContext` and set it on each matched frame, for struct-layout compatibility with
@@ -564,6 +630,10 @@ Options:
   `<Prefix>TxSignals`). Lets two similar APIs (e.g. two versions of one database) coexist in a single translation unit with distinct struct names. Off by default.
 * `--prefix-context-struct-names` — prefix the `MsgRxContext` / `MsgTxContext` type names and their include-guard tokens with the CamelCase API prefix, so the
   context structs of two coexisting APIs do not share a single definition. Off by default.
+* `-ct`, `--canframe-type TEXT` — the frame type used in every generated signature (default `CanFrame`). Include `struct` if it is not a typedef. Giving this
+  or `-ch` suppresses `canframe.h`. See [Using your own frame type](#using-your-own-frame-type).
+* `-ch`, `--canframe-header TEXT` — the header the generated `.h` includes for the frame type (default `canframe.h`). Giving this or `-ct` suppresses
+  `canframe.h`. See [Using your own frame type](#using-your-own-frame-type).
 * `-im`, `--id-member-name TEXT` — override the name of the `CanFrame` member that carries the arbitration id (default `arbitration_id`). Used to adapt the API
   to an existing project's frame struct naming.
 * `-lm`, `--length-member-name TEXT` — override the name of the `CanFrame` length member (default `length`).