dsi.h File Reference

DROPS Stream Interface public API. More...

Go to the source code of this file.

Functions

int dsi_init (void)

Library initialization.

void dsi_jcp_2_config (dsi_jcp_stream_t *jcp, dsi_stream_cfg_t *s_cfg)

Convert jcp to stream-config.

int dsi_set_sync_thread_prio (int new_prio)

Set priority of syncronisation threads created in the future.

int dsi_set_select_thread_prio (int new_prio)

Set priority of the select threads created in the future.

int dsi_set_event_thread_prio (int new_prio)

Set priority of event thread created in the future.

int dsi_socket_create (dsi_jcp_stream_t jcp_stream, dsi_stream_cfg_t cfg, l4dm_dataspace_t *ctrl_ds, l4dm_dataspace_t *data_ds, l4_threadid_t work_id, l4_threadid_t *sync_id, l4_uint32_t flags, dsi_socket_t **socket)

Create new send/receive socket.
This function allocates the necessary dataspaces, maps them, and creates the synchronisation thread using dsi_create_sync_thread(). The dataspace for the data area can be defined by the caller. Specify DSI_PACKET_MAP to indicate a preallocated dataspace. If no (invalid) control area or synchronization thread are specified, they are created.

int dsi_socket_stop (dsi_socket_t *socket)

Stop a socket.
This function stops the synchronisation thread. This ensures that the synchronization thread does not touch the control area any longer. This would be a problem if the sender sends a commit-message and destroys the control area afterwards: The receiver is scheduled (depending on the priorities), sees the received message and tries to access the (unmapped) control area.

int dsi_socket_close (dsi_socket_t *socket)

Close a socket.
This function stops the synchronisation thread and frees the allocated dataspaces. If the data dataspace was allocated prior to calling dsi_socket_create(), it will not be deleted.

int dsi_socket_connect (dsi_socket_t *socket, const dsi_socket_ref_t *remote_socket)

Connect the socket to a partner
This function enters the data describing a remote endpoint into the socket structure. No start IPC or similar things are performed here.

int dsi_socket_set_sync_callback (dsi_socket_t *socket, dsi_sync_callback_fn_t func)

Set callback for syncronisation events.
The specified function will be called if synchronisation IPC is necessary due to blocking. The call will be performed inside packet_get(), immediately before the request for sync-IPC is sent to the peer.

int dsi_socket_set_release_callback (dsi_socket_t *socket, dsi_release_callback_fn_t func)

Set callback for release events.
The specified function will be called if the release event is triggered. The release event will be triggered when the partner commits a packet with dsi_packet_commit() and release notification is set for this packet or the entire stream (flag DSI_PACKET_RELEASE_CALLBACK).

int dsi_socket_get_ref (dsi_socket_t *socket, dsi_socket_ref_t *ref)

Obtain a reference to a socket
This function returns a reference to a socket which can be passed to another task. The other task can use the reference to communicate with this socket (see dsi_socket_connect()).

int dsi_socket_get_descriptor (dsi_socketid_t id, dsi_socket_t **socket)

Get the socket of a given socket-ID.
To get the socket of a socket reference x (dsi_socket_ref_t), use dsi_socket_get_descriptor(x.socket,&s). Note, the socket reference must refer to a socket in the own task.

int dsi_socket_get_data_area (dsi_socket_t *socket, void **data_area, l4_size_t *area_size)

Return start address and size of data area.
On socket creation, the data area is mapped into the local address space. Use this function should be used to get a pointer to the mapped area.

int dsi_socket_set_flags (dsi_socket_t *socket, l4_uint32_t flags)

Set socket flags.

int dsi_socket_clear_flags (dsi_socket_t *socket, l4_uint32_t flags)

Clear socket flags.

int dsi_socket_test_flag (dsi_socket_t *socket, l4_uint32_t flag)

Test socket flag.

int dsi_socket_set_event (dsi_socket_t *socket, l4_uint32_t events)

Set event.

int dsi_socket_share_ds (dsi_socket_t *socket, l4_threadid_t client)

Share socket dataspaces.

int dsi_socket_get_packet_num (dsi_socket_t *socket)

Return number of packets in ring list.

int dsi_socket_get_num_committed_packets (dsi_socket_t *socket)

Return number of committed send packets in ring list.

int dsi_packet_get (dsi_socket_t *socket, dsi_packet_t **packet)

Request next send/receive packet.

int dsi_packet_get_abort (dsi_socket_t *socket)

Abort an ongoing packet_get() in the work-thread.

int dsi_packet_commit (dsi_socket_t *socket, dsi_packet_t *packet)

Commit send / release receive packet.

int dsi_packet_add_data (dsi_socket_t *socket, dsi_packet_t *packet, void *addr, l4_size_t size, l4_uint32_t flags)

Add data area to packet's scatter gather list.

int dsi_packet_get_data (dsi_socket_t *socket, dsi_packet_t *packet, void **addr, l4_size_t *size)

Get next data area from packet.

int dsi_packet_set_no (dsi_socket_t *socket, dsi_packet_t *packet, l4_uint32_t no)

Set packet number.

int dsi_packet_get_no (dsi_socket_t *socket, dsi_packet_t *packet, l4_uint32_t *no)

Get packet number.

int dsi_packet_get_nr (dsi_socket_t *socket, unsigned nr, dsi_packet_t **packet)

Wait for specific packet.

void dsi_ds_set_dataspace_manager (l4_threadid_t id)

Set new dataspace manager.

int dsi_ds_setup_ctrl_dataspace (l4dm_dataspace_t *ds, dsi_stream_cfg_t cfg)

Setup control dataspace.

int dsi_ds_create_ctrl_dataspace (dsi_stream_cfg_t cfg, l4dm_dataspace_t *ds)

Create control dataspace.

int dsi_stream_create (dsi_component_t *sender, dsi_component_t *receiver, l4dm_dataspace_t ctrl, l4dm_dataspace_t data, dsi_stream_t **stream)

Create application stream and connect send/receive component.

int dsi_stream_close (dsi_stream_t *stream)

Close stream.

int dsi_stream_start (dsi_stream_t *stream)

Send start messages to send/receive components.

int dsi_stream_stop (dsi_stream_t *stream)

stop the transfer on a stream
This function calls the stop-functions provided on dsi_stream_create() to stop the data transfer. It is up to the two components to react in a reasonable way, dsi does not check anything, it just calls the functions, first sender, receiver then.

int dsi_stream_select (dsi_select_socket_t *sockets, const int num_sockets, dsi_select_socket_t *events, int *num_events)

Wait for component events.

int dsi_thread_start_worker (dsi_socket_t *socket, l4_umword_t *ret_code)

Send start message to work thread and wait for ready-notification.
We start the work-thread and wait until it gives an ok..

int dsi_thread_worker_wait (dsi_socket_t **socket)

Wait until our parent sends the socket.

int dsi_thread_worker_started (int ret_code)

Send ready-notification to parent thread.

int dsi_socket_local_create (dsi_stream_cfg_t cfg, l4dm_dataspace_t *ctrl_ds, l4dm_dataspace_t *data_ds, l4_threadid_t work_id, l4_uint32_t flags, dsi_socket_t **socket, dsi_component_t *comp)

Open-function for use with local sockets.

int dsi_socket_local_close (dsi_component_t *comp)

Close-function for use with local socket refs
This callback can be used for the close-callback in a DSI component descriptor (dsi_component_t) if the socket is a socket in the local address space, and no other actions must be performed on connecting a socket than to call dsi_socket_close().

int dsi_socket_local_connect (dsi_component_t *comp, dsi_socket_ref_t *remote)

Connect-function for use with local socket refs
This callback can be used for the connect-callback in a DSI component descriptor (dsi_component_t) if the socket is a socket in the local address space, and no other actions must be performed on connecting a socket than to call dsi_socket_connect().

int dsi_socket_local_stop (dsi_component_t *comp)

Stop-function for use with local socket refs
This callback can be used for the stop-callback in a DSI component descriptor (dsi_component_t) if the socket is a socket in the local address space, and no other actions must be performed on connecting a socket than to call dsi_socket_stop().

Variables

__BEGIN_DECLS

__END_DECLS

Detailed Description

DROPS Stream Interface public API.

Date:: 07/01/2000

Author:: Lars Reuther <reuther@os.inf.tu-dresden.de>

See dsi/doc/ for further information.

Definition in file dsi.h.


Functions
int	dsi_init (void)
	Library initialization.
void	dsi_jcp_2_config (dsi_jcp_stream_t jcp, dsi_stream_cfg_t s_cfg)
	Convert jcp to stream-config.
int	dsi_set_sync_thread_prio (int new_prio)
	Set priority of syncronisation threads created in the future.
int	dsi_set_select_thread_prio (int new_prio)
	Set priority of the select threads created in the future.
int	dsi_set_event_thread_prio (int new_prio)
	Set priority of event thread created in the future.
int	dsi_socket_create (dsi_jcp_stream_t jcp_stream, dsi_stream_cfg_t cfg, l4dm_dataspace_t ctrl_ds, l4dm_dataspace_t data_ds, l4_threadid_t work_id, l4_threadid_t sync_id, l4_uint32_t flags, dsi_socket_t *socket)
	Create new send/receive socket. This function allocates the necessary dataspaces, maps them, and creates the synchronisation thread using dsi_create_sync_thread(). The dataspace for the data area can be defined by the caller. Specify DSI_PACKET_MAP to indicate a preallocated dataspace. If no (invalid) control area or synchronization thread are specified, they are created.
int	dsi_socket_stop (dsi_socket_t *socket)
	Stop a socket. This function stops the synchronisation thread. This ensures that the synchronization thread does not touch the control area any longer. This would be a problem if the sender sends a commit-message and destroys the control area afterwards: The receiver is scheduled (depending on the priorities), sees the received message and tries to access the (unmapped) control area.
int	dsi_socket_close (dsi_socket_t *socket)
	Close a socket. This function stops the synchronisation thread and frees the allocated dataspaces. If the data dataspace was allocated prior to calling dsi_socket_create(), it will not be deleted.
int	dsi_socket_connect (dsi_socket_t socket, const dsi_socket_ref_t remote_socket)
	Connect the socket to a partner This function enters the data describing a remote endpoint into the socket structure. No start IPC or similar things are performed here.
int	dsi_socket_set_sync_callback (dsi_socket_t *socket, dsi_sync_callback_fn_t func)
	Set callback for syncronisation events. The specified function will be called if synchronisation IPC is necessary due to blocking. The call will be performed inside packet_get(), immediately before the request for sync-IPC is sent to the peer.
int	dsi_socket_set_release_callback (dsi_socket_t *socket, dsi_release_callback_fn_t func)
	Set callback for release events. The specified function will be called if the release event is triggered. The release event will be triggered when the partner commits a packet with dsi_packet_commit() and release notification is set for this packet or the entire stream (flag DSI_PACKET_RELEASE_CALLBACK).
int	dsi_socket_get_ref (dsi_socket_t socket, dsi_socket_ref_t ref)
	Obtain a reference to a socket This function returns a reference to a socket which can be passed to another task. The other task can use the reference to communicate with this socket (see dsi_socket_connect()).
int	dsi_socket_get_descriptor (dsi_socketid_t id, dsi_socket_t **socket)
	Get the socket of a given socket-ID. To get the socket of a socket reference `x` (dsi_socket_ref_t), use `dsi_socket_get_descriptor`(x.socket,&s). Note, the socket reference must refer to a socket in the own task.
int	dsi_socket_get_data_area (dsi_socket_t socket, void data_area, l4_size_t area_size)
	Return start address and size of data area. On socket creation, the data area is mapped into the local address space. Use this function should be used to get a pointer to the mapped area.
int	dsi_socket_set_flags (dsi_socket_t *socket, l4_uint32_t flags)
	Set socket flags.
int	dsi_socket_clear_flags (dsi_socket_t *socket, l4_uint32_t flags)
	Clear socket flags.
int	dsi_socket_test_flag (dsi_socket_t *socket, l4_uint32_t flag)
	Test socket flag.
int	dsi_socket_set_event (dsi_socket_t *socket, l4_uint32_t events)
	Set event.
int	dsi_socket_share_ds (dsi_socket_t *socket, l4_threadid_t client)
	Share socket dataspaces.
int	dsi_socket_get_packet_num (dsi_socket_t *socket)
	Return number of packets in ring list.
int	dsi_socket_get_num_committed_packets (dsi_socket_t *socket)
	Return number of committed send packets in ring list.
int	dsi_packet_get (dsi_socket_t socket, dsi_packet_t *packet)
	Request next send/receive packet.
int	dsi_packet_get_abort (dsi_socket_t *socket)
	Abort an ongoing packet_get() in the work-thread.
int	dsi_packet_commit (dsi_socket_t socket, dsi_packet_t packet)
	Commit send / release receive packet.
int	dsi_packet_add_data (dsi_socket_t socket, dsi_packet_t packet, void *addr, l4_size_t size, l4_uint32_t flags)
	Add data area to packet's scatter gather list.
int	dsi_packet_get_data (dsi_socket_t socket, dsi_packet_t packet, void *addr, l4_size_t size)
	Get next data area from packet.
int	dsi_packet_set_no (dsi_socket_t socket, dsi_packet_t packet, l4_uint32_t no)
	Set packet number.
int	dsi_packet_get_no (dsi_socket_t socket, dsi_packet_t packet, l4_uint32_t *no)
	Get packet number.
int	dsi_packet_get_nr (dsi_socket_t socket, unsigned nr, dsi_packet_t *packet)
	Wait for specific packet.
void	dsi_ds_set_dataspace_manager (l4_threadid_t id)
	Set new dataspace manager.
int	dsi_ds_setup_ctrl_dataspace (l4dm_dataspace_t *ds, dsi_stream_cfg_t cfg)
	Setup control dataspace.
int	dsi_ds_create_ctrl_dataspace (dsi_stream_cfg_t cfg, l4dm_dataspace_t *ds)
	Create control dataspace.
int	dsi_stream_create (dsi_component_t sender, dsi_component_t receiver, l4dm_dataspace_t ctrl, l4dm_dataspace_t data, dsi_stream_t **stream)
	Create application stream and connect send/receive component.
int	dsi_stream_close (dsi_stream_t *stream)
	Close stream.
int	dsi_stream_start (dsi_stream_t *stream)
	Send start messages to send/receive components.
int	dsi_stream_stop (dsi_stream_t *stream)
	stop the transfer on a stream This function calls the stop-functions provided on dsi_stream_create() to stop the data transfer. It is up to the two components to react in a reasonable way, dsi does not check anything, it just calls the functions, first sender, receiver then.
int	dsi_stream_select (dsi_select_socket_t sockets, const int num_sockets, dsi_select_socket_t events, int *num_events)
	Wait for component events.
int	dsi_thread_start_worker (dsi_socket_t socket, l4_umword_t ret_code)
	Send start message to work thread and wait for ready-notification. We start the work-thread and wait until it gives an ok..
int	dsi_thread_worker_wait (dsi_socket_t **socket)
	Wait until our parent sends the socket.
int	dsi_thread_worker_started (int ret_code)
	Send ready-notification to parent thread.
int	dsi_socket_local_create (dsi_stream_cfg_t cfg, l4dm_dataspace_t ctrl_ds, l4dm_dataspace_t data_ds, l4_threadid_t work_id, l4_uint32_t flags, dsi_socket_t *socket, dsi_component_t comp)
	Open-function for use with local sockets.
int	dsi_socket_local_close (dsi_component_t *comp)
	Close-function for use with local socket refs This callback can be used for the close-callback in a DSI component descriptor (dsi_component_t) if the socket is a socket in the local address space, and no other actions must be performed on connecting a socket than to call dsi_socket_close().
int	dsi_socket_local_connect (dsi_component_t comp, dsi_socket_ref_t remote)
	Connect-function for use with local socket refs This callback can be used for the connect-callback in a DSI component descriptor (dsi_component_t) if the socket is a socket in the local address space, and no other actions must be performed on connecting a socket than to call dsi_socket_connect().
int	dsi_socket_local_stop (dsi_component_t *comp)
	Stop-function for use with local socket refs This callback can be used for the stop-callback in a DSI component descriptor (dsi_component_t) if the socket is a socket in the local address space, and no other actions must be performed on connecting a socket than to call dsi_socket_stop().
Variables
	__BEGIN_DECLS
	__END_DECLS