| Message ID | 1455013157-5191-4-git-send-email-christophe.milard@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
I agree spaces make more sense in diagrams since that makes them independent. Tabs are really a legacy of dial-up modems and tiny hard drives. We've discussed modifying checkpatch to only apply to source code files (.c, .h, etc.) The main thing you want in an .adoc file is a spell check but even there they tend to trip up over acronyms. On Tue, Feb 9, 2016 at 4:19 AM, Christophe Milard < christophe.milard@linaro.org> wrote: > updates of the documentation to reflect the new structure allowing new > interface addition. > > Signed-off-by: Christophe Milard <christophe.milard@linaro.org> > --- > doc/implementers-guide/implementers-guide.adoc | 72 > +++++++++++++++----------- > doc/users-guide/users-guide.adoc | 13 +++-- > 2 files changed, 51 insertions(+), 34 deletions(-) > > diff --git a/doc/implementers-guide/implementers-guide.adoc > b/doc/implementers-guide/implementers-guide.adoc > index d68354d..d855148 100644 > --- a/doc/implementers-guide/implementers-guide.adoc > +++ b/doc/implementers-guide/implementers-guide.adoc > @@ -18,44 +18,58 @@ The implementers view of the include source tree > allows the common API > definitions and documentation to be reused by all the platforms defined > in the > tree, but leave the actual definitions to be defined by the specific > platform. > > -.Implementers include structure > +.Implementers include structure (in repository) > ---- > ./ > ├── include/ > │ ├── odp/ > -│ │ └── api/ <1> > -│ │ └── The Public API and the documentation. > +│ │ └── api/ > +│ │ └── spec/ > +│ │ └── The Public API specification and its documentation. > <1> > │ │ > -│ └── odp.h <4> This file should be the only file included by the > application. > +│ └── odp_api.h This file should be the only file included by the any > ODP > +│ application. <4> > │ > -├── platform/ > -│ ├── <implementation name>/ > -│ │ ├── include/ > -│ │ │ ├── odp/ <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. > -│ │ │ │ > -│ │ │ └── Internal header files seen only by the implementation. > +└── 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. > ---- > - > -<1> The doxygen description of the API definition is held in the public > api file > -'include/odp/api'. > -<2> The public file is included by a counterpart in > -'platform/<implementation name>/include/odp'. > -The include of the public API is AFTER the platform specific definitions > to > -allow the platform to provide definitions that match the underlying > hardware. > -<3> The implementation code includes 'platform/<implementation > name>/include/plat' > -and this then provides the source files with a complete definition the > ODP API > -to be implemented. > -<4> Applications in turn include the include/odp.h file which includes the > -'platform/<implementation name>/include/plat' files to provide a complete > +<1> The specification, defining the ODP application programming interface > (API) > +is held in 'include/odp/api/spec/'. The ODP API is defined by a set of > '.h' > +files including doxygen documentation. > +<2> Each public specification file is included by a counterpart in > +'platform/<implementation name>/include/odp/api'. > +The include of the specification API is AFTER the platform specific > definitions > +to allow the platform to provide definitions that match the underlying > hardware. > +<3> The implementation code may include files from > +'platform/<implementation name>/include/odp/api/plat' > +<4> Applications in turn include the include/odp_api.h file which > includes the > +'platform/<implementation name>/include/odp/api' files to provide a > complete > definition of the API. > > +After ODP installation (make install), the structure becomes as follows: > + > +.Installed ODP structure > +---- > +./ > +└── include/ > + ├── odp/ > + │ └── api/ API In-line for this platform. > + │ ├── plat/ API Platform specific types. > + │ └── spec/ The public API specification. > + └── odp_api.h > +---- > + > == The validation Suite == > > ODP provides a comprehensive set of API validation tests that are > intended to be > diff --git a/doc/users-guide/users-guide.adoc > b/doc/users-guide/users-guide.adoc > index 5668a0b..1591505 100644 > --- a/doc/users-guide/users-guide.adoc > +++ b/doc/users-guide/users-guide.adoc > @@ -462,8 +462,8 @@ _synchronization_ mechanisms. > ODP provides APIs to assist in each of these areas. > > === The include structure > -Applications only include the 'include/odp.h' file, which includes the > -'platform/<implementation name>/include/odp' files to provide a complete > +Applications only include the 'include/odp_api.h' file, which includes the > +'platform/<implementation name>/include/odp/api' files to provide a > complete > definition of the API on that platform. The doxygen documentation defining > the behavior of the ODP API is all contained in the public API files, and > the > actual definitions for an implementation will be found in the per platform > @@ -477,9 +477,12 @@ visible to the application. > ├── include/ > │ ├── odp/ > │ │ └── api/ > -│ │ └── The Public API and the documentation. > -│ │ > -│ └── odp.h This file should be the only file included by the > application. > +│ │ └── spec/ > +│ │ └── The Public API and the documentation. > +│ │ > +│ │ > +│ ├── odp_api.h This file should be the only file included by the > +│ │ application. > ---- > > === Initialization > -- > 2.1.4 > >
If you want to make custom checkers then we need coverage for all the file types currently covered in linux-generic. Checkpatch is a tool for a human to interpret Debian 1 (0.20%) 12 (0.01%) 12 ac 1 (0.20%) 412 (0.42%) 412 adoc 5 (0.98%) 1603 (1.64%) 320 am 50 (9.84%) 984 (1.01%) 19 c 131 (25.79%) 42357 (43.29%) 323 cfg 1 (0.20%) 49 (0.05%) 49 conf 1 (0.20%) 9 (0.01%) 9 cpp 1 (0.20%) 12 (0.01%) 12 css 1 (0.20%) 134 (0.14%) 134 dirs 5 (0.98%) 7 (0.01%) 1 dox 4 (0.79%) 345 (0.35%) 86 h 188 (37.01%) 20525 (20.98%) 109 in 2 (0.39%) 22 (0.02%) 11 inc 6 (1.18%) 118 (0.12%) 19 install 5 (0.98%) 11 (0.01%) 2 m4 8 (1.57%) 1170 (1.20%) 146 msc 1 (0.20%) 45 (0.05%) 45 pl 1 (0.20%) 5584 (5.71%) 5584 sh 3 (0.59%) 62 (0.06%) 20 spec 1 (0.20%) 78 (0.08%) 78 svg 11 (2.17%) 3193 (3.26%) 290 txt 1 (0.20%) 1043 (1.07%) 1043 xml 1 (0.20%) 193 (0.20%) 193 On 9 February 2016 at 07:40, Bill Fischofer <bill.fischofer@linaro.org> wrote: > I agree spaces make more sense in diagrams since that makes them > independent. Tabs are really a legacy of dial-up modems and tiny hard > drives. We've discussed modifying checkpatch to only apply to source code > files (.c, .h, etc.) The main thing you want in an .adoc file is a spell > check but even there they tend to trip up over acronyms. > > On Tue, Feb 9, 2016 at 4:19 AM, Christophe Milard < > christophe.milard@linaro.org> wrote: > >> updates of the documentation to reflect the new structure allowing new >> interface addition. >> >> Signed-off-by: Christophe Milard <christophe.milard@linaro.org> >> --- >> doc/implementers-guide/implementers-guide.adoc | 72 >> +++++++++++++++----------- >> doc/users-guide/users-guide.adoc | 13 +++-- >> 2 files changed, 51 insertions(+), 34 deletions(-) >> >> diff --git a/doc/implementers-guide/implementers-guide.adoc >> b/doc/implementers-guide/implementers-guide.adoc >> index d68354d..d855148 100644 >> --- a/doc/implementers-guide/implementers-guide.adoc >> +++ b/doc/implementers-guide/implementers-guide.adoc >> @@ -18,44 +18,58 @@ The implementers view of the include source tree >> allows the common API >> definitions and documentation to be reused by all the platforms defined >> in the >> tree, but leave the actual definitions to be defined by the specific >> platform. >> >> -.Implementers include structure >> +.Implementers include structure (in repository) >> ---- >> ./ >> ├── include/ >> │ ├── odp/ >> -│ │ └── api/ <1> >> -│ │ └── The Public API and the documentation. >> +│ │ └── api/ >> +│ │ └── spec/ >> +│ │ └── The Public API specification and its documentation. >> <1> >> │ │ >> -│ └── odp.h <4> This file should be the only file included by the >> application. >> +│ └── odp_api.h This file should be the only file included by the any >> ODP >> +│ application. <4> >> │ >> -├── platform/ >> -│ ├── <implementation name>/ >> -│ │ ├── include/ >> -│ │ │ ├── odp/ <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. >> -│ │ │ │ >> -│ │ │ └── Internal header files seen only by the implementation. >> +└── 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. >> ---- >> - >> -<1> The doxygen description of the API definition is held in the public >> api file >> -'include/odp/api'. >> -<2> The public file is included by a counterpart in >> -'platform/<implementation name>/include/odp'. >> -The include of the public API is AFTER the platform specific definitions >> to >> -allow the platform to provide definitions that match the underlying >> hardware. >> -<3> The implementation code includes 'platform/<implementation >> name>/include/plat' >> -and this then provides the source files with a complete definition the >> ODP API >> -to be implemented. >> -<4> Applications in turn include the include/odp.h file which includes >> the >> -'platform/<implementation name>/include/plat' files to provide a complete >> +<1> The specification, defining the ODP application programming >> interface (API) >> +is held in 'include/odp/api/spec/'. The ODP API is defined by a set of >> '.h' >> +files including doxygen documentation. >> +<2> Each public specification file is included by a counterpart in >> +'platform/<implementation name>/include/odp/api'. >> +The include of the specification API is AFTER the platform specific >> definitions >> +to allow the platform to provide definitions that match the underlying >> hardware. >> +<3> The implementation code may include files from >> +'platform/<implementation name>/include/odp/api/plat' >> +<4> Applications in turn include the include/odp_api.h file which >> includes the >> +'platform/<implementation name>/include/odp/api' files to provide a >> complete >> definition of the API. >> >> +After ODP installation (make install), the structure becomes as follows: >> + >> +.Installed ODP structure >> +---- >> +./ >> +└── include/ >> + ├── odp/ >> + │ └── api/ API In-line for this platform. >> + │ ├── plat/ API Platform specific types. >> + │ └── spec/ The public API specification. >> + └── odp_api.h >> +---- >> + >> == The validation Suite == >> >> ODP provides a comprehensive set of API validation tests that are >> intended to be >> diff --git a/doc/users-guide/users-guide.adoc >> b/doc/users-guide/users-guide.adoc >> index 5668a0b..1591505 100644 >> --- a/doc/users-guide/users-guide.adoc >> +++ b/doc/users-guide/users-guide.adoc >> @@ -462,8 +462,8 @@ _synchronization_ mechanisms. >> ODP provides APIs to assist in each of these areas. >> >> === The include structure >> -Applications only include the 'include/odp.h' file, which includes the >> -'platform/<implementation name>/include/odp' files to provide a complete >> +Applications only include the 'include/odp_api.h' file, which includes >> the >> +'platform/<implementation name>/include/odp/api' files to provide a >> complete >> definition of the API on that platform. The doxygen documentation >> defining >> the behavior of the ODP API is all contained in the public API files, >> and the >> actual definitions for an implementation will be found in the per >> platform >> @@ -477,9 +477,12 @@ visible to the application. >> ├── include/ >> │ ├── odp/ >> │ │ └── api/ >> -│ │ └── The Public API and the documentation. >> -│ │ >> -│ └── odp.h This file should be the only file included by the >> application. >> +│ │ └── spec/ >> +│ │ └── The Public API and the documentation. >> +│ │ >> +│ │ >> +│ ├── odp_api.h This file should be the only file included by the >> +│ │ application. >> ---- >> >> === Initialization >> -- >> 2.1.4 >> >> > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs "Work should be fun and collborative, the rest follows"
On 9 February 2016 at 13:40, Bill Fischofer <bill.fischofer@linaro.org> wrote: > I agree spaces make more sense in diagrams since that makes them > independent. Tabs are really a legacy of dial-up modems and tiny hard > drives. We've discussed modifying checkpatch to only apply to source code > files (.c, .h, etc.) The main thing you want in an .adoc file is a spell > check but even there they tend to trip up over acronyms. why modify checkpatch? if there isn't an option in .checkpatch.conf we shouldn't modify checkpatch itself. that means extra burden on us. I think that the reviewer need to actually look at the text and files and not blindly run a script on it. Cheers, Anders > > On Tue, Feb 9, 2016 at 4:19 AM, Christophe Milard > <christophe.milard@linaro.org> wrote: >> >> updates of the documentation to reflect the new structure allowing new >> interface addition. >> >> Signed-off-by: Christophe Milard <christophe.milard@linaro.org> >> --- >> doc/implementers-guide/implementers-guide.adoc | 72 >> +++++++++++++++----------- >> doc/users-guide/users-guide.adoc | 13 +++-- >> 2 files changed, 51 insertions(+), 34 deletions(-) >> >> diff --git a/doc/implementers-guide/implementers-guide.adoc >> b/doc/implementers-guide/implementers-guide.adoc >> index d68354d..d855148 100644 >> --- a/doc/implementers-guide/implementers-guide.adoc >> +++ b/doc/implementers-guide/implementers-guide.adoc >> @@ -18,44 +18,58 @@ The implementers view of the include source tree >> allows the common API >> definitions and documentation to be reused by all the platforms defined >> in the >> tree, but leave the actual definitions to be defined by the specific >> platform. >> >> -.Implementers include structure >> +.Implementers include structure (in repository) >> ---- >> ./ >> ├── include/ >> │ ├── odp/ >> -│ │ └── api/ <1> >> -│ │ └── The Public API and the documentation. >> +│ │ └── api/ >> +│ │ └── spec/ >> +│ │ └── The Public API specification and its documentation. >> <1> >> │ │ >> -│ └── odp.h <4> This file should be the only file included by the >> application. >> +│ └── odp_api.h This file should be the only file included by the any >> ODP >> +│ application. <4> >> │ >> -├── platform/ >> -│ ├── <implementation name>/ >> -│ │ ├── include/ >> -│ │ │ ├── odp/ <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. >> -│ │ │ │ >> -│ │ │ └── Internal header files seen only by the implementation. >> +└── 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. >> ---- >> - >> -<1> The doxygen description of the API definition is held in the public >> api file >> -'include/odp/api'. >> -<2> The public file is included by a counterpart in >> -'platform/<implementation name>/include/odp'. >> -The include of the public API is AFTER the platform specific definitions >> to >> -allow the platform to provide definitions that match the underlying >> hardware. >> -<3> The implementation code includes 'platform/<implementation >> name>/include/plat' >> -and this then provides the source files with a complete definition the >> ODP API >> -to be implemented. >> -<4> Applications in turn include the include/odp.h file which includes >> the >> -'platform/<implementation name>/include/plat' files to provide a complete >> +<1> The specification, defining the ODP application programming interface >> (API) >> +is held in 'include/odp/api/spec/'. The ODP API is defined by a set of >> '.h' >> +files including doxygen documentation. >> +<2> Each public specification file is included by a counterpart in >> +'platform/<implementation name>/include/odp/api'. >> +The include of the specification API is AFTER the platform specific >> definitions >> +to allow the platform to provide definitions that match the underlying >> hardware. >> +<3> The implementation code may include files from >> +'platform/<implementation name>/include/odp/api/plat' >> +<4> Applications in turn include the include/odp_api.h file which >> includes the >> +'platform/<implementation name>/include/odp/api' files to provide a >> complete >> definition of the API. >> >> +After ODP installation (make install), the structure becomes as follows: >> + >> +.Installed ODP structure >> +---- >> +./ >> +└── include/ >> + ├── odp/ >> + │ └── api/ API In-line for this platform. >> + │ ├── plat/ API Platform specific types. >> + │ └── spec/ The public API specification. >> + └── odp_api.h >> +---- >> + >> == The validation Suite == >> >> ODP provides a comprehensive set of API validation tests that are >> intended to be >> diff --git a/doc/users-guide/users-guide.adoc >> b/doc/users-guide/users-guide.adoc >> index 5668a0b..1591505 100644 >> --- a/doc/users-guide/users-guide.adoc >> +++ b/doc/users-guide/users-guide.adoc >> @@ -462,8 +462,8 @@ _synchronization_ mechanisms. >> ODP provides APIs to assist in each of these areas. >> >> === The include structure >> -Applications only include the 'include/odp.h' file, which includes the >> -'platform/<implementation name>/include/odp' files to provide a complete >> +Applications only include the 'include/odp_api.h' file, which includes >> the >> +'platform/<implementation name>/include/odp/api' files to provide a >> complete >> definition of the API on that platform. The doxygen documentation >> defining >> the behavior of the ODP API is all contained in the public API files, and >> the >> actual definitions for an implementation will be found in the per >> platform >> @@ -477,9 +477,12 @@ visible to the application. >> ├── include/ >> │ ├── odp/ >> │ │ └── api/ >> -│ │ └── The Public API and the documentation. >> -│ │ >> -│ └── odp.h This file should be the only file included by the >> application. >> +│ │ └── spec/ >> +│ │ └── The Public API and the documentation. >> +│ │ >> +│ │ >> +│ ├── odp_api.h This file should be the only file included by the >> +│ │ application. >> ---- >> >> === Initialization >> -- >> 2.1.4 >> >
diff --git a/doc/implementers-guide/implementers-guide.adoc b/doc/implementers-guide/implementers-guide.adoc index d68354d..d855148 100644 --- a/doc/implementers-guide/implementers-guide.adoc +++ b/doc/implementers-guide/implementers-guide.adoc @@ -18,44 +18,58 @@ The implementers view of the include source tree allows the common API definitions and documentation to be reused by all the platforms defined in the tree, but leave the actual definitions to be defined by the specific platform. -.Implementers include structure +.Implementers include structure (in repository) ---- ./ ├── include/ │ ├── odp/ -│ │ └── api/ <1> -│ │ └── The Public API and the documentation. +│ │ └── api/ +│ │ └── spec/ +│ │ └── The Public API specification and its documentation. <1> │ │ -│ └── odp.h <4> This file should be the only file included by the application. +│ └── odp_api.h This file should be the only file included by the any ODP +│ application. <4> │ -├── platform/ -│ ├── <implementation name>/ -│ │ ├── include/ -│ │ │ ├── odp/ <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. -│ │ │ │ -│ │ │ └── Internal header files seen only by the implementation. +└── 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. ---- - -<1> The doxygen description of the API definition is held in the public api file -'include/odp/api'. -<2> The public file is included by a counterpart in -'platform/<implementation name>/include/odp'. -The include of the public API is AFTER the platform specific definitions to -allow the platform to provide definitions that match the underlying hardware. -<3> The implementation code includes 'platform/<implementation name>/include/plat' -and this then provides the source files with a complete definition the ODP API -to be implemented. -<4> Applications in turn include the include/odp.h file which includes the -'platform/<implementation name>/include/plat' files to provide a complete +<1> The specification, defining the ODP application programming interface (API) +is held in 'include/odp/api/spec/'. The ODP API is defined by a set of '.h' +files including doxygen documentation. +<2> Each public specification file is included by a counterpart in +'platform/<implementation name>/include/odp/api'. +The include of the specification API is AFTER the platform specific definitions +to allow the platform to provide definitions that match the underlying hardware. +<3> The implementation code may include files from +'platform/<implementation name>/include/odp/api/plat' +<4> Applications in turn include the include/odp_api.h file which includes the +'platform/<implementation name>/include/odp/api' files to provide a complete definition of the API. +After ODP installation (make install), the structure becomes as follows: + +.Installed ODP structure +---- +./ +└── include/ + ├── odp/ + │ └── api/ API In-line for this platform. + │ ├── plat/ API Platform specific types. + │ └── spec/ The public API specification. + └── odp_api.h +---- + == The validation Suite == ODP provides a comprehensive set of API validation tests that are intended to be diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 5668a0b..1591505 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -462,8 +462,8 @@ _synchronization_ mechanisms. ODP provides APIs to assist in each of these areas. === The include structure -Applications only include the 'include/odp.h' file, which includes the -'platform/<implementation name>/include/odp' files to provide a complete +Applications only include the 'include/odp_api.h' file, which includes the +'platform/<implementation name>/include/odp/api' files to provide a complete definition of the API on that platform. The doxygen documentation defining the behavior of the ODP API is all contained in the public API files, and the actual definitions for an implementation will be found in the per platform @@ -477,9 +477,12 @@ visible to the application. ├── include/ │ ├── odp/ │ │ └── api/ -│ │ └── The Public API and the documentation. -│ │ -│ └── odp.h This file should be the only file included by the application. +│ │ └── spec/ +│ │ └── The Public API and the documentation. +│ │ +│ │ +│ ├── odp_api.h This file should be the only file included by the +│ │ application. ---- === Initialization
updates of the documentation to reflect the new structure allowing new interface addition. Signed-off-by: Christophe Milard <christophe.milard@linaro.org> --- doc/implementers-guide/implementers-guide.adoc | 72 +++++++++++++++----------- doc/users-guide/users-guide.adoc | 13 +++-- 2 files changed, 51 insertions(+), 34 deletions(-)