Re: [PATCHv2 bpf-next 01/15] bpf: Import syscall arg documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 





On 3/3/21 11:38 AM, Yonghong Song wrote:


On 3/2/21 9:19 AM, Joe Stringer wrote:
These descriptions are present in the man-pages project from the
original submissions around 2015-2016. Import them so that they can be
kept up to date as developers extend the bpf syscall commands.

These descriptions follow the pattern used by scripts/bpf_helpers_doc.py
so that we can take advantage of the parser to generate more up-to-date
man page writing based upon these headers.

Some minor wording adjustments were made to make the descriptions
more consistent for the description / return format.

Acked-by: Toke Høiland-Jørgensen <toke@xxxxxxxxxx>
Reviewed-by: Quentin Monnet <quentin@xxxxxxxxxxxxx>
Co-authored-by: Alexei Starovoitov <ast@xxxxxxxxxx>
Co-authored-by: Michael Kerrisk <mtk.manpages@xxxxxxxxx>
Signed-off-by: Joe Stringer <joe@xxxxxxxxx>

Ack with one nit below.

Acked-by: Yonghong Song <yhs@xxxxxx>

---
  include/uapi/linux/bpf.h | 122 ++++++++++++++++++++++++++++++++++++++-
  1 file changed, 121 insertions(+), 1 deletion(-)

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index b89af20cfa19..fb16c590e6d9 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -93,7 +93,127 @@ union bpf_iter_link_info {
      } map;
  };
-/* BPF syscall commands, see bpf(2) man-page for details. */
+/* BPF syscall commands, see bpf(2) man-page for more details. */
+/**
+ * DOC: eBPF Syscall Preamble
+ *
+ * The operation to be performed by the **bpf**\ () system call is determined
+ * by the *cmd* argument. Each operation takes an accompanying argument,
+ * provided via *attr*, which is a pointer to a union of type *bpf_attr* (see + * below). The size argument is the size of the union pointed to by *attr*.
+ */
+/**
+ * DOC: eBPF Syscall Commands
+ *
+ * BPF_MAP_CREATE
+ *    Description
+ *        Create a map and return a file descriptor that refers to the
+ *        map. The close-on-exec file descriptor flag (see **fcntl**\ (2))
+ *        is automatically enabled for the new file descriptor.
+ *
+ *        Applying **close**\ (2) to the file descriptor returned by
+ *        **BPF_MAP_CREATE** will delete the map (but see NOTES).
+ *
+ *    Return
+ *        A new file descriptor (a nonnegative integer), or -1 if an
+ *        error occurred (in which case, *errno* is set appropriately).
+ *
[...]
+ * BPF_PROG_LOAD
+ *    Description
+ *        Verify and load an eBPF program, returning a new file
+ *        descriptor associated with the program.
+ *
+ *        Applying **close**\ (2) to the file descriptor returned by
+ *        **BPF_PROG_LOAD** will unload the eBPF program (but see NOTES).
+ *
+ *        The close-on-exec file descriptor flag (see **fcntl**\ (2)) is
+ *        automatically enabled for the new file descriptor.
+ *
+ *    Return
+ *        A new file descriptor (a nonnegative integer), or -1 if an
+ *        error occurred (in which case, *errno* is set appropriately).
+ *
+ * NOTES
+ *    eBPF objects (maps and programs) can be shared between processes.
+ *    For example, after **fork**\ (2), the child inherits file descriptors
+ *    referring to the same eBPF objects. In addition, file descriptors
+ *    referring to eBPF objects can be transferred over UNIX domain sockets. + *    File descriptors referring to eBPF objects can be duplicated in the
+ *    usual way, using **dup**\ (2) and similar calls. An eBPF object is
+ *    deallocated only after all file descriptors referring to the object
+ *    have been closed.

if the object is pinned, the object will be live if the pinned file is not removed. The file description can refer to a link file descriptor or an iterator file descriptor which will (indirectly) hold a reference count to the program as well. It will be good we can clarify a little more in Patch #2 at NOTES section after other bpf syscall commands are
introduced.

Sorry. Looks like NOTES are properly updated in patch #4. So you can
ignore this comment.


+ */
  enum bpf_cmd {
      BPF_MAP_CREATE,
      BPF_MAP_LOOKUP_ELEM,




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux