kernel/drivers/staging/fsl-mc/include/dpbp.h

   1 /* Copyright 2013-2015 Freescale Semiconductor Inc.
   2  *
   3  * Redistribution and use in source and binary forms, with or without
   4  * modification, are permitted provided that the following conditions are met:
   5  * * Redistributions of source code must retain the above copyright
   6  * notice, this list of conditions and the following disclaimer.
   7  * * Redistributions in binary form must reproduce the above copyright
   8  * notice, this list of conditions and the following disclaimer in the
   9  * documentation and/or other materials provided with the distribution.
  10  * * Neither the name of the above-listed copyright holders nor the
  11  * names of any contributors may be used to endorse or promote products
  12  * derived from this software without specific prior written permission.
  13  *
  14  *
  15  * ALTERNATIVELY, this software may be distributed under the terms of the
  16  * GNU General Public License ("GPL") as published by the Free Software
  17  * Foundation, either version 2 of that License or (at your option) any
  18  * later version.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
  24  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  25  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  26  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  29  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  30  * POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 #ifndef __FSL_DPBP_H
  33 #define __FSL_DPBP_H
  34
  35 /* Data Path Buffer Pool API
  36  * Contains initialization APIs and runtime control APIs for DPBP
  37  */
  38
  39 struct fsl_mc_io;
  40
  41 /**
  42  * dpbp_open() - Open a control session for the specified object.
  43  * @mc_io:      Pointer to MC portal's I/O object
  44  * @dpbp_id:    DPBP unique ID
  45  * @token:      Returned token; use in subsequent API calls
  46  *
  47  * This function can be used to open a control session for an
  48  * already created object; an object may have been declared in
  49  * the DPL or by calling the dpbp_create function.
  50  * This function returns a unique authentication token,
  51  * associated with the specific object ID and the specific MC
  52  * portal; this token must be used in all subsequent commands for
  53  * this specific object
  54  *
  55  * Return:      '0' on Success; Error code otherwise.
  56  */
  57 int dpbp_open(struct fsl_mc_io *mc_io, int dpbp_id, uint16_t *token);
  58
  59 /**
  60  * dpbp_close() - Close the control session of the object
  61  * @mc_io:      Pointer to MC portal's I/O object
  62  * @token:      Token of DPBP object
  63  *
  64  * After this function is called, no further operations are
  65  * allowed on the object without opening a new control session.
  66  *
  67  * Return:      '0' on Success; Error code otherwise.
  68  */
  69 int dpbp_close(struct fsl_mc_io *mc_io, uint16_t token);
  70
  71 /**
  72  * struct dpbp_cfg() - Structure representing DPBP configuration
  73  * @options:    place holder
  74  */
  75 struct dpbp_cfg {
  76         uint32_t options;
  77 };
  78
  79 /**
  80  * dpbp_create() - Create the DPBP object.
  81  * @mc_io:      Pointer to MC portal's I/O object
  82  * @cfg:        Configuration structure
  83  * @token:      Returned token; use in subsequent API calls
  84  *
  85  * Create the DPBP object, allocate required resources and
  86  * perform required initialization.
  87  *
  88  * The object can be created either by declaring it in the
  89  * DPL file, or by calling this function.
  90  * This function returns a unique authentication token,
  91  * associated with the specific object ID and the specific MC
  92  * portal; this token must be used in all subsequent calls to
  93  * this specific object. For objects that are created using the
  94  * DPL file, call dpbp_open function to get an authentication
  95  * token first.
  96  *
  97  * Return:      '0' on Success; Error code otherwise.
  98  */
  99 int dpbp_create(struct fsl_mc_io        *mc_io,
 100                 const struct dpbp_cfg   *cfg,
 101                 uint16_t                *token);
 102
 103 /**
 104  * dpbp_destroy() - Destroy the DPBP object and release all its resources.
 105  * @mc_io:      Pointer to MC portal's I/O object
 106  * @token:      Token of DPBP object
 107  *
 108  * Return:      '0' on Success; error code otherwise.
 109  */
 110 int dpbp_destroy(struct fsl_mc_io *mc_io, uint16_t token);
 111
 112 /**
 113  * dpbp_enable() - Enable the DPBP.
 114  * @mc_io:      Pointer to MC portal's I/O object
 115  * @token:      Token of DPBP object
 116  *
 117  * Return:      '0' on Success; Error code otherwise.
 118  */
 119 int dpbp_enable(struct fsl_mc_io *mc_io, uint16_t token);
 120
 121 /**
 122  * dpbp_disable() - Disable the DPBP.
 123  * @mc_io:      Pointer to MC portal's I/O object
 124  * @token:      Token of DPBP object
 125  *
 126  * Return:      '0' on Success; Error code otherwise.
 127  */
 128 int dpbp_disable(struct fsl_mc_io *mc_io, uint16_t token);
 129
 130 /**
 131  * dpbp_is_enabled() - Check if the DPBP is enabled.
 132  * @mc_io:      Pointer to MC portal's I/O object
 133  * @token:      Token of DPBP object
 134  * @en:         Returns '1' if object is enabled; '0' otherwise
 135  *
 136  * Return:      '0' on Success; Error code otherwise.
 137  */
 138 int dpbp_is_enabled(struct fsl_mc_io *mc_io, uint16_t token, int *en);
 139
 140 /**
 141  * dpbp_reset() - Reset the DPBP, returns the object to initial state.
 142  * @mc_io:      Pointer to MC portal's I/O object
 143  * @token:      Token of DPBP object
 144  *
 145  * Return:      '0' on Success; Error code otherwise.
 146  */
 147 int dpbp_reset(struct fsl_mc_io *mc_io, uint16_t token);
 148
 149 /**
 150  * dpbp_set_irq() - Set IRQ information for the DPBP to trigger an interrupt.
 151  * @mc_io:      Pointer to MC portal's I/O object
 152  * @token:      Token of DPBP object
 153  * @irq_index:  Identifies the interrupt index to configure
 154  * @irq_addr:   Address that must be written to
 155  *                              signal a message-based interrupt
 156  * @irq_val:    Value to write into irq_addr address
 157  * @user_irq_id: A user defined number associated with this IRQ
 158  *
 159  * Return:      '0' on Success; Error code otherwise.
 160  */
 161 int dpbp_set_irq(struct fsl_mc_io       *mc_io,
 162                  uint16_t               token,
 163                  uint8_t                irq_index,
 164                  uint64_t               irq_addr,
 165                  uint32_t               irq_val,
 166                  int                    user_irq_id);
 167
 168 /**
 169  * dpbp_get_irq() - Get IRQ information from the DPBP.
 170  * @mc_io:      Pointer to MC portal's I/O object
 171  * @token:      Token of DPBP object
 172  * @irq_index:  The interrupt index to configure
 173  * @type:       Interrupt type: 0 represents message interrupt
 174  *                              type (both irq_addr and irq_val are valid)
 175  * @irq_addr:   Returned address that must be written to
 176  *                              signal the message-based interrupt
 177  * @irq_val:    Value to write into irq_addr address
 178  * @user_irq_id: A user defined number associated with this IRQ
 179  *
 180  * Return:      '0' on Success; Error code otherwise.
 181  */
 182 int dpbp_get_irq(struct fsl_mc_io       *mc_io,
 183                  uint16_t               token,
 184                  uint8_t                irq_index,
 185                  int                    *type,
 186                  uint64_t               *irq_addr,
 187                  uint32_t               *irq_val,
 188                  int                    *user_irq_id);
 189
 190 /**
 191  * dpbp_set_irq_enable() - Set overall interrupt state.
 192  * @mc_io:      Pointer to MC portal's I/O object
 193  * @token:      Token of DPBP object
 194  * @irq_index:  The interrupt index to configure
 195  * @en: Interrupt state - enable = 1, disable = 0
 196  *
 197  * Allows GPP software to control when interrupts are generated.
 198  * Each interrupt can have up to 32 causes.  The enable/disable control's the
 199  * overall interrupt state. if the interrupt is disabled no causes will cause
 200  * an interrupt.
 201  *
 202  * Return:      '0' on Success; Error code otherwise.
 203  */
 204 int dpbp_set_irq_enable(struct fsl_mc_io        *mc_io,
 205                         uint16_t                token,
 206                         uint8_t                 irq_index,
 207                         uint8_t                 en);
 208
 209 /**
 210  * dpbp_get_irq_enable() - Get overall interrupt state
 211  * @mc_io:      Pointer to MC portal's I/O object
 212  * @token:      Token of DPBP object
 213  * @irq_index:  The interrupt index to configure
 214  * @en:         Returned interrupt state - enable = 1, disable = 0
 215  *
 216  * Return:      '0' on Success; Error code otherwise.
 217  */
 218 int dpbp_get_irq_enable(struct fsl_mc_io        *mc_io,
 219                         uint16_t                token,
 220                         uint8_t                 irq_index,
 221                         uint8_t                 *en);
 222
 223 /**
 224  * dpbp_set_irq_mask() - Set interrupt mask.
 225  * @mc_io:      Pointer to MC portal's I/O object
 226  * @token:      Token of DPBP object
 227  * @irq_index:  The interrupt index to configure
 228  * @mask:       Event mask to trigger interrupt;
 229  *                      each bit:
 230  *                              0 = ignore event
 231  *                              1 = consider event for asserting IRQ
 232  *
 233  * Every interrupt can have up to 32 causes and the interrupt model supports
 234  * masking/unmasking each cause independently
 235  *
 236  * Return:      '0' on Success; Error code otherwise.
 237  */
 238 int dpbp_set_irq_mask(struct fsl_mc_io  *mc_io,
 239                       uint16_t          token,
 240                       uint8_t           irq_index,
 241                       uint32_t          mask);
 242
 243 /**
 244  * dpbp_get_irq_mask() - Get interrupt mask.
 245  * @mc_io:      Pointer to MC portal's I/O object
 246  * @token:      Token of DPBP object
 247  * @irq_index:  The interrupt index to configure
 248  * @mask:       Returned event mask to trigger interrupt
 249  *
 250  * Every interrupt can have up to 32 causes and the interrupt model supports
 251  * masking/unmasking each cause independently
 252  *
 253  * Return:      '0' on Success; Error code otherwise.
 254  */
 255 int dpbp_get_irq_mask(struct fsl_mc_io  *mc_io,
 256                       uint16_t          token,
 257                       uint8_t           irq_index,
 258                       uint32_t          *mask);
 259
 260 /**
 261  * dpbp_get_irq_status() - Get the current status of any pending interrupts.
 262  *
 263  * @mc_io:      Pointer to MC portal's I/O object
 264  * @token:      Token of DPBP object
 265  * @irq_index:  The interrupt index to configure
 266  * @status:     Returned interrupts status - one bit per cause:
 267  *                      0 = no interrupt pending
 268  *                      1 = interrupt pending
 269  *
 270  * Return:      '0' on Success; Error code otherwise.
 271  */
 272 int dpbp_get_irq_status(struct fsl_mc_io        *mc_io,
 273                         uint16_t                token,
 274                         uint8_t                 irq_index,
 275                         uint32_t                *status);
 276
 277 /**
 278  * dpbp_clear_irq_status() - Clear a pending interrupt's status
 279  *
 280  * @mc_io:      Pointer to MC portal's I/O object
 281  * @token:      Token of DPBP object
 282  * @irq_index:  The interrupt index to configure
 283  * @status:     Bits to clear (W1C) - one bit per cause:
 284  *                                      0 = don't change
 285  *                                      1 = clear status bit
 286  *
 287  * Return:      '0' on Success; Error code otherwise.
 288  */
 289 int dpbp_clear_irq_status(struct fsl_mc_io      *mc_io,
 290                           uint16_t              token,
 291                           uint8_t               irq_index,
 292                           uint32_t              status);
 293
 294 /**
 295  * struct dpbp_attr - Structure representing DPBP attributes
 296  * @id:         DPBP object ID
 297  * @version:    DPBP version
 298  * @bpid:       Hardware buffer pool ID; should be used as an argument in
 299  *              acquire/release operations on buffers
 300  */
 301 struct dpbp_attr {
 302         int id;
 303         /**
 304          * struct version - Structure representing DPBP version
 305          * @major:      DPBP major version
 306          * @minor:      DPBP minor version
 307          */
 308         struct {
 309                 uint16_t major;
 310                 uint16_t minor;
 311         } version;
 312         uint16_t bpid;
 313 };
 314
 315 /**
 316  * dpbp_get_attributes - Retrieve DPBP attributes.
 317  *
 318  * @mc_io:      Pointer to MC portal's I/O object
 319  * @token:      Token of DPBP object
 320  * @attr:       Returned object's attributes
 321  *
 322  * Return:      '0' on Success; Error code otherwise.
 323  */
 324 int dpbp_get_attributes(struct fsl_mc_io        *mc_io,
 325                         uint16_t                token,
 326                         struct dpbp_attr        *attr);
 327
 328 /** @} */
 329
 330 #endif /* __FSL_DPBP_H */