On 2016-06-23 12:19, Bill Fischofer wrote: > Clean up whitespace and line length issues with current doc. > > Signed-off-by: Bill Fischofer <[email protected]> > --- > doc/implementers-guide/implementers-guide.adoc | 253 > ++++++++++++------------- > 1 file changed, 121 insertions(+), 132 deletions(-) > > diff --git a/doc/implementers-guide/implementers-guide.adoc > b/doc/implementers-guide/implementers-guide.adoc > index abd49c0..1abd884 100644 > --- a/doc/implementers-guide/implementers-guide.adoc > +++ b/doc/implementers-guide/implementers-guide.adoc > @@ -11,9 +11,8 @@ Abstract > This document is intended to guide a new ODP implementation developer. > Further details about ODP may be found at http://opendataplane.org[ODP > homepage] > > - > :numbered: > -== The include structure == > +== The include structure > > The implementers view of the include source tree allows the common interface > definitions and documentation to be reused by all the platforms defined in > the > @@ -25,7 +24,7 @@ similar structures: > ---- > ./ > ├── include/ > -│ ├── odp/ > +│ ├── odp/ > │ │ ├── api/ > │ │ │ └── spec/ > │ │ │ └── The Public API specification and its documentation. <1> > @@ -33,7 +32,7 @@ similar structures: > │ │ └── drv/ > │ │ └── spec/ > │ │ └── The Public Nic driver interface and its documentation. > <5> > -│ │ > +│ │ > │ │ > │ ├── odp_api.h This file should be the only file included by the any ODP > │ │ application. <4> > @@ -43,29 +42,29 @@ similar structures: > │ > └── platform/ > └── <implementation name>/ > - └── include/ > - ├── Internal header files seen only by the implementation. > - └── odp/ > - ├── api/ <2> > - │ ├── In-line function definitions of the public API for > this > - │ │ platform seen by the application. > - │ │ > - │ └── plat/ <3> > - │ └── Platform specific types, enums etc as seen by the > - │ application but require overriding by the > - │ implementation. > - │ > - ├── drv/ <6> > - │ ├── In-line function definitions of the nic driver > interface > - │ │ for this platform seen by the application. > - │ │ > - │ └── plat/ <7> > - │ └── Platform specific types, enums etc as seen by the > - │ nic driver but require overriding by the > - │ implementation. > - │ > - └── com/ > - └── Things common to both interfaces are placed here. > + └── include/ > + ├── Internal header files seen only by the implementation. > + └── odp/ > + ├── api/ <2> > + │ ├── In-line function definitions of the public API for this > + │ │ platform seen by the application. > + │ │ > + │ └── plat/ <3> > + │ └── Platform specific types, enums etc as seen by the > + │ application but require overriding by the > + │ implementation. > + │ > + ├── drv/ <6> > + │ ├── In-line function definitions of the nic driver interface > + │ │ for this platform seen by the application. > + │ │ > + │ └── plat/ <7> > + │ └── Platform specific types, enums etc as seen by the > + │ nic driver but require overriding by the > + │ implementation. > + │ > + └── com/ > + └── Things common to both interfaces are placed here. >
Should spaces be replaced by tabs in the docs? (I remember beeing told the opposite) Christophe. > ---- > <1> The specification, defining the ODP application programming interface > (API) > @@ -114,16 +113,16 @@ After ODP installation (make install), the structure > becomes as follows: > └── odp_drv.h > ---- > > -== ODP library naming recommendations == > +== ODP library naming recommendations > > -The ODP project supports two implementations ODP-linux and ODP-DPDK. The > name > -of the libraries are libodp-linux and libodp-dpdk respectively. It is > +The ODP project supports two implementations *odp-linux* and *odp-dpdk*. The > +name of the libraries are `libodp-linux` and `libodp-dpdk` respectively. It > is > recommended that other implementations follow the same schema > -(odp-<implementation name>) to make the representation of the ODP > +(*odp-<implementation name>*) to make the representation of the ODP > implementations uniform in a distribution. > Additionally there is an ODP helper library to abstract OS differences. > > -== The validation Suite == > +== The validation Suite > > ODP provides a comprehensive set of API validation tests that are intended > to be > used by implementers during development and by application developers to > verify > @@ -132,7 +131,7 @@ that a particular implementation meets their requirements. > The list of these tests is expected to grow as ODP grows. > > The list of test executables is run by the automake test harness, when > running > -"make check". > +`make check`. > Therefore, as required by this harness, each executable should return 0 on > success (tests passed), 77 on inconclusive, or any other values on failure. > The automake functionality shows a status line (PASSED/FAIL...) for each of > the > @@ -152,56 +151,53 @@ divided in two distinct areas: > * The platform agnostic area, > * A platform dependent area (one per platform). > > -=== Platform agnostic === > +=== Platform agnostic > > This grouping defines tests that are expected to be executable and succeed on > -any platform, though possibly with very different performances, depending on > the > -underlying platform. > -They are written in plain C code, and may only use functions defined in the > -standard libC (C99) library (besides the ODP functions being tested, of > course). > -A free C99 specification can be found at > -http://www.open-std.org/JTC1/sc22/wg14/www/docs/n1256.pdf. > -No other languages (like scripting) are allowed as their usage would make > -assumptions on the platform capability. > - > -This area is located at: 'test/validation/' > - > -The ODP API itself is ordered by module, where each module groups the set of > ODP > -API functions related to the same "topic". > -Examples of modules includes "classification" (API functions dealing with > ingress > -packets classification), time (functions dealing with time, excluding timers > -which have their own module), timer,... > -The complete module list can be seen at: > -http://docs.opendataplane.org/master/linux-generic-doxygen-html/modules.html[ODP > Modules] + > -Within the platform agnostic area, the tests are also grouped by modules, > -matching the ODP API modules: 'test/validation/' mainly contains a list of > -directories matching each module name (as defined by the doxygen "@defgroup" > or > -"@ingroup" statement present in each API ".h" file). > - > -Within each of these directories, a library (called "libtest<module>.la") and > -its associated ".h" file (called "<module>.h") defines all the test functions > +any platform, though possibly with very different performance, depending on > +the underlying platform. They are written in plain C code, and may only use > +functions defined in the standard libC (C99) library (besides the ODP > +functions being tested, of course). A free C99 specification can be found at > +the http://www.open-std.org/JTC1/sc22/wg14/www/docs/n1256.pdf[open-std.org] > +web site. No other languages (like scripting) are allowed as their usage > +would make assumptions on the platform capability. > + > +This area is located at `test/validation/` in the odp git repository. > + > +The ODP API itself is ordered by module, where each module groups the set of > +ODP API functions related to the same "topic". Examples of modules includes > +"classification" (API functions dealing with ingress packets classification), > +time (functions dealing with time, excluding timers which have their own > +module), timer,... The complete module list can be seen at: > +http://docs.opendataplane.org/master/linux-generic-doxygen-html/modules.html[ODP > +Modules] + Within the platform agnostic area, the tests are also grouped by > +modules, matching the ODP API modules: `test/validation/` mainly contains a > +list of directories matching each module name (as defined by the doxygen > +`@defgroup` or `@ingroup` statement present in each API `.h` file). > + > +Within each of these directories, a library (called `libtest<module>.la`) and > +its associated `.h` file (called `<module>.h`) defines all the test functions > for this module as well as few other functions to initialize, terminate, and > -group the tests. > -An executable called "<module>_main*", is also built. It is permissible to > -generate more than one executable to cover the functionality in the test > library > -for the module. > -These executable(s) shall call all the tests for this module. + > -See <<anchor-1, Module test and naming convention>> for more details. > +group the tests. An executable called `<module>_main*`, is also built. It is > +permissible to generate more than one executable to cover the functionality > in > +the test library for the module. These executable(s) shall call all the > tests > +for this module. See <<anchor-1, Module test and naming convention>> for > +more details. > > It is important to be aware that the tests defined for a given module > -(defined in 'test/validation/<module>') are focused to test the ODP functions > +(defined in `test/validation/<module>`) are focused to test the ODP functions > belonging to this module, but are not limited to use this module's ODP > functions > only: many modules needs some interaction with some other module to be > tested. > The obvious illustration of this is for module "init" whose functions are > required by all tests of all other modules (as ODP needs to be initialized to > -test anything else). + > +test anything else). > > -There is a "Makefile.am" located at the top of the platform agnostic area. > Its > +There is a `Makefile.am` located at the top of the platform agnostic area. > Its > role is limited to the construction of the different test libraries and the > -"<module>_main*" executables. No tests are run from this area when "make > check" > +`<module>_main*` executables. No tests are run from this area when `make > check` > is performed. > > -==== CUnit ==== > +==== CUnit > > Within a given test executable CUnit is used to run the different tests. The > usage of CUnit implies the following structure: > @@ -214,65 +210,58 @@ before and after the whole suite is run. > registry run by the test executable. > > Moreover, two extra functions can be used to initialize/terminate the test > -executable (these are not part of CUnit). + > +executable (these are not part of CUnit). > A test executable return success (0) if every test of each suite succeed. > > -More details about > -http://cunit.sourceforge.net/doc/index.html[CUnit users guide] > +More details about CUnit can be found in the > +http://cunit.sourceforge.net/doc/index.html[CUnit User's Guide] > > [[anchor-1]] > -==== Module test and naming convention ==== > - > +==== Module test and naming convention > > * Tests, i.e. C functions which are used in CUnit test suites are named: > - *<Module>_test_+++*+++* + > - where the suffix identifies the test. > + *<Module>_test_+++*+++* where the suffix identifies the test. > > -* Test arrays, i.e. arrays of odp_testinfo_t, listing the test functions > - belonging to a suite, are called: > - *<Module>_suite+++[_*]+++* + > - where the possible suffix can be used if many suites are declared. > +* Test arrays, _i.e.,_ arrays of `odp_testinfo_t`, listing the test functions > + belonging to a suite, are called: *<Module>_suite+++[_*]+++* where the > + possible suffix can be used if many suites are declared. > > * CUnit suite init and termination functions are called: > - *<Module>+++_suite[_*]_init()+++* and *<Module>+++_suite[_*]_term()+++* > respectively. + > - where the possible extra middle pattern can be used if many suites are > - declared. > + *<Module>+++_suite[_*]_init()+++* and *<Module>+++_suite[_*]_term()+++* > + respectively, where the possible extra middle pattern can be used if > + many suites are declared. > > -* Suite arrays, i.e. arrays of odp_suiteinfo_t used in executables > - (CUnit registry) are called: > - *<Module>+++_suites[_*]+++* + > - where the possible suffix identifies the executable using it, if many. > +* Suite arrays, _i.e.,_ arrays of `odp_suiteinfo_t` used in executables > (CUnit > + registry) are called *<Module>+++_suites[_*]+++* where the possible suffix > + identifies the executable using it, if any. > > -* Main executable function(s), are called: > - *<Module>+++_main[_*]+++* + > - where the possible suffix identifies the executable, if many, using it. > +* Main executable function(s), are called <Module>+++_main[_*]+++* where the > + *possible suffix identifies the executable, if any, using it. > > -* Init/term functions for the whole executable are called: > - *<Module>_init* > +* Init/term functions for the whole executable are called *<Module>_init* and > *<Module>_term* > > -All the above symbols are part of the generated libtest<Module>.la libraries. > -The generated main executable(s) (named <module>_+++main[_*]+++, where the > +All the above symbols are part of the generated `libtest<Module>.la` > libraries. > +The generated main executable(s) (named `<module>_+++main[_*]+++`, where the > optional suffix is used to distinguish the executables belonging to the same > -module, if many) simply call(s) the related <Module>_main+++[_*]+++ from the > +module, if many) simply call(s) the related `<Module>_main+++[_*]+++` from > the > library. > > -=== Platform specific === > +=== Platform specific > > -These tests are located under 'platform/<platform>/test'. There is one such > area > -for each platform implementing ODP. > -This location will be referred as <PLATFORM_SPECIFIC> in the rest of this > -document. > +These tests are located under `platform/<platform>/test`. There is one such > +area for each platform implementing ODP. This location will be referred as > +<PLATFORM_SPECIFIC> in the rest of this document. > > -==== The normal case ==== > +==== The normal case > > If the considered platform needs no platform specific tests, this directory > -simply needs to contain a single Makefile.am listing each of the executables > +simply needs to contain a single `Makefile.am` listing each of the > executables > (named <module>_main) built from the platform agnostic area. The executables > are > listed in the automake TEST variable and will therefore be run on "make > check". > > For the linux-generic platform, most tested modules fall into this category: > -currently, the 'platform/linux-generic/test/Makefile.am' looks as follows: > +currently, the `platform/linux-generic/test/Makefile.am` looks as follows: > > [source,am] > ---- > @@ -311,13 +300,13 @@ endif > With the exception for module pktio, all other modules testing just involves > calling the platform agnostic <module>_main executables (in test/validation). > > -==== Using other languages ==== > +==== Using other languages > > The pktio module, above, is actually tested using a bash script. This script > is > -needed to set up the interfaces used by the tests. The pktio_run script > -eventually calls the platform agnostic 'test/validation/pktio/pktio_main' > after > +needed to set up the interfaces used by the tests. The `pktio_run` script > +eventually calls the platform agnostic `test/validation/pktio/pktio_main` > after > setting up the interfaces needed by the tests. > -Notice that the path to the script, 'pktio/pktio_run', is pointing to a file > +Notice that the path to the script, `pktio/pktio_run`, is pointing to a file > within the <PLATFORM_SPECIFIC> tree so is private to this platform. Any > languages supported by the tested platform can be used there, as it will not > impact other platforms. > @@ -325,11 +314,11 @@ The platform "private" executables (such as this > script), of course, must also > return one of the return code expected by the automake test harness > (0 for success, 77 for skipped, other values for errors). > > -==== Defining test wrappers ==== > +==== Defining test wrappers > > The pktio case above is actually using a script as wrapper around the > "standard" > (platform independent) test executable. Wrappers can also be defined by using > -the LOG_COMPILER variable of automake. > +the `LOG_COMPILER` variable of automake. > This is applicable in cases where the same wrapper should be used for more > then > one test, as the test name is passed has parameter to the wrapper. A wrapper > is > just a program expecting one argument: the test name. > @@ -339,8 +328,8 @@ filename suffix. See > > https://www.gnu.org/software/automake/manual/html_node/Parallel-Test-Harness.html[Parallel-Test-Harness] > for more information. > > -To add a wrapper around the executed test, just add the following > LOG_COMPILER > -definition line in the '<PLATFORM_SPECIFIC>/Makefile.am': > +To add a wrapper around the executed test, just add the following > `LOG_COMPILER` > +definition line in the `<PLATFORM_SPECIFIC>/Makefile.am`: > > [source,am] > ---- > @@ -374,23 +363,23 @@ exit $res > Note how the above script stores the return code of the test executable to > return it properly to the automake test harness. > > -==== Defining platform specific tests ==== > +==== Defining platform specific tests > > Sometimes, it may be necessary to call platform specific system calls to > check > -some functionality: For instance, testing odp_cpumask_* could involve > checking > +some functionality: For instance, testing `odp_cpumask_*` could involve > checking > the underlying system CPU mask. On linux, such a test would require using the > CPU_ISSET macro, which is linux specific. Such a test would be written in > -'<PLATFORM_SPECIFIC>/cpumask/...' The contents of this directory would be > very > +`<PLATFORM_SPECIFIC>/cpumask/...` The contents of this directory would be > very > similar to the contents of the platform agnostic side cpu_mask tests > -(including a Makefile.am...), but platform specific test would be written > there. > -'<PLATFORM_SPECIFIC>/Makefile.am' would then trigger the building of the > -platform specific tests (by listing their module name in SUBDIRS and > therefore > -calling the appropriate Makefile.am) and then it would call both the platform > +(including a `Makefile.am`), but platform specific test would be written > there. > +`<PLATFORM_SPECIFIC>/Makefile.am` would then trigger the building of the > +platform specific tests (by listing their module name in `SUBDIRS` and > therefore > +calling the appropriate `Makefile.am`) and then it would call both the > platform > agnostic executable(s) and the platform specific test executable. > > -==== Marking tests as inactive ==== > +==== Marking tests as inactive > > -The general policy is that a full run of the validation suite (a "make > check") > +The general policy is that a full run of the validation suite (a `make > check`) > must pass at all times. However a particular platform may have one or more > test > cases that are known to be unimplemented either during development or > permanently, so to avoid these test cases being reported as failures it's > useful > @@ -401,12 +390,12 @@ as inactive while leaving the remaining tests active. > It's important that the > unwanted tests are still registered with the test framework to allow the fact > that they're not being tested to be recorded. > > -The odp_cunit_update() function is intended for this purpose, it is used to > +The `odp_cunit_update()` function is intended for this purpose, it is used to > modify the properties of previously registered tests, for example to mark > them > as inactive. Inactive tests are registered with the test framework but aren't > executed and will be recorded as inactive in test reports. > > -In 'test/validation/foo/foo.c', define all tests for the 'foo' module: > +In `test/validation/foo/foo.c`, define all tests for the `foo` module: > > [source,c] > ------------------ > @@ -422,8 +411,8 @@ odp_suiteinfo_t foo_suites[] = { > }; > ------------------ > > -In 'platform/<platform>/test/foo/foo_main.c', register all the tests defined > in > -the 'foo' module, then mark a single specific test case as inactive: > +In `platform/<platform>/test/foo/foo_main.c`, register all the tests defined > in > +the `foo` module, then mark a single specific test case as inactive: > > [source,c] > ------------------ > @@ -451,18 +440,18 @@ int foo_main(void) > } > ------------------ > > -So 'foo_test_a' will be executed and 'foo_test_b' is inactive. > +So `foo_test_a` will be executed and `foo_test_b` is inactive. > > It's expected that early in the development cycle of a new implementation the > inactive list will be quite long, but it should shrink over time as more > parts > of the API are implemented. > > -==== conditionnal tests ==== > +==== Conditional Tests > > Some tests may require specific conditions to make sense: for instance, on > pktio, checking that sending a packet larger than the MTU is rejected only > makes > sense if packets can indeed, on that ODP implementation, exceed the MTU. > -A test can be marked conditionnal as follows: > +A test can be marked conditional as follows: > > [source,c] > ------------------ > @@ -480,7 +469,7 @@ odp_suiteinfo_t foo_suites[] = { > ------------------ > > Foo_test_x is the usual test function. Foo_check_x is the test precondition, > -i.e. a function returning an bollean (int). > +i.e. a function returning a Boolean (int). > It is called before the test suite is started. If it returns true, the > test (foo_test_x) is run. If the precondition function (foo_check_x above) > returns false, the test is not relevant (or impossible to perform) and it > will > @@ -489,7 +478,7 @@ be skipped. > ================= > *Note* > > -Conditionnal tests can be marked as inactive, keeping the precondition > +Conditional tests can be marked as inactive, keeping the precondition > function. Both the test and the precondition function will be skipped, > but re-activating the test is then just a matter of changing back the macro > from ODP_TEST_INFO_INACTIVE to ODP_TEST_INFO_CONDITIONAL: > @@ -497,10 +486,10 @@ from ODP_TEST_INFO_INACTIVE to > ODP_TEST_INFO_CONDITIONAL: > [source,c] > ------------------ > ... > - /* active conditionnal test */ > + /* active conditional test */ > ODP_TEST_INFO_CONDITIONAL(foo_test_x, foo_check_x), > > - /* inactive conditionnal test */ > + /* inactive conditional test */ > ODP_TEST_INFO_INACTIVE(foo_test_y, foo_check_y), > ... > ------------------ > -- > 2.5.0 > > _______________________________________________ > lng-odp mailing list > [email protected] > https://lists.linaro.org/mailman/listinfo/lng-odp _______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
