packages/ti/sdo/ce/Server.xdc

   1 /*
   2  * Copyright (c) 2013, 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  *  ======== Server ========
  35  *  DSP Server Configuration interface
  36  */
  37 @Template("./Server.xdt")
  38
  39 metaonly module Server
  40 {
  41     /*!
  42      *  ======== MINPRI ========
  43      *  Minimum priority that a thread can assume
  44      *
  45      *  All threads must have a priority value greater than or equal to
  46      *  {@link #MINPRI Server.MINPRI} and less than or equal to
  47      *  {@link #MAXPRI Server.MAXPRI}.
  48      */
  49     readonly config Int MINPRI = 1;
  50
  51     /*!
  52      *  ======== MAXPRI ========
  53      *  Maximum priority that a thread can assume
  54      *
  55      *  All threads must have a priority value greater than or equal to
  56      *  {@link #MINPRI Server.MINPRI} and less than or equal to
  57      *  {@link #MAXPRI Server.MAXPRI}.
  58      */
  59     readonly config Int MAXPRI = 15;
  60
  61     /*!
  62      *  ======== ThreadAttrs ========
  63      *  Thread attributes
  64      *
  65      *  This structure defines the thread attrubutes for any threads created
  66      *  by the RMS thread; see Server.threadAttrs.
  67      */
  68     struct ThreadAttrs {
  69         Int stackSize;      /*! minimum stack size required for this thread */
  70         Int stackMemId;     /*! MEM seg id for the thread's stack */
  71         Int priority;       /*! priority of the thread */
  72     };
  73
  74     /*!
  75      *  ======== AlgDesc ========
  76      *  Algorithm descriptor
  77      *
  78      *  This structure describes the execution context provided by
  79      *  the server for an algorithm module.
  80      *
  81      *  @field(name)    This string specifies the "local" name used by the
  82      *                  server to generate instance names
  83      *  @field(mod)     This field is a module reference that identifies the
  84      *                  actual module implementing the algorithm to instantiate.
  85      *                  This module reference is often acquired by a call to
  86      *                  `xdc.useModule();` like this:
  87      *                  @p(code)
  88      *                      modReference = xdc.useModule('package.Module');
  89      *                  @p
  90      *  @field(threadAttrs)  This structure defines attributes of the "server"
  91      *                  thread that will handle instance processing
  92      *                  requests; e.g., stack size and priority.
  93      *                  @p(blist)
  94      *                  -{@link #ThreadAttrs threadAttrs.stackSize}:  This
  95      *                      field is optional when configuring
  96      *                      an algorithm in a server, though strongly
  97      *                      recommended.  Stack overrun is a very common
  98      *                      cause of system instability.  If it's not supplied
  99      *                      by the server integrator's script, the stack size
 100      *                      returned by the codec's
 101      *                      {@link ICodec#getStackSize()} method will be
 102      *                      added to the value of
 103      *                      {@link #stackSizePad stackSizePad}.
 104      *                  -{@link #ThreadAttrs threadAttrs.stackMemId}:  This
 105      *                      field is required when configuring
 106      *                      an algorithm in a server.
 107      *                  -{@link #ThreadAttrs threadAttrs.priority}:  This
 108      *                      field is optional (though strongly recommended)
 109      *                       when configuring an algorithm in a server.
 110      *                      If it's not supplied by the server integrator's
 111      *                      script, a default priority will be assigned, and a
 112      *                      remark will be printed to the console during server
 113      *                      configuration to indicate which priority was
 114      *                      assigned to the algorithm.  Note that this priority
 115      *                      can be overridden at runtime by the application;
 116      *                      see the various `*_create()` VISA APIs for more
 117      *                      details.
 118      *                  @p
 119      *  @field(groupId) This id specifies which resource sharing group
 120      *                  this codec will be placed into.  The system
 121      *                  integrator must ensure that codecs within the same
 122      *                  group can not pre-empt each other.
 123      *
 124      *                  A common technique for assigning groupId's in
 125      *                  systems where same-priority tasks don't pre-empt
 126      *                  each other (e.g. DSP/BIOS) is to use the task priority.
 127      *                  Some systems do not allow sharing resources.  In
 128      *                  those systems, this parameter is ignored.
 129      *
 130      *                  Note that this parameter is ignored if "local" is not
 131      *                  TRUE.
 132      */
 133     struct AlgDesc {
 134         String          name;           /*! alg nick-name */
 135         ICodec.Module   mod;            /*! alg that implements skeletons */
 136         ThreadAttrs     threadAttrs;    /*! thread properties for each alg instance  */
 137         Int             groupId;        /*! group id of the algorithm */
 138     };
 139
 140     /*!
 141      *  ======== threadAttrs ========
 142      *  Thread attributes for the Server daemon thread
 143      *
 144      *  A single Server thread is created within each DSP Server.  This thread
 145      *  accepts requests to create/destroy algorithm instances.
 146      *
 147      *  This thread is sometimes referred to as the Resource Manager Server
 148      *  (RMS) thread.
 149      *
 150      *  The `threadAttrs.stackSize` field is optional when configuring a
 151      *  server, though strongly recommended.  Stack overrun is a very common
 152      *  cause of system instability.  If the `threadAttrs.stackSize` field is
 153      *  not assigned by the server integrator's script, a default value of
 154      *  1K (1024 bytes) will be added to the value of
 155      *  {@link #stackSizePad stackSizePad} and used.
 156      *
 157      *  The `threadAttrs.priority` field is optional when configuring a
 158      *  server.  If it is not assigned, by the server integrator's script, a
 159      *  default value of {@link #MINPRI MINPRI} will be used.
 160      *
 161      *  The `threadAttrs.stackMemId` field is optional when configuring a
 162      *  server.  If it is not assigned, by the server integrator's script, a
 163      *  default value of 0 will be used.
 164      */
 165     config ThreadAttrs threadAttrs;
 166
 167     /*!
 168      *  ======== algs ========
 169      *  Table of all algorithms supported by this DSP Server
 170      *
 171      *  See {@link #AlgDesc} documentation for more details.
 172      */
 173     config AlgDesc algs[];
 174
 175
 176     /*!
 177      *  ======== stackSizePad ========
 178      *  Pad applied to unconfigured, CE-created threads.
 179      *
 180      *  This pad is only applied to algorithm stacks that are not configured,
 181      *  as well as the {@link #threadAttrs Server thread} if it is not
 182      *  configured.
 183      */
 184     config Int stackSizePad = 8192;
 185
 186
 187     /*!
 188      *  ======== traceBufferSize ========
 189      *  (DEPRECATED) Size of the server trace buffer, in MAUs.
 190      *
 191      *  Trace buffer size should be set via {@link
 192      *  ti.sdo.ce.osal.Global#traceBufferSize}.  Changing
 193      *  traceBufferSize here is currently supported for backward
 194      *  compatibility, but will not be supported in the future.
 195      *
 196      *  The server trace buffer is a circular buffer of characters written
 197      *  to by clients of the {@link ti.sdo.ce.osal} Trace interface -
 198      *  and read by the Engine_*Trace() methods.
 199      *
 200      * @_nodoc
 201      */
 202     config Int traceBufferSize = 0;
 203
 204     /*!
 205      *  ======== autoGenScratchSizeArrays ========
 206      *  Enable automatic generation of {@link ti.sdo.fc.dskt2.DSKT2 DSKT2}
 207      *  scratch group size arrays.
 208      *
 209      *  This configuration flag enables/disables automatic generation of
 210      *  the {@link ti.sdo.fc.dskt2.DSKT2#DARAM_SCRATCH_SIZES} and
 211      *  {@link ti.sdo.fc.dskt2.DSKT2#SARAM_SCRATCH_SIZES} scratch group sizes
 212      *  arrays.
 213      *
 214      *  When enabled (1), the arrays will be automatically generated during
 215      *  Server configuration, based upon the
 216      *  {@link ICodec#getDaramScratchSize()} and
 217      *  {@link ICodec#getSaramScratchSize()} methods of the configured set of
 218      *  algorithms.
 219      *
 220      *  When disabled (0), the engine integrator needs to manually configure
 221      *  the scratch group sizes arrays.
 222      */
 223     config Bool autoGenScratchSizeArrays = 0;
 224
 225     /*!
 226      *  ======== SkelCachingPolicy ========
 227      *  Caching behavior that all skeletons will use.
 228      */
 229     enum SkelCachingPolicy {
 230         LOCALBUFFERINVWB = 0, /*! Invalidate before process, writeback after */
 231         WBINVALL         = 1, /*! Writeback invalidate all after process */
 232         NONE             = 2  /*! No cache management of buffers */
 233     };
 234
 235     /*!
 236      *  ======== SkelCachingPolicy ========
 237      *  Caching behavior that all skeletons will use.
 238      */
 239     config SkelCachingPolicy skelCachingPolicy;
 240
 241     /*!
 242      *  ======== close ========
 243      *  internal close method (see package.xs)
 244      * @_nodoc
 245      */
 246     function close();
 247
 248     /*!
 249      *  ======== validate ========
 250      *  internal validate method (see package.xs)
 251      * @_nodoc
 252      */
 253     function validate();
 254 }