1    /* --COPYRIGHT--,ESD
     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     * --/COPYRIGHT--*/
    13    
    14    /*
    15     *  ======== ISemaphore.xdc ========
    16     */
    17     
    18     import xdc.runtime.Error;
    19    
    20    /*! 
    21     *  ======== ISemaphore ========
    22     *  Interface implemented by all front-end semaphore providers. 
    23     *  {@link #SemThread} and {@link #SemProcess}. [EXPERIMENTAL]
    24     *
    25     *  Semaphores can be used for synchronization and mutual exclusion.
    26     *
    27     *  pend() is used to wait for a semaphore. The timeout parameter allows the 
    28     *  caller to wait until a timeout, wait indefinitely, or not wait at all.
    29     *  The return value indicates whether or not the wait was successful.
    30     *
    31     *  post() is used to signal a semaphore. If no thread is waiting on the
    32     *  semaphore, then post() increments the semaphore count (for binary
    33     *  semaphores, the count is always 0 or 1).
    34     *
    35     *  getCount() returns the count of the semaphore.
    36     *
    37     *  reset() sets the semaphore count to a given value. There should be no
    38     *  threads waiting on the semaphore when reset() is called.
    39     *
    40     */
    41    interface ISemaphore {
    42    
    43        /*!
    44         *  ======== PendStatus ========
    45         *  Error codes returned by Semaphore_pend
    46         */
    47        enum PendStatus {
    48            PendStatus_ERROR = -1,
    49            PendStatus_TIMEOUT = 0,
    50            PendStatus_SUCCESS = 1
    51        };
    52        /*! Used as the timeout value to specify wait forever */
    53        const UInt FOREVER = ~(0);
    54        
    55        /*! Types of semaphores. */
    56        enum Mode {
    57            Mode_COUNTING,  /*! Counting semaphore. */
    58            Mode_BINARY     /*! Binary Semaphore. */
    59        };
    60        
    61    instance:
    62    
    63        /*! 
    64         *  ======== mode ========
    65         *  Semaphore mode. Default is COUNTING.
    66         *
    67         *  When mode is BINARY , the semaphore has only two states, available
    68         *  and unavailable. When mode is COUNTING, the semaphore keeps track of
    69         *  number of times a semaphore is posted.
    70         */
    71        config Mode mode = Mode_COUNTING;
    72        
    73        /*!
    74         *  ======== pend ========
    75         *  Wait for the semaphore to become available.
    76         *
    77         *  @p(blist)
    78         *  -{@link #PendStatus_ERROR} if an error occured.
    79         *  -{@link #PendStatus_TIMEOUT} denotes timeout.
    80         *  -{@link #PendStatus_SUCCESS} semaphore was decremented. 
    81         *    details.
    82         *  @p
    83         *
    84         *  @param(timeout) timeout in microseconds
    85         *  @param(eb)      error block 
    86         *  @a(returns)     refer to description above
    87         */
    88        Int pend(UInt timeout, Error.Block *eb);
    89    
    90        /*!
    91         *  ======== post ========
    92         *  Increment the semaphore count.
    93         *
    94         *  @param(eb)      error block 
    95         *  @a(returns)     true for success, false for error in error block
    96         */
    97        Bool post(Error.Block *eb);
    98    }
    99    
   100    /*
   101     *! Revision History
   102     *! ================
   103     *! 17-Apr-2009 nitya    Review updates
   104     */
   105    
   106    /*
   107     *  @(#) xdc.runtime.knl; 1, 0, 0,23; 7-29-2009 14:53:49; /db/ztree/library/trees/xdc-t56x/src/packages/
   108     */
   109