kernel/2.6/Documentation/networking/can/can-drivers.txt

   1 ============================================================================
   2
   3 can-drivers.txt : CAN network drivers
   4
   5 Part of the documentation for the socketCAN subsystem
   6
   7 This file contains:
   8
   9   1 CAN network drivers
  10     1.1 general settings
  11     1.2 local loopback of sent frames
  12     1.3 CAN controller hardware filters
  13     1.4 The virtual CAN driver (vcan)
  14     1.5 The CAN network device driver interface
  15       1.5.1 Netlink interface to set/get devices properties
  16       1.5.2 Setting the CAN bit-timing
  17       1.5.3 Starting and stopping the CAN network device
  18     1.6 supported CAN hardware
  19
  20 ============================================================================
  21
  22 1. CAN network drivers
  23 ----------------------
  24
  25   Writing a CAN network device driver is much easier than writing a
  26   CAN character device driver. Similar to other known network device
  27   drivers you mainly have to deal with:
  28
  29   - TX: Put the CAN frame from the socket buffer to the CAN controller.
  30   - RX: Put the CAN frame from the CAN controller to the socket buffer.
  31
  32   See e.g. at Documentation/networking/netdevices.txt . The differences
  33   for writing CAN network device driver are described below:
  34
  35   1.1 general settings
  36
  37     dev->type  = ARPHRD_CAN; /* the netdevice hardware type */
  38     dev->flags = IFF_NOARP;  /* CAN has no arp */
  39
  40     dev->mtu   = sizeof(struct can_frame);
  41
  42   The struct can_frame is the payload of each socket buffer in the
  43   protocol family PF_CAN.
  44
  45   1.2 local loopback of sent frames
  46
  47   As described in can-sockets.txt (chapter 1.2) the CAN network device
  48   driver should support a local loopback functionality similar to the
  49   local echo e.g. of tty devices. In this case the driver flag IFF_ECHO
  50   has to be set to prevent the PF_CAN core from locally echoing sent
  51   frames (aka loopback) as fallback solution:
  52
  53     dev->flags = (IFF_NOARP | IFF_ECHO);
  54
  55   1.3 CAN controller hardware filters
  56
  57   To reduce the interrupt load on deep embedded systems some CAN
  58   controllers support the filtering of CAN IDs or ranges of CAN IDs.
  59   These hardware filter capabilities vary from controller to
  60   controller and have to be identified as not feasible in a multi-user
  61   networking approach. The use of the very controller specific
  62   hardware filters could make sense in a very dedicated use-case, as a
  63   filter on driver level would affect all users in the multi-user
  64   system. The high efficient filter sets inside the PF_CAN core allow
  65   to set different multiple filters for each socket separately.
  66   Therefore the use of hardware filters goes to the category 'handmade
  67   tuning on deep embedded systems'. The author is running a MPC603e
  68   @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus
  69   load without any problems ...
  70
  71   1.4 The virtual CAN driver (vcan)
  72
  73   Similar to the network loopback devices, vcan offers a virtual local
  74   CAN interface. A full qualified address on CAN consists of
  75
  76   - a unique CAN Identifier (CAN ID)
  77   - the CAN bus this CAN ID is transmitted on (e.g. can0)
  78
  79   so in common use cases more than one virtual CAN interface is needed.
  80
  81   The virtual CAN interfaces allow the transmission and reception of CAN
  82   frames without real CAN controller hardware. Virtual CAN network
  83   devices are usually named 'vcanX', like vcan0 vcan1 vcan2 ...
  84   When compiled as a module the virtual CAN driver module is called vcan.ko
  85
  86   Since Linux Kernel version 2.6.24 the vcan driver supports the Kernel
  87   netlink interface to create vcan network devices. The creation and
  88   removal of vcan network devices can be managed with the ip(8) tool:
  89
  90   - Create a virtual CAN network interface:
  91        $ ip link add type vcan
  92
  93   - Create a virtual CAN network interface with a specific name 'vcan42':
  94        $ ip link add dev vcan42 type vcan
  95
  96   - Remove a (virtual CAN) network interface 'vcan42':
  97        $ ip link del vcan42
  98
  99   1.5 The CAN network device driver interface
 100
 101   The CAN network device driver interface provides a generic interface
 102   to setup, configure and monitor CAN network devices. The user can then
 103   configure the CAN device, like setting the bit-timing parameters, via
 104   the netlink interface using the program "ip" from the "IPROUTE2"
 105   utility suite. The following chapter describes briefly how to use it.
 106   Furthermore, the interface uses a common data structure and exports a
 107   set of common functions, which all real CAN network device drivers
 108   should use. Please have a look to the SJA1000 or MSCAN driver to
 109   understand how to use them. The name of the module is can-dev.ko.
 110
 111   1.5.1 Netlink interface to set/get devices properties
 112
 113   The CAN device must be configured via netlink interface. The supported
 114   netlink message types are defined and briefly described in
 115   "include/linux/can/netlink.h". CAN link support for the program "ip"
 116   of the IPROUTE2 utility suite is avaiable and it can be used as shown
 117   below:
 118
 119   - Setting CAN device properties:
 120
 121     $ ip link set can0 type can help
 122     Usage: ip link set DEVICE type can
 123         [ bitrate BITRATE [ sample-point SAMPLE-POINT] ] |
 124         [ tq TQ prop-seg PROP_SEG phase-seg1 PHASE-SEG1
 125           phase-seg2 PHASE-SEG2 [ sjw SJW ] ]
 126
 127         [ loopback { on | off } ]
 128         [ listen-only { on | off } ]
 129         [ triple-sampling { on | off } ]
 130
 131         [ restart-ms TIME-MS ]
 132         [ restart ]
 133
 134         Where: BITRATE       := { 1..1000000 }
 135                SAMPLE-POINT  := { 0.000..0.999 }
 136                TQ            := { NUMBER }
 137                PROP-SEG      := { 1..8 }
 138                PHASE-SEG1    := { 1..8 }
 139                PHASE-SEG2    := { 1..8 }
 140                SJW           := { 1..4 }
 141                RESTART-MS    := { 0 | NUMBER }
 142
 143   - Display CAN device details and statistics:
 144
 145     $ ip -details -statistics link show can0
 146     2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UP qlen 10
 147       link/can
 148       can <TRIPLE-SAMPLING> state ERROR-ACTIVE restart-ms 100
 149       bitrate 125000 sample_point 0.875
 150       tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1
 151       sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
 152       clock 8000000
 153       re-started bus-errors arbit-lost error-warn error-pass bus-off
 154       41         17457      0          41         42         41
 155       RX: bytes  packets  errors  dropped overrun mcast
 156       140859     17608    17457   0       0       0
 157       TX: bytes  packets  errors  dropped carrier collsns
 158       861        112      0       41      0       0
 159
 160   More info to the above output:
 161
 162     "<TRIPLE-SAMPLING>"
 163     Shows the list of selected CAN controller modes: LOOPBACK,
 164     LISTEN-ONLY, or TRIPLE-SAMPLING.
 165
 166     "state ERROR-ACTIVE"
 167     The current state of the CAN controller: "ERROR-ACTIVE",
 168     "ERROR-WARNING", "ERROR-PASSIVE", "BUS-OFF" or "STOPPED"
 169
 170     "restart-ms 100"
 171     Automatic restart delay time. If set to a non-zero value, a
 172     restart of the CAN controller will be triggered automatically
 173     in case of a bus-off condition after the specified delay time
 174     in milliseconds. By default it's off.
 175
 176     "bitrate 125000 sample_point 0.875"
 177     Shows the real bit-rate in bits/sec and the sample-point in the
 178     range 0.000..0.999. If the calculation of bit-timing parameters
 179     is enabled in the kernel (CONFIG_CAN_CALC_BITTIMING=y), the
 180     bit-timing can be defined by setting the "bitrate" argument.
 181     Optionally the "sample-point" can be specified. By default it's
 182     0.000 assuming CIA-recommended sample-points.
 183
 184     "tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1"
 185     Shows the time quanta in ns, propagation segment, phase buffer
 186     segment 1 and 2 and the synchronisation jump width in units of
 187     tq. They allow to define the CAN bit-timing in a hardware
 188     independent format as proposed by the Bosch CAN 2.0 spec (see
 189     chapter 8 of http://www.semiconductors.bosch.de/pdf/can2spec.pdf).
 190
 191     "sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
 192      clock 8000000"
 193     Shows the bit-timing constants of the CAN controller, here the
 194     "sja1000". The minimum and maximum values of the time segment 1
 195     and 2, the synchronisation jump width in units of tq, the
 196     bitrate pre-scaler and the CAN system clock frequency in Hz.
 197     These constants could be used for user-defined (non-standard)
 198     bit-timing calculation algorithms in user-space.
 199
 200     "re-started bus-errors arbit-lost error-warn error-pass bus-off"
 201     Shows the number of restarts, bus and arbitration lost errors,
 202     and the state changes to the error-warning, error-passive and
 203     bus-off state. RX overrun errors are listed in the "overrun"
 204     field of the standard network statistics.
 205
 206   1.5.2 Setting the CAN bit-timing
 207
 208   The CAN bit-timing parameters can always be defined in a hardware
 209   independent format as proposed in the Bosch CAN 2.0 specification
 210   specifying the arguments "tq", "prop_seg", "phase_seg1", "phase_seg2"
 211   and "sjw":
 212
 213     $ ip link set canX type can tq 125 prop-seg 6 \
 214                 phase-seg1 7 phase-seg2 2 sjw 1
 215
 216   If the kernel option CONFIG_CAN_CALC_BITTIMING is enabled, CIA
 217   recommended CAN bit-timing parameters will be calculated if the bit-
 218   rate is specified with the argument "bitrate":
 219
 220     $ ip link set canX type can bitrate 125000
 221
 222   Note that this works fine for the most common CAN controllers with
 223   standard bit-rates but may *fail* for exotic bit-rates or CAN system
 224   clock frequencies. Disabling CONFIG_CAN_CALC_BITTIMING saves some
 225   space and allows user-space tools to solely determine and set the
 226   bit-timing parameters. The CAN controller specific bit-timing
 227   constants can be used for that purpose. They are listed by the
 228   following command:
 229
 230     $ ip -details link show can0
 231     ...
 232       sja1000: clock 8000000 tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1
 233
 234   6.5.3 Starting and stopping the CAN network device
 235
 236   A CAN network device is started or stopped as usual with the command
 237   "ifconfig canX up/down" or "ip link set canX up/down". Be aware that
 238   you *must* define proper bit-timing parameters for real CAN devices
 239   before you can start it to avoid error-prone default settings:
 240
 241     $ ip link set canX up type can bitrate 125000
 242
 243   A device may enter the "bus-off" state if too much errors occurred on
 244   the CAN bus. Then no more messages are received or sent. An automatic
 245   bus-off recovery can be enabled by setting the "restart-ms" to a
 246   non-zero value, e.g.:
 247
 248     $ ip link set canX type can restart-ms 100
 249
 250   Alternatively, the application may realize the "bus-off" condition
 251   by monitoring CAN error frames and do a restart when appropriate with
 252   the command:
 253
 254     $ ip link set canX type can restart
 255
 256   Note that a restart will also create a CAN error frame (see also
 257   can-sockets.txt, chapter 1.4).
 258
 259   1.6 Supported CAN hardware
 260
 261   Please check the "Kconfig" file in "drivers/net/can" to get an actual
 262   list of the support CAN hardware. On the Socket CAN project website
 263   (see overview.txt, chapter 5) there might be further drivers available,
 264   also for older kernel versions.
 265