BeRTOS
Data Structures | Defines | Typedefs | Enumerations | Functions
Simple RPC machinery
Middleware facilities

Channel protocol parser and commands. More...

Data Structures

union  parms
 union that contains parameters passed to and from commands More...
struct  CmdTemplate
 Define a command that can be tokenized by the parser. More...

Defines

#define REGISTER_CMD(NAME)   REGISTER_FUNCTION(&cmd_ ## NAME ## _template)
 Utility function to register a command.
#define MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS)
 Utility macro to create a command template.
#define MAKE_CMD(NAME, ARGS, RES, BODY, FLAGS)
 Utility macro to create command templates and callback functions.

Typedefs

typedef ResultCode(* CmdFuncPtr )(parms args_results[])
 pointer to commands

Enumerations

enum  ResultCode { RC_ERROR = -1, RC_OK = 0, RC_REPLY = 1, RC_SKIP = 2 }
 Error generated by the commands through the return code. More...

Functions

void parser_init (void)
 Initialize the parser module.
void parser_register_cmd (const struct CmdTemplate *cmd)
 Register a new command into the parser.
const char * parser_rl_match (void *dummy, const char *word, int word_len)
 Hook for readline to provide completion support for the commands registered in the parser.
bool parser_process_line (const char *line)
 Command input handler.
bool parser_execute_cmd (const struct CmdTemplate *templ, parms args[CONFIG_PARSER_MAX_ARGS])
 Execute a command with its arguments, and fetch its results.
struct CmdTemplateparser_get_cmd_template (const char *line)
 Find the template for the command contained in the text line.
bool parser_get_cmd_arguments (const char *line, const struct CmdTemplate *templ, parms args[CONFIG_PARSER_MAX_ARGS])
 Extract the arguments for the command contained in the text line.

Detailed Description

Channel protocol parser and commands.

This module provides a simple text based RPC implementation. Often there is the need to give a command to the device and receive results back. Each command may have a variable number of input and output parameters, with variable type, and a return code which indicates if the command was successfully executed or not; this module provides the machinery to facilitate the above RPC scenario. You will need to write the RPC input and reply code as well as the definition of the commands.

Commands are defined using a CmdTemplate struct containing:

Once you have declared the commands, you need to register them in the parser with the function parser_register_cmd(). You are strongly encouraged to use MAKE_CMD() (or alternatively MAKE_TEMPLATE()) and REGISTER_CMD() to declare and register commands.

A command line can be parsed with the following steps:

You can also provide interactive command line completion using parser_rl_match().

Example:

 // Declare a buzzer command
 MAKE_CMD(beep, "d", "",
 ({
    buz_beep(args[1].l);
    RC_OK;
 }), 0)

 // initialize the parser
 parser_init();
 REGISTER_CMD(beep);

 // parse an input line
 char buf[80];
 // read line from somewhere
 rpc_get(buf);
 // now parse the line
 const struct CmdTemplate *templ;
 templ = parser_get_cmd_template(buf);

 // Take arguments (optionally check errors)
 parms args[PARSER_MAX_ARGS];
 parser_get_cmd_arguments(buf, templ, args);
 //Execute command
 if(!parser_execute_cmd(templ, args))
 {
    // error
 }
 // Now args contain the outputs of the function, you can send it
 // back to the caller
 rpc_reply(args)

Configuration file: cfg_parser.h

Author:
Bernie Innocenti <bernie@codewiz.org>
Stefano Fedrigo <aleph@develer.com>
Giovanni Bajo <rasky@develer.com>

Define Documentation

#define MAKE_CMD (   NAME,
  ARGS,
  RES,
  BODY,
  FLAGS 
)
Value:
static ResultCode cmd_ ## NAME (parms *args)    \
{                                               \
    return (ResultCode)BODY;                \
}                                               \
MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS)

Utility macro to create command templates and callback functions.

Example for a version command:

 MAKE_CMD(ver, "", "ddd",
 ({
    args[1].l = VERS_MAJOR;
    args[2].l = VERS_MINOR;
    args[3].l = VERS_REV;
    RC_OK;
 }), 0);

Remember that input and output parameters start from index 1, since args[0] is the command itself. The last line is the return value of the function.

Parameters:
NAMECommand name matched by the parser
ARGSInput arguments to the command
RESOutput arguments of the command
BODYCommand body, expressed with C 'statement expression'
FLAGSCommand flags

Definition at line 208 of file parser.h.

#define MAKE_TEMPLATE (   NAME,
  ARGS,
  RES,
  FLAGS 
)
Value:
const struct CmdTemplate cmd_ ## NAME ## _template =   \
{                                                      \
    #NAME, ARGS, RES, cmd_ ## NAME, FLAGS          \
};

Utility macro to create a command template.

It requires that a callback function with name cmd_NAME is already defined.

Parameters:
NAMECommand name
ARGSInput arguments
RESOutput arguments
FLAGSCommand flags

Definition at line 178 of file parser.h.

#define REGISTER_CMD (   NAME)    REGISTER_FUNCTION(&cmd_ ## NAME ## _template)

Utility function to register a command.

Parameters:
NAMECommand name to register

Definition at line 166 of file parser.h.


Enumeration Type Documentation

enum ResultCode

Error generated by the commands through the return code.

Enumerator:
RC_ERROR 

Reply with error.

RC_OK 

No reply (ignore reply arguments).

RC_REPLY 

Reply command arguments.

RC_SKIP 

Skip following commands.

Definition at line 125 of file parser.h.


Function Documentation

bool parser_execute_cmd ( const struct CmdTemplate templ,
parms  args[CONFIG_PARSER_MAX_ARGS] 
) [inline]

Execute a command with its arguments, and fetch its results.

The args paramenter is value-result: it provides input arguments to the callback function and it stores output values on return.

Parameters:
templTemplate of the command to be executed
argsArguments for the command, and will contain the results
Returns:
False if the command returned an error, true otherwise

Definition at line 247 of file parser.h.

bool parser_get_cmd_arguments ( const char *  input,
const struct CmdTemplate cmdp,
parms  args[CONFIG_PARSER_MAX_ARGS] 
)

Extract the arguments for the command contained in the text line.

The first argument will always be the command name, so the actual arguments will start at index 1.

Parameters:
inputText line to be processed (ASCIIZ)
cmdpCommand template for this line
argsWill contain the extracted parameters
Returns:
True if everything OK, false in case of parsing error.

Definition at line 261 of file parser.c.

struct CmdTemplate* parser_get_cmd_template ( const char *  input) [read]

Find the template for the command contained in the text line.

The template can be used to tokenize the command and interpret it.

This function can be used to find out which command is contained in a given text line without parsing all the parameters and executing it.

Parameters:
inputText line to be processed (ASCIIZ)
Returns:
The command template associated with the command contained in the line, or NULL if the command is invalid.

Definition at line 216 of file parser.c.

void parser_init ( void  )

Initialize the parser module.

Note:
This function must be called before any other function in this module

Definition at line 318 of file parser.c.

bool parser_process_line ( const char *  input)

Command input handler.

Process the input, calling the requested command (if found).

Parameters:
inputText line to be processed (ASCIIZ)
Returns:
true if everything is OK, false in case of errors

Definition at line 290 of file parser.c.

void parser_register_cmd ( const struct CmdTemplate cmd)

Register a new command into the parser.

Parameters:
cmdCommand template describing the command

Definition at line 313 of file parser.c.

const char* parser_rl_match ( void *  dummy,
const char *  word,
int  word_len 
)

Hook for readline to provide completion support for the commands registered in the parser.

Note:
This is meant to be used with mware/readline.c. See the documentation there for a description of this hook.