[PATCH] Broadcast manager documentation

[Brian Thorne <hardbyte@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 248 bytes --]

Hi all,

I wanted to use the bcm module and ended up putting together some basic findings
that might be a useful addition to the can.txt documentation.

I haven't tried submitting any patches before so please point out any mistakes.

Cheers,
Brian

[-- Attachment #2: 0001-net-Update-the-CAN-broadcast-manager-documentation.patch --]
[-- Type: application/octet-stream, Size: 5890 bytes --]

From 282b4d202b580d57c384dc84aeb7bbb08dff556f Mon Sep 17 00:00:00 2001
From: Brian Thorne <hardbyte@gmail.com>
Date: Tue, 8 Oct 2013 12:10:43 +1300
Subject: [PATCH] net: Update the CAN broadcast manager documentation

Add content to empty section in controller area network
documentation.

Signed-off-by: Brian Thorne <hardbyte@gmail.com>
---
 Documentation/networking/can.txt | 132 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)

diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt
index 820f553..38b1d7e 100644
--- a/Documentation/networking/can.txt
+++ b/Documentation/networking/can.txt
@@ -593,6 +593,138 @@ solution for a couple of reasons:
       In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set.
 
   4.2 Broadcast Manager protocol sockets (SOCK_DGRAM)
+
+  The Broadcast Manager protocol provides an interface to filter and send
+  cyclic CAN packets in kernel space.
+
+  Periodic transmissions can be modified at runtime; both the message content
+  and the interval can be altered. Periodic transmissions can use multiple
+  intervals, sending N messages at a interval, then continuing to send at
+  another given interval.
+
+  Receive filters can be used to down sample frequent messages; detect events
+  such as message contents changes, packet length changes, and do time-out
+  monitoring of received messages.
+
+  A BCM socket is not used for sending individual can frames, instead a new
+  special message is defined. The basic BCM frame structure used to
+  communicate with the broadcast manager and the available operations are
+  defined in include/linux/can/bcm.h. The basic BCM frame consists of a
+  message header with an opcode command followed by zero or more can frames.
+  The broadcast manager sends responses to user space in the same form:
+
+    struct bcm_msg_head {
+            __u32 opcode;                   /* command */
+            __u32 flags;                    /* special flags */
+            __u32 count;                    /* run 'count' times with ival1 */
+            struct timeval ival1, ival2;    /* count and subsequent interval */
+            canid_t can_id;                 /* unique can_id for task */
+            __u32 nframes;                  /* number of can_frames following */
+            struct can_frame frames[0];
+    };
+
+  The frames payload uses the same basic CAN frame structure defined at the
+  beginning of section 4. All messages to the broadcast manager from user
+  space have this structure.
+
+  Note a CAN_BCM socket must be connected instead of bound after socket
+  creation (example without error checking):
+
+    int s;
+    struct sockaddr_can addr;
+    struct ifreq ifr;
+
+    s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
+
+    strcpy(ifr.ifr_name, "can0");
+    ioctl(s, SIOCGIFINDEX, &ifr);
+
+    addr.can_family = AF_CAN;
+    addr.can_ifindex = ifr.ifr_ifindex;
+
+    connect(s, (struct sockaddr *)&addr, sizeof(addr))
+
+    (..)
+
+  The broadcast manager socket is able to handle any number of in flight
+  transmissions or receive filters concurrently. However additional sockets
+  are required to communicate on multiple CAN buses.
+
+  4.2.1 Broadcast Manager Operations
+
+  The opcode defines the operation for the broadcast manager to carry out, or
+  details the broadcast managers response to several events, including user
+  requests.
+
+  Transmit Operations
+
+  The following transmit operations may be sent from user space to the
+  broadcast manager:
+
+    TX_SETUP:   create (cyclic) transmission task
+
+    TX_DELETE:  remove (cyclic) transmission task, requires only can_id.
+
+    TX_READ:    read properties of (cyclic) transmission task
+
+    TX_SEND:    send one CAN frame
+
+  Transmit Responses
+
+    TX_STATUS:  reply to TX_READ request
+
+    TX_EXPIRED: notification when counter finishes sending at initial interval
+      Requires the TX_COUNTEVT flag to be set.
+
+  Receive Operations
+
+    RX_SETUP:   create RX content filter subscription
+
+    RX_DELETE:  remove RX content filter subscription
+
+    RX_READ:    read properties of RX content filter subscription
+
+  Receive Responses
+
+    RX_STATUS:  reply to RX_READ request
+
+    RX_TIMEOUT: Cyclic message is absent. Sent when time controlled
+      message reception failed.
+
+    RX_CHANGED: updated CAN frame (detected content change). Sent on first
+      message received, or on a receipt of a revised CAN messages.
+
+  4.2.2 Broadcast Manager message flags
+
+  When sending a message to the broadcast manager the msg->flags may contain
+  the following flags which influence the behaviour:
+
+    SETTIMER:           Set the value of ival1, ival2 and count
+
+    STARTTIMER:         Start the timer with the actual value of ival1, ival2
+      and count. Starting the timer leads simultaneously to emit a can_frame.
+
+    TX_COUNTEVT:        create the message TX_EXPIRED when count expires
+
+    TX_ANNOUNCE:        A change of data by the process is emitted immediately.
+
+    TX_CP_CAN_ID:       Copies the can_id from the message header attached to
+      each frame in frames. This is intended only as usage simplification.
+
+    RX_FILTER_ID:       Filter by can_id alone, no frames required (nframes=0)
+
+    RX_CHECK_DLC:       A change of the DLC leads to an RX_CHANGED.
+
+    RX_NO_AUTOTIMER:    Prevent automatically starting the timeout monitor.
+
+    RX_ANNOUNCE_RESUME: If passed to RX_SETUP, when a receive timeout occurs,
+      an RX_CHANGED will be generated when the (cyclic) receive restarts.
+
+    TX_RESET_MULTI_IDX: Start multiple frame transmission with index 0.
+
+    RX_RTR_FRAME:       send reply for RTR-request (placed in op->frames[0])
+
+
   4.3 connected transport protocols (SOCK_SEQPACKET)
   4.4 unconnected transport protocols (SOCK_DGRAM)
 
-- 
1.8.1.2