Lines Matching +full:multi +full:- +full:socket
2 SocketCAN - Controller Area Network
13 socket API, the Linux network stack and implements the CAN device
14 drivers as network interfaces. The CAN socket API has been designed
20 .. _socketcan-motivation:
22 Motivation / Why Using the Socket API
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
41 protocol family has been implemented which provides a socket interface
47 protocol family module and also vice-versa. Also, the protocol family
57 communicate using a specific transport protocol, e.g. ISO-TP, just
58 selects that protocol when opening the socket, and then can read and
60 CAN-IDs, frames, etc.
62 Similar functionality visible from user-space could be provided by a
67 socket(2) and using bind(2) to select a CAN interface and CAN ID, an
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
109 provide a socket interface to user space applications which builds
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
129 application opens a CAN RAW socket, the raw protocol module itself
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 -----------------------------
209 Like TCP/IP, you first need to open a socket for communicating over a
211 need to pass PF_CAN as the first argument to the socket(2) system
213 socket protocol and the broadcast manager (BCM). So to open a socket,
216 s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
220 s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
222 respectively. After the successful creation of the socket, you would
223 normally use the bind(2) system call to bind the socket to a CAN
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
228 on the socket as usual. There are also CAN specific socket options
234 .. code-block:: C
248 default. A read(2) system call on a CAN_RAW socket transfers a
252 PF_PACKET socket, that also binds to a specific interface:
254 .. code-block:: C
270 .. code-block:: C
276 s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
288 To bind a socket to all(!) CAN interfaces the interface index must
289 be 0 (zero). In this case the socket receives CAN frames from every
292 on a socket that is bound to 'any' interface sendto(2) is needed to
295 Reading CAN frames from a bound CAN_RAW socket (see above) consists
298 .. code-block:: C
305 perror("can raw socket read");
325 .. code-block:: C
343 .. code-block:: C
354 a message from the socket:
356 .. code-block:: C
371 bytes of payload (struct can_frame) like the CAN_RAW socket. Therefore e.g.
372 the CAN_RAW socket supports a new socket option CAN_RAW_FD_FRAMES that
373 switches the socket into a mode that allows the handling of CAN FD frames
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 ------------------------------------------------
421 provided by the multi user SocketCAN approach, some reasonable
422 defaults are set at RAW socket binding time:
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)
429 These default settings may be changed before or after binding the socket.
430 To use the referenced definitions of the socket options for CAN_RAW
434 .. _socketcan-rawfilter:
436 RAW socket option CAN_RAW_FILTER
440 by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
444 .. code-block:: C
453 .. code-block:: C
461 receive filters for each open socket separately:
463 .. code-block:: C
474 To disable the reception of CAN frames on the selected CAN_RAW socket:
476 .. code-block:: C
481 data causes the raw socket to discard the received CAN frames. But
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
526 RAW Socket Option CAN_RAW_ERR_FILTER
529 As described in :ref:`socketcan-network-problem-notifications` the CAN interface driver can generat…
537 .. code-block:: C
545 RAW Socket Option CAN_RAW_LOOPBACK
548 To meet multi user needs the local loopback is enabled by default
549 (see :ref:`socketcan-local-loopback1` for details). But in some embedded use-cases
551 functionality can be disabled (separately for each socket):
553 .. code-block:: C
560 RAW socket option CAN_RAW_RECV_OWN_MSGS
565 frames' CAN-ID on this given interface to meet the multi user
566 needs. The reception of the CAN frames on the same socket that was
571 .. code-block:: C
579 .. _socketcan-rawfd:
581 RAW Socket Option CAN_RAW_FD_FRAMES
584 CAN FD support in CAN_RAW sockets can be enabled with a new socket option
585 CAN_RAW_FD_FRAMES which is off by default. When the new socket option is
586 not supported by the CAN_RAW socket (e.g. on older kernels), switching the
587 CAN_RAW_FD_FRAMES option returns the error -ENOPROTOOPT.
591 when reading from the socket:
593 .. code-block:: C
600 .. code-block:: C
626 been received from the socket a legacy CAN frame has been read into the
636 socket option returns an error: No problem. You'll get legacy CAN frames
644 RAW socket option CAN_RAW_JOIN_FILTERS
647 The CAN_RAW socket can set multiple CAN identifier specific filters that
650 applied (see :ref:`socketcan-rawfilter`).
652 This socket option joines the given CAN filters in the way that only CAN
661 RAW Socket Returned Message Flags
664 When using recvmsg() call, the msg->msg_flags may contain following flags:
670 set when the frame was sent via the socket it is received on.
673 :ref:`socketcan-local-loopback1` and :ref:`socketcan-local-loopback2`.
678 -----------------------------------------------
684 such as message contents changes, packet length changes, and do time-out
691 A BCM socket is not intended for sending individual CAN frames using the
692 struct can_frame as known from the CAN_RAW socket. Instead a special BCM
699 .. code-block:: C
712 at the beginning of :ref:`socketcan-rawfd` and in the include/linux/can.h include. All
715 Note a CAN_BCM socket must be connected instead of bound after socket
718 .. code-block:: C
724 s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
736 The broadcast manager socket is able to handle any number of in flight
740 When the broadcast manager socket is bound to 'any' CAN interface (=> the
744 socket messages the originating CAN interface is provided in can_ifindex.
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.
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 */
1078 The struct can_frame or struct canfd_frame is the payload of each socket
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
1107 to set different multiple filters for each socket separately.
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
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)