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     *  ======== ISync.xdc ========
    15     */
    16    
    17    import xdc.runtime.Error;
    18    
    19    /*!
    20     *  ======== ISync ========
    21     *  OS independent synchronization
    22     *
    23     *  This interface allows clients to select method of synchronization in an OS
    24     *  independent way.
    25     *
    26     *  Modules that require the user to pick a synchronization method, will
    27     *  request a `{@link #Handle}`. Clients of such modules can pick a blocking
    28     *  `ISync` implementation  or a non-blocking implementation.
    29     *
    30     *  This interface specifies two main functions `{@link #signal}` and
    31     *  `{@link #wait}`. These two functions are always used in pairs in modules 
    32     *  that use `ISync` instances. The `signal()` function is used to signal
    33     *  completion of an activity. The `wait()` function will allow the module to
    34     *  block or poll for completion of the same activity.
    35     *
    36     *  `ISync` mandates that the sync mechanism be binary and not support counters.
    37     *  Although the `wait()` function seems meaningless in the case of
    38     *  non-blocking sync, it allows modules to be written generically and support
    39     *  all `ISync` implementations. For non-blocking `ISync` the `wait()` function
    40     *  will return `WaitStatus_TIMEOUT` to denote timeout.
    41     */
    42    @DirectCall
    43    
    44    interface ISync
    45    {
    46        /*!
    47         *  ======== WaitStatus ========
    48         *  Error codes returned by ISync_wait
    49         */
    50        enum WaitStatus {
    51            WaitStatus_ERROR = -1,
    52            WaitStatus_TIMEOUT = 0,
    53            WaitStatus_SUCCESS = 1
    54        };
    55    
    56        /*!
    57         *  ======== Q_BLOCKING ========
    58         *  Blocking quality
    59         *
    60         *  Implementations with this "quality" may cause the calling thread to 
    61         *  block; 
    62         */
    63        const Int Q_BLOCKING = 1;
    64        
    65        /*! Used to wait forever */
    66        const UInt WAIT_FOREVER = ~(0);
    67    
    68        /*! Used to specify no waiting */
    69        const UInt NO_WAIT = 0;
    70    
    71    instance: 
    72        /*! 
    73         *  ======== create ========
    74         *  Create an ISync instance.
    75         */
    76        create();
    77    
    78        /*!
    79         *  ======== query ========
    80         *  Query for a particular quality.
    81         *
    82         *  FALSE is returned if quality not supported.
    83         *
    84         *  @param(qual)    quality
    85         *  @b(returns)     TRUE or FALSE.
    86         */
    87        Bool query(Int qual);
    88    
    89        /*!
    90         *  ======== signal ========
    91         *  Called at completion of an activity.
    92         *
    93         *  This function is non-blocking. It is also required that the underlying
    94         *  sync be binary in nature.
    95         *
    96         *  This function does not take an Error.Block intentionally because
    97         *  it can be called from ISR context.
    98         */
    99        Void signal();
   100    
   101        /*!
   102         *  ======== wait ========
   103         *  Called to wait/poll for completion of an activity.
   104         *
   105         *  This function can block. Non-blocking implementations should return
   106         *  WaitStatus_TIMEOUT to indicate a timeout.
   107         *
   108         *  @p(blist)
   109         *  -{@link #WaitStatus_ERROR} if an error occured.
   110         *  -{@link #WaitStatus_TIMEOUT} denotes timeout.
   111         *  -{@link #WaitStatus_SUCCESS} semaphore was decremented. 
   112         *  @p
   113         *
   114         *  @param(timeout)     Timeout in microseconds
   115         *  @param(eb)Hist      Pointer to Error.Block
   116         *  @b(returns)         Refer to description above
   117         */
   118        Int wait(UInt timeout, Error.Block *eb);
   119    }
   120    /*
   121     *  @(#) xdc.runtime.knl; 1, 0, 0,0; 8-8-2017 17:31:10; /db/ztree/library/trees/xdc/xdc-D20/src/packages/
   122     */
   123