can4linux - the Linux CAN driver
 All Data Structures Files Functions Variables Pages
can4linux - CAN network device driver

The LINUX CAN driver can be used to control the CAN bus (http://www.can-cia.org) connected to a PC running LINUX or embedded LINUX systems using uClinux.Different interface boards and target micro controllers are supported (see TARGET=VARIABLE in Makefile). The most popular interfaces are the old fashioned ISA board AT-CAN-MINI (port GmbH) and CPC-PCI http://www.ems-wuensche.de or PCI-express

This project was born in cooperation with the LINUX LLP Project to control laboratory or automation devices via CAN. It started already in 1995 and is now considered as mature.

Attention
The former and older can4linux version 1.x did support many different interface boards. It was possible to use different kinds of boards at the same time. Up to four boards could be placed in one computer. With this feature it was possible to use /dev/can0 and /dev/can2 for two boards AT-CAN-MINI with SJA1000 and /dev/can1 and /dev/can3 with two CPC-XT equipped with Intel 82527.
Attention: This can4linux version isn't supported anymore !

Instead the new version has to be compiled for the target hardware. It was unlikely in the past that a PC or embedded device was equipped with different CAN controllers.

Virtual CAN
In a special mode which is selected by setting the kernel parameter virtual to true, no hardware at all is needed. The driver implements something like a virtual CAN network, where producer and consumer exchange CAN frames only virtually.
/sbin/insmod can4linux.ko virtual=1

In all these configurations the programmer sees the same driver interface with open(), close(), read(), write() and ioctl() calls ( can_open(), can_close(), can_read(), can_write(), can_ioctl() ).

The driver itself is highly configurable using the /proc interface of the LINUX kernel.

The following listing shows a typical configuration with three boards:

$ grep . /proc/sys/dev/Can/\*
/proc/sys/dev/Can/AccCode: -1 -1 -1 -1
/proc/sys/dev/Can/AccMask: -1 -1 -1 -1
/proc/sys/dev/Can/ArbitrationLost 0 0 0 0
/proc/sys/dev/Can/Base: 800 672 832 896
/proc/sys/dev/Can/Baud: 125 125 125 250
/proc/sys/dev/Can/CAN clock:8000000
/proc/sys/dev/Can/Chipset: SJA1000
/proc/sys/dev/Can/dbgmask: 0
/proc/sys/dev/Can/framelength:8
/proc/sys/dev/Can/IOModel: pppp
/proc/sys/dev/Can/IRQ: 5 7 3 5
/proc/sys/dev/Can/OpenCount: 0(4) 0(4) 0(4) 0(4
/proc/sys/dev/Can/Outc: 250 250 250 0
/proc/sys/dev/Can/Overrun: 0 0 0 0
/proc/sys/dev/Can/RxErr: 0 0 0 0
/proc/sys/dev/Can/RxErrCounter:0 0 0 0
/proc/sys/dev/Can/Speedfactor:1 1 1 1
/proc/sys/dev/Can/Timeout: 100 100 100 100
/proc/sys/dev/Can/Transmitterdelay:100 100 100 100
/proc/sys/dev/Can/TxErr: 0 0 0 0
/proc/sys/dev/Can/TxErrCounter: 0 0 0 0
/proc/sys/dev/Can/version: 4.0_ATCANMINI_PELICAN SVN Revision: 239

This above mentioned full flexibility is not needed in embedded applications. For this applications, a stripped-down version exists. It uses the same programming interface but does the most configurations at compile time. That means especially that only one CAN controller support with a special register access method is compiled into the driver. Actually the only CAN controller supported by this version is the Philips SJA 1000 in both the compatibility mode BasicCAN and the Philips PeliCAN mode (compile time selectable).

The version of can4linux currently available at SourceForge http://sourceforge.net/projects/can4linux is also supporting the Motorola FlexCAN module as ist is implemented on Motorolas ColdFire 5282 CPU, the FlexCAN controllers found on the Freescale ARM i.MX series controllers, the Analog Devices BlackFin DSP with CAN, Atmels ARM AT91SAM9263 with integrated CAN and also Microchips stand alone CAN CAN controller MCP2515 connected via SPI. One version of the SPI controlled MCP2515 is using direct register access to the SPI controller found on Atmels AT91 CPUs. This design was chosen to improve the performance of this special can4linux version. Care has to be taken not to use the Linux SPI driver at the same time. Another possible make target, TARGET)MCP2515SPI, is using the kernels SPI master driver to control the CAN MCP2515.

Since version 3.4.6 can4linux assumes that your distribution uses udev to have the device `/dev/can[0-9]' automatically created. It is usually necessary to change the device access rights set by udev . With the Fedora Core >= 4 or SuSE/novell you can do:

echo 'KERNEL=="[Cc]an*", NAME="%k", MODE="0666"' \
> /etc/udev/rules.d/91-Can.rules

Alternatively create the device inodes in /lib/udev/devices . At system start-up, the contents of that directory is copied to the /dev directory with the same ownership and permissions as the files in /lib/udev/devices.

The driver creates class Can, with information in /sys/class/Can/

See also udev (7)

The following sections are describing the sysctl entries.
AccCode/AccMask
contents of the message acceptance mask and acceptance code registers of 82x200/SJA1000 compatible CAN controllers (see can_ioctl()).
Base
CAN controllers base address for each board. Depending of the IOModel entry that can be a memory or I/O address. (read-only for PCI boards)
Baud
used bit rate for this board in Kbit/s
Chipset
name of the supported CAN chip used with this boards Read only for this version.
IOModel
one letter for each port. Readonly. Read the CAN register access model. The following models are currently supported:
  • b - special mode for the B&R CAN card, two special I/O addresses for register addressing and access
  • f - fast register access, special mode for the 82527 uses memory locations for register addresses (ELIMA)
  • i - indexed access, one address serves as register selector, the next one as register access (MMC_SJA1000)
  • m - memory access, the registers are directly mapped into memory
  • p - port I/O, 80x86 specific I/O address range (AT-CAN-MINI,CTI_CANPRO, KVASER_PCICAN)
  • s - access via SPI (the only CAN controller supported so far is the Microchip MCP2515)
Since version 2.4 the IOModel is set at compile time.
IRQ
used IRQ numbers, one value for each board. (read-only for PCI boards)
Outc
value of the output control register of the CAN controller Since version 2.4 set at compile time. A board specific value is used when the module the first time is loaded. This board specific value can be reloaded by writing the value 0 to Outc .
With the most boards using a Philips SJA1000, by changing the value of the Outc it is possible to inhibit generating the CAN Acknowledge. Using this feature, it is possible to implement a listen only mode. Please refer the CAN controller documentation for more details.
Another way is implementing access to the mode register with an ioctl () call in later can4linux versions.
Overrun
counter for overrun conditions in the CAN controller
RxErr
counter for CAN controller RX error conditions
  • CAN controller RX buffer hardware overflow
RxErrCounter
CAN controllers RX error counter
Timeout
time out value for waiting for a successful transmission
Transmitterdelay
Only in CAN FD mode. Specifies the CAN Transceivers transmitter delay in ns. Transceiver Delay Compensation (TDC).
TxErr
counter for CAN controller TX error conditions
TxErrCounter
CAN controllers TX error counter
dbgMask
if compiled with debugging support, writing a value greater then 0 enables debugging to syslogd . The value is bit coded.
Bit 0 print all debug messages
Bit 1 print function entry message
Bit 2 print function exit message
Bit 3 print if a function branches in two different branches
Bit 4 print debug data statements
version
read only entry containing the drivers version number and hardware acronym
OpenCount
displays for each CAN channel the number of processes using currently the device and in parenthesis the maximum number of processes which can use the device.
framelength
Number of bytes which are used for the data section of the CAN frame. This is typical 8 for classic CAN an 64 for CAN FD frames.
Speedfactor
Only in CAN FD mode. Factor to be used for the bit timing in the optional High Bit Rate section (data phase) of an CAN FD frame. Data type is integer, the default is 1.
CAN errors
In case the driver detects internal or CAN controller related errors it reports this on two ways. The flags field of a received message is used by signaling common CAN errors like ERROR PASSIVE or Buffer overflows. This can be combined with a real received message. Or the driver uses a special error signaling message with an invalid message id 0f 0xFFFF.FFFF together with the flags.

If the driver is using the NXP SJA1000 it is possible to detect CAN error frames caused by bit errors, crc errors, stuff errors, and so on. In this case the driver reports an error signaling message to the read() caller with =xFFFF.FFFF and two data bytes containing the content of the Error Code Register. data[0] = ecc; data[1] = ecc & 0x1f;

This special error diagnosis feature must be enabled at driver load time by setting the module parameter errint .

/sbin/insmod can4linux.ko errint=1
miscellaneous

Since 2010 the driver is hosted at SourceForge. The used svn version number can be obtained by asking /sbin/modinfo.

Please see also at can_ioctl() for some additional descriptions.

For initially writing these sysctl entries after loading the driver (or at any time) a shell script utility does exist. It uses a board configuration file that is written over /proc/sys/dev/Can .

utils/cansetup port.conf

or, like used in the Makefile:

CONFIG := $(shell uname -n)
# load host specific CAN configuration
load:
@echo "Loading etc/$(CONFIG).conf CAN configuration"
utils/cansetup etc/$(CONFIG).conf
echo 0 >/proc/sys/dev/Can/dbgMask

Example *.conf files are located in the etc/ directory.

Note
This documentation was created using the wonderful tool Doxygen http://www.doxygen.org/index.html . Die Dokumentation wurde unter Verwendung von Doxygen http://www.doxygen.org/index.html erstellt