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