source: svn/trunk/newcon3bcm2_21bu/magnum/portinginterface/urt/7552/burt.h

Last change on this file was 2, checked in by jglee, 11 years ago

first commit
  • Property svn:executable set to *
File size: 21.4 KB
Line 
1/***************************************************************************
2 *     Copyright (c) 2003-2011, Broadcom Corporation
3 *     All Rights Reserved
4 *     Confidential Property of Broadcom Corporation
5 *
6 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
7 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
8 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
9 *
10 * $brcm_Workfile: burt.h $
11 * $brcm_Revision: Hydra_Software_Devel/15 $
12 * $brcm_Date: 6/20/11 10:58a $
13 *
14 * Module Description:
15 *
16 * Revision History:
17 *
18 * $brcm_Log: /magnum/portinginterface/urt/7038/burt.h $
19 *
20 * Hydra_Software_Devel/15   6/20/11 10:58a agin
21 * SW7346-273:  Expand databits enum.
22 *
23 * Hydra_Software_Devel/14   12/22/10 5:18p rpereira
24 * SW7550-627: Corrected function name of ResetTxRx
25 *
26 * Hydra_Software_Devel/13   12/22/10 4:58p rpereira
27 * SW7550-627: Need a method to flush/reset the RX fifo
28 *
29 * Hydra_Software_Devel/12   7/21/09 5:42p jkim
30 * PR30806: Add the enum for stop bits
31 *
32 * Hydra_Software_Devel/11   2/24/09 5:05p jkim
33 * PR44823: add function prototype for BURT_Read_Isr()
34 *
35 * Hydra_Software_Devel/10   4/25/07 4:13p jkim
36 * PR29625: Add three functions, which can be called within ISR.
37 *
38 * Hydra_Software_Devel/9   3/1/07 5:00p jkim
39 * PR14344: make changes so that it is backward compatible.
40 *
41 * Hydra_Software_Devel/8   2/23/07 11:14a jkim
42 * PR26690: remove global variable and make it part of channel handle
43 * structure
44 *
45 * Hydra_Software_Devel/7   1/31/07 11:42a jkim
46 * PR26690: Add function prototype for BURT_RegisterCallback
47 *
48 * Hydra_Software_Devel/6   1/15/07 3:41p jkim
49 * PR26690: separate rx/tx interrupt flag in the structure so that each
50 * interrupt can be enabled/disabled indepent of the other
51 *
52 * Hydra_Software_Devel/5   3/15/06 10:10a brianlee
53 * PR14344: Fixed sample code.
54 *
55 * Hydra_Software_Devel/4   9/25/03 12:23p brianlee
56 * Fixed tags for Midas service generator.
57 *
58 * Hydra_Software_Devel/3   9/16/03 4:58p brianlee
59 * Modified several APIs, fixed sample code.
60 *
61 * Hydra_Software_Devel/2   7/31/03 6:15p brianlee
62 * Added GetEventHandle() function.
63 *
64 * Hydra_Software_Devel/1   7/24/03 7:07p brianlee
65 * Initial version.
66 *
67 ***************************************************************************/
68
69
70/*= Module Overview *********************************************************
71<verbatim>
72
73Overview
74The URT PI module controls the UART core within the BCM7038.
75There are two independent UARTs that are separately configurable for
76baud rate, number of bits per character (7 or 8), number of stop bits
77(0, 1, or 2), and parity bit (none, odd, or even).
78
79Design
80The design for BURT PI API is broken into two parts.
81  Part 1 (open/close/configuration):
82    These APIs are used for opening and closing BURT device/device channel.
83  Part 2 (receive data or send data)
84    These APIs are used to send/receive data.
85
86Usage
87The usage of BURT involves the following:
88   * Configure/Open of BURT
89      * Configure BURT device for the target system
90      * Open BURT device
91      * Configure BURT device channel for the target system
92      * Open BURT device channel
93   * Receive/Send data.
94
95Sample Code
96void main( void )
97{
98    BURT_Handle hUrt;
99    BURT_ChannelHandle hUrtChan;
100    BURT_ChannelSettings defChnSettings;
101    BREG_Handle hReg;
102    BCHP_Handle hChip;
103        BINT_Handle hInt;
104    int chanNo;
105        BKNI_EventHandle rxEventHandle;
106        uint8_t         data[32];
107        BURT_RxError            rxError;
108        uint32_t                        bytesRead;
109
110    // Do other initialization, i.e. for BREG, BCHP, etc.
111
112    BURT_Open (&hUrt, hChip, hReg, hInt, (BURT_Settings *)NULL);
113
114    chnIdx = 0; // example for channel 0
115    BURT_GetChannelDefaultSettings( hUrt, chanNo, &defChnSettings );
116
117    // Make any changes required from the default values
118    defChnSettings.rxEnable = true;
119    defChnSettings.txEnable = true;
120    defChnSettings.baud     = 115200;
121    defChnSettings.bits     = BURT_DataBits_eDataBits8;
122    defChnSettings.parity   = BURT_Parity_eNone;
123    defChnSettings.intMode      = true;
124    BURT_OpenChannel( hUrt, &hUrtChan, chnIdx, &defChnSettings );
125
126        BURT_GetRxEventHandle(hUrtChan, &rxEventHandle);
127
128        // Wait to receive a character
129        BKNI_WaitForEvent(rxEventHandle, BKNI_INFINITE);
130
131    if (BURT_Read (hUrtChan, data, 32, &bytesRead, &rxError) == BURT_ERR_RX_ERROR)
132                printf("Error code is %d\n", rxError);
133        else
134                printf("Number of bytes read was %d\n", bytesRead);
135}
136
137</verbatim>
138***************************************************************************/
139
140
141#ifndef BURT_H__
142#define BURT_H__
143
144#include "bchp.h"
145#include "breg_mem.h"
146#include "bint.h"
147#include "bkni.h"
148#include "berr_ids.h"
149
150#ifdef __cplusplus
151extern "C" {
152#endif
153
154/***************************************************************************
155Summary:
156        Error Codes specific to BURT
157
158Description:
159
160See Also:
161
162****************************************************************************/
163#define BURT_ERR_NOTAVAIL_CHN_NO                BERR_MAKE_CODE(BERR_URT_ID, 0)
164#define BURT_ERR_RX_ERROR                               BERR_MAKE_CODE(BERR_URT_ID, 1)
165#define BURT_ERR_TX_FIFO_NOT_AVAIL              BERR_MAKE_CODE(BERR_URT_ID, 2)
166
167/***************************************************************************
168Summary:
169        The handles for urt module.
170
171Description:
172        Since BURT is a device channel, it has main device handle as well
173        as a device channel handle.
174
175See Also:
176        BURT_Open(), BURT_OpenChannel()
177
178****************************************************************************/
179typedef struct BURT_P_Handle                            *BURT_Handle;
180typedef struct BURT_P_ChannelHandle                     *BURT_ChannelHandle;
181
182/***************************************************************************
183Summary:
184        Enumeration for URT parity setting
185
186Description:
187        This enumeration defines the parity setting option for URT
188
189See Also:
190        None.
191
192****************************************************************************/
193typedef enum
194{
195   BURT_Parity_eNone,
196   BURT_Parity_eOdd,
197   BURT_Parity_eEven
198} BURT_Parity;
199
200/***************************************************************************
201Summary:
202        Enumeration for URT number of bits setting
203
204Description:
205        This enumeration defines the number of bits setting for UART
206
207See Also:
208        None.
209
210****************************************************************************/
211typedef enum
212{
213        BURT_DataBits_eDataBits5,
214        BURT_DataBits_eDataBits6,
215        BURT_DataBits_eDataBits7,
216        BURT_DataBits_eDataBits8
217} BURT_DataBits;
218
219/***************************************************************************
220Summary:
221        Enumeration for URT number of stop bits setting
222
223Description:
224        This enumeration defines the number of stop bits setting for UART
225
226See Also:
227        None.
228
229****************************************************************************/
230typedef enum
231{
232        BURT_StopBits_eOneBit,
233        BURT_StopBits_eTwoBit
234} BURT_StopBits;
235
236/***************************************************************************
237Summary:
238        Enumeration for URT receiver error
239
240Description:
241        This enumeration defines the receiver errors
242
243See Also:
244        None.
245
246****************************************************************************/
247typedef enum
248{
249   BURT_RxError_eNoError,
250   BURT_RxError_eReceiverOverRun,
251   BURT_RxError_eReceiverFrameError,
252   BURT_RxError_eReceiverParityError
253} BURT_RxError;
254
255/***************************************************************************
256Summary:
257        Required default settings structure for URT module.
258
259Description:
260        The default setting structure defines the default configure of
261        URT when the device is opened.  Since BURT is a device
262        channel, it also has default settings for a device channel.
263        Currently there are no parameters for device setting.
264
265See Also:
266        BURT_Open(), BURT_OpenChannel()
267
268****************************************************************************/
269typedef void *BURT_Settings;
270
271typedef struct BURT_ChannelSettings
272{
273   bool         rxEnable;                               /* receiver enable */
274   bool         txEnable;                               /* transmitter enable */
275   uint32_t             baud;                                   /* baud rate */
276   BURT_DataBits bits;                                  /* number of bits */
277   BURT_Parity  parity;                                 /* parity setting */
278   bool                 intMode;                                /* interrupt enable flag. If enable, rxIntMode and txIntMode are not used */
279   bool                 rxIntMode;                              /* rx interrupt enable flag */
280   bool                 txIntMode;                              /* tx interrupt enable flag */
281   BURT_StopBits stopBits;                              /* number of stop bit */
282} BURT_ChannelSettings;
283
284/***************************************************************************
285Summary:
286        This function opens URT module.
287
288Description:
289        This function is responsible for opening BURT module. When BURT is
290        opened, it will create a module handle and configure the module based
291        on the default settings. Once the device is opened, it must be closed
292        before it can be opened again.
293
294Returns:
295        TODO:
296
297See Also:
298        BURT_Close(), BURT_OpenChannel(), BURT_CloseChannel(),
299        BURT_GetDefaultSettings()
300
301****************************************************************************/
302BERR_Code BURT_Open(
303        BURT_Handle *pURT,                                      /* [out] Returns handle */
304        BCHP_Handle hChip,                                      /* [in] Chip handle */
305        BREG_Handle hRegister,                          /* [in] Register handle */
306        BINT_Handle hInterrupt,                         /* [in] Interrupt handle */
307        const BURT_Settings *pDefSettings       /* [in] Default settings */
308        );
309
310/***************************************************************************
311Summary:
312        This function closes URT module.
313
314Description:
315        This function is responsible for closing BURT module. Closing BURT
316        will free main BURT handle. It is required that all opened
317        BURT channels must be closed before calling this function. If this
318        is not done, the results will be unpredicable.
319
320Returns:
321        TODO:
322
323See Also:
324        BURT_Open(), BURT_CloseChannel()
325
326****************************************************************************/
327BERR_Code BURT_Close(
328        BURT_Handle hDev                                        /* [in] Device handle */
329        );
330
331/***************************************************************************
332Summary:
333        This function returns the default settings for URT module.
334
335Description:
336        This function is responsible for returns the default setting for
337        BURT module. The returning default setting should be when
338        opening the device.
339
340Returns:
341        TODO:
342
343See Also:
344        BURT_Open()
345
346****************************************************************************/
347BERR_Code BURT_GetDefaultSettings(
348        BURT_Settings *pDefSettings,            /* [out] Returns default setting */
349        BCHP_Handle hChip                                       /* [in] Chip handle */
350        );
351
352/***************************************************************************
353Summary:
354        This function returns the total number of channels supported by
355        URT module.
356
357Description:
358        This function is responsible for getting total number of channels
359        supported by BURT module, since BURT device is implemented as a
360        device channel.
361
362Returns:
363        TODO:
364
365See Also:
366        BURT_OpenChannel(), BURT_ChannelDefaultSettings()
367
368****************************************************************************/
369BERR_Code BURT_GetTotalChannels(
370        BURT_Handle hDev,                                       /* [in] Device handle */
371        unsigned int *totalChannels                     /* [out] Returns total number downstream channels supported */
372        );
373
374/***************************************************************************
375Summary:
376        This function gets default setting for a URT module channel.
377
378Description:
379        This function is responsible for returning the default setting for
380        channel of BURT. The return default setting is used when opening
381        a channel.
382
383Returns:
384        TODO:
385
386See Also:
387        BURT_OpenChannel()
388
389****************************************************************************/
390BERR_Code BURT_GetChannelDefaultSettings(
391        BURT_Handle hDev,                                       /* [in] Device handle */
392        unsigned int channelNo,                         /* [in] Channel number to default setting for */
393    BURT_ChannelSettings *pChnDefSettings /* [out] Returns channel default setting */
394    );
395
396
397
398/***************************************************************************
399Summary:
400        This function resets the Tx and Rx Fifo's
401
402Description:
403
404Returns:
405        TODO:
406
407****************************************************************************/
408void BURT_ResetTxRx(
409        BURT_ChannelHandle      hChn                    /* Device channel handle */
410        );
411
412/***************************************************************************
413Summary:
414        This function opens URT module channel.
415
416Description:
417        This function is responsible for opening BURT module channel. When a
418        BURT channel is opened, it will create a module channel handle and
419        configure the module based on the channel default settings. Once a
420        channel is opened, it must be closed before it can be opened again.
421
422Returns:
423        TODO:
424
425See Also:
426        BURT_CloseChannel(), BURT_GetChannelDefaultSettings()
427
428****************************************************************************/
429BERR_Code BURT_OpenChannel(
430        BURT_Handle hDev,                                       /* [in] Device handle */
431        BURT_ChannelHandle *phChn,                      /* [out] Returns channel handle */
432        unsigned int channelNo,                         /* [in] Channel number to open */
433        const BURT_ChannelSettings *pChnDefSettings /* [in] Channel default setting */
434        );
435
436/***************************************************************************
437Summary:
438        This function closes URT module channel.
439
440Description:
441        This function is responsible for closing BURT module channel. Closing
442        BURT channel it will free BURT channel handle. It is required that all
443        opened BURT channels must be closed before closing BURT.
444
445Returns:
446        TODO:
447
448See Also:
449        BURT_OpenChannel(), BURT_CloseChannel()
450
451****************************************************************************/
452BERR_Code BURT_CloseChannel(
453        BURT_ChannelHandle hChn                         /* [in] Device channel handle */
454        );
455
456/***************************************************************************
457Summary:
458        This function gets URT module device handle based on
459        the device channel handle.
460
461Description:
462        This function is responsible returning BURT module handle based on the
463        BURT module channel.
464
465Returns:
466        TODO:
467
468See Also:
469
470****************************************************************************/
471BERR_Code BURT_GetDevice(
472        BURT_ChannelHandle hChn,                        /* [in] Device channel handle */
473        BURT_Handle *pURT                                       /* [out] Returns Device handle */
474        );
475
476/***************************************************************************
477Summary:
478        This function checks to see if data is received
479
480Description:
481        This function is used to poll for data received
482
483Returns:
484        TODO:
485
486See Also:
487
488
489****************************************************************************/
490bool BURT_IsRxDataAvailable(
491        BURT_ChannelHandle      hChn                    /* [in] Device channel handle */
492        );
493
494/***************************************************************************
495Summary:
496        This function checks to see if data is received, called in ISR
497
498Description:
499        This function is used to poll for data received, called in ISR
500
501Returns:
502        TODO:
503
504See Also:
505
506
507****************************************************************************/
508bool BURT_IsRxDataAvailable_Isr(
509        BURT_ChannelHandle      hChn                    /* Device channel handle */
510        );
511
512/***************************************************************************
513Summary:
514        This function returns the TX fifo size available
515
516Description:
517        This function gets the available TX fifo count.  If the TX fifo is empty
518        the count will be the maximum size of FIFO (in this case, it's 32 bytes).
519        If the TX fifo is not empty, it will return 0 since it doesn't know
520        exactly how many bytes are left in FIFO.  It only knows that the FIFO
521        is not empty.
522
523Returns:
524        TODO:
525
526See Also:
527
528
529****************************************************************************/
530uint32_t BURT_GetAvailTxFifoCnt (
531        BURT_ChannelHandle      hChn                    /* [in] Device channel handle */
532        );
533
534/***************************************************************************
535Summary:
536        This function returns the TX fifo size available, called in ISR
537
538Description:
539        This function gets the available TX fifo count.  If the TX fifo is empty
540        the count will be the maximum size of FIFO (in this case, it's 32 bytes).
541        If the TX fifo is not empty, it will return 0 since it doesn't know
542        exactly how many bytes are left in FIFO.  It only knows that the FIFO
543        is not empty. Called in ISR.
544
545Returns:
546        TODO:
547
548See Also:
549
550****************************************************************************/
551uint32_t BURT_GetAvailTxFifoCnt_Isr(
552        BURT_ChannelHandle      hChn                    /* Device channel handle */
553        );
554
555/***************************************************************************
556Summary:
557        This function enables or disables TX interrupt
558
559Description:
560        This function is used to turn on and off TX interrupt
561
562Returns:
563        TODO:
564
565See Also:
566
567
568****************************************************************************/
569void BURT_EnableTxInt(
570        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
571        bool                            enableTxInt             /* [in] enable flag for transmitter interrupt */
572        );
573
574/***************************************************************************
575Summary:
576        This function enables or disables RX interrupt
577
578Description:
579        This function is used to turn on and off RX interrupt
580
581Returns:
582        TODO:
583
584See Also:
585
586
587****************************************************************************/
588void BURT_EnableRxInt(
589        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
590        bool                            enableRxInt             /* [in] enable flag for receiver interrupt */
591        );
592
593/***************************************************************************
594Summary:
595        This function reads a byte from UART fifo
596
597Description:
598        This function is used to get a data byte from the UART fifo.
599
600Returns:
601        TODO:
602
603See Also:
604
605
606****************************************************************************/
607BERR_Code BURT_Read_Isr (
608        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
609        uint8_t                         *data,                  /* [in] pointer to memory to store data */
610        uint32_t                        numBytes,               /* [in] number of bytes to read */
611        uint32_t                        *bytesRead,             /* [out] number of actual bytes read */
612        BURT_RxError            *rxError                /* [out] receive error code */
613        );
614
615/***************************************************************************
616Summary:
617        This function reads a byte from UART fifo
618
619Description:
620        This function is used to get a data byte from the UART fifo.
621
622Returns:
623        TODO:
624
625See Also:
626
627
628****************************************************************************/
629BERR_Code BURT_Read (
630        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
631        uint8_t                         *data,                  /* [in] pointer to memory to store data */
632        uint32_t                        numBytes,               /* [in] number of bytes to read */
633        uint32_t                        *bytesRead,             /* [out] number of actual bytes read */
634        BURT_RxError            *rxError                /* [out] receive error code */
635        );
636
637/***************************************************************************
638Summary:
639        This function write a byte to the UART fifo
640
641Description:
642        This function is used to send a byte out of the UART.
643
644Returns:
645        TODO:
646
647See Also:
648
649
650****************************************************************************/
651BERR_Code BURT_Write (
652        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
653        uint8_t                 *data,                          /* [in] pointers to data to send */
654        uint32_t                numBytes                        /* [in] number of bytes to write */
655        );
656
657/***************************************************************************
658Summary:
659        This function gets the receive error
660
661Description:
662        This function is used to get the receive error status after an error occurs.
663
664Returns:
665        TODO:
666
667See Also:
668
669
670****************************************************************************/
671BURT_RxError BURT_GetRxError (
672        BURT_ChannelHandle      hChn                    /* [in] Device channel handle */
673        );
674
675/***************************************************************************
676Summary:
677        This function gets the receive error, called in ISR
678
679Description:
680        This function is used to get the receive error status after an error occurs. Called in ISR.
681
682Returns:
683        TODO:
684
685See Also:
686
687
688****************************************************************************/
689BURT_RxError BURT_GetRxError_Isr (
690        BURT_ChannelHandle      hChn                    /* Device channel handle */
691        );
692
693/***************************************************************************
694Summary:
695        This function gets the transmit event handle for BURT module.
696
697Description:
698        This function is responsible for getting the event handle. The
699        application code should use this function get BURT's event handle,
700        which the application should use to pend on.  The URT ISR will
701        set the event if a transmit interrupt happens.
702
703Returns:
704        TODO:
705
706See Also:
707
708****************************************************************************/
709BERR_Code BURT_GetTxEventHandle(
710        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
711        BKNI_EventHandle        *phEvent                /* [out] Returns event handle */
712        );
713
714/***************************************************************************
715Summary:
716        This function gets the receive event handle for BURT module.
717
718Description:
719        This function is responsible for getting the event handle. The
720        application code should use this function get BURT's event handle,
721        which the application should use to pend on.  The URT ISR will
722        set the event if a receive interrupt happens.
723
724Returns:
725        TODO:
726
727See Also:
728
729****************************************************************************/
730BERR_Code BURT_GetRxEventHandle(
731        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
732        BKNI_EventHandle        *phEvent                /* [out] Returns event handle */
733        );
734
735/***************************************************************************
736Summary:
737        This function registers callback function.
738
739Description:
740        This function registers callback function used during interrupt handling.
741        Normally, event is posted to notify the ocurrance of the interrupt.
742        If callback is registered, then callback function is used instead
743        of posting event.
744
745Returns:
746        TODO:
747
748See Also:
749
750****************************************************************************/
751void BURT_RegisterCallback(
752        BURT_ChannelHandle      hChn,                   /* [in] Device channel handle */
753        BINT_CallbackFunc callbackFunc  /* [in] callback function to register */
754        );
755
756#ifdef __cplusplus
757}
758#endif
759
760#endif
761
762
763
Note: See TracBrowser for help on using the repository browser.