[RFC bpf-next v2 3/8] bpf: add documentation for eBPF helpers (12-22)

[Quentin Monnet]

2018-04-10 15:43 UTC-0700 ~ Alexei Starovoitov

> On Tue, Apr 10, 2018 at 03:41:52PM +0100, Quentin Monnet wrote:
>> Add documentation for eBPF helper functions to bpf.h user header file.
>> This documentation can be parsed with the Python script provided in
>> another commit of the patch series, in order to provide a RST document
>> that can later be converted into a man page.
>>
>> The objective is to make the documentation easily understandable and
>> accessible to all eBPF developers, including beginners.
>>
>> This patch contains descriptions for the following helper functions, all
>> writter by Alexei:
>>
>> - bpf_get_current_pid_tgid()
>> - bpf_get_current_uid_gid()
>> - bpf_get_current_comm()
>> - bpf_skb_vlan_push()
>> - bpf_skb_vlan_pop()
>> - bpf_skb_get_tunnel_key()
>> - bpf_skb_set_tunnel_key()
>> - bpf_redirect()
>> - bpf_perf_event_output()
>> - bpf_get_stackid()
>> - bpf_get_current_task()
>>
>> Cc: Alexei Starovoitov 
>> Signed-off-by: Quentin Monnet 
>> ---
>>  include/uapi/linux/bpf.h | 237 
>> +++
>>  1 file changed, 237 insertions(+)
>>
>> diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
>> index 2bc653a3a20f..f3ea8824efbc 100644
>> --- a/include/uapi/linux/bpf.h
>> +++ b/include/uapi/linux/bpf.h
>> @@ -580,6 +580,243 @@ union bpf_attr {
>>   *  performed again.
>>   *  Return
>>   *  0 on success, or a negative error in case of failure.
>> + *
>> + * u64 bpf_get_current_pid_tgid(void)
>> + *  Return
>> + *  A 64-bit integer containing the current tgid and pid, and
>> + *  created as such:
>> + *  *current_task*\ **->tgid << 32 \|**
>> + *  *current_task*\ **->pid**.
>> + *
>> + * u64 bpf_get_current_uid_gid(void)
>> + *  Return
>> + *  A 64-bit integer containing the current GID and UID, and
>> + *  created as such: *current_gid* **<< 32 \|** *current_uid*.
>> + *
>> + * int bpf_get_current_comm(char *buf, u32 size_of_buf)
>> + *  Description
>> + *  Copy the **comm** attribute of the current task into *buf* of
>> + *  *size_of_buf*. The **comm** attribute contains the name of
>> + *  the executable (excluding the path) for the current task. The
>> + *  *size_of_buf* must be strictly positive. On success, the
> 
> that reminds me that we probably should relax it to ARG_CONST_SIZE_OR_ZERO.
> The programs won't be passing an actual zero into it, but it helps
> a lot to tell verifier that zero is also valid, since programs
> become much simpler.
> 

Ok. No change to helper description for now, we will update here when
your patch lands.

>> + *  helper makes sure that the *buf* is NUL-terminated. On failure,
>> + *  it is filled with zeroes.
>> + *  Return
>> + *  0 on success, or a negative error in case of failure.
>> + *
>> + * int bpf_skb_vlan_push(struct sk_buff *skb, __be16 vlan_proto, u16 
>> vlan_tci)
>> + *  Description
>> + *  Push a *vlan_tci* (VLAN tag control information) of protocol
>> + *  *vlan_proto* to the packet associated to *skb*, then update
>> + *  the checksum. Note that if *vlan_proto* is different from
>> + *  **ETH_P_8021Q** and **ETH_P_8021AD**, it is considered to
>> + *  be **ETH_P_8021Q**.
>> + *
>> + *  A call to this helper is susceptible to change data from the
>> + *  packet. Therefore, at load time, all checks on pointers
>> + *  previously done by the verifier are invalidated and must be
>> + *  performed again.
>> + *  Return
>> + *  0 on success, or a negative error in case of failure.
>> + *
>> + * int bpf_skb_vlan_pop(struct sk_buff *skb)
>> + *  Description
>> + *  Pop a VLAN header from the packet associated to *skb*.
>> + *
>> + *  A call to this helper is susceptible to change data from the
>> + *  packet. Therefore, at load time, all checks on pointers
>> + *  previously done by the verifier are invalidated and must be
>> + *  performed again.
>> + *  Return
>> + *  0 on success, or a negative error in case of failure.
>> + *
>> + * int bpf_skb_get_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key 
>> *key, u32 size, u64 flags)
>> + *  Description
>> + *  Get tunnel metadata. This helper takes a pointer *key* to an
>> + *  empty **struct bpf_tunnel_key** of **size**, that will be
>> + *  filled with tunnel metadata for the packet associated to *skb*.
>> + *  The *flags* can be set to **BPF_F_TUNINFO_IPV6**, which
>> + *  indicates that the tunnel is based on IPv6 protocol instead of
>> + *  IPv4.
>> + *
>> + *  This is typically used on the receive path to perform a lookup
>> + *  or a packet redirection based on the value of *key*:
> 
> above is correct, but feels a bit cryptic.
> May be give more 

Re: [RFC bpf-next v2 3/8] bpf: add documentation for eBPF helpers (12-22)

[Alexei Starovoitov]

On Tue, Apr 10, 2018 at 03:41:52PM +0100, Quentin Monnet wrote:
> Add documentation for eBPF helper functions to bpf.h user header file.
> This documentation can be parsed with the Python script provided in
> another commit of the patch series, in order to provide a RST document
> that can later be converted into a man page.
> 
> The objective is to make the documentation easily understandable and
> accessible to all eBPF developers, including beginners.
> 
> This patch contains descriptions for the following helper functions, all
> writter by Alexei:
> 
> - bpf_get_current_pid_tgid()
> - bpf_get_current_uid_gid()
> - bpf_get_current_comm()
> - bpf_skb_vlan_push()
> - bpf_skb_vlan_pop()
> - bpf_skb_get_tunnel_key()
> - bpf_skb_set_tunnel_key()
> - bpf_redirect()
> - bpf_perf_event_output()
> - bpf_get_stackid()
> - bpf_get_current_task()
> 
> Cc: Alexei Starovoitov 
> Signed-off-by: Quentin Monnet 
> ---
>  include/uapi/linux/bpf.h | 237 
> +++
>  1 file changed, 237 insertions(+)
> 
> diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
> index 2bc653a3a20f..f3ea8824efbc 100644
> --- a/include/uapi/linux/bpf.h
> +++ b/include/uapi/linux/bpf.h
> @@ -580,6 +580,243 @@ union bpf_attr {
>   *   performed again.
>   *   Return
>   *   0 on success, or a negative error in case of failure.
> + *
> + * u64 bpf_get_current_pid_tgid(void)
> + *   Return
> + *   A 64-bit integer containing the current tgid and pid, and
> + *   created as such:
> + *   *current_task*\ **->tgid << 32 \|**
> + *   *current_task*\ **->pid**.
> + *
> + * u64 bpf_get_current_uid_gid(void)
> + *   Return
> + *   A 64-bit integer containing the current GID and UID, and
> + *   created as such: *current_gid* **<< 32 \|** *current_uid*.
> + *
> + * int bpf_get_current_comm(char *buf, u32 size_of_buf)
> + *   Description
> + *   Copy the **comm** attribute of the current task into *buf* of
> + *   *size_of_buf*. The **comm** attribute contains the name of
> + *   the executable (excluding the path) for the current task. The
> + *   *size_of_buf* must be strictly positive. On success, the

that reminds me that we probably should relax it to ARG_CONST_SIZE_OR_ZERO.
The programs won't be passing an actual zero into it, but it helps
a lot to tell verifier that zero is also valid, since programs
become much simpler.

> + *   helper makes sure that the *buf* is NUL-terminated. On failure,
> + *   it is filled with zeroes.
> + *   Return
> + *   0 on success, or a negative error in case of failure.
> + *
> + * int bpf_skb_vlan_push(struct sk_buff *skb, __be16 vlan_proto, u16 
> vlan_tci)
> + *   Description
> + *   Push a *vlan_tci* (VLAN tag control information) of protocol
> + *   *vlan_proto* to the packet associated to *skb*, then update
> + *   the checksum. Note that if *vlan_proto* is different from
> + *   **ETH_P_8021Q** and **ETH_P_8021AD**, it is considered to
> + *   be **ETH_P_8021Q**.
> + *
> + *   A call to this helper is susceptible to change data from the
> + *   packet. Therefore, at load time, all checks on pointers
> + *   previously done by the verifier are invalidated and must be
> + *   performed again.
> + *   Return
> + *   0 on success, or a negative error in case of failure.
> + *
> + * int bpf_skb_vlan_pop(struct sk_buff *skb)
> + *   Description
> + *   Pop a VLAN header from the packet associated to *skb*.
> + *
> + *   A call to this helper is susceptible to change data from the
> + *   packet. Therefore, at load time, all checks on pointers
> + *   previously done by the verifier are invalidated and must be
> + *   performed again.
> + *   Return
> + *   0 on success, or a negative error in case of failure.
> + *
> + * int bpf_skb_get_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key 
> *key, u32 size, u64 flags)
> + *   Description
> + *   Get tunnel metadata. This helper takes a pointer *key* to an
> + *   empty **struct bpf_tunnel_key** of **size**, that will be
> + *   filled with tunnel metadata for the packet associated to *skb*.
> + *   The *flags* can be set to **BPF_F_TUNINFO_IPV6**, which
> + *   indicates that the tunnel is based on IPv6 protocol instead of
> + *   IPv4.
> + *
> + *   This is typically used on the receive path to perform a lookup
> + *   or a packet redirection based on the value of *key*:

above is correct, but feels a bit cryptic.
May be give more concrete example for particular tunneling protocol like gre
and say that tunnel_key.remote_ip[46] is essential part of the encap and
bpf prog will make decisions based on the contents of the encap header
where bpf_tunnel_key is a 

[RFC bpf-next v2 3/8] bpf: add documentation for eBPF helpers (12-22)

[Quentin Monnet]

Add documentation for eBPF helper functions to bpf.h user header file.
This documentation can be parsed with the Python script provided in
another commit of the patch series, in order to provide a RST document
that can later be converted into a man page.

The objective is to make the documentation easily understandable and
accessible to all eBPF developers, including beginners.

This patch contains descriptions for the following helper functions, all
writter by Alexei:

- bpf_get_current_pid_tgid()
- bpf_get_current_uid_gid()
- bpf_get_current_comm()
- bpf_skb_vlan_push()
- bpf_skb_vlan_pop()
- bpf_skb_get_tunnel_key()
- bpf_skb_set_tunnel_key()
- bpf_redirect()
- bpf_perf_event_output()
- bpf_get_stackid()
- bpf_get_current_task()

Cc: Alexei Starovoitov 
Signed-off-by: Quentin Monnet 
---
 include/uapi/linux/bpf.h | 237 +++
 1 file changed, 237 insertions(+)

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 2bc653a3a20f..f3ea8824efbc 100644
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -580,6 +580,243 @@ union bpf_attr {
  * performed again.
  * Return
  * 0 on success, or a negative error in case of failure.
+ *
+ * u64 bpf_get_current_pid_tgid(void)
+ * Return
+ * A 64-bit integer containing the current tgid and pid, and
+ * created as such:
+ * *current_task*\ **->tgid << 32 \|**
+ * *current_task*\ **->pid**.
+ *
+ * u64 bpf_get_current_uid_gid(void)
+ * Return
+ * A 64-bit integer containing the current GID and UID, and
+ * created as such: *current_gid* **<< 32 \|** *current_uid*.
+ *
+ * int bpf_get_current_comm(char *buf, u32 size_of_buf)
+ * Description
+ * Copy the **comm** attribute of the current task into *buf* of
+ * *size_of_buf*. The **comm** attribute contains the name of
+ * the executable (excluding the path) for the current task. The
+ * *size_of_buf* must be strictly positive. On success, the
+ * helper makes sure that the *buf* is NUL-terminated. On failure,
+ * it is filled with zeroes.
+ * Return
+ * 0 on success, or a negative error in case of failure.
+ *
+ * int bpf_skb_vlan_push(struct sk_buff *skb, __be16 vlan_proto, u16 vlan_tci)
+ * Description
+ * Push a *vlan_tci* (VLAN tag control information) of protocol
+ * *vlan_proto* to the packet associated to *skb*, then update
+ * the checksum. Note that if *vlan_proto* is different from
+ * **ETH_P_8021Q** and **ETH_P_8021AD**, it is considered to
+ * be **ETH_P_8021Q**.
+ *
+ * A call to this helper is susceptible to change data from the
+ * packet. Therefore, at load time, all checks on pointers
+ * previously done by the verifier are invalidated and must be
+ * performed again.
+ * Return
+ * 0 on success, or a negative error in case of failure.
+ *
+ * int bpf_skb_vlan_pop(struct sk_buff *skb)
+ * Description
+ * Pop a VLAN header from the packet associated to *skb*.
+ *
+ * A call to this helper is susceptible to change data from the
+ * packet. Therefore, at load time, all checks on pointers
+ * previously done by the verifier are invalidated and must be
+ * performed again.
+ * Return
+ * 0 on success, or a negative error in case of failure.
+ *
+ * int bpf_skb_get_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key *key, 
u32 size, u64 flags)
+ * Description
+ * Get tunnel metadata. This helper takes a pointer *key* to an
+ * empty **struct bpf_tunnel_key** of **size**, that will be
+ * filled with tunnel metadata for the packet associated to *skb*.
+ * The *flags* can be set to **BPF_F_TUNINFO_IPV6**, which
+ * indicates that the tunnel is based on IPv6 protocol instead of
+ * IPv4.
+ *
+ * This is typically used on the receive path to perform a lookup
+ * or a packet redirection based on the value of *key*:
+ *
+ * ::
+ *
+ * struct bpf_tunnel_key key = {};
+ * bpf_skb_get_tunnel_key(skb, , sizeof(key), 0);
+ *  lookup or redirect based on key ...
+ *
+ * Return
+ * 0 on success, or a negative error in case of failure.
+ *
+ * int bpf_skb_set_tunnel_key(struct sk_buff *skb, struct bpf_tunnel_key *key, 
u32 size, u64 flags)
+ * Description
+ * Populate tunnel metadata for packet associated to *skb.* The
+ * tunnel metadata is set to the contents of *key*, of *size*. The
+ * *flags* can be set to a combination of the following values:
+ *
+ *