These files simply describe the APIs, their parameters, and expected
behaviors. As such they are implementation-independent. The only
implementation-specific things in them are the typedef definitions, which
is what we were discussing moving. The sequence of #includes should be:
Application Implementation Common ODP API
#include odp.h
#include platform/.../odp_xxx.h
(defines typedefs and inlines)
#include
common/odp_xxx.h
(references typedefs.
If typedefs missing
or inlines
conflict, will cause
compile
error, indicating a
problem in
platform
understanding of API)
Does this structure make sense?
On Tue, Nov 4, 2014 at 11:14 AM, Ciprian Barbu <[email protected]>
wrote:
> On Tue, Nov 4, 2014 at 3:45 PM, Bill Fischofer
> <[email protected]> wrote:
> > Please take a look at the RFC patches I circulated for odp_buffer.h,
> > odp_buffer_pool.h, and odp_packet.h. These now serve as both executables
> > and doxygen source so the information is in one place.
>
> Ok, I saw the two patches, but after sending the previous email.
> Whether to keep the doxygen annotation in the API or not is one of the
> aspects, it has its advantages and disadvantages. One of the lows is
> that the API headers that differ between platforms (odp_buffer.h and
> odp_buffer_pool.h are likely to do so) will be hard to compare from
> platform to platform. Also the documentation can diverge between
> platforms without being the case. Could be only formatting, not
> necessarily differences in design (it should not be if a platform is
> supposed to suport API vx.x.x). But anyway it lacks clarity from my
> point of view.
>
> Another aspect that was discussed is how to handle the need to inline
> APIs, Taras has done some work for that and he encountered some
> problems. I spent a couple of hours today too on this, I was
> intrigued, and I sent out a patch. Here is a link to in case it was
> missed:
>
> http://lists.linaro.org/pipermail/lng-odp/2014-November/004478.html
>
> /Ciprian
>
> >
> > The split discussion refers to where the platform-specific typedefs are
> > defined + the question of how inlined implementations of select APIs are
> > expressed.
> >
> > On Tue, Nov 4, 2014 at 7:15 AM, Ciprian Barbu <[email protected]>
> > wrote:
> >>
> >> On Mon, Nov 3, 2014 at 5:47 PM, Taras Kondratiuk
> >> <[email protected]> wrote:
> >> > A need to split out a clean API headers is being discussed again, so
> >> > pulling this thread up to remind what the previous attempt was.
> >> >
> >> > On 07/08/2014 05:55 PM, Mike Holmes wrote:
> >> >> We discussed this on a hangout, here are the results as a way forward
> >> >> on
> >> >> this 1 month old topic.
> >> >>
> >> >>
> >> >> Attendees:
> >> >> Bala
> >> >> Taras
> >> >> Maxim
> >> >> Santosh
> >> >> Marshall
> >> >> Mike
> >> >> Bill
> >> >>
> >> >> Actions required:
> >> >>
> >> >> Step one:
> >> >> Move odp/include to odp/platform/linux-generic/include, update the
> make
> >> >> files to suit.
> >> >>
> >> >> Step two:
> >> >> Pull the doxygen documentation back up to odp/doc/odp_xxx.dox out of
> >> >> the
> >> >> header files.
> >> >>
> >> >> General Rational:
> >> >>
> >> >> 1. Anecdotal evidence from previous projects suggests we will end up
> >> >> with per platform includes anyway
> >>
> >> Is this because of the need to inline and to have per-platform defines
> >> / typedefs ?
> >>
> >> >> 2. We are trying to accommodate splitting out the platform specifics
> >> >> on
> >> >> this thread, that is what has driven this issue so No.1 looks
> >> >> correct
> >> >> 3. Linux-generic is the reference implementation and by default it
> is
> >> >> what is built now so there is no change in observed bechavior.
> This
> >> >> includes the fact that the platform specifics show though, all
> that
> >> >> changes is that is it now clear that they are specific to that
> >> >> platform and no pretense that the default doc is is platform
> >> >> independent.
> >> >> 4. We reduce the directory structure complexity, no need to include
> >> >> odp/include for each platforms make file.
> >> >> 5. Other platforms already include Linux-generic to reuse its code
> so
> >> >> we are not adding any new paths to find the same headers for
> those
> >> >> cases, there is no impact if the Linux-generic is not needed.
> >> >> 6. The API documentation is still common, it can be stored once in
> >> >> odp/doc/odpxxxxx.dox, doxygen will tie this together with the
> >> >> headers found per platform.
> >> >> 7. Platforms are still free to add pages to augment the
> documentation
> >> >> with platform specifics.
> >> >>
> >> >> Negatives:
> >> >>
> >> >> 1. Documentation is no longer all kept right next to the definitions
> >> >> which is one reason to use doxygen in the first place.
> >>
> >> From my point of view, Doxygen is primarily helpful for having a nice
> >> rendered view of the documentation in html/pdf format. Having the
> >> documentation in the same place as the headers (whether it contains
> >> Doxygen tags or not) makes for a more comfortable view for the
> >> programmer who may not be always looking at the browser (those
> >> hardcore Linux guys :) So I think we should have separate dox file.
> >>
> >> >> 2. There is less enforcement of the API across platforms, hopefully
> >> >> mitigated by the ODP-validation test suite.
> >> >>
> >> >>
> >> >>
> >> >> On 3 July 2014 13:14, Mike Holmes <[email protected]
> >> >> <mailto:[email protected]>> wrote:
> >> >>
> >> >> Let me take a look, I will ping you offline to make sure I
> >> >> understand and replicate the issue correctly
> >> >>
> >> >>
> >> >> On 3 July 2014 06:26, Taras Kondratiuk <
> [email protected]
> >> >> <mailto:[email protected]>> wrote:
> >> >>
> >> >> On 06/26/2014 06:24 PM, Taras Kondratiuk wrote:
> >> >>
> >> >> As we have discussed during a call, I've tried to
> implement
> >> >> option #2
> >> >> for several files, but looks like Doxygen is not happy if
> >> >> documented
> >> >> variable can't be found in its input files. I couldn't
> find
> >> >> a Doxygen
> >> >> option that controls this behavior.
> >> >> Mike, do you have some ideas how to workaround it?
> >> >>
> >> >>
> >> >> Mike, do you have some hints?
> >> >>
> >> >>
> >> >>
> >> >>
> >> >> --
> >> >> *Mike Holmes*
> >> >> Linaro Technical Manager / Lead
> >> >> LNG - ODP
> >> >>
> >> >>
> >> >>
> >> >>
> >> >> --
> >> >> *Mike Holmes*
> >> >> Linaro Technical Manager / Lead
> >> >> LNG - ODP
> >> >
> >> >
> >> > _______________________________________________
> >> > lng-odp mailing list
> >> > [email protected]
> >> > http://lists.linaro.org/mailman/listinfo/lng-odp
> >
> >
>
_______________________________________________
lng-odp mailing list
[email protected]
http://lists.linaro.org/mailman/listinfo/lng-odp
