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  *
   9  *   This program is free software; you can redistribute it and/or modify
  10  *   it under the terms of version 2 of the GNU General Public License as
  11  *   published by the Free Software Foundation.
  12  *
  13  *   This program is distributed in the hope that it will be useful, but
  14  *   WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  *   General Public License for more details.
  17  *
  18  *   BSD LICENSE
  19  *
  20  *   Copyright (C) 2015 EMC Corporation. All Rights Reserved.
  21  *
  22  *   Redistribution and use in source and binary forms, with or without
  23  *   modification, are permitted provided that the following conditions
  24  *   are met:
  25  *
  26  *     * Redistributions of source code must retain the above copyright
  27  *       notice, this list of conditions and the following disclaimer.
  28  *     * Redistributions in binary form must reproduce the above copy
  29  *       notice, this list of conditions and the following disclaimer in
  30  *       the documentation and/or other materials provided with the
  31  *       distribution.
  32  *     * Neither the name of Intel Corporation nor the names of its
  33  *       contributors may be used to endorse or promote products derived
  34  *       from this software without specific prior written permission.
  35  *
  36  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  37  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  38  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  39  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  40  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  41  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  42  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  43  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  44  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  45  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  46  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  47  *
  48  * PCIe NTB Linux driver
  49  *
  50  * Contact Information:
  51  * Allen Hubbe <Allen.Hubbe@emc.com>
  52  */
  53
  54 #ifndef _NTB_H_
  55 #define _NTB_H_
  56
  57 #include <linux/completion.h>
  58 #include <linux/device.h>
  59
  60 struct ntb_client;
  61 struct ntb_dev;
  62 struct pci_dev;
  63
  64 /**
  65  * enum ntb_topo - NTB connection topology
  66  * @NTB_TOPO_NONE:      Topology is unknown or invalid.
  67  * @NTB_TOPO_PRI:       On primary side of local ntb.
  68  * @NTB_TOPO_SEC:       On secondary side of remote ntb.
  69  * @NTB_TOPO_B2B_USD:   On primary side of local ntb upstream of remote ntb.
  70  * @NTB_TOPO_B2B_DSD:   On primary side of local ntb downstream of remote ntb.
  71  */
  72 enum ntb_topo {
  73         NTB_TOPO_NONE = -1,
  74         NTB_TOPO_PRI,
  75         NTB_TOPO_SEC,
  76         NTB_TOPO_B2B_USD,
  77         NTB_TOPO_B2B_DSD,
  78 };
  79
  80 static inline int ntb_topo_is_b2b(enum ntb_topo topo)
  81 {
  82         switch ((int)topo) {
  83         case NTB_TOPO_B2B_USD:
  84         case NTB_TOPO_B2B_DSD:
  85                 return 1;
  86         }
  87         return 0;
  88 }
  89
  90 static inline char *ntb_topo_string(enum ntb_topo topo)
  91 {
  92         switch (topo) {
  93         case NTB_TOPO_NONE:     return "NTB_TOPO_NONE";
  94         case NTB_TOPO_PRI:      return "NTB_TOPO_PRI";
  95         case NTB_TOPO_SEC:      return "NTB_TOPO_SEC";
  96         case NTB_TOPO_B2B_USD:  return "NTB_TOPO_B2B_USD";
  97         case NTB_TOPO_B2B_DSD:  return "NTB_TOPO_B2B_DSD";
  98         }
  99         return "NTB_TOPO_INVALID";
 100 }
 101
 102 /**
 103  * enum ntb_speed - NTB link training speed
 104  * @NTB_SPEED_AUTO:     Request the max supported speed.
 105  * @NTB_SPEED_NONE:     Link is not trained to any speed.
 106  * @NTB_SPEED_GEN1:     Link is trained to gen1 speed.
 107  * @NTB_SPEED_GEN2:     Link is trained to gen2 speed.
 108  * @NTB_SPEED_GEN3:     Link is trained to gen3 speed.
 109  */
 110 enum ntb_speed {
 111         NTB_SPEED_AUTO = -1,
 112         NTB_SPEED_NONE = 0,
 113         NTB_SPEED_GEN1 = 1,
 114         NTB_SPEED_GEN2 = 2,
 115         NTB_SPEED_GEN3 = 3,
 116 };
 117
 118 /**
 119  * enum ntb_width - NTB link training width
 120  * @NTB_WIDTH_AUTO:     Request the max supported width.
 121  * @NTB_WIDTH_NONE:     Link is not trained to any width.
 122  * @NTB_WIDTH_1:        Link is trained to 1 lane width.
 123  * @NTB_WIDTH_2:        Link is trained to 2 lane width.
 124  * @NTB_WIDTH_4:        Link is trained to 4 lane width.
 125  * @NTB_WIDTH_8:        Link is trained to 8 lane width.
 126  * @NTB_WIDTH_12:       Link is trained to 12 lane width.
 127  * @NTB_WIDTH_16:       Link is trained to 16 lane width.
 128  * @NTB_WIDTH_32:       Link is trained to 32 lane width.
 129  */
 130 enum ntb_width {
 131         NTB_WIDTH_AUTO = -1,
 132         NTB_WIDTH_NONE = 0,
 133         NTB_WIDTH_1 = 1,
 134         NTB_WIDTH_2 = 2,
 135         NTB_WIDTH_4 = 4,
 136         NTB_WIDTH_8 = 8,
 137         NTB_WIDTH_12 = 12,
 138         NTB_WIDTH_16 = 16,
 139         NTB_WIDTH_32 = 32,
 140 };
 141
 142 /**
 143  * struct ntb_client_ops - ntb client operations
 144  * @probe:              Notify client of a new device.
 145  * @remove:             Notify client to remove a device.
 146  */
 147 struct ntb_client_ops {
 148         int (*probe)(struct ntb_client *client, struct ntb_dev *ntb);
 149         void (*remove)(struct ntb_client *client, struct ntb_dev *ntb);
 150 };
 151
 152 static inline int ntb_client_ops_is_valid(const struct ntb_client_ops *ops)
 153 {
 154         /* commented callbacks are not required: */
 155         return
 156                 ops->probe                      &&
 157                 ops->remove                     &&
 158                 1;
 159 }
 160
 161 /**
 162  * struct ntb_ctx_ops - ntb driver context operations
 163  * @link_event:         See ntb_link_event().
 164  * @db_event:           See ntb_db_event().
 165  */
 166 struct ntb_ctx_ops {
 167         void (*link_event)(void *ctx);
 168         void (*db_event)(void *ctx, int db_vector);
 169 };
 170
 171 static inline int ntb_ctx_ops_is_valid(const struct ntb_ctx_ops *ops)
 172 {
 173         /* commented callbacks are not required: */
 174         return
 175                 /* ops->link_event              && */
 176                 /* ops->db_event                && */
 177                 1;
 178 }
 179
 180 /**
 181  * struct ntb_ctx_ops - ntb device operations
 182  * @mw_count:           See ntb_mw_count().
 183  * @mw_get_range:       See ntb_mw_get_range().
 184  * @mw_set_trans:       See ntb_mw_set_trans().
 185  * @mw_clear_trans:     See ntb_mw_clear_trans().
 186  * @link_is_up:         See ntb_link_is_up().
 187  * @link_enable:        See ntb_link_enable().
 188  * @link_disable:       See ntb_link_disable().
 189  * @db_is_unsafe:       See ntb_db_is_unsafe().
 190  * @db_valid_mask:      See ntb_db_valid_mask().
 191  * @db_vector_count:    See ntb_db_vector_count().
 192  * @db_vector_mask:     See ntb_db_vector_mask().
 193  * @db_read:            See ntb_db_read().
 194  * @db_set:             See ntb_db_set().
 195  * @db_clear:           See ntb_db_clear().
 196  * @db_read_mask:       See ntb_db_read_mask().
 197  * @db_set_mask:        See ntb_db_set_mask().
 198  * @db_clear_mask:      See ntb_db_clear_mask().
 199  * @peer_db_addr:       See ntb_peer_db_addr().
 200  * @peer_db_read:       See ntb_peer_db_read().
 201  * @peer_db_set:        See ntb_peer_db_set().
 202  * @peer_db_clear:      See ntb_peer_db_clear().
 203  * @peer_db_read_mask:  See ntb_peer_db_read_mask().
 204  * @peer_db_set_mask:   See ntb_peer_db_set_mask().
 205  * @peer_db_clear_mask: See ntb_peer_db_clear_mask().
 206  * @spad_is_unsafe:     See ntb_spad_is_unsafe().
 207  * @spad_count:         See ntb_spad_count().
 208  * @spad_read:          See ntb_spad_read().
 209  * @spad_write:         See ntb_spad_write().
 210  * @peer_spad_addr:     See ntb_peer_spad_addr().
 211  * @peer_spad_read:     See ntb_peer_spad_read().
 212  * @peer_spad_write:    See ntb_peer_spad_write().
 213  */
 214 struct ntb_dev_ops {
 215         int (*mw_count)(struct ntb_dev *ntb);
 216         int (*mw_get_range)(struct ntb_dev *ntb, int idx,
 217                             phys_addr_t *base, resource_size_t *size,
 218                         resource_size_t *align, resource_size_t *align_size);
 219         int (*mw_set_trans)(struct ntb_dev *ntb, int idx,
 220                             dma_addr_t addr, resource_size_t size);
 221         int (*mw_clear_trans)(struct ntb_dev *ntb, int idx);
 222
 223         int (*link_is_up)(struct ntb_dev *ntb,
 224                           enum ntb_speed *speed, enum ntb_width *width);
 225         int (*link_enable)(struct ntb_dev *ntb,
 226                            enum ntb_speed max_speed, enum ntb_width max_width);
 227         int (*link_disable)(struct ntb_dev *ntb);
 228
 229         int (*db_is_unsafe)(struct ntb_dev *ntb);
 230         u64 (*db_valid_mask)(struct ntb_dev *ntb);
 231         int (*db_vector_count)(struct ntb_dev *ntb);
 232         u64 (*db_vector_mask)(struct ntb_dev *ntb, int db_vector);
 233
 234         u64 (*db_read)(struct ntb_dev *ntb);
 235         int (*db_set)(struct ntb_dev *ntb, u64 db_bits);
 236         int (*db_clear)(struct ntb_dev *ntb, u64 db_bits);
 237
 238         u64 (*db_read_mask)(struct ntb_dev *ntb);
 239         int (*db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
 240         int (*db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
 241
 242         int (*peer_db_addr)(struct ntb_dev *ntb,
 243                             phys_addr_t *db_addr, resource_size_t *db_size);
 244         u64 (*peer_db_read)(struct ntb_dev *ntb);
 245         int (*peer_db_set)(struct ntb_dev *ntb, u64 db_bits);
 246         int (*peer_db_clear)(struct ntb_dev *ntb, u64 db_bits);
 247
 248         u64 (*peer_db_read_mask)(struct ntb_dev *ntb);
 249         int (*peer_db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
 250         int (*peer_db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
 251
 252         int (*spad_is_unsafe)(struct ntb_dev *ntb);
 253         int (*spad_count)(struct ntb_dev *ntb);
 254
 255         u32 (*spad_read)(struct ntb_dev *ntb, int idx);
 256         int (*spad_write)(struct ntb_dev *ntb, int idx, u32 val);
 257
 258         int (*peer_spad_addr)(struct ntb_dev *ntb, int idx,
 259                               phys_addr_t *spad_addr);
 260         u32 (*peer_spad_read)(struct ntb_dev *ntb, int idx);
 261         int (*peer_spad_write)(struct ntb_dev *ntb, int idx, u32 val);
 262 };
 263
 264 static inline int ntb_dev_ops_is_valid(const struct ntb_dev_ops *ops)
 265 {
 266         /* commented callbacks are not required: */
 267         return
 268                 ops->mw_count                           &&
 269                 ops->mw_get_range                       &&
 270                 ops->mw_set_trans                       &&
 271                 /* ops->mw_clear_trans                  && */
 272                 ops->link_is_up                         &&
 273                 ops->link_enable                        &&
 274                 ops->link_disable                       &&
 275                 /* ops->db_is_unsafe                    && */
 276                 ops->db_valid_mask                      &&
 277
 278                 /* both set, or both unset */
 279                 (!ops->db_vector_count == !ops->db_vector_mask) &&
 280
 281                 ops->db_read                            &&
 282                 /* ops->db_set                          && */
 283                 ops->db_clear                           &&
 284                 /* ops->db_read_mask                    && */
 285                 ops->db_set_mask                        &&
 286                 ops->db_clear_mask                      &&
 287                 /* ops->peer_db_addr                    && */
 288                 /* ops->peer_db_read                    && */
 289                 ops->peer_db_set                        &&
 290                 /* ops->peer_db_clear                   && */
 291                 /* ops->peer_db_read_mask               && */
 292                 /* ops->peer_db_set_mask                && */
 293                 /* ops->peer_db_clear_mask              && */
 294                 /* ops->spad_is_unsafe                  && */
 295                 ops->spad_count                         &&
 296                 ops->spad_read                          &&
 297                 ops->spad_write                         &&
 298                 /* ops->peer_spad_addr                  && */
 299                 /* ops->peer_spad_read                  && */
 300                 ops->peer_spad_write                    &&
 301                 1;
 302 }
 303
 304 /**
 305  * struct ntb_client - client interested in ntb devices
 306  * @drv:                Linux driver object.
 307  * @ops:                See &ntb_client_ops.
 308  */
 309 struct ntb_client {
 310         struct device_driver            drv;
 311         const struct ntb_client_ops     ops;
 312 };
 313
 314 #define drv_ntb_client(__drv) container_of((__drv), struct ntb_client, drv)
 315
 316 /**
 317  * struct ntb_device - ntb device
 318  * @dev:                Linux device object.
 319  * @pdev:               Pci device entry of the ntb.
 320  * @topo:               Detected topology of the ntb.
 321  * @ops:                See &ntb_dev_ops.
 322  * @ctx:                See &ntb_ctx_ops.
 323  * @ctx_ops:            See &ntb_ctx_ops.
 324  */
 325 struct ntb_dev {
 326         struct device                   dev;
 327         struct pci_dev                  *pdev;
 328         enum ntb_topo                   topo;
 329         const struct ntb_dev_ops        *ops;
 330         void                            *ctx;
 331         const struct ntb_ctx_ops        *ctx_ops;
 332
 333         /* private: */
 334
 335         /* synchronize setting, clearing, and calling ctx_ops */
 336         spinlock_t                      ctx_lock;
 337         /* block unregister until device is fully released */
 338         struct completion               released;
 339 };
 340
 341 #define dev_ntb(__dev) container_of((__dev), struct ntb_dev, dev)
 342
 343 /**
 344  * ntb_register_client() - register a client for interest in ntb devices
 345  * @client:     Client context.
 346  *
 347  * The client will be added to the list of clients interested in ntb devices.
 348  * The client will be notified of any ntb devices that are not already
 349  * associated with a client, or if ntb devices are registered later.
 350  *
 351  * Return: Zero if the client is registered, otherwise an error number.
 352  */
 353 #define ntb_register_client(client) \
 354         __ntb_register_client((client), THIS_MODULE, KBUILD_MODNAME)
 355
 356 int __ntb_register_client(struct ntb_client *client, struct module *mod,
 357                           const char *mod_name);
 358
 359 /**
 360  * ntb_unregister_client() - unregister a client for interest in ntb devices
 361  * @client:     Client context.
 362  *
 363  * The client will be removed from the list of clients interested in ntb
 364  * devices.  If any ntb devices are associated with the client, the client will
 365  * be notified to remove those devices.
 366  */
 367 void ntb_unregister_client(struct ntb_client *client);
 368
 369 #define module_ntb_client(__ntb_client) \
 370         module_driver(__ntb_client, ntb_register_client, \
 371                         ntb_unregister_client)
 372
 373 /**
 374  * ntb_register_device() - register a ntb device
 375  * @ntb:        NTB device context.
 376  *
 377  * The device will be added to the list of ntb devices.  If any clients are
 378  * interested in ntb devices, each client will be notified of the ntb device,
 379  * until at most one client accepts the device.
 380  *
 381  * Return: Zero if the device is registered, otherwise an error number.
 382  */
 383 int ntb_register_device(struct ntb_dev *ntb);
 384
 385 /**
 386  * ntb_register_device() - unregister a ntb device
 387  * @ntb:        NTB device context.
 388  *
 389  * The device will be removed from the list of ntb devices.  If the ntb device
 390  * is associated with a client, the client will be notified to remove the
 391  * device.
 392  */
 393 void ntb_unregister_device(struct ntb_dev *ntb);
 394
 395 /**
 396  * ntb_set_ctx() - associate a driver context with an ntb device
 397  * @ntb:        NTB device context.
 398  * @ctx:        Driver context.
 399  * @ctx_ops:    Driver context operations.
 400  *
 401  * Associate a driver context and operations with a ntb device.  The context is
 402  * provided by the client driver, and the driver may associate a different
 403  * context with each ntb device.
 404  *
 405  * Return: Zero if the context is associated, otherwise an error number.
 406  */
 407 int ntb_set_ctx(struct ntb_dev *ntb, void *ctx,
 408                 const struct ntb_ctx_ops *ctx_ops);
 409
 410 /**
 411  * ntb_clear_ctx() - disassociate any driver context from an ntb device
 412  * @ntb:        NTB device context.
 413  *
 414  * Clear any association that may exist between a driver context and the ntb
 415  * device.
 416  */
 417 void ntb_clear_ctx(struct ntb_dev *ntb);
 418
 419 /**
 420  * ntb_link_event() - notify driver context of a change in link status
 421  * @ntb:        NTB device context.
 422  *
 423  * Notify the driver context that the link status may have changed.  The driver
 424  * should call ntb_link_is_up() to get the current status.
 425  */
 426 void ntb_link_event(struct ntb_dev *ntb);
 427
 428 /**
 429  * ntb_db_event() - notify driver context of a doorbell event
 430  * @ntb:        NTB device context.
 431  * @vector:     Interrupt vector number.
 432  *
 433  * Notify the driver context of a doorbell event.  If hardware supports
 434  * multiple interrupt vectors for doorbells, the vector number indicates which
 435  * vector received the interrupt.  The vector number is relative to the first
 436  * vector used for doorbells, starting at zero, and must be less than
 437  ** ntb_db_vector_count().  The driver may call ntb_db_read() to check which
 438  * doorbell bits need service, and ntb_db_vector_mask() to determine which of
 439  * those bits are associated with the vector number.
 440  */
 441 void ntb_db_event(struct ntb_dev *ntb, int vector);
 442
 443 /**
 444  * ntb_mw_count() - get the number of memory windows
 445  * @ntb:        NTB device context.
 446  *
 447  * Hardware and topology may support a different number of memory windows.
 448  *
 449  * Return: the number of memory windows.
 450  */
 451 static inline int ntb_mw_count(struct ntb_dev *ntb)
 452 {
 453         return ntb->ops->mw_count(ntb);
 454 }
 455
 456 /**
 457  * ntb_mw_get_range() - get the range of a memory window
 458  * @ntb:        NTB device context.
 459  * @idx:        Memory window number.
 460  * @base:       OUT - the base address for mapping the memory window
 461  * @size:       OUT - the size for mapping the memory window
 462  * @align:      OUT - the base alignment for translating the memory window
 463  * @align_size: OUT - the size alignment for translating the memory window
 464  *
 465  * Get the range of a memory window.  NULL may be given for any output
 466  * parameter if the value is not needed.  The base and size may be used for
 467  * mapping the memory window, to access the peer memory.  The alignment and
 468  * size may be used for translating the memory window, for the peer to access
 469  * memory on the local system.
 470  *
 471  * Return: Zero on success, otherwise an error number.
 472  */
 473 static inline int ntb_mw_get_range(struct ntb_dev *ntb, int idx,
 474                                    phys_addr_t *base, resource_size_t *size,
 475                 resource_size_t *align, resource_size_t *align_size)
 476 {
 477         return ntb->ops->mw_get_range(ntb, idx, base, size,
 478                         align, align_size);
 479 }
 480
 481 /**
 482  * ntb_mw_set_trans() - set the translation of a memory window
 483  * @ntb:        NTB device context.
 484  * @idx:        Memory window number.
 485  * @addr:       The dma address local memory to expose to the peer.
 486  * @size:       The size of the local memory to expose to the peer.
 487  *
 488  * Set the translation of a memory window.  The peer may access local memory
 489  * through the window starting at the address, up to the size.  The address
 490  * must be aligned to the alignment specified by ntb_mw_get_range().  The size
 491  * must be aligned to the size alignment specified by ntb_mw_get_range().
 492  *
 493  * Return: Zero on success, otherwise an error number.
 494  */
 495 static inline int ntb_mw_set_trans(struct ntb_dev *ntb, int idx,
 496                                    dma_addr_t addr, resource_size_t size)
 497 {
 498         return ntb->ops->mw_set_trans(ntb, idx, addr, size);
 499 }
 500
 501 /**
 502  * ntb_mw_clear_trans() - clear the translation of a memory window
 503  * @ntb:        NTB device context.
 504  * @idx:        Memory window number.
 505  *
 506  * Clear the translation of a memory window.  The peer may no longer access
 507  * local memory through the window.
 508  *
 509  * Return: Zero on success, otherwise an error number.
 510  */
 511 static inline int ntb_mw_clear_trans(struct ntb_dev *ntb, int idx)
 512 {
 513         if (!ntb->ops->mw_clear_trans)
 514                 return ntb->ops->mw_set_trans(ntb, idx, 0, 0);
 515
 516         return ntb->ops->mw_clear_trans(ntb, idx);
 517 }
 518
 519 /**
 520  * ntb_link_is_up() - get the current ntb link state
 521  * @ntb:        NTB device context.
 522  * @speed:      OUT - The link speed expressed as PCIe generation number.
 523  * @width:      OUT - The link width expressed as the number of PCIe lanes.
 524  *
 525  * Get the current state of the ntb link.  It is recommended to query the link
 526  * state once after every link event.  It is safe to query the link state in
 527  * the context of the link event callback.
 528  *
 529  * Return: One if the link is up, zero if the link is down, otherwise a
 530  *              negative value indicating the error number.
 531  */
 532 static inline int ntb_link_is_up(struct ntb_dev *ntb,
 533                                  enum ntb_speed *speed, enum ntb_width *width)
 534 {
 535         return ntb->ops->link_is_up(ntb, speed, width);
 536 }
 537
 538 /**
 539  * ntb_link_enable() - enable the link on the secondary side of the ntb
 540  * @ntb:        NTB device context.
 541  * @max_speed:  The maximum link speed expressed as PCIe generation number.
 542  * @max_width:  The maximum link width expressed as the number of PCIe lanes.
 543  *
 544  * Enable the link on the secondary side of the ntb.  This can only be done
 545  * from the primary side of the ntb in primary or b2b topology.  The ntb device
 546  * should train the link to its maximum speed and width, or the requested speed
 547  * and width, whichever is smaller, if supported.
 548  *
 549  * Return: Zero on success, otherwise an error number.
 550  */
 551 static inline int ntb_link_enable(struct ntb_dev *ntb,
 552                                   enum ntb_speed max_speed,
 553                                   enum ntb_width max_width)
 554 {
 555         return ntb->ops->link_enable(ntb, max_speed, max_width);
 556 }
 557
 558 /**
 559  * ntb_link_disable() - disable the link on the secondary side of the ntb
 560  * @ntb:        NTB device context.
 561  *
 562  * Disable the link on the secondary side of the ntb.  This can only be
 563  * done from the primary side of the ntb in primary or b2b topology.  The ntb
 564  * device should disable the link.  Returning from this call must indicate that
 565  * a barrier has passed, though with no more writes may pass in either
 566  * direction across the link, except if this call returns an error number.
 567  *
 568  * Return: Zero on success, otherwise an error number.
 569  */
 570 static inline int ntb_link_disable(struct ntb_dev *ntb)
 571 {
 572         return ntb->ops->link_disable(ntb);
 573 }
 574
 575 /**
 576  * ntb_db_is_unsafe() - check if it is safe to use hardware doorbell
 577  * @ntb:        NTB device context.
 578  *
 579  * It is possible for some ntb hardware to be affected by errata.  Hardware
 580  * drivers can advise clients to avoid using doorbells.  Clients may ignore
 581  * this advice, though caution is recommended.
 582  *
 583  * Return: Zero if it is safe to use doorbells, or One if it is not safe.
 584  */
 585 static inline int ntb_db_is_unsafe(struct ntb_dev *ntb)
 586 {
 587         if (!ntb->ops->db_is_unsafe)
 588                 return 0;
 589
 590         return ntb->ops->db_is_unsafe(ntb);
 591 }
 592
 593 /**
 594  * ntb_db_valid_mask() - get a mask of doorbell bits supported by the ntb
 595  * @ntb:        NTB device context.
 596  *
 597  * Hardware may support different number or arrangement of doorbell bits.
 598  *
 599  * Return: A mask of doorbell bits supported by the ntb.
 600  */
 601 static inline u64 ntb_db_valid_mask(struct ntb_dev *ntb)
 602 {
 603         return ntb->ops->db_valid_mask(ntb);
 604 }
 605
 606 /**
 607  * ntb_db_vector_count() - get the number of doorbell interrupt vectors
 608  * @ntb:        NTB device context.
 609  *
 610  * Hardware may support different number of interrupt vectors.
 611  *
 612  * Return: The number of doorbell interrupt vectors.
 613  */
 614 static inline int ntb_db_vector_count(struct ntb_dev *ntb)
 615 {
 616         if (!ntb->ops->db_vector_count)
 617                 return 1;
 618
 619         return ntb->ops->db_vector_count(ntb);
 620 }
 621
 622 /**
 623  * ntb_db_vector_mask() - get a mask of doorbell bits serviced by a vector
 624  * @ntb:        NTB device context.
 625  * @vector:     Doorbell vector number.
 626  *
 627  * Each interrupt vector may have a different number or arrangement of bits.
 628  *
 629  * Return: A mask of doorbell bits serviced by a vector.
 630  */
 631 static inline u64 ntb_db_vector_mask(struct ntb_dev *ntb, int vector)
 632 {
 633         if (!ntb->ops->db_vector_mask)
 634                 return ntb_db_valid_mask(ntb);
 635
 636         return ntb->ops->db_vector_mask(ntb, vector);
 637 }
 638
 639 /**
 640  * ntb_db_read() - read the local doorbell register
 641  * @ntb:        NTB device context.
 642  *
 643  * Read the local doorbell register, and return the bits that are set.
 644  *
 645  * Return: The bits currently set in the local doorbell register.
 646  */
 647 static inline u64 ntb_db_read(struct ntb_dev *ntb)
 648 {
 649         return ntb->ops->db_read(ntb);
 650 }
 651
 652 /**
 653  * ntb_db_set() - set bits in the local doorbell register
 654  * @ntb:        NTB device context.
 655  * @db_bits:    Doorbell bits to set.
 656  *
 657  * Set bits in the local doorbell register, which may generate a local doorbell
 658  * interrupt.  Bits that were already set must remain set.
 659  *
 660  * This is unusual, and hardware may not support it.
 661  *
 662  * Return: Zero on success, otherwise an error number.
 663  */
 664 static inline int ntb_db_set(struct ntb_dev *ntb, u64 db_bits)
 665 {
 666         if (!ntb->ops->db_set)
 667                 return -EINVAL;
 668
 669         return ntb->ops->db_set(ntb, db_bits);
 670 }
 671
 672 /**
 673  * ntb_db_clear() - clear bits in the local doorbell register
 674  * @ntb:        NTB device context.
 675  * @db_bits:    Doorbell bits to clear.
 676  *
 677  * Clear bits in the local doorbell register, arming the bits for the next
 678  * doorbell.
 679  *
 680  * Return: Zero on success, otherwise an error number.
 681  */
 682 static inline int ntb_db_clear(struct ntb_dev *ntb, u64 db_bits)
 683 {
 684         return ntb->ops->db_clear(ntb, db_bits);
 685 }
 686
 687 /**
 688  * ntb_db_read_mask() - read the local doorbell mask
 689  * @ntb:        NTB device context.
 690  *
 691  * Read the local doorbell mask register, and return the bits that are set.
 692  *
 693  * This is unusual, though hardware is likely to support it.
 694  *
 695  * Return: The bits currently set in the local doorbell mask register.
 696  */
 697 static inline u64 ntb_db_read_mask(struct ntb_dev *ntb)
 698 {
 699         if (!ntb->ops->db_read_mask)
 700                 return 0;
 701
 702         return ntb->ops->db_read_mask(ntb);
 703 }
 704
 705 /**
 706  * ntb_db_set_mask() - set bits in the local doorbell mask
 707  * @ntb:        NTB device context.
 708  * @db_bits:    Doorbell mask bits to set.
 709  *
 710  * Set bits in the local doorbell mask register, preventing doorbell interrupts
 711  * from being generated for those doorbell bits.  Bits that were already set
 712  * must remain set.
 713  *
 714  * Return: Zero on success, otherwise an error number.
 715  */
 716 static inline int ntb_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
 717 {
 718         return ntb->ops->db_set_mask(ntb, db_bits);
 719 }
 720
 721 /**
 722  * ntb_db_clear_mask() - clear bits in the local doorbell mask
 723  * @ntb:        NTB device context.
 724  * @db_bits:    Doorbell bits to clear.
 725  *
 726  * Clear bits in the local doorbell mask register, allowing doorbell interrupts
 727  * from being generated for those doorbell bits.  If a doorbell bit is already
 728  * set at the time the mask is cleared, and the corresponding mask bit is
 729  * changed from set to clear, then the ntb driver must ensure that
 730  * ntb_db_event() is called.  If the hardware does not generate the interrupt
 731  * on clearing the mask bit, then the driver must call ntb_db_event() anyway.
 732  *
 733  * Return: Zero on success, otherwise an error number.
 734  */
 735 static inline int ntb_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
 736 {
 737         return ntb->ops->db_clear_mask(ntb, db_bits);
 738 }
 739
 740 /**
 741  * ntb_peer_db_addr() - address and size of the peer doorbell register
 742  * @ntb:        NTB device context.
 743  * @db_addr:    OUT - The address of the peer doorbell register.
 744  * @db_size:    OUT - The number of bytes to write the peer doorbell register.
 745  *
 746  * Return the address of the peer doorbell register.  This may be used, for
 747  * example, by drivers that offload memory copy operations to a dma engine.
 748  * The drivers may wish to ring the peer doorbell at the completion of memory
 749  * copy operations.  For efficiency, and to simplify ordering of operations
 750  * between the dma memory copies and the ringing doorbell, the driver may
 751  * append one additional dma memory copy with the doorbell register as the
 752  * destination, after the memory copy operations.
 753  *
 754  * Return: Zero on success, otherwise an error number.
 755  */
 756 static inline int ntb_peer_db_addr(struct ntb_dev *ntb,
 757                                    phys_addr_t *db_addr,
 758                                    resource_size_t *db_size)
 759 {
 760         if (!ntb->ops->peer_db_addr)
 761                 return -EINVAL;
 762
 763         return ntb->ops->peer_db_addr(ntb, db_addr, db_size);
 764 }
 765
 766 /**
 767  * ntb_peer_db_read() - read the peer doorbell register
 768  * @ntb:        NTB device context.
 769  *
 770  * Read the peer doorbell register, and return the bits that are set.
 771  *
 772  * This is unusual, and hardware may not support it.
 773  *
 774  * Return: The bits currently set in the peer doorbell register.
 775  */
 776 static inline u64 ntb_peer_db_read(struct ntb_dev *ntb)
 777 {
 778         if (!ntb->ops->peer_db_read)
 779                 return 0;
 780
 781         return ntb->ops->peer_db_read(ntb);
 782 }
 783
 784 /**
 785  * ntb_peer_db_set() - set bits in the peer doorbell register
 786  * @ntb:        NTB device context.
 787  * @db_bits:    Doorbell bits to set.
 788  *
 789  * Set bits in the peer doorbell register, which may generate a peer doorbell
 790  * interrupt.  Bits that were already set must remain set.
 791  *
 792  * Return: Zero on success, otherwise an error number.
 793  */
 794 static inline int ntb_peer_db_set(struct ntb_dev *ntb, u64 db_bits)
 795 {
 796         return ntb->ops->peer_db_set(ntb, db_bits);
 797 }
 798
 799 /**
 800  * ntb_peer_db_clear() - clear bits in the peer doorbell register
 801  * @ntb:        NTB device context.
 802  * @db_bits:    Doorbell bits to clear.
 803  *
 804  * Clear bits in the peer doorbell register, arming the bits for the next
 805  * doorbell.
 806  *
 807  * This is unusual, and hardware may not support it.
 808  *
 809  * Return: Zero on success, otherwise an error number.
 810  */
 811 static inline int ntb_peer_db_clear(struct ntb_dev *ntb, u64 db_bits)
 812 {
 813         if (!ntb->ops->db_clear)
 814                 return -EINVAL;
 815
 816         return ntb->ops->peer_db_clear(ntb, db_bits);
 817 }
 818
 819 /**
 820  * ntb_peer_db_read_mask() - read the peer doorbell mask
 821  * @ntb:        NTB device context.
 822  *
 823  * Read the peer doorbell mask register, and return the bits that are set.
 824  *
 825  * This is unusual, and hardware may not support it.
 826  *
 827  * Return: The bits currently set in the peer doorbell mask register.
 828  */
 829 static inline u64 ntb_peer_db_read_mask(struct ntb_dev *ntb)
 830 {
 831         if (!ntb->ops->db_read_mask)
 832                 return 0;
 833
 834         return ntb->ops->peer_db_read_mask(ntb);
 835 }
 836
 837 /**
 838  * ntb_peer_db_set_mask() - set bits in the peer doorbell mask
 839  * @ntb:        NTB device context.
 840  * @db_bits:    Doorbell mask bits to set.
 841  *
 842  * Set bits in the peer doorbell mask register, preventing doorbell interrupts
 843  * from being generated for those doorbell bits.  Bits that were already set
 844  * must remain set.
 845  *
 846  * This is unusual, and hardware may not support it.
 847  *
 848  * Return: Zero on success, otherwise an error number.
 849  */
 850 static inline int ntb_peer_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
 851 {
 852         if (!ntb->ops->db_set_mask)
 853                 return -EINVAL;
 854
 855         return ntb->ops->peer_db_set_mask(ntb, db_bits);
 856 }
 857
 858 /**
 859  * ntb_peer_db_clear_mask() - clear bits in the peer doorbell mask
 860  * @ntb:        NTB device context.
 861  * @db_bits:    Doorbell bits to clear.
 862  *
 863  * Clear bits in the peer doorbell mask register, allowing doorbell interrupts
 864  * from being generated for those doorbell bits.  If the hardware does not
 865  * generate the interrupt on clearing the mask bit, then the driver should not
 866  * implement this function!
 867  *
 868  * This is unusual, and hardware may not support it.
 869  *
 870  * Return: Zero on success, otherwise an error number.
 871  */
 872 static inline int ntb_peer_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
 873 {
 874         if (!ntb->ops->db_clear_mask)
 875                 return -EINVAL;
 876
 877         return ntb->ops->peer_db_clear_mask(ntb, db_bits);
 878 }
 879
 880 /**
 881  * ntb_spad_is_unsafe() - check if it is safe to use the hardware scratchpads
 882  * @ntb:        NTB device context.
 883  *
 884  * It is possible for some ntb hardware to be affected by errata.  Hardware
 885  * drivers can advise clients to avoid using scratchpads.  Clients may ignore
 886  * this advice, though caution is recommended.
 887  *
 888  * Return: Zero if it is safe to use scratchpads, or One if it is not safe.
 889  */
 890 static inline int ntb_spad_is_unsafe(struct ntb_dev *ntb)
 891 {
 892         if (!ntb->ops->spad_is_unsafe)
 893                 return 0;
 894
 895         return ntb->ops->spad_is_unsafe(ntb);
 896 }
 897
 898 /**
 899  * ntb_spad_count() - get the number of scratchpads
 900  * @ntb:        NTB device context.
 901  *
 902  * Hardware and topology may support a different number of scratchpads.
 903  *
 904  * Return: the number of scratchpads.
 905  */
 906 static inline int ntb_spad_count(struct ntb_dev *ntb)
 907 {
 908         return ntb->ops->spad_count(ntb);
 909 }
 910
 911 /**
 912  * ntb_spad_read() - read the local scratchpad register
 913  * @ntb:        NTB device context.
 914  * @idx:        Scratchpad index.
 915  *
 916  * Read the local scratchpad register, and return the value.
 917  *
 918  * Return: The value of the local scratchpad register.
 919  */
 920 static inline u32 ntb_spad_read(struct ntb_dev *ntb, int idx)
 921 {
 922         return ntb->ops->spad_read(ntb, idx);
 923 }
 924
 925 /**
 926  * ntb_spad_write() - write the local scratchpad register
 927  * @ntb:        NTB device context.
 928  * @idx:        Scratchpad index.
 929  * @val:        Scratchpad value.
 930  *
 931  * Write the value to the local scratchpad register.
 932  *
 933  * Return: Zero on success, otherwise an error number.
 934  */
 935 static inline int ntb_spad_write(struct ntb_dev *ntb, int idx, u32 val)
 936 {
 937         return ntb->ops->spad_write(ntb, idx, val);
 938 }
 939
 940 /**
 941  * ntb_peer_spad_addr() - address of the peer scratchpad register
 942  * @ntb:        NTB device context.
 943  * @idx:        Scratchpad index.
 944  * @spad_addr:  OUT - The address of the peer scratchpad register.
 945  *
 946  * Return the address of the peer doorbell register.  This may be used, for
 947  * example, by drivers that offload memory copy operations to a dma engine.
 948  *
 949  * Return: Zero on success, otherwise an error number.
 950  */
 951 static inline int ntb_peer_spad_addr(struct ntb_dev *ntb, int idx,
 952                                      phys_addr_t *spad_addr)
 953 {
 954         if (!ntb->ops->peer_spad_addr)
 955                 return -EINVAL;
 956
 957         return ntb->ops->peer_spad_addr(ntb, idx, spad_addr);
 958 }
 959
 960 /**
 961  * ntb_peer_spad_read() - read the peer scratchpad register
 962  * @ntb:        NTB device context.
 963  * @idx:        Scratchpad index.
 964  *
 965  * Read the peer scratchpad register, and return the value.
 966  *
 967  * Return: The value of the local scratchpad register.
 968  */
 969 static inline u32 ntb_peer_spad_read(struct ntb_dev *ntb, int idx)
 970 {
 971         if (!ntb->ops->peer_spad_read)
 972                 return 0;
 973
 974         return ntb->ops->peer_spad_read(ntb, idx);
 975 }
 976
 977 /**
 978  * ntb_peer_spad_write() - write the peer scratchpad register
 979  * @ntb:        NTB device context.
 980  * @idx:        Scratchpad index.
 981  * @val:        Scratchpad value.
 982  *
 983  * Write the value to the peer scratchpad register.
 984  *
 985  * Return: Zero on success, otherwise an error number.
 986  */
 987 static inline int ntb_peer_spad_write(struct ntb_dev *ntb, int idx, u32 val)
 988 {
 989         return ntb->ops->peer_spad_write(ntb, idx, val);
 990 }
 991
 992 #endif