Events.h File Reference

#include <stdint.h>
#include "temu-c/Support/Objsys.h"
#include "temu-c/Support/LegacyEvents.h"
#include "temu-c/Support/Attributes.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_Event
struct	temu_EventIface

Macros
#define	TEMU_EVENT_IFACE_TYPE   "EventIface"
#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 *)

Enumerations
enum	temu_SyncEvent { teSE_Cpu, teSE_Machine }

Functions
TEMU_API void *	temu_allocateEventQueue (void)
	Allocate event queue. More...
TEMU_API void	temu_disposeEventQueue (void *Queue)
	Dispose event queue. More...
TEMU_API void	temu_postCallbackInQueue (void *Queue, temu_ThreadSafeCb Cb, void *Arg)
	Post an event directly into a queue object. More...
TEMU_API void	temu_removeCallbackInQueue (void *Queue, temu_ThreadSafeCb Cb, void *Arg)
	Remove an event from a queue object. More...
	TEMU_IFACE_REFERENCE_TYPE (temu_Event)
TEMU_API int64_t	temu_eventPublishOldStyle (const char *Name, void *Obj, void(*Ev)(void *, void *))
TEMU_API int64_t	temu_eventGetOldStyleID (void(*Ev)(void *, void *), void *Sender)
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_eventPostCycles (void *Q, int64_t EvID, int64_t Delta, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostNanos (void *Q, int64_t EvID, int64_t Delta, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostSecs (void *Q, int64_t EvID, double Delta, temu_SyncEvent Sync)
TEMU_API void	temu_eventPostStack (void *Q, int64_t EvID, 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 (void *Q, int64_t EvID)
TEMU_API int64_t	temu_eventGetNanos (void *Q, int64_t EvID)
TEMU_API double	temu_eventGetSecs (void *Q, int64_t EvID)
TEMU_API int	temu_asyncTimerAdd (void *Q, double T, unsigned Flags, void(*CB)(void *), void *Data)
TEMU_API void	temu_asyncTimerRemove (int Fd)
TEMU_API int	temu_asyncSocketAdd (void *Q, int Sock, unsigned Flags, void(*CB)(void *), void *Data)
TEMU_API void	temu_asyncSocketRemove (int Fd, unsigned Flags)
TEMU_API void	temu_eventPostAsync (void *Q, 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 (void *Q)

Macro Definition Documentation

#define TEMU_ASYNC_CYCLIC   1

Flags for async functions below.

Definition at line 273 of file Events.h.

#define TEMU_ASYNC_READ   (1 << 1)

Definition at line 274 of file Events.h.

#define TEMU_ASYNC_WRITE   (1 << 2)

Definition at line 275 of file Events.h.

#define TEMU_EVENT_IFACE_TYPE   "EventIface"

Definition at line 96 of file Events.h.

Typedef Documentation

typedef struct temu_Event temu_Event

typedef struct temu_EventQueue temu_EventQueue

Definition at line 42 of file Events.h.

typedef void(* temu_ThreadSafeCb)(void *)

Definition at line 60 of file Events.h.

Enumeration Type Documentation

enum temu_SyncEvent

Enumerator
teSE_Cpu
teSE_Machine

Definition at line 167 of file Events.h.

Function Documentation

TEMU_API void* temu_allocateEventQueue

(

void

)

Allocate event queue.

The function is deprecated for non-internal use. It will be removed from the public API in a later release.

Returns

Pointer to allocated event buffer

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

Add asynchronous event triggered by file descriptor changes

Parameters

Q	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_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_API int temu_asyncTimerAdd	(	void *	Q,
		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

Q	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_API void temu_asyncTimerRemove

(

int

Fd

)

Remove an async timer

Parameters

Fd	Timer ID to remove

TEMU_API void temu_disposeEventQueue

(

void *

Queue

)

Dispose event queue.

The function is deprecated for non-internal use. It will be removed from the public API in a later release.

Parameters

Queue

Buffer to be deleted

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_API void temu_eventDeschedule

(

int64_t

EvID

)

Deschedule event

Parameters

EvID	The event ID of the event to deschedule.

TEMU_API int64_t temu_eventGetCycles	(	void *	Q,
		int64_t	EvID
	)

Get delta time in cycles for the given event and queue

Parameters

Q	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_API int64_t temu_eventGetNanos	(	void *	Q,
		int64_t	EvID
	)

Get delta time in nanoseconds for the given event and queue

Parameters

Q	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_API int64_t temu_eventGetOldStyleID	(	void(*)(void *, void *)	Ev,
		void *	Sender
	)

Get a legacy style event ID

Parameters

Ev	Event handling function
Sender	The object issuing the event

Returns

Event ID

TEMU_API double temu_eventGetSecs	(	void *	Q,
		int64_t	EvID
	)

Get delta time in seconds for the given event and queue

Parameters

Q	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_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_API void temu_eventPostAsync	(	void *	Q,
		temu_ThreadSafeCb	CB,
		void *	Data,
		temu_SyncEvent	Sync
	)

Post an event to an asynchronous queue

Parameters

Q	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_API void temu_eventPostCycles	(	void *	Q,
		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

Q	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_API void temu_eventPostNanos	(	void *	Q,
		int64_t	EvID,
		int64_t	Delta,
		temu_SyncEvent	Sync
	)

Post events with a relative time in nanoseconds in the future

Parameters

Q	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_API void temu_eventPostSecs	(	void *	Q,
		int64_t	EvID,
		double	Delta,
		temu_SyncEvent	Sync
	)

Post events with a relative time in seconds in the future

Parameters

Q	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_API void temu_eventPostStack	(	void *	Q,
		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

Q	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_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 checkpointed (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_API int64_t temu_eventPublishOldStyle	(	const char *	Name,
		void *	Obj,
		void(*)(void *, void *)	Ev
	)

Publish an old style event

Parameters

Name	Event name
Obj	Object issuing the event
Ev	Event handling function

Returns

Event ID

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_API uint64_t temu_eventQueueGetFreq

(

void *

Q

)

Get the frequency in Hz of the given queue.

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_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_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_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

TEMU_IFACE_REFERENCE_TYPE

(

temu_Event

)

TEMU_API void temu_postCallbackInQueue	(	void *	Queue,
		temu_ThreadSafeCb	Cb,
		void *	Arg
	)

Post an event directly into a queue object.

The queue object must be allocated with allocateEventQueue() The function is deprecated for non-internal use. It will be removed from the public API in a later release.

Parameters

Queue	Pointer to the queue object
Cb	Thread-safe call-back function
Arg	The context argument to pass to the call-back function

TEMU_API void temu_removeCallbackInQueue	(	void *	Queue,
		temu_ThreadSafeCb	Cb,
		void *	Arg
	)

Remove an event from a queue object.

The queue object must be allocated with allocateEventQueue() The function is deprecated for non-internal use. It will be removed from the public API in a later release.

Parameters

Queue	Pointer to the queue object
Cb	Thread-safe call-back function
Arg	The context argument to pass to the call-back function