1302484Smav/*- 2302484Smav * Copyright (c) 2016 Alexander Motin <mav@FreeBSD.org> 3302484Smav * All rights reserved. 4302484Smav * 5302484Smav * Redistribution and use in source and binary forms, with or without 6302484Smav * modification, are permitted provided that the following conditions 7302484Smav * are met: 8302484Smav * 1. Redistributions of source code must retain the above copyright 9302484Smav * notice, this list of conditions and the following disclaimer. 10302484Smav * 2. Redistributions in binary form must reproduce the above copyright 11302484Smav * notice, this list of conditions and the following disclaimer in the 12302484Smav * documentation and/or other materials provided with the distribution. 13302484Smav * 14302484Smav * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15302484Smav * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16302484Smav * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17302484Smav * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18302484Smav * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19302484Smav * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20302484Smav * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21302484Smav * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22302484Smav * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23302484Smav * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24302484Smav * SUCH DAMAGE. 25302484Smav * 26302484Smav * $FreeBSD: stable/11/sys/dev/ntb/ntb.h 355152 2019-11-28 00:41:42Z mav $ 27302484Smav */ 28302484Smav 29302484Smav#ifndef _NTB_H_ 30302484Smav#define _NTB_H_ 31302484Smav 32302484Smav#include "ntb_if.h" 33302484Smav 34302484Smavextern devclass_t ntb_hw_devclass; 35302484SmavSYSCTL_DECL(_hw_ntb); 36302484Smav 37304367Smavint ntb_register_device(device_t ntb); 38304367Smavint ntb_unregister_device(device_t ntb); 39323455Smavint ntb_child_location_str(device_t dev, device_t child, char *buf, 40323455Smav size_t buflen); 41323455Smavint ntb_print_child(device_t dev, device_t child); 42355152Smavbus_dma_tag_t ntb_get_dma_tag(device_t bus, device_t child); 43304367Smav 44304367Smav/* 45304367Smav * ntb_link_event() - notify driver context of a change in link status 46304367Smav * @ntb: NTB device context 47304367Smav * 48304367Smav * Notify the driver context that the link status may have changed. The driver 49304367Smav * should call intb_link_is_up() to get the current status. 50304367Smav */ 51304367Smavvoid ntb_link_event(device_t ntb); 52304367Smav 53304367Smav/* 54304367Smav * ntb_db_event() - notify driver context of a doorbell event 55304367Smav * @ntb: NTB device context 56304367Smav * @vector: Interrupt vector number 57304367Smav * 58304367Smav * Notify the driver context of a doorbell event. If hardware supports 59304367Smav * multiple interrupt vectors for doorbells, the vector number indicates which 60304367Smav * vector received the interrupt. The vector number is relative to the first 61304367Smav * vector used for doorbells, starting at zero, and must be less than 62304367Smav * ntb_db_vector_count(). The driver may call ntb_db_read() to check which 63304367Smav * doorbell bits need service, and ntb_db_vector_mask() to determine which of 64304367Smav * those bits are associated with the vector number. 65304367Smav */ 66304367Smavvoid ntb_db_event(device_t ntb, uint32_t vec); 67304367Smav 68304367Smav/* 69304367Smav * ntb_link_is_up() - get the current ntb link state 70304367Smav * @ntb: NTB device context 71304367Smav * @speed: OUT - The link speed expressed as PCIe generation number 72304367Smav * @width: OUT - The link width expressed as the number of PCIe lanes 73304367Smav * 74304367Smav * RETURNS: true or false based on the hardware link state 75304367Smav */ 76304367Smavbool ntb_link_is_up(device_t ntb, enum ntb_speed *speed, enum ntb_width *width); 77304367Smav 78304367Smav/* 79304367Smav * ntb_link_enable() - enable the link on the secondary side of the ntb 80304367Smav * @ntb: NTB device context 81304367Smav * @max_speed: The maximum link speed expressed as PCIe generation number[0] 82304367Smav * @max_width: The maximum link width expressed as the number of PCIe lanes[0] 83304367Smav * 84304367Smav * Enable the link on the secondary side of the ntb. This can only be done 85304367Smav * from the primary side of the ntb in primary or b2b topology. The ntb device 86304367Smav * should train the link to its maximum speed and width, or the requested speed 87304367Smav * and width, whichever is smaller, if supported. 88304367Smav * 89304367Smav * Return: Zero on success, otherwise an error number. 90304367Smav * 91304367Smav * [0]: Only NTB_SPEED_AUTO and NTB_WIDTH_AUTO are valid inputs; other speed 92304367Smav * and width input will be ignored. 93304367Smav */ 94304367Smavint ntb_link_enable(device_t ntb, enum ntb_speed speed, enum ntb_width width); 95304367Smav 96304367Smav/* 97304367Smav * ntb_link_disable() - disable the link on the secondary side of the ntb 98304367Smav * @ntb: NTB device context 99304367Smav * 100304367Smav * Disable the link on the secondary side of the ntb. This can only be done 101304367Smav * from the primary side of the ntb in primary or b2b topology. The ntb device 102304367Smav * should disable the link. Returning from this call must indicate that a 103304367Smav * barrier has passed, though with no more writes may pass in either direction 104304367Smav * across the link, except if this call returns an error number. 105304367Smav * 106304367Smav * Return: Zero on success, otherwise an error number. 107304367Smav */ 108304367Smavint ntb_link_disable(device_t ntb); 109304367Smav 110304367Smav/* 111304367Smav * get enable status of the link on the secondary side of the ntb 112304367Smav */ 113304367Smavbool ntb_link_enabled(device_t ntb); 114304367Smav 115304367Smav/* 116304367Smav * ntb_set_ctx() - associate a driver context with an ntb device 117304367Smav * @ntb: NTB device context 118304367Smav * @ctx: Driver context 119304367Smav * @ctx_ops: Driver context operations 120304367Smav * 121304367Smav * Associate a driver context and operations with a ntb device. The context is 122304367Smav * provided by the client driver, and the driver may associate a different 123304367Smav * context with each ntb device. 124304367Smav * 125304367Smav * Return: Zero if the context is associated, otherwise an error number. 126304367Smav */ 127304367Smavint ntb_set_ctx(device_t ntb, void *ctx, const struct ntb_ctx_ops *ctx_ops); 128304367Smav 129304367Smav/* 130304367Smav * ntb_set_ctx() - get a driver context associated with an ntb device 131304367Smav * @ntb: NTB device context 132304367Smav * @ctx_ops: Driver context operations 133304367Smav * 134304367Smav * Get a driver context and operations associated with a ntb device. 135304367Smav */ 136304367Smavvoid * ntb_get_ctx(device_t ntb, const struct ntb_ctx_ops **ctx_ops); 137304367Smav 138304367Smav/* 139304367Smav * ntb_clear_ctx() - disassociate any driver context from an ntb device 140304367Smav * @ntb: NTB device context 141304367Smav * 142304367Smav * Clear any association that may exist between a driver context and the ntb 143304367Smav * device. 144304367Smav */ 145304367Smavvoid ntb_clear_ctx(device_t ntb); 146304367Smav 147304367Smav/* 148304367Smav * ntb_mw_count() - Get the number of memory windows available for KPI 149304367Smav * consumers. 150304367Smav * 151304367Smav * (Excludes any MW wholly reserved for register access.) 152304367Smav */ 153304367Smavuint8_t ntb_mw_count(device_t ntb); 154304367Smav 155304367Smav/* 156304367Smav * ntb_mw_get_range() - get the range of a memory window 157304367Smav * @ntb: NTB device context 158304367Smav * @idx: Memory window number 159304367Smav * @base: OUT - the base address for mapping the memory window 160304367Smav * @size: OUT - the size for mapping the memory window 161304367Smav * @align: OUT - the base alignment for translating the memory window 162304367Smav * @align_size: OUT - the size alignment for translating the memory window 163304367Smav * 164304367Smav * Get the range of a memory window. NULL may be given for any output 165304367Smav * parameter if the value is not needed. The base and size may be used for 166304367Smav * mapping the memory window, to access the peer memory. The alignment and 167304367Smav * size may be used for translating the memory window, for the peer to access 168304367Smav * memory on the local system. 169304367Smav * 170304367Smav * Return: Zero on success, otherwise an error number. 171304367Smav */ 172304367Smavint ntb_mw_get_range(device_t ntb, unsigned mw_idx, vm_paddr_t *base, 173304367Smav caddr_t *vbase, size_t *size, size_t *align, size_t *align_size, 174304367Smav bus_addr_t *plimit); 175304367Smav 176304367Smav/* 177304367Smav * ntb_mw_set_trans() - set the translation of a memory window 178304367Smav * @ntb: NTB device context 179304367Smav * @idx: Memory window number 180304367Smav * @addr: The dma address local memory to expose to the peer 181304367Smav * @size: The size of the local memory to expose to the peer 182304367Smav * 183304367Smav * Set the translation of a memory window. The peer may access local memory 184304367Smav * through the window starting at the address, up to the size. The address 185304367Smav * must be aligned to the alignment specified by ntb_mw_get_range(). The size 186304367Smav * must be aligned to the size alignment specified by ntb_mw_get_range(). The 187304367Smav * address must be below the plimit specified by ntb_mw_get_range() (i.e. for 188304367Smav * 32-bit BARs). 189304367Smav * 190304367Smav * Return: Zero on success, otherwise an error number. 191304367Smav */ 192304367Smavint ntb_mw_set_trans(device_t ntb, unsigned mw_idx, bus_addr_t addr, 193304367Smav size_t size); 194304367Smav 195304367Smav/* 196304367Smav * ntb_mw_clear_trans() - clear the translation of a memory window 197304367Smav * @ntb: NTB device context 198304367Smav * @idx: Memory window number 199304367Smav * 200304367Smav * Clear the translation of a memory window. The peer may no longer access 201304367Smav * local memory through the window. 202304367Smav * 203304367Smav * Return: Zero on success, otherwise an error number. 204304367Smav */ 205304367Smavint ntb_mw_clear_trans(device_t ntb, unsigned mw_idx); 206304367Smav 207304367Smav/* 208304367Smav * ntb_mw_get_wc - Get the write-combine status of a memory window 209304367Smav * 210304367Smav * Returns: Zero on success, setting *wc; otherwise an error number (e.g. if 211304367Smav * idx is an invalid memory window). 212304367Smav * 213304367Smav * Mode is a VM_MEMATTR_* type. 214304367Smav */ 215304367Smavint ntb_mw_get_wc(device_t ntb, unsigned mw_idx, vm_memattr_t *mode); 216304367Smav 217304367Smav/* 218304367Smav * ntb_mw_set_wc - Set the write-combine status of a memory window 219304367Smav * 220304367Smav * If 'mode' matches the current status, this does nothing and succeeds. Mode 221304367Smav * is a VM_MEMATTR_* type. 222304367Smav * 223304367Smav * Returns: Zero on success, setting the caching attribute on the virtual 224304367Smav * mapping of the BAR; otherwise an error number (e.g. if idx is an invalid 225304367Smav * memory window, or if changing the caching attribute fails). 226304367Smav */ 227304367Smavint ntb_mw_set_wc(device_t ntb, unsigned mw_idx, vm_memattr_t mode); 228304367Smav 229304367Smav/* 230304367Smav * ntb_spad_count() - get the total scratch regs usable 231304367Smav * @ntb: pointer to ntb_softc instance 232304367Smav * 233304367Smav * This function returns the max 32bit scratchpad registers usable by the 234304367Smav * upper layer. 235304367Smav * 236304367Smav * RETURNS: total number of scratch pad registers available 237304367Smav */ 238304367Smavuint8_t ntb_spad_count(device_t ntb); 239304367Smav 240304367Smav/* 241304367Smav * ntb_get_max_spads() - zero local scratch registers 242304367Smav * @ntb: pointer to ntb_softc instance 243304367Smav * 244304367Smav * This functions overwrites all local scratchpad registers with zeroes. 245304367Smav */ 246304367Smavvoid ntb_spad_clear(device_t ntb); 247304367Smav 248304367Smav/* 249304367Smav * ntb_spad_write() - write to the secondary scratchpad register 250304367Smav * @ntb: pointer to ntb_softc instance 251304367Smav * @idx: index to the scratchpad register, 0 based 252304367Smav * @val: the data value to put into the register 253304367Smav * 254304367Smav * This function allows writing of a 32bit value to the indexed scratchpad 255304367Smav * register. The register resides on the secondary (external) side. 256304367Smav * 257304367Smav * RETURNS: An appropriate ERRNO error value on error, or zero for success. 258304367Smav */ 259304367Smavint ntb_spad_write(device_t ntb, unsigned int idx, uint32_t val); 260304367Smav 261304367Smav/* 262304367Smav * ntb_spad_read() - read from the primary scratchpad register 263304367Smav * @ntb: pointer to ntb_softc instance 264304367Smav * @idx: index to scratchpad register, 0 based 265304367Smav * @val: pointer to 32bit integer for storing the register value 266304367Smav * 267304367Smav * This function allows reading of the 32bit scratchpad register on 268304367Smav * the primary (internal) side. 269304367Smav * 270304367Smav * RETURNS: An appropriate ERRNO error value on error, or zero for success. 271304367Smav */ 272304367Smavint ntb_spad_read(device_t ntb, unsigned int idx, uint32_t *val); 273304367Smav 274304367Smav/* 275304367Smav * ntb_peer_spad_write() - write to the secondary scratchpad register 276304367Smav * @ntb: pointer to ntb_softc instance 277304367Smav * @idx: index to the scratchpad register, 0 based 278304367Smav * @val: the data value to put into the register 279304367Smav * 280304367Smav * This function allows writing of a 32bit value to the indexed scratchpad 281304367Smav * register. The register resides on the secondary (external) side. 282304367Smav * 283304367Smav * RETURNS: An appropriate ERRNO error value on error, or zero for success. 284304367Smav */ 285304367Smavint ntb_peer_spad_write(device_t ntb, unsigned int idx, uint32_t val); 286304367Smav 287304367Smav/* 288304367Smav * ntb_peer_spad_read() - read from the primary scratchpad register 289304367Smav * @ntb: pointer to ntb_softc instance 290304367Smav * @idx: index to scratchpad register, 0 based 291304367Smav * @val: pointer to 32bit integer for storing the register value 292304367Smav * 293304367Smav * This function allows reading of the 32bit scratchpad register on 294304367Smav * the primary (internal) side. 295304367Smav * 296304367Smav * RETURNS: An appropriate ERRNO error value on error, or zero for success. 297304367Smav */ 298304367Smavint ntb_peer_spad_read(device_t ntb, unsigned int idx, uint32_t *val); 299304367Smav 300304367Smav/* 301304367Smav * ntb_db_valid_mask() - get a mask of doorbell bits supported by the ntb 302304367Smav * @ntb: NTB device context 303304367Smav * 304304367Smav * Hardware may support different number or arrangement of doorbell bits. 305304367Smav * 306304367Smav * Return: A mask of doorbell bits supported by the ntb. 307304367Smav */ 308304367Smavuint64_t ntb_db_valid_mask(device_t ntb); 309304367Smav 310304367Smav/* 311304367Smav * ntb_db_vector_count() - get the number of doorbell interrupt vectors 312304367Smav * @ntb: NTB device context. 313304367Smav * 314304367Smav * Hardware may support different number of interrupt vectors. 315304367Smav * 316304367Smav * Return: The number of doorbell interrupt vectors. 317304367Smav */ 318304367Smavint ntb_db_vector_count(device_t ntb); 319304367Smav 320304367Smav/* 321304367Smav * ntb_db_vector_mask() - get a mask of doorbell bits serviced by a vector 322304367Smav * @ntb: NTB device context 323304367Smav * @vector: Doorbell vector number 324304367Smav * 325304367Smav * Each interrupt vector may have a different number or arrangement of bits. 326304367Smav * 327304367Smav * Return: A mask of doorbell bits serviced by a vector. 328304367Smav */ 329304367Smavuint64_t ntb_db_vector_mask(device_t ntb, uint32_t vector); 330304367Smav 331304367Smav/* 332304367Smav * ntb_peer_db_addr() - address and size of the peer doorbell register 333304367Smav * @ntb: NTB device context. 334304367Smav * @db_addr: OUT - The address of the peer doorbell register. 335304367Smav * @db_size: OUT - The number of bytes to write the peer doorbell register. 336304367Smav * 337304367Smav * Return the address of the peer doorbell register. This may be used, for 338304367Smav * example, by drivers that offload memory copy operations to a dma engine. 339304367Smav * The drivers may wish to ring the peer doorbell at the completion of memory 340304367Smav * copy operations. For efficiency, and to simplify ordering of operations 341304367Smav * between the dma memory copies and the ringing doorbell, the driver may 342304367Smav * append one additional dma memory copy with the doorbell register as the 343304367Smav * destination, after the memory copy operations. 344304367Smav * 345304367Smav * Return: Zero on success, otherwise an error number. 346304367Smav * 347304367Smav * Note that writing the peer doorbell via a memory window will *not* generate 348304367Smav * an interrupt on the remote host; that must be done separately. 349304367Smav */ 350304367Smavint ntb_peer_db_addr(device_t ntb, bus_addr_t *db_addr, vm_size_t *db_size); 351304367Smav 352304367Smav/* 353304367Smav * ntb_db_clear() - clear bits in the local doorbell register 354304367Smav * @ntb: NTB device context. 355304367Smav * @db_bits: Doorbell bits to clear. 356304367Smav * 357304367Smav * Clear bits in the local doorbell register, arming the bits for the next 358304367Smav * doorbell. 359304367Smav * 360304367Smav * Return: Zero on success, otherwise an error number. 361304367Smav */ 362304367Smavvoid ntb_db_clear(device_t ntb, uint64_t bits); 363304367Smav 364304367Smav/* 365304367Smav * ntb_db_clear_mask() - clear bits in the local doorbell mask 366304367Smav * @ntb: NTB device context. 367304367Smav * @db_bits: Doorbell bits to clear. 368304367Smav * 369304367Smav * Clear bits in the local doorbell mask register, allowing doorbell interrupts 370304367Smav * from being generated for those doorbell bits. If a doorbell bit is already 371304367Smav * set at the time the mask is cleared, and the corresponding mask bit is 372304367Smav * changed from set to clear, then the ntb driver must ensure that 373304367Smav * ntb_db_event() is called. If the hardware does not generate the interrupt 374304367Smav * on clearing the mask bit, then the driver must call ntb_db_event() anyway. 375304367Smav * 376304367Smav * Return: Zero on success, otherwise an error number. 377304367Smav */ 378304367Smavvoid ntb_db_clear_mask(device_t ntb, uint64_t bits); 379304367Smav 380304367Smav/* 381304367Smav * ntb_db_read() - read the local doorbell register 382304367Smav * @ntb: NTB device context. 383304367Smav * 384304367Smav * Read the local doorbell register, and return the bits that are set. 385304367Smav * 386304367Smav * Return: The bits currently set in the local doorbell register. 387304367Smav */ 388304367Smavuint64_t ntb_db_read(device_t ntb); 389304367Smav 390304367Smav/* 391304367Smav * ntb_db_set_mask() - set bits in the local doorbell mask 392304367Smav * @ntb: NTB device context. 393304367Smav * @db_bits: Doorbell mask bits to set. 394304367Smav * 395304367Smav * Set bits in the local doorbell mask register, preventing doorbell interrupts 396304367Smav * from being generated for those doorbell bits. Bits that were already set 397304367Smav * must remain set. 398304367Smav * 399304367Smav * Return: Zero on success, otherwise an error number. 400304367Smav */ 401304367Smavvoid ntb_db_set_mask(device_t ntb, uint64_t bits); 402304367Smav 403304367Smav/* 404304367Smav * ntb_peer_db_set() - Set the doorbell on the secondary/external side 405304367Smav * @ntb: pointer to ntb_softc instance 406304367Smav * @bit: doorbell bits to ring 407304367Smav * 408304367Smav * This function allows triggering of a doorbell on the secondary/external 409304367Smav * side that will initiate an interrupt on the remote host 410304367Smav */ 411304367Smavvoid ntb_peer_db_set(device_t ntb, uint64_t bits); 412304367Smav 413302484Smav#endif /* _NTB_H_ */ 414