update the filtering API

Author: pavel-kirienko

.idea/dictionaries/project.xml

@@ -1546,15 +1546,15 @@ static canard_subscription_t* rx_route(const canard_t* const self, const frame_t
     if ((fr->dst != CANARD_NODE_ID_ANONYMOUS) && (fr->dst != self->node_id)) {
         return NULL; // misfiltered
     }
-    return (canard_subscription_t*)cavl2_find(
+    return (canard_subscription_t*)(void*)cavl2_find(
       self->rx.subscriptions[fr->kind], &fr->port_id, rx_subscription_cavl_compare);
 }
 
 // Recompute the filter configuration and apply.
 // Must be invoked after modification of the subscription set and after the local node-ID is changed.
 static void rx_filter_configure(const canard_t* const self)
 {
-    if (self->vtable->filter == NULL) {
+    if ((self->vtable->filter == NULL) || (self->rx.filter_count == 0)) {
         return; // No filtering support, nothing to do.
     }
     (void)self;
@@ -1602,18 +1602,16 @@ bool canard_new(canard_t* const              self,
                 const canard_mem_set_t       memory,
                 const size_t                 tx_queue_capacity,
                 const uint64_t               prng_seed,
-                const size_t                 filter_count,
-                canard_filter_t* const       filter_storage)
+                const size_t                 filter_count)
 {
     const bool ok = (self != NULL) && (vtable != NULL) && (vtable->now != NULL) && (vtable->tx != NULL) &&
                     mem_valid(memory.tx_transfer) && mem_valid(memory.tx_frame) && mem_valid(memory.rx_session) &&
-                    mem_valid(memory.rx_payload) && ((filter_count == 0U) || (filter_storage != NULL));
+                    mem_valid(memory.rx_payload);
     if (ok) {
         (void)memset(self, 0, sizeof(*self));
         self->tx.fd                     = true;
         self->tx.queue_capacity         = tx_queue_capacity;
-        self->rx.filter_count           = filter_count;
-        self->rx.filters                = filter_storage;
+        self->rx.filter_count           = (vtable->filter == NULL) ? 0 : smaller(filter_count, CANARD_FILTERS_MAX);
         self->mem                       = memory;
         self->prng_state                = prng_seed ^ (uintptr_t)self;
         self->vtable                    = vtable;

libcanard/canard.c

@@ -80,6 +80,16 @@ extern "C"
 #define CANARD_MTU_CAN_CLASSIC 8U
 #define CANARD_MTU_CAN_FD      64U
 
+/// If CAN acceptance filter configuration is enabled, the library will be able to configure at most this many filters.
+/// The application can configure a smaller limit at runtime if necessary; this value only affects a stack array size.
+/// The default value is large enough to utilize all available filters in most CAN controllers out there,
+/// considering that we use filters in the extended ID&mask mode which tends to consume more hardware resources.
+/// This value can be reduced to reduce the stack pressure on the filter configuration update path,
+/// or increased if more filters are available (e.g., Bosch M_CAN or ST FDCAN support up to 64, SocketCAN up to 512).
+#ifndef CANARD_FILTERS_MAX
+#define CANARD_FILTERS_MAX 32U
+#endif
+
 /// All valid transfer kind and version combinations.
 typedef enum canard_kind_t
 {
@@ -293,7 +303,8 @@ typedef struct canard_vtable_t
 
     /// Reconfigure the acceptance filters of the CAN controller hardware.
     /// The prior configuration, if any, is replaced entirely.
-    /// filter_count is guaranteed to not exceed the value given at initialization.
+    /// filter_count is guaranteed to not exceed the value given at initialization and CANARD_FILTERS_MAX,
+    /// whichever is smaller.
     /// This function may be NULL if the CAN controller/driver does not support filtering or it is not desired.
     /// The implementation is assumed to be infallible; if error handling is necessary, it must be implemented
     /// on the application side, perhaps with retries.
@@ -345,9 +356,7 @@ struct canard_t
     {
         canard_tree_t* subscriptions[CANARD_KIND_COUNT];
         canard_list_t  list_session_by_animation; ///< Oldest at the head.
-
-        size_t           filter_count;
-        canard_filter_t* filters; ///< Storage provided by the user.
+        size_t         filter_count;              ///< At most CANARD_FILTERS_MAX.
     } rx;
 
     /// Error counters incremented automatically when the corresponding error condition occurs.
@@ -388,9 +397,9 @@ struct canard_t
 /// and collisions, and will automatically migrate to a free node-ID shall a collision be detected.
 /// If manual allocation is desired, use the corresponding function to set the node-ID after initialization.
 ///
-/// The filter storage is an array of filters that is used by the library to automatically set up the acceptance
-/// filters when the RX pipeline is reconfigured. The filter count equals the storage size. The storage must
-/// outlive the library instance. It is possible to pass zero filters & NULL if filtering is unneeded/unsupported.
+/// The filter count is the number of CAN acceptance filters that the library can utilize. If there are fewer filters
+/// than subscriptions, similar filters will be coalesced. The value will be clamped to CANARD_FILTERS_MAX.
+/// It is possible to pass zero filters if filtering is unneeded/unsupported.
 ///
 /// CAN FD mode is selected by default for outgoing frames; override the fd flag to change the mode if needed.
 ///
@@ -400,8 +409,7 @@ bool canard_new(canard_t* const              self,
                 const canard_mem_set_t       memory,
                 const size_t                 tx_queue_capacity,
                 const uint64_t               prng_seed,
-                const size_t                 filter_count,
-                canard_filter_t* const       filter_storage);
+                const size_t                 filter_count);
 
 /// The application MUST destroy all subscriptions before invoking this (this is asserted).
 /// The TX queue will be purged automatically if not empty.

libcanard/canard.h

@@ -102,7 +102,7 @@ static void init_with_capture_node_id(canard_t* const self, tx_capture_t* const
     capture->now       = 0;
     capture->accept_tx = true;
     capture->count     = 0;
-    TEST_ASSERT_TRUE(canard_new(self, &capture_vtable, make_std_memory(), 16U, 1234U, 0U, nullptr));
+    TEST_ASSERT_TRUE(canard_new(self, &capture_vtable, make_std_memory(), 16U, 1234U, 0U));
     TEST_ASSERT_TRUE(canard_set_node_id(self, node_id));
     self->user_context = capture;
 }
@@ -117,7 +117,7 @@ static void test_canard_pending_ifaces()
 {
     canard_t               self = {};
     const canard_mem_set_t mem  = make_std_memory();
-    TEST_ASSERT_TRUE(canard_new(&self, &test_vtable, mem, 16, 1234, 0, nullptr));
+    TEST_ASSERT_TRUE(canard_new(&self, &test_vtable, mem, 16, 1234, 0));
 
     const canard_bytes_chain_t payload = { .bytes = { .size = 0, .data = nullptr }, .next = nullptr };
     TEST_ASSERT_EQUAL_UINT8(0U, canard_pending_ifaces(&self));