| Message ID | 1437740785-15255-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | New |
| Headers | show |
On Fri, Jul 24, 2015 at 7:26 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > The directory structure is a little unorthodox, explain the structure > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org> > --- > doc/users-guide/dir_structure.dox | 63 > +++++++++++++++++++++++++++++++++++++++ > 1 file changed, 63 insertions(+) > create mode 100644 doc/users-guide/dir_structure.dox > > diff --git a/doc/users-guide/dir_structure.dox > b/doc/users-guide/dir_structure.dox > new file mode 100644 > index 0000000..aa89dec > --- /dev/null > +++ b/doc/users-guide/dir_structure.dox > @@ -0,0 +1,63 @@ > +/* Copyright (c) 2015, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page dir_structure Directory Structure > + > +The ODP API requires that the function definitions, structures and enums > be implementation specific so that they are as efficient as possible, > however this results in a more complex include hierarchy. > + > +@section application_view Application View > +The single header file odp.h (see diagram below) is the only file an > application may include directly if portability is to be maintained for the > application. > +The structure is then not a familiar hierarchical tree of includes > because platform specific files are included before the traditional top > level API definition files. > + > +The single odp.h includes the platform specific files from include/odp > giving the implementer an opportunity to define the public API functions as > inline and static for performance as necessary on a per platform basis. > +The files in include/odp in turn include files from include/odp/plat that > contain structure and enum definitions specific to the platform to ensure > that the structures used by the implementation are also optimal. > +Finally files in include/odp include the traditional pubic api from > include/odp/api to complete the API by adding truly generic definitions and > the documentation. > + > +@verbatim > +./ > +├── include/ > +│ ├── odp/ > +│ │ ├── In-line function definitions of the public API for this > platform > +│ │ │ seen by the application. > +│ │ │ > +│ │ ├── plat/ > +│ │ │ └── Platform specific types, enums etc as seen by the > application > +│ │ │ but require overriding by the implementation > +│ │ │ > +│ │ └── api/ > +│ │ └── The Public API and the documentation. > +│ │ > +│ └── odp.h This file should be the only file included by the > application. > +@endverbatim > + > + > +@section implementers_view Implementation View > +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 still leave the actual definitions to be defined by the > platform. > + > +@verbatim > +./ > +├── include/ > +│ ├── odp/ > +│ │ └── api/ > +│ │ └── The Public API and the documentation. > +│ │ > +│ └── odp.h This file should be the only file included by the > application. > +│ > +├── platform/ > +│ ├── <implementation name>/ > +│ │ ├── include/ > +│ │ │ ├── odp/ > +│ │ │ │ ├── In-line function definitions of the public API > for this platform > +│ │ │ │ │ seen by the application. > +│ │ │ │ │ > +│ │ │ │ └── plat/ > +│ │ │ │ └── Platform specific types, enums etc as seen by > the application > +│ │ │ │ but require overriding by the implementation > +│ │ │ │ > +│ │ │ └── Internal header files seen only by the implementation > +@endverbatim > +*/ > -- > 2.1.4 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp > >
On 07/24/15 15:26, Mike Holmes wrote: > The directory structure is a little unorthodox, explain the structure > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > doc/users-guide/dir_structure.dox | 63 +++++++++++++++++++++++++++++++++++++++ > 1 file changed, 63 insertions(+) > create mode 100644 doc/users-guide/dir_structure.dox > > diff --git a/doc/users-guide/dir_structure.dox b/doc/users-guide/dir_structure.dox > new file mode 100644 > index 0000000..aa89dec > --- /dev/null > +++ b/doc/users-guide/dir_structure.dox > @@ -0,0 +1,63 @@ > +/* Copyright (c) 2015, Linaro Limited > + * All rights reserved > + * > + * SPDX-License-Identifier: BSD-3-Clause > + */ > + > +/** > +@page dir_structure Directory Structure > + > +The ODP API requires that the function definitions, structures and enums be implementation specific so that they are as efficient as possible, however this results in a more complex include hierarchy. > + > +@section application_view Application View > +The single header file odp.h (see diagram below) is the only file an application may include directly if portability is to be maintained for the application. > +The structure is then not a familiar hierarchical tree of includes because platform specific files are included before the traditional top level API definition files. > + > +The single odp.h includes the platform specific files from include/odp giving the implementer an opportunity to define the public API functions as inline and static for performance as necessary on a per platform basis. > +The files in include/odp in turn include files from include/odp/plat that contain structure and enum definitions specific to the platform to ensure that the structures used by the implementation are also optimal. > +Finally files in include/odp include the traditional pubic api from include/odp/api to complete the API by adding truly generic definitions and the documentation. > + > +@verbatim > +./ > +├── include/ > +│ ├── odp/ > +│ │ ├── In-line function definitions of the public API for this platform > +│ │ │ seen by the application. > +│ │ │ > +│ │ ├── plat/ > +│ │ │ └── Platform specific types, enums etc as seen by the application > +│ │ │ but require overriding by the implementation dot is missing here. > +│ │ │ > +│ │ └── api/ > +│ │ └── The Public API and the documentation. > +│ │ > +│ └── odp.h This file should be the only file included by the application. > +@endverbatim > + > + > +@section implementers_view Implementation View > +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 still leave the actual definitions to be defined by the platform. > + > +@verbatim > +./ > +├── include/ > +│ ├── odp/ > +│ │ └── api/ > +│ │ └── The Public API and the documentation. > +│ │ > +│ └── odp.h This file should be the only file included by the application. > +│ > +├── platform/ > +│ ├── <implementation name>/ > +│ │ ├── include/ > +│ │ │ ├── odp/ > +│ │ │ │ ├── In-line function definitions of the public API for this platform > +│ │ │ │ │ seen by the application. > +│ │ │ │ │ > +│ │ │ │ └── plat/ > +│ │ │ │ └── Platform specific types, enums etc as seen by the application > +│ │ │ │ but require overriding by the implementation dot is missing here. Also I think it might be reasonable to add: platform/linux-generic/m4 - platform specific ./configure checks and options. platform/linux-generic/README - platform documentation. Or if you describe only API, then please specify it in file name, like api_dirs_structure.dox and tag @page with api_ prefix as you did in api_guide_lines.dox, and add API for section name. Thanks, Maxim. > +│ │ │ │ > +│ │ │ └── Internal header files seen only by the implementation > +@endverbatim > +*/ > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp
On 27 July 2015 at 05:45, Maxim Uvarov <maxim.uvarov@linaro.org> wrote: > On 07/24/15 15:26, Mike Holmes wrote: > >> The directory structure is a little unorthodox, explain the structure >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> >> --- >> doc/users-guide/dir_structure.dox | 63 >> +++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 63 insertions(+) >> create mode 100644 doc/users-guide/dir_structure.dox >> >> diff --git a/doc/users-guide/dir_structure.dox >> b/doc/users-guide/dir_structure.dox >> new file mode 100644 >> index 0000000..aa89dec >> --- /dev/null >> +++ b/doc/users-guide/dir_structure.dox >> @@ -0,0 +1,63 @@ >> +/* Copyright (c) 2015, Linaro Limited >> + * All rights reserved >> + * >> + * SPDX-License-Identifier: BSD-3-Clause >> + */ >> + >> +/** >> +@page dir_structure Directory Structure >> + >> +The ODP API requires that the function definitions, structures and enums >> be implementation specific so that they are as efficient as possible, >> however this results in a more complex include hierarchy. >> + >> +@section application_view Application View >> +The single header file odp.h (see diagram below) is the only file an >> application may include directly if portability is to be maintained for the >> application. >> +The structure is then not a familiar hierarchical tree of includes >> because platform specific files are included before the traditional top >> level API definition files. >> + >> +The single odp.h includes the platform specific files from include/odp >> giving the implementer an opportunity to define the public API functions as >> inline and static for performance as necessary on a per platform basis. >> +The files in include/odp in turn include files from include/odp/plat >> that contain structure and enum definitions specific to the platform to >> ensure that the structures used by the implementation are also optimal. >> +Finally files in include/odp include the traditional pubic api from >> include/odp/api to complete the API by adding truly generic definitions and >> the documentation. >> + >> +@verbatim >> +./ >> +├── include/ >> +│ ├── odp/ >> +│ │ ├── In-line function definitions of the public API for this >> platform >> +│ │ │ seen by the application. >> +│ │ │ >> +│ │ ├── plat/ >> +│ │ │ └── Platform specific types, enums etc as seen by the >> application >> +│ │ │ but require overriding by the implementation >> > dot is missing here. Thanks, no probelm > > > +│ │ │ >> +│ │ └── api/ >> +│ │ └── The Public API and the documentation. >> +│ │ >> +│ └── odp.h This file should be the only file included by the >> application. >> +@endverbatim >> + >> + >> +@section implementers_view Implementation View >> +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 still leave the actual definitions to be defined by the >> platform. >> + >> +@verbatim >> +./ >> +├── include/ >> +│ ├── odp/ >> +│ │ └── api/ >> +│ │ └── The Public API and the documentation. >> +│ │ >> +│ └── odp.h This file should be the only file included by the >> application. >> +│ >> +├── platform/ >> +│ ├── <implementation name>/ >> +│ │ ├── include/ >> +│ │ │ ├── odp/ >> +│ │ │ │ ├── In-line function definitions of the public API >> for this platform >> +│ │ │ │ │ seen by the application. >> +│ │ │ │ │ >> +│ │ │ │ └── plat/ >> +│ │ │ │ └── Platform specific types, enums etc as seen >> by the application >> +│ │ │ │ but require overriding by the implementation >> > dot is missing here. > Thanks, no problem > > Also I think it might be reasonable to add: > platform/linux-generic/m4 - platform specific ./configure checks and > options. > platform/linux-generic/README - platform documentation. > This note is focused on the include structure since this api_doc focuses on the user rather than the implementer, so I was not planning to describe how everything is structured in one diagram, but I agree we need to expand the implementers guide with all of this stuff. I think we can build that in a new doc/implementers-guide > Or if you describe only API, then please specify it in file name, like > api_dirs_structure.dox and tag @page > with api_ prefix as you did in api_guide_lines.dox, and add API for > section name. > sure, as above will split, and then once we get this established I will add material. > > Thanks, > Maxim. > > +│ │ │ │ >> +│ │ │ └── Internal header files seen only by the implementation >> +@endverbatim >> +*/ >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
diff --git a/doc/users-guide/dir_structure.dox b/doc/users-guide/dir_structure.dox new file mode 100644 index 0000000..aa89dec --- /dev/null +++ b/doc/users-guide/dir_structure.dox @@ -0,0 +1,63 @@ +/* Copyright (c) 2015, Linaro Limited + * All rights reserved + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +/** +@page dir_structure Directory Structure + +The ODP API requires that the function definitions, structures and enums be implementation specific so that they are as efficient as possible, however this results in a more complex include hierarchy. + +@section application_view Application View +The single header file odp.h (see diagram below) is the only file an application may include directly if portability is to be maintained for the application. +The structure is then not a familiar hierarchical tree of includes because platform specific files are included before the traditional top level API definition files. + +The single odp.h includes the platform specific files from include/odp giving the implementer an opportunity to define the public API functions as inline and static for performance as necessary on a per platform basis. +The files in include/odp in turn include files from include/odp/plat that contain structure and enum definitions specific to the platform to ensure that the structures used by the implementation are also optimal. +Finally files in include/odp include the traditional pubic api from include/odp/api to complete the API by adding truly generic definitions and the documentation. + +@verbatim +./ +├── include/ +│ ├── odp/ +│ │ ├── In-line function definitions of the public API for this platform +│ │ │ seen by the application. +│ │ │ +│ │ ├── plat/ +│ │ │ └── Platform specific types, enums etc as seen by the application +│ │ │ but require overriding by the implementation +│ │ │ +│ │ └── api/ +│ │ └── The Public API and the documentation. +│ │ +│ └── odp.h This file should be the only file included by the application. +@endverbatim + + +@section implementers_view Implementation View +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 still leave the actual definitions to be defined by the platform. + +@verbatim +./ +├── include/ +│ ├── odp/ +│ │ └── api/ +│ │ └── The Public API and the documentation. +│ │ +│ └── odp.h This file should be the only file included by the application. +│ +├── platform/ +│ ├── <implementation name>/ +│ │ ├── include/ +│ │ │ ├── odp/ +│ │ │ │ ├── In-line function definitions of the public API for this platform +│ │ │ │ │ seen by the application. +│ │ │ │ │ +│ │ │ │ └── plat/ +│ │ │ │ └── Platform specific types, enums etc as seen by the application +│ │ │ │ but require overriding by the implementation +│ │ │ │ +│ │ │ └── Internal header files seen only by the implementation +@endverbatim +*/
The directory structure is a little unorthodox, explain the structure Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/users-guide/dir_structure.dox | 63 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 doc/users-guide/dir_structure.dox