Add README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..3b42be8
--- /dev/null
+++ b/README
@@ -0,0 +1,59 @@
+Examples of using different system calls for sending/receiving CAN frames under Linux
+=====================================================================================
+
+There are two types of programs: candump-* and cansend-*. Candump
+receives the messages from a CAN interface and prints their content to
+stdout. Cansend sends one or more CAN frames to the specified CAN
+interface. Variants of each program differ in which Linux system calls
+they use to accomplish their task.
+
+The syntax of candump commands is:
+
+    candump-xxx <CAN interface>
+
+For example:
+
+    candump-read can0
+
+The syntax of cansend commands is:
+
+    cansend-xxx <CAN interface> <CAN frame>...
+
+For example:
+
+    cansend-write can0 123#4567 321#987654
+
+The individual programs are described below/
+
+- candump-read.c - The simplest possible candump implementation using
+  read() system call.
+
+- candump-recvmmsg.c - Implementation based on recvmmsg() system call.
+  Here, one system call can receive "multiple messages". Therefore, in
+  case of highbandwidth CAN traffic and slow CPU, this can
+  significantly improve system throughput.
+
+- candump-mmap.c - Implementation based on PF_PACKET protocol family
+  and memory mapped ring buffers. The performance is slightly better
+  than of recvmmsg. If needed, reception can be happen completely
+  without any system call, because the kernel automatically stores
+  received CAN frames in memory mapped to the user space.
+
+  Bug: When this is used with a virtual CAN interface (vcan), each
+  message is received two times.
+
+- cansend-write.c - The simplest way to send CAN frames.
+
+- cansend-sendmmsg.c - Sends multiple CAN frames with one system call
+  and thus reducing the overhead. Note that the sendmmsg() system call
+  is only available in Linux 3.0 and later.
+
+- cansend-mmap.c - Implementation based on PF_PACKET protocol family
+  and memory mapped ring buffers. In terms of performance it is
+  similar to sendmmsg().
+
+  Bug: This method does not work with virtual CAN (vcan) interfaces.
+
+More information about these system calls and their performance in the
+context of CAN bus can be found in
+https://rtime.felk.cvut.cz/can/can-syscalls.pdf.