Lightweight command interpreter implemented as a protothreads. More...

Data Structures
struct	console_cmd_t
	Console command descriptor. More...

struct	console
	Console descriptor. More...

struct	console_gpio_t
	GPIO command descriptor. More...

Macros
#define	CONSOLE_CMD_VAR_INIT(n, f)

#define	SCRATCH_SIZE 80

#define	CONSOLE_GPIO_VAR_INIT(name, port_, pin_, flags_)

Typedefs
typedef struct console	console_t
	Console descriptor. More...

Enumerations
enum	console_gpio_flags_t { console_gpio_active_low = 0x01, console_gpio_default_on = 0x02, console_gpio_open_drain = 0x04, console_gpio_explore = 0x08 }
	Request special features from the GPIO command. More...

Functions
void	console_init (console_t c, FILE f)
	Initialized the console handler. More...

void	console_hwinit (console_t *c)
	Platform dependant function that will be called during console_init(). More...

int	console_register (const console_cmd_t *cmd)
	Register a new command. More...

void	console_putchar (console_t *c, char d)
	Asynchronously send a character to the command processor. More...

pt_state_t	console_eval (pt_t pt, console_t c, const char *cmd)
	Proto-thread to inject a string into the command parser. More...

int	console_getch (console_t *c)
	Fetch a character from the command processors queue. More...

pt_state_t	console_run (console_t *c)
	Console protothread entrypoint. More...

void	console_process (console_t *c, char d)
	Synchronous console function for use in threaded environments. More...

int	console_gpio_register (const console_gpio_t *gpio)
	Register a new GPIO command. More...

Detailed Description

Lightweight command interpreter implemented as a protothreads.

The use of protothreads means this command interpreter can be used effectively on run-to-completion schedulers and comes with out of the box support for fibres.

Note: The use of the fibre scheduler is optional (although the fibre header file is needed to compile source without modification).

No dynamic memory allocation is required by the console handling (although currently it uses stdio.

Macro Definition Documentation

#define CONSOLE_CMD_VAR_INIT	(	n,
		f
	)

Value:

{                                                                      \
                .name = (n),                                                   \
                .fn = (f)                                                      \
        }

Definition at line 52 of file console.h.

#define CONSOLE_GPIO_VAR_INIT	(	name,
		port_,
		pin_,
		flags_
	)

Value:

{                                                                      \
                .cmd = CONSOLE_CMD_VAR_INIT(name, console_gpio_do_cmd),        \
                .port = port_, .pin = pin_, .flags = flags_                    \
        }

Definition at line 263 of file console.h.

#define SCRATCH_SIZE 80

Definition at line 58 of file console.h.

Typedef Documentation

typedef struct console console_t

Console descriptor.

This is a relatively large structure (164 bytes on a 32-bit machine) due to the integrated scratch array.

Enumeration Type Documentation

enum console_gpio_flags_t

Request special features from the GPIO command.

Enumerator
console_gpio_active_low
console_gpio_default_on
console_gpio_open_drain
console_gpio_explore

Definition at line 238 of file console.h.

Function Documentation

pt_state_t console_eval	(	pt_t *	pt,
		console_t *	c,
		const char *	cmd
	)

Proto-thread to inject a string into the command parser.

When buffering is already happening somewhere else in the system then this is a safe alternative to console_putchar() since it will yield rather than dropping input during overflow conditions.

Definition at line 189 of file console.c.

int console_getch ( console_t * c )

Fetch a character from the command processors queue.

This function is used internally by the command processor and may also be used by console commands to read character input from the user. It must not be called outside of console command handling (because it will race with the command processor to handle the character).

It is safe to use PT_WAIT_UNTIL() to wait until a character is received because the console fibre, which is used to execute console commands, will be woken up for each new character received.

 // ch need not be static unless the it is used after another wait.
 int ch;
 PT_WAIT_UNTIL((ch = console_getchar(c)) != -1);

Definition at line 172 of file console.c.

int console_gpio_register ( const console_gpio_t * gpio )

Register a new GPIO command.

Definition at line 211 of file console_cmd_gpio.c.

void console_hwinit ( console_t * c )

Platform dependant function that will be called during console_init().

librfn provides example implementations of this function but, in some cases, this function must be provided by the application.

Definition at line 369 of file console_cdcacm.c.

void console_init	(	console_t *	c,
		FILE *	f
	)

Initialized the console handler.

Parameters

c	Pointer to console descriptor
f	File pointer to be used for all console output

Definition at line 136 of file console.c.

void console_process	(	console_t *	c,
		char	d
	)

Synchronous console function for use in threaded environments.

This function can also be used to implement a command console that executes from an interrupt handler. Such a command interpreter would be extremely robust although potentially at the cost of poor interrupt latencies.

To use this function console_hwinit() may have to altered to remove code that asynchronously delivers characters.

1 while ((ch = getchar()) != -1)

2 console_process(console, ch);

Definition at line 254 of file console.c.

void console_putchar	(	console_t *	c,
		char	d
	)

Asynchronously send a character to the command processor.

This function is safe to call from interrupt. It will insert a character into the command processors ring buffer and will, optionally, schedule the console fibre.

Definition at line 177 of file console.c.

int console_register ( const console_cmd_t * cmd )

Register a new command.

The following example shows a simple protothreaded command to list the command's arguments:

 static pt_state_t listargs(console_t *c)
 {
     static int i;
     PT_BEGIN(&c->pt);
 
     for (i=0; i<c->argc; i++) {
         fprintf(c->out, "%d: %s\n", i, c->argv[i]);
         PT_YIELD();
     }
 
     PT_END();
 }
 static const console_cmd_t cmd_listagrs =
     CONSOLE_CMD_VAR_INIT("listargs", listargs);
 
 (void) console_register(cmd_listargs);

The use of protothreading is optional. The following command is functionally equivalent although may cause a run-to-completion scheduler to run poorly if fprintf() is slow (for example if it synchronously sends characters to a serial port):

 pt_state_t listargs(console_t *c)
 {
     for (int i=0; i<c->argc; i++)
         fprintf(c->out, "%d: %s\n", i, c->argv[i]);
     return PT_EXITED;
 }

Definition at line 151 of file console.c.

pt_state_t console_run ( console_t * c )

Console protothread entrypoint.

This function can be used to integrate the command processor into simple polling loops or to "alien" run-to-completion schedulers.

The return code can be used to realize power saving modes. However a simple polling loop without support for power saving can simply ignore it.

 while (true) {
     poll_something();
     (void) console_run(console); // poll console
     poll_something_else();
 }

Definition at line 217 of file console.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation