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