DSI packet interface

Functions operating on packets. More...


Functions
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_get_nr (dsi_socket_t socket, unsigned nr, dsi_packet_t *packet)
	Wait for specific packet.
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.

Detailed Description

Functions operating on packets.

Function Documentation

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.

Parameters:

	socket	Socket descriptor
	packet	Packet descriptor
	addr	data start address
	size	data size
	flags	data area flags, can be a combination of DSI_DATA_AREA_GAP to add a gap, address ignored DSI_DATA_AREA_EOS to signal the end of stream, address and size are ignored DSI_DATA_AREA_PHYS to add a packet whose physical address is given in addr

Returns:

0 on success, error code otherwise:

-L4_EINVAL invalid socket/packet/data area
-DSI_ESGLIST scatter gather list too long
-DSI_ENOSGELEM no scatter gather element available

Definition at line 928 of file packet.c.

References __get_sg_elem(), __is_valid_packet(), dsi_sg_elem::addr, dsi_socket::data_area, dsi_socket::data_size, dsi_is_valid_socket(), dsi_sg_elem::flags, dsi_socket::header, dsi_ctrl_header::max_sg_len, dsi_sg_elem::next, dsi_packet::sg_idx, dsi_packet::sg_len, dsi_packet::sg_list, dsi_socket::sg_lists, and dsi_sg_elem::size.

int dsi_packet_commit	(	dsi_socket_t *	socket,
		dsi_packet_t *	packet
	)

Commit send / release receive packet.

Parameters:

	socket	socket descriptor
	packet	packet to commit

Return values:

	0	success
	-L4_EINVAL	invalid socket/packet descriptor
	-DSI_ENODATA	tried to commit empty send packet
	-DSI_ENOPACKET	peer in blocking mode: committing required a sync-message which failed

Definition at line 874 of file packet.c.

References __commit_receive_packet(), __commit_send_packet(), and dsi_is_valid_socket().

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

Request next send/receive packet.

Parameters:

socket

Socket descriptor

Return values:

	packet	Pointer to next packet
	0	on success (packet contains valid index)
	-DSI_ENOPACKET	non-blocking mode: next packet still used by the receive component
	-DSI_ENOPACKET	blocking mode: block/unblock-ipc returned an error
	-DSI_EEOS	aborted by dsi_packet_get_abort()
	-DSI_ECONNECT	blocking mode: communication peer does not exist

Definition at line 723 of file packet.c.

References __get_receive_packet(), __get_send_packet(), dsi_is_valid_socket(), dsi_socket::packets, and dsi_packet::sg_idx.

int dsi_packet_get_abort ( dsi_socket_t * socket )

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

Parameters:

socket

Socket descriptor

Return values:

	0	on success (packet_get was ongoing), error otherwise
	-DSI_ENOPACKET	the work-thread was not blocking inside a packet_get. The next dsi_packet_get() will return -DSI_EEOS
	-DSI_EINVAL	invalid socket descriptor

This function can be used to abort a dsi_packet_get(), which was issued by the work-thread of the socket. After the abort, the socket is in an undefined state regarding the packet list. This means, further calls to dsi_packet_get() deliver undefined results. The same hold for the communication peer.

The intended use of this function is to unblock the worker if the socket should be shut down by an service thread.

Note:: This function must not be called if the dsi_packet_get() was not issued by the work-thread of the socket.
This function must not called more than once per socket.

Definition at line 798 of file packet.c.

References dsi_is_valid_socket(), dsi_socket::flags, dsi_socket::packet_get_abort_env, and dsi_socket::work_th.

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.

Parameters:

	socket	Socket descriptor
	packet	Packet descriptor

Return values:

	addr	Start address (absolute) of data area
	size	Size of data area

Returns:

0 on success (addr and size describe a valid data area), error code otherwise:

-DSI_EPHYS chunk describes a piece of physical memory. addr contains the physical address of the data.

-DSI_EGAP chunk describes gap in stream, size is the size of the gap
- -DSI_EEOS packet signals the end of the stream
-DSI_ENODATA packet contains no more data
-L4_EINVAL invalid socket or packet descriptor

Get next data area from packet. If the packet contains more than one area, get_data returns the next area in the scatter gather list and dsi_packet_get_data must be called repeatedly to get the rest of the scatter gather list.

Definition at line 1037 of file packet.c.

References __is_valid_packet(), dsi_sg_elem::addr, dsi_socket::data_area, dsi_is_valid_socket(), dsi_sg_elem::flags, dsi_sg_elem::next, dsi_packet::sg_idx, dsi_socket::sg_lists, and dsi_sg_elem::size.

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

Get packet number.

Parameters:

	socket	Socket descriptor
	packet	Packet descriptor

Return values:

no

Packet number

Returns:

0 on success (no contains packet number), error code otherwise:

-L4_EINVAL invalid socket or packet descriptor

Definition at line 1141 of file packet.c.

References __is_valid_packet(), dsi_is_valid_socket(), and dsi_packet::no.

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

Wait for specific packet.

Parameters:

	socket	Socket descriptor
	packet	Packet descriptor

Return values:

	0	success (packet contains valid packet)
	-DSI_ENOPACKET	- non-blocking mode: next packet still used by the receive component blocking mode: block/unblock-ipc returned an error
	-DSI_ENODATA	tried to commit empty send packet

Implemented dsi_packet_get_nr().

This function requests a packet with a given sequence number. It should be used together with unblocking synchronisation.

Note:: The range of sequence numbers is limited, resulting in a wraparound sometimes. When calculating the packet number directly using the remainder of a division, we end up in having steps in our sequence. Thus we have a window of valid framenumbers represented by a number limited in size, out of an inifinite range of framenumbers. This also requires an additional offset that is added prior to packet-place calculation out of the packet nr. But, we will deal with this later. For now, it is sufficient to have 32bit-IDs, this lasts for about 50days with 1kHz framerate.

Definition at line 852 of file packet.c.

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

Set packet number.

Parameters:

	socket	Socket descriptor
	packet	Packet descriptor
	np	Packet number

Returns:

0 on success, error code otherwise:

-L4_EINVAL invalid socket or packet descriptor

Note:: The packet number can be any desired number that makes the packet kind of unique.

Definition at line 1103 of file packet.c.

References __is_valid_packet(), dsi_is_valid_socket(), and dsi_packet::no.