History

bpf: Import syscall arg documentation

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. Signed-off-by: Joe Stringer <joe@cilium.io> Signed-off-by: Alexei Starovoitov <ast@kernel.org> Reviewed-by: Quentin Monnet <quentin@isovalent.com> Acked-by: Toke Høiland-Jørgensen <toke@redhat.com> Acked-by: Yonghong Song <yhs@fb.com> Link: https://lore.kernel.org/bpf/20210302171947.2268128-2-joe@cilium.io

Joe Stringer committed 5 years ago

Commit 7799e4d1 parent 13ec0211 file · +121 −1Browse files

Unified · Split

include/uapi/linux/bpf.h+121−1
@@ -93,7 +93,127 @@ union bpf_iter_link_info { · 92 unmodified lines
9393 } map;
9494 };
9595
96−/* BPF syscall commands, see bpf(2) man-page for details. */
96+/* BPF syscall commands, see bpf(2) man-page for more details. */
97+/**
98+ * DOC: eBPF Syscall Preamble
99+ *
100+ * The operation to be performed by the **bpf**\ () system call is determined
101+ * by the *cmd* argument. Each operation takes an accompanying argument,
102+ * provided via *attr*, which is a pointer to a union of type *bpf_attr* (see
103+ * below). The size argument is the size of the union pointed to by *attr*.
104+ */
105+/**
106+ * DOC: eBPF Syscall Commands
107+ *
108+ * BPF_MAP_CREATE
109+ * Description
110+ * Create a map and return a file descriptor that refers to the
111+ * map. The close-on-exec file descriptor flag (see **fcntl**\ (2))
112+ * is automatically enabled for the new file descriptor.
113+ *
114+ * Applying **close**\ (2) to the file descriptor returned by
115+ * **BPF_MAP_CREATE** will delete the map (but see NOTES).
116+ *
117+ * Return
118+ * A new file descriptor (a nonnegative integer), or -1 if an
119+ * error occurred (in which case, *errno* is set appropriately).
120+ *
121+ * BPF_MAP_LOOKUP_ELEM
122+ * Description
123+ * Look up an element with a given *key* in the map referred to
124+ * by the file descriptor *map_fd*.
125+ *
126+ * Return
127+ * Returns zero on success. On error, -1 is returned and *errno*
128+ * is set appropriately.
129+ *
130+ * BPF_MAP_UPDATE_ELEM
131+ * Description
132+ * Create or update an element (key/value pair) in a specified map.
133+ *
134+ * The *flags* argument should be specified as one of the
135+ * following:
136+ *
137+ * **BPF_ANY**
138+ * Create a new element or update an existing element.
139+ * **BPF_NOEXIST**
140+ * Create a new element only if it did not exist.
141+ * **BPF_EXIST**
142+ * Update an existing element.
143+ *
144+ * Return
145+ * Returns zero on success. On error, -1 is returned and *errno*
146+ * is set appropriately.
147+ *
148+ * May set *errno* to **EINVAL**, **EPERM**, **ENOMEM**,
149+ * **E2BIG**, **EEXIST**, or **ENOENT**.
150+ *
151+ * **E2BIG**
152+ * The number of elements in the map reached the
153+ * *max_entries* limit specified at map creation time.
154+ * **EEXIST**
155+ * If *flags* specifies **BPF_NOEXIST** and the element
156+ * with *key* already exists in the map.
157+ * **ENOENT**
158+ * If *flags* specifies **BPF_EXIST** and the element with
159+ * *key* does not exist in the map.
160+ *
161+ * BPF_MAP_DELETE_ELEM
162+ * Description
163+ * Look up and delete an element by key in a specified map.
164+ *
165+ * Return
166+ * Returns zero on success. On error, -1 is returned and *errno*
167+ * is set appropriately.
168+ *
169+ * BPF_MAP_GET_NEXT_KEY
170+ * Description
171+ * Look up an element by key in a specified map and return the key
172+ * of the next element. Can be used to iterate over all elements
173+ * in the map.
174+ *
175+ * Return
176+ * Returns zero on success. On error, -1 is returned and *errno*
177+ * is set appropriately.
178+ *
179+ * The following cases can be used to iterate over all elements of
180+ * the map:
181+ *
182+ * * If *key* is not found, the operation returns zero and sets
183+ * the *next_key* pointer to the key of the first element.
184+ * * If *key* is found, the operation returns zero and sets the
185+ * *next_key* pointer to the key of the next element.
186+ * * If *key* is the last element, returns -1 and *errno* is set
187+ * to **ENOENT**.
188+ *
189+ * May set *errno* to **ENOMEM**, **EFAULT**, **EPERM**, or
190+ * **EINVAL** on error.
191+ *
192+ * BPF_PROG_LOAD
193+ * Description
194+ * Verify and load an eBPF program, returning a new file
195+ * descriptor associated with the program.
196+ *
197+ * Applying **close**\ (2) to the file descriptor returned by
198+ * **BPF_PROG_LOAD** will unload the eBPF program (but see NOTES).
199+ *
200+ * The close-on-exec file descriptor flag (see **fcntl**\ (2)) is
201+ * automatically enabled for the new file descriptor.
202+ *
203+ * Return
204+ * A new file descriptor (a nonnegative integer), or -1 if an
205+ * error occurred (in which case, *errno* is set appropriately).
206+ *
207+ * NOTES
208+ * eBPF objects (maps and programs) can be shared between processes.
209+ * For example, after **fork**\ (2), the child inherits file descriptors
210+ * referring to the same eBPF objects. In addition, file descriptors
211+ * referring to eBPF objects can be transferred over UNIX domain sockets.
212+ * File descriptors referring to eBPF objects can be duplicated in the
213+ * usual way, using **dup**\ (2) and similar calls. An eBPF object is
214+ * deallocated only after all file descriptors referring to the object
215+ * have been closed.
216+ */
97217 enum bpf_cmd {
98218 BPF_MAP_CREATE,
99219 BPF_MAP_LOOKUP_ELEM,