DSI socket interface

Functions operating on sockets. More...

Functions

int dsi_socket_share_ds (dsi_socket_t *socket, l4_threadid_t client)
 Share socket dataspaces.
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_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_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_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_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_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_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().

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().

Detailed Description

Functions operating on sockets.

Function Documentation

int dsi_socket_clear_flags ( dsi_socket_t *  socket,
l4_uint32_t  flags 
)

Clear socket flags.

Parameters:
socket Socket descriptor
flags Flags to clear
Returns:
0 on success (modified socket flags), error code otherwise:
  • -L4_EINVAL invalid socket descriptor

Definition at line 601 of file socket.c.

References dsi_is_valid_socket(), and dsi_socket::flags.

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.

Parameters:
socket socket descriptor
Return values:
0 success, closed socket
-L4_EINVAL invalid socket descriptor

Definition at line 304 of file socket.c.

References dsi_is_valid_socket(), dsi_release_ctrl_area(), dsi_release_data_area(), dsi_shutdown_sync_thread(), and dsi_socket::flags.

Referenced by dsi_socket_local_close(), and dsi_socket_local_create().

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.

Parameters:
socket local socket descriptor
remote_socket remote socket reference
Return values:
0 success, socket connected to remote socket
-L4_EINVAL invalid socket reference
See also:
dsi_socket_connect_ref().

Definition at line 372 of file socket.c.

References dsi_is_valid_socket(), dsi_start_sync_thread(), dsi_socket::remote_socket, dsi_socket_ref::socket, dsi_socket::socket_id, dsi_socket_ref::sync_th, and dsi_socket_ref::work_th.

Referenced by dsi_socket_local_connect().

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.

Parameters:
jcp_stream stream description
cfg low level stream configuration
ctrl_ds control area (if invalid, allocate new area)
data_ds data area
work_id work thread id
sync_id synchronization thread id (if invalid, create thread)
flags socket flags:
  • DSI_SOCKET_SEND create send socket
  • DSI_SOCKET_RECEIVE create receive socket
  • DSI_SOCKET_BLOCK block if no packet is available in dsi_packet_get, the default behavior is to return an error
  • for more see include/l4/dsi/types.h
Return values:
ctrl_ds contains control area
sync_id synchronization thread id of newly created thread
socket socket descriptor
0 success, created socket
-L4_EINVAL invalid data area or work thread
-L4_ENOSOCKET no socket descriptor available

Definition at line 157 of file socket.c.

References __allocate_socket(), dsi_socket::clients, dsi_socket::ctrl_ds, dsi_create_ctrl_area(), dsi_create_sync_thread(), DSI_MAX_EVENTS, dsi_release_ctrl_area(), dsi_set_ctrl_area(), dsi_set_data_area(), dsi_shutdown_sync_thread(), dsi_socket::events, dsi_socket::flags, dsi_socket::next_packet, dsi_socket::next_sg_elem, dsi_socket::packet_count, dsi_socket::release_callback, SOCKET_FLAGS_USER, dsi_socket::socket_id, dsi_socket::sync_callback, dsi_socket::sync_th, dsi_socket::waiting, and dsi_socket::work_th.

Referenced by dsi_socket_local_create().

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.

Parameters:
socket socket descriptor
Return values:
data_area start address of data area
area_size size of data area
0 success
-L4_EINVAL invalid socket descriptor

Definition at line 548 of file socket.c.

References dsi_socket::data_area, dsi_socket::data_size, and dsi_is_valid_socket().

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.

Parameters:
id socket id
Return values:
socket contains the socket
0 success
-L4_EINVAL invalid socket id

Definition at line 520 of file socket.c.

Referenced by __reset_event(), __set_event(), __wait_for_events(), dsi_socket_local_close(), dsi_socket_local_connect(), and dsi_socket_local_stop().

int dsi_socket_get_num_committed_packets ( dsi_socket_t *  socket  ) 

Return number of committed send packets in ring list.

Parameters:
socket Socket descriptor
Returns:
Number of committed send packets in ring list (> 0), error code otherwise:
  • -L4_EINVAL invalid socket descriptor

Definition at line 703 of file socket.c.

References dsi_is_valid_socket(), dsi_socket::header, and dsi_ctrl_header::packets_committed.

int dsi_socket_get_packet_num ( dsi_socket_t *  socket  ) 

Return number of packets in ring list.

Parameters:
socket Socket descriptor
Returns:
Number of packest in socket ring list (> 0), error code otherwise:
  • -L4_EINVAL invalid socket descriptor

Definition at line 681 of file socket.c.

References dsi_is_valid_socket(), and dsi_socket::num_packets.

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()).

Parameters:
socket socket descriptor
Return values:
ref contains socket reference
0 success
-L4_EINVAL invalid socket descriptor

Definition at line 491 of file socket.c.

References dsi_get_event_thread_id(), dsi_is_valid_socket(), dsi_socket_ref::event_th, dsi_socket_ref::socket, dsi_socket::socket_id, dsi_socket::sync_th, dsi_socket_ref::sync_th, dsi_socket::work_th, and dsi_socket_ref::work_th.

Referenced by dsi_socket_local_create().

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().

See also:
dsi_socket_connect().

Definition at line 194 of file convenience.c.

References dsi_socket_close(), dsi_socket_get_descriptor(), dsi_socket_ref::socket, and dsi_component::socketref.

Referenced by dsi_socket_local_create().

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().

See also:
dsi_socket_connect().

Definition at line 236 of file convenience.c.

References dsi_socket_connect(), dsi_socket_get_descriptor(), dsi_socket_ref::socket, and dsi_component::socketref.

Referenced by dsi_socket_local_create().

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.

Parameters:
cfg low level stream configuration
ctrl_ds control area (if invalid, allocate new area)
data_ds data area
work_id work thread id
flags socket flags, see dsi_socket_create()
socket ptr to a dsi_socket_t pointer, that will be set to the newly created socket. Ignored if 0.
comp ptr to a dsi_component_t structure, that will be filled in
This function can be used to create a component with a local socket in it. Use this function if your application is endpoint of a communication as well.

The start and stop entries in comp will be set to 0. If you want a notification of this events, set your own callbacks after calling.

See also:
dsi_socket_create().

Definition at line 154 of file convenience.c.

References dsi_component::close, dsi_component::connect, dsi_socket_close(), dsi_socket_create(), dsi_socket_get_ref(), dsi_socket_local_close(), dsi_socket_local_connect(), dsi_socket_local_stop(), dsi_component::socketref, dsi_component::start, and dsi_component::stop.

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().

See also:
dsi_socket_connect().

Definition at line 215 of file convenience.c.

References dsi_socket_get_descriptor(), dsi_socket_stop(), dsi_socket_ref::socket, and dsi_component::socketref.

Referenced by dsi_socket_local_create().

int dsi_socket_set_event ( dsi_socket_t *  socket,
l4_uint32_t  events 
)

Set event.

Parameters:
socket Socket descriptor
events Event mask
Returns:
0 on success (called event signalling thread), error code otherwise:
  • -L4_EINVAL invalid socket descriptor
  • -L4_EIPC IPC error calling signalling thread
This function queues a given event for the socket. The event can be waited for at the client application using the dsi_event_wait() function.

This function just calls dsi_event_set().

Definition at line 657 of file socket.c.

References dsi_event_set(), dsi_is_valid_socket(), and dsi_socket::socket_id.

int dsi_socket_set_flags ( dsi_socket_t *  socket,
l4_uint32_t  flags 
)

Set socket flags.

Parameters:
socket Socket descriptor
flags Flags to set
Returns:
0 on success (modified socket flags), error code otherwise:
  • -L4_EINVAL invalid socket descriptor

Definition at line 575 of file socket.c.

References dsi_is_valid_socket(), and dsi_socket::flags.

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).

Parameters:
socket socket descriptor
func packet release callback function
Return values:
0 success, registered new callback function
-L4_EINVAL invalid socket descriptor / callback function

Definition at line 462 of file socket.c.

References dsi_is_valid_socket(), dsi_socket::flags, and dsi_socket::release_callback.

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.

Parameters:
socket socket descriptor
func synchronization callback function
Return values:
0 success, registered new callback function
-L4_EINVAL invalid socket descriptor / callback function

Definition at line 432 of file socket.c.

References dsi_is_valid_socket(), dsi_socket::flags, and dsi_socket::sync_callback.

int dsi_socket_share_ds ( dsi_socket_t *  socket,
l4_threadid_t  client 
)

Share socket dataspaces.

Parameters:
socket Socket descriptor
client Client thread id
Returns:
0 on success (allowed read-write access for client), error code otherwise:
  • -L4_EINVAL invalid socket descriptor
  • -L4_EPERM operation not allowed
  • -L4_EIPC error calling dataspace manager

Definition at line 665 of file dataspace.c.

References dsi_socket::ctrl_ds, dsi_socket::data_ds, and dsi_is_valid_socket().

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.

Parameters:
socket socket descriptor
Return values:
0 success, closed socket
-L4_EINVAL invalid socket descriptor

Definition at line 342 of file socket.c.

References dsi_is_valid_socket(), dsi_shutdown_sync_thread(), and dsi_socket::flags.

Referenced by dsi_socket_local_stop().

int dsi_socket_test_flag ( dsi_socket_t *  socket,
l4_uint32_t  flag 
)

Test socket flag.

Parameters:
socket Socket descriptor
flag Flag
Returns:
!= 0 if flag is set, 0 if flag is not set or invalid socket descriptor

Definition at line 627 of file socket.c.

References dsi_is_valid_socket(), and dsi_socket::flags.

Generated on Wed Apr 11 06:40:14 2012 for DSI - Drops Streaming Interface by  doxygen 1.5.6