docs/system/devices/can.rst

   1 CAN Bus Emulation Support
   2 =========================
   3 The CAN bus emulation provides mechanism to connect multiple
   4 emulated CAN controller chips together by one or multiple CAN buses
   5 (the controller device "canbus"  parameter). The individual buses
   6 can be connected to host system CAN API (at this time only Linux
   7 SocketCAN is supported).
   8
   9 The concept of buses is generic and different CAN controllers
  10 can be implemented.
  11
  12 The initial submission implemented SJA1000 controller which
  13 is common and well supported by by drivers for the most operating
  14 systems.
  15
  16 The PCI addon card hardware has been selected as the first CAN
  17 interface to implement because such device can be easily connected
  18 to systems with different CPU architectures (x86, PowerPC, Arm, etc.).
  19
  20 In 2020, CTU CAN FD controller model has been added as part
  21 of the bachelor thesis of Jan Charvat. This controller is complete
  22 open-source/design/hardware solution. The core designer
  23 of the project is Ondrej Ille, the financial support has been
  24 provided by CTU, and more companies including Volkswagen subsidiaries.
  25
  26 The project has been initially started in frame of RTEMS GSoC 2013
  27 slot by Jin Yang under our mentoring  The initial idea was to provide generic
  28 CAN subsystem for RTEMS. But lack of common environment for code and RTEMS
  29 testing lead to goal change to provide environment which provides complete
  30 emulated environment for testing and RTEMS GSoC slot has been donated
  31 to work on CAN hardware emulation on QEMU.
  32
  33 Examples how to use CAN emulation for SJA1000 based boards
  34 ----------------------------------------------------------
  35 When QEMU with CAN PCI support is compiled then one of the next
  36 CAN boards can be selected
  37
  38 (1) CAN bus Kvaser PCI CAN-S (single SJA1000 channel) board. QEMU startup options::
  39
  40     -object can-bus,id=canbus0
  41     -device kvaser_pci,canbus=canbus0
  42
  43 Add "can-host-socketcan" object to connect device to host system CAN bus::
  44
  45     -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus0
  46
  47 (2) CAN bus PCM-3680I PCI (dual SJA1000 channel) emulation::
  48
  49     -object can-bus,id=canbus0
  50     -device pcm3680_pci,canbus0=canbus0,canbus1=canbus0
  51
  52 Another example::
  53
  54     -object can-bus,id=canbus0
  55     -object can-bus,id=canbus1
  56     -device pcm3680_pci,canbus0=canbus0,canbus1=canbus1
  57
  58 (3) CAN bus MIOe-3680 PCI (dual SJA1000 channel) emulation::
  59
  60     -device mioe3680_pci,canbus0=canbus0
  61
  62 The ''kvaser_pci'' board/device model is compatible with and has been tested with
  63 the ''kvaser_pci'' driver included in mainline Linux kernel.
  64 The tested setup was Linux 4.9 kernel on the host and guest side.
  65
  66 Example for qemu-system-x86_64::
  67
  68     qemu-system-x86_64 -accel kvm -kernel /boot/vmlinuz-4.9.0-4-amd64 \
  69       -initrd ramdisk.cpio \
  70       -virtfs local,path=shareddir,security_model=none,mount_tag=shareddir \
  71       -object can-bus,id=canbus0 \
  72       -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus0 \
  73       -device kvaser_pci,canbus=canbus0 \
  74       -nographic -append "console=ttyS0"
  75
  76 Example for qemu-system-arm::
  77
  78     qemu-system-arm -cpu arm1176 -m 256 -M versatilepb \
  79       -kernel kernel-qemu-arm1176-versatilepb \
  80       -hda rpi-wheezy-overlay \
  81       -append "console=ttyAMA0 root=/dev/sda2 ro init=/sbin/init-overlay" \
  82       -nographic \
  83       -virtfs local,path=shareddir,security_model=none,mount_tag=shareddir \
  84       -object can-bus,id=canbus0 \
  85       -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus0 \
  86       -device kvaser_pci,canbus=canbus0,host=can0 \
  87
  88 The CAN interface of the host system has to be configured for proper
  89 bitrate and set up. Configuration is not propagated from emulated
  90 devices through bus to the physical host device. Example configuration
  91 for 1 Mbit/s::
  92
  93   ip link set can0 type can bitrate 1000000
  94   ip link set can0 up
  95
  96 Virtual (host local only) can interface can be used on the host
  97 side instead of physical interface::
  98
  99   ip link add dev can0 type vcan
 100
 101 The CAN interface on the host side can be used to analyze CAN
 102 traffic with "candump" command which is included in "can-utils"::
 103
 104   candump can0
 105
 106 CTU CAN FD support examples
 107 ---------------------------
 108 This open-source core provides CAN FD support. CAN FD drames are
 109 delivered even to the host systems when SocketCAN interface is found
 110 CAN FD capable.
 111
 112 The PCIe board emulation is provided for now (the device identifier is
 113 ctucan_pci). The default build defines two CTU CAN FD cores
 114 on the board.
 115
 116 Example how to connect the canbus0-bus (virtual wire) to the host
 117 Linux system (SocketCAN used) and to both CTU CAN FD cores emulated
 118 on the corresponding PCI card expects that host system CAN bus
 119 is setup according to the previous SJA1000 section::
 120
 121   qemu-system-x86_64 -enable-kvm -kernel /boot/vmlinuz-4.19.52+ \
 122       -initrd ramdisk.cpio \
 123       -virtfs local,path=shareddir,security_model=none,mount_tag=shareddir \
 124       -vga cirrus \
 125       -append "console=ttyS0" \
 126       -object can-bus,id=canbus0-bus \
 127       -object can-host-socketcan,if=can0,canbus=canbus0-bus,id=canbus0-socketcan \
 128       -device ctucan_pci,canbus0=canbus0-bus,canbus1=canbus0-bus \
 129       -nographic
 130
 131 Setup of CTU CAN FD controller in a guest Linux system::
 132
 133   insmod ctucanfd.ko || modprobe ctucanfd
 134   insmod ctucanfd_pci.ko || modprobe ctucanfd_pci
 135
 136   for ifc in /sys/class/net/can* ; do
 137     if [ -e  $ifc/device/vendor ] ; then
 138       if ! grep -q 0x1760 $ifc/device/vendor ; then
 139         continue;
 140       fi
 141     else
 142       continue;
 143     fi
 144     if [ -e  $ifc/device/device ] ; then
 145        if ! grep -q 0xff00 $ifc/device/device ; then
 146          continue;
 147        fi
 148     else
 149       continue;
 150     fi
 151     ifc=$(basename $ifc)
 152     /bin/ip link set $ifc type can bitrate 1000000 dbitrate 10000000 fd on
 153     /bin/ip link set $ifc up
 154   done
 155
 156 The test can run for example::
 157
 158   candump can1
 159
 160 in the guest system and next commands in the host system for basic CAN::
 161
 162   cangen can0
 163
 164 for CAN FD without bitrate switch::
 165
 166   cangen can0 -f
 167
 168 and with bitrate switch::
 169
 170   cangen can0 -b
 171
 172 The test can also be run the other way around, generating messages in the
 173 guest system and capturing them in the host system. Other combinations are
 174 also possible.
 175
 176 Links to other resources
 177 ------------------------
 178
 179  (1) `CAN related projects at Czech Technical University, Faculty of Electrical Engineering <http://canbus.pages.fel.cvut.cz>`_
 180  (2) `Repository with development can-pci branch at Czech Technical University <https://gitlab.fel.cvut.cz/canbus/qemu-canbus>`_
 181  (3) `RTEMS page describing project <https://devel.rtems.org/wiki/Developer/Simulators/QEMU/CANEmulation>`_
 182  (4) `RTLWS 2015 article about the project and its use with CANopen emulation <http://cmp.felk.cvut.cz/~pisa/can/doc/rtlws-17-pisa-qemu-can.pdf>`_
 183  (5) `GNU/Linux, CAN and CANopen in Real-time Control Applications Slides from LinuxDays 2017 (include updated RTLWS 2015 content) <https://www.linuxdays.cz/2017/video/Pavel_Pisa-CAN_canopen.pdf>`_
 184  (6) `Linux SocketCAN utilities <https://github.com/linux-can/can-utils>`_
 185  (7) `CTU CAN FD project including core VHDL design, Linux driver, test utilities etc. <https://gitlab.fel.cvut.cz/canbus/ctucanfd_ip_core>`_
 186  (8) `CTU CAN FD Core Datasheet Documentation <http://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/doc/Datasheet.pdf>`_
 187  (9) `CTU CAN FD Core System Architecture Documentation <http://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/doc/System_Architecture.pdf>`_
 188  (10) `CTU CAN FD Driver Documentation <https://canbus.pages.fel.cvut.cz/ctucanfd_ip_core/doc/linux_driver/build/ctucanfd-driver.html>`_
 189  (11) `Integration with PCIe interfacing for Intel/Altera Cyclone IV based board <https://gitlab.fel.cvut.cz/canbus/pcie-ctu_can_fd>`_