linux-kernel - Re: [PATCH bpf-next 05/13] docs: net: Fix indentation issues for code snippets

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20180806002220.GJ3088@eros>
Date:   Mon, 6 Aug 2018 10:22:20 +1000
From:   "Tobin C. Harding" <me@...in.cc>
To:     Daniel Borkmann <daniel@...earbox.net>
Cc:     Alexei Starovoitov <ast@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        "David S. Miller" <davem@...emloft.net>, linux-doc@...r.kernel.org,
        netdev@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH bpf-next 05/13] docs: net: Fix indentation issues for
 code snippets

On Fri, Aug 03, 2018 at 10:44:23AM +0200, Daniel Borkmann wrote:
> On 08/01/2018 07:09 AM, Tobin C. Harding wrote:
> [...]
> > -Starting bpf_dbg is trivial and just requires issuing:
> > +Starting bpf_dbg is trivial and just requires issuing::
> >  
> > -# ./bpf_dbg
> > +  # ./bpf_dbg
> >  
> >  In case input and output do not equal stdin/stdout, bpf_dbg takes an
> >  alternative stdin source as a first argument, and an alternative stdout
> > @@ -381,86 +384,87 @@ file "~/.bpf_dbg_init" and the command history is stored in the file
> >  Interaction in bpf_dbg happens through a shell that also has auto-completion
> >  support (follow-up example commands starting with '>' denote bpf_dbg shell).
> >  The usual workflow would be to ...
> > -
> > -> load bpf 6,40 0 0 12,21 0 3 2048,48 0 0 23,21 0 1 1,6 0 0 65535,6 0 0 0
> > -  Loads a BPF filter from standard output of bpf_asm, or transformed via
> > -  e.g. `tcpdump -iem1 -ddd port 22 | tr '\n' ','`. Note that for JIT
> > -  debugging (next section), this command creates a temporary socket and
> > -  loads the BPF code into the kernel. Thus, this will also be useful for
> > -  JIT developers.
> > -
> > -> load pcap foo.pcap
> > -  Loads standard tcpdump pcap file.
> > -
> > -> run [<n>]
> > -bpf passes:1 fails:9
> > -  Runs through all packets from a pcap to account how many passes and fails
> > -  the filter will generate. A limit of packets to traverse can be given.
> > -
> > -> disassemble
> > -l0:	ldh [12]
> > -l1:	jeq #0x800, l2, l5
> > -l2:	ldb [23]
> > -l3:	jeq #0x1, l4, l5
> > -l4:	ret #0xffff
> > -l5:	ret #0
> > -  Prints out BPF code disassembly.
> > -
> > -> dump
> > -/* { op, jt, jf, k }, */
> > -{ 0x28,  0,  0, 0x0000000c },
> > -{ 0x15,  0,  3, 0x00000800 },
> > -{ 0x30,  0,  0, 0x00000017 },
> > -{ 0x15,  0,  1, 0x00000001 },
> > -{ 0x06,  0,  0, 0x0000ffff },
> > -{ 0x06,  0,  0, 0000000000 },
> > -  Prints out C-style BPF code dump.
> > -
> > -> breakpoint 0
> > -breakpoint at: l0:	ldh [12]
> > -> breakpoint 1
> > -breakpoint at: l1:	jeq #0x800, l2, l5
> > -  ...
> > -  Sets breakpoints at particular BPF instructions. Issuing a `run` command
> > -  will walk through the pcap file continuing from the current packet and
> > -  break when a breakpoint is being hit (another `run` will continue from
> > -  the currently active breakpoint executing next instructions):
> > -
> > -  > run
> > -  -- register dump --
> > -  pc:       [0]                       <-- program counter
> > -  code:     [40] jt[0] jf[0] k[12]    <-- plain BPF code of current instruction
> > -  curr:     l0:	ldh [12]              <-- disassembly of current instruction
> > -  A:        [00000000][0]             <-- content of A (hex, decimal)
> > -  X:        [00000000][0]             <-- content of X (hex, decimal)
> > -  M[0,15]:  [00000000][0]             <-- folded content of M (hex, decimal)
> > -  -- packet dump --                   <-- Current packet from pcap (hex)
> > -  len: 42
> > -    0: 00 19 cb 55 55 a4 00 14 a4 43 78 69 08 06 00 01
> > -   16: 08 00 06 04 00 01 00 14 a4 43 78 69 0a 3b 01 26
> > -   32: 00 00 00 00 00 00 0a 3b 01 01
> > -  (breakpoint)
> > -  >
> > -
> > -> breakpoint
> > -breakpoints: 0 1
> > -  Prints currently set breakpoints.
> > -
> > -> step [-<n>, +<n>]
> > -  Performs single stepping through the BPF program from the current pc
> > -  offset. Thus, on each step invocation, above register dump is issued.
> > -  This can go forwards and backwards in time, a plain `step` will break
> > -  on the next BPF instruction, thus +1. (No `run` needs to be issued here.)
> > -
> > -> select <n>
> > -  Selects a given packet from the pcap file to continue from. Thus, on
> > -  the next `run` or `step`, the BPF program is being evaluated against
> > -  the user pre-selected packet. Numbering starts just as in Wireshark
> > -  with index 1.
> > -
> > -> quit
> > -#
> > -  Exits bpf_dbg.
> > +::
> > +
> > +  > load bpf 6,40 0 0 12,21 0 3 2048,48 0 0 23,21 0 1 1,6 0 0 65535,6 0 0 0
> > +    Loads a BPF filter from standard output of bpf_asm, or transformed via
> > +    e.g. `tcpdump -iem1 -ddd port 22 | tr '\n' ','`. Note that for JIT
> > +    debugging (next section), this command creates a temporary socket and
> > +    loads the BPF code into the kernel. Thus, this will also be useful for
> > +    JIT developers.
> 
> Here for the bpf_dbg howto, it would be good to separate explanation from
> the cmdline code snippets. This would more easily clarify the commands
> themselves if we already go the rst route, so I'd prefer splitting this up.

Sure thing.  Will do as suggested. Thanks for the review.


	Tobin