writing msus

Writing MSUs

New MSUs should be placed in the directory src/msus/<app_name>, where <app_name> is a name chosen for the group of interconnected MSUs.

MSUs must provide a c-compilable header interface to their internal functions (though the MSU may be written and compiled in C++).

Three steps must be taken to create and use a new MSU:

1. Create the MSU header and source file
2. Add the MSU to runtime/msu_type_list.h
3. Add the MSU group to the Makefile so it will be compiled. Optionally, if custom rules are necessary for the global controller:
4. Add MSU id to global_controller/msu_ids.h

Each of these steps is walked through in detail below.

MSU code

MSU header

Only one declaration is necessary in each MSU's header file: The struct msu_type declaration. Optionally, one can define the type ID, but this is not strictly necessary.

A sample MSU header contains:

// Not strictly necessary
#define TEST_MS_TYPE_ID 100

// Definitely necessary
struct msu_type TEST_MSU_TYPE

MSU source

The MSU source file must define the struct msu_type declared in the header file. This means that it must, at a minimum, also define the receive() function for that MSU type, though it should also define the MSU's name, id, and any other functions necessary for the MSU to function properly.

Any functions declared in this file that are not needed outside of this MSU should be declared static. This includes, but is not limited to, the functions that are listed in the msu_type struct.

A sample MSU source file contains:

static int receive(struct local_msu *self, struct msu_msg *msg) {
    // This receive function does nothing. Yours should do more.
    return 0;
}

struct msu_type TEST_MSU_TYPE = {
    .name = "Test_MSU",
    .id = TEST_MSU_TYPE_ID,
    .receive = receive
}

For a description of each function that can be declared in an MSU type, view the sourcecode or doxygen for runtime/msu_type.c.

For a detailed description of the capabilities of an MSU's receive function, click here.

Adding to msu_type_list.h

The file runtime/msu_type_list.h defines all of the MSU types that can be instantiated in a runtime. As your MSU might not be needed by all users of DeDos, it should be added to this list with a #define guard to enable optional compilation.

To add to the list of MSUs, include the following code:

#ifdef COMPILE_YOUR_GROUP_MSUS
#include "your_group/msu1.h"
#include "your_group/msu2.h"

#define YOUR_GROUP_MSUS \
    &MSU1_TYPE, \
    &MSU2_TYPE
#else
// This is important so that things will still compile
#define YOUR_GROUP_MSUS
#endif

Then finally, at the bottom of the file, add your group definition to the list of MSU types defined.

#define MSU_TYPE_LIST \
    { \
        &TEST_MSU_TYPE, \
        &SOCKET_MSU_TYPE, \
        YOUR_GROUP_MSUS \
    }

Adding MSU group to the makefile

This part is simple...

At the top of runtime.mk, a list of MSU_APPLICATIONS are defined. These applications are the ones that are compiled.

For this purpose, you should modify the line to read:

MSU_APPLICATIONS = your_group