<commit_before>Module Programming Guide
========================

SOS modules are programmed in C. 
However, the SOS system follows a lot of conventions that enable a module to
be reolcated and dynamically loaded on a sensor node.
This guide will describe the SOS programming concepts.
The running example used in this guide is the Surge data collection module
that is located at `$SOSROOT/modules/demo/surge`.
The concepts are listed below.
A new user is encouraged to read all the concepts.
Familiar users can directly jump to the relevant section.

1. xref:module_header[Module Header]
2. xref:msg_handler[Message Handler]
3. xref:mod_state[Module State]
4. xref:sys_calls[System Calls]
5. xref:local_calls[Local Function Calls]
6. xref:fnptr_calls[Function Pointer Pointer Calls]

[[<module_header>]]

Module Header
-------------
Module header is a special record that contains all the necessary
information used by the SOS tools for distributing, loading and linking a
module into a sensor network.


IMPORTANT: *'All modules are required to declare exactly one module header.'*


Below is an example of the header used in Surge module using
link:http://gcc.gnu.org/onlinedocs/gcc-3.4.3/gcc/Designated-Inits.html[designated initialization].

.Surge Module Header
[c]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
static const mod_header_t mod_header SOS_MODULE_HEADER = {
  .mod_id         = SURGE_MOD_PID,
  .code_id        = ehtons(SURGE_MOD_PID),
  .module_handler = surge_module,
  .state_size     = sizeof(surge_state_t),
  .platform_type  = HW_TYPE /* or PLATFORM_ANY */,
  .processor_type = MCU_TYPE,
  .num_sub_func   = 1,
  .num_prov_func  = 0,
  .funct = {
	[0] = {error_8, "Cvv0", TREE_ROUTING_PID, MOD_GET_HDR_SIZE_FID},
  },
};
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TIP: Module header can be created by copying the header template and
modifying the values as needed.

Module header is declared as a static constant variable of type
`mod_header_t`.
Module headers are stored in program memory space.
The compiler (e.g. avr-gcc) requires special directives to place the data
structure in program memory space.
These directives are platform specific and are encapsulated by the
`SOS_MODULE_HEADER` macro.
The fields in the module header are:

mod_id::
*Module identifier*. Module Ids are used for inter-module
communication within a node and across the network. Thus module Ids are equivalent to a
combination of process Ids and TCP Ports on a regular PC. 
Simple modules that are being used for testing, debugging and prototyping
are encouraged to pick one of the pre-defined general module Ids.<commit_msg>Fixed the code from the Surge Module Header example: replaced the code example with current code (it has all of the same fields but in a slightly different order). Also fixed two gramatical mistakes directly thereafter. The surge message handler is also out-of-date, but changing that would require other changes to the tutorial (and perhaps added content), so I'm leaving it alone for now. I haven't looked through the rest of this document... it may well have other inconsistencies with the current codebase.<commit_after>Module Programming Guide
========================

SOS modules are programmed in C. 
However, the SOS system follows a lot of conventions that enable a module to
be reolcated and dynamically loaded on a sensor node.
This guide will describe the SOS programming concepts.
The running example used in this guide is the Surge data collection module
that is located at `$SOSROOT/modules/demo/surge`.
The concepts are listed below.
A new user is encouraged to read all the concepts.
Familiar users can directly jump to the relevant section.

1. xref:module_header[Module Header]
2. xref:msg_handler[Message Handler]
3. xref:mod_state[Module State]
4. xref:sys_calls[System Calls]
5. xref:local_calls[Local Function Calls]
6. xref:fnptr_calls[Function Pointer Pointer Calls]

[[<module_header>]]

Module Header
-------------
Module header is a special record that contains all the necessary
information used by the SOS tools for distributing, loading and linking a
module into a sensor network.


IMPORTANT: *'All modules are required to declare exactly one module header.'*


Below is an example of the header used in Surge module using
link:http://gcc.gnu.org/onlinedocs/gcc-3.4.3/gcc/Designated-Inits.html[designated initialization].

.Surge Module Header
[c]
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
static const mod_header_t mod_header SOS_MODULE_HEADER = {
  .mod_id        = SURGE_MOD_PID,
  .state_size    = sizeof(surge_state_t),
  .num_sub_func  = 1,
  .num_prov_func = 0,
  .platform_type  = HW_TYPE /* or PLATFORM_ANY */,
  .processor_type = MCU_TYPE,
  .code_id       = ehtons(SURGE_MOD_PID),
  .module_handler = surge_module_handler,
  .funct = {
    [0] = {error_8, "Cvv0", TREE_ROUTING_PID, MOD_GET_HDR_SIZE_FID},
  },
};
source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TIP: A module header can be created by copying the header template and
modifying the values as needed.

A module header is declared as a static constant variable of type
`mod_header_t`.
Module headers are stored in program memory space.
The compiler (e.g. avr-gcc) requires special directives to place the data
structure in program memory space.
These directives are platform specific and are encapsulated by the
`SOS_MODULE_HEADER` macro.
The fields in the module header are:

mod_id::
*Module identifier*. Module Ids are used for inter-module
communication within a node and across the network. Thus module Ids are equivalent to a
combination of process Ids and TCP Ports on a regular PC. 
Simple modules that are being used for testing, debugging and prototyping
are encouraged to pick one of the pre-defined general module Ids.
{'fraction_non_alphanumeric': 0.1022903392457379, 'fraction_numerical': 0.004821766833132427, 'mean_word_length': 4.627906976744186, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1766015', 'n_tokens_mistral': 1667, 'n_tokens_neox': 1593, 'n_words': 729}