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