ibv_free_dm(3)

1IBV_ALLOC_DM(3)         Libibverbs Programmer's Manual         IBV_ALLOC_DM(3)
2
3
4

NAME

6       ibv_alloc_dm,  ibv_free_dm,  ibv_memcpy_to/from_dm - allocate or free a
7       device memory buffer (DMs) and perform memory copy to or from it
8

SYNOPSIS

10       #include <infiniband/verbs.h>
11
12       struct ibv_dm *ibv_alloc_dm(struct ibv_context *context,
13                                   struct ibv_alloc_dm_attr *attr);
14
15       int ibv_free_dm(struct ibv_dm *dm);
16

DESCRIPTION

18       ibv_alloc_dm() allocates a device memory buffer  for  the  RDMA  device
19       context  context.   The  argument  attr  is  a  pointer  to  an ibv_al‐
20       loc_dm_attr struct, as defined in <infiniband/verbs.h>.
21
22       ibv_free_dm() free the device memory buffer dm.
23
24       struct ibv_alloc_dm_attr {
25               size_t length;           /* Length of desired device memory buffer */
26               uint32_t log_align_req;       /* Log base 2 of address alignment requirement */
27               uint32_t comp_mask;      /* Compatibility mask that defines which of the following variables are valid */
28       };
29
30       Address alignment may be required in cases where RDMA atomic operations will be performed using the device memory.
31
32       In such cases, the user may specify the device memory start address alignment using the log_align_req parameter
33
34       in the allocation attributes struct.
35

Accessing an allocated device memory

37       In order to perform a write/read memory access to an allocated device memory, a user could use the ibv_memcpy_to_dm
38       and ibv_memcpy_from_dm calls respectively.
39
40       int ibv_memcpy_to_dm(struct ibv_dm *dm, uint64_t dm_offset,
41                            void *host_addr, size_t length);
42
43       int ibv_memcpy_from_dm(void *host_addr, struct ibv_dm *dm,
44                          uint64_t dm_offset, size_t length);
45
46       dm_offest
47       is the byte offset from the beginning of the allocated device memory buffer to access.
48
49       host_addr
50       is the host memory buffer address to access.
51
52       length
53       is the copy length in bytes.
54
55

Device memory registration

57       User may register the allocated device memory as a memory region and use the lkey/rkey inside sge when posting receive
58       or sending work request. This type of MR is defined as zero based and therefore any reference to it (specifically in sge)
59       is done with a byte offset from the beginning of the region.
60
61       This type of registration is done using ibv_reg_dm_mr.
62
63       struct ibv_mr* ibv_reg_dm_mr(struct ibv_pd *pd, struct ibv_dm *dm, uint64_t dm_offset,
64                         size_t length, uint32_t access);
65
66       pd
67       the associated pd for this registration.
68
69       dm
70       the associated dm for this registartion.
71
72       dm_offest
73       is the byte offset from the beginning of the allocated device memory buffer to register.
74
75       length
76       the memory length to register.
77
78       access
79       mr access flags (Use enum ibv_access_flags). For this type of registration, user must set the IBV_ACCESS_ZERO_BASED
80       flag.
81
82

RETURN VALUE

84       ibv_alloc_dm() returns a pointer to an ibv_dm struct or NULL if the re‐
85       quest  fails.  The output dm contains the handle which could be used by
86       user to import this device memory.
87
88       ibv_free_dm() returns 0 on success, or the value of  errno  on  failure
89       (which indicates the failure reason).
90
91       ibv_reg_dm_mr()  returns  a  pointer  to an ibv_mr struct on success or
92       NULL if request fails.
93
94       ibv_memcpy_to_dm()/ibv_memcpy_from_dm() returns 0  on  success  or  the
95       failure reason value on failure.
96

NOTES

98       ibv_alloc_dm()  may fail if device has no more free device memory left,
99       where the maximum  amount  of  allocated  memory  is  provided  by  the
100       max_dm_size  attribute in ibv_device_attr_ex struct.  ibv_free_dm() may
101       fail if any other resources (such as an MR) is  still  associated  with
102       the DM being freed.
103

AUTHORS

108       Ariel Levkovich <lariel@mellanox.com>
109
110
111
112libibverbs                        2017-07-25                   IBV_ALLOC_DM(3)