doc: add prog guide section documenting pmdinfo script

[dpdk.git] / doc / guides / prog_guide / dev_kit_build_system.rst

diff --git a/doc/guides/prog_guide/dev_kit_build_system.rst b/doc/guides/prog_guide/dev_kit_build_system.rst
index 23944f4..1dc1388 100644 (file)
--- 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/
@@ -85,7 +85,7 @@ Each build directory contains include files, libraries, and applications:
 
     librte_cmdline.a librte_lpm.a librte_mempool.a librte_ring.a
 
-    librte_eal.a librte_malloc.a librte_pmd_e1000.a librte_timer.a
+    librte_eal.a librte_pmd_e1000.a librte_timer.a
 
 
     ~/DEV/DPDK$ ls i686-native-linuxapp-gcc/include/
@@ -194,7 +194,7 @@ To compile an application, the user must set the RTE_SDK and RTE_TARGET environm
     cd /path/to/my_app
 
 For a new application, the user must create their own Makefile that includes some .mk files, such as
-${RTE_SDK}/mk/DPDK.vars.mk, and ${RTE_SDK}/mk/ DPDK.app.mk.
+${RTE_SDK}/mk/rte.vars.mk, and ${RTE_SDK}/mk/ rte.app.mk.
 This is described in
 :ref:`Building Your Own Application <Building_Your_Own_Application>`.
 
@@ -217,11 +217,11 @@ General Rules For DPDK Makefiles
 
 In the DPDK, Makefiles always follow the same scheme:
 
-#. Include $(RTE_SDK)/mk/DPDK.vars.mk at the beginning.
+#. Include $(RTE_SDK)/mk/rte.vars.mk at the beginning.
 
 #. Define specific variables for RTE build system.
 
-#. Include a specific $(RTE_SDK)/mk/DPDK.XYZ.mk, where XYZ can be app, lib, extapp, extlib, obj, gnuconfigure,
+#. Include a specific $(RTE_SDK)/mk/rte.XYZ.mk, where XYZ can be app, lib, extapp, extlib, obj, gnuconfigure,
    and so on, depending on what kind of object you want to build.
    :ref:`See Makefile Types <Makefile_Types>` below.
 
@@ -231,7 +231,7 @@ In the DPDK, Makefiles always follow the same scheme:
 
    ..  code-block:: make
 
-        include $(RTE_SDK)/mk/DPDK.vars.mk
+        include $(RTE_SDK)/mk/rte.vars.mk
 
         # binary name
         APP = helloworld
@@ -242,7 +242,7 @@ In the DPDK, Makefiles always follow the same scheme:
         CFLAGS += -O3
         CFLAGS += $(WERROR_FLAGS)
 
-        include $(RTE_SDK)/mk/DPDK.extapp.mk
+        include $(RTE_SDK)/mk/rte.extapp.mk
 
 .. _Makefile_Types:
 
@@ -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.hostapp.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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``app/pmdinfogen``
+
+
+``pmdinfogen`` scans an object (.o) file for various well known symbol names.  These
+well known 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
@@ -317,7 +356,7 @@ Useful Variables Provided by the Build System
     When compiling an external application, the variable points to the root of external application sources.
 
 *   RTE_OUTPUT: The path to which output files are written.
-    Typically, it is $(RTE_SRCDIR)/build, but it can be overriden by the O= option in the make command line.
+    Typically, it is $(RTE_SRCDIR)/build, but it can be overridden by the O= option in the make command line.
 
 *   RTE_TARGET: A string identifying the target for which we are building.
     The format is arch-machine-execenv-toolchain.
@@ -343,6 +382,8 @@ Useful Variables Provided by the Build System
     By default, the variable is set to /lib/modules/$(shell uname -r)/build,
     which is correct when the target machine is also the build machine.
 
+*   RTE_DEVEL_BUILD: Stricter options (stop on warning). It defaults to y in a git tree.
+
 Variables that Can be Set/Overridden in a Makefile Only
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -407,12 +448,12 @@ Variables that Can be Set/Overridden by the User in a Makefile or Command Line
 
 *   LDFLAGS_my_app: Specific flags to add when linking my_app.
 
-*   NO_AUTOLIBS: If set, the libraries provided by the framework will not be included in the LDLIBS variable automatically.
-
 *   EXTRA_CFLAGS: The content of this variable is appended after CFLAGS when compiling.
 
 *   EXTRA_LDFLAGS: The content of this variable is appended after LDFLAGS when linking.
 
+*   EXTRA_LDLIBS: The content of this variable is appended after LDLIBS when linking.
+
 *   EXTRA_ASFLAGS: The content of this variable is appended after ASFLAGS when assembling.
 
 *   EXTRA_CPPFLAGS: The content of this variable is appended after CPPFLAGS when using a C preprocessor on assembly files.