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 int ntb_child_location_str(device_t dev, device_t child, char *buf,
  40     size_t buflen);
  41 int ntb_print_child(device_t dev, device_t child);
  42
  43 /*
  44  * ntb_link_event() - notify driver context of a change in link status
  45  * @ntb:        NTB device context
  46  *
  47  * Notify the driver context that the link status may have changed.  The driver
  48  * should call intb_link_is_up() to get the current status.
  49  */
  50 void ntb_link_event(device_t ntb);
  51
  52 /*
  53  * ntb_db_event() - notify driver context of a doorbell event
  54  * @ntb:        NTB device context
  55  * @vector:     Interrupt vector number
  56  *
  57  * Notify the driver context of a doorbell event.  If hardware supports
  58  * multiple interrupt vectors for doorbells, the vector number indicates which
  59  * vector received the interrupt.  The vector number is relative to the first
  60  * vector used for doorbells, starting at zero, and must be less than
  61  * ntb_db_vector_count().  The driver may call ntb_db_read() to check which
  62  * doorbell bits need service, and ntb_db_vector_mask() to determine which of
  63  * those bits are associated with the vector number.
  64  */
  65 void ntb_db_event(device_t ntb, uint32_t vec);
  66
  67 /**
  68  * ntb_port_number() - get the local port number
  69  * @ntb:        NTB device context.
  70  *
  71  * Hardware driver returns local port number in compliance with topology.
  72  *
  73  * Return: the local port number
  74  */
  75 int ntb_port_number(device_t ntb);
  76
  77 /**
  78  * ntb_port_count() - get the number of peer device ports
  79  * @ntb:        NTB device context.
  80  *
  81  * By default hardware driver supports just one peer device.
  82  *
  83  * Return: the number of peer ports
  84  */
  85 int ntb_peer_port_count(device_t ntb);
  86
  87 /**
  88  * ntb_peer_port_number() - get the peer port by given index
  89  * @ntb:        NTB device context.
  90  * @idx:        Peer port index (should be zero for now).
  91  *
  92  * By default hardware driver supports just one peer device, so this method
  93  * shall return the corresponding value.
  94  *
  95  * Return: the peer device port or an error number
  96  */
  97 int ntb_peer_port_number(device_t ntb, int pidx);
  98
  99 /*
 100  * ntb_peer_port_idx() - get the peer device port index by given port
 101  *                       number
 102  * @ntb:        NTB device context.
 103  * @port:       Peer port number
 104  *
 105  * By default hardware driver supports just one peer device, so given a
 106  * valid peer port number, the return value shall be zero.
 107  *
 108  * Return: the peer port index or an error number
 109  */
 110 int ntb_peer_port_idx(device_t ntb, int port);
 111
 112 /*
 113  * ntb_link_is_up() - get the current ntb link state
 114  * @ntb:        NTB device context
 115  * @speed:      OUT - The link speed expressed as PCIe generation number
 116  * @width:      OUT - The link width expressed as the number of PCIe lanes
 117  *
 118  * RETURNS: true or false based on the hardware link state
 119  */
 120 bool ntb_link_is_up(device_t ntb, enum ntb_speed *speed, enum ntb_width *width);
 121
 122 /*
 123  * ntb_link_enable() - enable the link on the secondary side of the ntb
 124  * @ntb:        NTB device context
 125  * @max_speed:  The maximum link speed expressed as PCIe generation number[0]
 126  * @max_width:  The maximum link width expressed as the number of PCIe lanes[0]
 127  *
 128  * Enable the link on the secondary side of the ntb.  This can only be done
 129  * from the primary side of the ntb in primary or b2b topology.  The ntb device
 130  * should train the link to its maximum speed and width, or the requested speed
 131  * and width, whichever is smaller, if supported.
 132  *
 133  * Return: Zero on success, otherwise an error number.
 134  *
 135  * [0]: Only NTB_SPEED_AUTO and NTB_WIDTH_AUTO are valid inputs; other speed
 136  *      and width input will be ignored.
 137  */
 138 int ntb_link_enable(device_t ntb, enum ntb_speed speed, enum ntb_width width);
 139
 140 /*
 141  * ntb_link_disable() - disable the link on the secondary side of the ntb
 142  * @ntb:        NTB device context
 143  *
 144  * Disable the link on the secondary side of the ntb.  This can only be done
 145  * from the primary side of the ntb in primary or b2b topology.  The ntb device
 146  * should disable the link.  Returning from this call must indicate that a
 147  * barrier has passed, though with no more writes may pass in either direction
 148  * across the link, except if this call returns an error number.
 149  *
 150  * Return: Zero on success, otherwise an error number.
 151  */
 152 int ntb_link_disable(device_t ntb);
 153
 154 /*
 155  * get enable status of the link on the secondary side of the ntb
 156  */
 157 bool ntb_link_enabled(device_t ntb);
 158
 159 /*
 160  * ntb_set_ctx() - associate a driver context with an ntb device
 161  * @ntb:        NTB device context
 162  * @ctx:        Driver context
 163  * @ctx_ops:    Driver context operations
 164  *
 165  * Associate a driver context and operations with a ntb device.  The context is
 166  * provided by the client driver, and the driver may associate a different
 167  * context with each ntb device.
 168  *
 169  * Return: Zero if the context is associated, otherwise an error number.
 170  */
 171 int ntb_set_ctx(device_t ntb, void *ctx, const struct ntb_ctx_ops *ctx_ops);
 172
 173 /*
 174  * ntb_set_ctx() - get a driver context associated with an ntb device
 175  * @ntb:        NTB device context
 176  * @ctx_ops:    Driver context operations
 177  *
 178  * Get a driver context and operations associated with a ntb device.
 179  */
 180 void * ntb_get_ctx(device_t ntb, const struct ntb_ctx_ops **ctx_ops);
 181
 182 /*
 183  * ntb_clear_ctx() - disassociate any driver context from an ntb device
 184  * @ntb:        NTB device context
 185  *
 186  * Clear any association that may exist between a driver context and the ntb
 187  * device.
 188  */
 189 void ntb_clear_ctx(device_t ntb);
 190
 191 /*
 192  * ntb_mw_count() - Get the number of memory windows available for KPI
 193  * consumers.
 194  *
 195  * (Excludes any MW wholly reserved for register access.)
 196  */
 197 uint8_t ntb_mw_count(device_t ntb);
 198
 199 /*
 200  * ntb_mw_get_range() - get the range of a memory window
 201  * @ntb:        NTB device context
 202  * @idx:        Memory window number
 203  * @base:       OUT - the base address for mapping the memory window
 204  * @size:       OUT - the size for mapping the memory window
 205  * @align:      OUT - the base alignment for translating the memory window
 206  * @align_size: OUT - the size alignment for translating the memory window
 207  *
 208  * Get the range of a memory window.  NULL may be given for any output
 209  * parameter if the value is not needed.  The base and size may be used for
 210  * mapping the memory window, to access the peer memory.  The alignment and
 211  * size may be used for translating the memory window, for the peer to access
 212  * memory on the local system.
 213  *
 214  * Return: Zero on success, otherwise an error number.
 215  */
 216 int ntb_mw_get_range(device_t ntb, unsigned mw_idx, vm_paddr_t *base,
 217     caddr_t *vbase, size_t *size, size_t *align, size_t *align_size,
 218     bus_addr_t *plimit);
 219
 220 /*
 221  * ntb_mw_set_trans() - set the translation of a memory window
 222  * @ntb:        NTB device context
 223  * @idx:        Memory window number
 224  * @addr:       The dma address local memory to expose to the peer
 225  * @size:       The size of the local memory to expose to the peer
 226  *
 227  * Set the translation of a memory window.  The peer may access local memory
 228  * through the window starting at the address, up to the size.  The address
 229  * must be aligned to the alignment specified by ntb_mw_get_range().  The size
 230  * must be aligned to the size alignment specified by ntb_mw_get_range().  The
 231  * address must be below the plimit specified by ntb_mw_get_range() (i.e. for
 232  * 32-bit BARs).
 233  *
 234  * Return: Zero on success, otherwise an error number.
 235  */
 236 int ntb_mw_set_trans(device_t ntb, unsigned mw_idx, bus_addr_t addr,
 237     size_t size);
 238
 239 /*
 240  * ntb_mw_clear_trans() - clear the translation of a memory window
 241  * @ntb:        NTB device context
 242  * @idx:        Memory window number
 243  *
 244  * Clear the translation of a memory window.  The peer may no longer access
 245  * local memory through the window.
 246  *
 247  * Return: Zero on success, otherwise an error number.
 248  */
 249 int ntb_mw_clear_trans(device_t ntb, unsigned mw_idx);
 250
 251 /*
 252  * ntb_mw_get_wc - Get the write-combine status of a memory window
 253  *
 254  * Returns:  Zero on success, setting *wc; otherwise an error number (e.g. if
 255  * idx is an invalid memory window).
 256  *
 257  * Mode is a VM_MEMATTR_* type.
 258  */
 259 int ntb_mw_get_wc(device_t ntb, unsigned mw_idx, vm_memattr_t *mode);
 260
 261 /*
 262  * ntb_mw_set_wc - Set the write-combine status of a memory window
 263  *
 264  * If 'mode' matches the current status, this does nothing and succeeds.  Mode
 265  * is a VM_MEMATTR_* type.
 266  *
 267  * Returns:  Zero on success, setting the caching attribute on the virtual
 268  * mapping of the BAR; otherwise an error number (e.g. if idx is an invalid
 269  * memory window, or if changing the caching attribute fails).
 270  */
 271 int ntb_mw_set_wc(device_t ntb, unsigned mw_idx, vm_memattr_t mode);
 272
 273 /*
 274  * ntb_spad_count() - get the total scratch regs usable
 275  * @ntb: pointer to ntb_softc instance
 276  *
 277  * This function returns the max 32bit scratchpad registers usable by the
 278  * upper layer.
 279  *
 280  * RETURNS: total number of scratch pad registers available
 281  */
 282 uint8_t ntb_spad_count(device_t ntb);
 283
 284 /*
 285  * ntb_get_max_spads() - zero local scratch registers
 286  * @ntb: pointer to ntb_softc instance
 287  *
 288  * This functions overwrites all local scratchpad registers with zeroes.
 289  */
 290 void ntb_spad_clear(device_t ntb);
 291
 292 /*
 293  * ntb_spad_write() - write to the secondary scratchpad register
 294  * @ntb: pointer to ntb_softc instance
 295  * @idx: index to the scratchpad register, 0 based
 296  * @val: the data value to put into the register
 297  *
 298  * This function allows writing of a 32bit value to the indexed scratchpad
 299  * register. The register resides on the secondary (external) side.
 300  *
 301  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 302  */
 303 int ntb_spad_write(device_t ntb, unsigned int idx, uint32_t val);
 304
 305 /*
 306  * ntb_spad_read() - read from the primary scratchpad register
 307  * @ntb: pointer to ntb_softc instance
 308  * @idx: index to scratchpad register, 0 based
 309  * @val: pointer to 32bit integer for storing the register value
 310  *
 311  * This function allows reading of the 32bit scratchpad register on
 312  * the primary (internal) side.
 313  *
 314  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 315  */
 316 int ntb_spad_read(device_t ntb, unsigned int idx, uint32_t *val);
 317
 318 /*
 319  * ntb_peer_spad_write() - write to the secondary scratchpad register
 320  * @ntb: pointer to ntb_softc instance
 321  * @idx: index to the scratchpad register, 0 based
 322  * @val: the data value to put into the register
 323  *
 324  * This function allows writing of a 32bit value to the indexed scratchpad
 325  * register. The register resides on the secondary (external) side.
 326  *
 327  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 328  */
 329 int ntb_peer_spad_write(device_t ntb, unsigned int idx, uint32_t val);
 330
 331 /*
 332  * ntb_peer_spad_read() - read from the primary scratchpad register
 333  * @ntb: pointer to ntb_softc instance
 334  * @idx: index to scratchpad register, 0 based
 335  * @val: pointer to 32bit integer for storing the register value
 336  *
 337  * This function allows reading of the 32bit scratchpad register on
 338  * the primary (internal) side.
 339  *
 340  * RETURNS: An appropriate ERRNO error value on error, or zero for success.
 341  */
 342 int ntb_peer_spad_read(device_t ntb, unsigned int idx, uint32_t *val);
 343
 344 /*
 345  * ntb_db_valid_mask() - get a mask of doorbell bits supported by the ntb
 346  * @ntb:        NTB device context
 347  *
 348  * Hardware may support different number or arrangement of doorbell bits.
 349  *
 350  * Return: A mask of doorbell bits supported by the ntb.
 351  */
 352 uint64_t ntb_db_valid_mask(device_t ntb);
 353
 354 /*
 355  * ntb_db_vector_count() - get the number of doorbell interrupt vectors
 356  * @ntb:        NTB device context.
 357  *
 358  * Hardware may support different number of interrupt vectors.
 359  *
 360  * Return: The number of doorbell interrupt vectors.
 361  */
 362 int ntb_db_vector_count(device_t ntb);
 363
 364 /*
 365  * ntb_db_vector_mask() - get a mask of doorbell bits serviced by a vector
 366  * @ntb:        NTB device context
 367  * @vector:     Doorbell vector number
 368  *
 369  * Each interrupt vector may have a different number or arrangement of bits.
 370  *
 371  * Return: A mask of doorbell bits serviced by a vector.
 372  */
 373 uint64_t ntb_db_vector_mask(device_t ntb, uint32_t vector);
 374
 375 /*
 376  * ntb_peer_db_addr() - address and size of the peer doorbell register
 377  * @ntb:        NTB device context.
 378  * @db_addr:    OUT - The address of the peer doorbell register.
 379  * @db_size:    OUT - The number of bytes to write the peer doorbell register.
 380  *
 381  * Return the address of the peer doorbell register.  This may be used, for
 382  * example, by drivers that offload memory copy operations to a dma engine.
 383  * The drivers may wish to ring the peer doorbell at the completion of memory
 384  * copy operations.  For efficiency, and to simplify ordering of operations
 385  * between the dma memory copies and the ringing doorbell, the driver may
 386  * append one additional dma memory copy with the doorbell register as the
 387  * destination, after the memory copy operations.
 388  *
 389  * Return: Zero on success, otherwise an error number.
 390  *
 391  * Note that writing the peer doorbell via a memory window will *not* generate
 392  * an interrupt on the remote host; that must be done separately.
 393  */
 394 int ntb_peer_db_addr(device_t ntb, bus_addr_t *db_addr, vm_size_t *db_size);
 395
 396 /*
 397  * ntb_db_clear() - clear bits in the local doorbell register
 398  * @ntb:        NTB device context.
 399  * @db_bits:    Doorbell bits to clear.
 400  *
 401  * Clear bits in the local doorbell register, arming the bits for the next
 402  * doorbell.
 403  *
 404  * Return: Zero on success, otherwise an error number.
 405  */
 406 void ntb_db_clear(device_t ntb, uint64_t bits);
 407
 408 /*
 409  * ntb_db_clear_mask() - clear bits in the local doorbell mask
 410  * @ntb:        NTB device context.
 411  * @db_bits:    Doorbell bits to clear.
 412  *
 413  * Clear bits in the local doorbell mask register, allowing doorbell interrupts
 414  * from being generated for those doorbell bits.  If a doorbell bit is already
 415  * set at the time the mask is cleared, and the corresponding mask bit is
 416  * changed from set to clear, then the ntb driver must ensure that
 417  * ntb_db_event() is called.  If the hardware does not generate the interrupt
 418  * on clearing the mask bit, then the driver must call ntb_db_event() anyway.
 419  *
 420  * Return: Zero on success, otherwise an error number.
 421  */
 422 void ntb_db_clear_mask(device_t ntb, uint64_t bits);
 423
 424 /*
 425  * ntb_db_read() - read the local doorbell register
 426  * @ntb:        NTB device context.
 427  *
 428  * Read the local doorbell register, and return the bits that are set.
 429  *
 430  * Return: The bits currently set in the local doorbell register.
 431  */
 432 uint64_t ntb_db_read(device_t ntb);
 433
 434 /*
 435  * ntb_db_set_mask() - set bits in the local doorbell mask
 436  * @ntb:        NTB device context.
 437  * @db_bits:    Doorbell mask bits to set.
 438  *
 439  * Set bits in the local doorbell mask register, preventing doorbell interrupts
 440  * from being generated for those doorbell bits.  Bits that were already set
 441  * must remain set.
 442  *
 443  * Return: Zero on success, otherwise an error number.
 444  */
 445 void ntb_db_set_mask(device_t ntb, uint64_t bits);
 446
 447 /*
 448  * ntb_peer_db_set() - Set the doorbell on the secondary/external side
 449  * @ntb: pointer to ntb_softc instance
 450  * @bit: doorbell bits to ring
 451  *
 452  * This function allows triggering of a doorbell on the secondary/external
 453  * side that will initiate an interrupt on the remote host
 454  */
 455 void ntb_peer_db_set(device_t ntb, uint64_t bits);
 456
 457 #endif /* _NTB_H_ */