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 <ciprian.ba...@linaro.org> wrote: > On Tue, Nov 4, 2014 at 3:45 PM, Bill Fischofer > <bill.fischo...@linaro.org> 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 <ciprian.ba...@linaro.org> > > wrote: > >> > >> On Mon, Nov 3, 2014 at 5:47 PM, Taras Kondratiuk > >> <taras.kondrat...@linaro.org> 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 <mike.hol...@linaro.org > >> >> <mailto:mike.hol...@linaro.org>> 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 < > taras.kondrat...@linaro.org > >> >> <mailto:taras.kondrat...@linaro.org>> 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 > >> > lng-odp@lists.linaro.org > >> > http://lists.linaro.org/mailman/listinfo/lng-odp > > > > >
_______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org http://lists.linaro.org/mailman/listinfo/lng-odp