GreenMessage Technical Overview

This is a generic module-to-module message passing framework, used for control, configuration and other side band messages.

1) Introduction

This project offers a simple API to support assembling a data structure so-called message and send this message to some other module in the system that implements a receiver interface for messages.

The message contents are based on properties of the form (name)->(value). The map of names supports hierarchy. By convention, the hierarchy separator is the dot '.' character. A valid name for a property is the string "my_cpu.cache.size". The values for each property are stored in a type-independent way, and can be retrived as an integral or real number, or as a string.

The module that will receive the message is located by name look-up, and the write method is invoked to send the message to it's destination. The receiver module implementation can chose get the message delivered to a fifo or it can handle the message directly.

2) Usage

All the functionality is defined in the header "greenmessage/messenger.hpp". After #include this file, some names get defined in the namespace gs::msg. They are listed bellow:

2.1) class Message

A message is a mapping of name->value. In fact, this class is inherited from std::map, and can use the methods provided by this parent to retrieve the values or to iterate over the first level of property names. Both key and value accepts numbers and strings. Examples:

gs::msg::Message msg;
msg["command"] = "start";
msg["repeat"] = 10;
msg[1] = "test";
msg[2] = 42.123;
The mapping is hierarchical and implemented as a tree. The hierarchy can be acesed in two ways: (1) using a dot '.' in the name string or (2) use the subscript operator multiple times.

msg["my_cpu.cache"]["size"] = 4096
msg["my_cpu"]["cache.type"] = "wb";
Getting a reference to a branch is a low-cost operation:

gs::msg::Message& my_cache = msg["my_cpu.cache"];
cout << my_cache["size"]; // outputs 4096
2.2) class WriteIf

This interface contais the method write(Message). The message will go to a sc_fifo or this method can be implemented by the receiver module directly.

2.3) function: WriteIf& findReceiver(string)

This function does a look-up in the SystemC object hierarchy to find an object with the given name. This object can be a sc_module that implements the WriteIf interface or that contains a registered sc_fifo. It can also be a sc_fifo itself. A reference to the WriteIf is returned, so the write method of this interface can be used to send several messages to the named receiver.

2.4) class Receiver

A receiver module can inherit from this class to register a sc_fifo as the end-point for messages to this module. The registration is done in construction time and doesn't change during simulation.