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 for it but at this time only SJA1000 chip
  12 controller is implemented.
  13
  14 The PCI addon card hardware has been selected as the first CAN
  15 interface to implement because such device can be easily connected
  16 to systems with different CPU architectures (x86, PowerPC, ARM, etc.).
  17
  18 The project has been initially started in frame of RTEMS GSoC 2013
  19 slot by Jin Yang under our mentoring  The initial idea was to provide generic
  20 CAN subsystem for RTEMS. But lack of common environment for code and RTEMS
  21 testing lead to goal change to provide environment which provides complete
  22 emulated environment for testing and RTEMS GSoC slot has been donated
  23 to work on CAN hardware emulation on QEMU.
  24
  25 Examples how to use CAN emulation
  26 =================================
  27
  28 When QEMU with CAN PCI support is compiled then one of the next
  29 CAN boards can be selected
  30
  31  (1) CAN bus Kvaser PCI CAN-S (single SJA1000 channel) boad. QEMU startup options
  32     -object can-bus,id=canbus0
  33     -device kvaser_pci,canbus=canbus0
  34     Add "can-host-socketcan" object to connect device to host system CAN bus
  35     -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus0
  36
  37  (2) CAN bus PCM-3680I PCI (dual SJA1000 channel) emulation
  38     -object can-bus,id=canbus0
  39     -device pcm3680_pci,canbus0=canbus0,canbus1=canbus0
  40
  41  another example:
  42     -object can-bus,id=canbus0
  43     -object can-bus,id=canbus1
  44     -device pcm3680_pci,canbus0=canbus0,canbus1=canbus1
  45
  46  (3) CAN bus MIOe-3680 PCI (dual SJA1000 channel) emulation
  47     -device mioe3680_pci,canbus0=canbus0
  48
  49
  50 The ''kvaser_pci'' board/device model is compatible with and has been tested with
  51 ''kvaser_pci'' driver included in mainline Linux kernel.
  52 The tested setup was Linux 4.9 kernel on the host and guest side.
  53 Example for qemu-system-x86_64:
  54
  55     qemu-system-x86_64 -accel kvm -kernel /boot/vmlinuz-4.9.0-4-amd64 \
  56       -initrd ramdisk.cpio \
  57       -virtfs local,path=shareddir,security_model=none,mount_tag=shareddir \
  58       -object can-bus,id=canbus0 \
  59       -object can-host-socketcan,id=canhost0,if=can0,canbus=canbus0 \
  60       -device kvaser_pci,canbus=canbus0 \
  61       -nographic -append "console=ttyS0"
  62
  63 Example for qemu-system-arm:
  64
  65     qemu-system-arm -cpu arm1176 -m 256 -M versatilepb \
  66       -kernel kernel-qemu-arm1176-versatilepb \
  67       -hda rpi-wheezy-overlay \
  68       -append "console=ttyAMA0 root=/dev/sda2 ro init=/sbin/init-overlay" \
  69       -nographic \
  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,host=can0 \
  74
  75 The CAN interface of the host system has to be configured for proper
  76 bitrate and set up. Configuration is not propagated from emulated
  77 devices through bus to the physical host device. Example configuration
  78 for 1 Mbit/s
  79
  80   ip link set can0 type can bitrate 1000000
  81   ip link set can0 up
  82
  83 Virtual (host local only) can interface can be used on the host
  84 side instead of physical interface
  85
  86   ip link add dev can0 type vcan
  87
  88 The CAN interface on the host side can be used to analyze CAN
  89 traffic with "candump" command which is included in "can-utils".
  90
  91   candump can0
  92
  93 Links to other resources
  94 ========================
  95
  96  (1) Repository with development branch can-pci at Czech Technical University
  97      https://gitlab.fel.cvut.cz/canbus/qemu-canbus
  98  (2) GitHub repository with can-pci and our other changes included
  99      https://gitlab.fel.cvut.cz/canbus/qemu-canbus
 100  (3) RTEMS page describing project
 101      https://devel.rtems.org/wiki/Developer/Simulators/QEMU/CANEmulation
 102  (4) RTLWS 2015 article about the project and its use with CANopen emulation
 103      http://rtime.felk.cvut.cz/publications/public/rtlws2015-qemu-can.pdf
 104      Slides
 105      http://rtime.felk.cvut.cz/publications/public/rtlws2015-qemu-can-slides.pdf
 106  (5) Linux SocketCAN utilities
 107      https://github.com/linux-can/can-utils/