uapi/bpf: Add missing description and returns for helper documentation

Both description and returns section will become mandatory
for helpers and syscalls in a later commit to generate man pages.

This commit also adds in the documentation that BPF_PROG_RUN is
an alias for BPF_PROG_TEST_RUN for anyone searching for the
syscall in the generated man pages.

Signed-off-by: Usama Arif <usama.arif@bytedance.com>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/20220119114442.1452088-1-usama.arif@bytedance.com

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index b0383d371b9af53ea816766fb9fc95cbec277ebe..a9c96c21330ad70410cab30e0d866d4bbfe8ee6a 100644 (file)
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -330,6 +330,8 @@ union bpf_iter_link_info {
  *                     *ctx_out*, *data_in* and *data_out* must be NULL.
  *                     *repeat* must be zero.
  *
+ *             BPF_PROG_RUN is an alias for BPF_PROG_TEST_RUN.
+ *
  *     Return
  *             Returns zero on success. On error, -1 is returned and *errno*
  *             is set appropriately.
@@ -1775,6 +1777,8 @@ union bpf_attr {
  *             0 on success, or a negative error in case of failure.
  *
  * u64 bpf_get_current_pid_tgid(void)
+ *     Description
+ *             Get the current pid and tgid.
  *     Return
  *             A 64-bit integer containing the current tgid and pid, and
  *             created as such:
@@ -1782,6 +1786,8 @@ union bpf_attr {
  *             *current_task*\ **->pid**.
  *
  * u64 bpf_get_current_uid_gid(void)
+ *     Description
+ *             Get the current uid and gid.
  *     Return
  *             A 64-bit integer containing the current GID and UID, and
  *             created as such: *current_gid* **<< 32 \|** *current_uid*.
@@ -2256,6 +2262,8 @@ union bpf_attr {
  *             The 32-bit hash.
  *
  * u64 bpf_get_current_task(void)
+ *     Description
+ *             Get the current task.
  *     Return
  *             A pointer to the current task struct.
  *
@@ -2369,6 +2377,8 @@ union bpf_attr {
  *             indicate that the hash is outdated and to trigger a
  *             recalculation the next time the kernel tries to access this
  *             hash or when the **bpf_get_hash_recalc**\ () helper is called.
+ *     Return
+ *             void.
  *
  * long bpf_get_numa_node_id(void)
  *     Description
@@ -2466,6 +2476,8 @@ union bpf_attr {
  *             A 8-byte long unique number or 0 if *sk* is NULL.
  *
  * u32 bpf_get_socket_uid(struct sk_buff *skb)
+ *     Description
+ *             Get the owner UID of the socked associated to *skb*.
  *     Return
  *             The owner UID of the socket associated to *skb*. If the socket
  *             is **NULL**, or if it is not a full socket (i.e. if it is a
@@ -3240,6 +3252,9 @@ union bpf_attr {
  *             The id is returned or 0 in case the id could not be retrieved.
  *
  * u64 bpf_get_current_cgroup_id(void)
+ *     Description
+ *             Get the current cgroup id based on the cgroup within which
+ *             the current task is running.
  *     Return
  *             A 64-bit integer containing the current cgroup id based
  *             on the cgroup within which the current task is running.

diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h
index b0383d371b9af53ea816766fb9fc95cbec277ebe..a9c96c21330ad70410cab30e0d866d4bbfe8ee6a 100644 (file)
--- a/tools/include/uapi/linux/bpf.h
+++ b/tools/include/uapi/linux/bpf.h
@@ -330,6 +330,8 @@ union bpf_iter_link_info {
  *                     *ctx_out*, *data_in* and *data_out* must be NULL.
  *                     *repeat* must be zero.
  *
+ *             BPF_PROG_RUN is an alias for BPF_PROG_TEST_RUN.
+ *
  *     Return
  *             Returns zero on success. On error, -1 is returned and *errno*
  *             is set appropriately.
@@ -1775,6 +1777,8 @@ union bpf_attr {
  *             0 on success, or a negative error in case of failure.
  *
  * u64 bpf_get_current_pid_tgid(void)
+ *     Description
+ *             Get the current pid and tgid.
  *     Return
  *             A 64-bit integer containing the current tgid and pid, and
  *             created as such:
@@ -1782,6 +1786,8 @@ union bpf_attr {
  *             *current_task*\ **->pid**.
  *
  * u64 bpf_get_current_uid_gid(void)
+ *     Description
+ *             Get the current uid and gid.
  *     Return
  *             A 64-bit integer containing the current GID and UID, and
  *             created as such: *current_gid* **<< 32 \|** *current_uid*.
@@ -2256,6 +2262,8 @@ union bpf_attr {
  *             The 32-bit hash.
  *
  * u64 bpf_get_current_task(void)
+ *     Description
+ *             Get the current task.
  *     Return
  *             A pointer to the current task struct.
  *
@@ -2369,6 +2377,8 @@ union bpf_attr {
  *             indicate that the hash is outdated and to trigger a
  *             recalculation the next time the kernel tries to access this
  *             hash or when the **bpf_get_hash_recalc**\ () helper is called.
+ *     Return
+ *             void.
  *
  * long bpf_get_numa_node_id(void)
  *     Description
@@ -2466,6 +2476,8 @@ union bpf_attr {
  *             A 8-byte long unique number or 0 if *sk* is NULL.
  *
  * u32 bpf_get_socket_uid(struct sk_buff *skb)
+ *     Description
+ *             Get the owner UID of the socked associated to *skb*.
  *     Return
  *             The owner UID of the socket associated to *skb*. If the socket
  *             is **NULL**, or if it is not a full socket (i.e. if it is a
@@ -3240,6 +3252,9 @@ union bpf_attr {
  *             The id is returned or 0 in case the id could not be retrieved.
  *
  * u64 bpf_get_current_cgroup_id(void)
+ *     Description
+ *             Get the current cgroup id based on the cgroup within which
+ *             the current task is running.
  *     Return
  *             A 64-bit integer containing the current cgroup id based
  *             on the cgroup within which the current task is running.