--- /dev/null
+============================================================================
+
+can-bcm.txt : Broadcast Manager API
+
+Part of the documentation for the socketCAN subsystem
+
+This file contains:
+
+ 1 Broadcast Manager protocol sockets (SOCK_DGRAM)
+ 1.1 Opening BCM sockets
+ 1.2 BCM messages (struct bcm_msg_head)
+ 1.3 TX_SETUP opcode
+ 1.4 TX_DELETE opcode
+ 1.5 TX_READ opcode
+ 1.6 TX_SEND opcode
+ 1.7 RX_SETUP opcode
+ 1.8 RX_DELETE opcode
+ 1.9 RX_READ opcode
+
+============================================================================
+
+1. Broadcast Manager protocol sockets (SOCK_DGRAM)
+--------------------------------------------------
+
+ The Broadcast Manager (BCM) provides functions to send CAN frames
+ once or periodically, as well as notify applications of changes in
+ received CAN frames, recognizing specific CAN IDs.
+
+ Capabilities on the trasmission side:
+ - Cyclic transmission of a CAN frame with a given interval
+ - Modification of message content and intervals at runtime (e.g.
+ switching to a new interval with or without immediate restart of
+ the timer)
+ - Automatically switching to a second interval after a certain number
+ of frames has been sent
+ - Instant transmission of changed frames, without influencing the
+ interval cycle
+ - One-time transmission of CAN messages
+
+ Capabilities on the receiving side:
+ - Receive filter to detect changes in frame ID, data or length (DLC)
+ - Receive filter for multiplex frames (e.g. with packet counters in
+ the data field)
+ - RTR replies to messages
+ - Time-out monitoring of frames
+ - Frequency reduction of messages (throttle function) to the user
+ application
+
+ 1.1 Opening BCM sockets
+
+ To use Broadcast-Manager include the file "bcm.h".
+ A socket for Broadcast-Manager is created with:
+
+ s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
+
+ The CAN interface is assigned with a call to connect() on the socket.
+
+ addr.can_family = AF_CAN;
+ strcpy(ifr.ifr_name, "can0");
+ ioctl(s, SIOCGIFINDEX, &ifr);
+ addr.can_ifindex = ifr.ifr_ifindex;
+
+ connect(s, (struct sockaddr *)&addr, sizeof(addr));
+
+ If a process must operate on multiple CAN buses, it must open several
+ sockets. It is also possible for a process to open multiple sockets
+ on a single CAN-bus, if it makes sense for the application programmer
+ to structure different data flows.
+ Every single instance of Broadcast-Manager is able to manage any number of
+ filter and/or send requests.
+
+ 1.2 BCM messages (struct bcm_msg_head)
+
+ All messages from the (user) process to Broadcast-Manager have the same
+ structure. It consists of a message header with the command (opcode),
+ several options and zero or more CAN frames, depending on the command
+ used and the action requested:
+
+ struct bcm_msg_head {
+ int opcode; /* command */
+ int flags; /* special flags */
+ int count; /* run 'count' times ival1 then ival2 */
+ struct timeval ival1, ival2; /* intervals */
+ canid_t can_id; /* 32 Bit SFF/EFF. MSB set at EFF */
+ int nframes; /* number of can_frame's in the next field */
+ struct can_frame frames[0];
+ };
+
+ The value of nframes indicates how many user data frames follow the
+ message header. The user data frames are used to describe the actual
+ content of a CAN message:
+
+ struct can_frame {
+ canid_t can_id; /* 32 bit CAN_ID + EFF/RTR flags */
+ __u8 can_dlc; /* data length code: 0 .. 8 */
+ __u8 data[8] __attribute__ ((aligned(8)));
+ };
+
+ The opcode defines the type of message. Messages from the user to
+ BCM control the operations of the BCM, replies from the BCM indicate
+ certain changes to the user, such as timeouts, etc.
+
+ The transmit and receive path of the BCM are two independent functional
+ blocks.
+
+ For the transmit path the following opcodes exist:
+
+ TX_SETUP: for setting up and modifying transmission requests
+ TX_DELETE: to remove send requests
+ TX_READ: to read out the current broadcasting commands
+ (for debugging purposes)
+ TX_SEND: for sending a single CAN message
+
+ For the receive path the following opcodes exist:
+
+ RX_SETUP: for setting and modifying receive filters
+ RX_DELETE: for deleting receive filters
+ RX_READ: to read out the current receive filter (for debugging purposes)
+
+ The Broadcast-Manager sends response messages in the same form. The
+ BCM sends these opcodes:
+
+ TX_STATUS: in response to TX_READ
+ TX_EXPIRED: is sent when the counter count reaches ival1 (only if
+ flag TX_COUNTEVT is set, see below)
+
+ RX_STATUS: in response to RX_READ
+ RX_TIMEOUT: sent if the time-controlled reception of a message failed
+ RX_CHANGED: sent if the first or a revised CAN message was received
+
+ Each of these opcode needs CAN ID specified either in the "can_id" field or
+ in the first can_frame structure attached to the command.
+
+ In addition, there are optional flags which can influence the BCM behavior:
+
+ SETTIMER: set the value of ival1, ival2 and count
+ STARTTIMER: start the timer with the actual value of ival1, ival2 and count.
+ Starting the timer leads simultaneously to the transmission of a can_frame
+ TX_COUNTEVT: create the message TX_EXPIRED when count is reached
+ TX_ANNOUNCE: a change of data by the process is emitted with a new frame,
+ regardless of the timer status
+ TX_CP_CAN_ID: copies the can_id from the message header attached to each
+ of can_frame. This is intended only as usage simplification
+ TX_RESET_MULTI_IDX: forces a reset of the index counter from the update
+ to be sent by multiplex message even if it would not be necessary
+ because of the length
+ RX_FILTER_ID: there is no filtering of the user data. A match with the
+ received message can_id automatically leads to a RX_CHANGED. Use
+ caution in cyclic messages. If RX_FILTER_ID flag is set, the CAN frame
+ in RX_SETUP can be ignored (i.e., nframes = 0)
+ RX_RTR_FRAME: the filter passed is used as CAN message to be sent when
+ receiving an RTR frame
+ RX_CHECK_DLC: a change of the DLC leads to an RX_CHANGED message to the user
+ application
+ RX_NO_AUTOTIMER: if the timer ival1 in the RX_SETUP has been set equal to
+ zero, on receipt of the CAN message the timer for the timeout
+ monitoring is automatically started. Setting this flag prevents the
+ automatic reset of the start timer
+ RX_ANNOUNCE_RESUME: refers also to the time-out supervision of RX_SETUP. By
+ setting this flag, when an RX-outs occours, a RX_CHANGED will be
+ generated when the (cyclic) receive restarts. This will happen even
+ if the user data have not changed
+
+ 1.3 TX_SETUP opcode
+ 1.4 TX_DELETE opcode
+
+ This opcode will delete the entry for transmission of the CAN frame with
+ the specified can_id CAN identifier. The message length for the command
+ TX_DELETE is sizeof(bcm_msg_head) (only the header).
+
+ 1.5 TX_READ opcode
+ 1.6 TX_SEND opcode
+ 1.7 RX_SETUP opcode
+ 1.8 RX_DELETE opcode
+ 1.9 RX_READ opcode
+
--- /dev/null
+============================================================================
+
+can-core.txt : core module description
+
+Part of the documentation for the socketCAN subsystem
+
+This file contains:
+
+ 1 Socket CAN core module
+ 1.1 can.ko module params
+ 1.2 procfs content
+ 1.3 writing own CAN protocol modules
+
+============================================================================
+
+1. Socket CAN core module
+-------------------------
+
+ The Socket CAN core module implements the protocol family
+ PF_CAN. CAN protocol modules are loaded by the core module at
+ runtime. The core module provides an interface for CAN protocol
+ modules to subscribe needed CAN IDs (see overview.txt, chapter 3.1).
+
+ 1.1 can.ko module params
+
+ - stats_timer: To calculate the Socket CAN core statistics
+ (e.g. current/maximum frames per second) this 1 second timer is
+ invoked at can.ko module start time by default. This timer can be
+ disabled by using stattimer=0 on the module commandline.
+
+ - debug: (removed since SocketCAN SVN r546)
+
+ 1.2 procfs content
+
+ As described in overview.txt, chapter 3.1 the Socket CAN core uses
+ several filter lists to deliver received CAN frames to CAN protocol
+ modules. These receive lists, their filters and the count of filter
+ matches can be checked in the appropriate receive list. All entries
+ contain the device and a protocol module identifier:
+
+ foo@bar:~$ cat /proc/net/can/rcvlist_all
+
+ receive list 'rx_all':
+ (vcan3: no entry)
+ (vcan2: no entry)
+ (vcan1: no entry)
+ device can_id can_mask function userdata matches ident
+ vcan0 000 00000000 f88e6370 f6c6f400 0 raw
+ (any: no entry)
+
+ In this example an application requests any CAN traffic from vcan0.
+
+ rcvlist_all - list for unfiltered entries (no filter operations)
+ rcvlist_eff - list for single extended frame (EFF) entries
+ rcvlist_err - list for error frames masks
+ rcvlist_fil - list for mask/value filters
+ rcvlist_inv - list for mask/value filters (inverse semantic)
+ rcvlist_sff - list for single standard frame (SFF) entries
+
+ Additional procfs files in /proc/net/can
+
+ stats - Socket CAN core statistics (rx/tx frames, match ratios, ...)
+ reset_stats - manual statistic reset
+ version - prints the Socket CAN core version and the ABI version
+
+ 1.3 writing own CAN protocol modules
+
+ To implement a new protocol in the protocol family PF_CAN a new
+ protocol has to be defined in include/linux/can.h .
+ The prototypes and definitions to use the Socket CAN core can be
+ accessed by including include/linux/can/core.h .
+ In addition to functions that register the CAN protocol and the
+ CAN device notifier chain there are functions to subscribe CAN
+ frames received by CAN interfaces and to send CAN frames:
+
+ can_rx_register - subscribe CAN frames from a specific interface
+ can_rx_unregister - unsubscribe CAN frames from a specific interface
+ can_send - transmit a CAN frame (optional with local loopback)
+
+ For details see the kerneldoc documentation in net/can/af_can.c or
+ the source code of net/can/raw.c or net/can/bcm.c .
+
+
--- /dev/null
+============================================================================
+
+can-drivers.txt : CAN network drivers
+
+Part of the documentation for the socketCAN subsystem
+
+This file contains:
+
+ 1 CAN network drivers
+ 1.1 general settings
+ 1.2 local loopback of sent frames
+ 1.3 CAN controller hardware filters
+ 1.4 The virtual CAN driver (vcan)
+ 1.5 The CAN network device driver interface
+ 1.5.1 Netlink interface to set/get devices properties
+ 1.5.2 Setting the CAN bit-timing
+ 1.5.3 Starting and stopping the CAN network device
+ 1.6 supported CAN hardware
+
+============================================================================
+
+1. CAN network drivers
+----------------------
+
+ Writing a CAN network device driver is much easier than writing a
+ CAN character device driver. Similar to other known network device
+ drivers you mainly have to deal with:
+
+ - TX: Put the CAN frame from the socket buffer to the CAN controller.
+ - RX: Put the CAN frame from the CAN controller to the socket buffer.
+
+ See e.g. at Documentation/networking/netdevices.txt . The differences
+ for writing CAN network device driver are described below:
+
+ 1.1 general settings
+
+ dev->type = ARPHRD_CAN; /* the netdevice hardware type */
+ dev->flags = IFF_NOARP; /* CAN has no arp */
+
+ dev->mtu = sizeof(struct can_frame);
+
+ The struct can_frame is the payload of each socket buffer in the
+ protocol family PF_CAN.
+
+ 1.2 local loopback of sent frames
+
+ As described in can-sockets.txt (chapter 1.2) the CAN network device
+ driver should support a local loopback functionality similar to the
+ local echo e.g. of tty devices. In this case the driver flag IFF_ECHO
+ has to be set to prevent the PF_CAN core from locally echoing sent
+ frames (aka loopback) as fallback solution:
+
+ dev->flags = (IFF_NOARP | IFF_ECHO);
+
+ 1.3 CAN controller hardware filters
+
+ To reduce the interrupt load on deep embedded systems some CAN
+ controllers support the filtering of CAN IDs or ranges of CAN IDs.
+ These hardware filter capabilities vary from controller to
+ controller and have to be identified as not feasible in a multi-user
+ networking approach. The use of the very controller specific
+ hardware filters could make sense in a very dedicated use-case, as a
+ filter on driver level would affect all users in the multi-user
+ system. The high efficient filter sets inside the PF_CAN core allow
+ to set different multiple filters for each socket separately.
+ Therefore the use of hardware filters goes to the category 'handmade
+ tuning on deep embedded systems'. The author is running a MPC603e
+ @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
+ load without any problems ...
+
+ 1.4 The virtual CAN driver (vcan)
+
+ Similar to the network loopback devices, vcan offers a virtual local
+ CAN interface. A full qualified address on CAN consists of
+
+ - a unique CAN Identifier (CAN ID)
+ - the CAN bus this CAN ID is transmitted on (e.g. can0)
+
+ so in common use cases more than one virtual CAN interface is needed.
+
+ The virtual CAN interfaces allow the transmission and reception of CAN
+ frames without real CAN controller hardware. Virtual CAN network
+ devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ...
+ When compiled as a module the virtual CAN driver module is called vcan.ko
+
+ Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel
+ netlink interface to create vcan network devices. The creation and
+ removal of vcan network devices can be managed with the ip(8) tool:
+
+ - Create a virtual CAN network interface:
+ $ ip link add type vcan
+
+ - Create a virtual CAN network interface with a specific name 'vcan42':
+ $ ip link add dev vcan42 type vcan
+
+ - Remove a (virtual CAN) network interface 'vcan42':
+ $ ip link del vcan42
+
+ 1.5 The CAN network device driver interface
+
+ The CAN network device driver interface provides a generic interface
+ to setup, configure and monitor CAN network devices. The user can then
+ configure the CAN device, like setting the bit-timing parameters, via
+ the netlink interface using the program "ip" from the "IPROUTE2"
+ utility suite. The following chapter describes briefly how to use it.
+ Furthermore, the interface uses a common data structure and exports a
+ set of common functions, which all real CAN network device drivers
+ should use. Please have a look to the SJA1000 or MSCAN driver to
+ understand how to use them. The name of the module is can-dev.ko.
+
+ 1.5.1 Netlink interface to set/get devices properties
+
+ The CAN device must be configured via netlink interface. The supported
+ netlink message types are defined and briefly described in
+ "include/linux/can/netlink.h". CAN link support for the program "ip"
+ of the IPROUTE2 utility suite is avaiable and it can be used as shown
+ below:
+
+ - Setting CAN device properties:
+
+ $ ip link set can0 type can help
+ Usage: ip link set DEVICE type can
+ [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
+ [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
+ phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
+
+ [ loopback { on | off } ]
+ [ listen-only { on | off } ]
+ [ triple-sampling { on | off } ]
+
+ [ restart-ms TIME-MS ]
+ [ restart ]
+
+ Where: BITRATE := { 1..1000000 }
+ SAMPLE-POINT := { 0.000..0.999 }
+ TQ := { NUMBER }
+ PROP-SEG := { 1..8 }
+ PHASE-SEG1 := { 1..8 }
+ PHASE-SEG2 := { 1..8 }
+ SJW := { 1..4 }
+ RESTART-MS := { 0 | NUMBER }
+
+ - Display CAN device details and statistics:
+
+ $ ip -details -statistics link show can0
+ 2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10
+ link/can
+ can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
+ bitrate 125000 sample_point 0.875
+ tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
+ sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
+ clock 8000000
+ re-started bus-errors arbit-lost error-warn error-pass bus-off
+ 41 17457 0 41 42 41
+ RX: bytes packets errors dropped overrun mcast
+ 140859 17608 17457 0 0 0
+ TX: bytes packets errors dropped carrier collsns
+ 861 112 0 41 0 0
+
+ More info to the above output:
+
+ "<TRIPLE-SAMPLING>"
+ Shows the list of selected CAN controller modes: LOOPBACK,
+ LISTEN-ONLY, or TRIPLE-SAMPLING.
+
+ "state ERROR-ACTIVE"
+ The current state of the CAN controller: "ERROR-ACTIVE",
+ "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED"
+
+ "restart-ms 100"
+ Automatic restart delay time. If set to a non-zero value, a
+ restart of the CAN controller will be triggered automatically
+ in case of a bus-off condition after the specified delay time
+ in milliseconds. By default it's off.
+
+ "bitrate 125000 sample_point 0.875"
+ Shows the real bit-rate in bits/sec and the sample-point in the
+ range 0.000..0.999. If the calculation of bit-timing parameters
+ is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the
+ bit-timing can be defined by setting the "bitrate" argument.
+ Optionally the "sample-point" can be specified. By default it's
+ 0.000 assuming CIA-recommended sample-points.
+
+ "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1"
+ Shows the time quanta in ns, propagation segment, phase buffer
+ segment 1 and 2 and the synchronisation jump width in units of
+ tq. They allow to define the CAN bit-timing in a hardware
+ independent format as proposed by the Bosch CAN 2.0 spec (see
+ chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf).
+
+ "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
+ clock 8000000"
+ Shows the bit-timing constants of the CAN controller, here the
+ "sja1000". The minimum and maximum values of the time segment 1
+ and 2, the synchronisation jump width in units of tq, the
+ bitrate pre-scaler and the CAN system clock frequency in Hz.
+ These constants could be used for user-defined (non-standard)
+ bit-timing calculation algorithms in user-space.
+
+ "re-started bus-errors arbit-lost error-warn error-pass bus-off"
+ Shows the number of restarts, bus and arbitration lost errors,
+ and the state changes to the error-warning, error-passive and
+ bus-off state. RX overrun errors are listed in the "overrun"
+ field of the standard network statistics.
+
+ 1.5.2 Setting the CAN bit-timing
+
+ The CAN bit-timing parameters can always be defined in a hardware
+ independent format as proposed in the Bosch CAN 2.0 specification
+ specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2"
+ and "sjw":
+
+ $ ip link set canX type can tq 125 prop-seg 6 \
+ phase-seg1 7 phase-seg2 2 sjw 1
+
+ If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA
+ recommended CAN bit-timing parameters will be calculated if the bit-
+ rate is specified with the argument "bitrate":
+
+ $ ip link set canX type can bitrate 125000
+
+ Note that this works fine for the most common CAN controllers with
+ standard bit-rates but may *fail* for exotic bit-rates or CAN system
+ clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some
+ space and allows user-space tools to solely determine and set the
+ bit-timing parameters. The CAN controller specific bit-timing
+ constants can be used for that purpose. They are listed by the
+ following command:
+
+ $ ip -details link show can0
+ ...
+ sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
+
+ 6.5.3 Starting and stopping the CAN network device
+
+ A CAN network device is started or stopped as usual with the command
+ "ifconfig canX up/down" or "ip link set canX up/down". Be aware that
+ you *must* define proper bit-timing parameters for real CAN devices
+ before you can start it to avoid error-prone default settings:
+
+ $ ip link set canX up type can bitrate 125000
+
+ A device may enter the "bus-off" state if too much errors occurred on
+ 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
+ non-zero value, e.g.:
+
+ $ ip link set canX type can restart-ms 100
+
+ Alternatively, the application may realize the "bus-off" condition
+ by monitoring CAN error frames and do a restart when appropriate with
+ the command:
+
+ $ ip link set canX type can restart
+
+ Note that a restart will also create a CAN error frame (see also
+ can-sockets.txt, chapter 1.4).
+
+ 1.6 Supported CAN hardware
+
+ 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
+ (see overview.txt, chapter 5) there might be further drivers available,
+ also for older kernel versions.
+
--- /dev/null
+============================================================================
+
+can-raw.txt : Raw CAN sockets
+
+Part of the documentation for the socketCAN subsystem
+
+This file contains
+
+ 1 RAW protocol sockets with can_filters (SOCK_RAW)
+ 1.1 RAW socket option CAN_RAW_FILTER
+ 1.2 RAW socket option CAN_RAW_ERR_FILTER
+ 1.3 RAW socket option CAN_RAW_LOOPBACK
+ 1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
+ 1.5 RAW socket returned message flags
+
+============================================================================
+
+1. RAW protocol sockets with can_filters (SOCK_RAW)
+---------------------------------------------------
+
+ Using CAN_RAW sockets is extensively comparable to the commonly
+ known access to CAN character devices. To meet the new possibilities
+ provided by the multi user SocketCAN approach, some reasonable
+ defaults are set at RAW socket binding time:
+
+ - The filters are set to exactly one filter receiving everything
+ - The socket only receives valid data frames (=> no error frames)
+ - The loopback of sent CAN frames is enabled (see overview.txt, chapter 3.2)
+ - The socket does not receive its own sent frames (in loopback mode)
+
+ These default settings may be changed before or after binding the socket.
+ To use the referenced definitions of the socket options for CAN_RAW
+ sockets, include <linux/can/raw.h>.
+
+ 1.1 RAW socket option CAN_RAW_FILTER
+
+ The reception of CAN frames using CAN_RAW sockets can be controlled
+ by defining 0 .. n filters with the CAN_RAW_FILTER socket option.
+
+ The CAN filter structure is defined in include/linux/can.h:
+
+ struct can_filter {
+ canid_t can_id;
+ canid_t can_mask;
+ };
+
+ A filter matches, when
+
+ <received_can_id> & mask == can_id & mask
+
+ which is analogous to known CAN controllers hardware filter semantics.
+ The filter can be inverted in this semantic, when the CAN_INV_FILTER
+ bit is set in can_id element of the can_filter structure. In
+ contrast to CAN controller hardware filters the user may set 0 .. n
+ receive filters for each open socket separately:
+
+ struct can_filter rfilter[2];
+
+ rfilter[0].can_id = 0x123;
+ rfilter[0].can_mask = CAN_SFF_MASK;
+ rfilter[1].can_id = 0x200;
+ rfilter[1].can_mask = 0x700;
+
+ setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, &rfilter, sizeof(rfilter));
+
+ To disable the reception of CAN frames on the selected CAN_RAW socket:
+
+ setsockopt(s, SOL_CAN_RAW, CAN_RAW_FILTER, NULL, 0);
+
+ To set the filters to zero filters is quite obsolete as not read
+ data causes the raw socket to discard the received CAN frames. But
+ having this 'send only' use-case we may remove the receive list in the
+ Kernel to save a little (really a very little!) CPU usage.
+
+ 1.2 RAW socket option CAN_RAW_ERR_FILTER
+
+ As described in overview.txt (chapter 3.4) the CAN interface driver
+ can generate so called Error Frames that can optionally be passed
+ to the user application in the same way as other CAN frames. The possible
+ errors are divided into different error classes that may be filtered
+ using the appropriate error mask. To register for every possible
+ error condition CAN_ERR_MASK can be used as value for the error mask.
+ The values for the error mask are defined in linux/can/error.h .
+
+ can_err_mask_t err_mask = ( CAN_ERR_TX_TIMEOUT | CAN_ERR_BUSOFF );
+
+ setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER,
+ &err_mask, sizeof(err_mask));
+
+ 1.3 RAW socket option CAN_RAW_LOOPBACK
+
+ To meet multi user needs the local loopback is enabled by default
+ (see overview.txt, chapter 3.2, for details). But in some embedded
+ use-cases (e.g. when only one application uses the CAN bus) this
+ loopback functionality can be disabled (separately for each socket):
+
+ int loopback = 0; /* 0 = disabled, 1 = enabled (default) */
+
+ setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback));
+
+ 1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS
+
+ When the local loopback is enabled, all the sent CAN frames are
+ looped back to the open CAN sockets that registered for the CAN
+ frames' CAN-ID on this given interface to meet the multi user
+ needs. The reception of the CAN frames on the same socket that was
+ sending the CAN frame is assumed to be unwanted and therefore
+ disabled by default. This default behaviour may be changed on
+ demand:
+
+ int recv_own_msgs = 1; /* 0 = disabled (default), 1 = enabled */
+
+ setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS,
+ &recv_own_msgs, sizeof(recv_own_msgs));
+
+ 1.5 RAW socket returned message flags
+
+ When using recvmsg() call, the msg->msg_flags may contain following flags:
+
+ MSG_DONTROUTE: set when the received frame was created on the local host.
+
+ MSG_CONFIRM: set when the frame was sent via the socket it is received on.
+ This flag can be interpreted as a 'transmission confirmation' when the
+ CAN driver supports the echo of frames on driver level, see 3.2 and 6.2.
+ In order to receive such messages, CAN_RAW_RECV_OWN_MSGS must be set.
+
--- /dev/null
+============================================================================
+
+can-sockets.txt : general socketCAN API documentation
+
+See can-raw.txt and can-bcm.txt for in-depth documentation
+on RAW and BCM sockets.
+
+Part of the documentation for the socketCAN subsystem
+
+This file contains:
+
+ 1 How to use Socket CAN
+ 1.1 Timestamps
+
+============================================================================
+
+1. How to use Socket CAN
+------------------------
+
+ Like TCP/IP, you first need to open a socket for communicating over a
+ CAN network. Since Socket CAN implements a new protocol family, you
+ need to pass PF_CAN as the first argument to the socket(2) system
+ call. Currently, there are two CAN protocols to choose from, the raw
+ socket protocol and the broadcast manager (BCM). So to open a socket,
+ you would write
+
+ s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
+
+ and
+
+ s = socket(PF_CAN, SOCK_DGRAM, CAN_BCM);
+
+ respectively. After the successful creation of the socket, you would
+ normally use the bind(2) system call to bind the socket to a CAN
+ interface (which is different from TCP/IP due to different addressing
+ - see overview.txt, chapter 3). After binding (CAN_RAW) or connecting
+ (CAN_BCM) the socket, you can read(2) and write(2) from/to the socket
+ or use send(2), sendto(2), sendmsg(2) and the recv* counterpart operations
+ on the socket as usual. There are also CAN specific socket options
+ described below.
+
+ The basic CAN frame structure and the sockaddr structure are defined
+ in include/linux/can.h:
+
+ struct can_frame {
+ canid_t can_id; /* 32 bit CAN_ID + EFF/RTR/ERR flags */
+ __u8 can_dlc; /* data length code: 0 .. 8 */
+ __u8 data[8] __attribute__((aligned(8)));
+ };
+
+ The alignment of the (linear) payload data[] to a 64bit boundary
+ allows the user to define own structs and unions to easily access the
+ CAN payload. There is no given byteorder on the CAN bus by
+ default. A read(2) system call on a CAN_RAW socket transfers a
+ struct can_frame to the user space.
+
+ The sockaddr_can structure has an interface index like the
+ PF_PACKET socket, that also binds to a specific interface:
+
+ struct sockaddr_can {
+ sa_family_t can_family;
+ int can_ifindex;
+ union {
+ /* transport protocol class address info (e.g. ISOTP) */
+ struct { canid_t rx_id, tx_id; } tp;
+
+ /* reserved for future CAN protocols address information */
+ } can_addr;
+ };
+
+ To determine the interface index an appropriate ioctl() has to
+ be used (example for CAN_RAW sockets without error checking):
+
+ int s;
+ struct sockaddr_can addr;
+ struct ifreq ifr;
+
+ s = socket(PF_CAN, SOCK_RAW, CAN_RAW);
+
+ strcpy(ifr.ifr_name, "can0" );
+ ioctl(s, SIOCGIFINDEX, &ifr);
+
+ addr.can_family = AF_CAN;
+ addr.can_ifindex = ifr.ifr_ifindex;
+
+ bind(s, (struct sockaddr *)&addr, sizeof(addr));
+
+ (..)
+
+ To bind a socket to all(!) CAN interfaces the interface index must
+ be 0 (zero). In this case the socket receives CAN frames from every
+ enabled CAN interface. To determine the originating CAN interface
+ the system call recvfrom(2) may be used instead of read(2). To send
+ on a socket that is bound to 'any' interface sendto(2) is needed to
+ specify the outgoing interface.
+
+ Reading CAN frames from a bound CAN_RAW socket (see above) consists
+ of reading a struct can_frame:
+
+ struct can_frame frame;
+
+ nbytes = read(s, &frame, sizeof(struct can_frame));
+
+ if (nbytes < 0) {
+ perror("can raw socket read");
+ return 1;
+ }
+
+ /* paranoid check ... */
+ if (nbytes < sizeof(struct can_frame)) {
+ fprintf(stderr, "read: incomplete CAN frame\n");
+ return 1;
+ }
+
+ /* do something with the received CAN frame */
+
+ Writing CAN frames can be done similarly, with the write(2) system call:
+
+ nbytes = write(s, &frame, sizeof(struct can_frame));
+
+ When the CAN interface is bound to 'any' existing CAN interface
+ (addr.can_ifindex = 0) it is recommended to use recvfrom(2) if the
+ information about the originating CAN interface is needed:
+
+ struct sockaddr_can addr;
+ struct ifreq ifr;
+ socklen_t len = sizeof(addr);
+ struct can_frame frame;
+
+ nbytes = recvfrom(s, &frame, sizeof(struct can_frame),
+ 0, (struct sockaddr*)&addr, &len);
+
+ /* get interface name of the received CAN frame */
+ ifr.ifr_ifindex = addr.can_ifindex;
+ ioctl(s, SIOCGIFNAME, &ifr);
+ printf("Received a CAN frame from interface %s", ifr.ifr_name);
+
+ To write CAN frames on sockets bound to 'any' CAN interface the
+ outgoing interface has to be defined certainly.
+
+ strcpy(ifr.ifr_name, "can0");
+ ioctl(s, SIOCGIFINDEX, &ifr);
+ addr.can_ifindex = ifr.ifr_ifindex;
+ addr.can_family = AF_CAN;
+
+ nbytes = sendto(s, &frame, sizeof(struct can_frame),
+ 0, (struct sockaddr*)&addr, sizeof(addr));
+
+ 1.1 Timestamps
+
+ For applications in the CAN environment it is often of interest an
+ accurate timestamp of the instant a message from CAN bus has been received.
+ Such a timestamp can be read with ioctl(2) after reading a message from
+ the socket. Example:
+
+ struct timeval tv;
+ ioctl(s, SIOCGSTAMP, &tv);
+
+ The timestamp on Linux has a resolution of one microsecond and it is set
+ automatically at the reception of a CAN frame.
+
+ Alternatively the timestamp can be obtained as a control message (cmsg) using
+ the recvmsg() system call. After enabling the timestamps in the cmsg's by
+
+ const int timestamp = 1;
+ setsockopt(s, SOL_SOCKET, SO_TIMESTAMP, ×tamp, sizeof(timestamp));
+
+ the data structures filled by recvmsg() need to be parsed for
+ cmsg->cmsg_type == SO_TIMESTAMP to get the timestamp. See cmsg() manpage.
+
--- /dev/null
+============================================================================
+
+overview.txt : introduction and general concepts
+
+Part of the documentation for the socketCAN subsystem
+
+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 Socket CAN resources
+
+ 5 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 could be provided by a
+ character device, 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
+ 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
+ device without such a (complete) abstraction layer, as is done by most
+ existing drivers. The right way, however, would be to add such a
+ layer with all the functionality like registering for certain CAN
+ IDs, supporting several open file descriptors and (de)multiplexing
+ CAN frames between them, (sophisticated) queueing of CAN frames, and
+ 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
+ networking framework provided by the Linux kernel, and this is what
+ Socket CAN does.
+
+ The use of the networking framework of the Linux kernel is just the
+ natural and most appropriate way to implement CAN for Linux.
+
+3. Socket CAN concept
+---------------------
+
+ As described in chapter 2 it is the main goal of Socket CAN to
+ provide a socket interface to user space applications which builds
+ upon the Linux network layer. In contrast to the commonly known
+ 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.1 receive lists
+
+ The network transparent access of multiple applications leads to the
+ problem that different applications may be interested in the same
+ CAN-IDs from the same CAN network interface. The Socket CAN core
+ module - which implements the protocol family CAN - provides several
+ high efficient receive lists for this reason. If e.g. a user space
+ application opens a CAN RAW socket, the raw protocol module itself
+ requests the (range of) CAN-IDs from the Socket CAN core that are
+ requested by the user. The subscription and unsubscription of
+ CAN-IDs can be done for specific CAN interfaces or for all(!) known
+ CAN interfaces with the can_rx_(un)register() functions provided to
+ CAN protocol modules by the SocketCAN core (see can-core.txt).
+ To optimize the CPU usage at runtime the receive lists are split up
+ into several specific lists per device that match the requested
+ filter complexity for a given use-case.
+
+ 3.2 local loopback of sent frames
+
+ 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 of the sent CAN frames on the appropriate
+ node.
+
+ The Linux network devices (by default) just can handle the
+ transmission and reception of media dependent frames. Due to the
+ arbitration on the CAN bus the transmission of a low prio CAN-ID
+ may be delayed by the reception of a high prio CAN frame. To
+ 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 can-drivers.txt, chapter 1.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 can-raw.txt.
+
+ * = you really like to have this when you're running analyser tools
+ like 'candump' or 'cansniffer' on the (same) node.
+
+ 3.3 network security issues (capabilities)
+
+ The Controller Area Network is a local field bus transmitting only
+ broadcast messages without any routing and security concepts.
+ In the majority of cases the user application has to deal with
+ raw CAN frames. Therefore it might be reasonable NOT to restrict
+ the CAN access only to the user root, as known from other networks.
+ Since the currently implemented CAN_RAW and CAN_BCM sockets can only
+ send and receive frames to/from CAN interfaces it does not affect
+ security of others networks to allow all users to access the CAN.
+ To enable non-root users to access CAN_RAW and CAN_BCM protocol
+ sockets the Kconfig options CAN_RAW_USER and/or CAN_BCM_USER may be
+ selected at kernel compile time.
+
+ 3.4 network problem notifications
+
+ The use of the CAN bus may lead to several problems on the physical
+ and media access control layer. Detecting and logging of these lower
+ layer problems is a vital requirement for CAN users to identify
+ hardware issues on the physical transceiver layer as well as
+ arbitration problems and error frames caused by the different
+ ECUs. The occurrence of detected errors are important for diagnosis
+ and have to be logged together with the exact timestamp. For this
+ reason the CAN interface driver can generate so called Error Frames
+ that can optionally be passed to the user application in the same
+ way as other CAN frames. Whenever an error on the physical layer
+ or the MAC layer is detected (e.g. by the CAN controller) the driver
+ creates an appropriate error frame. Error frames can be requested by
+ the user application using the common CAN filter mechanisms. Inside
+ this filter definition the (interested) type of errors may be
+ selected. The reception of error frames is disabled by default.
+ The format of the CAN error frame is briefly decribed in the Linux
+ header file "include/linux/can/error.h".
+
+4. Socket CAN resources
+-----------------------
+
+ You can find further resources for Socket CAN like user space tools,
+ support for old kernel versions, more drivers, mailing lists, etc.
+ at the BerliOS OSS project website for Socket CAN:
+
+ 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.
+
+5. Credits
+----------
+
+ Oliver Hartkopp (PF_CAN core, filters, drivers, bcm, SJA1000 driver)
+ Urs Thuermann (PF_CAN core, kernel integration, socket interfaces, raw, vcan)
+ Jan Kizka (RT-SocketCAN core, Socket-API reconciliation)
+ Wolfgang Grandegger (RT-SocketCAN core & drivers, Raw Socket-API reviews,
+ CAN device driver interface, MSCAN driver)
+ Robert Schwebel (design reviews, PTXdist integration)
+ Marc Kleine-Budde (design reviews, Kernel 2.6 cleanups, drivers)
+ Benedikt Spranger (reviews)
+ Thomas Gleixner (LKML reviews, coding style, posting hints)
+ Andrey Volkov (kernel subtree structure, ioctls, MSCAN driver)
+ Matthias Brukner (first SJA1000 CAN netdevice implementation Q2/2003)
+ Klaus Hitschler (PEAK driver integration)
+ Uwe Koppe (CAN netdevices with PF_PACKET approach)
+ Michael Schulze (driver layer loopback requirement, RT CAN drivers review)
+ Pavel Pisa (Bit-timing calculation)
+ Sascha Hauer (SJA1000 platform driver)
+ Sebastian Haas (SJA1000 EMS PCI driver)
+ Markus Plessing (SJA1000 EMS PCI driver)
+ Per Dalen (SJA1000 Kvaser PCI driver)
+ Sam Ravnborg (reviews, coding style, kbuild help)
+
projects / socketcan-devel.git / commitdiff