|
1 /* |
|
2 * CmdMBox_api.h |
|
3 * |
|
4 * Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved. |
|
5 * All rights reserved. |
|
6 * |
|
7 * This program and the accompanying materials are made available under the |
|
8 * terms of the Eclipse Public License v1.0 or BSD License which accompanies |
|
9 * this distribution. The Eclipse Public License is available at |
|
10 * http://www.eclipse.org/legal/epl-v10.html and the BSD License is as below. |
|
11 * |
|
12 * Redistribution and use in source and binary forms, with or without |
|
13 * modification, are permitted provided that the following conditions |
|
14 * are met: |
|
15 * |
|
16 * * Redistributions of source code must retain the above copyright |
|
17 * notice, this list of conditions and the following disclaimer. |
|
18 * * Redistributions in binary form must reproduce the above copyright |
|
19 * notice, this list of conditions and the following disclaimer in |
|
20 * the documentation and/or other materials provided with the |
|
21 * distribution. |
|
22 * * Neither the name Texas Instruments nor the names of its |
|
23 * contributors may be used to endorse or promote products derived |
|
24 * from this software without specific prior written permission. |
|
25 * |
|
26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
|
27 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
|
28 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
|
29 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
|
30 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
|
31 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
|
32 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
|
33 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
|
34 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
|
35 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
|
36 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
37 */ |
|
38 |
|
39 |
|
40 /** \file CmdMBox_api.h |
|
41 * \brief CmdMbox api |
|
42 * |
|
43 * \see CmdMBox.c |
|
44 */ |
|
45 |
|
46 #ifndef _CMDMBOX_API_H_ |
|
47 #define _CMDMBOX_API_H_ |
|
48 |
|
49 #include "TWDriverInternal.h" |
|
50 |
|
51 |
|
52 /***************************************************************************** |
|
53 ** Types ** |
|
54 *****************************************************************************/ |
|
55 typedef TI_STATUS (*TCmdMboxErrorCb) (TI_HANDLE hCmdQueue, TI_UINT32 command, TI_UINT32 status, void *param); |
|
56 |
|
57 |
|
58 /***************************************************************************** |
|
59 ** API functions definitions ** |
|
60 *****************************************************************************/ |
|
61 |
|
62 /* |
|
63 * \brief Create the mailbox object |
|
64 * |
|
65 * \param hOs - OS module object handle |
|
66 * \return Handle to the created object |
|
67 * |
|
68 * \par Description |
|
69 * Calling this function creates a CmdMbox object |
|
70 * |
|
71 * \sa cmdMbox_Destroy |
|
72 */ |
|
73 TI_HANDLE cmdMbox_Create (TI_HANDLE hOs); |
|
74 |
|
75 |
|
76 /* |
|
77 * \brief Destroys the mailbox object |
|
78 * |
|
79 * \param hCmdMbox - The object to free |
|
80 * \return TI_OK |
|
81 * |
|
82 * \par Description |
|
83 * Calling this function destroys a CmdMbox object |
|
84 * |
|
85 * \sa cmdMbox_Create |
|
86 */ |
|
87 TI_STATUS cmdMbox_Destroy (TI_HANDLE hCmdMbox); |
|
88 |
|
89 |
|
90 /* |
|
91 * \brief Configure the CmdMbox object |
|
92 * |
|
93 * \param hCmdMbox - Handle to CmdMbox |
|
94 * \param hReport - Handle to report module |
|
95 * \param hTwIf - Handle to TwIf |
|
96 * \param hTimer - Handle to os timer |
|
97 * \param hCmdQueue - Handle to CmdQueue |
|
98 * \param fErrorCb - Handle to error handling function |
|
99 * \return TI_OK on success or TI_NOK on failure |
|
100 * |
|
101 * \par Description |
|
102 * |
|
103 * \sa |
|
104 */ |
|
105 TI_STATUS cmdMbox_Init (TI_HANDLE hCmdMbox, |
|
106 TI_HANDLE hReport, |
|
107 TI_HANDLE hTwIf, |
|
108 TI_HANDLE hTimer, |
|
109 TI_HANDLE hCmdQueue, |
|
110 TCmdMboxErrorCb fErrorCb); |
|
111 |
|
112 |
|
113 /* |
|
114 * \brief configure the mailbox address. |
|
115 * |
|
116 * \param hCmdMbox - Handle to CmdMbox |
|
117 * \param fCb - Pointer to the CB |
|
118 * \param hCb - Cb's handle |
|
119 * \return TI_OK or TI_PENDING |
|
120 * |
|
121 * \par Description |
|
122 * Called from HwInit to read the command mailbox address. |
|
123 * |
|
124 * \sa |
|
125 */ |
|
126 TI_STATUS cmdMbox_ConfigHw (TI_HANDLE hCmdMbox, fnotify_t fCb, TI_HANDLE hCb); |
|
127 |
|
128 |
|
129 /* |
|
130 * \brief Send the Command to the Mailbox |
|
131 * |
|
132 * \param hCmdMbox - Handle to CmdMbox |
|
133 * \param cmdType - |
|
134 * \param pParamsBuf - The buffer that will be written to the mailbox |
|
135 * \param uWriteLen - Length of data to write to the mailbox |
|
136 * \param uReadLen - Length of data to read from the mailbox (when the result is received) |
|
137 * \return TI_PENDING |
|
138 * |
|
139 * \par Description |
|
140 * Copy the buffer given to a local struct, update the write & read lengths |
|
141 * and send to the FW's mailbox. |
|
142 * |
|
143 * ------------------------------------------------------ |
|
144 * | CmdMbox Header | Cmd Header | Command parameters | |
|
145 * ------------------------------------------------------ |
|
146 * | ID | Status | Type | Length | Command parameters | |
|
147 * ------------------------------------------------------ |
|
148 * 16bit 16bit 16bit 16bit |
|
149 * |
|
150 * \sa cmdMbox_CommandComplete |
|
151 */ |
|
152 TI_STATUS cmdMbox_SendCommand (TI_HANDLE hCmdMbox, Command_e cmdType, TI_UINT8* pParamsBuf, TI_UINT32 uWriteLen, TI_UINT32 uReadLen); |
|
153 |
|
154 |
|
155 /* |
|
156 * \brief Read the command's result |
|
157 * |
|
158 * \param hCmdMbox - Handle to CmdMbox |
|
159 * \return void |
|
160 * |
|
161 * \par Description |
|
162 * This function is called for FwEvent module uppon receiving command complete interrupt. |
|
163 * It issues a read transaction from the mailbox with a CB. |
|
164 * |
|
165 * \sa cmdMbox_SendCommand, cmdMbox_TransferComplete |
|
166 */ |
|
167 void cmdMbox_CommandComplete (TI_HANDLE hCmdMbox); |
|
168 |
|
169 |
|
170 /* |
|
171 * \brief Calls the cmdQueue_ResultReceived. |
|
172 * |
|
173 * \param hCmdMbox - Handle to CmdMbox |
|
174 * \return TI_OK |
|
175 * |
|
176 * \par Description |
|
177 * This function is called from cmdMbox_CommandComplete on a sync read, or from TwIf as a CB on an async read. |
|
178 * It calls cmdQueue_ResultReceived to continue the result handling procces & switch the bCmdInProgress flag to TI_FALSE, |
|
179 * meaning other commands can be sent to the FW. |
|
180 * |
|
181 * \sa cmdMbox_SendCommand, cmdMbox_TransferComplete |
|
182 */ |
|
183 TI_STATUS cmdMbox_TransferComplete (TI_HANDLE hCmdMbox); |
|
184 |
|
185 |
|
186 /* |
|
187 * \brief Restart the module upon driver stop or restart |
|
188 * |
|
189 * \param hCmdMbox - Handle to CmdMbox |
|
190 * \return TI_OK |
|
191 * |
|
192 * \par Description |
|
193 * |
|
194 * \sa |
|
195 */ |
|
196 TI_STATUS cmdMbox_Restart (TI_HANDLE hCmdMbox); |
|
197 |
|
198 |
|
199 /* |
|
200 * \brief Return the latest command status |
|
201 * |
|
202 * \param hCmdMbox - Handle to CmdMbox |
|
203 * \return TI_OK or TI_NOK |
|
204 * |
|
205 * \par Description |
|
206 * |
|
207 * \sa |
|
208 */ |
|
209 TI_STATUS cmdMbox_GetStatus (TI_HANDLE hCmdMbox); |
|
210 |
|
211 |
|
212 /* |
|
213 * \brief Return the MBox address |
|
214 * |
|
215 * \param hCmdMbox - Handle to CmdMbox |
|
216 * \return MBox address |
|
217 * |
|
218 * \par Description |
|
219 * |
|
220 * \sa |
|
221 */ |
|
222 TI_UINT32 cmdMbox_GetMboxAddress (TI_HANDLE hCmdMbox); |
|
223 |
|
224 |
|
225 /* |
|
226 * \brief Return the Command parameters buffer |
|
227 * |
|
228 * \param hCmdMbox - Handle to CmdMbox |
|
229 * \param pParamBuf - Holds the returned buffer |
|
230 * \return |
|
231 * |
|
232 * \par Description |
|
233 * Copying the command's data to pParamBuf |
|
234 * |
|
235 * \sa |
|
236 */ |
|
237 void cmdMbox_GetCmdParams (TI_HANDLE hCmdMbox, TI_UINT8* pParamBuf); |
|
238 |
|
239 |
|
240 #ifdef TI_DBG |
|
241 void cmdMbox_PrintInfo (TI_HANDLE hCmdMbox); |
|
242 #endif |
|
243 |
|
244 |
|
245 #endif |