unified MX27, MX25, MX37 trees
[karo-tx-redboot.git] / packages / io / can / v2_0 / include / canio.h
1 #ifndef CYGONCE_CANIO_H
2 #define CYGONCE_CANIO_H
3 // ====================================================================
4 //
5 //      canio.h
6 //
7 //      Device I/O 
8 //
9 // ====================================================================
10 //####ECOSGPLCOPYRIGHTBEGIN####
11 // -------------------------------------------
12 // This file is part of eCos, the Embedded Configurable Operating System.
13 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
14 //
15 // eCos is free software; you can redistribute it and/or modify it under
16 // the terms of the GNU General Public License as published by the Free
17 // Software Foundation; either version 2 or (at your option) any later version.
18 //
19 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
20 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
21 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
22 // for more details.
23 //
24 // You should have received a copy of the GNU General Public License along
25 // with eCos; if not, write to the Free Software Foundation, Inc.,
26 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
27 //
28 // As a special exception, if other files instantiate templates or use macros
29 // or inline functions from this file, or you compile this file and link it
30 // with other works to produce a work based on this file, this file does not
31 // by itself cause the resulting work to be covered by the GNU General Public
32 // License. However the source code for this file must still be made available
33 // in accordance with section (3) of the GNU General Public License.
34 //
35 // This exception does not invalidate any other reasons why a work based on
36 // this file might be covered by the GNU General Public License.
37 //
38 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
39 // at http://sources.redhat.com/ecos/ecos-license/
40 // -------------------------------------------
41 //####ECOSGPLCOPYRIGHTEND####
42 // ====================================================================
43 //#####DESCRIPTIONBEGIN####
44 //
45 // Author(s):    Uwe Kindler
46 // Contributors: gthomas
47 // Date:         2005-05-12
48 // Purpose:      Special support for CAN I/O devices
49 // Description:
50 //
51 //####DESCRIPTIONEND####
52 //
53 // ====================================================================
54
55
56 //===========================================================================
57 //                               INCLUDES
58 //===========================================================================
59 #include <pkgconf/system.h>
60 #include <pkgconf/io_can.h>
61 #include <pkgconf/hal.h>
62 #include <cyg/infra/cyg_type.h>
63 #include <cyg/io/config_keys.h>
64
65
66 #ifdef __cplusplus
67 extern "C" {
68 #endif
69
70
71 //===========================================================================
72 //                                DATA TYPES
73 //===========================================================================
74
75 //
76 // Supported baud rates
77 //
78 typedef enum {
79     CYGNUM_CAN_KBAUD_10 = 1,
80     CYGNUM_CAN_KBAUD_20,
81     CYGNUM_CAN_KBAUD_50,
82     CYGNUM_CAN_KBAUD_100,
83     CYGNUM_CAN_KBAUD_125,
84     CYGNUM_CAN_KBAUD_250,
85     CYGNUM_CAN_KBAUD_500,
86     CYGNUM_CAN_KBAUD_800,
87     CYGNUM_CAN_KBAUD_1000,
88     CYGNUM_CAN_KBAUD_AUTO, // automatic detection of baudrate (if supported by hardware)
89 } cyg_can_baud_rate_t;
90 #define CYGNUM_CAN_KBAUD_MIN CYGNUM_CAN_KBAUD_10 
91 #define CYGNUM_CAN_KBAUD_MAX CYGNUM_CAN_KBAUD_1000
92
93
94 // Note: two levels of macro are required to get proper expansion.
95 #define _CYG_CAN_BAUD_RATE(n) CYGNUM_CAN_KBAUD_##n
96 #define CYG_CAN_BAUD_RATE(n) _CYG_CAN_BAUD_RATE(n)
97
98 //
99 // Event types for received events. Not all event types are supported by each CAN
100 // hardware but normally these events should cover the most common CAN events
101 // that may occur. A combination of the event type values is allowed.
102 //
103 typedef enum 
104 {
105     CYGNUM_CAN_EVENT_RX                  = 0x0001, // message received
106     CYGNUM_CAN_EVENT_TX                  = 0x0002, // mesage transmitted
107     CYGNUM_CAN_EVENT_WARNING_RX          = 0x0004, // tx error counter (TEC) reached warning level (>96)
108     CYGNUM_CAN_EVENT_WARNING_TX          = 0x0008, // rx error counter (REC) reached warning level (>96)
109     CYGNUM_CAN_EVENT_ERR_PASSIVE         = 0x0010, // CAN "error passive" occured
110     CYGNUM_CAN_EVENT_BUS_OFF             = 0x0020, // CAN "bus off" error occured
111     CYGNUM_CAN_EVENT_OVERRUN_RX          = 0x0040, // overrun in RX queue or hardware occured
112     CYGNUM_CAN_EVENT_OVERRUN_TX          = 0x0080, // overrun in TX queue occured
113     CYGNUM_CAN_EVENT_CAN_ERR             = 0x0100, // a CAN bit or frame error occured
114     CYGNUM_CAN_EVENT_LEAVING_STANDBY     = 0x0200, // CAN hardware leaves standby / power don mode or is waked up
115     CYGNUM_CAN_EVENT_ENTERING_STANDBY    = 0x0400, // CAN hardware enters standby / power down mode
116     CYGNUM_CAN_EVENT_ARBITRATION_LOST    = 0x0800, // arbitration lost
117     CYGNUM_CAN_EVENT_FILTER_ERR          = 0x1000, // CAN message filter / acceptance filter error
118     CYGNUM_CAN_EVENT_PHY_FAULT           = 0x2000, // General failure of physical layer detected (if supported by hardware)
119     CYGNUM_CAN_EVENT_PHY_H               = 0x4000, // Fault on CAN-H detected (Low Speed CAN)
120     CYGNUM_CAN_EVENT_PHY_L               = 0x8000, // Fault on CAN-L detected (Low Speed CAN)
121 } cyg_can_event_flags;
122
123 //
124 // State of CAN controller
125 //
126 typedef enum e_cyg_can_state
127 {
128     CYGNUM_CAN_STATE_ACTIVE,       // CAN controller is active, no errors
129     CYGNUM_CAN_STATE_STOPPED,      // CAN controller is in stopped mode
130     CYGNUM_CAN_STATE_STANDBY,      // CAN controller is in Sleep mode
131     CYGNUM_CAN_STATE_BUS_WARN,     // CAN controller is active, warning level is reached
132     CYGNUM_CAN_STATE_ERR_PASSIVE,  // CAN controller went into error passive mode
133     CYGNUM_CAN_STATE_BUS_OFF,      // CAN controller went into bus off mode
134     CYGNUM_CAN_STATE_PHY_FAULT,    // General failure of physical layer detected (if supported by hardware)
135     CYGNUM_CAN_STATE_PHY_H,        // Fault on CAN-H detected (Low Speed CAN)
136     CYGNUM_CAN_STATE_PHY_L,        // Fault on CAN-L detected (Low Speed CAN)
137     CYGNUM_CAN_STATE_CONFIG,       // CAN controller is in configuration state
138 } cyg_can_state;
139
140 //
141 // Identifiers for operating mode of the CAN controller.
142 //
143 typedef enum e_cyg_can_mode
144 {
145     CYGNUM_CAN_MODE_STOP,   // set controller into stop mode
146     CYGNUM_CAN_MODE_START,  // set controller into operational mode
147     CYGNUM_CAN_MODE_STANDBY,// set controller into standby / sleep mode
148     CYGNUM_CAN_MODE_CONFIG  // set controller and driver into a state where it is safe to add/delete message buffers
149 } cyg_can_mode;
150
151 //
152 // Type of CAN identifier. 
153 //
154 typedef enum e_cyg_can_id_type
155 {
156     CYGNUM_CAN_ID_STD = 0x00, // standard ID 11 Bit
157     CYGNUM_CAN_ID_EXT = 0x01  // extended ID 29 Bit
158 } cyg_can_id_type;
159
160 //
161 // Type of CAN frame
162 //
163 typedef enum e_cyg_can_frame_type
164 {
165     CYGNUM_CAN_FRAME_DATA = 0x00, // CAN data frame
166     CYGNUM_CAN_FRAME_RTR  = 0x01  // CAN remote transmission request
167 } cyg_can_frame_type;
168
169 //
170 // Message buffer configuration identifier - we do not use an enum here so that
171 // a specific device driver can add its own configuration identifier
172 //
173 typedef cyg_uint8 cyg_can_msgbuf_cfg_id;
174 #define CYGNUM_CAN_MSGBUF_RESET_ALL         0 // no message will be received, all remote buffers deleted
175 #define CYGNUM_CAN_MSGBUF_RX_FILTER_ALL     1 // cfg driver for reception of all can messges
176 #define CYGNUM_CAN_MSGBUF_RX_FILTER_ADD     2 // add single message filter
177 #define CYGNUM_CAN_MSGBUF_REMOTE_BUF_ADD    3 // add new remote response buffer
178 #define CYGNUM_CAN_MSGBUF_REMOTE_BUF_WRITE  4 // store data into existing remote buffer (remote buf handle required)
179
180
181 //
182 // CAN message data - this union is a container for the 8 data bytes of a can
183 // message and the union is alway part of a can message - no matter if this type
184 // is defined by generic CAN layer or by CAN hardware device driver
185 //
186 typedef union u_cyg_can_msg_data
187 {
188     cyg_uint8  bytes[8];    // byte access (array of 8 bytes)
189     cyg_uint16 words[4];    // word access (array of 4 words)
190     cyg_uint32 dwords[2];   // double word access (array of 2 dwords)
191 } cyg_can_msg_data;
192
193 //
194 // CAN message type for transport or transmit of CAN messages 
195 // The message data is a union. This enables byte, word and dword access and
196 // also ensures a 4 byte alignment of the message data
197 //
198 typedef struct st_cyg_can_message
199 {
200     cyg_uint32          id;     // 11 Bit or 29 Bit CAN identifier - cyg_can_id_type 
201     cyg_can_msg_data    data;   // CAN data (8 data bytes)
202     cyg_can_id_type     ext;    // CYGNUM_CAN_ID_STD = 11 Bit CAN id, CYGNUM_CAN_ID_EXT = 29 Bit CAN id
203     cyg_can_frame_type  rtr;    // CYGNUM_CAN_FRAME_DATA = data frame, CYGNUM_CAN_FRAME_RTR = remote transmission request
204     cyg_uint8           dlc;    // data length code (number of bytes (0 - 8) containing valid data
205 } cyg_can_message;
206
207 //
208 // CAN event type for reception of CAN events from driver. CAN events may be
209 // a received CAN message or any other status information like tx msg or
210 // arbitration lost
211 //
212 typedef struct cyg_can_event_st
213 {
214     cyg_uint32      timestamp;
215     cyg_can_message msg;
216     cyg_uint16      flags;     
217 } cyg_can_event;
218
219 //
220 // CAN configuration - at the moment there is only one data member but we are
221 // prepared for future enhancements
222 //
223 typedef struct cyg_can_info_st {
224     cyg_can_baud_rate_t   baud;
225 } cyg_can_info_t;
226
227
228 #define CYG_CAN_INFO_INIT(_baud) \
229   { _baud}
230
231 //
232 // buffer configuration - bufsize and count for tx are the number of messages
233 // and for rx the number of events
234 //
235 typedef struct cyg_can_buf_info_st
236 {  
237     cyg_uint32 rx_bufsize; 
238     cyg_uint32 rx_count;
239     cyg_uint32 tx_bufsize;
240     cyg_uint32 tx_count;
241 } cyg_can_buf_info_t;
242
243 //
244 // Message box configuration
245 //
246 typedef struct cyg_can_msgbox_info_st
247 {
248     cyg_uint16 count;    // number of message buffers available for this device
249     cyg_uint16 free;     // number of free message buffers
250 } cyg_can_msgbuf_info;
251
252
253 //
254 // Timeout configuration
255 //
256 typedef struct cyg_can_timeout_info_st
257 {
258     cyg_uint32 rx_timeout; 
259     cyg_uint32 tx_timeout;
260 } cyg_can_timeout_info_t;
261
262
263 //
264 // this data type defines a handle to a message buffer or message box
265 // of the CAN hardware device
266 //
267 typedef cyg_int32 cyg_can_msgbuf_handle;
268
269
270 //
271 // structure for configuration of message buffers
272 //
273 typedef struct cyg_can_msgbox_cfg_st
274 {
275     cyg_can_msgbuf_cfg_id  cfg_id; // configuration id - cfg. what to do with message buffer
276     cyg_can_msgbuf_handle  handle; // handle to message buffer
277     cyg_can_message        msg;    // CAN message - for configuration of buffer
278 } cyg_can_msgbuf_cfg;
279
280 //
281 // this data type defines a CAN message filter. It consits
282 // of a handle to a message box or message buffer and a CAN message.
283 // For the filtering only the id and the ext field of the CAN message are
284 // important. The values of the other fields doesn't matter
285 //
286 typedef cyg_can_msgbuf_cfg cyg_can_filter;
287
288 //
289 // this data type defines a remote buffer. It consits
290 // of a handle to a message box or message buffer and the message data
291 // to send on reception of a remote request
292 //
293 typedef cyg_can_msgbuf_cfg cyg_can_remote_buf;
294
295 //
296 // Values for the handle field of the cyg_can_rtr_buf, cyg_can_filter and
297 // cyg_can_msgbuf_cfg data structure
298 //
299 #define CYGNUM_CAN_MSGBUF_NA    -0x01 // no free message buffer available
300
301
302 //
303 // The Hardware Description Interface provides a method to gather information
304 // about the CAN hardware and the functionality of the driver. For
305 // this purpose the following structure is defined:
306 //
307 // Support flags:
308 // |   7   |   6   |   5   |   4   |   3    |   2   |   1   |   0    |
309 // +-------+-------+-------+-------+--------+-------+-------+--------+
310 // | res   |  res  |  res  |timest.|autobaud|FullCAN|   Frametype    |
311 //
312 typedef struct cyg_can_hdi_st
313 {
314     cyg_uint8 support_flags;
315     cyg_uint8 controller_type;
316 } cyg_can_hdi;
317  
318 //
319 // Bit 0 and Bit 1 of the structure member support_flags describe the
320 // possibities of the CAN controller. The following values are defined: 
321 //
322 #define CYGNUM_CAN_HDI_FRAMETYPE_STD           0x00 // standard frame (11-bit identifier), 2.0A
323 #define CYGNUM_CAN_HDI_FRAMETYPE_EXT_PASSIVE   0x01 // extended frame (29-bit identifier), 2.0B passive
324 #define CYGNUM_CAN_HDI_FRAMETYPE_EXT_ACTIVE    0x02 // extended frame (29-bit identifier), 2.0B active
325 #define CYGNUM_CAN_HDI_FULLCAN                 0x04 // controller supports more than one receive and transmit buffer
326 #define CYGNUM_CAN_HDI_AUTBAUD                 0x08 // driver supports automatic baudrate detection
327 #define CYGNUM_CAN_HDI_TIMESTAMP               0x10 // driver supports timestamps
328
329
330 //
331 // Callback configuration structure.
332 //
333
334 typedef void (*cyg_can_event_cb_t)(cyg_uint16, CYG_ADDRWORD);
335 //
336 // flag_mask should be set with a combination of CYGNUM_CAN_EVENT_* flags.
337 // If one of these events happens, the callback function will be called,
338 // with the actually event flags passed as a parameter.
339 //
340 typedef struct cyg_can_callback_cfg_st
341 {
342     cyg_can_event_cb_t callback_func;              // callback function
343     cyg_uint16  flag_mask;                         // flags mask
344     CYG_ADDRWORD data;                             // data passed to callback
345 } cyg_can_callback_cfg;
346
347
348 //===========================================================================
349 //                      CAN MESSAGE ACCESS MACROS
350 //
351 // An application should not access a cyg_can_message directly instead it
352 // should use these macros for all manipulations to a CAN message.
353 //===========================================================================
354
355 //---------------------------------------------------------------------------
356 // Frame type macros
357 //
358 #define CYG_CAN_MSG_SET_FRAME_TYPE(_msg_, _type_)  ((_msg_).rtr = (_type_))
359 #define CYG_CAN_MSG_GET_FRAME_TYPE(_msg_)          ((_msg_).rtr)
360 #define CYG_CAN_MSG_SET_RTR(_msg_)                 ((_msg_).rtr = CYGNUM_CAN_FRAME_RTR)
361 #define CYG_CAN_MSG_IS_REMOTE(_msg_)               ((_msg_).rtr == CYGNUM_CAN_FRAME_RTR)
362
363
364 //---------------------------------------------------------------------------
365 // ID type macros
366 //
367 #define CYG_CAN_MSG_SET_ID_TYPE(_msg_, _type_)     ((_msg_).ext = (_type_))
368 #define CYG_CAN_MSG_GET_ID_TYPE(_msg_)             ((_msg_).ext)
369 #define CYG_CAN_MSG_SET_EXT(_msg_)                 ((_msg_).ext = CYGNUM_CAN_ID_EXT)
370 #define CYG_CAN_MSG_SET_STD(_msg_)                 ((_msg_).ext = CYGNUM_CAN_ID_STD)
371 #define CYG_CAN_MSG_IS_EXT(_msg_)                  ((_msg_).ext == CYGNUM_CAN_ID_EXT)
372
373
374 //---------------------------------------------------------------------------
375 // Identifier access macros
376 //
377 #define CYG_CAN_MSG_GET_ID(_msg_)                  ((_msg_).id)
378 #define CYG_CAN_MSG_SET_ID(_msg_, _id_)            ((_msg_).id = (_id_))
379 #define CYG_CAN_MSG_SET_STD_ID(_msg_, _id_)  \
380 CYG_MACRO_START                              \
381     CYG_CAN_MSG_SET_ID(_msg_, _id_);         \
382     CYG_CAN_MSG_SET_STD(_msg_);              \
383 CYG_MACRO_END
384
385 #define CYG_CAN_MSG_SET_EXT_ID(_msg_, _id_)  \
386 CYG_MACRO_START                              \
387     CYG_CAN_MSG_SET_ID(_msg_, _id_);         \
388     CYG_CAN_MSG_SET_EXT(_msg_);              \
389 CYG_MACRO_END
390
391
392 //---------------------------------------------------------------------------
393 // DLC (data length code) access macros
394 //
395 #define CYG_CAN_MSG_GET_DATA_LEN(_msg_)             ((_msg_).dlc)
396 #define CYG_CAN_MSG_SET_DATA_LEN(_msg_, _len_)      ((_msg_).dlc = (_len_))
397
398
399 //---------------------------------------------------------------------------
400 // CAN message data access
401 // This macro returns a pointer to a cyg_can_msg_data union
402 //
403 #define CYG_CAN_MSG_DATA_PTR(_msg_)                 (&(_msg_).data)
404 #define CYG_CAN_MSG_GET_DATA(_msg_, _pos_)          ((_msg_).data.bytes[_pos_])
405 #define CYG_CAN_MSG_SET_DATA(_msg_, _pos_, _val_)   ((_msg_).data.bytes[_pos_] = (_val_)) 
406
407
408 //---------------------------------------------------------------------------
409 // Access multiple parameters
410 //
411 #define CYG_CAN_MSG_SET_PARAM(_msg_, _id_, _ext_, _dlc_, _rtr_)     \
412 CYG_MACRO_START                                                     \
413     CYG_CAN_MSG_SET_ID(_msg_, _id_);                                \
414     CYG_CAN_MSG_SET_ID_TYPE(_msg_, _ext_);                          \
415     CYG_CAN_MSG_SET_DATA_LEN(_msg_, _dlc_);                         \
416     CYG_CAN_MSG_SET_FRAME_TYPE(_msg_, _rtr_);                       \
417 CYG_MACRO_END
418
419 #define CYG_CAN_MSG_INIT(_clabel_, _id_, _ext_, _dlc_, _rtr_)      \
420 cyg_can_message _clabel_ =                                         \
421 {                                                                  \
422         id  : _id_,                                                    \
423     ext : _ext_,                                                   \
424     rtr : _rtr_,                                                   \
425     dlc : _dlc_,                                                   \
426 }
427                                                        
428
429
430 #ifdef __cplusplus
431 }
432 #endif
433
434 //---------------------------------------------------------------------------
435 #endif // CYGONCE_CANIO_H