page_console.h File Reference

A bench console: link pages read and written from command lines, through the page handlers the link uses. More...

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "link_dev.h"
#include "link_pages.h"

Go to the source code of this file.

Data Structures
struct	page_console_t
	The console state: the command line being read, the output buffer, the staged HITEC registers and the work space of the requests. More...

Macros
#define	PAGE_CONSOLE_LINE_MAX   160u
	The longest command line, without its end.
#define	PAGE_CONSOLE_OUT_LINE   200u
	The longest output line, with its LF.
#define	PAGE_CONSOLE_OUT_MAX   2048u
	The output buffer.

Functions
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.
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.
void	page_console_vsay (page_console_t *c, const char *fmt, va_list ap)
	page_console_say() with a va_list.
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.

Detailed Description

A bench console: link pages read and written from command lines, through the page handlers the link uses.

A bench tool, not part of a released image: the IOmcu builds it only with the build option IOMCU_CONSOLE (firmware/iomcu/CMakeLists.txt) and reads its lines from the USB (Universal Serial Bus) serial port.

Every request goes through link_dev_apply(): the page table, the range checks, the handlers and their refusals are the link's. Whatever a page refuses to the panel it refuses here: a write of ARM while the arm latch is set, a HITEC or KST transaction without the write key, a supply ON without a heartbeat. A request from here is not link traffic: it does not hold the link's silence failsafe off (LINK_DEV_SILENCE_MS, 200ms). Every page that needs a trusted heartbeat and a link that is not silent needs a running panel beside the console.

Lines end with CR or LF; tokens are separated by spaces; numbers are decimal or 0x hexadecimal. Commands:

help the commands pages each page: number, registers, rw or ro r <page> <off> [n] read n registers (1 to 32, default 1) w <page> <off> <v> [v ...] write up to 32 registers hitec [state] the HITEC page, decoded hitec open <port> c|d [od|pp] [pu|pre] OPEN: classic or D series, open drain (default) or push-pull; for the D series pu or pre writes the receive mode, PULL-UP or PRECHARGE, first (register 23), and without either the mode stays as the page holds it hitec close|abort|clear <port> hitec send <port> [lead=<us>] [gap=<bits>] [window=<us>] [rx=<n>] [dec=<dec>] <byte> [<byte> ...] hitec listen <port> window=<us> rx=<n> [answer=<byte>] [dec=<dec>] hitec level <port> 0|1 <us> hitec power <port> mv=<mV> ma=<mA> off=<ms> window=<us> rx=<n> [answer=<byte>] [dec=<dec>] hitec c <port> <cmd> <p1> <p2> a classic command and its reply hitec d <port> read <id> <addr> a D series read and its answer hitec d <port> write <id> <addr>

<dec> is none, c:<cmd>, d:<addr> or l:<byte> (link_hitec_dec_t and its argument). The hitec commands stage the HITEC page's registers, name their CRC (cyclic redundancy check) and the next SEQ, and put LINK_HITEC_WRITE_KEY in every command that puts a byte on the wire. A command that starts something is followed by its report when the port has finished it: hitec done, hitec cap and one hitec byte line per byte received. A raw w of the HITEC page gets none of this.

Replies, one line each: data, ack, nack, err, page, hitec.

The output is a buffer of PAGE_CONSOLE_OUT_MAX bytes of whole lines; what does not fit is dropped and counted, and a line says how many bytes were lost. It is taken in whole lines, or with page_console_take_part() as a stream that cuts a line where the caller's room ends. Lines from outside the console (page_console_say()) go into the same buffer, so they leave in the order they were said and never inside another line.

Pure logic with no hardware: the caller feeds characters and takes the output.

SPDX-License-Identifier: MIT

Function Documentation

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.