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     *  ======== Idle.xdc ========
    34     *
    35     */
    36    package ti.sysbios.knl;
    37    
    38    import xdc.rov.ViewInfo;
    39    
    40    /*!
    41     *  ======== Idle ========
    42     *  Idle Thread Manager.
    43     *
    44     *  The Idle module is used to specify a list of functions to be called
    45     *  when no other tasks are running in the system. 
    46     *  
    47     *  If tasking is enabled (ie {@link ti.sysbios.BIOS#taskEnabled 
    48     *  BIOS.taskEnabled} = true), then the Task module will create an "Idle task"
    49     *  with the lowest possible priority. When no other tasks are running, this
    50     *  idle task runs in an infinite loop, calling the list of functions 
    51     *  specified by the Idle module. 
    52     *
    53     *  If tasking is disabled (ie {@link ti.sysbios.BIOS#taskEnabled 
    54     *  BIOS.taskEnabled} = false), then the idle functions are called in an 
    55     *  infinite loop within the {@link ti.sysbios.BIOS#start BIOS_start} 
    56     *  function called within main().
    57     *
    58     *  The list of idle functions is only statically configurable; it cannot be
    59     *  modified at runtime.
    60     *
    61     */
    62    
    63    @DirectCall
    64    module Idle
    65    {
    66        /*! Idle function type definition. */
    67        typedef Void (*FuncPtr)();
    68    
    69        metaonly struct ModuleView {
    70            UInt    index;
    71            UInt    coreId;
    72            String  fxn;
    73        }
    74        
    75        /*! @_nodoc */
    76        @Facet
    77        metaonly config ViewInfo.Instance rovViewInfo = 
    78            xdc.rov.ViewInfo.create({
    79                viewMap: [
    80                    ['Idle.funcList',
    81                        {
    82                            type: ViewInfo.MODULE_DATA,   
    83                            viewInitFxn: 'viewInitModule',   
    84                            structName: 'ModuleView'
    85                        }
    86                    ]
    87                ]
    88            });
    89        
    90        /*!
    91         *  ======== funcList ========
    92         *  @_nodoc
    93         *  The array of functions to be called when no other Tasks are running.
    94         */
    95        config FuncPtr funcList[length] = [];
    96        
    97        /*!
    98         *  ======== coreList ========
    99         *  @_nodoc
   100         *  The array of coreIds associated with Idle funcList[]
   101         */
   102        config UInt coreList[length] = [];
   103        
   104        /*!
   105         *  ======== idleFxns ========
   106         *  Functions to be called when no other Tasks are running
   107         *
   108         *  Functions added to the Idle.idleFxns[] array, as well as those
   109         *  added via the Idle.addFunc() API will be run by the Idle loop.
   110         *
   111         *  @a(NOTE)
   112         *  This array is intended for use by the GUI config tool.
   113         *
   114         *  Config script authors are encourged to use the 
   115         *  {@link #addFunc Idle.addFunc()} API to add idle functions
   116         *  to their applications.
   117         */
   118        metaonly config FuncPtr idleFxns[length] = [
   119            null, null, null, null,  /* slots for GUI */
   120            null, null, null, null
   121        ];
   122        
   123        /*!
   124         *  ======== addFunc ========
   125         *  Statically add a function to the Idle function list.
   126         *
   127         *  Functions added to the Idle function list are 
   128         *  called repeatedly by the Idle task function.
   129         *
   130         *  @see Idle#run
   131         *
   132         *  Usage example:
   133         *
   134         *  @p(code)
   135         *  var Idle = xdc.useModule('ti.sysbios.knl.Idle');
   136         *  Idle.addFunc('&myIdleFunc'); // add myIdleFunc() 
   137         *  @p
   138         *
   139         *  @a(NOTE)
   140         *  Idle functions have the following signature:
   141         *  @p(code)
   142         *  Void func(Void);
   143         *  @p
   144         */
   145        metaonly Void addFunc(FuncPtr func);
   146        
   147        /*!
   148         *  ======== addCoreFunc ========
   149         *  Statically add a core-unique function to the Idle function list.
   150         */
   151        metaonly Void addCoreFunc(FuncPtr func, UInt coreId);
   152        
   153        /*!
   154         *  ======== loop ========
   155         *  @_nodoc
   156         *  Idle loop which calls the idle functions in an infinite loop.
   157         *
   158         *  This function is called internally and is not normally intended
   159         *  to be called by the client.
   160         *
   161         *  When tasking is enabled, the Task module creates an Idle task which
   162         *  simply calls this function. If tasking is disabled, then this function
   163         *  is called after main and any module startup functions.
   164         *
   165         *  The body of this function is an infinite loop that calls the "run" 
   166         *  function.
   167         */
   168        Void loop(UArg arg1, UArg arg2);
   169    
   170        /*!
   171         *  ======== run ========
   172         *  Make one pass through idle functions
   173         *
   174         *  This function is called repeatedly by the Idle task when
   175         *  the Idle task has been enabled in the Task module 
   176         *  (see {@link Task#enableIdleTask}). 
   177         *
   178         *  This function makes one pass through an internal static array 
   179         *  of functions made up of functions added using the 
   180         *  {@link #addFunc Idle.addFunc()} API as well as any functions
   181         *  defined in the GUI tool's {@link #idleFxns Idle.idleFxns[]} array.
   182         *
   183         *  This function returns after all functions have been executed one 
   184         *  time.
   185         *
   186         *  @see Idle#addFunc
   187         *  @see Task#enableIdleTask
   188         *  @see Task#allBlockedFunc
   189         */
   190        Void run();
   191    
   192    }