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