[instance] single OpenThread instance optimizations (#1926)

This commit new configuration option `enable-multiple-instances` and
its corresponding option `OPENTHREAD_ENABLE_MULTIPLE_INSTANCES`. When
enabled OpenThread supports handling of multiple instances. By default
this is disabled.

This commit also adds two optimizations for single instance case to
simplify the code and also help reduce memory/RAM usage:

(1) OpenThread objects/classes typically keep a reference to a higher
level object (e.g., many classes keep track of owning `ThreadNetif`)
to be able to access other objects/methods within OpenThread class
hierarchy. In single instance mode, the reference member variables are
removed and instead global functions are used to access the singleton
objects from one class to the other. To implement this, a group of
`<Object>Locator` classes are defined (e.g., `ThreadNetifLocator`,
etc.) which are then used as base class of other OpenThread classes.

(2) OpenThread objects which provide a callback/handler (e.g.,
`Timer`, `Tasklet`, etc.) have `void *mContext` member variable which
is used to keep track of the owner of the object. In single instance
mode the `mConext` member variables are removed since the owner is
expected to be a singleton and can be uniquely determined from the
callback function.

To implement this, two changes are made: First the handler methods are
modified to provide a reference to the object (e.g., `Timer` handler
will provide a `Timer &aTimer` as a parameter of its handler
callback). Second, a new base class `Context` is introduced which
hides the implementation providing an arbitrary context information. A
new static method `GetOwner(aContext)` is added to classes which own a
callback providing objects. This method help convert a `Context` to
the reference of the owner class object.

src/core/api/instance_api.cpp

@@ -40,13 +40,45 @@
 #include <openthread/platform/settings.h>
 
 #include "openthread-instance.h"
+#include "openthread-single-instance.h"
 #include "common/logging.hpp"
 #include "common/new.hpp"
 
-#ifndef OPENTHREAD_MULTIPLE_INSTANCE
+#if !OPENTHREAD_ENABLE_MULTIPLE_INSTANCES
+
 static otDEFINE_ALIGNED_VAR(sInstanceRaw, sizeof(otInstance), uint64_t);
 otInstance *sInstance = NULL;
-#endif
+
+otInstance *otGetInstance(void)
+{
+    return sInstance;
+}
+
+ot::ThreadNetif &otGetThreadNetif(void)
+{
+    return sInstance->mThreadNetif;
+}
+
+ot::MeshForwarder &otGetMeshForwarder(void)
+{
+    return sInstance->mThreadNetif.GetMeshForwarder();
+}
+
+ot::TimerScheduler &otGetTimerScheduler(void)
+{
+    return sInstance->mIp6.mTimerScheduler;
+}
+
+ot::TaskletScheduler &otGetTaskletScheduler(void)
+{
+    return sInstance->mIp6.mTaskletScheduler;
+}
+
+ot::Ip6::Ip6 &otGetIp6(void)
+{
+    return sInstance->mIp6;
+}
+#endif // #if !OPENTHREAD_ENABLE_MULTIPLE_INSTANCES
 
 otInstance::otInstance(void) :
     mReceiveIp6DatagramCallback(NULL),
@@ -95,11 +127,11 @@ void otInstancePostConstructor(otInstance *aInstance)
 #endif
 }
 
-#ifdef OPENTHREAD_MULTIPLE_INSTANCE
+#if OPENTHREAD_ENABLE_MULTIPLE_INSTANCES
 
 otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)
 {
-    otInstance *aInstance = NULL;
+    otInstance *instance = NULL;
 
     otLogFuncEntry();
 
@@ -111,27 +143,31 @@ otInstance *otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)
     VerifyOrExit(aInstanceBuffer != NULL);
 
     // Construct the context
-    aInstance = new(aInstanceBuffer)otInstance();
+    instance = new(aInstanceBuffer)otInstance();
 
     // Execute post constructor operations
-    otInstancePostConstructor(aInstance);
+    otInstancePostConstructor(instance);
 
-    otLogInfoApi(aInstance, "otInstance Initialized");
+    otLogInfoApi(instance, "otInstance Initialized");
 
 exit:
 
     otLogFuncExit();
-    return aInstance;
+    return instance;
 }
 
-#else
+#else // #if OPENTHREAD_ENABLE_MULTIPLE_INSTANCES
 
-otInstance *otInstanceInit()
+otInstance *otInstanceInitSingle(void)
 {
     otLogFuncEntry();
 
     VerifyOrExit(sInstance == NULL);
 
+    // We need to ensure `sInstance` pointer is correctly set
+    // before any object constructor is called.
+    sInstance = reinterpret_cast<otInstance *>(&sInstanceRaw);
+
     // Construct the context
     sInstance = new(&sInstanceRaw)otInstance();
 
@@ -146,7 +182,7 @@ exit:
     return sInstance;
 }
 
-#endif
+#endif // #if OPENTHREAD_ENABLE_MULTIPLE_INSTANCES
 
 void otInstanceFinalize(otInstance *aInstance)
 {
@@ -156,9 +192,10 @@ void otInstanceFinalize(otInstance *aInstance)
     (void)otThreadSetEnabled(aInstance, false);
     (void)otIp6SetEnabled(aInstance, false);
 
-#ifndef OPENTHREAD_MULTIPLE_INSTANCE
+#if !OPENTHREAD_ENABLE_MULTIPLE_INSTANCES
     sInstance = NULL;
 #endif
+
     otLogFuncExit();
 }