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 */ 412