[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_irqlock.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  *\r
4  * This software is available to you under the OpenIB.org BSD license\r
5  * below:\r
6  *\r
7  *     Redistribution and use in source and binary forms, with or\r
8  *     without modification, are permitted provided that the following\r
9  *     conditions are met:\r
10  *\r
11  *      - Redistributions of source code must retain the above\r
12  *        copyright notice, this list of conditions and the following\r
13  *        disclaimer.\r
14  *\r
15  *      - Redistributions in binary form must reproduce the above\r
16  *        copyright notice, this list of conditions and the following\r
17  *        disclaimer in the documentation and/or other materials\r
18  *        provided with the distribution.\r
19  *\r
20  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
21  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
22  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
23  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
24  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
25  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
26  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
27  * SOFTWARE.\r
28  *\r
29  * $Id$\r
30  */\r
31 \r
32 \r
33 /*\r
34  * Abstract:\r
35  *      Declaration of interrupt level IRQ lock object.\r
36  * \r
37  * Environment:\r
38  *      All\r
39  */\r
40 \r
41 \r
42 #ifndef _CL_IRQLOCK_H_\r
43 #define _CL_IRQLOCK_H_\r
44 \r
45 \r
46 #include <complib/cl_irqlock_osd.h>\r
47 \r
48 \r
49 /****h* Component Library/Irqlock\r
50 * NAME\r
51 *       Irqlock\r
52 *\r
53 * DESCRIPTION\r
54 *       Irqlock provides synchronization at interrupt level between threads for \r
55 *       exclusive access to a resource.\r
56 *\r
57 *       The irqlock functions manipulate a cl_irqlock_t structure which should \r
58 *       be treated as opaque and should be manipulated only through the provided \r
59 *       functions.\r
60 *\r
61 * SEE ALSO\r
62 *       Structures:\r
63 *               cl_irqlock_t\r
64 *\r
65 *       Initialization:\r
66 *               cl_irqlock_construct, cl_irqlock_init, cl_irqlock_destroy\r
67 *\r
68 *       Manipulation\r
69 *               cl_irqlock_acquire, cl_irqlock_release\r
70 *********/\r
71 \r
72 \r
73 #ifdef __cplusplus\r
74 extern "C"\r
75 {\r
76 #endif\r
77 \r
78 \r
79 /****f* Component Library: Irqlock/cl_irqlock_construct\r
80 * NAME\r
81 *       cl_irqlock_construct\r
82 *\r
83 * DESCRIPTION\r
84 *       The cl_irqlock_construct function initializes the state of a \r
85 *       IRQ lock.\r
86 *\r
87 * SYNOPSIS\r
88 */\r
89 CL_EXPORT void CL_API\r
90 cl_irqlock_construct( \r
91         IN      cl_irqlock_t* const             p_irqlock );\r
92 /*\r
93 * PARAMETERS\r
94 *       p_irqlock \r
95 *               [in] Pointer to a IRQ lock structure whose state to initialize.\r
96 *\r
97 * RETURN VALUE\r
98 *       This function does not return a value.\r
99 *\r
100 * NOTES\r
101 *       Allows calling cl_irqlock_destroy without first calling \r
102 *       cl_irqlock_init.\r
103 *\r
104 *       Calling cl_irqlock_construct is a prerequisite to calling any other\r
105 *       IRQ lock function except cl_irqlock_init.\r
106 *\r
107 * SEE ALSO\r
108 *       Irqlock, cl_irqlock_init, cl_irqlock_destroy\r
109 *********/\r
110 \r
111 \r
112 /****f* Component Library: Irqlock/cl_irqlock_init\r
113 * NAME\r
114 *       cl_irqlock_init\r
115 *\r
116 * DESCRIPTION\r
117 *       The cl_irqlock_init function initializes a IRQ lock for use.\r
118 *\r
119 * SYNOPSIS\r
120 */\r
121 CL_EXPORT cl_status_t CL_API\r
122 cl_irqlock_init( \r
123         IN      cl_irqlock_t* const             p_irqlock,\r
124         IN      cl_interrupt_t* const   p_interrupt );\r
125 /*\r
126 * PARAMETERS\r
127 *       p_irqlock \r
128 *               [in] Pointer to a IRQ lock structure to initialize.\r
129 *\r
130 *       p_interrupt\r
131 *               [in] Platform specific pointer conveying information about the\r
132 *               interrupt vector and level with which to synchronize.\r
133 *\r
134 * RETURN VALUES\r
135 *       CL_SUCCESS if initialization succeeded.\r
136 *\r
137 *       CL_ERROR if initialization failed. Callers should call \r
138 *       cl_irqlock_destroy to clean up any resources allocated during \r
139 *       initialization.\r
140 *\r
141 * NOTES\r
142 *       Initialize the IRQ lock structure. Allows calling cl_irqlock_aquire \r
143 *       and cl_irqlock_release.\r
144 *\r
145 *       In Linux, the p_interrupt parameter is currently ignored.\r
146 *\r
147 *       In Windows, the p_interrupt parameter is a pointer to a KINTERRUPT object,\r
148 *       the value of which is supplied by a call to IoConnectInterrupt.\r
149 *\r
150 * SEE ALSO\r
151 *       Irqlock, cl_irqlock_construct, cl_irqlock_destroy, \r
152 *       cl_irqlock_acquire, cl_irqlock_release\r
153 *********/\r
154 \r
155 \r
156 /****f* Component Library: Irqlock/cl_irqlock_destroy\r
157 * NAME\r
158 *       cl_irqlock_destroy\r
159 *\r
160 * DESCRIPTION\r
161 *       The cl_irqlock_destroy function performs all necessary cleanup of a \r
162 *       IRQ lock.\r
163 *\r
164 * SYNOPSIS\r
165 */\r
166 CL_EXPORT void CL_API\r
167 cl_irqlock_destroy( \r
168         IN      cl_irqlock_t* const             p_irqlock );\r
169 /*\r
170 * PARAMETERS\r
171 *       p_irqlock \r
172 *               [in] Pointer to a IRQ lock structure to destroy.\r
173 *\r
174 * RETURN VALUE\r
175 *       This function does not return a value.\r
176 *\r
177 * NOTES\r
178 *       Performs any necessary cleanup of a IRQ lock. This function must only \r
179 *       be called if either cl_irqlock_construct or cl_irqlock_init has been \r
180 *       called.\r
181 *\r
182 * SEE ALSO\r
183 *       Irqlock, cl_irqlock_construct, cl_irqlock_init\r
184 *********/\r
185 \r
186 \r
187 /****f* Component Library: Irqlock/cl_irqlock_acquire\r
188 * NAME\r
189 *       cl_irqlock_acquire\r
190 *\r
191 * DESCRIPTION\r
192 *       The cl_irqlock_acquire function acquires a IRQ lock.\r
193 *       This version of lock does not prevent an interrupt from \r
194 *       occuring on the processor on which the code is being\r
195 *       executed. To protect from an interrupt level resource\r
196 *       use the cl_irqlock_acquire_irq function.\r
197 *\r
198 * SYNOPSIS\r
199 */\r
200 CL_EXPORT void CL_API\r
201 cl_irqlock_acquire( \r
202         IN      cl_irqlock_t* const             p_irqlock );\r
203 /*\r
204 * PARAMETERS\r
205 *       p_irqlock \r
206 *               [in] Pointer to a IRQ lock structure to acquire.\r
207 *\r
208 * RETURN VALUE\r
209 *       This function does not return a value.\r
210 *\r
211 * SEE ALSO\r
212 *       Irqlock, cl_irqlock_release\r
213 *********/\r
214 \r
215 \r
216 /****f* Component Library: Irqlock/cl_irqlock_release\r
217 * NAME\r
218 *       cl_irqlock_release\r
219 *\r
220 * DESCRIPTION\r
221 *       The cl_irqlock_release function releases a IRQ lock object.\r
222 *\r
223 * SYNOPSIS\r
224 */\r
225 CL_EXPORT void CL_API\r
226 cl_irqlock_release(\r
227         IN      cl_irqlock_t* const             p_irqlock );\r
228 /*\r
229 * PARAMETERS\r
230 *       p_irqlock \r
231 *               [in] Pointer to a IRQ lock structure to release.\r
232 *\r
233 * RETURN VALUE\r
234 *       This function does not return a value.\r
235 *\r
236 * NOTES\r
237 *       Releases a IRQ lock after a call to cl_irqlock_acquire.\r
238 *\r
239 * SEE ALSO\r
240 *       Irqlock, cl_irqlock_acquire\r
241 *********/\r
242 \r
243 \r
244 #ifdef __cplusplus\r
245 }       /* extern "C" */\r
246 #endif\r
247 \r
248 #endif /* _CL_IRQLOCK_H_ */\r