bpf: fix minor issues in documentation for BPF helpers.
authorQuentin Monnet <quentin.monnet@netronome.com>
Fri, 10 May 2019 14:51:24 +0000 (15:51 +0100)
committerDaniel Borkmann <daniel@iogearbox.net>
Sun, 12 May 2019 23:12:45 +0000 (01:12 +0200)
This commit brings many minor fixes to the documentation for BPF helper
functions. Mostly, this is limited to formatting fixes and improvements.
In particular, fix broken formatting for bpf_skb_adjust_room().

Besides formatting, replace the mention of "bpf_fullsock()" (that is not
associated with any function or type exposed to the user) in the
description of bpf_sk_storage_get() by "full socket".

Signed-off-by: Quentin Monnet <quentin.monnet@netronome.com>
Acked-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
include/uapi/linux/bpf.h

index 989ef6b1c26972efee2787c44e9b0f13169b9318..63e0cf66f01a9698ff6bc41ac5492809bb83d834 100644 (file)
@@ -1518,18 +1518,18 @@ union bpf_attr {
  *             * **BPF_F_ADJ_ROOM_FIXED_GSO**: Do not adjust gso_size.
  *               Adjusting mss in this way is not allowed for datagrams.
  *
- *             * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV4 **:
- *             * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV6 **:
+ *             * **BPF_F_ADJ_ROOM_ENCAP_L3_IPV4**,
+ *               **BPF_F_ADJ_ROOM_ENCAP_L3_IPV6**:
  *               Any new space is reserved to hold a tunnel header.
  *               Configure skb offsets and other fields accordingly.
  *
- *             * **BPF_F_ADJ_ROOM_ENCAP_L4_GRE **:
- *             * **BPF_F_ADJ_ROOM_ENCAP_L4_UDP **:
+ *             * **BPF_F_ADJ_ROOM_ENCAP_L4_GRE**,
+ *               **BPF_F_ADJ_ROOM_ENCAP_L4_UDP**:
  *               Use with ENCAP_L3 flags to further specify the tunnel type.
  *
- *             * **BPF_F_ADJ_ROOM_ENCAP_L2(len) **:
+ *             * **BPF_F_ADJ_ROOM_ENCAP_L2**\ (*len*):
  *               Use with ENCAP_L3/L4 flags to further specify the tunnel
- *               type; **len** is the length of the inner MAC header.
+ *               type; *len* is the length of the inner MAC header.
  *
  *             A call to this helper is susceptible to change the underlying
  *             packet buffer. Therefore, at load time, all checks on pointers
@@ -2061,16 +2061,16 @@ union bpf_attr {
  *             **BPF_LWT_ENCAP_IP**
  *                     IP encapsulation (GRE/GUE/IPIP/etc). The outer header
  *                     must be IPv4 or IPv6, followed by zero or more
- *                     additional headers, up to LWT_BPF_MAX_HEADROOM total
- *                     bytes in all prepended headers. Please note that
- *                     if skb_is_gso(skb) is true, no more than two headers
- *                     can be prepended, and the inner header, if present,
- *                     should be either GRE or UDP/GUE.
+ *                     additional headers, up to **LWT_BPF_MAX_HEADROOM**
+ *                     total bytes in all prepended headers. Please note that
+ *                     if **skb_is_gso**\ (*skb*) is true, no more than two
+ *                     headers can be prepended, and the inner header, if
+ *                     present, should be either GRE or UDP/GUE.
  *
- *             BPF_LWT_ENCAP_SEG6*** types can be called by bpf programs of
- *             type BPF_PROG_TYPE_LWT_IN; BPF_LWT_ENCAP_IP type can be called
- *             by bpf programs of types BPF_PROG_TYPE_LWT_IN and
- *             BPF_PROG_TYPE_LWT_XMIT.
+ *             **BPF_LWT_ENCAP_SEG6**\ \* types can be called by BPF programs
+ *             of type **BPF_PROG_TYPE_LWT_IN**; **BPF_LWT_ENCAP_IP** type can
+ *             be called by bpf programs of types **BPF_PROG_TYPE_LWT_IN** and
+ *             **BPF_PROG_TYPE_LWT_XMIT**.
  *
  *             A call to this helper is susceptible to change the underlying
  *             packet buffer. Therefore, at load time, all checks on pointers
@@ -2126,11 +2126,11 @@ union bpf_attr {
  *                     Type of *param*: **int**.
  *             **SEG6_LOCAL_ACTION_END_B6**
  *                     End.B6 action: Endpoint bound to an SRv6 policy.
- *                     Type of param: **struct ipv6_sr_hdr**.
+ *                     Type of *param*: **struct ipv6_sr_hdr**.
  *             **SEG6_LOCAL_ACTION_END_B6_ENCAP**
  *                     End.B6.Encap action: Endpoint bound to an SRv6
  *                     encapsulation policy.
- *                     Type of param: **struct ipv6_sr_hdr**.
+ *                     Type of *param*: **struct ipv6_sr_hdr**.
  *
  *             A call to this helper is susceptible to change the underlying
  *             packet buffer. Therefore, at load time, all checks on pointers
@@ -2285,7 +2285,8 @@ union bpf_attr {
  *     Return
  *             Pointer to **struct bpf_sock**, or **NULL** in case of failure.
  *             For sockets with reuseport option, the **struct bpf_sock**
- *             result is from **reuse->socks**\ [] using the hash of the tuple.
+ *             result is from *reuse*\ **->socks**\ [] using the hash of the
+ *             tuple.
  *
  * struct bpf_sock *bpf_sk_lookup_udp(void *ctx, struct bpf_sock_tuple *tuple, u32 tuple_size, u64 netns, u64 flags)
  *     Description
@@ -2321,7 +2322,8 @@ union bpf_attr {
  *     Return
  *             Pointer to **struct bpf_sock**, or **NULL** in case of failure.
  *             For sockets with reuseport option, the **struct bpf_sock**
- *             result is from **reuse->socks**\ [] using the hash of the tuple.
+ *             result is from *reuse*\ **->socks**\ [] using the hash of the
+ *             tuple.
  *
  * int bpf_sk_release(struct bpf_sock *sock)
  *     Description
@@ -2490,31 +2492,34 @@ union bpf_attr {
  *             network namespace *netns*. The return value must be checked,
  *             and if non-**NULL**, released via **bpf_sk_release**\ ().
  *
- *             This function is identical to bpf_sk_lookup_tcp, except that it
- *             also returns timewait or request sockets. Use bpf_sk_fullsock
- *             or bpf_tcp_socket to access the full structure.
+ *             This function is identical to **bpf_sk_lookup_tcp**\ (), except
+ *             that it also returns timewait or request sockets. Use
+ *             **bpf_sk_fullsock**\ () or **bpf_tcp_sock**\ () to access the
+ *             full structure.
  *
  *             This helper is available only if the kernel was compiled with
  *             **CONFIG_NET** configuration option.
  *     Return
  *             Pointer to **struct bpf_sock**, or **NULL** in case of failure.
  *             For sockets with reuseport option, the **struct bpf_sock**
- *             result is from **reuse->socks**\ [] using the hash of the tuple.
+ *             result is from *reuse*\ **->socks**\ [] using the hash of the
+ *             tuple.
  *
  * int bpf_tcp_check_syncookie(struct bpf_sock *sk, void *iph, u32 iph_len, struct tcphdr *th, u32 th_len)
  *     Description
- *             Check whether iph and th contain a valid SYN cookie ACK for
- *             the listening socket in sk.
+ *             Check whether *iph* and *th* contain a valid SYN cookie ACK for
+ *             the listening socket in *sk*.
  *
- *             iph points to the start of the IPv4 or IPv6 header, while
- *             iph_len contains sizeof(struct iphdr) or sizeof(struct ip6hdr).
+ *             *iph* points to the start of the IPv4 or IPv6 header, while
+ *             *iph_len* contains **sizeof**\ (**struct iphdr**) or
+ *             **sizeof**\ (**struct ip6hdr**).
  *
- *             th points to the start of the TCP header, while th_len contains
- *             sizeof(struct tcphdr).
+ *             *th* points to the start of the TCP header, while *th_len*
+ *             contains **sizeof**\ (**struct tcphdr**).
  *
  *     Return
- *             0 if iph and th are a valid SYN cookie ACK, or a negative error
- *             otherwise.
+ *             0 if *iph* and *th* are a valid SYN cookie ACK, or a negative
+ *             error otherwise.
  *
  * int bpf_sysctl_get_name(struct bpf_sysctl *ctx, char *buf, size_t buf_len, u64 flags)
  *     Description
@@ -2592,17 +2597,17 @@ union bpf_attr {
  *             and save the result in *res*.
  *
  *             The string may begin with an arbitrary amount of white space
- *             (as determined by isspace(3)) followed by a single optional '-'
- *             sign.
+ *             (as determined by **isspace**\ (3)) followed by a single
+ *             optional '**-**' sign.
  *
  *             Five least significant bits of *flags* encode base, other bits
  *             are currently unused.
  *
  *             Base must be either 8, 10, 16 or 0 to detect it automatically
- *             similar to user space strtol(3).
+ *             similar to user space **strtol**\ (3).
  *     Return
  *             Number of characters consumed on success. Must be positive but
- *             no more than buf_len.
+ *             no more than *buf_len*.
  *
  *             **-EINVAL** if no valid digits were found or unsupported base
  *             was provided.
@@ -2616,16 +2621,16 @@ union bpf_attr {
  *             given base and save the result in *res*.
  *
  *             The string may begin with an arbitrary amount of white space
- *             (as determined by isspace(3)).
+ *             (as determined by **isspace**\ (3)).
  *
  *             Five least significant bits of *flags* encode base, other bits
  *             are currently unused.
  *
  *             Base must be either 8, 10, 16 or 0 to detect it automatically
- *             similar to user space strtoul(3).
+ *             similar to user space **strtoul**\ (3).
  *     Return
  *             Number of characters consumed on success. Must be positive but
- *             no more than buf_len.
+ *             no more than *buf_len*.
  *
  *             **-EINVAL** if no valid digits were found or unsupported base
  *             was provided.
@@ -2634,26 +2639,26 @@ union bpf_attr {
  *
  * void *bpf_sk_storage_get(struct bpf_map *map, struct bpf_sock *sk, void *value, u64 flags)
  *     Description
- *             Get a bpf-local-storage from a sk.
+ *             Get a bpf-local-storage from a *sk*.
  *
  *             Logically, it could be thought of getting the value from
  *             a *map* with *sk* as the **key**.  From this
  *             perspective,  the usage is not much different from
- *             **bpf_map_lookup_elem(map, &sk)** except this
- *             helper enforces the key must be a **bpf_fullsock()**
- *             and the map must be a BPF_MAP_TYPE_SK_STORAGE also.
+ *             **bpf_map_lookup_elem**\ (*map*, **&**\ *sk*) except this
+ *             helper enforces the key must be a full socket and the map must
+ *             be a **BPF_MAP_TYPE_SK_STORAGE** also.
  *
  *             Underneath, the value is stored locally at *sk* instead of
- *             the map.  The *map* is used as the bpf-local-storage **type**.
- *             The bpf-local-storage **type** (i.e. the *map*) is searched
- *             against all bpf-local-storages residing at sk.
+ *             the *map*.  The *map* is used as the bpf-local-storage
+ *             "type". The bpf-local-storage "type" (i.e. the *map*) is
+ *             searched against all bpf-local-storages residing at *sk*.
  *
- *             An optional *flags* (BPF_SK_STORAGE_GET_F_CREATE) can be
+ *             An optional *flags* (**BPF_SK_STORAGE_GET_F_CREATE**) can be
  *             used such that a new bpf-local-storage will be
  *             created if one does not exist.  *value* can be used
- *             together with BPF_SK_STORAGE_GET_F_CREATE to specify
+ *             together with **BPF_SK_STORAGE_GET_F_CREATE** to specify
  *             the initial value of a bpf-local-storage.  If *value* is
- *             NULL, the new bpf-local-storage will be zero initialized.
+ *             **NULL**, the new bpf-local-storage will be zero initialized.
  *     Return
  *             A bpf-local-storage pointer is returned on success.
  *
@@ -2662,7 +2667,7 @@ union bpf_attr {
  *
  * int bpf_sk_storage_delete(struct bpf_map *map, struct bpf_sock *sk)
  *     Description
- *             Delete a bpf-local-storage from a sk.
+ *             Delete a bpf-local-storage from a *sk*.
  *     Return
  *             0 on success.
  *