Writing Your Own Module

Overview

In general, writing a custom BESS module is very simple:

1. Add new message types in protobuf/module_msg.proto if necessary. The message types are used as arguments for module initialization and commands.

2. Define and implement the custom module class in core/modules/[new_module].[cc|h].

Message Type

Message types for module initialization and command arguments are defined in protobuf/module_msg.proto. Built In Modules and Ports documents all built-in types. You may need to define new types for your custom module. Types follow the naming convention below:

• Init argument: [ModuleName]Arg (e.g. QueueArg)
• Command argument: [ModuleName]Command[CommandName]Arg (e.g. BPFCommandClearArg)

Module Class

The module class should inherit Module from core/module.h. A minimum module class should include either ProcessBatch() or RunTask() function:

class MinimalModule final : public Module {
  public:
    CommandResponse Init(const bess::pb::MinimalModuleArg &arg);

    // Pick one
    struct task_result RunTask(void *arg) override;
    void ProcessBatch(bess::PacketBatch *batch) override;
}

Finally, register the module class by appending this line to the cc file:

ADD_MODULE(MinimalModule, "minimal", "description of your module")

Command

In addition to Init(), modules may be configured via commands. To add a command, first define a static const variable cmds as well as command handlers inside the module class definition.

class MinimalModule final : public Module {
 public:
  ...
  static const Commands cmds;

  CommandResponse CommandAdd(const bess::pb::MinimalModuleCommandArg &arg);
  CommandResponse CommandClear(const bess::pb::EmptyArg &arg);
  ...
};

Then initialize this variable in the cc file:

const Commands MinimalModule::cmds = {
    {"add", "MinimalModuleCommandArg", MODULE_CMD_FUNC(&MinimalModule::CommandAdd), 0},
    {"clear", "EmptyArg", MODULE_CMD_FUNC(&MinimalModule::CommandClear), 0}};

Commands is simply a typedef of std::vector<struct Command>. The last field of struct Command denotes whether the command is thread-safe or not.