diff options
author | Bill Fischofer <bill.fischofer@linaro.org> | 2017-06-13 07:55:15 -0500 |
---|---|---|
committer | Maxim Uvarov <maxim.uvarov@linaro.org> | 2017-11-10 14:03:29 +0300 |
commit | b6b667b1e95635a6ba77a19078d7d28013bcde1d (patch) | |
tree | 13d4581851cbc3eeaf22994950672faf70b000bb /doc/users-guide | |
parent | bae53291795e9c19cbfde9c0d0e11a19d9870623 (diff) |
doc: userguide: add odp_init_global() documentation for unused features
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>
Reviewed-by: Petri Savolainen <petri.savolainen@linaro.org>
Signed-off-by: Maxim Uvarov <maxim.uvarov@linaro.org>
Diffstat (limited to 'doc/users-guide')
-rw-r--r-- | doc/users-guide/users-guide.adoc | 36 |
1 files changed, 30 insertions, 6 deletions
diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 0d1e5eb78..0c7d3f773 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -558,20 +558,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 |