Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1/*
2 * This file is provided under a dual BSD/GPLv2 license. When using or
3 * redistributing this file, you may do so under either license.
4 *
5 * GPL LICENSE SUMMARY
6 *
7 * Copyright (C) 2015 EMC Corporation. All Rights Reserved.
8 * Copyright (C) 2016 T-Platforms. All Rights Reserved.
9 *
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of version 2 of the GNU General Public License as
12 * published by the Free Software Foundation.
13 *
14 * This program is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * General Public License for more details.
18 *
19 * BSD LICENSE
20 *
21 * Copyright (C) 2015 EMC Corporation. All Rights Reserved.
22 * Copyright (C) 2016 T-Platforms. All Rights Reserved.
23 *
24 * Redistribution and use in source and binary forms, with or without
25 * modification, are permitted provided that the following conditions
26 * are met:
27 *
28 * * Redistributions of source code must retain the above copyright
29 * notice, this list of conditions and the following disclaimer.
30 * * Redistributions in binary form must reproduce the above copy
31 * notice, this list of conditions and the following disclaimer in
32 * the documentation and/or other materials provided with the
33 * distribution.
34 * * Neither the name of Intel Corporation nor the names of its
35 * contributors may be used to endorse or promote products derived
36 * from this software without specific prior written permission.
37 *
38 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
39 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
40 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
41 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
42 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
44 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
45 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
46 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
47 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
48 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
49 *
50 * PCIe NTB Linux driver
51 *
52 * Contact Information:
53 * Allen Hubbe <Allen.Hubbe@emc.com>
54 */
55
56#ifndef _NTB_H_
57#define _NTB_H_
58
59#include <linux/completion.h>
60#include <linux/device.h>
61#include <linux/interrupt.h>
62
63struct ntb_client;
64struct ntb_dev;
65struct ntb_msi;
66struct pci_dev;
67
68/**
69 * enum ntb_topo - NTB connection topology
70 * @NTB_TOPO_NONE: Topology is unknown or invalid.
71 * @NTB_TOPO_PRI: On primary side of local ntb.
72 * @NTB_TOPO_SEC: On secondary side of remote ntb.
73 * @NTB_TOPO_B2B_USD: On primary side of local ntb upstream of remote ntb.
74 * @NTB_TOPO_B2B_DSD: On primary side of local ntb downstream of remote ntb.
75 * @NTB_TOPO_SWITCH: Connected via a switch which supports ntb.
76 * @NTB_TOPO_CROSSLINK: Connected via two symmetric switchecs
77 */
78enum ntb_topo {
79 NTB_TOPO_NONE = -1,
80 NTB_TOPO_PRI,
81 NTB_TOPO_SEC,
82 NTB_TOPO_B2B_USD,
83 NTB_TOPO_B2B_DSD,
84 NTB_TOPO_SWITCH,
85 NTB_TOPO_CROSSLINK,
86};
87
88static inline int ntb_topo_is_b2b(enum ntb_topo topo)
89{
90 switch ((int)topo) {
91 case NTB_TOPO_B2B_USD:
92 case NTB_TOPO_B2B_DSD:
93 return 1;
94 }
95 return 0;
96}
97
98static inline char *ntb_topo_string(enum ntb_topo topo)
99{
100 switch (topo) {
101 case NTB_TOPO_NONE: return "NTB_TOPO_NONE";
102 case NTB_TOPO_PRI: return "NTB_TOPO_PRI";
103 case NTB_TOPO_SEC: return "NTB_TOPO_SEC";
104 case NTB_TOPO_B2B_USD: return "NTB_TOPO_B2B_USD";
105 case NTB_TOPO_B2B_DSD: return "NTB_TOPO_B2B_DSD";
106 case NTB_TOPO_SWITCH: return "NTB_TOPO_SWITCH";
107 case NTB_TOPO_CROSSLINK: return "NTB_TOPO_CROSSLINK";
108 }
109 return "NTB_TOPO_INVALID";
110}
111
112/**
113 * enum ntb_speed - NTB link training speed
114 * @NTB_SPEED_AUTO: Request the max supported speed.
115 * @NTB_SPEED_NONE: Link is not trained to any speed.
116 * @NTB_SPEED_GEN1: Link is trained to gen1 speed.
117 * @NTB_SPEED_GEN2: Link is trained to gen2 speed.
118 * @NTB_SPEED_GEN3: Link is trained to gen3 speed.
119 * @NTB_SPEED_GEN4: Link is trained to gen4 speed.
120 */
121enum ntb_speed {
122 NTB_SPEED_AUTO = -1,
123 NTB_SPEED_NONE = 0,
124 NTB_SPEED_GEN1 = 1,
125 NTB_SPEED_GEN2 = 2,
126 NTB_SPEED_GEN3 = 3,
127 NTB_SPEED_GEN4 = 4
128};
129
130/**
131 * enum ntb_width - NTB link training width
132 * @NTB_WIDTH_AUTO: Request the max supported width.
133 * @NTB_WIDTH_NONE: Link is not trained to any width.
134 * @NTB_WIDTH_1: Link is trained to 1 lane width.
135 * @NTB_WIDTH_2: Link is trained to 2 lane width.
136 * @NTB_WIDTH_4: Link is trained to 4 lane width.
137 * @NTB_WIDTH_8: Link is trained to 8 lane width.
138 * @NTB_WIDTH_12: Link is trained to 12 lane width.
139 * @NTB_WIDTH_16: Link is trained to 16 lane width.
140 * @NTB_WIDTH_32: Link is trained to 32 lane width.
141 */
142enum ntb_width {
143 NTB_WIDTH_AUTO = -1,
144 NTB_WIDTH_NONE = 0,
145 NTB_WIDTH_1 = 1,
146 NTB_WIDTH_2 = 2,
147 NTB_WIDTH_4 = 4,
148 NTB_WIDTH_8 = 8,
149 NTB_WIDTH_12 = 12,
150 NTB_WIDTH_16 = 16,
151 NTB_WIDTH_32 = 32,
152};
153
154/**
155 * enum ntb_default_port - NTB default port number
156 * @NTB_PORT_PRI_USD: Default port of the NTB_TOPO_PRI/NTB_TOPO_B2B_USD
157 * topologies
158 * @NTB_PORT_SEC_DSD: Default port of the NTB_TOPO_SEC/NTB_TOPO_B2B_DSD
159 * topologies
160 */
161enum ntb_default_port {
162 NTB_PORT_PRI_USD,
163 NTB_PORT_SEC_DSD
164};
165#define NTB_DEF_PEER_CNT (1)
166#define NTB_DEF_PEER_IDX (0)
167
168/**
169 * struct ntb_client_ops - ntb client operations
170 * @probe: Notify client of a new device.
171 * @remove: Notify client to remove a device.
172 */
173struct ntb_client_ops {
174 int (*probe)(struct ntb_client *client, struct ntb_dev *ntb);
175 void (*remove)(struct ntb_client *client, struct ntb_dev *ntb);
176};
177
178static inline int ntb_client_ops_is_valid(const struct ntb_client_ops *ops)
179{
180 /* commented callbacks are not required: */
181 return
182 ops->probe &&
183 ops->remove &&
184 1;
185}
186
187/**
188 * struct ntb_ctx_ops - ntb driver context operations
189 * @link_event: See ntb_link_event().
190 * @db_event: See ntb_db_event().
191 * @msg_event: See ntb_msg_event().
192 */
193struct ntb_ctx_ops {
194 void (*link_event)(void *ctx);
195 void (*db_event)(void *ctx, int db_vector);
196 void (*msg_event)(void *ctx);
197};
198
199static inline int ntb_ctx_ops_is_valid(const struct ntb_ctx_ops *ops)
200{
201 /* commented callbacks are not required: */
202 return
203 /* ops->link_event && */
204 /* ops->db_event && */
205 /* ops->msg_event && */
206 1;
207}
208
209/**
210 * struct ntb_dev_ops - ntb device operations
211 * @port_number: See ntb_port_number().
212 * @peer_port_count: See ntb_peer_port_count().
213 * @peer_port_number: See ntb_peer_port_number().
214 * @peer_port_idx: See ntb_peer_port_idx().
215 * @link_is_up: See ntb_link_is_up().
216 * @link_enable: See ntb_link_enable().
217 * @link_disable: See ntb_link_disable().
218 * @mw_count: See ntb_mw_count().
219 * @mw_get_align: See ntb_mw_get_align().
220 * @mw_set_trans: See ntb_mw_set_trans().
221 * @mw_clear_trans: See ntb_mw_clear_trans().
222 * @peer_mw_count: See ntb_peer_mw_count().
223 * @peer_mw_get_addr: See ntb_peer_mw_get_addr().
224 * @peer_mw_set_trans: See ntb_peer_mw_set_trans().
225 * @peer_mw_clear_trans:See ntb_peer_mw_clear_trans().
226 * @db_is_unsafe: See ntb_db_is_unsafe().
227 * @db_valid_mask: See ntb_db_valid_mask().
228 * @db_vector_count: See ntb_db_vector_count().
229 * @db_vector_mask: See ntb_db_vector_mask().
230 * @db_read: See ntb_db_read().
231 * @db_set: See ntb_db_set().
232 * @db_clear: See ntb_db_clear().
233 * @db_read_mask: See ntb_db_read_mask().
234 * @db_set_mask: See ntb_db_set_mask().
235 * @db_clear_mask: See ntb_db_clear_mask().
236 * @peer_db_addr: See ntb_peer_db_addr().
237 * @peer_db_read: See ntb_peer_db_read().
238 * @peer_db_set: See ntb_peer_db_set().
239 * @peer_db_clear: See ntb_peer_db_clear().
240 * @peer_db_read_mask: See ntb_peer_db_read_mask().
241 * @peer_db_set_mask: See ntb_peer_db_set_mask().
242 * @peer_db_clear_mask: See ntb_peer_db_clear_mask().
243 * @spad_is_unsafe: See ntb_spad_is_unsafe().
244 * @spad_count: See ntb_spad_count().
245 * @spad_read: See ntb_spad_read().
246 * @spad_write: See ntb_spad_write().
247 * @peer_spad_addr: See ntb_peer_spad_addr().
248 * @peer_spad_read: See ntb_peer_spad_read().
249 * @peer_spad_write: See ntb_peer_spad_write().
250 * @msg_count: See ntb_msg_count().
251 * @msg_inbits: See ntb_msg_inbits().
252 * @msg_outbits: See ntb_msg_outbits().
253 * @msg_read_sts: See ntb_msg_read_sts().
254 * @msg_clear_sts: See ntb_msg_clear_sts().
255 * @msg_set_mask: See ntb_msg_set_mask().
256 * @msg_clear_mask: See ntb_msg_clear_mask().
257 * @msg_read: See ntb_msg_read().
258 * @peer_msg_write: See ntb_peer_msg_write().
259 * @get_dma_dev: See ntb_get_dma_dev().
260 */
261struct ntb_dev_ops {
262 int (*port_number)(struct ntb_dev *ntb);
263 int (*peer_port_count)(struct ntb_dev *ntb);
264 int (*peer_port_number)(struct ntb_dev *ntb, int pidx);
265 int (*peer_port_idx)(struct ntb_dev *ntb, int port);
266
267 u64 (*link_is_up)(struct ntb_dev *ntb,
268 enum ntb_speed *speed, enum ntb_width *width);
269 int (*link_enable)(struct ntb_dev *ntb,
270 enum ntb_speed max_speed, enum ntb_width max_width);
271 int (*link_disable)(struct ntb_dev *ntb);
272
273 int (*mw_count)(struct ntb_dev *ntb, int pidx);
274 int (*mw_get_align)(struct ntb_dev *ntb, int pidx, int widx,
275 resource_size_t *addr_align,
276 resource_size_t *size_align,
277 resource_size_t *size_max);
278 int (*mw_set_trans)(struct ntb_dev *ntb, int pidx, int widx,
279 dma_addr_t addr, resource_size_t size);
280 int (*mw_clear_trans)(struct ntb_dev *ntb, int pidx, int widx);
281 int (*peer_mw_count)(struct ntb_dev *ntb);
282 int (*peer_mw_get_addr)(struct ntb_dev *ntb, int widx,
283 phys_addr_t *base, resource_size_t *size);
284 int (*peer_mw_set_trans)(struct ntb_dev *ntb, int pidx, int widx,
285 u64 addr, resource_size_t size);
286 int (*peer_mw_clear_trans)(struct ntb_dev *ntb, int pidx, int widx);
287
288 int (*db_is_unsafe)(struct ntb_dev *ntb);
289 u64 (*db_valid_mask)(struct ntb_dev *ntb);
290 int (*db_vector_count)(struct ntb_dev *ntb);
291 u64 (*db_vector_mask)(struct ntb_dev *ntb, int db_vector);
292
293 u64 (*db_read)(struct ntb_dev *ntb);
294 int (*db_set)(struct ntb_dev *ntb, u64 db_bits);
295 int (*db_clear)(struct ntb_dev *ntb, u64 db_bits);
296
297 u64 (*db_read_mask)(struct ntb_dev *ntb);
298 int (*db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
299 int (*db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
300
301 int (*peer_db_addr)(struct ntb_dev *ntb,
302 phys_addr_t *db_addr, resource_size_t *db_size,
303 u64 *db_data, int db_bit);
304 u64 (*peer_db_read)(struct ntb_dev *ntb);
305 int (*peer_db_set)(struct ntb_dev *ntb, u64 db_bits);
306 int (*peer_db_clear)(struct ntb_dev *ntb, u64 db_bits);
307
308 u64 (*peer_db_read_mask)(struct ntb_dev *ntb);
309 int (*peer_db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
310 int (*peer_db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
311
312 int (*spad_is_unsafe)(struct ntb_dev *ntb);
313 int (*spad_count)(struct ntb_dev *ntb);
314
315 u32 (*spad_read)(struct ntb_dev *ntb, int sidx);
316 int (*spad_write)(struct ntb_dev *ntb, int sidx, u32 val);
317
318 int (*peer_spad_addr)(struct ntb_dev *ntb, int pidx, int sidx,
319 phys_addr_t *spad_addr);
320 u32 (*peer_spad_read)(struct ntb_dev *ntb, int pidx, int sidx);
321 int (*peer_spad_write)(struct ntb_dev *ntb, int pidx, int sidx,
322 u32 val);
323
324 int (*msg_count)(struct ntb_dev *ntb);
325 u64 (*msg_inbits)(struct ntb_dev *ntb);
326 u64 (*msg_outbits)(struct ntb_dev *ntb);
327 u64 (*msg_read_sts)(struct ntb_dev *ntb);
328 int (*msg_clear_sts)(struct ntb_dev *ntb, u64 sts_bits);
329 int (*msg_set_mask)(struct ntb_dev *ntb, u64 mask_bits);
330 int (*msg_clear_mask)(struct ntb_dev *ntb, u64 mask_bits);
331 u32 (*msg_read)(struct ntb_dev *ntb, int *pidx, int midx);
332 int (*peer_msg_write)(struct ntb_dev *ntb, int pidx, int midx, u32 msg);
333 struct device *(*get_dma_dev)(struct ntb_dev *ntb);
334};
335
336static inline int ntb_dev_ops_is_valid(const struct ntb_dev_ops *ops)
337{
338 /* commented callbacks are not required: */
339 return
340 /* Port operations are required for multiport devices */
341 !ops->peer_port_count == !ops->port_number &&
342 !ops->peer_port_number == !ops->port_number &&
343 !ops->peer_port_idx == !ops->port_number &&
344
345 /* Link operations are required */
346 ops->link_is_up &&
347 ops->link_enable &&
348 ops->link_disable &&
349
350 /* One or both MW interfaces should be developed */
351 ops->mw_count &&
352 ops->mw_get_align &&
353 (ops->mw_set_trans ||
354 ops->peer_mw_set_trans) &&
355 /* ops->mw_clear_trans && */
356 ops->peer_mw_count &&
357 ops->peer_mw_get_addr &&
358 /* ops->peer_mw_clear_trans && */
359
360 /* Doorbell operations are mostly required */
361 /* ops->db_is_unsafe && */
362 ops->db_valid_mask &&
363 /* both set, or both unset */
364 (!ops->db_vector_count == !ops->db_vector_mask) &&
365 ops->db_read &&
366 /* ops->db_set && */
367 ops->db_clear &&
368 /* ops->db_read_mask && */
369 ops->db_set_mask &&
370 ops->db_clear_mask &&
371 /* ops->peer_db_addr && */
372 /* ops->peer_db_read && */
373 ops->peer_db_set &&
374 /* ops->peer_db_clear && */
375 /* ops->peer_db_read_mask && */
376 /* ops->peer_db_set_mask && */
377 /* ops->peer_db_clear_mask && */
378
379 /* Scrachpads interface is optional */
380 /* !ops->spad_is_unsafe == !ops->spad_count && */
381 !ops->spad_read == !ops->spad_count &&
382 !ops->spad_write == !ops->spad_count &&
383 /* !ops->peer_spad_addr == !ops->spad_count && */
384 /* !ops->peer_spad_read == !ops->spad_count && */
385 !ops->peer_spad_write == !ops->spad_count &&
386
387 /* Messaging interface is optional */
388 !ops->msg_inbits == !ops->msg_count &&
389 !ops->msg_outbits == !ops->msg_count &&
390 !ops->msg_read_sts == !ops->msg_count &&
391 !ops->msg_clear_sts == !ops->msg_count &&
392 /* !ops->msg_set_mask == !ops->msg_count && */
393 /* !ops->msg_clear_mask == !ops->msg_count && */
394 !ops->msg_read == !ops->msg_count &&
395 !ops->peer_msg_write == !ops->msg_count &&
396
397 /* ops->get_dma_dev is optional */
398 1;
399}
400
401/**
402 * struct ntb_client - client interested in ntb devices
403 * @drv: Linux driver object.
404 * @ops: See &ntb_client_ops.
405 */
406struct ntb_client {
407 struct device_driver drv;
408 const struct ntb_client_ops ops;
409};
410#define drv_ntb_client(__drv) container_of((__drv), struct ntb_client, drv)
411
412/**
413 * struct ntb_dev - ntb device
414 * @dev: Linux device object.
415 * @pdev: PCI device entry of the ntb.
416 * @topo: Detected topology of the ntb.
417 * @ops: See &ntb_dev_ops.
418 * @ctx: See &ntb_ctx_ops.
419 * @ctx_ops: See &ntb_ctx_ops.
420 */
421struct ntb_dev {
422 struct device dev;
423 struct pci_dev *pdev;
424 enum ntb_topo topo;
425 const struct ntb_dev_ops *ops;
426 void *ctx;
427 const struct ntb_ctx_ops *ctx_ops;
428
429 /* private: */
430
431 /* synchronize setting, clearing, and calling ctx_ops */
432 spinlock_t ctx_lock;
433 /* block unregister until device is fully released */
434 struct completion released;
435
436#ifdef CONFIG_NTB_MSI
437 struct ntb_msi *msi;
438#endif
439};
440#define dev_ntb(__dev) container_of((__dev), struct ntb_dev, dev)
441
442/**
443 * ntb_register_client() - register a client for interest in ntb devices
444 * @client: Client context.
445 *
446 * The client will be added to the list of clients interested in ntb devices.
447 * The client will be notified of any ntb devices that are not already
448 * associated with a client, or if ntb devices are registered later.
449 *
450 * Return: Zero if the client is registered, otherwise an error number.
451 */
452#define ntb_register_client(client) \
453 __ntb_register_client((client), THIS_MODULE, KBUILD_MODNAME)
454
455int __ntb_register_client(struct ntb_client *client, struct module *mod,
456 const char *mod_name);
457
458/**
459 * ntb_unregister_client() - unregister a client for interest in ntb devices
460 * @client: Client context.
461 *
462 * The client will be removed from the list of clients interested in ntb
463 * devices. If any ntb devices are associated with the client, the client will
464 * be notified to remove those devices.
465 */
466void ntb_unregister_client(struct ntb_client *client);
467
468#define module_ntb_client(__ntb_client) \
469 module_driver(__ntb_client, ntb_register_client, \
470 ntb_unregister_client)
471
472/**
473 * ntb_register_device() - register a ntb device
474 * @ntb: NTB device context.
475 *
476 * The device will be added to the list of ntb devices. If any clients are
477 * interested in ntb devices, each client will be notified of the ntb device,
478 * until at most one client accepts the device.
479 *
480 * Return: Zero if the device is registered, otherwise an error number.
481 */
482int ntb_register_device(struct ntb_dev *ntb);
483
484/**
485 * ntb_unregister_device() - unregister a ntb device
486 * @ntb: NTB device context.
487 *
488 * The device will be removed from the list of ntb devices. If the ntb device
489 * is associated with a client, the client will be notified to remove the
490 * device.
491 */
492void ntb_unregister_device(struct ntb_dev *ntb);
493
494/**
495 * ntb_set_ctx() - associate a driver context with an ntb device
496 * @ntb: NTB device context.
497 * @ctx: Driver context.
498 * @ctx_ops: Driver context operations.
499 *
500 * Associate a driver context and operations with a ntb device. The context is
501 * provided by the client driver, and the driver may associate a different
502 * context with each ntb device.
503 *
504 * Return: Zero if the context is associated, otherwise an error number.
505 */
506int ntb_set_ctx(struct ntb_dev *ntb, void *ctx,
507 const struct ntb_ctx_ops *ctx_ops);
508
509/**
510 * ntb_clear_ctx() - disassociate any driver context from an ntb device
511 * @ntb: NTB device context.
512 *
513 * Clear any association that may exist between a driver context and the ntb
514 * device.
515 */
516void ntb_clear_ctx(struct ntb_dev *ntb);
517
518/**
519 * ntb_link_event() - notify driver context of a change in link status
520 * @ntb: NTB device context.
521 *
522 * Notify the driver context that the link status may have changed. The driver
523 * should call ntb_link_is_up() to get the current status.
524 */
525void ntb_link_event(struct ntb_dev *ntb);
526
527/**
528 * ntb_db_event() - notify driver context of a doorbell event
529 * @ntb: NTB device context.
530 * @vector: Interrupt vector number.
531 *
532 * Notify the driver context of a doorbell event. If hardware supports
533 * multiple interrupt vectors for doorbells, the vector number indicates which
534 * vector received the interrupt. The vector number is relative to the first
535 * vector used for doorbells, starting at zero, and must be less than
536 * ntb_db_vector_count(). The driver may call ntb_db_read() to check which
537 * doorbell bits need service, and ntb_db_vector_mask() to determine which of
538 * those bits are associated with the vector number.
539 */
540void ntb_db_event(struct ntb_dev *ntb, int vector);
541
542/**
543 * ntb_msg_event() - notify driver context of a message event
544 * @ntb: NTB device context.
545 *
546 * Notify the driver context of a message event. If hardware supports
547 * message registers, this event indicates, that a new message arrived in
548 * some incoming message register or last sent message couldn't be delivered.
549 * The events can be masked/unmasked by the methods ntb_msg_set_mask() and
550 * ntb_msg_clear_mask().
551 */
552void ntb_msg_event(struct ntb_dev *ntb);
553
554/**
555 * ntb_default_port_number() - get the default local port number
556 * @ntb: NTB device context.
557 *
558 * If hardware driver doesn't specify port_number() callback method, the NTB
559 * is considered with just two ports. So this method returns default local
560 * port number in compliance with topology.
561 *
562 * NOTE Don't call this method directly. The ntb_port_number() function should
563 * be used instead.
564 *
565 * Return: the default local port number
566 */
567int ntb_default_port_number(struct ntb_dev *ntb);
568
569/**
570 * ntb_default_port_count() - get the default number of peer device ports
571 * @ntb: NTB device context.
572 *
573 * By default hardware driver supports just one peer device.
574 *
575 * NOTE Don't call this method directly. The ntb_peer_port_count() function
576 * should be used instead.
577 *
578 * Return: the default number of peer ports
579 */
580int ntb_default_peer_port_count(struct ntb_dev *ntb);
581
582/**
583 * ntb_default_peer_port_number() - get the default peer port by given index
584 * @ntb: NTB device context.
585 * @idx: Peer port index (should not differ from zero).
586 *
587 * By default hardware driver supports just one peer device, so this method
588 * shall return the corresponding value from enum ntb_default_port.
589 *
590 * NOTE Don't call this method directly. The ntb_peer_port_number() function
591 * should be used instead.
592 *
593 * Return: the peer device port or negative value indicating an error
594 */
595int ntb_default_peer_port_number(struct ntb_dev *ntb, int pidx);
596
597/**
598 * ntb_default_peer_port_idx() - get the default peer device port index by
599 * given port number
600 * @ntb: NTB device context.
601 * @port: Peer port number (should be one of enum ntb_default_port).
602 *
603 * By default hardware driver supports just one peer device, so while
604 * specified port-argument indicates peer port from enum ntb_default_port,
605 * the return value shall be zero.
606 *
607 * NOTE Don't call this method directly. The ntb_peer_port_idx() function
608 * should be used instead.
609 *
610 * Return: the peer port index or negative value indicating an error
611 */
612int ntb_default_peer_port_idx(struct ntb_dev *ntb, int port);
613
614/**
615 * ntb_port_number() - get the local port number
616 * @ntb: NTB device context.
617 *
618 * Hardware must support at least simple two-ports ntb connection
619 *
620 * Return: the local port number
621 */
622static inline int ntb_port_number(struct ntb_dev *ntb)
623{
624 if (!ntb->ops->port_number)
625 return ntb_default_port_number(ntb);
626
627 return ntb->ops->port_number(ntb);
628}
629/**
630 * ntb_peer_port_count() - get the number of peer device ports
631 * @ntb: NTB device context.
632 *
633 * Hardware may support an access to memory of several remote domains
634 * over multi-port NTB devices. This method returns the number of peers,
635 * local device can have shared memory with.
636 *
637 * Return: the number of peer ports
638 */
639static inline int ntb_peer_port_count(struct ntb_dev *ntb)
640{
641 if (!ntb->ops->peer_port_count)
642 return ntb_default_peer_port_count(ntb);
643
644 return ntb->ops->peer_port_count(ntb);
645}
646
647/**
648 * ntb_peer_port_number() - get the peer port by given index
649 * @ntb: NTB device context.
650 * @pidx: Peer port index.
651 *
652 * Peer ports are continuously enumerated by NTB API logic, so this method
653 * lets to retrieve port real number by its index.
654 *
655 * Return: the peer device port or negative value indicating an error
656 */
657static inline int ntb_peer_port_number(struct ntb_dev *ntb, int pidx)
658{
659 if (!ntb->ops->peer_port_number)
660 return ntb_default_peer_port_number(ntb, pidx);
661
662 return ntb->ops->peer_port_number(ntb, pidx);
663}
664
665/**
666 * ntb_logical_port_number() - get the logical port number of the local port
667 * @ntb: NTB device context.
668 *
669 * The Logical Port Number is defined to be a unique number for each
670 * port starting from zero through to the number of ports minus one.
671 * This is in contrast to the Port Number where each port can be assigned
672 * any unique physical number by the hardware.
673 *
674 * The logical port number is useful for calculating the resource indexes
675 * used by peers.
676 *
677 * Return: the logical port number or negative value indicating an error
678 */
679static inline int ntb_logical_port_number(struct ntb_dev *ntb)
680{
681 int lport = ntb_port_number(ntb);
682 int pidx;
683
684 if (lport < 0)
685 return lport;
686
687 for (pidx = 0; pidx < ntb_peer_port_count(ntb); pidx++)
688 if (lport <= ntb_peer_port_number(ntb, pidx))
689 return pidx;
690
691 return pidx;
692}
693
694/**
695 * ntb_peer_logical_port_number() - get the logical peer port by given index
696 * @ntb: NTB device context.
697 * @pidx: Peer port index.
698 *
699 * The Logical Port Number is defined to be a unique number for each
700 * port starting from zero through to the number of ports minus one.
701 * This is in contrast to the Port Number where each port can be assigned
702 * any unique physical number by the hardware.
703 *
704 * The logical port number is useful for calculating the resource indexes
705 * used by peers.
706 *
707 * Return: the peer's logical port number or negative value indicating an error
708 */
709static inline int ntb_peer_logical_port_number(struct ntb_dev *ntb, int pidx)
710{
711 if (ntb_peer_port_number(ntb, pidx) < ntb_port_number(ntb))
712 return pidx;
713 else
714 return pidx + 1;
715}
716
717/**
718 * ntb_peer_port_idx() - get the peer device port index by given port number
719 * @ntb: NTB device context.
720 * @port: Peer port number.
721 *
722 * Inverse operation of ntb_peer_port_number(), so one can get port index
723 * by specified port number.
724 *
725 * Return: the peer port index or negative value indicating an error
726 */
727static inline int ntb_peer_port_idx(struct ntb_dev *ntb, int port)
728{
729 if (!ntb->ops->peer_port_idx)
730 return ntb_default_peer_port_idx(ntb, port);
731
732 return ntb->ops->peer_port_idx(ntb, port);
733}
734
735/**
736 * ntb_link_is_up() - get the current ntb link state
737 * @ntb: NTB device context.
738 * @speed: OUT - The link speed expressed as PCIe generation number.
739 * @width: OUT - The link width expressed as the number of PCIe lanes.
740 *
741 * Get the current state of the ntb link. It is recommended to query the link
742 * state once after every link event. It is safe to query the link state in
743 * the context of the link event callback.
744 *
745 * Return: bitfield of indexed ports link state: bit is set/cleared if the
746 * link is up/down respectively.
747 */
748static inline u64 ntb_link_is_up(struct ntb_dev *ntb,
749 enum ntb_speed *speed, enum ntb_width *width)
750{
751 return ntb->ops->link_is_up(ntb, speed, width);
752}
753
754/**
755 * ntb_link_enable() - enable the local port ntb connection
756 * @ntb: NTB device context.
757 * @max_speed: The maximum link speed expressed as PCIe generation number.
758 * @max_width: The maximum link width expressed as the number of PCIe lanes.
759 *
760 * Enable the NTB/PCIe link on the local or remote (for bridge-to-bridge
761 * topology) side of the bridge. If it's supported the ntb device should train
762 * the link to its maximum speed and width, or the requested speed and width,
763 * whichever is smaller. Some hardware doesn't support PCIe link training, so
764 * the last two arguments will be ignored then.
765 *
766 * Return: Zero on success, otherwise an error number.
767 */
768static inline int ntb_link_enable(struct ntb_dev *ntb,
769 enum ntb_speed max_speed,
770 enum ntb_width max_width)
771{
772 return ntb->ops->link_enable(ntb, max_speed, max_width);
773}
774
775/**
776 * ntb_link_disable() - disable the local port ntb connection
777 * @ntb: NTB device context.
778 *
779 * Disable the link on the local or remote (for b2b topology) of the ntb.
780 * The ntb device should disable the link. Returning from this call must
781 * indicate that a barrier has passed, though with no more writes may pass in
782 * either direction across the link, except if this call returns an error
783 * number.
784 *
785 * Return: Zero on success, otherwise an error number.
786 */
787static inline int ntb_link_disable(struct ntb_dev *ntb)
788{
789 return ntb->ops->link_disable(ntb);
790}
791
792/**
793 * ntb_mw_count() - get the number of inbound memory windows, which could
794 * be created for a specified peer device
795 * @ntb: NTB device context.
796 * @pidx: Port index of peer device.
797 *
798 * Hardware and topology may support a different number of memory windows.
799 * Moreover different peer devices can support different number of memory
800 * windows. Simply speaking this method returns the number of possible inbound
801 * memory windows to share with specified peer device. Note: this may return
802 * zero if the link is not up yet.
803 *
804 * Return: the number of memory windows.
805 */
806static inline int ntb_mw_count(struct ntb_dev *ntb, int pidx)
807{
808 return ntb->ops->mw_count(ntb, pidx);
809}
810
811/**
812 * ntb_mw_get_align() - get the restriction parameters of inbound memory window
813 * @ntb: NTB device context.
814 * @pidx: Port index of peer device.
815 * @widx: Memory window index.
816 * @addr_align: OUT - the base alignment for translating the memory window
817 * @size_align: OUT - the size alignment for translating the memory window
818 * @size_max: OUT - the maximum size of the memory window
819 *
820 * Get the alignments of an inbound memory window with specified index.
821 * NULL may be given for any output parameter if the value is not needed.
822 * The alignment and size parameters may be used for allocation of proper
823 * shared memory. Note: this must only be called when the link is up.
824 *
825 * Return: Zero on success, otherwise a negative error number.
826 */
827static inline int ntb_mw_get_align(struct ntb_dev *ntb, int pidx, int widx,
828 resource_size_t *addr_align,
829 resource_size_t *size_align,
830 resource_size_t *size_max)
831{
832 if (!(ntb_link_is_up(ntb, NULL, NULL) & BIT_ULL(pidx)))
833 return -ENOTCONN;
834
835 return ntb->ops->mw_get_align(ntb, pidx, widx, addr_align, size_align,
836 size_max);
837}
838
839/**
840 * ntb_mw_set_trans() - set the translation of an inbound memory window
841 * @ntb: NTB device context.
842 * @pidx: Port index of peer device.
843 * @widx: Memory window index.
844 * @addr: The dma address of local memory to expose to the peer.
845 * @size: The size of the local memory to expose to the peer.
846 *
847 * Set the translation of a memory window. The peer may access local memory
848 * through the window starting at the address, up to the size. The address
849 * and size must be aligned in compliance with restrictions of
850 * ntb_mw_get_align(). The region size should not exceed the size_max parameter
851 * of that method.
852 *
853 * This method may not be implemented due to the hardware specific memory
854 * windows interface.
855 *
856 * Return: Zero on success, otherwise an error number.
857 */
858static inline int ntb_mw_set_trans(struct ntb_dev *ntb, int pidx, int widx,
859 dma_addr_t addr, resource_size_t size)
860{
861 if (!ntb->ops->mw_set_trans)
862 return 0;
863
864 return ntb->ops->mw_set_trans(ntb, pidx, widx, addr, size);
865}
866
867/**
868 * ntb_mw_clear_trans() - clear the translation address of an inbound memory
869 * window
870 * @ntb: NTB device context.
871 * @pidx: Port index of peer device.
872 * @widx: Memory window index.
873 *
874 * Clear the translation of an inbound memory window. The peer may no longer
875 * access local memory through the window.
876 *
877 * Return: Zero on success, otherwise an error number.
878 */
879static inline int ntb_mw_clear_trans(struct ntb_dev *ntb, int pidx, int widx)
880{
881 if (!ntb->ops->mw_clear_trans)
882 return ntb_mw_set_trans(ntb, pidx, widx, 0, 0);
883
884 return ntb->ops->mw_clear_trans(ntb, pidx, widx);
885}
886
887/**
888 * ntb_peer_mw_count() - get the number of outbound memory windows, which could
889 * be mapped to access a shared memory
890 * @ntb: NTB device context.
891 *
892 * Hardware and topology may support a different number of memory windows.
893 * This method returns the number of outbound memory windows supported by
894 * local device.
895 *
896 * Return: the number of memory windows.
897 */
898static inline int ntb_peer_mw_count(struct ntb_dev *ntb)
899{
900 return ntb->ops->peer_mw_count(ntb);
901}
902
903/**
904 * ntb_peer_mw_get_addr() - get map address of an outbound memory window
905 * @ntb: NTB device context.
906 * @widx: Memory window index (within ntb_peer_mw_count() return value).
907 * @base: OUT - the base address of mapping region.
908 * @size: OUT - the size of mapping region.
909 *
910 * Get base and size of memory region to map. NULL may be given for any output
911 * parameter if the value is not needed. The base and size may be used for
912 * mapping the memory window, to access the peer memory.
913 *
914 * Return: Zero on success, otherwise a negative error number.
915 */
916static inline int ntb_peer_mw_get_addr(struct ntb_dev *ntb, int widx,
917 phys_addr_t *base, resource_size_t *size)
918{
919 return ntb->ops->peer_mw_get_addr(ntb, widx, base, size);
920}
921
922/**
923 * ntb_peer_mw_set_trans() - set a translation address of a memory window
924 * retrieved from a peer device
925 * @ntb: NTB device context.
926 * @pidx: Port index of peer device the translation address received from.
927 * @widx: Memory window index.
928 * @addr: The dma address of the shared memory to access.
929 * @size: The size of the shared memory to access.
930 *
931 * Set the translation of an outbound memory window. The local device may
932 * access shared memory allocated by a peer device sent the address.
933 *
934 * This method may not be implemented due to the hardware specific memory
935 * windows interface, so a translation address can be only set on the side,
936 * where shared memory (inbound memory windows) is allocated.
937 *
938 * Return: Zero on success, otherwise an error number.
939 */
940static inline int ntb_peer_mw_set_trans(struct ntb_dev *ntb, int pidx, int widx,
941 u64 addr, resource_size_t size)
942{
943 if (!ntb->ops->peer_mw_set_trans)
944 return 0;
945
946 return ntb->ops->peer_mw_set_trans(ntb, pidx, widx, addr, size);
947}
948
949/**
950 * ntb_peer_mw_clear_trans() - clear the translation address of an outbound
951 * memory window
952 * @ntb: NTB device context.
953 * @pidx: Port index of peer device.
954 * @widx: Memory window index.
955 *
956 * Clear the translation of a outbound memory window. The local device may no
957 * longer access a shared memory through the window.
958 *
959 * This method may not be implemented due to the hardware specific memory
960 * windows interface.
961 *
962 * Return: Zero on success, otherwise an error number.
963 */
964static inline int ntb_peer_mw_clear_trans(struct ntb_dev *ntb, int pidx,
965 int widx)
966{
967 if (!ntb->ops->peer_mw_clear_trans)
968 return ntb_peer_mw_set_trans(ntb, pidx, widx, 0, 0);
969
970 return ntb->ops->peer_mw_clear_trans(ntb, pidx, widx);
971}
972
973/**
974 * ntb_db_is_unsafe() - check if it is safe to use hardware doorbell
975 * @ntb: NTB device context.
976 *
977 * It is possible for some ntb hardware to be affected by errata. Hardware
978 * drivers can advise clients to avoid using doorbells. Clients may ignore
979 * this advice, though caution is recommended.
980 *
981 * Return: Zero if it is safe to use doorbells, or One if it is not safe.
982 */
983static inline int ntb_db_is_unsafe(struct ntb_dev *ntb)
984{
985 if (!ntb->ops->db_is_unsafe)
986 return 0;
987
988 return ntb->ops->db_is_unsafe(ntb);
989}
990
991/**
992 * ntb_db_valid_mask() - get a mask of doorbell bits supported by the ntb
993 * @ntb: NTB device context.
994 *
995 * Hardware may support different number or arrangement of doorbell bits.
996 *
997 * Return: A mask of doorbell bits supported by the ntb.
998 */
999static inline u64 ntb_db_valid_mask(struct ntb_dev *ntb)
1000{
1001 return ntb->ops->db_valid_mask(ntb);
1002}
1003
1004/**
1005 * ntb_db_vector_count() - get the number of doorbell interrupt vectors
1006 * @ntb: NTB device context.
1007 *
1008 * Hardware may support different number of interrupt vectors.
1009 *
1010 * Return: The number of doorbell interrupt vectors.
1011 */
1012static inline int ntb_db_vector_count(struct ntb_dev *ntb)
1013{
1014 if (!ntb->ops->db_vector_count)
1015 return 1;
1016
1017 return ntb->ops->db_vector_count(ntb);
1018}
1019
1020/**
1021 * ntb_db_vector_mask() - get a mask of doorbell bits serviced by a vector
1022 * @ntb: NTB device context.
1023 * @vector: Doorbell vector number.
1024 *
1025 * Each interrupt vector may have a different number or arrangement of bits.
1026 *
1027 * Return: A mask of doorbell bits serviced by a vector.
1028 */
1029static inline u64 ntb_db_vector_mask(struct ntb_dev *ntb, int vector)
1030{
1031 if (!ntb->ops->db_vector_mask)
1032 return ntb_db_valid_mask(ntb);
1033
1034 return ntb->ops->db_vector_mask(ntb, vector);
1035}
1036
1037/**
1038 * ntb_db_read() - read the local doorbell register
1039 * @ntb: NTB device context.
1040 *
1041 * Read the local doorbell register, and return the bits that are set.
1042 *
1043 * Return: The bits currently set in the local doorbell register.
1044 */
1045static inline u64 ntb_db_read(struct ntb_dev *ntb)
1046{
1047 return ntb->ops->db_read(ntb);
1048}
1049
1050/**
1051 * ntb_db_set() - set bits in the local doorbell register
1052 * @ntb: NTB device context.
1053 * @db_bits: Doorbell bits to set.
1054 *
1055 * Set bits in the local doorbell register, which may generate a local doorbell
1056 * interrupt. Bits that were already set must remain set.
1057 *
1058 * This is unusual, and hardware may not support it.
1059 *
1060 * Return: Zero on success, otherwise an error number.
1061 */
1062static inline int ntb_db_set(struct ntb_dev *ntb, u64 db_bits)
1063{
1064 if (!ntb->ops->db_set)
1065 return -EINVAL;
1066
1067 return ntb->ops->db_set(ntb, db_bits);
1068}
1069
1070/**
1071 * ntb_db_clear() - clear bits in the local doorbell register
1072 * @ntb: NTB device context.
1073 * @db_bits: Doorbell bits to clear.
1074 *
1075 * Clear bits in the local doorbell register, arming the bits for the next
1076 * doorbell.
1077 *
1078 * Return: Zero on success, otherwise an error number.
1079 */
1080static inline int ntb_db_clear(struct ntb_dev *ntb, u64 db_bits)
1081{
1082 return ntb->ops->db_clear(ntb, db_bits);
1083}
1084
1085/**
1086 * ntb_db_read_mask() - read the local doorbell mask
1087 * @ntb: NTB device context.
1088 *
1089 * Read the local doorbell mask register, and return the bits that are set.
1090 *
1091 * This is unusual, though hardware is likely to support it.
1092 *
1093 * Return: The bits currently set in the local doorbell mask register.
1094 */
1095static inline u64 ntb_db_read_mask(struct ntb_dev *ntb)
1096{
1097 if (!ntb->ops->db_read_mask)
1098 return 0;
1099
1100 return ntb->ops->db_read_mask(ntb);
1101}
1102
1103/**
1104 * ntb_db_set_mask() - set bits in the local doorbell mask
1105 * @ntb: NTB device context.
1106 * @db_bits: Doorbell mask bits to set.
1107 *
1108 * Set bits in the local doorbell mask register, preventing doorbell interrupts
1109 * from being generated for those doorbell bits. Bits that were already set
1110 * must remain set.
1111 *
1112 * Return: Zero on success, otherwise an error number.
1113 */
1114static inline int ntb_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
1115{
1116 return ntb->ops->db_set_mask(ntb, db_bits);
1117}
1118
1119/**
1120 * ntb_db_clear_mask() - clear bits in the local doorbell mask
1121 * @ntb: NTB device context.
1122 * @db_bits: Doorbell bits to clear.
1123 *
1124 * Clear bits in the local doorbell mask register, allowing doorbell interrupts
1125 * from being generated for those doorbell bits. If a doorbell bit is already
1126 * set at the time the mask is cleared, and the corresponding mask bit is
1127 * changed from set to clear, then the ntb driver must ensure that
1128 * ntb_db_event() is called. If the hardware does not generate the interrupt
1129 * on clearing the mask bit, then the driver must call ntb_db_event() anyway.
1130 *
1131 * Return: Zero on success, otherwise an error number.
1132 */
1133static inline int ntb_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
1134{
1135 return ntb->ops->db_clear_mask(ntb, db_bits);
1136}
1137
1138/**
1139 * ntb_peer_db_addr() - address and size of the peer doorbell register
1140 * @ntb: NTB device context.
1141 * @db_addr: OUT - The address of the peer doorbell register.
1142 * @db_size: OUT - The number of bytes to write the peer doorbell register.
1143 * @db_data: OUT - The data of peer doorbell register
1144 * @db_bit: door bell bit number
1145 *
1146 * Return the address of the peer doorbell register. This may be used, for
1147 * example, by drivers that offload memory copy operations to a dma engine.
1148 * The drivers may wish to ring the peer doorbell at the completion of memory
1149 * copy operations. For efficiency, and to simplify ordering of operations
1150 * between the dma memory copies and the ringing doorbell, the driver may
1151 * append one additional dma memory copy with the doorbell register as the
1152 * destination, after the memory copy operations.
1153 *
1154 * Return: Zero on success, otherwise an error number.
1155 */
1156static inline int ntb_peer_db_addr(struct ntb_dev *ntb,
1157 phys_addr_t *db_addr,
1158 resource_size_t *db_size,
1159 u64 *db_data, int db_bit)
1160{
1161 if (!ntb->ops->peer_db_addr)
1162 return -EINVAL;
1163
1164 return ntb->ops->peer_db_addr(ntb, db_addr, db_size, db_data, db_bit);
1165}
1166
1167/**
1168 * ntb_peer_db_read() - read the peer doorbell register
1169 * @ntb: NTB device context.
1170 *
1171 * Read the peer doorbell register, and return the bits that are set.
1172 *
1173 * This is unusual, and hardware may not support it.
1174 *
1175 * Return: The bits currently set in the peer doorbell register.
1176 */
1177static inline u64 ntb_peer_db_read(struct ntb_dev *ntb)
1178{
1179 if (!ntb->ops->peer_db_read)
1180 return 0;
1181
1182 return ntb->ops->peer_db_read(ntb);
1183}
1184
1185/**
1186 * ntb_peer_db_set() - set bits in the peer doorbell register
1187 * @ntb: NTB device context.
1188 * @db_bits: Doorbell bits to set.
1189 *
1190 * Set bits in the peer doorbell register, which may generate a peer doorbell
1191 * interrupt. Bits that were already set must remain set.
1192 *
1193 * Return: Zero on success, otherwise an error number.
1194 */
1195static inline int ntb_peer_db_set(struct ntb_dev *ntb, u64 db_bits)
1196{
1197 return ntb->ops->peer_db_set(ntb, db_bits);
1198}
1199
1200/**
1201 * ntb_peer_db_clear() - clear bits in the peer doorbell register
1202 * @ntb: NTB device context.
1203 * @db_bits: Doorbell bits to clear.
1204 *
1205 * Clear bits in the peer doorbell register, arming the bits for the next
1206 * doorbell.
1207 *
1208 * This is unusual, and hardware may not support it.
1209 *
1210 * Return: Zero on success, otherwise an error number.
1211 */
1212static inline int ntb_peer_db_clear(struct ntb_dev *ntb, u64 db_bits)
1213{
1214 if (!ntb->ops->db_clear)
1215 return -EINVAL;
1216
1217 return ntb->ops->peer_db_clear(ntb, db_bits);
1218}
1219
1220/**
1221 * ntb_peer_db_read_mask() - read the peer doorbell mask
1222 * @ntb: NTB device context.
1223 *
1224 * Read the peer doorbell mask register, and return the bits that are set.
1225 *
1226 * This is unusual, and hardware may not support it.
1227 *
1228 * Return: The bits currently set in the peer doorbell mask register.
1229 */
1230static inline u64 ntb_peer_db_read_mask(struct ntb_dev *ntb)
1231{
1232 if (!ntb->ops->db_read_mask)
1233 return 0;
1234
1235 return ntb->ops->peer_db_read_mask(ntb);
1236}
1237
1238/**
1239 * ntb_peer_db_set_mask() - set bits in the peer doorbell mask
1240 * @ntb: NTB device context.
1241 * @db_bits: Doorbell mask bits to set.
1242 *
1243 * Set bits in the peer doorbell mask register, preventing doorbell interrupts
1244 * from being generated for those doorbell bits. Bits that were already set
1245 * must remain set.
1246 *
1247 * This is unusual, and hardware may not support it.
1248 *
1249 * Return: Zero on success, otherwise an error number.
1250 */
1251static inline int ntb_peer_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
1252{
1253 if (!ntb->ops->db_set_mask)
1254 return -EINVAL;
1255
1256 return ntb->ops->peer_db_set_mask(ntb, db_bits);
1257}
1258
1259/**
1260 * ntb_peer_db_clear_mask() - clear bits in the peer doorbell mask
1261 * @ntb: NTB device context.
1262 * @db_bits: Doorbell bits to clear.
1263 *
1264 * Clear bits in the peer doorbell mask register, allowing doorbell interrupts
1265 * from being generated for those doorbell bits. If the hardware does not
1266 * generate the interrupt on clearing the mask bit, then the driver should not
1267 * implement this function!
1268 *
1269 * This is unusual, and hardware may not support it.
1270 *
1271 * Return: Zero on success, otherwise an error number.
1272 */
1273static inline int ntb_peer_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
1274{
1275 if (!ntb->ops->db_clear_mask)
1276 return -EINVAL;
1277
1278 return ntb->ops->peer_db_clear_mask(ntb, db_bits);
1279}
1280
1281/**
1282 * ntb_spad_is_unsafe() - check if it is safe to use the hardware scratchpads
1283 * @ntb: NTB device context.
1284 *
1285 * It is possible for some ntb hardware to be affected by errata. Hardware
1286 * drivers can advise clients to avoid using scratchpads. Clients may ignore
1287 * this advice, though caution is recommended.
1288 *
1289 * Return: Zero if it is safe to use scratchpads, or One if it is not safe.
1290 */
1291static inline int ntb_spad_is_unsafe(struct ntb_dev *ntb)
1292{
1293 if (!ntb->ops->spad_is_unsafe)
1294 return 0;
1295
1296 return ntb->ops->spad_is_unsafe(ntb);
1297}
1298
1299/**
1300 * ntb_spad_count() - get the number of scratchpads
1301 * @ntb: NTB device context.
1302 *
1303 * Hardware and topology may support a different number of scratchpads.
1304 * Although it must be the same for all ports per NTB device.
1305 *
1306 * Return: the number of scratchpads.
1307 */
1308static inline int ntb_spad_count(struct ntb_dev *ntb)
1309{
1310 if (!ntb->ops->spad_count)
1311 return 0;
1312
1313 return ntb->ops->spad_count(ntb);
1314}
1315
1316/**
1317 * ntb_spad_read() - read the local scratchpad register
1318 * @ntb: NTB device context.
1319 * @sidx: Scratchpad index.
1320 *
1321 * Read the local scratchpad register, and return the value.
1322 *
1323 * Return: The value of the local scratchpad register.
1324 */
1325static inline u32 ntb_spad_read(struct ntb_dev *ntb, int sidx)
1326{
1327 if (!ntb->ops->spad_read)
1328 return ~(u32)0;
1329
1330 return ntb->ops->spad_read(ntb, sidx);
1331}
1332
1333/**
1334 * ntb_spad_write() - write the local scratchpad register
1335 * @ntb: NTB device context.
1336 * @sidx: Scratchpad index.
1337 * @val: Scratchpad value.
1338 *
1339 * Write the value to the local scratchpad register.
1340 *
1341 * Return: Zero on success, otherwise an error number.
1342 */
1343static inline int ntb_spad_write(struct ntb_dev *ntb, int sidx, u32 val)
1344{
1345 if (!ntb->ops->spad_write)
1346 return -EINVAL;
1347
1348 return ntb->ops->spad_write(ntb, sidx, val);
1349}
1350
1351/**
1352 * ntb_peer_spad_addr() - address of the peer scratchpad register
1353 * @ntb: NTB device context.
1354 * @pidx: Port index of peer device.
1355 * @sidx: Scratchpad index.
1356 * @spad_addr: OUT - The address of the peer scratchpad register.
1357 *
1358 * Return the address of the peer scratchpad register. This may be used, for
1359 * example, by drivers that offload memory copy operations to a dma engine.
1360 *
1361 * Return: Zero on success, otherwise an error number.
1362 */
1363static inline int ntb_peer_spad_addr(struct ntb_dev *ntb, int pidx, int sidx,
1364 phys_addr_t *spad_addr)
1365{
1366 if (!ntb->ops->peer_spad_addr)
1367 return -EINVAL;
1368
1369 return ntb->ops->peer_spad_addr(ntb, pidx, sidx, spad_addr);
1370}
1371
1372/**
1373 * ntb_peer_spad_read() - read the peer scratchpad register
1374 * @ntb: NTB device context.
1375 * @pidx: Port index of peer device.
1376 * @sidx: Scratchpad index.
1377 *
1378 * Read the peer scratchpad register, and return the value.
1379 *
1380 * Return: The value of the peer scratchpad register.
1381 */
1382static inline u32 ntb_peer_spad_read(struct ntb_dev *ntb, int pidx, int sidx)
1383{
1384 if (!ntb->ops->peer_spad_read)
1385 return ~(u32)0;
1386
1387 return ntb->ops->peer_spad_read(ntb, pidx, sidx);
1388}
1389
1390/**
1391 * ntb_peer_spad_write() - write the peer scratchpad register
1392 * @ntb: NTB device context.
1393 * @pidx: Port index of peer device.
1394 * @sidx: Scratchpad index.
1395 * @val: Scratchpad value.
1396 *
1397 * Write the value to the peer scratchpad register.
1398 *
1399 * Return: Zero on success, otherwise an error number.
1400 */
1401static inline int ntb_peer_spad_write(struct ntb_dev *ntb, int pidx, int sidx,
1402 u32 val)
1403{
1404 if (!ntb->ops->peer_spad_write)
1405 return -EINVAL;
1406
1407 return ntb->ops->peer_spad_write(ntb, pidx, sidx, val);
1408}
1409
1410/**
1411 * ntb_msg_count() - get the number of message registers
1412 * @ntb: NTB device context.
1413 *
1414 * Hardware may support a different number of message registers.
1415 *
1416 * Return: the number of message registers.
1417 */
1418static inline int ntb_msg_count(struct ntb_dev *ntb)
1419{
1420 if (!ntb->ops->msg_count)
1421 return 0;
1422
1423 return ntb->ops->msg_count(ntb);
1424}
1425
1426/**
1427 * ntb_msg_inbits() - get a bitfield of inbound message registers status
1428 * @ntb: NTB device context.
1429 *
1430 * The method returns the bitfield of status and mask registers, which related
1431 * to inbound message registers.
1432 *
1433 * Return: bitfield of inbound message registers.
1434 */
1435static inline u64 ntb_msg_inbits(struct ntb_dev *ntb)
1436{
1437 if (!ntb->ops->msg_inbits)
1438 return 0;
1439
1440 return ntb->ops->msg_inbits(ntb);
1441}
1442
1443/**
1444 * ntb_msg_outbits() - get a bitfield of outbound message registers status
1445 * @ntb: NTB device context.
1446 *
1447 * The method returns the bitfield of status and mask registers, which related
1448 * to outbound message registers.
1449 *
1450 * Return: bitfield of outbound message registers.
1451 */
1452static inline u64 ntb_msg_outbits(struct ntb_dev *ntb)
1453{
1454 if (!ntb->ops->msg_outbits)
1455 return 0;
1456
1457 return ntb->ops->msg_outbits(ntb);
1458}
1459
1460/**
1461 * ntb_msg_read_sts() - read the message registers status
1462 * @ntb: NTB device context.
1463 *
1464 * Read the status of message register. Inbound and outbound message registers
1465 * related bits can be filtered by masks retrieved from ntb_msg_inbits() and
1466 * ntb_msg_outbits().
1467 *
1468 * Return: status bits of message registers
1469 */
1470static inline u64 ntb_msg_read_sts(struct ntb_dev *ntb)
1471{
1472 if (!ntb->ops->msg_read_sts)
1473 return 0;
1474
1475 return ntb->ops->msg_read_sts(ntb);
1476}
1477
1478/**
1479 * ntb_msg_clear_sts() - clear status bits of message registers
1480 * @ntb: NTB device context.
1481 * @sts_bits: Status bits to clear.
1482 *
1483 * Clear bits in the status register.
1484 *
1485 * Return: Zero on success, otherwise a negative error number.
1486 */
1487static inline int ntb_msg_clear_sts(struct ntb_dev *ntb, u64 sts_bits)
1488{
1489 if (!ntb->ops->msg_clear_sts)
1490 return -EINVAL;
1491
1492 return ntb->ops->msg_clear_sts(ntb, sts_bits);
1493}
1494
1495/**
1496 * ntb_msg_set_mask() - set mask of message register status bits
1497 * @ntb: NTB device context.
1498 * @mask_bits: Mask bits.
1499 *
1500 * Mask the message registers status bits from raising the message event.
1501 *
1502 * Return: Zero on success, otherwise a negative error number.
1503 */
1504static inline int ntb_msg_set_mask(struct ntb_dev *ntb, u64 mask_bits)
1505{
1506 if (!ntb->ops->msg_set_mask)
1507 return -EINVAL;
1508
1509 return ntb->ops->msg_set_mask(ntb, mask_bits);
1510}
1511
1512/**
1513 * ntb_msg_clear_mask() - clear message registers mask
1514 * @ntb: NTB device context.
1515 * @mask_bits: Mask bits to clear.
1516 *
1517 * Clear bits in the message events mask register.
1518 *
1519 * Return: Zero on success, otherwise a negative error number.
1520 */
1521static inline int ntb_msg_clear_mask(struct ntb_dev *ntb, u64 mask_bits)
1522{
1523 if (!ntb->ops->msg_clear_mask)
1524 return -EINVAL;
1525
1526 return ntb->ops->msg_clear_mask(ntb, mask_bits);
1527}
1528
1529/**
1530 * ntb_msg_read() - read inbound message register with specified index
1531 * @ntb: NTB device context.
1532 * @pidx: OUT - Port index of peer device a message retrieved from
1533 * @midx: Message register index
1534 *
1535 * Read data from the specified message register. Source port index of a
1536 * message is retrieved as well.
1537 *
1538 * Return: The value of the inbound message register.
1539 */
1540static inline u32 ntb_msg_read(struct ntb_dev *ntb, int *pidx, int midx)
1541{
1542 if (!ntb->ops->msg_read)
1543 return ~(u32)0;
1544
1545 return ntb->ops->msg_read(ntb, pidx, midx);
1546}
1547
1548/**
1549 * ntb_peer_msg_write() - write data to the specified peer message register
1550 * @ntb: NTB device context.
1551 * @pidx: Port index of peer device a message being sent to
1552 * @midx: Message register index
1553 * @msg: Data to send
1554 *
1555 * Send data to a specified peer device using the defined message register.
1556 * Message event can be raised if the midx registers isn't empty while
1557 * calling this method and the corresponding interrupt isn't masked.
1558 *
1559 * Return: Zero on success, otherwise a negative error number.
1560 */
1561static inline int ntb_peer_msg_write(struct ntb_dev *ntb, int pidx, int midx,
1562 u32 msg)
1563{
1564 if (!ntb->ops->peer_msg_write)
1565 return -EINVAL;
1566
1567 return ntb->ops->peer_msg_write(ntb, pidx, midx, msg);
1568}
1569
1570/**
1571 * ntb_get_dma_dev() - get the device to use for DMA allocations/mappings
1572 * @ntb: NTB device context.
1573 *
1574 * Return a struct device suitable for DMA API allocations and mappings.
1575 * This is typically the parent of the NTB device, but may be overridden by a
1576 * driver by implementing .get_dma_dev().
1577 *
1578 * Drivers that implement .get_dma_dev() must return a non-NULL pointer.
1579 *
1580 * Return: device pointer to use for DMA operations.
1581 */
1582static inline struct device *ntb_get_dma_dev(struct ntb_dev *ntb)
1583{
1584 if (!ntb->ops->get_dma_dev)
1585 return ntb->dev.parent;
1586
1587 return ntb->ops->get_dma_dev(ntb);
1588}
1589
1590/**
1591 * ntb_peer_resource_idx() - get a resource index for a given peer idx
1592 * @ntb: NTB device context.
1593 * @pidx: Peer port index.
1594 *
1595 * When constructing a graph of peers, each remote peer must use a different
1596 * resource index (mw, doorbell, etc) to communicate with each other
1597 * peer.
1598 *
1599 * In a two peer system, this function should always return 0 such that
1600 * resource 0 points to the remote peer on both ports.
1601 *
1602 * In a 5 peer system, this function will return the following matrix
1603 *
1604 * pidx \ port 0 1 2 3 4
1605 * 0 0 0 1 2 3
1606 * 1 0 1 1 2 3
1607 * 2 0 1 2 2 3
1608 * 3 0 1 2 3 3
1609 *
1610 * For example, if this function is used to program peer's memory
1611 * windows, port 0 will program MW 0 on all it's peers to point to itself.
1612 * port 1 will program MW 0 in port 0 to point to itself and MW 1 on all
1613 * other ports. etc.
1614 *
1615 * For the legacy two host case, ntb_port_number() and ntb_peer_port_number()
1616 * both return zero and therefore this function will always return zero.
1617 * So MW 0 on each host would be programmed to point to the other host.
1618 *
1619 * Return: the resource index to use for that peer.
1620 */
1621static inline int ntb_peer_resource_idx(struct ntb_dev *ntb, int pidx)
1622{
1623 int local_port, peer_port;
1624
1625 if (pidx >= ntb_peer_port_count(ntb))
1626 return -EINVAL;
1627
1628 local_port = ntb_logical_port_number(ntb);
1629 peer_port = ntb_peer_logical_port_number(ntb, pidx);
1630
1631 if (peer_port < local_port)
1632 return local_port - 1;
1633 else
1634 return local_port;
1635}
1636
1637/**
1638 * ntb_peer_highest_mw_idx() - get a memory window index for a given peer idx
1639 * using the highest index memory windows first
1640 *
1641 * @ntb: NTB device context.
1642 * @pidx: Peer port index.
1643 *
1644 * Like ntb_peer_resource_idx(), except it returns indexes starting with
1645 * last memory window index.
1646 *
1647 * Return: the resource index to use for that peer.
1648 */
1649static inline int ntb_peer_highest_mw_idx(struct ntb_dev *ntb, int pidx)
1650{
1651 int ret;
1652
1653 ret = ntb_peer_resource_idx(ntb, pidx);
1654 if (ret < 0)
1655 return ret;
1656
1657 return ntb_mw_count(ntb, pidx) - ret - 1;
1658}
1659
1660struct ntb_msi_desc {
1661 u32 addr_offset;
1662 u32 data;
1663};
1664
1665#ifdef CONFIG_NTB_MSI
1666
1667int ntb_msi_init(struct ntb_dev *ntb, void (*desc_changed)(void *ctx));
1668int ntb_msi_setup_mws(struct ntb_dev *ntb);
1669void ntb_msi_clear_mws(struct ntb_dev *ntb);
1670int ntbm_msi_request_threaded_irq(struct ntb_dev *ntb, irq_handler_t handler,
1671 irq_handler_t thread_fn,
1672 const char *name, void *dev_id,
1673 struct ntb_msi_desc *msi_desc);
1674int ntb_msi_peer_trigger(struct ntb_dev *ntb, int peer,
1675 struct ntb_msi_desc *desc);
1676
1677#else /* not CONFIG_NTB_MSI */
1678
1679static inline int ntb_msi_init(struct ntb_dev *ntb,
1680 void (*desc_changed)(void *ctx))
1681{
1682 return -EOPNOTSUPP;
1683}
1684static inline int ntb_msi_setup_mws(struct ntb_dev *ntb)
1685{
1686 return -EOPNOTSUPP;
1687}
1688static inline void ntb_msi_clear_mws(struct ntb_dev *ntb) {}
1689static inline int ntbm_msi_request_threaded_irq(struct ntb_dev *ntb,
1690 irq_handler_t handler,
1691 irq_handler_t thread_fn,
1692 const char *name, void *dev_id,
1693 struct ntb_msi_desc *msi_desc)
1694{
1695 return -EOPNOTSUPP;
1696}
1697static inline int ntb_msi_peer_trigger(struct ntb_dev *ntb, int peer,
1698 struct ntb_msi_desc *desc)
1699{
1700 return -EOPNOTSUPP;
1701}
1702#endif /* CONFIG_NTB_MSI */
1703
1704static inline int ntbm_msi_request_irq(struct ntb_dev *ntb,
1705 irq_handler_t handler,
1706 const char *name, void *dev_id,
1707 struct ntb_msi_desc *msi_desc)
1708{
1709 return ntbm_msi_request_threaded_irq(ntb, handler, NULL, name,
1710 dev_id, msi_desc);
1711}
1712
1713#endif