Working

bertos/mware/parser.h

@@ -0,0 +1,277 @@
+/**
+ * \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 2003, 2006 Develer S.r.l. (http://www.develer.com/)
+ * All Rights Reserved.
+ * -->
+ *
+ * \defgroup parser Simple RPC machinery
+ * \ingroup mware
+ * \{
+ *
+ * \brief 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:
+ * - command name: the string that will be matched by the parser;
+ * - command arguments: a string representing type and number of input
+ *   arguments;
+ * - command output: a string representing type and number of output arguments;
+ * - function callback: function implementing the command.
+ *
+ * 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:
+ * - find the corresponding command template with parser_get_cmd_template()
+ * - extract command arguments with parser_get_cmd_arguments()
+ * - execute the command with parser_execute_cmd()
+ *
+ * You can also provide interactive command line completion using
+ * parser_rl_match().
+ *
+ * Example:
+ * \code
+ * // 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)
+ *
+ * \endcode
+ *
+ * <b>Configuration file</b>: cfg_parser.h
+ *
+ * \author Bernie Innocenti <bernie@codewiz.org>
+ * \author Stefano Fedrigo <aleph@develer.com>
+ * \author Giovanni Bajo <rasky@develer.com>
+ *
+ * $WIZ$ module_name = "parser"
+ * $WIZ$ module_configuration = "bertos/cfg/cfg_parser.h"
+ * $WIZ$ module_depends = "kfile", "hashtable"
+ */
+
+
+#ifndef MWARE_PARSER_H
+#define MWARE_PARSER_H
+
+#include "cfg/cfg_parser.h"
+
+#include <cpu/types.h>
+#include <cfg/debug.h>
+
+/**
+ * Error generated by the commands through the return code.
+ */
+typedef enum
+{
+	RC_ERROR  = -1, ///< Reply with error.
+	RC_OK     = 0,  ///< No reply (ignore reply arguments).
+	RC_REPLY  = 1,  ///< Reply command arguments.
+	RC_SKIP   = 2   ///< Skip following commands
+} ResultCode;
+
+/** union that contains parameters passed to and from commands */
+typedef union { long l; const char *s; } parms;
+/** pointer to commands */
+typedef ResultCode (*CmdFuncPtr)(parms args_results[]);
+
+/**
+ * Define a command that can be tokenized by the parser.
+ *
+ * The format strings are sequences of characters, one for each
+ * parameter/result. Valid characters are:
+ *
+ *  d - a long integer, in decimal format
+ *  s - a var string (in RAM)
+ *
+ * \note To create and fill an instance for this function, it is strongly
+ * advised to use \c DECLARE_CMD_HUNK (cmd_hunk.h).
+ */
+struct CmdTemplate
+{
+	const char *name;          ///< Name of command
+	const char *arg_fmt;       ///< Format string for the input
+	const char *result_fmt;    ///< Format string for the output
+	CmdFuncPtr func;           ///< Pointer to the handler function
+	uint16_t   flags;          ///< Currently unused.
+};
+
+#define REGISTER_FUNCTION parser_register_cmd
+
+/**
+ * Utility function to register a command.
+ *
+ * \param NAME Command name to register
+ */
+#define REGISTER_CMD(NAME) \
+	do { \
+		if (!REGISTER_FUNCTION(&cmd_ ## NAME ## _template)) \
+			ASSERT2(0, "Error in registering command, no space left"); \
+	} while (0)
+
+/**
+ * Utility macro to create a command template.
+ *
+ * It requires that a callback function with name \a cmd_NAME
+ * is already defined.
+ * \param NAME Command name
+ * \param ARGS Input arguments
+ * \param RES Output arguments
+ * \param FLAGS Command flags
+ */
+#define MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS)          \
+const struct CmdTemplate cmd_ ## NAME ## _template =   \
+{                                                      \
+	#NAME, ARGS, RES, cmd_ ## NAME, FLAGS          \
+};
+
+/**
+ * Utility macro to create command templates and callback functions.
+ *
+ * Example for a version command:
+ * \code
+ * MAKE_CMD(ver, "", "ddd",
+ * ({
+ * 	args[1].l = VERS_MAJOR;
+ * 	args[2].l = VERS_MINOR;
+ * 	args[3].l = VERS_REV;
+ * 	RC_OK;
+ * }), 0);
+ * \endcode
+ *
+ * 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.
+ *
+ * \param NAME Command name matched by the parser
+ * \param ARGS Input arguments to the command
+ * \param RES Output arguments of the command
+ * \param BODY Command body, expressed with C 'statement expression'
+ * \param FLAGS Command flags
+ */
+#define MAKE_CMD(NAME, ARGS, RES, BODY, FLAGS)  \
+static ResultCode cmd_ ## NAME (parms *args)    \
+{                                               \
+	return (ResultCode)BODY;                \
+}                                               \
+MAKE_TEMPLATE(NAME, ARGS, RES, FLAGS)
+
+/**
+ * Initialize the parser module
+ *
+ * \note This function must be called before any other function in this module
+ */
+void parser_init(void);
+
+bool parser_register_cmd(const struct CmdTemplate* cmd);
+
+
+/**
+ * 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.
+ */
+const char* parser_rl_match(void* dummy, const char* word, int word_len);
+
+bool parser_process_line(const char* line);
+
+/**
+ * Execute a command with its arguments, and fetch its results.
+ *
+ * The \a args paramenter is value-result: it provides input arguments to
+ * the callback function and it stores output values on return.
+ *
+ * \param templ Template of the command to be executed
+ * \param args Arguments for the command, and will contain the results
+ *
+ * \return False if the command returned an error, true otherwise
+ */
+INLINE bool parser_execute_cmd(const struct CmdTemplate* templ, parms args[CONFIG_PARSER_MAX_ARGS])
+{
+	return (templ->func(args) == 0);
+}
+
+const struct CmdTemplate* parser_get_cmd_template(const char* line);
+
+bool parser_get_cmd_arguments(const char* line, const struct CmdTemplate* templ, parms args[CONFIG_PARSER_MAX_ARGS]);
+
+#if CONFIG_ENABLE_COMPAT_BEHAVIOUR
+/**
+ * Extract the ID from the command text line.
+ *
+ * \param line Text line to be processed (ASCIIZ)
+ * \param ID Will contain the ID extracted.
+ *
+ * \return True if everything ok, false if there is no ID
+ *
+ */
+bool parser_get_cmd_id(const char* line, unsigned long* ID);
+#endif
+
+
+/** \} */ // defgroup parser
+#endif /* MWARE_PARSER_H */
+