Skip to contentSkip to conversation

bpf: fix bpf_skb_pull_data documentation

PATCH Superseded Joanne Koong 3 participants 6 messages Jul 14, 2022 – Jul 15, 2022 BPF

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 bpf: fix bpf_skb_pull_data documentation

Fix documentation for bpf_skb_pull_data() helper for when flags == 0.

Fixes fa15601ab31e ("bpf: add documentation for eBPF helpers (33-41)")
---
 include/uapi/linux/bpf.h       | 3 ++-
 tools/include/uapi/linux/bpf.h | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)
include/uapi/linux/bpf.h +2 -1
index 379e68fb866f..a80c1f6bbe25 100644
@@ -2361,7 +2361,8 @@ union bpf_attr {
  * 		Pull in non-linear data in case the *skb* is non-linear and not
  * 		all of *len* are part of the linear section. Make *len* bytes
  * 		from *skb* readable and writable. If a zero value is passed for
- * 		*len*, then the whole length of the *skb* is pulled.
+ *		*len*, then all bytes in the head of the skb will be made readable
+ *		and writable.
  *
  * 		This helper is only needed for reading and writing with direct
  * 		packet access.
tools/include/uapi/linux/bpf.h +2 -1
index 379e68fb866f..a80c1f6bbe25 100644
@@ -2361,7 +2361,8 @@ union bpf_attr {
  * 		Pull in non-linear data in case the *skb* is non-linear and not
  * 		all of *len* are part of the linear section. Make *len* bytes
  * 		from *skb* readable and writable. If a zero value is passed for
- * 		*len*, then the whole length of the *skb* is pulled.
+ *		*len*, then all bytes in the head of the skb will be made readable
+ *		and writable.
  *
  * 		This helper is only needed for reading and writing with direct
  * 		packet access.
Signature · 1 line
2.30.2
#1 lore raw
Quoted 3 lines · Joanne Koong

Fix documentation for bpf_skb_pull_data() helper for when flags == 0.

sorry, this commit message should be "when len == 0" (not flags).

Quoted 39 lines
Fixes fa15601ab31e ("bpf: add documentation for eBPF helpers (33-41)")
---
 include/uapi/linux/bpf.h       | 3 ++-
 tools/include/uapi/linux/bpf.h | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)
include/uapi/linux/bpf.h +2 -1
index 379e68fb866f..a80c1f6bbe25 100644
@@ -2361,7 +2361,8 @@ union bpf_attr {
  *             Pull in non-linear data in case the *skb* is non-linear and not
  *             all of *len* are part of the linear section. Make *len* bytes
  *             from *skb* readable and writable. If a zero value is passed for
- *             *len*, then the whole length of the *skb* is pulled.
+ *             *len*, then all bytes in the head of the skb will be made readable
+ *             and writable.
  *
  *             This helper is only needed for reading and writing with direct
  *             packet access.
tools/include/uapi/linux/bpf.h +2 -2
index 379e68fb866f..a80c1f6bbe25 100644
@@ -2361,7 +2361,8 @@ union bpf_attr {
  *             Pull in non-linear data in case the *skb* is non-linear and not
  *             all of *len* are part of the linear section. Make *len* bytes
  *             from *skb* readable and writable. If a zero value is passed for
- *             *len*, then the whole length of the *skb* is pulled.
+ *             *len*, then all bytes in the head of the skb will be made readable
+ *             and writable.
  *
  *             This helper is only needed for reading and writing with direct
  *             packet access.
--

2.30.2

#2 lore raw
Quoted 8 lines · Joanne Koong
Quoted 3 lines · Joanne Koong

Fix documentation for bpf_skb_pull_data() helper for when flags == 0.

sorry, this commit message should be "when len == 0" (not flags).

Quoted 3 lines
Fixes fa15601ab31e ("bpf: add documentation for eBPF helpers (33-41)")

Yes, Rumen reported this to me some time ago but I never took the time to send a fix. Thanks a lot!

maintainer
#3 lore raw
In reply to Joanne Koong
Quoted 15 lines · Joanne Koong

Fix documentation for bpf_skb_pull_data() helper for when flags == 0.

Fixes fa15601ab31e ("bpf: add documentation for eBPF helpers (33-41)")
---
  include/uapi/linux/bpf.h       | 3 ++-
  tools/include/uapi/linux/bpf.h | 3 ++-
  2 files changed, 4 insertions(+), 2 deletions(-)
include/uapi/linux/bpf.h +0 -0
index 379e68fb866f..a80c1f6bbe25 100644

include/uapi/linux/bpf.h union bpf_attr { · line 2364

Quoted 5 lines
include/uapi/linux/bpf.h +1 -1
@@ -2361,7 +2361,8 @@ union bpf_attr {
   * 		Pull in non-linear data in case the *skb* is non-linear and not
   * 		all of *len* are part of the linear section. Make *len* bytes
   * 		from *skb* readable and writable. If a zero value is passed for
- * 		*len*, then the whole length of the *skb* is pulled.
+ *		*len*, then all bytes in the head of the skb will be made readable

Quentin, should the formatting be '*skb*' instead of 'skb'?

Maybe it's more clear if we speak of 'all bytes in the linear part' instead of 'all bytes in the head' of the skb to make it clearer? Either is ok with me though.

Thanks,
Daniel

#4 lore raw
Quoted 11 lines · Daniel Borkmann
Quoted 10 lines · Joanne Koong

Fix documentation for bpf_skb_pull_data() helper for when flags == 0.

Fixes fa15601ab31e ("bpf: add documentation for eBPF helpers (33-41)")

---
  include/uapi/linux/bpf.h       | 3 ++-
  tools/include/uapi/linux/bpf.h | 3 ++-

  2 files changed, 4 insertions(+), 2 deletions(-)
Quoted 16 lines
Quoted 6 lines
include/uapi/linux/bpf.h +0 -0
index 379e68fb866f..a80c1f6bbe25 100644
@@ -2361,7 +2361,8 @@ union bpf_attr {
    *         Pull in non-linear data in case the *skb* is non-linear
Quoted 8 lines

and not
   *         all of *len* are part of the linear section. Make *len* bytes
   *         from *skb* readable and writable. If a zero value is passed for
- *         *len*, then the whole length of the *skb* is pulled.
+ *        *len*, then all bytes in the head of the skb will be made readable

Quentin, should the formatting be '*skb*' instead of 'skb'?

Correct

Quoted 4 lines

Maybe it's more clear if we speak of 'all bytes in the linear part' instead of 'all
bytes in the head' of the skb to make it clearer? Either is ok with me though.

Good suggestion, “linear part” is maybe easier to understand given that the paragraph has no other mention the “head”.

Would it be worth, even, linking to e.g. Dave's doc
(http://vger.kernel.org/~davem/skb.html) here, to provide more details? People reading the header file may not need that, but folks reading the generated man page may not be aware of what a skb contains.

Quentin

#5 lore raw
Quoted 32 lines · Quentin Monnet
Quoted 11 lines · Daniel Borkmann
Quoted 10 lines · Joanne Koong

Fix documentation for bpf_skb_pull_data() helper for when flags == 0.

Fixes fa15601ab31e ("bpf: add documentation for eBPF helpers (33-41)")
---
  include/uapi/linux/bpf.h       | 3 ++-
  tools/include/uapi/linux/bpf.h | 3 ++-
  2 files changed, 4 insertions(+), 2 deletions(-)
Quoted 16 lines
Quoted 6 lines
include/uapi/linux/bpf.h +0 -0
index 379e68fb866f..a80c1f6bbe25 100644
@@ -2361,7 +2361,8 @@ union bpf_attr {
   *         Pull in non-linear data in case the *skb* is non-linear
Quoted 8 lines

and not
* all of *len* are part of the linear section. Make *len*
bytes
* from *skb* readable and writable. If a zero value is
passed for
- * *len*, then the whole length of the *skb* is pulled.
+ * *len*, then all bytes in the head of the skb will be made
readable

Quentin, should the formatting be '*skb*' instead of 'skb'?

Correct

Quoted 8 lines
Quoted 4 lines

Maybe it's more clear if we speak of 'all bytes in the linear part' instead of 'all
bytes in the head' of the skb to make it clearer? Either is ok with me though.

Good suggestion, “linear part” is maybe easier to understand given that the paragraph has no other mention the “head”.

Great, I'll send out v2 with these edits:
* changing skb -> *skb*
* changing "all bytes in the head" -> "all bytes in the linear part"

Quoted 4 lines

Would it be worth, even, linking to e.g. Dave's doc
(http://vger.kernel.org/~davem/skb.html) here, to provide more details? People reading the header file may not need that, but folks reading the generated man page may not be aware of what a skb contains.

In my personal opinion, I think people who are writing programs that are using skbs will already have read that page and/or know the internals of skbs. But I'm also happy to add that link in if you think it'd provide more context.

Quoted 3 lines

Quentin