Registry services.
[Xenomai nucleus.]

Collaboration diagram for Registry services.:

---

Detailed Description

The registry provides a mean to index real-time object descriptors created by Xenomai skins on unique alphanumeric keys. When labeled this way, a real-time object is globally exported; it can be searched for, and its descriptor returned to the caller for further use; the latter operation is called a "binding". When no object has been registered under the given name yet, the registry can be asked to set up a rendez-vous, blocking the caller until the object is eventually registered.

Files
file	registry.h
	This file is part of the Xenomai project.
file	registry.c
	This file is part of the Xenomai project.
Functions
int	xnregistry_enter (const char *key, void *objaddr, xnhandle_t *phandle, xnpnode_t *pnode)
int	xnregistry_bind (const char *key, xnticks_t timeout, xnhandle_t *phandle)
int	xnregistry_remove (xnhandle_t handle)
int	xnregistry_remove_safe (xnhandle_t handle, xnticks_t timeout)
void *	xnregistry_get (xnhandle_t handle)
u_long	xnregistry_put (xnhandle_t handle)
void *	xnregistry_fetch (xnhandle_t handle)

---

Function Documentation

int xnregistry_bind	(	const char *	key,
		xnticks_t	timeout,
		xnhandle_t *	phandle
	)

Bind to a real-time object.

This service retrieves the registry handle of a given object identified by its key. Unless otherwise specified, this service will block the caller if the object is not registered yet, waiting for such registration to occur.

Parameters:

	key	A valid NULL-terminated string which identifies the object to bind to.
	timeout	The number of clock ticks to wait for the registration to occur (see note). Passing XN_INFINITE causes the caller to block indefinitely until the object is registered. Passing XN_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.
	phandle	A pointer to a memory location which will be written upon success with the generic handle defined by the registry for the retrieved object. Contents of this memory is undefined upon failure.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if key is NULL.

• -EINTR is returned if xnpod_unblock_thread() has been called for the waiting thread before the retrieval has completed.

• -EWOULDBLOCK is returned if timeout is equal to XN_NONBLOCK and the searched object is not registered on entry. As a special exception, this error is also returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).

• -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine only if timeout is equal to XN_NONBLOCK.

• Kernel-based thread.

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:

The timeout value will be interpreted as jiffies if thread is bound to a periodic time base (see xnpod_init_thread), or nanoseconds otherwise.

int xnregistry_enter	(	const char *	key,
		void *	objaddr,
		xnhandle_t *	phandle,
		xnpnode_t *	pnode
	)

Register a real-time object.

This service allocates a new registry slot for an associated object, and indexes it by an alphanumeric key for later retrieval.

Parameters:

	key	A valid NULL-terminated string by which the object will be indexed and later retrieved in the registry. Since it is assumed that such key is stored into the registered object, it will *not* be copied but only kept by reference in the registry.
	objaddr	An opaque pointer to the object to index by key.
	phandle	A pointer to a generic handle defined by the registry which will uniquely identify the indexed object, until the latter is unregistered using the xnregistry_remove() service.
	pnode	A pointer to an optional /proc node class descriptor. This structure provides the information needed to export all objects from the given class through the /proc filesystem, under the /proc/xenomai/registry entry. Passing NULL indicates that no /proc support is available for the newly registered object.

Returns:

0 is returned upon success. Otherwise:

• -EINVAL is returned if key or objaddr are NULL, or if key constains an invalid '/' character.

• -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the object.

• -EEXIST is returned if the key is already in use.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based thread

Rescheduling: possible.

void* xnregistry_fetch

(

xnhandle_t

handle

)

Find a real-time object into the registry.

This service retrieves an object from its handle into the registry and returns the memory address of its descriptor.

Parameters:

handle

The generic handle of the object to fetch. If XNOBJECT_SELF is passed, the object is the calling Xenomai thread.

Returns:

The memory address of the object's descriptor is returned on success. Otherwise, NULL is returned if handle does not reference a registered object, or if handle is equal to XNOBJECT_SELF but the current context is not a real-time thread.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine only if handle is different from XNOBJECT_SELF.

• Kernel-based thread

Rescheduling: never.

void* xnregistry_get

(

xnhandle_t

handle

)

Find and lock a real-time object into the registry.

This service retrieves an object from its handle into the registry and prevents it removal atomically. A locking count is tracked, so that xnregistry_get() and xnregistry_put() must be used in pair.

Parameters:

handle

The generic handle of the object to find and lock. If XNOBJECT_SELF is passed, the object is the calling Xenomai thread.

Returns:

The memory address of the object's descriptor is returned on success. Otherwise, NULL is returned if handle does not reference a registered object, or if handle is equal to XNOBJECT_SELF but the current context is not a real-time thread.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine only if handle is different from XNOBJECT_SELF.

• Kernel-based thread.

Rescheduling: never.

u_long xnregistry_put

(

xnhandle_t

handle

)

Unlock a real-time object from the registry.

This service decrements the lock count of a registered object previously locked by a call to xnregistry_get(). The object is actually unlocked from the registry when the locking count falls down to zero, thus waking up any thread currently blocked on xnregistry_remove() for unregistering it.

Parameters:

handle

The generic handle of the object to unlock. If XNOBJECT_SELF is passed, the object is the calling Xenomai thread.

Returns:

The decremented lock count is returned upon success. Zero is also returned if handle does not reference a registered object, or if handle is equal to XNOBJECT_SELF but the current context is not a real-time thread.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine only if handle is different from XNOBJECT_SELF.

• Kernel-based thread

Rescheduling: possible if the lock count falls down to zero and some thread is currently waiting for the object to be unlocked.

int xnregistry_remove

(

xnhandle_t

handle

)

Forcibly unregister a real-time object.

This service forcibly removes an object from the registry. The removal is performed regardless of the current object's locking status.

Parameters:

handle

The generic handle of the object to remove.

Returns:

0 is returned upon success. Otherwise:

• -ESRCH is returned if handle does not reference a registered object.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Kernel-based thread

Rescheduling: never.

int xnregistry_remove_safe	(	xnhandle_t	handle,
		xnticks_t	timeout
	)

Unregister an idle real-time object.

This service removes an object from the registry. The caller might sleep as a result of waiting for the target object to be unlocked prior to the removal (see xnregistry_put()).

Parameters:

	handle	The generic handle of the object to remove.
	timeout	If the object is locked on entry, param gives the number of clock ticks to wait for the unlocking to occur (see note). Passing XN_INFINITE causes the caller to block indefinitely until the object is unlocked. Passing XN_NONBLOCK causes the service to return immediately without waiting if the object is locked on entry.

Returns:

0 is returned upon success. Otherwise:

• -ESRCH is returned if handle does not reference a registered object.

• -EWOULDBLOCK is returned if timeout is equal to XN_NONBLOCK and the object is locked on entry.

• -EBUSY is returned if handle refers to a locked object and the caller could not sleep until it is unlocked.

• -ETIMEDOUT is returned if the object cannot be removed within the specified amount of time.

• -EINTR is returned if xnpod_unblock_thread() has been called for the calling thread waiting for the object to be unlocked.

Environments:

This service can be called from:

• Kernel module initialization/cleanup code
• Interrupt service routine only if timeout is equal to XN_NONBLOCK.

• Kernel-based thread.

Rescheduling: possible if the object to remove is currently locked and the calling context can sleep.

Note:

The timeout value will be interpreted as jiffies if the current thread is bound to a periodic time base (see xnpod_init_thread), or nanoseconds otherwise.

---