FreeCalypso > hg > freecalypso-citrine

comparison g23m-aci/gdd_dio/gdd.h @ 0:75a11d740a02

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial import of gsm-fw from freecalypso-sw rev 1033:5ab737ac3ad7
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 09 Jun 2016 00:02:41 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:75a11d740a02
1 /*
2 +-----------------------------------------------------------------------------
3 | Project : GSM-F&D (8411)
4 | Modul : BAT library
5 +-----------------------------------------------------------------------------
6 | Copyright 2002 Texas Instruments Berlin, AG
7 | All rights reserved.
8 |
9 | This file is confidential and a trade secret of Texas
10 | Instruments Berlin, AG
11 | The receipt of or possession of this file does not convey
12 | any rights to reproduce or disclose its contents or to
13 | manufacture, use, or sell anything it may describe, in
14 | whole, or in part, without the specific written consent of
15 | Texas Instruments Berlin, AG.
16 +-----------------------------------------------------------------------------
17 | Purpose : API of the Generic Data aDapter (GDD) which connects the
18 | application domain with the protocol stack.
19 +-----------------------------------------------------------------------------
20 */
21
22 #ifndef GDD_H
23 #define GDD_H
24
25 /*==== INCLUDES =============================================================*/
26
27 /*==== DEFINITIONS ==========================================================*/
28
29 /** Return and error values of GDD functions */
30 enum GDD_RESULT_CODES
31 {
32 GDD_OK = 0, /* OK, no error occured */
33 GDD_BUSY = 1, /* Currently busy */
34 GDD_DIO_NOT_READY = 2, /* Dio not initialized or ready */
35 GDD_NO_CONNECTION_SLOT = 3, /* Max number of connections already open */
36 GDD_NO_BUF_AVAILABLE = 4, /* No buffer available (for sending) */
37 GDD_INVALID_PARAMS = 5, /* Invalid input parameter */
38 GDD_REQ_BUF_TOO_LARGE = 6, /* Requested buffer too large */
39 GDD_INVALID_BUFFER = 7, /* Invalid buffer */
40 GDD_ALREADY_INITIALIZED = 97, /* Instance already initialized */
41 GDD_NO_MEMORY = 98, /* Memory allocation during initialization failed */
42 GDD_INTERNAL_ERROR = 99 /* General error code for all other errors */
43 };
44
45
46 /*==== CONSTS ===============================================================*/
47
48 /** This size that's required for maintenance of one single connection.
49 Only needed if the application must allocated memory to be passed into
50 gdd_init(). */
51 #define GDD_DIO_SIZEOF_CONDATA 64
52
53 /** Size of first buffer segment (used for internal purposes) */
54 #define GDD_DIO_PID_SEG_SIZE 2
55
56
57 /*==== TYPES =================================================================*/
58
59 /** Connection handle */
60 typedef U32 T_GDD_CON_HANDLE;
61
62
63 /** Identifier for the adapter instances - each instance corresponds to a
64 DIO driver type */
65 typedef enum
66 {
67 GDD_INST_NONE = -1,
68 GDD_INST_BAT = 0, /* The BAT library */
69 GDD_INST_APP, /* Application */
70 GDD_INST_TCP, /* TCPIP entity */
71 GDD_INST_SOCK, /* Socket library */
72 GDD_INST_SOCKCFG, /* Socket library configuration */
73
74 /* Add new instances here and increase GDD_NUM_INSTS accordingly */
75 GDD_NUM_INSTS,
76 /* Maximum number of instances is defined by GDD_MAX_INST_ID */
77 GDD_MAX_INST_ID = 255
78 } T_GDD_INST_ID;
79
80
81 /*
82 * GDD data format - identicial to DIOv4 data format.
83 */
84 typedef struct
85 {
86 U8 _align0; /*< 0: 1> alignment */
87 U8 _align1; /*< 1: 1> alignment */
88 U16 c_data; /*< 2: 2> counter */
89 U8 *ptr_data; /*< 4: 4> pointer to pointer to the first
90 byte of the data buffer segment */
91 } T_GDD_SEGMENT;
92
93 typedef struct
94 {
95 U16 length; /*< 0: 2> len of dio_ctrl */
96 U8 _align0; /*< 2: 1> alignment */
97 U8 c_segment; /*< 3: 1> counter of segments */
98 T_GDD_SEGMENT *ptr_gdd_segment; /*< 4: 4> pointer to Structured Element */
99 } T_GDD_BUF;
100
101
102
103 /** Capabilities of DIO BAT adapter, to be set by the client */
104 typedef struct
105 {
106 U32 mtu_size;
107 } T_GDD_DIO_CAP;
108
109
110 /** Capabilities of the BAT adapter, to be set by the client */
111 typedef union
112 {
113 T_GDD_DIO_CAP dio_cap;
114 /* Capabilities for future adapter implementations to be added here */
115 } T_GDD_CAP;
116
117
118 /** GDD result type */
119 typedef U16 GDD_RESULT;
120
121
122 /** Signal types */
123 typedef enum
124 {
125 GDD_SIGTYPE_CONNECTION_OPENED = 1, /* Connection is established and usable */
126 GDD_SIGTYPE_CONNECTION_FAILED = 2, /* Connection failed or closed down unexpectedly */
127 GDD_SIGTYPE_SEND_BUF_AVAILABLE = 3, /* A new send buffer becomes available after an
128 unsuccessfull call to gdd_get_send_buffer */
129 GDD_SIGTYPE_BUF_SENT = 4 /* Indicates that the last sent buffer has been
130 successfully sent */
131 } T_GDD_SIGTYPE;
132
133
134
135 /** Data associated with a GDD signal */
136 typedef struct
137 {
138 T_GDD_SIGTYPE sig;
139 } T_GDD_SIGNAL;
140
141
142
143 /***************************************************************************
144 * Call-back function definitions (to be implemented by the client)
145 ***************************************************************************/
146
147
148 /*
149 +------------------------------------------------------------------------------
150 | Function : gdd_signal_cb
151 +------------------------------------------------------------------------------
152 | Description : The adapter calls this call-back function to send received data
153 | to the client. The client must copy the data contained in the
154 | buffer, since the buffer will be invalidated upon returning
155 | from this function.
156 | Alternatively, the client can indicate that he is currently
157 | busy. In this case, he has to call gdd_signal_ready_rcv() at a
158 | later time to invoke this call-back function again.
159 |
160 | Parameters : sig - Signal
161 +------------------------------------------------------------------------------
162 */
163 typedef void (* T_GDD_SIGNAL_CB)
164 ( T_GDD_CON_HANDLE con,
165 T_GDD_SIGNAL sig );
166
167 /*
168 +------------------------------------------------------------------------------
169 | Function : gdd_received_data_cb
170 +------------------------------------------------------------------------------
171 | Description : The adapter calls this callback function to signal events to
172 | the client.
173 |
174 | Parameters : sig - Signal
175 |
176 | Return : GDD_OK - Data was copied by client
177 | GDD_BUSY - Client was busy and could not receive data.
178 +------------------------------------------------------------------------------
179 */
180 typedef GDD_RESULT (* T_GDD_RECEIVE_DATA_CB)
181 ( T_GDD_CON_HANDLE con,
182 T_GDD_BUF * buf );
183
184
185 /***************************************************************************
186 * Function definitions
187 ***************************************************************************/
188
189 /*
190 +------------------------------------------------------------------------------
191 | Function : gdd_init
192 +------------------------------------------------------------------------------
193 | Description : This optional function can be used to provide the house-keeping
194 | memory required for the given adapter instance. On platforms
195 | where memory allocation is available, the function might be
196 | called with the parameter mem set to 0. In this case, it is
197 | just use to limit the number of connections via the parameter
198 | num_con.
199 |
200 | Parameters : inst - Instance identifier of the adapter
201 | mem - Memory allocated by client for maintenance
202 | of the connections (Input parameter).
203 | If set to 0, the adapter will allocate
204 | the memory itself.
205 | num_con - Maximum number of connections
206 |
207 | Return : GDD_OK - Initialization successful
208 | >GDD_OK - Error (see manual for error codes)
209 +------------------------------------------------------------------------------
210 */
211 typedef GDD_RESULT (* T_GDD_INIT)
212 ( T_GDD_INST_ID inst,
213 void * mem,
214 U16 num_con);
215
216
217 /*
218 +------------------------------------------------------------------------------
219 | Function : gdd_deinit
220 +------------------------------------------------------------------------------
221 | Description : This function de-initializes an adapter instance.
222 | Any memory that the adapter has allocated internally is freed.
223 |
224 | Parameters : inst - Instance identifier of the adapter
225 |
226 | Return : GDD_OK - Initialization successful
227 | >GDD_OK - Error (see manual for error codes)
228 +------------------------------------------------------------------------------
229 */
230 typedef GDD_RESULT (* T_GDD_DEINIT)
231 ( T_GDD_INST_ID inst);
232
233
234 /*
235 +------------------------------------------------------------------------------
236 | Function : gdd_connect
237 +------------------------------------------------------------------------------
238 | Description : This function prepares a new connection for data transmission.
239 | If the function succeeds, it will return a connection handle
240 | in the parameter 'con_handle' to the caller. Each connection is
241 | uniquely identified by its connection handle.
242 |
243 | Note : The connection cannot be used straight away. Instead, the
244 | client receives a signal GDD_SIGTYPE_CONNECTION_OPENED when the
245 | connection setup has been finished.
246 |
247 | Each open connection should be closed using the function
248 | gdd_close() when it is not used any longer.
249 |
250 | Parameters : inst - Instance identifier of the adapter
251 | con_handle - New handle to the adapter passed back to the
252 | caller (output parameter).
253 | cap - capabilities of the adapter
254 | rcv_cb - Call-back for receiving data (provided by client)
255 | sig_cb - Call-back for signals (provided by client)
256 |
257 | Return : GDD_OK - Connecting is setup and being created. The client
258 | has to wait for signal GDD_SIGTYPE_CONNECTION_OPENED
259 | before the connection is usable.
260 | >GDD_OK - Error (see manual for error codes)
261 +------------------------------------------------------------------------------
262 */
263 typedef GDD_RESULT (* T_GDD_CONNECT)
264 ( T_GDD_INST_ID inst,
265 T_GDD_CON_HANDLE * con_handle,
266 const T_GDD_CAP * cap,
267 T_GDD_RECEIVE_DATA_CB rcv_cb,
268 T_GDD_SIGNAL_CB sig_cb );
269
270
271 /*
272 +------------------------------------------------------------------------------
273 | Function : gdd_disconnect
274 +------------------------------------------------------------------------------
275 | Description : This function closes and deletes a connection.
276 | The connection handle will not be valid any longer.
277 |
278 | Parameters : con_handle - Handle to the connection to be closed
279 |
280 | Return : GDD_OK - Initialization successful
281 | >GDD_OK - Error (see manual for error codes)
282 +------------------------------------------------------------------------------
283 */
284 typedef GDD_RESULT (* T_GDD_DISCONNECT)
285 ( T_GDD_CON_HANDLE con_handle );
286
287
288 /*
289 +------------------------------------------------------------------------------
290 | Function : gdd_get_send_buffer
291 +------------------------------------------------------------------------------
292 | Description : This function request a send buffer of a minimum size data_size
293 | for sending on the connection specified with con. The buffer is
294 | passed back in the parameter 'buf'.
295 | After a successful call to this function, it is the
296 | responsibility of the caller to subsequently fill the buffer
297 | and call gdd_send_data(), before another call to
298 | gdd_get_send_buffer() is done. In other words, the client must
299 | make sure that calls to these two functions are synchronized.
300 |
301 | Parameters : con_handle - Connection handle
302 | buf - Pointer to pointer to send buffer (out parameter)
303 | data_size - Minimum size of requested buffer
304 |
305 | Return : GDD_OK - Initialization successful
306 | >GDD_OK - Error (see manual for error codes)
307 | GDD_NO_BUF_AVAILABLE - No buffer available. The client
308 | will be notified with a signal
309 | GDD_SIGTYPE_SEND_BUF_AVAILABLE when a
310 | buffer is ready and can be requested.
311 +------------------------------------------------------------------------------
312 */
313 typedef GDD_RESULT (* T_GDD_GET_SEND_BUFFER)
314 ( T_GDD_CON_HANDLE con_handle,
315 T_GDD_BUF ** buf,
316 U16 data_size );
317
318
319 /*
320 +------------------------------------------------------------------------------
321 | Function : gdd_send_data
322 +------------------------------------------------------------------------------
323 | Description : This functions sends a buffer over the specified connection.
324 | Please see also description of gdd_get_send_buffer().
325 |
326 |
327 | Parameters : con_handle - Connection handle
328 | buf - Buffer to be sent
329 |
330 | Return : GDD_OK - Initialization successful
331 | >GDD_OK - Error (see manual for error codes)
332 | GDD_INVALID_BUFFER - The buffer pointed to is incorrect, i.e.
333 | not the one that was previously requested
334 +------------------------------------------------------------------------------
335 */
336 typedef GDD_RESULT (* T_GDD_SEND_DATA)
337 ( T_GDD_CON_HANDLE con,
338 T_GDD_BUF * buf);
339
340
341 /*
342 +------------------------------------------------------------------------------
343 | Function : gdd_signal_ready_rcv
344 +------------------------------------------------------------------------------
345 | Description : This function is called from the client to indicate that he
346 | is ready to receive. Typically, it is called from the client
347 | when he becomes ready after a preceding result callback
348 | (result_cb) was returned with GDD_BUSY.
349 |
350 | Parameters : con_handle - Connection handle
351 +------------------------------------------------------------------------------
352 */
353 typedef void (* T_GDD_SIGNAL_READY_RCV)
354 ( T_GDD_CON_HANDLE con );
355
356
357 /** GDD Function pointer table */
358 typedef struct
359 {
360 T_GDD_INIT gdd_init;
361 T_GDD_DEINIT gdd_deinit;
362 T_GDD_CONNECT gdd_connect;
363 T_GDD_DISCONNECT gdd_disconnect;
364 T_GDD_GET_SEND_BUFFER gdd_get_send_buffer;
365 T_GDD_SEND_DATA gdd_send_data;
366 T_GDD_SIGNAL_READY_RCV gdd_signal_ready_rcv;
367 } T_GDD_FUNC;
368
369
370 /** Needed for initialization of client of BAT adapter (BAT library) */
371 extern T_GDD_FUNC gdd_func_dio;
372
373
374 /***************************************************************************
375 * Helper function definitions
376 ***************************************************************************/
377
378 /*
379 +------------------------------------------------------------------------------
380 | Function : gdd_write_buf
381 +------------------------------------------------------------------------------
382 | Description : Write data from a client buffer into into a GDD buffer
383 | The datagram protocol ID for the following link layer (PPP) is
384 | set internally to 0x21 (IPv4). If you need to set the protocol
385 | ID to something else, please use the function
386 | gdd_write_buf_with_pid()..
387 |
388 | Parameters : src_buf - Source buffer (client owned)
389 | src_size - Size of source buffer
390 | dest_buf - Destination buffer
391 |
392 | Return : 0 if all bytes have been written to the destination buffer.
393 | If not all bytes could be written, the return value is larger
394 | than 0 and denotes the number of remaining (unwritten) bytes.
395 | A negative return value indicates an error.
396 +------------------------------------------------------------------------------
397 */
398 S32 gdd_write_buf(const U8 * src_buf, U16 src_size, T_GDD_BUF * dest_buf);
399
400 /*
401 +------------------------------------------------------------------------------
402 | Description : Write user data and a datagram protocol ID used by the link
403 | layer (PPP) into a GDD buffer.
404 |
405 | Parameters : src_buf - Source buffer (client owned)
406 | src_size - Size of source buffer
407 | dest_buf - Destination buffer
408 | protocol_id - datagram protocol identifier
409 |
410 | Return : 0 if all bytes have been written to the destination buffer.
411 | If not all bytes could be written, the return value is larger
412 | than 0 and denotes the number of remaining (unwritten) bytes.
413 | A negative return value indicates an error.
414 +------------------------------------------------------------------------------
415 */
416 S32 gdd_write_buf_with_pid(const U8 * src_buf, U16 src_size,
417 T_GDD_BUF * dest_buf,U8 protocol_id);
418
419
420 /*
421 +------------------------------------------------------------------------------
422 | Function : gdd_read_buf
423 +------------------------------------------------------------------------------
424 | Description : Read data from a GDD buffer into a client buffer.
425 |
426 | Parameters : src_buf - Source buffer received from GDD
427 | dest_buf - Destination buffer (client owned)
428 | dest_size - Size of destination buffer
429 |
430 | Return : 0 if all bytes have been copied into the destination buffer.
431 | If not all bytes could be copied into the destination buffer,
432 | the return value is larger than 0 and denotes the number of
433 | remaining (unread) bytes. A negative return value indicase an
434 | error.
435 +------------------------------------------------------------------------------
436 */
437 S32 gdd_read_buf(const T_GDD_BUF * src_buf, U8 * dest_buf, U16 dest_size);
438
439
440 #endif /* GDD_H */