Registry

From NESTFE Wiki

Jump to: navigation, search

Contents

[edit]

Overview

The Registry is a programming abstraction that contains node "attributes", which are properties of the node such as the Light reading, the Location, the GPS coordinates, etc. A node can declare a new Attribute simply by using an interface to that attribute. It can then get and set the attribute value, or be notified when other modules change the value. A module may also "provide" the attribute interface, in which case it must implement the get/set functions and signal "updated" events whenever the value changes.

The Registry generation script checks the entire application to see which "attribute" interfaces are being "used", and then automatically generates a RegistryC component which implements those attributes and instantiating a new generic component of type AttributeM for each used attribute. If a user's module provides the attribute interface, RegistryC will simply expose an interface to that module instead of instantiating a new AttributeM module. In this way, the user can override the default attribute behavior.

A complete sample application can be found in contrib/hood/apps/TestRegistry. The Registry libraries can be found in tos/lib/Registry. Some documentation of the API is below.

Registry attributes can be made persistent across reboots and can be shared between different program images by using RegistryStore.

[edit]

API

The registry allows one to declare a Registry Attribute as follows: 

 module TestRegistryM
 {
    uses interface Attribute<uint16_t> as Light @registry("Light");
    ...

which means there is now a uint16_t Attribute called "Light". The module would wire this interface directly to the Registry, as follows: 

 components  
   TestRegistryM,
   RegistryC,
   ...

 Main.StdControl -> TestRegistryM;
 Main.StdControl -> RegistryC;

 TestRegistryM.Light -> RegistryC;

Any other module could also wire to the same interface. As long as the types and the @registry tags are the same, the two modules will be accessing the same values.

The Registry intentionally uses the word "Attribute" instead of "Attr" to avoid a naming conflict with Nucleus attributes.


The Attribute interface has the following functions: 

 interface Attribute<t>
 {
   command bool valid();
   command t get();
   command result_t set(t val);
   command bool update();
   event void updated(t val);
 }
[edit]

Setting Up

In order to use the API described above, the user must:

  1. use the new makesystem by setting the Makerules environment variable to point to the tinyos-1.x/tools/make/Makerules file
  2. add the following include directories to their makefile 
CFLAGS += -I$(TOSDIR)/../tos/lib/Registry
CFLAGS += -I$(TOSDIR)/../tos/lib/Rpc
CFLAGS += -I$(TOSDIR)/../beta/Drip
CFLAGS += -I$(TOSDIR)/../beta/Drain
  1. include the RegistryC module somewhere in their application
  1. invoke the registry.extra file in their make process by either declaring "registry" on the command line when making the application as follows 
make telosb registry

or adding registry to the GOALS variable in their makefile 

GOALS+=registry

For problems, the Pytos Installation Instructions setup instructions may contain more details.

[edit]

Differences from other implementations

  • Nucleus attributes are pull-based, ie the data is usually generated when another module (e.g. MgmtQuery) asks for it. This is because nucleus attributes are intended for pc-side network management; they are queryable by the user on a PC.
  • Hood-style attributes (from the old version of Hood in contrib/SystemC/neighborhood) were meant to be shared between modules on the same node, somewhat like shared variables. Therefore, they were implemented as a push-based cached: a module generates data and pushes it into the attribute, where it is cached for the next module to read.
  • The current Registry implementation attempts to combine these two concepts by allowing both push (single-phase "get" and "set" commands) and pull (split-phase "update" commands with "updated" events). The default module is a push-based shared-variable-like attribute. However, the user can override it and produce anything, including a pull-based attribute. The tools such as MgmtQuery are being ported to the Registry library to allow the same pc-side management support as nucleus attributes.
  • Besides the above, this Registry library also differs from the nucleus attribute library by:
    • providing a push-based default attribute
    • allowing Registry queries to be sent in multiple packets if they don't fit in a single packet
    • refactoring the mgmtQuery code into a Marshaller, which can be reused between RegistryQuery, RamQuery, HoodQuery, and HoodTransport modules. This decoupling allows, for example, one to use RamQuery without using RegistryQuery. Furthermore, the PC-side tools can therefore reuse the same PC-side marshaller tool to unpack the data from all packets.
    • fixing bugs in code generation scripts
    • allowing pc-side casting for more than int values
[edit]

Implementation

AttributeM.nc is a module with single cached value of whatever type it is parameterized by, that also provides the Attribute.nc interface. The RegistryC.nc file is a configuration file that instantiates multiple AttributeM modules when necessary and exposes all of their interfaces. It is automatically generated based on the @tags in the interface declarations. A single Registry.h file is also generated.

All registry attributes are exposed through nucleus, and can be get/set by the user. The @registry() tag can also be filled with an optional "rpc" value to allow this registry entry's Attribute interface to be rpc-able.

Retrieved from "http://nest.cs.berkeley.edu/nestfe/index.php/Registry"