1 /**
2 * @file Gate.h
3 *
4 * @brief Critical section support.
5 *
6 * Gates are used by clients to protect concurrent access to critical
7 * data structures. Critical data structures are those that must be
8 * updated by at most one thread at a time. All code that needs access
9 * to a critical data structure "enters" a gate (that's associated with the
10 * data structure) prior to accessing the data, modifies the data structure,
11 * then "leaves" the gate.
12 *
13 * A gate is responsible for ensuring that at most one thread at a time
14 * can enter and execute "inside" the gate. There are several
15 * implementations of gates, with different system executation times and
16 * latency tradoffs. In addition, some gates must not be entered by certain
17 * thread types; e.g., a gate that is implemented via a "blocking" semaphore
18 * must not be called by an interrupt service routine (ISR).
19 *
20 * A module can be declared "gated" by adding the `@Gated` attribute to the
21 * module's XDC spec file. A "gated" module is assigned a module-level gate
22 * at the configuration time, and that gate is then used to protect critical
23 * sections in the module's target code. A module-level gate is an instance of
24 * a module implementing `{@link IGateProvider}` interface. However, gated
25 * modules do not access their module-level gates directly. They use this
26 * module to access transparently their module-level gate.
27 *
28 * Application code that is not a part of any module also has a
29 * module-level gate, configured through the module `{@link Main}`.
30 *
31 * Each gated module can optionally create gates on an adhoc basis at
32 * runtime using the same gate module that was used to create the module
33 * level gate.
34 *
35 * Gates that work by disabling all preemption while inside a gate can be
36 * used to protect data structures accessed by ISRs and other
37 * threads. But, if the time required to update the data structure is not
38 * a small constant, this type of gate may violate a system's real-time
39 * requirements.
40 *
41 * Gates have two orthogonal attributes: "blocking" and "preemptible".
42 * In general, gates that are "blocking" can not be use by code that is
43 * called by ISRs and gates that are not "preemptible" should only be used to
44 * to protect data manipulated by code that has small constant execution
45 * time.
46 *
47 *
48 * @ver 02.00.00.46_alpha1
49 *
50 * ============================================================================
51 *
52 * Copyright (c) 2008-2009, Texas Instruments Incorporated
53 *
54 * Redistribution and use in source and binary forms, with or without
55 * modification, are permitted provided that the following conditions
56 * are met:
57 *
58 * * Redistributions of source code must retain the above copyright
59 * notice, this list of conditions and the following disclaimer.
60 *
61 * * Redistributions in binary form must reproduce the above copyright
62 * notice, this list of conditions and the following disclaimer in the
63 * documentation and/or other materials provided with the distribution.
64 *
65 * * Neither the name of Texas Instruments Incorporated nor the names of
66 * its contributors may be used to endorse or promote products derived
67 * from this software without specific prior written permission.
68 *
69 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
70 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
71 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
72 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
73 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
74 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
75 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
76 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
77 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
78 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
79 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
80 * Contact information for paper mail:
81 * Texas Instruments
82 * Post Office Box 655303
83 * Dallas, Texas 75265
84 * Contact information:
85 * http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm?
86 * DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact
87 * ============================================================================
88 *
89 */
92 #ifndef GATE_H_0xAF6F
93 #define GATE_H_0xAF6F
95 #include <ti/syslink/utils/IGateProvider.h>
97 #if defined (__cplusplus)
98 extern "C" {
99 #endif
101 extern IGateProvider_Handle Gate_systemHandle;
103 /* =============================================================================
104 * APIs
105 * =============================================================================
106 */
107 /* Function to enter a Gate */
108 IArg Gate_enterSystem (void);
110 /* Function to leave a Gate */
111 Void Gate_leaveSystem (IArg key);
113 #if defined (__cplusplus)
114 }
115 #endif /* defined (__cplusplus) */
117 #endif /* GATE_H_0xAF6F */