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