Lines Matching +full:rx +full:- +full:sample +full:- +full:delay +full:- +full:ns
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
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
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
537 .. code-block:: C
547 .. code-block:: C
562 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
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
685 applied (see :ref:`socketcan-rawfilter`).
699 When using recvmsg() call, the msg->msg_flags may contain following flags:
708 :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`.
713 -----------------------------------------------
718 Receive filters can be used to down sample frequent messages; detect events
719 such as message contents changes, packet length changes, and do time-out
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
772 transmissions or receive filters concurrently. The different RX/TX jobs are
815 Create RX content filter subscription.
818 Remove RX content filter subscription, requires only can_id.
821 Read properties of RX content filter subscription for can_id.
878 Send reply for RTR-request (placed in op->frames[0]).
902 .. code-block:: C
923 The timer values ival1 or ival2 may be set to non-zero values at RX_SETUP.
929 is activated directly - even without a former CAN frame reception.
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.
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
1250 RX: bytes packets errors dropped overrun mcast
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"
1280 Shows the time quanta in ns, propagation segment, phase buffer
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
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
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)