include/linux/ntb.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  *   GPL LICENSE SUMMARY
   6  *
   7  *   Copyright (C) 2015 EMC Corporation. All Rights Reserved.
   8  *   Copyright (C) 2016 T-Platforms. All Rights Reserved.
   9  *
  10  *   This program is free software; you can redistribute it and/or modify
  11  *   it under the terms of version 2 of the GNU General Public License as
  12  *   published by the Free Software Foundation.
  13  *
  14  *   This program is distributed in the hope that it will be useful, but
  15  *   WITHOUT ANY WARRANTY; without even the implied warranty of
  16  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  *   General Public License for more details.
  18  *
  19  *   BSD LICENSE
  20  *
  21  *   Copyright (C) 2015 EMC Corporation. All Rights Reserved.
  22  *   Copyright (C) 2016 T-Platforms. All Rights Reserved.
  23  *
  24  *   Redistribution and use in source and binary forms, with or without
  25  *   modification, are permitted provided that the following conditions
  26  *   are met:
  27  *
  28  *     * Redistributions of source code must retain the above copyright
  29  *       notice, this list of conditions and the following disclaimer.
  30  *     * Redistributions in binary form must reproduce the above copy
  31  *       notice, this list of conditions and the following disclaimer in
  32  *       the documentation and/or other materials provided with the
  33  *       distribution.
  34  *     * Neither the name of Intel Corporation nor the names of its
  35  *       contributors may be used to endorse or promote products derived
  36  *       from this software without specific prior written permission.
  37  *
  38  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  39  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  40  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  41  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  42  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  44  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  45  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  46  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  47  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  48  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  49  *
  50  * PCIe NTB Linux driver
  51  *
  52  * Contact Information:
  53  * Allen Hubbe <Allen.Hubbe@emc.com>
  54  */
  55
  56 #ifndef _NTB_H_
  57 #define _NTB_H_
  58
  59 #include <linux/completion.h>
  60 #include <linux/device.h>
  61 #include <linux/interrupt.h>
  62
  63 struct ntb_client;
  64 struct ntb_dev;
  65 struct ntb_msi;
  66 struct pci_dev;
  67
  68 /**
  69  * enum ntb_topo - NTB connection topology
  70  * @NTB_TOPO_NONE:      Topology is unknown or invalid.
  71  * @NTB_TOPO_PRI:       On primary side of local ntb.
  72  * @NTB_TOPO_SEC:       On secondary side of remote ntb.
  73  * @NTB_TOPO_B2B_USD:   On primary side of local ntb upstream of remote ntb.
  74  * @NTB_TOPO_B2B_DSD:   On primary side of local ntb downstream of remote ntb.
  75  * @NTB_TOPO_SWITCH:    Connected via a switch which supports ntb.
  76  * @NTB_TOPO_CROSSLINK: Connected via two symmetric switchecs
  77  */
  78 enum ntb_topo {
  79         NTB_TOPO_NONE = -1,
  80         NTB_TOPO_PRI,
  81         NTB_TOPO_SEC,
  82         NTB_TOPO_B2B_USD,
  83         NTB_TOPO_B2B_DSD,
  84         NTB_TOPO_SWITCH,
  85         NTB_TOPO_CROSSLINK,
  86 };
  87
  88 static inline int ntb_topo_is_b2b(enum ntb_topo topo)
  89 {
  90         switch ((int)topo) {
  91         case NTB_TOPO_B2B_USD:
  92         case NTB_TOPO_B2B_DSD:
  93                 return 1;
  94         }
  95         return 0;
  96 }
  97
  98 static inline char *ntb_topo_string(enum ntb_topo topo)
  99 {
 100         switch (topo) {
 101         case NTB_TOPO_NONE:             return "NTB_TOPO_NONE";
 102         case NTB_TOPO_PRI:              return "NTB_TOPO_PRI";
 103         case NTB_TOPO_SEC:              return "NTB_TOPO_SEC";
 104         case NTB_TOPO_B2B_USD:          return "NTB_TOPO_B2B_USD";
 105         case NTB_TOPO_B2B_DSD:          return "NTB_TOPO_B2B_DSD";
 106         case NTB_TOPO_SWITCH:           return "NTB_TOPO_SWITCH";
 107         case NTB_TOPO_CROSSLINK:        return "NTB_TOPO_CROSSLINK";
 108         }
 109         return "NTB_TOPO_INVALID";
 110 }
 111
 112 /**
 113  * enum ntb_speed - NTB link training speed
 114  * @NTB_SPEED_AUTO:     Request the max supported speed.
 115  * @NTB_SPEED_NONE:     Link is not trained to any speed.
 116  * @NTB_SPEED_GEN1:     Link is trained to gen1 speed.
 117  * @NTB_SPEED_GEN2:     Link is trained to gen2 speed.
 118  * @NTB_SPEED_GEN3:     Link is trained to gen3 speed.
 119  * @NTB_SPEED_GEN4:     Link is trained to gen4 speed.
 120  */
 121 enum ntb_speed {
 122         NTB_SPEED_AUTO = -1,
 123         NTB_SPEED_NONE = 0,
 124         NTB_SPEED_GEN1 = 1,
 125         NTB_SPEED_GEN2 = 2,
 126         NTB_SPEED_GEN3 = 3,
 127         NTB_SPEED_GEN4 = 4
 128 };
 129
 130 /**
 131  * enum ntb_width - NTB link training width
 132  * @NTB_WIDTH_AUTO:     Request the max supported width.
 133  * @NTB_WIDTH_NONE:     Link is not trained to any width.
 134  * @NTB_WIDTH_1:        Link is trained to 1 lane width.
 135  * @NTB_WIDTH_2:        Link is trained to 2 lane width.
 136  * @NTB_WIDTH_4:        Link is trained to 4 lane width.
 137  * @NTB_WIDTH_8:        Link is trained to 8 lane width.
 138  * @NTB_WIDTH_12:       Link is trained to 12 lane width.
 139  * @NTB_WIDTH_16:       Link is trained to 16 lane width.
 140  * @NTB_WIDTH_32:       Link is trained to 32 lane width.
 141  */
 142 enum ntb_width {
 143         NTB_WIDTH_AUTO = -1,
 144         NTB_WIDTH_NONE = 0,
 145         NTB_WIDTH_1 = 1,
 146         NTB_WIDTH_2 = 2,
 147         NTB_WIDTH_4 = 4,
 148         NTB_WIDTH_8 = 8,
 149         NTB_WIDTH_12 = 12,
 150         NTB_WIDTH_16 = 16,
 151         NTB_WIDTH_32 = 32,
 152 };
 153
 154 /**
 155  * enum ntb_default_port - NTB default port number
 156  * @NTB_PORT_PRI_USD:   Default port of the NTB_TOPO_PRI/NTB_TOPO_B2B_USD
 157  *                      topologies
 158  * @NTB_PORT_SEC_DSD:   Default port of the NTB_TOPO_SEC/NTB_TOPO_B2B_DSD
 159  *                      topologies
 160  */
 161 enum ntb_default_port {
 162         NTB_PORT_PRI_USD,
 163         NTB_PORT_SEC_DSD
 164 };
 165 #define NTB_DEF_PEER_CNT        (1)
 166 #define NTB_DEF_PEER_IDX        (0)
 167
 168 /**
 169  * struct ntb_client_ops - ntb client operations
 170  * @probe:              Notify client of a new device.
 171  * @remove:             Notify client to remove a device.
 172  */
 173 struct ntb_client_ops {
 174         int (*probe)(struct ntb_client *client, struct ntb_dev *ntb);
 175         void (*remove)(struct ntb_client *client, struct ntb_dev *ntb);
 176 };
 177
 178 static inline int ntb_client_ops_is_valid(const struct ntb_client_ops *ops)
 179 {
 180         /* commented callbacks are not required: */
 181         return
 182                 ops->probe                      &&
 183                 ops->remove                     &&
 184                 1;
 185 }
 186
 187 /**
 188  * struct ntb_ctx_ops - ntb driver context operations
 189  * @link_event:         See ntb_link_event().
 190  * @db_event:           See ntb_db_event().
 191  * @msg_event:          See ntb_msg_event().
 192  */
 193 struct ntb_ctx_ops {
 194         void (*link_event)(void *ctx);
 195         void (*db_event)(void *ctx, int db_vector);
 196         void (*msg_event)(void *ctx);
 197 };
 198
 199 static inline int ntb_ctx_ops_is_valid(const struct ntb_ctx_ops *ops)
 200 {
 201         /* commented callbacks are not required: */
 202         return
 203                 /* ops->link_event              && */
 204                 /* ops->db_event                && */
 205                 /* ops->msg_event               && */
 206                 1;
 207 }
 208
 209 /**
 210  * struct ntb_dev_ops - ntb device operations
 211  * @port_number:        See ntb_port_number().
 212  * @peer_port_count:    See ntb_peer_port_count().
 213  * @peer_port_number:   See ntb_peer_port_number().
 214  * @peer_port_idx:      See ntb_peer_port_idx().
 215  * @link_is_up:         See ntb_link_is_up().
 216  * @link_enable:        See ntb_link_enable().
 217  * @link_disable:       See ntb_link_disable().
 218  * @mw_count:           See ntb_mw_count().
 219  * @mw_get_align:       See ntb_mw_get_align().
 220  * @mw_set_trans:       See ntb_mw_set_trans().
 221  * @mw_clear_trans:     See ntb_mw_clear_trans().
 222  * @peer_mw_count:      See ntb_peer_mw_count().
 223  * @peer_mw_get_addr:   See ntb_peer_mw_get_addr().
 224  * @peer_mw_set_trans:  See ntb_peer_mw_set_trans().
 225  * @peer_mw_clear_trans:See ntb_peer_mw_clear_trans().
 226  * @db_is_unsafe:       See ntb_db_is_unsafe().
 227  * @db_valid_mask:      See ntb_db_valid_mask().
 228  * @db_vector_count:    See ntb_db_vector_count().
 229  * @db_vector_mask:     See ntb_db_vector_mask().
 230  * @db_read:            See ntb_db_read().
 231  * @db_set:             See ntb_db_set().
 232  * @db_clear:           See ntb_db_clear().
 233  * @db_read_mask:       See ntb_db_read_mask().
 234  * @db_set_mask:        See ntb_db_set_mask().
 235  * @db_clear_mask:      See ntb_db_clear_mask().
 236  * @peer_db_addr:       See ntb_peer_db_addr().
 237  * @peer_db_read:       See ntb_peer_db_read().
 238  * @peer_db_set:        See ntb_peer_db_set().
 239  * @peer_db_clear:      See ntb_peer_db_clear().
 240  * @peer_db_read_mask:  See ntb_peer_db_read_mask().
 241  * @peer_db_set_mask:   See ntb_peer_db_set_mask().
 242  * @peer_db_clear_mask: See ntb_peer_db_clear_mask().
 243  * @spad_is_unsafe:     See ntb_spad_is_unsafe().
 244  * @spad_count:         See ntb_spad_count().
 245  * @spad_read:          See ntb_spad_read().
 246  * @spad_write:         See ntb_spad_write().
 247  * @peer_spad_addr:     See ntb_peer_spad_addr().
 248  * @peer_spad_read:     See ntb_peer_spad_read().
 249  * @peer_spad_write:    See ntb_peer_spad_write().
 250  * @msg_count:          See ntb_msg_count().
 251  * @msg_inbits:         See ntb_msg_inbits().
 252  * @msg_outbits:        See ntb_msg_outbits().
 253  * @msg_read_sts:       See ntb_msg_read_sts().
 254  * @msg_clear_sts:      See ntb_msg_clear_sts().
 255  * @msg_set_mask:       See ntb_msg_set_mask().
 256  * @msg_clear_mask:     See ntb_msg_clear_mask().
 257  * @msg_read:           See ntb_msg_read().
 258  * @peer_msg_write:     See ntb_peer_msg_write().
 259  */
 260 struct ntb_dev_ops {
 261         int (*port_number)(struct ntb_dev *ntb);
 262         int (*peer_port_count)(struct ntb_dev *ntb);
 263         int (*peer_port_number)(struct ntb_dev *ntb, int pidx);
 264         int (*peer_port_idx)(struct ntb_dev *ntb, int port);
 265
 266         u64 (*link_is_up)(struct ntb_dev *ntb,
 267                           enum ntb_speed *speed, enum ntb_width *width);
 268         int (*link_enable)(struct ntb_dev *ntb,
 269                            enum ntb_speed max_speed, enum ntb_width max_width);
 270         int (*link_disable)(struct ntb_dev *ntb);
 271
 272         int (*mw_count)(struct ntb_dev *ntb, int pidx);
 273         int (*mw_get_align)(struct ntb_dev *ntb, int pidx, int widx,
 274                             resource_size_t *addr_align,
 275                             resource_size_t *size_align,
 276                             resource_size_t *size_max);
 277         int (*mw_set_trans)(struct ntb_dev *ntb, int pidx, int widx,
 278                             dma_addr_t addr, resource_size_t size);
 279         int (*mw_clear_trans)(struct ntb_dev *ntb, int pidx, int widx);
 280         int (*peer_mw_count)(struct ntb_dev *ntb);
 281         int (*peer_mw_get_addr)(struct ntb_dev *ntb, int widx,
 282                                 phys_addr_t *base, resource_size_t *size);
 283         int (*peer_mw_set_trans)(struct ntb_dev *ntb, int pidx, int widx,
 284                                  u64 addr, resource_size_t size);
 285         int (*peer_mw_clear_trans)(struct ntb_dev *ntb, int pidx, int widx);
 286
 287         int (*db_is_unsafe)(struct ntb_dev *ntb);
 288         u64 (*db_valid_mask)(struct ntb_dev *ntb);
 289         int (*db_vector_count)(struct ntb_dev *ntb);
 290         u64 (*db_vector_mask)(struct ntb_dev *ntb, int db_vector);
 291
 292         u64 (*db_read)(struct ntb_dev *ntb);
 293         int (*db_set)(struct ntb_dev *ntb, u64 db_bits);
 294         int (*db_clear)(struct ntb_dev *ntb, u64 db_bits);
 295
 296         u64 (*db_read_mask)(struct ntb_dev *ntb);
 297         int (*db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
 298         int (*db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
 299
 300         int (*peer_db_addr)(struct ntb_dev *ntb,
 301                             phys_addr_t *db_addr, resource_size_t *db_size,
 302                                 u64 *db_data, int db_bit);
 303         u64 (*peer_db_read)(struct ntb_dev *ntb);
 304         int (*peer_db_set)(struct ntb_dev *ntb, u64 db_bits);
 305         int (*peer_db_clear)(struct ntb_dev *ntb, u64 db_bits);
 306
 307         u64 (*peer_db_read_mask)(struct ntb_dev *ntb);
 308         int (*peer_db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
 309         int (*peer_db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
 310
 311         int (*spad_is_unsafe)(struct ntb_dev *ntb);
 312         int (*spad_count)(struct ntb_dev *ntb);
 313
 314         u32 (*spad_read)(struct ntb_dev *ntb, int sidx);
 315         int (*spad_write)(struct ntb_dev *ntb, int sidx, u32 val);
 316
 317         int (*peer_spad_addr)(struct ntb_dev *ntb, int pidx, int sidx,
 318                               phys_addr_t *spad_addr);
 319         u32 (*peer_spad_read)(struct ntb_dev *ntb, int pidx, int sidx);
 320         int (*peer_spad_write)(struct ntb_dev *ntb, int pidx, int sidx,
 321                                u32 val);
 322
 323         int (*msg_count)(struct ntb_dev *ntb);
 324         u64 (*msg_inbits)(struct ntb_dev *ntb);
 325         u64 (*msg_outbits)(struct ntb_dev *ntb);
 326         u64 (*msg_read_sts)(struct ntb_dev *ntb);
 327         int (*msg_clear_sts)(struct ntb_dev *ntb, u64 sts_bits);
 328         int (*msg_set_mask)(struct ntb_dev *ntb, u64 mask_bits);
 329         int (*msg_clear_mask)(struct ntb_dev *ntb, u64 mask_bits);
 330         u32 (*msg_read)(struct ntb_dev *ntb, int *pidx, int midx);
 331         int (*peer_msg_write)(struct ntb_dev *ntb, int pidx, int midx, u32 msg);
 332 };
 333
 334 static inline int ntb_dev_ops_is_valid(const struct ntb_dev_ops *ops)
 335 {
 336         /* commented callbacks are not required: */
 337         return
 338                 /* Port operations are required for multiport devices */
 339                 !ops->peer_port_count == !ops->port_number      &&
 340                 !ops->peer_port_number == !ops->port_number     &&
 341                 !ops->peer_port_idx == !ops->port_number        &&
 342
 343                 /* Link operations are required */
 344                 ops->link_is_up                         &&
 345                 ops->link_enable                        &&
 346                 ops->link_disable                       &&
 347
 348                 /* One or both MW interfaces should be developed */
 349                 ops->mw_count                           &&
 350                 ops->mw_get_align                       &&
 351                 (ops->mw_set_trans                      ||
 352                  ops->peer_mw_set_trans)                &&
 353                 /* ops->mw_clear_trans                  && */
 354                 ops->peer_mw_count                      &&
 355                 ops->peer_mw_get_addr                   &&
 356                 /* ops->peer_mw_clear_trans             && */
 357
 358                 /* Doorbell operations are mostly required */
 359                 /* ops->db_is_unsafe                    && */
 360                 ops->db_valid_mask                      &&
 361                 /* both set, or both unset */
 362                 (!ops->db_vector_count == !ops->db_vector_mask) &&
 363                 ops->db_read                            &&
 364                 /* ops->db_set                          && */
 365                 ops->db_clear                           &&
 366                 /* ops->db_read_mask                    && */
 367                 ops->db_set_mask                        &&
 368                 ops->db_clear_mask                      &&
 369                 /* ops->peer_db_addr                    && */
 370                 /* ops->peer_db_read                    && */
 371                 ops->peer_db_set                        &&
 372                 /* ops->peer_db_clear                   && */
 373                 /* ops->peer_db_read_mask               && */
 374                 /* ops->peer_db_set_mask                && */
 375                 /* ops->peer_db_clear_mask              && */
 376
 377                 /* Scrachpads interface is optional */
 378                 /* !ops->spad_is_unsafe == !ops->spad_count     && */
 379                 !ops->spad_read == !ops->spad_count             &&
 380                 !ops->spad_write == !ops->spad_count            &&
 381                 /* !ops->peer_spad_addr == !ops->spad_count     && */
 382                 /* !ops->peer_spad_read == !ops->spad_count     && */
 383                 !ops->peer_spad_write == !ops->spad_count       &&
 384
 385                 /* Messaging interface is optional */
 386                 !ops->msg_inbits == !ops->msg_count             &&
 387                 !ops->msg_outbits == !ops->msg_count            &&
 388                 !ops->msg_read_sts == !ops->msg_count           &&
 389                 !ops->msg_clear_sts == !ops->msg_count          &&
 390                 /* !ops->msg_set_mask == !ops->msg_count        && */
 391                 /* !ops->msg_clear_mask == !ops->msg_count      && */
 392                 !ops->msg_read == !ops->msg_count               &&
 393                 !ops->peer_msg_write == !ops->msg_count         &&
 394                 1;
 395 }
 396
 397 /**
 398  * struct ntb_client - client interested in ntb devices
 399  * @drv:                Linux driver object.
 400  * @ops:                See &ntb_client_ops.
 401  */
 402 struct ntb_client {
 403         struct device_driver            drv;
 404         const struct ntb_client_ops     ops;
 405 };
 406 #define drv_ntb_client(__drv) container_of((__drv), struct ntb_client, drv)
 407
 408 /**
 409  * struct ntb_dev - ntb device
 410  * @dev:                Linux device object.
 411  * @pdev:               PCI device entry of the ntb.
 412  * @topo:               Detected topology of the ntb.
 413  * @ops:                See &ntb_dev_ops.
 414  * @ctx:                See &ntb_ctx_ops.
 415  * @ctx_ops:            See &ntb_ctx_ops.
 416  */
 417 struct ntb_dev {
 418         struct device                   dev;
 419         struct pci_dev                  *pdev;
 420         enum ntb_topo                   topo;
 421         const struct ntb_dev_ops        *ops;
 422         void                            *ctx;
 423         const struct ntb_ctx_ops        *ctx_ops;
 424
 425         /* private: */
 426
 427         /* synchronize setting, clearing, and calling ctx_ops */
 428         spinlock_t                      ctx_lock;
 429         /* block unregister until device is fully released */
 430         struct completion               released;
 431
 432 #ifdef CONFIG_NTB_MSI
 433         struct ntb_msi *msi;
 434 #endif
 435 };
 436 #define dev_ntb(__dev) container_of((__dev), struct ntb_dev, dev)
 437
 438 /**
 439  * ntb_register_client() - register a client for interest in ntb devices
 440  * @client:     Client context.
 441  *
 442  * The client will be added to the list of clients interested in ntb devices.
 443  * The client will be notified of any ntb devices that are not already
 444  * associated with a client, or if ntb devices are registered later.
 445  *
 446  * Return: Zero if the client is registered, otherwise an error number.
 447  */
 448 #define ntb_register_client(client) \
 449         __ntb_register_client((client), THIS_MODULE, KBUILD_MODNAME)
 450
 451 int __ntb_register_client(struct ntb_client *client, struct module *mod,
 452                           const char *mod_name);
 453
 454 /**
 455  * ntb_unregister_client() - unregister a client for interest in ntb devices
 456  * @client:     Client context.
 457  *
 458  * The client will be removed from the list of clients interested in ntb
 459  * devices.  If any ntb devices are associated with the client, the client will
 460  * be notified to remove those devices.
 461  */
 462 void ntb_unregister_client(struct ntb_client *client);
 463
 464 #define module_ntb_client(__ntb_client) \
 465         module_driver(__ntb_client, ntb_register_client, \
 466                         ntb_unregister_client)
 467
 468 /**
 469  * ntb_register_device() - register a ntb device
 470  * @ntb:        NTB device context.
 471  *
 472  * The device will be added to the list of ntb devices.  If any clients are
 473  * interested in ntb devices, each client will be notified of the ntb device,
 474  * until at most one client accepts the device.
 475  *
 476  * Return: Zero if the device is registered, otherwise an error number.
 477  */
 478 int ntb_register_device(struct ntb_dev *ntb);
 479
 480 /**
 481  * ntb_unregister_device() - unregister a ntb device
 482  * @ntb:        NTB device context.
 483  *
 484  * The device will be removed from the list of ntb devices.  If the ntb device
 485  * is associated with a client, the client will be notified to remove the
 486  * device.
 487  */
 488 void ntb_unregister_device(struct ntb_dev *ntb);
 489
 490 /**
 491  * ntb_set_ctx() - associate a driver context with an ntb device
 492  * @ntb:        NTB device context.
 493  * @ctx:        Driver context.
 494  * @ctx_ops:    Driver context operations.
 495  *
 496  * Associate a driver context and operations with a ntb device.  The context is
 497  * provided by the client driver, and the driver may associate a different
 498  * context with each ntb device.
 499  *
 500  * Return: Zero if the context is associated, otherwise an error number.
 501  */
 502 int ntb_set_ctx(struct ntb_dev *ntb, void *ctx,
 503                 const struct ntb_ctx_ops *ctx_ops);
 504
 505 /**
 506  * ntb_clear_ctx() - disassociate any driver context from an ntb device
 507  * @ntb:        NTB device context.
 508  *
 509  * Clear any association that may exist between a driver context and the ntb
 510  * device.
 511  */
 512 void ntb_clear_ctx(struct ntb_dev *ntb);
 513
 514 /**
 515  * ntb_link_event() - notify driver context of a change in link status
 516  * @ntb:        NTB device context.
 517  *
 518  * Notify the driver context that the link status may have changed.  The driver
 519  * should call ntb_link_is_up() to get the current status.
 520  */
 521 void ntb_link_event(struct ntb_dev *ntb);
 522
 523 /**
 524  * ntb_db_event() - notify driver context of a doorbell event
 525  * @ntb:        NTB device context.
 526  * @vector:     Interrupt vector number.
 527  *
 528  * Notify the driver context of a doorbell event.  If hardware supports
 529  * multiple interrupt vectors for doorbells, the vector number indicates which
 530  * vector received the interrupt.  The vector number is relative to the first
 531  * vector used for doorbells, starting at zero, and must be less than
 532  * ntb_db_vector_count().  The driver may call ntb_db_read() to check which
 533  * doorbell bits need service, and ntb_db_vector_mask() to determine which of
 534  * those bits are associated with the vector number.
 535  */
 536 void ntb_db_event(struct ntb_dev *ntb, int vector);
 537
 538 /**
 539  * ntb_msg_event() - notify driver context of a message event
 540  * @ntb:        NTB device context.
 541  *
 542  * Notify the driver context of a message event.  If hardware supports
 543  * message registers, this event indicates, that a new message arrived in
 544  * some incoming message register or last sent message couldn't be delivered.
 545  * The events can be masked/unmasked by the methods ntb_msg_set_mask() and
 546  * ntb_msg_clear_mask().
 547  */
 548 void ntb_msg_event(struct ntb_dev *ntb);
 549
 550 /**
 551  * ntb_default_port_number() - get the default local port number
 552  * @ntb:        NTB device context.
 553  *
 554  * If hardware driver doesn't specify port_number() callback method, the NTB
 555  * is considered with just two ports. So this method returns default local
 556  * port number in compliance with topology.
 557  *
 558  * NOTE Don't call this method directly. The ntb_port_number() function should
 559  * be used instead.
 560  *
 561  * Return: the default local port number
 562  */
 563 int ntb_default_port_number(struct ntb_dev *ntb);
 564
 565 /**
 566  * ntb_default_port_count() - get the default number of peer device ports
 567  * @ntb:        NTB device context.
 568  *
 569  * By default hardware driver supports just one peer device.
 570  *
 571  * NOTE Don't call this method directly. The ntb_peer_port_count() function
 572  * should be used instead.
 573  *
 574  * Return: the default number of peer ports
 575  */
 576 int ntb_default_peer_port_count(struct ntb_dev *ntb);
 577
 578 /**
 579  * ntb_default_peer_port_number() - get the default peer port by given index
 580  * @ntb:        NTB device context.
 581  * @idx:        Peer port index (should not differ from zero).
 582  *
 583  * By default hardware driver supports just one peer device, so this method
 584  * shall return the corresponding value from enum ntb_default_port.
 585  *
 586  * NOTE Don't call this method directly. The ntb_peer_port_number() function
 587  * should be used instead.
 588  *
 589  * Return: the peer device port or negative value indicating an error
 590  */
 591 int ntb_default_peer_port_number(struct ntb_dev *ntb, int pidx);
 592
 593 /**
 594  * ntb_default_peer_port_idx() - get the default peer device port index by
 595  *                               given port number
 596  * @ntb:        NTB device context.
 597  * @port:       Peer port number (should be one of enum ntb_default_port).
 598  *
 599  * By default hardware driver supports just one peer device, so while
 600  * specified port-argument indicates peer port from enum ntb_default_port,
 601  * the return value shall be zero.
 602  *
 603  * NOTE Don't call this method directly. The ntb_peer_port_idx() function
 604  * should be used instead.
 605  *
 606  * Return: the peer port index or negative value indicating an error
 607  */
 608 int ntb_default_peer_port_idx(struct ntb_dev *ntb, int port);
 609
 610 /**
 611  * ntb_port_number() - get the local port number
 612  * @ntb:        NTB device context.
 613  *
 614  * Hardware must support at least simple two-ports ntb connection
 615  *
 616  * Return: the local port number
 617  */
 618 static inline int ntb_port_number(struct ntb_dev *ntb)
 619 {
 620         if (!ntb->ops->port_number)
 621                 return ntb_default_port_number(ntb);
 622
 623         return ntb->ops->port_number(ntb);
 624 }
 625 /**
 626  * ntb_peer_port_count() - get the number of peer device ports
 627  * @ntb:        NTB device context.
 628  *
 629  * Hardware may support an access to memory of several remote domains
 630  * over multi-port NTB devices. This method returns the number of peers,
 631  * local device can have shared memory with.
 632  *
 633  * Return: the number of peer ports
 634  */
 635 static inline int ntb_peer_port_count(struct ntb_dev *ntb)
 636 {
 637         if (!ntb->ops->peer_port_count)
 638                 return ntb_default_peer_port_count(ntb);
 639
 640         return ntb->ops->peer_port_count(ntb);
 641 }
 642
 643 /**
 644  * ntb_peer_port_number() - get the peer port by given index
 645  * @ntb:        NTB device context.
 646  * @pidx:       Peer port index.
 647  *
 648  * Peer ports are continuously enumerated by NTB API logic, so this method
 649  * lets to retrieve port real number by its index.
 650  *
 651  * Return: the peer device port or negative value indicating an error
 652  */
 653 static inline int ntb_peer_port_number(struct ntb_dev *ntb, int pidx)
 654 {
 655         if (!ntb->ops->peer_port_number)
 656                 return ntb_default_peer_port_number(ntb, pidx);
 657
 658         return ntb->ops->peer_port_number(ntb, pidx);
 659 }
 660
 661 /**
 662  * ntb_logical_port_number() - get the logical port number of the local port
 663  * @ntb:        NTB device context.
 664  *
 665  * The Logical Port Number is defined to be a unique number for each
 666  * port starting from zero through to the number of ports minus one.
 667  * This is in contrast to the Port Number where each port can be assigned
 668  * any unique physical number by the hardware.
 669  *
 670  * The logical port number is useful for calculating the resource indexes
 671  * used by peers.
 672  *
 673  * Return: the logical port number or negative value indicating an error
 674  */
 675 static inline int ntb_logical_port_number(struct ntb_dev *ntb)
 676 {
 677         int lport = ntb_port_number(ntb);
 678         int pidx;
 679
 680         if (lport < 0)
 681                 return lport;
 682
 683         for (pidx = 0; pidx < ntb_peer_port_count(ntb); pidx++)
 684                 if (lport <= ntb_peer_port_number(ntb, pidx))
 685                         return pidx;
 686
 687         return pidx;
 688 }
 689
 690 /**
 691  * ntb_peer_logical_port_number() - get the logical peer port by given index
 692  * @ntb:        NTB device context.
 693  * @pidx:       Peer port index.
 694  *
 695  * The Logical Port Number is defined to be a unique number for each
 696  * port starting from zero through to the number of ports minus one.
 697  * This is in contrast to the Port Number where each port can be assigned
 698  * any unique physical number by the hardware.
 699  *
 700  * The logical port number is useful for calculating the resource indexes
 701  * used by peers.
 702  *
 703  * Return: the peer's logical port number or negative value indicating an error
 704  */
 705 static inline int ntb_peer_logical_port_number(struct ntb_dev *ntb, int pidx)
 706 {
 707         if (ntb_peer_port_number(ntb, pidx) < ntb_port_number(ntb))
 708                 return pidx;
 709         else
 710                 return pidx + 1;
 711 }
 712
 713 /**
 714  * ntb_peer_port_idx() - get the peer device port index by given port number
 715  * @ntb:        NTB device context.
 716  * @port:       Peer port number.
 717  *
 718  * Inverse operation of ntb_peer_port_number(), so one can get port index
 719  * by specified port number.
 720  *
 721  * Return: the peer port index or negative value indicating an error
 722  */
 723 static inline int ntb_peer_port_idx(struct ntb_dev *ntb, int port)
 724 {
 725         if (!ntb->ops->peer_port_idx)
 726                 return ntb_default_peer_port_idx(ntb, port);
 727
 728         return ntb->ops->peer_port_idx(ntb, port);
 729 }
 730
 731 /**
 732  * ntb_link_is_up() - get the current ntb link state
 733  * @ntb:        NTB device context.
 734  * @speed:      OUT - The link speed expressed as PCIe generation number.
 735  * @width:      OUT - The link width expressed as the number of PCIe lanes.
 736  *
 737  * Get the current state of the ntb link.  It is recommended to query the link
 738  * state once after every link event.  It is safe to query the link state in
 739  * the context of the link event callback.
 740  *
 741  * Return: bitfield of indexed ports link state: bit is set/cleared if the
 742  *         link is up/down respectively.
 743  */
 744 static inline u64 ntb_link_is_up(struct ntb_dev *ntb,
 745                                  enum ntb_speed *speed, enum ntb_width *width)
 746 {
 747         return ntb->ops->link_is_up(ntb, speed, width);
 748 }
 749
 750 /**
 751  * ntb_link_enable() - enable the local port ntb connection
 752  * @ntb:        NTB device context.
 753  * @max_speed:  The maximum link speed expressed as PCIe generation number.
 754  * @max_width:  The maximum link width expressed as the number of PCIe lanes.
 755  *
 756  * Enable the NTB/PCIe link on the local or remote (for bridge-to-bridge
 757  * topology) side of the bridge. If it's supported the ntb device should train
 758  * the link to its maximum speed and width, or the requested speed and width,
 759  * whichever is smaller. Some hardware doesn't support PCIe link training, so
 760  * the last two arguments will be ignored then.
 761  *
 762  * Return: Zero on success, otherwise an error number.
 763  */
 764 static inline int ntb_link_enable(struct ntb_dev *ntb,
 765                                   enum ntb_speed max_speed,
 766                                   enum ntb_width max_width)
 767 {
 768         return ntb->ops->link_enable(ntb, max_speed, max_width);
 769 }
 770
 771 /**
 772  * ntb_link_disable() - disable the local port ntb connection
 773  * @ntb:        NTB device context.
 774  *
 775  * Disable the link on the local or remote (for b2b topology) of the ntb.
 776  * The ntb device should disable the link.  Returning from this call must
 777  * indicate that a barrier has passed, though with no more writes may pass in
 778  * either direction across the link, except if this call returns an error
 779  * number.
 780  *
 781  * Return: Zero on success, otherwise an error number.
 782  */
 783 static inline int ntb_link_disable(struct ntb_dev *ntb)
 784 {
 785         return ntb->ops->link_disable(ntb);
 786 }
 787
 788 /**
 789  * ntb_mw_count() - get the number of inbound memory windows, which could
 790  *                  be created for a specified peer device
 791  * @ntb:        NTB device context.
 792  * @pidx:       Port index of peer device.
 793  *
 794  * Hardware and topology may support a different number of memory windows.
 795  * Moreover different peer devices can support different number of memory
 796  * windows. Simply speaking this method returns the number of possible inbound
 797  * memory windows to share with specified peer device. Note: this may return
 798  * zero if the link is not up yet.
 799  *
 800  * Return: the number of memory windows.
 801  */
 802 static inline int ntb_mw_count(struct ntb_dev *ntb, int pidx)
 803 {
 804         return ntb->ops->mw_count(ntb, pidx);
 805 }
 806
 807 /**
 808  * ntb_mw_get_align() - get the restriction parameters of inbound memory window
 809  * @ntb:        NTB device context.
 810  * @pidx:       Port index of peer device.
 811  * @widx:       Memory window index.
 812  * @addr_align: OUT - the base alignment for translating the memory window
 813  * @size_align: OUT - the size alignment for translating the memory window
 814  * @size_max:   OUT - the maximum size of the memory window
 815  *
 816  * Get the alignments of an inbound memory window with specified index.
 817  * NULL may be given for any output parameter if the value is not needed.
 818  * The alignment and size parameters may be used for allocation of proper
 819  * shared memory. Note: this must only be called when the link is up.
 820  *
 821  * Return: Zero on success, otherwise a negative error number.
 822  */
 823 static inline int ntb_mw_get_align(struct ntb_dev *ntb, int pidx, int widx,
 824                                    resource_size_t *addr_align,
 825                                    resource_size_t *size_align,
 826                                    resource_size_t *size_max)
 827 {
 828         if (!(ntb_link_is_up(ntb, NULL, NULL) & BIT_ULL(pidx)))
 829                 return -ENOTCONN;
 830
 831         return ntb->ops->mw_get_align(ntb, pidx, widx, addr_align, size_align,
 832                                       size_max);
 833 }
 834
 835 /**
 836  * ntb_mw_set_trans() - set the translation of an inbound memory window
 837  * @ntb:        NTB device context.
 838  * @pidx:       Port index of peer device.
 839  * @widx:       Memory window index.
 840  * @addr:       The dma address of local memory to expose to the peer.
 841  * @size:       The size of the local memory to expose to the peer.
 842  *
 843  * Set the translation of a memory window.  The peer may access local memory
 844  * through the window starting at the address, up to the size.  The address
 845  * and size must be aligned in compliance with restrictions of
 846  * ntb_mw_get_align(). The region size should not exceed the size_max parameter
 847  * of that method.
 848  *
 849  * This method may not be implemented due to the hardware specific memory
 850  * windows interface.
 851  *
 852  * Return: Zero on success, otherwise an error number.
 853  */
 854 static inline int ntb_mw_set_trans(struct ntb_dev *ntb, int pidx, int widx,
 855                                    dma_addr_t addr, resource_size_t size)
 856 {
 857         if (!ntb->ops->mw_set_trans)
 858                 return 0;
 859
 860         return ntb->ops->mw_set_trans(ntb, pidx, widx, addr, size);
 861 }
 862
 863 /**
 864  * ntb_mw_clear_trans() - clear the translation address of an inbound memory
 865  *                        window
 866  * @ntb:        NTB device context.
 867  * @pidx:       Port index of peer device.
 868  * @widx:       Memory window index.
 869  *
 870  * Clear the translation of an inbound memory window.  The peer may no longer
 871  * access local memory through the window.
 872  *
 873  * Return: Zero on success, otherwise an error number.
 874  */
 875 static inline int ntb_mw_clear_trans(struct ntb_dev *ntb, int pidx, int widx)
 876 {
 877         if (!ntb->ops->mw_clear_trans)
 878                 return ntb_mw_set_trans(ntb, pidx, widx, 0, 0);
 879
 880         return ntb->ops->mw_clear_trans(ntb, pidx, widx);
 881 }
 882
 883 /**
 884  * ntb_peer_mw_count() - get the number of outbound memory windows, which could
 885  *                       be mapped to access a shared memory
 886  * @ntb:        NTB device context.
 887  *
 888  * Hardware and topology may support a different number of memory windows.
 889  * This method returns the number of outbound memory windows supported by
 890  * local device.
 891  *
 892  * Return: the number of memory windows.
 893  */
 894 static inline int ntb_peer_mw_count(struct ntb_dev *ntb)
 895 {
 896         return ntb->ops->peer_mw_count(ntb);
 897 }
 898
 899 /**
 900  * ntb_peer_mw_get_addr() - get map address of an outbound memory window
 901  * @ntb:        NTB device context.
 902  * @widx:       Memory window index (within ntb_peer_mw_count() return value).
 903  * @base:       OUT - the base address of mapping region.
 904  * @size:       OUT - the size of mapping region.
 905  *
 906  * Get base and size of memory region to map.  NULL may be given for any output
 907  * parameter if the value is not needed.  The base and size may be used for
 908  * mapping the memory window, to access the peer memory.
 909  *
 910  * Return: Zero on success, otherwise a negative error number.
 911  */
 912 static inline int ntb_peer_mw_get_addr(struct ntb_dev *ntb, int widx,
 913                                       phys_addr_t *base, resource_size_t *size)
 914 {
 915         return ntb->ops->peer_mw_get_addr(ntb, widx, base, size);
 916 }
 917
 918 /**
 919  * ntb_peer_mw_set_trans() - set a translation address of a memory window
 920  *                           retrieved from a peer device
 921  * @ntb:        NTB device context.
 922  * @pidx:       Port index of peer device the translation address received from.
 923  * @widx:       Memory window index.
 924  * @addr:       The dma address of the shared memory to access.
 925  * @size:       The size of the shared memory to access.
 926  *
 927  * Set the translation of an outbound memory window.  The local device may
 928  * access shared memory allocated by a peer device sent the address.
 929  *
 930  * This method may not be implemented due to the hardware specific memory
 931  * windows interface, so a translation address can be only set on the side,
 932  * where shared memory (inbound memory windows) is allocated.
 933  *
 934  * Return: Zero on success, otherwise an error number.
 935  */
 936 static inline int ntb_peer_mw_set_trans(struct ntb_dev *ntb, int pidx, int widx,
 937                                         u64 addr, resource_size_t size)
 938 {
 939         if (!ntb->ops->peer_mw_set_trans)
 940                 return 0;
 941
 942         return ntb->ops->peer_mw_set_trans(ntb, pidx, widx, addr, size);
 943 }
 944
 945 /**
 946  * ntb_peer_mw_clear_trans() - clear the translation address of an outbound
 947  *                             memory window
 948  * @ntb:        NTB device context.
 949  * @pidx:       Port index of peer device.
 950  * @widx:       Memory window index.
 951  *
 952  * Clear the translation of a outbound memory window.  The local device may no
 953  * longer access a shared memory through the window.
 954  *
 955  * This method may not be implemented due to the hardware specific memory
 956  * windows interface.
 957  *
 958  * Return: Zero on success, otherwise an error number.
 959  */
 960 static inline int ntb_peer_mw_clear_trans(struct ntb_dev *ntb, int pidx,
 961                                           int widx)
 962 {
 963         if (!ntb->ops->peer_mw_clear_trans)
 964                 return ntb_peer_mw_set_trans(ntb, pidx, widx, 0, 0);
 965
 966         return ntb->ops->peer_mw_clear_trans(ntb, pidx, widx);
 967 }
 968
 969 /**
 970  * ntb_db_is_unsafe() - check if it is safe to use hardware doorbell
 971  * @ntb:        NTB device context.
 972  *
 973  * It is possible for some ntb hardware to be affected by errata.  Hardware
 974  * drivers can advise clients to avoid using doorbells.  Clients may ignore
 975  * this advice, though caution is recommended.
 976  *
 977  * Return: Zero if it is safe to use doorbells, or One if it is not safe.
 978  */
 979 static inline int ntb_db_is_unsafe(struct ntb_dev *ntb)
 980 {
 981         if (!ntb->ops->db_is_unsafe)
 982                 return 0;
 983
 984         return ntb->ops->db_is_unsafe(ntb);
 985 }
 986
 987 /**
 988  * ntb_db_valid_mask() - get a mask of doorbell bits supported by the ntb
 989  * @ntb:        NTB device context.
 990  *
 991  * Hardware may support different number or arrangement of doorbell bits.
 992  *
 993  * Return: A mask of doorbell bits supported by the ntb.
 994  */
 995 static inline u64 ntb_db_valid_mask(struct ntb_dev *ntb)
 996 {
 997         return ntb->ops->db_valid_mask(ntb);
 998 }
 999
1000 /**
1001  * ntb_db_vector_count() - get the number of doorbell interrupt vectors
1002  * @ntb:        NTB device context.
1003  *
1004  * Hardware may support different number of interrupt vectors.
1005  *
1006  * Return: The number of doorbell interrupt vectors.
1007  */
1008 static inline int ntb_db_vector_count(struct ntb_dev *ntb)
1009 {
1010         if (!ntb->ops->db_vector_count)
1011                 return 1;
1012
1013         return ntb->ops->db_vector_count(ntb);
1014 }
1015
1016 /**
1017  * ntb_db_vector_mask() - get a mask of doorbell bits serviced by a vector
1018  * @ntb:        NTB device context.
1019  * @vector:     Doorbell vector number.
1020  *
1021  * Each interrupt vector may have a different number or arrangement of bits.
1022  *
1023  * Return: A mask of doorbell bits serviced by a vector.
1024  */
1025 static inline u64 ntb_db_vector_mask(struct ntb_dev *ntb, int vector)
1026 {
1027         if (!ntb->ops->db_vector_mask)
1028                 return ntb_db_valid_mask(ntb);
1029
1030         return ntb->ops->db_vector_mask(ntb, vector);
1031 }
1032
1033 /**
1034  * ntb_db_read() - read the local doorbell register
1035  * @ntb:        NTB device context.
1036  *
1037  * Read the local doorbell register, and return the bits that are set.
1038  *
1039  * Return: The bits currently set in the local doorbell register.
1040  */
1041 static inline u64 ntb_db_read(struct ntb_dev *ntb)
1042 {
1043         return ntb->ops->db_read(ntb);
1044 }
1045
1046 /**
1047  * ntb_db_set() - set bits in the local doorbell register
1048  * @ntb:        NTB device context.
1049  * @db_bits:    Doorbell bits to set.
1050  *
1051  * Set bits in the local doorbell register, which may generate a local doorbell
1052  * interrupt.  Bits that were already set must remain set.
1053  *
1054  * This is unusual, and hardware may not support it.
1055  *
1056  * Return: Zero on success, otherwise an error number.
1057  */
1058 static inline int ntb_db_set(struct ntb_dev *ntb, u64 db_bits)
1059 {
1060         if (!ntb->ops->db_set)
1061                 return -EINVAL;
1062
1063         return ntb->ops->db_set(ntb, db_bits);
1064 }
1065
1066 /**
1067  * ntb_db_clear() - clear bits in the local doorbell register
1068  * @ntb:        NTB device context.
1069  * @db_bits:    Doorbell bits to clear.
1070  *
1071  * Clear bits in the local doorbell register, arming the bits for the next
1072  * doorbell.
1073  *
1074  * Return: Zero on success, otherwise an error number.
1075  */
1076 static inline int ntb_db_clear(struct ntb_dev *ntb, u64 db_bits)
1077 {
1078         return ntb->ops->db_clear(ntb, db_bits);
1079 }
1080
1081 /**
1082  * ntb_db_read_mask() - read the local doorbell mask
1083  * @ntb:        NTB device context.
1084  *
1085  * Read the local doorbell mask register, and return the bits that are set.
1086  *
1087  * This is unusual, though hardware is likely to support it.
1088  *
1089  * Return: The bits currently set in the local doorbell mask register.
1090  */
1091 static inline u64 ntb_db_read_mask(struct ntb_dev *ntb)
1092 {
1093         if (!ntb->ops->db_read_mask)
1094                 return 0;
1095
1096         return ntb->ops->db_read_mask(ntb);
1097 }
1098
1099 /**
1100  * ntb_db_set_mask() - set bits in the local doorbell mask
1101  * @ntb:        NTB device context.
1102  * @db_bits:    Doorbell mask bits to set.
1103  *
1104  * Set bits in the local doorbell mask register, preventing doorbell interrupts
1105  * from being generated for those doorbell bits.  Bits that were already set
1106  * must remain set.
1107  *
1108  * Return: Zero on success, otherwise an error number.
1109  */
1110 static inline int ntb_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
1111 {
1112         return ntb->ops->db_set_mask(ntb, db_bits);
1113 }
1114
1115 /**
1116  * ntb_db_clear_mask() - clear bits in the local doorbell mask
1117  * @ntb:        NTB device context.
1118  * @db_bits:    Doorbell bits to clear.
1119  *
1120  * Clear bits in the local doorbell mask register, allowing doorbell interrupts
1121  * from being generated for those doorbell bits.  If a doorbell bit is already
1122  * set at the time the mask is cleared, and the corresponding mask bit is
1123  * changed from set to clear, then the ntb driver must ensure that
1124  * ntb_db_event() is called.  If the hardware does not generate the interrupt
1125  * on clearing the mask bit, then the driver must call ntb_db_event() anyway.
1126  *
1127  * Return: Zero on success, otherwise an error number.
1128  */
1129 static inline int ntb_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
1130 {
1131         return ntb->ops->db_clear_mask(ntb, db_bits);
1132 }
1133
1134 /**
1135  * ntb_peer_db_addr() - address and size of the peer doorbell register
1136  * @ntb:        NTB device context.
1137  * @db_addr:    OUT - The address of the peer doorbell register.
1138  * @db_size:    OUT - The number of bytes to write the peer doorbell register.
1139  * @db_data:    OUT - The data of peer doorbell register
1140  * @db_bit:             door bell bit number
1141  *
1142  * Return the address of the peer doorbell register.  This may be used, for
1143  * example, by drivers that offload memory copy operations to a dma engine.
1144  * The drivers may wish to ring the peer doorbell at the completion of memory
1145  * copy operations.  For efficiency, and to simplify ordering of operations
1146  * between the dma memory copies and the ringing doorbell, the driver may
1147  * append one additional dma memory copy with the doorbell register as the
1148  * destination, after the memory copy operations.
1149  *
1150  * Return: Zero on success, otherwise an error number.
1151  */
1152 static inline int ntb_peer_db_addr(struct ntb_dev *ntb,
1153                                    phys_addr_t *db_addr,
1154                                    resource_size_t *db_size,
1155                                    u64 *db_data, int db_bit)
1156 {
1157         if (!ntb->ops->peer_db_addr)
1158                 return -EINVAL;
1159
1160         return ntb->ops->peer_db_addr(ntb, db_addr, db_size, db_data, db_bit);
1161 }
1162
1163 /**
1164  * ntb_peer_db_read() - read the peer doorbell register
1165  * @ntb:        NTB device context.
1166  *
1167  * Read the peer doorbell register, and return the bits that are set.
1168  *
1169  * This is unusual, and hardware may not support it.
1170  *
1171  * Return: The bits currently set in the peer doorbell register.
1172  */
1173 static inline u64 ntb_peer_db_read(struct ntb_dev *ntb)
1174 {
1175         if (!ntb->ops->peer_db_read)
1176                 return 0;
1177
1178         return ntb->ops->peer_db_read(ntb);
1179 }
1180
1181 /**
1182  * ntb_peer_db_set() - set bits in the peer doorbell register
1183  * @ntb:        NTB device context.
1184  * @db_bits:    Doorbell bits to set.
1185  *
1186  * Set bits in the peer doorbell register, which may generate a peer doorbell
1187  * interrupt.  Bits that were already set must remain set.
1188  *
1189  * Return: Zero on success, otherwise an error number.
1190  */
1191 static inline int ntb_peer_db_set(struct ntb_dev *ntb, u64 db_bits)
1192 {
1193         return ntb->ops->peer_db_set(ntb, db_bits);
1194 }
1195
1196 /**
1197  * ntb_peer_db_clear() - clear bits in the peer doorbell register
1198  * @ntb:        NTB device context.
1199  * @db_bits:    Doorbell bits to clear.
1200  *
1201  * Clear bits in the peer doorbell register, arming the bits for the next
1202  * doorbell.
1203  *
1204  * This is unusual, and hardware may not support it.
1205  *
1206  * Return: Zero on success, otherwise an error number.
1207  */
1208 static inline int ntb_peer_db_clear(struct ntb_dev *ntb, u64 db_bits)
1209 {
1210         if (!ntb->ops->db_clear)
1211                 return -EINVAL;
1212
1213         return ntb->ops->peer_db_clear(ntb, db_bits);
1214 }
1215
1216 /**
1217  * ntb_peer_db_read_mask() - read the peer doorbell mask
1218  * @ntb:        NTB device context.
1219  *
1220  * Read the peer doorbell mask register, and return the bits that are set.
1221  *
1222  * This is unusual, and hardware may not support it.
1223  *
1224  * Return: The bits currently set in the peer doorbell mask register.
1225  */
1226 static inline u64 ntb_peer_db_read_mask(struct ntb_dev *ntb)
1227 {
1228         if (!ntb->ops->db_read_mask)
1229                 return 0;
1230
1231         return ntb->ops->peer_db_read_mask(ntb);
1232 }
1233
1234 /**
1235  * ntb_peer_db_set_mask() - set bits in the peer doorbell mask
1236  * @ntb:        NTB device context.
1237  * @db_bits:    Doorbell mask bits to set.
1238  *
1239  * Set bits in the peer doorbell mask register, preventing doorbell interrupts
1240  * from being generated for those doorbell bits.  Bits that were already set
1241  * must remain set.
1242  *
1243  * This is unusual, and hardware may not support it.
1244  *
1245  * Return: Zero on success, otherwise an error number.
1246  */
1247 static inline int ntb_peer_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
1248 {
1249         if (!ntb->ops->db_set_mask)
1250                 return -EINVAL;
1251
1252         return ntb->ops->peer_db_set_mask(ntb, db_bits);
1253 }
1254
1255 /**
1256  * ntb_peer_db_clear_mask() - clear bits in the peer doorbell mask
1257  * @ntb:        NTB device context.
1258  * @db_bits:    Doorbell bits to clear.
1259  *
1260  * Clear bits in the peer doorbell mask register, allowing doorbell interrupts
1261  * from being generated for those doorbell bits.  If the hardware does not
1262  * generate the interrupt on clearing the mask bit, then the driver should not
1263  * implement this function!
1264  *
1265  * This is unusual, and hardware may not support it.
1266  *
1267  * Return: Zero on success, otherwise an error number.
1268  */
1269 static inline int ntb_peer_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
1270 {
1271         if (!ntb->ops->db_clear_mask)
1272                 return -EINVAL;
1273
1274         return ntb->ops->peer_db_clear_mask(ntb, db_bits);
1275 }
1276
1277 /**
1278  * ntb_spad_is_unsafe() - check if it is safe to use the hardware scratchpads
1279  * @ntb:        NTB device context.
1280  *
1281  * It is possible for some ntb hardware to be affected by errata.  Hardware
1282  * drivers can advise clients to avoid using scratchpads.  Clients may ignore
1283  * this advice, though caution is recommended.
1284  *
1285  * Return: Zero if it is safe to use scratchpads, or One if it is not safe.
1286  */
1287 static inline int ntb_spad_is_unsafe(struct ntb_dev *ntb)
1288 {
1289         if (!ntb->ops->spad_is_unsafe)
1290                 return 0;
1291
1292         return ntb->ops->spad_is_unsafe(ntb);
1293 }
1294
1295 /**
1296  * ntb_spad_count() - get the number of scratchpads
1297  * @ntb:        NTB device context.
1298  *
1299  * Hardware and topology may support a different number of scratchpads.
1300  * Although it must be the same for all ports per NTB device.
1301  *
1302  * Return: the number of scratchpads.
1303  */
1304 static inline int ntb_spad_count(struct ntb_dev *ntb)
1305 {
1306         if (!ntb->ops->spad_count)
1307                 return 0;
1308
1309         return ntb->ops->spad_count(ntb);
1310 }
1311
1312 /**
1313  * ntb_spad_read() - read the local scratchpad register
1314  * @ntb:        NTB device context.
1315  * @sidx:       Scratchpad index.
1316  *
1317  * Read the local scratchpad register, and return the value.
1318  *
1319  * Return: The value of the local scratchpad register.
1320  */
1321 static inline u32 ntb_spad_read(struct ntb_dev *ntb, int sidx)
1322 {
1323         if (!ntb->ops->spad_read)
1324                 return ~(u32)0;
1325
1326         return ntb->ops->spad_read(ntb, sidx);
1327 }
1328
1329 /**
1330  * ntb_spad_write() - write the local scratchpad register
1331  * @ntb:        NTB device context.
1332  * @sidx:       Scratchpad index.
1333  * @val:        Scratchpad value.
1334  *
1335  * Write the value to the local scratchpad register.
1336  *
1337  * Return: Zero on success, otherwise an error number.
1338  */
1339 static inline int ntb_spad_write(struct ntb_dev *ntb, int sidx, u32 val)
1340 {
1341         if (!ntb->ops->spad_write)
1342                 return -EINVAL;
1343
1344         return ntb->ops->spad_write(ntb, sidx, val);
1345 }
1346
1347 /**
1348  * ntb_peer_spad_addr() - address of the peer scratchpad register
1349  * @ntb:        NTB device context.
1350  * @pidx:       Port index of peer device.
1351  * @sidx:       Scratchpad index.
1352  * @spad_addr:  OUT - The address of the peer scratchpad register.
1353  *
1354  * Return the address of the peer scratchpad register.  This may be used, for
1355  * example, by drivers that offload memory copy operations to a dma engine.
1356  *
1357  * Return: Zero on success, otherwise an error number.
1358  */
1359 static inline int ntb_peer_spad_addr(struct ntb_dev *ntb, int pidx, int sidx,
1360                                      phys_addr_t *spad_addr)
1361 {
1362         if (!ntb->ops->peer_spad_addr)
1363                 return -EINVAL;
1364
1365         return ntb->ops->peer_spad_addr(ntb, pidx, sidx, spad_addr);
1366 }
1367
1368 /**
1369  * ntb_peer_spad_read() - read the peer scratchpad register
1370  * @ntb:        NTB device context.
1371  * @pidx:       Port index of peer device.
1372  * @sidx:       Scratchpad index.
1373  *
1374  * Read the peer scratchpad register, and return the value.
1375  *
1376  * Return: The value of the peer scratchpad register.
1377  */
1378 static inline u32 ntb_peer_spad_read(struct ntb_dev *ntb, int pidx, int sidx)
1379 {
1380         if (!ntb->ops->peer_spad_read)
1381                 return ~(u32)0;
1382
1383         return ntb->ops->peer_spad_read(ntb, pidx, sidx);
1384 }
1385
1386 /**
1387  * ntb_peer_spad_write() - write the peer scratchpad register
1388  * @ntb:        NTB device context.
1389  * @pidx:       Port index of peer device.
1390  * @sidx:       Scratchpad index.
1391  * @val:        Scratchpad value.
1392  *
1393  * Write the value to the peer scratchpad register.
1394  *
1395  * Return: Zero on success, otherwise an error number.
1396  */
1397 static inline int ntb_peer_spad_write(struct ntb_dev *ntb, int pidx, int sidx,
1398                                       u32 val)
1399 {
1400         if (!ntb->ops->peer_spad_write)
1401                 return -EINVAL;
1402
1403         return ntb->ops->peer_spad_write(ntb, pidx, sidx, val);
1404 }
1405
1406 /**
1407  * ntb_msg_count() - get the number of message registers
1408  * @ntb:        NTB device context.
1409  *
1410  * Hardware may support a different number of message registers.
1411  *
1412  * Return: the number of message registers.
1413  */
1414 static inline int ntb_msg_count(struct ntb_dev *ntb)
1415 {
1416         if (!ntb->ops->msg_count)
1417                 return 0;
1418
1419         return ntb->ops->msg_count(ntb);
1420 }
1421
1422 /**
1423  * ntb_msg_inbits() - get a bitfield of inbound message registers status
1424  * @ntb:        NTB device context.
1425  *
1426  * The method returns the bitfield of status and mask registers, which related
1427  * to inbound message registers.
1428  *
1429  * Return: bitfield of inbound message registers.
1430  */
1431 static inline u64 ntb_msg_inbits(struct ntb_dev *ntb)
1432 {
1433         if (!ntb->ops->msg_inbits)
1434                 return 0;
1435
1436         return ntb->ops->msg_inbits(ntb);
1437 }
1438
1439 /**
1440  * ntb_msg_outbits() - get a bitfield of outbound message registers status
1441  * @ntb:        NTB device context.
1442  *
1443  * The method returns the bitfield of status and mask registers, which related
1444  * to outbound message registers.
1445  *
1446  * Return: bitfield of outbound message registers.
1447  */
1448 static inline u64 ntb_msg_outbits(struct ntb_dev *ntb)
1449 {
1450         if (!ntb->ops->msg_outbits)
1451                 return 0;
1452
1453         return ntb->ops->msg_outbits(ntb);
1454 }
1455
1456 /**
1457  * ntb_msg_read_sts() - read the message registers status
1458  * @ntb:        NTB device context.
1459  *
1460  * Read the status of message register. Inbound and outbound message registers
1461  * related bits can be filtered by masks retrieved from ntb_msg_inbits() and
1462  * ntb_msg_outbits().
1463  *
1464  * Return: status bits of message registers
1465  */
1466 static inline u64 ntb_msg_read_sts(struct ntb_dev *ntb)
1467 {
1468         if (!ntb->ops->msg_read_sts)
1469                 return 0;
1470
1471         return ntb->ops->msg_read_sts(ntb);
1472 }
1473
1474 /**
1475  * ntb_msg_clear_sts() - clear status bits of message registers
1476  * @ntb:        NTB device context.
1477  * @sts_bits:   Status bits to clear.
1478  *
1479  * Clear bits in the status register.
1480  *
1481  * Return: Zero on success, otherwise a negative error number.
1482  */
1483 static inline int ntb_msg_clear_sts(struct ntb_dev *ntb, u64 sts_bits)
1484 {
1485         if (!ntb->ops->msg_clear_sts)
1486                 return -EINVAL;
1487
1488         return ntb->ops->msg_clear_sts(ntb, sts_bits);
1489 }
1490
1491 /**
1492  * ntb_msg_set_mask() - set mask of message register status bits
1493  * @ntb:        NTB device context.
1494  * @mask_bits:  Mask bits.
1495  *
1496  * Mask the message registers status bits from raising the message event.
1497  *
1498  * Return: Zero on success, otherwise a negative error number.
1499  */
1500 static inline int ntb_msg_set_mask(struct ntb_dev *ntb, u64 mask_bits)
1501 {
1502         if (!ntb->ops->msg_set_mask)
1503                 return -EINVAL;
1504
1505         return ntb->ops->msg_set_mask(ntb, mask_bits);
1506 }
1507
1508 /**
1509  * ntb_msg_clear_mask() - clear message registers mask
1510  * @ntb:        NTB device context.
1511  * @mask_bits:  Mask bits to clear.
1512  *
1513  * Clear bits in the message events mask register.
1514  *
1515  * Return: Zero on success, otherwise a negative error number.
1516  */
1517 static inline int ntb_msg_clear_mask(struct ntb_dev *ntb, u64 mask_bits)
1518 {
1519         if (!ntb->ops->msg_clear_mask)
1520                 return -EINVAL;
1521
1522         return ntb->ops->msg_clear_mask(ntb, mask_bits);
1523 }
1524
1525 /**
1526  * ntb_msg_read() - read inbound message register with specified index
1527  * @ntb:        NTB device context.
1528  * @pidx:       OUT - Port index of peer device a message retrieved from
1529  * @midx:       Message register index
1530  *
1531  * Read data from the specified message register. Source port index of a
1532  * message is retrieved as well.
1533  *
1534  * Return: The value of the inbound message register.
1535  */
1536 static inline u32 ntb_msg_read(struct ntb_dev *ntb, int *pidx, int midx)
1537 {
1538         if (!ntb->ops->msg_read)
1539                 return ~(u32)0;
1540
1541         return ntb->ops->msg_read(ntb, pidx, midx);
1542 }
1543
1544 /**
1545  * ntb_peer_msg_write() - write data to the specified peer message register
1546  * @ntb:        NTB device context.
1547  * @pidx:       Port index of peer device a message being sent to
1548  * @midx:       Message register index
1549  * @msg:        Data to send
1550  *
1551  * Send data to a specified peer device using the defined message register.
1552  * Message event can be raised if the midx registers isn't empty while
1553  * calling this method and the corresponding interrupt isn't masked.
1554  *
1555  * Return: Zero on success, otherwise a negative error number.
1556  */
1557 static inline int ntb_peer_msg_write(struct ntb_dev *ntb, int pidx, int midx,
1558                                      u32 msg)
1559 {
1560         if (!ntb->ops->peer_msg_write)
1561                 return -EINVAL;
1562
1563         return ntb->ops->peer_msg_write(ntb, pidx, midx, msg);
1564 }
1565
1566 /**
1567  * ntb_peer_resource_idx() - get a resource index for a given peer idx
1568  * @ntb:        NTB device context.
1569  * @pidx:       Peer port index.
1570  *
1571  * When constructing a graph of peers, each remote peer must use a different
1572  * resource index (mw, doorbell, etc) to communicate with each other
1573  * peer.
1574  *
1575  * In a two peer system, this function should always return 0 such that
1576  * resource 0 points to the remote peer on both ports.
1577  *
1578  * In a 5 peer system, this function will return the following matrix
1579  *
1580  * pidx \ port    0    1    2    3    4
1581  * 0              0    0    1    2    3
1582  * 1              0    1    1    2    3
1583  * 2              0    1    2    2    3
1584  * 3              0    1    2    3    3
1585  *
1586  * For example, if this function is used to program peer's memory
1587  * windows, port 0 will program MW 0 on all it's peers to point to itself.
1588  * port 1 will program MW 0 in port 0 to point to itself and MW 1 on all
1589  * other ports. etc.
1590  *
1591  * For the legacy two host case, ntb_port_number() and ntb_peer_port_number()
1592  * both return zero and therefore this function will always return zero.
1593  * So MW 0 on each host would be programmed to point to the other host.
1594  *
1595  * Return: the resource index to use for that peer.
1596  */
1597 static inline int ntb_peer_resource_idx(struct ntb_dev *ntb, int pidx)
1598 {
1599         int local_port, peer_port;
1600
1601         if (pidx >= ntb_peer_port_count(ntb))
1602                 return -EINVAL;
1603
1604         local_port = ntb_logical_port_number(ntb);
1605         peer_port = ntb_peer_logical_port_number(ntb, pidx);
1606
1607         if (peer_port < local_port)
1608                 return local_port - 1;
1609         else
1610                 return local_port;
1611 }
1612
1613 /**
1614  * ntb_peer_highest_mw_idx() - get a memory window index for a given peer idx
1615  *      using the highest index memory windows first
1616  *
1617  * @ntb:        NTB device context.
1618  * @pidx:       Peer port index.
1619  *
1620  * Like ntb_peer_resource_idx(), except it returns indexes starting with
1621  * last memory window index.
1622  *
1623  * Return: the resource index to use for that peer.
1624  */
1625 static inline int ntb_peer_highest_mw_idx(struct ntb_dev *ntb, int pidx)
1626 {
1627         int ret;
1628
1629         ret = ntb_peer_resource_idx(ntb, pidx);
1630         if (ret < 0)
1631                 return ret;
1632
1633         return ntb_mw_count(ntb, pidx) - ret - 1;
1634 }
1635
1636 struct ntb_msi_desc {
1637         u32 addr_offset;
1638         u32 data;
1639 };
1640
1641 #ifdef CONFIG_NTB_MSI
1642
1643 int ntb_msi_init(struct ntb_dev *ntb, void (*desc_changed)(void *ctx));
1644 int ntb_msi_setup_mws(struct ntb_dev *ntb);
1645 void ntb_msi_clear_mws(struct ntb_dev *ntb);
1646 int ntbm_msi_request_threaded_irq(struct ntb_dev *ntb, irq_handler_t handler,
1647                                   irq_handler_t thread_fn,
1648                                   const char *name, void *dev_id,
1649                                   struct ntb_msi_desc *msi_desc);
1650 void ntbm_msi_free_irq(struct ntb_dev *ntb, unsigned int irq, void *dev_id);
1651 int ntb_msi_peer_trigger(struct ntb_dev *ntb, int peer,
1652                          struct ntb_msi_desc *desc);
1653 int ntb_msi_peer_addr(struct ntb_dev *ntb, int peer,
1654                       struct ntb_msi_desc *desc,
1655                       phys_addr_t *msi_addr);
1656
1657 #else /* not CONFIG_NTB_MSI */
1658
1659 static inline int ntb_msi_init(struct ntb_dev *ntb,
1660                                void (*desc_changed)(void *ctx))
1661 {
1662         return -EOPNOTSUPP;
1663 }
1664 static inline int ntb_msi_setup_mws(struct ntb_dev *ntb)
1665 {
1666         return -EOPNOTSUPP;
1667 }
1668 static inline void ntb_msi_clear_mws(struct ntb_dev *ntb) {}
1669 static inline int ntbm_msi_request_threaded_irq(struct ntb_dev *ntb,
1670                                                 irq_handler_t handler,
1671                                                 irq_handler_t thread_fn,
1672                                                 const char *name, void *dev_id,
1673                                                 struct ntb_msi_desc *msi_desc)
1674 {
1675         return -EOPNOTSUPP;
1676 }
1677 static inline void ntbm_msi_free_irq(struct ntb_dev *ntb, unsigned int irq,
1678                                      void *dev_id) {}
1679 static inline int ntb_msi_peer_trigger(struct ntb_dev *ntb, int peer,
1680                                        struct ntb_msi_desc *desc)
1681 {
1682         return -EOPNOTSUPP;
1683 }
1684 static inline int ntb_msi_peer_addr(struct ntb_dev *ntb, int peer,
1685                                     struct ntb_msi_desc *desc,
1686                                     phys_addr_t *msi_addr)
1687 {
1688         return -EOPNOTSUPP;
1689
1690 }
1691
1692 #endif /* CONFIG_NTB_MSI */
1693
1694 static inline int ntbm_msi_request_irq(struct ntb_dev *ntb,
1695                                        irq_handler_t handler,
1696                                        const char *name, void *dev_id,
1697                                        struct ntb_msi_desc *msi_desc)
1698 {
1699         return ntbm_msi_request_threaded_irq(ntb, handler, NULL, name,
1700                                              dev_id, msi_desc);
1701 }
1702
1703 #endif