comparison src/cs/drivers/drv_app/uart/uartfax.h @ 0:b6a5e36de839

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