perf_watch.h File Reference

What the panel's console reports about its own frame times, stacks and heap: the statistics behind each line and the frame each line is due on, without the clock, the tasks or the log. More...

#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	perf_span_t
	One figure's minimum, maximum and sum over a window. More...
struct	perf_window_t
	The frames drawn on one screen since the window started. More...
struct	perf_low_t
	One name's least free bytes. More...
struct	perf_lows_t
	The least free figure of every name noted. More...

Macros
#define	PERF_WINDOW_FRAMES   300u
	Frames between two rate lines: 5.0s at 60.4fps, 9.9s at 30.2fps.
#define	PERF_LOWS_MAX   48u
	Rows in the table of lows: tasks, the internal heap, and room. At most 64, the bits of perf_lows_t::due.
#define	PERF_LOWS_NAME   16u
	Bytes of a name in the table, the terminator included; FreeRTOS's configMAX_TASK_NAME_LEN in ESP-IDF.

Enumerations
enum	perf_line_t { PERF_LINE_RATE , PERF_LINE_WINDOW , PERF_LINE_LOW }
	The console line a frame carries. More...

Functions
void	perf_window_start (perf_window_t *w, int screen)
	Start an empty window on screen.
void	perf_window_add (perf_window_t *w, int screen, uint32_t draw_us, uint32_t wait_us, uint32_t turn_us)
	Add one frame.
uint32_t	perf_span_mean_us (const perf_span_t *s, uint32_t frames)
	The mean of one figure over frames, rounded to the nearest us.
void	perf_lows_init (perf_lows_t *t)
	Empty the table.
void	perf_name_copy (char dst[PERF_LOWS_NAME], const char *name)
	Copy a task's name into a row-sized buffer.
bool	perf_lows_note (perf_lows_t *t, const char *name, uint32_t least)
	Note least free bytes for name.
int	perf_lows_take (perf_lows_t *t)
	Take the first row due for a line.
perf_line_t	perf_line_due (uint32_t frames)
	The line due after frame frames.

Detailed Description

What the panel's console reports about its own frame times, stacks and heap: the statistics behind each line and the frame each line is due on, without the clock, the tasks or the log.

Three parts, all pure and all run in the host suite:

• The frame window: DRAW, WAIT and TURN, minimum, mean and maximum, over the frames drawn on one screen since the last console line. A frame on another screen restarts the window with that screen, so a line names one screen and covers fewer than PERF_WINDOW_FRAMES frames when the screen changed inside it.
• The table of lows: for each name (a task, or the internal heap), the least free stack or heap noted so far. A note reports whether the name is new or its figure fell and marks the row due for a console line, so the console prints a task only when its high-water mark moves. Two tasks of one name share a row and keep the lower figure.
• The schedule: at most one line a frame. The console is UART0 at 115,200 baud with no driver installed, so a line that does not fit the 128-byte transmit FIFO (first in, first out) holds the render loop until the rest is sent, 87us a byte. One line of at most 128 bytes a frame finds the FIFO empty: 128 bytes drain in 11.1ms, and a frame at 60.4fps is 16.6ms.

SPDX-License-Identifier: MIT

Enumeration Type Documentation

perf_line_t

enum perf_line_t

The console line a frame carries.

Enumerator
PERF_LINE_RATE	fps, the last frame, VSYNC, the counts
PERF_LINE_WINDOW	the window of the screen shown
PERF_LINE_LOW	one row of the lows, if one is due

Function Documentation

perf_line_due()

perf_line_t perf_line_due

(

uint32_t

frames

)

The line due after frame frames.

The rate line closes a window of PERF_WINDOW_FRAMES frames; the window line follows on the next frame; every other frame may carry one row of the lows.

Parameters

frames

Frames drawn since the loop started, this one included. 2^32 is not a multiple of 300: the window across the wrap is 196 frames long, 3.2s at 60.4fps after 2.25 years.

Returns

The line.

perf_lows_init()

void perf_lows_init

(

perf_lows_t *

t

)

Empty the table.

Parameters

t	The table.

perf_lows_note()

bool perf_lows_note	(	perf_lows_t *	t,
		const char *	name,
		uint32_t	least )

Note least free bytes for name.

Parameters

t	The table.
name	The task's name, or another the caller chooses; cut to PERF_LOWS_NAME - 1 bytes, of which no more are read (perf_name_copy()). NULL is noted as "".
least	The least free bytes now.

Returns

true when the name is new or least is below its last figure, which it then becomes, and the row is due for a line; false when it held or rose, and for a new name when every row is in use, which counts in dropped.

perf_lows_take()

int perf_lows_take

(

perf_lows_t *

t

)

Take the first row due for a line.

Parameters

t	The table.

Returns

The row's index, no longer due; -1 when none is due.

perf_name_copy()

void perf_name_copy	(	char	dst[PERF_LOWS_NAME],
		const char *	name )

Copy a task's name into a row-sized buffer.

Reads at most PERF_LOWS_NAME - 1 bytes of name and none past its terminator, so a name without one is cut, not run past.

Parameters

dst	The buffer, PERF_LOWS_NAME bytes; always terminated.
name	The name; NULL is copied as "".

perf_span_mean_us()

uint32_t perf_span_mean_us	(	const perf_span_t *	s,
		uint32_t	frames )

The mean of one figure over frames, rounded to the nearest us.

Parameters

s	The figure's span.
frames	The frames it was added over.

Returns

The mean, us; 0 with no frame.

perf_window_add()

void perf_window_add	(	perf_window_t *	w,
		int	screen,
		uint32_t	draw_us,
		uint32_t	wait_us,
		uint32_t	turn_us )

Add one frame.

Parameters

w	The window.
screen	The screen the frame was drawn on; another than the window's starts the window again on it, with this frame.
draw_us	The frame's paint time, us.
wait_us	How long the flip after it blocked, us.
turn_us	The part of wait_us Screen rotation 180° spent copying the frame turned, us; 0 in NORMAL.

perf_window_start()

void perf_window_start	(	perf_window_t *	w,
		int	screen )

Start an empty window on screen.

Parameters

w	The window.
screen	The screen its frames are drawn on.