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-loopback1` 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
254 .. code-block:: C
270 .. code-block:: C
298 .. code-block:: C
325 .. code-block:: C
343 .. code-block:: C
356 .. code-block:: C
374 and (legacy) CAN frames simultaneously (see :ref:`socketcan-rawfd`).
378 .. code-block:: C
393 all structure elements can be used as-is - only the data[] becomes extended.
402 the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`.
408 .. code-block:: C
414 .. _socketcan-raw-sockets:
417 ------------------------------------------------
424 - The filters are set to exactly one filter receiving everything
425 - The socket only receives valid data frames (=> no error message frames)
426 - The loopback of sent CAN frames is enabled (see :ref:`socketcan-local-loopback2`)
427 - The socket does not receive its own sent frames (in loopback mode)
434 .. _socketcan-rawfilter:
444 .. code-block:: C
453 .. code-block:: C
463 .. code-block:: C
476 .. code-block:: C
482 having this 'send only' use-case we may remove the receive list in the
488 The CAN filters are processed in per-device filter lists at CAN frame
504 .. code-block:: C
514 .. code-block:: C
529 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
537 .. code-block:: C
549 (see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases
553 .. code-block:: C
565 frames' CAN-ID on this given interface to meet the multi user
571 .. code-block:: C
579 .. _socketcan-rawfd:
587 CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT.
593 .. code-block:: C
600 .. code-block:: C
650 applied (see :ref:`socketcan-rawfilter`).
664 When using recvmsg() call, the msg->msg_flags may contain following flags:
673 :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`.
678 -----------------------------------------------
684 such as message contents changes, packet length changes, and do time-out
699 .. code-block:: C
712 at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
718 .. code-block:: C
843 Send reply for RTR-request (placed in op->frames[0]).
865 .. code-block:: C
886 The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP.
892 is activated directly - even without a former CAN frame reception.
895 Throttle the received message rate down to the value of ival2. This
912 .. code-block:: C
914 /* usually used to clear CAN frame data[] - beware of endian problems! */
915 #define U64_DATA(p) (*(unsigned long long*)(p)->data)
944 .. code-block:: C
962 ----------------------------------------------
968 --------------------------------------------
973 .. _socketcan-core-module:
981 modules to subscribe needed CAN IDs (see :ref:`socketcan-receive-lists`).
985 --------------------
987 - **stats_timer**:
993 - **debug**:
998 --------------
1000 As described in :ref:`socketcan-receive-lists` the SocketCAN core uses several filter
1018 rcvlist_all - list for unfiltered entries (no filter operations)
1019 rcvlist_eff - list for single extended frame (EFF) entries
1020 rcvlist_err - list for error message frames masks
1021 rcvlist_fil - list for mask/value filters
1022 rcvlist_inv - list for mask/value filters (inverse semantic)
1023 rcvlist_sff - list for single standard frame (SFF) entries
1027 stats - SocketCAN core statistics (rx/tx frames, match ratios, ...)
1028 reset_stats - manual statistic reset
1029 version - prints the SocketCAN core version and the ABI version
1033 --------------------------------
1043 can_rx_register - subscribe CAN frames from a specific interface
1044 can_rx_unregister - unsubscribe CAN frames from a specific interface
1045 can_send - transmit a CAN frame (optional with local loopback)
1058 - TX: Put the CAN frame from the socket buffer to the CAN controller.
1059 - RX: Put the CAN frame from the CAN controller to the socket buffer.
1066 ----------------
1068 .. code-block:: C
1070 dev->type = ARPHRD_CAN; /* the netdevice hardware type */
1071 dev->flags = IFF_NOARP; /* CAN has no arp */
1073 dev->mtu = CAN_MTU; /* sizeof(struct can_frame) -> legacy CAN interface */
1076 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
1082 .. _socketcan-local-loopback2:
1085 -----------------------------
1087 As described in :ref:`socketcan-local-loopback1` the CAN network device driver should
1093 dev->flags = (IFF_NOARP | IFF_ECHO);
1097 -------------------------------
1102 controller and have to be identified as not feasible in a multi-user
1104 hardware filters could make sense in a very dedicated use-case, as a
1105 filter on driver level would affect all users in the multi-user
1115 -----------------------------
1120 - a unique CAN Identifier (CAN ID)
1121 - the CAN bus this CAN ID is transmitted on (e.g. can0)
1134 - Create a virtual CAN network interface:
1137 - Create a virtual CAN network interface with a specific name 'vcan42':
1140 - Remove a (virtual CAN) network interface 'vcan42':
1145 ---------------------------------------
1149 configure the CAN device, like setting the bit-timing parameters, via
1155 understand how to use them. The name of the module is can-dev.ko.
1171 [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
1172 [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
1173 phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
1175 [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
1176 [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
1177 dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
1180 [ listen-only { on | off } ]
1181 [ triple-sampling { on | off } ]
1182 [ one-shot { on | off } ]
1183 [ berr-reporting { on | off } ]
1185 [ fd-non-iso { on | off } ]
1186 [ presume-ack { on | off } ]
1188 [ restart-ms TIME-MS ]
1192 SAMPLE-POINT := { 0.000..0.999 }
1194 PROP-SEG := { 1..8 }
1195 PHASE-SEG1 := { 1..8 }
1196 PHASE-SEG2 := { 1..8 }
1198 RESTART-MS := { 0 | NUMBER }
1202 $ ip -details -statistics link show can0
1205 can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
1207 tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
1208 sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1210 re-started bus-errors arbit-lost error-warn error-pass bus-off
1212 RX: bytes packets errors dropped overrun mcast
1219 "<TRIPLE-SAMPLING>"
1221 LISTEN-ONLY, or TRIPLE-SAMPLING.
1223 "state ERROR-ACTIVE"
1224 The current state of the CAN controller: "ERROR-ACTIVE",
1225 "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED"
1227 "restart-ms 100"
1228 Automatic restart delay time. If set to a non-zero value, a
1230 in case of a bus-off condition after the specified delay time
1233 "bitrate 125000 sample-point 0.875"
1234 Shows the real bit-rate in bits/sec and the sample-point in the
1235 range 0.000..0.999. If the calculation of bit-timing parameters
1237 bit-timing can be defined by setting the "bitrate" argument.
1238 Optionally the "sample-point" can be specified. By default it's
1239 0.000 assuming CIA-recommended sample-points.
1241 "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1"
1244 tq. They allow to define the CAN bit-timing in a hardware
1248 "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000"
1249 Shows the bit-timing constants of the CAN controller, here the
1252 bitrate pre-scaler and the CAN system clock frequency in Hz.
1253 These constants could be used for user-defined (non-standard)
1254 bit-timing calculation algorithms in user-space.
1256 "re-started bus-errors arbit-lost error-warn error-pass bus-off"
1258 and the state changes to the error-warning, error-passive and
1259 bus-off state. RX overrun errors are listed in the "overrun"
1262 Setting the CAN Bit-Timing
1265 The CAN bit-timing parameters can always be defined in a hardware
1270 $ ip link set canX type can tq 125 prop-seg 6 \
1271 phase-seg1 7 phase-seg2 2 sjw 1
1274 recommended CAN bit-timing parameters will be calculated if the bit-
1280 standard bit-rates but may *fail* for exotic bit-rates or CAN system
1282 space and allows user-space tools to solely determine and set the
1283 bit-timing parameters. The CAN controller specific bit-timing
1287 $ ip -details link show can0
1289 sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1297 you *must* define proper bit-timing parameters for real CAN devices
1298 before you can start it to avoid error-prone default settings::
1302 A device may enter the "bus-off" state if too many errors occurred on
1304 bus-off recovery can be enabled by setting the "restart-ms" to a
1305 non-zero value, e.g.::
1307 $ ip link set canX type can restart-ms 100
1309 Alternatively, the application may realize the "bus-off" condition
1316 also :ref:`socketcan-network-problem-notifications`).
1319 .. _socketcan-can-fd-driver:
1322 ------------------------------------------
1333 CAN frames anyway. The payload length to the bus-relevant DLC mapping is
1351 dsample-point, dsjw or dtq and similar settings. When a data bitrate is set
1360 - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
1361 - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
1366 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c)
1367 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
1369 The current ISO/non-ISO mode is announced by the CAN controller driver via
1370 netlink and displayed by the 'ip' tool (controller option FD-NON-ISO).
1371 The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
1376 $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
1377 dbitrate 4000000 dsample-point 0.8 fd on
1378 $ ip -details link show can0
1382 can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1383 bitrate 500000 sample-point 0.750
1384 tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
1386 brp-inc 1
1387 dbitrate 4000000 dsample-point 0.800
1388 dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
1390 dbrp-inc 1
1393 Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
1395 can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1399 ----------------------
1403 (see :ref:`socketcan-resources`) there might be further drivers available, also for
1407 .. _socketcan-resources:
1419 - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
1420 - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
1421 - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
1422 - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver inter…
1423 - Robert Schwebel (design reviews, PTXdist integration)
1424 - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
1425 - Benedikt Spranger (reviews)
1426 - Thomas Gleixner (LKML reviews, coding style, posting hints)
1427 - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
1428 - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
1429 - Klaus Hitschler (PEAK driver integration)
1430 - Uwe Koppe (CAN netdevices with PF_PACKET approach)
1431 - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
1432 - Pavel Pisa (Bit-timing calculation)
1433 - Sascha Hauer (SJA1000 platform driver)
1434 - Sebastian Haas (SJA1000 EMS PCI driver)
1435 - Markus Plessing (SJA1000 EMS PCI driver)
1436 - Per Dalen (SJA1000 Kvaser PCI driver)
1437 - Sam Ravnborg (reviews, coding style, kbuild help)