42646ede739abc7b21ffa9259796a6ef7d66281f
[keystone-rtos/mcbsp-lld.git] / mcbsp_drv.h
1 /*
2  * mcbsp_drv.h
3  *
4  * This file contains Application programming interface for the Mcbsp driver and
5  * command/macro definitions used by the Mcbsp driver.
6  *
7  * Copyright (C) 2012 Texas Instruments Incorporated - http://www.ti.com/
8  *
9  *
10  *  Redistribution and use in source and binary forms, with or without
11  *  modification, are permitted provided that the following conditions
12  *  are met:
13  *
14  *    Redistributions of source code must retain the above copyright
15  *    notice, this list of conditions and the following disclaimer.
16  *
17  *    Redistributions in binary form must reproduce the above copyright
18  *    notice, this list of conditions and the following disclaimer in the
19  *    documentation and/or other materials provided with the
20  *    distribution.
21  *
22  *    Neither the name of Texas Instruments Incorporated nor the names of
23  *    its contributors may be used to endorse or promote products derived
24  *    from this software without specific prior written permission.
25  *
26  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
27  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
28  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
29  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
30  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
31  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
32  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
33  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
34  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
35  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
36  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37  *
38 */
40 /**
41  * \file        mcbsp_drv.h
42  *
43  * \brief       McBSP driver interface definition file
44  *
45  *              This file contains the interfaces, data types and symbolic
46  *              definitions that are needed by the application to utilize the
47  *              services of the McBSP device driver.
48  *
49  *              (C) Copyright 2012, Texas Instruments, Inc
50  *
51  */
53 #ifndef _MCBSP_DRV_H_
54 #define _MCBSP_DRV_H_
56 /*============================================================================*/
57 /*                            INCLUDE FILES                                   */
58 /*============================================================================*/
60 #ifdef __cplusplus
61 extern "C" {
62 #endif
64 /* CSL RL includes */
65 #include <ti/csl/cslr_device.h> // Freon has no cslr_device.h
66 #include <ti/csl/cslr_mcbsp.h> // Freon only has cslr directory
67 #include "mcbspver.h"
69 /*============================================================================*/
70 /*                         MACRO TYPES                                        */
71 /*============================================================================*/
73 /**
74  * \def    MCBSP_LOOPJOB_ENABLE
75  *         To enable loop job mode support in the MCBSP driver, uncomment 
76  *         following compiler switch and rebuild the MCBSP LLD.
77  */
78 /* #define MCBSP_LOOPJOB_ENABLE */
80 /**
81  * \def    Mcbsp_POLLED_RETRYCOUNT
82  *         This macro specifies the default retry count to be used by the Mcbsp
83  *         driver when polling for any hardware bit to be set or reset.
84  *
85  * \note   This default value used by the driver can be changed by an IOCTL
86  *         "Mcbsp_Ioctl_SET_TIMEOUT".
87  */
88 #define Mcbsp_POLLED_RETRYCOUNT   (0xFFFFu)
90 /**
91  * \def    MCBSP_CACHE_LENGTH
92  *         Defines the Maximum length of cache line that is possible.
93  */
94 #define MCBSP_CACHE_LENGTH        (128u)
96 /**
97  * \def    MCBSP_MAX_CACHE_ALIGN
98  *         Defines the Maximum cache line size for alignment.
99  */
100 #define MCBSP_MAX_CACHE_ALIGN        (128u)
102 /**
103  * \def    MCBSP_COMPILE_TIME_SIZE_CHECK
104  *         This macro generates compiler error if postulate is false, so 
105  *         allows 0 overhead compile time size check.  This "works" when
106  *         the expression contains sizeof() which otherwise doesn't work
107  *         with preprocessor.
108  */
109 #define MCBSP_COMPILE_TIME_SIZE_CHECK(postulate)                              \
110    do {                                                                       \
111        typedef struct {                                                       \
112          uint8_t McbspNegativeSizeIfPostulateFalse[((int)(postulate))*2 - 1]; \
113        } McbspPostulateCheck_t;                                               \
114    }                                                                          \
115    while (0)
117 /*============================================================================*/
118 /*                         ENUMERATED DATA TYPES                              */
119 /*============================================================================*/
121 /**
122  *  \brief  Mcbsp device operational mode.
123  *
124  *          This enum is used to define the operational mode of the mcbsp device
125  *          like normal mcbsp device.
126  */
127 typedef enum Mcbsp_DevMode_t
129     Mcbsp_DevMode_McBSP      = (0u)
130     /**< Option to operate in normal McBSP mode     */
132 }Mcbsp_DevMode;
133 /**< Mcbsp device operational mode.       */
135 /**
136  *  \brief  Mcbsp driver operational mode
137  *
138  *          Enumeration of the different modes of operation available for the
139  *          Mcbsp device driver.(Mcbsp driver supports only EDMA mode).
140  */
141 typedef enum Mcbsp_OpMode_t
143     Mcbsp_OpMode_POLLED = 0,
144     /**< Polled Mode                     */
146     Mcbsp_OpMode_INTERRUPT,
147     /**< Interrupt Mode                  */
149     Mcbsp_OpMode_DMAINTERRUPT
150     /**< DMA Mode                        */
152 }Mcbsp_OpMode;
153 /**< Mcbsp driver operational mode       */
155 /**
156  * \brief   Mcbsp Emulation mode settings
157  *
158  *          Use this symbol to set the Emulation Mode to Free mode or any other 
159  *          mode.
160  *
161  * \note    The SOFT mode settings are applicable only is the FREE mode is
162  *          disabled.Hence if the soft mode is selected (both enable or disable)
163  *          the driver will internally disable the FREE mode.
164  */
165 typedef enum Mcbsp_EmuMode_t
167     Mcbsp_EmuMode_SOFT_ABORT  = (0u),
168     /**< SOFT mode is disabled.          */
170     Mcbsp_EmuMode_SOFT_STOP   = (1u),
171     /**< SOFT mode is enabled            */
173     Mcbsp_EmuMode_FREE        = (2u)
174     /**< FREE mode is enabled            */
176 }Mcbsp_EmuMode;
177 /**< Mcbsp emulation modes               */
179 /**
180  *  \brief  McBSP digital loopback mode selection
181  *
182  *          Enum to select the enable/disable of Loopback mode of the mcbsp.
183  */
184 typedef enum Mcbsp_Loopback_t
186     Mcbsp_Loopback_DISABLE = 0,
187     /**< loopback mode off                 */
189     Mcbsp_Loopback_ENABLE = 1
190     /**< loopback mode on                  */
192 } Mcbsp_Loopback;
193 /**< McBSP digital loopback mode selection */
195 /**
196  * \brief   ENUM for receive data justification settings
197  *
198  *          Use this symbol for setting up RCV sign-extension and justification
199  *          mode
200  */
201 typedef enum Mcbsp_Rxjust_t
203     Mcbsp_RxJust_RZF        = (0u),
204     /**< RCV setting - right justify, fill MSBs with zeros                    */
206     Mcbsp_RxJust_RSE        = (1u),
207     /**< RCV setting - right justify, sign-extend the data into MSBs          */
209     Mcbsp_RxJust_RxJUST_LZF = (2u)
210     /**< RCV setting - left justify, fill LSBs with zeros                     */
212 }Mcbsp_Rxjust;
213 /**< Enumeration for the Receive data justification                           */
215 /**
216  * \brief   Transmit pin mode configuration
217  *
218  *          DX pin settings used for setting the pin in high impedance mode.
219  */
220 typedef enum Mcbsp_DxEna_t
222     Mcbsp_DxEna_OFF  = (0),
223     /**< DX enabler is OFF                       */
225     Mcbsp_DxEna_ON   = (1u)
226     /**< DX enabler is ON                        */
227 }Mcbsp_DxEna;
228 /**< DX pin High impedance enable/disable option */
230 /**
231  * \brief Polarity of the CLKS pin
232  *
233  *        Enum to Set the polarity of the CLKS pin used to generate Frame Sync
234  *        and bit clock
235  */
236 typedef enum Mcbsp_ClkSPol_t
238     Mcbsp_ClkSPol_RISING_EDGE   = 0,
239     /**< Rising edge of CLKS generates CLKG and FSG.                          */
241     Mcbsp_ClkSPol_FALLING_EDGE  = 1
242     /**< Falling edge of CLKS generates CLKG and FSG.                         */
244 }Mcbsp_ClkSPol;
245 /**< Polarity of the CLKS pin                                                 */
247 /**
248  * \brief   SRG clock source
249  *
250  *          Use this symbol to select input clock source for Sample Rate
251  *          Generator
252  */
253 typedef enum Mcbsp_SrgClk_t
255     Mcbsp_SrgClk_CLKS   = (0u),
256     /**< input clock source for Sample Rate Generator is CLKS pin             */
258     Mcbsp_SrgClk_CLKCPU = (1u),
259     /**< input clock source for Sample Rate Generator is CPU                  */
261     Mcbsp_SrgClk_CLKR   = (2u),
262     /**< input clock source for Sample Rate Generator is BCLKR pin            */
264     Mcbsp_SrgClk_CLKX   = (3u)
265     /**< input clock source for Sample Rate Generator is BCLKX pin            */
267 }Mcbsp_SrgClk;
268 /**< SRG clock source selection                                               */
270 /**
271  * \brief Enum to specify the supported buffer formats.
272  *
273  * Interleaved and non-interleaved is standard format, this enumeration
274  * captures the standard and custom data formats.
275  */
276 typedef enum Mcbsp_BufferFormat_t
278     /* This mode is used for buffer containing the data in continous      *
279      * memory locations where each sample is  "wordWidth" long. This      *
280      * format is supported for following configurations                   *
281      * Note : interleaved and non interleaved does not apply for this     *
282      * buffer format                                                      */
283     Mcbsp_BufferFormat_1SLOT,
285     /* This is used for transfer of data with multiple slots.please note  *
286      * that the slot data is not interleaved in this format.              */
287     Mcbsp_BufferFormat_MULTISLOT_NON_INTERLEAVED,
289     /* This is used for transfer of data for multiple slots.please note   *
290      * that the slot data is interleaved in this format.                  */
291     Mcbsp_BufferFormat_MULTISLOT_INTERLEAVED
292 }Mcbsp_BufferFormat;
293 /**< Mcbsp supported buffer formats                                       */
295 /**
296  * \brief Mcbsp PHASE control enums
297  *
298  * \note These enums are used to control the Phase settings of the MCBSP.
299  */
300 typedef enum Mcbsp_Phase_t
302     Mcbsp_Phase_SINGLE = (0u),
303     /**< Single phase for frame                */
305     Mcbsp_Phase_DUAL   = (1u)
306     /**< Dual phase for frame                  */
307 } Mcbsp_Phase;
308 /**< Mcbsp frame phase selection ENUMERATION   */
310 /**
311  *  \brief  Mcbsp supported wordlength.
312  *
313  *          Enumerated constant for wordlength supported by the MCBSP device
314  */
315 typedef enum Mcbsp_WordLength_t
317     Mcbsp_WordLength_8  = 8u,
318     /**< Word length of 8 bits            */
320     Mcbsp_WordLength_12 = 12u,
321     /**< Word length of 12 bits           */
323     Mcbsp_WordLength_16 = 16u,
324     /**< Word length of 16 bits           */
326     Mcbsp_WordLength_20 = 20u,
327     /**< Word length of 20 bits           */
329     Mcbsp_WordLength_24 = 24u,
330     /**< Word length of 24 bits           */
332     Mcbsp_WordLength_32 = 32u
333     /**< Word length of 32 bits           */
335 }Mcbsp_WordLength;
336 /**< Mcbsp supported wordlength.          */
338 /**
339  * \brief   Frame sync ignore status enum
340  *
341  * \note    Use this symbol to detect or ignore frame synchronisation
342  */
343 typedef enum Mcbsp_FrmSync_t
345     Mcbsp_FrmSync_DETECT  = (0u),
346     /**< detect frame synchronisation          */
348     Mcbsp_FrmSync_IGNORE  = (1u)
349     /**< ignore frame synchronisation          */
351 }Mcbsp_FrmSync;
352 /**< Frame sync detection options ENUMERATION  */
354 /**
355  * \brief   Enum to select Data delay in bits
356  *
357  *          Use this Enum to set XMT/RCV Data Delay (in bits)
358  */
359 typedef enum Mcbsp_DataDelay_t
361     Mcbsp_DataDelay_0_BIT = (0u),
362     /**< sets XMT/RCV Data Delay to 0 bits     */
364     Mcbsp_DataDelay_1_BIT = (1u),
365     /**< sets XMT/RCV Data Delay to 1 bits     */
367     Mcbsp_DataDelay_2_BIT = (2u)
368     /**< sets XMT/RCV Data Delay to 2 bits     */
370 } Mcbsp_DataDelay;
371 /**< Enum to select Data delay in bits         */
373 /**
374  * \brief   Enum to select the companding law
375  *
376  *          Use this Enum to select the appropriate companding rule applicable.
377  */
378 typedef enum Mcbsp_Compand_t
380     Mcbsp_Compand_OFF_MSB_FIRST =  (0u),
381     /**< No companding, data transfer starts with MSB first.                  */
383     Mcbsp_Compand_OFF_LSB_FIRST =  (1u),
384     /**< No companding, 8-bit data transfer starts with LSB first.            */
386     Mcbsp_Compand_MULAW         =  (2u),
387     /**< mu-law comapanding enable for channel                                */
389     Mcbsp_Compand_ALAW          =  (3u)
390     /**< A-law comapanding enable for channel                                 */
392 }Mcbsp_Compand;
393 /**< Enum to select the companding law         */
395 /**
396  * \brief   McBSP 32-bit reversal feature
397  *
398  *          This ENUM allows the user to select the option of BIT reversal.
399  */
400 typedef enum Mcbsp_BitReversal_t
402     Mcbsp_BitReversal_DISABLE   = (0u),
403     /**< 32-bit reversal disabled                                             */
405     Mcbsp_BitReversal_ENABLE    = (1u)
406     /**< 32-bit reversal enabled. 32-bit data is received LSB first. Word     *
407      * length should be set for 32-bit operation; else operation undefined    */
409 }Mcbsp_BitReversal;
410 /**< McBSP 32-bit reversal feature                                            */
412 /**
413  * \brief   Frame sync clock source
414  *
415  *          Use this ENUM to set the frame sync clock source as internal or
416  *          external
417  */
418 typedef enum Mcbsp_FsClkMode_t
420     Mcbsp_FsClkMode_EXTERNAL = (0u),
421     /**< frame sync clock source as internal     */
423     Mcbsp_FsClkMode_INTERNAL = (1u),
424     /**< frame sync clock source as external     */
426     Mcbsp_FsClkMode_DXR_XSR  = (2u)
427     /**< frame sync is generated on DXR_XSR copy */
428     
429 } Mcbsp_FsClkMode;
430 /**< Frame sync clock source                     */
432 /**
433  * \brief   Clock source selection ENUM
434  *
435  *          Use this symbol to set the clock source as internal or external
436  */
437 typedef enum Mcbsp_TxRxClkMode_t
439     Mcbsp_TxRxClkMode_EXTERNAL = (0u),
440     /**< clock source as internal */
442     Mcbsp_TxRxClkMode_INTERNAL = (1u)
443     /**< clock source as external */
445 } Mcbsp_TxRxClkMode;
446 /**< Clock source selection ENUM  */
448 /**
449  * \brief   Clock polarity
450  *
451  *          Use this symbol to set XMT or RCV clock polarity as rising or
452  *          falling edge
453  */
454 typedef enum Mcbsp_ClkPol_t
456     Mcbsp_ClkPol_RISING_EDGE  = (0u),
457     /**< Data sampled on rising edge of the bit Clock                         */
459     Mcbsp_ClkPol_FALLING_EDGE = (1u),
460     /**< Data sampled on falling edge of the bit Clock                        */
462     Mcbsp_ClkPol_SRG_RISING_EDGE = (0u),
463     /**< SRG clock polarity is rising edge      */
465     Mcbsp_ClkPol_SRG_FALLING_EDGE = (1u)
466    /**< SRG clock polarity Is falling edge      */
468 } Mcbsp_ClkPol;
469 /**< Clock polarity                             */
471 /**
472  * \brief   Frame sync polarity
473  *
474  *          Use this symbol to set frame sync polarity as active-high or
475  *          active-low
476  */
477 typedef enum Mcbsp_FsPol_t
479     Mcbsp_FsPol_ACTIVE_HIGH   = (0u),
480     /**< frame sync polarity is active-high */
482     Mcbsp_FsPol_ACTIVE_LOW    = (1u)
483     /**< frame sync polarity is active-low  */
485 }Mcbsp_FsPol;
486 /**< Frame sync polarity                                                      */
488 /**
489  * \brief   MCBSP Interrupt mode
490  *
491  *          Use this symbol to set Interrupt mode (i.e. source of interrupt
492  *          generation).This symbol is used on both RCV and XMT for RINT and
493  *          XINT generation mode.
494  */
495 typedef enum Mcbsp_IntMode_t
497     Mcbsp_IntMode_ON_READY   = (0u),
498     /**< Interrupt generated on RRDY of RCV or XRDY of XMT                    */
500     Mcbsp_IntMode_ON_EOB     = (1u),
501     /**< Interrupt generated on end of 16-channel block transfer in           *
502      *   multichannel mode                                                    */
504     Mcbsp_IntMode_ON_FSYNC   = (2u),
505     /**< Interrupt generated on frame sync                                    */
507     Mcbsp_IntMode_ON_SYNCERR = (3u)
508     /**< Interrupt generated on synchronisation error                         */
510 }Mcbsp_IntMode;
511 /**< MCBSP Interrupt mode                                                     */
513 /**
514  * \brief    Transmit multichannel selection mode bit.
515  *            
516  *           MCM determines whether all channels or only selected channels are 
517  *           enabled and unmasked for transmission/reception.
518  *
519  */
520 typedef enum Mcbsp_McmMode_t
522     Mcbsp_McmMode_ALL_CHAN_ENABLED_UNMASKED  = (0u),
523     /**< All the 128 channels are enabled                                     */
525     Mcbsp_McmMode_ALL_CHAN_DISABLED_UNMASKED = (1u),
526     /**< All channels are disabled unless selected by enable mask             */
528     Mcbsp_McmMode_ALL_CHAN_ENABLED_MASKED    = (2u),
529     /**< All channels are enabled but masked unless selected by Enable mask   */
531     Mcbsp_McmMode_ALL_CHAN_DISABLED_MASKED   = (3u)
532     /**< Symmetric transmission and reception                                 */
534 }Mcbsp_McmMode;
535 /**< Transmit multichannel selection mode bit.                                */
537 /**
538  * \brief      Partition A/B block channel selection bit.
539  */
540 typedef enum Mcbsp_PartitionSel_t
542     Mcbsp_PartitionMode_CHAN_0_15    = (0u),
543     /**< Select the channel 0-15 in block A     */
544     
545     Mcbsp_PartitionMode_CHAN_16_31   = (0u),
546     /**< Select the channel 16-31 in block B    */
548     Mcbsp_PartitionMode_CHAN_32_47   = (1u),
549     /**< Select the channel 32-47 in block A    */
551     Mcbsp_PartitionMode_CHAN_48_63   = (1u),
552     /**< Select the channel 48-63 in block B    */
553     
554     Mcbsp_PartitionMode_CHAN_64_79   = (2u),
555     /**< Select the channel 64-79 in block A    */
557     Mcbsp_PartitionMode_CHAN_80_95   = (2u),
558     /**< Select the channel 80-95 in block B    */
560     Mcbsp_PartitionMode_CHAN_96_111  = (3u),
561     /**< Select the channel 96-111 in block A   */
563     Mcbsp_PartitionMode_CHAN_112_127 = (3u)
564     /**< Select the channel 112-127 in block B  */
566 }Mcbsp_PartitionSel;
567 /**< Partition A/B block selection bit. */
569 /**
570  * \brief    Multichannel partition mode selection.
571  *
572  *           Multichannel mode allows selection of either an 2 partition mode or
573  *           8 partition mode.This enum allows the user to select the required
574  *           partition mode of choice.
575  */
576 typedef enum Mcbsp_PartitionMode_t
578     Mcbsp_PartitionMode_2 = (0u),
579     /**< 2-partition mode. Only partitions A and B are used.      */
580     
581     Mcbsp_PartitionMode_8 = (1u)
582     /**< 8-partition mode. All partitions (A through H) are used  */
584 }Mcbsp_PartitionMode;
585 /**< Multichannel partition mode selction                         */
587 /*============================================================================*/
588 /*                              DATA STRUCTURES                               */
589 /*============================================================================*/
591 /**
592  *  \brief McBSP sample rate generator configuration structure
593  *
594  *         Configurations for the Sample rate  generator to generate the BCLK 
595  *         and Frame Sync signals are specified using this structure.
596  */
597 typedef struct Mcbsp_srgConfig_t
599     Bool             gSync;
600     /**< sample rate generator clock syncronization bit (only if CLKS is used)*/
602     Mcbsp_ClkSPol    clksPolarity;
603     /**< CLKS polarity used to drive the CLKG and FSG clocks                  */
605     Mcbsp_SrgClk     srgInputClkMode;
606     /**< Source for the Sample rate generator (CLKS,CPU,CLKX,CLKR)            */
608     uint32_t         srgrInputFreq;
609     /**< input clock frequency for the SRGR (freq of CLKS or CLKX etc..)      */
611     uint32_t         srgFrmPulseWidth;
612     /**< Set the Frame Sync Pulse width in terms of FSG clock                 */
614 } Mcbsp_srgConfig;
615 /**< McBSP sample rate generator configuration structure                      */
617 /**
618  * \brief   Mcbsp TX/RX section configuration structure.
619  *
620  *          This strcuture specifies the configuration for the McBSP data stream
621  *          including the whether it is single phase or dual phase, number of
622  *          frames,the word length in each phase and data delay etc.
623  */
624 typedef struct Mcbsp_DataConfig_t
626     Mcbsp_Phase               phaseNum;
627     /**< Phase of the McBSP data stream                                       */
629     Mcbsp_WordLength          wrdLen1;
630     /**< Length of the data word in first phase                               */
632     Mcbsp_WordLength          wrdLen2;
633     /**< Length of the data word in second when dual phase is selected        */
635     uint32_t                  frmLen1;
636     /**< Length of the data frame in first phase                              */
638     uint32_t                  frmLen2;
639     /**< Length of the data frame in second phase                             */
641     Mcbsp_FrmSync             frmSyncIgn;
642     /**< Frame sync ignore bit                                                */
644     Mcbsp_DataDelay           dataDelay;
645     /**< Data delay to be configured in number of Bits                        */
647     Mcbsp_Compand             compandSel;
648     /**< companding selection                                                 */
650     Mcbsp_BitReversal         bitReversal;
651     /**< Transmit 32-bit bit reversal feature enable bit.                     */
653     Mcbsp_IntMode             intMode;
654     /**< Event for which the interrupt is to be generated                     */
656     Mcbsp_Rxjust              rjust;
657     /**< Receive sign extension and justification settings (RX only setting)  */
658     
659     Mcbsp_DxEna               dxState;
660     /**< High impedance enable/disbale bit for the DX pin (TX only setting)   */
661     
662 }Mcbsp_DataConfig;
663 /**< Mcbsp TX/RX section configuration structure.                             */
665 /**
666  * \brief   Mcbsp multi channel control settings
667  *
668  *          structure to configure the multi channel settings for the mcbsp.used
669  *          when the multi channel configuration is to be enabled.
670  */
671 typedef struct Mcbsp_McrSetup_t
673     Mcbsp_McmMode          multiChanMode;
674     /**< Multi channel mode to be selcted                                     */  
676     Mcbsp_PartitionSel     partitionSelA;
677     /**< Channel selection for partition A                                    */
679     Mcbsp_PartitionSel     partitionSelB;
680     /**< Channel selection for partition B                                    */
682     Mcbsp_PartitionMode    partitionMode;
683     /**< Channel partition mode selection                                     */
684 }Mcbsp_McrSetup;
685 /**< Mcbsp multi channel control settings                                     */
687 /**
688  * \brief   Mcbsp clock settings setup structure.
689  *
690  *          This structure contains the information required to configure the 
691  *          clocks for the Mcbsp.Both the frame sync settings and the bit clock
692  *          settings can be configured in this structure.
693  */
694 typedef struct Mcbsp_ClkSetup_t
696     Mcbsp_FsClkMode        frmSyncMode;
697     /**< Frame sync mode bit (FSXM/FSRM)(Internal/External)                   */
699     uint32_t                 samplingRate;
700     /**< Frame sync frequency                                                 */
702     Mcbsp_TxRxClkMode      clkMode;
703     /**< Bit clock mode (internal or external)                                */
705     Mcbsp_FsPol            frmSyncPolarity;
706     /**< frmSyncTxPolarity                                                    */
708     Mcbsp_ClkPol           clkPolarity;
709     /**< clkTxPolarity                                                        */
710 }Mcbsp_ClkSetup;
711 /**< Mcbsp clock settings setup structure                                     */
713 /**
714  * \brief Mcbsp Hardware specific information Object
715  *
716  *  This structure maintains the information specific to the hardware instance
717  *  of the Mcbsp. information like the base address and the cpu event numbers
718  *  and DMA events is specific to the instance. This structure is a collection
719  *  of such information.
720  */
721 typedef struct 
723     uint32_t               instNum;
724     /**< Instance of MCBSP being referred by this object                      */
726     CSL_McbspRegsOvly    regs;
727     /**< Pointer to the register overlay structure of the MCBSP               */
729     CSL_BfifoRegsOvly    fifoRegs;
730     /**< Fifo address of the mcbsp instance                                   */
732     CSL_BdataRegsOvly    dataAddress;
733     /**< Mcbsp data registers address                                         */
735     uint32_t               edmaTxEventNum;
736     /**< edma Transmit event number                                           */
738     uint32_t               edmaRxEventNum;
739     /**< edma Receive event number                                            */
741     uint32_t               cpuTxEventNum;
742     /**< Transmit interrupt number                                            */
744     uint32_t               cpuRxEventNum;
745     /**< Receive interrupt number                                             */
747 }Mcbsp_HwInfo_Unpadded;
749 typedef struct
751     /** Data structure without padding, so sizeof() can compute padding */
752     Mcbsp_HwInfo_Unpadded obj;
753     /** Pad out to end of MCBSP_MAX_CACHE_ALIGN bytes to prevent something else
754      * from being placed on same cache line as Mcbsp_HwInfo. Note that pad[0]
755      * is illegal, so must add full MCBSP_MAX_CACHE_ALIGN if structure is
756      * already padded by chance. */
757     uint8_t                 pad[MCBSP_MAX_CACHE_ALIGN - 
758                             (sizeof(Mcbsp_HwInfo_Unpadded) % MCBSP_MAX_CACHE_ALIGN)];
759 } Mcbsp_HwInfo;
760 /**< Mcbsp Hardware specific information Object                               */
762 /**
763  *  \brief  Loop job buffer structure.
764  *          This structure defines the format of the Loop job buffer.
765  *
766  *  \note   Loop job buffer is a buffer used by the mcbsp in edma mode. The 
767  *          Mcbsp uses this buffer when no iobufs are present and the mcbsp 
768  *          is also not stopped. In this condition the Mcbsp utilises the 
769  *          loop job buffer to transmit a known pattern of data from the loopjob
770  *          buffer or receives the data in to a loop job buffer
771  */
772 typedef struct Mcbsp_TempBuffer_t
774     Uint8   scratchBuf[(4u) + MCBSP_CACHE_LENGTH];
775     /**< This buffer will be aligned and also the same buffer will be used
776      * for all slots and also only 4 bytes are required because the
777      * max wordwidth is 4 and the cache length is used for buffer alignment   */
778     uint32_t *scratchBuffer;
779     /**< Pointer to hold the aligned buffer                                   */
780 }Mcbsp_TempBuffer;
781 /**< loop job buffer format.                                                  */
783 /*============================================================================*/
784 /*                               DATA TYPES                                   */
785 /*============================================================================*/
787 /**
788  * \brief Global error callback function protype
789  *
790  *        This is the global error callback function for the McBSP driver.
791  *        This function is called directly called from ISR context in case of
792  *        error.
793  * \note  Since this function is called from an ISR context,care should be taken
794  *        that this function conforms to ISR coding guidelines.
795  */
796 typedef void (*Mcbsp_GblErrCallback)(uint32_t Arg1,uint32_t Arg2,uint32_t Arg3);
798 /**
799  *  \brief  McBSP channel setup params
800  *
801  *          This structure holds configuration to be used for
802  *          creating a channel of the Mcbsp. These parameters need to be 
803  *          specified during the creation of the channel.
804  */
805 typedef struct Mcbsp_ChanParams_t
807     uint32_t                  wordWidth;
808     /**< This parameter informs the driver what is the width word (not        *
809      * slot) and this help driver indirectly to decided no. of bytes to       *
810      * be transfered for each slot- This is very                              *
811      * important parameter - in case of invalid value default value           *
812      * driver will assume is 32                                               */
814     void*                     userLoopJobBuffer;
815     /**< Buffer to be transferred when the loop job is running.               */
817     uint16_t                  userLoopJobLength;
818     /**< Number of bytes of the userloopjob buffer for each slot
819      * Please note that this is no. of bytes and this should be
820      * pre-calcuated properly for word width of slot - Please refer the
821      * wordWidth of this structure                                            */
823     Mcbsp_GblErrCallback    gblCbk;
824     /**< callback required when global error occurs - must be callable        *
825      * directly from the ISR context                                          */
827     void*                     edmaHandle;
828     /**< Handle to the EDMA Driver                                            */
830     uint32_t                  edmaEventQue;
831     /**< EDMA event queue to be used by the channel                           */
833     uint32_t                  hwiNumber;
834     /**< Variable to specify the Hwi number to be used by the driver          */
836     Mcbsp_BufferFormat      dataFormat;
837     /**< Format of the application supplied buffer                            */
839     Bool                    enableHwFifo;
840     /**< Option to enable/disable the Hardware FIFO                           */
842     Mcbsp_DataConfig       *chanConfig;
843     /**< settings to configure the TX or RX hardware sections                 */
845     Mcbsp_ClkSetup         *clkSetup;
846     /**< clock setup for the RX or the TX section                             */
848     Mcbsp_McrSetup         *multiChanCtrl;
849     /**< multiple channel control settings                                    */
851     uint32_t                  chanEnableMask[4];
852     /**< Mask of the channels to be enabled or disabled                       */
854     uint32_t               numEnabledChannels;
855     /**< Number of channels enabled with multichannel mode
856      *   Note: This should match the number of bits in chanEnable Mask if in
857      *         Mcbsp_McmMode_ALL_CHAN_DISABLED_UNMASKED  mode                 */
859 }Mcbsp_ChanParams;
860 /**< Mcbsp Channel setup parameters                                           */
862 /**
863  *  \brief  McBSP device create params
864  *
865  *          This structure holds the configuration to be used for the
866  *          creation of the Mcbsp device instance.This configuration need to be
867  *          supplied during the creation of the device instance.
868  */
869 typedef struct Mcbsp_Params_t
871     Mcbsp_DevMode           mode;
872     /**< Mode in which mcbsp instance needs to be created                     */
874     Mcbsp_OpMode            opMode;
875     /**< Operation mode of driver i.e. interrupt or EDMA.Mcbsp supports only
876      *   EDMA mode                                                            */
878     Bool                    enablecache;
879     /**< whether the cache operations are to be performed on the application
880      *   buffers or not                                                       */
882     Mcbsp_EmuMode           emulationMode;
883     /**< Emulation mode settings for the Mcbsp                                */
885     Mcbsp_Loopback          dlbMode;
886     /**< digital loop back mode (ENABLE/DISABLE)                              */
888     Mcbsp_srgConfig        *srgSetup;
889     /**< configuration for the sample rate generator configurations           */
891     void*                   txQPendingList;
892     /**< Queue to hold the pending buffers received from the application      */
893   
894     void*                   txQFloatingList;
895     /**< Queue to manage floating buffers in DMA                              */
897     void*                   rxQPendingList;
898     /**< Queue to hold the pending buffers received from the application      */
900     void*                   rxQFloatingList;
901     /**< Queue to manage floating buffers in DMA                              */
903 } Mcbsp_Params;
904 /**< McBSP device setup params                                                */
906 /**
907  *  \brief  McBSP queue element
908  *
909  *          Doubly linked list for queue elements. 
910  *          Required for Mcbsp_IOBuf structure. 
911  */
912 typedef struct Mcbsp_QueueElem_t {
913     struct Mcbsp_QueueElem_t* volatile  next;
914     struct Mcbsp_QueueElem_t* volatile  prev;
915 } Mcbsp_QueueElem;
917 /**
918  *  \brief  McBSP frame object params
919  *
920  *          Mcbsp_IOBuf structures are managed by the driver. MCBSP 
921  *          buffers are the basis for all I/O operations. 'cmd' field 
922  *          contains the command id for the driver. 'status' is filled 
923  *          in by the driver and contains the status of the commmand.
924  */
925 typedef struct Mcbsp_IOBuf_t 
927     Mcbsp_QueueElem     link;
928     /**< queue link                */
930     void*               addr;
931     /**< buffer address            */
933     uint32_t            size;   
934     /**< buffer size               */
936     uint32_t            arg;    
937     /**< arg to be used by end app */
939     uint32_t            cmd;    
940     /**< command for driver - READ, WRITE, ABORT or FLUSH  */
942     int32_t             status; 
943     /**< status of command         */
945     uint32_t            misc;   
946     /**< reserved for driver       */
947 } Mcbsp_IOBuf;
948 /**< Mcbsp frame object params     */
950 /**
951  *  \brief MCBSP driver callback function
952  *
953  *         This is the driver's callback function. The driver will
954  *         call a function of this type whenever an I/O operation
955  *         is over.
956  */
957 typedef void (*Mcbsp_CallbackFxn)(void* arg, Mcbsp_IOBuf *ioBuf);
959 /*============================================================================*/
960 /*                           IOCTL COMMANDS                                   */
961 /*============================================================================*/
963 /**
964  *  \brief  McBSP Ioctl commands
965  *
966  *          List of all the ioctl commands supported by the Mcbsp driver.
967  *
968  */
969 typedef enum Mcbsp_IOCTL_t
971     Mcbsp_IOCTL_START = 128,
972     /**< Starts the data transfer                                             */
974     Mcbsp_IOCTL_SAMPLE_RATE_CHANGE,
975     /**< Command to chnage the sample rate                                    */
977     Mcbsp_IOCTL_STOP,
978     /**< Stops the data transfer                                              */
980     Mcbsp_IOCTL_SRGR_START,
981     /**< Start the McBSP SRG                                                  */
983     Mcbsp_IOCTL_SRGR_STOP,
984     /**< Stop the McBSP SRG                                                   */
986     Mcbsp_IOCTL_FSGR_START,
987     /**< Start the McBSP FSG                                                  */
989     Mcbsp_IOCTL_FSGR_STOP,
990     /**< Stop the McBSP FSG                                                   */
992     Mcbsp_IOCTL_SET_TIMEOUT,
993     /**< Modify the timeout value in the driver                               */
995     Mcbsp_IOCTL_MUTE_ON,
996     /**< Mute ON the transfer                                                 */
998     Mcbsp_IOCTL_MUTE_OFF,
999     /**< Take out of Muted state                                              */
1001     Mcbsp_IOCTL_PAUSE,
1002     /**< Pause the playback operation                                         */
1004     Mcbsp_IOCTL_RESUME,
1005     /**< Resume the playback operation                                        */
1007     Mcbsp_IOCTL_CHAN_RESET,
1008     /**< Reset an I/O channel                                                 */
1010     Mcbsp_IOCTL_DEVICE_RESET,
1011     /**< Reset both input and output channel                                  */
1013     Mcbsp_IOCTL_SET_CLKMODE,
1014     /**< Set Bit clock mode for the McBSP                                     */
1016     Mcbsp_IOCTL_SET_FRMSYNCMODE,
1017     /**< Set Frame Sync mode for the McBSP                                    */
1019     Mcbsp_IOCTL_CONFIG_SRGR,
1020     /**< configure Sample Rate Generator                                      */
1022     Mcbsp_IOCTL_SET_BCLK_POL,
1023     /**< Set the CLKR or CLKX clock polarity                                  */
1025     Mcbsp_IOCTL_SET_FRMSYNC_POL,
1026     /**< Set the FSR and FSX polarity                                         */
1028     Mcbsp_IOCTL_MODIFY_LOOPJOB,
1029     /**< Enable/disable the loopjob                                           */
1031     Mcbsp_IOCTL_SYNCERR_INT_ENABLE,
1032     /**< Enable/disable the sync error                                        */
1034     Mcbsp_IOCTL_LOOPBACK,
1035     /**< enable/disable the loop back mode                                    */
1037     Mcbsp_IOCTL_CANCEL_PENDING_IO
1038     /**< Cancel all the current pending IO in the driver                      */
1040 } Mcbsp_IOCTL;
1041 /**< McBSP Ioctl commands list */
1043 /*============================================================================*/
1044 /*                           MCBSP MODES                                      */
1045 /*============================================================================*/
1046 /**
1047  *  \brief  McBSP Create Modes
1048  *
1049  *          Mcbsp driver create functions take a mode parameter.
1050  *
1051  */
1052 /**
1053  * \def    MCBSP_MODE_INPUT
1054  *         Defines the mode as input.
1055  */
1056 #define MCBSP_MODE_INPUT    0x0001
1057 /**
1058  * \def    MCBSP_MODE_OUTPUT
1059  *         Defines the mode as output.
1060  */
1061 #define MCBSP_MODE_OUTPUT   0x0002
1062 /**
1063  * \def    MCBSP_MODE_INOUT
1064  *         Defines the mode as input and output.
1065  */
1066 #define MCBSP_MODE_INOUT    (MCBSP_MODE_INPUT | MCBSP_MODE_OUTPUT)
1068 /*============================================================================*/
1069 /*                           MCBSP STATUS CODES                               */
1070 /*============================================================================*/
1071 /**
1072  *  \brief  McBSP Driver Status Codes
1073  *
1074  *          Mcbsp driver status codes.
1075  *
1076  */
1077 /**
1078  * \def    MCBSP_STATUS_COMPLETED
1079  *         Defines the status as completed successfully.
1080  */
1081 #define  MCBSP_STATUS_COMPLETED     0
1082 /**
1083  * \def    MCBSP_STATUS_PENDING
1084  *         Defines the status as queued and pending.
1085  */
1086 #define  MCBSP_STATUS_PENDING       1
1087 /**
1088  * \def    MCBSP_STATUS_FLUSHED
1089  *         Defines the status as request flushed. Queued writes 
1090  *         will be completed w/ MCBSP_STATUS_COMPLETED. Queued 
1091  *         read requests return w/ MCBSP_STATUS_FLUSHED.
1092  */
1093 #define  MCBSP_STATUS_FLUSHED      2 
1095 /**
1096  * \def    MCBSP_STATUS_ABORTED
1097  *         Defines the status as request aborted. Non-completed
1098  *         read or write requests return w/ MCBSP_STATUS_ABORTED.
1099  */
1100 #define  MCBSP_STATUS_ABORTED      3      
1103 /*============================================================================*/
1104 /*                           MCBSP DRIVER ERROR CODES                         */
1105 /*============================================================================*/
1106 /**
1107  *  \brief  McBSP Driver Error Codes
1108  *
1109  *          Mcbsp driver error codes.
1110  *
1111  */
1112 /**
1113  * \def    MCBSP_ERR_BADIO
1114  *         Generic failure condition
1115  */
1116 #define  MCBSP_ERR_BADIO        -1
1117 /**
1118  * \def    MCBSP_ERR_TIMEOUT
1119  *         Timeout occurred
1120  */
1121 #define  MCBSP_ERR_TIMEOUT      -2
1122 /**
1123  * \def    MCBSP_ERR_NOIOBUFFERS
1124  *         No buffers available for I/O
1125  */
1126 #define  MCBSP_ERR_NOIOBUFFERS  -3
1127 /**
1128  * \def    MCBSP_ERR_FREE
1129  *         Unable to free resources
1130  */
1131 #define  MCBSP_ERR_FREE         -4
1132 /**
1133  * \def    MCBSP_ERR_ALLOC
1134  *         Unable to allocate resource
1135  */
1136 #define  MCBSP_ERR_ALLOC        -5
1137 /**
1138  * \def    MCBSP_ERR_ABORT
1139  *         I/O was aborted before completed
1140  */
1141 #define  MCBSP_ERR_ABORT        -6
1142 /**
1143  * \def    MCBSP_ERR_BADMODE
1144  *         Invalid device mode
1145  */
1146 #define  MCBSP_ERR_BADMODE      -7
1147 /**
1148  * \def    MCBSP_ERR_EOF
1149  *         End-of-File was encountered
1150  */
1151 #define  MCBSP_ERR_EOF          -8
1152 /**
1153  * \def    MCBSP_ERR_NOTIMPL
1154  *         Operation not implemented or supported
1155  */
1156 #define  MCBSP_ERR_NOTIMPL      -9
1157 /**
1158  * \def    MCBSP_ERR_BADARGS
1159  *         Invalid arguments specified
1160  */
1161 #define  MCBSP_ERR_BADARGS      -10
1162 /**
1163  * \def    MCBSP_ERR_TIMEOUTUNREC
1164  *         Unrecoverable timeout occurred
1165  */
1166 #define  MCBSP_ERR_TIMEOUTUNREC -11
1167 /**
1168  * \def    MCBSP_ERR_INUSE
1169  *         Device already in use
1170  */
1171 #define  MCBSP_ERR_INUSE        -12
1173 /**
1174  *  \brief  McBSP Driver Buffer Frame Command Codes
1175  *
1176  *          Mcbsp driver frame command codes.
1177  *
1178  */
1179 /**
1180  * \def    Mcbsp_IOBuf_Cmd_READ
1181  *         Read command
1182  */
1183 #define Mcbsp_IOBuf_Cmd_READ        0
1184 /**
1185  * \def    Mcbsp_IOBuf_Cmd_WRITE
1186  *         Write command
1187  */
1188 #define Mcbsp_IOBuf_Cmd_WRITE       1
1189 /**
1190  * \def    Mcbsp_IOBuf_Cmd_ABORT
1191  *         Abort command
1192  */
1193 #define Mcbsp_IOBuf_Cmd_ABORT       2
1194 /**
1195  * \def    Mcbsp_IOBuf_Cmd_FLUSH
1196  *         Flush command
1197  */
1198 #define Mcbsp_IOBuf_Cmd_FLUSH       3
1200 /**
1201  *  \brief  McBSP Driver Command Codes Reserved for Control
1202  *
1203  *          Mcbsp driver command codes reserved for control.
1204  *
1205  */
1206 /**
1207  * \def    MCBSP_CTRL_CHAN_RESET
1208  *         Reset channel only
1209  */
1210 #define MCBSP_CTRL_CHAN_RESET          0
1211 /**
1212  * \def    MCBSP_CTRL_CHAN_TIMEDOUT
1213  *         Channel timeout occured
1214  */
1215 #define MCBSP_CTRL_CHAN_TIMEDOUT       1
1216 /**
1217  * \def    MCBSP_CTRL_DEVICE_RESET
1218  *         Reset entire device
1219  */
1220 #define MCBSP_CTRL_DEVICE_RESET        2
1222 /**********************************************************************
1223  **************************** EXPORTED API ****************************
1224  **********************************************************************/
1226 int32_t mcbspInit (void);
1227 int32_t mcbspBindDev(void* *devp, int32_t devid, void* devParams);
1228 int32_t mcbspUnBindDev(void* devp);
1229 int32_t mcbspCreateChan(void* *chanp, void* devp, int32_t mode, 
1230                        void* chanParams, Mcbsp_CallbackFxn cbFxn,
1231                        void* cbArg);
1232 int32_t mcbspDeleteChan(void* chanp);
1233 int32_t mcbspSubmitChan(void* chanp, Mcbsp_IOBuf *const ioBuf);
1234 int32_t mcbspControlChan(void* chanp, Mcbsp_IOCTL cmd, void* arg);
1235 void mcbspGblXmtIsr(void *hChan);
1236 void mcbspGblRcvIsr(void *hChan);
1238 #ifdef __cplusplus
1240 #endif /* extern "C" */
1242 #endif /* _MCBSP_DRV_H_ */
1243 /*============================================================================*/
1244 /*                         END OF FILE                                        */
1245 /*============================================================================*/