HwSpinLock: Pull in the ti.gates.hwspinlock module from omapzoom sysbios-rpmsg.
[ipc/ipcdev.git] / packages / ti / gates / hwspinlock / HwSpinlock.h
1 /*
2  * Copyright (c) 2011-2013, 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  */
33 #ifndef ti_gates_HwSpinlock__include
34 #define ti_gates_HwSpinlock__include
36 #if defined (__cplusplus)
37 extern "C" {
38 #endif
40 extern UInt32 ti_gates_HwSpinlock_sharedState[];
41 extern const UInt32 ti_gates_HwSpinlock_numLocks;
43 /* =============================================================================
44  *  All success and failure codes for the module
45  * =============================================================================
46  */
48 /*!
49  *  @def    HwSpinlock_S_SUCCESS
50  *  @brief  Operation is successful.
51  */
52 #define HwSpinlock_S_SUCCESS            0
54 /*!
55  *  @def    HwSpinlock_NO_SPINLOCK
56  *  @brief  Not hwspinlock Id associated to the obj.
57  */
58 #define HwSpinlock_NO_SPINLOCK         -1
60 /*!
61  *  @def    HwSpinlock_E_FAIL
62  *  @brief  Generic failure.
63  */
64 #define HwSpinlock_E_FAIL              -2
66 /*!
67  *  @def    HwSpinlock_E_TIMEOUT
68  *  @brief  Operation timed out.
69  */
70 #define HwSpinlock_E_TIMEOUT           -3
72 /*!
73  *  @def    HwSpinlock_STILL_IN_USE
74  *  @brief  handle is still in use..
75  */
76 #define HwSpinlock_STILL_IN_USE        -4
78 /*!
79  *  @def    HwSpinlock_WAIT_FOREVER
80  *  @brief  Use as a NOT timeout option.
81  */
82 #define HwSpinlock_WAIT_FOREVER        0xFFFFFFFF
85 /* =============================================================================
86  *  Structures & Enums
87  * =============================================================================
88  */
90 /*!
91  *  @brief  HwSpinlock state
92  */
93 typedef enum {
94     HwSpinlock_STATE_FREE,
95     HwSpinlock_STATE_TAKEN
96 } HwSpinlock_State;
98 /*!
99  *  @brief  A set of local context protection levels
100  *          - HwSpinlock_PreemptGate_HWI  -> GateHwi: disables interrupts
101  *          - HwSpinlock_PreemptGate_SWI  -> GateSwi: disables Swi's (software interrupts)
102  *          - HwSpinlock_PreemptGate_TASK -> GateTask: disables Task's preemption
103  */
104 typedef enum HwSpinlock_PreemptGate {
105     HwSpinlock_PreemptGate_NONE   = 0,  /* Use no local protection */
106     HwSpinlock_PreemptGate_HWI    = 1,  /* Use the INTERRUPT local protection level */
107     HwSpinlock_PreemptGate_SWI    = 2,  /* Use the SWI local protection level */
108     HwSpinlock_PreemptGate_TASK   = 3   /* Use the TASK local protection level */
109 } HwSpinlock_PreemptGate;
111 typedef Void * (*HwSpinlock_hookFxn)(Void *);
113 /*!
114  *  @brief  HwSpinlock_Params
115  */
116 typedef struct HwSpinlock_Params {
117     Int                   id;
118     HwSpinlock_hookFxn    reqFxn;
119     HwSpinlock_hookFxn    relFxn;
120     Void                  *arg1;
121     Void                  *arg2;
122 } HwSpinlock_Params;
124 /*!
125  *  @brief  HwSpinlock_Key
126  */
127 typedef struct HwSpinlock_Key {
128     IArg key;
129     Bool valid;
130 } HwSpinlock_Key;
132 /*!
133  *  @brief  HwSpinlock_Handle type
134  */
135 typedef struct HwSpinlock_Object *HwSpinlock_Handle;
138 /* =============================================================================
139  *  HwSpinlock Interface Functions
140  * =============================================================================
141  */
143 /*!
144  *  @brief      HwSpinlock_Params_init
145  *
146  *  @param[in]  HwSpinlock_Params
147  *
148  *  @return     Void
149  */
150 Void HwSpinlock_Params_init(HwSpinlock_Params *params);
152 /*!
153  *  @brief      Create spinlock
154  *
155  *  @param[in]  resourceId, baseAddr
156  *
157  *  @return     HwSpinlock_Handle
158  */
159 HwSpinlock_Handle HwSpinlock_create(HwSpinlock_Params *params);
161 /*!
162 *  @brief      HwSpinlock_delete
164 *  @param[in]  HwSpinlock_Handle
166 *  @return     Status
167 */
168 Int HwSpinlock_delete(HwSpinlock_Handle handle);
170 /*!
171  *  @brief      Enter/Acquire the HwSpinlock
172  *
173  *  @param[in]  timeout, local protecttion option
174  *
175  *  @return     Status
176  */
177 Int HwSpinlock_enter(HwSpinlock_Handle handle, HwSpinlock_PreemptGate pType,
178                      UInt timeout, HwSpinlock_Key *key);
180 /*!
181  *  @brief      Leave the HwSpinlock
182  *
183  *  @param[in]  HwSpinlock handle
184  *
185  *  @return     Void
186  */
187 Void HwSpinlock_leave(HwSpinlock_Handle handle, HwSpinlock_Key *key);
189 /*!
190  *  @brief      HwSpinlock_getId
191  *
192  *  @param[in]  HwSpinlock handle
193  *
194  *  @return     Spinlock Id
195  */
196 Int HwSpinlock_getId(HwSpinlock_Handle handle);
198 /*!
199  *  @brief      HwSpinlock_getState
200  *
201  *  @param[in]  HwSpinlock handle
202  *
203  *  @return     Current State
204  */
205 HwSpinlock_State HwSpinlock_getState(HwSpinlock_Handle handle);
207 #if defined (__cplusplus)
209 #endif /* defined (__cplusplus) */
211 #endif /* ti_gates_HwSpinlock__include */