aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/networking/can.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/networking/can.txt')
-rw-r--r--Documentation/networking/can.txt94
1 files changed, 37 insertions, 57 deletions
diff --git a/Documentation/networking/can.txt b/Documentation/networking/can.txt
index 4c072414eadb..f3089d423515 100644
--- a/Documentation/networking/can.txt
+++ b/Documentation/networking/can.txt
@@ -2,21 +2,20 @@
2 2
3can.txt 3can.txt
4 4
5Readme file for the Controller Area Network Protocol Family (aka Socket CAN) 5Readme file for the Controller Area Network Protocol Family (aka SocketCAN)
6 6
7This file contains 7This file contains
8 8
9 1 Overview / What is Socket CAN 9 1 Overview / What is SocketCAN
10 10
11 2 Motivation / Why using the socket API 11 2 Motivation / Why using the socket API
12 12
13 3 Socket CAN concept 13 3 SocketCAN concept
14 3.1 receive lists 14 3.1 receive lists
15 3.2 local loopback of sent frames 15 3.2 local loopback of sent frames
16 3.3 network security issues (capabilities) 16 3.3 network problem notifications
17 3.4 network problem notifications
18 17
19 4 How to use Socket CAN 18 4 How to use SocketCAN
20 4.1 RAW protocol sockets with can_filters (SOCK_RAW) 19 4.1 RAW protocol sockets with can_filters (SOCK_RAW)
21 4.1.1 RAW socket option CAN_RAW_FILTER 20 4.1.1 RAW socket option CAN_RAW_FILTER
22 4.1.2 RAW socket option CAN_RAW_ERR_FILTER 21 4.1.2 RAW socket option CAN_RAW_ERR_FILTER
@@ -34,7 +33,7 @@ This file contains
34 4.3 connected transport protocols (SOCK_SEQPACKET) 33 4.3 connected transport protocols (SOCK_SEQPACKET)
35 4.4 unconnected transport protocols (SOCK_DGRAM) 34 4.4 unconnected transport protocols (SOCK_DGRAM)
36 35
37 5 Socket CAN core module 36 5 SocketCAN core module
38 5.1 can.ko module params 37 5.1 can.ko module params
39 5.2 procfs content 38 5.2 procfs content
40 5.3 writing own CAN protocol modules 39 5.3 writing own CAN protocol modules
@@ -51,20 +50,20 @@ This file contains
51 6.6 CAN FD (flexible data rate) driver support 50 6.6 CAN FD (flexible data rate) driver support
52 6.7 supported CAN hardware 51 6.7 supported CAN hardware
53 52
54 7 Socket CAN resources 53 7 SocketCAN resources
55 54
56 8 Credits 55 8 Credits
57 56
58============================================================================ 57============================================================================
59 58
601. Overview / What is Socket CAN 591. Overview / What is SocketCAN
61-------------------------------- 60--------------------------------
62 61
63The socketcan package is an implementation of CAN protocols 62The socketcan package is an implementation of CAN protocols
64(Controller Area Network) for Linux. CAN is a networking technology 63(Controller Area Network) for Linux. CAN is a networking technology
65which has widespread use in automation, embedded devices, and 64which has widespread use in automation, embedded devices, and
66automotive fields. While there have been other CAN implementations 65automotive fields. While there have been other CAN implementations
67for Linux based on character devices, Socket CAN uses the Berkeley 66for Linux based on character devices, SocketCAN uses the Berkeley
68socket API, the Linux network stack and implements the CAN device 67socket API, the Linux network stack and implements the CAN device
69drivers as network interfaces. The CAN socket API has been designed 68drivers as network interfaces. The CAN socket API has been designed
70as similar as possible to the TCP/IP protocols to allow programmers, 69as similar as possible to the TCP/IP protocols to allow programmers,
@@ -74,7 +73,7 @@ sockets.
742. Motivation / Why using the socket API 732. Motivation / Why using the socket API
75---------------------------------------- 74----------------------------------------
76 75
77There have been CAN implementations for Linux before Socket CAN so the 76There have been CAN implementations for Linux before SocketCAN so the
78question arises, why we have started another project. Most existing 77question arises, why we have started another project. Most existing
79implementations come as a device driver for some CAN hardware, they 78implementations come as a device driver for some CAN hardware, they
80are based on character devices and provide comparatively little 79are based on character devices and provide comparatively little
@@ -89,10 +88,10 @@ the CAN controller requires employment of another device driver and
89often the need for adaption of large parts of the application to the 88often the need for adaption of large parts of the application to the
90new driver's API. 89new driver's API.
91 90
92Socket CAN was designed to overcome all of these limitations. A new 91SocketCAN was designed to overcome all of these limitations. A new
93protocol family has been implemented which provides a socket interface 92protocol family has been implemented which provides a socket interface
94to user space applications and which builds upon the Linux network 93to user space applications and which builds upon the Linux network
95layer, so to use all of the provided queueing functionality. A device 94layer, enabling use all of the provided queueing functionality. A device
96driver for CAN controller hardware registers itself with the Linux 95driver for CAN controller hardware registers itself with the Linux
97network layer as a network device, so that CAN frames from the 96network layer as a network device, so that CAN frames from the
98controller can be passed up to the network layer and on to the CAN 97controller can be passed up to the network layer and on to the CAN
@@ -146,15 +145,15 @@ solution for a couple of reasons:
146 providing an API for device drivers to register with. However, then 145 providing an API for device drivers to register with. However, then
147 it would be no more difficult, or may be even easier, to use the 146 it would be no more difficult, or may be even easier, to use the
148 networking framework provided by the Linux kernel, and this is what 147 networking framework provided by the Linux kernel, and this is what
149 Socket CAN does. 148 SocketCAN does.
150 149
151 The use of the networking framework of the Linux kernel is just the 150 The use of the networking framework of the Linux kernel is just the
152 natural and most appropriate way to implement CAN for Linux. 151 natural and most appropriate way to implement CAN for Linux.
153 152
1543. Socket CAN concept 1533. SocketCAN concept
155--------------------- 154---------------------
156 155
157 As described in chapter 2 it is the main goal of Socket CAN to 156 As described in chapter 2 it is the main goal of SocketCAN to
158 provide a socket interface to user space applications which builds 157 provide a socket interface to user space applications which builds
159 upon the Linux network layer. In contrast to the commonly known 158 upon the Linux network layer. In contrast to the commonly known
160 TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) 159 TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
@@ -168,11 +167,11 @@ solution for a couple of reasons:
168 167
169 The network transparent access of multiple applications leads to the 168 The network transparent access of multiple applications leads to the
170 problem that different applications may be interested in the same 169 problem that different applications may be interested in the same
171 CAN-IDs from the same CAN network interface. The Socket CAN core 170 CAN-IDs from the same CAN network interface. The SocketCAN core
172 module - which implements the protocol family CAN - provides several 171 module - which implements the protocol family CAN - provides several
173 high efficient receive lists for this reason. If e.g. a user space 172 high efficient receive lists for this reason. If e.g. a user space
174 application opens a CAN RAW socket, the raw protocol module itself 173 application opens a CAN RAW socket, the raw protocol module itself
175 requests the (range of) CAN-IDs from the Socket CAN core that are 174 requests the (range of) CAN-IDs from the SocketCAN core that are
176 requested by the user. The subscription and unsubscription of 175 requested by the user. The subscription and unsubscription of
177 CAN-IDs can be done for specific CAN interfaces or for all(!) known 176 CAN-IDs can be done for specific CAN interfaces or for all(!) known
178 CAN interfaces with the can_rx_(un)register() functions provided to 177 CAN interfaces with the can_rx_(un)register() functions provided to
@@ -217,21 +216,7 @@ solution for a couple of reasons:
217 * = you really like to have this when you're running analyser tools 216 * = you really like to have this when you're running analyser tools
218 like 'candump' or 'cansniffer' on the (same) node. 217 like 'candump' or 'cansniffer' on the (same) node.
219 218
220 3.3 network security issues (capabilities) 219 3.3 network problem notifications
221
222 The Controller Area Network is a local field bus transmitting only
223 broadcast messages without any routing and security concepts.
224 In the majority of cases the user application has to deal with
225 raw CAN frames. Therefore it might be reasonable NOT to restrict
226 the CAN access only to the user root, as known from other networks.
227 Since the currently implemented CAN_RAW and CAN_BCM sockets can only
228 send and receive frames to/from CAN interfaces it does not affect
229 security of others networks to allow all users to access the CAN.
230 To enable non-root users to access CAN_RAW and CAN_BCM protocol
231 sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be
232 selected at kernel compile time.
233
234 3.4 network problem notifications
235 220
236 The use of the CAN bus may lead to several problems on the physical 221 The use of the CAN bus may lead to several problems on the physical
237 and media access control layer. Detecting and logging of these lower 222 and media access control layer. Detecting and logging of these lower
@@ -251,11 +236,11 @@ solution for a couple of reasons:
251 by default. The format of the CAN error message frame is briefly 236 by default. The format of the CAN error message frame is briefly
252 described in the Linux header file "include/linux/can/error.h". 237 described in the Linux header file "include/linux/can/error.h".
253 238
2544. How to use Socket CAN 2394. How to use SocketCAN
255------------------------ 240------------------------
256 241
257 Like TCP/IP, you first need to open a socket for communicating over a 242 Like TCP/IP, you first need to open a socket for communicating over a
258 CAN network. Since Socket CAN implements a new protocol family, you 243 CAN network. Since SocketCAN implements a new protocol family, you
259 need to pass PF_CAN as the first argument to the socket(2) system 244 need to pass PF_CAN as the first argument to the socket(2) system
260 call. Currently, there are two CAN protocols to choose from, the raw 245 call. Currently, there are two CAN protocols to choose from, the raw
261 socket protocol and the broadcast manager (BCM). So to open a socket, 246 socket protocol and the broadcast manager (BCM). So to open a socket,
@@ -286,8 +271,8 @@ solution for a couple of reasons:
286 }; 271 };
287 272
288 The alignment of the (linear) payload data[] to a 64bit boundary 273 The alignment of the (linear) payload data[] to a 64bit boundary
289 allows the user to define own structs and unions to easily access the 274 allows the user to define their own structs and unions to easily access
290 CAN payload. There is no given byteorder on the CAN bus by 275 the CAN payload. There is no given byteorder on the CAN bus by
291 default. A read(2) system call on a CAN_RAW socket transfers a 276 default. A read(2) system call on a CAN_RAW socket transfers a
292 struct can_frame to the user space. 277 struct can_frame to the user space.
293 278
@@ -479,7 +464,7 @@ solution for a couple of reasons:
479 464
480 setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0); 465 setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
481 466
482 To set the filters to zero filters is quite obsolete as not read 467 To set the filters to zero filters is quite obsolete as to not read
483 data causes the raw socket to discard the received CAN frames. But 468 data causes the raw socket to discard the received CAN frames. But
484 having this 'send only' use-case we may remove the receive list in the 469 having this 'send only' use-case we may remove the receive list in the
485 Kernel to save a little (really a very little!) CPU usage. 470 Kernel to save a little (really a very little!) CPU usage.
@@ -814,17 +799,17 @@ solution for a couple of reasons:
814 4.4 unconnected transport protocols (SOCK_DGRAM) 799 4.4 unconnected transport protocols (SOCK_DGRAM)
815 800
816 801
8175. Socket CAN core module 8025. SocketCAN core module
818------------------------- 803-------------------------
819 804
820 The Socket CAN core module implements the protocol family 805 The SocketCAN core module implements the protocol family
821 PF_CAN. CAN protocol modules are loaded by the core module at 806 PF_CAN. CAN protocol modules are loaded by the core module at
822 runtime. The core module provides an interface for CAN protocol 807 runtime. The core module provides an interface for CAN protocol
823 modules to subscribe needed CAN IDs (see chapter 3.1). 808 modules to subscribe needed CAN IDs (see chapter 3.1).
824 809
825 5.1 can.ko module params 810 5.1 can.ko module params
826 811
827 - stats_timer: To calculate the Socket CAN core statistics 812 - stats_timer: To calculate the SocketCAN core statistics
828 (e.g. current/maximum frames per second) this 1 second timer is 813 (e.g. current/maximum frames per second) this 1 second timer is
829 invoked at can.ko module start time by default. This timer can be 814 invoked at can.ko module start time by default. This timer can be
830 disabled by using stattimer=0 on the module commandline. 815 disabled by using stattimer=0 on the module commandline.
@@ -833,7 +818,7 @@ solution for a couple of reasons:
833 818
834 5.2 procfs content 819 5.2 procfs content
835 820
836 As described in chapter 3.1 the Socket CAN core uses several filter 821 As described in chapter 3.1 the SocketCAN core uses several filter
837 lists to deliver received CAN frames to CAN protocol modules. These 822 lists to deliver received CAN frames to CAN protocol modules. These
838 receive lists, their filters and the count of filter matches can be 823 receive lists, their filters and the count of filter matches can be
839 checked in the appropriate receive list. All entries contain the 824 checked in the appropriate receive list. All entries contain the
@@ -860,15 +845,15 @@ solution for a couple of reasons:
860 845
861 Additional procfs files in /proc/net/can 846 Additional procfs files in /proc/net/can
862 847
863 stats - Socket CAN core statistics (rx/tx frames, match ratios, ...) 848 stats - SocketCAN core statistics (rx/tx frames, match ratios, ...)
864 reset_stats - manual statistic reset 849 reset_stats - manual statistic reset
865 version - prints the Socket CAN core version and the ABI version 850 version - prints the SocketCAN core version and the ABI version
866 851
867 5.3 writing own CAN protocol modules 852 5.3 writing own CAN protocol modules
868 853
869 To implement a new protocol in the protocol family PF_CAN a new 854 To implement a new protocol in the protocol family PF_CAN a new
870 protocol has to be defined in include/linux/can.h . 855 protocol has to be defined in include/linux/can.h .
871 The prototypes and definitions to use the Socket CAN core can be 856 The prototypes and definitions to use the SocketCAN core can be
872 accessed by including include/linux/can/core.h . 857 accessed by including include/linux/can/core.h .
873 In addition to functions that register the CAN protocol and the 858 In addition to functions that register the CAN protocol and the
874 CAN device notifier chain there are functions to subscribe CAN 859 CAN device notifier chain there are functions to subscribe CAN
@@ -1105,7 +1090,7 @@ solution for a couple of reasons:
1105 1090
1106 $ ip link set canX up type can bitrate 125000 1091 $ ip link set canX up type can bitrate 125000
1107 1092
1108 A device may enter the "bus-off" state if too much errors occurred on 1093 A device may enter the "bus-off" state if too many errors occurred on
1109 the CAN bus. Then no more messages are received or sent. An automatic 1094 the CAN bus. Then no more messages are received or sent. An automatic
1110 bus-off recovery can be enabled by setting the "restart-ms" to a 1095 bus-off recovery can be enabled by setting the "restart-ms" to a
1111 non-zero value, e.g.: 1096 non-zero value, e.g.:
@@ -1125,7 +1110,7 @@ solution for a couple of reasons:
1125 1110
1126 CAN FD capable CAN controllers support two different bitrates for the 1111 CAN FD capable CAN controllers support two different bitrates for the
1127 arbitration phase and the payload phase of the CAN FD frame. Therefore a 1112 arbitration phase and the payload phase of the CAN FD frame. Therefore a
1128 second bittiming has to be specified in order to enable the CAN FD bitrate. 1113 second bit timing has to be specified in order to enable the CAN FD bitrate.
1129 1114
1130 Additionally CAN FD capable CAN controllers support up to 64 bytes of 1115 Additionally CAN FD capable CAN controllers support up to 64 bytes of
1131 payload. The representation of this length in can_frame.can_dlc and 1116 payload. The representation of this length in can_frame.can_dlc and
@@ -1150,21 +1135,16 @@ solution for a couple of reasons:
1150 6.7 Supported CAN hardware 1135 6.7 Supported CAN hardware
1151 1136
1152 Please check the "Kconfig" file in "drivers/net/can" to get an actual 1137 Please check the "Kconfig" file in "drivers/net/can" to get an actual
1153 list of the support CAN hardware. On the Socket CAN project website 1138 list of the support CAN hardware. On the SocketCAN project website
1154 (see chapter 7) there might be further drivers available, also for 1139 (see chapter 7) there might be further drivers available, also for
1155 older kernel versions. 1140 older kernel versions.
1156 1141
11577. Socket CAN resources 11427. SocketCAN resources
1158----------------------- 1143-----------------------
1159 1144
1160 You can find further resources for Socket CAN like user space tools, 1145 The Linux CAN / SocketCAN project ressources (project site / mailing list)
1161 support for old kernel versions, more drivers, mailing lists, etc. 1146 are referenced in the MAINTAINERS file in the Linux source tree.
1162 at the BerliOS OSS project website for Socket CAN: 1147 Search for CAN NETWORK [LAYERS|DRIVERS].
1163
1164 http://developer.berlios.de/projects/socketcan
1165
1166 If you have questions, bug fixes, etc., don't hesitate to post them to
1167 the Socketcan-Users mailing list. But please search the archives first.
1168 1148
11698. Credits 11498. Credits
1170---------- 1150----------