[PATCH 7/7] CAN: Add documentation
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 | 637 ++ 2 files changed, 639 insertions(+) Index: net-2.6.25/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ net-2.6.25/Documentation/networking/can.txt 2007-11-14 13:04:57.0 +0100 @@ -0,0 +1,637 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 local loopback of sent frames +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 local loopback of sent frames +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 widespread use in automation, embedded devices, and +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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. A device +driver for CAN controller hardware registers itself with the Linux +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 cannot be used without loading at least one additional +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. + +Sim
[PATCH 7/7] CAN: Add documentation
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 | 629 ++ 2 files changed, 631 insertions(+) Index: net-2.6.25/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ net-2.6.25/Documentation/networking/can.txt 2007-11-16 14:56:31.0 +0100 @@ -0,0 +1,629 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 local loopback of sent frames +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 local loopback of sent frames +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 widespread use in automation, embedded devices, and +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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. A device +driver for CAN controller hardware registers itself with the Linux +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 cannot be used without loading at least one additional +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. + +Sim
[patch 7/7] CAN: Add documentation
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/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ net-2.6/Documentation/networking/can.txt2007-08-03 11:21:58.0 +0200 @@ -0,0 +1,635 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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 +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 +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 co
[patch 7/7] CAN: Add documentation
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/can.txt | 635 +++ 1 file changed, 635 insertions(+) Index: linux-2.6.22-rc1-git4/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ linux-2.6.22-rc1-git4/Documentation/networking/can.txt 2007-05-16 10:50:53.0 +0200 @@ -0,0 +1,635 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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 +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 +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 provide
[patch 7/7] CAN: Add documentation
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: linux-2.6.22-rc3/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ linux-2.6.22-rc3/Documentation/networking/can.txt 2007-05-30 14:58:07.0 +0200 @@ -0,0 +1,635 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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 +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 +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 f
[patch 7/7] CAN: Add documentation
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: linux-2.6.22-rc5/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ linux-2.6.22-rc5/Documentation/networking/can.txt 2007-06-20 14:11:31.0 +0200 @@ -0,0 +1,635 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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 +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 +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 f
[PATCH 7/7] CAN: Add documentation
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.0 + +++ net-2.6.24/Documentation/networking/can.txt 2007-09-17 10:27:25.0 +0200 @@ -0,0 +1,635 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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 +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 +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
[PATCH 7/7] CAN: Add documentation
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.0 + +++ net-2.6.24/Documentation/networking/can.txt 2007-09-20 18:49:01.0 +0200 @@ -0,0 +1,635 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 widespread use in automation, embedded devices, and +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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. A device +driver for CAN controller hardware registers itself with the Linux +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 cannot be used without loading at least one additional +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
[PATCH 7/7] CAN: Add documentation
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 | 634 ++ 2 files changed, 636 insertions(+) Index: net-2.6.24/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ net-2.6.24/Documentation/networking/can.txt 2007-09-25 13:28:26.0 +0200 @@ -0,0 +1,634 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 widespread use in automation, embedded devices, and +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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. A device +driver for CAN controller hardware registers itself with the Linux +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 cannot be used without loading at least one additional +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
[PATCH 7/7] CAN: Add documentation
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 | 637 ++ 2 files changed, 639 insertions(+) Index: net-2.6.24/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ net-2.6.24/Documentation/networking/can.txt 2007-10-02 08:43:50.0 +0200 @@ -0,0 +1,637 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 local loopback of sent frames +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 local loopback of sent frames +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 widespread use in automation, embedded devices, and +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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. A device +driver for CAN controller hardware registers itself with the Linux +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 cannot be used without loading at least one additional +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. + +Sim
[PATCH 7/7] CAN: Add documentation
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 | 637 ++ 2 files changed, 639 insertions(+) Index: net-2.6.24/Documentation/networking/can.txt === --- /dev/null 1970-01-01 00:00:00.0 + +++ net-2.6.24/Documentation/networking/can.txt 2007-10-02 08:43:50.0 +0200 @@ -0,0 +1,637 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 local loopback of sent frames +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 local loopback of sent frames +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 widespread use in automation, embedded devices, and +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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. A device +driver for CAN controller hardware registers itself with the Linux +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 cannot be used without loading at least one additional +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. + +Sim
Re: [PATCH 7/7] CAN: Add documentation
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.0 + > +++ net-2.6.24/Documentation/networking/can.txt 2007-09-17 > 10:27:25.0 +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
Re: [PATCH 7/7] CAN: Add documentation
Hi Randy, > Thanks for all of this informative documentation. > > I have some typo/spello corrections below. Thank you very much. I have applied all your suggestions to our SVN repository. To reduce traffic on the list, I only repeat the pointer to the repository: http://svn.berlios.de/svnroot/repos/socketcan/trunk/patch-series/net-2.6.24 If you request, I could send PATCH 7/7 on the list again. urs - 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
Re: [PATCH 7/7] CAN: Add documentation
Urs, On Mon, 2007-09-17 at 22:22 +0200, Urs Thuermann wrote: > Thank you very much. I have applied all your suggestions to our SVN > repository. To reduce traffic on the list, I only repeat the pointer > to the repository: > > http://svn.berlios.de/svnroot/repos/socketcan/trunk/patch-series/net-2.6.24 > > If you request, I could send PATCH 7/7 on the list again. Please do, having the patch in mail makes it easier to review and to comment. Thanks, tglx - 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
Re: [PATCH 7/7] CAN: Add documentation
Thomas Gleixner <[EMAIL PROTECTED]> writes: > Please do, having the patch in mail makes it easier to review and to > comment. OK, here it is: 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.0 + +++ net-2.6.24/Documentation/networking/can.txt 2007-09-17 21:57:29.0 +0200 @@ -0,0 +1,635 @@ + + +can.txt + +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) + +This file contains + + 1 Overview / What is Socket CAN + + 2 Motivation / Why using the socket API + + 3 Socket CAN concept +3.1 receive lists +3.2 loopback +3.3 network security issues (capabilities) +3.4 network problem notifications + + 4 How to use Socket CAN +4.1 RAW protocol sockets with can_filters (SOCK_RAW) + 4.1.1 RAW socket option CAN_RAW_FILTER + 4.1.2 RAW socket option CAN_RAW_ERR_FILTER + 4.1.3 RAW socket option CAN_RAW_LOOPBACK + 4.1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS +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 +5.1 can.ko module params +5.2 procfs content +5.3 writing own CAN protocol modules + + 6 CAN network drivers +6.1 general settings +6.2 loopback +6.3 CAN controller hardware filters +6.4 currently supported CAN hardware +6.5 todo + + 7 Credits + + + +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 widespread use in automation, embedded devices, and +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 + + +There have been CAN implementations for Linux before Socket CAN so the +question arises, why we have started another project. Most existing +implementations come as a device driver for some CAN hardware, they +are based on character devices and provide comparatively little +functionality. Usually, there is only a hardware-specific device +driver which provides a character device interface to send and +receive raw CAN frames, directly to/from the controller hardware. +Queueing of frames and higher-level transport protocols like ISO-TP +have to be implemented in user space applications. Also, most +character-device implementations support only one single process to +open the device at a time, similar to a serial interface. Exchanging +the CAN controller requires employment of another device driver and +often the need for adaption of large parts of the application to the +new driver's 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. A device +driver for CAN controller hardware registers itself with the Linux +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 cannot be used without loading at least one additional +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
Re: [PATCH 7/7] CAN: Add documentation
On 17 Sep 2007 22:49:34 +0200 Urs Thuermann wrote: > Thomas Gleixner <[EMAIL PROTECTED]> writes: > > > Please do, having the patch in mail makes it easier to review and to > > comment. > > OK, here it is: Just a few more minor changes... Thanks again. > +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 contrast to the commonly known network layer. > + TCP/IP and ethernet networking, the CAN bus is a broadcast-only(!) > + medium that has no MAC-layer addressing like ethernet. The CAN-identifier > + (can_id) is used for arbitration on the CAN-bus. Therefore the CAN-IDs > + have to be chosen uniquely on the bus. When designing a CAN-ECU > + network the CAN-IDs are mapped to be sent by a specific ECU. > + For this reason a CAN-ID can be treated best as a kind of source address. > + > + 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 for the according addressing information): > + > + ___ ___ ___ ___ ___ > +| _ | | _ | | _ | | _ _ | | _ | > +||A|| ||B|| ||C|| ||A| |B|| ||C|| > +|___| |___| |___| |___| |___| > + | | | | | > +-(1)- CAN bus -(2)--- > + > + To ensure that application A receives the same information in the > + example (2) as it would receive in example (1) there is need for > + some kind of local loopback on the appropriate node. > + > + The Linux network devices (by default) just can handle the > + transmission and reception of media dependent frames. Due to the > + arbritration on the CAN bus the transmission of a low prio CAN-ID > + may be delayed by the recepition of a high prio CAN frame. To 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 of performing the loopback for > + 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 > + separate socket. See sockopts from the CAN RAW sockets in chapter 4.1. > + > + * = you really like to have this when you're running analyser tools > + like 'candump' or 'cansniffer' on the (same) node. > + --- ~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
Re: [PATCH 7/7] CAN: Add documentation
Hi Randy, > Just a few more minor changes... Thanks again. Again, thank you. I have applied these two typo fixes, too. urs - 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
Re: [PATCH 7/7] CAN: Add documentation
On 17 Sep 2007, Urs Thuermann wrote: > Thomas Gleixner <[EMAIL PROTECTED]> writes: > > > Please do, having the patch in mail makes it easier to review and to > > comment. > > OK, here it is: One more typo. > 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.0 + > +++ net-2.6.24/Documentation/networking/can.txt 2007-09-17 > 21:57:29.0 +0200 > @@ -0,0 +1,635 @@ > + > + > +can.txt > + > +Readme file for the Controller Area Network Protocol Family (aka Socket CAN) > + > +This file contains > + > + 1 Overview / What is Socket CAN > + > + 2 Motivation / Why using the socket API > + ... > + > + > +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 widespread use in automation, embedded devices, and > +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 > + > + > +There have been CAN implementations for Linux before Socket CAN so the > +question arises, why we have started another project. Most existing > +implementations come as a device driver for some CAN hardware, they > +are based on character devices and provide comparatively little > +functionality. Usually, there is only a hardware-specific device > +driver which provides a character device interface to send and > +receive raw CAN frames, directly to/from the controller hardware. > +Queueing of frames and higher-level transport protocols like ISO-TP > +have to be implemented in user space applications. Also, most > +character-device implementations support only one single process to > +open the device at a time, similar to a serial interface. Exchanging > +the CAN controller requires employment of another device driver and > +often the need for adaption of large parts of the application to the > +new driver's 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. A device > +driver for CAN controller hardware registers itself with the Linux > +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 cannot be used without loading at least one additional > +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: "decive" -> "device" above. -Bill - 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
Re: [PATCH 7/7] CAN: Add documentation
Bill Fink <[EMAIL PROTECTED]> writes: > One more typo. > "decive" -> "device" above. Thank you. It's fixed now. urs - 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
