[dpdk-dev,PATCHv6,7/7] doc: Add prog_guide section documenting pmdinfo script

Message ID 1464703068-2924-8-git-send-email-nhorman@tuxdriver.com (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers

Commit Message

Neil Horman May 31, 2016, 1:57 p.m. UTC
Information on pmdinfogen may be useful to 3rd party driver developers.  Include
documentation on what it does

Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
CC: Thomas Monjalon <thomas.monjalon@6wind.com>
CC: Stephen Hemminger <stephen@networkplumber.org>
CC: Panu Matilainen <pmatilai@redhat.com>
---
 doc/guides/prog_guide/dev_kit_build_system.rst | 43 ++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)
  

Comments

Mcnamara, John June 8, 2016, 5:14 p.m. UTC | #1
> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> Sent: Tuesday, May 31, 2016 2:58 PM
> To: dev@dpdk.org
> Cc: Neil Horman <nhorman@tuxdriver.com>; Richardson, Bruce
> <bruce.richardson@intel.com>; Thomas Monjalon <thomas.monjalon@6wind.com>;
> Stephen Hemminger <stephen@networkplumber.org>; Panu Matilainen
> <pmatilai@redhat.com>
> Subject: [dpdk-dev] [PATCHv6 7/7] doc: Add prog_guide section documenting
> pmdinfo script
> 
> Information on pmdinfogen may be useful to 3rd party driver developers.
> Include documentation on what it does

Hi,

There are some trailing whitespace warnings on merge. Some other, minor,
comments below.


> 
> +.. _Internally_Generated_Build_Tools

The target needs a colon at the end to make it valid:

    .. _Internally_Generated_Build_Tools:


> +
> +buildtools/pmdinfogen

This might be better with some distinguishing highlighting, either
``buildtools/pmdinfogen`` or **buildtools/pmdinfogen**.


> +pmdinfogen scans an object (.o) file for various well known symbol

Instances of pmdinfogen would be better as a fixed width ``pmdinfogen``.


> +names.  These well know symbol names are defined by various macros and
> +used to export important information about hardware support and usage
> +for pmd files.  for instance the macro:

s/know/known
s/for/For


> +These strings can then be searched for by external tools to determine
> +the hardware support of a given library or application

Missing full stop.

Apart from these minor changes:


Acked-by: John McNamara <john.mcnamara@intel.com>
  
Neil Horman June 9, 2016, 5:31 p.m. UTC | #2
On Wed, Jun 08, 2016 at 05:14:05PM +0000, Mcnamara, John wrote:
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Neil Horman
> > Sent: Tuesday, May 31, 2016 2:58 PM
> > To: dev@dpdk.org
> > Cc: Neil Horman <nhorman@tuxdriver.com>; Richardson, Bruce
> > <bruce.richardson@intel.com>; Thomas Monjalon <thomas.monjalon@6wind.com>;
> > Stephen Hemminger <stephen@networkplumber.org>; Panu Matilainen
> > <pmatilai@redhat.com>
> > Subject: [dpdk-dev] [PATCHv6 7/7] doc: Add prog_guide section documenting
> > pmdinfo script
> > 
> > Information on pmdinfogen may be useful to 3rd party driver developers.
> > Include documentation on what it does
> 
> Hi,
> 
> There are some trailing whitespace warnings on merge. Some other, minor,
> comments below.
> 
> 
> > 
> > +.. _Internally_Generated_Build_Tools
> 
> The target needs a colon at the end to make it valid:
> 
>     .. _Internally_Generated_Build_Tools:
> 
> 
> > +
> > +buildtools/pmdinfogen
> 
> This might be better with some distinguishing highlighting, either
> ``buildtools/pmdinfogen`` or **buildtools/pmdinfogen**.
> 
> 
> > +pmdinfogen scans an object (.o) file for various well known symbol
> 
> Instances of pmdinfogen would be better as a fixed width ``pmdinfogen``.
> 
> 
> > +names.  These well know symbol names are defined by various macros and
> > +used to export important information about hardware support and usage
> > +for pmd files.  for instance the macro:
> 
> s/know/known
> s/for/For
> 
> 
> > +These strings can then be searched for by external tools to determine
> > +the hardware support of a given library or application
> 
> Missing full stop.
> 
> Apart from these minor changes:
> 
> 
> Acked-by: John McNamara <john.mcnamara@intel.com>
Thanks, I'm incorporating this with the updates that Thomas and I have been
arguing about.
Neil

> 
> 
>
  

Patch

diff --git a/doc/guides/prog_guide/dev_kit_build_system.rst b/doc/guides/prog_guide/dev_kit_build_system.rst
index 3e89eae..e5043dc 100644
--- a/doc/guides/prog_guide/dev_kit_build_system.rst
+++ b/doc/guides/prog_guide/dev_kit_build_system.rst
@@ -70,7 +70,7 @@  Each build directory contains include files, libraries, and applications:
     ...
     ~/DEV/DPDK$ ls i686-native-linuxapp-gcc
 
-    app build hostapp include kmod lib Makefile
+    app build buildtools include kmod lib Makefile
 
 
     ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/app/
@@ -264,7 +264,7 @@  These Makefiles generate a binary application.
 
 *   rte.extapp.mk: External application
 
-*   rte.hostapp.mk: Host application in the development kit framework
+*   rte.buildtools.mk: prerequisite tool to build dpdk 
 
 Library
 ^^^^^^^
@@ -304,6 +304,45 @@  Misc
 
 *   rte.subdir.mk: Build several directories in the development kit framework.
 
+.. _Internally_Generated_Build_Tools
+
+Internally Generated Build Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+buildtools/pmdinfogen
+
+
+pmdinfogen scans an object (.o) file for various well known symbol names.  These
+well know symbol names are defined by various macros and used to export
+important information about hardware support and usage for pmd files.  for
+instance the macro:
+
+.. code-block:: c 
+
+    PMD_REGISTER_DRIVER(drv, name)
+
+
+Creates the following symbol:
+
+.. code-block:: c 
+
+   static char this_pmd_name0[] __attribute__((used)) = "<name>";
+
+
+Which pmdinfogen scans for.  Using this information other relevant bits of data
+can be exported from the object file and used to produce a hardware support
+description, that pmdinfogen then encodes into a json formatted string in the
+following format:
+
+.. code-block:: C
+
+   static char <name_pmd_string>="PMD_INFO_STRING=\"{'name' : '<name>', ...}\"";
+
+
+These strings can then be searched for by external tools to determine the
+hardware support of a given library or application
+
+
 .. _Useful_Variables_Provided_by_the_Build_System:
 
 Useful Variables Provided by the Build System