Re: [bpf-next PATCH 0/5] bpf, doc: convert Documentation/bpf to RST-formatting

[Y Song]

On Mon, May 14, 2018 at 6:42 AM, Jesper Dangaard Brouer
 wrote:
> The kernel is moving files under Documentation to use the RST
> (reStructuredText) format and Sphinx [1].  This patchset converts the
> files under Documentation/bpf/ into RST format.  The Sphinx
> integration is left as followup work.
>
> [1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html
>
> This patchset have been uploaded as branch bpf_doc10 on github[2], so
> reviewers can see how GitHub renders this.
>
> [2] https://github.com/netoptimizer/linux/tree/bpf_doc10/Documentation/bpf
>
> ---
>
> Jesper Dangaard Brouer (5):
>   bpf, doc: add basic README.rst file
>   bpf, doc: rename txt files to rst files
>   bpf, doc: convert bpf_design_QA.rst to use RST formatting
>   bpf, doc: convert bpf_devel_QA.rst to use RST formatting
>   bpf, doc: howto use/run the BPF selftests

This initial conversion from .txt to .rst files look good to me. Ack
for the whole series.
Acked-by: Yonghong Song 

>
>
>  Documentation/bpf/README.rst|   36 ++
>  Documentation/bpf/bpf_design_QA.rst |  221 
>  Documentation/bpf/bpf_design_QA.txt |  156 -
>  Documentation/bpf/bpf_devel_QA.rst  |  640 
> +++
>  Documentation/bpf/bpf_devel_QA.txt  |  570 ---
>  5 files changed, 897 insertions(+), 726 deletions(-)
>  create mode 100644 Documentation/bpf/README.rst
>  create mode 100644 Documentation/bpf/bpf_design_QA.rst
>  delete mode 100644 Documentation/bpf/bpf_design_QA.txt
>  create mode 100644 Documentation/bpf/bpf_devel_QA.rst
>  delete mode 100644 Documentation/bpf/bpf_devel_QA.txt
>
> --
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] Documentation: arm: clean up Marvell Berlin family info

[Thomas Hebb]

Remove dead links, make spacing consistent, and note that the family was
acquired by Synaptics in 2017.

Signed-off-by: Thomas Hebb 
---
 Documentation/arm/Marvell/README | 15 +++
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README
index b5bb7f518840..56ada27c53be 100644
--- a/Documentation/arm/Marvell/README
+++ b/Documentation/arm/Marvell/README
@@ -302,19 +302,15 @@ Berlin family (Multimedia Solutions)
88DE3010, Armada 1000 (no Linux support)
Core:   Marvell PJ1 (ARMv5TE), Dual-core
Product Brief:  
http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf
-   88DE3005, Armada 1500-mini
88DE3005, Armada 1500 Mini
Design name:BG2CD
Core:   ARM Cortex-A9, PL310 L2CC
-   Homepage:   
http://www.marvell.com/multimedia-solutions/armada-1500-mini/
-88DE3006, Armada 1500 Mini Plus
-Design name:BG2CDP
-Core:   Dual Core ARM Cortex-A7
-Homepage:   
http://www.marvell.com/multimedia-solutions/armada-1500-mini-plus/
+   88DE3006, Armada 1500 Mini Plus
+   Design name:BG2CDP
+   Core:   Dual Core ARM Cortex-A7
88DE3100, Armada 1500
Design name:BG2
Core:   Marvell PJ4B-MP (ARMv7), Tauros3 L2CC
-   Product Brief:  
http://www.marvell.com/digital-entertainment/armada-1500/assets/Marvell-ARMADA-1500-Product-Brief.pdf
88DE3114, Armada 1500 Pro
Design name:BG2Q
Core:   Quad Core ARM Cortex-A9, PL310 L2CC
@@ -324,13 +320,16 @@ Berlin family (Multimedia Solutions)
88DE3218, ARMADA 1500 Ultra
Core:   ARM Cortex-A53
 
-  Homepage: http://www.marvell.com/multimedia-solutions/
+  Homepage: https://www.synaptics.com/products/multimedia-solutions
   Directory: arch/arm/mach-berlin
 
   Comments:
+
* This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs
  with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, 
ETH, ...).
 
+   * The Berlin family was acquired by Synaptics from Marvell in 2017.
+
 CPU Cores
 -
 
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v3] coresight: documentation: update sysfs section

[Randy Dunlap]

On 05/14/2018 12:18 PM, Kim Phillips wrote:
> - Align and show updated ls devices output from the TC2, based on
>   current driver
> 
> - Provide an example from an ETMv4 based system (Juno)
> 
> - Reflect changes to the way the RAM write pointer is accessed since
>   it got changed in commit 7d83d17795ef ("coresight: tmc: adding sysFS
>   management entries").
> 
> Cc: Mathieu Poirier 
> Cc: Randy Dunlap 
> Cc: Jonathan Corbet 
> Signed-off-by: Kim Phillips 

FWIW:
Acked-by: Randy Dunlap 

Thanks.

> ---
> v3: address Randy Dunlap's showns->shown,  corrected - and + line merging
> v2: address Mathieu's comment about clarifying the sinks on the Juno
> vs. TC2 platforms.
> 
>  Documentation/trace/coresight.txt | 43 +++
>  1 file changed, 26 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/trace/coresight.txt 
> b/Documentation/trace/coresight.txt
> index 6f0120c3a4f1..15d2a0f1e1b8 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.txt
> @@ -141,13 +141,25 @@ register the device with the core framework.  The 
> unregister function takes
>  a reference to a "struct coresight_device", obtained at registration time.
>  
>  If everything goes well during the registration process the new devices will
> -show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:
> +show up under /sys/bus/coresight/devices, as shown here for a TC2 platform:
>  
>  root:~# ls /sys/bus/coresight/devices/
> -replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
> -2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
> +2001.etb   2004.funnel   2201d000.ptm  2203d000.etm  replicator
> +2003.tpiu  2201c000.ptm  2203c000.etm  2203e000.etm
>  root:~#
>  
> +and here for a Juno platform:
> +
> +root@juno:~# ls /sys/bus/coresight/devices/
> +2001.etf  2012.replicator  2204.etm 230c.funnel
> +2003.tpiu 2013.funnel  220c.funnel  2314.etm
> +2004.funnel  2014.etf  2214.etm 2324.etm
> +2007.etr  2015.funnel  2304.etm 2334.etm
> +root@juno:~# 
> +
> +Note that on Juno users can select the ETF, ETR and TPIU as a sink target 
> while
> +on TC2, the ETB and TPIU can be selected.
> +
>  The functions take a "struct coresight_device", which looks like this:
>  
>  struct coresight_desc {
> @@ -193,16 +205,16 @@ the information carried in "THIS_MODULE".
>  How to use the tracer modules
>  -
>  
> -Before trace collection can start, a coresight sink needs to be identify.
> +Before trace collection can start, a coresight sink needs to be identified.
>  There is no limit on the amount of sinks (nor sources) that can be enabled at
>  any given moment.  As a generic operation, all device pertaining to the sink
>  class will have an "active" entry in sysfs:
>  
>  root:/sys/bus/coresight/devices# ls
> -replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
> -2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
> +2001.etb   2004.funnel   2201d000.ptm  2203d000.etm  replicator
> +2003.tpiu  2201c000.ptm  2203c000.etm  2203e000.etm
>  root:/sys/bus/coresight/devices# ls 2001.etb
> -enable_sink  status  trigger_cntr
> +enable_sink  mgmt  power  subsystem  trigger_cntr  uevent
>  root:/sys/bus/coresight/devices# echo 1 > 2001.etb/enable_sink
>  root:/sys/bus/coresight/devices# cat 2001.etb/enable_sink
>  1
> @@ -216,16 +228,13 @@ trigger a trace capture:
>  root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
>  root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
>  1
> -root:/sys/bus/coresight/devices# cat 2001.etb/status
> -Depth:  0x2000
> -Status: 0x1
> -RAM read ptr:   0x0
> -RAM wrt ptr:0x19d3   <- The write pointer is moving
> -Trigger cnt:0x0
> -Control:0x1
> -Flush status:   0x0
> -Flush ctrl: 0x2001
> -root:/sys/bus/coresight/devices#
> +
> +Observe the write pointer moving:
> +
> +root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
> +0x1a8
> +root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
> +0x19a6
>  
>  Trace collection is stopped the same way:
>  
> 


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 10/18] rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()

[Paul E. McKenney]

On Wed, May 09, 2018 at 08:55:33AM -0300, Mauro Carvalho Chehab wrote:
> Em Mon, 7 May 2018 07:23:22 -0700
> "Paul E. McKenney"  escreveu:
> 
> > On Mon, May 07, 2018 at 06:35:46AM -0300, Mauro Carvalho Chehab wrote:
> > > The code example at rcupdate.h currently produce lots of warnings:
> > > 
> > >   ./include/linux/rcupdate.h:572: WARNING: Unexpected indentation.
> > >   ./include/linux/rcupdate.h:576: WARNING: Unexpected indentation.
> > >   ./include/linux/rcupdate.h:580: WARNING: Block quote ends without a 
> > > blank line; unexpected unindent.
> > >   ./include/linux/rcupdate.h:582: WARNING: Block quote ends without a 
> > > blank line; unexpected unindent.
> > >   ./include/linux/rcupdate.h:582: WARNING: Inline literal start-string 
> > > without end-string.
> > > 
> > > Change it to a code-block.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab   
> > 
> > Acked-by: Paul E. McKenney 
> > 
> > If you don't tell me otherwise, I will assume that you are pushing this.
> > If you would rather that I take it, please let me know!
> 
> Hi Paul,
> 
> Feel free to merge it via your tree. It seems that Jon prefers to have
> code changes merged via the usual maintainers.

I have queued it for v4.19, thank you!

Thanx, Paul

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v3] coresight: documentation: update sysfs section

[Kim Phillips]

- Align and show updated ls devices output from the TC2, based on
  current driver

- Provide an example from an ETMv4 based system (Juno)

- Reflect changes to the way the RAM write pointer is accessed since
  it got changed in commit 7d83d17795ef ("coresight: tmc: adding sysFS
  management entries").

Cc: Mathieu Poirier 
Cc: Randy Dunlap 
Cc: Jonathan Corbet 
Signed-off-by: Kim Phillips 
---
v3: address Randy Dunlap's showns->shown,  corrected - and + line merging
v2: address Mathieu's comment about clarifying the sinks on the Juno
vs. TC2 platforms.

 Documentation/trace/coresight.txt | 43 +++
 1 file changed, 26 insertions(+), 17 deletions(-)

diff --git a/Documentation/trace/coresight.txt 
b/Documentation/trace/coresight.txt
index 6f0120c3a4f1..15d2a0f1e1b8 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.txt
@@ -141,13 +141,25 @@ register the device with the core framework.  The 
unregister function takes
 a reference to a "struct coresight_device", obtained at registration time.
 
 If everything goes well during the registration process the new devices will
-show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:
+show up under /sys/bus/coresight/devices, as shown here for a TC2 platform:
 
 root:~# ls /sys/bus/coresight/devices/
-replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
-2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
+2001.etb   2004.funnel 2201d000.ptm  2203d000.etm  replicator
+2003.tpiu  2201c000.ptm2203c000.etm  2203e000.etm
 root:~#
 
+and here for a Juno platform:
+
+root@juno:~# ls /sys/bus/coresight/devices/
+2001.etf2012.replicator  2204.etm 230c.funnel
+2003.tpiu   2013.funnel  220c.funnel  2314.etm
+2004.funnel  2014.etf2214.etm 2324.etm
+2007.etr2015.funnel  2304.etm 2334.etm
+root@juno:~# 
+
+Note that on Juno users can select the ETF, ETR and TPIU as a sink target while
+on TC2, the ETB and TPIU can be selected.
+
 The functions take a "struct coresight_device", which looks like this:
 
 struct coresight_desc {
@@ -193,16 +205,16 @@ the information carried in "THIS_MODULE".
 How to use the tracer modules
 -
 
-Before trace collection can start, a coresight sink needs to be identify.
+Before trace collection can start, a coresight sink needs to be identified.
 There is no limit on the amount of sinks (nor sources) that can be enabled at
 any given moment.  As a generic operation, all device pertaining to the sink
 class will have an "active" entry in sysfs:
 
 root:/sys/bus/coresight/devices# ls
-replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
-2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
+2001.etb   2004.funnel 2201d000.ptm  2203d000.etm  replicator
+2003.tpiu  2201c000.ptm2203c000.etm  2203e000.etm
 root:/sys/bus/coresight/devices# ls 2001.etb
-enable_sink  status  trigger_cntr
+enable_sink  mgmt  power  subsystem  trigger_cntr  uevent
 root:/sys/bus/coresight/devices# echo 1 > 2001.etb/enable_sink
 root:/sys/bus/coresight/devices# cat 2001.etb/enable_sink
 1
@@ -216,16 +228,13 @@ trigger a trace capture:
 root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
 root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
 1
-root:/sys/bus/coresight/devices# cat 2001.etb/status
-Depth:  0x2000
-Status: 0x1
-RAM read ptr:   0x0
-RAM wrt ptr:0x19d3   <- The write pointer is moving
-Trigger cnt:0x0
-Control:0x1
-Flush status:   0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
+
+Observe the write pointer moving:
+
+root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
+0x1a8
+root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
+0x19a6
 
 Trace collection is stopped the same way:
 
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] coresight: documentation: update sysfs section

[Randy Dunlap]

On 05/14/2018 10:19 AM, Kim Phillips wrote:
> - Align and show updated ls devices output from the TC2, based on
>   current driver
> 
> - Provide an example from an ETMv4 based system (Juno)
> 
> - Reflect changes to the way the RAM write pointer is accessed since
>   it got changed in commit 7d83d17795ef ("coresight: tmc: adding sysFS
>   management entries").
> 
> Cc: Mathieu Poirier 
> Cc: Jonathan Corbet 
> Signed-off-by: Kim Phillips 
> ---
> v2: address Mathieu's comment about clarifying the sinks on the Juno
> vs. TC2 platforms.
> 
>  Documentation/trace/coresight.txt | 41 +++
>  1 file changed, 25 insertions(+), 16 deletions(-)
> 
> diff --git a/Documentation/trace/coresight.txt
> b/Documentation/trace/coresight.txt index 6f0120c3a4f1..134994e9fa6d
> 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.txt
> @@ -144,10 +144,22 @@ If everything goes well during the registration
> process the new devices will show up under /sys/bus/coresight/devices,
> as showns here for a TC2 platform: 

  as shown here

>  root:~# ls /sys/bus/coresight/devices/
> -replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
> -2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
> +2001.etb   2004.funnel   2201d000.ptm  2203d000.etm
> replicator +2003.tpiu  2201c000.ptm   2203c000.etm
> 2203e000.etm root:~#
>  
> +and here for a Juno platform:
> +
> +root@juno:~# ls /sys/bus/coresight/devices/
> +2001.etf  2012.replicator  2204.etm
> 230c.funnel +2003.tpiu 2013.funnel
> 220c.funnel  2314.etm +2004.funnel
> 2014.etf2214.etm 2324.etm
> +2007.etr  2015.funnel  2304.etm
> 2334.etm +root@juno:~# +
> +Note that on Juno users can select the ETF, ETR and TPIU as a sink
> target while +on TC2, the ETB and TPIU can be selected.
> +
>  The functions take a "struct coresight_device", which looks like this:
>  
>  struct coresight_desc {
> @@ -193,16 +205,16 @@ the information carried in "THIS_MODULE".
>  How to use the tracer modules
>  -
>  
> -Before trace collection can start, a coresight sink needs to be
> identify. +Before trace collection can start, a coresight sink needs to

The - and + lines seems to be merged...

> be identified. There is no limit on the amount of sinks (nor sources)
> that can be enabled at any given moment.  As a generic operation, all
> device pertaining to the sink class will have an "active" entry in
> sysfs: 
>  root:/sys/bus/coresight/devices# ls
> -replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
> -2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
> +2001.etb   2004.funnel   2201d000.ptm  2203d000.etm
> replicator +2003.tpiu  2201c000.ptm   2203c000.etm
> 2203e000.etm root:/sys/bus/coresight/devices# ls 2001.etb
> -enable_sink  status  trigger_cntr
> +enable_sink  mgmt  power  subsystem  trigger_cntr  uevent
>  root:/sys/bus/coresight/devices# echo 1 > 2001.etb/enable_sink
>  root:/sys/bus/coresight/devices# cat 2001.etb/enable_sink
>  1
> @@ -216,16 +228,13 @@ trigger a trace capture:
>  root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
>  root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
>  1
> -root:/sys/bus/coresight/devices# cat 2001.etb/status
> -Depth:  0x2000
> -Status: 0x1
> -RAM read ptr:   0x0
> -RAM wrt ptr:0x19d3   <- The write pointer is moving
> -Trigger cnt:0x0
> -Control:0x1
> -Flush status:   0x0
> -Flush ctrl: 0x2001
> -root:/sys/bus/coresight/devices#
> +
> +Observe the write pointer moving:
> +
> +root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
> +0x1a8
> +root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
> +0x19a6
>  
>  Trace collection is stopped the same way:
>  
> 


-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2] coresight: documentation: update sysfs section

[Kim Phillips]

- Align and show updated ls devices output from the TC2, based on
  current driver

- Provide an example from an ETMv4 based system (Juno)

- Reflect changes to the way the RAM write pointer is accessed since
  it got changed in commit 7d83d17795ef ("coresight: tmc: adding sysFS
  management entries").

Cc: Mathieu Poirier 
Cc: Jonathan Corbet 
Signed-off-by: Kim Phillips 
---
v2: address Mathieu's comment about clarifying the sinks on the Juno
vs. TC2 platforms.

 Documentation/trace/coresight.txt | 41 +++
 1 file changed, 25 insertions(+), 16 deletions(-)

diff --git a/Documentation/trace/coresight.txt
b/Documentation/trace/coresight.txt index 6f0120c3a4f1..134994e9fa6d
100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.txt
@@ -144,10 +144,22 @@ If everything goes well during the registration
process the new devices will show up under /sys/bus/coresight/devices,
as showns here for a TC2 platform: 
 root:~# ls /sys/bus/coresight/devices/
-replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
-2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
+2001.etb   2004.funnel 2201d000.ptm  2203d000.etm
replicator +2003.tpiu  2201c000.ptm 2203c000.etm
2203e000.etm root:~#
 
+and here for a Juno platform:
+
+root@juno:~# ls /sys/bus/coresight/devices/
+2001.etf2012.replicator  2204.etm
230c.funnel +2003.tpiu   2013.funnel
220c.funnel  2314.etm +2004.funnel
2014.etf  2214.etm 2324.etm
+2007.etr2015.funnel  2304.etm
2334.etm +root@juno:~# +
+Note that on Juno users can select the ETF, ETR and TPIU as a sink
target while +on TC2, the ETB and TPIU can be selected.
+
 The functions take a "struct coresight_device", which looks like this:
 
 struct coresight_desc {
@@ -193,16 +205,16 @@ the information carried in "THIS_MODULE".
 How to use the tracer modules
 -
 
-Before trace collection can start, a coresight sink needs to be
identify. +Before trace collection can start, a coresight sink needs to
be identified. There is no limit on the amount of sinks (nor sources)
that can be enabled at any given moment.  As a generic operation, all
device pertaining to the sink class will have an "active" entry in
sysfs: 
 root:/sys/bus/coresight/devices# ls
-replicator  2003.tpiu2201c000.ptm  2203c000.etm  2203e000.etm
-2001.etb 2004.funnel  2201d000.ptm  2203d000.etm
+2001.etb   2004.funnel 2201d000.ptm  2203d000.etm
replicator +2003.tpiu  2201c000.ptm 2203c000.etm
2203e000.etm root:/sys/bus/coresight/devices# ls 2001.etb
-enable_sink  status  trigger_cntr
+enable_sink  mgmt  power  subsystem  trigger_cntr  uevent
 root:/sys/bus/coresight/devices# echo 1 > 2001.etb/enable_sink
 root:/sys/bus/coresight/devices# cat 2001.etb/enable_sink
 1
@@ -216,16 +228,13 @@ trigger a trace capture:
 root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
 root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
 1
-root:/sys/bus/coresight/devices# cat 2001.etb/status
-Depth:  0x2000
-Status: 0x1
-RAM read ptr:   0x0
-RAM wrt ptr:0x19d3   <- The write pointer is moving
-Trigger cnt:0x0
-Control:0x1
-Flush status:   0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
+
+Observe the write pointer moving:
+
+root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
+0x1a8
+root:/sys/bus/coresight/devices# cat 2001.etb/mgmt/rwp
+0x19a6
 
 Trace collection is stopped the same way:
 
-- 
2.17.0

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [bpf-next PATCH 5/5] bpf, doc: howto use/run the BPF selftests

[Jesper Dangaard Brouer]

On Mon, 14 May 2018 17:15:54 +0200
Silvan Jegen  wrote:

> Hi
> 
> Some typo fixes below.
> 
> On Mon, May 14, 2018 at 3:43 PM Jesper Dangaard Brouer 
> wrote:
> > I always forget howto run the BPF selftests. Thus, lets add that info
> > to the QA document.  
> 
> > Documentation was based on Cilium's documentation:
> >   http://cilium.readthedocs.io/en/latest/bpf/#verifying-the-setup  
> 
> > Signed-off-by: Jesper Dangaard Brouer 
> > ---
> >   Documentation/bpf/bpf_devel_QA.rst |   29 +
> >   1 file changed, 29 insertions(+)  
> 
> > diff --git a/Documentation/bpf/bpf_devel_QA.rst  
> b/Documentation/bpf/bpf_devel_QA.rst
> > index 2254bdeae990..0e7c1d946e83 100644
> > --- a/Documentation/bpf/bpf_devel_QA.rst
> > +++ b/Documentation/bpf/bpf_devel_QA.rst
> > @@ -417,6 +417,33 @@ submitted by the BPF maintainers to the stable  
> maintainers.
> >   Testing patches
> >   ===  
> 
> > +Q: How to run BPF selftests
> > +---
> > +A: After you have booted into the newly compiled kernel, navigate to
> > +the BPF selftests_ suite in order to test BPF functionality (current
> > +working directory points to the root of the cloned git tree)::
> > +
> > +  $ cd tools/testing/selftests/bpf/
> > +  $ make
> > +
> > +To run the verifier tests::
> > +
> > +  $ sudo ./test_verifier
> > +
> > +The verifier tests print out all the current checks being
> > +performed. The summary at the end of running all tests will dump
> > +information of test successes and failures::  
> 
> Two colons at the end of the line. Don't think that was intended.

It is intended, that is part of the RST formatting.

> 
> > +
> > +  Summary: 418 PASSED, 0 FAILED
> > +
> > +In order to run through all BPF selftests, the following command is
> > +needed::
> > +
> > +  $ sudo make run_tests
> > +
> > +See the kernels selftest `Documentation/dev-tools/kselftest.rst`_  
> 
> s/kernels/kernel's/

I guess that is more correct...

> I also think the underscore at the end of this line is misplaced (or it
> should be a dash instead).

This is also part of the RST formatting.  This is a link. 


> > +document for further documentation.
> > +
> >   Q: Which BPF kernel selftests version should I run my kernel against?
> >   -
> >   A: If you run a kernel ``xyz``, then always run the BPF kernel selftests
> > @@ -607,5 +634,7 @@ when:
> >   .. _netdev FAQ: ../networking/netdev-FAQ.txt
> >   .. _samples/bpf/: ../../samples/bpf/
> >   .. _selftests: ../../tools/testing/selftests/bpf/
> > +.. _Documentation/dev-tools/kselftest.rst:
> > +   https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html  

The link is defined above/here.

-- 
Best regards,
  Jesper Dangaard Brouer
  MSc.CS, Principal Kernel Engineer at Red Hat
  LinkedIn: http://www.linkedin.com/in/brouer
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [bpf-next PATCH 5/5] bpf, doc: howto use/run the BPF selftests

[Silvan Jegen]

Hi

Some typo fixes below.

On Mon, May 14, 2018 at 3:43 PM Jesper Dangaard Brouer 
wrote:
> I always forget howto run the BPF selftests. Thus, lets add that info
> to the QA document.

> Documentation was based on Cilium's documentation:
>   http://cilium.readthedocs.io/en/latest/bpf/#verifying-the-setup

> Signed-off-by: Jesper Dangaard Brouer 
> ---
>   Documentation/bpf/bpf_devel_QA.rst |   29 +
>   1 file changed, 29 insertions(+)

> diff --git a/Documentation/bpf/bpf_devel_QA.rst
b/Documentation/bpf/bpf_devel_QA.rst
> index 2254bdeae990..0e7c1d946e83 100644
> --- a/Documentation/bpf/bpf_devel_QA.rst
> +++ b/Documentation/bpf/bpf_devel_QA.rst
> @@ -417,6 +417,33 @@ submitted by the BPF maintainers to the stable
maintainers.
>   Testing patches
>   ===

> +Q: How to run BPF selftests
> +---
> +A: After you have booted into the newly compiled kernel, navigate to
> +the BPF selftests_ suite in order to test BPF functionality (current
> +working directory points to the root of the cloned git tree)::
> +
> +  $ cd tools/testing/selftests/bpf/
> +  $ make
> +
> +To run the verifier tests::
> +
> +  $ sudo ./test_verifier
> +
> +The verifier tests print out all the current checks being
> +performed. The summary at the end of running all tests will dump
> +information of test successes and failures::

Two colons at the end of the line. Don't think that was intended.


> +
> +  Summary: 418 PASSED, 0 FAILED
> +
> +In order to run through all BPF selftests, the following command is
> +needed::
> +
> +  $ sudo make run_tests
> +
> +See the kernels selftest `Documentation/dev-tools/kselftest.rst`_

s/kernels/kernel's/

I also think the underscore at the end of this line is misplaced (or it
should be a dash instead).

Cheers,

Silvan


> +document for further documentation.
> +
>   Q: Which BPF kernel selftests version should I run my kernel against?
>   -
>   A: If you run a kernel ``xyz``, then always run the BPF kernel selftests
> @@ -607,5 +634,7 @@ when:
>   .. _netdev FAQ: ../networking/netdev-FAQ.txt
>   .. _samples/bpf/: ../../samples/bpf/
>   .. _selftests: ../../tools/testing/selftests/bpf/
> +.. _Documentation/dev-tools/kselftest.rst:
> +   https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html

>   Happy BPF hacking!

> --
> To unsubscribe from this list: send the line "unsubscribe linux-man" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[bpf-next PATCH 3/5] bpf, doc: convert bpf_design_QA.rst to use RST formatting

[Jesper Dangaard Brouer]

The RST formatting is done such that that when rendered or converted
to different formats, an automatic index with links are created to the
subsections.

Thus, the questions are created as sections (or subsections), in-order
to get the wanted auto-generated FAQ/QA index.

Special thanks to Quentin Monnet  who
have reviewed and corrected both RST formatting and GitHub rendering
issues in this file.  Those commits have been squashed.

I've manually tested that this also renders nicely if included as part
of the kernel 'make htmldocs'.  As the end-goal is for this to become
more integrated with kernel-doc project/movement.

Signed-off-by: Jesper Dangaard Brouer 
---
 Documentation/bpf/bpf_design_QA.rst |  223 +++
 1 file changed, 144 insertions(+), 79 deletions(-)

diff --git a/Documentation/bpf/bpf_design_QA.rst 
b/Documentation/bpf/bpf_design_QA.rst
index f3e458a0bb2f..6780a6d81745 100644
--- a/Documentation/bpf/bpf_design_QA.rst
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -1,156 +1,221 @@
+==
+BPF Design Q
+==
+
 BPF extensibility and applicability to networking, tracing, security
 in the linux kernel and several user space implementations of BPF
 virtual machine led to a number of misunderstanding on what BPF actually is.
 This short QA is an attempt to address that and outline a direction
 of where BPF is heading long term.
 
+.. contents::
+:local:
+:depth: 3
+
+Questions and Answers
+=
+
 Q: Is BPF a generic instruction set similar to x64 and arm64?
+-
 A: NO.
 
 Q: Is BPF a generic virtual machine ?
+-
 A: NO.
 
-BPF is generic instruction set _with_ C calling convention.
+BPF is generic instruction set *with* C calling convention.
+---
 
 Q: Why C calling convention was chosen?
+~~~
+
 A: Because BPF programs are designed to run in the linux kernel
-   which is written in C, hence BPF defines instruction set compatible
-   with two most used architectures x64 and arm64 (and takes into
-   consideration important quirks of other architectures) and
-   defines calling convention that is compatible with C calling
-   convention of the linux kernel on those architectures.
+which is written in C, hence BPF defines instruction set compatible
+with two most used architectures x64 and arm64 (and takes into
+consideration important quirks of other architectures) and
+defines calling convention that is compatible with C calling
+convention of the linux kernel on those architectures.
 
 Q: can multiple return values be supported in the future?
+~
 A: NO. BPF allows only register R0 to be used as return value.
 
 Q: can more than 5 function arguments be supported in the future?
+~
 A: NO. BPF calling convention only allows registers R1-R5 to be used
-   as arguments. BPF is not a standalone instruction set.
-   (unlike x64 ISA that allows msft, cdecl and other conventions)
+as arguments. BPF is not a standalone instruction set.
+(unlike x64 ISA that allows msft, cdecl and other conventions)
 
 Q: can BPF programs access instruction pointer or return address?
+-
 A: NO.
 
 Q: can BPF programs access stack pointer ?
-A: NO. Only frame pointer (register R10) is accessible.
-   From compiler point of view it's necessary to have stack pointer.
-   For example LLVM defines register R11 as stack pointer in its
-   BPF backend, but it makes sure that generated code never uses it.
+--
+A: NO.
+
+Only frame pointer (register R10) is accessible.
+From compiler point of view it's necessary to have stack pointer.
+For example LLVM defines register R11 as stack pointer in its
+BPF backend, but it makes sure that generated code never uses it.
 
 Q: Does C-calling convention diminishes possible use cases?
-A: YES. BPF design forces addition of major functionality in the form
-   of kernel helper functions and kernel objects like BPF maps with
-   seamless interoperability between them. It lets kernel call into
-   BPF programs and programs call kernel helpers with zero overhead.
-   As all of them were native C code. That is particularly the case
-   for JITed BPF programs that are indistinguishable from
-   native kernel C code.
+---
+A: YES.
+
+BPF design forces addition of major functionality in the form
+of kernel helper functions and kernel objects like BPF maps with
+seamless interoperability between them. It lets kernel call into
+BPF programs and programs call kernel helpers with zero overhead.
+As all of them were native C 

[bpf-next PATCH 5/5] bpf, doc: howto use/run the BPF selftests

[Jesper Dangaard Brouer]

I always forget howto run the BPF selftests. Thus, lets add that info
to the QA document.

Documentation was based on Cilium's documentation:
 http://cilium.readthedocs.io/en/latest/bpf/#verifying-the-setup

Signed-off-by: Jesper Dangaard Brouer 
---
 Documentation/bpf/bpf_devel_QA.rst |   29 +
 1 file changed, 29 insertions(+)

diff --git a/Documentation/bpf/bpf_devel_QA.rst 
b/Documentation/bpf/bpf_devel_QA.rst
index 2254bdeae990..0e7c1d946e83 100644
--- a/Documentation/bpf/bpf_devel_QA.rst
+++ b/Documentation/bpf/bpf_devel_QA.rst
@@ -417,6 +417,33 @@ submitted by the BPF maintainers to the stable maintainers.
 Testing patches
 ===
 
+Q: How to run BPF selftests
+---
+A: After you have booted into the newly compiled kernel, navigate to
+the BPF selftests_ suite in order to test BPF functionality (current
+working directory points to the root of the cloned git tree)::
+
+  $ cd tools/testing/selftests/bpf/
+  $ make
+
+To run the verifier tests::
+
+  $ sudo ./test_verifier
+
+The verifier tests print out all the current checks being
+performed. The summary at the end of running all tests will dump
+information of test successes and failures::
+
+  Summary: 418 PASSED, 0 FAILED
+
+In order to run through all BPF selftests, the following command is
+needed::
+
+  $ sudo make run_tests
+
+See the kernels selftest `Documentation/dev-tools/kselftest.rst`_
+document for further documentation.
+
 Q: Which BPF kernel selftests version should I run my kernel against?
 -
 A: If you run a kernel ``xyz``, then always run the BPF kernel selftests
@@ -607,5 +634,7 @@ when:
 .. _netdev FAQ: ../networking/netdev-FAQ.txt
 .. _samples/bpf/: ../../samples/bpf/
 .. _selftests: ../../tools/testing/selftests/bpf/
+.. _Documentation/dev-tools/kselftest.rst:
+   https://www.kernel.org/doc/html/latest/dev-tools/kselftest.html
 
 Happy BPF hacking!

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[bpf-next PATCH 4/5] bpf, doc: convert bpf_devel_QA.rst to use RST formatting

[Jesper Dangaard Brouer]

Same story as bpf_design_QA.rst RST format conversion.

Again thanks to Quentin Monnet  for
fixes and patches that have been squashed.

Signed-off-by: Jesper Dangaard Brouer 
---
 Documentation/bpf/bpf_devel_QA.rst |  799 +++-
 1 file changed, 420 insertions(+), 379 deletions(-)

diff --git a/Documentation/bpf/bpf_devel_QA.rst 
b/Documentation/bpf/bpf_devel_QA.rst
index da57601153a0..2254bdeae990 100644
--- a/Documentation/bpf/bpf_devel_QA.rst
+++ b/Documentation/bpf/bpf_devel_QA.rst
@@ -1,424 +1,446 @@
+=
+HOWTO interact with BPF subsystem
+=
+
 This document provides information for the BPF subsystem about various
 workflows related to reporting bugs, submitting patches, and queueing
 patches for stable kernels.
 
 For general information about submitting patches, please refer to
-Documentation/process/. This document only describes additional specifics
+`Documentation/process/`_. This document only describes additional specifics
 related to BPF.
 
-Reporting bugs:

+.. contents::
+:local:
+:depth: 2
 
-Q: How do I report bugs for BPF kernel code?
+Reporting bugs
+==
 
+Q: How do I report bugs for BPF kernel code?
+
 A: Since all BPF kernel development as well as bpftool and iproute2 BPF
-   loader development happens through the netdev kernel mailing list,
-   please report any found issues around BPF to the following mailing
-   list:
+loader development happens through the netdev kernel mailing list,
+please report any found issues around BPF to the following mailing
+list:
 
- net...@vger.kernel.org
+ net...@vger.kernel.org
 
-   This may also include issues related to XDP, BPF tracing, etc.
+This may also include issues related to XDP, BPF tracing, etc.
 
-   Given netdev has a high volume of traffic, please also add the BPF
-   maintainers to Cc (from kernel MAINTAINERS file):
+Given netdev has a high volume of traffic, please also add the BPF
+maintainers to Cc (from kernel MAINTAINERS_ file):
 
- Alexei Starovoitov 
- Daniel Borkmann 
+* Alexei Starovoitov 
+* Daniel Borkmann 
 
-   In case a buggy commit has already been identified, make sure to keep
-   the actual commit authors in Cc as well for the report. They can
-   typically be identified through the kernel's git tree.
+In case a buggy commit has already been identified, make sure to keep
+the actual commit authors in Cc as well for the report. They can
+typically be identified through the kernel's git tree.
 
-   Please do *not* report BPF issues to bugzilla.kernel.org since it
-   is a guarantee that the reported issue will be overlooked.
+**Please do NOT report BPF issues to bugzilla.kernel.org since it
+is a guarantee that the reported issue will be overlooked.**
 
-Submitting patches:

+Submitting patches
+==
 
 Q: To which mailing list do I need to submit my BPF patches?
-
+
 A: Please submit your BPF patches to the netdev kernel mailing list:
 
- net...@vger.kernel.org
+ net...@vger.kernel.org
 
-   Historically, BPF came out of networking and has always been maintained
-   by the kernel networking community. Although these days BPF touches
-   many other subsystems as well, the patches are still routed mainly
-   through the networking community.
+Historically, BPF came out of networking and has always been maintained
+by the kernel networking community. Although these days BPF touches
+many other subsystems as well, the patches are still routed mainly
+through the networking community.
 
-   In case your patch has changes in various different subsystems (e.g.
-   tracing, security, etc), make sure to Cc the related kernel mailing
-   lists and maintainers from there as well, so they are able to review
-   the changes and provide their Acked-by's to the patches.
+In case your patch has changes in various different subsystems (e.g.
+tracing, security, etc), make sure to Cc the related kernel mailing
+lists and maintainers from there as well, so they are able to review
+the changes and provide their Acked-by's to the patches.
 
 Q: Where can I find patches currently under discussion for BPF subsystem?
-
+-
 A: All patches that are Cc'ed to netdev are queued for review under netdev
-   patchwork project:
+patchwork project:
 
- http://patchwork.ozlabs.org/project/netdev/list/
+  http://patchwork.ozlabs.org/project/netdev/list/
 
-   Those patches which target BPF, are assigned to a 'bpf' delegate for
-   further processing from BPF maintainers. The current queue with
-   patches under review can be found at:
+Those patches which target BPF, are 

[bpf-next PATCH 2/5] bpf, doc: rename txt files to rst files

[Jesper Dangaard Brouer]

This will cause them to get auto rendered, e.g. when viewing them on GitHub.
Followup patches will correct the content to be RST compliant.

Also adjust README.rst to point to the renamed files.

Signed-off-by: Jesper Dangaard Brouer 
---
 Documentation/bpf/README.rst|4 
 Documentation/bpf/bpf_design_QA.rst |  156 ++
 Documentation/bpf/bpf_design_QA.txt |  156 --
 Documentation/bpf/bpf_devel_QA.rst  |  570 +++
 Documentation/bpf/bpf_devel_QA.txt  |  570 ---
 5 files changed, 728 insertions(+), 728 deletions(-)
 create mode 100644 Documentation/bpf/bpf_design_QA.rst
 delete mode 100644 Documentation/bpf/bpf_design_QA.txt
 create mode 100644 Documentation/bpf/bpf_devel_QA.rst
 delete mode 100644 Documentation/bpf/bpf_devel_QA.txt

diff --git a/Documentation/bpf/README.rst b/Documentation/bpf/README.rst
index 329469c33db8..b9a80c9e9392 100644
--- a/Documentation/bpf/README.rst
+++ b/Documentation/bpf/README.rst
@@ -28,8 +28,8 @@ Two sets of Questions and Answers (Q) are maintained.
 
 
 .. Links:
-.. _bpf_design_QA: bpf_design_QA.txt
-.. _bpf_devel_QA:  bpf_devel_QA.txt
+.. _bpf_design_QA: bpf_design_QA.rst
+.. _bpf_devel_QA:  bpf_devel_QA.rst
 .. _Documentation/networking/filter.txt: ../networking/filter.txt
 .. _man-pages: https://www.kernel.org/doc/man-pages/
 .. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
diff --git a/Documentation/bpf/bpf_design_QA.rst 
b/Documentation/bpf/bpf_design_QA.rst
new file mode 100644
index ..f3e458a0bb2f
--- /dev/null
+++ b/Documentation/bpf/bpf_design_QA.rst
@@ -0,0 +1,156 @@
+BPF extensibility and applicability to networking, tracing, security
+in the linux kernel and several user space implementations of BPF
+virtual machine led to a number of misunderstanding on what BPF actually is.
+This short QA is an attempt to address that and outline a direction
+of where BPF is heading long term.
+
+Q: Is BPF a generic instruction set similar to x64 and arm64?
+A: NO.
+
+Q: Is BPF a generic virtual machine ?
+A: NO.
+
+BPF is generic instruction set _with_ C calling convention.
+
+Q: Why C calling convention was chosen?
+A: Because BPF programs are designed to run in the linux kernel
+   which is written in C, hence BPF defines instruction set compatible
+   with two most used architectures x64 and arm64 (and takes into
+   consideration important quirks of other architectures) and
+   defines calling convention that is compatible with C calling
+   convention of the linux kernel on those architectures.
+
+Q: can multiple return values be supported in the future?
+A: NO. BPF allows only register R0 to be used as return value.
+
+Q: can more than 5 function arguments be supported in the future?
+A: NO. BPF calling convention only allows registers R1-R5 to be used
+   as arguments. BPF is not a standalone instruction set.
+   (unlike x64 ISA that allows msft, cdecl and other conventions)
+
+Q: can BPF programs access instruction pointer or return address?
+A: NO.
+
+Q: can BPF programs access stack pointer ?
+A: NO. Only frame pointer (register R10) is accessible.
+   From compiler point of view it's necessary to have stack pointer.
+   For example LLVM defines register R11 as stack pointer in its
+   BPF backend, but it makes sure that generated code never uses it.
+
+Q: Does C-calling convention diminishes possible use cases?
+A: YES. BPF design forces addition of major functionality in the form
+   of kernel helper functions and kernel objects like BPF maps with
+   seamless interoperability between them. It lets kernel call into
+   BPF programs and programs call kernel helpers with zero overhead.
+   As all of them were native C code. That is particularly the case
+   for JITed BPF programs that are indistinguishable from
+   native kernel C code.
+
+Q: Does it mean that 'innovative' extensions to BPF code are disallowed?
+A: Soft yes. At least for now until BPF core has support for
+   bpf-to-bpf calls, indirect calls, loops, global variables,
+   jump tables, read only sections and all other normal constructs
+   that C code can produce.
+
+Q: Can loops be supported in a safe way?
+A: It's not clear yet. BPF developers are trying to find a way to
+   support bounded loops where the verifier can guarantee that
+   the program terminates in less than 4096 instructions.
+
+Q: How come LD_ABS and LD_IND instruction are present in BPF whereas
+   C code cannot express them and has to use builtin intrinsics?
+A: This is artifact of compatibility with classic BPF. Modern
+   networking code in BPF performs better without them.
+   See 'direct packet access'.
+
+Q: It seems not all BPF instructions are one-to-one to native CPU.
+   For example why BPF_JNE and other compare and jumps are not cpu-like?
+A: This was necessary to avoid introducing flags into ISA which are
+   impossible to make generic and efficient across CPU architectures.
+
+Q: why 

[bpf-next PATCH 1/5] bpf, doc: add basic README.rst file

[Jesper Dangaard Brouer]

A README.rst file in a directory have special meaning for sites like
github, which auto renders the contents.  Plus search engines like
Google also index these README.rst files.

Auto rendering allow us to use links, for (re)directing eBPF users to
other places where docs live.  The end-goal would be to direct users
towards https://www.kernel.org/doc/html/latest but we haven't written
the full docs yet, so we start out small and take this incrementally.

This directory itself contains some useful docs, which can be linked
to from the README.rst file (verified this works for github).

Signed-off-by: Jesper Dangaard Brouer 
---
 Documentation/bpf/README.rst |   36 
 1 file changed, 36 insertions(+)
 create mode 100644 Documentation/bpf/README.rst

diff --git a/Documentation/bpf/README.rst b/Documentation/bpf/README.rst
new file mode 100644
index ..329469c33db8
--- /dev/null
+++ b/Documentation/bpf/README.rst
@@ -0,0 +1,36 @@
+=
+BPF documentation
+=
+
+This directory contains documentation for the BPF (Berkeley Packet
+Filter) facility, with a focus on the extended BPF version (eBPF).
+
+This kernel side documentation is still work in progress.  The main
+textual documentation is (for historical reasons) described in
+`Documentation/networking/filter.txt`_, which describe both classical
+and extended BPF instruction-set.
+The Cilium project also maintains a `BPF and XDP Reference Guide`_
+that goes into great technical depth about the BPF Architecture.
+
+The primary info for the bpf syscall is available in the `man-pages`_
+for `bpf(2)`_.
+
+
+
+Frequently asked questions (FAQ)
+
+
+Two sets of Questions and Answers (Q) are maintained.
+
+* QA for common questions about BPF see: bpf_design_QA_
+
+* QA for developers interacting with BPF subsystem: bpf_devel_QA_
+
+
+.. Links:
+.. _bpf_design_QA: bpf_design_QA.txt
+.. _bpf_devel_QA:  bpf_devel_QA.txt
+.. _Documentation/networking/filter.txt: ../networking/filter.txt
+.. _man-pages: https://www.kernel.org/doc/man-pages/
+.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html
+.. _BPF and XDP Reference Guide: http://cilium.readthedocs.io/en/latest/bpf/

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[bpf-next PATCH 0/5] bpf, doc: convert Documentation/bpf to RST-formatting

[Jesper Dangaard Brouer]

The kernel is moving files under Documentation to use the RST
(reStructuredText) format and Sphinx [1].  This patchset converts the
files under Documentation/bpf/ into RST format.  The Sphinx
integration is left as followup work.

[1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html

This patchset have been uploaded as branch bpf_doc10 on github[2], so
reviewers can see how GitHub renders this.

[2] https://github.com/netoptimizer/linux/tree/bpf_doc10/Documentation/bpf

---

Jesper Dangaard Brouer (5):
  bpf, doc: add basic README.rst file
  bpf, doc: rename txt files to rst files
  bpf, doc: convert bpf_design_QA.rst to use RST formatting
  bpf, doc: convert bpf_devel_QA.rst to use RST formatting
  bpf, doc: howto use/run the BPF selftests


 Documentation/bpf/README.rst|   36 ++
 Documentation/bpf/bpf_design_QA.rst |  221 
 Documentation/bpf/bpf_design_QA.txt |  156 -
 Documentation/bpf/bpf_devel_QA.rst  |  640 +++
 Documentation/bpf/bpf_devel_QA.txt  |  570 ---
 5 files changed, 897 insertions(+), 726 deletions(-)
 create mode 100644 Documentation/bpf/README.rst
 create mode 100644 Documentation/bpf/bpf_design_QA.rst
 delete mode 100644 Documentation/bpf/bpf_design_QA.txt
 create mode 100644 Documentation/bpf/bpf_devel_QA.rst
 delete mode 100644 Documentation/bpf/bpf_devel_QA.txt

--
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks

[Jani Nikula]

On Thu, 10 May 2018, Jonathan Corbet  wrote:
> On Thu, 10 May 2018 09:34:56 -0700
> Matthew Wilcox  wrote:
>
>> I think this is a bit fragile.  Why not just search for ':\n'?  Is
>> there ever a case where we want to write:
>> 
>> /**
>>  * foo is a bar:
>>  * wibble
>>  */
>> and have wibble not be a code-block?
>
> Yeah, we might want to write something like:
>
>  - Leading off a bulleted list
>
>  1) or a numbered list
>
> for example.  That's why I was thinking of looking for explicit markers
> for such lists.
>
> It'll take some playing around with to have a hope of getting right,
> methinks.

We had serious trouble with the old DocBook toolchain because the tool
pipeline was so long, and each step had its own expectations and quirks.
For example, remember the escaping needed for xml in kernel-doc? Or tmpl
xml files being invalid xml because of the docproc directives? One of
the big benefits of the current toolchain is minimizing the amount of
special casing magic required.

The more we add custom syntax sugar in kernel-doc, the more we run the
risk of running into hard problems later on in the Sphinx phase. For
example, our own syntax preventing the use of legitimate rst syntax. And
now we get somewhat reasonable error messages from Sphinx when things go
wrong; we didn't get that when the impedance mismatches caused issues
with the old toolchain. They were hard to debug and mostly nobody even
bothered. We should work to reduce the amount of special processing in
kernel-doc, not the other way round.

The use of "::" is a valid and arguably rather non-invasive rst token
for indicating the following indented block is a literal block. Adding
heuristics (especially ones based on English language magic words) will
lead to bigger problems than it's trying to solve.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH v3 0/6] Documentation/features: Provide and apply 'features-refresh.sh'

[Ingo Molnar]

* Jonathan Corbet  wrote:

> On Mon,  7 May 2018 12:43:37 +0200
> Andrea Parri  wrote:
> 
> > This series provides the script 'features-refresh.sh', which operates on
> > the arch support status files, and it applies this script to refresh the
> > status files in place; previous discussions about this series are at [1].
> 
> Looks good, I've applied the set, thanks.

A belated:

  Reviewed-by: Ingo Molnar 

Thanks guys!

Ingo
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 0/3] docs/vm: transhuge: split userspace bits to admin-guide/mm

[Mike Rapoport]

Hi,

Here are minor updates to transparent hugepage docs. Except from minor
formatting and spelling updates, these patches re-arrange the transhuge.rst
so that userspace interface description will not be interleaved with the
implementation details and it would be possible to split the userspace
related bits to Documentation/admin-guide/mm, which is done by the third
patch.

Mike Rapoport (3):
  docs/vm: transhuge: change sections order
  docs/vm: transhuge: minor updates
  docs/vm: transhuge: split userspace bits to admin-guide/mm/transhuge

 Documentation/admin-guide/kernel-parameters.txt |   3 +-
 Documentation/admin-guide/mm/index.rst  |   1 +
 Documentation/admin-guide/mm/transhuge.rst  | 418 
 Documentation/vm/transhuge.rst  | 395 +-
 4 files changed, 426 insertions(+), 391 deletions(-)
 create mode 100644 Documentation/admin-guide/mm/transhuge.rst

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/3] docs/vm: transhuge: change sections order

[Mike Rapoport]

so that userspace interface and implementation description will be grouped
together

Signed-off-by: Mike Rapoport 
---
 Documentation/vm/transhuge.rst | 82 +-
 1 file changed, 41 insertions(+), 41 deletions(-)

diff --git a/Documentation/vm/transhuge.rst b/Documentation/vm/transhuge.rst
index 2c6867f..56d04cbb 100644
--- a/Documentation/vm/transhuge.rst
+++ b/Documentation/vm/transhuge.rst
@@ -38,31 +38,6 @@ are using hugepages but a significant speedup already 
happens if only
 one of the two is using hugepages just because of the fact the TLB
 miss is going to run faster.
 
-Design
-==
-
-- "graceful fallback": mm components which don't have transparent hugepage
-  knowledge fall back to breaking huge pmd mapping into table of ptes and,
-  if necessary, split a transparent hugepage. Therefore these components
-  can continue working on the regular pages or regular pte mappings.
-
-- if a hugepage allocation fails because of memory fragmentation,
-  regular pages should be gracefully allocated instead and mixed in
-  the same vma without any failure or significant delay and without
-  userland noticing
-
-- if some task quits and more hugepages become available (either
-  immediately in the buddy or through the VM), guest physical memory
-  backed by regular pages should be relocated on hugepages
-  automatically (with khugepaged)
-
-- it doesn't require memory reservation and in turn it uses hugepages
-  whenever possible (the only possible reservation here is kernelcore=
-  to avoid unmovable pages to fragment all the memory but such a tweak
-  is not specific to transparent hugepage support and it's a generic
-  feature that applies to all dynamic high order allocations in the
-  kernel)
-
 Transparent Hugepage Support maximizes the usefulness of free memory
 if compared to the reservation approach of hugetlbfs by allowing all
 unused memory to be used as cache or other movable (or even unmovable
@@ -401,6 +376,47 @@ tracer to record how long was spent in 
__alloc_pages_nodemask and
 using the mm_page_alloc tracepoint to identify which allocations were
 for huge pages.
 
+Optimizing the applications
+===
+
+To be guaranteed that the kernel will map a 2M page immediately in any
+memory region, the mmap region has to be hugepage naturally
+aligned. posix_memalign() can provide that guarantee.
+
+Hugetlbfs
+=
+
+You can use hugetlbfs on a kernel that has transparent hugepage
+support enabled just fine as always. No difference can be noted in
+hugetlbfs other than there will be less overall fragmentation. All
+usual features belonging to hugetlbfs are preserved and
+unaffected. libhugetlbfs will also work fine as usual.
+
+Design principles
+=
+
+- "graceful fallback": mm components which don't have transparent hugepage
+  knowledge fall back to breaking huge pmd mapping into table of ptes and,
+  if necessary, split a transparent hugepage. Therefore these components
+  can continue working on the regular pages or regular pte mappings.
+
+- if a hugepage allocation fails because of memory fragmentation,
+  regular pages should be gracefully allocated instead and mixed in
+  the same vma without any failure or significant delay and without
+  userland noticing
+
+- if some task quits and more hugepages become available (either
+  immediately in the buddy or through the VM), guest physical memory
+  backed by regular pages should be relocated on hugepages
+  automatically (with khugepaged)
+
+- it doesn't require memory reservation and in turn it uses hugepages
+  whenever possible (the only possible reservation here is kernelcore=
+  to avoid unmovable pages to fragment all the memory but such a tweak
+  is not specific to transparent hugepage support and it's a generic
+  feature that applies to all dynamic high order allocations in the
+  kernel)
+
 get_user_pages and follow_page
 ==
 
@@ -432,22 +448,6 @@ hugepages being returned (as it's not only checking the 
pfn of the
 page and pinning it during the copy but it pretends to migrate the
 memory in regular page sizes and with regular pte/pmd mappings).
 
-Optimizing the applications
-===
-
-To be guaranteed that the kernel will map a 2M page immediately in any
-memory region, the mmap region has to be hugepage naturally
-aligned. posix_memalign() can provide that guarantee.
-
-Hugetlbfs
-=
-
-You can use hugetlbfs on a kernel that has transparent hugepage
-support enabled just fine as always. No difference can be noted in
-hugetlbfs other than there will be less overall fragmentation. All
-usual features belonging to hugetlbfs are preserved and
-unaffected. libhugetlbfs will also work fine as usual.
-
 Graceful fallback
 =
 
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org

[PATCH 2/3] docs/vm: transhuge: minor updates

[Mike Rapoport]

Some formatting changes and addition of a sentence introducing khugepaged

Signed-off-by: Mike Rapoport 
---
 Documentation/vm/transhuge.rst | 47 --
 1 file changed, 36 insertions(+), 11 deletions(-)

diff --git a/Documentation/vm/transhuge.rst b/Documentation/vm/transhuge.rst
index 56d04cbb..47c7e47 100644
--- a/Documentation/vm/transhuge.rst
+++ b/Documentation/vm/transhuge.rst
@@ -9,14 +9,19 @@ Objective
 
 Performance critical computing applications dealing with large memory
 working sets are already running on top of libhugetlbfs and in turn
-hugetlbfs. Transparent Hugepage Support is an alternative means of
+hugetlbfs. Transparent HugePage Support (THP) is an alternative mean of
 using huge pages for the backing of virtual memory with huge pages
 that supports the automatic promotion and demotion of page sizes and
 without the shortcomings of hugetlbfs.
 
-Currently it only works for anonymous memory mappings and tmpfs/shmem.
+Currently THP only works for anonymous memory mappings and tmpfs/shmem.
 But in the future it can expand to other filesystems.
 
+.. note::
+   in the examples below we presume that the basic page size is 4K and
+   the huge page size is 2M, although the actual numbers may vary
+   depending on the CPU architecture.
+
 The reason applications are running faster is because of two
 factors. The first factor is almost completely irrelevant and it's not
 of significant interest because it'll also have the downside of
@@ -28,15 +33,27 @@ only matters the first time the memory is accessed for the 
lifetime of
 a memory mapping. The second long lasting and much more important
 factor will affect all subsequent accesses to the memory for the whole
 runtime of the application. The second factor consist of two
-components: 1) the TLB miss will run faster (especially with
-virtualization using nested pagetables but almost always also on bare
-metal without virtualization) and 2) a single TLB entry will be
-mapping a much larger amount of virtual memory in turn reducing the
-number of TLB misses. With virtualization and nested pagetables the
-TLB can be mapped of larger size only if both KVM and the Linux guest
-are using hugepages but a significant speedup already happens if only
-one of the two is using hugepages just because of the fact the TLB
-miss is going to run faster.
+components:
+
+1) the TLB miss will run faster (especially with virtualization using
+   nested pagetables but almost always also on bare metal without
+   virtualization)
+
+2) a single TLB entry will be mapping a much larger amount of virtual
+   memory in turn reducing the number of TLB misses. With
+   virtualization and nested pagetables the TLB can be mapped of
+   larger size only if both KVM and the Linux guest are using
+   hugepages but a significant speedup already happens if only one of
+   the two is using hugepages just because of the fact the TLB miss is
+   going to run faster.
+
+THP can be enabled system wide or restricted to certain tasks or even
+memory ranges inside task's address space. Unless THP is completely
+disabled, there is ``khugepaged`` daemon that scans memory and
+collapses sequences of basic pages into huge pages.
+
+The THP behaviour is controlled via :ref:`sysfs `
+interface and using madivse(2) and prctl(2) system calls.
 
 Transparent Hugepage Support maximizes the usefulness of free memory
 if compared to the reservation approach of hugetlbfs by allowing all
@@ -69,9 +86,14 @@ Applications that gets a lot of benefit from hugepages and 
that don't
 risk to lose memory by using hugepages, should use
 madvise(MADV_HUGEPAGE) on their critical mmapped regions.
 
+.. _thp_sysfs:
+
 sysfs
 =
 
+Global THP controls
+---
+
 Transparent Hugepage Support for anonymous memory can be entirely disabled
 (mostly for debugging purposes) or only enabled inside MADV_HUGEPAGE
 regions (to avoid the risk of consuming more memory resources) or enabled
@@ -142,6 +164,9 @@ khugepaged will be automatically started when
 transparent_hugepage/enabled is set to "always" or "madvise, and it'll
 be automatically shutdown if it's set to "never".
 
+Khugepaged controls
+---
+
 khugepaged runs usually at low frequency so while one may not want to
 invoke defrag algorithms synchronously during the page faults, it
 should be worth invoking defrag at least in khugepaged. However it's
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html