Re: [PATCH bpf-next 12/13] docs: net: Fix various minor typos

[Tobin C. Harding]

On Fri, Aug 03, 2018 at 10:41:12AM +0200, Daniel Borkmann wrote:
> On 08/01/2018 07:09 AM, Tobin C. Harding wrote:
> > There are a few minor typos and grammatical issues.  We should however
> > try to keep the current flavour of the document.
> > 
> > Fix typos and grammar if glaringly required.
> > 
> > Signed-off-by: Tobin C. Harding <me@xxxxxxxx>
> 
> Overall looks good, just some minor nits:
> 
> >  Documentation/networking/filter.rst | 65 +++++++++++++++--------------
> >  1 file changed, 33 insertions(+), 32 deletions(-)
> > 
> > diff --git a/Documentation/networking/filter.rst b/Documentation/networking/filter.rst
> > index 99dfa74fc4f7..b989a6c882b8 100644
> > --- a/Documentation/networking/filter.rst
> > +++ b/Documentation/networking/filter.rst
> > @@ -32,10 +32,10 @@ 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.
> > +assured  that the filter will be kept until the socket is closed.
> 
>           ^-- looks like extra whitespace slipped in?
> 
> >  The biggest user of this construct might be libpcap. Issuing a high-level
> >  filter command like ``tcpdump -i em1 port 22`` passes through the libpcap
> > @@ -470,7 +470,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::
> >  
> > @@ -580,7 +580,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'
> > @@ -655,12 +655,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.
> > @@ -694,7 +694,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::
> > @@ -732,7 +732,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
> > @@ -831,9 +831,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.
> > @@ -844,11 +845,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
> 
>                                                                 ^-- ditto

Hi Daniel,

Thanks for doing such a careful review that you noticed this.  I'm
working on this more ATM and I've moved the document to use double
spaces between _all_ full stops.  Currently the document uses mostly
single spaces but there are some sections with double space.  The
internet tells me this is a 'style' issue not a rule.  And I've seen
single and double spacing in tree and do not know if one is favoured.

Do you care?  If you do not care I'll just use double spaces.  If you do
care and would prefer me to uniformly use a single space I can do that
also.  Oh, and FTR filter.txt looks like its going into userspace-api/
so you may care even less with that move.

If this is overly pedantic just tell me to go away :)

thanks,
Tobin.