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*//***************************************************************************/
78typedef 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*//***************************************************************************/
109t_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*//***************************************************************************/
120t_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*//***************************************************************************/
133t_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*//***************************************************************************/
173t_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*//***************************************************************************/
190t_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*//***************************************************************************/
206t_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*//***************************************************************************/
223t_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*//***************************************************************************/
239t_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*//***************************************************************************/
256t_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*//***************************************************************************/
272t_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*//***************************************************************************/
288t_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*//***************************************************************************/
306t_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*//***************************************************************************/
332uint32_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*//***************************************************************************/
347uint8_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*//***************************************************************************/
369t_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*//***************************************************************************/
386uint64_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*//***************************************************************************/
403uint8_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 */
412