1 /*
2 * Copyright 2008-2012 Freescale Semiconductor Inc.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 * * Redistributions of source code must retain the above copyright
7 * notice, this list of conditions and the following disclaimer.
8 * * Redistributions in binary form must reproduce the above copyright
9 * notice, this list of conditions and the following disclaimer in the
10 * documentation and/or other materials provided with the distribution.
11 * * Neither the name of Freescale Semiconductor nor the
12 * names of its contributors may be used to endorse or promote products
13 * derived from this software without specific prior written permission.
14 *
15 *
16 * ALTERNATIVELY, this software may be distributed under the terms of the
17 * GNU General Public License ("GPL") as published by the Free Software
18 * Foundation, either version 2 of that License or (at your option) any
19 * later version.
20 *
21 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
22 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24 * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
25 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33
34 /**************************************************************************//**
35 @File fm_vsp_ext.h
36
37 @Description FM Virtual Storage-Profile ...
38 *//***************************************************************************/
39 #ifndef __FM_VSP_EXT_H
40 #define __FM_VSP_EXT_H
41
42 #include "std_ext.h"
43 #include "error_ext.h"
44 #include "string_ext.h"
45 #include "debug_ext.h"
46
47 #include "fm_ext.h"
48
49
50 /**************************************************************************//**
51
52 @Group FM_grp Frame Manager API
53
54 @Description FM API functions, definitions and enums
55
56 @{
57 *//***************************************************************************/
58
59 /**************************************************************************//**
60 @Group FM_VSP_grp FM Virtual-Storage-Profile
61
62 @Description FM Virtual-Storage-Profile API
63
64 @{
65 *//***************************************************************************/
66
67 /**************************************************************************//**
68 @Group FM_VSP_init_grp FM VSP Initialization Unit
69
70 @Description FM VSP initialization API.
71
72 @{
73 *//***************************************************************************/
74
75 /**************************************************************************//**
76 @Description Virtual Storage Profile
77 *//***************************************************************************/
78 typedef struct t_FmVspParams {
79 t_Handle h_Fm; /**< A handle to the FM object this VSP related to */
80 t_FmExtPools extBufPools; /**< Which external buffer pools are used
81 (up to FM_PORT_MAX_NUM_OF_EXT_POOLS), and their sizes.
82 parameter associated with Rx / OP port */
83 uint16_t liodnOffset; /**< VSP's LIODN offset */
84 struct {
85 e_FmPortType portType; /**< Port type */
86 uint8_t portId; /**< Port Id - relative to type */
87 } portParams;
88 uint8_t relativeProfileId; /**< VSP Id - relative to VSP's range
89 defined in relevant FM object */
90 } t_FmVspParams;
91
92
93 /**************************************************************************//**
94 @Function FM_VSP_Config
95
96 @Description Creates descriptor for the FM VSP module.
97
98 The routine returns a handle (descriptor) to the FM VSP object.
99 This descriptor must be passed as first parameter to all other
100 FM VSP function calls.
101
102 No actual initialization or configuration of FM hardware is
103 done by this routine.
104
105 @Param[in] p_FmVspParams Pointer to data structure of parameters
106
107 @Retval Handle to FM VSP object, or NULL for Failure.
108 *//***************************************************************************/
109 t_Handle FM_VSP_Config(t_FmVspParams *p_FmVspParams);
110
111 /**************************************************************************//**
112 @Function FM_VSP_Init
113
114 @Description Initializes the FM VSP module
115
116 @Param[in] h_FmVsp - FM VSP module descriptor
117
118 @Return E_OK on success; Error code otherwise.
119 *//***************************************************************************/
120 t_Error FM_VSP_Init(t_Handle h_FmVsp);
121
122 /**************************************************************************//**
123 @Function FM_VSP_Free
124
125 @Description Frees all resources that were assigned to FM VSP module.
126
127 Calling this routine invalidates the descriptor.
128
129 @Param[in] h_FmVsp - FM VSP module descriptor
130
131 @Return E_OK on success; Error code otherwise.
132 *//***************************************************************************/
133 t_Error FM_VSP_Free(t_Handle h_FmVsp);
134
135
136 /**************************************************************************//**
137 @Group FM_VSP_adv_config_grp FM VSP Advanced Configuration Unit
138
139 @Description FM VSP advanced configuration functions.
140
141 @{
142 *//***************************************************************************/
143
144 /**************************************************************************//**
145 @Function FM_VSP_ConfigBufferPrefixContent
146
147 @Description Defines the structure, size and content of the application buffer.
148
149 The prefix will
150 In VSPs defined for Tx ports, if 'passPrsResult', the application
151 should set a value to their offsets in the prefix of
152 the FM will save the first 'privDataSize', than,
153 depending on 'passPrsResult' and 'passTimeStamp', copy parse result
154 and timeStamp, and the packet itself (in this order), to the
155 application buffer, and to offset.
156
157 Calling this routine changes the buffer margins definitions
158 in the internal driver data base from its default
159 configuration: Data size: [DEFAULT_FM_SP_bufferPrefixContent_privDataSize]
160 Pass Parser result: [DEFAULT_FM_SP_bufferPrefixContent_passPrsResult].
161 Pass timestamp: [DEFAULT_FM_SP_bufferPrefixContent_passTimeStamp].
162
163 @Param[in] h_FmVsp A handle to a FM VSP module.
164 @Param[in,out] p_FmBufferPrefixContent A structure of parameters describing the
165 structure of the buffer.
166 Out parameter: Start margin - offset
167 of data from start of external buffer.
168
169 @Return E_OK on success; Error code otherwise.
170
171 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
172 *//***************************************************************************/
173 t_Error FM_VSP_ConfigBufferPrefixContent(t_Handle h_FmVsp,
174 t_FmBufferPrefixContent *p_FmBufferPrefixContent);
175
176 /**************************************************************************//**
177 @Function FM_VSP_ConfigDmaSwapData
178
179 @Description Calling this routine changes the DMA swap data parameter
180 in the internal driver data base from its default
181 configuration [DEFAULT_FM_SP_dmaSwapData]
182
183 @Param[in] h_FmVsp A handle to a FM VSP module.
184 @Param[in] swapData New selection
185
186 @Return E_OK on success; Error code otherwise.
187
188 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
189 *//***************************************************************************/
190 t_Error FM_VSP_ConfigDmaSwapData(t_Handle h_FmVsp, e_FmDmaSwapOption swapData);
191
192 /**************************************************************************//**
193 @Function FM_VSP_ConfigDmaIcCacheAttr
194
195 @Description Calling this routine changes the internal context cache
196 attribute parameter in the internal driver data base
197 from its default configuration [DEFAULT_FM_SP_dmaIntContextCacheAttr]
198
199 @Param[in] h_FmVsp A handle to a FM VSP module.
200 @Param[in] intContextCacheAttr New selection
201
202 @Return E_OK on success; Error code otherwise.
203
204 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
205 *//***************************************************************************/
206 t_Error FM_VSP_ConfigDmaIcCacheAttr(t_Handle h_FmVsp,
207 e_FmDmaCacheOption intContextCacheAttr);
208
209 /**************************************************************************//**
210 @Function FM_VSP_ConfigDmaHdrAttr
211
212 @Description Calling this routine changes the header cache
213 attribute parameter in the internal driver data base
214 from its default configuration [DEFAULT_FM_SP_dmaHeaderCacheAttr]
215
216 @Param[in] h_FmVsp A handle to a FM VSP module.
217 @Param[in] headerCacheAttr New selection
218
219 @Return E_OK on success; Error code otherwise.
220
221 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
222 *//***************************************************************************/
223 t_Error FM_VSP_ConfigDmaHdrAttr(t_Handle h_FmVsp, e_FmDmaCacheOption headerCacheAttr);
224
225 /**************************************************************************//**
226 @Function FM_VSP_ConfigDmaScatterGatherAttr
227
228 @Description Calling this routine changes the scatter gather cache
229 attribute parameter in the internal driver data base
230 from its default configuration [DEFAULT_FM_SP_dmaScatterGatherCacheAttr]
231
232 @Param[in] h_FmVsp A handle to a FM VSP module.
233 @Param[in] scatterGatherCacheAttr New selection
234
235 @Return E_OK on success; Error code otherwise.
236
237 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
238 *//***************************************************************************/
239 t_Error FM_VSP_ConfigDmaScatterGatherAttr(t_Handle h_FmVsp,
240 e_FmDmaCacheOption scatterGatherCacheAttr);
241
242 /**************************************************************************//**
243 @Function FM_VSP_ConfigDmaWriteOptimize
244
245 @Description Calling this routine changes the write optimization
246 parameter in the internal driver data base
247 from its default configuration: optimize = [DEFAULT_FM_SP_dmaWriteOptimize]
248
249 @Param[in] h_FmVsp A handle to a FM VSP module.
250 @Param[in] optimize TRUE to enable optimization, FALSE for normal operation
251
252 @Return E_OK on success; Error code otherwise.
253
254 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
255 *//***************************************************************************/
256 t_Error FM_VSP_ConfigDmaWriteOptimize(t_Handle h_FmVsp, bool optimize);
257
258 /**************************************************************************//**
259 @Function FM_VSP_ConfigNoScatherGather
260
261 @Description Calling this routine changes the possibility to receive S/G frame
262 in the internal driver data base
263 from its default configuration: optimize = [DEFAULT_FM_SP_noScatherGather]
264
265 @Param[in] h_FmVsp A handle to a FM VSP module.
266 @Param[in] noScatherGather TRUE to operate without scatter/gather capability.
267
268 @Return E_OK on success; Error code otherwise.
269
270 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
271 *//***************************************************************************/
272 t_Error FM_VSP_ConfigNoScatherGather(t_Handle h_FmVsp, bool noScatherGather);
273
274 /**************************************************************************//**
275 @Function FM_VSP_ConfigPoolDepletion
276
277 @Description Calling this routine enables pause frame generation depending on the
278 depletion status of BM pools. It also defines the conditions to activate
279 this functionality. By default, this functionality is disabled.
280
281 @Param[in] h_FmVsp A handle to a FM VSP module.
282 @Param[in] p_BufPoolDepletion A structure of pool depletion parameters
283
284 @Return E_OK on success; Error code otherwise.
285
286 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
287 *//***************************************************************************/
288 t_Error FM_VSP_ConfigPoolDepletion(t_Handle h_FmVsp, t_FmBufPoolDepletion *p_BufPoolDepletion);
289
290 /**************************************************************************//**
291 @Function FM_VSP_ConfigBackupPools
292
293 @Description Calling this routine allows the configuration of some of the BM pools
294 defined for this port as backup pools.
295 A pool configured to be a backup pool will be used only if all other
296 enabled non-backup pools are depleted.
297
298 @Param[in] h_FmVsp A handle to a FM VSP module.
299 @Param[in] p_BackupBmPools An array of pool id's. All pools specified here will
300 be defined as backup pools.
301
302 @Return E_OK on success; Error code otherwise.
303
304 @Cautions Allowed only following FM_VSP_Config() and before FM_VSP_Init().
305 *//***************************************************************************/
306 t_Error FM_VSP_ConfigBackupPools(t_Handle h_FmVsp, t_FmBackupBmPools *p_BackupBmPools);
307
308 /** @} */ /* end of FM_VSP_adv_config_grp group */
309 /** @} */ /* end of FM_VSP_init_grp group */
310
311
312 /**************************************************************************//**
313 @Group FM_VSP_control_grp FM VSP Control Unit
314
315 @Description FM VSP runtime control API.
316
317 @{
318 *//***************************************************************************/
319
320 /**************************************************************************//**
321 @Function FM_VSP_GetBufferDataOffset
322
323 @Description Relevant for Rx ports.
324 Returns the data offset from the beginning of the data buffer
325
326 @Param[in] h_FmVsp - FM PORT module descriptor
327
328 @Return data offset.
329
330 @Cautions Allowed only following FM_VSP_Init().
331 *//***************************************************************************/
332 uint32_t FM_VSP_GetBufferDataOffset(t_Handle h_FmVsp);
333
334 /**************************************************************************//**
335 @Function FM_VSP_GetBufferICInfo
336
337 @Description Returns the Internal Context offset from the beginning of the data buffer
338
339 @Param[in] h_FmVsp - FM PORT module descriptor
340 @Param[in] p_Data - A pointer to the data buffer.
341
342 @Return Internal context info pointer on success, NULL if 'allOtherInfo' was not
343 configured for this port.
344
345 @Cautions Allowed only following FM_VSP_Init().
346 *//***************************************************************************/
347 uint8_t * FM_VSP_GetBufferICInfo(t_Handle h_FmVsp, char *p_Data);
348
349 /**************************************************************************//**
350 @Function FM_VSP_GetBufferPrsResult
351
352 @Description Returns the pointer to the parse result in the data buffer.
353 In Rx ports this is relevant after reception, if parse
354 result is configured to be part of the data passed to the
355 application. For non Rx ports it may be used to get the pointer
356 of the area in the buffer where parse result should be
357 initialized - if so configured.
358 See FM_VSP_ConfigBufferPrefixContent for data buffer prefix
359 configuration.
360
361 @Param[in] h_FmVsp - FM PORT module descriptor
362 @Param[in] p_Data - A pointer to the data buffer.
363
364 @Return Parse result pointer on success, NULL if parse result was not
365 configured for this port.
366
367 @Cautions Allowed only following FM_VSP_Init().
368 *//***************************************************************************/
369 t_FmPrsResult * FM_VSP_GetBufferPrsResult(t_Handle h_FmVsp, char *p_Data);
370
371 /**************************************************************************//**
372 @Function FM_VSP_GetBufferTimeStamp
373
374 @Description Returns the time stamp in the data buffer.
375 Relevant for Rx ports for getting the buffer time stamp.
376 See FM_VSP_ConfigBufferPrefixContent for data buffer prefix
377 configuration.
378
379 @Param[in] h_FmVsp - FM PORT module descriptor
380 @Param[in] p_Data - A pointer to the data buffer.
381
382 @Return A pointer to the hash result on success, NULL otherwise.
383
384 @Cautions Allowed only following FM_VSP_Init().
385 *//***************************************************************************/
386 uint64_t * FM_VSP_GetBufferTimeStamp(t_Handle h_FmVsp, char *p_Data);
387
388 /**************************************************************************//**
389 @Function FM_VSP_GetBufferHashResult
390
391 @Description Given a data buffer, on the condition that hash result was defined
392 as a part of the buffer content (see FM_VSP_ConfigBufferPrefixContent)
393 this routine will return the pointer to the hash result location in the
394 buffer prefix.
395
396 @Param[in] h_FmVsp - FM PORT module descriptor
397 @Param[in] p_Data - A pointer to the data buffer.
398
399 @Return A pointer to the hash result on success, NULL otherwise.
400
401 @Cautions Allowed only following FM_VSP_Init().
402 *//***************************************************************************/
403 uint8_t * FM_VSP_GetBufferHashResult(t_Handle h_FmVsp, char *p_Data);
404
405
406 /** @} */ /* end of FM_VSP_control_grp group */
407 /** @} */ /* end of FM_VSP_grp group */
408 /** @} */ /* end of FM_grp group */
409
410
411 #endif /* __FM_VSP_EXT_H */
Cache object: 8508f7ba0059c40dba95dc65b554ee34
|