fm_vsp_ext.h

/*
 * Copyright 2008-2012 Freescale Semiconductor Inc.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of Freescale Semiconductor nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 *
 * ALTERNATIVELY, this software may be distributed under the terms of the
 * GNU General Public License ("GPL") as published by the Free Software
 * Foundation, either version 2 of that License or (at your option) any
 * later version.
 *
 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */


/**************************************************************************//**
 @File          fm_vsp_ext.h

 @Description   FM Virtual Storage-Profile ...
*//***************************************************************************/
#ifndef __FM_VSP_EXT_H
#define __FM_VSP_EXT_H

#include "std_ext.h"
#include "error_ext.h"
#include "string_ext.h"
#include "debug_ext.h"

#include "fm_ext.h"


/**************************************************************************//**

 @Group         FM_grp Frame Manager API

 @Description   FM API functions, definitions and enums

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Group         FM_VSP_grp FM Virtual-Storage-Profile

 @Description   FM Virtual-Storage-Profile API

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Group         FM_VSP_init_grp FM VSP Initialization Unit

 @Description   FM VSP initialization API.

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Description   Virtual Storage Profile
*//***************************************************************************/
typedef struct t_FmVspParams {
    t_Handle            h_Fm;               /**< A handle to the FM object this VSP related to */
    t_FmExtPools        extBufPools;        /**< Which external buffer pools are used
                                                 (up to FM_PORT_MAX_NUM_OF_EXT_POOLS), and their sizes.
                                                 parameter associated with Rx / OP port */
    uint16_t            liodnOffset;        /**< VSP's LIODN offset */
    struct {
        e_FmPortType    portType;           /**< Port type */
        uint8_t         portId;             /**< Port Id - relative to type */
    } portParams;
    uint8_t             relativeProfileId;  /**< VSP Id - relative to VSP's range
                                                 defined in relevant FM object */
} t_FmVspParams;


/**************************************************************************//**
 @Function      FM_VSP_Config

 @Description   Creates descriptor for the FM VSP module.

                The routine returns a handle (descriptor) to the FM VSP object.
                This descriptor must be passed as first parameter to all other
                FM VSP function calls.

                No actual initialization or configuration of FM hardware is
                done by this routine.

@Param[in]      p_FmVspParams   Pointer to data structure of parameters

 @Retval        Handle to FM VSP object, or NULL for Failure.
*//***************************************************************************/
t_Handle FM_VSP_Config(t_FmVspParams *p_FmVspParams);

/**************************************************************************//**
 @Function      FM_VSP_Init

 @Description   Initializes the FM VSP module

 @Param[in]     h_FmVsp - FM VSP module descriptor

 @Return        E_OK on success; Error code otherwise.
*//***************************************************************************/
t_Error FM_VSP_Init(t_Handle h_FmVsp);

/**************************************************************************//**
 @Function      FM_VSP_Free

 @Description   Frees all resources that were assigned to FM VSP module.

                Calling this routine invalidates the descriptor.

 @Param[in]     h_FmVsp - FM VSP module descriptor

 @Return        E_OK on success; Error code otherwise.
*//***************************************************************************/
t_Error FM_VSP_Free(t_Handle h_FmVsp);


/**************************************************************************//**
 @Group         FM_VSP_adv_config_grp  FM VSP Advanced Configuration Unit

 @Description   FM VSP advanced configuration functions.

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Function      FM_VSP_ConfigBufferPrefixContent

 @Description   Defines the structure, size and content of the application buffer.

                The prefix will
                In VSPs defined for Tx ports, if 'passPrsResult', the application
                should set a value to their offsets in the prefix of
                the FM will save the first 'privDataSize', than,
                depending on 'passPrsResult' and 'passTimeStamp', copy parse result
                and timeStamp, and the packet itself (in this order), to the
                application buffer, and to offset.

                Calling this routine changes the buffer margins definitions
                in the internal driver data base from its default
                configuration: Data size:  [DEFAULT_FM_SP_bufferPrefixContent_privDataSize]
                               Pass Parser result: [DEFAULT_FM_SP_bufferPrefixContent_passPrsResult].
                               Pass timestamp: [DEFAULT_FM_SP_bufferPrefixContent_passTimeStamp].

 @Param[in]     h_FmVsp                         A handle to a FM VSP module.
 @Param[in,out] p_FmBufferPrefixContent         A structure of parameters describing the
                                                structure of the buffer.
                                                Out parameter: Start margin - offset
                                                of data from start of external buffer.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigBufferPrefixContent(t_Handle                   h_FmVsp,
                                         t_FmBufferPrefixContent    *p_FmBufferPrefixContent);

/**************************************************************************//**
 @Function      FM_VSP_ConfigDmaSwapData

 @Description   Calling this routine changes the DMA swap data parameter
                in the internal driver data base from its default
                configuration  [DEFAULT_FM_SP_dmaSwapData]

 @Param[in]     h_FmVsp     A handle to a FM VSP module.
 @Param[in]     swapData    New selection

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigDmaSwapData(t_Handle h_FmVsp, e_FmDmaSwapOption swapData);

/**************************************************************************//**
 @Function      FM_VSP_ConfigDmaIcCacheAttr

 @Description   Calling this routine changes the internal context cache
                attribute parameter in the internal driver data base
                from its default configuration  [DEFAULT_FM_SP_dmaIntContextCacheAttr]

 @Param[in]     h_FmVsp                 A handle to a FM VSP module.
 @Param[in]     intContextCacheAttr     New selection

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigDmaIcCacheAttr(t_Handle            h_FmVsp,
                                    e_FmDmaCacheOption  intContextCacheAttr);

/**************************************************************************//**
 @Function      FM_VSP_ConfigDmaHdrAttr

 @Description   Calling this routine changes the header cache
                attribute parameter in the internal driver data base
                from its default configuration  [DEFAULT_FM_SP_dmaHeaderCacheAttr]

 @Param[in]     h_FmVsp                     A handle to a FM VSP module.
 @Param[in]     headerCacheAttr             New selection

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigDmaHdrAttr(t_Handle h_FmVsp, e_FmDmaCacheOption headerCacheAttr);

/**************************************************************************//**
 @Function      FM_VSP_ConfigDmaScatterGatherAttr

 @Description   Calling this routine changes the scatter gather cache
                attribute parameter in the internal driver data base
                from its default configuration [DEFAULT_FM_SP_dmaScatterGatherCacheAttr]

 @Param[in]     h_FmVsp                     A handle to a FM VSP module.
 @Param[in]     scatterGatherCacheAttr      New selection

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigDmaScatterGatherAttr(t_Handle              h_FmVsp,
                                          e_FmDmaCacheOption    scatterGatherCacheAttr);

/**************************************************************************//**
 @Function      FM_VSP_ConfigDmaWriteOptimize

 @Description   Calling this routine changes the write optimization
                parameter in the internal driver data base
                from its default configuration: optimize = [DEFAULT_FM_SP_dmaWriteOptimize]

 @Param[in]     h_FmVsp     A handle to a FM VSP module.
 @Param[in]     optimize    TRUE to enable optimization, FALSE for normal operation

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigDmaWriteOptimize(t_Handle h_FmVsp, bool optimize);

/**************************************************************************//**
 @Function      FM_VSP_ConfigNoScatherGather

 @Description   Calling this routine changes the possibility to receive S/G frame
                in the internal driver data base
                from its default configuration: optimize = [DEFAULT_FM_SP_noScatherGather]

 @Param[in]     h_FmVsp             A handle to a FM VSP module.
 @Param[in]     noScatherGather     TRUE to operate without scatter/gather capability.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigNoScatherGather(t_Handle h_FmVsp, bool noScatherGather);

/**************************************************************************//**
 @Function      FM_VSP_ConfigPoolDepletion

 @Description   Calling this routine enables pause frame generation depending on the
                depletion status of BM pools. It also defines the conditions to activate
                this functionality. By default, this functionality is disabled.

 @Param[in]     h_FmVsp                 A handle to a FM VSP module.
 @Param[in]     p_BufPoolDepletion      A structure of pool depletion parameters

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigPoolDepletion(t_Handle h_FmVsp, t_FmBufPoolDepletion *p_BufPoolDepletion);

/**************************************************************************//**
 @Function      FM_VSP_ConfigBackupPools

 @Description   Calling this routine allows the configuration of some of the BM pools
                defined for this port as backup pools.
                A pool configured to be a backup pool will be used only if all other
                enabled non-backup pools are depleted.

 @Param[in]     h_FmVsp                 A handle to a FM VSP module.
 @Param[in]     p_BackupBmPools         An array of pool id's. All pools specified here will
                                        be defined as backup pools.

 @Return        E_OK on success; Error code otherwise.

 @Cautions      Allowed only following FM_VSP_Config() and before FM_VSP_Init().
*//***************************************************************************/
t_Error FM_VSP_ConfigBackupPools(t_Handle h_FmVsp, t_FmBackupBmPools *p_BackupBmPools);

/** @} */ /* end of FM_VSP_adv_config_grp group */
/** @} */ /* end of FM_VSP_init_grp group */


/**************************************************************************//**
 @Group         FM_VSP_control_grp FM VSP Control Unit

 @Description   FM VSP runtime control API.

 @{
*//***************************************************************************/

/**************************************************************************//**
 @Function      FM_VSP_GetBufferDataOffset

 @Description   Relevant for Rx ports.
                Returns the data offset from the beginning of the data buffer

 @Param[in]     h_FmVsp - FM PORT module descriptor

 @Return        data offset.

 @Cautions      Allowed only following FM_VSP_Init().
*//***************************************************************************/
uint32_t FM_VSP_GetBufferDataOffset(t_Handle h_FmVsp);

/**************************************************************************//**
 @Function      FM_VSP_GetBufferICInfo

 @Description   Returns the Internal Context offset from the beginning of the data buffer

 @Param[in]     h_FmVsp - FM PORT module descriptor
 @Param[in]     p_Data   - A pointer to the data buffer.

 @Return        Internal context info pointer on success, NULL if 'allOtherInfo' was not
                configured for this port.

 @Cautions      Allowed only following FM_VSP_Init().
*//***************************************************************************/
uint8_t * FM_VSP_GetBufferICInfo(t_Handle h_FmVsp, char *p_Data);

/**************************************************************************//**
 @Function      FM_VSP_GetBufferPrsResult

 @Description   Returns the pointer to the parse result in the data buffer.
                In Rx ports this is relevant after reception, if parse
                result is configured to be part of the data passed to the
                application. For non Rx ports it may be used to get the pointer
                of the area in the buffer where parse result should be
                initialized - if so configured.
                See FM_VSP_ConfigBufferPrefixContent for data buffer prefix
                configuration.

 @Param[in]     h_FmVsp    - FM PORT module descriptor
 @Param[in]     p_Data      - A pointer to the data buffer.

 @Return        Parse result pointer on success, NULL if parse result was not
                configured for this port.

 @Cautions      Allowed only following FM_VSP_Init().
*//***************************************************************************/
t_FmPrsResult * FM_VSP_GetBufferPrsResult(t_Handle h_FmVsp, char *p_Data);

/**************************************************************************//**
 @Function      FM_VSP_GetBufferTimeStamp

 @Description   Returns the time stamp in the data buffer.
                Relevant for Rx ports for getting the buffer time stamp.
                See FM_VSP_ConfigBufferPrefixContent for data buffer prefix
                configuration.

 @Param[in]     h_FmVsp    - FM PORT module descriptor
 @Param[in]     p_Data      - A pointer to the data buffer.

 @Return        A pointer to the hash result on success, NULL otherwise.

 @Cautions      Allowed only following FM_VSP_Init().
*//***************************************************************************/
uint64_t * FM_VSP_GetBufferTimeStamp(t_Handle h_FmVsp, char *p_Data);

/**************************************************************************//**
 @Function      FM_VSP_GetBufferHashResult

 @Description   Given a data buffer, on the condition that hash result was defined
                as a part of the buffer content (see FM_VSP_ConfigBufferPrefixContent)
                this routine will return the pointer to the hash result location in the
                buffer prefix.

 @Param[in]     h_FmVsp    - FM PORT module descriptor
 @Param[in]     p_Data      - A pointer to the data buffer.

 @Return        A pointer to the hash result on success, NULL otherwise.

 @Cautions      Allowed only following FM_VSP_Init().
*//***************************************************************************/
uint8_t * FM_VSP_GetBufferHashResult(t_Handle h_FmVsp, char *p_Data);


/** @} */ /* end of FM_VSP_control_grp group */
/** @} */ /* end of FM_VSP_grp group */
/** @} */ /* end of FM_grp group */


#endif /* __FM_VSP_EXT_H */