From patchwork Sun Feb 24 13:06:38 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Noa Osherovich X-Patchwork-Id: 10827963 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 9442417E9 for ; Sun, 24 Feb 2019 13:09:07 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 83213296ED for ; Sun, 24 Feb 2019 13:09:07 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 777CC2A98F; Sun, 24 Feb 2019 13:09:07 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI,UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 1ED95296ED for ; Sun, 24 Feb 2019 13:09:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1728233AbfBXNJA (ORCPT ); Sun, 24 Feb 2019 08:09:00 -0500 Received: from mail-il-dmz.mellanox.com ([193.47.165.129]:50612 "EHLO mellanox.co.il" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728308AbfBXNI7 (ORCPT ); Sun, 24 Feb 2019 08:08:59 -0500 Received: from Internal Mail-Server by MTLPINE1 (envelope-from noaos@mellanox.com) with ESMTPS (AES256-SHA encrypted); 24 Feb 2019 15:06:49 +0200 Received: from reg-l-vrt-059-009.mtl.labs.mlnx (reg-l-vrt-059-009.mtl.labs.mlnx [10.135.59.9]) by labmailer.mlnx (8.13.8/8.13.8) with ESMTP id x1OD6mfn026210; Sun, 24 Feb 2019 15:06:49 +0200 From: Noa Osherovich To: leonro@mellanox.com, jgg@mellanox.com, dledford@redhat.com Cc: linux-rdma@vger.kernel.org, Noa Osherovich Subject: [PATCH rdma-core 19/19] Documentation: update pyverbs Date: Sun, 24 Feb 2019 15:06:38 +0200 Message-Id: <20190224130638.31848-20-noaos@mellanox.com> X-Mailer: git-send-email 2.17.2 In-Reply-To: <20190224130638.31848-1-noaos@mellanox.com> References: <20190224130638.31848-1-noaos@mellanox.com> Sender: linux-rdma-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-rdma@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Update pyverbs.md with small examples: - Query a port - Extended query device - Create a PD - Create a MR - Create a MW - Create a DM - Create a DmMr Signed-off-by: Noa Osherovich --- Documentation/pyverbs.md | 129 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) diff --git a/Documentation/pyverbs.md b/Documentation/pyverbs.md index a3e85c26574a..62faaed97b13 100644 --- a/Documentation/pyverbs.md +++ b/Documentation/pyverbs.md @@ -23,6 +23,7 @@ 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 +Note that all examples use a hard-coded device name ('mlx5_0'). ##### Open an IB device Import the device module and open a device by name: @@ -96,3 +97,131 @@ print(gid) ``` 'gid' is Pyverbs' equivalent to ibv_gid, provided to the user by Pyverbs. + +##### Query port +The following code snippet provides an example of pyverbs' equivalent of +querying an a port. Context's query_port() command wraps ibv_query_port(). +The example below queries the first port of the device. +```python +import pyverbs.device as d +ctx=d.Context(name='mlx5_0') +port_attr = ctx.query_port(1) +print(port_attr) +Port state : Active (4) +Max MTU : 4096 (5) +Active MTU : 1024 (3) +SM lid : 0 +Port lid : 0 +lmc : 0x0 +Link layer : Ethernet +Max message size : 0x40000000 +Port cap flags : IBV_PORT_CM_SUP IBV_PORT_IP_BASED_GIDS +Port cap flags 2 : +max VL num : 0 +Bad Pkey counter : 0 +Qkey violations counter : 0 +Gid table len : 256 +Pkey table len : 1 +SM sl : 0 +Subnet timeout : 0 +Init type reply : 0 +Active width : 4X (2) +Ative speed : 25.0 Gbps (32) +Phys state : Link up (5) +Flags : 1 +``` + +##### Extended query device +The example below shows how to open a device using pyverbs and query the +extended device's attributes. +Context's query_device_ex() command wraps ibv_query_device_ex(). +```python +import pyverbs.device as d + +ctx = d.Context(name='mlx5_0') +attr = ctx.query_device_ex() +attr.max_dm_size +131072 +attr.rss_caps.max_rwq_indirection_table_size +2048 +``` + +#### Create RDMA objects +##### PD +The following example shows how to open a device and use its context to create +a PD. +```python +import pyverbs.device as d +from pyverbs.pd import PD + +with d.Context(name='mlx5_0') as ctx: + pd = PD(ctx) +``` +##### MR +The example below shows how to create a MR using pyverbs. Similar to C, a +device must be opened prior to creation and a PD has to be allocated. +```python +import pyverbs.device as d +from pyverbs.pd import PD +from pyverbs.mr import MR +import pyverbs.enums as e + +with d.Context(name='mlx5_0') as ctx: + with PD(ctx) as pd: + mr_len = 1000 + flags = e.IBV_ACCESS_LOCAL_WRITE + mr = MR(pd, mr_len, flags) +``` +##### Memory window +The following example shows the equivalent of creating a type 1 memory window. +It includes opening a device and allocating the necessary PD. +```python +import pyverbs.device as d +from pyverbs.pd import PD +from pyverbs.mr import MW +import pyverbs.enums as e + +with d.Context(name='mlx5_0') as ctx: + with PD(ctx) as pd: + mw = MW(pd, e.IBV_MW_TYPE_1) +``` +##### Device memory +The following snippet shows how to allocate a DM - a direct memory object, +using the device's memory. +```python +import random + +from pyverbs.device import DM, AllocDmAttr +import pyverbs.device as d + +with d.Context(name='mlx5_0') as ctx: + attr = ctx.query_device_ex() + if attr.max_dm_size != 0: + dm_len = random.randint(4, attr.max_dm_size) + dm_attrs = AllocDmAttr(dm_len) + dm = DM(ctx, dm_attrs) +``` + +##### DM MR +The example below shows how to open a DMMR - device memory MR, using the +device's own memory rather than a user-allocated buffer. +```python +import random + +from pyverbs.device import DM, AllocDmAttr +from pyverbs.mr import DmMr +import pyverbs.device as d +from pyverbs.pd import PD +import pyverbs.enums as e + +with d.Context(name='mlx5_0') as ctx: + attr = ctx.query_device_ex() + if attr.max_dm_size != 0: + dm_len = random.randint(4, attr.max_dm_size) + dm_attrs = AllocDmAttr(dm_len) + dm_mr_len = random.randint(4, dm_len) + with DM(ctx, dm_attrs) as dm: + with PD(ctx) as pd: + dm_mr = DmMr(pd, dm_mr_len, e.IBV_ACCESS_ZERO_BASED, dm=dm, + offset=0) +``` \ No newline at end of file