| Message ID | 20250130211539.428952-2-almasrymina@google.com (mailing list archive) |
|---|---|
| State | RFC |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | Device memory TCP TX | expand |
On 01/30, Mina Almasry wrote: > Add documentation outlining the usage and details of the devmem TCP TX > API. > > Signed-off-by: Mina Almasry <almasrymina@google.com> > > --- > > v2: > - Update documentation for iov_base is the dmabuf offset (Stan) > --- > Documentation/networking/devmem.rst | 144 +++++++++++++++++++++++++++- > 1 file changed, 140 insertions(+), 4 deletions(-) > > diff --git a/Documentation/networking/devmem.rst b/Documentation/networking/devmem.rst > index d95363645331..8166fe09da13 100644 > --- a/Documentation/networking/devmem.rst > +++ b/Documentation/networking/devmem.rst > @@ -62,15 +62,15 @@ More Info > https://lore.kernel.org/netdev/20240831004313.3713467-1-almasrymina@google.com/ > > > -Interface > -========= > +RX Interface > +============ > > > Example > ------- > > -tools/testing/selftests/net/ncdevmem.c:do_server shows an example of setting up > -the RX path of this API. > +./tools/testing/selftests/drivers/net/hw/ncdevmem:do_server shows an example of > +setting up the RX path of this API. > > > NIC Setup > @@ -235,6 +235,142 @@ can be less than the tokens provided by the user in case of: > (a) an internal kernel leak bug. > (b) the user passed more than 1024 frags. > > +TX Interface > +============ > + > + > +Example > +------- > + > +./tools/testing/selftests/drivers/net/hw/ncdevmem:do_client shows an example of > +setting up the TX path of this API. > + > + > +NIC Setup > +--------- > + > +The user must bind a TX dmabuf to a given NIC using the netlink API:: > + > + struct netdev_bind_tx_req *req = NULL; > + struct netdev_bind_tx_rsp *rsp = NULL; > + struct ynl_error yerr; > + > + *ys = ynl_sock_create(&ynl_netdev_family, &yerr); > + > + req = netdev_bind_tx_req_alloc(); > + netdev_bind_tx_req_set_ifindex(req, ifindex); > + netdev_bind_tx_req_set_fd(req, dmabuf_fd); > + > + rsp = netdev_bind_tx(*ys, req); > + > + tx_dmabuf_id = rsp->id; > + > + > +The netlink API returns a dmabuf_id: a unique ID that refers to this dmabuf > +that has been bound. > + > +The user can unbind the dmabuf from the netdevice by closing the netlink socket > +that established the binding. We do this so that the binding is automatically > +unbound even if the userspace process crashes. > + > +Note that any reasonably well-behaved dmabuf from any exporter should work with > +devmem TCP, even if the dmabuf is not actually backed by devmem. An example of > +this is udmabuf, which wraps user memory (non-devmem) in a dmabuf. > + > +Socket Setup > +------------ > + > +The user application must use MSG_ZEROCOPY flag when sending devmem TCP. Devmem > +cannot be copied by the kernel, so the semantics of the devmem TX are similar > +to the semantics of MSG_ZEROCOPY. > + > + ret = setsockopt(socket_fd, SOL_SOCKET, SO_ZEROCOPY, &opt, sizeof(opt)); > + > +Sending data > +-------------- > + > +Devmem data is sent using the SCM_DEVMEM_DMABUF cmsg. > + > +The user should create a msghdr where, > + > +iov_base is set to the offset into the dmabuf to start sending from. > +iov_len is set to the number of bytes to be sent from the dmabuf. > + > +The user passes the dma-buf id to send from via the dmabuf_tx_cmsg.dmabuf_id. > + > +The example below sends 1024 bytes from offset 100 into the dmabuf, and 2048 > +from offset 2000 into the dmabuf. The dmabuf to send from is tx_dmabuf_id:: > + > + char ctrl_data[CMSG_SPACE(sizeof(struct dmabuf_tx_cmsg))]; > + struct dmabuf_tx_cmsg ddmabuf; > + struct msghdr msg = {}; > + struct cmsghdr *cmsg; > + struct iovec iov[2]; > + > + iov[0].iov_base = (void*)100; > + iov[0].iov_len = 1024; > + iov[1].iov_base = (void*)2000; > + iov[1].iov_len = 2048; > + > + msg.msg_iov = iov; > + msg.msg_iovlen = 2; > + > + msg.msg_control = ctrl_data; > + msg.msg_controllen = sizeof(ctrl_data); > + > + cmsg = CMSG_FIRSTHDR(&msg); > + cmsg->cmsg_level = SOL_SOCKET; > + cmsg->cmsg_type = SCM_DEVMEM_DMABUF; > + cmsg->cmsg_len = CMSG_LEN(sizeof(struct dmabuf_tx_cmsg)); > + > + ddmabuf.dmabuf_id = tx_dmabuf_id; > + > + *((struct dmabuf_tx_cmsg *)CMSG_DATA(cmsg)) = ddmabuf; [..] > + sendmsg(socket_fd, &msg, MSG_ZEROCOPY); Not super important, but any reason not to use MSG_SOCK_DEVMEM as a flag? We already use it for recvmsg, seems logical to mirror the same flag on the transmit side?
On Thu, Jan 30, 2025 at 2:59 PM Stanislav Fomichev <stfomichev@gmail.com> wrote: > > On 01/30, Mina Almasry wrote: > > Add documentation outlining the usage and details of the devmem TCP TX > > API. > > > > Signed-off-by: Mina Almasry <almasrymina@google.com> > > > > --- > > > > v2: > > - Update documentation for iov_base is the dmabuf offset (Stan) > > --- > > Documentation/networking/devmem.rst | 144 +++++++++++++++++++++++++++- > > 1 file changed, 140 insertions(+), 4 deletions(-) > > > > diff --git a/Documentation/networking/devmem.rst b/Documentation/networking/devmem.rst > > index d95363645331..8166fe09da13 100644 > > --- a/Documentation/networking/devmem.rst > > +++ b/Documentation/networking/devmem.rst > > @@ -62,15 +62,15 @@ More Info > > https://lore.kernel.org/netdev/20240831004313.3713467-1-almasrymina@google.com/ > > > > > > -Interface > > -========= > > +RX Interface > > +============ > > > > > > Example > > ------- > > > > -tools/testing/selftests/net/ncdevmem.c:do_server shows an example of setting up > > -the RX path of this API. > > +./tools/testing/selftests/drivers/net/hw/ncdevmem:do_server shows an example of > > +setting up the RX path of this API. > > > > > > NIC Setup > > @@ -235,6 +235,142 @@ can be less than the tokens provided by the user in case of: > > (a) an internal kernel leak bug. > > (b) the user passed more than 1024 frags. > > > > +TX Interface > > +============ > > + > > + > > +Example > > +------- > > + > > +./tools/testing/selftests/drivers/net/hw/ncdevmem:do_client shows an example of > > +setting up the TX path of this API. > > + > > + > > +NIC Setup > > +--------- > > + > > +The user must bind a TX dmabuf to a given NIC using the netlink API:: > > + > > + struct netdev_bind_tx_req *req = NULL; > > + struct netdev_bind_tx_rsp *rsp = NULL; > > + struct ynl_error yerr; > > + > > + *ys = ynl_sock_create(&ynl_netdev_family, &yerr); > > + > > + req = netdev_bind_tx_req_alloc(); > > + netdev_bind_tx_req_set_ifindex(req, ifindex); > > + netdev_bind_tx_req_set_fd(req, dmabuf_fd); > > + > > + rsp = netdev_bind_tx(*ys, req); > > + > > + tx_dmabuf_id = rsp->id; > > + > > + > > +The netlink API returns a dmabuf_id: a unique ID that refers to this dmabuf > > +that has been bound. > > + > > +The user can unbind the dmabuf from the netdevice by closing the netlink socket > > +that established the binding. We do this so that the binding is automatically > > +unbound even if the userspace process crashes. > > + > > +Note that any reasonably well-behaved dmabuf from any exporter should work with > > +devmem TCP, even if the dmabuf is not actually backed by devmem. An example of > > +this is udmabuf, which wraps user memory (non-devmem) in a dmabuf. > > + > > +Socket Setup > > +------------ > > + > > +The user application must use MSG_ZEROCOPY flag when sending devmem TCP. Devmem > > +cannot be copied by the kernel, so the semantics of the devmem TX are similar > > +to the semantics of MSG_ZEROCOPY. > > + > > + ret = setsockopt(socket_fd, SOL_SOCKET, SO_ZEROCOPY, &opt, sizeof(opt)); > > + > > +Sending data > > +-------------- > > + > > +Devmem data is sent using the SCM_DEVMEM_DMABUF cmsg. > > + > > +The user should create a msghdr where, > > + > > +iov_base is set to the offset into the dmabuf to start sending from. > > +iov_len is set to the number of bytes to be sent from the dmabuf. > > + > > +The user passes the dma-buf id to send from via the dmabuf_tx_cmsg.dmabuf_id. > > + > > +The example below sends 1024 bytes from offset 100 into the dmabuf, and 2048 > > +from offset 2000 into the dmabuf. The dmabuf to send from is tx_dmabuf_id:: > > + > > + char ctrl_data[CMSG_SPACE(sizeof(struct dmabuf_tx_cmsg))]; > > + struct dmabuf_tx_cmsg ddmabuf; > > + struct msghdr msg = {}; > > + struct cmsghdr *cmsg; > > + struct iovec iov[2]; > > + > > + iov[0].iov_base = (void*)100; > > + iov[0].iov_len = 1024; > > + iov[1].iov_base = (void*)2000; > > + iov[1].iov_len = 2048; > > + > > + msg.msg_iov = iov; > > + msg.msg_iovlen = 2; > > + > > + msg.msg_control = ctrl_data; > > + msg.msg_controllen = sizeof(ctrl_data); > > + > > + cmsg = CMSG_FIRSTHDR(&msg); > > + cmsg->cmsg_level = SOL_SOCKET; > > + cmsg->cmsg_type = SCM_DEVMEM_DMABUF; > > + cmsg->cmsg_len = CMSG_LEN(sizeof(struct dmabuf_tx_cmsg)); > > + > > + ddmabuf.dmabuf_id = tx_dmabuf_id; > > + > > + *((struct dmabuf_tx_cmsg *)CMSG_DATA(cmsg)) = ddmabuf; > > [..] > > > + sendmsg(socket_fd, &msg, MSG_ZEROCOPY); > > Not super important, but any reason not to use MSG_SOCK_DEVMEM as a > flag? We already use it for recvmsg, seems logical to mirror the same > flag on the transmit side? Only to remove redundancy, and the possible confusion that could arise, and the extra checks needed to catch invalid input. With this, the user tells the kernel to send from the dmabuf by supplying the SCM_DEVMEM_DMABUF cmsg. If we add another signal like MSG_SOCK_DEVMEM, there is room for the user to supply the cmg but not the flag (confusion), and the kernel needs to have the code and overhead to check that both the flag and the cmsg are provided.
diff --git a/Documentation/networking/devmem.rst b/Documentation/networking/devmem.rst index d95363645331..8166fe09da13 100644 --- a/Documentation/networking/devmem.rst +++ b/Documentation/networking/devmem.rst @@ -62,15 +62,15 @@ More Info https://lore.kernel.org/netdev/20240831004313.3713467-1-almasrymina@google.com/ -Interface -========= +RX Interface +============ Example ------- -tools/testing/selftests/net/ncdevmem.c:do_server shows an example of setting up -the RX path of this API. +./tools/testing/selftests/drivers/net/hw/ncdevmem:do_server shows an example of +setting up the RX path of this API. NIC Setup @@ -235,6 +235,142 @@ can be less than the tokens provided by the user in case of: (a) an internal kernel leak bug. (b) the user passed more than 1024 frags. +TX Interface +============ + + +Example +------- + +./tools/testing/selftests/drivers/net/hw/ncdevmem:do_client shows an example of +setting up the TX path of this API. + + +NIC Setup +--------- + +The user must bind a TX dmabuf to a given NIC using the netlink API:: + + struct netdev_bind_tx_req *req = NULL; + struct netdev_bind_tx_rsp *rsp = NULL; + struct ynl_error yerr; + + *ys = ynl_sock_create(&ynl_netdev_family, &yerr); + + req = netdev_bind_tx_req_alloc(); + netdev_bind_tx_req_set_ifindex(req, ifindex); + netdev_bind_tx_req_set_fd(req, dmabuf_fd); + + rsp = netdev_bind_tx(*ys, req); + + tx_dmabuf_id = rsp->id; + + +The netlink API returns a dmabuf_id: a unique ID that refers to this dmabuf +that has been bound. + +The user can unbind the dmabuf from the netdevice by closing the netlink socket +that established the binding. We do this so that the binding is automatically +unbound even if the userspace process crashes. + +Note that any reasonably well-behaved dmabuf from any exporter should work with +devmem TCP, even if the dmabuf is not actually backed by devmem. An example of +this is udmabuf, which wraps user memory (non-devmem) in a dmabuf. + +Socket Setup +------------ + +The user application must use MSG_ZEROCOPY flag when sending devmem TCP. Devmem +cannot be copied by the kernel, so the semantics of the devmem TX are similar +to the semantics of MSG_ZEROCOPY. + + ret = setsockopt(socket_fd, SOL_SOCKET, SO_ZEROCOPY, &opt, sizeof(opt)); + +Sending data +-------------- + +Devmem data is sent using the SCM_DEVMEM_DMABUF cmsg. + +The user should create a msghdr where, + +iov_base is set to the offset into the dmabuf to start sending from. +iov_len is set to the number of bytes to be sent from the dmabuf. + +The user passes the dma-buf id to send from via the dmabuf_tx_cmsg.dmabuf_id. + +The example below sends 1024 bytes from offset 100 into the dmabuf, and 2048 +from offset 2000 into the dmabuf. The dmabuf to send from is tx_dmabuf_id:: + + char ctrl_data[CMSG_SPACE(sizeof(struct dmabuf_tx_cmsg))]; + struct dmabuf_tx_cmsg ddmabuf; + struct msghdr msg = {}; + struct cmsghdr *cmsg; + struct iovec iov[2]; + + iov[0].iov_base = (void*)100; + iov[0].iov_len = 1024; + iov[1].iov_base = (void*)2000; + iov[1].iov_len = 2048; + + msg.msg_iov = iov; + msg.msg_iovlen = 2; + + msg.msg_control = ctrl_data; + msg.msg_controllen = sizeof(ctrl_data); + + cmsg = CMSG_FIRSTHDR(&msg); + cmsg->cmsg_level = SOL_SOCKET; + cmsg->cmsg_type = SCM_DEVMEM_DMABUF; + cmsg->cmsg_len = CMSG_LEN(sizeof(struct dmabuf_tx_cmsg)); + + ddmabuf.dmabuf_id = tx_dmabuf_id; + + *((struct dmabuf_tx_cmsg *)CMSG_DATA(cmsg)) = ddmabuf; + + sendmsg(socket_fd, &msg, MSG_ZEROCOPY); + + +Reusing TX dmabufs +------------------ + +Similar to MSG_ZEROCOPY with regular memory, the user should not modify the +contents of the dma-buf while a send operation is in progress. This is because +the kernel does not keep a copy of the dmabuf contents. Instead, the kernel +will pin and send data from the buffer available to the userspace. + +Just as in MSG_ZEROCOPY, the kernel notifies the userspace of send completions +using MSG_ERRQUEUE:: + + int64_t tstop = gettimeofday_ms() + waittime_ms; + char control[CMSG_SPACE(100)] = {}; + struct sock_extended_err *serr; + struct msghdr msg = {}; + struct cmsghdr *cm; + int retries = 10; + __u32 hi, lo; + + msg.msg_control = control; + msg.msg_controllen = sizeof(control); + + while (gettimeofday_ms() < tstop) { + if (!do_poll(fd)) continue; + + ret = recvmsg(fd, &msg, MSG_ERRQUEUE); + + for (cm = CMSG_FIRSTHDR(&msg); cm; cm = CMSG_NXTHDR(&msg, cm)) { + serr = (void *)CMSG_DATA(cm); + + hi = serr->ee_data; + lo = serr->ee_info; + + fprintf(stdout, "tx complete [%d,%d]\n", lo, hi); + } + } + +After the associated sendmsg has been completed, the dmabuf can be reused by +the userspace. + + Implementation & Caveats ========================
Add documentation outlining the usage and details of the devmem TCP TX API. Signed-off-by: Mina Almasry <almasrymina@google.com> --- v2: - Update documentation for iov_base is the dmabuf offset (Stan) --- Documentation/networking/devmem.rst | 144 +++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 4 deletions(-)