drivers/bus/fslmc/mc/fsl_dpio.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 (c) 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_DPIO_H
  41 #define __FSL_DPIO_H
  42
  43 /* Data Path I/O Portal API
  44  * Contains initialization APIs and runtime control APIs for DPIO
  45  */
  46
  47 struct fsl_mc_io;
  48
  49 /**
  50  * dpio_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  * @dpio_id:    DPIO 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 dpio_create() function.
  59  * This function returns a unique authentication token,
  60  * associated with the specific object ID and any MC portals
  61  * assigned to the parent container; this token must be used in
  62  * all subsequent commands for this specific object.
  63  *
  64  * Return:      '0' on Success; Error code otherwise.
  65  */
  66 int dpio_open(struct fsl_mc_io  *mc_io,
  67               uint32_t          cmd_flags,
  68               int               dpio_id,
  69               uint16_t          *token);
  70
  71 /**
  72  * dpio_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 DPIO object
  76  *
  77  * Return:      '0' on Success; Error code otherwise.
  78  */
  79 int dpio_close(struct fsl_mc_io *mc_io,
  80                uint32_t         cmd_flags,
  81                uint16_t         token);
  82
  83 /**
  84  * enum dpio_channel_mode - DPIO notification channel mode
  85  * @DPIO_NO_CHANNEL: No support for notification channel
  86  * @DPIO_LOCAL_CHANNEL: Notifications on data availability can be received by a
  87  *      dedicated channel in the DPIO; user should point the queue's
  88  *      destination in the relevant interface to this DPIO
  89  */
  90 enum dpio_channel_mode {
  91         DPIO_NO_CHANNEL = 0,
  92         DPIO_LOCAL_CHANNEL = 1,
  93 };
  94
  95 /**
  96  * struct dpio_cfg - Structure representing DPIO configuration
  97  * @channel_mode: Notification channel mode
  98  * @num_priorities: Number of priorities for the notification channel (1-8);
  99  *                      relevant only if 'channel_mode = DPIO_LOCAL_CHANNEL'
 100  */
 101 struct dpio_cfg {
 102         enum dpio_channel_mode  channel_mode;
 103         uint8_t                 num_priorities;
 104 };
 105
 106 /**
 107  * dpio_create() - Create the DPIO object.
 108  * @mc_io:      Pointer to MC portal's I/O object
 109  * @dprc_token: Parent container token; '0' for default container
 110  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 111  * @cfg:        Configuration structure
 112  * @obj_id: returned object id
 113  *
 114  * Create the DPIO object, allocate required resources and
 115  * perform required initialization.
 116  *
 117  * The object can be created either by declaring it in the
 118  * DPL file, or by calling this function.
 119  *
 120  * The function accepts an authentication token of a parent
 121  * container that this object should be assigned to. The token
 122  * can be '0' so the object will be assigned to the default container.
 123  * The newly created object can be opened with the returned
 124  * object id and using the container's associated tokens and MC portals.
 125  *
 126  * Return:      '0' on Success; Error code otherwise.
 127  */
 128 int dpio_create(struct fsl_mc_io        *mc_io,
 129                 uint16_t                dprc_token,
 130                 uint32_t                cmd_flags,
 131                 const struct dpio_cfg   *cfg,
 132                 uint32_t                *obj_id);
 133
 134 /**
 135  * dpio_destroy() - Destroy the DPIO object and release all its resources.
 136  * @mc_io:      Pointer to MC portal's I/O object
 137  * @dprc_token: Parent container token; '0' for default container
 138  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 139  * @object_id:  The object id; it must be a valid id within the container that
 140  * created this object;
 141  *
 142  * The function accepts the authentication token of the parent container that
 143  * created the object (not the one that currently owns the object). The object
 144  * is searched within parent using the provided 'object_id'.
 145  * All tokens to the object must be closed before calling destroy.
 146  *
 147  * Return:      '0' on Success; Error code otherwise
 148  */
 149 int dpio_destroy(struct fsl_mc_io       *mc_io,
 150                  uint16_t               dprc_token,
 151                 uint32_t                cmd_flags,
 152                 uint32_t                object_id);
 153
 154 /**
 155  * dpio_enable() - Enable the DPIO, allow I/O portal operations.
 156  * @mc_io:      Pointer to MC portal's I/O object
 157  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 158  * @token:      Token of DPIO object
 159  *
 160  * Return:      '0' on Success; Error code otherwise
 161  */
 162 int dpio_enable(struct fsl_mc_io        *mc_io,
 163                 uint32_t                cmd_flags,
 164                 uint16_t                token);
 165
 166 /**
 167  * dpio_disable() - Disable the DPIO, stop any I/O portal operation.
 168  * @mc_io:      Pointer to MC portal's I/O object
 169  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 170  * @token:      Token of DPIO object
 171  *
 172  * Return:      '0' on Success; Error code otherwise
 173  */
 174 int dpio_disable(struct fsl_mc_io       *mc_io,
 175                  uint32_t               cmd_flags,
 176                  uint16_t               token);
 177
 178 /**
 179  * dpio_is_enabled() - Check if the DPIO is enabled.
 180  * @mc_io:      Pointer to MC portal's I/O object
 181  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 182  * @token:      Token of DPIO object
 183  * @en: Returns '1' if object is enabled; '0' otherwise
 184  *
 185  * Return:      '0' on Success; Error code otherwise.
 186  */
 187 int dpio_is_enabled(struct fsl_mc_io    *mc_io,
 188                     uint32_t            cmd_flags,
 189                     uint16_t            token,
 190                     int                 *en);
 191
 192 /**
 193  * dpio_reset() - Reset the DPIO, returns the object to initial state.
 194  * @mc_io:      Pointer to MC portal's I/O object
 195  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 196  * @token:      Token of DPIO object
 197  *
 198  * Return:      '0' on Success; Error code otherwise.
 199  */
 200 int dpio_reset(struct fsl_mc_io *mc_io,
 201                uint32_t         cmd_flags,
 202                uint16_t         token);
 203
 204 /**
 205  * dpio_set_stashing_destination() - Set the stashing destination.
 206  * @mc_io:      Pointer to MC portal's I/O object
 207  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 208  * @token:      Token of DPIO object
 209  * @sdest:      stashing destination value
 210  *
 211  * Return:      '0' on Success; Error code otherwise.
 212  */
 213 int dpio_set_stashing_destination(struct fsl_mc_io      *mc_io,
 214                                   uint32_t              cmd_flags,
 215                                   uint16_t              token,
 216                                   uint8_t               sdest);
 217
 218 /**
 219  * dpio_get_stashing_destination() - Get the stashing destination..
 220  * @mc_io:      Pointer to MC portal's I/O object
 221  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 222  * @token:      Token of DPIO object
 223  * @sdest:      Returns the stashing destination value
 224  *
 225  * Return:      '0' on Success; Error code otherwise.
 226  */
 227 int dpio_get_stashing_destination(struct fsl_mc_io      *mc_io,
 228                                   uint32_t              cmd_flags,
 229                                   uint16_t              token,
 230                                   uint8_t               *sdest);
 231
 232 /**
 233  * struct dpio_attr - Structure representing DPIO attributes
 234  * @id: DPIO object ID
 235  * @qbman_portal_ce_offset: offset of the software portal cache-enabled area
 236  * @qbman_portal_ci_offset: offset of the software portal cache-inhibited area
 237  * @qbman_portal_id: Software portal ID
 238  * @channel_mode: Notification channel mode
 239  * @num_priorities: Number of priorities for the notification channel (1-8);
 240  *                      relevant only if 'channel_mode = DPIO_LOCAL_CHANNEL'
 241  * @qbman_version: QBMAN version
 242  */
 243 struct dpio_attr {
 244         int                     id;
 245         uint64_t                qbman_portal_ce_offset;
 246         uint64_t                qbman_portal_ci_offset;
 247         uint16_t                qbman_portal_id;
 248         enum dpio_channel_mode  channel_mode;
 249         uint8_t                 num_priorities;
 250         uint32_t                qbman_version;
 251         uint32_t                clk;
 252 };
 253
 254 /**
 255  * dpio_get_attributes() - Retrieve DPIO attributes
 256  * @mc_io:      Pointer to MC portal's I/O object
 257  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 258  * @token:      Token of DPIO object
 259  * @attr:       Returned object's attributes
 260  *
 261  * Return:      '0' on Success; Error code otherwise
 262  */
 263 int dpio_get_attributes(struct fsl_mc_io        *mc_io,
 264                         uint32_t                cmd_flags,
 265                         uint16_t                token,
 266                         struct dpio_attr        *attr);
 267
 268 /**
 269  * dpio_get_api_version() - Get Data Path I/O API version
 270  * @mc_io:  Pointer to MC portal's I/O object
 271  * @cmd_flags:  Command flags; one or more of 'MC_CMD_FLAG_'
 272  * @major_ver:  Major version of data path i/o API
 273  * @minor_ver:  Minor version of data path i/o API
 274  *
 275  * Return:  '0' on Success; Error code otherwise.
 276  */
 277 int dpio_get_api_version(struct fsl_mc_io *mc_io,
 278                          uint32_t cmd_flags,
 279                          uint16_t *major_ver,
 280                          uint16_t *minor_ver);
 281
 282 #endif /* __FSL_DPIO_H */