1    /*
     2     * Copyright (c) 2014, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     */
    32    /*
    33     *  ======== package.xdc ========
    34     *
    35     */
    36    
    37    requires ti.sysbios.interfaces;
    38    requires ti.sysbios.knl;
    39    
    40    /*!
    41     *  ======== ti.sysbios.gates ========
    42     *  Contains modules that inherit from IGatePovider.
    43     *
    44     *  The {@link xdc.runtime.Gate} module is provided by XDCtools, and
    45     *  is documented in the XDCtools help, but SYS/BIOS provides
    46     *  additional implementations in the {@link ti.sysbios.gates} package.
    47     *
    48     *  A "Gate" is a module that implements the IGateProvider interface. 
    49     *  Gates are devices for preventing concurrent accesses to critical 
    50     *  regions of code. The various Gate implementations differ in how they 
    51     *  attempt to lock the critical regions.
    52     *  
    53     *  Threads can be preempted by other threads of higher priority, and 
    54     *  some sections of code need to be completed by one thread before they 
    55     *  can be executed by another thread. Code that modifies a linked list 
    56     *  is a common example of a critical region that may need to be protected 
    57     *  by a Gate.
    58     *  
    59     *  Gates generally work by either disabling some level of preemption such 
    60     *  as disabling task switching or even hardware interrupts, or by using a 
    61     *  binary semaphore.
    62     *  
    63     *  All Gate implementations support nesting through the use of a "key". 
    64     *  For Gates that function by disabling preemption, it is possible that 
    65     *  multiple threads would call Gate_enter(), but preemption should not be 
    66     *  restored until all of the threads have called Gate_leave(). 
    67     *  This functionality is provided through the use of a key. A call to 
    68     *  Gate_enter() returns a key that must then be passed back to Gate_leave(). 
    69     *  Only the outermost call to Gate_enter() returns the correct key for 
    70     *  restoring preemption. (The actual module name for the implementation 
    71     *  is used instead of "Gate" in the function name.)
    72     *  
    73     *  @a(Runtime Example)
    74     *  The following C code protects a critical region with 
    75     *  a Gate. This example uses a GateHwi, which disables and enables 
    76     *  interrupts as the locking mechanism.
    77     *  
    78     *  @p(code)
    79     *  UInt gateKey;
    80     *  GateHwi_Handle gateHwi;
    81     *  GateHwi_Params prms;
    82     *  GateHwi_Params_init(&prms);
    83     *  
    84     *  gateHwi = GateHwi_create(&prms, NULL);
    85     *  
    86     *  // Simultaneous operations on a List by multiple threads could
    87     *  // corrupt the List structure, so modifications to the List 
    88     *  // are protected with a Gate. 
    89     *  gateKey = GateHwi_enter(gateHwi);
    90     *  List_get(myList);
    91     *  GateHwi_leave(gateHwi, gateKey);
    92     *  @p
    93     *  
    94     */
    95    
    96    package ti.sysbios.gates [2,0,0,0] {
    97        module GateHwi;
    98        module GateAll;
    99        module GateSwi;
   100        module GateTask;
   101        module GateTest;
   102        module GateMutexPri;
   103        module GateMutex;
   104        module GateSpinlock;
   105    }