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 */
  39
  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  */
  52
  53 #ifndef _MCBSP_DRV_H_
  54 #define _MCBSP_DRV_H_
  55
  56 /*============================================================================*/
  57 /*                            INCLUDE FILES                                   */
  58 /*============================================================================*/
  59
  60 #ifdef __cplusplus
  61 extern "C" {
  62 #endif
  63
  64 /* CSL RL includes */
  65 #include <ti/csl/cslr_device.h>
  66 #include <ti/csl/cslr_mcbsp.h>
  67 #include "mcbspver.h"
  68
  69 /*============================================================================*/
  70 /*                         MACRO TYPES                                        */
  71 /*============================================================================*/
  72
  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 */
  79
  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)
  89
  90 /**
  91  * \def    MCBSP_CACHE_LENGTH
  92  *         Defines the Maximum length of cache line that is possible.
  93  */
  94 #define MCBSP_CACHE_LENGTH        (128u)
  95
  96 /**
  97  * \def    MCBSP_MAX_CACHE_ALIGN
  98  *         Defines the Maximum cache line size for alignment.
  99  */
 100 #define MCBSP_MAX_CACHE_ALIGN        (128u)
 101
 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)
 116
 117 /*============================================================================*/
 118 /*                         ENUMERATED DATA TYPES                              */
 119 /*============================================================================*/
 120
 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
 128 {
 129     Mcbsp_DevMode_McBSP      = (0u)
 130     /**< Option to operate in normal McBSP mode     */
 131
 132 }Mcbsp_DevMode;
 133 /**< Mcbsp device operational mode.       */
 134
 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
 142 {
 143     Mcbsp_OpMode_POLLED = 0,
 144     /**< Polled Mode                     */
 145
 146     Mcbsp_OpMode_INTERRUPT,
 147     /**< Interrupt Mode                  */
 148
 149     Mcbsp_OpMode_DMAINTERRUPT
 150     /**< DMA Mode                        */
 151
 152 }Mcbsp_OpMode;
 153 /**< Mcbsp driver operational mode       */
 154
 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
 166 {
 167     Mcbsp_EmuMode_SOFT_ABORT  = (0u),
 168     /**< SOFT mode is disabled.          */
 169
 170     Mcbsp_EmuMode_SOFT_STOP   = (1u),
 171     /**< SOFT mode is enabled            */
 172
 173     Mcbsp_EmuMode_FREE        = (2u)
 174     /**< FREE mode is enabled            */
 175
 176 }Mcbsp_EmuMode;
 177 /**< Mcbsp emulation modes               */
 178
 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
 185 {
 186     Mcbsp_Loopback_DISABLE = 0,
 187     /**< loopback mode off                 */
 188
 189     Mcbsp_Loopback_ENABLE = 1
 190     /**< loopback mode on                  */
 191
 192 } Mcbsp_Loopback;
 193 /**< McBSP digital loopback mode selection */
 194
 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
 202 {
 203     Mcbsp_RxJust_RZF        = (0u),
 204     /**< RCV setting - right justify, fill MSBs with zeros                    */
 205
 206     Mcbsp_RxJust_RSE        = (1u),
 207     /**< RCV setting - right justify, sign-extend the data into MSBs          */
 208
 209     Mcbsp_RxJust_RxJUST_LZF = (2u)
 210     /**< RCV setting - left justify, fill LSBs with zeros                     */
 211
 212 }Mcbsp_Rxjust;
 213 /**< Enumeration for the Receive data justification                           */
 214
 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
 221 {
 222     Mcbsp_DxEna_OFF  = (0),
 223     /**< DX enabler is OFF                       */
 224
 225     Mcbsp_DxEna_ON   = (1u)
 226     /**< DX enabler is ON                        */
 227 }Mcbsp_DxEna;
 228 /**< DX pin High impedance enable/disable option */
 229
 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
 237 {
 238     Mcbsp_ClkSPol_RISING_EDGE   = 0,
 239     /**< Rising edge of CLKS generates CLKG and FSG.                          */
 240
 241     Mcbsp_ClkSPol_FALLING_EDGE  = 1
 242     /**< Falling edge of CLKS generates CLKG and FSG.                         */
 243
 244 }Mcbsp_ClkSPol;
 245 /**< Polarity of the CLKS pin                                                 */
 246
 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
 254 {
 255     Mcbsp_SrgClk_CLKS   = (0u),
 256     /**< input clock source for Sample Rate Generator is CLKS pin             */
 257
 258     Mcbsp_SrgClk_CLKCPU = (1u),
 259     /**< input clock source for Sample Rate Generator is CPU                  */
 260
 261     Mcbsp_SrgClk_CLKR   = (2u),
 262     /**< input clock source for Sample Rate Generator is BCLKR pin            */
 263
 264     Mcbsp_SrgClk_CLKX   = (3u)
 265     /**< input clock source for Sample Rate Generator is BCLKX pin            */
 266
 267 }Mcbsp_SrgClk;
 268 /**< SRG clock source selection                                               */
 269
 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
 277 {
 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,
 284
 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,
 288
 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                                       */
 294
 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
 301 {
 302     Mcbsp_Phase_SINGLE = (0u),
 303     /**< Single phase for frame                */
 304
 305     Mcbsp_Phase_DUAL   = (1u)
 306     /**< Dual phase for frame                  */
 307 } Mcbsp_Phase;
 308 /**< Mcbsp frame phase selection ENUMERATION   */
 309
 310 /**
 311  *  \brief  Mcbsp supported wordlength.
 312  *
 313  *          Enumerated constant for wordlength supported by the MCBSP device
 314  */
 315 typedef enum Mcbsp_WordLength_t
 316 {
 317     Mcbsp_WordLength_8  = 8u,
 318     /**< Word length of 8 bits            */
 319
 320     Mcbsp_WordLength_12 = 12u,
 321     /**< Word length of 12 bits           */
 322
 323     Mcbsp_WordLength_16 = 16u,
 324     /**< Word length of 16 bits           */
 325
 326     Mcbsp_WordLength_20 = 20u,
 327     /**< Word length of 20 bits           */
 328
 329     Mcbsp_WordLength_24 = 24u,
 330     /**< Word length of 24 bits           */
 331
 332     Mcbsp_WordLength_32 = 32u
 333     /**< Word length of 32 bits           */
 334
 335 }Mcbsp_WordLength;
 336 /**< Mcbsp supported wordlength.          */
 337
 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
 344 {
 345     Mcbsp_FrmSync_DETECT  = (0u),
 346     /**< detect frame synchronisation          */
 347
 348     Mcbsp_FrmSync_IGNORE  = (1u)
 349     /**< ignore frame synchronisation          */
 350
 351 }Mcbsp_FrmSync;
 352 /**< Frame sync detection options ENUMERATION  */
 353
 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
 360 {
 361     Mcbsp_DataDelay_0_BIT = (0u),
 362     /**< sets XMT/RCV Data Delay to 0 bits     */
 363
 364     Mcbsp_DataDelay_1_BIT = (1u),
 365     /**< sets XMT/RCV Data Delay to 1 bits     */
 366
 367     Mcbsp_DataDelay_2_BIT = (2u)
 368     /**< sets XMT/RCV Data Delay to 2 bits     */
 369
 370 } Mcbsp_DataDelay;
 371 /**< Enum to select Data delay in bits         */
 372
 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
 379 {
 380     Mcbsp_Compand_OFF_MSB_FIRST =  (0u),
 381     /**< No companding, data transfer starts with MSB first.                  */
 382
 383     Mcbsp_Compand_OFF_LSB_FIRST =  (1u),
 384     /**< No companding, 8-bit data transfer starts with LSB first.            */
 385
 386     Mcbsp_Compand_MULAW         =  (2u),
 387     /**< mu-law comapanding enable for channel                                */
 388
 389     Mcbsp_Compand_ALAW          =  (3u)
 390     /**< A-law comapanding enable for channel                                 */
 391
 392 }Mcbsp_Compand;
 393 /**< Enum to select the companding law         */
 394
 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
 401 {
 402     Mcbsp_BitReversal_DISABLE   = (0u),
 403     /**< 32-bit reversal disabled                                             */
 404
 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    */
 408
 409 }Mcbsp_BitReversal;
 410 /**< McBSP 32-bit reversal feature                                            */
 411
 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
 419 {
 420     Mcbsp_FsClkMode_EXTERNAL = (0u),
 421     /**< frame sync clock source as internal     */
 422
 423     Mcbsp_FsClkMode_INTERNAL = (1u),
 424     /**< frame sync clock source as external     */
 425
 426     Mcbsp_FsClkMode_DXR_XSR  = (2u)
 427     /**< frame sync is generated on DXR_XSR copy */
 428
 429 } Mcbsp_FsClkMode;
 430 /**< Frame sync clock source                     */
 431
 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
 438 {
 439     Mcbsp_TxRxClkMode_EXTERNAL = (0u),
 440     /**< clock source as internal */
 441
 442     Mcbsp_TxRxClkMode_INTERNAL = (1u)
 443     /**< clock source as external */
 444
 445 } Mcbsp_TxRxClkMode;
 446 /**< Clock source selection ENUM  */
 447
 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
 455 {
 456     Mcbsp_ClkPol_RISING_EDGE  = (0u),
 457     /**< Data sampled on rising edge of the bit Clock                         */
 458
 459     Mcbsp_ClkPol_FALLING_EDGE = (1u),
 460     /**< Data sampled on falling edge of the bit Clock                        */
 461
 462     Mcbsp_ClkPol_SRG_RISING_EDGE = (0u),
 463     /**< SRG clock polarity is rising edge      */
 464
 465     Mcbsp_ClkPol_SRG_FALLING_EDGE = (1u)
 466    /**< SRG clock polarity Is falling edge      */
 467
 468 } Mcbsp_ClkPol;
 469 /**< Clock polarity                             */
 470
 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
 478 {
 479     Mcbsp_FsPol_ACTIVE_HIGH   = (0u),
 480     /**< frame sync polarity is active-high */
 481
 482     Mcbsp_FsPol_ACTIVE_LOW    = (1u)
 483     /**< frame sync polarity is active-low  */
 484
 485 }Mcbsp_FsPol;
 486 /**< Frame sync polarity                                                      */
 487
 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
 496 {
 497     Mcbsp_IntMode_ON_READY   = (0u),
 498     /**< Interrupt generated on RRDY of RCV or XRDY of XMT                    */
 499
 500     Mcbsp_IntMode_ON_EOB     = (1u),
 501     /**< Interrupt generated on end of 16-channel block transfer in           *
 502      *   multichannel mode                                                    */
 503
 504     Mcbsp_IntMode_ON_FSYNC   = (2u),
 505     /**< Interrupt generated on frame sync                                    */
 506
 507     Mcbsp_IntMode_ON_SYNCERR = (3u)
 508     /**< Interrupt generated on synchronisation error                         */
 509
 510 }Mcbsp_IntMode;
 511 /**< MCBSP Interrupt mode                                                     */
 512
 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
 521 {
 522     Mcbsp_McmMode_ALL_CHAN_ENABLED_UNMASKED  = (0u),
 523     /**< All the 128 channels are enabled                                     */
 524
 525     Mcbsp_McmMode_ALL_CHAN_DISABLED_UNMASKED = (1u),
 526     /**< All channels are disabled unless selected by enable mask             */
 527
 528     Mcbsp_McmMode_ALL_CHAN_ENABLED_MASKED    = (2u),
 529     /**< All channels are enabled but masked unless selected by Enable mask   */
 530
 531     Mcbsp_McmMode_ALL_CHAN_DISABLED_MASKED   = (3u)
 532     /**< Symmetric transmission and reception                                 */
 533
 534 }Mcbsp_McmMode;
 535 /**< Transmit multichannel selection mode bit.                                */
 536
 537 /**
 538  * \brief      Partition A/B block channel selection bit.
 539  */
 540 typedef enum Mcbsp_PartitionSel_t
 541 {
 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    */
 547
 548     Mcbsp_PartitionMode_CHAN_32_47   = (1u),
 549     /**< Select the channel 32-47 in block A    */
 550
 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    */
 556
 557     Mcbsp_PartitionMode_CHAN_80_95   = (2u),
 558     /**< Select the channel 80-95 in block B    */
 559
 560     Mcbsp_PartitionMode_CHAN_96_111  = (3u),
 561     /**< Select the channel 96-111 in block A   */
 562
 563     Mcbsp_PartitionMode_CHAN_112_127 = (3u)
 564     /**< Select the channel 112-127 in block B  */
 565
 566 }Mcbsp_PartitionSel;
 567 /**< Partition A/B block selection bit. */
 568
 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
 577 {
 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  */
 583
 584 }Mcbsp_PartitionMode;
 585 /**< Multichannel partition mode selction                         */
 586
 587 /*============================================================================*/
 588 /*                              DATA STRUCTURES                               */
 589 /*============================================================================*/
 590
 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
 598 {
 599     Bool             gSync;
 600     /**< sample rate generator clock syncronization bit (only if CLKS is used)*/
 601
 602     Mcbsp_ClkSPol    clksPolarity;
 603     /**< CLKS polarity used to drive the CLKG and FSG clocks                  */
 604
 605     Mcbsp_SrgClk     srgInputClkMode;
 606     /**< Source for the Sample rate generator (CLKS,CPU,CLKX,CLKR)            */
 607
 608     uint32_t         srgrInputFreq;
 609     /**< input clock frequency for the SRGR (freq of CLKS or CLKX etc..)      */
 610
 611     uint32_t         srgFrmPulseWidth;
 612     /**< Set the Frame Sync Pulse width in terms of FSG clock                 */
 613
 614 } Mcbsp_srgConfig;
 615 /**< McBSP sample rate generator configuration structure                      */
 616
 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
 625 {
 626     Mcbsp_Phase               phaseNum;
 627     /**< Phase of the McBSP data stream                                       */
 628
 629     Mcbsp_WordLength          wrdLen1;
 630     /**< Length of the data word in first phase                               */
 631
 632     Mcbsp_WordLength          wrdLen2;
 633     /**< Length of the data word in second when dual phase is selected        */
 634
 635     uint32_t                  frmLen1;
 636     /**< Length of the data frame in first phase                              */
 637
 638     uint32_t                  frmLen2;
 639     /**< Length of the data frame in second phase                             */
 640
 641     Mcbsp_FrmSync             frmSyncIgn;
 642     /**< Frame sync ignore bit                                                */
 643
 644     Mcbsp_DataDelay           dataDelay;
 645     /**< Data delay to be configured in number of Bits                        */
 646
 647     Mcbsp_Compand             compandSel;
 648     /**< companding selection                                                 */
 649
 650     Mcbsp_BitReversal         bitReversal;
 651     /**< Transmit 32-bit bit reversal feature enable bit.                     */
 652
 653     Mcbsp_IntMode             intMode;
 654     /**< Event for which the interrupt is to be generated                     */
 655
 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.                             */
 664
 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
 672 {
 673     Mcbsp_McmMode          multiChanMode;
 674     /**< Multi channel mode to be selcted                                     */
 675
 676     Mcbsp_PartitionSel     partitionSelA;
 677     /**< Channel selection for partition A                                    */
 678
 679     Mcbsp_PartitionSel     partitionSelB;
 680     /**< Channel selection for partition B                                    */
 681
 682     Mcbsp_PartitionMode    partitionMode;
 683     /**< Channel partition mode selection                                     */
 684 }Mcbsp_McrSetup;
 685 /**< Mcbsp multi channel control settings                                     */
 686
 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
 695 {
 696     Mcbsp_FsClkMode        frmSyncMode;
 697     /**< Frame sync mode bit (FSXM/FSRM)(Internal/External)                   */
 698
 699     uint32_t                 samplingRate;
 700     /**< Frame sync frequency                                                 */
 701
 702     Mcbsp_TxRxClkMode      clkMode;
 703     /**< Bit clock mode (internal or external)                                */
 704
 705     Mcbsp_FsPol            frmSyncPolarity;
 706     /**< frmSyncTxPolarity                                                    */
 707
 708     Mcbsp_ClkPol           clkPolarity;
 709     /**< clkTxPolarity                                                        */
 710 }Mcbsp_ClkSetup;
 711 /**< Mcbsp clock settings setup structure                                     */
 712
 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
 722 {
 723     uint32_t               instNum;
 724     /**< Instance of MCBSP being referred by this object                      */
 725
 726     CSL_McbspRegsOvly    regs;
 727     /**< Pointer to the register overlay structure of the MCBSP               */
 728
 729     CSL_BfifoRegsOvly    fifoRegs;
 730     /**< Fifo address of the mcbsp instance                                   */
 731
 732     CSL_BdataRegsOvly    dataAddress;
 733     /**< Mcbsp data registers address                                         */
 734
 735     uint32_t               edmaTxEventNum;
 736     /**< edma Transmit event number                                           */
 737
 738     uint32_t               edmaRxEventNum;
 739     /**< edma Receive event number                                            */
 740
 741     uint32_t               cpuTxEventNum;
 742     /**< Transmit interrupt number                                            */
 743
 744     uint32_t               cpuRxEventNum;
 745     /**< Receive interrupt number                                             */
 746
 747 }Mcbsp_HwInfo_Unpadded;
 748
 749 typedef struct
 750 {
 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                               */
 761
 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
 773 {
 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.                                                  */
 782
 783 /*============================================================================*/
 784 /*                               DATA TYPES                                   */
 785 /*============================================================================*/
 786
 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);
 797
 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
 806 {
 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                                               */
 813
 814     void*                     userLoopJobBuffer;
 815     /**< Buffer to be transferred when the loop job is running.               */
 816
 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                                            */
 822
 823     Mcbsp_GblErrCallback    gblCbk;
 824     /**< callback required when global error occurs - must be callable        *
 825      * directly from the ISR context                                          */
 826
 827     void*                     edmaHandle;
 828     /**< Handle to the EDMA Driver                                            */
 829
 830     uint32_t                  edmaEventQue;
 831     /**< EDMA event queue to be used by the channel                           */
 832
 833     uint32_t                  hwiNumber;
 834     /**< Variable to specify the Hwi number to be used by the driver          */
 835
 836     Mcbsp_BufferFormat      dataFormat;
 837     /**< Format of the application supplied buffer                            */
 838
 839     Bool                    enableHwFifo;
 840     /**< Option to enable/disable the Hardware FIFO                           */
 841
 842     Mcbsp_DataConfig       *chanConfig;
 843     /**< settings to configure the TX or RX hardware sections                 */
 844
 845     Mcbsp_ClkSetup         *clkSetup;
 846     /**< clock setup for the RX or the TX section                             */
 847
 848     Mcbsp_McrSetup         *multiChanCtrl;
 849     /**< multiple channel control settings                                    */
 850
 851     uint32_t                  chanEnableMask[4];
 852     /**< Mask of the channels to be enabled or disabled                       */
 853
 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                 */
 858
 859 }Mcbsp_ChanParams;
 860 /**< Mcbsp Channel setup parameters                                           */
 861
 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
 870 {
 871     Mcbsp_DevMode           mode;
 872     /**< Mode in which mcbsp instance needs to be created                     */
 873
 874     Mcbsp_OpMode            opMode;
 875     /**< Operation mode of driver i.e. interrupt or EDMA.Mcbsp supports only
 876      *   EDMA mode                                                            */
 877
 878     Bool                    enablecache;
 879     /**< whether the cache operations are to be performed on the application
 880      *   buffers or not                                                       */
 881
 882     Mcbsp_EmuMode           emulationMode;
 883     /**< Emulation mode settings for the Mcbsp                                */
 884
 885     Mcbsp_Loopback          dlbMode;
 886     /**< digital loop back mode (ENABLE/DISABLE)                              */
 887
 888     Mcbsp_srgConfig        *srgSetup;
 889     /**< configuration for the sample rate generator configurations           */
 890
 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                              */
 896
 897     void*                   rxQPendingList;
 898     /**< Queue to hold the pending buffers received from the application      */
 899
 900     void*                   rxQFloatingList;
 901     /**< Queue to manage floating buffers in DMA                              */
 902
 903 } Mcbsp_Params;
 904 /**< McBSP device setup params                                                */
 905
 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;
 916
 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
 926 {
 927     Mcbsp_QueueElem     link;
 928     /**< queue link                */
 929
 930     void*               addr;
 931     /**< buffer address            */
 932
 933     uint32_t            size;
 934     /**< buffer size               */
 935
 936     uint32_t            arg;
 937     /**< arg to be used by end app */
 938
 939     uint32_t            cmd;
 940     /**< command for driver - READ, WRITE, ABORT or FLUSH  */
 941
 942     int32_t             status;
 943     /**< status of command         */
 944
 945     uint32_t            misc;
 946     /**< reserved for driver       */
 947 } Mcbsp_IOBuf;
 948 /**< Mcbsp frame object params     */
 949
 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);
 958
 959 /*============================================================================*/
 960 /*                           IOCTL COMMANDS                                   */
 961 /*============================================================================*/
 962
 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
 970 {
 971     Mcbsp_IOCTL_START = 128,
 972     /**< Starts the data transfer                                             */
 973
 974     Mcbsp_IOCTL_SAMPLE_RATE_CHANGE,
 975     /**< Command to chnage the sample rate                                    */
 976
 977     Mcbsp_IOCTL_STOP,
 978     /**< Stops the data transfer                                              */
 979
 980     Mcbsp_IOCTL_SRGR_START,
 981     /**< Start the McBSP SRG                                                  */
 982
 983     Mcbsp_IOCTL_SRGR_STOP,
 984     /**< Stop the McBSP SRG                                                   */
 985
 986     Mcbsp_IOCTL_FSGR_START,
 987     /**< Start the McBSP FSG                                                  */
 988
 989     Mcbsp_IOCTL_FSGR_STOP,
 990     /**< Stop the McBSP FSG                                                   */
 991
 992     Mcbsp_IOCTL_SET_TIMEOUT,
 993     /**< Modify the timeout value in the driver                               */
 994
 995     Mcbsp_IOCTL_MUTE_ON,
 996     /**< Mute ON the transfer                                                 */
 997
 998     Mcbsp_IOCTL_MUTE_OFF,
 999     /**< Take out of Muted state                                              */
1000
1001     Mcbsp_IOCTL_PAUSE,
1002     /**< Pause the playback operation                                         */
1003
1004     Mcbsp_IOCTL_RESUME,
1005     /**< Resume the playback operation                                        */
1006
1007     Mcbsp_IOCTL_CHAN_RESET,
1008     /**< Reset an I/O channel                                                 */
1009
1010     Mcbsp_IOCTL_DEVICE_RESET,
1011     /**< Reset both input and output channel                                  */
1012
1013     Mcbsp_IOCTL_SET_CLKMODE,
1014     /**< Set Bit clock mode for the McBSP                                     */
1015
1016     Mcbsp_IOCTL_SET_FRMSYNCMODE,
1017     /**< Set Frame Sync mode for the McBSP                                    */
1018
1019     Mcbsp_IOCTL_CONFIG_SRGR,
1020     /**< configure Sample Rate Generator                                      */
1021
1022     Mcbsp_IOCTL_SET_BCLK_POL,
1023     /**< Set the CLKR or CLKX clock polarity                                  */
1024
1025     Mcbsp_IOCTL_SET_FRMSYNC_POL,
1026     /**< Set the FSR and FSX polarity                                         */
1027
1028     Mcbsp_IOCTL_MODIFY_LOOPJOB,
1029     /**< Enable/disable the loopjob                                           */
1030
1031     Mcbsp_IOCTL_SYNCERR_INT_ENABLE,
1032     /**< Enable/disable the sync error                                        */
1033
1034     Mcbsp_IOCTL_LOOPBACK,
1035     /**< enable/disable the loop back mode                                    */
1036
1037     Mcbsp_IOCTL_CANCEL_PENDING_IO
1038     /**< Cancel all the current pending IO in the driver                      */
1039
1040 } Mcbsp_IOCTL;
1041 /**< McBSP Ioctl commands list */
1042
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)
1067
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
1094
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
1101
1102
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
1172
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
1199
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
1221
1222 /**********************************************************************
1223  **************************** EXPORTED API ****************************
1224  **********************************************************************/
1225
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);
1237
1238 #ifdef __cplusplus
1239 }
1240 #endif /* extern "C" */
1241
1242 #endif /* _MCBSP_DRV_H_ */
1243 /*============================================================================*/
1244 /*                         END OF FILE                                        */
1245 /*============================================================================*/