can-api-generator 0.0.10__tar.gz

can_api_generator-0.0.10/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+dist/

can_api_generator-0.0.10/LICENSE.txt

@@ -0,0 +1,166 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+

can_api_generator-0.0.10/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: can-api-generator
+Version: 0.0.10
+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
+Project-URL: Source, https://sr.ht/~laplace/can-api-generator
+Author-email: Alexande Krishna-Becker <nabla.becker@mailbox.org>
+License-Expression: LGPL-3.0-only
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Requires-Dist: cantools
+Requires-Dist: click
+Requires-Dist: jinja2
+Requires-Dist: rich
+Description-Content-Type: text/markdown
+
+# can-api-generator
+
+[![PyPI - Version](https://img.shields.io/pypi/v/can-api-generator.svg)](https://pypi.org/project/can-api-generator)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/can-api-generator.svg)](https://pypi.org/project/can-api-generator)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [License](#license)
+- [Overview](#overview)
+- [Features of the library](#features-of-the-library)
+- [Additional features](#additional-features)
+  - [Global RX](#global-rx)
+  - [Periodic TX](#periodic-tx)
+  - [Encode All Signals](#encode-all-signals)
+  - [TI C2000 compatibility](#ti-c2000-compatibility)
+  - [Double-buffered signal access](#double-buffered-signal-access)
+- [Example Use](#example-use)
+- [Command-line reference](#command-line-reference)
+
+## Installation
+
+```console
+pip install can-api-generator
+```
+
+## License
+
+`can-api-generator` is distributed under the terms of the [GPL-3.0-only](https://spdx.org/licenses/GPL-3.0-only.html) license.
+
+## Overview
+The `can-api-generator` is a program to generate a C implementation for a 'signal' style CAN API from a KCD file describing the signals and their arrangement
+in to messages sent over the can bus.
+A signal represents a value that is shared among all nodes of the bus. Due to the fact that CAN is based on packets, which are referred
+to as frames, multiple signals may to be grouped into a common message which is then transmitted as a can frame. Different messages are distinguished via the arbitration id
+that is part of the can frame.
+Thus the arbitration ID acts as a content address (think address of memory shared over the can bus), and not a source or destination address.
+
+A Frames are sent out by the node that modifies a value that is contained in the Frame.
+A KCD file may encompass multiple nodes that have messages sent between them. To minimize the code generated, a Node needs to be specified so that only the messages that
+are transmitted or received by this node. Flags allow generating the additional code if needed.
+
+The API is only concerned with frames that are defined by the KCD file from which the API was generated. Other frames may be transmitted over the bus and are
+outside the scope of this API. The code simply decodes what it can identify and only produces frames that are defined as 'tx' from the nodes
+
+### Practical uses
+In practice frames are often sent periodically, even if no change has occured, to provide redundancy and fault tolerance to the system.
+Even though any node in the network may send any frame, in practice only a single node on a bus will update certain signals, thus avoiding the problems that
+arise when multiple nodes modify the same signal.
+
+Can frames generated by this library are compatible to the DBC and KCD definitions and can thus be decoded by industry standard tools like busmaster/canoe/PeakCan etc.
+
+# Features of the library
+---
+* One struct per message: The struct contains the signals that are explicitly defined in the can frame (including multiplexes). This allows a single message struct
+  to fully define a frame (the ID and length are declared as defines). (see the example for explicit code)
+* Decodeing/Encoding functions: For each Message a decode and encode functions is generated that allow to translate the struct into a 'CanFrame' and decode a 'CanFrame' struct in to the
+  message struct that contains the values encoded as native data types. The encoding function also sets the length and the arbitration id of the can frame.
+
+## Additional features
+---
+
+This generator may generate additional code that was found useful in many common cases:
+* a **global rx** function (enabled with `-r`/`--global-rx`): takes a received can frame, matches it against the message definitions in the API, and decodes it into
+  a 'global' api struct containing the signals for every message this node consumes.
+* a **periodic tx** function (enabled with `-p`/`--periodic-tx`): schedules messages to be sent automatically. Auxiliary information is stored, similar to the
+  'global rx', in a TxContext struct. It allows for changing the period of the transmission on the fly and also allows a tx callback to be called upon
+  transmission of any particular message. Transmission may also be disabled per message.
+* an **encode-every-signal** helper per message (enabled with `-a`/`--encode-all-signals-func`): fills a caller-provided buffer with the minimum number of frames
+  needed to cover every signal in a multiplexed message at least once. See [Encode All Signals](#encode-all-signals).
+* an **immediate-send override** for the periodic tx path (enabled with `--send-now`): adds a per-message `send_now` flag that fires the next `periodic_tx` call
+  regardless of schedule or enable state. Useful for publishing critical signal changes without waiting out the rest of the period.
+* **TI C2000 compatible** codegen (enabled with `--ti-compatible`): hoists local variable declarations to the top of encode/decode functions so the generated C
+  compiles under the TI C2000 compiler's strict C90 rules. See [TI C2000 compatibility](#ti-c2000-compatibility).
+* **double-buffered signal access** (enabled with `--double-buffered`): emits two storage slots and front/back pointers per message so that an ISR-side decode
+  never exposes a partially-written struct to readers, and a periodic tx encoder never reads a struct that user code is mid-update. See
+  [Double-buffered signal access](#double-buffered-signal-access).
+
+### Global RX
+Global RX generates the code needed to take any received can frame and decode it in to the API if the message matches a definition in the API. This allows the application to
+call a single function once per received frame and have access to all signals shared via the CAN bus system by simply reading the signals in the RX struct.
+
+The global rx funciton needs to be called with the 'current time'. which for MCUs is most often represented by a count of the milliseconds passed since power up.
+
+The global RX struct also contains one `MsgRxContext` struct per message. This allows to configure parameters and read back metadata about the message.
+The `MsgRxContext` has the following form:
+```c
+struct MsgRxContext {
+    uint16_t ignore;
+    uint16_t valid;
+    uint64_t last_rx;
+    void (*rx_callback)(void);
+};
+```
+* When the `ignore` value is set to 1, the received message is not decoded even if it's arbitration id and length matched with the message definition.
+* The `valid` field is set to 1 every time the corresponging message is received. This value may be written to 0 by the application and allows the application
+  to simply check if the information in the message has been written to. This is useful when a critical section is to be entered that requires other programs
+  to have set configuration parameters that need to be valid before the critical section is entered.
+* `last_rx` field stores the value of the 'clock' the last time this message was received. this may be used for diagnostics and statistics
+
+### Periodic TX
+The periodic TX is the counterpart to the 'global RX'. It takes care to schedule the transmission of periodic frames at the proper time. Periodic frames are pretty
+common on CAN bus systems and provide robust communication of critical data without the need for explicit synchronization mechanisms. Many controllers, often found in
+automotive applications send the same message periodically. This allows for 'quasi-analog' values to be transmitted via the CAN bus. When enabling the `-p`/`--periodic-tx` flag
+the can api generator generates a `<api>_periodic_tx` function that properly schedules periodic messages, an `<api>_periodic_tx_init` function that seeds the per-message
+contexts from the `cycle_time` values in the KCD, and an `<api>_get_msg_tx_context_by_id` helper for looking up a message context by arbitration id. To configure the
+periodic transmission the `TxSignals` struct, that is generated along with the periodic tx function, provisions one `MsgTxContext` struct for each message. The
+`MsgTxContext` is defined as following:
+```c
+struct MsgTxContext {
+    uint32_t arb_id;
+    uint16_t enable;
+    uint64_t last_tx;
+    uint32_t period;
+    uint32_t offset;
+    uint32_t offset_seed;
+    void (*tx_callback)(void);
+    uint16_t send_now;         // only present when compiled with --send-now
+};
+```
+* `arb_id` is the arbitration id of the message the context controls. It is seeded by `<api>_periodic_tx_init` so the application can look up a context by id via
+  `<api>_get_msg_tx_context_by_id`.
+* `enable` needs to be set to 1 for the message to be sent periodically. This allows the application to reduce bus load by silencing messages depending on the situation.
+  Init sets this to 1 for messages that declare a `cycle_time` in the KCD and 0 for the rest.
+* `last_tx` is updated by the periodic tx function every time a frame fires. Combined with `period`, it gates retransmission so a frame cannot fire more often than once
+  per period.
+* `period` configures the time between two messages (in MCU clock units). Most MCUs use a 1ms tick so this value often ends up being the number of milliseconds between
+  two periodic transmissions. The application may change this at runtime via `<api>_update_tx_period(ctx, new_period)`, which also recomputes `offset` so the phase stays
+  consistent.
+* `offset` is a value that adds an offset to the transmission time. Multiple messages will often have the same period (say 100ms). Without the offset the CAN bus becomes
+  quite 'bursty' as every 100ms many messages are encoded at once and require transmission. This may lead to dropped messages and bus load problems even at low average
+  load. This offset spreads out the transmission of messages through the entire transmission period, reducing pileup of messages.
+* `offset_seed` is a per-message constant seeded at generation time so that different messages with the same period end up at different phases inside that period without
+  the application having to pick offsets by hand.
+* `tx_callback` is a function that is called after the tx frame has been encoded. It allows sending one message after the other (as used for data transfers). Using this
+  technique it is possible to effectively set data transfer rates. This works well in combination with the enable flag.
+* `send_now` is only emitted when the generator is invoked with `--send-now`. Setting this flag to 1 makes the next `<api>_periodic_tx` call emit the corresponding frame
+  immediately, regardless of the periodic schedule or the `enable` bit. The function auto-clears the flag after firing, so each set fires exactly once. Useful when a
+  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.
+
+### 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
+must wait a long time until the multiplex is cycled throug all it's mux groups. To reduce the time it takes to read back this kind of message, the `encode all messages` function is used.
+This function generates a group of CanFrames and stores them in to a buffer provided by the caller. This buffer can then be flushed by the application. The size of the buffer required for
+a given message is declared as a preprocessor define in the library header file. To receive all frames generated by the function the caller needs to provide a buffer of at least that size.
+
+the 'encode all signals' function is generated when the tool is passed the `-a` option.
+
+### TI C2000 compatibility
+Some target compilers — notably the TI C2000 toolchain — refuse C99-style "declaration after statement" code, which requires all local variables to be declared at
+the top of a block before any statements. The default code generator emits variable declarations inline inside `switch`/`case` bodies for multiplexed messages, which
+the TI compiler rejects. Passing `--ti-compatible` changes the codegen so every per-signal temporary is hoisted to the top of the enclosing encode/decode function, all
+mux variant assignments become pure stores instead of declarations, and the loop counter in the `encode_every_signal` helper is predeclared before its initializer.
+The resulting source compiles cleanly under both `-std=c99` and `-std=c90 -Wdeclaration-after-statement -Werror=declaration-after-statement`, matching what the TI
+C2000 compiler will accept.
+
+### Double-buffered signal access
+When an RX frame is decoded from an ISR while the main loop reads signals (or the converse for TX, where the user updates the struct while `periodic_tx` encodes
+it), a reader can observe a half-written struct and act on inconsistent data. Passing `--double-buffered` changes the generated global RX and periodic TX
+structs so every message carries two storage slots and two pointers, and the dispatcher / commit helper publishes new values via an atomic pointer swap
+instead of an in-place update:
+
+```c
+struct DUTRxSignals {
+    struct MsgRxContext message_1_context;
+    struct Message1 message_1_signals_storage[2];
+    struct Message1 * volatile message_1_signals;       /* reader view */
+    struct Message1 * message_1_signals_back;            /* dispatcher decodes here */
+    /* ... */
+};
+
+struct DUTTxSignals {
+    struct MsgTxContext message_1_context;
+    struct Message1 message_1_signals_storage[2];
+    struct Message1 * message_1_signals;                 /* staging — user writes here */
+    struct Message1 * volatile message_1_signals_committed; /* periodic_tx reads this */
+    /* ... */
+};
+```
+
+Semantics:
+
+* Access to the signal sub-struct becomes pointer-style instead of dot-style. Read the latest decoded RX value as
+  `rx_signals.message_1_signals->field`, and write a pending TX value as `tx_signals.message_1_signals->field`.
+* `<api>_global_rx_init(&rx_signals)` wires up the front/back pointers and zeroes both storage slots. Call it once before `<api>_process_received_frame`.
+* `<api>_periodic_tx_init(&tx_signals, now)` wires up the staging/committed pointers in addition to the usual context init. Call it once before
+  `<api>_periodic_tx`.
+* For each TX message the generator emits a per-message commit helper, `<api>_<message_name>_commit(&tx_signals)`. It swaps the staging and committed
+  pointers — after the call, the values the user just wrote into staging are live on the `committed` side, and the new staging slot contains the previous
+  `committed` snapshot. The swap is cheap (two pointer writes) and allocation-free.
+* The RX dispatcher decodes into `message_<n>_signals_back` and, on success, swaps `message_<n>_signals` ↔ `message_<n>_signals_back` inside a short inner
+  block. A decode that aborts mid-way never publishes a partial struct — the front pointer keeps pointing at the previously-good decode.
+* Because commits are pointer-swap rather than memcpy, the new staging slot holds the previous committed snapshot. Code that updates a subset of fields per
+  commit therefore still publishes coherent messages, but code that relies on staging being zero after commit must zero it explicitly.
+
+Ordering guarantee: the front/committed pointers are declared `volatile` so the compiler will not reorder the pointer publish across reads in the same
+translation unit. This is sufficient for a single-core MCU where the dispatcher runs in an ISR and readers run in the main loop, which is the target use
+case. On weakly-ordered multicore hosts, user code is responsible for inserting the appropriate memory barrier between the decode writes and the pointer
+publish, and between reading the pointer and dereferencing it — the generator does not emit any barriers itself.
+
+## Example Use
+
+As an example the following KCD definition of all messages on a CAN bus is converted:
+```xml
+<?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="can-api-generator-test-1" version="1" author="Alexander Krishna-Becker" company="radiation.systems" date="2025-11-01"/>
+  <Node id="0" name="DUT"/>
+  <Node id="1" name="other"/>
+  <Bus name="ControlBus" baudrate="500000">
+    <Message id="0x0" length="1" name="Message 1" interval="100" format="extended">
+      <Notes>Test Note 1</Notes>
+      <Producer> <NodeRef id="0"/> </Producer>
+      <Signal name="Signal 1" offset="0" length="1">
+        <Notes>Signal 1 of Message 1 of the DUT</Notes>
+        <Consumer> <NodeRef id="1"/> </Consumer>
+        <Value type="unsigned"/>
+      </Signal>
+      <Signal name="Signal 2" offset="1" length="7">
+        <Notes>Signal 1 of Message 1 of the DUT</Notes>
+        <Consumer> <NodeRef id="1"/> </Consumer>
+        <Value type="signed"/>
+      </Signal>
+    </Message>
+
+    <Message id="0x1" length="2" name="Message 2" interval="100" format="extended">
+      <Notes>Test Note 1</Notes>
+      <Producer> <NodeRef id="0"/> </Producer>
+      <Signal name="Signal 3" offset="0" length="16">
+        <Notes>Signal 1 of Message 1 of the DUT</Notes>
+        <Consumer> <NodeRef id="1"/> </Consumer>
+        <Value type="unsigned"/>
+      </Signal>
+    </Message>
+  </Bus>
+</NetworkDefinition>
+```
+The result of the conversion are the decode/encode functions along with the structs to hold the application accessible signals.
+
+To convert the KCD file into C code the following command is used:
+
+```bash
+can-api-gen example.kcd my_api DUT
+```
+The first argument is the path to the kcd file. The second argument is the name of the API. This name determins the name of the C and H file headers as well as parts of the name of the struct and functions.
+This is done so that multiple APIs may be used within the same project without interfering with each other. The last entry is the name of the Device for which the can api is to be generated.
+This is needed as multiple devices may be described on a single can Bus. The KCD file then needs to describe what signal is sent by a device, as well as which signal a device is listening for.
+The interface generator uses this info to only generate messages that are relevant to the particular device. The following is the resulting header:
+
+```c
+#ifndef CAN_API_MY_API
+#define CAN_API_MY_API
+#include "canframe.h"
+
+// If all signals in a message need to be encoded then it will need
+// a buffer of at least the size defined here to hold the frames to set each signal
+// contained in the message at least once
+#define MESSAGE_1_MIN_FRAMES_FOR_ALL_SIGNALS 1
+#define MESSAGE_2_MIN_FRAMES_FOR_ALL_SIGNALS 1
+
+
+
+struct Message1 {
+    uint16_t signal_1;
+    int16_t signal_2;
+};
+struct Message2 {
+    uint16_t signal_3;
+};
+
+void my_api_message_1_decode(struct Message1 *msg, CanFrame *input_frame);
+void my_api_message_1_encode(struct Message1 *msg, CanFrame *output_frame);
+uint16_t my_api_message_1_encode_every_signal(struct Message1* msg, CanFrame *output_frame_buf, uint32_t buf_size);
+void my_api_message_2_decode(struct Message2 *msg, CanFrame *input_frame);
+void my_api_message_2_encode(struct Message2 *msg, CanFrame *output_frame);
+uint16_t my_api_message_2_encode_every_signal(struct Message2* msg, CanFrame *output_frame_buf, uint32_t buf_size);
+#endif
+```
+
+As can be seen it provides `encode` and `decode` functions for each message that interacts with the DUT. It also emits an `encode_every_signal` helper per message
+(because the example was generated with `-a`), the minimum buffer-size defines the caller needs for that helper, and the message structs themselves. The companion
+`canframe.h` file is written next to the library header; it declares the small `CanFrame` struct the API uses as an I/O boundary with the application's can driver.
+
+To enable the additional features, pass the corresponding flags at generation time:
+
+```bash
+# Generate a full-featured API with global rx, periodic tx, encode-every-signal,
+# send-now support, and TI C2000 compatible codegen.
+can-api-gen example.kcd my_api DUT -r -p -a --send-now --ti-compatible
+```
+
+## Command-line reference
+
+Positional arguments:
+* `KCD_FILE` — path to the KCD (XML) description of the bus.
+* `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
+  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.
+
+Options:
+* `-f`, `--force` — overwrite existing output files. Without this, the generator refuses to clobber an existing `.c`/`.h`.
+* `-a`, `--encode-all-signals-func` — for each message, emit an `<api>_<msg>_encode_every_signal` helper that fills a caller-provided buffer with enough
+  frames to cover every signal at least once (primarily useful for multiplexed config messages).
+* `-r`, `--global-rx` — emit the api-wide `RxSignals` struct plus a `<api>_process_received_frame` dispatcher that takes a raw `CanFrame`, figures out which
+  message it corresponds to, and decodes it into the right per-message struct. See the [Global RX](#global-rx) section for details.
+* `-p`, `--periodic-tx` — emit the api-wide `TxSignals` struct, the `<api>_periodic_tx` function, and `<api>_periodic_tx_init` / `<api>_update_tx_period` /
+  `<api>_get_msg_tx_context_by_id` helpers. See the [Periodic TX](#periodic-tx) section.
+* `--send-now` — add a `send_now` field to each `MsgTxContext` and a gate in the periodic tx function that fires a frame immediately when the flag is set,
+  bypassing both `enable` and the periodic schedule. Only meaningful together with `-p`.
+* `--ti-compatible` — hoist all per-signal temporaries to the top of every encode/decode function so the generated C compiles under strict C90
+  ("declarations before statements"), which is what the TI C2000 compiler requires. See [TI C2000 compatibility](#ti-c2000-compatibility).
+* `--double-buffered` — emit two signal-struct storage slots plus front/back pointers per message, an `<api>_global_rx_init` helper that wires the RX
+  pointers, and a per-message `<api>_<msg>_commit` helper that swaps the TX staging and committed pointers. The RX dispatcher publishes new decodes via
+  pointer swap, and `<api>_periodic_tx` encodes from the committed slot. See [Double-buffered signal access](#double-buffered-signal-access).
+* `-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`).
+* `-pm`, `--payload-member-name TEXT` — override the name of the `CanFrame` payload member (default `payload`).
+* `-v`, `--verbose` — dump the processed message dicts that get fed into the Jinja templates. Useful when debugging template or generator changes.
+* `--help` — show the CLI help and exit.