CH1's 1ms samples as text lines: core 0's side. More...

#include "sense_trace.h"
#include <string.h>

Data Structures
struct	line_t
	One line of the file text, without its line end. More...

Macros
#define	META_KIND(m)
#define	META_LOST(m)

Enumerations
enum	place_t { TRIG_LOST = 0 , TRIG_PLACED , TRIG_WAITS }
	Where a trigger went.
enum	act_t { ACT_NONE = 0 , ACT_STAGE , ACT_MARK , ACT_MARK_STALLED , ACT_LOST , ACT_LOST_AHEAD , ACT_REC , ACT_END , ACT_END_SETUP }
	What writing a line changes.
enum	past_t { NOT_YET = 0 , PASSED , STALLED }
	With the ring empty, whether a record of before `t` can still come: NOT_YET while core 1 has not finished a tick that started at or past `t`, STALLED when it has not SENSE_TRACE_STALL_MS after `t`.

Functions
bool	sense_trace_init (sense_trace_t tr, sense_trace_rec_t buf, uint32_t size)
	A trace over `buf` of `size` records.
static uint32_t	to_t (uint64_t us)
static bool	at_or_past (uint32_t a, uint32_t b)
	Whether `a` lies at or past `b`, modulo 2^32.
static uint32_t	tail_of (const sense_trace_t *tr)
	Read the ring's tail index.
static uint32_t	head_of (const sense_trace_t *tr)
	Read the ring's head index.
uint32_t	sense_trace_held (const sense_trace_t *tr)
	Records the ring holds.
bool	sense_trace_active (const sense_trace_t *tr)
	Whether a trace is under way.
int32_t	sense_trace_code (int32_t ua, uint32_t shunt_uohm)
	The shunt code of `ua` on a shunt of `shunt_uohm:` the inverse of ina3221_current_ua(), 0 for no shunt.
uint16_t	sense_trace_rendered (uint16_t pulse_us, uint32_t top)
	The pulse a PWM slice renders when asked for `pulse_us` with its counter wrapping at `top:` the frame's length at most, as the driver clamps it.
static const sense_trace_rec_t *	peek (const sense_trace_t *tr)
	The record at the tail, or NULL for an empty ring.
static bool	is_setup (const sense_trace_rec_t *r)
	Test whether a record is a set-up record.
static uint32_t	lost_before (const sense_trace_out_t o, const sense_trace_rec_t r)
	The records dropped before `r` that no $L line has said yet.
static void	pop (sense_trace_t *tr)
	The record at the tail leaves the ring; a set-up record leaves what it says behind.
static bool	changes_setup (const sense_trace_out_t o, const sense_trace_rec_t r)
	Whether `r` changes the shunt or the Configuration, and not the state alone.
static bool	open_at (const sense_trace_out_t *o, uint32_t t)
	Whether the trace under way is still open at `t:` not stopped, and `t` before its end.
static void	extend (sense_trace_out_t *o, uint32_t end_t)
	Move the trace's end time forward, never back.
static void	lost_add (uint32_t *n, uint32_t span[2], uint32_t add, uint32_t first, uint32_t last)
	`add` more triggers that found a queue full, the first of them at `first` and the last at `last`, onto a count and its two times.
static bool	mark (sense_trace_out_t *o, sense_trace_trig_t kind, uint32_t t, uint64_t at_us, uint16_t ch, uint16_t us, uint32_t cmd_t)
	A line for the console's queue, or counted when it is full.
static place_t	trigger (sense_trace_t *tr, sense_trace_trig_t kind, uint64_t at_us, uint16_t ch, uint16_t us)
	Record a trigger: start a trace, extend the one under way, or hold it for the next trace.
void	sense_trace_trigger (sense_trace_t *tr, sense_trace_trig_t kind, uint64_t at_us, uint16_t ch, uint16_t us)
	Core 0: a trigger of `kind` at `at_us` on the clock the schedule reads; `ch` and `us` are a cmd trigger's channel and pulse.
static void	wait_slew (sense_trace_out_t *o, sense_trace_trig_t kind, uint16_t ch, uint32_t t, uint16_t us, uint32_t cmd_t)
	A slewed command of channel `ch` changed last at `t`, or with SENSE_TRACE_MARK_DEST ended there, past the end of the trace under way: kept behind the command where that waits for the next trace, one entry for the command.
static void	slew_ends (sense_trace_out_t o, sense_trace_watch_t w, uint16_t ch)
	A slewed command of `w` has ended, at its last change: said in the trace that change is in.
bool	sense_trace_pulse (sense_trace_t *tr, unsigned slot, uint16_t ch, uint16_t pulse_us, uint64_t now_us)
	Core 0, every pass, for each PWM slot: the output channel `ch` it renders and the pulse, 0 for none.
void	sense_trace_unwatch (sense_trace_t *tr, unsigned slot)
	Core 0: slot `slot` renders no PWM pulse of its own – unbound, or another driver's: the next pulse seen on it starts its watch afresh.
void	sense_trace_key (sense_trace_t *tr, int c, uint64_t now_us)
	Core 0: a character from the console.
static void	put_c (line_t *l, char c)
	Append one character to a line, when there is room.
static void	put_s (line_t l, const char s)
	Append a string to a line.
static void	put_u (line_t *l, uint32_t v)
	Append an unsigned decimal number to a line.
static void	put_i (line_t *l, int32_t v)
	Append a signed decimal number to a line.
static void	put_x4 (line_t *l, uint32_t v)
	Append the low 16 bits as four upper-case hex digits.
static void	put_kv (line_t l, const char key, uint32_t v, uint32_t max)
	A key and its value, the value held to `max`.
static void	put_eol (line_t *l)
	Append the line end, CR LF.
static void	put_state (line_t *l, uint32_t cfg)
	Append the on and reset state of a set-up word.
static void	line_start (const sense_trace_out_t o, line_t l)
	Write the start line of a trace: its id, trigger kind and time.
static void	line_setup (const sense_trace_out_t o, line_t l)
	Write a set-up line: sample period, shunt and Configuration.
static void	line_mark (const sense_trace_mark_t m, line_t l)
	Write a trigger or destination mark line.
static void	line_end (const sense_trace_out_t o, sense_trace_end_t why, bool stalled, uint32_t n_mlost, line_t l)
	Write the end line of a trace.
static act_t	ends (const sense_trace_out_t o, bool stalled, line_t l)
	The end line of a trace that ran to its end.
static bool	next_starts (const sense_trace_out_t *o)
	Whether a trigger is left for a trace of its own when this one ends: one that waited, or – unless the console stopped this trace – one whose line is not written.
static bool	lost_past (const sense_trace_out_t *o, uint32_t cut)
	A trace that ends at a set-up record of time `cut:` the trigger lines not written are all of after `cut`, and so the next trace's.
static bool	lost_all_past (const sense_trace_out_t *o, uint32_t cut)
	Test whether all the dropped mark records lie before a cut time.
static past_t	past (uint32_t fed_t, uint32_t now_t, uint32_t t)
	Classify a record time against what has been fed and the clock.
static void	line_lost (uint32_t n, line_t *l)
	Write a lost-records line: the count of dropped records.
static act_t	next_line (const sense_trace_t tr, uint32_t now_t, line_t l, uint32_t *ahead)
	The next line of the trace under way into `l`, and what it stands for; for ACT_LOST_AHEAD the records it counts into `ahead`.
static void	to_idle (sense_trace_t *tr)
	Idle from here: the scan for set-up records starts at the tail.
static void	ended (sense_trace_t tr, const uint32_t cut)
	The end line is written: the triggers that waited for it start the next trace, in their order, over what the ring holds since the end. `cut` is the time of the set-up record the trace ended at, NULL for a trace that ended on its time.
static void	commit (sense_trace_t *tr, act_t act, uint32_t ahead)
	The line `act` stood for is written; `ahead` is ACT_LOST_AHEAD's count.
static void	idle (sense_trace_t *tr)
	No trace: the newest records stay for the one a trigger starts, none of them older than the last set-up or state record.
size_t	sense_trace_pump (sense_trace_t tr, uint64_t now_us, bool connected, char out, size_t room)
	Core 0, every pass: up to `room` bytes of whole lines into `out`; returns their length. `connected` false drops a trace under way.

Detailed Description

CH1's 1ms samples as text lines: core 0's side.

Core 1's feed is sense_trace_feed.c. See sense_trace.h.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ META_KIND

#define META_KIND ( m )

Value:

((uint8_t)((m) >> 24))

◆ META_LOST

#define META_LOST ( m )

Value:

((m) & SENSE_TRACE_LOST_MAX)

SENSE_TRACE_LOST_MAX

#define SENSE_TRACE_LOST_MAX

The most records a record's count of missing ones holds.

Definition sense_trace.h:225

Function Documentation

◆ at_or_past()

bool at_or_past	(	uint32_t	a,
		uint32_t	b )

static

Whether a lies at or past b, modulo 2^32.

Parameters

a	The time to test.
b	The time to compare with.

Returns: true when a is at or past b.

◆ changes_setup()

bool changes_setup	(	const sense_trace_out_t *	o,
		const sense_trace_rec_t *	r )

static

Whether r changes the shunt or the Configuration, and not the state alone.

Parameters

o	The output state.
r	The record.

Returns: true when the record changes the shunt or the Configuration.

◆ commit()

void commit	(	sense_trace_t *	tr,
		act_t	act,
		uint32_t	ahead )

static

The line act stood for is written; ahead is ACT_LOST_AHEAD's count.

Parameters

tr	The trace.
act	The action the line stood for.
ahead	Records dropped ahead of the ring, as the line counted them.

◆ ended()

void ended	(	sense_trace_t *	tr,
		const uint32_t *	cut )

static

The end line is written: the triggers that waited for it start the next trace, in their order, over what the ring holds since the end. cut is the time of the set-up record the trace ended at, NULL for a trace that ended on its time.

Parameters

tr	The trace.
cut	The time the trace ended, in 0.1ms.

◆ ends()

act_t ends	(	const sense_trace_out_t *	o,
		bool	stalled,
		line_t *	l )

static

The end line of a trace that ran to its end.

Parameters

o	The output state.
stalled	true when the trace ended stalled.
l	The line.

Returns: ACT_END.

◆ extend()

void extend	(	sense_trace_out_t *	o,
		uint32_t	end_t )

static

Move the trace's end time forward, never back.

Parameters

o	The output state.
end_t	Candidate end time, in 0.1ms.

◆ head_of()

uint32_t head_of ( const sense_trace_t * tr )

static

Read the ring's head index.

Parameters

tr	The trace.

Returns: The head index.

◆ idle()

void idle ( sense_trace_t * tr )

static

No trace: the newest records stay for the one a trigger starts, none of them older than the last set-up or state record.

Parameters

tr	The trace.

◆ is_setup()

bool is_setup ( const sense_trace_rec_t * r )

static

Test whether a record is a set-up record.

Parameters

r	The record.

Returns: true when its kind is SENSE_TRACE_CFG or later.

◆ line_end()

void line_end	(	const sense_trace_out_t *	o,
		sense_trace_end_t	why,
		bool	stalled,
		uint32_t	n_mlost,
		line_t *	l )

static

Write the end line of a trace.

Parameters

o	The output state.
why	Why the trace ended.
stalled	true when the trace ended stalled.
n_mlost	Mark records dropped and not yet reported.
l	The line.

◆ line_lost()

void line_lost	(	uint32_t	n,
		line_t *	l )

static

Write a lost-records line: the count of dropped records.

Parameters

n	The number of records lost.
l	The line.

◆ line_mark()

void line_mark	(	const sense_trace_mark_t *	m,
		line_t *	l )

static

Write a trigger or destination mark line.

Parameters

m	The mark.
l	The line.

◆ line_setup()

void line_setup	(	const sense_trace_out_t *	o,
		line_t *	l )

static

Write a set-up line: sample period, shunt and Configuration.

Parameters

o	The output state.
l	The line.

◆ line_start()

void line_start	(	const sense_trace_out_t *	o,
		line_t *	l )

static

Write the start line of a trace: its id, trigger kind and time.

Parameters

o	The output state.
l	The line.

◆ lost_add()

void lost_add	(	uint32_t *	n,
		uint32_t	span[2],
		uint32_t	add,
		uint32_t	first,
		uint32_t	last )

static

add more triggers that found a queue full, the first of them at first and the last at last, onto a count and its two times.

Parameters

n	The count to add to.
span	The first and last times of the dropped triggers.
add	Number of triggers dropped.
first	Time of the first one, in 0.1ms.
last	Time of the last one, in 0.1ms.

◆ lost_all_past()

bool lost_all_past	(	const sense_trace_out_t *	o,
		uint32_t	cut )

static

Test whether all the dropped mark records lie before a cut time.

Parameters

o	The output state.
cut	The cut time, in 0.1ms.

Returns: true when lost_past() holds and the first dropped mark lies past the cut.

◆ lost_before()

uint32_t lost_before	(	const sense_trace_out_t *	o,
		const sense_trace_rec_t *	r )

static

The records dropped before r that no $L line has said yet.

Parameters

o	The output state.
r	The record.

Returns: The number of records dropped before r that are not yet reported.

◆ lost_past()

bool lost_past	(	const sense_trace_out_t *	o,
		uint32_t	cut )

static

A trace that ends at a set-up record of time cut: the trigger lines not written are all of after cut, and so the next trace's.

Whether a trigger that found the queue full is the next trace's too, and whether all of them are. With no trigger left no trace follows, and the count stays here.

Parameters

o	The output state.
cut	The cut time, in 0.1ms.

Returns: true when the dropped marks lie past the cut and the next trace starts.

◆ mark()

bool mark	(	sense_trace_out_t *	o,
		sense_trace_trig_t	kind,
		uint32_t	t,
		uint64_t	at_us,
		uint16_t	ch,
		uint16_t	us,
		uint32_t	cmd_t )

static

A line for the console's queue, or counted when it is full.

Whether it found a place. cmd_t is a $D line's command's time.

Parameters

o	The output state.
kind	The trigger kind.
t	Time of the mark, in 0.1ms.
at_us	Time of the trigger, in µs.
ch	The channel.
us	The pulse, in µs.
cmd_t	Time of the command, in 0.1ms.

Returns: true when the mark was queued; false when the queue is full.

◆ next_line()

act_t next_line	(	const sense_trace_t *	tr,
		uint32_t	now_t,
		line_t *	l,
		uint32_t *	ahead )

static

The next line of the trace under way into l, and what it stands for; for ACT_LOST_AHEAD the records it counts into ahead.

Changes nothing else.

Parameters

tr	The trace.
now_t	The current time, in 0.1ms.
l	Receives the line.
ahead	Receives the count of dropped records that no record carries yet.

Returns: What the line stands for.

◆ next_starts()

bool next_starts ( const sense_trace_out_t * o )

static

Whether a trigger is left for a trace of its own when this one ends: one that waited, or – unless the console stopped this trace – one whose line is not written.

Parameters

o	The output state.

Returns: true when a trigger waits or a mark is queued that is not a destination mark.

◆ open_at()

bool open_at	(	const sense_trace_out_t *	o,
		uint32_t	t )

static

Whether the trace under way is still open at t: not stopped, and t before its end.

The console may owe lines of a trace long over.

Parameters

o	The output state.
t	The time, in 0.1ms.

Returns: true when a trace is under way, not stopped, and t lies before its end.

◆ past()

past_t past	(	uint32_t	fed_t,
		uint32_t	now_t,
		uint32_t	t )

static

Classify a record time against what has been fed and the clock.

Parameters

fed_t	The time core 1 has fed, in 0.1ms.
now_t	The current time, in 0.1ms.
t	The record time, in 0.1ms.

Returns: PASSED once fed_t has reached t, STALLED once now_t is SENSE_TRACE_STALL_MS past t, else NOT_YET.

◆ peek()

const sense_trace_rec_t * peek ( const sense_trace_t * tr )

static

The record at the tail, or NULL for an empty ring.

Parameters

tr	The trace.

Returns: The record at the tail, or NULL for an empty ring.

◆ pop()

void pop ( sense_trace_t * tr )

static

The record at the tail leaves the ring; a set-up record leaves what it says behind.

Every record leaves here, in a trace and out of one: the count of dropped records it carried is read.

Parameters

tr	The trace.

◆ put_c()

void put_c	(	line_t *	l,
		char	c )

static

Append one character to a line, when there is room.

Parameters

l	The line.
c	The character.

◆ put_eol()

void put_eol ( line_t * l )

static

Append the line end, CR LF.

Parameters

l The line.

◆ put_i()

void put_i	(	line_t *	l,
		int32_t	v )

static

Append a signed decimal number to a line.

Parameters

l	The line.
v	The number.

◆ put_kv()

void put_kv	(	line_t *	l,
		const char *	key,
		uint32_t	v,
		uint32_t	max )

static

A key and its value, the value held to max.

Parameters

l	The line.
key	The key text.
v	The value.
max	The largest value written.

◆ put_s()

void put_s	(	line_t *	l,
		const char *	s )

static

Append a string to a line.

Parameters

l	The line.
s	The string.

◆ put_state()

void put_state	(	line_t *	l,
		uint32_t	cfg )

static

Append the on and reset state of a set-up word.

Parameters

l	The line.
cfg	The set-up word.

◆ put_u()

void put_u	(	line_t *	l,
		uint32_t	v )

static

Append an unsigned decimal number to a line.

Parameters

l	The line.
v	The number.

◆ put_x4()

void put_x4	(	line_t *	l,
		uint32_t	v )

static

Append the low 16 bits as four upper-case hex digits.

Parameters

l	The line.
v	The value.

◆ sense_trace_active()

bool sense_trace_active ( const sense_trace_t * tr )

Whether a trace is under way.

Parameters

tr	The trace.

Returns: true while a trace is under way.

◆ sense_trace_code()

int32_t sense_trace_code	(	int32_t	ua,
		uint32_t	shunt_uohm )

The shunt code of ua on a shunt of shunt_uohm: the inverse of ina3221_current_ua(), 0 for no shunt.

Parameters

ua	The current, in µA.
shunt_uohm	Shunt resistance, in µΩ.

Returns: The shunt code of ua on a shunt of shunt_uohm; 0 for no shunt.

◆ sense_trace_held()

uint32_t sense_trace_held ( const sense_trace_t * tr )

Records the ring holds.

Parameters

tr	The trace.

Returns: The number of records held.

◆ sense_trace_init()

bool sense_trace_init	(	sense_trace_t *	tr,
		sense_trace_rec_t *	buf,
		uint32_t	size )

A trace over buf of size records.

False, and nothing usable, unless size is a power of two from 2 to 2^24.

Parameters

tr	The trace to set up.
buf	The record buffer.
size	Number of records in buf.

Returns: true when the trace is set up; false, and nothing usable, unless size is a power of two from 2 to 2^24.

◆ sense_trace_key()

void sense_trace_key	(	sense_trace_t *	tr,
		int	c,
		uint64_t	now_us )

Core 0: a character from the console.

Parameters

tr	The trace.
c	The character from the console.
now_us	The current time, in µs.

◆ sense_trace_pulse()

bool sense_trace_pulse	(	sense_trace_t *	tr,
		unsigned	slot,
		uint16_t	ch,
		uint16_t	pulse_us,
		uint64_t	now_us )

Core 0, every pass, for each PWM slot: the output channel ch it renders and the pulse, 0 for none.

A slot seen with another channel than before is watched afresh. True when this is a command: the caller then gives the time of the frame that carries it to sense_trace_trigger(), as a SENSE_TRACE_TRIG_CMD for every true return. That trigger sets the command time the slot's later $D line carries; without it the line carries an earlier command's time, or 0 on a slot that has none.

Parameters

tr	The trace.
slot	The PWM slot.
ch	The output channel the slot renders.
pulse_us	The pulse, in µs; 0 for none.
now_us	The current time, in µs.

Returns: true when this is a command.

◆ sense_trace_pump()

size_t sense_trace_pump	(	sense_trace_t *	tr,
		uint64_t	now_us,
		bool	connected,
		char *	out,
		size_t	room )

Core 0, every pass: up to room bytes of whole lines into out; returns their length. connected false drops a trace under way.

Parameters

tr	The trace.
now_us	The current time, in µs.
connected	false drops a trace under way.
out	Receives the lines.
room	Bytes that fit in out.

Returns: The length of the lines written.

◆ sense_trace_rendered()

uint16_t sense_trace_rendered	(	uint16_t	pulse_us,
		uint32_t	top )

The pulse a PWM slice renders when asked for pulse_us with its counter wrapping at top: the frame's length at most, as the driver clamps it.

Parameters

pulse_us	The requested pulse, in µs.
top	The counter's wrap value.

Returns: The pulse the PWM slice renders, in µs.

◆ sense_trace_trigger()

void sense_trace_trigger	(	sense_trace_t *	tr,
		sense_trace_trig_t	kind,
		uint64_t	at_us,
		uint16_t	ch,
		uint16_t	us )

Core 0: a trigger of kind at at_us on the clock the schedule reads; ch and us are a cmd trigger's channel and pulse.

Parameters

tr	The trace.
kind	The trigger kind.
at_us	Time of the trigger, in µs.
ch	The channel of a cmd trigger.
us	The pulse of a cmd trigger, in µs.

◆ sense_trace_unwatch()

void sense_trace_unwatch	(	sense_trace_t *	tr,
		unsigned	slot )

Core 0: slot slot renders no PWM pulse of its own – unbound, or another driver's: the next pulse seen on it starts its watch afresh.

Parameters

tr	The trace.
slot	The PWM slot.

◆ slew_ends()

void slew_ends	(	sense_trace_out_t *	o,
		sense_trace_watch_t *	w,
		uint16_t	ch )

static

A slewed command of w has ended, at its last change: said in the trace that change is in.

Parameters

o	The output state.
w	The watch of the output slot.
ch	The channel.

◆ tail_of()

uint32_t tail_of ( const sense_trace_t * tr )

static

Read the ring's tail index.

Parameters

tr	The trace.

Returns: The tail index.

◆ to_idle()

void to_idle ( sense_trace_t * tr )

static

Idle from here: the scan for set-up records starts at the tail.

Parameters

tr	The trace.

◆ trigger()

place_t trigger	(	sense_trace_t *	tr,
		sense_trace_trig_t	kind,
		uint64_t	at_us,
		uint16_t	ch,
		uint16_t	us )

static

Record a trigger: start a trace, extend the one under way, or hold it for the next trace.

Parameters

tr	The trace.
kind	The trigger kind.
at_us	Time of the trigger, in µs.
ch	The channel of a cmd trigger.
us	The pulse of a cmd trigger, in µs.

Returns: Where the trigger went.

◆ wait_slew()

void wait_slew	(	sense_trace_out_t *	o,
		sense_trace_trig_t	kind,
		uint16_t	ch,
		uint32_t	t,
		uint16_t	us,
		uint32_t	cmd_t )

static

A slewed command of channel ch changed last at t, or with SENSE_TRACE_MARK_DEST ended there, past the end of the trace under way: kept behind the command where that waits for the next trace, one entry for the command.

A command that does not wait has its line in a trace that is over, or none.

Parameters

o	The output state.
kind	The mark kind.
ch	The channel.
t	Time of the mark, in 0.1ms.
us	The pulse, in µs.
cmd_t	Time of the command, in 0.1ms.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ META_KIND

◆ META_LOST

Function Documentation

◆ at_or_past()

◆ changes_setup()

◆ commit()

◆ ended()

◆ ends()

◆ extend()

◆ head_of()

◆ idle()

◆ is_setup()

◆ line_end()

◆ line_lost()

◆ line_mark()

◆ line_setup()

◆ line_start()

◆ lost_add()

◆ lost_all_past()

◆ lost_before()

◆ lost_past()

◆ mark()

◆ next_line()

◆ next_starts()

◆ open_at()

◆ past()

◆ peek()

◆ pop()

◆ put_c()

◆ put_eol()

◆ put_i()

◆ put_kv()

◆ put_s()

◆ put_state()

◆ put_u()

◆ put_x4()

◆ sense_trace_active()

◆ sense_trace_code()

◆ sense_trace_held()

◆ sense_trace_init()

◆ sense_trace_key()

◆ sense_trace_pulse()

◆ sense_trace_pump()

◆ sense_trace_rendered()

◆ sense_trace_trigger()

◆ sense_trace_unwatch()

◆ slew_ends()

◆ tail_of()

◆ to_idle()

◆ trigger()

◆ wait_slew()