€•“w      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ+/translations/zh_CN/networking/msg_zerocopy”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/zh_TW/networking/msg_zerocopy”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/it_IT/networking/msg_zerocopy”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/ja_JP/networking/msg_zerocopy”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/ko_KR/networking/msg_zerocopy”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ+/translations/sp_SP/networking/msg_zerocopy”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒMSG_ZEROCOPY”h]”hŒMSG_ZEROCOPY”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒE/var/lib/git/docbuild/linux/Documentation/networking/msg_zerocopy.rst”h Kubh¢)”}”(hhh]”(h§)”}”(hŒIntro”h]”hŒIntro”…””}”(hhºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh·hžhhŸh¶h KubhŒ	paragraph”“”)”}”(hŒ The MSG_ZEROCOPY flag enables copy avoidance for socket send calls.
The feature is currently implemented for TCP, UDP and VSOCK (with
virtio transport) sockets.”h]”hŒ The MSG_ZEROCOPY flag enables copy avoidance for socket send calls.
The feature is currently implemented for TCP, UDP and VSOCK (with
virtio transport) sockets.”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K	hh·hžhubh¢)”}”(hhh]”(h§)”}”(hŒOpportunity and Caveats”h]”hŒOpportunity and Caveats”…””}”(hhÛhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhØhžhhŸh¶h KubhÉ)”}”(hŒþCopying large buffers between user process and kernel can be
expensive. Linux supports various interfaces that eschew copying,
such as sendfile and splice. The MSG_ZEROCOPY flag extends the
underlying copy avoidance mechanism to common socket send calls.”h]”hŒþCopying large buffers between user process and kernel can be
expensive. Linux supports various interfaces that eschew copying,
such as sendfile and splice. The MSG_ZEROCOPY flag extends the
underlying copy avoidance mechanism to common socket send calls.”…””}”(hhéhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KhhØhžhubhÉ)”}”(hŒóCopy avoidance is not a free lunch. As implemented, with page pinning,
it replaces per byte copy cost with page accounting and completion
notification overhead. As a result, MSG_ZEROCOPY is generally only
effective at writes over around 10 KB.”h]”hŒóCopy avoidance is not a free lunch. As implemented, with page pinning,
it replaces per byte copy cost with page accounting and completion
notification overhead. As a result, MSG_ZEROCOPY is generally only
effective at writes over around 10 KB.”…””}”(hh÷hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KhhØhžhubhÉ)”}”(hXe  Page pinning also changes system call semantics. It temporarily shares
the buffer between process and network stack. Unlike with copying, the
process cannot immediately overwrite the buffer after system call
return without possibly modifying the data in flight. Kernel integrity
is not affected, but a buggy program can possibly corrupt its own data
stream.”h]”hXe  Page pinning also changes system call semantics. It temporarily shares
the buffer between process and network stack. Unlike with copying, the
process cannot immediately overwrite the buffer after system call
return without possibly modifying the data in flight. Kernel integrity
is not affected, but a buggy program can possibly corrupt its own data
stream.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KhhØhžhubhÉ)”}”(hŒ­The kernel returns a notification when it is safe to modify data.
Converting an existing application to MSG_ZEROCOPY is not always as
trivial as just passing the flag, then.”h]”hŒ­The kernel returns a notification when it is safe to modify data.
Converting an existing application to MSG_ZEROCOPY is not always as
trivial as just passing the flag, then.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K"hhØhžhubeh}”(h]”Œopportunity-and-caveats”ah ]”h"]”Œopportunity and caveats”ah$]”h&]”uh1h¡hh·hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ	More Info”h]”hŒ	More Info”…””}”(hj,  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj)  hžhhŸh¶h K(ubhÉ)”}”(hŒÈMuch of this document was derived from a longer paper presented at
netdev 2.1. For more in-depth information see that paper and talk,
the excellent reporting over at LWN.net or read the original code.”h]”hŒÈMuch of this document was derived from a longer paper presented at
netdev 2.1. For more in-depth information see that paper and talk,
the excellent reporting over at LWN.net or read the original code.”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K*hj)  hžhubhŒblock_quote”“”)”}”(hX  paper, slides, video
  https://netdevconf.org/2.1/session.html?debruijn

LWN article
  https://lwn.net/Articles/726917/

patchset
  [PATCH net-next v4 0/9] socket sendmsg MSG_ZEROCOPY
  https://lore.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com

”h]”hŒdefinition_list”“”)”}”(hhh]”(hŒdefinition_list_item”“”)”}”(hŒFpaper, slides, video
https://netdevconf.org/2.1/session.html?debruijn
”h]”(hŒterm”“”)”}”(hŒpaper, slides, video”h]”hŒpaper, slides, video”…””}”(hj[  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hŸh¶h K/hjU  ubhŒ
definition”“”)”}”(hhh]”hÉ)”}”(hŒ0https://netdevconf.org/2.1/session.html?debruijn”h]”hŒ	reference”“”)”}”(hjp  h]”hŒ0https://netdevconf.org/2.1/session.html?debruijn”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jp  uh1jr  hjn  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K/hjk  ubah}”(h]”h ]”h"]”h$]”h&]”uh1ji  hjU  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jS  hŸh¶h K/hjP  ubjT  )”}”(hŒ-LWN article
https://lwn.net/Articles/726917/
”h]”(jZ  )”}”(hŒLWN article”h]”hŒLWN article”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hŸh¶h K2hj”  ubjj  )”}”(hhh]”hÉ)”}”(hŒ https://lwn.net/Articles/726917/”h]”js  )”}”(hj«  h]”hŒ https://lwn.net/Articles/726917/”…””}”(hj­  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j«  uh1jr  hj©  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K2hj¦  ubah}”(h]”h ]”h"]”h$]”h&]”uh1ji  hj”  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jS  hŸh¶h K2hjP  ubjT  )”}”(hŒ”patchset
[PATCH net-next v4 0/9] socket sendmsg MSG_ZEROCOPY
https://lore.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com

”h]”(jZ  )”}”(hŒpatchset”h]”hŒpatchset”…””}”(hjÑ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jY  hŸh¶h K7hjÍ  ubjj  )”}”(hhh]”hÉ)”}”(hŒ‰[PATCH net-next v4 0/9] socket sendmsg MSG_ZEROCOPY
https://lore.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com”h]”(hŒ4[PATCH net-next v4 0/9] socket sendmsg MSG_ZEROCOPY
”…””}”(hjâ  hžhhŸNh Nubjs  )”}”(hŒUhttps://lore.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com”h]”hŒUhttps://lore.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com”…””}”(hjê  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”jì  uh1jr  hjâ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K5hjß  ubah}”(h]”h ]”h"]”h$]”h&]”uh1ji  hjÍ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jS  hŸh¶h K7hjP  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jN  hjJ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jH  hŸh¶h K.hj)  hžhubeh}”(h]”Œ	more-info”ah ]”h"]”Œ	more info”ah$]”h&]”uh1h¡hh·hžhhŸh¶h K(ubeh}”(h]”Œintro”ah ]”h"]”Œintro”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ	Interface”h]”hŒ	Interface”…””}”(hj*  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj'  hžhhŸh¶h K:ubhÉ)”}”(hŒfPassing the MSG_ZEROCOPY flag is the most obvious step to enable copy
avoidance, but not the only one.”h]”hŒfPassing the MSG_ZEROCOPY flag is the most obvious step to enable copy
avoidance, but not the only one.”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K<hj'  hžhubh¢)”}”(hhh]”(h§)”}”(hŒSocket Setup”h]”hŒSocket Setup”…””}”(hjI  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjF  hžhhŸh¶h K@ubhÉ)”}”(hX   The kernel is permissive when applications pass undefined flags to the
send system call. By default it simply ignores these. To avoid enabling
copy avoidance mode for legacy processes that accidentally already pass
this flag, a process must first signal intent by setting a socket option:”h]”hX   The kernel is permissive when applications pass undefined flags to the
send system call. By default it simply ignores these. To avoid enabling
copy avoidance mode for legacy processes that accidentally already pass
this flag, a process must first signal intent by setting a socket option:”…””}”(hjW  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KBhjF  hžhubhŒliteral_block”“”)”}”(hŒoif (setsockopt(fd, SOL_SOCKET, SO_ZEROCOPY, &one, sizeof(one)))
        error(1, errno, "setsockopt zerocopy");”h]”hŒoif (setsockopt(fd, SOL_SOCKET, SO_ZEROCOPY, &one, sizeof(one)))
        error(1, errno, "setsockopt zerocopy");”…””}”hjg  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1je  hŸh¶h KIhjF  hžhubeh}”(h]”Œsocket-setup”ah ]”h"]”Œsocket setup”ah$]”h&]”uh1h¡hj'  hžhhŸh¶h K@ubh¢)”}”(hhh]”(h§)”}”(hŒTransmission”h]”hŒTransmission”…””}”(hj‚  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KMubhÉ)”}”(hŒWThe change to send (or sendto, sendmsg, sendmmsg) itself is trivial.
Pass the new flag.”h]”hŒWThe change to send (or sendto, sendmsg, sendmmsg) itself is trivial.
Pass the new flag.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KOhj  hžhubjf  )”}”(hŒ/ret = send(fd, buf, sizeof(buf), MSG_ZEROCOPY);”h]”hŒ/ret = send(fd, buf, sizeof(buf), MSG_ZEROCOPY);”…””}”hjž  sbah}”(h]”h ]”h"]”h$]”h&]”ju  jv  uh1je  hŸh¶h KThj  hžhubhÉ)”}”(hŒ›A zerocopy failure will return -1 with errno ENOBUFS. This happens if
the socket exceeds its optmem limit or the user exceeds their ulimit on
locked pages.”h]”hŒ›A zerocopy failure will return -1 with errno ENOBUFS. This happens if
the socket exceeds its optmem limit or the user exceeds their ulimit on
locked pages.”…””}”(hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KVhj  hžhubh¢)”}”(hhh]”(h§)”}”(hŒ!Mixing copy avoidance and copying”h]”hŒ!Mixing copy avoidance and copying”…””}”(hj½  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjº  hžhhŸh¶h K\ubhÉ)”}”(hŒâMany workloads have a mixture of large and small buffers. Because copy
avoidance is more expensive than copying for small packets, the
feature is implemented as a flag. It is safe to mix calls with the flag
with those without.”h]”hŒâMany workloads have a mixture of large and small buffers. Because copy
avoidance is more expensive than copying for small packets, the
feature is implemented as a flag. It is safe to mix calls with the flag
with those without.”…””}”(hjË  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K^hjº  hžhubeh}”(h]”Œ!mixing-copy-avoidance-and-copying”ah ]”h"]”Œ!mixing copy avoidance and copying”ah$]”h&]”uh1h¡hj  hžhhŸh¶h K\ubeh}”(h]”Œtransmission”ah ]”h"]”Œtransmission”ah$]”h&]”uh1h¡hj'  hžhhŸh¶h KMubh¢)”}”(hhh]”(h§)”}”(hŒNotifications”h]”hŒNotifications”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjé  hžhhŸh¶h KeubhÉ)”}”(hŒÄThe kernel has to notify the process when it is safe to reuse a
previously passed buffer. It queues completion notifications on the
socket error queue, akin to the transmit timestamping interface.”h]”hŒÄThe kernel has to notify the process when it is safe to reuse a
previously passed buffer. It queues completion notifications on the
socket error queue, akin to the transmit timestamping interface.”…””}”(hjú  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kghjé  hžhubhÉ)”}”(hXa  The notification itself is a simple scalar value. Each socket
maintains an internal unsigned 32-bit counter. Each send call with
MSG_ZEROCOPY that successfully sends data increments the counter. The
counter is not incremented on failure or if called with length zero.
The counter counts system call invocations, not bytes. It wraps after
UINT_MAX calls.”h]”hXa  The notification itself is a simple scalar value. Each socket
maintains an internal unsigned 32-bit counter. Each send call with
MSG_ZEROCOPY that successfully sends data increments the counter. The
counter is not incremented on failure or if called with length zero.
The counter counts system call invocations, not bytes. It wraps after
UINT_MAX calls.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kkhjé  hžhubh¢)”}”(hhh]”(h§)”}”(hŒNotification Reception”h]”hŒNotification Reception”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KtubhÉ)”}”(hŒ…The below snippet demonstrates the API. In the simplest case, each
send syscall is followed by a poll and recvmsg on the error queue.”h]”hŒ…The below snippet demonstrates the API. In the simplest case, each
send syscall is followed by a poll and recvmsg on the error queue.”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kvhj  hžhubhÉ)”}”(hX  Reading from the error queue is always a non-blocking operation. The
poll call is there to block until an error is outstanding. It will set
POLLERR in its output flags. That flag does not have to be set in the
events field. Errors are signaled unconditionally.”h]”hX  Reading from the error queue is always a non-blocking operation. The
poll call is there to block until an error is outstanding. It will set
POLLERR in its output flags. That flag does not have to be set in the
events field. Errors are signaled unconditionally.”…””}”(hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kyhj  hžhubjf  )”}”(hŒëpfd.fd = fd;
pfd.events = 0;
if (poll(&pfd, 1, -1) != 1 || pfd.revents & POLLERR == 0)
        error(1, errno, "poll");

ret = recvmsg(fd, &msg, MSG_ERRQUEUE);
if (ret == -1)
        error(1, errno, "recvmsg");

read_notification(msg);”h]”hŒëpfd.fd = fd;
pfd.events = 0;
if (poll(&pfd, 1, -1) != 1 || pfd.revents & POLLERR == 0)
        error(1, errno, "poll");

ret = recvmsg(fd, &msg, MSG_ERRQUEUE);
if (ret == -1)
        error(1, errno, "recvmsg");

read_notification(msg);”…””}”hjC  sbah}”(h]”h ]”h"]”h$]”h&]”ju  jv  uh1je  hŸh¶h K€hj  hžhubhÉ)”}”(hŒ¥The example is for demonstration purpose only. In practice, it is more
efficient to not wait for notifications, but read without blocking
every couple of send calls.”h]”hŒ¥The example is for demonstration purpose only. In practice, it is more
efficient to not wait for notifications, but read without blocking
every couple of send calls.”…””}”(hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K‹hj  hžhubhÉ)”}”(hX  Notifications can be processed out of order with other operations on
the socket. A socket that has an error queued would normally block
other operations until the error is read. Zerocopy notifications have
a zero error code, however, to not block send and recv calls.”h]”hX  Notifications can be processed out of order with other operations on
the socket. A socket that has an error queued would normally block
other operations until the error is read. Zerocopy notifications have
a zero error code, however, to not block send and recv calls.”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj  hžhubeh}”(h]”Œnotification-reception”ah ]”h"]”Œnotification reception”ah$]”h&]”uh1h¡hjé  hžhhŸh¶h Ktubh¢)”}”(hhh]”(h§)”}”(hŒNotification Batching”h]”hŒNotification Batching”…””}”(hjx  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hju  hžhhŸh¶h K–ubhÉ)”}”(hX	  Multiple outstanding packets can be read at once using the recvmmsg
call. This is often not needed. In each message the kernel returns not
a single value, but a range. It coalesces consecutive notifications
while one is outstanding for reception on the error queue.”h]”hX	  Multiple outstanding packets can be read at once using the recvmmsg
call. This is often not needed. In each message the kernel returns not
a single value, but a range. It coalesces consecutive notifications
while one is outstanding for reception on the error queue.”…””}”(hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K˜hju  hžhubhÉ)”}”(hX  When a new notification is about to be queued, it checks whether the
new value extends the range of the notification at the tail of the
queue. If so, it drops the new notification packet and instead increases
the range upper value of the outstanding notification.”h]”hX  When a new notification is about to be queued, it checks whether the
new value extends the range of the notification at the tail of the
queue. If so, it drops the new notification packet and instead increases
the range upper value of the outstanding notification.”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khju  hžhubhÉ)”}”(hŒ·For protocols that acknowledge data in-order, like TCP, each
notification can be squashed into the previous one, so that no more
than one notification is outstanding at any one point.”h]”hŒ·For protocols that acknowledge data in-order, like TCP, each
notification can be squashed into the previous one, so that no more
than one notification is outstanding at any one point.”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¢hju  hžhubhÉ)”}”(hŒ…Ordered delivery is the common case, but not guaranteed. Notifications
may arrive out of order on retransmission and socket teardown.”h]”hŒ…Ordered delivery is the common case, but not guaranteed. Notifications
may arrive out of order on retransmission and socket teardown.”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¦hju  hžhubeh}”(h]”Œnotification-batching”ah ]”h"]”Œnotification batching”ah$]”h&]”uh1h¡hjé  hžhhŸh¶h K–ubh¢)”}”(hhh]”(h§)”}”(hŒNotification Parsing”h]”hŒNotification Parsing”…””}”(hjÉ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÆ  hžhhŸh¶h K«ubhÉ)”}”(hŒÁThe below snippet demonstrates how to parse the control message: the
read_notification() call in the previous snippet. A notification
is encoded in the standard error format, sock_extended_err.”h]”hŒÁThe below snippet demonstrates how to parse the control message: the
read_notification() call in the previous snippet. A notification
is encoded in the standard error format, sock_extended_err.”…””}”(hj×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K­hjÆ  hžhubhÉ)”}”(hŒÓThe level and type fields in the control data are protocol family
specific, IP_RECVERR or IPV6_RECVERR (for TCP or UDP socket).
For VSOCK socket, cmsg_level will be SOL_VSOCK and cmsg_type will be
VSOCK_RECVERR.”h]”hŒÓThe level and type fields in the control data are protocol family
specific, IP_RECVERR or IPV6_RECVERR (for TCP or UDP socket).
For VSOCK socket, cmsg_level will be SOL_VSOCK and cmsg_type will be
VSOCK_RECVERR.”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K±hjÆ  hžhubhÉ)”}”(hŒ—Error origin is the new type SO_EE_ORIGIN_ZEROCOPY. ee_errno is zero,
as explained before, to avoid blocking read and write system calls on
the socket.”h]”hŒ—Error origin is the new type SO_EE_ORIGIN_ZEROCOPY. ee_errno is zero,
as explained before, to avoid blocking read and write system calls on
the socket.”…””}”(hjó  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¶hjÆ  hžhubhÉ)”}”(hŒ¶The 32-bit notification range is encoded as [ee_info, ee_data]. This
range is inclusive. Other fields in the struct must be treated as
undefined, bar for ee_code, as discussed below.”h]”hŒ¶The 32-bit notification range is encoded as [ee_info, ee_data]. This
range is inclusive. Other fields in the struct must be treated as
undefined, bar for ee_code, as discussed below.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KºhjÆ  hžhubjf  )”}”(hXo  struct sock_extended_err *serr;
struct cmsghdr *cm;

cm = CMSG_FIRSTHDR(msg);
if (cm->cmsg_level != SOL_IP &&
    cm->cmsg_type != IP_RECVERR)
        error(1, 0, "cmsg");

serr = (void *) CMSG_DATA(cm);
if (serr->ee_errno != 0 ||
    serr->ee_origin != SO_EE_ORIGIN_ZEROCOPY)
        error(1, 0, "serr");

printf("completed: %u..%u\n", serr->ee_info, serr->ee_data);”h]”hXo  struct sock_extended_err *serr;
struct cmsghdr *cm;

cm = CMSG_FIRSTHDR(msg);
if (cm->cmsg_level != SOL_IP &&
    cm->cmsg_type != IP_RECVERR)
        error(1, 0, "cmsg");

serr = (void *) CMSG_DATA(cm);
if (serr->ee_errno != 0 ||
    serr->ee_origin != SO_EE_ORIGIN_ZEROCOPY)
        error(1, 0, "serr");

printf("completed: %u..%u\n", serr->ee_info, serr->ee_data);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”ju  jv  uh1je  hŸh¶h KÀhjÆ  hžhubeh}”(h]”Œnotification-parsing”ah ]”h"]”Œnotification parsing”ah$]”h&]”uh1h¡hjé  hžhhŸh¶h K«ubh¢)”}”(hhh]”(h§)”}”(hŒDeferred copies”h]”hŒDeferred copies”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj%  hžhhŸh¶h KÑubhÉ)”}”(hŒ¾Passing flag MSG_ZEROCOPY is a hint to the kernel to apply copy
avoidance, and a contract that the kernel will queue a completion
notification. It is not a guarantee that the copy is elided.”h]”hŒ¾Passing flag MSG_ZEROCOPY is a hint to the kernel to apply copy
avoidance, and a contract that the kernel will queue a completion
notification. It is not a guarantee that the copy is elided.”…””}”(hj6  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÓhj%  hžhubhÉ)”}”(hX  Copy avoidance is not always feasible. Devices that do not support
scatter-gather I/O cannot send packets made up of kernel generated
protocol headers plus zerocopy user data. A packet may need to be
converted to a private copy of data deep in the stack, say to compute
a checksum.”h]”hX  Copy avoidance is not always feasible. Devices that do not support
scatter-gather I/O cannot send packets made up of kernel generated
protocol headers plus zerocopy user data. A packet may need to be
converted to a private copy of data deep in the stack, say to compute
a checksum.”…””}”(hjD  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K×hj%  hžhubhÉ)”}”(hX  In all these cases, the kernel returns a completion notification when
it releases its hold on the shared pages. That notification may arrive
before the (copied) data is fully transmitted. A zerocopy completion
notification is not a transmit completion notification, therefore.”h]”hX  In all these cases, the kernel returns a completion notification when
it releases its hold on the shared pages. That notification may arrive
before the (copied) data is fully transmitted. A zerocopy completion
notification is not a transmit completion notification, therefore.”…””}”(hjR  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÝhj%  hžhubhÉ)”}”(hX»  Deferred copies can be more expensive than a copy immediately in the
system call, if the data is no longer warm in the cache. The process
also incurs notification processing cost for no benefit. For this
reason, the kernel signals if data was completed with a copy, by
setting flag SO_EE_CODE_ZEROCOPY_COPIED in field ee_code on return.
A process may use this signal to stop passing flag MSG_ZEROCOPY on
subsequent requests on the same socket.”h]”hX»  Deferred copies can be more expensive than a copy immediately in the
system call, if the data is no longer warm in the cache. The process
also incurs notification processing cost for no benefit. For this
reason, the kernel signals if data was completed with a copy, by
setting flag SO_EE_CODE_ZEROCOPY_COPIED in field ee_code on return.
A process may use this signal to stop passing flag MSG_ZEROCOPY on
subsequent requests on the same socket.”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kâhj%  hžhubeh}”(h]”Œdeferred-copies”ah ]”h"]”Œdeferred copies”ah$]”h&]”uh1h¡hjé  hžhhŸh¶h KÑubeh}”(h]”Œnotifications”ah ]”h"]”Œnotifications”ah$]”h&]”uh1h¡hj'  hžhhŸh¶h Keubeh}”(h]”Œ	interface”ah ]”h"]”Œ	interface”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K:ubh¢)”}”(hhh]”(h§)”}”(hŒImplementation”h]”hŒImplementation”…””}”(hj‰  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj†  hžhhŸh¶h Kìubh¢)”}”(hhh]”(h§)”}”(hŒLoopback”h]”hŒLoopback”…””}”(hjš  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj—  hžhhŸh¶h KïubhÉ)”}”(hXh  For TCP and UDP:
Data sent to local sockets can be queued indefinitely if the receive
process does not read its socket. Unbound notification latency is not
acceptable. For this reason all packets generated with MSG_ZEROCOPY
that are looped to a local socket will incur a deferred copy. This
includes looping onto packet sockets (e.g., tcpdump) and tun devices.”h]”hXh  For TCP and UDP:
Data sent to local sockets can be queued indefinitely if the receive
process does not read its socket. Unbound notification latency is not
acceptable. For this reason all packets generated with MSG_ZEROCOPY
that are looped to a local socket will incur a deferred copy. This
includes looping onto packet sockets (e.g., tcpdump) and tun devices.”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kñhj—  hžhubhÉ)”}”(hŒPFor VSOCK:
Data path sent to local sockets is the same as for non-local sockets.”h]”hŒPFor VSOCK:
Data path sent to local sockets is the same as for non-local sockets.”…””}”(hj¶  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Køhj—  hžhubeh}”(h]”Œloopback”ah ]”h"]”Œloopback”ah$]”h&]”uh1h¡hj†  hžhhŸh¶h Kïubeh}”(h]”Œimplementation”ah ]”h"]”Œimplementation”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kìubh¢)”}”(hhh]”(h§)”}”(hŒTesting”h]”hŒTesting”…””}”(hj×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÔ  hžhhŸh¶h KüubhÉ)”}”(hŒoMore realistic example code can be found in the kernel source under
tools/testing/selftests/net/msg_zerocopy.c.”h]”hŒoMore realistic example code can be found in the kernel source under
tools/testing/selftests/net/msg_zerocopy.c.”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KþhjÔ  hžhubhÉ)”}”(hX{  Be cognizant of the loopback constraint. The test can be run between
a pair of hosts. But if run between a local pair of processes, for
instance when run with msg_zerocopy.sh between a veth pair across
namespaces, the test will not show any improvement. For testing, the
loopback restriction can be temporarily relaxed by making
skb_orphan_frags_rx identical to skb_orphan_frags.”h]”hX{  Be cognizant of the loopback constraint. The test can be run between
a pair of hosts. But if run between a local pair of processes, for
instance when run with msg_zerocopy.sh between a veth pair across
namespaces, the test will not show any improvement. For testing, the
loopback restriction can be temporarily relaxed by making
skb_orphan_frags_rx identical to skb_orphan_frags.”…””}”(hjó  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MhjÔ  hžhubhÉ)”}”(hŒ[For VSOCK type of socket example can be found in
tools/testing/vsock/vsock_test_zerocopy.c.”h]”hŒ[For VSOCK type of socket example can be found in
tools/testing/vsock/vsock_test_zerocopy.c.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MhjÔ  hžhubeh}”(h]”Œtesting”ah ]”h"]”Œtesting”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Küubeh}”(h]”Œmsg-zerocopy”ah ]”h"]”Œmsg_zerocopy”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jB  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j  j  j$  j!  j&  j#  j  j  jƒ  j€  j|  jy  jæ  jã  jÞ  jÛ  j{  jx  jr  jo  jÃ  jÀ  j"  j  js  jp  jÑ  jÎ  jÉ  jÆ  j  j  uŒ	nametypes”}”(j  ‰j$  ‰j&  ‰j  ‰jƒ  ‰j|  ‰jæ  ‰jÞ  ‰j{  ‰jr  ‰jÃ  ‰j"  ‰js  ‰jÑ  ‰jÉ  ‰j  ‰uh}”(j  h£j!  h·j#  hØj  j)  j€  j'  jy  jF  jã  j  jÛ  jº  jx  jé  jo  j  jÀ  ju  j  jÆ  jp  j%  jÎ  j†  jÆ  j—  j  jÔ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.