sys/dev/ntb/ntb.h

   1 /*-
   2  * Copyright (c) 2016 Alexander Motin <mav@FreeBSD.org>
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24  * SUCH DAMAGE.
  25  *
  26  * $FreeBSD$
  27  */
  28
  29 #ifndef _NTB_H_
  30 #define _NTB_H_
  31
  32 #include "ntb_if.h"
  33
  34 extern devclass_t ntb_hw_devclass;
  35 SYSCTL_DECL(_hw_ntb);
  36
  37 int ntb_register_device(device_t ntb);
  38 int ntb_unregister_device(device_t ntb);
  39
  40 /*
  41  * ntb_link_event() - notify driver context of a change in link status
  42  * @ntb:        NTB device context
  43  *
  44  * Notify the driver context that the link status may have changed.  The driver
  45  * should call intb_link_is_up() to get the current status.
  46  */
  47 void ntb_link_event(device_t ntb);
  48
  49 /*
  50  * ntb_db_event() - notify driver context of a doorbell event
  51  * @ntb:        NTB device context
  52  * @vector:     Interrupt vector number
  53  *
  54  * Notify the driver context of a doorbell event.  If hardware supports
  55  * multiple interrupt vectors for doorbells, the vector number indicates which
  56  * vector received the interrupt.  The vector number is relative to the first
  57  * vector used for doorbells, starting at zero, and must be less than
  58  * ntb_db_vector_count().  The driver may call ntb_db_read() to check which
  59  * doorbell bits need service, and ntb_db_vector_mask() to determine which of
  60  * those bits are associated with the vector number.
  61  */
  62 void ntb_db_event(device_t ntb, uint32_t vec);
  63
  64 /*
  65  * ntb_link_is_up() - get the current ntb link state
  66  * @ntb:        NTB device context
  67  * @speed:      OUT - The link speed expressed as PCIe generation number
  68  * @width:      OUT - The link width expressed as the number of PCIe lanes
  69  *
  70  * RETURNS: true or false based on the hardware link state
  71  */
  72 bool ntb_link_is_up(device_t ntb, enum ntb_speed *speed, enum ntb_width *width);
  73
  74 /*
  75  * ntb_link_enable() - enable the link on the secondary side of the ntb
  76  * @ntb:        NTB device context
  77  * @max_speed:  The maximum link speed expressed as PCIe generation number[0]
  78  * @max_width:  The maximum link width expressed as the number of PCIe lanes[0]
  79  *
  80  * Enable the link on the secondary side of the ntb.  This can only be done
  81  * from the primary side of the ntb in primary or b2b topology.  The ntb device
  82  * should train the link to its maximum speed and width, or the requested speed
  83  * and width, whichever is smaller, if supported.
  84  *
  85  * Return: Zero on success, otherwise an error number.
  86  *
  87  * [0]: Only NTB_SPEED_AUTO and NTB_WIDTH_AUTO are valid inputs; other speed
  88  *      and width input will be ignored.
  89  */
  90 int ntb_link_enable(device_t ntb, enum ntb_speed speed, enum ntb_width width);
  91
  92 /*
  93  * ntb_link_disable() - disable the link on the secondary side of the ntb
  94  * @ntb:        NTB device context
  95  *
  96  * Disable the link on the secondary side of the ntb.  This can only be done
  97  * from the primary side of the ntb in primary or b2b topology.  The ntb device
  98  * should disable the link.  Returning from this call must indicate that a
  99  * barrier has passed, though with no more writes may pass in either direction
 100  * across the link, except if this call returns an error number.
 101  *
 102  * Return: Zero on success, otherwise an error number.
 103  */
 104 int ntb_link_disable(device_t ntb);
 105
 106 /*
 107  * get enable status of the link on the secondary side of the ntb
 108  */
 109 bool ntb_link_enabled(device_t ntb);
 110
 111 /*
 112  * ntb_set_ctx() - associate a driver context with an ntb device
 113  * @ntb:        NTB device context
 114  * @ctx:        Driver context
 115  * @ctx_ops:    Driver context operations
 116  *
 117  * Associate a driver context and operations with a ntb device.  The context is
 118  * provided by the client driver, and the driver may associate a different
 119  * context with each ntb device.
 120  *
 121  * Return: Zero if the context is associated, otherwise an error number.
 122  */
 123 int ntb_set_ctx(device_t ntb, void *ctx, const struct ntb_ctx_ops *ctx_ops);
 124
 125 /*
 126  * ntb_set_ctx() - get a driver context associated with an ntb device
 127  * @ntb:        NTB device context
 128  * @ctx_ops:    Driver context operations
 129  *
 130  * Get a driver context and operations associated with a ntb device.
 131  */
 132 void * ntb_get_ctx(device_t ntb, const struct ntb_ctx_ops **ctx_ops);
 133
 134 /*
 135  * ntb_clear_ctx() - disassociate any driver context from an ntb device
 136  * @ntb:        NTB device context
 137  *
 138  * Clear any association that may exist between a driver context and the ntb
 139  * device.
 140  */
 141 void ntb_clear_ctx(device_t ntb);
 142
 143 /*
 144  * ntb_mw_count() - Get the number of memory windows available for KPI
 145  * consumers.
 146  *
 147  * (Excludes any MW wholly reserved for register access.)
 148  */
 149 uint8_t ntb_mw_count(device_t ntb);
 150
 151 /*
 152  * ntb_mw_get_range() - get the range of a memory window
 153  * @ntb:        NTB device context
 154  * @idx:        Memory window number
 155  * @base:       OUT - the base address for mapping the memory window
 156  * @size:       OUT - the size for mapping the memory window
 157  * @align:      OUT - the base alignment for translating the memory window
 158  * @align_size: OUT - the size alignment for translating the memory window
 159  *
 160  * Get the range of a memory window.  NULL may be given for any output
 161  * parameter if the value is not needed.  The base and size may be used for
 162  * mapping the memory window, to access the peer memory.  The alignment and
 163  * size may be used for translating the memory window, for the peer to access
 164  * memory on the local system.
 165  *
 166  * Return: Zero on success, otherwise an error number.
 167  */
 168 int ntb_mw_get_range(device_t ntb, unsigned mw_idx, vm_paddr_t *base,
 169     caddr_t *vbase, size_t *size, size_t *align, size_t *align_size,
 170     bus_addr_t *plimit);
 171
 172 /*
 173  * ntb_mw_set_trans() - set the translation of a memory window
 174  * @ntb:        NTB device context
 175  * @idx:        Memory window number
 176  * @addr:       The dma address local memory to expose to the peer
 177  * @size:       The size of the local memory to expose to the peer
 178  *
 179  * Set the translation of a memory window.  The peer may access local memory
 180  * through the window starting at the address, up to the size.  The address
 181  * must be aligned to the alignment specified by ntb_mw_get_range().  The size
 182  * must be aligned to the size alignment specified by ntb_mw_get_range().  The
 183  * address must be below the plimit specified by ntb_mw_get_range() (i.e. for
 184  * 32-bit BARs).
 185  *
 186  * Return: Zero on success, otherwise an error number.
 187  */
 188 int ntb_mw_set_trans(device_t ntb, unsigned mw_idx, bus_addr_t addr,
 189     size_t size);
 190
 191 /*
 192  * ntb_mw_clear_trans() - clear the translation of a memory window
 193  * @ntb:        NTB device context
 194  * @idx:        Memory window number
 195  *
 196  * Clear the translation of a memory window.  The peer may no longer access
 197  * local memory through the window.
 198  *
 199  * Return: Zero on success, otherwise an error number.
 200  */
 201 int ntb_mw_clear_trans(device_t ntb, unsigned mw_idx);
 202
 203 /*
 204  * ntb_mw_get_wc - Get the write-combine status of a memory window
 205  *
 206  * Returns:  Zero on success, setting *wc; otherwise an error number (e.g. if
 207  * idx is an invalid memory window).
 208  *
 209  * Mode is a VM_MEMATTR_* type.
 210  */
 211 int ntb_mw_get_wc(device_t ntb, unsigned mw_idx, vm_memattr_t *mode);
 212
 213 /*
 214  * ntb_mw_set_wc - Set the write-combine status of a memory window
 215  *
 216  * If 'mode' matches the current status, this does nothing and succeeds.  Mode
 217  * is a VM_MEMATTR_* type.
 218  *
 219  * Returns:  Zero on success, setting the caching attribute on the virtual
 220  * mapping of the BAR; otherwise an error number (e.g. if idx is an invalid
 221  * memory window, or if changing the caching attribute fails).
 222  */
 223 int ntb_mw_set_wc(device_t ntb, unsigned mw_idx, vm_memattr_t mode);
 224
 225 /*
 226  * ntb_spad_count() - get the total scratch regs usable
 227  * @ntb: pointer to ntb_softc instance
 228  *
 229  * This function returns the max 32bit scratchpad registers usable by the
 230  * upper layer.
 231  *
 232  * RETURNS: total number of scratch pad registers available
 233  */
 234 uint8_t ntb_spad_count(device_t ntb);
 235
 236 /*
 237  * ntb_get_max_spads() - zero local scratch registers
 238  * @ntb: pointer to ntb_softc instance
 239  *
 240  * This functions overwrites all local scratchpad registers with zeroes.
 241  */
 242 void ntb_spad_clear(device_t ntb);
 243
 244 /*
 245  * ntb_spad_write() - write to the secondary scratchpad register
 246  * @ntb: pointer to ntb_softc instance
 247  * @idx: index to the scratchpad register, 0 based
 248  * @val: the data value to put into the register
 249  *
 250  * This function allows writing of a 32bit value to the indexed scratchpad
 251  * register. The register resides on the secondary (external) side.
 252  *
 253  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 254  */
 255 int ntb_spad_write(device_t ntb, unsigned int idx, uint32_t val);
 256
 257 /*
 258  * ntb_spad_read() - read from the primary scratchpad register
 259  * @ntb: pointer to ntb_softc instance
 260  * @idx: index to scratchpad register, 0 based
 261  * @val: pointer to 32bit integer for storing the register value
 262  *
 263  * This function allows reading of the 32bit scratchpad register on
 264  * the primary (internal) side.
 265  *
 266  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 267  */
 268 int ntb_spad_read(device_t ntb, unsigned int idx, uint32_t *val);
 269
 270 /*
 271  * ntb_peer_spad_write() - write to the secondary scratchpad register
 272  * @ntb: pointer to ntb_softc instance
 273  * @idx: index to the scratchpad register, 0 based
 274  * @val: the data value to put into the register
 275  *
 276  * This function allows writing of a 32bit value to the indexed scratchpad
 277  * register. The register resides on the secondary (external) side.
 278  *
 279  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 280  */
 281 int ntb_peer_spad_write(device_t ntb, unsigned int idx, uint32_t val);
 282
 283 /*
 284  * ntb_peer_spad_read() - read from the primary scratchpad register
 285  * @ntb: pointer to ntb_softc instance
 286  * @idx: index to scratchpad register, 0 based
 287  * @val: pointer to 32bit integer for storing the register value
 288  *
 289  * This function allows reading of the 32bit scratchpad register on
 290  * the primary (internal) side.
 291  *
 292  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 293  */
 294 int ntb_peer_spad_read(device_t ntb, unsigned int idx, uint32_t *val);
 295
 296 /*
 297  * ntb_db_valid_mask() - get a mask of doorbell bits supported by the ntb
 298  * @ntb:        NTB device context
 299  *
 300  * Hardware may support different number or arrangement of doorbell bits.
 301  *
 302  * Return: A mask of doorbell bits supported by the ntb.
 303  */
 304 uint64_t ntb_db_valid_mask(device_t ntb);
 305
 306 /*
 307  * ntb_db_vector_count() - get the number of doorbell interrupt vectors
 308  * @ntb:        NTB device context.
 309  *
 310  * Hardware may support different number of interrupt vectors.
 311  *
 312  * Return: The number of doorbell interrupt vectors.
 313  */
 314 int ntb_db_vector_count(device_t ntb);
 315
 316 /*
 317  * ntb_db_vector_mask() - get a mask of doorbell bits serviced by a vector
 318  * @ntb:        NTB device context
 319  * @vector:     Doorbell vector number
 320  *
 321  * Each interrupt vector may have a different number or arrangement of bits.
 322  *
 323  * Return: A mask of doorbell bits serviced by a vector.
 324  */
 325 uint64_t ntb_db_vector_mask(device_t ntb, uint32_t vector);
 326
 327 /*
 328  * ntb_peer_db_addr() - address and size of the peer doorbell register
 329  * @ntb:        NTB device context.
 330  * @db_addr:    OUT - The address of the peer doorbell register.
 331  * @db_size:    OUT - The number of bytes to write the peer doorbell register.
 332  *
 333  * Return the address of the peer doorbell register.  This may be used, for
 334  * example, by drivers that offload memory copy operations to a dma engine.
 335  * The drivers may wish to ring the peer doorbell at the completion of memory
 336  * copy operations.  For efficiency, and to simplify ordering of operations
 337  * between the dma memory copies and the ringing doorbell, the driver may
 338  * append one additional dma memory copy with the doorbell register as the
 339  * destination, after the memory copy operations.
 340  *
 341  * Return: Zero on success, otherwise an error number.
 342  *
 343  * Note that writing the peer doorbell via a memory window will *not* generate
 344  * an interrupt on the remote host; that must be done separately.
 345  */
 346 int ntb_peer_db_addr(device_t ntb, bus_addr_t *db_addr, vm_size_t *db_size);
 347
 348 /*
 349  * ntb_db_clear() - clear bits in the local doorbell register
 350  * @ntb:        NTB device context.
 351  * @db_bits:    Doorbell bits to clear.
 352  *
 353  * Clear bits in the local doorbell register, arming the bits for the next
 354  * doorbell.
 355  *
 356  * Return: Zero on success, otherwise an error number.
 357  */
 358 void ntb_db_clear(device_t ntb, uint64_t bits);
 359
 360 /*
 361  * ntb_db_clear_mask() - clear bits in the local doorbell mask
 362  * @ntb:        NTB device context.
 363  * @db_bits:    Doorbell bits to clear.
 364  *
 365  * Clear bits in the local doorbell mask register, allowing doorbell interrupts
 366  * from being generated for those doorbell bits.  If a doorbell bit is already
 367  * set at the time the mask is cleared, and the corresponding mask bit is
 368  * changed from set to clear, then the ntb driver must ensure that
 369  * ntb_db_event() is called.  If the hardware does not generate the interrupt
 370  * on clearing the mask bit, then the driver must call ntb_db_event() anyway.
 371  *
 372  * Return: Zero on success, otherwise an error number.
 373  */
 374 void ntb_db_clear_mask(device_t ntb, uint64_t bits);
 375
 376 /*
 377  * ntb_db_read() - read the local doorbell register
 378  * @ntb:        NTB device context.
 379  *
 380  * Read the local doorbell register, and return the bits that are set.
 381  *
 382  * Return: The bits currently set in the local doorbell register.
 383  */
 384 uint64_t ntb_db_read(device_t ntb);
 385
 386 /*
 387  * ntb_db_set_mask() - set bits in the local doorbell mask
 388  * @ntb:        NTB device context.
 389  * @db_bits:    Doorbell mask bits to set.
 390  *
 391  * Set bits in the local doorbell mask register, preventing doorbell interrupts
 392  * from being generated for those doorbell bits.  Bits that were already set
 393  * must remain set.
 394  *
 395  * Return: Zero on success, otherwise an error number.
 396  */
 397 void ntb_db_set_mask(device_t ntb, uint64_t bits);
 398
 399 /*
 400  * ntb_peer_db_set() - Set the doorbell on the secondary/external side
 401  * @ntb: pointer to ntb_softc instance
 402  * @bit: doorbell bits to ring
 403  *
 404  * This function allows triggering of a doorbell on the secondary/external
 405  * side that will initiate an interrupt on the remote host
 406  */
 407 void ntb_peer_db_set(device_t ntb, uint64_t bits);
 408
 409 #endif /* _NTB_H_ */