docs/can.txt

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