On 13-Nov-18 05:31, Leon Romanovsky wrote: > From: Noa Osherovich <noaos@xxxxxxxxxxxx> > > Add an initial documentation including usage examples. Nit: "Documetn" -> "Document" (in the patch subject) > > 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 >
