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
32SYSCTL_DECL(_hw_ntb);
33
34int ntb_register_device(device_t ntb);
35int ntb_unregister_device(device_t ntb);
36int ntb_child_location(device_t dev, device_t child, struct sbuf *sb);
37int ntb_print_child(device_t dev, device_t child);
38bus_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 */
47void 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 */
62void 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 */
72int 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 */
82int 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 */
94int 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 */
107int 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 */
117bool 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 */
135int 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 */
149int ntb_link_disable(device_t ntb);
150
151/*
152 * get enable status of the link on the secondary side of the ntb
153 */
154bool 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 */
168int 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 */
177void * 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 */
186void 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 */
194uint8_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 */
213int 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 */
233int 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 */
246int 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 */
256int 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 */
268int 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 */
279uint8_t ntb_spad_count(device_t ntb);
280
281/*
282 * ntb_spad_clear() - zero local scratch registers
283 * @ntb: pointer to ntb_softc instance
284 *
285 * This functions overwrites all local scratchpad registers with zeroes.
286 */
287void 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 */
300int 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 */
313int 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 */
326int 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 */
339int 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 */
349uint64_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 */
359int 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 */
370uint64_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 */
391int 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 */
403void 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 */
419void 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 */
429uint64_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 */
442void 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 */
452void ntb_peer_db_set(device_t ntb, uint64_t bits);
453
454#endif /* _NTB_H_ */
455