Lines Matching +full:message +full:- +full:handling +full:- +full:unit
2 SocketCAN - Controller Area Network
20 .. _socketcan-motivation:
29 functionality. Usually, there is only a hardware-specific device
32 Queueing of frames and higher-level transport protocols like ISO-TP
34 character-device implementations support only one single process to
47 protocol family module and also vice-versa. Also, the protocol family
57 communicate using a specific transport protocol, e.g. ISO-TP, just
60 CAN-IDs, frames, etc.
62 Similar functionality visible from user-space could be provided by a
74 * **Abstraction:** In most existing character-device implementations, the
75 hardware-specific device driver for a CAN controller directly
83 application on the one hand, and a interface for hardware-specific
103 .. _socketcan-concept:
108 As described in :ref:`socketcan-motivation` the main goal of SocketCAN is to
111 TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
112 medium that has no MAC-layer addressing like ethernet. The CAN-identifier
113 (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs
114 have to be chosen uniquely on the bus. When designing a CAN-ECU
115 network the CAN-IDs are mapped to be sent by a specific ECU.
116 For this reason a CAN-ID can be treated best as a kind of source address.
119 .. _socketcan-receive-lists:
122 -------------
126 CAN-IDs from the same CAN network interface. The SocketCAN core
127 module - which implements the protocol family CAN - provides several
130 requests the (range of) CAN-IDs from the SocketCAN core that are
132 CAN-IDs can be done for specific CAN interfaces or for all(!) known
134 CAN protocol modules by the SocketCAN core (see :ref:`socketcan-core-module`).
137 filter complexity for a given use-case.
140 .. _socketcan-local-loopback1:
143 -----------------------------
156 -----------------(1)- CAN bus -(2)---------------
165 arbitration on the CAN bus the transmission of a low prio CAN-ID
171 See :ref:`socketcan-local-loopback2` for details (recommended).
175 the RT-SocketCAN group the loopback optionally may be disabled for each
176 separate socket. See sockopts from the CAN RAW sockets in :ref:`socketcan-raw-sockets`.
182 .. _socketcan-network-problem-notifications:
185 -----------------------------
194 reason the CAN interface driver can generate so called Error Message
198 creates an appropriate error message frame. Error messages frames can
202 by default. The format of the CAN error message frame is briefly
225 - see :ref:`socketcan-concept`). After binding (CAN_RAW) or connecting (CAN_BCM)
234 .. code-block:: C
270 .. code-block:: C
303 .. code-block:: C
331 .. code-block:: C
358 .. code-block:: C
376 .. code-block:: C
387 a message from the socket:
389 .. code-block:: C
399 Generally the handling of CAN FD is very similar to the formerly described
406 switches the socket into a mode that allows the handling of CAN FD frames
407 and Classical CAN frames simultaneously (see :ref:`socketcan-rawfd`).
411 .. code-block:: C
426 all structure elements can be used as-is - only the data[] becomes extended.
431 the easy handling of the length information the canfd_frame.len element
435 the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`.
438 unit (MTU) of the CAN(FD) network interface and skbuff data length. Two
441 .. code-block:: C
447 .. _socketcan-raw-sockets:
450 ------------------------------------------------
457 - The filters are set to exactly one filter receiving everything
458 - The socket only receives valid data frames (=> no error message frames)
459 - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`)
460 - The socket does not receive its own sent frames (in loopback mode)
467 .. _socketcan-rawfilter:
477 .. code-block:: C
486 .. code-block:: C
496 .. code-block:: C
509 .. code-block:: C
515 having this 'send only' use-case we may remove the receive list in the
521 The CAN filters are processed in per-device filter lists at CAN frame
524 filter handling when the filter subscription focusses on a single CAN ID.
537 .. code-block:: C
547 .. code-block:: C
562 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
563 called Error Message Frames that can optionally be passed to the user
570 .. code-block:: C
582 (see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases
586 .. code-block:: C
598 frames' CAN-ID on this given interface to meet the multi user
604 .. code-block:: C
612 filtering as other CAN frames (see :ref:`socketcan-rawfilter`).
614 .. _socketcan-rawfd:
622 CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT.
628 .. code-block:: C
635 .. code-block:: C
675 CAN FD frames by checking if the device maximum transfer unit is CANFD_MTU.
685 applied (see :ref:`socketcan-rawfilter`).
696 RAW Socket Returned Message Flags
699 When using recvmsg() call, the msg->msg_flags may contain following flags:
708 :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`.
713 -----------------------------------------------
719 such as message contents changes, packet length changes, and do time-out
723 created and modified at runtime; both the message content and the two
728 configuration message is defined. The basic BCM configuration message used
730 defined in the linux/can/bcm.h include. The BCM message consists of a
731 message header with a command ('opcode') followed by zero or more CAN frames.
734 .. code-block:: C
747 at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
753 .. code-block:: C
773 distinguished by the unique can_id in each BCM message. However additional
829 Cyclic message is detected to be absent (timer ival1 expired).
832 BCM message with updated CAN frame (detected content change).
833 Sent on first message received or on receipt of revised CAN messages.
836 Broadcast Manager Message Flags
839 When sending a message to the broadcast manager the 'flags' element may
850 Create the message TX_EXPIRED when count expires
856 Copies the can_id from the message header to each
858 TX tasks the unique can_id from the message header may differ from the
872 RX_CHANGED message will be generated when the (cyclic) receive restarts.
878 Send reply for RTR-request (placed in op->frames[0]).
894 Broadcast Manager message sequence transmission
899 element of the BCM message head. The defined number of CAN frames are added
900 as array to the TX_SETUP BCM configuration message:
902 .. code-block:: C
923 The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP.
927 Send RX_TIMEOUT when a received message is not received again within
929 is activated directly - even without a former CAN frame reception.
932 Throttle the received message rate down to the value of ival2. This
937 Broadcast Manager Multiplex Message Receive Filter
940 To filter for content changes in multiplex message sequences an array of more
941 than one CAN frames can be passed in a RX_SETUP configuration message. The
947 filters) can be added as array to the TX_SETUP BCM configuration message:
949 .. code-block:: C
951 /* usually used to clear CAN frame data[] - beware of endian problems! */
952 #define U64_DATA(p) (*(unsigned long long*)(p)->data)
981 .. code-block:: C
999 ----------------------------------------------
1005 --------------------------------------------
1010 .. _socketcan-core-module:
1018 modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`).
1022 --------------------
1024 - **stats_timer**:
1030 - **debug**:
1035 --------------
1037 As described in :ref:`socketcan-receive-lists` the SocketCAN core uses several filter
1055 rcvlist_all - list for unfiltered entries (no filter operations)
1056 rcvlist_eff - list for single extended frame (EFF) entries
1057 rcvlist_err - list for error message frames masks
1058 rcvlist_fil - list for mask/value filters
1059 rcvlist_inv - list for mask/value filters (inverse semantic)
1060 rcvlist_sff - list for single standard frame (SFF) entries
1064 stats - SocketCAN core statistics (rx/tx frames, match ratios, ...)
1065 reset_stats - manual statistic reset
1066 version - prints SocketCAN core and ABI version (removed in Linux 5.10)
1070 --------------------------------
1080 can_rx_register - subscribe CAN frames from a specific interface
1081 can_rx_unregister - unsubscribe CAN frames from a specific interface
1082 can_send - transmit a CAN frame (optional with local loopback)
1095 - TX: Put the CAN frame from the socket buffer to the CAN controller.
1096 - RX: Put the CAN frame from the CAN controller to the socket buffer.
1103 ----------------
1105 .. code-block:: C
1107 dev->type = ARPHRD_CAN; /* the netdevice hardware type */
1108 dev->flags = IFF_NOARP; /* CAN has no arp */
1110 dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> Classical CAN interface */
1113 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
1119 .. _socketcan-local-loopback2:
1122 -----------------------------
1124 As described in :ref:`socketcan-local-loopback1` the CAN network device driver should
1130 dev->flags = (IFF_NOARP | IFF_ECHO);
1134 -------------------------------
1139 controller and have to be identified as not feasible in a multi-user
1141 hardware filters could make sense in a very dedicated use-case, as a
1142 filter on driver level would affect all users in the multi-user
1152 -----------------------------
1157 - a unique CAN Identifier (CAN ID)
1158 - the CAN bus this CAN ID is transmitted on (e.g. can0)
1171 - Create a virtual CAN network interface:
1174 - Create a virtual CAN network interface with a specific name 'vcan42':
1177 - Remove a (virtual CAN) network interface 'vcan42':
1182 ---------------------------------------
1186 configure the CAN device, like setting the bit-timing parameters, via
1192 understand how to use them. The name of the module is can-dev.ko.
1199 netlink message types are defined and briefly described in
1208 [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
1209 [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
1210 phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
1212 [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
1213 [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
1214 dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
1217 [ listen-only { on | off } ]
1218 [ triple-sampling { on | off } ]
1219 [ one-shot { on | off } ]
1220 [ berr-reporting { on | off } ]
1222 [ fd-non-iso { on | off } ]
1223 [ presume-ack { on | off } ]
1224 [ cc-len8-dlc { on | off } ]
1226 [ restart-ms TIME-MS ]
1230 SAMPLE-POINT := { 0.000..0.999 }
1232 PROP-SEG := { 1..8 }
1233 PHASE-SEG1 := { 1..8 }
1234 PHASE-SEG2 := { 1..8 }
1236 RESTART-MS := { 0 | NUMBER }
1240 $ ip -details -statistics link show can0
1243 can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
1245 tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
1246 sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1248 re-started bus-errors arbit-lost error-warn error-pass bus-off
1257 "<TRIPLE-SAMPLING>"
1259 LISTEN-ONLY, or TRIPLE-SAMPLING.
1261 "state ERROR-ACTIVE"
1262 The current state of the CAN controller: "ERROR-ACTIVE",
1263 "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED"
1265 "restart-ms 100"
1266 Automatic restart delay time. If set to a non-zero value, a
1268 in case of a bus-off condition after the specified delay time
1271 "bitrate 125000 sample-point 0.875"
1272 Shows the real bit-rate in bits/sec and the sample-point in the
1273 range 0.000..0.999. If the calculation of bit-timing parameters
1275 bit-timing can be defined by setting the "bitrate" argument.
1276 Optionally the "sample-point" can be specified. By default it's
1277 0.000 assuming CIA-recommended sample-points.
1279 "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1"
1282 tq. They allow to define the CAN bit-timing in a hardware
1286 "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000"
1287 Shows the bit-timing constants of the CAN controller, here the
1290 bitrate pre-scaler and the CAN system clock frequency in Hz.
1291 These constants could be used for user-defined (non-standard)
1292 bit-timing calculation algorithms in user-space.
1294 "re-started bus-errors arbit-lost error-warn error-pass bus-off"
1296 and the state changes to the error-warning, error-passive and
1297 bus-off state. RX overrun errors are listed in the "overrun"
1300 Setting the CAN Bit-Timing
1303 The CAN bit-timing parameters can always be defined in a hardware
1308 $ ip link set canX type can tq 125 prop-seg 6 \
1309 phase-seg1 7 phase-seg2 2 sjw 1
1312 recommended CAN bit-timing parameters will be calculated if the bit-
1318 standard bit-rates but may *fail* for exotic bit-rates or CAN system
1320 space and allows user-space tools to solely determine and set the
1321 bit-timing parameters. The CAN controller specific bit-timing
1325 $ ip -details link show can0
1327 sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1335 you *must* define proper bit-timing parameters for real CAN devices
1336 before you can start it to avoid error-prone default settings::
1340 A device may enter the "bus-off" state if too many errors occurred on
1342 bus-off recovery can be enabled by setting the "restart-ms" to a
1343 non-zero value, e.g.::
1345 $ ip link set canX type can restart-ms 100
1347 Alternatively, the application may realize the "bus-off" condition
1348 by monitoring CAN error message frames and do a restart when
1353 Note that a restart will also create a CAN error message frame (see
1354 also :ref:`socketcan-network-problem-notifications`).
1357 .. _socketcan-can-fd-driver:
1360 ------------------------------------------
1371 CAN frames anyway. The payload length to the bus-relevant DLC mapping is
1376 devices maximum transfer unit (MTU)::
1389 dsample-point, dsjw or dtq and similar settings. When a data bitrate is set
1398 - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
1399 - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
1404 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c)
1405 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
1407 The current ISO/non-ISO mode is announced by the CAN controller driver via
1408 netlink and displayed by the 'ip' tool (controller option FD-NON-ISO).
1409 The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
1414 $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
1415 dbitrate 4000000 dsample-point 0.8 fd on
1416 $ ip -details link show can0
1420 can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1421 bitrate 500000 sample-point 0.750
1422 tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
1424 brp-inc 1
1425 dbitrate 4000000 dsample-point 0.800
1426 dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
1428 dbrp-inc 1
1431 Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
1433 can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1437 ----------------------
1441 (see :ref:`socketcan-resources`) there might be further drivers available, also for
1445 .. _socketcan-resources:
1457 - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
1458 - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
1459 - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
1460 - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver inter…
1461 - Robert Schwebel (design reviews, PTXdist integration)
1462 - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
1463 - Benedikt Spranger (reviews)
1464 - Thomas Gleixner (LKML reviews, coding style, posting hints)
1465 - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
1466 - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
1467 - Klaus Hitschler (PEAK driver integration)
1468 - Uwe Koppe (CAN netdevices with PF_PACKET approach)
1469 - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
1470 - Pavel Pisa (Bit-timing calculation)
1471 - Sascha Hauer (SJA1000 platform driver)
1472 - Sebastian Haas (SJA1000 EMS PCI driver)
1473 - Markus Plessing (SJA1000 EMS PCI driver)
1474 - Per Dalen (SJA1000 Kvaser PCI driver)
1475 - Sam Ravnborg (reviews, coding style, kbuild help)