BOROSOFTWAREAll work →
← scantool/diag_l2.h 432 lines
1 finding in this fileD15L184
D15
1#ifndef _DIAG_L2_H_
2#define _DIAG_L2_H_
3
4/*
5 * freediag - Vehicle Diagnostic Utility
6 *
7 *
8 * Copyright (C) 2001 Richard Almeida & Ibex Ltd ([email protected])
9 * 2009-2015 fenugrec
10 *
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 *
25 *************************************************************************
26 *
27 * Diagnostic Software
28 *
29 * - Layer 2 interface definitions
30 */
31
32/*
33 * Structure of definitions of L2 types supported
34 */
35
36/*
37 * Links down to layer 1, there will only be one link per protocol per device,
38 * may be many connections (defined in diag_l2.h) per link
39 */
40#if defined(__cplusplus)
41extern "C" {
42#endif
43
44#include <stdint.h>
45
46#include "diag.h"
47
48struct diag_l0_device;
49
50//diag_l2_link : elements of the diag_l2_links linked-list.
51//An l2 link associates an existing diag_l0_device with
52//one L1 proto and L1 flags.
53struct diag_l2_link {
54 struct diag_l0_device *l2_dl0d; /* Link we're using to talk to lower layer */
55 int l1proto; /* L1 protocol used; see diag_l1.h*/
56
57 uint32_t l1flags; /* L1 flags, filled with diag_l1_getflags in diag_l2_open*/
58 int l1type; /* L1 type (see diag_l1.h): mask of supported L1 protos. */
59
60 struct diag_l2_link *next; /* linked list of all connections */
61
62};
63
64/*
65 * A structure to represent a link to an ECU from here
66 * There is one of these per ECU we are talking to - we may be talking to
67 * more than one ECU per L1 link
68 */
69struct diag_l2_conn {
70 enum {
71 DIAG_L2_STATE_CLOSED, /* Not in use (but not free for anyones use !!) */
72 DIAG_L2_STATE_SENTCONREQ, /* Sent connection request (waiting for response/reject) */
73 DIAG_L2_STATE_OPEN, /* Up and running; only legal state for sending a keepalive request */
74 DIAG_L2_STATE_CLOSING /* sending close request (possibly), waiting for response/timeout */
75 } diag_l2_state; /* State: mainly used by the timer code for keepalive msgs.*/
76
77
78
79 struct diag_l2_link *diag_link; /* info about L1 connection */
80
81 //The following two members are used for periodic keep-alive messages.
82 //tlast is updated when diag_l2_send, _recv,
83 // _request, or _startcomm is called succesfully.
84 unsigned long tlast; // Time of last received || sent data, in ms.
85 unsigned long tinterval; // How long before expiry (usually set by startcomms() once). Set to -1 for "never"
86
87 const struct diag_l2_proto *l2proto; /* Protocol handler */
88
89 flag_type diag_l2_type; /* Type info for this L2 connection; */
90 //will contain init type (slow/mon/fast/etc) and anything else passed
91 //in the flag_type flags argument of l2_startcomms. See DIAG_L2_TYPE_*
92 // defines below.
93
94 // Message timing values.
95 // See SAE-J1979 for general usage;
96 // See ISO-14230-2, ISO-9141-2, SAE-J1850 for specific values;
97 uint16_t diag_l2_p1min;
98 uint16_t diag_l2_p1max; // p1 = byte gap from ECU;
99 uint16_t diag_l2_p2min;
100 uint16_t diag_l2_p2max; // p2 = gap from request to response;
101 uint16_t diag_l2_p2emin;
102 uint16_t diag_l2_p2emax; // p2 in extended mode (ISO14230 "rspPending");
103 uint16_t diag_l2_p3min;
104 uint16_t diag_l2_p3max; // p3 = gap from end of all responses to new request;
105 uint16_t diag_l2_p4min;
106 uint16_t diag_l2_p4max; // p4 = byte gap from tester.
107
108 /* Protocol independent data */
109 void *diag_l2_proto_data;
110
111 /* Speed we're using (baud) */
112 unsigned int diag_l2_speed;
113
114 /*
115 * Physical ECU address (useful if doing logical addressing
116 * only useful if only one responder, should use addressing
117 * from received messages only - some of this may belong in
118 * protocol specific l2 info not in this general structure.
119 */
120 uint8_t diag_l2_physaddr;
121
122 uint8_t diag_l2_destaddr; /* Dest (ECU) */
123 uint8_t diag_l2_srcaddr; /* Source (US) */
124 /*
125 * The following two should be in the protocol specific bit
126 * because they only apply to ISO protocols (move at some time
127 * unless they are useful in other protocols, but I haven't
128 * written any other protocols to find out ;-))
129 * XXX Doing that would require protocol-specific ioctl handlers
130 * to handle DIAG_IOCTL_GET_L2_DATA . It could stay in here for
131 * the moment
132 */
133 uint8_t diag_l2_kb1; /* KB 1, (ISO stuff really) */
134 uint8_t diag_l2_kb2; /* KB 2, (ISO stuff really) */
135
136
137 /* Main linked list of all connections */
138 struct diag_l2_conn *next;
139
140 /* Generic receive buffer */
141 uint8_t rxbuf[MAXRBUF];
142 int rxoffset;
143
144 /* Generic 'msg' holder */
145 struct diag_msg *diag_msg;
146
147};
148
149
150/*
151 * Default ISO 14230 timing values, ms, used as defaults for L2 timeouts
152 */
153#define ISO_14230_TIM_MIN_P1 0 /* Inter byte timing in ECU response */
154#define ISO_14230_TIM_MAX_P1 20
155#define ISO_14230_TIM_MIN_P2 25 /* Time between end of tester request and start of ECU response */
156#define ISO_14230_TIM_MAX_P2 50 /* or between ECU responses */
157#define ISO_14230_TIM_MIN_P2E 25 /* Extended mode for "rspPending" */
158#define ISO_14230_TIM_MAX_P2E 5000 /* Extended mode for "rspPending" */
159#define ISO_14230_TIM_MIN_P3 55 /* Time between end of ECU response and start of new tester request */
160#define ISO_14230_TIM_MAX_P3 5000 /* or time between end of tester request and start of new request if ECU
161 doesn't respond */
162#define ISO_14230_TIM_MIN_P4 5 /* Inter byte time in tester request */
163#define ISO_14230_TIM_MAX_P4 20
164
165
166/*
167 * Application Interface
168 */
169
170/*
171 * Operational L2 protocols; for struct diag_l2_proto->diag_l2_protocol
172 *
173 * NOTE, many of these protocols run on each others physical layer,
174 * for instance J1850 runs on J1850/ISO9141/ISO14230 interfaces
175 */
176#define DIAG_L2_PROT_RAW 0 /* Raw send/receive, ie. L2 pass thru */
177#define DIAG_L2_PROT_ISO9141 1 /* Iso 9141, keywords 08 08 */
178#define DIAG_L2_PROT_NOTUSED 2 /* NOT USED */
179#define DIAG_L2_PROT_ISO14230 3 /* Iso 14230 using appropriate message format */
180#define DIAG_L2_PROT_SAEJ1850 4 /* SAEJ1850 */
181#define DIAG_L2_PROT_CAN 5 /* CAN L2 (is this defined ??) */
182#define DIAG_L2_PROT_VAG 6 /* VAG ISO9141 based protocol */
183#define DIAG_L2_PROT_MB1 7 /* MB protocol 1 */
184#define DIAG_L2_PROT_MB2 8 /* MB protocol 2 */
185#define DIAG_L2_PROT_D2 9 /* Volvo D2 over K-line (kw D3 B0) */
186#define DIAG_L2_PROT_TEST 10 /* Dummy L2 test driver */
187#define DIAG_L2_PROT_MAX 11 /* Maximum number of protocols */
188
189/*
190 * l2proto_list : static-allocated list of supported L2 protocols.
191 * The last item is a NULL ptr to ease iterating.
192 * The array indices don't necessarily match the macros above !
193 */
194
195extern const struct diag_l2_proto *l2proto_list[];
196
197/* *****
198 * Flags for diag_l2_proto_startcomms(...flag_type flags); this is not the same
199 * as the L2 handler flags (diag_l2_proto->diag_l2_flags) above.
200 * Some flags are iso14230-specific and have no meaning with other
201 * L2 protos.
202
203 * The bottom 4 bits are not a bit mask because of how scantool_set.c works, i.e.
204 * "5BAUD" has to be ==0, etc. That's also why we need _INITMASK
205 * "initmode" macros
206 */
207#define DIAG_L2_TYPE_SLOWINIT 0 /* Do 5 Baud init */
208#define DIAG_L2_TYPE_FASTINIT 1 /* Do fast init */
209#define DIAG_L2_TYPE_CARBINIT 2 /* Do CARB init (see ISO14230-2 5.2.4), not implemented. */
210#define DIAG_L2_TYPE_MONINIT 3 /* Don't do any init, just connect to bus */
211#define DIAG_L2_TYPE_INITMASK 0x0F /* Init options mask */
212/*
213 * DIAG_L2_TYPE_FUNCADDR : the address supplied is a functional
214 * address (instead of physical), used for protocols such as ISO14230
215 */
216#define DIAG_L2_TYPE_FUNCADDR 0x10
217
218/*
219 * DIAG_L2_TYPE_PHYSCONN: tell protocols that support both functional and physical
220 * addressing to switch to physical addressing after initial communications
221 * are established (such as ISO14230)
222 */
223//#define DIAG_L2_TYPE_PHYSCONN 0x10 //XXX unused !!
224
225/*
226 * DIAG_L2_IDLE_J1978: tell the ISO14230 code to use SAE J1978 idle
227 * messages (mode 1 PID 0) instead of the ISO "Tester Present"
228 * messages for preventing link timeout
229 *
230 * SAE J1978 is the ODB II ScanTool specification document
231 */
232#define DIAG_L2_IDLE_J1978 0x20
233/*****/
234
235
236
237
238// Special Timeout for so-called "Smart" interfaces;
239// Slower than any protocol, give them time to unframe
240// and checksum the data:
241#define SMART_TIMEOUT 150
242#define RXTOFFSET 20 //ms to add to some diag_l1_recv calls in L2 code
243//In theory this should be 0... It's a band-aid
244//hack to allow system to system variations but NEEDS
245//to be replaced by something runtime-configurable either
246//by the user or some auto-configured feature of the
247//scantool (not implemented yet)
248
249
250
251/* struct diag_l2_data: Used for DIAG_IOCTL_GET_L2_DATA */
252//this isn't used frequently but L3_vag will eventually need it,
253//and cmd_diag_probe uses it to report found ECUs.
254
255struct diag_l2_data {
256 uint8_t physaddr; /* Physical address of ECU */
257 uint8_t kb1; /* Keybyte 0 */
258 uint8_t kb2; /* Keybyte 1 */
259};
260
261
262/*
263 * L2 flags returned from GET_L2_FLAGS
264 * ( for struct diag_l2_proto->diag_l2_flags )
265 */
266
267/*FLAG_FRAMED:
268 * Received data is sent upwards in frames (ie L3 doesn't have to try
269 * and re-frame the data - this is done by timing windows or by the
270 * protocol itself
271 */
272#define DIAG_L2_FLAG_FRAMED 0x01
273
274
275/*
276 * L2 does keep alive to ECU
277 */
278#define DIAG_L2_FLAG_KEEPALIVE 0x04
279
280/*
281 * L2 adds L2 checksum : ALWAYS !! Either it lets L1 handle it, or does it itself.
282 */
283//#define DIAG_L2_FLAG_DOESCKSUM 0x08
284
285/*
286 * L2 startcomms() always suceeds, but only way to find out if
287 * a connection really exists is to send some data and wait for
288 * response. This is useful when connected to car networks such as CAN or J1850
289 * networks as opposed to normal diagnostic type interface such as ISO9141
290 */
291#define DIAG_L2_FLAG_CONNECTS_ALWAYS 0x10
292
293
294
295/*
296 * Internal interface
297 */
298/* Add a msg to a L2 connection */
299void diag_l2_addmsg(struct diag_l2_conn *d_l2_conn, struct diag_msg *msg);
300
301
302/* Public functions */
303
304/** Initialize L2 layer
305 * Must be called once before using any L2 function
306 */
307int diag_l2_init(void);
308
309/** De-initialize L2 layer
310 * opposite of diag_l2_init(); call before unloading / exiting
311 */
312int diag_l2_end(void);
313
314/** Opens a layer 1 device for usage
315
316 * Opens L1 + L0, setting speed etc etc as requested.
317 * @param dl0d L0 device to use
318 * @return 0 if ok
319 */
320int diag_l2_open(struct diag_l0_device *dl0d, int L1protocol);
321
322/** Close an L1 device
323 * @return 0 if ok
324 */
325int diag_l2_close(struct diag_l0_device *);
326
327/** Starts up a session with ECU
328 * @param L2protocol - see diag_l2.h - Type of L2 session (ISO14230,
329 * SAE J1850, etc)
330 * @param flags flags / type: see diag_l2.h
331 * @param bitrate - bit rate to use (bps)
332 * @param target - target initialisation address
333 * @param source - source (tester) initialisation address
334 * @return a new struct diag_l2_conn for representing the connection
335 */
336struct diag_l2_conn *diag_l2_StartCommunications(struct diag_l0_device *, int L2protocol,
337 flag_type flags, unsigned int bitrate, target_type target, source_type source );
338
339/** Stop talking to an ECU;
340 *
341 * @return 0 if ok
342 *
343 * This will undo anything done by l2_startcommunications()
344 */
345int diag_l2_StopCommunications(struct diag_l2_conn *);
346
347/** Send a message (blocking)
348 * @param connection self-explanatory
349 * @param msg same. NOTE, the source address MAY
350 * be ignored, the one specified to StartCommunications
351 * is used for certain L2 protocols
352 * @return 0 on success, <0 on error
353 */
354int diag_l2_send(struct diag_l2_conn *connection, struct diag_msg *msg);
355
356/** Checks if there's anything to receive (blocking).
357 * @param timeout in milliseconds
358 * @param callback Callback routine if read succesful
359 * @param handle : generic handle passed to callback
360 * @return 0 on success
361 */
362int diag_l2_recv(struct diag_l2_conn *connection, unsigned int timeout,
363 void (* rcv_call_back)(void *, struct diag_msg *), void *handle );
364
365
366/** Send a message, and wait the appropriate time for a response.
367 *
368 * This calls the
369 * diag_l2_proto_request() function.
370 * This is important because some L2 protocols such as ISO
371 * will return a "request not yet complete", requiring a retry.
372 * This function deals with that behavior, as well as getting the timeouts and
373 * everything else correct.
374 * It is also coded to return the received message, rather than
375 * use callbacks; this provides a different (but non conflicting)
376 * type of API compared to send / recv calls.
377 *
378 * @param errval Pointer to error result if applicable
379 *
380 * @return a new msg if successful, or NULL + sets *errval if failed.
381 *
382 */
383struct diag_msg *diag_l2_request(struct diag_l2_conn *connection, struct diag_msg *msg,
384 int *errval);
385
386/** Send IOCTL to L2/L1
387 * @param command : IOCTL #, defined in diag.h
388 * @param data optional input/output data
389 * @return 0 if OK, diag error num (<0) on error
390 */
391int diag_l2_ioctl(struct diag_l2_conn *connection, unsigned int cmd, void *data);
392
393
394void diag_l2_timer(void); /* Regular timer routine */
395
396extern int diag_l2_debug;
397extern struct diag_l2_conn *global_l2_conn; //TODO : move in globcfg struct
398
399/** L2 protocol descriptor
400 *
401 * each diag_l2_???.c handler fills in one of these.
402 */
403struct diag_l2_proto {
404 int diag_l2_protocol;
405 const char *shortname;
406 int diag_l2_flags; //see #defines above
407
408 //_StartCommunications: the l2 proto implementation of this should modify
409 //the timing parameters in diag_l2_conn if required; by default in
410 //diag_l2_startcommunications() iso14230 timings are used.
411 int (*diag_l2_proto_startcomms)(struct diag_l2_conn *,
412 flag_type, unsigned int bitrate, target_type, source_type);
413 int (*diag_l2_proto_stopcomms)(struct diag_l2_conn *);
414 //diag_l2_proto_send : returns 0 if ok
415 int (*diag_l2_proto_send)(struct diag_l2_conn *, struct diag_msg *);
416 //diag_l2_proto_recv: ret 0 if ok
417 int (*diag_l2_proto_recv)(struct diag_l2_conn *d_l2_conn,
418 unsigned int timeout, void (*callback)(void *handle, struct diag_msg *msg),
419 void *handle);
420 //diag_l2_proto_request : return a new diag_msg if succesful.
421 struct diag_msg *(*diag_l2_proto_request)(struct diag_l2_conn *,
422 struct diag_msg *, int *);
423 //diag_l2_proto_timeout : this is called periodically (interval
424 //defined in struct diag_l2_conn, usually to send keepalive messages.
425 void (*diag_l2_proto_timeout)(struct diag_l2_conn *);
426};
427
428#if defined(__cplusplus)
429}
430#endif
431#endif /* _DIAG_L2_H_ */
432