From: Joe Stringer <joe@cilium.io>
To: bpf@vger.kernel.org
Cc: daniel@iogearbox.net, ast@kernel.org, linux-doc@vger.kernel.org,
linux-man@vger.kernel.org,
"Toke Høiland-Jørgensen" <toke@redhat.com>,
"Quentin Monnet" <quentin@isovalent.com>
Subject: [PATCHv2 bpf-next 04/15] bpf: Document BPF_PROG_PIN syscall command
Date: Tue, 2 Mar 2021 09:19:36 -0800 [thread overview]
Message-ID: <20210302171947.2268128-5-joe@cilium.io> (raw)
In-Reply-To: <20210302171947.2268128-1-joe@cilium.io>
Commit b2197755b263 ("bpf: add support for persistent maps/progs")
contains the original implementation and git logs, used as reference for
this documentation.
Also pull in the filename restriction as documented in commit 6d8cb045cde6
("bpf: comment why dots in filenames under BPF virtual FS are not allowed")
Acked-by: Toke Høiland-Jørgensen <toke@redhat.com>
Reviewed-by: Quentin Monnet <quentin@isovalent.com>
Signed-off-by: Joe Stringer <joe@cilium.io>
---
CC: Daniel Borkmann <daniel@iogearbox.net>
---
include/uapi/linux/bpf.h | 36 +++++++++++++++++++++++++++++-------
1 file changed, 29 insertions(+), 7 deletions(-)
diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index eb9f059f0569..6946dde90c56 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -219,6 +219,22 @@ union bpf_iter_link_info {
* Pin an eBPF program or map referred by the specified *bpf_fd*
* to the provided *pathname* on the filesystem.
*
+ * The *pathname* argument must not contain a dot (".").
+ *
+ * On success, *pathname* retains a reference to the eBPF object,
+ * preventing deallocation of the object when the original
+ * *bpf_fd* is closed. This allow the eBPF object to live beyond
+ * **close**\ (\ *bpf_fd*\ ), and hence the lifetime of the parent
+ * process.
+ *
+ * Applying **unlink**\ (2) or similar calls to the *pathname*
+ * unpins the object from the filesystem, removing the reference.
+ * If no other file descriptors or filesystem nodes refer to the
+ * same object, it will be deallocated (see NOTES).
+ *
+ * The filesystem type for the parent directory of *pathname* must
+ * be **BPF_FS_MAGIC**.
+ *
* Return
* Returns zero on success. On error, -1 is returned and *errno*
* is set appropriately.
@@ -584,13 +600,19 @@ union bpf_iter_link_info {
*
* 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.
+ *
+ * * After **fork**\ (2), the child inherits file descriptors
+ * referring to the same eBPF objects.
+ * * File descriptors referring to eBPF objects can be transferred over
+ * **unix**\ (7) domain sockets.
+ * * File descriptors referring to eBPF objects can be duplicated in the
+ * usual way, using **dup**\ (2) and similar calls.
+ * * File descriptors referring to eBPF objects can be pinned to the
+ * filesystem using the **BPF_OBJ_PIN** command of **bpf**\ (2).
+ *
+ * An eBPF object is deallocated only after all file descriptors referring
+ * to the object have been closed and no references remain pinned to the
+ * filesystem or attached (for example, bound to a program or device).
*/
enum bpf_cmd {
BPF_MAP_CREATE,
--
2.27.0
next prev parent reply other threads:[~2021-03-03 3:55 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-03-02 17:19 [PATCHv2 bpf-next 00/15] Improve BPF syscall command documentation Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 01/15] bpf: Import syscall arg documentation Joe Stringer
2021-03-03 19:38 ` Yonghong Song
2021-03-03 20:20 ` Yonghong Song
2021-03-02 17:19 ` [PATCHv2 bpf-next 02/15] bpf: Add minimal bpf() command documentation Joe Stringer
2021-03-03 19:44 ` Yonghong Song
2021-03-02 17:19 ` [PATCHv2 bpf-next 03/15] bpf: Document BPF_F_LOCK in syscall commands Joe Stringer
2021-03-03 20:16 ` Yonghong Song
2021-03-02 17:19 ` Joe Stringer [this message]
2021-03-03 20:21 ` [PATCHv2 bpf-next 04/15] bpf: Document BPF_PROG_PIN syscall command Yonghong Song
2021-03-02 17:19 ` [PATCHv2 bpf-next 05/15] bpf: Document BPF_PROG_ATTACH " Joe Stringer
2021-03-03 20:23 ` Yonghong Song
2021-03-02 17:19 ` [PATCHv2 bpf-next 06/15] bpf: Document BPF_PROG_TEST_RUN " Joe Stringer
2021-03-03 20:29 ` Yonghong Song
2021-03-03 23:53 ` Joe Stringer
2021-04-10 18:12 ` Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 07/15] bpf: Document BPF_PROG_QUERY " Joe Stringer
2021-03-03 20:31 ` Yonghong Song
2021-03-02 17:19 ` [PATCHv2 bpf-next 08/15] bpf: Document BPF_MAP_*_BATCH syscall commands Joe Stringer
2021-03-03 17:38 ` Brian Vazquez
2021-03-03 20:44 ` Yonghong Song
2021-03-02 17:19 ` [PATCHv2 bpf-next 09/15] scripts/bpf: Abstract eBPF API target parameter Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 10/15] scripts/bpf: Add syscall commands printer Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 11/15] tools/bpf: Remove bpf-helpers from bpftool docs Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 12/15] selftests/bpf: Templatize man page generation Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 13/15] selftests/bpf: Test syscall command parsing Joe Stringer
2021-03-03 22:23 ` Yonghong Song
2021-03-03 23:50 ` Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 14/15] docs/bpf: Add bpf() syscall command reference Joe Stringer
2021-03-02 17:19 ` [PATCHv2 bpf-next 15/15] tools: Sync uapi bpf.h header with latest changes Joe Stringer
2021-03-03 17:25 ` [PATCHv2 bpf-next 00/15] Improve BPF syscall command documentation Jonathan Corbet
2021-03-03 18:50 ` Joe Stringer
2021-03-05 2:51 ` Alexei Starovoitov
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210302171947.2268128-5-joe@cilium.io \
--to=joe@cilium.io \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=quentin@isovalent.com \
--cc=toke@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).