Hi,
This is my latest attempt at converting Documentation/filter.txt to RST
format. Added to the CC list because of additional changes to
Documentation/userspace-api/seccomp_filter.rst
For reference this set is a progression of the follow sets (in order of
post date to LKML)
1. [PATCH bpf-next 00/13] docs: Convert BPF filter.txt to RST
2. [RFC bpf-next 0/3] docs: Convert filter.txt to RST
3. [RFC bpf-next v2 0/3] docs: Convert filter.txt to RST
Sending this to BPF maintainers for hopeful inclusion in the bpf-next
tree. As discussed on LKML this set does all the conversion in a single
patch. This includes adding SPDX licence comments
(inc. seccomp_filter), adding RST labels, and updating references.
Please note this set adds three files to the MAINTAINERS file for the
BPF maintainers. Is this rude?
Also this set adds a SPDX licence to all new files and also to
seccomp_filter.rst I did this because checkpatch asked me to but I am
unsure on the protocol, is it acceptable to add a licence to
documentation that someone else wrote?
For the Record;
Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
docs?
Kees, Andy, and Drewry, can I please have permission to add GPLv2+ to
seccomp_filter.rst
(added Cc: tag to patch 2 that adds the licence identifiers)
thanks,
Tobin.
Tobin C. Harding (4):
docs: net: Fix various minor typos
docs: Separate and convert filter.txt to RST
docs: Judiciously use double ticks
docs: Remove filter.txt from the tree
Documentation/networking/filter.txt | 1476 -----------------
Documentation/userspace-api/cBPF.rst | 432 +++++
Documentation/userspace-api/eBPF.rst | 1006 +++++++++++
Documentation/userspace-api/index.rst | 3 +
.../userspace-api/seccomp_filter.rst | 11 +
Documentation/userspace-api/socket_filter.rst | 183 ++
MAINTAINERS | 4 +-
7 files changed, 1638 insertions(+), 1477 deletions(-)
delete mode 100644 Documentation/networking/filter.txt
create mode 100644 Documentation/userspace-api/cBPF.rst
create mode 100644 Documentation/userspace-api/eBPF.rst
create mode 100644 Documentation/userspace-api/socket_filter.rst
--
2.17.1
Document contains a few minor typos and grammatical issues. We should
however try to keep the current flavour of the document.
Fix typos and grammar if fix is _really_ an improvement.
Signed-off-by: Tobin C. Harding <[email protected]>
---
Documentation/networking/filter.txt | 66 +++++++++++++++--------------
1 file changed, 35 insertions(+), 31 deletions(-)
diff --git a/Documentation/networking/filter.txt b/Documentation/networking/filter.txt
index e6b4ebb2b243..1fe4adf9c4c6 100644
--- a/Documentation/networking/filter.txt
+++ b/Documentation/networking/filter.txt
@@ -29,8 +29,8 @@ removing the old one and placing your new one in its place, assuming your
filter has passed the checks, otherwise if it fails the old filter will
remain on that socket.
-SO_LOCK_FILTER option allows to lock the filter attached to a socket. Once
-set, a filter cannot be removed or changed. This allows one process to
+SO_LOCK_FILTER option allows locking of the filter attached to a socket.
+Once set, a filter cannot be removed or changed. This allows one process to
setup a socket, attach a filter, lock it then drop privileges and be
assured that the filter will be kept until the socket is closed.
@@ -463,7 +463,7 @@ JIT compiler
------------
The Linux kernel has a built-in BPF JIT compiler for x86_64, SPARC, PowerPC,
-ARM, ARM64, MIPS and s390 and can be enabled through CONFIG_BPF_JIT. The JIT
+ARM, ARM64, MIPS and s390 which can be enabled through CONFIG_BPF_JIT. The JIT
compiler is transparently invoked for each attached filter from user space
or for internal kernel users if it has been previously enabled by root:
@@ -572,7 +572,7 @@ Internally, for the kernel interpreter, a different instruction set
format with similar underlying principles from BPF described in previous
paragraphs is being used. However, the instruction set format is modelled
closer to the underlying architecture to mimic native instruction sets, so
-that a better performance can be achieved (more details later). This new
+that better performance can be achieved (more details later). This new
ISA is called 'eBPF' or 'internal BPF' interchangeably. (Note: eBPF which
originates from [e]xtended BPF is not the same as BPF extensions! While
eBPF is an ISA, BPF extensions date back to classic BPF's 'overloading'
@@ -647,12 +647,12 @@ Some core changes of the new internal format:
32-bit architectures run 64-bit internal BPF programs via interpreter.
Their JITs may convert BPF programs that only use 32-bit subregisters into
- native instruction set and let the rest being interpreted.
+ native instruction set and let the rest be interpreted.
- Operation is 64-bit, because on 64-bit architectures, pointers are also
- 64-bit wide, and we want to pass 64-bit values in/out of kernel functions,
- so 32-bit eBPF registers would otherwise require to define register-pair
- ABI, thus, there won't be able to use a direct eBPF register to HW register
+ Operation is 64-bit since on 64-bit architectures pointers are also
+ 64-bit wide and we want to pass 64-bit values in/out of kernel functions.
+ 32-bit eBPF registers would otherwise require us to define a register-pair
+ ABI, thus we would not be able to use a direct eBPF register to HW register
mapping and JIT would need to do combine/split/move operations for every
register in and out of the function, which is complex, bug prone and slow.
Another reason is the use of atomic 64-bit counters.
@@ -677,7 +677,7 @@ Some core changes of the new internal format:
situations without performance penalty.
After an in-kernel function call, R1 - R5 are reset to unreadable and R0 has
- a return value of the function. Since R6 - R9 are callee saved, their state
+ the return value of the function. Since R6 - R9 are callee saved, their state
is preserved across the call.
For example, consider three C functions:
@@ -715,7 +715,7 @@ Some core changes of the new internal format:
are currently not supported, but these restrictions can be lifted if necessary
in the future.
- On 64-bit architectures all register map to HW registers one to one. For
+ On 64-bit architectures all registers map to HW registers one to one. For
example, x86_64 JIT compiler can map them as ...
R0 - rax
@@ -814,9 +814,10 @@ A program, that is translated internally consists of the following elements:
op:16, jt:8, jf:8, k:32 ==> op:8, dst_reg:4, src_reg:4, off:16, imm:32
-So far 87 internal BPF instructions were implemented. 8-bit 'op' opcode field
-has room for new instructions. Some of them may use 16/24/32 byte encoding. New
-instructions must be multiple of 8 bytes to preserve backward compatibility.
+So far 87 internal BPF instructions have been implemented. 8-bit 'op' opcode
+field has room for new instructions. Some of them may use 16/24/32 byte
+encoding. New instructions must be a multiple of 8 bytes to preserve backward
+compatibility.
Internal BPF is a general purpose RISC instruction set. Not every register and
every instruction are used during translation from original BPF to new format.
@@ -827,11 +828,11 @@ out of registers and would have to resort to spill/fill to stack.
Internal BPF can used as generic assembler for last step performance
optimizations, socket filters and seccomp are using it as assembler. Tracing
-filters may use it as assembler to generate code from kernel. In kernel usage
+filters may use it as assembler to generate code from kernel. In-kernel usage
may not be bounded by security considerations, since generated internal BPF code
-may be optimizing internal code path and not being exposed to the user space.
-Safety of internal BPF can come from a verifier (TBD). In such use cases as
-described, it may be used as safe instruction set.
+may use an optimised internal code path and may not be being exposed to user
+space. Safety of internal BPF can come from a verifier (TBD). In such use cases
+as described, it may be used as safe as the instruction set.
Just like the original BPF, the new format runs within a controlled environment,
is deterministic and the kernel can easily prove that. The safety of the program
@@ -927,7 +928,7 @@ Classic BPF is using BPF_MISC class to represent A = X and X = A moves.
eBPF is using BPF_MOV | BPF_X | BPF_ALU code instead. Since there are no
BPF_MISC operations in eBPF, the class 7 is used as BPF_ALU64 to mean
exactly the same operations as BPF_ALU, but with 64-bit wide operands
-instead. So BPF_ADD | BPF_X | BPF_ALU64 means 64-bit addition, i.e.:
+instead. So BPF_ADD | BPF_X | BPF_ALU64 means 64-bit addition i.e.
dst_reg = dst_reg + src_reg
Classic BPF wastes the whole BPF_RET class to represent a single 'ret'
@@ -1005,9 +1006,10 @@ BPF_XADD | BPF_DW | BPF_STX: lock xadd *(u64 *)(dst_reg + off16) += src_reg
Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. Note that 1 and
2 byte atomic increments are not supported.
-eBPF has one 16-byte instruction: BPF_LD | BPF_DW | BPF_IMM which consists
-of two consecutive 'struct bpf_insn' 8-byte blocks and interpreted as single
+eBPF has one 16-byte instruction: BPF_LD | BPF_DW | BPF_IMM which consists of
+two consecutive 'struct bpf_insn' 8-byte blocks and is interpreted as single
instruction that loads 64-bit immediate value into a dst_reg.
+
Classic BPF has similar instruction: BPF_LD | BPF_W | BPF_IMM which loads
32-bit immediate value into a register.
@@ -1016,8 +1018,8 @@ eBPF verifier
The safety of the eBPF program is determined in two steps.
First step does DAG check to disallow loops and other CFG validation.
-In particular it will detect programs that have unreachable instructions.
-(though classic BPF checker allows them)
+In particular it will detect programs that have unreachable instructions
+(though classic BPF checker allows them).
Second step starts from the first insn and descends all possible paths.
It simulates execution of every insn and observes the state change of
@@ -1078,7 +1080,9 @@ Classic BPF verifier does similar check with M[0-15] memory slots.
For example:
bpf_ld R0 = *(u32 *)(R10 - 4)
bpf_exit
-is invalid program.
+
+is an invalid program.
+
Though R10 is correct read-only register and has type PTR_TO_STACK
and R10 - 4 is within stack bounds, there were no stores into that location.
@@ -1089,13 +1093,13 @@ Allowed function calls are customized with bpf_verifier_ops->get_func_proto()
The eBPF verifier will check that registers match argument constraints.
After the call register R0 will be set to return type of the function.
-Function calls is a main mechanism to extend functionality of eBPF programs.
-Socket filters may let programs to call one set of functions, whereas tracing
-filters may allow completely different set.
+Function calls is an important mechanism to extend functionality of eBPF
+programs. Socket filters may let programs call one set of functions,
+whereas tracing filters may allow a completely different set.
-If a function made accessible to eBPF program, it needs to be thought through
-from safety point of view. The verifier will guarantee that the function is
-called with valid arguments.
+If a function is made accessible to eBPF program, it needs to be thought
+through from a safety point of view. The verifier will guarantee that the
+function is called with valid arguments.
seccomp vs socket filters have different security restrictions for classic BPF.
Seccomp solves this by two stage verifier: classic BPF verifier is followed
@@ -1167,7 +1171,7 @@ checked and found to be non-NULL, all copies can become PTR_TO_MAP_VALUEs.
As well as range-checking, the tracked information is also used for enforcing
alignment of pointer accesses. For instance, on most systems the packet pointer
is 2 bytes after a 4-byte alignment. If a program adds 14 bytes to that to jump
-over the Ethernet header, then reads IHL and addes (IHL * 4), the resulting
+over the Ethernet header, then reads IHL and adds (IHL * 4), the resulting
pointer will have a variable offset known to be 4n+2 for some n, so adding the 2
bytes (NET_IP_ALIGN) gives a 4-byte alignment and so word-sized accesses through
that pointer are safe.
--
2.17.1
Double ticks _can_ make the documentation easier to follow in HTML.
They can however make the documentation _harder_ to read in plain text.
We should use double ticks but judiciously.
Judiciously use double ticks to replace single ticks.
Signed-off-by: Tobin C. Harding <[email protected]>
---
Documentation/userspace-api/eBPF.rst | 69 ++++++++++++++--------------
1 file changed, 34 insertions(+), 35 deletions(-)
diff --git a/Documentation/userspace-api/eBPF.rst b/Documentation/userspace-api/eBPF.rst
index 39fbe18a38fa..e4813d69de49 100644
--- a/Documentation/userspace-api/eBPF.rst
+++ b/Documentation/userspace-api/eBPF.rst
@@ -155,7 +155,7 @@ to in-kernel function. If R1 - R5 registers are mapped to CPU registers
that are used for argument passing on given architecture, the JIT
compiler doesn't need to emit extra moves. Function arguments will be
in the correct registers and BPF_CALL instruction will be JITed as
-single 'call' HW instruction. This calling convention was picked to
+single ``call`` HW instruction. This calling convention was picked to
cover common call situations without performance penalty.
After an in-kernel function call, R1 - R5 are reset to unreadable and R0
@@ -268,7 +268,7 @@ Which is in this example equivalent in C to::
In-kernel functions foo() and bar() with prototype: u64 (*)(u64 arg1,
u64 arg2, u64 arg3, u64 arg4, u64 arg5); will receive arguments in
-proper registers and place their return value into '%rax' which is R0 in
+proper registers and place their return value into ``%rax`` which is R0 in
eBPF. Prologue and epilogue are emitted by JIT and are implicit in the
interpreter. R0-R5 are scratch registers, so eBPF program needs to
preserve them across the calls as defined by calling convention.
@@ -425,7 +425,7 @@ exactly the same operations as BPF_ALU, but with 64-bit wide operands
instead. So BPF_ADD | BPF_X | BPF_ALU64 means 64-bit addition i.e.
dst_reg = dst_reg + src_reg
-Classic BPF wastes the whole BPF_RET class to represent a single 'ret'
+Classic BPF wastes the whole BPF_RET class to represent a single ``ret``
operation. Classic BPF_RET | BPF_K means copy imm32 into return
register and perform function exit. eBPF is modeled to match CPU, so
BPF_JMP | BPF_EXIT in eBPF means function exit only. The eBPF program
@@ -469,7 +469,7 @@ eBPF has two non-generic instructions: (BPF_ABS | <size> | BPF_LD) and
They had to be carried over from classic to have strong performance of
socket filters running in eBPF interpreter. These instructions can only
-be used when interpreter context is a pointer to 'struct sk_buff' and
+be used when interpreter context is a pointer to ``struct sk_buff`` and
have seven implicit operands. Register R6 is an implicit input that
must contain pointer to sk_buff. Register R0 is an implicit output
which contains the data fetched from the packet. Registers R1-R5 are
@@ -502,7 +502,7 @@ Where size is one of: BPF_B or BPF_H or BPF_W or BPF_DW. Note that 1
and 2 byte atomic increments are not supported.
eBPF has one 16-byte instruction: BPF_LD | BPF_DW | BPF_IMM which
-consists of two consecutive 'struct bpf_insn' 8-byte blocks and is
+consists of two consecutive ``struct bpf_insn`` 8-byte blocks and is
interpreted as single instruction that loads 64-bit immediate value into
a dst_reg.
@@ -565,8 +565,8 @@ alignment checked. For example::
will be rejected, since R1 doesn't have a valid pointer type at the time
of execution of instruction bpf_xadd.
-At the start R1 type is PTR_TO_CTX (a pointer to generic 'struct
-bpf_context'). A callback is used to customize verifier to restrict
+At the start R1 type is PTR_TO_CTX (a pointer to generic ``struct
+bpf_context``). A callback is used to customize verifier to restrict
eBPF program access to only certain fields within ctx structure with
specified size and alignment.
@@ -628,7 +628,7 @@ Register value tracking
In order to determine the safety of an eBPF program, the verifier must
track the range of possible values in each register and also in each
-stack slot. This is done with 'struct bpf_reg_state', defined in
+stack slot. This is done with ``struct bpf_reg_state``, defined in
include/linux/bpf_verifier.h, which unifies tracking of scalar and
pointer values. Each register state has a type, which is either
NOT_INIT (the register has not been written to), SCALAR_VALUE (some
@@ -715,7 +715,7 @@ data via skb->data and skb->data_end pointers, e.g.::
6: r0 = *(u16 *)(r3 +12) /* access 12 and 13 bytes of the packet */
this 2byte load from the packet is safe to do, since the program author
-did check 'if (skb->data + 14 > skb->data_end) goto err' at insn #5
+did check ``if (skb->data + 14 > skb->data_end) goto err`` at insn #5
which means that in the fall-through case the register R3 (which points
to skb->data) has at least 14 directly accessible bytes. The verifier
marks it as R3=pkt(id=0,off=0,r=14). id=0 means that no additional
@@ -723,8 +723,8 @@ variables were added to the register. off=0 means that no additional
constants were added. r=14 is the range of safe access which means that
bytes [R3, R3 + 14) are ok. Note that R5 is marked as
R5=pkt(id=0,off=14,r=14). It also points to the packet data, but
-constant 14 was added to the register, so it now points to 'skb->data +
-14' and accessible range is [R5, R5 + 14 - 14) which is zero bytes.
+constant 14 was added to the register, so it now points to ``skb->data +
+14`` and accessible range is [R5, R5 + 14 - 14) which is zero bytes.
More complex packet access may look like::
@@ -745,30 +745,29 @@ More complex packet access may look like::
R0=inv(id=0,umax_value=255,var_off=(0x0; 0xff)) R1=pkt_end R2=pkt(id=2,off=8,r=8) R3=pkt(id=2,off=0,r=8) R4=inv(id=0,umax_value=3570,var_off=(0x0; 0xfffe)) R5=pkt(id=0,off=14,r=14) R10=fp
19: r1 = *(u8 *)(r3 +4)
-The state of the register R3 is R3=pkt(id=2,off=0,r=8) id=2 means that
-two 'r3 += rX' instructions were seen, so r3 points to some offset
-within a packet and since the program author did 'if (r3 + 8 > r1) goto
-err' at insn #18, the safe range is [R3, R3 + 8). The verifier only
-allows 'add'/'sub' operations on packet registers. Any other operation
-will set the register state to 'SCALAR_VALUE' and it won't be available
-for direct packet access. Operation 'r3 += rX' may overflow and become
-less than original skb->data, therefore the verifier has to prevent
-that. So when it sees 'r3 += rX' instruction and rX is more than 16-bit
-value, any subsequent bounds-check of r3 against skb->data_end will not
-give us 'range' information, so attempts to read through the pointer
-will give "invalid access to packet" error. Ex. after insn 'r4 = *(u8
-*)(r3 +12)' (insn #7 above) the state of r4 is
-R4=inv(id=0,umax_value=255,var_off=(0x0; 0xff)) which means that upper
-56 bits of the register are guaranteed to be zero, and nothing is known
-about the lower 8 bits. After insn 'r4 *= 14' the state becomes
-R4=inv(id=0,umax_value=3570,var_off=(0x0; 0xfffe)), since multiplying an
-8-bit value by constant 14 will keep upper 52 bits as zero, also the
-least significant bit will be zero as 14 is even. Similarly 'r2 >>= 48'
-will make R2=inv(id=0,umax_value=65535,var_off=(0x0; 0xffff)), since the
-shift is not sign extending. This logic is implemented in
-adjust_reg_min_max_vals() function, which calls
-adjust_ptr_min_max_vals() for adding pointer to scalar (or vice versa)
-and adjust_scalar_min_max_vals() for operations on two scalars.
+The state of the register R3 is ``R3=pkt(id=2,off=0,r=8)`` id=2 means that
+two ``r3 += rX`` instructions were seen, so r3 points to some offset within
+a packet and since the program author did ``if (r3 + 8 > r1) goto err`` at
+insn #18, the safe range is [R3, R3 + 8). The verifier only allows
+'add'/'sub' operations on packet registers. Any other operation will set
+the register state to 'SCALAR_VALUE' and it won't be available for direct
+packet access. Operation ``r3 += rX`` may overflow and become less than
+original skb->data, therefore the verifier has to prevent that. So when it
+sees ``r3 += rX`` instruction and rX is more than 16-bit value, any
+subsequent bounds-check of r3 against skb->data_end will not give us
+'range' information, so attempts to read through the pointer will give
+"invalid access to packet" error. Ex. after insn ``r4 = *(u8 *)(r3 +12)``
+(insn #7 above) the state of r4 is R4=inv(id=0,umax_value=255,var_off=(0x0;
+0xff)) which means that upper 56 bits of the register are guaranteed to be
+zero, and nothing is known about the lower 8 bits. After insn ``r4 *= 14``
+the state becomes R4=inv(id=0,umax_value=3570,var_off=(0x0; 0xfffe)), since
+multiplying an 8-bit value by constant 14 will keep upper 52 bits as zero,
+also the least significant bit will be zero as 14 is even. Similarly ``r2
+>>= 48`` will make R2=inv(id=0,umax_value=65535,var_off=(0x0; 0xffff)),
+since the shift is not sign extending. This logic is implemented in
+adjust_reg_min_max_vals() function, which calls adjust_ptr_min_max_vals()
+for adding pointer to scalar (or vice versa) and
+adjust_scalar_min_max_vals() for operations on two scalars.
The end result is that bpf program author can access packet directly
using normal C code as::
--
2.17.1
On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
>
> Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
> docs?
kernel licensing is GPLv2 without +
every file (including docs) can potentially have a different
compatible license, but since they were developed
implicitly under v2 only you would need to get a buy-in from
all contributors before making such change.
On Wed, Aug 08, 2018 at 11:07:35PM -0700, Alexei Starovoitov wrote:
> On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
> >
> > Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
> > docs?
>
> kernel licensing is GPLv2 without +
According to process/license-rules.rst
GPL-2.0+ : GNU General Public License v2.0 or later
> every file (including docs) can potentially have a different
> compatible license, but since they were developed
> implicitly under v2 only you would need to get a buy-in from
> all contributors before making such change.
So if a file does not _explicitly_ state that it is under another
licence it is ok to add GPLv2?
thanks,
Tobin.
On 08/09/2018 09:27 AM, Tobin C. Harding wrote:
> On Wed, Aug 08, 2018 at 11:07:35PM -0700, Alexei Starovoitov wrote:
>> On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
>>>
>>> Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
>>> docs?
>>
>> kernel licensing is GPLv2 without +
>
> According to process/license-rules.rst
>
> GPL-2.0+ : GNU General Public License v2.0 or later
Not really, please see the first three paragraphs of process/license-rules.rst.
The COPYING file of the kernel says that it's 'v2' and not 'v2 or later',
unless otherwise _explicitly_ noted. Given that and given there is no other
specific note in filter.txt, it would mean it's v2-only due to that rule.
>> every file (including docs) can potentially have a different
>> compatible license, but since they were developed
>> implicitly under v2 only you would need to get a buy-in from
>> all contributors before making such change.
>
> So if a file does not _explicitly_ state that it is under another
> licence it is ok to add GPLv2?
>
>
> thanks,
> Tobin.
>
On Thu, Aug 09, 2018 at 10:24:54AM +0200, Daniel Borkmann wrote:
> On 08/09/2018 09:27 AM, Tobin C. Harding wrote:
> > On Wed, Aug 08, 2018 at 11:07:35PM -0700, Alexei Starovoitov wrote:
> >> On Thu, Aug 09, 2018 at 03:23:24PM +1000, Tobin C. Harding wrote:
> >>>
> >>> Daniel and Alexei, can I please have permission to add GPLv2+ to the BPF
> >>> docs?
> >>
> >> kernel licensing is GPLv2 without +
> >
> > According to process/license-rules.rst
> >
> > GPL-2.0+ : GNU General Public License v2.0 or later
>
> Not really, please see the first three paragraphs of process/license-rules.rst.
> The COPYING file of the kernel says that it's 'v2' and not 'v2 or later',
> unless otherwise _explicitly_ noted. Given that and given there is no other
> specific note in filter.txt, it would mean it's v2-only due to that rule.
Thanks for clarifying. My understanding is now; this is a case where
checkpatch is too verbose and we do not actually need to add a specific
license identifier to the documentation files (new or otherwise). They
get an implicit GPLv2.
I'll remove the licences identifiers and re-spin.
thanks,
Tobin.
On Fri, 10 Aug 2018 11:46:36 +1000
"Tobin C. Harding" <[email protected]> wrote:
> Thanks for clarifying. My understanding is now; this is a case where
> checkpatch is too verbose and we do not actually need to add a specific
> license identifier to the documentation files (new or otherwise). They
> get an implicit GPLv2.
The objective actually is to have SPDX tags in all files in the kernel.
That includes documentation, even though people, as always, care less
about the docs than they do the code.
As I understood it, the complaint with the tags you put in wasn't their
existence, it was your putting GPLv2+ rather than straight GPLv2. In the
absence of information to the contrary, you really have to assume the
latter, since that's the overall license for the kernel.
Thanks,
jon
On Fri, Aug 10, 2018 at 5:57 AM Jonathan Corbet <[email protected]> wrote:
>
> The objective actually is to have SPDX tags in all files in the kernel.
> That includes documentation, even though people, as always, care less
> about the docs than they do the code.
right, but let's do that as a separate patch set.
In the current set I'd focus on reviewing the actual doc changes.
In particular completely removing
Documentation/networking/filter.txt
feels wrong, since lots of websites point directly there.
Can we have at least few words there pointing to new location?
On Fri, Aug 10, 2018 at 06:57:52AM -0600, Jonathan Corbet wrote:
> On Fri, 10 Aug 2018 11:46:36 +1000
> "Tobin C. Harding" <[email protected]> wrote:
>
> > Thanks for clarifying. My understanding is now; this is a case where
> > checkpatch is too verbose and we do not actually need to add a specific
> > license identifier to the documentation files (new or otherwise). They
> > get an implicit GPLv2.
>
> The objective actually is to have SPDX tags in all files in the kernel.
> That includes documentation, even though people, as always, care less
> about the docs than they do the code.
>
> As I understood it, the complaint with the tags you put in wasn't their
> existence, it was your putting GPLv2+ rather than straight GPLv2. In the
> absence of information to the contrary, you really have to assume the
> latter, since that's the overall license for the kernel.
Righto, thanks Jon. GPLv0 tags going in for v3
Tobin
On Fri, Aug 10, 2018 at 10:51:28AM -0700, Alexei Starovoitov wrote:
> On Fri, Aug 10, 2018 at 5:57 AM Jonathan Corbet <[email protected]> wrote:
> >
> > The objective actually is to have SPDX tags in all files in the kernel.
> > That includes documentation, even though people, as always, care less
> > about the docs than they do the code.
>
> right, but let's do that as a separate patch set.
> In the current set I'd focus on reviewing the actual doc changes.
> In particular completely removing
> Documentation/networking/filter.txt
> feels wrong, since lots of websites point directly there.
> Can we have at least few words there pointing to new location?
Something like ...
------------ filter.txt
BPF documentation can now be found in the following places:
- Introduction to BPF (Linux Socket Filter) - Documentation/userspace-api/socket-filter.rst
- Classic BPF (cBPF) - Documentation/userspace-api/cBPF.rst
- Internal BPF (eBPF) - Documentation/userspace-api/eBPF.rst
- SECCOMP BPF - Documentation/userspace-api/seccomp_filter.rst
- BPF Design Q&A - Documentation/bpf/bpf_design_QA.rst
- BPF Development Q&A - Documentation/bpf/bpf_devel_QA.rst
-------------
Also this highlights that bpf/index.rst is not quite correct yet in this
set. The Q&A files are indexed but not explicitly mentioned. My
feeling is that bpf/index.rst should mirror the information above.
thanks,
Tobin.
On Sat, Aug 11, 2018 at 09:50:58PM +1000, Tobin C. Harding wrote:
> On Fri, Aug 10, 2018 at 10:51:28AM -0700, Alexei Starovoitov wrote:
> > On Fri, Aug 10, 2018 at 5:57 AM Jonathan Corbet <[email protected]> wrote:
> > >
> > > The objective actually is to have SPDX tags in all files in the kernel.
> > > That includes documentation, even though people, as always, care less
> > > about the docs than they do the code.
> >
> > right, but let's do that as a separate patch set.
> > In the current set I'd focus on reviewing the actual doc changes.
> > In particular completely removing
> > Documentation/networking/filter.txt
> > feels wrong, since lots of websites point directly there.
> > Can we have at least few words there pointing to new location?
>
> Something like ...
>
>
> ------------ filter.txt
>
> BPF documentation can now be found in the following places:
>
> - Introduction to BPF (Linux Socket Filter) - Documentation/userspace-api/socket-filter.rst
> - Classic BPF (cBPF) - Documentation/userspace-api/cBPF.rst
> - Internal BPF (eBPF) - Documentation/userspace-api/eBPF.rst
Internal ?
that was the name we used for may be a month many years ago.
Please use 'extended BPF' in new filter.txt and all other places.
since merge window is open the patches would need to wait until
bpf-next opens up in few weeks.
Thanks