1    /* 
     2     * Copyright (c) 2010, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     * 
    32     */
    33    /*!
    34     *  ======== DMAN3 ========
    35     *  EDMA3 QDMA resource manager.
    36     */
    37    @Template("./DMAN3.xdt")
    38    
    39    metaonly module DMAN3 {
    40    
    41        /*!
    42         *  ======= customDmaLib =======
    43         *  Set this to TRUE if a custom library is being used to perform DMA  
    44         *  transfers. In this case, qdma channels will have to be partitioned 
    45         *  into scratch groups using the numQdmaGroup configuration.
    46         */  
    47        config Bool customDmaLib; 
    48    
    49        /* DMAN3 configuration settings for memory requirements */
    50        /*!
    51         *  ======== heapInternal ========
    52         *  Heap ID for dynamic allocation of DMAN3 objects.
    53         *
    54         *  This must be allocated in L1D Internal RAM.
    55         *
    56         *  This parameter is unused when DMAN3 is used in a Linux environment.
    57         *
    58         *  This parameter is set to `DMAN3_HEAP_INTERNAL`.
    59         */
    60        config String heapInternal = "DMAN3_heapInternal_undefined";
    61    
    62        /*!
    63         *  ======== heapExternal ========
    64         *  Heap ID for dyn allocation of private DMAN3 data structures.
    65         *
    66         *  This parameter is unused when DMAN3 is used in a Linux environment.
    67         *
    68         *  This parameter is set to `DMAN3_HEAP_EXTERNAL`.
    69         */
    70        config String heapExternal = "DMAN3_heapExternal_undefined";
    71    
    72        /*!
    73         *  ======== scratchAllocFxn ========
    74         *  Function for allocating IDMA3 channel object's "env" in scratch
    75         *  memory.
    76         */
    77        config String scratchAllocFxn = null;
    78    
    79        /*!
    80         *  ======== scratchFreeFxn ========
    81         *  Function for freeing IDMA3 channel object's "env" that was allocated
    82         *  in scratch memory.
    83         */
    84        config String scratchFreeFxn = null;
    85    
    86        /*!
    87         *  ======== idma3Internal ========
    88         *  Use the internal memory heap for dynamic allocation of IDMA3 objects.
    89         *
    90         *  A value of `false` means that IDMA3 objects will be allocated
    91         *  in the heap specified by {@link #heapExternal}. If the
    92         *  value is `true`, IDMA3 objects will be
    93         *  allocated in the heap specified by {@link #heapInternal}.
    94         */
    95        config bool idma3Internal = true;
    96    
    97        /*!
    98         *  ======== cpu ========
    99         *  Use the non-EDMA3, CPU version of DMAN3.  
   100         */
   101        config bool cpu = false; 
   102    
   103        /*! 
   104         *  ======= useExternalRM =======
   105         *  Boolean flag indicating if the EDMA3 Low Level 
   106         *  Resource Manager should be used to manage EDMA3
   107         *  resources. If this flag is set to true, the SOC 
   108         *  specific settings are not required to be set in 
   109         *  this module. The ti.sdo.fc.edma3.Settings module
   110         *  should be set up correctly 
   111         */ 
   112        config bool useExternalRM = false;
   113    
   114        /*!
   115         *  ======== numQdmaChannels ========
   116         *  The number of Physical QDMA channels that are assigned to
   117         *  DMAN3 via configuration. These channels will be granted either 
   118         *  as scratch or persistently as part of IDMA3 handles.   
   119         *
   120         *  This parameter is set to `DMAN3_NUM_QDMA_CHANNELS`.
   121         */
   122        config UInt numQdmaChannels = 4;
   123    
   124        /* If DMAN3.useExternalRM is set to true, the SOC specific settings below
   125           are ignored.
   126        */
   127        /* SOC specific settings for EDMA3 */
   128    
   129        /*!
   130         *  ======== qdmaPaRamBase ========
   131         *  Physical base address of the PARAM0 in the EDMA3/QDMA
   132         *  hardware whose resources are being managed by DMAN3.
   133         *
   134         *  This parameter is set to `DMAN3_QDMA_PARAM_BASE`.
   135         */
   136        config Ptr  qdmaPaRamBase =  0x01C04000;
   137    
   138        /*!
   139         *  ======== maxPaRamEntries ========
   140         *  Total number of PARAM Table entries on the target hardware.
   141         *  (eg, for IVA2, Davinci this is 128, for Himalaya, this is 256).
   142         *
   143         *  This parameter is set to `DMAN3_MAX_PARAM_ENTRIES`.
   144         */
   145        config UInt maxPaRamEntries = 128;
   146    
   147        /*!
   148         *  ======== maxQdmaChannels ========
   149         *  The total number of Physical QDMA channels available on the
   150         *  target hardware (eg, 8 for DaVinci, 4 for IVA2).
   151         *
   152         *  This parameter is set to `DMAN3_MAX_QDMA_CHANNELS`.
   153         */
   154        config UInt maxQdmaChannels = 8;
   155    
   156       /*!
   157        *  ======= maxTCs ========
   158        *  Maximum number of transfer controllers on this SOC
   159        */
   160        config UInt maxTCs = 8;
   161    
   162        /* DMAN3 resource configuration settings */
   163        /* If DMAN3.useExternalRM is set to true, the resource specific settings 
   164           below are ignored.
   165           Instead setup the ti.sdo.fc.edma3.Settings module with the EDMA3
   166           that you would like to make available to this region */ 
   167    
   168        /*!
   169         *  ======== paRamBaseIndex ========
   170         *  (0 > value > 255) represents the first PARAM TABLE ENTRY
   171         *  NUMBER that is assigned by configuration for exclusive DMAN3 allocation.
   172         *
   173         *  Typically, addresses (PaRam sets) between 0 and 63 are reserved for use
   174         *  by drivers that need EDMA/chaining capabilities.
   175         *
   176         *  Additionally, on some multi-core devices (e.g. DM644x), PaRams are
   177         *  shared between the different cores (e.g. ARM and C64+).  In these
   178         *  cases, an executable will be configured for each core, and each
   179         *  executable should configure only the DMAN3 resources which will be used
   180         *  on that core.  E.g., on DM644x, the C64+ executable should
   181         *  be configured to avoid using what the ARM uses.  Note that on
   182         *  OMAP2430, the ARM doesn't have access to EDMA so all PaRam sets
   183         *  are available for the C64+ device.
   184         *
   185         *  This parameter is set to `DMAN3_PARAM_BASE_INDEX`.
   186         */
   187        config UInt paRamBaseIndex =  96;
   188    
   189        /*!
   190         *  ======== numPaRamEntries ========
   191         *  Number of PARAM Table entries starting at DMAN3_PARAM_BASE_INDEX
   192         *  assigned by configuration for exclusive DMAN3 allocation.
   193         *
   194         *  This parameter is set to `DMAN3_NUM_CONTIGUOUS_PARAM_ENTRIES`.
   195         */
   196        config UInt numPaRamEntries = 32;
   197    
   198        /*!
   199         *  ======== nullPaRamIndex ========
   200         *  Index of PARAM to be reserved as a "null" PaRam. This index will be
   201         *  used to set QCHMAP when the corresponding QDMA channel is not active.
   202         *  The value of nullPaRamIndex should be outside of the range of
   203         *  PaRam indices alloted to DMAN3, i.e., nullPaRamIndex should be less
   204         *  than paRamBaseIndex, or greater than paRamBaseIndex + numPaRamEntries.
   205         *  If PaRam registers are shared between two processors (eg, an Arm
   206         *  and a DSP), make sure the nullPaRamIndex is not used by the other
   207         *  processor.
   208         *     
   209         *  This parameter is set to `DMAN3_NULLPARAMINDEX`.
   210         */
   211        config UInt nullPaRamIndex = 0;
   212    
   213        /*!
   214         *  ======== qdmaChannels ========
   215         *  Array containing list of physical QDMA channels assigned to DMAN3.
   216         *
   217         *  This array is of size `DMAN3_NUM_QDMA_CHANNELS`
   218         *  (configured by {@link #numQdmaChannels}).
   219         *
   220         *  This parameter is set to `DMAN3_QDMA_CHANNELS[]`.
   221         *
   222         *  @see numQdmaChannels
   223         */
   224        config UInt qdmaChannels[] = [0, 1, 2, 3];
   225    
   226        /*!
   227         *  ======== tccAllocationMaskH ========
   228         *  32-bit bitmask representing configuration provided list of TCCs
   229         *  for exclusive DMAN3 allocation.
   230         *
   231         *  For example, for TCC's in the range 0-31 the Low Mask
   232         *  (tccAllocationMaskL) is configured so that a '1' in bit position 'i'
   233         *  indicates the TCC 'i' is assigned to DMAN3.
   234         *
   235         *  This parameter is set to `DMAN3_TCC_FREEMASK_H`.
   236         */
   237        config UInt tccAllocationMaskH = 0xffffffff;
   238    
   239        /*!
   240         *  ======== tccAllocationMaskL ========
   241         *  32-bit bitmask representing configuration provided list of TCCs
   242         *  for exclusive DMAN3 allocation.
   243         *
   244         *  For example, for TCC's in the range 0-31 the Low Mask
   245         *  (tccAllocationMaskL) is configured so that a '1' in bit position 'i'
   246         *  indicates the TCC 'i' is assigned to DMAN3.
   247         *
   248         *  This parameter is set to `DMAN3_TCC_FREEMASK_L`.
   249         */
   250        config UInt tccAllocationMaskL = 0x00000000;
   251    
   252        /*!
   253         *  ======= qdmaQueueMap ========
   254         *  Array contaning the mapping from QDMA Channels to Event Queues
   255         *
   256         *  Indicates mapping of all "qdmaChannels" defined above to
   257         *  particular Event Queue.  For example, `channelQueueMap[0]`
   258         *  specifies queue number for `qdmaChannel[0]`, etc.
   259         *
   260         *  Defaults map all qdmaChannels to Queue# 1
   261         */
   262        config UInt qdmaQueueMap[] = [1,1,1,1,1,1,1,1];
   263    
   264        /*!
   265         *  ======= queueTCMap ========
   266         * Array contaning the mapping from Event Queues to Transfer Controllers
   267         *
   268         * Indicates mapping of individual hardware Event Queues to the Transfer
   269         * Controllers.
   270         */
   271        config UInt queueTCMap[] = [0, 1, 2, 3, 4, 5, 6, 7];
   272    
   273        /*!
   274         *  ======= queuePri ========
   275         * Array contaning priorities of the event queues
   276         *
   277         * Indicates the priority accorded to each physical event queue.
   278         */
   279        config UInt queuePri[] = [3, 7, 0, 0, 0, 0, 0, 0];
   280    
   281        /* These const values must match those in dman3.h */
   282    
   283        const Int MAXGROUPS = 20;  /*! Maximum number of groups for sharing
   284                                     TCCs and parameter RAM. */
   285    
   286        /* DMAN3 configuration settings  for scratch groups */
   287    
   288        /*!
   289         *  ======== numTccGroup ========
   290         *  Arrays containing the number of TCC that will be assigned to groups for
   291         *  sharing
   292         *
   293         *  Channels created with a given group ID will use TCCs and PaRams
   294         *  allocated for that group ID, and may share them with other channels
   295         *  created with the same group ID.
   296         *
   297         *  This parameter is set to `DMAN3_NUMTCC_GROUP`.
   298         */
   299        config Int numTccGroup[MAXGROUPS] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0,0, 0, 0,
   300                0, 0, 0, 0, 0, 0, 0,];
   301    
   302        /*!
   303         *  ======== numPaRamGroup ========
   304         *  Arrays containing the number of PaRam entries that will be assigned to
   305         * groups for sharing.
   306         *
   307         *  Channels created with a given group ID will use TCCs and PaRams
   308         *  allocated for that group ID, and may share them with other channels
   309         *  created with the same group ID.
   310         *
   311         *  This parameter is set to `DMAN3_NUMPARAM_GROUP`.
   312         */
   313        config Int numPaRamGroup[MAXGROUPS]= [0, 0, 0, 0, 0, 0, 0, 0, 0, 0,0, 0, 0,
   314                0, 0, 0, 0, 0, 0, 0,] ;
   315    
   316        /*!
   317         *  ======= numQdmaGroup =======
   318         *  Arrays containing the number of Qdma channels that will be assigned to 
   319         *  groups for sharing.
   320         *
   321         *  This configuration is required ONLY if the application uses atleast one 
   322         *  custom (non-ACPY3) DMA library that will request QDMA channels from
   323         *  DMAN3.  In this case, the configuration param "customDmaLib" should be 
   324         *  set to true.
   325         *
   326         *  Channels created with a given group ID will use TCCs and PaRams 
   327         *  allocated for that grup ID, and may share them with other channels  
   328         *  created with the same group ID. Qdma channels may be shared across
   329         *  algorithms and scratch groups if all algorithms use the same ACPY3
   330         *  library. But if even one algorithm uses a custom DMA library, Qdma
   331         *  channels should be distribued among scratch groups like other EDMA3
   332         *  resources. 
   333         */
   334        config Int numQdmaGroup[MAXGROUPS]; 
   335    
   336        /*
   337         * TODO:  These "Strings" should be Ints... how do we get a handle to
   338         * the BIOS objects in javascript-land?
   339         */
   340    
   341        /*!
   342         *  ======== debug ========
   343         *  Enable the debug profile of the DMAN3 library.
   344         *
   345         *  This will likely result in a larger and slower library being linked in.
   346         */
   347        config bool debug = false;
   348    
   349        /*!
   350         *  ======== trace ========
   351         *  Enable trace support
   352         */
   353        config bool trace = false;
   354    
   355        /*!
   356         *  ======== ipcKeyBase ========
   357         *  Linux only. Base value of keys of Linux IPC objects used by
   358         *  DMAN3. The IPC objects created by DMAN3 will use keys starting at this
   359         *  value, and incrementing with each new object. There are currently
   360         *  three IPC objects, so keys in the range of ipcKeyBase to ipcKeyBase + 2
   361         *  will be reserved for DMAN3. The default value of ipcKeyBase is
   362         *  ascii code for "NAMD".
   363         *
   364         *  WARNING: This value should only be changed if it conflicts with
   365         *  another IPC key in the system that cannot be changed. If this value
   366         *  is changed, all programs using DMAN3 that will be run simultaneously
   367         *  must have the ipcKeyBase configured to the new value.
   368         *  @_nodoc
   369         */
   370        config UInt ipcKeyBase = 0x4e414d44;
   371    
   372        /*!
   373         *  ======== allowUnshared ========
   374         *  Allow DMAN3-related resources to be granted to an algorithm, even
   375         *  if there are not enough resources configured into the shared
   376         *  groupId which the algorithm is a member of.
   377         *
   378         *  If this property is set to `false`, the DMAN3 library will fail
   379         *  to grant DMA channels to an algorithm requesting more TCCs or
   380         *  PaRams then the number configured for its scratch group.
   381         *
   382         *  If this property is `true`, and an algorithm requests more TCCs or
   383         *  PaRams than the number configured for its scratch group, DMAN3 will
   384         *  do either of the following:
   385         *  @p(nlist)
   386         *     - If no algorithm is currently instantiated for the given scratch
   387         *       group, DMAN3 will bump up the number of TCCs and PaRams to the
   388         *       maximum of the number configured and that requested by the
   389         *       algorithm, for the scratch group. This will remain in effect
   390         *       until all algorithms for that scratch group are deleted.
   391         *     - If an algorithm has already been granted DMA channels for the
   392         *       given scratch group (so the number of TCCs and PaRams for that
   393         *       scratch group has already been determined by (1) above), and the
   394         *       number of TCCs or PaRams for the scratch group is insufficient for
   395         *       the algorithm currently requesting DMA channels, DMAN3 will
   396         *       allocate new TCCs and PaRams if available. These new TCCs and
   397         *       PaRams will not be shared by any other algorithm.
   398         */
   399        config bool allowUnshared = true;
   400    
   401    }
   402    /*
   403     *  @(#) ti.sdo.fc.dman3; 1, 0, 4,300; 12-1-2010 17:24:24; /db/atree/library/trees/fc/fc-p01x/src/ xlibrary
   404    
   405     */
   406