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    /*
    15     *  ======== ISemaphore.xdc ========
    16     */
    17    
    18    import xdc.runtime.Error;
    19    
    20    /*!
    21     *  ======== ISemaphore ========
    22     *  Interface implemented by all front-end semaphore providers.
    23     *
    24     *  {@link #SemThread} and {@link #SemProcess}. [EXPERIMENTAL]
    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     */
    36    @DirectCall
    37    interface ISemaphore {
    38    
    39        /*!
    40         *  ======== PendStatus ========
    41         *  Error codes returned by Semaphore_pend
    42         */
    43        enum PendStatus {
    44            PendStatus_ERROR = -1,
    45            PendStatus_TIMEOUT = 0,
    46            PendStatus_SUCCESS = 1
    47        };
    48        
    49        /*! Used as the timeout value to specify wait forever */
    50        const UInt FOREVER = ~(0);
    51        
    52        /*! Types of semaphores. */
    53        enum Mode {
    54            Mode_COUNTING,  /*! Counting semaphore. */
    55            Mode_BINARY     /*! Binary Semaphore. */
    56        };
    57        
    58    instance:
    59    
    60        /*! 
    61         *  ======== mode ========
    62         *  Semaphore mode. Default is COUNTING.
    63         *
    64         *  When mode is BINARY , the semaphore has only two states, available
    65         *  and unavailable. When mode is COUNTING, the semaphore keeps track of
    66         *  number of times a semaphore is posted.
    67         */
    68        config Mode mode = Mode_COUNTING;
    69        
    70        /*!
    71         *  ======== pend ========
    72         *  Wait for the semaphore to become available.
    73         *
    74         *  @p(blist)
    75         *  -{@link #PendStatus_ERROR} if an error occured.
    76         *  -{@link #PendStatus_TIMEOUT} denotes timeout.
    77         *  -{@link #PendStatus_SUCCESS} semaphore was decremented. 
    78         *    details.
    79         *  @p
    80         *
    81         *  @param(timeout) timeout in microseconds
    82         *  @param(eb)      error block 
    83         *  @a(returns)     refer to description above
    84         */
    85        Int pend(UInt timeout, Error.Block *eb);
    86    
    87        /*!
    88         *  ======== post ========
    89         *  Increment the semaphore count.
    90         *
    91         *  @param(eb)      error block 
    92         *  @a(returns)     true for success, false for error in error block
    93         */
    94        Bool post(Error.Block *eb);
    95    }
    96    /*
    97     *  @(#) xdc.runtime.knl; 1, 0, 0,281; 3-20-2014 17:05:52; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
    98     */
    99