On Mon, 17 Sep 2007 12:03:28 +0200 Urs Thuermann wrote: Hi, Thanks for all of this informative documentation.
I have some typo/spello corrections below. > This patch adds documentation for the PF_CAN protocol family. > > Signed-off-by: Oliver Hartkopp <[EMAIL PROTECTED]> > Signed-off-by: Urs Thuermann <[EMAIL PROTECTED]> > > --- > Documentation/networking/00-INDEX | 2 > Documentation/networking/can.txt | 635 > ++++++++++++++++++++++++++++++++++++++ > 2 files changed, 637 insertions(+) > > Index: net-2.6.24/Documentation/networking/can.txt > =================================================================== > --- /dev/null 1970-01-01 00:00:00.000000000 +0000 > +++ net-2.6.24/Documentation/networking/can.txt 2007-09-17 > 10:27:25.000000000 +0200 > @@ -0,0 +1,635 @@ > +============================================================================ > + > +1. Overview / What is Socket CAN > +-------------------------------- > + > +The socketcan package is an implementation of CAN protocols > +(Controller Area Network) for Linux. CAN is a networking technology > +which has wide-spread use in automation, embedded devices, and widespread > +automotive fields. While there have been other CAN implementations > +for Linux based on character devices, Socket CAN uses the Berkeley > +socket API, the Linux network stack and implements the CAN device > +drivers as network interfaces. The CAN socket API has been designed > +as similar as possible to the TCP/IP protocols to allow programmers, > +familiar with network programming, to easily learn how to use CAN > +sockets. > + > +2. Motivation / Why using the socket API > +---------------------------------------- > + > +Socket CAN was designed to overcome all of these limitations. A new > +protocol family has been implemented which provides a socket interface > +to user space applications and which builds upon the Linux network > +layer, so to use all of the provided queueing functionality. Device > +drivers for CAN controller hardware register itself with the Linux A device driver ... registers itself > +network layer as a network device, so that CAN frames from the > +controller can be passed up to the network layer and on to the CAN > +protocol family module and also vice-versa. Also, the protocol family > +module provides an API for transport protocol modules to register, so > +that any number of transport protocols can be loaded or unloaded > +dynamically. In fact, the can core module alone does not provide any > +protocol and can not be used without loading at least one additional cannot > +protocol module. Multiple sockets can be opened at the same time, > +on different or the same protocol module and they can listen/send > +frames on different or the same CAN IDs. Several sockets listening on > +the same interface for frames with the same CAN ID are all passed the > +same received matching CAN frames. An application wishing to > +communicate using a specific transport protocol, e.g. ISO-TP, just > +selects that protocol when opening the socket, and then can read and > +write application data byte streams, without having to deal with > +CAN-IDs, frames, etc. > + > +Similar functionality visible from user-space could be provided by a > +character decive, too, but this would lead to a technically inelegant > +solution for a couple of reasons: > + > +* Intricate usage. Instead of passing a protocol argument to > + socket(2) and using bind(2) to select a CAN interface and CAN ID, an > + application would have to do all these operations using ioctl(2)s. > + > +* Code duplication. A character device cannot make use of the Linux > + network queueing code, so all that code would have to be duplicated > + for CAN networking. > + > +* Abstraction. In most existing character-device implementations, the > + hardware-specific device driver for a CAN controller directly > + provides the character device for the application to work with. > + This is at least very unusual in Unix systems, for both, char and ^drop comma > + block devices. For example you don't have a character device for a > + certain UART of a serial interface, a certain sound chip in your > + computer, a SCSI or IDE controller providing access to your hard > + disk or tape streamer device. Instead, you have abstraction layers > + which provide a unified character or block device interface to the > + application on the one hand, and a interface for hardware-specific > + device drivers on the other hand. These abstractions are provided > + by subsystems like the tty layer, the audio subsystem or the SCSI > + and IDE subsystems for the devices mentioned above. > + > + The easiest way to implement a CAN device driver is as a character > + without such a (complete) abstraction layer, as is done by most > + existing drivers. The right way, however, would be to add such a > + layer with all the functionality like registering for certain CAN > + IDs, supporting several open file descriptors and (de)multplexing (de)multiplexing > + CAN frames between them, (sophisticated) queueing of CAN frames, and > + providing an API for device driver to register with. However, then drivers > + it would be no more difficult, or may be even easier, to use the > + networking framework provided by the Linux kernel, and this is what > + Socket CAN does. > + > + The use of the networking framework of the Linux kernel is just the > + natural and most appropriate way to implement CAN for Linux. > + > +3. Socket CAN concept > +--------------------- > + > + As described in chapter 2 it is the main goal of Socket CAN to > + provide a socket interface to user space applications which builds > + upon the Linux networklayer. In opposite to the commonly known network layer. In constrast to > + TCP/IP and ethernet networking the CAN bus is a broadcast-only(!) ^insert comma > + medium that has no MAC-layer adressing like ethernet. The CAN-identifier addressing > + (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs > + have to be choosen unique on the bus. When designing a CAN-ECU chosen uniquely > + network the CAN-IDs are mapped to be sent by a specific ECU. > + For this reason a CAN-ID can be treatened best as a kind of source address. treated > + > + 3.1 receive lists > + > + The network transparent access of multiple applications leads to the > + problem that different applications may be interrested in the same interested > + CAN-IDs from the same CAN network interface. The Socket CAN core > + module - which implements the protocol family CAN - provides several > + high efficient receive lists for this reason. If e.g. a user space > + application opens a CAN RAW socket, the raw protocol module itself > + requests the (range of) CAN-IDs from the Socket CAN core that are > + requested by the user. The subscription and unsubscription of > + CAN-IDs can be done for specific CAN interfaces or for all(!) known > + CAN interfaces with the can_rx_(un)register() functions provided to > + CAN protocol modules by the SocketCAN core (see chapter 5). > + To optimize the CPU usage at runtime the receive lists are split up > + into several specific lists per device that match the requested > + filter complexity for a given use-case. > + > + 3.2 loopback > + > + As known from other networking concepts the data exchanging > + applications may run on the same or different nodes without any > + change (except if the according addressing information): except for > + > + ___ ___ ___ _______ ___ > + | _ | | _ | | _ | | _ _ | | _ | > + ||A|| ||B|| ||C|| ||A| |B|| ||C|| > + |___| |___| |___| |_______| |___| > + | | | | | > + -----------------(1)- CAN bus -(2)--------------- > + > + To ensure that application A receives the same information in the > + expample (2) as it would receive in example (1) there is need for example > + some kind of local loopback on the appropriate node. > + > + The Linux network devices (by default) just can handle the > + transmission and receiption of media dependend frames. Due to the reception of media dependent > + arbritration on the CAN bus the transmission of a low prio CAN-ID > + may be delayed from the receipition of a high prio CAN frame. To by reception > + reflect the correct* traffic on the node the loopback of the sent > + data has to be performed right after a successful transmission. If > + the CAN network interface is not capable to perform the loopback for of performing > + some reason the SocketCAN core can do this task as a fallback solution. > + See chapter 6.2 for details (recommended). > + > + The loopback functionality is enabled by default to reflect standard > + networking behaviour for CAN applications. Due to some requests from > + the RT-SocketCAN group the loopback optionally may be disabled for each > + seperate socket. See sockopts from the CAN RAW sockets in chapter 4.1 . separate 4.1. > + > + * = you really like to have this when you're running analyser tools > + like 'candump' or 'cansniffer' on the (same) node. > + > + 3.3 network security issues (capabilities) > + > + The Controller Area Network is a local field bus transmitting only > + broadcast messages without any routing and security concepts. > + In the majority of cases the user application has to deal with > + raw CAN frames. Therefore it might be reasonable NOT to restrict > + the CAN access only to the user root, as known from other networks. > + Since the currently implemented CAN_RAW and CAN_BCM sockets can only > + send and receive frames to/from CAN interfaces it does not affect > + security of others networks to allow all users to access the CAN. > + To enable non-root users to access CAN_RAW and CAN_BCM protocol > + sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be > + selected at kernel compile time. > + > + 3.4 network problem notifications > + > + The use of the CAN bus may lead to several problems on the physical > + and media access control layer. Detecting and logging of these lower > + layer problems is a vital requirement for CAN users to identify > + hardware issues on the physical transceiver layer as well as > + arbitration problems and error frames caused by the different > + ECUs. The occurance of detected errors are important for diagnosis occurrence > + and have to be logged together with the exact timestamp. For this > + reason the CAN interface driver can generate so called Error Frames > + that can optionally be passed to the user application on the same in > + way like other CAN frames. Whenever an error on the physical layer as > + or the MAC layer is detected (e.g. by the CAN controller) the driver > + creates an appropriate error frame. Error frames can be requested by > + the user application using the common CAN filter mechanisms. Inside > + this filter definition the (interrested) type of errors may be (interested) > + selected. The receiption of error frames is disabled by default. reception > + > +4. How to use Socket CAN > +------------------------ > + > + Like TCP/IP, you first need to open a socket for communicating over a > + CAN network. Since Socket CAN implements a new protocol family, you > + need to pass PF_CAN as the first argument to the socket(2) system > + call. Currently, there are two CAN protocols to choose from, the raw > + socket protocol and the broadcast manager (BCM). So to open a socket, > + you would write > + > + s = socket(PF_CAN, SOCK_RAW, CAN_RAW); > + > + and > + > + s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM); > + > + respectively. After the successful creation of the socket, you would > + normally use the bind(2) system call to bind the socket to a CAN > + interface (which is different to TCP/IP due to different addressing from > + - see chapter 3). After binding (CAN_RAW) or connecting (CAN_BCM) > + the socket, you can read(2) and write(2) from/to the socket or use > + send(2), sendto(2), sendmsg(2) and the recv* counterpart operations > + on the socket as usual. There are also CAN specific socket options > + described below. > + > + The basic CAN frame structure and the sockaddr structure are defined > + in include/linux/can.h: > + > + struct can_frame { > + canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */ > + __u8 can_dlc; /* data length code: 0 .. 8 */ > + __u8 data[8] __attribute__((aligned(8))); > + }; > + > + The alignment of the (linear) payload data[] to a 64bit boundary > + allows the user to define own structs and unions to easily access the > + CAN payload. There is no given byteorder on the CAN bus by > + default. A read(2) system call on a CAN_RAW socket transfers a > + struct can_frame to the user space. > + > + The sockaddr_can structure has an interface index analogue to the > + PF_PACKET socket, that also binds to a specific interface: > + > + struct sockaddr_can { > + sa_family_t can_family; > + int can_ifindex; > + union { > + struct { canid_t rx_id, tx_id; } tp16; > + struct { canid_t rx_id, tx_id; } tp20; > + struct { canid_t rx_id, tx_id; } mcnet; > + struct { canid_t rx_id, tx_id; } isotp; > + struct { int lcu, type; } bap; > + } can_addr; > + }; > + > + To determine the interface index the an appropriate ioctl() has to ^ drop "the" > + be used (example for CAN_RAW sockets without error checking): > + > + int s; > + struct sockaddr_can addr; > + struct ifreq ifr; > + > + s = socket(PF_CAN, SOCK_RAW, CAN_RAW); > + > + strcpy(ifr.ifr_name, "can0" ); > + ioctl(s, SIOCGIFINDEX, &ifr); > + > + addr.can_family = AF_CAN; > + addr.can_ifindex = ifr.ifr_ifindex; > + > + bind(s, (struct sockaddr *)&addr, sizeof(addr)); > + > + (..) > + > + To bind a socket to all(!) CAN interfaces the interface index might Why "might be"? How about "would be" or "shall be" or "must be" or simply "is"? > + be 0 (zero). In this case the socket receives CAN frames from every > + enabled CAN interface. To determine the originating CAN interface > + the system call recvfrom(2) may be used instead of read(2). To send > + on a socket that is bound to 'any' interface sendto(2) is needed to > + specify the outgoing interface. > + > + Reading CAN frames from a bound CAN_RAW socket (see above) consists > + of reading a struct can_frame: > + > + struct can_frame frame; > + > + nbytes = read(s, &frame, sizeof(struct can_frame)); > + > + if (nbytes < 0) { > + perror("can raw socket read"); > + return 1; > + } > + > + /* paraniod check ... */ > + if (nbytes < sizeof(struct can_frame)) { > + fprintf(stderr, "read: incomplete CAN frame\n"); > + return 1; > + } > + > + /* do something with the received CAN frame */ > + > + Writing CAN frames can be done analogue with the write(2) system call: similarly, or analogously, > + > + nbytes = write(s, &frame, sizeof(struct can_frame)); > + > + When the CAN interface is bound to 'any' existing CAN interface > + (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the > + information about the originating CAN interface is needed: > + > + struct sockaddr_can addr; > + struct ifreq ifr; > + socklen_t len = sizeof(addr); > + struct can_frame frame; > + > + nbytes = recvfrom(s, &frame, sizeof(struct can_frame), > + 0, (struct sockaddr*)&addr, &len); > + > + /* get interface name of the received CAN frame */ > + ifr.ifr_ifindex = addr.can_ifindex; > + ioctl(s, SIOCGIFNAME, &ifr); > + printf("Received a CAN frame from interface %s", ifr.ifr_name); > + > + To write CAN frames on sockets bound to 'any' CAN interface the > + outgoing interface has to be defined certainly. > + > + strcpy(ifr.ifr_name, "can0"); > + ioctl(s, SIOCGIFINDEX, &ifr); > + addr.can_ifindex = ifr.ifr_ifindex; > + addr.can_family = AF_CAN; > + > + nbytes = sendto(s, &frame, sizeof(struct can_frame), > + 0, (struct sockaddr*)&addr, sizeof(addr)); > + > + 4.1 RAW protocol sockets with can_filters (SOCK_RAW) > + > + Using CAN_RAW sockets is extensively comparable to the commonly > + known access to CAN character devices. To meet the new possibilities > + provided by the multi user SocketCAN approach, some reasonable > + defaults are set at RAW socket bindung time: binding > + > + - The filters are set to exactly one filter receiving everything > + - The socket only receives valid data frames (=> no error frames) > + - The loopback of sent CAN frames is enabled (see chapter 3.2) > + - The socket does not receive it's own sent frames (in loopback mode) its > + > + These default settings may be changed before or after binding the socket. > + To use the referenced definitions of the socket options for CAN_RAW > + sockets include linux/can/raw.h . sockets, include <linux/can/raw.h>. > + > + 4.1.1 RAW socket option CAN_RAW_FILTER > + > + The receiption of CAN frames using CAN_RAW sockets can be controlled reception > + by defining 0 .. n filters with the CAN_RAW_FILTER socket option. > + > + The CAN filter structure is defined in include/linux/can.h: > + > + struct can_filter { > + canid_t can_id; > + canid_t can_mask; > + }; > + > + A filter matches, when > + > + <received_can_id> & mask == can_id & mask > + > + which is analogue to known CAN controllers hardware filter semantics. similar to or analagous to > + The filter can be inverted in this semantic, when the CAN_INV_FILTER > + bit is set in can_id element of the can_filter structure. In > + opposite to CAN controller hardware filters the user may set 0 .. n contrast > + receive filters for each open socket separately: > + > + struct can_filter rfilter[2]; > + > + rfilter[0].can_id = 0x123; > + rfilter[0].can_mask = CAN_SFF_MASK; > + rfilter[1].can_id = 0x200; > + rfilter[1].can_mask = 0x700; > + > + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter)); > + > + To disable the receiption of CAN frames on the selected CAN_RAW socket: reception > + > + setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); > + > + To set the filters to zero filters is quite obsolete as not readed read > + data causes the raw socket to discard the received CAN frames. But > + having this 'send only' use-case we may remove the receive list in the > + Kernel to save a little (really a very little!) CPU usage. > + > + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER > + > + As described in chapter 3.4 the CAN interface driver can generate so > + called Error Frames that can optionally be passed to the user > + application on the same way like other CAN frames. The possible in as > + errors are devided into different error classes that may be filtered divided > + using the appropriate error mask. To register for every possible > + error condition CAN_ERR_MASK can be used as value for the error mask. > + The values for the error mask are defined in linux/can/error.h . > + > + can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF ); > + > + setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, > + &err_mask, sizeof(err_mask)); > + > + 4.1.3 RAW socket option CAN_RAW_LOOPBACK > + > + To meet multi user needs the local loopback is enabled by default > + (see chapter 3.2 for details). But in some embedded use-cases > + (e.g. when only one application uses the CAN bus) this loopback > + functionality can be disabled (separately for each socket): > + > + int loopback = 0; /* 0 = disabled, 1 = enabled (default) */ > + > + setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, > sizeof(loopback)); > + > + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS > + > + When the local loopback is enabled, all the sent CAN frames are > + looped back to the open CAN sockets that registered for the CAN > + frames' CAN-ID on this given interface to meet the multi user > + needs. The receiption of the CAN frames on the same socket that was reception > + sending the CAN frame is assumed to be unwanted and therefore > + disabled by default. This default behaviour may be changed on > + demand: > + > + int set_recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */ > + > + setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, > + &recv_own_msgs, sizeof(recv_own_msgs)); ^^^ and ^^^ variable name is incorrect. > + > + 4.2 Broadcast Manager protocol sockets (SOCK_DGRAM) > + 4.3 connected transport protocols (SOCK_SEQPACKET) > + 4.4 unconnected transport protocols (SOCK_DGRAM) > + > + > +5. Socket CAN core module > +------------------------- > + > + The Socket CAN core module implements the protocol family > + PF_CAN. CAN protocol modules are loaded by the core module at > + runtime. The core module provides an interface for CAN protocol > + modules to subscribe needed CAN IDs (see chapter 3.1). > + > + 5.1 can.ko module params > + > + - stats_timer: To calculate the Socket CAN core statistics > + (e.g. current/maximum frames per second) this 1 second timer is > + invoked at can.ko module start time by default. This timer can be > + disabled giving stattimer=0 on the module comandline. by using > + > + - debug: When the Kconfig option CONFIG_CAN_DEBUG_CORE is set at > + compile time, the debug output code is compiled into the module. > + debug = 0x01 => print general debug information > + debug = 0x02 => print content of processed CAN frames > + debug = 0x04 => print content of processed socket buffers > + > + It is possible or have ORed values e.g. 3 or 7 for an output off to use of > + all available debug information. Using 0x02 and 0x04 may flood > + your kernel log - so be careful. > + > + 5.2 procfs content > + > + As described in chapter 3.1 the Socket CAN core uses several filter > + lists to deliver received CAN frames to CAN protocol modules. These > + receive lists, their filters and the count of filter matches can be > + checked in the appropriate receive list. All entries contain the > + device and a protocol module identifier: > + > + [EMAIL PROTECTED]:~$ cat /proc/net/can/rcvlist_all > + > + receive list 'rx_all': > + (vcan3: no entry) > + (vcan2: no entry) > + (vcan1: no entry) > + device can_id can_mask function userdata matches ident > + vcan0 000 00000000 f88e6370 f6c6f400 0 raw > + (any: no entry) > + > + In this example an application requests any CAN traffic from vcan0. > + > + rcvlist_all - list for unfiltered entries (no filter operations) > + rcvlist_eff - list for single extended frame (EFF) entries > + rcvlist_err - list for error frames masks > + rcvlist_fil - list for mask/value filters > + rcvlist_inv - list for mask/value filters (inverse semantic) > + rcvlist_sff - list for single standard frame (SFF) entries > + > + Additional procfs files in /proc/net/can > + > + stats - Socket CAN core statistics (rx/tx frames, match ratios, > ...) > + reset_stats - manual statistic reset > + version - prints the Socket CAN core version and the ABI version > + > + 5.3 writing own CAN protocol modules > + > + To implement a new protocol in the protocol family PF_CAN a new > + protocol has to be defined in include/linux/can.h . > + The prototypes and definitions to use the Socket CAN core can be > + accessed by including include/linux/can/core.h . > + Additionally to functions that register the CAN protocol and the Similar to ... > + CAN device notifier chain there are functions to subscribe CAN > + frames received by CAN interfaces and to send CAN frames: > + > + can_rx_register - subscribe CAN frames from a specific interface > + can_rx_unregister - unsubscribe CAN frames from a specific interface > + can_send - transmit a CAN frame (optional with local loopback) > + > + For details see the kerneldoc documentation in net/can/af_can.c or > + the source code of net/can/raw.c or net/can/bcm.c . > + > +6. CAN network drivers > +---------------------- > + > + Writing a CAN network device driver is much easier than writing a > + CAN character device driver. Analogue to other know network device Similar to other known > + drivers you mainly have to deal with: > + > + - TX: Put the CAN frame from the socket buffer to the CAN controller. > + - RX: Put the CAN frame from the CAN controller to the socket buffer. > + > + See e.g. at Documentation/networking/netdevices.txt . The differences > + for writing CAN network device driver are described below: > + > + 6.1 general settings > + > + dev->type = ARPHRD_CAN; /* the netdevice hardware type */ > + dev->flags = IFF_NOARP; /* CAN has no arp */ > + > + dev->mtu = sizeof(struct can_frame); > + > + The struct can_frame is the payload of each socket buffer in the > + protocol family PF_CAN. > + > + 6.2 loopback > + > + As described in chapter 3.2 the CAN network device driver should > + support a local loopback functionality. If so the driver flag > + IFF_LOOPBACK has to be set to omit the PF_CAN core to perform the to cause (?) > + loopback as fallback solution: > + > + dev->flags = (IFF_NOARP | IFF_LOOPBACK); > + > + 6.3 CAN controller hardware filters > + > + To reduce the interrupt load on deep embedded systems some CAN > + controllers support the filtering of CAN IDs or ranges of CAN IDs. > + These hardware filter capabilities vary from controller to > + controller and have to be identified as not feasible in a multi-user > + networking approach. The use of the very controller specific > + hardware filters could make sense in a very dedicated use-case, as a > + filter on driver level would affect all users in the multi-user > + system. The high efficient filter sets inside the PF_CAN core allow > + to set different multiple filters for each socket separately. > + Therefore the use of hardware filters goes to the category 'handmade > + tuning on deep embedded systems'. The author is running a MPC603e > + @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus > + load without any problems ... > + > + 6.4 currently supported CAN hardware (May 2007) > + > + On the project website http://developer.berlios.de/projects/socketcan > + there are different drivers available: > + > + vcan: Virtual CAN interface driver (if no real hardware is available) > + sja1000: Philips SJA1000 CAN controller (recommended) > + i82527: Intel i82527 CAN controller > + mscan: Motorola/Freescale CAN controller (e.g. inside SOC MPC5200) > + slcan: For a bunch of CAN adaptors that are attached via a > + serial line ASCII protocol (for serial / USB adaptors) > + > + Additionally the different CAN adaptors (ISA/PCI/PCMCIA/USB/Parport) > + from PEAK Systemtechnik support the CAN netdevice driver modell model > + since Linux driver v6.0: http://www.peak-system.com/linux/index.htm > + > + Please check the Mailing Lists on the berlios OSS project website. > + > + 6.5 todo (May 2007) > + > + The configuration interface for CAN network drivers is still an open > + issue that has not been finalized in the socketcan project. Also the > + idea of having a library module (candev.ko) that holds functions > + that are needed by all CAN netdevices is not ready to ship. > + Your contribution is welcome. --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** - To unsubscribe from this list: send the line "unsubscribe netdev" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html