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
62 struct ntb_client;
63 struct ntb_dev;
64 struct pci_dev;
65
66 /**
67 * enum ntb_topo - NTB connection topology
68 * @NTB_TOPO_NONE: Topology is unknown or invalid.
69 * @NTB_TOPO_PRI: On primary side of local ntb.
70 * @NTB_TOPO_SEC: On secondary side of remote ntb.
71 * @NTB_TOPO_B2B_USD: On primary side of local ntb upstream of remote ntb.
72 * @NTB_TOPO_B2B_DSD: On primary side of local ntb downstream of remote ntb.
73 */
74 enum ntb_topo {
75 NTB_TOPO_NONE = -1,
76 NTB_TOPO_PRI,
77 NTB_TOPO_SEC,
78 NTB_TOPO_B2B_USD,
79 NTB_TOPO_B2B_DSD,
80 };
81
ntb_topo_is_b2b(enum ntb_topo topo)82 static inline int ntb_topo_is_b2b(enum ntb_topo topo)
83 {
84 switch ((int)topo) {
85 case NTB_TOPO_B2B_USD:
86 case NTB_TOPO_B2B_DSD:
87 return 1;
88 }
89 return 0;
90 }
91
ntb_topo_string(enum ntb_topo topo)92 static inline char *ntb_topo_string(enum ntb_topo topo)
93 {
94 switch (topo) {
95 case NTB_TOPO_NONE: return "NTB_TOPO_NONE";
96 case NTB_TOPO_PRI: return "NTB_TOPO_PRI";
97 case NTB_TOPO_SEC: return "NTB_TOPO_SEC";
98 case NTB_TOPO_B2B_USD: return "NTB_TOPO_B2B_USD";
99 case NTB_TOPO_B2B_DSD: return "NTB_TOPO_B2B_DSD";
100 }
101 return "NTB_TOPO_INVALID";
102 }
103
104 /**
105 * enum ntb_speed - NTB link training speed
106 * @NTB_SPEED_AUTO: Request the max supported speed.
107 * @NTB_SPEED_NONE: Link is not trained to any speed.
108 * @NTB_SPEED_GEN1: Link is trained to gen1 speed.
109 * @NTB_SPEED_GEN2: Link is trained to gen2 speed.
110 * @NTB_SPEED_GEN3: Link is trained to gen3 speed.
111 * @NTB_SPEED_GEN4: Link is trained to gen4 speed.
112 */
113 enum ntb_speed {
114 NTB_SPEED_AUTO = -1,
115 NTB_SPEED_NONE = 0,
116 NTB_SPEED_GEN1 = 1,
117 NTB_SPEED_GEN2 = 2,
118 NTB_SPEED_GEN3 = 3,
119 NTB_SPEED_GEN4 = 4
120 };
121
122 /**
123 * enum ntb_width - NTB link training width
124 * @NTB_WIDTH_AUTO: Request the max supported width.
125 * @NTB_WIDTH_NONE: Link is not trained to any width.
126 * @NTB_WIDTH_1: Link is trained to 1 lane width.
127 * @NTB_WIDTH_2: Link is trained to 2 lane width.
128 * @NTB_WIDTH_4: Link is trained to 4 lane width.
129 * @NTB_WIDTH_8: Link is trained to 8 lane width.
130 * @NTB_WIDTH_12: Link is trained to 12 lane width.
131 * @NTB_WIDTH_16: Link is trained to 16 lane width.
132 * @NTB_WIDTH_32: Link is trained to 32 lane width.
133 */
134 enum ntb_width {
135 NTB_WIDTH_AUTO = -1,
136 NTB_WIDTH_NONE = 0,
137 NTB_WIDTH_1 = 1,
138 NTB_WIDTH_2 = 2,
139 NTB_WIDTH_4 = 4,
140 NTB_WIDTH_8 = 8,
141 NTB_WIDTH_12 = 12,
142 NTB_WIDTH_16 = 16,
143 NTB_WIDTH_32 = 32,
144 };
145
146 /**
147 * enum ntb_default_port - NTB default port number
148 * @NTB_PORT_PRI_USD: Default port of the NTB_TOPO_PRI/NTB_TOPO_B2B_USD
149 * topologies
150 * @NTB_PORT_SEC_DSD: Default port of the NTB_TOPO_SEC/NTB_TOPO_B2B_DSD
151 * topologies
152 */
153 enum ntb_default_port {
154 NTB_PORT_PRI_USD,
155 NTB_PORT_SEC_DSD
156 };
157 #define NTB_DEF_PEER_CNT (1)
158 #define NTB_DEF_PEER_IDX (0)
159
160 /**
161 * struct ntb_client_ops - ntb client operations
162 * @probe: Notify client of a new device.
163 * @remove: Notify client to remove a device.
164 */
165 struct ntb_client_ops {
166 int (*probe)(struct ntb_client *client, struct ntb_dev *ntb);
167 void (*remove)(struct ntb_client *client, struct ntb_dev *ntb);
168 };
169
ntb_client_ops_is_valid(const struct ntb_client_ops * ops)170 static inline int ntb_client_ops_is_valid(const struct ntb_client_ops *ops)
171 {
172 /* commented callbacks are not required: */
173 return
174 ops->probe &&
175 ops->remove &&
176 1;
177 }
178
179 /**
180 * struct ntb_ctx_ops - ntb driver context operations
181 * @link_event: See ntb_link_event().
182 * @db_event: See ntb_db_event().
183 * @msg_event: See ntb_msg_event().
184 */
185 struct ntb_ctx_ops {
186 void (*link_event)(void *ctx);
187 void (*db_event)(void *ctx, int db_vector);
188 void (*msg_event)(void *ctx);
189 };
190
ntb_ctx_ops_is_valid(const struct ntb_ctx_ops * ops)191 static inline int ntb_ctx_ops_is_valid(const struct ntb_ctx_ops *ops)
192 {
193 /* commented callbacks are not required: */
194 return
195 /* ops->link_event && */
196 /* ops->db_event && */
197 /* ops->msg_event && */
198 1;
199 }
200
201 /**
202 * struct ntb_ctx_ops - ntb device operations
203 * @port_number: See ntb_port_number().
204 * @peer_port_count: See ntb_peer_port_count().
205 * @peer_port_number: See ntb_peer_port_number().
206 * @peer_port_idx: See ntb_peer_port_idx().
207 * @link_is_up: See ntb_link_is_up().
208 * @link_enable: See ntb_link_enable().
209 * @link_disable: See ntb_link_disable().
210 * @mw_count: See ntb_mw_count().
211 * @mw_get_align: See ntb_mw_get_align().
212 * @mw_set_trans: See ntb_mw_set_trans().
213 * @mw_clear_trans: See ntb_mw_clear_trans().
214 * @peer_mw_count: See ntb_peer_mw_count().
215 * @peer_mw_get_addr: See ntb_peer_mw_get_addr().
216 * @peer_mw_set_trans: See ntb_peer_mw_set_trans().
217 * @peer_mw_clear_trans:See ntb_peer_mw_clear_trans().
218 * @db_is_unsafe: See ntb_db_is_unsafe().
219 * @db_valid_mask: See ntb_db_valid_mask().
220 * @db_vector_count: See ntb_db_vector_count().
221 * @db_vector_mask: See ntb_db_vector_mask().
222 * @db_read: See ntb_db_read().
223 * @db_set: See ntb_db_set().
224 * @db_clear: See ntb_db_clear().
225 * @db_read_mask: See ntb_db_read_mask().
226 * @db_set_mask: See ntb_db_set_mask().
227 * @db_clear_mask: See ntb_db_clear_mask().
228 * @peer_db_addr: See ntb_peer_db_addr().
229 * @peer_db_read: See ntb_peer_db_read().
230 * @peer_db_set: See ntb_peer_db_set().
231 * @peer_db_clear: See ntb_peer_db_clear().
232 * @peer_db_read_mask: See ntb_peer_db_read_mask().
233 * @peer_db_set_mask: See ntb_peer_db_set_mask().
234 * @peer_db_clear_mask: See ntb_peer_db_clear_mask().
235 * @spad_is_unsafe: See ntb_spad_is_unsafe().
236 * @spad_count: See ntb_spad_count().
237 * @spad_read: See ntb_spad_read().
238 * @spad_write: See ntb_spad_write().
239 * @peer_spad_addr: See ntb_peer_spad_addr().
240 * @peer_spad_read: See ntb_peer_spad_read().
241 * @peer_spad_write: See ntb_peer_spad_write().
242 * @msg_count: See ntb_msg_count().
243 * @msg_inbits: See ntb_msg_inbits().
244 * @msg_outbits: See ntb_msg_outbits().
245 * @msg_read_sts: See ntb_msg_read_sts().
246 * @msg_clear_sts: See ntb_msg_clear_sts().
247 * @msg_set_mask: See ntb_msg_set_mask().
248 * @msg_clear_mask: See ntb_msg_clear_mask().
249 * @msg_read: See ntb_msg_read().
250 * @msg_write: See ntb_msg_write().
251 */
252 struct ntb_dev_ops {
253 int (*port_number)(struct ntb_dev *ntb);
254 int (*peer_port_count)(struct ntb_dev *ntb);
255 int (*peer_port_number)(struct ntb_dev *ntb, int pidx);
256 int (*peer_port_idx)(struct ntb_dev *ntb, int port);
257
258 u64 (*link_is_up)(struct ntb_dev *ntb,
259 enum ntb_speed *speed, enum ntb_width *width);
260 int (*link_enable)(struct ntb_dev *ntb,
261 enum ntb_speed max_speed, enum ntb_width max_width);
262 int (*link_disable)(struct ntb_dev *ntb);
263
264 int (*mw_count)(struct ntb_dev *ntb, int pidx);
265 int (*mw_get_align)(struct ntb_dev *ntb, int pidx, int widx,
266 resource_size_t *addr_align,
267 resource_size_t *size_align,
268 resource_size_t *size_max);
269 int (*mw_set_trans)(struct ntb_dev *ntb, int pidx, int widx,
270 dma_addr_t addr, resource_size_t size);
271 int (*mw_clear_trans)(struct ntb_dev *ntb, int pidx, int widx);
272 int (*peer_mw_count)(struct ntb_dev *ntb);
273 int (*peer_mw_get_addr)(struct ntb_dev *ntb, int widx,
274 phys_addr_t *base, resource_size_t *size);
275 int (*peer_mw_set_trans)(struct ntb_dev *ntb, int pidx, int widx,
276 u64 addr, resource_size_t size);
277 int (*peer_mw_clear_trans)(struct ntb_dev *ntb, int pidx, int widx);
278
279 int (*db_is_unsafe)(struct ntb_dev *ntb);
280 u64 (*db_valid_mask)(struct ntb_dev *ntb);
281 int (*db_vector_count)(struct ntb_dev *ntb);
282 u64 (*db_vector_mask)(struct ntb_dev *ntb, int db_vector);
283
284 u64 (*db_read)(struct ntb_dev *ntb);
285 int (*db_set)(struct ntb_dev *ntb, u64 db_bits);
286 int (*db_clear)(struct ntb_dev *ntb, u64 db_bits);
287
288 u64 (*db_read_mask)(struct ntb_dev *ntb);
289 int (*db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
290 int (*db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
291
292 int (*peer_db_addr)(struct ntb_dev *ntb,
293 phys_addr_t *db_addr, resource_size_t *db_size);
294 u64 (*peer_db_read)(struct ntb_dev *ntb);
295 int (*peer_db_set)(struct ntb_dev *ntb, u64 db_bits);
296 int (*peer_db_clear)(struct ntb_dev *ntb, u64 db_bits);
297
298 u64 (*peer_db_read_mask)(struct ntb_dev *ntb);
299 int (*peer_db_set_mask)(struct ntb_dev *ntb, u64 db_bits);
300 int (*peer_db_clear_mask)(struct ntb_dev *ntb, u64 db_bits);
301
302 int (*spad_is_unsafe)(struct ntb_dev *ntb);
303 int (*spad_count)(struct ntb_dev *ntb);
304
305 u32 (*spad_read)(struct ntb_dev *ntb, int sidx);
306 int (*spad_write)(struct ntb_dev *ntb, int sidx, u32 val);
307
308 int (*peer_spad_addr)(struct ntb_dev *ntb, int pidx, int sidx,
309 phys_addr_t *spad_addr);
310 u32 (*peer_spad_read)(struct ntb_dev *ntb, int pidx, int sidx);
311 int (*peer_spad_write)(struct ntb_dev *ntb, int pidx, int sidx,
312 u32 val);
313
314 int (*msg_count)(struct ntb_dev *ntb);
315 u64 (*msg_inbits)(struct ntb_dev *ntb);
316 u64 (*msg_outbits)(struct ntb_dev *ntb);
317 u64 (*msg_read_sts)(struct ntb_dev *ntb);
318 int (*msg_clear_sts)(struct ntb_dev *ntb, u64 sts_bits);
319 int (*msg_set_mask)(struct ntb_dev *ntb, u64 mask_bits);
320 int (*msg_clear_mask)(struct ntb_dev *ntb, u64 mask_bits);
321 int (*msg_read)(struct ntb_dev *ntb, int midx, int *pidx, u32 *msg);
322 int (*msg_write)(struct ntb_dev *ntb, int midx, int pidx, u32 msg);
323 };
324
ntb_dev_ops_is_valid(const struct ntb_dev_ops * ops)325 static inline int ntb_dev_ops_is_valid(const struct ntb_dev_ops *ops)
326 {
327 /* commented callbacks are not required: */
328 return
329 /* Port operations are required for multiport devices */
330 !ops->peer_port_count == !ops->port_number &&
331 !ops->peer_port_number == !ops->port_number &&
332 !ops->peer_port_idx == !ops->port_number &&
333
334 /* Link operations are required */
335 ops->link_is_up &&
336 ops->link_enable &&
337 ops->link_disable &&
338
339 /* One or both MW interfaces should be developed */
340 ops->mw_count &&
341 ops->mw_get_align &&
342 (ops->mw_set_trans ||
343 ops->peer_mw_set_trans) &&
344 /* ops->mw_clear_trans && */
345 ops->peer_mw_count &&
346 ops->peer_mw_get_addr &&
347 /* ops->peer_mw_clear_trans && */
348
349 /* Doorbell operations are mostly required */
350 /* ops->db_is_unsafe && */
351 ops->db_valid_mask &&
352 /* both set, or both unset */
353 (!ops->db_vector_count == !ops->db_vector_mask) &&
354 ops->db_read &&
355 /* ops->db_set && */
356 ops->db_clear &&
357 /* ops->db_read_mask && */
358 ops->db_set_mask &&
359 ops->db_clear_mask &&
360 /* ops->peer_db_addr && */
361 /* ops->peer_db_read && */
362 ops->peer_db_set &&
363 /* ops->peer_db_clear && */
364 /* ops->peer_db_read_mask && */
365 /* ops->peer_db_set_mask && */
366 /* ops->peer_db_clear_mask && */
367
368 /* Scrachpads interface is optional */
369 /* !ops->spad_is_unsafe == !ops->spad_count && */
370 !ops->spad_read == !ops->spad_count &&
371 !ops->spad_write == !ops->spad_count &&
372 /* !ops->peer_spad_addr == !ops->spad_count && */
373 /* !ops->peer_spad_read == !ops->spad_count && */
374 !ops->peer_spad_write == !ops->spad_count &&
375
376 /* Messaging interface is optional */
377 !ops->msg_inbits == !ops->msg_count &&
378 !ops->msg_outbits == !ops->msg_count &&
379 !ops->msg_read_sts == !ops->msg_count &&
380 !ops->msg_clear_sts == !ops->msg_count &&
381 /* !ops->msg_set_mask == !ops->msg_count && */
382 /* !ops->msg_clear_mask == !ops->msg_count && */
383 !ops->msg_read == !ops->msg_count &&
384 !ops->msg_write == !ops->msg_count &&
385 1;
386 }
387
388 /**
389 * struct ntb_client - client interested in ntb devices
390 * @drv: Linux driver object.
391 * @ops: See &ntb_client_ops.
392 */
393 struct ntb_client {
394 struct device_driver drv;
395 const struct ntb_client_ops ops;
396 };
397 #define drv_ntb_client(__drv) container_of((__drv), struct ntb_client, drv)
398
399 /**
400 * struct ntb_device - ntb device
401 * @dev: Linux device object.
402 * @pdev: PCI device entry of the ntb.
403 * @topo: Detected topology of the ntb.
404 * @ops: See &ntb_dev_ops.
405 * @ctx: See &ntb_ctx_ops.
406 * @ctx_ops: See &ntb_ctx_ops.
407 */
408 struct ntb_dev {
409 struct device dev;
410 struct pci_dev *pdev;
411 enum ntb_topo topo;
412 const struct ntb_dev_ops *ops;
413 void *ctx;
414 const struct ntb_ctx_ops *ctx_ops;
415
416 /* private: */
417
418 /* synchronize setting, clearing, and calling ctx_ops */
419 spinlock_t ctx_lock;
420 /* block unregister until device is fully released */
421 struct completion released;
422 };
423 #define dev_ntb(__dev) container_of((__dev), struct ntb_dev, dev)
424
425 /**
426 * ntb_register_client() - register a client for interest in ntb devices
427 * @client: Client context.
428 *
429 * The client will be added to the list of clients interested in ntb devices.
430 * The client will be notified of any ntb devices that are not already
431 * associated with a client, or if ntb devices are registered later.
432 *
433 * Return: Zero if the client is registered, otherwise an error number.
434 */
435 #define ntb_register_client(client) \
436 __ntb_register_client((client), THIS_MODULE, KBUILD_MODNAME)
437
438 int __ntb_register_client(struct ntb_client *client, struct module *mod,
439 const char *mod_name);
440
441 /**
442 * ntb_unregister_client() - unregister a client for interest in ntb devices
443 * @client: Client context.
444 *
445 * The client will be removed from the list of clients interested in ntb
446 * devices. If any ntb devices are associated with the client, the client will
447 * be notified to remove those devices.
448 */
449 void ntb_unregister_client(struct ntb_client *client);
450
451 #define module_ntb_client(__ntb_client) \
452 module_driver(__ntb_client, ntb_register_client, \
453 ntb_unregister_client)
454
455 /**
456 * ntb_register_device() - register a ntb device
457 * @ntb: NTB device context.
458 *
459 * The device will be added to the list of ntb devices. If any clients are
460 * interested in ntb devices, each client will be notified of the ntb device,
461 * until at most one client accepts the device.
462 *
463 * Return: Zero if the device is registered, otherwise an error number.
464 */
465 int ntb_register_device(struct ntb_dev *ntb);
466
467 /**
468 * ntb_register_device() - unregister a ntb device
469 * @ntb: NTB device context.
470 *
471 * The device will be removed from the list of ntb devices. If the ntb device
472 * is associated with a client, the client will be notified to remove the
473 * device.
474 */
475 void ntb_unregister_device(struct ntb_dev *ntb);
476
477 /**
478 * ntb_set_ctx() - associate a driver context with an ntb device
479 * @ntb: NTB device context.
480 * @ctx: Driver context.
481 * @ctx_ops: Driver context operations.
482 *
483 * Associate a driver context and operations with a ntb device. The context is
484 * provided by the client driver, and the driver may associate a different
485 * context with each ntb device.
486 *
487 * Return: Zero if the context is associated, otherwise an error number.
488 */
489 int ntb_set_ctx(struct ntb_dev *ntb, void *ctx,
490 const struct ntb_ctx_ops *ctx_ops);
491
492 /**
493 * ntb_clear_ctx() - disassociate any driver context from an ntb device
494 * @ntb: NTB device context.
495 *
496 * Clear any association that may exist between a driver context and the ntb
497 * device.
498 */
499 void ntb_clear_ctx(struct ntb_dev *ntb);
500
501 /**
502 * ntb_link_event() - notify driver context of a change in link status
503 * @ntb: NTB device context.
504 *
505 * Notify the driver context that the link status may have changed. The driver
506 * should call ntb_link_is_up() to get the current status.
507 */
508 void ntb_link_event(struct ntb_dev *ntb);
509
510 /**
511 * ntb_db_event() - notify driver context of a doorbell event
512 * @ntb: NTB device context.
513 * @vector: Interrupt vector number.
514 *
515 * Notify the driver context of a doorbell event. If hardware supports
516 * multiple interrupt vectors for doorbells, the vector number indicates which
517 * vector received the interrupt. The vector number is relative to the first
518 * vector used for doorbells, starting at zero, and must be less than
519 * ntb_db_vector_count(). The driver may call ntb_db_read() to check which
520 * doorbell bits need service, and ntb_db_vector_mask() to determine which of
521 * those bits are associated with the vector number.
522 */
523 void ntb_db_event(struct ntb_dev *ntb, int vector);
524
525 /**
526 * ntb_msg_event() - notify driver context of a message event
527 * @ntb: NTB device context.
528 *
529 * Notify the driver context of a message event. If hardware supports
530 * message registers, this event indicates, that a new message arrived in
531 * some incoming message register or last sent message couldn't be delivered.
532 * The events can be masked/unmasked by the methods ntb_msg_set_mask() and
533 * ntb_msg_clear_mask().
534 */
535 void ntb_msg_event(struct ntb_dev *ntb);
536
537 /**
538 * ntb_default_port_number() - get the default local port number
539 * @ntb: NTB device context.
540 *
541 * If hardware driver doesn't specify port_number() callback method, the NTB
542 * is considered with just two ports. So this method returns default local
543 * port number in compliance with topology.
544 *
545 * NOTE Don't call this method directly. The ntb_port_number() function should
546 * be used instead.
547 *
548 * Return: the default local port number
549 */
550 int ntb_default_port_number(struct ntb_dev *ntb);
551
552 /**
553 * ntb_default_port_count() - get the default number of peer device ports
554 * @ntb: NTB device context.
555 *
556 * By default hardware driver supports just one peer device.
557 *
558 * NOTE Don't call this method directly. The ntb_peer_port_count() function
559 * should be used instead.
560 *
561 * Return: the default number of peer ports
562 */
563 int ntb_default_peer_port_count(struct ntb_dev *ntb);
564
565 /**
566 * ntb_default_peer_port_number() - get the default peer port by given index
567 * @ntb: NTB device context.
568 * @idx: Peer port index (should not differ from zero).
569 *
570 * By default hardware driver supports just one peer device, so this method
571 * shall return the corresponding value from enum ntb_default_port.
572 *
573 * NOTE Don't call this method directly. The ntb_peer_port_number() function
574 * should be used instead.
575 *
576 * Return: the peer device port or negative value indicating an error
577 */
578 int ntb_default_peer_port_number(struct ntb_dev *ntb, int pidx);
579
580 /**
581 * ntb_default_peer_port_idx() - get the default peer device port index by
582 * given port number
583 * @ntb: NTB device context.
584 * @port: Peer port number (should be one of enum ntb_default_port).
585 *
586 * By default hardware driver supports just one peer device, so while
587 * specified port-argument indicates peer port from enum ntb_default_port,
588 * the return value shall be zero.
589 *
590 * NOTE Don't call this method directly. The ntb_peer_port_idx() function
591 * should be used instead.
592 *
593 * Return: the peer port index or negative value indicating an error
594 */
595 int ntb_default_peer_port_idx(struct ntb_dev *ntb, int port);
596
597 /**
598 * ntb_port_number() - get the local port number
599 * @ntb: NTB device context.
600 *
601 * Hardware must support at least simple two-ports ntb connection
602 *
603 * Return: the local port number
604 */
ntb_port_number(struct ntb_dev * ntb)605 static inline int ntb_port_number(struct ntb_dev *ntb)
606 {
607 if (!ntb->ops->port_number)
608 return ntb_default_port_number(ntb);
609
610 return ntb->ops->port_number(ntb);
611 }
612
613 /**
614 * ntb_peer_port_count() - get the number of peer device ports
615 * @ntb: NTB device context.
616 *
617 * Hardware may support an access to memory of several remote domains
618 * over multi-port NTB devices. This method returns the number of peers,
619 * local device can have shared memory with.
620 *
621 * Return: the number of peer ports
622 */
ntb_peer_port_count(struct ntb_dev * ntb)623 static inline int ntb_peer_port_count(struct ntb_dev *ntb)
624 {
625 if (!ntb->ops->peer_port_count)
626 return ntb_default_peer_port_count(ntb);
627
628 return ntb->ops->peer_port_count(ntb);
629 }
630
631 /**
632 * ntb_peer_port_number() - get the peer port by given index
633 * @ntb: NTB device context.
634 * @pidx: Peer port index.
635 *
636 * Peer ports are continuously enumerated by NTB API logic, so this method
637 * lets to retrieve port real number by its index.
638 *
639 * Return: the peer device port or negative value indicating an error
640 */
ntb_peer_port_number(struct ntb_dev * ntb,int pidx)641 static inline int ntb_peer_port_number(struct ntb_dev *ntb, int pidx)
642 {
643 if (!ntb->ops->peer_port_number)
644 return ntb_default_peer_port_number(ntb, pidx);
645
646 return ntb->ops->peer_port_number(ntb, pidx);
647 }
648
649 /**
650 * ntb_peer_port_idx() - get the peer device port index by given port number
651 * @ntb: NTB device context.
652 * @port: Peer port number.
653 *
654 * Inverse operation of ntb_peer_port_number(), so one can get port index
655 * by specified port number.
656 *
657 * Return: the peer port index or negative value indicating an error
658 */
ntb_peer_port_idx(struct ntb_dev * ntb,int port)659 static inline int ntb_peer_port_idx(struct ntb_dev *ntb, int port)
660 {
661 if (!ntb->ops->peer_port_idx)
662 return ntb_default_peer_port_idx(ntb, port);
663
664 return ntb->ops->peer_port_idx(ntb, port);
665 }
666
667 /**
668 * ntb_link_is_up() - get the current ntb link state
669 * @ntb: NTB device context.
670 * @speed: OUT - The link speed expressed as PCIe generation number.
671 * @width: OUT - The link width expressed as the number of PCIe lanes.
672 *
673 * Get the current state of the ntb link. It is recommended to query the link
674 * state once after every link event. It is safe to query the link state in
675 * the context of the link event callback.
676 *
677 * Return: bitfield of indexed ports link state: bit is set/cleared if the
678 * link is up/down respectively.
679 */
ntb_link_is_up(struct ntb_dev * ntb,enum ntb_speed * speed,enum ntb_width * width)680 static inline u64 ntb_link_is_up(struct ntb_dev *ntb,
681 enum ntb_speed *speed, enum ntb_width *width)
682 {
683 return ntb->ops->link_is_up(ntb, speed, width);
684 }
685
686 /**
687 * ntb_link_enable() - enable the local port ntb connection
688 * @ntb: NTB device context.
689 * @max_speed: The maximum link speed expressed as PCIe generation number.
690 * @max_width: The maximum link width expressed as the number of PCIe lanes.
691 *
692 * Enable the NTB/PCIe link on the local or remote (for bridge-to-bridge
693 * topology) side of the bridge. If it's supported the ntb device should train
694 * the link to its maximum speed and width, or the requested speed and width,
695 * whichever is smaller. Some hardware doesn't support PCIe link training, so
696 * the last two arguments will be ignored then.
697 *
698 * Return: Zero on success, otherwise an error number.
699 */
ntb_link_enable(struct ntb_dev * ntb,enum ntb_speed max_speed,enum ntb_width max_width)700 static inline int ntb_link_enable(struct ntb_dev *ntb,
701 enum ntb_speed max_speed,
702 enum ntb_width max_width)
703 {
704 return ntb->ops->link_enable(ntb, max_speed, max_width);
705 }
706
707 /**
708 * ntb_link_disable() - disable the local port ntb connection
709 * @ntb: NTB device context.
710 *
711 * Disable the link on the local or remote (for b2b topology) of the ntb.
712 * The ntb device should disable the link. Returning from this call must
713 * indicate that a barrier has passed, though with no more writes may pass in
714 * either direction across the link, except if this call returns an error
715 * number.
716 *
717 * Return: Zero on success, otherwise an error number.
718 */
ntb_link_disable(struct ntb_dev * ntb)719 static inline int ntb_link_disable(struct ntb_dev *ntb)
720 {
721 return ntb->ops->link_disable(ntb);
722 }
723
724 /**
725 * ntb_mw_count() - get the number of inbound memory windows, which could
726 * be created for a specified peer device
727 * @ntb: NTB device context.
728 * @pidx: Port index of peer device.
729 *
730 * Hardware and topology may support a different number of memory windows.
731 * Moreover different peer devices can support different number of memory
732 * windows. Simply speaking this method returns the number of possible inbound
733 * memory windows to share with specified peer device.
734 *
735 * Return: the number of memory windows.
736 */
ntb_mw_count(struct ntb_dev * ntb,int pidx)737 static inline int ntb_mw_count(struct ntb_dev *ntb, int pidx)
738 {
739 return ntb->ops->mw_count(ntb, pidx);
740 }
741
742 /**
743 * ntb_mw_get_align() - get the restriction parameters of inbound memory window
744 * @ntb: NTB device context.
745 * @pidx: Port index of peer device.
746 * @widx: Memory window index.
747 * @addr_align: OUT - the base alignment for translating the memory window
748 * @size_align: OUT - the size alignment for translating the memory window
749 * @size_max: OUT - the maximum size of the memory window
750 *
751 * Get the alignments of an inbound memory window with specified index.
752 * NULL may be given for any output parameter if the value is not needed.
753 * The alignment and size parameters may be used for allocation of proper
754 * shared memory.
755 *
756 * Return: Zero on success, otherwise a negative error number.
757 */
ntb_mw_get_align(struct ntb_dev * ntb,int pidx,int widx,resource_size_t * addr_align,resource_size_t * size_align,resource_size_t * size_max)758 static inline int ntb_mw_get_align(struct ntb_dev *ntb, int pidx, int widx,
759 resource_size_t *addr_align,
760 resource_size_t *size_align,
761 resource_size_t *size_max)
762 {
763 return ntb->ops->mw_get_align(ntb, pidx, widx, addr_align, size_align,
764 size_max);
765 }
766
767 /**
768 * ntb_mw_set_trans() - set the translation of an inbound memory window
769 * @ntb: NTB device context.
770 * @pidx: Port index of peer device.
771 * @widx: Memory window index.
772 * @addr: The dma address of local memory to expose to the peer.
773 * @size: The size of the local memory to expose to the peer.
774 *
775 * Set the translation of a memory window. The peer may access local memory
776 * through the window starting at the address, up to the size. The address
777 * and size must be aligned in compliance with restrictions of
778 * ntb_mw_get_align(). The region size should not exceed the size_max parameter
779 * of that method.
780 *
781 * This method may not be implemented due to the hardware specific memory
782 * windows interface.
783 *
784 * Return: Zero on success, otherwise an error number.
785 */
ntb_mw_set_trans(struct ntb_dev * ntb,int pidx,int widx,dma_addr_t addr,resource_size_t size)786 static inline int ntb_mw_set_trans(struct ntb_dev *ntb, int pidx, int widx,
787 dma_addr_t addr, resource_size_t size)
788 {
789 if (!ntb->ops->mw_set_trans)
790 return 0;
791
792 return ntb->ops->mw_set_trans(ntb, pidx, widx, addr, size);
793 }
794
795 /**
796 * ntb_mw_clear_trans() - clear the translation address of an inbound memory
797 * window
798 * @ntb: NTB device context.
799 * @pidx: Port index of peer device.
800 * @widx: Memory window index.
801 *
802 * Clear the translation of an inbound memory window. The peer may no longer
803 * access local memory through the window.
804 *
805 * Return: Zero on success, otherwise an error number.
806 */
ntb_mw_clear_trans(struct ntb_dev * ntb,int pidx,int widx)807 static inline int ntb_mw_clear_trans(struct ntb_dev *ntb, int pidx, int widx)
808 {
809 if (!ntb->ops->mw_clear_trans)
810 return ntb_mw_set_trans(ntb, pidx, widx, 0, 0);
811
812 return ntb->ops->mw_clear_trans(ntb, pidx, widx);
813 }
814
815 /**
816 * ntb_peer_mw_count() - get the number of outbound memory windows, which could
817 * be mapped to access a shared memory
818 * @ntb: NTB device context.
819 *
820 * Hardware and topology may support a different number of memory windows.
821 * This method returns the number of outbound memory windows supported by
822 * local device.
823 *
824 * Return: the number of memory windows.
825 */
ntb_peer_mw_count(struct ntb_dev * ntb)826 static inline int ntb_peer_mw_count(struct ntb_dev *ntb)
827 {
828 return ntb->ops->peer_mw_count(ntb);
829 }
830
831 /**
832 * ntb_peer_mw_get_addr() - get map address of an outbound memory window
833 * @ntb: NTB device context.
834 * @widx: Memory window index (within ntb_peer_mw_count() return value).
835 * @base: OUT - the base address of mapping region.
836 * @size: OUT - the size of mapping region.
837 *
838 * Get base and size of memory region to map. NULL may be given for any output
839 * parameter if the value is not needed. The base and size may be used for
840 * mapping the memory window, to access the peer memory.
841 *
842 * Return: Zero on success, otherwise a negative error number.
843 */
ntb_peer_mw_get_addr(struct ntb_dev * ntb,int widx,phys_addr_t * base,resource_size_t * size)844 static inline int ntb_peer_mw_get_addr(struct ntb_dev *ntb, int widx,
845 phys_addr_t *base, resource_size_t *size)
846 {
847 return ntb->ops->peer_mw_get_addr(ntb, widx, base, size);
848 }
849
850 /**
851 * ntb_peer_mw_set_trans() - set a translation address of a memory window
852 * retrieved from a peer device
853 * @ntb: NTB device context.
854 * @pidx: Port index of peer device the translation address received from.
855 * @widx: Memory window index.
856 * @addr: The dma address of the shared memory to access.
857 * @size: The size of the shared memory to access.
858 *
859 * Set the translation of an outbound memory window. The local device may
860 * access shared memory allocated by a peer device sent the address.
861 *
862 * This method may not be implemented due to the hardware specific memory
863 * windows interface, so a translation address can be only set on the side,
864 * where shared memory (inbound memory windows) is allocated.
865 *
866 * Return: Zero on success, otherwise an error number.
867 */
ntb_peer_mw_set_trans(struct ntb_dev * ntb,int pidx,int widx,u64 addr,resource_size_t size)868 static inline int ntb_peer_mw_set_trans(struct ntb_dev *ntb, int pidx, int widx,
869 u64 addr, resource_size_t size)
870 {
871 if (!ntb->ops->peer_mw_set_trans)
872 return 0;
873
874 return ntb->ops->peer_mw_set_trans(ntb, pidx, widx, addr, size);
875 }
876
877 /**
878 * ntb_peer_mw_clear_trans() - clear the translation address of an outbound
879 * memory window
880 * @ntb: NTB device context.
881 * @pidx: Port index of peer device.
882 * @widx: Memory window index.
883 *
884 * Clear the translation of a outbound memory window. The local device may no
885 * longer access a shared memory through the window.
886 *
887 * This method may not be implemented due to the hardware specific memory
888 * windows interface.
889 *
890 * Return: Zero on success, otherwise an error number.
891 */
ntb_peer_mw_clear_trans(struct ntb_dev * ntb,int pidx,int widx)892 static inline int ntb_peer_mw_clear_trans(struct ntb_dev *ntb, int pidx,
893 int widx)
894 {
895 if (!ntb->ops->peer_mw_clear_trans)
896 return ntb_peer_mw_set_trans(ntb, pidx, widx, 0, 0);
897
898 return ntb->ops->peer_mw_clear_trans(ntb, pidx, widx);
899 }
900
901 /**
902 * ntb_db_is_unsafe() - check if it is safe to use hardware doorbell
903 * @ntb: NTB device context.
904 *
905 * It is possible for some ntb hardware to be affected by errata. Hardware
906 * drivers can advise clients to avoid using doorbells. Clients may ignore
907 * this advice, though caution is recommended.
908 *
909 * Return: Zero if it is safe to use doorbells, or One if it is not safe.
910 */
ntb_db_is_unsafe(struct ntb_dev * ntb)911 static inline int ntb_db_is_unsafe(struct ntb_dev *ntb)
912 {
913 if (!ntb->ops->db_is_unsafe)
914 return 0;
915
916 return ntb->ops->db_is_unsafe(ntb);
917 }
918
919 /**
920 * ntb_db_valid_mask() - get a mask of doorbell bits supported by the ntb
921 * @ntb: NTB device context.
922 *
923 * Hardware may support different number or arrangement of doorbell bits.
924 *
925 * Return: A mask of doorbell bits supported by the ntb.
926 */
ntb_db_valid_mask(struct ntb_dev * ntb)927 static inline u64 ntb_db_valid_mask(struct ntb_dev *ntb)
928 {
929 return ntb->ops->db_valid_mask(ntb);
930 }
931
932 /**
933 * ntb_db_vector_count() - get the number of doorbell interrupt vectors
934 * @ntb: NTB device context.
935 *
936 * Hardware may support different number of interrupt vectors.
937 *
938 * Return: The number of doorbell interrupt vectors.
939 */
ntb_db_vector_count(struct ntb_dev * ntb)940 static inline int ntb_db_vector_count(struct ntb_dev *ntb)
941 {
942 if (!ntb->ops->db_vector_count)
943 return 1;
944
945 return ntb->ops->db_vector_count(ntb);
946 }
947
948 /**
949 * ntb_db_vector_mask() - get a mask of doorbell bits serviced by a vector
950 * @ntb: NTB device context.
951 * @vector: Doorbell vector number.
952 *
953 * Each interrupt vector may have a different number or arrangement of bits.
954 *
955 * Return: A mask of doorbell bits serviced by a vector.
956 */
ntb_db_vector_mask(struct ntb_dev * ntb,int vector)957 static inline u64 ntb_db_vector_mask(struct ntb_dev *ntb, int vector)
958 {
959 if (!ntb->ops->db_vector_mask)
960 return ntb_db_valid_mask(ntb);
961
962 return ntb->ops->db_vector_mask(ntb, vector);
963 }
964
965 /**
966 * ntb_db_read() - read the local doorbell register
967 * @ntb: NTB device context.
968 *
969 * Read the local doorbell register, and return the bits that are set.
970 *
971 * Return: The bits currently set in the local doorbell register.
972 */
ntb_db_read(struct ntb_dev * ntb)973 static inline u64 ntb_db_read(struct ntb_dev *ntb)
974 {
975 return ntb->ops->db_read(ntb);
976 }
977
978 /**
979 * ntb_db_set() - set bits in the local doorbell register
980 * @ntb: NTB device context.
981 * @db_bits: Doorbell bits to set.
982 *
983 * Set bits in the local doorbell register, which may generate a local doorbell
984 * interrupt. Bits that were already set must remain set.
985 *
986 * This is unusual, and hardware may not support it.
987 *
988 * Return: Zero on success, otherwise an error number.
989 */
ntb_db_set(struct ntb_dev * ntb,u64 db_bits)990 static inline int ntb_db_set(struct ntb_dev *ntb, u64 db_bits)
991 {
992 if (!ntb->ops->db_set)
993 return -EINVAL;
994
995 return ntb->ops->db_set(ntb, db_bits);
996 }
997
998 /**
999 * ntb_db_clear() - clear bits in the local doorbell register
1000 * @ntb: NTB device context.
1001 * @db_bits: Doorbell bits to clear.
1002 *
1003 * Clear bits in the local doorbell register, arming the bits for the next
1004 * doorbell.
1005 *
1006 * Return: Zero on success, otherwise an error number.
1007 */
ntb_db_clear(struct ntb_dev * ntb,u64 db_bits)1008 static inline int ntb_db_clear(struct ntb_dev *ntb, u64 db_bits)
1009 {
1010 return ntb->ops->db_clear(ntb, db_bits);
1011 }
1012
1013 /**
1014 * ntb_db_read_mask() - read the local doorbell mask
1015 * @ntb: NTB device context.
1016 *
1017 * Read the local doorbell mask register, and return the bits that are set.
1018 *
1019 * This is unusual, though hardware is likely to support it.
1020 *
1021 * Return: The bits currently set in the local doorbell mask register.
1022 */
ntb_db_read_mask(struct ntb_dev * ntb)1023 static inline u64 ntb_db_read_mask(struct ntb_dev *ntb)
1024 {
1025 if (!ntb->ops->db_read_mask)
1026 return 0;
1027
1028 return ntb->ops->db_read_mask(ntb);
1029 }
1030
1031 /**
1032 * ntb_db_set_mask() - set bits in the local doorbell mask
1033 * @ntb: NTB device context.
1034 * @db_bits: Doorbell mask bits to set.
1035 *
1036 * Set bits in the local doorbell mask register, preventing doorbell interrupts
1037 * from being generated for those doorbell bits. Bits that were already set
1038 * must remain set.
1039 *
1040 * Return: Zero on success, otherwise an error number.
1041 */
ntb_db_set_mask(struct ntb_dev * ntb,u64 db_bits)1042 static inline int ntb_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
1043 {
1044 return ntb->ops->db_set_mask(ntb, db_bits);
1045 }
1046
1047 /**
1048 * ntb_db_clear_mask() - clear bits in the local doorbell mask
1049 * @ntb: NTB device context.
1050 * @db_bits: Doorbell bits to clear.
1051 *
1052 * Clear bits in the local doorbell mask register, allowing doorbell interrupts
1053 * from being generated for those doorbell bits. If a doorbell bit is already
1054 * set at the time the mask is cleared, and the corresponding mask bit is
1055 * changed from set to clear, then the ntb driver must ensure that
1056 * ntb_db_event() is called. If the hardware does not generate the interrupt
1057 * on clearing the mask bit, then the driver must call ntb_db_event() anyway.
1058 *
1059 * Return: Zero on success, otherwise an error number.
1060 */
ntb_db_clear_mask(struct ntb_dev * ntb,u64 db_bits)1061 static inline int ntb_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
1062 {
1063 return ntb->ops->db_clear_mask(ntb, db_bits);
1064 }
1065
1066 /**
1067 * ntb_peer_db_addr() - address and size of the peer doorbell register
1068 * @ntb: NTB device context.
1069 * @db_addr: OUT - The address of the peer doorbell register.
1070 * @db_size: OUT - The number of bytes to write the peer doorbell register.
1071 *
1072 * Return the address of the peer doorbell register. This may be used, for
1073 * example, by drivers that offload memory copy operations to a dma engine.
1074 * The drivers may wish to ring the peer doorbell at the completion of memory
1075 * copy operations. For efficiency, and to simplify ordering of operations
1076 * between the dma memory copies and the ringing doorbell, the driver may
1077 * append one additional dma memory copy with the doorbell register as the
1078 * destination, after the memory copy operations.
1079 *
1080 * Return: Zero on success, otherwise an error number.
1081 */
ntb_peer_db_addr(struct ntb_dev * ntb,phys_addr_t * db_addr,resource_size_t * db_size)1082 static inline int ntb_peer_db_addr(struct ntb_dev *ntb,
1083 phys_addr_t *db_addr,
1084 resource_size_t *db_size)
1085 {
1086 if (!ntb->ops->peer_db_addr)
1087 return -EINVAL;
1088
1089 return ntb->ops->peer_db_addr(ntb, db_addr, db_size);
1090 }
1091
1092 /**
1093 * ntb_peer_db_read() - read the peer doorbell register
1094 * @ntb: NTB device context.
1095 *
1096 * Read the peer doorbell register, and return the bits that are set.
1097 *
1098 * This is unusual, and hardware may not support it.
1099 *
1100 * Return: The bits currently set in the peer doorbell register.
1101 */
ntb_peer_db_read(struct ntb_dev * ntb)1102 static inline u64 ntb_peer_db_read(struct ntb_dev *ntb)
1103 {
1104 if (!ntb->ops->peer_db_read)
1105 return 0;
1106
1107 return ntb->ops->peer_db_read(ntb);
1108 }
1109
1110 /**
1111 * ntb_peer_db_set() - set bits in the peer doorbell register
1112 * @ntb: NTB device context.
1113 * @db_bits: Doorbell bits to set.
1114 *
1115 * Set bits in the peer doorbell register, which may generate a peer doorbell
1116 * interrupt. Bits that were already set must remain set.
1117 *
1118 * Return: Zero on success, otherwise an error number.
1119 */
ntb_peer_db_set(struct ntb_dev * ntb,u64 db_bits)1120 static inline int ntb_peer_db_set(struct ntb_dev *ntb, u64 db_bits)
1121 {
1122 return ntb->ops->peer_db_set(ntb, db_bits);
1123 }
1124
1125 /**
1126 * ntb_peer_db_clear() - clear bits in the peer doorbell register
1127 * @ntb: NTB device context.
1128 * @db_bits: Doorbell bits to clear.
1129 *
1130 * Clear bits in the peer doorbell register, arming the bits for the next
1131 * doorbell.
1132 *
1133 * This is unusual, and hardware may not support it.
1134 *
1135 * Return: Zero on success, otherwise an error number.
1136 */
ntb_peer_db_clear(struct ntb_dev * ntb,u64 db_bits)1137 static inline int ntb_peer_db_clear(struct ntb_dev *ntb, u64 db_bits)
1138 {
1139 if (!ntb->ops->db_clear)
1140 return -EINVAL;
1141
1142 return ntb->ops->peer_db_clear(ntb, db_bits);
1143 }
1144
1145 /**
1146 * ntb_peer_db_read_mask() - read the peer doorbell mask
1147 * @ntb: NTB device context.
1148 *
1149 * Read the peer doorbell mask register, and return the bits that are set.
1150 *
1151 * This is unusual, and hardware may not support it.
1152 *
1153 * Return: The bits currently set in the peer doorbell mask register.
1154 */
ntb_peer_db_read_mask(struct ntb_dev * ntb)1155 static inline u64 ntb_peer_db_read_mask(struct ntb_dev *ntb)
1156 {
1157 if (!ntb->ops->db_read_mask)
1158 return 0;
1159
1160 return ntb->ops->peer_db_read_mask(ntb);
1161 }
1162
1163 /**
1164 * ntb_peer_db_set_mask() - set bits in the peer doorbell mask
1165 * @ntb: NTB device context.
1166 * @db_bits: Doorbell mask bits to set.
1167 *
1168 * Set bits in the peer doorbell mask register, preventing doorbell interrupts
1169 * from being generated for those doorbell bits. Bits that were already set
1170 * must remain set.
1171 *
1172 * This is unusual, and hardware may not support it.
1173 *
1174 * Return: Zero on success, otherwise an error number.
1175 */
ntb_peer_db_set_mask(struct ntb_dev * ntb,u64 db_bits)1176 static inline int ntb_peer_db_set_mask(struct ntb_dev *ntb, u64 db_bits)
1177 {
1178 if (!ntb->ops->db_set_mask)
1179 return -EINVAL;
1180
1181 return ntb->ops->peer_db_set_mask(ntb, db_bits);
1182 }
1183
1184 /**
1185 * ntb_peer_db_clear_mask() - clear bits in the peer doorbell mask
1186 * @ntb: NTB device context.
1187 * @db_bits: Doorbell bits to clear.
1188 *
1189 * Clear bits in the peer doorbell mask register, allowing doorbell interrupts
1190 * from being generated for those doorbell bits. If the hardware does not
1191 * generate the interrupt on clearing the mask bit, then the driver should not
1192 * implement this function!
1193 *
1194 * This is unusual, and hardware may not support it.
1195 *
1196 * Return: Zero on success, otherwise an error number.
1197 */
ntb_peer_db_clear_mask(struct ntb_dev * ntb,u64 db_bits)1198 static inline int ntb_peer_db_clear_mask(struct ntb_dev *ntb, u64 db_bits)
1199 {
1200 if (!ntb->ops->db_clear_mask)
1201 return -EINVAL;
1202
1203 return ntb->ops->peer_db_clear_mask(ntb, db_bits);
1204 }
1205
1206 /**
1207 * ntb_spad_is_unsafe() - check if it is safe to use the hardware scratchpads
1208 * @ntb: NTB device context.
1209 *
1210 * It is possible for some ntb hardware to be affected by errata. Hardware
1211 * drivers can advise clients to avoid using scratchpads. Clients may ignore
1212 * this advice, though caution is recommended.
1213 *
1214 * Return: Zero if it is safe to use scratchpads, or One if it is not safe.
1215 */
ntb_spad_is_unsafe(struct ntb_dev * ntb)1216 static inline int ntb_spad_is_unsafe(struct ntb_dev *ntb)
1217 {
1218 if (!ntb->ops->spad_is_unsafe)
1219 return 0;
1220
1221 return ntb->ops->spad_is_unsafe(ntb);
1222 }
1223
1224 /**
1225 * ntb_spad_count() - get the number of scratchpads
1226 * @ntb: NTB device context.
1227 *
1228 * Hardware and topology may support a different number of scratchpads.
1229 * Although it must be the same for all ports per NTB device.
1230 *
1231 * Return: the number of scratchpads.
1232 */
ntb_spad_count(struct ntb_dev * ntb)1233 static inline int ntb_spad_count(struct ntb_dev *ntb)
1234 {
1235 if (!ntb->ops->spad_count)
1236 return 0;
1237
1238 return ntb->ops->spad_count(ntb);
1239 }
1240
1241 /**
1242 * ntb_spad_read() - read the local scratchpad register
1243 * @ntb: NTB device context.
1244 * @sidx: Scratchpad index.
1245 *
1246 * Read the local scratchpad register, and return the value.
1247 *
1248 * Return: The value of the local scratchpad register.
1249 */
ntb_spad_read(struct ntb_dev * ntb,int sidx)1250 static inline u32 ntb_spad_read(struct ntb_dev *ntb, int sidx)
1251 {
1252 if (!ntb->ops->spad_read)
1253 return ~(u32)0;
1254
1255 return ntb->ops->spad_read(ntb, sidx);
1256 }
1257
1258 /**
1259 * ntb_spad_write() - write the local scratchpad register
1260 * @ntb: NTB device context.
1261 * @sidx: Scratchpad index.
1262 * @val: Scratchpad value.
1263 *
1264 * Write the value to the local scratchpad register.
1265 *
1266 * Return: Zero on success, otherwise an error number.
1267 */
ntb_spad_write(struct ntb_dev * ntb,int sidx,u32 val)1268 static inline int ntb_spad_write(struct ntb_dev *ntb, int sidx, u32 val)
1269 {
1270 if (!ntb->ops->spad_write)
1271 return -EINVAL;
1272
1273 return ntb->ops->spad_write(ntb, sidx, val);
1274 }
1275
1276 /**
1277 * ntb_peer_spad_addr() - address of the peer scratchpad register
1278 * @ntb: NTB device context.
1279 * @pidx: Port index of peer device.
1280 * @sidx: Scratchpad index.
1281 * @spad_addr: OUT - The address of the peer scratchpad register.
1282 *
1283 * Return the address of the peer doorbell register. This may be used, for
1284 * example, by drivers that offload memory copy operations to a dma engine.
1285 *
1286 * Return: Zero on success, otherwise an error number.
1287 */
ntb_peer_spad_addr(struct ntb_dev * ntb,int pidx,int sidx,phys_addr_t * spad_addr)1288 static inline int ntb_peer_spad_addr(struct ntb_dev *ntb, int pidx, int sidx,
1289 phys_addr_t *spad_addr)
1290 {
1291 if (!ntb->ops->peer_spad_addr)
1292 return -EINVAL;
1293
1294 return ntb->ops->peer_spad_addr(ntb, pidx, sidx, spad_addr);
1295 }
1296
1297 /**
1298 * ntb_peer_spad_read() - read the peer scratchpad register
1299 * @ntb: NTB device context.
1300 * @pidx: Port index of peer device.
1301 * @sidx: Scratchpad index.
1302 *
1303 * Read the peer scratchpad register, and return the value.
1304 *
1305 * Return: The value of the local scratchpad register.
1306 */
ntb_peer_spad_read(struct ntb_dev * ntb,int pidx,int sidx)1307 static inline u32 ntb_peer_spad_read(struct ntb_dev *ntb, int pidx, int sidx)
1308 {
1309 if (!ntb->ops->peer_spad_read)
1310 return ~(u32)0;
1311
1312 return ntb->ops->peer_spad_read(ntb, pidx, sidx);
1313 }
1314
1315 /**
1316 * ntb_peer_spad_write() - write the peer scratchpad register
1317 * @ntb: NTB device context.
1318 * @pidx: Port index of peer device.
1319 * @sidx: Scratchpad index.
1320 * @val: Scratchpad value.
1321 *
1322 * Write the value to the peer scratchpad register.
1323 *
1324 * Return: Zero on success, otherwise an error number.
1325 */
ntb_peer_spad_write(struct ntb_dev * ntb,int pidx,int sidx,u32 val)1326 static inline int ntb_peer_spad_write(struct ntb_dev *ntb, int pidx, int sidx,
1327 u32 val)
1328 {
1329 if (!ntb->ops->peer_spad_write)
1330 return -EINVAL;
1331
1332 return ntb->ops->peer_spad_write(ntb, pidx, sidx, val);
1333 }
1334
1335 /**
1336 * ntb_msg_count() - get the number of message registers
1337 * @ntb: NTB device context.
1338 *
1339 * Hardware may support a different number of message registers.
1340 *
1341 * Return: the number of message registers.
1342 */
ntb_msg_count(struct ntb_dev * ntb)1343 static inline int ntb_msg_count(struct ntb_dev *ntb)
1344 {
1345 if (!ntb->ops->msg_count)
1346 return 0;
1347
1348 return ntb->ops->msg_count(ntb);
1349 }
1350
1351 /**
1352 * ntb_msg_inbits() - get a bitfield of inbound message registers status
1353 * @ntb: NTB device context.
1354 *
1355 * The method returns the bitfield of status and mask registers, which related
1356 * to inbound message registers.
1357 *
1358 * Return: bitfield of inbound message registers.
1359 */
ntb_msg_inbits(struct ntb_dev * ntb)1360 static inline u64 ntb_msg_inbits(struct ntb_dev *ntb)
1361 {
1362 if (!ntb->ops->msg_inbits)
1363 return 0;
1364
1365 return ntb->ops->msg_inbits(ntb);
1366 }
1367
1368 /**
1369 * ntb_msg_outbits() - get a bitfield of outbound message registers status
1370 * @ntb: NTB device context.
1371 *
1372 * The method returns the bitfield of status and mask registers, which related
1373 * to outbound message registers.
1374 *
1375 * Return: bitfield of outbound message registers.
1376 */
ntb_msg_outbits(struct ntb_dev * ntb)1377 static inline u64 ntb_msg_outbits(struct ntb_dev *ntb)
1378 {
1379 if (!ntb->ops->msg_outbits)
1380 return 0;
1381
1382 return ntb->ops->msg_outbits(ntb);
1383 }
1384
1385 /**
1386 * ntb_msg_read_sts() - read the message registers status
1387 * @ntb: NTB device context.
1388 *
1389 * Read the status of message register. Inbound and outbound message registers
1390 * related bits can be filtered by masks retrieved from ntb_msg_inbits() and
1391 * ntb_msg_outbits().
1392 *
1393 * Return: status bits of message registers
1394 */
ntb_msg_read_sts(struct ntb_dev * ntb)1395 static inline u64 ntb_msg_read_sts(struct ntb_dev *ntb)
1396 {
1397 if (!ntb->ops->msg_read_sts)
1398 return 0;
1399
1400 return ntb->ops->msg_read_sts(ntb);
1401 }
1402
1403 /**
1404 * ntb_msg_clear_sts() - clear status bits of message registers
1405 * @ntb: NTB device context.
1406 * @sts_bits: Status bits to clear.
1407 *
1408 * Clear bits in the status register.
1409 *
1410 * Return: Zero on success, otherwise a negative error number.
1411 */
ntb_msg_clear_sts(struct ntb_dev * ntb,u64 sts_bits)1412 static inline int ntb_msg_clear_sts(struct ntb_dev *ntb, u64 sts_bits)
1413 {
1414 if (!ntb->ops->msg_clear_sts)
1415 return -EINVAL;
1416
1417 return ntb->ops->msg_clear_sts(ntb, sts_bits);
1418 }
1419
1420 /**
1421 * ntb_msg_set_mask() - set mask of message register status bits
1422 * @ntb: NTB device context.
1423 * @mask_bits: Mask bits.
1424 *
1425 * Mask the message registers status bits from raising the message event.
1426 *
1427 * Return: Zero on success, otherwise a negative error number.
1428 */
ntb_msg_set_mask(struct ntb_dev * ntb,u64 mask_bits)1429 static inline int ntb_msg_set_mask(struct ntb_dev *ntb, u64 mask_bits)
1430 {
1431 if (!ntb->ops->msg_set_mask)
1432 return -EINVAL;
1433
1434 return ntb->ops->msg_set_mask(ntb, mask_bits);
1435 }
1436
1437 /**
1438 * ntb_msg_clear_mask() - clear message registers mask
1439 * @ntb: NTB device context.
1440 * @mask_bits: Mask bits to clear.
1441 *
1442 * Clear bits in the message events mask register.
1443 *
1444 * Return: Zero on success, otherwise a negative error number.
1445 */
ntb_msg_clear_mask(struct ntb_dev * ntb,u64 mask_bits)1446 static inline int ntb_msg_clear_mask(struct ntb_dev *ntb, u64 mask_bits)
1447 {
1448 if (!ntb->ops->msg_clear_mask)
1449 return -EINVAL;
1450
1451 return ntb->ops->msg_clear_mask(ntb, mask_bits);
1452 }
1453
1454 /**
1455 * ntb_msg_read() - read message register with specified index
1456 * @ntb: NTB device context.
1457 * @midx: Message register index
1458 * @pidx: OUT - Port index of peer device a message retrieved from
1459 * @msg: OUT - Data
1460 *
1461 * Read data from the specified message register. Source port index of a
1462 * message is retrieved as well.
1463 *
1464 * Return: Zero on success, otherwise a negative error number.
1465 */
ntb_msg_read(struct ntb_dev * ntb,int midx,int * pidx,u32 * msg)1466 static inline int ntb_msg_read(struct ntb_dev *ntb, int midx, int *pidx,
1467 u32 *msg)
1468 {
1469 if (!ntb->ops->msg_read)
1470 return -EINVAL;
1471
1472 return ntb->ops->msg_read(ntb, midx, pidx, msg);
1473 }
1474
1475 /**
1476 * ntb_msg_write() - write data to the specified message register
1477 * @ntb: NTB device context.
1478 * @midx: Message register index
1479 * @pidx: Port index of peer device a message being sent to
1480 * @msg: Data to send
1481 *
1482 * Send data to a specified peer device using the defined message register.
1483 * Message event can be raised if the midx registers isn't empty while
1484 * calling this method and the corresponding interrupt isn't masked.
1485 *
1486 * Return: Zero on success, otherwise a negative error number.
1487 */
ntb_msg_write(struct ntb_dev * ntb,int midx,int pidx,u32 msg)1488 static inline int ntb_msg_write(struct ntb_dev *ntb, int midx, int pidx,
1489 u32 msg)
1490 {
1491 if (!ntb->ops->msg_write)
1492 return -EINVAL;
1493
1494 return ntb->ops->msg_write(ntb, midx, pidx, msg);
1495 }
1496
1497 #endif
1498