[RFC 05/10] pyverbs: Documetn pyverbs usage and examples

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



From: Noa Osherovich <noaos@xxxxxxxxxxxx>

Add an initial documentation including usage examples.

Signed-off-by: Noa Osherovich <noaos@xxxxxxxxxxxx>
Signed-off-by: Leon Romanovsky <leonro@xxxxxxxxxxxx>
---
 Documentation/pyverbs.md | 98 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 Documentation/pyverbs.md

diff --git a/Documentation/pyverbs.md b/Documentation/pyverbs.md
new file mode 100644
index 00000000..a603f03d
--- /dev/null
+++ b/Documentation/pyverbs.md
@@ -0,0 +1,98 @@
+# Pyverbs
+
+Pyverbs provides a Python API over rdma-core, the Linux userspace C API for
+the RDMA stack.
+
+## Goals
+
+1. Provide easier access to RDMA: RDMA has a steep learning curve as is and
+   the C interface requires the user to initialize multiple structs before
+   having usable objects. Pyverbs attempts to remove much of this overhead and
+   provide a smoother user experience.
+2. Improve our code by providing a test suite for rdma-core. This means that
+   new features will be tested before merge, and it also means that users and
+   distros will have tests for new and existing features, as well as the means
+   to create them quickly.
+3. Stay up-to-date with rdma-core - cover new features during development and
+   provide a test / unit-test alongside the feature.
+
+## Limitations
+
+Python handles memory for users. As a result, memory is allocated by Pyverbs
+when needed (e.g. user buffer for memory region). The memory will be accessible
+to the users, but not allocated or freed by them.
+
+## Usage Examples
+##### Open an IB device
+
+Import the device module and open a device by name:
+
+```python
+import pyverbs.device as d
+ctx = d.Context(name='mlx5_0')
+```
+
+'ctx' is Pyverbs' equivalent to rdma-core's ibv_context. At this point, the IB
+device is already open and ready to use.
+
+##### Query a device
+```python
+import pyverbs.device as d
+ctx = d.Context(name='mlx5_0')
+attr = ctx.query_device()
+print(attr)
+FW version            : 16.24.0185
+Node guid             : 9803:9b03:0000:e4c6
+Sys image GUID        : 9803:9b03:0000:e4c6
+Max MR size           : 0xffffffffffffffff
+Page size cap         : 0xfffffffffffff000
+Vendor ID             : 0x2c9
+Vender part ID        : 4119
+HW version            : 0
+Max QP                : 262144
+Max QP WR             : 32768
+Device cap flags      : 3983678518
+Max SGE               : 30
+Max SGE RD            : 30
+MAX CQ                : 16777216
+Max CQE               : 4194303
+Max MR                : 16777216
+Max PD                : 16777216
+Max QP RD atom        : 16
+Max EE RD atom        : 0
+Max res RD atom       : 4194304
+Max QP init RD atom   : 16
+Max EE init RD atom   : 0
+Atomic caps           : 1
+Max EE                : 0
+Max RDD               : 0
+Max MW                : 16777216
+Max raw IPv6 QPs      : 0
+Max raw ethy QP       : 0
+Max mcast group       : 2097152
+Max mcast QP attach   : 240
+Max AH                : 2147483647
+Max FMR               : 0
+Max map per FMR       : 2147483647
+Max SRQ               : 8388608
+Max SRQ WR            : 32767
+Max SRQ SGE           : 31
+Max PKeys             : 128
+local CA ack delay    : 16
+Phys port count       : 1
+```
+
+'attr' is Pyverbs' equivalent to ibv_device_attr. Pyverbs will provide it to
+the user upon completion of the call to ibv_query_device.
+
+##### Query GID
+
+```python
+import pyverbs.device as d
+ctx = d.Context(name='mlx5_0')
+gid = ctx.query_gid(port_num=1, index=3)
+print(gid)
+0000:0000:0000:0000:0000:ffff:0b87:3c08
+```
+
+'gid' is Pyverbs' equivalent to ibv_gid, provided to the user by Pyverbs.
--
2.19.1




[Index of Archives]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Photo]     [Yosemite News]     [Yosemite Photos]     [Linux Kernel]     [Linux SCSI]     [XFree86]

  Powered by Linux