1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 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 }