drivers/bus/fslmc/mc/fsl_dpbp.h

   1 /*-
   2  * This file is provided under a dual BSD/GPLv2 license. When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  *   BSD LICENSE
   6  *
   7  * Copyright 2013-2016 Freescale Semiconductor Inc.
   8  * Copyright 2016 NXP.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions are met:
  12  * * Redistributions of source code must retain the above copyright
  13  * notice, this list of conditions and the following disclaimer.
  14  * * Redistributions in binary form must reproduce the above copyright
  15  * notice, this list of conditions and the following disclaimer in the
  16  * documentation and/or other materials provided with the distribution.
  17  * * Neither the name of the above-listed copyright holders nor the
  18  * names of any contributors may be used to endorse or promote products
  19  * derived from this software without specific prior written permission.
  20  *
  21  *   GPL LICENSE SUMMARY
  22  *
  23  * ALTERNATIVELY, this software may be distributed under the terms of the
  24  * GNU General Public License ("GPL") as published by the Free Software
  25  * Foundation, either version 2 of that License or (at your option) any
  26  * later version.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  29  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  30  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  31  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
  32  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  34  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  35  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  36  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  37  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  38  * POSSIBILITY OF SUCH DAMAGE.
  39  */
  40 #ifndef __FSL_DPBP_H
  41 #define __FSL_DPBP_H
  42
  43 /* Data Path Buffer Pool API
  44  * Contains initialization APIs and runtime control APIs for DPBP
  45  */
  46
  47 struct fsl_mc_io;
  48
  49 /**
  50  * dpbp_open() - Open a control session for the specified object.
  51  * @mc_io:      Pointer to MC portal's I/O object
  52  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
  53  * @dpbp_id:    DPBP unique ID
  54  * @token:      Returned token; use in subsequent API calls
  55  *
  56  * This function can be used to open a control session for an
  57  * already created object; an object may have been declared in
  58  * the DPL or by calling the dpbp_create function.
  59  * This function returns a unique authentication token,
  60  * associated with the specific object ID and the specific MC
  61  * portal; this token must be used in all subsequent commands for
  62  * this specific object
  63  *
  64  * Return:      '0' on Success; Error code otherwise.
  65  */
  66 int dpbp_open(struct fsl_mc_io  *mc_io,
  67               uint32_t          cmd_flags,
  68               int               dpbp_id,
  69               uint16_t          *token);
  70
  71 /**
  72  * dpbp_close() - Close the control session of the object
  73  * @mc_io:      Pointer to MC portal's I/O object
  74  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
  75  * @token:      Token of DPBP object
  76  *
  77  * After this function is called, no further operations are
  78  * allowed on the object without opening a new control session.
  79  *
  80  * Return:      '0' on Success; Error code otherwise.
  81  */
  82 int dpbp_close(struct fsl_mc_io *mc_io,
  83                uint32_t         cmd_flags,
  84                uint16_t         token);
  85
  86 /**
  87  * struct dpbp_cfg - Structure representing DPBP configuration
  88  * @options:    place holder
  89  */
  90 struct dpbp_cfg {
  91         uint32_t options;
  92 };
  93
  94 /**
  95  * dpbp_create() - Create the DPBP object.
  96  * @mc_io:      Pointer to MC portal's I/O object
  97  * @dprc_token: Parent container token; '0' for default container
  98  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
  99  * @cfg:        Configuration structure
 100  * @obj_id: returned object id
 101  *
 102  * Create the DPBP object, allocate required resources and
 103  * perform required initialization.
 104  *
 105  * The object can be created either by declaring it in the
 106  * DPL file, or by calling this function.
 107  *
 108  * The function accepts an authentication token of a parent
 109  * container that this object should be assigned to. The token
 110  * can be '0' so the object will be assigned to the default container.
 111  * The newly created object can be opened with the returned
 112  * object id and using the container's associated tokens and MC portals.
 113  *
 114  * Return:      '0' on Success; Error code otherwise.
 115  */
 116 int dpbp_create(struct fsl_mc_io        *mc_io,
 117                 uint16_t                dprc_token,
 118                 uint32_t                cmd_flags,
 119                 const struct dpbp_cfg   *cfg,
 120                 uint32_t                *obj_id);
 121
 122 /**
 123  * dpbp_destroy() - Destroy the DPBP object and release all its resources.
 124  * @dprc_token: Parent container token; '0' for default container
 125  * @mc_io:      Pointer to MC portal's I/O object
 126  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 127  * @object_id:  The object id; it must be a valid id within the container that
 128  * created this object;
 129  *
 130  * Return:      '0' on Success; error code otherwise.
 131  */
 132 int dpbp_destroy(struct fsl_mc_io       *mc_io,
 133                  uint16_t               dprc_token,
 134                  uint32_t               cmd_flags,
 135                  uint32_t               object_id);
 136
 137 /**
 138  * dpbp_enable() - Enable the DPBP.
 139  * @mc_io:      Pointer to MC portal's I/O object
 140  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 141  * @token:      Token of DPBP object
 142  *
 143  * Return:      '0' on Success; Error code otherwise.
 144  */
 145 int dpbp_enable(struct fsl_mc_io        *mc_io,
 146                 uint32_t                cmd_flags,
 147                 uint16_t                token);
 148
 149 /**
 150  * dpbp_disable() - Disable the DPBP.
 151  * @mc_io:      Pointer to MC portal's I/O object
 152  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 153  * @token:      Token of DPBP object
 154  *
 155  * Return:      '0' on Success; Error code otherwise.
 156  */
 157 int dpbp_disable(struct fsl_mc_io       *mc_io,
 158                  uint32_t               cmd_flags,
 159                  uint16_t               token);
 160
 161 /**
 162  * dpbp_is_enabled() - Check if the DPBP is enabled.
 163  * @mc_io:      Pointer to MC portal's I/O object
 164  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 165  * @token:      Token of DPBP object
 166  * @en:         Returns '1' if object is enabled; '0' otherwise
 167  *
 168  * Return:      '0' on Success; Error code otherwise.
 169  */
 170 int dpbp_is_enabled(struct fsl_mc_io    *mc_io,
 171                     uint32_t            cmd_flags,
 172                     uint16_t            token,
 173                     int                 *en);
 174
 175 /**
 176  * dpbp_reset() - Reset the DPBP, returns the object to initial state.
 177  * @mc_io:      Pointer to MC portal's I/O object
 178  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 179  * @token:      Token of DPBP object
 180  *
 181  * Return:      '0' on Success; Error code otherwise.
 182  */
 183 int dpbp_reset(struct fsl_mc_io *mc_io,
 184                uint32_t         cmd_flags,
 185                uint16_t         token);
 186
 187 /**
 188  * struct dpbp_attr - Structure representing DPBP attributes
 189  * @id:         DPBP object ID
 190  * @bpid:       Hardware buffer pool ID; should be used as an argument in
 191  *              acquire/release operations on buffers
 192  */
 193 struct dpbp_attr {
 194         int id;
 195         uint16_t bpid;
 196 };
 197
 198 /**
 199  * dpbp_get_attributes - Retrieve DPBP attributes.
 200  *
 201  * @mc_io:      Pointer to MC portal's I/O object
 202  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 203  * @token:      Token of DPBP object
 204  * @attr:       Returned object's attributes
 205  *
 206  * Return:      '0' on Success; Error code otherwise.
 207  */
 208 int dpbp_get_attributes(struct fsl_mc_io        *mc_io,
 209                         uint32_t                cmd_flags,
 210                         uint16_t                token,
 211                         struct dpbp_attr        *attr);
 212
 213 /**
 214  * dpbp_get_api_version() - Get buffer pool API version
 215  * @mc_io:  Pointer to MC portal's I/O object
 216  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 217  * @major_ver:  Major version of data path buffer pool API
 218  * @minor_ver:  Minor version of data path buffer pool API
 219  *
 220  * Return:  '0' on Success; Error code otherwise.
 221  */
 222 int dpbp_get_api_version(struct fsl_mc_io *mc_io,
 223                          uint32_t cmd_flags,
 224                          uint16_t *major_ver,
 225                          uint16_t *minor_ver);
 226
 227 /**
 228  * dpbp_get_num_free_bufs() - Get number of free buffers in the buffer pool
 229  * @mc_io:  Pointer to MC portal's I/O object
 230  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 231  * @token:      Token of DPBP object
 232  * @num_free_bufs:      Number of free buffers
 233  *
 234  * Return:  '0' on Success; Error code otherwise.
 235  */
 236 int dpbp_get_num_free_bufs(struct fsl_mc_io *mc_io,
 237                            uint32_t cmd_flags,
 238                            uint16_t token,
 239                            uint32_t *num_free_bufs);
 240
 241 #endif /* __FSL_DPBP_H */