[API-NEXT,PATCHv7,5/5] doc: userguide: add odp_init_global() documentation for unused features

Message ID 20170613125515.24874-5-bill.fischofer@linaro.org
State New
Headers show
Series
  • [API-NEXT,PATCHv7,1/5] api: feature: add odp feature bits
Related show

Commit Message

Bill Fischofer June 13, 2017, 12:55 p.m.
Update User Guide startup section to include current parameters for
odp_init_global() and odp_init_local() as well as optimization hints for
unused features.

Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org>

---
 doc/users-guide/users-guide.adoc | 36 ++++++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

-- 
2.11.0

Patch hide | download patch | download mbox

diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc
index ead8da5e..d78e0777 100755
--- a/doc/users-guide/users-guide.adoc
+++ b/doc/users-guide/users-guide.adoc
@@ -530,20 +530,44 @@  calling the terminate functions should only be done when the application is
 sure it has closed the ingress and subsequently drained all queues, etc.
 
 === Startup
-The first API that must be called by an ODP application is 'odp_init_global()'.
+The first API that must be called by an ODP application is `odp_init_global()`:
+[source,c]
+-----
+int odp_init_global(odp_instance_t *instance,
+		    const odp_init_t *param,
+		    const odp_platform_init_t *platform_param);
+-----
 This takes two pointers. The first, `odp_init_t`, contains ODP initialization
 data that is platform independent and portable, while the second,
 `odp_platform_init_t`, is passed unparsed to the implementation
 to be used for platform specific data that is not yet, or may never be
-suitable for the ODP API.
+suitable for the ODP API. Each of these parameters is optional and may be
+specified as NULL to accept the implementation-defined default initialization
+values.
 
-Calling odp_init_global() establishes the ODP API framework and MUST be
+Calling `odp_init_global()` establishes the ODP API framework and MUST be
 called before any other ODP API may be called. Note that it is only called
-once per application. Following global initialization, each thread in turn
+once per application. A successful call to `odp_init_global()` returns rc = 0
+and sets the `instance` variable supplied as input to the call to an handle
+representing this unique ODP instance.
+
+The `odp_init_t` parameter is used to specify various customizations to the
+ODP environment being established by this call. For example, the caller can
+specify the maximum number of worker threads it will use, the thread masks
+associated with these threads, as well as whether the default logging or
+abort functions are to be overridden with an application-supplied handler.
+
+The application may also provide optimization hints to the ODP implementation
+if it knows that it will never use specific ODP feature sets, such as the
+packet classifier or traffic manager. Implementations may use such hints to
+provide optimized behavior to applications that are known not to need these
+features.
+
+Following global initialization, each thread in turn
 calls 'odp_init_local()'. This establishes the local ODP thread
 context for that thread and MUST be called before other ODP APIs may be
-called by that thread. The sole argument to this call is the _thread type_,
-which is either `ODP_THREAD_WORKER` or `ODP_THREAD_CONTROL`.
+called by that thread. The sole argument to this call is the `instance`
+variable returned by `odp_init_global()`.
 
 === Shutdown
 Shutdown is the logical reverse of the initialization procedure, with