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