| Message ID | 1453505797-20108-4-git-send-email-gary.robertson@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
On Tue, Feb 2, 2016 at 5:41 AM, Savolainen, Petri (Nokia - FI/Espoo) <petri.savolainen@nokia.com> wrote: > > ... >> + This cpumask is used only to convey externally supplied >> + ODP instance during initialization. Applications code must call >> + odp_cpumask_default_worker() to obtain information as to the > > Since the function above returns the default mask for workers, the call makes > sense (only) when user wants to use default settings of the implementation. So, > the "must" above should be "may". When user does not know or care which CPUs to use > it can pass NULL here and call default_worker(). > My intent was to indicate that the cpumask should never be referenced directly from an application - but rather that this information should only be obtained via the above function call. However, I see this line can be misinterpreted - so less ambiguously perhaps it should say: Applications code wishing to obtain information as to the CPU resources available for worker threads must call odp_cpumask_default_worker() and should never reference this cpumask directly. > If user passes a bad CPU mask (a bad range of CPUs), the global init should fail. I did not want to specify this in the API. Determining what constitutes a valid range of CPUs may be a complex issue - so I wanted to leave the handling of that to the implementation developer rather than mandating it in the API spec. In fact, my proposed helper code takes the user's passed-in CPU masks and sanitizes them based on a number of factors including the underlying CPU topology and the kernel's internal handling of CPU resources... details which I think the application writer shouldn't be burdened with. The passed-in CPU masks are used as 'boundaries' (with the exception of overrides regarding CPU 0) and any invalid contents are cleaned up prior to calling odp_init_global(). Whether it is preferred simply to abort on bad cpumask input or to clean them up, possibly emit diagnostic error messages, and continue as best as possible is a debatable policy issue which I hoped to address with patches not yet submitted. I had hoped to confine this patch to simply include the API extension adding the ability to pass externally specified cpumasks and to address what should be done with those cpumasks in other patch submissions. Thanks for your attention and inputs. If you will let me know whether it is acceptable not to specify bad CPU mask input handling in the API documentation, then I will modify the comments as needed and resubmit. ... >> + This cpumask is used only to convey externally supplied >> + information regarding control CPU resources available to this >> + ODP instance during initialization. Applications code must call > > Same here. Applications code wishing to obtain information as to the CPU resources available for control threads must call odp_cpumask_default_control() and should never reference this cpumask directly . > > -Petri > > >> + odp_cpumask_default_control() to obtain information as to the >> + CPU resources available for control threads. */ >> + odp_cpumask_t *control_cpus; >> /** Replacement for the default log fn */ >> odp_log_func_t log_fn; >> /** Replacement for the default abort fn */ >> -- >> 1.9.1 >
diff --git a/include/odp/api/init.h b/include/odp/api/init.h index e667d25..448a520 100644 --- a/include/odp/api/init.h +++ b/include/odp/api/init.h @@ -31,6 +31,7 @@ extern "C" { #include <odp/std_types.h> #include <odp/hints.h> #include <odp/thread.h> +#include <odp/cpumask.h> /** @defgroup odp_initialization ODP INITIALIZATION * Initialisation operations. @@ -118,6 +119,40 @@ typedef struct odp_init_t { Valid range is from 0 to platform specific maximum. Set both num_worker and num_control to zero for default number of threads. */ int num_control; + /** Pointer to bit mask mapping CPUs available to this ODP instance + for running worker threads. + Valid range for mask is from 0 to platform specific maximum CPU. + Initialize to a NULL pointer to use default cpu mapping and + default isolation setup (or the lack of isolation) for + worker CPUs. + If worker CPUs are expected to provide isolated runtime + environments for worker threads, then the contents of this cpumask + should be unique for each ODP instance running concurrently + on the underlying platform, and should not contain any + control CPUs. + This cpumask is used only to convey externally supplied + information regarding worker CPU resources available to this + ODP instance during initialization. Applications code must call + odp_cpumask_default_worker() to obtain information as to the + CPU resources available for worker threads. */ + odp_cpumask_t *worker_cpus; + /** Pointer to bit mask mapping CPUs available to this ODP instance + for running control threads. + Valid range for mask is from 0 to platform specific maximum CPU. + Initialize to a NULL pointer to use default cpu mapping for + control CPUs. + Control CPUs are expected to provide shared, non-isolated + runtime environments for control threads. + It must therefore be anticipated that this cpumask may be + identical for all ODP instances running concurrently + on the underlying platform and may specify CPU resources + to be shared among all concurrent ODP instances. + This cpumask is used only to convey externally supplied + information regarding control CPU resources available to this + ODP instance during initialization. Applications code must call + odp_cpumask_default_control() to obtain information as to the + CPU resources available for control threads. */ + odp_cpumask_t *control_cpus; /** Replacement for the default log fn */ odp_log_func_t log_fn; /** Replacement for the default abort fn */
Adds pointers to externally supplied cpumasks for control and worker CPUs to the ODP global init data which is passed as an argument to odp_init_global. The intent is to allow an external entity to pass in lists of the CPU resources available to the current ODP application. It is assumed that these pointers would be NULL unless explicitly populated prior to calling odp_init_global. odp_init_global would respond to NULL pointers here by ensuring that odp_cpumask_default_control and odp_cpumask_default_worker would return the platform-specific default CPU configurations. If these pointers were not NULL when odp_init_global was called, then the above functions would return cpumasks reflecting the (possibly amended) contents of the referenced cpumasks instead of the platform defaults. Signed-off-by: Gary S. Robertson <gary.robertson@linaro.org> --- include/odp/api/init.h | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+)