Lines Matching +full:overrun +full:- +full:throttle +full:- +full:ms
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 -----------------------------
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
389 .. code-block:: C
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.
435 the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`.
441 .. code-block:: C
448 ----------------------
451 msg->msg_flags field may contain the following flags:
460 :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`.
465 .. _socketcan-raw-sockets:
468 ------------------------------------------------
475 - The filters are set to exactly one filter receiving everything
476 - The socket only receives valid data frames (=> no error message frames)
477 - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`)
478 - The socket does not receive its own sent frames (in loopback mode)
485 .. _socketcan-rawfilter:
495 .. code-block:: C
504 .. code-block:: C
514 .. code-block:: C
527 .. code-block:: C
533 having this 'send only' use-case we may remove the receive list in the
539 The CAN filters are processed in per-device filter lists at CAN frame
555 .. code-block:: C
565 .. code-block:: C
580 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
588 .. code-block:: C
600 (see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases
604 .. code-block:: C
616 frames' CAN-ID on this given interface to meet the multi user
622 .. code-block:: C
630 filtering as other CAN frames (see :ref:`socketcan-rawfilter`).
632 .. _socketcan-rawfd:
640 CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT.
646 .. code-block:: C
653 .. code-block:: C
703 applied (see :ref:`socketcan-rawfilter`).
715 -----------------------------------------------
721 such as message contents changes, packet length changes, and do time-out
736 .. code-block:: C
749 at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
755 .. code-block:: C
880 Send reply for RTR-request (placed in op->frames[0]).
904 .. code-block:: C
925 The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP.
931 is activated directly - even without a former CAN frame reception.
934 Throttle the received message rate down to the value of ival2. This
951 .. code-block:: C
953 /* usually used to clear CAN frame data[] - beware of endian problems! */
954 #define U64_DATA(p) (*(unsigned long long*)(p)->data)
983 .. code-block:: C
1001 ----------------------------------------------
1007 --------------------------------------------
1012 .. _socketcan-core-module:
1020 modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`).
1024 --------------------
1026 - **stats_timer**:
1032 - **debug**:
1037 --------------
1039 As described in :ref:`socketcan-receive-lists` the SocketCAN core uses several filter
1057 rcvlist_all - list for unfiltered entries (no filter operations)
1058 rcvlist_eff - list for single extended frame (EFF) entries
1059 rcvlist_err - list for error message frames masks
1060 rcvlist_fil - list for mask/value filters
1061 rcvlist_inv - list for mask/value filters (inverse semantic)
1062 rcvlist_sff - list for single standard frame (SFF) entries
1066 stats - SocketCAN core statistics (rx/tx frames, match ratios, ...)
1067 reset_stats - manual statistic reset
1068 version - prints SocketCAN core and ABI version (removed in Linux 5.10)
1072 --------------------------------
1082 can_rx_register - subscribe CAN frames from a specific interface
1083 can_rx_unregister - unsubscribe CAN frames from a specific interface
1084 can_send - transmit a CAN frame (optional with local loopback)
1097 - TX: Put the CAN frame from the socket buffer to the CAN controller.
1098 - RX: Put the CAN frame from the CAN controller to the socket buffer.
1105 ----------------
1107 .. code-block:: C
1109 dev->type = ARPHRD_CAN; /* the netdevice hardware type */
1110 dev->flags = IFF_NOARP; /* CAN has no arp */
1112 dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> Classical CAN interface */
1115 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
1121 .. _socketcan-local-loopback2:
1124 -----------------------------
1126 As described in :ref:`socketcan-local-loopback1` the CAN network device driver should
1132 dev->flags = (IFF_NOARP | IFF_ECHO);
1136 -------------------------------
1141 controller and have to be identified as not feasible in a multi-user
1143 hardware filters could make sense in a very dedicated use-case, as a
1144 filter on driver level would affect all users in the multi-user
1154 --------------------------------
1163 $ ip -details link show can0
1175 To enable termination resistor support to a can-controller, either
1176 implement in the controller's struct can-priv::
1183 Documentation/devicetree/bindings/net/can/can-controller.yaml
1187 -----------------------------
1192 - a unique CAN Identifier (CAN ID)
1193 - the CAN bus this CAN ID is transmitted on (e.g. can0)
1206 - Create a virtual CAN network interface:
1209 - Create a virtual CAN network interface with a specific name 'vcan42':
1212 - Remove a (virtual CAN) network interface 'vcan42':
1217 ---------------------------------------
1221 configure the CAN device, like setting the bit-timing parameters, via
1227 understand how to use them. The name of the module is can-dev.ko.
1243 [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
1244 [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
1245 phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
1247 [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
1248 [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
1249 dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
1252 [ listen-only { on | off } ]
1253 [ triple-sampling { on | off } ]
1254 [ one-shot { on | off } ]
1255 [ berr-reporting { on | off } ]
1257 [ fd-non-iso { on | off } ]
1258 [ presume-ack { on | off } ]
1259 [ cc-len8-dlc { on | off } ]
1261 [ restart-ms TIME-MS ]
1265 SAMPLE-POINT := { 0.000..0.999 }
1267 PROP-SEG := { 1..8 }
1268 PHASE-SEG1 := { 1..8 }
1269 PHASE-SEG2 := { 1..8 }
1271 RESTART-MS := { 0 | NUMBER }
1275 $ ip -details -statistics link show can0
1278 can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
1280 tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
1281 sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1283 re-started bus-errors arbit-lost error-warn error-pass bus-off
1285 RX: bytes packets errors dropped overrun mcast
1292 "<TRIPLE-SAMPLING>"
1294 LISTEN-ONLY, or TRIPLE-SAMPLING.
1296 "state ERROR-ACTIVE"
1297 The current state of the CAN controller: "ERROR-ACTIVE",
1298 "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED"
1300 "restart-ms 100"
1301 Automatic restart delay time. If set to a non-zero value, a
1303 in case of a bus-off condition after the specified delay time
1306 "bitrate 125000 sample-point 0.875"
1307 Shows the real bit-rate in bits/sec and the sample-point in the
1308 range 0.000..0.999. If the calculation of bit-timing parameters
1310 bit-timing can be defined by setting the "bitrate" argument.
1311 Optionally the "sample-point" can be specified. By default it's
1312 0.000 assuming CIA-recommended sample-points.
1314 "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1"
1317 tq. They allow to define the CAN bit-timing in a hardware
1321 "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000"
1322 Shows the bit-timing constants of the CAN controller, here the
1325 bitrate pre-scaler and the CAN system clock frequency in Hz.
1326 These constants could be used for user-defined (non-standard)
1327 bit-timing calculation algorithms in user-space.
1329 "re-started bus-errors arbit-lost error-warn error-pass bus-off"
1331 and the state changes to the error-warning, error-passive and
1332 bus-off state. RX overrun errors are listed in the "overrun"
1335 Setting the CAN Bit-Timing
1338 The CAN bit-timing parameters can always be defined in a hardware
1343 $ ip link set canX type can tq 125 prop-seg 6 \
1344 phase-seg1 7 phase-seg2 2 sjw 1
1347 recommended CAN bit-timing parameters will be calculated if the bit-
1353 standard bit-rates but may *fail* for exotic bit-rates or CAN system
1355 space and allows user-space tools to solely determine and set the
1356 bit-timing parameters. The CAN controller specific bit-timing
1360 $ ip -details link show can0
1362 sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1370 you *must* define proper bit-timing parameters for real CAN devices
1371 before you can start it to avoid error-prone default settings::
1375 A device may enter the "bus-off" state if too many errors occurred on
1377 bus-off recovery can be enabled by setting the "restart-ms" to a
1378 non-zero value, e.g.::
1380 $ ip link set canX type can restart-ms 100
1382 Alternatively, the application may realize the "bus-off" condition
1389 also :ref:`socketcan-network-problem-notifications`).
1392 .. _socketcan-can-fd-driver:
1395 ------------------------------------------
1406 CAN frames anyway. The payload length to the bus-relevant DLC mapping is
1424 dsample-point, dsjw or dtq and similar settings. When a data bitrate is set
1433 - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
1434 - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
1439 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c)
1440 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
1442 The current ISO/non-ISO mode is announced by the CAN controller driver via
1443 netlink and displayed by the 'ip' tool (controller option FD-NON-ISO).
1444 The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
1449 $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
1450 dbitrate 4000000 dsample-point 0.8 fd on
1451 $ ip -details link show can0
1455 can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1456 bitrate 500000 sample-point 0.750
1457 tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
1459 brp-inc 1
1460 dbitrate 4000000 dsample-point 0.800
1461 dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
1463 dbrp-inc 1
1466 Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
1468 can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1472 ----------------------
1476 (see :ref:`socketcan-resources`) there might be further drivers available, also for
1480 .. _socketcan-resources:
1492 - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
1493 - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
1494 - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
1495 - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver inter…
1496 - Robert Schwebel (design reviews, PTXdist integration)
1497 - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
1498 - Benedikt Spranger (reviews)
1499 - Thomas Gleixner (LKML reviews, coding style, posting hints)
1500 - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
1501 - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
1502 - Klaus Hitschler (PEAK driver integration)
1503 - Uwe Koppe (CAN netdevices with PF_PACKET approach)
1504 - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
1505 - Pavel Pisa (Bit-timing calculation)
1506 - Sascha Hauer (SJA1000 platform driver)
1507 - Sebastian Haas (SJA1000 EMS PCI driver)
1508 - Markus Plessing (SJA1000 EMS PCI driver)
1509 - Per Dalen (SJA1000 Kvaser PCI driver)
1510 - Sam Ravnborg (reviews, coding style, kbuild help)