README.isotp

   1 ============================================================================
   2
   3 README.isotp
   4
   5 Readme file for ISO 15765-2 CAN transport protocol for protocol family CAN
   6
   7
   8 * WARNING: This is ALPHA code for discussions and first tests that should
   9 *          not be used in production environments.
  10 *
  11 * In the discussion the Socket-API to the userspace or the ISO-TP socket
  12 * options or the return values we may change! Current behaviour:
  13 *
  14 * - no ISO-TP specific return values are provided to the userspace
  15 * - when a transfer (tx) is on the run the next write() blocks until it's done
  16 * - no support for sending wait frames to the data source in the rx path
  17
  18
  19   1 What is ISO-TP for CAN
  20
  21   2 Tools and Examples
  22     2.1 isotpsend - send PDUs from stdin to CAN
  23     2.2 isotprecv - print received PDU on stdout
  24     2.3 isotpdump - dump CAN frames with PCI decoding (using CAN_RAW socket)
  25     2.4 isotpsniffer - dump reassembled ISO-TP PDUs (using CAN_ISOTP socket)
  26     2.5 isotptun - create an IP tunnel over unreliable ISO-TP PDUs
  27
  28   3 Remarks
  29     3.1 tx_queue_len on real CAN busses (!!!)
  30     3.2 State of the Socket API & Discussion
  31
  32 1 What is ISO-TP for CAN
  33 ------------------------
  34
  35   CAN Transport Protocols offer support for segmented Point-to-Point
  36   communication between CAN nodes via two defined CAN Identifiers.
  37   This protocol driver implements data transfers according ISO 15765-2.
  38
  39   CAN ISO-TP is an unreliable datagram protocol and is implemented like this.
  40   For that reason error indications, like 'dropped PDUs in the receive path due
  41   to wrong SequenceNumbers' are intentionally not supported.
  42   See discussion in section 3.2
  43
  44   Code examples of how to use ISO-TP sockets can be found in the source code
  45   of the available tools described below. The API is still a RFC and will be
  46   described in detail later, when it's finalized.
  47
  48
  49 2 Tools and Examples
  50 --------------------
  51
  52   The source code of these tools can be found in the BerliOS SVN repository
  53   http://developer.berlios.de/svn/?group_id=6475 in trunk/can-utils
  54
  55   For the examples below we assume a test setup with two hosts:
  56
  57          _______          _______
  58         |       |        |       |
  59         | Host1 |        | Host2 |
  60         |       |        |       |
  61         | can1  |        | can2  |
  62         |_______|        |_______|
  63             |                |
  64      |------------------------------| CAN bus
  65
  66
  67   2.1 isotpsend - send PDUs from stdin to CAN
  68
  69   isotpsend gives this help when invoked without any parameters:
  70
  71   Usage: isotpsend [options] <CAN interface>
  72   Options: -s <can_id>  (source can_id. Use 8 digits for extended IDs)
  73            -d <can_id>  (destination can_id. Use 8 digits for extended IDs)
  74            -x <addr>    (extended addressing mode. Use 'any' for all addresses)
  75            -p <byte>    (set and enable padding byte)
  76            -P <mode>    (check padding in FC. (l)ength (c)ontent (a)ll)
  77            -t <time ns> (transmit time in nanosecs)
  78
  79   CAN IDs and addresses are given and expected in hexadecimal values.
  80   The pdu data is expected on STDIN in space separated ASCII hex values.
  81
  82   Example (send ISOTP PDU from Host2 to Host1):
  83   echo 11 22 33 44 55 66 DE AD BE EF | isotpsend -s 321 -d 123 can2
  84
  85
  86   2.2 isotprecv - print received PDU on stdout
  87
  88   isotpsend gives this help when invoked without any parameters:
  89
  90   Usage: isotprecv [options] <CAN interface>
  91   Options: -s <can_id>  (source can_id. Use 8 digits for extended IDs)
  92            -d <can_id>  (destination can_id. Use 8 digits for extended IDs)
  93            -x <addr>    (extended addressing mode.)
  94            -p <byte>    (set and enable padding byte)
  95            -P <mode>    (check padding in SF/CF. (l)ength (c)ontent (a)ll)
  96            -b <bs>      (blocksize. 0 = off)
  97            -m <val>     (STmin in ms/ns. See spec.)
  98            -w <num>     (max. wait frame transmissions.)
  99            -l           (loop: do not exit after pdu receiption.)
 100
 101   CAN IDs and addresses are given and expected in hexadecimal values.
 102   The pdu data is written on STDOUT in space separated ASCII hex values.
 103
 104   Example (receive ISOTP PDU from Host2 on Host1):
 105   isotprecv -s 123 -d 321 -l can1
 106
 107   In this example '-l' is set which causes isotprecv to continue listening on
 108   the given connection after printing a received PDU.
 109
 110
 111   2.3 isotpdump - dump CAN frames with PCI decoding (using CAN_RAW socket)
 112
 113   isotpdump gives this help when invoked without any parameters:
 114
 115   Usage: isotpdump [options] <CAN interface>
 116   Options: -s <can_id> (source can_id. Use 8 digits for extended IDs)
 117            -d <can_id> (destination can_id. Use 8 digits for extended IDs)
 118            -x <addr>   (extended addressing mode. Use 'any' for all addresses)
 119            -c          (color mode)
 120            -a          (print data also in ASCII-chars)
 121            -t <type>   (timestamp: (a)bsolute/(d)elta/(z)ero/(A)bsolute w date)
 122
 123   CAN IDs and addresses are given and expected in hexadecimal values.
 124
 125   Example (dump CAN Frames on Host1):
 126   isotpdump -s 123 -d 321 -c -ta can1
 127
 128
 129   2.4 isotpsniffer - dump reassembled ISO-TP PDUs (using CAN_ISOTP socket)
 130
 131   The difference to isotpdump is, that isotpsniffer opens two CAN_ISOTP
 132   sockets and sets the CAN_ISOTP_LISTEN_MODE flag on both of these sockets.
 133   This causes the ISO-TP protocol driver to reassemble the received data but
 134   not send and flow control frames on the CAN bus.
 135
 136   isotpsniffer gives this help when invoked without any parameters:
 137
 138   Usage: isotpsniffer [options] <CAN interface>
 139   Options: -s <can_id> (source can_id. Use 8 digits for extended IDs)
 140            -d <can_id> (destination can_id. Use 8 digits for extended IDs)
 141            -x <addr>   (extended addressing mode.)
 142            -c          (color mode)
 143            -t <type>   (timestamp: (a)bsolute/(d)elta/(z)ero/(A)bsolute w date)
 144            -f <format> (1 = HEX, 2 = ASCII, 3 = HEX & ASCII - default: 3)
 145            -h <len>    (head: print only first <len> bytes)
 146
 147   CAN IDs and addresses are given and expected in hexadecimal values.
 148
 149   Example (dump reassembled ISO-TP PDUs on Host1):
 150   isotpsniffer -s 123 -d 321 -c -ta can1
 151
 152
 153   2.5 isotptun - create an IP tunnel over unreliable ISO-TP PDUs
 154
 155   The ISO-TP provides an unreliable datagram protocol with PDU sizes up to
 156   4095 bytes. Having Linux tunnel driver in mind creating an IP over ISO-TP
 157   tunnel became obvious - so here it is ;-)
 158
 159   From linux/Documentation/networking/tuntap.txt:
 160   TUN/TAP provides packet reception and transmission for user space programs.
 161   It can be seen as a simple Point-to-Point or Ethernet device, which,
 162   instead of receiving packets from physical media, receives them from
 163   user space program and instead of sending packets via physical media
 164   writes them to the user space program.
 165
 166   isotptun gives this help when invoked without any parameters:
 167
 168   Usage: isotptun [options] <CAN interface>
 169
 170   This program creates a Linux tunnel netdevice 'ctunX' and transfers the
 171   ethernet frames inside ISO15765-2 (unreliable) datagrams on CAN.
 172
 173   Options: -s <can_id>  (source can_id. Use 8 digits for extended IDs)
 174            -d <can_id>  (destination can_id. Use 8 digits for extended IDs)
 175            -x <addr>    (extended addressing mode.)
 176            -p <byte>    (padding byte rx path)
 177            -q <byte>    (padding byte tx path)
 178            -P <mode>    (check padding. (l)ength (c)ontent (a)ll)
 179            -t <time ns> (transmit time in nanosecs)
 180            -b <bs>      (blocksize. 0 = off)
 181            -m <val>     (STmin in ms/ns. See spec.)
 182            -w <num>     (max. wait frame transmissions.)
 183            -h           (half duplex mode.)
 184            -v           (verbose mode. Print symbols for tunneled msgs.)
 185
 186   CAN IDs and addresses are given and expected in hexadecimal values.
 187   Use e.g. 'ifconfig ctun0 123.123.123.1 pointopoint 123.123.123.2 up'
 188   to create a point-to-point IP connection on CAN.
 189
 190   Example:
 191
 192   on Host1 run as root:
 193   isotptun -s 123 -d 321 -v can1 (this blocks, so use a separate terminal)
 194
 195   ifconfig ctun0 123.123.123.1 pointopoint 123.123.123.2 up
 196
 197   on Host2 run as root:
 198   isotptun -s 321 -d 123 -v can2 (this blocks, so use a separate terminal)
 199
 200   ifconfig ctun0 123.123.123.2 pointopoint 123.123.123.1 up
 201
 202   Have fun (like in early modem dialup days):
 203   ping 123.123.123.1
 204   ssh user@123.123.123.1
 205   scp user@123.123.123.1:myfile.tar.gz .
 206
 207   scp get's about 27kByte/s over a 500kbit/s CAN interface.
 208
 209
 210 3 Remarks
 211 ---------
 212
 213   3.1 tx_queue_len on real CAN busses (!!!)
 214
 215   The blocksize (BS) splits the CAN frame stream into chunks that need to be
 216   acknowledged on the receiver side with a flow control frame. In the case
 217   the blocksize is set to zero the protocol does not wait for flow control
 218   frames and sends all the CAN frames for the ISO-TP PDU in one burst.
 219
 220   In the case of a 4095 bytes PDU the protocol driver must create 586(!)
 221   CAN frames, that are pushed into the CAN network device. This is no problem
 222   with virtual CAN devices (vcan) but for real CAN devices with real bus
 223   timings. Even though the frame_txtime (N_As/N_Ar) can be set in the ISO-TP
 224   socket options, it is recommended to have an appropriate tx queue available
 225   in the CAN driver, e.g.:
 226
 227   echo 4000 > /sys/class/net/can0/tx_queue_len
 228
 229
 230   3.2 State of the Socket API for this Linux CAN ISO-TP implementation
 231
 232   Implementing transport protocol drivers in userspace on top of a CAN_RAW
 233   socket is possible but has massive drawbacks for fullfilling timing
 234   constrains and multi-user handling. Implementing a CAN transport protocol
 235   inside the Kernel brings different requirements, as ...
 236
 237   - it needs to fit into a standard socket API
 238   - datagram sockets should always behave similar (e.g. like UDP/IP)
 239   - reduce user interaction to a minimal absolutely required level
 240   - reduce user programming interface to a minimal absolutely required level
 241
 242   In the real world applications using unreliable datagram protocols recognize
 243   problems via timeouts. So do ISO-TP applications. So the questions is:
 244   What does it help for the application to know, that someone 'dropped a PDU
 245   in the receive path due to wrong SequenceNumbers'?
 246
 247   The application does not know the (so far received) content and therefore
 248   gets this completely useless information to do *what* with it?
 249
 250   From current applications perspective the things that have not been
 251   implemented have not been required so far. So this might become the
 252   discussion upon this implementation:
 253
 254   - what is really needed and for what use-case?
 255   - how does this fit into standard networking and socket philosophy?
 256
 257 Oliver Hartkopp (2008-11-05)