NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO
#include <lap/chLap.h>int svLapCreate(KnCap * actorcap, KnLapHdl laphdl, void * cookie, unsigned int options, KnLapDesc * lapdesc);
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.
CORE, (LAPSAFE)
The svLapCreate() system call creates a new local access point (LAP) for the actor designated by the actorcap capability. If actorcap is equal to K_MYACTOR , the home actor of the calling thread is considered. If the call succeeds, the LAP descriptor pointed to by lapdesc represents this new LAP and can be passed to client threads that will use it to invoke the LAP handler.
On LAP invocation (see lapInvoke(2K) ), the laphdl handler is called. This handler is a function which takes two arguments:
void handler (arg, cookie) void *arg ; void *cookie ; |
Arg is the argument specified by lapInvoke(2K) and cookie is the value of the cookie specified by svLapCreate() .
By default, as a consequence of a LAP invocation, the execution actor of the calling thread is set to the actor that owns the LAP for the duration of the LAP handler execution.
Additional actions may take place during the LAP invocation, depending on the combination of flags specified in the options parameter:
A LAP frame descriptor is allocated to register the calling thread as a temporary resource of the invoked actor. Each LAP frame has an associated level (LAP frame level) which represents the number of LAP frames for the thread.
This option is valid only if the LAPSAFE feature has been set. K_LAP_SAFE enforces more rigorous checking during LAP invocation. This guarantees, in particular, that the microkernel synchronizes the svLapDelete(2K) operation with concurrent LAP invocations.
In addition, full context of the calling thread is saved prior to the LAP invocation. This guarantees that the calling thread can return from its invocation even if a failure, such as an exception or deletion of the actor that owns the LAP, occurs during the execution of the LAP handler.
This option is mandatory for LAPs to be called from user mode.
The two utility routines lapDescZero() and lapDescIsZero() are available to manipulate the state of a LAP descriptor with the following semantics. If a LAP descriptor has been initialized with lapDescZero() or is implemented in a zero-filled memory region, lapDescIsZero() returns a non-zero value until the LAP descriptor has been successfully initialized by svLapCreate() or lapResolve(2K) .
lapDescDup() must be used to duplicate the contents of a LAP descriptor.
On success, svLapCreate() returns K_OK . Otherwise, a negative error code is returned.
lapDescIsZero() returns a non-zero value if the LAP descriptor is not initialized.
lapDescZero() and lapDescDup() have no return values.
The current implementation does not support the K_LAP_SETJMP option, which is silently ignored.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | RESTRICTIONS | ATTRIBUTES | SEE ALSO