FreeCalypso > hg > freecalypso-citrine

comparison serial/uartfax.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 * UARTFAX.H
4 *
5 * This driver allows to control the UARTs of chipset 1.5 for fax and data
6 * It performs flow control: RTS/CTS, XON/XOFF.
7 *
8 * (C) Texas Instruments 1999 - 2003
9 *
10 ******************************************************************************/
11
12 #ifndef __UARTFAX_H__
13 #define __UARTFAX_H__
14
15 #ifndef C_EXTERN
16 #if 1 //(OP_L1_STANDALONE == 1)
17 #define C_EXTERN extern
18 #else
19 #define C_EXTERN
20 #endif
21 #endif
22
23 /*
24 * In UAF_Init, a constant is used to identify the UART.
25 */
26
27 typedef enum {
28 UAF_UART_0, /* IrDA */
29 UAF_UART_1 /* Modem */
30 #if (CHIPSET == 12)
31 , UAF_UART_2 /* Modem 2 */
32 #endif
33 } T_fd_UartId;
34
35 #if (CHIPSET == 12)
36 #define NUMBER_OF_FD_UART (3)
37 #else
38 #define NUMBER_OF_FD_UART (2)
39 #endif
40
41 /*******************************************************************************
42 *
43 * UAF_Init
44 *
45 * Purpose : Initializes the UART hardware and installs interrupt handlers.
46 * The parameters are set to the default values:
47 * - 19200 baud,
48 * - 8 bits / character,
49 * - no parity,
50 * - 1 stop bit,
51 * - no flow control.
52 * All functionalities of the UART driver are disabled.
53 *
54 * Arguments: In : uartNo: Used UART.
55 * Out: none
56 *
57 * Returns : FD_OK : Successful operation.
58 * FD_NOT_SUPPORTED: Wrong UART number.
59 * FD_INTERNAL_ERR : Internal problem.
60 *
61 ******************************************************************************/
62
63 C_EXTERN T_FDRET UAF_Init (T_fd_UartId uartNo);
64
65 /*******************************************************************************
66 *
67 * UAF_Enable
68 *
69 * Purpose : The functionalities of the UART driver are disabled or enabled.
70 * In the deactivated state, all information about the communication
71 * parameters should be stored and recalled if the driver is again
72 * enabled. When the driver is enabled the RX and TX buffers are
73 * cleared.
74 *
75 * Arguments: In : uartNo: Used UART.
76 * : enable: 1: enable the driver
77 * 0: disable the driver
78 * Out: none
79 *
80 * Returns : FD_OK : Successful operation.
81 * FD_NOT_SUPPORTED: Wrong UART number.
82 * FD_INTERNAL_ERR : Internal problem with the hardware.
83 *
84 ******************************************************************************/
85
86 C_EXTERN T_FDRET UAF_Enable (T_fd_UartId uartNo,
87 SYS_BOOL enable);
88
89 /*******************************************************************************
90 *
91 * UAF_SetComPar
92 *
93 * Purpose : Sets up the communication parameters: baud rate, bits per
94 * character, number of stop bits, parity.
95 *
96 * Arguments: In : uartNo : Used UART.
97 * baudrate: Used baud rate.
98 * bpc : Used bits per character.
99 * sb : Used stop bits.
100 * parity : Used parity.
101 * Out: none
102 *
103 * Returns : FD_OK : Successful operation.
104 * FD_NOT_SUPPORTED: The specified parameters don't fit to the
105 * capabilities of the UART or wrong UART number.
106 * FD_INTERNAL_ERR : Internal problem with the hardware.
107 *
108 ******************************************************************************/
109
110 C_EXTERN T_FDRET UAF_SetComPar (T_fd_UartId uartNo,
111 T_baudrate baudrate,
112 T_bitsPerCharacter bpc,
113 T_stopBits sb,
114 T_parity parity);
115
116 /*******************************************************************************
117 *
118 * UAF_SetBuffer
119 *
120 * Purpose : Sets up the size of the circular buffers to be used in the UART
121 * driver. This function may be called only if the UART is disabled
122 * with UAF_Enable.
123 *
124 * Arguments: In : uartNo : Used UART.
125 * bufSize : Specifies the size of the circular buffer.
126 * rxThreshold: Amount of received bytes that leads to a call
127 * to suspended read-out function which is passed
128 * to the function UAF_ReadData.
129 * txThreshold: Amount of bytes in the TX buffer to call the
130 * suspended write-in function which is passed to
131 * the function UAF_WriteData
132 * Out: none
133 *
134 * Returns : FD_OK : Successful operation.
135 * FD_NOT_SUPPORTED: bufSize exceeds the maximal possible
136 * capabilities of the driver or the threshold
137 * values don't correspond to the bufSize or
138 * wrong UART number.
139 * FD_INTERNAL_ERR : Internal problem with the hardware or the
140 * function has been called while the UART is
141 * enabled.
142 *
143 ******************************************************************************/
144
145 C_EXTERN T_FDRET UAF_SetBuffer (T_fd_UartId uartNo,
146 SYS_UWORD16 bufSize,
147 SYS_UWORD16 rxThreshold,
148 SYS_UWORD16 txThreshold);
149
150 /*******************************************************************************
151 *
152 * UAF_SetFlowCtrl
153 *
154 * Purpose : Changes the flow control mode of the UART driver.
155 * If a flow control is activated, DTR is activated or XOFF is sent
156 * if the RX buffer is not able to store the received characters else
157 * DTR is deactivated or XON is sent.
158 *
159 * Arguments: In : uartNo: Used UART.
160 * fcMode: flow control mode (none, DTR/DSR, RTS/CTS, XON/XOFF).
161 * XON : ASCII code of the XON character.
162 * XOFF : ASCII code of the XOFF character.
163 * Out: none
164 *
165 * Returns : FD_OK : Successful operation.
166 * FD_NOT_SUPPORTED: The flow control mode is not supported or wrong
167 * UART number.
168 * FD_INTERNAL_ERR : Internal problem with the hardware.
169 *
170 ******************************************************************************/
171
172 C_EXTERN T_FDRET UAF_SetFlowCtrl (T_fd_UartId uartNo,
173 T_flowCtrlMode fcMode,
174 SYS_UWORD8 XON,
175 SYS_UWORD8 XOFF);
176
177 /*******************************************************************************
178 *
179 * UAF_SetEscape
180 *
181 * Purpose : To return to the command mode at the ACI while a data connection
182 * is established, an escape sequence has to be detected.
183 * To distinguish between user data and the escape sequence a
184 * defined guard period is necessary before and after this sequence.
185 *
186 * Arguments: In: uartNo : Used UART.
187 * escChar : ASCII character which could appear three times
188 * as an escape sequence.
189 * guardPeriod: Denotes the minimal duration of the rest before
190 * the first and after the last character of the
191 * escape sequence, and the maximal receiving
192 * duration of the whole escape string. This value
193 * is expressed in ms.
194 * Out: none
195 *
196 * Returns : FD_OK : Successful operation.
197 * FD_NOT_SUPPORTED: Wrong UART number.
198 * FD_INTERNAL_ERR : Internal problem with the hardware.
199 *
200 ******************************************************************************/
201
202 C_EXTERN T_FDRET UAF_SetEscape (T_fd_UartId uartNo,
203 SYS_UWORD8 escChar,
204 SYS_UWORD16 guardPeriod);
205
206 /*******************************************************************************
207 *
208 * UAF_InpAvail
209 *
210 * Purpose : Returns the number of characters available in the RX buffer of the
211 * driver. If the driver is disabled the function returns 0.
212 *
213 * Arguments: In : uartNo: Used UART.
214 * Out: none
215 *
216 * Returns : >= 0 : The returned value is the amount of data in the
217 * RX buffer.
218 * FD_NOT_SUPPORTED: Wrong UART number.
219 * FD_NOT_READY : The function is called while the callback of the
220 * readOutFunc function is activated and still not
221 * terminated.
222 * FD_INTERNAL_ERR : Internal problem with the hardware.
223 *
224 ******************************************************************************/
225
226 C_EXTERN T_FDRET UAF_InpAvail (T_fd_UartId uartNo);
227
228 /*******************************************************************************
229 *
230 * UAF_OutpAvail
231 *
232 * Purpose : Returns the number of free characters in TX buffer of the driver.
233 * If the driver is disabled the function returns 0.
234 *
235 * Arguments: In : uartNo: Used UART.
236 * Out: none
237 *
238 * Returns : >= 0 : The returned value is the amount of data in the
239 * TX buffer.
240 * FD_NOT_SUPPORTED: Wrong UART number.
241 * FD_NOT_READY : The function is called while the callback of the
242 * writeInFunc function is activated and still not
243 * terminated.
244 * FD_INTERNAL_ERR : Internal problem with the hardware.
245 *
246 ******************************************************************************/
247
248 C_EXTERN T_FDRET UAF_OutpAvail (T_fd_UartId uartNo);
249
250 /*******************************************************************************
251 *
252 * UAF_EnterSleep
253 *
254 * Purpose : Checks if UART is ready to enter Deep Sleep. If ready, enables
255 * wake-up interrupt.
256 *
257 * Arguments: In : uartNo: Used UART.
258 * Out: none
259 *
260 * Returns : 0 : Deep Sleep is not possible.
261 * >= 1 : Deep Sleep is possible.
262 * FD_NOT_SUPPORTED: Wrong UART number.
263 *
264 * Warning: Parameters are not verified.
265 *
266 ******************************************************************************/
267
268 C_EXTERN T_FDRET UAF_EnterSleep (T_fd_UartId uartNo);
269
270 /*******************************************************************************
271 *
272 * UAF_WakeUp
273 *
274 * Purpose : Wakes up UART after Deep Sleep.
275 *
276 * Arguments: In : uartNo: Used UART.
277 * Out: none
278 *
279 * Returns : FD_OK : Successful operation.
280 * FD_NOT_SUPPORTED: Wrong UART number.
281 *
282 * Warning: Parameters are not verified.
283 *
284 ******************************************************************************/
285
286 C_EXTERN T_FDRET UAF_WakeUp (T_fd_UartId uartNo);
287
288 /*******************************************************************************
289 *
290 * UAF_ReadData
291 *
292 * Purpose : To read the received characters out of the RX buffer the address
293 * of a function is passed. If characters are available, the driver
294 * calls this function and pass the address and the amount of
295 * readable characters. Because the RX buffer is circular, the
296 * callback function may be called with more than one address of
297 * buffer fragment.
298 * The readOutFunc function modifies the contents of the size array
299 * to return the driver the number of processed characters. Each
300 * array entry is decremented by the number of bytes read in the
301 * fragment.
302 * If the UAF_ReadData is called while the RX buffer is empty, it
303 * depends on the suspend parameter to suspend the call-back or to
304 * leave without any operation. In the case of suspension, the
305 * return value of UAF_ReadData is UAF_SUSPENDED. A delayed call-back
306 * will be performed if:
307 * - the RX buffer reachs the adjusted threshold (rxThreshold of
308 * UAF_SetBuffer),
309 * - the state of a V.24 input line has changed,
310 * - a break is detected,
311 * - an escape sequence is detected.
312 * If no suspension is necessary the function returns the number of
313 * processed bytes.
314 *
315 * Arguments: In : uartNo : Used UART.
316 * suspend : mode of suspension in case of RX buffer empty.
317 * readOutFunc: Callback function.
318 * cldFromIrq: The driver sets this parameter to 1
319 * if the callback function is called
320 * from an interrupt service routine.
321 * reInstall : The call-back function sets this
322 * parameter to rm_reInstall if the
323 * driver must call again the callback
324 * function when the RX threshold level
325 * is reached. Else it will be set to
326 * rm_noInstall. Before to call the
327 * readOutFunc function this parameter
328 * is set to rm_notDefined.
329 * nsource : Informed the callback function about
330 * the number of fragments which are
331 * ready to copy from the circular RX
332 * buffer.
333 * source : Array which contains the addresses
334 * of the fragments.
335 * size : Array which contains the sizes of
336 * each fragments.
337 * state : The state parameter is the status
338 * of the V.24 lines and the break /
339 * escape detection. The state
340 * parameter is described in the
341 * specification of UAF_GetLineState.
342 * Out: none
343 *
344 * Returns : >= 0 : Succesful operation. Amount of processed bytes.
345 * FD_NOT_SUPPORTED: Wrong UART number.
346 * FD_SUSPENDED : The callback is suspended until the buffer or
347 * state condition changed.
348 * FD_NOT_READY : The function is called while the callback is
349 * activated and still not terminated.
350 * FD_INTERNAL_ERR : Internal problems with the hardware.
351 *
352 ******************************************************************************/
353
354 C_EXTERN T_FDRET UAF_ReadData (T_fd_UartId uartNo,
355 T_suspendMode suspend,
356 void (readOutFunc (SYS_BOOL cldFromIrq,
357 T_reInstMode *reInstall,
358 SYS_UWORD8 nsource,
359 SYS_UWORD8 *source[],
360 SYS_UWORD16 size[],
361 SYS_UWORD32 state)));
362
363 /*******************************************************************************
364 *
365 * UAF_WriteData
366 *
367 * Purpose : To write characters into the TX buffer the address of a function
368 * is passed. If free space is available in the buffer, the driver
369 * calls this function and passes the destination address and the
370 * amount of space. Because the TX buffer is circular, the callback
371 * function may be called with more than one address of buffer
372 * fragment.
373 * The writeInFunc function modifies the contents of the size array
374 * to return the driver the number of processed bytes. Each array
375 * entry is decremented by the number of bytes written in this
376 * fragment.
377 * If the UAF_WriteData function is called while the TX buffer is
378 * full, it depends on the suspend parameter to suspend the
379 * call-back or to leave this function without any operation. In the
380 * case of suspension the returned value of the UAF_WriteData is
381 * UAF_SUSPENDED. A delayed call-back will be performed if the TX
382 * buffer reaches the adjusted threshold (txThreshold of
383 * UAF_SetBuffer). If no suspension is necessary the function returns
384 * the number of processed bytes.
385 *
386 * Arguments: In : uartNo : Used UART.
387 * suspend : mode of suspension in case of TX buffer empty.
388 * writeInFunc: Callback function.
389 * cldFromIrq: The driver sets this parameter to 1
390 * if the call-back function is called
391 * from an interrupt service routine.
392 * reInstall : The callback function sets this
393 * parameter to rm_reInstall if the
394 * driver must call again the callback
395 * function when the TX threshold level
396 * is reached. Else it will be set to
397 * rm_noInstall. Before to call the
398 * writeInFunc function this parameter
399 * is set to rm_notDefined.
400 * ndest : Informed the callback function about
401 * the number of fragments which are
402 * available in the TX buffer.
403 * dest : Array which contains the addresses
404 * of the fragments.
405 * size : Array which contains the sizes of
406 * each fragments.
407 * Out: none
408 *
409 * Returns : >= 0 : Succesful operation. Amount of processed bytes.
410 * FD_NOT_SUPPORTED: Wrong UART number.
411 * FD_SUSPENDED : The callback is suspended until the buffer
412 * condition changed.
413 * FD_NOT_READY : The function is called while the callback is
414 * activated and still not terminated.
415 * FD_INTERNAL_ERR : Internal problems with the hardware.
416 *
417 ******************************************************************************/
418
419 C_EXTERN T_FDRET UAF_WriteData (T_fd_UartId uartNo,
420 T_suspendMode suspend,
421 void (writeInFunc (SYS_BOOL cldFromIrq,
422 T_reInstMode *reInstall,
423 SYS_UWORD8 ndest,
424 SYS_UWORD8 *dest[],
425 SYS_UWORD16 size[])));
426
427 /*******************************************************************************
428 *
429 * UAF_StopRec
430 *
431 * Purpose : If a flow control mode is set, this function tells the terminal
432 * equipment that no more data can be received.
433 * XON/XOFF: XOFF is sent.
434 * DTR/DSR : DTR is desactivated.
435 * RTS/CTS : RTS is deactivated.
436 *
437 * Arguments: In : uartNo: Used UART.
438 * Out: none
439 *
440 * Returns : FD_OK : Successful operation.
441 * FD_NOT_SUPPORTED: Wrong UART number.
442 * FD_INTERNAL_ERR : Internal problem with the hardware.
443 *
444 ******************************************************************************/
445
446 C_EXTERN T_FDRET UAF_StopRec (T_fd_UartId uartNo);
447
448 /*******************************************************************************
449 *
450 * UAF_StartRec
451 *
452 * Purpose : If a flow control mode is set, this function tells the terminal
453 * equipment that the receiver is again able to receive more data.
454 * If the buffer has already reached the high water mark the driver
455 * sends the signal only if the buffer drains to a low water mark.
456 * XON/XOFF: XON is sent.
457 * DTR/DSR : DTR is activated.
458 * RTS/CTS : RTS is activated.
459 *
460 * Arguments: In : uartNo: Used UART.
461 * Out: none
462 *
463 * Returns : FD_OK : Successful operation.
464 * FD_NOT_SUPPORTED: Wrong UART number.
465 * FD_INTERNAL_ERR : Internal problem with the hardware.
466 *
467 ******************************************************************************/
468
469 C_EXTERN T_FDRET UAF_StartRec (T_fd_UartId uartNo);
470
471 /*******************************************************************************
472 *
473 * UAF_GetLineState
474 *
475 * Purpose : Returns the state of the V.24 lines, the flow control state and
476 * the result of the break/escape detection process as a bit field.
477 *
478 * Arguments: In : uartNo: Used UART.
479 * Out: state : State of the V.24 lines, the flow control state and
480 * the result of the break/escape sequence detection
481 * process as a bit field.
482 *
483 * Returns : FD_OK : Successful operation.
484 * FD_NOT_SUPPORTED: Wrong UART number.
485 * FD_NOT_READY : The function is called while the callback of
486 * the readOutFunc function is activated and still
487 * not terminated.
488 * FD_INTERNAL_ERR : Internal problem with the hardware.
489 *
490 ******************************************************************************/
491
492 C_EXTERN T_FDRET UAF_GetLineState (T_fd_UartId uartNo,
493 SYS_UWORD32 *state);
494
495 /*******************************************************************************
496 *
497 * UAF_SetLineState
498 *
499 * Purpose : Sets the states of the V.24 status lines according to the bit
500 * field of the parameter state.
501 *
502 * Arguments: In : uartNo: Used UART.
503 * state : Bit field. Only the signals which are marked with
504 * the 'set' access can be used to change the state of
505 * the signal.
506 * mask : Bit field with the same structure as state. Each bit
507 * in state corresponds to a bit in mask. Settabled
508 * bits marked by a 1 are manipulated by the driver.
509 * Out: none
510 *
511 * Returns : FD_OK : Successful operation.
512 * FD_NOT_SUPPORTED: Wrong UART number.
513 * FD_INTERNAL_ERR : Internal problem with the hardware.
514 *
515 ******************************************************************************/
516
517 C_EXTERN T_FDRET UAF_SetLineState (T_fd_UartId uartNo,
518 SYS_UWORD32 state,
519 SYS_UWORD32 mask);
520
521 /*******************************************************************************
522 *
523 * UAF_InterruptHandler
524 *
525 * Purpose : Interrupt handler.
526 *
527 * Arguments: In : uart_id : origin of interrupt
528 * interrupt_status: source of interrupt
529 * Out: none
530 *
531 * Returns : none
532 *
533 ******************************************************************************/
534
535 C_EXTERN void UAF_InterruptHandler (T_fd_UartId uart_id,
536 SYS_UWORD8 interrupt_status);
537
538 /*******************************************************************************
539 *
540 * UAF_CheckXEmpty
541 *
542 * Purpose : Checks the empty condition of the Transmitter.
543 *
544 * Arguments: In : uartNo: Used UART.
545 * Out: none
546 *
547 * Returns : FD_OK : Empty condition OK.
548 * FD_NOT_SUPPORTED: Wrong UART number.
549 * FD_NOT_READY : Empty condition not OK.
550 * FD_INTERNAL_ERR : Internal problem with the hardware.
551 *
552 ******************************************************************************/
553
554 C_EXTERN T_FDRET UAF_CheckXEmpty (T_fd_UartId uartNo);
555
556 /*******************************************************************************
557 *
558 * UAF_DTRInterruptHandler
559 *
560 * Purpose : This function is only used on C-Sample. On this platform, the DTR
561 * signal is controlled with an I/O. A change of state of this signal
562 * is detected with an interrupt. This function is called when this
563 * interrupt occurs.
564 *
565 * Arguments: In : none
566 * Out: none
567 *
568 * Returns : none
569 *
570 ******************************************************************************/
571
572 void UAF_DTRInterruptHandler (void);
573
574 /*******************************************************************************
575 *
576 * UAF_Exit
577 *
578 * Purpose :
579 *
580 * Arguments: In : uartNo: Used UART.
581 * Out: none
582 *
583 * Returns : FD_OK : Successful operation.
584 * FD_NOT_SUPPORTED: Wrong UART number.
585 * FD_INTERNAL_ERR : Internal problem.
586 *
587 ******************************************************************************/
588
589 T_FDRET UAF_Exit (T_fd_UartId uartNo);
590
591 #undef C_EXTERN
592
593 #endif /* __UARTFAX_H__ */