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