praet_horologiorum_custos.h File Reference

Where the microseconds come from: the caller's clock, or one of ours pinned to a core they name, and the scaling between that clock's ticks and a microsecond. More...

#include "mmgr.h"
#include "memoriam_praetereo/praet_praefinitum.h"
#include "memoriam_praetereo/praet_platform_detection.h"

Go to the source code of this file.

Macros
#define	PRAET_CLOCK_CALLER
	The clock is the caller's, read through the port.
#define	PRAET_CLOCK_OWN
	The clock is ours, pinned to the core PRAET_CLOCK_CORE names.
#define	PRAET_CLOCK_HZ
	Ticks the clock counts in one second.
#define	PRAET_UNSET_CLOCK_HZ
#define	PRAET_UNSET_CLOCK_SOURCE
	Whether the clock is the caller's or ours.
#define	PRAET_CLOCK_SOURCE
#define	PRAET_CLOCK_CORE
	The core our timer is pinned to.
#define	PRAET_UNSET_CLOCK_CORE
#define	PRAET_TICKS_PER_MICRO
	Ticks this clock counts in one microsecond.
#define	PRAET_CLOCK_MICROS(ticks_)
	Converts a tick count from this clock into microseconds.

Detailed Description

Where the microseconds come from: the caller's clock, or one of ours pinned to a core they name, and the scaling between that clock's ticks and a microsecond.

Author

dstroy0 (Douglas Quigg) dquig.nosp@m.g123.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Date

2026-09-01

Note

Every deadline in this module is microseconds, and a clock makes a microsecond mean anything. A build with no clock declared has deadlines it cannot honor, and so it stops and asks for one.

What the clock is does not matter here. A counter that runs and can be read is the whole requirement - this scales its ticks against the frequency the caller states and never looks at where it came from.

Definition in file praet_horologiorum_custos.h.

Macro Definition Documentation

PRAET_CLOCK_CALLER

#define PRAET_CLOCK_CALLER

The clock is the caller's, read through the port.

Definition at line 33 of file praet_horologiorum_custos.h.

PRAET_CLOCK_OWN

#define PRAET_CLOCK_OWN

The clock is ours, pinned to the core PRAET_CLOCK_CORE names.

Definition at line 38 of file praet_horologiorum_custos.h.

PRAET_CLOCK_HZ

#define PRAET_CLOCK_HZ

Ticks the clock counts in one second.

Note

This is the PLL figure, and it is what everything else scales against. There is no way to read it off a part at compile time, and so it is declared or the build stops.

The default is one megahertz, which reads a tick as a microsecond. Not a guess at the part's frequency - guessing one would make every deadline in the module quietly wrong by whatever the guess missed by. One megahertz is the floor this module supports, and so what a build gets by taking it is timing that is honest about being unscaled.

Definition at line 55 of file praet_horologiorum_custos.h.

PRAET_UNSET_CLOCK_HZ

#define PRAET_UNSET_CLOCK_HZ

Definition at line 56 of file praet_horologiorum_custos.h.

PRAET_UNSET_CLOCK_SOURCE

#define PRAET_UNSET_CLOCK_SOURCE

Whether the clock is the caller's or ours.

Note

PRAET_CLOCK_CALLER where the caller already runs a counter this can read, the usual answer on a part whose application owns the timers. PRAET_CLOCK_OWN where it does not, and this pins one to a core.

The default is ours, because that is the arm that needs nothing from the caller. A build that took this default and meant the other one finds out from the message, not from a timer that was never started.

Definition at line 72 of file praet_horologiorum_custos.h.

PRAET_CLOCK_SOURCE

#define PRAET_CLOCK_SOURCE

Definition at line 78 of file praet_horologiorum_custos.h.

PRAET_CLOCK_CORE

#define PRAET_CLOCK_CORE

The core our timer is pinned to.

Note

A field of PRAET_CLOCK_SOURCE being PRAET_CLOCK_OWN, and required once it is. Which core is the caller's call - this only needs to know the timer is somewhere it will keep running.

What the number means is the platform's business. Zero, one, whatever a part calls its cores; nothing here reads it beyond handing it to the port.

Definition at line 109 of file praet_horologiorum_custos.h.

PRAET_UNSET_CLOCK_CORE

#define PRAET_UNSET_CLOCK_CORE

Definition at line 110 of file praet_horologiorum_custos.h.

PRAET_TICKS_PER_MICRO

#define PRAET_TICKS_PER_MICRO

Ticks this clock counts in one microsecond.

Note

A compile-time constant, and so the division below folds to a multiply and a shift, and reaches no divide instruction on a part that may not have one.

Definition at line 132 of file praet_horologiorum_custos.h.

PRAET_CLOCK_MICROS

#define PRAET_CLOCK_MICROS

(

ticks_

)

Converts a tick count from this clock into microseconds.

Parameters

[in]

ticks_

Ticks read off the clock.

Returns

Those ticks as whole microseconds, rounded down.

Note

Rounded down deliberately. A deadline reached a fraction of a microsecond early is a window that was slightly short; one reached late is a stall reported after the fact.

Definition at line 142 of file praet_horologiorum_custos.h.