Documentation/networking/can.txt

5 Readme file for the Controller Area Network Protocol Family (aka Socket CAN)
9   1 Overview / What is Socket CAN
11   2 Motivation / Why using the socket API
13   3 Socket CAN concept
19   4 How to use Socket CAN
21       4.1.1 RAW socket option CAN_RAW_FILTER
22       4.1.2 RAW socket option CAN_RAW_ERR_FILTER
23       4.1.3 RAW socket option CAN_RAW_LOOPBACK
24       4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
25       4.1.5 RAW socket returned message flags
30   5 Socket CAN core module
46   7 Socket CAN resources
52 1. Overview / What is Socket CAN
59 for Linux based on character devices, Socket CAN uses the Berkeley
60 socket API, the Linux network stack and implements the CAN device
61 drivers as network interfaces.  The CAN socket API has been designed
66 2. Motivation / Why using the socket API
69 There have been CAN implementations for Linux before Socket CAN so the
84 Socket CAN was designed to overcome all of these limitations.  A new
85 protocol family has been implemented which provides a socket interface
102 selects that protocol when opening the socket, and then can read and
111   socket(2) and using bind(2) to select a CAN interface and CAN ID, an
141   Socket CAN does.
146 3. Socket CAN concept
149   As described in chapter 2 it is the main goal of Socket CAN to
150   provide a socket interface to user space applications which builds
163   CAN-IDs from the same CAN network interface. The Socket CAN core
166   application opens a CAN RAW socket, the raw protocol module itself
167   requests the (range of) CAN-IDs from the Socket CAN core that are
207   separate socket. See sockopts from the CAN RAW sockets in chapter 4.1.
246 4. How to use Socket CAN
249   Like TCP/IP, you first need to open a socket for communicating over a
250   CAN network. Since Socket CAN implements a new protocol family, you
251   need to pass PF_CAN as the first argument to the socket(2) system
253   socket protocol and the broadcast manager (BCM). So to open a socket,
256     s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
260     s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
262   respectively.  After the successful creation of the socket, you would
263   normally use the bind(2) system call to bind the socket to a CAN
266   the socket, you can read(2) and write(2) from/to the socket or use
268   on the socket as usual. There are also CAN specific socket options
283   default. A read(2) system call on a CAN_RAW socket transfers a
287   PF_PACKET socket, that also binds to a specific interface:
307     s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
319   To bind a socket to all(!) CAN interfaces the interface index must
320   be 0 (zero). In this case the socket receives CAN frames from every
323   on a socket that is bound to 'any' interface sendto(2) is needed to
326   Reading CAN frames from a bound CAN_RAW socket (see above) consists
334             perror("can raw socket read");
383   defaults are set at RAW socket binding time:
386   - The socket only receives valid data frames (=> no error frames)
388   - The socket does not receive its own sent frames (in loopback mode)
390   These default settings may be changed before or after binding the socket.
391   To use the referenced definitions of the socket options for CAN_RAW
394   4.1.1 RAW socket option CAN_RAW_FILTER
397   by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
414   receive filters for each open socket separately:
425   To disable the reception of CAN frames on the selected CAN_RAW socket:
430   data causes the raw socket to discard the received CAN frames. But
434   4.1.2 RAW socket option CAN_RAW_ERR_FILTER
449   4.1.3 RAW socket option CAN_RAW_LOOPBACK
454   functionality can be disabled (separately for each socket):
460   4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
465   needs. The reception of the CAN frames on the same socket that was
475   4.1.5 RAW socket returned message flags
481     MSG_CONFIRM: set when the frame was sent via the socket it is received on.
491 5. Socket CAN core module
494   The Socket CAN core module implements the protocol family
501   - stats_timer: To calculate the Socket CAN core statistics
510   As described in chapter 3.1 the Socket CAN core uses several filter
537     stats       - Socket CAN core statistics (rx/tx frames, match ratios, ...)
539     version     - prints the Socket CAN core version and the ABI version
545   The prototypes and definitions to use the Socket CAN core can be
565   - TX: Put the CAN frame from the socket buffer to the CAN controller.
566   - RX: Put the CAN frame from the CAN controller to the socket buffer.
578   The struct can_frame is the payload of each socket buffer in the
601   to set different multiple filters for each socket separately.
798   list of the support CAN hardware. On the Socket CAN project website
802 7. Socket CAN resources
805   You can find further resources for Socket CAN like user space tools,
807   at the BerliOS OSS project website for Socket CAN:
818   Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
819   Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
820   Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews,