Policies to write correctly wizard parameters in cfg files and in module definitions

Overview

BeRTOS Configuration Wizard is a powerful tool that permits to create a new BeRTOS project quickly, and to modify the BeRTOS configuration easily using a simple but complete GUI. This tool reads the needed informations directly from the BeRTOS source tree. It needs the following types of informations:

The syntax is pretty simple, it's very similar to the python syntax. In order to facilitate the writing process you can use the test/testModulePage.py script, that show you the result of the parse process and eventually the errors occurred using the wizard's BModulePage widget.

Module definition syntax

When a programmer write a BeRTOS module, he have to write also a cuple of informations needed by the wizard, like the module name and optionally the dependencies and the path of the configuration file. Theese informations should be located in the main comment at the beginning of the header file.

An example of module definition is the one belove: 

/**
 * \file
 * <!--
 * This file is part of BeRTOS.
 *
 * Bertos is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * As a special exception, you may use this file as part of a free software
 * library without restriction.  Specifically, if other files instantiate
 * templates or use macros or inline functions from this file, or you compile
 * this file and link it with other files to produce an executable, this
 * file does not by itself cause the resulting executable to be covered by
 * the GNU General Public License.  This exception does not however
 * invalidate any other reasons why the executable file might be covered by
 * the GNU General Public License.
 *
 * Copyright 2005 Develer S.r.l. (http://www.develer.com/)
 *
 * -->
 *
 * \version $Id: adc.h 1796 2008-09-05 17:23:37Z batt $
 *
 * \brief ADC driver (interface)
 *
 * \version $Id: adc.h 1796 2008-09-05 17:23:37Z batt $
 * \author Francesco Sacchi <batt@develer.com>
 *
 * $WIZARD_MODULE = {
 * "name": "adc",
 * "depends": ["battfs"],
 * "configuration": "bertos/cfg/cfg_adc.h"     
 * }
 */

As you can see the wizard informations are located in the comment, and have a syntax very similar to the python dict definition syntax. 

$WIZARD_MODULE = {
"name": "adc",
"depends": ["battfs"],
"configuration": "bertos/cfg/cfg_adc.h"     
}

Let's analize in depth the definition parameters:

  • "name": this parameter is associate to a string parameter and it's the name of the module ("adc", in our example).
  • "depends": this parameter contains a list of string (the modules needed in order to be our module usable). As you can see the list is defined like the python's lists.
  • "configuration": this parameter contains the path of the configuration file (a string) relatively to the root directory of BeRTOS sources.

"depends" and "configuration" parameters are optional.

Enum definition syntax

Sometime in a header file is defined a list of constants, and theese constants are used il the configuration files. In order to make theese lists visible to the wizard we need to write some simple lines in a comment, before the list.

An example of list definition is the one belove: 

/**
 * Logging level definition
 *
 * When you choose a log level messages you choose
 * also which print function are linked.
 * If you choose a low level of log you link all log function (error, warning and info),
 * but if choose a hight level you link only that have the priority egual or hight.
 * The priority level go from error (highest) to info (lowest) (see cfg/debug.h
 * for more detail).
 * 
 * $WIZARD_LIST = {
 * "log_level": ["LOG_LVL_NONE", "LOG_LVL_ERR", "LOG_LVL_WARN", "LOG_LVL_INFO"]
 * }
 */
#define LOG_LVL_NONE      0
#define LOG_LVL_ERR       1
#define LOG_LVL_WARN      2
#define LOG_LVL_INFO      3

Also in this case the the wizard informations are rapresented in a python dict form. 

$WIZARD_LIST = {
"log_level": ["LOG_LVL_NONE", "LOG_LVL_ERR", "LOG_LVL_WARN", "LOG_LVL_INFO"]
}

Let's analize the structure of this information:

  • the only item in this dict has the name of the enum as key and a list as value. That list contains the name of the constants defined belove the comment.

Configuration parameter definition syntax

The cfg files contain the configuration of BeRTOS modules. The wizard is able to read theese files and to show to the user the appropriate widget so that the user can comfortly modify the value of the parameters. You probably want to see some examples of configuration parameter definition. 

#define CONFIG_ADC_CLOCK        4800000L    ///< Frequency clock for ADC conversion. $WIZARD = {"type": "int", "min": "0", "max": "100000000"}

/// Module logging level. $WIZARD = {"type": "enum", "value_list": "log_level"}
#define ADC_LOG_LEVEL      LOG_LVL_INFO

/**
 * Enable ADS Strobe.
 * $WIZARD = {
 * "type": "boolean"
 * }
 */
#define CONFIG_ADC_STROBE  0

As you can see the wizard is able to understand all the doxygen-like comments. Let's see how to write theese definitions:

  • "type": the type field contains the type of the parameter. Possible values are "int", "boolean", "enum".
  • "min" (only for int parameters, optional): this field contains the minimum value of the parameter.
  • "max" (only for int parameters, optional): this field contains the maximum value of the parameter.
  • "long" (only for int parameters, optional): this field contains a boolean, if True the parameter is a long instead of an int. (No longer needed)
  • "unsigned" (only for int parameters, optional): this field contains a boolean, if True the parameter is an unsigned (int or long). (No longer needed)
  • "value_list" (only for enum parameters): this field contains the name of the list which constants are suitable values for the above definition. The list definition is described above.

The parameter default value is the one written in the define statement.

That's all, it's pretty simple, isn't it? So start working! :)