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 }