| Message ID | 1466677154-15944-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | Accepted |
| Commit | fbe74cce0bbe02430de3439b594bf712e791419a |
| Headers | show |
On 2016-06-23 12:19, Bill Fischofer wrote: > Clean up whitespace and line length issues with current doc. > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > 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 > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp
On 23 June 2016 at 06:19, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Clean up whitespace and line length issues with current doc. > Re Christophs point, docs dont have quite the same rules, but in this case the result is better than it was IMHO I think the cleanups on the whole are good, they go beyond white space however, they also fix asciidoc formatting etc so the description could have been clearer. > > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > Series: Reviewed-by: Mike Holmes <mike.holmes@linaro.org> > --- > 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. > ---- > <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 > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs "Work should be fun and collaborative, the rest follows"
On 07/08/16 16:59, Mike Holmes wrote: > On 23 June 2016 at 06:19, Bill Fischofer <bill.fischofer@linaro.org> wrote: > >> Clean up whitespace and line length issues with current doc. >> > Re Christophs point, docs dont have quite the same rules, but in this case > the result is better than it was IMHO > > I think the cleanups on the whole are good, they go beyond white space > however, they also fix asciidoc formatting etc so the description could > have been clearer. > I prefer to see spaces in things like 'tree' command output or some diagrams. Email client is not very friendly for tabs and might be some other html output formats. Maxim. > >> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> >> > Series: > > Reviewed-by: Mike Holmes <mike.holmes@linaro.org> > > > >> --- >> 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. >> > ---- >> <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 >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> > >
Merged, Maxim. On 07/08/16 16:59, Mike Holmes wrote: > On 23 June 2016 at 06:19, Bill Fischofer <bill.fischofer@linaro.org> wrote: > >> Clean up whitespace and line length issues with current doc. >> > Re Christophs point, docs dont have quite the same rules, but in this case > the result is better than it was IMHO > > I think the cleanups on the whole are good, they go beyond white space > however, they also fix asciidoc formatting etc so the description could > have been clearer. > > > >> Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> >> > Series: > > Reviewed-by: Mike Holmes <mike.holmes@linaro.org> > > > >> --- >> 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. >> > ---- >> <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 >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> > >
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. ---- <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), ... ------------------
Clean up whitespace and line length issues with current doc. Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- doc/implementers-guide/implementers-guide.adoc | 253 ++++++++++++------------- 1 file changed, 121 insertions(+), 132 deletions(-)