Lines Matching +full:len +full:- +full:or +full:- +full:define
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
49 that any number of transport protocols can be loaded or unloaded
53 on different or the same protocol module and they can listen/send
54 frames on different or the same CAN IDs. Several sockets listening on
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
80 computer, a SCSI or IDE controller providing access to your hard
81 disk or tape streamer device. Instead, you have abstraction layers
82 which provide a unified character or block device interface to the
83 application on the one hand, and a interface for hardware-specific
85 by subsystems like the tty layer, the audio subsystem or the SCSI
95 it would be no more difficult, or may be even easier, to use the
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 -----------------------------
146 applications may run on the same or different nodes without any
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`.
179 tools like 'candump' or 'cansniffer' on the (same) node.
182 .. _socketcan-network-problem-notifications:
185 -----------------------------
197 or the MAC layer is detected (e.g. by the CAN controller) the driver
225 - see :ref:`socketcan-concept`). After binding (CAN_RAW) or connecting (CAN_BCM)
226 the socket, you can read(2) and write(2) from/to the socket or use
234 .. code-block:: C
243 __u8 len;
252 Remark: The len element contains the payload length in bytes and should be
258 element can contain values 9 .. 15 when the len element is 8 (the real
259 payload length for all DLC values greater or equal to 8).
262 allows the user to define their own structs and unions to easily access
270 .. code-block:: C
303 .. code-block:: C
331 .. code-block:: C
358 .. code-block:: C
362 socklen_t len = sizeof(addr);
366 0, (struct sockaddr*)&addr, &len);
376 .. code-block:: C
389 .. code-block:: C
407 and Classical CAN frames simultaneously (see :ref:`socketcan-rawfd`).
411 .. code-block:: C
415 __u8 len; /* frame payload length in byte (0 .. 64) */
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
432 contains a plain length value from 0 .. 64. So both canfd_frame.len and
433 can_frame.len are equal and contain a length information and no DLC.
435 the mapping to the bus-relevant data length code (DLC), see :ref:`socketcan-can-fd-driver`.
437 The length of the two CAN(FD) frame structures define the maximum transfer
441 .. code-block:: C
443 #define CAN_MTU (sizeof(struct can_frame)) == 16 => Classical CAN frame
444 #define CANFD_MTU (sizeof(struct canfd_frame)) == 72 => CAN FD frame
448 ----------------------
450 When using the system call recvmsg(2) on a RAW or a BCM socket, the
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)
480 These default settings may be changed before or after binding the socket.
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
550 CAN_SFF_MASK or CAN_EFF_MASK have to be set into can_filter.mask together
552 can_filter.mask makes clear that it matters whether a SFF or EFF CAN ID is
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
662 printf("got CAN FD frame with length %d\n", cfd.len);
665 printf("got Classical CAN frame with length %d\n", cfd.len);
674 printf("can_id: %X data length: %d data: ", cfd.can_id, cfd.len);
675 for (i = 0; i < cfd.len; i++)
690 or CAN FD frames and can process them the same way.
702 are indenpendent from each other which leads to logical OR'ed filters when
703 applied (see :ref:`socketcan-rawfilter`).
710 where the CAN_INV_FILTER flag is set in order to notch single CAN IDs or
715 -----------------------------------------------
721 such as message contents changes, packet length changes, and do time-out
724 Periodic transmission tasks of CAN frames or a sequence of CAN frames can be
733 message header with a command ('opcode') followed by zero or more CAN frames.
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
774 transmissions or receive filters concurrently. The different RX/TX jobs are
788 or details the broadcast managers response to several events, including
835 Sent on first message received or on receipt of revised CAN messages.
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.
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)
1086 For details see the kerneldoc documentation in net/can/af_can.c or
1087 the source code of net/can/raw.c or net/can/bcm.c .
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 */
1114 or alternative, when the controller supports CAN with flexible data rate:
1115 dev->mtu = CANFD_MTU; /* sizeof(struct canfd_frame) -> CAN FD interface */
1117 The struct can_frame or struct canfd_frame is the payload of each socket
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 -------------------------------
1139 controllers support the filtering of CAN IDs or ranges of CAN IDs.
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::
1182 or add gpio control with the device tree entries from
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
1226 should use. Please have a look to the SJA1000 or MSCAN driver to
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
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
1368 A CAN network device is started or stopped as usual with the command
1369 "ifconfig canX up/down" or "ip link set canX up/down". Be aware that
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
1376 the CAN bus. Then no more messages are received or sent. An automatic
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 ------------------------------------------
1402 payload. The representation of this length in can_frame.len and
1403 canfd_frame.len for userspace applications and inside the Linux network
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)