page_console.c File Reference

The bench console: command lines read and written as link page requests and replies. More...

#include "page_console.h"
#include <stdarg.h>
#include <stdio.h>
#include <string.h>
#include "hitec_wire.h"

Data Structures
struct	hitec_args_t
	The options of send, listen and power, and the bytes of a send. More...

Macros
#define	TOKENS_MAX   40u
#define	say   page_console_say
	The console's own lines.
#define	NAME(table, v)
	The name of value v in table, or "?".
#define	HST(c, reg)
	The staged HITEC register reg of console c.
#define	RUN_AT(reg)

Functions
static void	push (page_console_t *c, const char *s, size_t n)
	Append n bytes of s to the output, or drop them and count the loss.
void	page_console_vsay (page_console_t *c, const char *fmt, va_list ap)
	page_console_say() with a va_list.
void	page_console_say (page_console_t *c, const char *fmt,...)
	One line of output from outside the console, formatted as printf() formats: the LF is added, and one the text ends with is not doubled.
static size_t	take_out (page_console_t *c, char *buf, size_t n)
	Move n bytes from the head of the output to buf.
size_t	page_console_take (page_console_t *c, char *buf, size_t room)
	Whole lines of output, at most room bytes; the bytes copied.
size_t	page_console_take_part (page_console_t *c, char *buf, size_t room)
	The first room bytes of output, a line cut where the room ends: a line longer than room leaves in pieces, and the rest of it comes first in the next take.
static const char *	name_of (const char *const *names, unsigned count, unsigned v)
	The name of value v from a table of names.
static bool	apply (page_console_t *c, uint8_t op, uint8_t page, uint8_t off, uint8_t n, const uint16_t *in)
	A read or a write through the link's handlers; the reply.
static bool	read_regs (page_console_t *c, uint8_t page, uint8_t off, uint8_t n, uint16_t *out)
	Read n registers of a page through the link.
static bool	write_regs (page_console_t *c, uint8_t page, uint8_t off, uint8_t n, const uint16_t *in)
	A write; false, with the refusal said, when it is not acknowledged.
static bool	parse_u32 (const char *s, uint32_t *out)
	Parse an unsigned number, decimal or 0x hexadecimal.
static bool	parse_max (const char *s, uint32_t max, uint32_t *out)
	Parse an unsigned number no larger than max.
static const char *	value_of (const char *tok, const char *key)
	"key=value": the value when tok starts with key and '='.
static unsigned	split (char *line, char **tok)
	Split a line into tokens at spaces and tabs.
static void	say_regs (page_console_t *c, const char *what, uint8_t page, uint8_t off, uint8_t n, const uint16_t *regs)
	The reply's registers: up to 32 of 7 characters each, so the line is made in two halves of 16 when it is long.
static void	cmd_pages (page_console_t *c)
	Answer the pages command: one line per page.
static void	cmd_read (page_console_t *c, char **tok, unsigned n)
	Answer the r command: read n registers and reply with them.
static void	cmd_write (page_console_t *c, char **tok, unsigned n)
	Answer the w command: write the values and reply with the acknowledgement.
static void	hst32 (page_console_t *c, unsigned lo, uint32_t v)
	Stage a 32-bit value in two HITEC registers, low word first.
static uint32_t	u32_of (const uint16_t *r, unsigned lo)
	Read a 32-bit value from two registers, low word first.
static void	say_flags (char *buf, size_t size, uint16_t st)
	Write the names of the STATE flags set in st, comma separated, or "-".
static void	hitec_report (page_console_t *c, const char *what)
	What the page says now: the state line, and the capture with its bytes when it holds one.
static void	hitec_command (page_console_t *c, link_hitec_op_t op, uint32_t port, bool key)
	Stage, name the CRC and the next SEQ, and send the command.
static bool	parse_dec (const char *v, uint16_t *out)
	dec=none | c:<cmd> | d:<addr> | l:<byte>
static bool	parse_args (page_console_t *c, char **tok, unsigned n, hitec_args_t *a)
	Parse the options and the bytes of send, listen, power and level.
static void	stage_xfer (page_console_t *c, const hitec_xfer_t *x, uint16_t dec)
	The staged registers of a transaction; LINE and the supply's are 0.
static bool	parse_port (page_console_t *c, const char *tok, uint32_t *port)
	Parse a programming port number, 0 to 15.
static void	hitec_open (page_console_t *c, uint32_t port, char **tok, unsigned n)
	Answer hitec open: OPEN the port with the family, drive and receive mode.
static bool	open_family (page_console_t *c, uint8_t *family)
	The family of the open line, from the page; false when none is open.
static void	hitec_send (page_console_t *c, uint32_t port, char **tok, unsigned n)
	Answer hitec send: transmit the bytes in one transaction.
static void	hitec_listen (page_console_t *c, uint32_t port, char **tok, unsigned n, bool power)
	Answer hitec listen or hitec power, the listen part of it.
static void	hitec_level (page_console_t *c, uint32_t port, char **tok, unsigned n)
	Answer hitec level: hold the line at a level for a time.
static bool	family_is (page_console_t *c, uint8_t family)
	Whether the open line is of family; says why not.
static void	hitec_classic (page_console_t *c, uint32_t port, char **tok, unsigned n)
	Answer hitec c: one classic command and its reply.
static void	hitec_d (page_console_t *c, uint32_t port, char **tok, unsigned n)
	Answer hitec d: one D series read or write.
static void	cmd_hitec (page_console_t *c, char **tok, unsigned n)
	Answer the hitec command and route it by its subcommand.
static void	cmd_help (page_console_t *c)
	Answer the help command: the command list.
static void	run_line (page_console_t *c)
	Run the command line held in the console.
void	page_console_init (page_console_t *c, const link_dev_t *dev)
	An empty console on the pages of dev.
void	page_console_key (page_console_t *c, int ch)
	One character in.
void	page_console_poll (page_console_t *c)
	Once a pass: the report of a HITEC operation that has ended.

Variables
static const char *const	k_nack []
static const char *const	k_state []
static const char *const	k_op []
static const char *const	k_result []
static const char *const	k_refusal []
static const char *const	k_dec [] = { "NONE", "C", "D", "LISTEN" }
static const char *const	k_rx []

Detailed Description

The bench console: command lines read and written as link page requests and replies.

SPDX-License-Identifier: MIT

Macro Definition Documentation

HST

#define HST	(		c,
			reg )

Value:

((c)->staged[(reg) - LINK_HT_W_LINE])

The staged HITEC register reg of console c.

NAME

#define NAME	(		table,
			v )

Value:

name_of((table), sizeof(table) / sizeof((table)[0]), (v))

The name of value v in table, or "?".

RUN_AT

#define RUN_AT

(

reg

)

Value:

((reg) - LINK_HT_DATA)

Function Documentation

apply()

bool apply ( page_console_t * c, uint8_t op, uint8_t page, uint8_t off, uint8_t n, const uint16_t * in )

static

A read or a write through the link's handlers; the reply.

The reply is c->reply.

Parameters

c	The console.
op	The operation, LINK_OP_READ or LINK_OP_WRITE.
page	The page number.
off	First register of the window.
n	Number of registers.
in	The n values to write; NULL for a read.

Returns

true when the link device answered; the reply is c->reply.

cmd_help()

void cmd_help ( page_console_t * c )

static

Answer the help command: the command list.

Parameters

c	The console.

cmd_hitec()

void cmd_hitec ( page_console_t * c, char ** tok, unsigned n )

static

Answer the hitec command and route it by its subcommand.

Parameters

c	The console.
tok	The tokens of the line.
n	Number of tokens.

cmd_pages()

void cmd_pages ( page_console_t * c )

static

Answer the pages command: one line per page.

Parameters

c	The console.

cmd_read()

void cmd_read ( page_console_t * c, char ** tok, unsigned n )

static

Answer the r command: read n registers and reply with them.

Parameters

c	The console.
tok	The tokens of the line.
n	Number of tokens.

cmd_write()

void cmd_write ( page_console_t * c, char ** tok, unsigned n )

static

Answer the w command: write the values and reply with the acknowledgement.

Parameters

c	The console.
tok	The tokens of the line.
n	Number of tokens.

family_is()

bool family_is ( page_console_t * c, uint8_t family )

static

Whether the open line is of family; says why not.

A frame of one family on a line of the other goes out at the wrong rate and polarity.

Parameters

c	The console.
family	The family the command needs.

Returns

true when the open line is of family; false otherwise, with the error said.

hitec_classic()

void hitec_classic ( page_console_t * c, uint32_t port, char ** tok, unsigned n )

static

Answer hitec c: one classic command and its reply.

Parameters

c	The console.
port	Programming port index.
tok	The tokens after the port.
n	Number of tokens.

hitec_command()

void hitec_command ( page_console_t * c, link_hitec_op_t op, uint32_t port, bool key )

static

Stage, name the CRC and the next SEQ, and send the command.

Parameters

c	The console.
op	The operation.
port	Programming port index.
key	true to put LINK_HITEC_WRITE_KEY in the command.

hitec_d()

void hitec_d ( page_console_t * c, uint32_t port, char ** tok, unsigned n )

static

Answer hitec d: one D series read or write.

Parameters

c	The console.
port	Programming port index.
tok	The tokens after the port.
n	Number of tokens.

hitec_level()

void hitec_level ( page_console_t * c, uint32_t port, char ** tok, unsigned n )

static

Answer hitec level: hold the line at a level for a time.

Parameters

c	The console.
port	Programming port index.
tok	The tokens after the port.
n	Number of tokens.

hitec_listen()

void hitec_listen ( page_console_t * c, uint32_t port, char ** tok, unsigned n, bool power )

static

Answer hitec listen or hitec power, the listen part of it.

Parameters

c	The console.
port	Programming port index.
tok	The tokens after the port.
n	Number of tokens.
power	true for hitec power.

hitec_open()

void hitec_open ( page_console_t * c, uint32_t port, char ** tok, unsigned n )

static

Answer hitec open: OPEN the port with the family, drive and receive mode.

Parameters

c	The console.
port	Programming port index.
tok	The tokens after the port.
n	Number of tokens.

hitec_report()

void hitec_report ( page_console_t * c, const char * what )

static

What the page says now: the state line, and the capture with its bytes when it holds one.

Parameters

c	The console.
what	The word that opens the report, such as done.

hitec_send()

void hitec_send ( page_console_t * c, uint32_t port, char ** tok, unsigned n )

static

Answer hitec send: transmit the bytes in one transaction.

Parameters

c	The console.
port	Programming port index.
tok	The tokens after the port.
n	Number of tokens.

hst32()

void hst32 ( page_console_t * c, unsigned lo, uint32_t v )

static

Stage a 32-bit value in two HITEC registers, low word first.

Parameters

c	The console.
lo	Register number of the low word.
v	The value.

name_of()

const char * name_of ( const char *const * names, unsigned count, unsigned v )

static

The name of value v from a table of names.

Parameters

names	The table of names.
count	Entries in the table.
v	The value to name.

Returns

The name of v, or "?" when v is out of range or has no name.

open_family()

bool open_family ( page_console_t * c, uint8_t * family )

static

The family of the open line, from the page; false when none is open.

Parameters

c	The console.
family	Receives the family of the open line.

Returns

true when a line is open; false when none is open.

page_console_init()

void page_console_init	(	page_console_t *	c,
		const link_dev_t *	dev )

An empty console on the pages of dev.

Parameters

c	The console; zeroed first. A NULL c is ignored.
dev	The link device whose pages the console reads and writes.

page_console_key()

void page_console_key	(	page_console_t *	c,
		int	ch )

One character in.

CR or LF runs the line.

Parameters

c	The console.
ch	The character; a value below 0 is ignored, and so is a control character other than CR, LF, BS and DEL.

page_console_poll()

void page_console_poll

(

page_console_t *

c

)

Once a pass: the report of a HITEC operation that has ended.

Parameters

c	The console.

page_console_say()

void page_console_say	(	page_console_t *	c,
		const char *	fmt,
			... )

One line of output from outside the console, formatted as printf() formats: the LF is added, and one the text ends with is not doubled.

At most PAGE_CONSOLE_OUT_LINE bytes with the LF; a longer text is cut.

Parameters

c	The console.
fmt	The printf format.
...	The arguments of fmt.

page_console_take()

size_t page_console_take	(	page_console_t *	c,
		char *	buf,
		size_t	room )

Whole lines of output, at most room bytes; the bytes copied.

A line longer than room does not leave: a caller whose room can be smaller than PAGE_CONSOLE_OUT_LINE takes with page_console_take_part().

Parameters

c	The console.
buf	Receives the bytes.
room	Size of buf in bytes.

Returns

The number of bytes copied, whole lines only; 0 for a NULL c or buf.

page_console_take_part()

size_t page_console_take_part	(	page_console_t *	c,
		char *	buf,
		size_t	room )

The first room bytes of output, a line cut where the room ends: a line longer than room leaves in pieces, and the rest of it comes first in the next take.

Any room from 1 byte on moves the output. A caller that takes in parts keeps to this function: page_console_take() leaves a part-taken line where it is until the rest of it fits.

Parameters

c	The console.
buf	Receives the bytes.
room	Size of buf in bytes.

Returns

The number of bytes copied; 0 for a NULL c or buf.

page_console_vsay()

void page_console_vsay	(	page_console_t *	c,
		const char *	fmt,
		va_list	ap )

page_console_say() with a va_list.

Parameters

c	The console.
fmt	The printf format.
ap	The argument list, started by the caller.

parse_args()

bool parse_args ( page_console_t * c, char ** tok, unsigned n, hitec_args_t * a )

static

Parse the options and the bytes of send, listen, power and level.

Parameters

c	The console.
tok	The tokens of the line.
n	Number of tokens.
a	Receives the options and the bytes.

Returns

true when every token parses; otherwise false, with the bad token said.

parse_dec()

bool parse_dec ( const char * v, uint16_t * out )

static

dec=none | c:<cmd> | d:<addr> | l:<byte>

Parameters

v	The text after dec=.
out	Receives the packed decoder word.

Returns

true when the text parses.

parse_max()

bool parse_max ( const char * s, uint32_t max, uint32_t * out )

static

Parse an unsigned number no larger than max.

Parameters

s	The text, as parse_u32() reads it.
max	The largest value accepted.
out	Receives the value.

Returns

true when parse_u32() accepts the text and the value is at most max.

parse_port()

bool parse_port ( page_console_t * c, const char * tok, uint32_t * port )

static

Parse a programming port number, 0 to 15.

Parameters

c	The console.
tok	The token.
port	Receives the port.

Returns

true when the token is a port number; otherwise false, with the error said.

parse_u32()

bool parse_u32 ( const char * s, uint32_t * out )

static

Parse an unsigned number, decimal or 0x hexadecimal.

Parameters

s	The text: decimal, or hexadecimal after 0x.
out	Receives the value.

Returns

true when the text has at least one digit and its value fits 32 bits.

push()

void push ( page_console_t * c, const char * s, size_t n )

static

Append n bytes of s to the output, or drop them and count the loss.

Parameters

c	The console.
s	The bytes.
n	Number of bytes.

read_regs()

bool read_regs ( page_console_t * c, uint8_t page, uint8_t off, uint8_t n, uint16_t * out )

static

Read n registers of a page through the link.

Parameters

c	The console.
page	The page number.
off	First register of the window.
n	Number of registers to read.
out	Receives the n register values.

Returns

true when the reply is data; false otherwise.

run_line()

void run_line ( page_console_t * c )

static

Run the command line held in the console.

Parameters

c	The console.

say_flags()

void say_flags ( char * buf, size_t size, uint16_t st )

static

Write the names of the STATE flags set in st, comma separated, or "-".

Parameters

buf	Receives the text, NUL-terminated.
size	Size of buf in bytes.
st	The STATE register value.

say_regs()

void say_regs ( page_console_t * c, const char * what, uint8_t page, uint8_t off, uint8_t n, const uint16_t * regs )

static

The reply's registers: up to 32 of 7 characters each, so the line is made in two halves of 16 when it is long.

Parameters

c	The console.
what	The word that opens the line, such as data or ack.
page	The page number.
off	First register of the window.
n	Number of registers.
regs	The register values.

split()

unsigned split ( char * line, char ** tok )

static

Split a line into tokens at spaces and tabs.

Parameters

line	The line; each separator is replaced by a NUL.
tok	Receives a pointer to each token, TOKENS_MAX entries.

Returns

The number of tokens.

stage_xfer()

void stage_xfer ( page_console_t * c, const hitec_xfer_t * x, uint16_t dec )

static

The staged registers of a transaction; LINE and the supply's are 0.

Parameters

c	The console.
x	The transaction to stage.
dec	The packed decoder word.

take_out()

size_t take_out ( page_console_t * c, char * buf, size_t n )

static

Move n bytes from the head of the output to buf.

Parameters

c	The console.
buf	Receives the bytes.
n	Number of bytes to take from the head of the output.

Returns

n, the bytes taken.

u32_of()

uint32_t u32_of ( const uint16_t * r, unsigned lo )

static

Read a 32-bit value from two registers, low word first.

Parameters

r	The register values.
lo	Index of the low word.

Returns

The value.

value_of()

const char * value_of ( const char * tok, const char * key )

static

"key=value": the value when tok starts with key and '='.

Parameters

tok	A token of the line.
key	The key to match.

Returns

The text after the '=' when tok is key=value, otherwise NULL.

write_regs()

bool write_regs ( page_console_t * c, uint8_t page, uint8_t off, uint8_t n, const uint16_t * in )

static

A write; false, with the refusal said, when it is not acknowledged.

Parameters

c	The console.
page	The page number.
off	First register of the window.
n	Number of registers to write.
in	The n register values.

Returns

true when the device acknowledges the write; false otherwise, with the refusal said.

Variable Documentation

k_nack

const char* const k_nack[]

static

Initial value:

                               = {
    "OK", "BAD_PAGE", "BAD_RANGE", "READ_ONLY", "BAD_VALUE", "NOT_ARMED",
    "BUSY",
}

k_op

const char* const k_op[]

static

Initial value:

                             = {
    "NONE", "OPEN", "CLOSE", "SEND", "LISTEN", "LEVEL", "ABORT", "POWER",
    "CLEAR",
}

k_refusal

const char* const k_refusal[]

static

Initial value:

                                  = {
    "NONE", "BUSY", "PORT", "HELD", "ARMED", "UNSAFE", "NOT_OPEN", "NO_KEY",
    "STAGED", "STOPPED", "NO_PIN", "RANGE", "SUPPLY_RANGE", "NO_SUPPLY",
}

k_result

const char* const k_result[]

static

Initial value:

                                 = {
    "NONE", "RUNNING", "DONE", "SUPPLY", "START", "NO_LINE", "CUT",
}

k_rx

const char* const k_rx[]

static

Initial value:

                             = {
    "OK", "ARG", "ABORTED", "OVERFLOW", "SILENT", "EARLY", "LATE", "NAK",
    "LENGTH", "FRAMING", "GAP", "ACK", "HEADER", "ADDRESS", "SUM",
}

k_state

const char* const k_state[]

static

Initial value:

                                = {
    "FREE", "STOPPING", "OPEN", "BUSY", "POWER_OFF",
}