ChorusOS man pages section 3EXT: ChorusOS Extensions

syseventGetConf(3EXT)

NAME

syseventGetConf- retrieve sysevent configuration settings

SYNOPSIS

$(NUCLEUS_DIR)/lib/sysevent/sysevent.a
#include <sysevent/chSysevent.h>

parm

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

PARAMETERS

parm: Address of a KnSyseventParm structure holding the configuration settings.

DESCRIPTION

The syseventGetConf() function fills the parm structure with the sysevent settings specified at system configuration time.

These settings include:

A system-wide event space identifier, used by all the participants to resolve a common event space prior to any interaction
For each event queue, the number and the size of the event buffers to be allocated.

At least K_SYSEVENT_DEFAULT_QUEUES are available. A number of extra event queues (up to and including K_SYSEVENT_EXTRA_QUEUES) can also be configured. The number of configured extra queues, and the number and size of their dedicated event buffers is also returned by syseventGetConf().

These configuration settings are read from the SYSEVENT_CONF environment variable. The format of this variable is as follows:

<msg space id> <event nbr>:<event size> <event nbr>:<event size>...

In this variable there is one <event nbr>:<event size> pair per event queue.

Following the 32-bit global event space identifier, the number of <event nbr>:<event size> pairs defines the number of valid event queues. At least K_SYSEVENT_DEFAULT_QUEUES pairs must be configured.

The mandatory pairs are related to the following predefined queues:

K_SYSEVENT_NUCLEUS: Used by the Chorus OS microkernel to publish system events
K_SYSEVENT_DRV: Used by the device drivers to publish events
K_SYSEVENT_OS: Used by the Chorus OS operating system (C_OS) to publish events
K_SYSEVENT_USER: Used by user-level applications to publish events

The use of the following extra event queues, if any, is application-specific.

At most K_SYSEVENT_EVNUMBER_MAX events can be allocated per event queue. The size of an event is also bounded by K_SYSEVENT_EVSIZE_MAX.

The configured event queues are then identified by two index ranges:

The default queue index range defined by the macros K_SYSEVENT_NUCLEUS, K_SYSEVENT_DRV, K_SYSEVENT_OS, and K_SYSEVENT_USER;
The extra queue index range from 0 to K_SYSEVENT_EXTRA_QUEUES - 1.

Consequently, any event queue identifier must belong to one of these index ranges when syseventAllocate(), syseventPut() or syseventGet() is invoked. Otherwise, the identifier is considered invalid.

RETURN VALUE

K_OK is returned on successful completion. Otherwise, a negative error code is returned.

ERRORS

[K_EFAIL]

No SYSEVENT_CONF environment variable found

[K_ENOMEM]

The SYSEVENT_CONF variable exceeds the maximum length accepted by sysGetEnv()

[K_EADDR]

Parm has a null value

[K_EINVAL]

For one of the following reasons:

SYSEVENT_CONF defines less than K_SYSEVENT_DEFAULT_QUEUES queues
SYSEVENT_CONF defines more than K_SYSEVENT_DEFAULT_QUEUES + K_SYSEVENT_EXTRA_QUEUES queues
the event space identifier has a negative or a null value
an event size has a negative or a null value
an event number has a negative or a null value
the format of the SYSEVENT_CONF variable is incorrect

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving