On 5 August 2016 at 11:53, Maxim Uvarov <[email protected]> wrote:
> Hello Christophe,
>
> I'm still not sure if that is good path for documentation. Mixing c code
> and doxygen might be not good.
>
> $(top_srcdir)/platform/${with_platform}/include/odp/api/*.dox
>
> Why not to put it under ./doc ?
>
It cant just be under the top level, but /git/odp/doc/platform-api-guide
- I could buy into that for now.
However remember that in the future there maybe be multiple platforms in a
repo each with different platform specifics so then we will need to
replicate the platform include structure for the docs if they are not just
in the include structure.
>
> Also it looks like we need ./doc/linux-generic/ for everything
> linux-generic specific. So that other platforms
> can pull from us with out breaking their paths.
We dont know if they will reuse linux generic in anyway at all so I dont
think we should add that, or I missed your intent.
>
>
> Maxim.
>
>
>
> On 08/05/16 18:27, Mike Holmes wrote:
>
>> From: Christophe Milard <[email protected]>
>>
>> Signed-off-by: Christophe Milard <[email protected]>
>> Signed-off-by: Mike Holmes <[email protected]>
>> ---
>> v2
>> Added the new file to the distribution in a generic way (maxim)
>>
>>
>> Do we want to put additional documentation in the DOC dir or in with the
>> platform
>> specific header files as Christophe has done initially in this patch ?
>>
>> I see pros to both.
>> In the include dir is where a coder who does not look at docs will find
>> it,
>> however generally we put dox files in the DOC dir
>>
>> I am leaning towards case one as the most helpful to a common case where
>> docs
>> are not consulted.
>>
>>
>> doc/platform-api-guide/Makefile.am | 7 +++-
>> .../include/odp/api/platform_specific.dox | 46
>> ++++++++++++++++++++++
>> 2 files changed, 52 insertions(+), 1 deletion(-)
>> create mode 100644 platform/linux-generic/include
>> /odp/api/platform_specific.dox
>>
>> diff --git a/doc/platform-api-guide/Makefile.am
>> b/doc/platform-api-guide/Makefile.am
>> index a04c254..a3c7f14 100644
>> --- a/doc/platform-api-guide/Makefile.am
>> +++ b/doc/platform-api-guide/Makefile.am
>> @@ -1,5 +1,10 @@
>> +#If additional documentation is added in the platform include directory
>> but it is
>> +#not in a .h file, it must be included here as an extra part of the
>> distribution
>> +
>> EXTRA_DIST = \
>> - Doxyfile
>> + Doxyfile \
>> + $(top_srcdir)/platform/${with_platform}/include/odp/api/*.do
>> x
>> +
>> clean-local:
>> rm -rf output
>> diff --git a/platform/linux-generic/include/odp/api/platform_specific.dox
>> b/platform/linux-generic/include/odp/api/platform_specific.dox
>> new file mode 100644
>> index 0000000..e116ec6
>> --- /dev/null
>> +++ b/platform/linux-generic/include/odp/api/platform_specific.dox
>> @@ -0,0 +1,46 @@
>> +/* Copyright (c) 2016, Linaro Limited
>> + * All rights reserved
>> + *
>> + * SPDX-License-Identifier: BSD-3-Clause
>> + */
>> +
>> +/**
>> +* @file platform_specific.dox
>> +* extra linux-generic documentation
>> +*/
>> +
>> +/** @addtogroup odp_thread
>> + * @par ODP thread
>> + * In this ODP implementation an odp thread is either:
>> + * - a linux process descendant (or same as) the odp instantiation
>> process.
>> + * - a pthread 'member' of a linux process descendant (or same as) the
>> odp
>> + * instantiation process.
>> + */
>> +
>> +/**
>> + * @fn odp_init_local(odp_instance_t instance, odp_thread_type_t
>> thr_type)
>> + * @note In this ODP implementation odpthreads have to be
>> + * processes descendant of (or same as) the ODP
>> + * instantiation process, or pthreads 'member' of
>> such
>> + * processes.
>> + * @note As ODP instantiation processes cannot be
>> descendants
>> + * of each others, the instance parameter provided
>> + * to odp_init_local() is actually fully defined by
>> these
>> + * requirements: It has to be the value returned by
>> the
>> + * unique call to odp_init_global() made by one
>> single
>> + * acsendant of the current process.
>> + */
>> +
>> +/**
>> + * @fn odp_init_global(odp_instance_t *instance,
>> + * const odp_init_t *params,
>> + * const odp_platform_init_t *platform_params)
>> + * @note This ODP implementation supports mupliple instances of ODP
>> + * (i.e. multiple call to odp_init_global()) with the
>> following
>> + * restrictions:
>> + * @note -Different ODP instances cannot share the same
>> instantiation
>> + * process. In other words, a single process may
>> + * only call odp_init_global() once.
>> + * @note -Different ODP instantiation processes cannot be
>> descendant of
>> + * each other.
>> + */
>>
>
>
--
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"
