bulk_transfer.h File Reference

Generic bulk data transfer mechanism. More...

Data Structures
struct	bulk_continuation
struct	bulk_implementation
struct	bulk_channel_constraints
struct	bulk_channel_callbacks
struct	bulk_channel
struct	bulk_endpoint_descriptor
struct	bulk_pool_id
struct	bulk_pool
struct	bulk_pool_list
struct	bulk_buffer
struct	bulk_channel_setup
struct	bulk_channel_bind_params

Enumerations

Functions
errval_t	bulk_channel_create (struct bulk_channel *channel, struct bulk_endpoint_descriptor *ep_desc, struct bulk_channel_callbacks *callbacks, struct bulk_channel_setup *setup)
errval_t	bulk_channel_bind (struct bulk_channel *channel, struct bulk_endpoint_descriptor *remote_ep_desc, struct bulk_channel_callbacks *callbacks, struct bulk_channel_bind_params *params, struct bulk_continuation cont)
errval_t	bulk_channel_assign_pool (struct bulk_channel *channel, struct bulk_pool *pool, struct bulk_continuation cont)
errval_t	bulk_channel_remove_pool (struct bulk_channel *channel, struct bulk_pool *pool, struct bulk_continuation cont)
errval_t	bulk_channel_destroy (struct bulk_channel *channel, struct bulk_continuation cont)
errval_t	bulk_channel_move (struct bulk_channel *channel, struct bulk_buffer *buffer, void *meta, struct bulk_continuation cont)
errval_t	bulk_channel_pass (struct bulk_channel *channel, struct bulk_buffer *buffer, void *meta, struct bulk_continuation cont)
errval_t	bulk_channel_copy (struct bulk_channel *channel, struct bulk_buffer *buffer, void *meta, struct bulk_continuation cont)
errval_t	bulk_channel_release (struct bulk_channel *channel, struct bulk_buffer *buffer, struct bulk_continuation cont)

Detailed Description

Generic bulk data transfer mechanism.

Enumeration Type Documentation

enum bulk_buffer_state

represents the state of a buffer

Enumerator
BULK_BUFFER_INVALID	the buffer is not present XXX: name?
BULK_BUFFER_READ_ONLY	the buffer is mapped read only
BULK_BUFFER_RO_OWNED	the buffer is copied first
BULK_BUFFER_READ_WRITE	the buffer is mapped read write

enum bulk_channel_direction

Specifies the direction of data flow over a channel.

Enumerator
BULK_DIRECTION_TX	This side of the channel is the data source.
BULK_DIRECTION_RX	This side of the channel is the data sink.

enum bulk_channel_role

The role of the domain with respect to the channel.

1) Creation: upon channel creation the role can either be given or generic 2) Binding: The roles are given either Master-Slave or Slave-Master

Enumerator
BULK_ROLE_GENERIC	the role of this endpoint depends on the binding side
BULK_ROLE_MASTER	this endpoint is the channel master
BULK_ROLE_SLAVE	this endpoint is the channel slave

enum bulk_channel_state

Enumerator
BULK_STATE_UNINITIALIZED	channel not initialized, no endpoint assigned
BULK_STATE_INITIALIZED	local endpoint assigned, ready for binding
BULK_STATE_BINDING	binding is in progress
BULK_STATE_BIND_NEGOTIATE	channel properties are negotiated (role, trust)
BULK_STATE_CONNECTED	binding is completed and ready for use
BULK_STATE_TEARDOWN	teardown is initiated
BULK_STATE_CLOSED	the channel has been closed

enum bulk_trust_level

the trust levels of the channel

Enumerator
BULK_TRUST_UNINITIALIZED	trust level is not initialized
BULK_TRUST_NONE	untrusted case, policies are enforced
BULK_TRUST_HALF	same as untrusted, but no revocation of caps
BULK_TRUST_FULL	complete trust, no unmapping

Function Documentation

errval_t bulk_channel_assign_pool	(	struct bulk_channel *	channel,
		struct bulk_pool *	pool,
		struct bulk_continuation	cont
	)

Assign a pool to a channel.

Parameters

channel	Channel
pool	Pool to assign (must not be assigned to this channel yet)

• There is the pool assigned callback that serves as a continuation for this.

Assign a pool to a channel.

Parameters

channel	Channel
pool	Pool to assign (must not be assigned to this channel yet)

errval_t bulk_channel_bind	(	struct bulk_channel *	channel,
		struct bulk_endpoint_descriptor *	remote_ep_desc,
		struct bulk_channel_callbacks *	callbacks,
		struct bulk_channel_bind_params *	params,
		struct bulk_continuation	cont
	)

Bind to an existing unbound channel.

Parameters

channel	Pointer to unused channel handle
ep_desc	Description of endpoint to bind to
callbacks	Callbacks for events on this channel
params	parameters for the binding process

There is the bind done callback that serves as a continuation for this.

Bind to an existing unbound channel.

Parameters

channel	Pointer to unused channel handle
ep_desc	Description of the remote endpoint to bind to
callbacks	Callbacks for events on this channel
params	bind parameters

errval_t bulk_channel_copy	(	struct bulk_channel *	channel,
		struct bulk_buffer *	buffer,
		void *	meta,
		struct bulk_continuation	cont
	)

Copy buffer to other endpoint.

Parameters

channel	Channel, this endpoint must be source
buffer	Buffer, must belong to a pool on this channel. Must hold ownersihp, or hold a copy of this buffer.
meta	Pointer to metadata to be passed along with the buffer (channel-wide meta_size is used).
cont	event continuation

errval_t bulk_channel_create	(	struct bulk_channel *	channel,
		struct bulk_endpoint_descriptor *	local_ep_desc,
		struct bulk_channel_callbacks *	callbacks,
		struct bulk_channel_setup *	setup
	)

Create a new channel.

Parameters

channel	Pointer to unused channel handle
ep_desc	Description of endpoint to bind to
callbacks	Callbacks for events on this channel
setup	struct containing the setup information

errval_t bulk_channel_destroy	(	struct bulk_channel *	channel,
		struct bulk_continuation	cont
	)

Free a channel

Parameters

channel

Channel to be freed

Free a channel

Parameters

channel	Channel to be freed
free_resources	Flag if the resources i.e. pools also should be freed

errval_t bulk_channel_move	(	struct bulk_channel *	channel,
		struct bulk_buffer *	buffer,
		void *	meta,
		struct bulk_continuation	cont
	)

Move buffer on the channel. Data and ownership are passed to the other endpoint. After the other endpoint is done with the respective buffer, it can pass it back.

Parameters

channel	Channel, this endpoint must be source
buffer	Buffer, must hold ownership and belong to a pool on this channel
meta	Pointer to metadata to be passed along with the data (channel-wide meta_size is used).
cont	event continuation

errval_t bulk_channel_pass	(	struct bulk_channel *	channel,
		struct bulk_buffer *	buffer,
		void *	meta,
		struct bulk_continuation	cont
	)

Pass buffer ownership to the other endpoint, the buffer contents are not guaranteed to be transported.

Parameters

channel	Channel
buffer	Buffer, must hold ownership and belong to a pool on this channel
meta	Pointer to metadata to be passed along with the buffer (channel-wide meta_size is used).
cont	event continuation

errval_t bulk_channel_release	(	struct bulk_channel *	channel,
		struct bulk_buffer *	buffer,
		struct bulk_continuation	cont
	)

Release copy received over channel. Must only be called after all outgoing copies from this domain of the same buffer have been released.

Parameters

channel	Channel, this endpoint must be sink
buffer	Buffer, must have received it as a copy over this channel, all outgoing copies must have been released.
cont	event continuation

errval_t bulk_channel_remove_pool	(	struct bulk_channel *	channel,
		struct bulk_pool *	pool,
		struct bulk_continuation	cont
	)

Remove a pool from a channel

Parameters

channel	Channel
pool	Pool to remove (must be previously assigned to the channel)