1    /* 
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved. 
     3     *  This program and the accompanying materials are made available under the 
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at 
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IThreadSupport.xdc ========
    15     */
    16    
    17    import xdc.runtime.Error;
    18    
    19    /*!
    20     *  ======== IThreadSupport ========
    21     *  Interface for OS specific back-end.
    22     *
    23     *  The {@link xdc.runtime.knl} package contains modules that provide typical
    24     *  OS services. These xdc.runtime.knl modules require proxies to be
    25     *  bound to an OS specific delegate. This specifies the interface to 
    26     *  be implemented by the OS specific delegate for 
    27     *  {@link xdc.runtime.knl.Thread} module.
    28     *
    29     *  Refer to {@link xdc.runtime.knl.Thread} for more details on the APIs.
    30     */
    31    interface IThreadSupport
    32    {
    33        /*! Thread priorities which are mapped to OS specific value by Proxy */
    34        enum Priority {
    35        Priority_INVALID,
    36            Priority_LOWEST,
    37            Priority_BELOW_NORMAL,
    38            Priority_NORMAL,
    39            Priority_ABOVE_NORMAL,
    40            Priority_HIGHEST
    41        };
    42    
    43        /*! Invalid OS priority value */
    44        const Int INVALID_OS_PRIORITY = 0;
    45    
    46        /*! 
    47         *  The error status for {@link #getPriority} when an error is captured in 
    48         *  the  Error.Block.
    49         */
    50        const Int GETPRI_FAILED = -2;
    51    
    52        /*! Status returned by {@link #compareOsPriorities} when an error occurs */
    53        enum CompStatus {
    54            CompStatus_ERROR = -2,
    55        CompStatus_LOWER = -1,
    56        CompStatus_EQUAL = 0,
    57        CompStatus_HIGHER = 1
    58        };
    59    
    60        /*! typedef for function that gets called when the Thread runs. */
    61        typedef Void (*RunFxn)(IArg);
    62    
    63        /*! Struct to hold thread statistics from {@link #stat} */
    64        struct Stat {
    65            SizeT stackSize;
    66            SizeT stackUsed;
    67        }
    68    
    69        /*!
    70         *  ======== self ========
    71         *  Acquire the currently executing thread's handle.
    72         *
    73         *  Refer to {@link xdc.runtime.knl.Thread#self} for more details.
    74         *
    75         *  @param(eb)     Pointer to Error.Block
    76         *  @a(returns)    Handle in case of success; null for error;
    77         */
    78        Handle self(Error.Block* eb);
    79    
    80        /*!
    81         *  ======== start ========
    82         *  Start threads running.
    83         *
    84         *  Refer to {@link xdc.runtime.knl.Thread#start} for more details.
    85         *
    86         *  @param(eb)     Pointer to Error.Block
    87         *  @a(returns)    true for success; false for failure
    88         */
    89        Bool start(Error.Block* eb);
    90    
    91        /*!
    92         *  ======== yield ========
    93         *  Yield the currently scheduled thread.
    94         *
    95         *  Refer to {@link xdc.runtime.knl.Thread#yield} for more details.
    96         *
    97         *  @param(eb)     Pointer to Error.Block
    98         *  @a(returns)    true for success; false for failure
    99         */
   100        Bool yield(Error.Block* eb);
   101    
   102        /*!
   103         *  ======== compareOsPriorities ========
   104         *  Compare two priority values and find out which one represents a
   105         *  higher priority.
   106         *
   107         *  Refer to {@link xdc.runtime.knl.Thread#compareOsPriorities} for more 
   108         *  details.
   109         *
   110         *  @p(blist)
   111         *  -{@link #CompStatus_ERROR} if an error occured
   112         *  -{@link #CompStatus_LOWER} if p1 is lower than p2
   113         *  -{@link #CompStatus_EQUAL} if p1=p2
   114         *  -{@link #CompStatus_HIGHER} if p1 is higher than p2
   115         *    details.
   116         *  @p
   117         *
   118         *  @param(p1)      priority one
   119         *  @param(p2)      priority two
   120         *  @param(eb)      Pointer to Error.Block
   121         *  @a(returns)     Refer to description above
   122         */
   123        Int compareOsPriorities(Int p1, Int p2, Error.Block *eb);
   124        
   125        /*!
   126         *  ======== sleep ========
   127         *  Sleep for certain number of microseconds
   128         *
   129         *  Refer to {@link xdc.runtime.knl.Thread#sleep} for more details.
   130         *
   131         *  @param(timeout)     timeout in microseconds
   132         *  @param(eb)          Pointer to Error.Block
   133         *  @a(returns)         true for success; false for failure
   134         */
   135        Bool sleep(UInt timeout, Error.Block *eb);
   136    
   137    instance:
   138    
   139        /*! Thread function argument. Default is NULL. */
   140        config IArg arg = null;
   141    
   142        /*!
   143         *  ======== priority ========
   144         *  Thread priority
   145         *
   146         *  Thread defines several constants which allows applications to select
   147         *  a priority in an OS independent way. Priority_LOWEST, 
   148         *  Priority_BELOW_NORMAL, Priority_NORMAL, Priority_ABOVE_NORMAL and 
   149         *  Priority_HIGHEST. These values get mapped to OS specific priorities 
   150         *  by the OS specific delegate.
   151         */
   152        config Priority priority = Priority_NORMAL;
   153    
   154        /*!
   155         *  ======== osPriority ========
   156         *  OS specific thread priority
   157         *
   158         *  Used to specify an OS specific value for priority. If set this value
   159         *  takes precedence over {@link #priority}.
   160         */
   161        config Int osPriority = INVALID_OS_PRIORITY;
   162    
   163        /*! Thread stack size. If left at zero, OS default is used */
   164        config SizeT stackSize = 0;
   165    
   166        /*! User-specified thread local storage data. */
   167        config Ptr tls = null;
   168    
   169        /*!
   170         *  ======== create ========
   171         *  Create a Thread object.
   172         *
   173         *  This function spawns a new thread calling the function fxn.
   174         *
   175         *  @param(fxn) function for new thread to begin execution
   176         */
   177        create(RunFxn fxn);
   178    
   179        /*!
   180         *  ======== join ========
   181         *  Join on a Thread.
   182         *
   183         *  Refer to {@link xdc.runtime.knl.Thread#join} for more details.
   184         *
   185         *  @param(eb)     Pointer to Error.Block
   186         *  @a(returns)    true for success; false for failure
   187         */
   188        Bool join(Error.Block* eb);
   189    
   190        /*!
   191         *  ======== getPriority ========
   192         *  Obtain a thread's priority.
   193         *
   194         *  Refer to {@link xdc.runtime.knl.Thread#getPriority} for more details.
   195         *
   196         *  @param(eb)     Pointer to Error.Block
   197         *  @a(returns)    thread priority in case of success; Priority_INVALID in
   198         *                 case of error; 
   199         */
   200        Priority getPriority(Error.Block* eb);
   201    
   202        /*!
   203         *  ======== setPriority ========
   204         *  Set a thread's priority.
   205         *
   206         *  Refer to {@link xdc.runtime.knl.Thread#setPriority} for more details.
   207         *
   208         *  @param(newPri)    new thread priority
   209         *  @param(eb)        Pointer to Error.Block
   210         *  @a(returns)       true for success; false for failure
   211         */
   212        Bool setPriority(Priority newPri, Error.Block* eb);
   213    
   214        /*!
   215         *  ======== getOsPriority ========
   216         *  Obtain a thread's os specific priority.
   217         *
   218         *  For OSes that support dynamic priority boosting, the value returned 
   219         *  is the base priority of the thread.
   220         *
   221         *  Refer to {@link xdc.runtime.knl.Thread#getOsPriority} for more details.
   222         *
   223         *  @param(eb)      Pointer to Error.Block
   224         *  @a(returns)     thread priority in case of success; GETPRI_FAILED in
   225         *                  case of error;
   226         */
   227        Int getOsPriority(Error.Block *eb);
   228    
   229        /*!
   230         *  ======== setOsPriority ========
   231         *  Set a thread's priority.
   232         *
   233         *  This API sets the base priority of the thread on OSes that
   234         *  support dynamic priority boosting
   235         *
   236         *  Refer to {@link xdc.runtime.knl.Thread#setOsPriority} for more details.
   237         *
   238         *  @param(newPri)  new thread priority
   239         *  @param(eb)      Pointer to Error.Block
   240         *  @a(returns)     true for success; false for failure
   241         */
   242        Bool setOsPriority(Int newPri, Error.Block *eb);
   243    
   244        /*!
   245         *  ======== getOsHandle ========
   246         *  Get the OS thread handle
   247         *
   248         *   @a(returns)     null in case of error
   249         */
   250        Ptr getOsHandle();
   251    
   252        /*!
   253         *  ======== getTls ========
   254         *  Obtain a thread's local storage pointer
   255         *
   256         *  @a(returns)     null in case of error
   257         */ 
   258        Ptr getTls();
   259    
   260        /*!
   261         *  ======== setTls ========
   262         *  Set a thread's local storage pointer.
   263         *
   264         *  @param(tls)     thread tls 
   265         */
   266        Void setTls(Ptr tls);
   267    
   268    
   269        /*!
   270         *  ======== stat ========
   271         *  Obtain a thread's stats
   272         *
   273         *  @param(buf)    Pointer to Stat
   274         *  @param(eb)     Pointer to Error.Block
   275         *  @a(returns)    true for success; false for failure
   276         */
   277        Bool stat(Stat* buf, Error.Block* eb);
   278    
   279    }
   280    /*
   281     *  @(#) xdc.runtime.knl; 1, 0, 0,195; 9-20-2012 15:02:06; /db/ztree/library/trees/xdc/xdc-y36x/src/packages/
   282     */
   283