From db1cee10eec32efa548697f478c113cb728fae78 Mon Sep 17 00:00:00 2001 From: hartkopp Date: Mon, 22 Nov 2010 19:41:13 +0000 Subject: [PATCH] Added new documentation layout contributed by Daniele Venzano. git-svn-id: svn://svn.berlios.de//socketcan/trunk@1214 030b6a49-0b11-0410-94ab-b0dab22257f2 --- .../Documentation/networking/can/can-bcm.txt | 176 ++++++++++++ .../Documentation/networking/can/can-core.txt | 83 ++++++ .../networking/can/can-drivers.txt | 265 ++++++++++++++++++ .../Documentation/networking/can/can-raw.txt | 126 +++++++++ .../networking/can/can-sockets.txt | 170 +++++++++++ .../Documentation/networking/can/overview.txt | 254 +++++++++++++++++ 6 files changed, 1074 insertions(+) create mode 100644 kernel/2.6/Documentation/networking/can/can-bcm.txt create mode 100644 kernel/2.6/Documentation/networking/can/can-core.txt create mode 100644 kernel/2.6/Documentation/networking/can/can-drivers.txt create mode 100644 kernel/2.6/Documentation/networking/can/can-raw.txt create mode 100644 kernel/2.6/Documentation/networking/can/can-sockets.txt create mode 100644 kernel/2.6/Documentation/networking/can/overview.txt diff --git a/kernel/2.6/Documentation/networking/can/can-bcm.txt b/kernel/2.6/Documentation/networking/can/can-bcm.txt new file mode 100644 index 0000000..066ce55 --- /dev/null +++ b/kernel/2.6/Documentation/networking/can/can-bcm.txt @@ -0,0 +1,176 @@ +============================================================================ + +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 + diff --git a/kernel/2.6/Documentation/networking/can/can-core.txt b/kernel/2.6/Documentation/networking/can/can-core.txt new file mode 100644 index 0000000..beaab9e --- /dev/null +++ b/kernel/2.6/Documentation/networking/can/can-core.txt @@ -0,0 +1,83 @@ +============================================================================ + +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 . + + diff --git a/kernel/2.6/Documentation/networking/can/can-drivers.txt b/kernel/2.6/Documentation/networking/can/can-drivers.txt new file mode 100644 index 0000000..e666e50 --- /dev/null +++ b/kernel/2.6/Documentation/networking/can/can-drivers.txt @@ -0,0 +1,265 @@ +============================================================================ + +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: mtu 16 qdisc pfifo_fast state UP qlen 10 + link/can + can 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: + + "" + 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. + diff --git a/kernel/2.6/Documentation/networking/can/can-raw.txt b/kernel/2.6/Documentation/networking/can/can-raw.txt new file mode 100644 index 0000000..f1b3f46 --- /dev/null +++ b/kernel/2.6/Documentation/networking/can/can-raw.txt @@ -0,0 +1,126 @@ +============================================================================ + +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 . + + 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 + + & 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. + diff --git a/kernel/2.6/Documentation/networking/can/can-sockets.txt b/kernel/2.6/Documentation/networking/can/can-sockets.txt new file mode 100644 index 0000000..f07db19 --- /dev/null +++ b/kernel/2.6/Documentation/networking/can/can-sockets.txt @@ -0,0 +1,170 @@ +============================================================================ + +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. + diff --git a/kernel/2.6/Documentation/networking/can/overview.txt b/kernel/2.6/Documentation/networking/can/overview.txt new file mode 100644 index 0000000..6837172 --- /dev/null +++ b/kernel/2.6/Documentation/networking/can/overview.txt @@ -0,0 +1,254 @@ +============================================================================ + +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) + -- 2.39.2