Subsystem Module

Data Structures
struct	version_mmb_t
union	version_t
	version union More...

Macros
#define	SYSTEM_VERSION   0x03010001u
	subsystem module version number
#define	RECEIVE_MAX_LENGTH   64
	default length of receive line for commands
#define	RECEIVE_START_CHAR   '$'
	start character for command lines
#define	RECEIVE_STOP_CHAR   '\r'
	stop character for command lines
#define	RECEIVE_MAX_ARGC   8
	max number of arguments after the command name
#define	GetLogTimestamp()   TimeNow()

Functions
void	LogStr (char *str,...)
void	LogMsg (uint8_t subsystem_id, char *str,...)
uint8_t	Subsystem_Init (char *name, version_t version, void(*callback)(int argc, char *argv[]))
void	Subsystem_RegisterCallback (uint8_t subsystem_id, void(*callback)(int argc, char *argv[]))
char *	GetSubsystemName (uint8_t subsystem_id)
void	Log_EchoOn (void)
void	Log_EchoOff (void)
uint8_t	Log_GetEcho (void)
void	Log_Header (uint8_t subsystem_id)
void	MuteAll (void)
void	UnmuteAll (void)
void	MuteSys (uint8_t sys_id)
void	UnmuteSys (uint8_t sys_id)
uint16_t	ArgToU16 (char *arg)
uint8_t	ArgToU8 (char *arg)
uint32_t	ArgToU32 (char *arg)

Detailed Description

Created on: Mar 12, 2014

Author

: Michael

Version

2014.03.26 changed SystemTick to SubsystemTick so the Task Management Module can own SystemTick()

2.0.1 added version, setup SYSTEM subsystem, changed warning messages to priority WARNING and set default priority to ERROR to suppress messages

3.1.1 removed log levels and redueced to mute or unmute. Moved receiver functionality to UART module. Changed callback to take argc argv inputs and added parsing to create argc and argv.

SubSystem module command interface

If bi-directional communication is available (e.g. UART) then the user can interface with the SubSystem module in real time using the module's command interface.A command can be sent to the module in the following format:

$command -f0

Where the $ indicates the start of the command, command is the name of the command and -f8 is a flag with a value of 8.
Valid system flags are -s, -l and -g The commands available are:version (or ver) - will output a list of subsystems and their version. No flags are applicable.level (or lev) - if no flags are given level will output level a list of valid level codes and their names as used in the log messages. If a -l flag is given but not a -s flag then the level specified with the -l flag is set as the global level. If the -l and -s flags are given then set the level specified with the -l flag for the subsystem specified with the -s flag. If a -g flag is given it will set the global log level to the specified value. The global log level will for any message from any subsystem to be logged if its level is at the global level or below.subsystem (or sub or sys or system) - will output a list of valid subsystem codes and their associated subsystem names and their current log level setting as used by the log message functions. The -s flag can be used to return only information about the specified subsystem.Example usage:

$version

$sub

$level

$level -l0

$level -s0 -l2

In the above example:

• output the subsystems and their versions
• output the subsystems and their codes
• output the log levels and their codes
• set the global log level to 0 (OFF)
• set the log level for subsystem 0 (SYSTEM) is set to 2 (ERROR).

The end result is that no messages would be logged unless they were SYSTEM messages with a priority level greater than or equal to ERROR (note higher priority is lower numerically).Additionally commands may be forwarded to the callback of compatible subsystems using the following format

$12 command <anything goes>
$MUH play

In the first line subsystem index 12 is sent the command string starting after the space. In the second line a module named MUH is sent a command "play"

Todo:

MM Update this comment block

Subsystem module initialization

Below are three example of how a subsystem could initialize itself.

// define the version
#define TASK_VERSION (version_t)0x01010014u

// initialize module to log EVERYTHING and to use "task" to refer
// to this subsystem in output messages
SubsystemInit(TASK, EVERYTHING, "task", TASK_VERSION);

// or another way to do the same thing

#define TASK_VERSION_MAJOR 1
#define TASK_VERSION_MINOR 1
#define TASK_VERSION_BUILD 20

version_t task_version;
task_version.major = TASK_VERSION_MAJOR;
task_version.minor = TASK_VERSION_MINOR;
task_version.build = TASK_VERSION_BUILD;

SubsystemInit(TASK, EVERYTHING, "task", task_version);

// or to do it all in one line
uint8_t task_id;
task_id = SubsystemInit(EVERYTHING, "task", (version_t)0x01010014u);
LogMsG(task_id, WARNING, "Crap hit the fan");

Todo:

MM Update this comment block

Macro Definition Documentation

#define GetLogTimestamp

(

)

TimeNow()

GetLogTimestamp must be defined so that it returns a integer (up to 32 bits) timestamp

Function Documentation

char* GetSubsystemName

(

uint8_t

subsystem_id

)

Return a pointer to a string corresponding to the name of the subsystem

The name returned is the one set by SubsystemInit()

Parameters

subsystem_id

Returns

- pointer to a null terminated string corresponding to the name of the subsystem

void Log_EchoOff

(

void

)

Turn echo feature off

void Log_EchoOn

(

void

)

Turn echo featuren on (default is off)

uint8_t Log_GetEcho

(

void

)

Get status of echo setting

Returns

echo setting, 1 if echo is on

void Log_Header

(

uint8_t

subsystem_id

)

Log header (timestamp and subsystem name)

Parameters

subsystem_id

subsystem id (index)

void LogMsg	(	uint8_t	subsystem_id,
		char *	str,
			...
	)

Logs the message at the pointer (str) with a timestamp and subsystem name

Before logging the message the function will check the current log setting of the subsystem and to determine if the message should be logged

This function is implemented using Push_vprintf. See Push_printf() for supported flags/features.

Will log the string to the buffer defined by SUSSYS_UART

Parameters

subsystem_id	subsystem id
str	pointer to message to log
...	variable number of replacement parameters for the str string

Example usage:

LogMsg(sys.id, "oops I crapped my pants");
LogMsg(sys.id, "System Index %d, System Name %s.", sys.id, GetSubsystemName(SYSTEM));

void LogStr	(	char *	str,
			...
	)

Logs the null terminated string at the pointer (str)

Same as LogMsg() without the header in the beginning and without the CRLF at the end.

This function is implemented using Push_vprintf. See Push_printf() for supported flags/features.

Will log the string to the buffer defined by LOG_BUF (typically tx0)

Parameters

str	pointer to string to log
...	variable number of replacement parameters for the str string

Example usage:

LogStr("oops I crapped my pants");
LogStr("System Index %d, System Name %s.", SYSTEM, GetSubsystemName(SYSTEM));

void MuteAll

(

void

)

Mute all log messages

void MuteSys

(

uint8_t

sys_id

)

Mute messages from certain sys_id

uint8_t Subsystem_Init	(	char *	name,
		version_t	version,
		void(*)(int argc, char *argv[])	callback
	)

Initialize settings for a subsystem - critical for proper logging and command interface

If a module/subsystem uses logging it should call this function with the appropriate inputs when the subsystem is initializing.

Returns

subsystem index

Parameters

name	pointer to name of the subsystem (recommended to make the name 8 characters or less)
version	software version of subsystem, see version_t for more info
callback	callback function to be called when the user inputs a command in the form of "$name var1 var2 var3...". Where name is the name passed to this function. The callback will be passed the number of arguments, argc , and a array of pointers to the argument strings, argv.

void Subsystem_RegisterCallback	(	uint8_t	subsystem_id,
		void(*)(int argc, char *argv[])	callback
	)

Register a callback function for a subsystem

When a command is received by the logging module for the subsystem sys the callback function will be executed and passed the number of arguments argc and a array (vector) of pointer to the argument strungs argv.

The callback is set by Subsystem_Init(), this function can be used to update the callback.

Parameters

subsystem_id	- subsystem to register the callback for
callback	- function pointer to the function to run when a command is received for the subsystem.

void UnmuteAll

(

void

)

Global unmute

void UnmuteSys

(

uint8_t

sys_id

)

Unmute messages from certain sys_id