Re: [PATCH net-next] can: bcm: Document ival1 count semantics

From: Oliver Hartkopp

Date: Wed Nov 18 2026 - 03:43:49 EST


Hello Xu Rao,

many thanks for your patch.

On 12.11.26 03:31, raoxu wrote:
From: Xu Rao <raoxu@xxxxxxxxxxxxx>

Clarify that count controls the initial transmission schedule rather
than counting successfully transmitted CAN frames. An error returned by
can_send() does not prevent the counter from advancing.

Describe the transition to ival2 when count reaches zero, or termination
if ival2 is zero.

Signed-off-by: Xu Rao <raoxu@xxxxxxxxxxxxx>
---
This documentation-only patch follows Oliver Hartkopp's suggestion to
clarify count semantics in the discussion of my earlier patch,
"can: bcm: Account cyclic transmissions only on success".
That code change has been dropped; this patch does not change BCM behavior.

Documentation/networking/can.rst | 5 +++++
1 file changed, 5 insertions(+)

diff --git a/Documentation/networking/can.rst b/Documentation/networking/can.rst
index 51bc70748f75..840d840665a4 100644
--- a/Documentation/networking/can.rst
+++ b/Documentation/networking/can.rst
@@ -892,6 +892,11 @@ only one timer is needed 'count' is set to zero and only 'ival2' is used.
When SET_TIMER and START_TIMER flag were set the timers are activated.
The timer values can be altered at runtime when only SET_TIMER is set.

+For cyclic transmission tasks,

obsolete. the entire section is about cyclic transmission tasks.

``count`` specifies the number of
+transmission attempts scheduled at ``ival1``

correct.

, not the number of
+successfully transmitted CAN frames.

obsolete.
The counter advances even when
+``can_send()`` returns an error.

Yes. But no user knows about can_send().
When ``count`` reaches zero, the
+transmission continues at ``ival2`` if nonzero, or stops otherwise.

This duplicates the description of the functionality from the previous test block.

What about;

When a CAN frame can not be passed to the configured CAN network interface
(e.g. due to a full transmit queue or a network interface being down) this
failure is not reported to the user. In such a failure case the transmission
sequence continues as configured: The frame is not re-sent, the timing
remains unchanged and a non-zero 'count' value is decremented anyway.
Therefore a TX_EXPIRED notification (requested with TX_COUNTEVT) only
indicates that the 'count' transmissions at 'ival1' have been processed and
does not confirm that these frames have been sent successfully.

?

Would this be fine from a users perspective?

Best regards,
Oliver

ps. please tag the patch for can-next if you want to send a V2