Lines Matching +full:echo +full:- +full:active +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
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:
707 CAN driver supports the echo of frames on driver level, see
708 :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`.
713 -----------------------------------------------
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
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
1125 support a local loopback functionality similar to the local echo
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 --------------------------------
1161 $ ip -details link show can0
1173 To enable termination resistor support to a can-controller, either
1174 implement in the controller's struct can-priv::
1181 Documentation/devicetree/bindings/net/can/can-controller.yaml
1185 -----------------------------
1190 - a unique CAN Identifier (CAN ID)
1191 - the CAN bus this CAN ID is transmitted on (e.g. can0)
1204 - Create a virtual CAN network interface:
1207 - Create a virtual CAN network interface with a specific name 'vcan42':
1210 - Remove a (virtual CAN) network interface 'vcan42':
1215 ---------------------------------------
1219 configure the CAN device, like setting the bit-timing parameters, via
1225 understand how to use them. The name of the module is can-dev.ko.
1241 [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
1242 [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
1243 phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
1245 [ dbitrate BITRATE [ dsample-point SAMPLE-POINT] ] |
1246 [ dtq TQ dprop-seg PROP_SEG dphase-seg1 PHASE-SEG1
1247 dphase-seg2 PHASE-SEG2 [ dsjw SJW ] ]
1250 [ listen-only { on | off } ]
1251 [ triple-sampling { on | off } ]
1252 [ one-shot { on | off } ]
1253 [ berr-reporting { on | off } ]
1255 [ fd-non-iso { on | off } ]
1256 [ presume-ack { on | off } ]
1257 [ cc-len8-dlc { on | off } ]
1259 [ restart-ms TIME-MS ]
1263 SAMPLE-POINT := { 0.000..0.999 }
1265 PROP-SEG := { 1..8 }
1266 PHASE-SEG1 := { 1..8 }
1267 PHASE-SEG2 := { 1..8 }
1269 RESTART-MS := { 0 | NUMBER }
1273 $ ip -details -statistics link show can0
1274 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10
1276 can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
1278 tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
1279 sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1281 re-started bus-errors arbit-lost error-warn error-pass bus-off
1290 "<TRIPLE-SAMPLING>"
1292 LISTEN-ONLY, or TRIPLE-SAMPLING.
1294 "state ERROR-ACTIVE"
1295 The current state of the CAN controller: "ERROR-ACTIVE",
1296 "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED"
1298 "restart-ms 100"
1299 Automatic restart delay time. If set to a non-zero value, a
1301 in case of a bus-off condition after the specified delay time
1304 "bitrate 125000 sample-point 0.875"
1305 Shows the real bit-rate in bits/sec and the sample-point in the
1306 range 0.000..0.999. If the calculation of bit-timing parameters
1308 bit-timing can be defined by setting the "bitrate" argument.
1309 Optionally the "sample-point" can be specified. By default it's
1310 0.000 assuming CIA-recommended sample-points.
1312 "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1"
1315 tq. They allow to define the CAN bit-timing in a hardware
1319 "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 clock 8000000"
1320 Shows the bit-timing constants of the CAN controller, here the
1323 bitrate pre-scaler and the CAN system clock frequency in Hz.
1324 These constants could be used for user-defined (non-standard)
1325 bit-timing calculation algorithms in user-space.
1327 "re-started bus-errors arbit-lost error-warn error-pass bus-off"
1329 and the state changes to the error-warning, error-passive and
1330 bus-off state. RX overrun errors are listed in the "overrun"
1333 Setting the CAN Bit-Timing
1336 The CAN bit-timing parameters can always be defined in a hardware
1341 $ ip link set canX type can tq 125 prop-seg 6 \
1342 phase-seg1 7 phase-seg2 2 sjw 1
1345 recommended CAN bit-timing parameters will be calculated if the bit-
1351 standard bit-rates but may *fail* for exotic bit-rates or CAN system
1353 space and allows user-space tools to solely determine and set the
1354 bit-timing parameters. The CAN controller specific bit-timing
1358 $ ip -details link show can0
1360 sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
1368 you *must* define proper bit-timing parameters for real CAN devices
1369 before you can start it to avoid error-prone default settings::
1373 A device may enter the "bus-off" state if too many errors occurred on
1375 bus-off recovery can be enabled by setting the "restart-ms" to a
1376 non-zero value, e.g.::
1378 $ ip link set canX type can restart-ms 100
1380 Alternatively, the application may realize the "bus-off" condition
1387 also :ref:`socketcan-network-problem-notifications`).
1390 .. _socketcan-can-fd-driver:
1393 ------------------------------------------
1404 CAN frames anyway. The payload length to the bus-relevant DLC mapping is
1422 dsample-point, dsjw or dtq and similar settings. When a data bitrate is set
1431 - ISO compliant: The ISO 11898-1:2015 CAN FD implementation (default)
1432 - non-ISO compliant: The CAN FD implementation following the 2012 whitepaper
1437 2. non-ISO compliant (fixed, like the M_CAN IP core v3.0.1 in m_can.c)
1438 3. ISO/non-ISO CAN FD controllers (switchable, like the PEAK PCAN-USB FD)
1440 The current ISO/non-ISO mode is announced by the CAN controller driver via
1441 netlink and displayed by the 'ip' tool (controller option FD-NON-ISO).
1442 The ISO/non-ISO-mode can be altered by setting 'fd-non-iso {on|off}' for
1447 $ ip link set can0 up type can bitrate 500000 sample-point 0.75 \
1448 dbitrate 4000000 dsample-point 0.8 fd on
1449 $ ip -details link show can0
1450 5: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 72 qdisc pfifo_fast state UNKNOWN \
1453 can <FD> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1454 bitrate 500000 sample-point 0.750
1455 tq 50 prop-seg 14 phase-seg1 15 phase-seg2 10 sjw 1
1457 brp-inc 1
1458 dbitrate 4000000 dsample-point 0.800
1459 dtq 12 dprop-seg 7 dphase-seg1 8 dphase-seg2 4 dsjw 1
1461 dbrp-inc 1
1464 Example when 'fd-non-iso on' is added on this switchable CAN FD adapter::
1466 can <FD,FD-NON-ISO> state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0
1470 ----------------------
1474 (see :ref:`socketcan-resources`) there might be further drivers available, also for
1478 .. _socketcan-resources:
1490 - Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
1491 - Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
1492 - Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
1493 - Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews, CAN device driver inter…
1494 - Robert Schwebel (design reviews, PTXdist integration)
1495 - Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
1496 - Benedikt Spranger (reviews)
1497 - Thomas Gleixner (LKML reviews, coding style, posting hints)
1498 - Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
1499 - Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
1500 - Klaus Hitschler (PEAK driver integration)
1501 - Uwe Koppe (CAN netdevices with PF_PACKET approach)
1502 - Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
1503 - Pavel Pisa (Bit-timing calculation)
1504 - Sascha Hauer (SJA1000 platform driver)
1505 - Sebastian Haas (SJA1000 EMS PCI driver)
1506 - Markus Plessing (SJA1000 EMS PCI driver)
1507 - Per Dalen (SJA1000 Kvaser PCI driver)
1508 - Sam Ravnborg (reviews, coding style, kbuild help)