mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-23 09:19:51 +00:00
can: update MAINTAINERS and Documentation
Changed MAINTAINERS file to add Documentation/networking/can.txt to the list of maintained files. can.txt: - Globally changed Socket CAN to SocketCAN - Removed section 3.3 from the document - Updated Section 7 - Corrected a few simple typos Acked-by: Oliver Hartkopp <socketcan@hartkopp.net> Signed-off-by: John Whitmore <johnfwhitmore@gmail.com> Signed-off-by: Marc Kleine-Budde <mkl@pengutronix.de>
This commit is contained in:
parent
4ce78a838c
commit
f35f6c8f74
2 changed files with 38 additions and 57 deletions
|
@ -2,21 +2,20 @@
|
||||||
|
|
||||||
can.txt
|
can.txt
|
||||||
|
|
||||||
Readme file for the Controller Area Network Protocol Family (aka Socket CAN)
|
Readme file for the Controller Area Network Protocol Family (aka SocketCAN)
|
||||||
|
|
||||||
This file contains
|
This file contains
|
||||||
|
|
||||||
1 Overview / What is Socket CAN
|
1 Overview / What is SocketCAN
|
||||||
|
|
||||||
2 Motivation / Why using the socket API
|
2 Motivation / Why using the socket API
|
||||||
|
|
||||||
3 Socket CAN concept
|
3 SocketCAN concept
|
||||||
3.1 receive lists
|
3.1 receive lists
|
||||||
3.2 local loopback of sent frames
|
3.2 local loopback of sent frames
|
||||||
3.3 network security issues (capabilities)
|
3.3 network problem notifications
|
||||||
3.4 network problem notifications
|
|
||||||
|
|
||||||
4 How to use Socket CAN
|
4 How to use SocketCAN
|
||||||
4.1 RAW protocol sockets with can_filters (SOCK_RAW)
|
4.1 RAW protocol sockets with can_filters (SOCK_RAW)
|
||||||
4.1.1 RAW socket option CAN_RAW_FILTER
|
4.1.1 RAW socket option CAN_RAW_FILTER
|
||||||
4.1.2 RAW socket option CAN_RAW_ERR_FILTER
|
4.1.2 RAW socket option CAN_RAW_ERR_FILTER
|
||||||
|
@ -34,7 +33,7 @@ This file contains
|
||||||
4.3 connected transport protocols (SOCK_SEQPACKET)
|
4.3 connected transport protocols (SOCK_SEQPACKET)
|
||||||
4.4 unconnected transport protocols (SOCK_DGRAM)
|
4.4 unconnected transport protocols (SOCK_DGRAM)
|
||||||
|
|
||||||
5 Socket CAN core module
|
5 SocketCAN core module
|
||||||
5.1 can.ko module params
|
5.1 can.ko module params
|
||||||
5.2 procfs content
|
5.2 procfs content
|
||||||
5.3 writing own CAN protocol modules
|
5.3 writing own CAN protocol modules
|
||||||
|
@ -51,20 +50,20 @@ This file contains
|
||||||
6.6 CAN FD (flexible data rate) driver support
|
6.6 CAN FD (flexible data rate) driver support
|
||||||
6.7 supported CAN hardware
|
6.7 supported CAN hardware
|
||||||
|
|
||||||
7 Socket CAN resources
|
7 SocketCAN resources
|
||||||
|
|
||||||
8 Credits
|
8 Credits
|
||||||
|
|
||||||
============================================================================
|
============================================================================
|
||||||
|
|
||||||
1. Overview / What is Socket CAN
|
1. Overview / What is SocketCAN
|
||||||
--------------------------------
|
--------------------------------
|
||||||
|
|
||||||
The socketcan package is an implementation of CAN protocols
|
The socketcan package is an implementation of CAN protocols
|
||||||
(Controller Area Network) for Linux. CAN is a networking technology
|
(Controller Area Network) for Linux. CAN is a networking technology
|
||||||
which has widespread use in automation, embedded devices, and
|
which has widespread use in automation, embedded devices, and
|
||||||
automotive fields. While there have been other CAN implementations
|
automotive fields. While there have been other CAN implementations
|
||||||
for Linux based on character devices, Socket CAN uses the Berkeley
|
for Linux based on character devices, SocketCAN uses the Berkeley
|
||||||
socket API, the Linux network stack and implements the CAN device
|
socket API, the Linux network stack and implements the CAN device
|
||||||
drivers as network interfaces. The CAN socket API has been designed
|
drivers as network interfaces. The CAN socket API has been designed
|
||||||
as similar as possible to the TCP/IP protocols to allow programmers,
|
as similar as possible to the TCP/IP protocols to allow programmers,
|
||||||
|
@ -74,7 +73,7 @@ sockets.
|
||||||
2. Motivation / Why using the socket API
|
2. Motivation / Why using the socket API
|
||||||
----------------------------------------
|
----------------------------------------
|
||||||
|
|
||||||
There have been CAN implementations for Linux before Socket CAN so the
|
There have been CAN implementations for Linux before SocketCAN so the
|
||||||
question arises, why we have started another project. Most existing
|
question arises, why we have started another project. Most existing
|
||||||
implementations come as a device driver for some CAN hardware, they
|
implementations come as a device driver for some CAN hardware, they
|
||||||
are based on character devices and provide comparatively little
|
are based on character devices and provide comparatively little
|
||||||
|
@ -89,10 +88,10 @@ the CAN controller requires employment of another device driver and
|
||||||
often the need for adaption of large parts of the application to the
|
often the need for adaption of large parts of the application to the
|
||||||
new driver's API.
|
new driver's API.
|
||||||
|
|
||||||
Socket CAN was designed to overcome all of these limitations. A new
|
SocketCAN was designed to overcome all of these limitations. A new
|
||||||
protocol family has been implemented which provides a socket interface
|
protocol family has been implemented which provides a socket interface
|
||||||
to user space applications and which builds upon the Linux network
|
to user space applications and which builds upon the Linux network
|
||||||
layer, so to use all of the provided queueing functionality. A device
|
layer, enabling use all of the provided queueing functionality. A device
|
||||||
driver for CAN controller hardware registers itself with the Linux
|
driver for CAN controller hardware registers itself with the Linux
|
||||||
network layer as a network device, so that CAN frames from the
|
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
|
controller can be passed up to the network layer and on to the CAN
|
||||||
|
@ -146,15 +145,15 @@ solution for a couple of reasons:
|
||||||
providing an API for device drivers to register with. However, then
|
providing an API for device drivers to register with. However, then
|
||||||
it would be no more difficult, or may be even easier, to use the
|
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
|
networking framework provided by the Linux kernel, and this is what
|
||||||
Socket CAN does.
|
SocketCAN does.
|
||||||
|
|
||||||
The use of the networking framework of the Linux kernel is just the
|
The use of the networking framework of the Linux kernel is just the
|
||||||
natural and most appropriate way to implement CAN for Linux.
|
natural and most appropriate way to implement CAN for Linux.
|
||||||
|
|
||||||
3. Socket CAN concept
|
3. SocketCAN concept
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
As described in chapter 2 it is the main goal of Socket CAN to
|
As described in chapter 2 it is the main goal of SocketCAN to
|
||||||
provide a socket interface to user space applications which builds
|
provide a socket interface to user space applications which builds
|
||||||
upon the Linux network layer. In contrast to the commonly known
|
upon the Linux network layer. In contrast to the commonly known
|
||||||
TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
|
TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!)
|
||||||
|
@ -168,11 +167,11 @@ solution for a couple of reasons:
|
||||||
|
|
||||||
The network transparent access of multiple applications leads to the
|
The network transparent access of multiple applications leads to the
|
||||||
problem that different applications may be interested in the same
|
problem that different applications may be interested in the same
|
||||||
CAN-IDs from the same CAN network interface. The Socket CAN core
|
CAN-IDs from the same CAN network interface. The SocketCAN core
|
||||||
module - which implements the protocol family CAN - provides several
|
module - which implements the protocol family CAN - provides several
|
||||||
high efficient receive lists for this reason. If e.g. a user space
|
high efficient receive lists for this reason. If e.g. a user space
|
||||||
application opens a CAN RAW socket, the raw protocol module itself
|
application opens a CAN RAW socket, the raw protocol module itself
|
||||||
requests the (range of) CAN-IDs from the Socket CAN core that are
|
requests the (range of) CAN-IDs from the SocketCAN core that are
|
||||||
requested by the user. The subscription and unsubscription of
|
requested by the user. The subscription and unsubscription of
|
||||||
CAN-IDs can be done for specific CAN interfaces or for all(!) known
|
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 interfaces with the can_rx_(un)register() functions provided to
|
||||||
|
@ -217,21 +216,7 @@ solution for a couple of reasons:
|
||||||
* = you really like to have this when you're running analyser tools
|
* = you really like to have this when you're running analyser tools
|
||||||
like 'candump' or 'cansniffer' on the (same) node.
|
like 'candump' or 'cansniffer' on the (same) node.
|
||||||
|
|
||||||
3.3 network security issues (capabilities)
|
3.3 network problem notifications
|
||||||
|
|
||||||
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
|
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
|
and media access control layer. Detecting and logging of these lower
|
||||||
|
@ -251,11 +236,11 @@ solution for a couple of reasons:
|
||||||
by default. The format of the CAN error message frame is briefly
|
by default. The format of the CAN error message frame is briefly
|
||||||
described in the Linux header file "include/linux/can/error.h".
|
described in the Linux header file "include/linux/can/error.h".
|
||||||
|
|
||||||
4. How to use Socket CAN
|
4. How to use SocketCAN
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
Like TCP/IP, you first need to open a socket for communicating over a
|
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
|
CAN network. Since SocketCAN implements a new protocol family, you
|
||||||
need to pass PF_CAN as the first argument to the socket(2) system
|
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
|
call. Currently, there are two CAN protocols to choose from, the raw
|
||||||
socket protocol and the broadcast manager (BCM). So to open a socket,
|
socket protocol and the broadcast manager (BCM). So to open a socket,
|
||||||
|
@ -286,8 +271,8 @@ solution for a couple of reasons:
|
||||||
};
|
};
|
||||||
|
|
||||||
The alignment of the (linear) payload data[] to a 64bit boundary
|
The alignment of the (linear) payload data[] to a 64bit boundary
|
||||||
allows the user to define own structs and unions to easily access the
|
allows the user to define their own structs and unions to easily access
|
||||||
CAN payload. There is no given byteorder on the CAN bus by
|
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
|
default. A read(2) system call on a CAN_RAW socket transfers a
|
||||||
struct can_frame to the user space.
|
struct can_frame to the user space.
|
||||||
|
|
||||||
|
@ -479,7 +464,7 @@ solution for a couple of reasons:
|
||||||
|
|
||||||
setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
|
setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
|
||||||
|
|
||||||
To set the filters to zero filters is quite obsolete as not read
|
To set the filters to zero filters is quite obsolete as to not read
|
||||||
data causes the raw socket to discard the received CAN frames. But
|
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
|
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.
|
Kernel to save a little (really a very little!) CPU usage.
|
||||||
|
@ -814,17 +799,17 @@ solution for a couple of reasons:
|
||||||
4.4 unconnected transport protocols (SOCK_DGRAM)
|
4.4 unconnected transport protocols (SOCK_DGRAM)
|
||||||
|
|
||||||
|
|
||||||
5. Socket CAN core module
|
5. SocketCAN core module
|
||||||
-------------------------
|
-------------------------
|
||||||
|
|
||||||
The Socket CAN core module implements the protocol family
|
The SocketCAN core module implements the protocol family
|
||||||
PF_CAN. CAN protocol modules are loaded by the core module at
|
PF_CAN. CAN protocol modules are loaded by the core module at
|
||||||
runtime. The core module provides an interface for CAN protocol
|
runtime. The core module provides an interface for CAN protocol
|
||||||
modules to subscribe needed CAN IDs (see chapter 3.1).
|
modules to subscribe needed CAN IDs (see chapter 3.1).
|
||||||
|
|
||||||
5.1 can.ko module params
|
5.1 can.ko module params
|
||||||
|
|
||||||
- stats_timer: To calculate the Socket CAN core statistics
|
- stats_timer: To calculate the SocketCAN core statistics
|
||||||
(e.g. current/maximum frames per second) this 1 second timer is
|
(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
|
invoked at can.ko module start time by default. This timer can be
|
||||||
disabled by using stattimer=0 on the module commandline.
|
disabled by using stattimer=0 on the module commandline.
|
||||||
|
@ -833,7 +818,7 @@ solution for a couple of reasons:
|
||||||
|
|
||||||
5.2 procfs content
|
5.2 procfs content
|
||||||
|
|
||||||
As described in chapter 3.1 the Socket CAN core uses several filter
|
As described in chapter 3.1 the SocketCAN core uses several filter
|
||||||
lists to deliver received CAN frames to CAN protocol modules. These
|
lists to deliver received CAN frames to CAN protocol modules. These
|
||||||
receive lists, their filters and the count of filter matches can be
|
receive lists, their filters and the count of filter matches can be
|
||||||
checked in the appropriate receive list. All entries contain the
|
checked in the appropriate receive list. All entries contain the
|
||||||
|
@ -860,15 +845,15 @@ solution for a couple of reasons:
|
||||||
|
|
||||||
Additional procfs files in /proc/net/can
|
Additional procfs files in /proc/net/can
|
||||||
|
|
||||||
stats - Socket CAN core statistics (rx/tx frames, match ratios, ...)
|
stats - SocketCAN core statistics (rx/tx frames, match ratios, ...)
|
||||||
reset_stats - manual statistic reset
|
reset_stats - manual statistic reset
|
||||||
version - prints the Socket CAN core version and the ABI version
|
version - prints the SocketCAN core version and the ABI version
|
||||||
|
|
||||||
5.3 writing own CAN protocol modules
|
5.3 writing own CAN protocol modules
|
||||||
|
|
||||||
To implement a new protocol in the protocol family PF_CAN a new
|
To implement a new protocol in the protocol family PF_CAN a new
|
||||||
protocol has to be defined in include/linux/can.h .
|
protocol has to be defined in include/linux/can.h .
|
||||||
The prototypes and definitions to use the Socket CAN core can be
|
The prototypes and definitions to use the SocketCAN core can be
|
||||||
accessed by including include/linux/can/core.h .
|
accessed by including include/linux/can/core.h .
|
||||||
In addition to functions that register the CAN protocol and the
|
In addition to functions that register the CAN protocol and the
|
||||||
CAN device notifier chain there are functions to subscribe CAN
|
CAN device notifier chain there are functions to subscribe CAN
|
||||||
|
@ -1105,7 +1090,7 @@ solution for a couple of reasons:
|
||||||
|
|
||||||
$ ip link set canX up type can bitrate 125000
|
$ ip link set canX up type can bitrate 125000
|
||||||
|
|
||||||
A device may enter the "bus-off" state if too much errors occurred on
|
A device may enter the "bus-off" state if too many errors occurred on
|
||||||
the CAN bus. Then no more messages are received or sent. An automatic
|
the CAN bus. Then no more messages are received or sent. An automatic
|
||||||
bus-off recovery can be enabled by setting the "restart-ms" to a
|
bus-off recovery can be enabled by setting the "restart-ms" to a
|
||||||
non-zero value, e.g.:
|
non-zero value, e.g.:
|
||||||
|
@ -1125,7 +1110,7 @@ solution for a couple of reasons:
|
||||||
|
|
||||||
CAN FD capable CAN controllers support two different bitrates for the
|
CAN FD capable CAN controllers support two different bitrates for the
|
||||||
arbitration phase and the payload phase of the CAN FD frame. Therefore a
|
arbitration phase and the payload phase of the CAN FD frame. Therefore a
|
||||||
second bittiming has to be specified in order to enable the CAN FD bitrate.
|
second bit timing has to be specified in order to enable the CAN FD bitrate.
|
||||||
|
|
||||||
Additionally CAN FD capable CAN controllers support up to 64 bytes of
|
Additionally CAN FD capable CAN controllers support up to 64 bytes of
|
||||||
payload. The representation of this length in can_frame.can_dlc and
|
payload. The representation of this length in can_frame.can_dlc and
|
||||||
|
@ -1150,21 +1135,16 @@ solution for a couple of reasons:
|
||||||
6.7 Supported CAN hardware
|
6.7 Supported CAN hardware
|
||||||
|
|
||||||
Please check the "Kconfig" file in "drivers/net/can" to get an actual
|
Please check the "Kconfig" file in "drivers/net/can" to get an actual
|
||||||
list of the support CAN hardware. On the Socket CAN project website
|
list of the support CAN hardware. On the SocketCAN project website
|
||||||
(see chapter 7) there might be further drivers available, also for
|
(see chapter 7) there might be further drivers available, also for
|
||||||
older kernel versions.
|
older kernel versions.
|
||||||
|
|
||||||
7. Socket CAN resources
|
7. SocketCAN resources
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
||||||
You can find further resources for Socket CAN like user space tools,
|
The Linux CAN / SocketCAN project ressources (project site / mailing list)
|
||||||
support for old kernel versions, more drivers, mailing lists, etc.
|
are referenced in the MAINTAINERS file in the Linux source tree.
|
||||||
at the BerliOS OSS project website for Socket CAN:
|
Search for CAN NETWORK [LAYERS|DRIVERS].
|
||||||
|
|
||||||
http://developer.berlios.de/projects/socketcan
|
|
||||||
|
|
||||||
If you have questions, bug fixes, etc., don't hesitate to post them to
|
|
||||||
the Socketcan-Users mailing list. But please search the archives first.
|
|
||||||
|
|
||||||
8. Credits
|
8. Credits
|
||||||
----------
|
----------
|
||||||
|
|
|
@ -2012,6 +2012,7 @@ L: linux-can@vger.kernel.org
|
||||||
W: http://gitorious.org/linux-can
|
W: http://gitorious.org/linux-can
|
||||||
T: git git://gitorious.org/linux-can/linux-can-next.git
|
T: git git://gitorious.org/linux-can/linux-can-next.git
|
||||||
S: Maintained
|
S: Maintained
|
||||||
|
F: Documentation/networking/can.txt
|
||||||
F: net/can/
|
F: net/can/
|
||||||
F: include/linux/can/core.h
|
F: include/linux/can/core.h
|
||||||
F: include/uapi/linux/can.h
|
F: include/uapi/linux/can.h
|
||||||
|
|
Loading…
Reference in a new issue