On 8 July 2016 at 21:05, Mike Holmes <[email protected]> wrote: > > > On 7 July 2016 at 10:55, Christophe Milard <[email protected]> > wrote: >> >> Yes! I DID send a mail!!! It is in my mail history! >> >> I re-include it here again: >> >> On 2016-07-05 08:47, Mike Holmes wrote: >> > Add an initial driver API document structure for the existing driver >> > framework. >> > >> here again we have a vocabulary issue: the term "API" is used for >> "interface", >> but actually stands for "Application Programming Interface": >> If we talk about "driver API" we should also talk about "application API" >> (which would stand for Application Application Programing interface" :-( . > > > To me an API is any application interface - south, north anything that > call's something is calling that things API. However I don't mind changing > as you are driving for some specific consistency. > >> >> I would prefer "Add an initial driver interface document..." > > > Will change it > >> >> API is then the name of the north interface and DRV the name of the south >> interface: there is not such thing as a "application API", there is just >> the >> API (north) interface and the DRV (south) interface. >> This is the choice we already have made in the repo (api and drv prefix) >> should eventually be: [<scope>]-<interface_name>-guide, i.e: >> DX_INIT_DOXYGEN($PACKAGE_NAME, >> ${srcdir}/doc/specification-api-guide/Doxyfile, >> ${builddir}/doc/specification-api-guide/output, >> ${srcdir}/doc/helper-guide/Doxyfile, >> ${builddir}/doc/helper-guide/output, >> ${srcdir}/doc/platform-api-guide/Doxyfile, >> ${builddir}/doc/platform-api-guide/output, >> ${srcdir}/doc/specification-drv-guide/Doxyfile, >> ${builddir}/doc/specification-drv-guide/output) >> >> > >> > >> > ########################################################################## >> > # Enable/disable ODP_DEBUG_PRINT >> > diff --git a/doc/Makefile.am b/doc/Makefile.am >> > index d49d84b..59d6a6c 100644 >> > --- a/doc/Makefile.am >> > +++ b/doc/Makefile.am >> > @@ -1,4 +1,8 @@ >> > -SUBDIRS = application-api-guide helper-guide platform-api-guide >> > +SUBDIRS = \ >> > + application-api-guide \ >> > + helper-guide \ >> > + platform-api-guide \ >> > + driver-api-guide >> >> should eventually be: >> specification-api-guide >> helper-guide >> platform-api-guide >> specification-drv-guide > > > Not so sure about that but we can do that in another patch
sure > >> >> >> > >> > if user_guide >> > SUBDIRS += implementers-guide users-guide process-guide >> > diff --git a/doc/driver-api-guide/.gitignore >> > b/doc/driver-api-guide/.gitignore >> > new file mode 100644 >> > index 0000000..53752db >> > --- /dev/null >> > +++ b/doc/driver-api-guide/.gitignore >> > @@ -0,0 +1 @@ >> > +output >> > diff --git a/doc/driver-api-guide/Doxyfile >> > b/doc/driver-api-guide/Doxyfile >> > new file mode 100644 >> > index 0000000..eff3285 >> > --- /dev/null >> > +++ b/doc/driver-api-guide/Doxyfile >> > @@ -0,0 +1,14 @@ >> > +@INCLUDE = $(SRCDIR)/doc/Doxyfile_common >> > + >> > +PROJECT_NAME = "Driver Reference Manual" >> >> Should be "Driver Interface (drv) Reference Manual" > > > Will do > >> >> You can ommit the "(drv)" but this is the doc for the intervace, not a >> driver. >> should be: > > > I left drv in > >> >> AC_CONFIG_FILES([doc/specification-api-guide/Makefile >> doc/helper-guide/Makefile >> doc/implementers-guide/Makefile >> doc/Makefile >> doc/platform-api-guide/Makefile >> doc/process-guide/Makefile >> doc/users-guide/Makefile >> doc/specification-drv-guide/Makefile]) >> >> I am aware that this patch should not touch old names (otherwise it will >> go >> outside what its commit msg says), so part of the naming inconsistency >> will >> remain, but if you agree with the suggested names, maybe you can change >> the >> patch so it goes in the right direction. >> If you don't agree, I think I could cope with any other suggestion as long >> as >> it remain consistent. Remember as well that the interface prefixes in the >> repo >> are "api" and "drv". > > > I dont like doc/specification-drv-guide > > Firstly it does not read well it might be a driver specification but it is > not a specification driver > Secondly a specification and a guide are different, is this both things in > one ? sort of, but what matters is that it is a guide to using this api, it > tells you how the interface works and that allows you to attach driver > code. > > As a new user I would not open the specification to learn how to call the > apis, I would open the driver guide. > > So I could compromise and drop "api" to make it driver-guide ? I will not block this patch, compromise and I will say OK because it goes in the right direction! Christophe > > >> >> >> Thanks for helping the driver iinterface to be :-) >> >> On 7 July 2016 at 15:49, Mike Holmes <[email protected]> wrote: >> > >> > >> > On 6 July 2016 at 21:29, Bill Fischofer <[email protected]> >> > wrote: >> >> >> >> This looks good, but I think it makes more sense for this to be >> >> API-NEXT >> >> and considered part of Tiger Moth since we're not doing anything at all >> >> with >> >> drivers in Monarch and this inclusion could be confusing to readers. >> > >> > >> > I agree, it can be one of the first TigerMoth changes. >> > I think Christophe has comments but I have not seen a mail - Christophe >> > anything to add since this is your domain ? >> > >> >> >> >> >> >> >> >> On Tue, Jul 5, 2016 at 7:47 AM, Mike Holmes <[email protected]> >> >> wrote: >> >>> >> >>> Add an initial driver API document structure for the existing driver >> >>> framework. >> >>> >> >>> Signed-off-by: Mike Holmes <[email protected]> >> >> >> >> >> >> Reviewed-and-tested-by: Bill Fischofer <[email protected]> >> >> >> >>> >> >>> --- >> >>> configure.ac | 4 +++- >> >>> doc/Makefile.am | 6 +++++- >> >>> doc/driver-api-guide/.gitignore | 1 + >> >>> doc/driver-api-guide/Doxyfile | 14 ++++++++++++++ >> >>> doc/driver-api-guide/Makefile.am | 5 +++++ >> >>> doc/driver-api-guide/odp.dox | 20 ++++++++++++++++++++ >> >>> doc/m4/configure.m4 | 3 ++- >> >>> 7 files changed, 50 insertions(+), 3 deletions(-) >> >>> create mode 100644 doc/driver-api-guide/.gitignore >> >>> create mode 100644 doc/driver-api-guide/Doxyfile >> >>> create mode 100644 doc/driver-api-guide/Makefile.am >> >>> create mode 100644 doc/driver-api-guide/odp.dox >> >>> >> >>> diff --git a/configure.ac b/configure.ac >> >>> index c0eb207..d1e410a 100644 >> >>> --- a/configure.ac >> >>> +++ b/configure.ac >> >>> @@ -188,7 +188,9 @@ DX_INIT_DOXYGEN($PACKAGE_NAME, >> >>> ${srcdir}/doc/helper-guide/Doxyfile, >> >>> ${builddir}/doc/helper-guide/output, >> >>> ${srcdir}/doc/platform-api-guide/Doxyfile, >> >>> - ${builddir}/doc/platform-api-guide/output) >> >>> + ${builddir}/doc/platform-api-guide/output, >> >>> + ${srcdir}/doc/driver-api-guide/Doxyfile, >> >>> + ${builddir}/doc/driver-api-guide/output) >> >>> >> >>> >> >>> >> >>> ########################################################################## >> >>> # Enable/disable ODP_DEBUG_PRINT >> >>> diff --git a/doc/Makefile.am b/doc/Makefile.am >> >>> index d49d84b..59d6a6c 100644 >> >>> --- a/doc/Makefile.am >> >>> +++ b/doc/Makefile.am >> >>> @@ -1,4 +1,8 @@ >> >>> -SUBDIRS = application-api-guide helper-guide platform-api-guide >> >>> +SUBDIRS = \ >> >>> + application-api-guide \ >> >>> + helper-guide \ >> >>> + platform-api-guide \ >> >>> + driver-api-guide >> >>> >> >>> if user_guide >> >>> SUBDIRS += implementers-guide users-guide process-guide >> >>> diff --git a/doc/driver-api-guide/.gitignore >> >>> b/doc/driver-api-guide/.gitignore >> >>> new file mode 100644 >> >>> index 0000000..53752db >> >>> --- /dev/null >> >>> +++ b/doc/driver-api-guide/.gitignore >> >>> @@ -0,0 +1 @@ >> >>> +output >> >>> diff --git a/doc/driver-api-guide/Doxyfile >> >>> b/doc/driver-api-guide/Doxyfile >> >>> new file mode 100644 >> >>> index 0000000..eff3285 >> >>> --- /dev/null >> >>> +++ b/doc/driver-api-guide/Doxyfile >> >>> @@ -0,0 +1,14 @@ >> >>> +@INCLUDE = $(SRCDIR)/doc/Doxyfile_common >> >>> + >> >>> +PROJECT_NAME = "Driver Reference Manual" >> >>> +PROJECT_NUMBER = $(VERSION) >> >>> +PROJECT_LOGO = $(SRCDIR)/doc/images/ODP-Logo-HQ.svg >> >>> +INPUT = $(SRCDIR)/doc/driver-api-guide \ >> >>> + $(SRCDIR)/include/odp/drv \ >> >>> + $(SRCDIR)/include/odp_drv.h >> >>> +EXCLUDE_PATTERNS = drv* odp_drv.h >> >>> +EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR) >> >>> +PREDEFINED = __GNUC__ \ >> >>> + "ODP_HANDLE_T(type)=odp_handle_t type" \ >> >>> + odpdrv_bool_t=int >> >>> +WARNINGS = NO >> >>> diff --git a/doc/driver-api-guide/Makefile.am >> >>> b/doc/driver-api-guide/Makefile.am >> >>> new file mode 100644 >> >>> index 0000000..4fc4755 >> >>> --- /dev/null >> >>> +++ b/doc/driver-api-guide/Makefile.am >> >>> @@ -0,0 +1,5 @@ >> >>> +EXTRA_DIST = \ >> >>> + odp.dox >> >>> + >> >>> +clean-local: >> >>> + rm -rf output >> >>> diff --git a/doc/driver-api-guide/odp.dox >> >>> b/doc/driver-api-guide/odp.dox >> >>> new file mode 100644 >> >>> index 0000000..687a79e >> >>> --- /dev/null >> >>> +++ b/doc/driver-api-guide/odp.dox >> >>> @@ -0,0 +1,20 @@ >> >>> +/* Copyright (c) 2016, Linaro Limited >> >>> + * All rights reserved >> >>> + * >> >>> + * SPDX-License-Identifier: BSD-3-Clause >> >>> + */ >> >>> + >> >>> +/** >> >>> + * @mainpage >> >>> + * >> >>> + * @section sec_1 Introduction >> >>> + * >> >>> + * OpenDataPlane (ODP) provides a driver interface >> >>> + >> >>> + * >> >>> + * @section contact Contact Details >> >>> + * - The main web site is http://www.opendataplane.org/ >> >>> + * - The git repo is https://git.linaro.org/lng/odp.git >> >>> + * - Bug tracking is >> >>> https://bugs.linaro.org/buglist.cgi?product=OpenDataPlane >> >>> + * >> >>> + */ >> >>> diff --git a/doc/m4/configure.m4 b/doc/m4/configure.m4 >> >>> index ed9451d..6e02f76 100644 >> >>> --- a/doc/m4/configure.m4 >> >>> +++ b/doc/m4/configure.m4 >> >>> @@ -42,4 +42,5 @@ AC_CONFIG_FILES([doc/application-api-guide/Makefile >> >>> doc/Makefile >> >>> doc/platform-api-guide/Makefile >> >>> doc/process-guide/Makefile >> >>> - doc/users-guide/Makefile]) >> >>> + doc/users-guide/Makefile >> >>> + doc/driver-api-guide/Makefile]) >> >>> -- >> >>> 2.7.4 >> >>> >> >>> _______________________________________________ >> >>> lng-odp mailing list >> >>> [email protected] >> >>> https://lists.linaro.org/mailman/listinfo/lng-odp >> >> >> >> >> > >> > >> > >> > -- >> > Mike Holmes >> > Technical Manager - Linaro Networking Group >> > Linaro.org │ Open source software for ARM SoCs >> > "Work should be fun and collaborative, the rest follows" >> > >> > > > > > > -- > Mike Holmes > Technical Manager - Linaro Networking Group > Linaro.org │ Open source software for ARM SoCs > "Work should be fun and collaborative, the rest follows" > >
