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