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
>
> >
> > 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 ?
>
> 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 <http://www.linaro.org/> *│ *Open source software for ARM SoCs
"Work should be fun and collaborative, the rest follows"
