Notifications

Kernel internals supporting cross-process notifications. More...

Data Structures
struct	NotificationObject

Macros
#define	OS_NOTIFY_INVALID   0xFFFFFFFF

Enumerations
enum	EventTypes { EVT_DEFAULT = 0 , EVT_TIMEOUT , _EVT_COUNT }
	List of possible notification types. More...

Functions
void	os_notify_init ()
	Initialize the notification structure This will initialize internal notification buffers to the default unused state.
int	os_notify_thread (Thread_t thread_id, int candidate_timer, Event_t event)
	Notify specific thread waiting for object Delivers notification to a specific thread.
int	os_notify_object (const void *object, Event_t event, uint32_t flags)
	Resume one thread that are waiting for this object.
int	os_wait_for_object (const void *object, WaitHandler_t callback, uint32_t flags)
	Wait for object.
int	os_initialize_waitable_object (const void *object)
	Initialize waitable object.
int	os_sys_notify_object (const void *object)
	Implementation of notify_object syscall.
int	os_sys_notify_object2 (const void *object, uint32_t flags)
	Implementation of notify_object2 syscall.
int	os_sys_wait_for_object (const void *object, uint32_t timeout)
	Implementation of wait_for_object syscall.
int	os_sys_wait_for_object_value (uint8_t *object, uint8_t value, uint32_t timeout, uint32_t flags)
	Implementation of wait_for_object_value syscall.

Detailed Description

Kernel internals supporting cross-process notifications.

Notifications are concept that can be used to notify other threads implicitly without knowing their identity. The identity of notified thread is established based on the match of the object notified and waited for.

Thread which is waiting for notification can install a kernel-space callback that gets called before the thread is resumed.

Macro Definition Documentation

OS_NOTIFY_INVALID

#define OS_NOTIFY_INVALID   0xFFFFFFFF

Enumeration Type Documentation

EventTypes

enum EventTypes

List of possible notification types.

Notification subsystem allows for several notification types. Normally, the "default" notification is delivered to the waiting thread. Kernel can internally generate another types of notifications which can only be served by an actual waiting thread and cannot be stored into pending notification list.

Enumerator
EVT_DEFAULT	The default notification Notification delivering the information that event waiting thread was waiting for has happened.
EVT_TIMEOUT	Timeout notification Notification delivering the information that waiting for notification has timed out.
_EVT_COUNT

Function Documentation

cb_syscall_notify_object()

void cb_syscall_notify_object	(	const void *	object,
		Thread_t	thread,
		int	sleeper,
		Event_t	event
	)

Callback implementing reception of a userspace notification.

Warning

This callback is not executed within the context of the notified thread, rather in the context of notifying thread. The state of notified thread is largely pre-notification at this point.

This callback will manipulate thread state when notification is received. Handling is different when notification is received via notify_object and wait reaching timeout value.

os_initialize_waitable_object()

int os_initialize_waitable_object

(

const void *

object

)

Initialize waitable object.

Call to this function will initialize clean state: no one is waiting, no one had notified this particular object. If any notifications were pending for this object they will be deleted.

Parameters

object

address of the object for which notifications are being initialized

os_notify_init()

void os_notify_init

(

)

Initialize the notification structure This will initialize internal notification buffers to the default unused state.

os_notify_object()

int os_notify_object	(	const void *	object,
		Event_t	event,
		uint32_t	flags
	)

Resume one thread that are waiting for this object.

This function will find one single thread which is waiting for this particular object. If more than one thread is waiting for this object, then the thread with the highest priority will be resumed.

Parameters

object	address of the object that is notified
event	event that is signalled to the object

Returns

E_OK if any thread was waiting for this object and was woken up

Note

The object address is mostly meaningless. It allows threads to synchronize on any objects both externally from the userspace and internally in the kernel.

os_notify_thread()

int os_notify_thread	(	Thread_t	thread_id,
		int	candidate_timer,
		Event_t	event
	)

Notify specific thread waiting for object Delivers notification to a specific thread.

Parameters

thread_id	ID of thread notification has to be delivered to
event	event the thread is notified of

Returns

E_OK if thread was notified and no further action is needed; E_NOTAVAIL if thread is not waiting for any object and E_YIELD if scheduler yield may be required.

os_sys_notify_object()

int os_sys_notify_object

(

const void *

object

)

Implementation of notify_object syscall.

This is a wrapper around os_notify_object system call. It does some additional checking on arguments. See notify_object and os_notify_object for more info.

os_sys_notify_object2()

int os_sys_notify_object2	(	const void *	object,
		uint32_t	flags
	)

Implementation of notify_object2 syscall.

This is a wrapper around os_notify_object system call. It does some additional checking on arguments.

Parameters

object	address of the object that is being waited for
flags	optional flags affecting function behavior See notify_object and os_notify_object for more info.

os_sys_wait_for_object()

int os_sys_wait_for_object	(	const void *	object,
		uint32_t	timeout
	)

Implementation of wait_for_object syscall.

This is a wrapper around os_wait_for_object system call. It does some additional checking on arguments. See wait_for_object and os_wait_for_object for more info.

os_sys_wait_for_object_value()

int os_sys_wait_for_object_value	(	uint8_t *	object,
		uint8_t	value,
		uint32_t	timeout,
		uint32_t	flags
	)

Implementation of wait_for_object_value syscall.

This is a wrapper around os_wait_for_object system call. It does some additional checking on arguments. See wait_for_object and os_wait_for_object for more info.

os_wait_for_object()

int os_wait_for_object	(	const void *	object,
		WaitHandler_t	callback,
		uint32_t	flags
	)

Wait for object.

This function will block thread until some other thread notifies the object. Threads are being woken up based on their priorities. Highest priority first.

Parameters

object	address of the object that is being waited for
callback	address of the callback function that handles wakeup
flags	optional flags affecting function behavior

Returns

E_OK if thread is capable of waiting, E_BUSY if thread is already waiting for something, E_INVALID if callback is a NULL pointer