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     *  ======== Semaphore.xdc ========
    15     */
    16    
    17    import xdc.runtime.Assert;
    18    import xdc.runtime.Error;
    19    import xdc.runtime.knl.ISemaphore;
    20    
    21    /*!
    22     *  ======== Semaphore ========
    23     *  Provides semaphore services when an ISemaphore.Handle is available.
    24     *
    25     *  An application can isolate itself from ISemaphore implementations by using
    26     *  this module. The application must first obtain an ISemaphore.Handle.
    27     *  It make get such a handle by directly calling {@link SemThread#create} or
    28     *  {@link SemProcess#create}. Then the application can use the generic
    29     *  APIs provided by this module.
    30     */
    31    @DirectCall
    32    
    33    module Semaphore
    34    {
    35        /*!
    36         *  ======== PendStatus ========
    37         *  Error codes returned by Semaphore_pend
    38         */
    39        enum PendStatus {
    40            PendStatus_ERROR = -1,
    41            PendStatus_TIMEOUT = 0,
    42            PendStatus_SUCCESS = 1
    43        };
    44    
    45        /*! Used as the timeout value to specify wait forever */
    46        const UInt FOREVER = ISemaphore.FOREVER;
    47        
    48        /*!
    49         *  Proxy used for optimization.
    50         *
    51         *  If ALL ISemaphore.Handles were created using the same module 
    52         *  (e.g SemProcess) then setting this Proxy to SemProcess and 
    53         *  setting Semaphore.Proxy.abstractInstances$ = false, 
    54         *  Semaphore APIs can have better performance.
    55         */
    56        proxy Proxy inherits ISemaphore;
    57    
    58        /*!
    59         *  ======== pend ========
    60         *  Wait for the semaphore to have a nonzero count, then decrement it.
    61         *
    62         *  The function returns one of the following:
    63         *  @p(blist)
    64         *  -{@link #PendStatus_ERROR} if an error occured.
    65         *  -{@link #PendStatus_TIMEOUT} denotes timeout.
    66         *  -{@link #PendStatus_SUCCESS} semaphore was decremented. 
    67         * 
    68         *  @p
    69         *
    70         *  @param(sem)     ISemaphore.Handle to be used
    71         *  @param(timeout) timeout in microseconds or
    72         *  {@link #FOREVER Semaphore_FOREVER} to wait forever
    73         *  @param(eb)      Pointer to Error.Block
    74         *  @a(returns)     status returned. (refer to above description)
    75         */
    76        Int pend(ISemaphore.Handle sem, UInt timeout, Error.Block *eb);
    77    
    78        /*!
    79         *  ======== post ========
    80         *  Increment the semaphore count.
    81         *
    82         *  @param(sem)     ISemaphore.Handle to be used
    83         *  @param(eb)      Pointer to Error.Block
    84         *  @a(returns)     true for success, false for error in Error block.  
    85         */
    86        Bool post(ISemaphore.Handle sem, Error.Block *eb);
    87    }
    88    /*
    89     *  @(#) xdc.runtime.knl; 1, 0, 0,281; 3-20-2014 17:05:52; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
    90     */
    91