CHIP stack initialization

tags: CHIP Matter Firmware Engineer

2022/03/19
CHIP git hash code 67b4746ad8

In this post, we will check CHIP initialization.

PlatformMgr().InitChipStack();

In most of examples, we can always find this line of code at the beginning of main.cpp. So I think it's a good start.

What is PlatformMgr

You can find the header file at this path include/platform/PlatformManager.h and find its description:

Provides features for initializing and interacting with the chip network stack on a chip-enabled device.

Now we know the definition of this class, but where is the cpp? You certainly cannot find a file called "PlatformMgr.cpp" anywhere in this project.

The reason is that this project(CHIP stack) is designed to run on different platforms. So the basic idea is that there should be different implementations for different platforms. For example, you will find PlatformManagerImpl.h under platform/EFR32.

Explanation of the design at this doc.

Here is a simple recap of the document:

• The design pattern make it easier to adapt the code to different platforms and operating contexts.
• The CHIP Device Layer employs a pattern of static polymorphism to insulate its application-visible API from the underlying platform-specific implementation.
• As much as possible, the above goals are achieved via the use of zero-cost abstraction patterns (zero-cost in terms of code size and execution overhead).

So now we understand the design, let's get our hand dirty by walking through the call stack.

Call stack of InitChipStack

PlatformMgr()

First, in include/platform/PlatformManageer.h you can find this declaration:

extern PlatformManager & PlatformMgr();

And by the design pattern, we can find the definition:

/**
 * Returns the public interface of the PlatformManager singleton object.
 *
 * Chip applications should use this to access features of the PlatformManager object
 * that are common to all platforms.
 */
inline PlatformManager & PlatformMgr(void)
{
    return PlatformManagerImpl::sInstance;
}

at platform/EFR32/PlatformManagerImpl.h. And the PlatformManagerImpl is actually is the class defined in this header file. And of course this function is a friend funtion to the class PlatformManagerImpl otherwise it won't be able to access the private member: sInstance.

If you are a newbie to firmware development like me, and you may be curious about how exactly the CHIP call this PlatformMgr. After all, there are bunch of same function in different platform folders.

Here is the short answer:
Compile time

And speaking of compile, there is a hidden file called ".gn" in the example root, it includes the default cpu and os value. I had a really hard time to find them at first.

InitChipStack()

Next, you will find out there is no such function in the PlatformManagerImpl. You will probably have a intuition that InitChipStack() would eventually go to _InitChipStack(). So let's move to the parent class PlatformManageer, and find the definition:

inline CHIP_ERROR PlatformManager::InitChipStack()
{
    // NOTE: this is NOT thread safe and cannot be as the chip stack lock is prepared by
    // InitChipStack itself on many platforms.
    //
    // In the future, this could be moved into specific platform code (where it can
    // be made thread safe). In general however, init twice
    // is likely a logic error and we may want to avoid that path anyway. Likely to
    // be done once code stabilizes a bit more.
    if (mInitialized)
    {
        return CHIP_NO_ERROR;
    }

    CHIP_ERROR err = static_cast<ImplClass *>(this)->_InitChipStack();
    mInitialized   = (err == CHIP_NO_ERROR);
    return err;
}

Let's focus on this line:
CHIP_ERROR err = static_cast<ImplClass *>(this)->_InitChipStack();

As you can see, it first converts the this pointer to ImplClass pointer. And you will find ImplClass in the PlatformManageer:

using ImplClass = ::chip::DeviceLayer::PlatformManagerImpl;

In our case, ::chip::DeviceLayer::PlatformManagerImpl is located at platform/EFR32/PlatformManagerImpl.h

So, yes, the next item in call stack is _InitChipStack().

Recap a bit

If you feel a little bit confused now, I guess it's completely normal since I had been there too…

So I try to make the call stack a list, this list is not correct from compiler point of view. It's more like how I track this single line of code.

1. PlatformMgr().InitChipStack();
2. Find PlatformMgr()
   • include/platform/PlatformManager.h, extern PlatformManager & PlatformMgr();
   • platform/EFR32/PlatformManagerImpl.h,
     ​​​​​​​​inline PlatformManager & PlatformMgr(void)
     ​​​​​​​​{
     ​​​​​​​​    return PlatformManagerImpl::sInstance;
     ​​​​​​​​}
     

   • The PlatformMgr() becomes PlatformManagerImpl object.
3. Try to find PlatformManagerImpl.InitChipStack();
   • Because the PlatformManagerImpl inherite PlatformManager. So go to PlatformManager.
   • include/platform/PlatformManager.h, find InitChipStack()
     ​​​​​​​​CHIP_ERROR err = static_cast<ImplClass *>(this)->_InitChipStack();
     

   • this is the pointer points to the PlatformManagerImpl object. Like this PlatformManager * this = PlatformManagerImpl::sInstance.
   • ImplClass = ::chip::DeviceLayer::PlatformManagerImpl
   • So of course the this can be converted to PlatformManagerImpl
   • So static_cast<ImplClass *>(this) becomes (PlatformManagerImpl*)(this)
   • It's equivalent to PlatformManagerImpl::sInstance._InitChipStack().

In the _InitChipStack

Once we can find which _InitChipStack() the stack is actually calling, the rest will be easy. Basically, it just repeat this behavior: initialize something and call the _InitChipStack of the parent class. But we can find out that they create a thread for CHIP stack.

ThreadStackMgr().InitThreadStack()

We can easily use the same concept we mentioned above to track this function call. I think nothing special in this function because I don't really want to spent too much time on OpenThread itself. And this function also creates another thread for running OpenThread stack.

APP task

And the last thread is the app itself, this one is super easy to understand because this is just a simple example. However, in the init, there is a line of code to set up the entire CHIP stack.

chip::Server::GetInstance().Init(); 

More specifically, in this funciton, it will make this devcie ready for incoming connection request. Because there are too much things worth to study in this function. We will break it down to different posts and try to give it a better explanation.