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