kmo_invoke

Signature

Status kmo_invoke(
	CapRef	container,
	Bool	nested,
	Caddr	args,
	Csize	args_size)

Arguments

container - A CapRef referring to a container.
nested - Determines whether it is possible to return to the current address space.
args - The address of the argument block to be passed to the invoked address space.
args_size - The size of the argument block to be passed.

Semantics

kmo_invoke changes the address space of the calling locus to that defined by container and transfers the point of execution to the invocation point associated with container.

The nested flag allows the level of invocation nesting to be controlled. When the nested flag is set, the current invocation is placed on a stack and left outstanding while another takes place. Use of kmo_invoke in this manner is said to add one level of invocation nesting to the calling locus. A subsequent call to kmo_return may be used to remove a level of nesting. When the nested flag is not set, kmo_invoke provides a mechanism through which a locus may jump from one address space to another. The level of invocation nesting for the calling locus is unaffected. The net effect is to replace the top of the invocation stack with the new invocation.

The block of data defined by [args, args + args_size - 1] is passed by value at the time of the call. The contents of the block can be accessed from within the new address space following a call to get_in_args. Any data stored in certain architecture specific registers is preserved by the invocation. These registers are currently defined for the Alpha AXP archictecture.

Status

An invocation may fail and return the following Status values:

INVALID_CAPREF

This occurs if container specifies a Capref that is either illegally formed or does not refer to any capability.

INVALID_ENTITY

This is returned when container is a valid Capref but it does not refer to a capability for a container.

INVOCATION_DENIED

This occurs when container refers to a capability for a container that is not bound to a permission group which allows invocation of the container.

NO_INVOCATION_POINT

This occurs when an attempt is made to invoke a container for which there is no invocation point.

ARGS_TOO_LARGE

This occurs if the call is attempting to pass an argument block which, due to its size, would exhaust a kernel resource.

CANNOT_NEST

This occurs if the nested flag is set and recording the necessary information would exhaust a kernel resource.

SUCCESS

If an invocation is successful then the code following the call to kmo_invoke is not immediately executed so it does not make sense to return a Status value. However, if this code is subsequently executed due to a kmo_return call, it will appear as if the call to kmo_invoke returns a Status value of SUCCESS.