1 ============================================================================
5 Readme file for ISO 15765-2 CAN transport protocol for protocol family CAN
8 * WARNING: This is ALPHA code for discussions and first tests that should
9 * not be used in production environments.
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:
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
19 1 What is ISO-TP for CAN
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
29 3.1 tx_queue_len on real CAN busses (!!!)
30 3.2 State of the Socket API & Discussion
32 1 What is ISO-TP for CAN
33 ------------------------
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.
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
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.
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
55 For the examples below we assume a test setup with two hosts:
64 |------------------------------| CAN bus
67 2.1 isotpsend - send PDUs from stdin to CAN
69 isotpsend gives this help when invoked without any parameters:
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)
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.
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
86 2.2 isotprecv - print received PDU on stdout
88 isotpsend gives this help when invoked without any parameters:
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.)
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.
104 Example (receive ISOTP PDU from Host2 on Host1):
105 isotprecv -s 123 -d 321 -l can1
107 In this example '-l' is set which causes isotprecv to continue listening on
108 the given connection after printing a received PDU.
111 2.3 isotpdump - dump CAN frames with PCI decoding (using CAN_RAW socket)
113 isotpdump gives this help when invoked without any parameters:
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)
120 -a (print data also in ASCII-chars)
121 -t <type> (timestamp: (a)bsolute/(d)elta/(z)ero/(A)bsolute w date)
123 CAN IDs and addresses are given and expected in hexadecimal values.
125 Example (dump CAN Frames on Host1):
126 isotpdump -s 123 -d 321 -c -ta can1
129 2.4 isotpsniffer - dump reassembled ISO-TP PDUs (using CAN_ISOTP socket)
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.
136 isotpsniffer gives this help when invoked without any parameters:
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.)
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)
147 CAN IDs and addresses are given and expected in hexadecimal values.
149 Example (dump reassembled ISO-TP PDUs on Host1):
150 isotpsniffer -s 123 -d 321 -c -ta can1
153 2.5 isotptun - create an IP tunnel over unreliable ISO-TP PDUs
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 ;-)
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.
166 isotptun gives this help when invoked without any parameters:
168 Usage: isotptun [options] <CAN interface>
170 This program creates a Linux tunnel netdevice 'ctunX' and transfers the
171 ethernet frames inside ISO15765-2 (unreliable) datagrams on CAN.
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.)
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.
192 on Host1 run as root:
193 isotptun -s 123 -d 321 -v can1 (this blocks, so use a separate terminal)
195 ifconfig ctun0 123.123.123.1 pointopoint 123.123.123.2 up
197 on Host2 run as root:
198 isotptun -s 321 -d 123 -v can2 (this blocks, so use a separate terminal)
200 ifconfig ctun0 123.123.123.2 pointopoint 123.123.123.1 up
202 Have fun (like in early modem dialup days):
204 ssh user@123.123.123.1
205 scp user@123.123.123.1:myfile.tar.gz .
207 scp get's about 27kByte/s over a 500kbit/s CAN interface.
213 3.1 tx_queue_len on real CAN busses (!!!)
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.
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.:
227 echo 4000 > /sys/class/net/can0/tx_queue_len
230 3.2 State of the Socket API for this Linux CAN ISO-TP implementation
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 ...
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
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'?
247 The application does not know the (so far received) content and therefore
248 gets this completely useless information to do *what* with it?
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:
254 - what is really needed and for what use-case?
255 - how does this fit into standard networking and socket philosophy?
257 Oliver Hartkopp (2008-11-05)