v4 typedefs and migration guide (#237)

- eliminated struct/enum typedef-s
- added migration guide

Author: serges147

MIGRATION_v3.x_to_v4.0.md

@@ -0,0 +1,252 @@
+# Migration Guide: Updating from Libcanard v3.x to v4.0
+
+This guide is intended to help developers migrate their applications from Libcanard version 3.x to version 4.0. It outlines the key changes between the two versions and provides step-by-step instructions to update your code accordingly.
+
+## Introduction
+
+Libcanard is a compact implementation of the Cyphal/CAN protocol designed for high-integrity real-time embedded systems. Version 4 introduces several changes that may impact your existing codebase. This guide will help you understand these changes and update your application accordingly.
+
+These changes do not affect wire compatibility.
+
+## Version Changes
+
+- **Libcanard Version**:
+  - **Old**: `CANARD_VERSION_MAJOR 3`, `CANARD_VERSION_MINOR 3`
+  - **New**: `CANARD_VERSION_MAJOR 4`, `CANARD_VERSION_MINOR 0`
+- **Cyphal Specification Version**: Remains the same (`1.0`).
+
+## API Changes
+
+### New Functions
+
+- **`canardTxFree`**:
+  - **Description**: A helper function to free memory allocated for transmission queue items, including the frame payload buffer.
+  - **Prototype**:
+    ```c
+    void canardTxFree(
+        struct CanardTxQueue* const        que,
+        const struct CanardInstance* const ins,
+        struct CanardTxQueueItem* const    item);
+    ```
+  - **Usage**: After popping a transmission queue item using `canardTxPop`, use `canardTxFree` to deallocate its memory.
+
+### Modified Functions
+
+Several functions have updated prototypes and usage patterns:
+
+1. **`canardInit`**:
+   - **Old Prototype**:
+     ```c
+     CanardInstance canardInit(
+         const CanardMemoryAllocate memory_allocate,
+         const CanardMemoryFree     memory_free);
+     ```
+   - **New Prototype**:
+     ```c
+     struct CanardInstance canardInit(
+         const struct CanardMemoryResource memory);
+     ```
+   - **Changes**:
+     - Replaces `CanardMemoryAllocate` and `CanardMemoryFree` function pointers with a `CanardMemoryResource` struct.
+
+2. **`canardTxInit`**:
+   - **Old Prototype**:
+     ```c
+     CanardTxQueue canardTxInit(
+         const size_t capacity,
+         const size_t mtu_bytes);
+     ```
+   - **New Prototype**:
+     ```c
+     struct CanardTxQueue canardTxInit(
+         const size_t                      capacity,
+         const size_t                      mtu_bytes,
+         const struct CanardMemoryResource memory);
+     ```
+   - **Changes**:
+     - Adds a `CanardMemoryResource` parameter for memory allocation of payload data.
+
+3. **`canardTxPush`**:
+   - **Old Prototype**:
+     ```c
+     int32_t canardTxPush(
+         CanardTxQueue* const                que,
+         CanardInstance* const               ins,
+         const CanardMicrosecond             tx_deadline_usec,
+         const CanardTransferMetadata* const metadata,
+         const size_t                        payload_size,
+         const void* const                   payload);
+     ```
+   - **New Prototype**:
+     ```c
+     int32_t canardTxPush(
+         struct CanardTxQueue* const                que,
+         const struct CanardInstance* const         ins,
+         const CanardMicrosecond                    tx_deadline_usec,
+         const struct CanardTransferMetadata* const metadata,
+         const struct CanardPayload                 payload);
+     ```
+   - **Changes**:
+     - Replaces `payload_size` and `payload` with a single `CanardPayload` struct.
+
+4. **`canardTxPeek`** and **`canardTxPop`**:
+   - The functions now return and accept pointers to mutable `struct CanardTxQueueItem` instead of const pointers.
+
+### Removed Functions
+
+- No functions have been explicitly removed, but some have modified prototypes.
+
+## Data Structure Changes
+
+### Type Definitions
+
+- **Enumerations**:
+  - Changed from `typedef enum` to `enum` without `typedef`.
+  - **Old**:
+    ```c
+    typedef enum { ... } CanardPriority;
+    ```
+  - **New**:
+    ```c
+    enum CanardPriority { ... };
+    ```
+
+- **Structures**:
+  - Changed from forward declarations and `typedef struct` to direct `struct` definitions.
+  - **Old**:
+    ```c
+    typedef struct CanardInstance CanardInstance;
+    ```
+  - **New**:
+    ```c
+    struct CanardInstance { ... };
+    ```
+
+### Struct Modifications
+
+- **`CanardFrame`**:
+  - **Old**:
+    ```c
+    typedef struct {
+        uint32_t extended_can_id;
+        size_t   payload_size;
+        const void* payload;
+    } CanardFrame;
+    ```
+  - **New**:
+    ```c
+    struct CanardFrame {
+        uint32_t extended_can_id;
+        struct CanardPayload payload;
+    };
+    ```
+  - **Changes**:
+    - Payload now uses the `CanardPayload` struct.
+
+- **New Structs Introduced**:
+  - **`CanardPayload`** and **`CanardMutablePayload`**: Encapsulate payload data and size.
+  - **`CanardMutableFrame`**: Similar to `CanardFrame` but uses `CanardMutablePayload`.
+
+- **`CanardInstance`**:
+  - Now contains a `CanardMemoryResource` for memory management instead of separate function pointers.
+
+- **`CanardTxQueue`**:
+  - Includes a `CanardMemoryResource` for payload data allocation.
+
+- **`CanardMemoryResource`** and **`CanardMemoryDeleter`**:
+  - New structs to encapsulate memory allocation and deallocation functions along with user references.
+
+## Memory Management Changes
+
+- **Memory Resource Structs**:
+  - Memory allocation and deallocation are now handled via `CanardMemoryResource` and `CanardMemoryDeleter` structs.
+  - Functions now receive these structs instead of direct function pointers.
+
+- **Allocation Functions**:
+  - **Allocation**:
+    ```c
+    typedef void* (*CanardMemoryAllocate)(
+        void* const user_reference,
+        const size_t size);
+    ```
+  - **Deallocation**:
+    ```c
+    typedef void (*CanardMemoryDeallocate)(
+        void* const user_reference,
+        const size_t size,
+        void* const pointer);
+    ```
+
+## Migration Steps
+
+1. **Update Type Definitions**:
+   - Replace all `typedef`-based enum and struct types with direct `struct` and `enum` declarations.
+   - For example, change `CanardInstance` to `struct CanardInstance`.
+
+2. **Adjust Memory Management Code**:
+   - Replace separate memory allocation and deallocation function pointers with `CanardMemoryResource` and `CanardMemoryDeleter` structs.
+   - Update function calls and definitions accordingly.
+
+3. **Modify Function Calls**:
+   - Update all function calls to match the new prototypes.
+   - **`canardInit`**:
+     - Before:
+       ```c
+       canardInit(memory_allocate, memory_free);
+       ```
+     - After:
+       ```c
+       struct CanardMemoryResource memory = {
+           .user_reference = ...,
+           .allocate = memory_allocate,
+           .deallocate = memory_free
+       };
+       canardInit(memory);
+       ```
+   - **`canardTxInit`**:
+     - Before:
+       ```c
+       canardTxInit(capacity, mtu_bytes);
+       ```
+     - After:
+       ```c
+       canardTxInit(capacity, mtu_bytes, memory);
+       ```
+   - **`canardTxPush`**:
+     - Before:
+       ```c
+       canardTxPush(que, ins, tx_deadline_usec, metadata, payload_size, payload);
+       ```
+     - After:
+       ```c
+       struct CanardPayload payload_struct = {
+           .size = payload_size,
+           .data = payload
+       };
+       canardTxPush(que, ins, tx_deadline_usec, metadata, payload_struct);
+       ```
+
+4. **Handle New Functions**:
+   - Use `canardTxFree` to deallocate transmission queue items after popping them.
+   - Example:
+     ```c
+     struct CanardTxQueueItem* item = canardTxPeek(&tx_queue);
+     while (item != NULL) {
+         // Transmit the frame...
+         canardTxPop(&tx_queue, item);
+         canardTxFree(&tx_queue, &canard_instance, item);
+         item = canardTxPeek(&tx_queue);
+     }
+     ```
+
+5. **Update Struct Field Access**:
+   - Adjust your code to access struct fields directly, considering the changes in struct definitions.
+   - For example, access `payload.size` instead of `payload_size`.
+
+6. **Adjust Memory Allocation Logic**:
+   - Ensure that your memory allocation and deallocation functions conform to the new prototypes.
+   - Pay attention to the additional `size` parameter in the deallocation function.
+
+7. **Test Thoroughly**:
+   - After making the changes, thoroughly test your application to ensure that it functions correctly with the new library version.
+   - Pay special attention to memory management and potential leaks.

README.md

@@ -57,9 +57,6 @@ reused in the target application to speed up the design of the media IO layer (d
 
 ## Example
 
-## TODO: Update to show how to use the new sized de-allocations, and how not to confuse payload_size and allocated_size.
-☝ todo will be addressed as soon as the new API is stable (tx, rx, and "zero copy" aspects).
-
 The example augments the documentation but does not replace it.
 
 The library requires a constant-complexity deterministic dynamic memory allocator.
@@ -68,39 +65,43 @@ so let's suppose that we're using [O1Heap](https://github.com/pavel-kirienko/o1h
 We are going to need basic wrappers:
 
 ```c
-static void* memAllocate(CanardInstance* const canard, const size_t amount)
+static void* memAllocate(void* const user_reference, const size_t size)
 {
-    (void) canard;
-    return o1heapAllocate(my_allocator, amount);
+    (void) user_reference;
+    return o1heapAllocate(my_allocator, size);
 }
 
-static void memFree(CanardInstance* const canard, void* const pointer, const size_t amount)
+static void memFree(void* const user_reference, const size_t size, void* const pointer)
 {
-    (void) canard;
-    (void) amount;
+    (void) user_reference;
+    (void) size;
     o1heapFree(my_allocator, pointer);
 }
 ```
 
 Init a library instance:
 
 ```c
-CanardInstance canard = canardInit(&memAllocate, &memFree);
+const struct CanardMemoryResource memory{nullptr, &memAllocate, &memFree};
+struct CanardInstance canard = canardInit(memory);
 canard.node_id = 42;                        // Defaults to anonymous; can be set up later at any point.
 ```
 
 In order to be able to send transfers over the network, we will need one transmission queue per redundant CAN interface:
 
 ```c
-CanardTxQueue queue = canardTxInit(100,                 // Limit the size of the queue at 100 frames.
-                                   CANARD_MTU_CAN_FD);  // Set MTU = 64 bytes. There is also CANARD_MTU_CAN_CLASSIC.
+const struct CanardMemoryResource tx_memory{nullptr, memAllocate, memFree};
+struct CanardTxQueue queue = canardTxInit(
+    100,                // Limit the size of the queue at 100 frames.
+    CANARD_MTU_CAN_FD,  // Set MTU = 64 bytes. There is also CANARD_MTU_CAN_CLASSIC.
+    tx_memory);
 ```
 
 Publish a message (message serialization not shown):
 
 ```c
 static uint8_t my_message_transfer_id;  // Must be static or heap-allocated to retain state between calls.
-const CanardTransferMetadata transfer_metadata = {
+const struct CanardTransferMetadata transfer_metadata = {
     .priority       = CanardPriorityNominal,
     .transfer_kind  = CanardTransferKindMessage,
     .port_id        = 1234,                       // This is the subject-ID.
@@ -131,7 +132,7 @@ Normally, the following fragment should be invoked periodically to unload the CA
 prioritized transmission queue (or several, if redundant network interfaces are used) into the CAN driver:
 
 ```c
-for (const CanardTxQueueItem* ti = NULL; (ti = canardTxPeek(&queue)) != NULL;)  // Peek at the top of the queue.
+for (struct CanardTxQueueItem* ti = NULL; (ti = canardTxPeek(&queue)) != NULL;)  // Peek at the top of the queue.
 {
     if ((0U == ti->tx_deadline_usec) || (ti->tx_deadline_usec > getCurrentMicroseconds()))  // Check the deadline.
     {
@@ -141,7 +142,7 @@ for (const CanardTxQueueItem* ti = NULL; (ti = canardTxPeek(&queue)) != NULL;)
         }
     }
     // After the frame is transmitted or if it has timed out while waiting, pop it from the queue and deallocate:
-    canard.memory_free(&canard, canardTxPop(&queue, ti));
+    canardTxFree(&queue, &canard, canardTxPop(&queue, ti));
 }
 ```
 
@@ -150,15 +151,15 @@ from any of the redundant interfaces.
 But first, we need to subscribe:
 
 ```c
-CanardRxSubscription heartbeat_subscription;
+struct CanardRxSubscription heartbeat_subscription;
 (void) canardRxSubscribe(&canard,   // Subscribe to messages uavcan.node.Heartbeat.
                          CanardTransferKindMessage,
                          7509,      // The fixed Subject-ID of the Heartbeat message type (see DSDL definition).
                          16,        // The extent (the maximum possible payload size) provided by Nunavut.
                          CANARD_DEFAULT_TRANSFER_ID_TIMEOUT_USEC,
                          &heartbeat_subscription);
 
-CanardRxSubscription my_service_subscription;
+struct CanardRxSubscription my_service_subscription;
 (void) canardRxSubscribe(&canard,   // Subscribe to an arbitrary service response.
                          CanardTransferKindResponse,  // Specify that we want service responses, not requests.
                          123,       // The Service-ID whose responses we will receive.
@@ -183,7 +184,7 @@ Normally, however, an embedded application would subscribe once and roll with it
 Okay, this is how we receive transfers:
 
 ```c
-CanardRxTransfer transfer;
+struct CanardRxTransfer transfer;
 const int8_t result = canardRxAccept(&canard,
                                      rx_timestamp_usec,          // When the frame was received, in microseconds.
                                      &received_frame,            // The CAN frame received from the bus.
@@ -216,15 +217,15 @@ the number of irrelevant transfers processed in software.
 
 ```c
 // Generate an acceptance filter to receive only uavcan.node.Heartbeat.1.0 messages (fixed port-ID 7509):
-CanardFilter heartbeat_config = canardMakeFilterForSubject(7509);
+struct CanardFilter heartbeat_config = canardMakeFilterForSubject(7509);
 // And to receive only uavcan.register.Access.1.0 service transfers (fixed port-ID 384):
-CanardFilter register_access_config = canardMakeFilterForService(384, ins.node_id);
+struct CanardFilter register_access_config = canardMakeFilterForService(384, ins.node_id);
 
 // You can also combine the two filter configurations into one (may also accept irrelevant messages).
 // This allows consolidating a large set of configurations to fit the number of hardware filters.
 // For more information on the optimal subset of configurations to consolidate to minimize wasted CPU,
 // see the Cyphal specification.
-CanardFilter combined_config =
+struct CanardFilter combined_config =
         canardConsolidateFilters(&heartbeat_config, &register_access_config);
 configureHardwareFilters(combined_config.extended_can_id, combined_config.extended_mask);
 ```
@@ -234,6 +235,11 @@ If you find the examples to be unclear or incorrect, please, open a ticket.
 
 ## Revisions
 
+### v4.0
+
+- Updating from Libcanard v3 to v4 involves several significant changes, especially in memory management and API function prototypes.
+- Please follow [MIGRATION_v3.x_to_v4.0](MIGRATION_v3.x_to_v4.0.md) guide and carefully update your code.
+
 ### v3.2
 
 - Added new `canardRxGetSubscription`.