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