Events.h File Reference

#include "temu-c/Support/Attributes.h"
#include "temu-c/Support/Objsys.h"
#include <stdint.h>

Include dependency graph for Events.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	temu_TimeSource
struct	temu_Event

Macros
#define	TEMU_ASYNC_CYCLIC   1
#define	TEMU_ASYNC_READ   (1 << 1)
#define	TEMU_ASYNC_WRITE   (1 << 2)

Typedefs
typedef struct temu_EventQueue	temu_EventQueue
typedef struct temu_Event	temu_Event
typedef void(*	temu_ThreadSafeCb) (void *)
	Posting callback from other threads. More...

Enumerations
enum	temu_SyncEvent { teSE_Cpu, teSE_Machine }

Functions
TEMU_API int64_t	temu_eventPublishStruct (const char *EvName, temu_Event *Ev, void *Obj, void(*Func)(temu_Event *))
TEMU_API void	temu_eventDepublish (int64_t EvID)
TEMU_API int64_t	temu_eventPublish (const char *EvName, void *Obj, void(*Func)(temu_Event *))
TEMU_API void	temu_eventPostSteps (temu_TimeSource *TS, int64_t EvID, int64_t Delta, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostCycles (temu_TimeSource *TS, int64_t EvID, int64_t Delta, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostNanos (temu_TimeSource *TS, int64_t EvID, int64_t Delta, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostSecs (temu_TimeSource *TS, int64_t EvID, double Delta, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostStack (temu_TimeSource *TS, int64_t EvID, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostImmediate (temu_TimeSource *TS, int64_t EvID, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostCyclesAbsolute (temu_TimeSource *TS, int64_t EvID, int64_t AbsTime, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostNanosAbsolute (temu_TimeSource *TS, int64_t EvID, int64_t AbsTime, temu_SyncEvent Sync)
TEMU_API void	temu_eventRescheduleCycles (temu_TimeSource *TS, int64_t EvID, int64_t Delta, temu_SyncEvent Sync)
TEMU_API int	temu_eventIsScheduled (int64_t EvID)
TEMU_API void	temu_eventDeschedule (int64_t EvID)
TEMU_API int64_t	temu_eventGetCycles (temu_TimeSource *TS, int64_t EvID)
TEMU_API int64_t	temu_eventGetNanos (temu_TimeSource *TS, int64_t EvID)
TEMU_API double	temu_eventGetSecs (temu_TimeSource *TS, int64_t EvID)
TEMU_API int	temu_asyncTimerAdd (temu_TimeSource *TS, double T, unsigned Flags, void(*CB)(void *), void *Data)
TEMU_API void	temu_asyncTimerRemove (int Fd)
TEMU_API int	temu_asyncSocketAdd (temu_TimeSource *TS, int Sock, unsigned Flags, void(*CB)(void *), void *Data)
TEMU_API void	temu_asyncSocketRemove (int Fd, unsigned Flags)
TEMU_API void	temu_eventPostAsync (temu_TimeSource *TS, temu_ThreadSafeCb CB, void *Data, temu_SyncEvent Sync)
TEMU_API int	temu_eventSetRealTime (int64_t EvID)
TEMU_API void	temu_eventSetPeriodCycles (int64_t EvID, int64_t Period)
TEMU_API void	temu_eventSetRTPeriodNanos (int64_t EvID, int64_t Period)
TEMU_API void	temu_eventSetRTTime (int64_t EvID, int64_t Time)
TEMU_API uint64_t	temu_eventQueueGetFreq (temu_TimeSource *TS)

Macro Definition Documentation

TEMU_ASYNC_CYCLIC

#define TEMU_ASYNC_CYCLIC   1

Flags for async functions below.

TEMU_ASYNC_READ

#define TEMU_ASYNC_READ   (1 << 1)

TEMU_ASYNC_WRITE

#define TEMU_ASYNC_WRITE   (1 << 2)

Typedef Documentation

temu_Event

typedef struct temu_Event temu_Event

temu_EventQueue

typedef struct temu_EventQueue temu_EventQueue

temu_ThreadSafeCb

typedef void(* temu_ThreadSafeCb) (void *)

Posting callback from other threads.

Enumeration Type Documentation

temu_SyncEvent

enum temu_SyncEvent

Enumerator
teSE_Cpu
teSE_Machine

Function Documentation

temu_asyncSocketAdd()

TEMU_API int temu_asyncSocketAdd	(	temu_TimeSource *	TS,
		int	Sock,
		unsigned	Flags,
		void(*)(void *)	CB,
		void *	Data
	)

Add asynchronous event triggered by file descriptor changes

Parameters

TS	the synchronous queue or time source object (normally a CPU object)
Sock	File descriptor for the socket. This can also be a pipe FD. Note that the function is likely to be renamed. Note that in case you are intending to read from the socket, make sure it is non-blocking.
Flags	TEMU_ASYNC_READ in case you wish to be notified about data available to read.

Returns

Returns the file descriptor (Sock) if successful, otherwise -1.

temu_asyncSocketRemove()

TEMU_API void temu_asyncSocketRemove	(	int	Fd,
		unsigned	Flags
	)

Remove an asynchronous event triggered by file descriptor changes

Parameters

Fd	The ID of the socket to remove
Flags	The flags of removing

temu_asyncTimerAdd()

TEMU_API int temu_asyncTimerAdd	(	temu_TimeSource *	TS,
		double	T,
		unsigned	Flags,
		void(*)(void *)	CB,
		void *	Data
	)

Add asynchronously activated wall-clock timed events

The callback function will be called synchronously by the emulator core associated with Q. That means that when CB is executing it is safe to do anything that can be done from a normal event or MMIO handler.

Note that the event is only called when a CPU core or machine is running. When the timer has triggered, it is temporarily disabled and the CB is posted on the synchornous event queue as an async event. This will be executed when the next normal event expires (e.g. at the end of the current quanta). After the event has been called, depending on wether the timer is cyclic or not, it will be reactivated. This means that if the emulator is paused, at most one call to the event handler will be issued, and this will be done when the emulator is resumed.

Parameters

TS	The time source object (normally a CPU object)
T	Delta seconds in the future for the first event to be posted.
Flags	Set to TEMU_ASYNC_CYCLIC if the event should be executed as a cyclic event.
CB	Call back function on when timer expires
Data	Context data to be passed to the callback function

Returns

Returns a file descriptor or timer ID.

temu_asyncTimerRemove()

TEMU_API void temu_asyncTimerRemove

(

int

Fd

)

Remove an async timer

Parameters

Fd	Timer ID to remove

temu_eventDepublish()

TEMU_API void temu_eventDepublish

(

int64_t

EvID

)

It is possible to depublish events explicitly, but this is rarely needed as it is managed at termination time automatically.

Parameters

EvID

Event ID

temu_eventDeschedule()

TEMU_API void temu_eventDeschedule

(

int64_t

EvID

)

Deschedule event

Parameters

EvID	The event ID of the event to deschedule.

temu_eventGetCycles()

TEMU_API int64_t temu_eventGetCycles	(	temu_TimeSource *	TS,
		int64_t	EvID
	)

Get delta time in cycles for the given event and queue

Parameters

TS	The time source object (normally a CPU object)
EvID	the event to get the cycles for.

Returns

Number of simulated cycles in the future the event will trigger

temu_eventGetNanos()

TEMU_API int64_t temu_eventGetNanos	(	temu_TimeSource *	TS,
		int64_t	EvID
	)

Get delta time in nanoseconds for the given event and queue

Parameters

TS	The time source object (normally a CPU object)
EvID	the event to get the nanoseconds for.

Returns

Number of simulated nanoseconds in the future when the event will trigger

temu_eventGetSecs()

TEMU_API double temu_eventGetSecs	(	temu_TimeSource *	TS,
		int64_t	EvID
	)

Get delta time in seconds for the given event and queue

Parameters

TS	The time source object (normally a CPU object)
EvID	the event to get the seconds for.

Returns

Number of simulated seconds in the future when the event will trigger

temu_eventIsScheduled()

TEMU_API int temu_eventIsScheduled

(

int64_t

EvID

)

Check if event is scheduled

Parameters

EvID	The event ID to check whether it is scheduled.

Returns

Zero (0) in case the event is not scheduled, otherwise non-zero for scheduled events.

temu_eventPostAsync()

TEMU_API void temu_eventPostAsync	(	temu_TimeSource *	TS,
		temu_ThreadSafeCb	CB,
		void *	Data,
		temu_SyncEvent	Sync
	)

Post an event to an asynchronous queue

Parameters

TS	the asynchronous queue or time source object (normally a CPU object)
CB	The callback function to call when the event happens
Data	The context data to be passed to the callback function
Sync	Execute on CPU or machine level.

temu_eventPostCycles()

TEMU_API void temu_eventPostCycles	(	temu_TimeSource *	TS,
		int64_t	EvID,
		int64_t	Delta,
		temu_SyncEvent	Sync
	)

Post events with a relative time in cycles in the future

Note that if posting a scheduled event, a warning will be printed and the event will be automatically descheduled before being inserted in the event queue.

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
Delta	The number of CPU clock cycles in the future to post the event. This should be > 0.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPostCyclesAbsolute()

TEMU_API void temu_eventPostCyclesAbsolute	(	temu_TimeSource *	TS,
		int64_t	EvID,
		int64_t	AbsTime,
		temu_SyncEvent	Sync
	)

Post events with an absolute time in cycles The function is only well defined for times >= current time. Timestamps < current time will have undefined behaviour.

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
AbsTime	The absolute time stamp to run the event at, this should be > current time.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPostImmediate()

TEMU_API void temu_eventPostImmediate	(	temu_TimeSource *	TS,
		int64_t	EvID,
		temu_SyncEvent	Sync
	)

Post events in the immediate event queue

Immediate events are executed either after the current instruction is finished or when the machine quanta expires in case of machine synchronised events. This is the same as for stacked events, however immediate events are executed in FIFO order.

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPostNanos()

TEMU_API void temu_eventPostNanos	(	temu_TimeSource *	TS,
		int64_t	EvID,
		int64_t	Delta,
		temu_SyncEvent	Sync
	)

Post events with a relative time in nanoseconds in the future

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
Delta	The number of nanoseconds in the future to post the event. This should be > 0.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPostNanosAbsolute()

TEMU_API void temu_eventPostNanosAbsolute	(	temu_TimeSource *	TS,
		int64_t	EvID,
		int64_t	AbsTime,
		temu_SyncEvent	Sync
	)

Post events with an absolute time in nanoseconds The function is only well defined for times >= current time. Timestamps < current time will have undefined behaviour.

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
AbsTime	The absolute time stamp to run the event at, this should be > current time.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPostSecs()

TEMU_API void temu_eventPostSecs	(	temu_TimeSource *	TS,
		int64_t	EvID,
		double	Delta,
		temu_SyncEvent	Sync
	)

Post events with a relative time in seconds in the future

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
Delta	The number of seconds in the future to post the event. This should be > 0.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPostStack()

TEMU_API void temu_eventPostStack	(	temu_TimeSource *	TS,
		int64_t	EvID,
		temu_SyncEvent	Sync
	)

Post events in the event queue stack

Stacked events are executed either after the current instruction is finished or when the machine quanta expires in case of machine synchronised events.

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPostSteps()

TEMU_API void temu_eventPostSteps	(	temu_TimeSource *	TS,
		int64_t	EvID,
		int64_t	Delta,
		temu_SyncEvent	Sync
	)

Post events with a relative trigger in steps

Posting an event in steps is not effected by the IPC/CPI setting of the clock.

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
Delta	The number of CPU steps in the future to post the event. This should be > 0.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventPublish()

TEMU_API int64_t temu_eventPublish	(	const char *	EvName,
		void *	Obj,
		void(*)(temu_Event *)	Func
	)

Publish an event.

The function will allocate an event structure in the global event heap and return the event ID.

A typical use is to call the function in the object constructor and assign the event id to a field in the object. This field should not be snapshotted (i.e. it will be reassigned in the constructor) when restoring an object anyway.

Note

This function is non thread safe. Object construction is expected to be done in a single thread (e.g. the main thread).

Parameters

EvName	Name of the event
Obj	The object associated with the event
Func	The event callback function.

Returns

The event ID >= 0 in case of success. Negative values indicate errors.

temu_eventPublishStruct()

TEMU_API int64_t temu_eventPublishStruct	(	const char *	EvName,
		temu_Event *	Ev,
		void *	Obj,
		void(*)(temu_Event *)	Func
	)

Publish a preallocated event object.

The event objects can be embedded in your own class if needed.

Parameters

EvName	Name of the event
Ev	Pointer to the event struct
Obj	The object associated with the event
Func	The event callback function.

Returns

The event ID.

temu_eventQueueGetFreq()

TEMU_API uint64_t temu_eventQueueGetFreq

(

temu_TimeSource *

TS

)

Get the frequency in Hz of the given time source.

Parameters

TS	Time source

temu_eventRescheduleCycles()

TEMU_API void temu_eventRescheduleCycles	(	temu_TimeSource *	TS,
		int64_t	EvID,
		int64_t	Delta,
		temu_SyncEvent	Sync
	)

Reschedule event with relative time in cycles

This function automatically deschedules the event before scheduling it again. The function ensures only one lock is taken for the pattern:

• is scheduled?
• de-schedule
• post

Parameters

TS	The time source object (normally a CPU object)
EvID	The even ID returned by one of the event publish functions.
Delta	The number of CPU clock cycles in the future to post the event. This should be > 0.
Sync	whether the event should be executed on the CPU queue or the machine queue.

temu_eventSetPeriodCycles()

TEMU_API void temu_eventSetPeriodCycles	(	int64_t	EvID,
		int64_t	Period
	)

Set the cycles property on an event.

Periodic events have the advantage that they do not slip due to reposting of event with respect to the event triggering time and behaves as if the reposting is 1, automatic and 2, is relative to the event schedule time. which differ from the triggering time by possibly a few cycles. Note, calling this function does not reschedule the event.

Parameters

EvID	Event ID
Period	Cycles to add as period.

temu_eventSetRealTime()

TEMU_API int temu_eventSetRealTime

(

int64_t

EvID

)

Mark an event as real-time.

With a real-time event, it is meant that the event will execute at roughly real-time. In the case when the event is posted, it will compute a rough triggering time in wall clock. When the event is executed it will do two things:

1. Check if the event wall-clock time is before the current time, if so emit a "temu.realtime-slip" notification".
2. Check if the event is triggered in the future (with respect to wall clock), if so sleep until the wall-clock has caught up.

Due to the behaviour, the real-time events are suitable only for relatively short event times, as long sleep times may make the emulator non responsive. Especially at present, this will block the execution of async events as the event queue is halted until the wall-clock catches up to the simulated time.

Note that RT event support is primarily used to slow down the emulator artificially, this is accomplished by enabling real-time mode on the relevant model.

This function should only be called on in-flight events.

Parameters

EvID	Event ID to make real-time

Returns

0 On success.

temu_eventSetRTPeriodNanos()

TEMU_API void temu_eventSetRTPeriodNanos	(	int64_t	EvID,
		int64_t	Period
	)

Set the RT period (nanoseconds), this should be the same as the cycle period, but it should be in nanoseconds and tno cycles

Parameters

EvID	Event ID
Period	Period in nanoseconds

temu_eventSetRTTime()

TEMU_API void temu_eventSetRTTime	(	int64_t	EvID,
		int64_t	Time
	)

Set the RT time (nanoseconds absoulute time computed from temu_timeGetMonotonicWct()). This time is used by events flagged with TEMU_EVENT_RT to delay the execution of the event handler function.

Parameters

EvID	Event ID
Time	Absolute time to trigger event at in WCT