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/*.dox
+
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.
+ */
--
2.7.4
