Communication

Functions
int	glip_logic_reset (struct glip_ctx *ctx)
int	glip_read (struct glip_ctx *ctx, uint32_t channel, size_t size, uint8_t *data, size_t *size_read)
int	glip_read_b (struct glip_ctx *ctx, uint32_t channel, size_t size, uint8_t *data, size_t *size_read, unsigned int timeout)
int	glip_write (struct glip_ctx *ctx, uint32_t channel, size_t size, uint8_t *data, size_t *size_written)
int	glip_write_b (struct glip_ctx *ctx, uint32_t channel, size_t size, uint8_t *data, size_t *size_written, unsigned int timeout)

Detailed Description

The main purpose of GLIP is to communicate with a target device. Two main categories of communication exist: control and data communication.

Control communication is done by the following functions:

• glip_reset()

Data communication, i.e. reading and writing data from and to the device, is done by these functions:

• glip_read() and glip_read_b()
• glip_write() and glip_write_b()

All data communication functions need to be given the channel on which the communication should occur.

The GLIP API is modeled after a FIFO interface. This essentially means two things:

• There are no latency guarantees or acknowledgements: when you call one of the write functions, the data is queued to be transferred to the device. You don't know when or if it will arrive there. When you read from the device, you don't know when the data has been sent (and the device does not know when you read it).
• Just like in a regular FIFO, the data ordering is preserved. Whatever data you write first will reach the target first.

The read and write functions offer two types of API: a non-blocking API (glip_read() and glip_write()) and a blocking API (glip_read_b() and glip_write_b()). The non-blocking API functions return immediately with the data written to or read from an internal buffer inside GLIP. Since not enough data might be available for reading or not enough buffer space available for writing data, only a part of the requested data size could have been read or written. The amount of data actually processed is returned as size_read resp. size_written. The non-blocking API fits well into a polling style application which might e.g. poll the library for new data using an already existing event loop (like in GUI applications).

The blocking API functions on the other hand wait until all requested data has been read or written, i.e. if the internal buffers are full (for writes) or empty (for reads), the functions wait until further writing or reading is possible to transfer the requested amount of data. All blocking functions support a timeout parameter. A value of 0 blocks an unlimited amount of time, any other value makes the function abort after an specified amount of time, even if not all data has been transferred yet.

Function Documentation

int glip_logic_reset

(

struct glip_ctx *

ctx

)

Send reset signal to the user logic

This function enables the ctrl_logic_rst output signal of the GLIP hardware module. It is up to the hardware designer to use this signal for any purpose. Usually, this means only the attached logic is reset, not the the communication with the host PC, even though the signal can be used to create such functionality.

Parameters

ctx	the library context

Returns

0 if the call was successful, or an error code if something went wrong

int glip_read	(	struct glip_ctx *	ctx,
		uint32_t	channel,
		size_t	size,
		uint8_t *	data,
		size_t *	size_read
	)

Read from the target device FIFO on a given channel

Requests to read size bytes of data from channel channel into the variable data. The number of bytes actually read from the target is stored in the size_read output argument.

This function returns 0 if the call was successful; a nonzero return value indicates an error.

Note: You need to allocate sufficient space to read size bytes into data before calling this function.

Parameters

[in]	ctx	the library context
[in]	channel	the channel to read from
[in]	size	the number of bytes to read
[out]	data	the data read from the target (allocated by the user)
[out]	size_read	the number of bytes actually read from the target. Only those bytes may be considered valid inside data!

Returns

0 if the call was successful, or an error code if something went wrong

int glip_read_b	(	struct glip_ctx *	ctx,
		uint32_t	channel,
		size_t	size,
		uint8_t *	data,
		size_t *	size_read,
		unsigned int	timeout
	)

Blocking read from the target device FIFO on a given channel

This function is similar to glip_read(), but instead of returning whatever amount of data is available and returning immediately, it blocks until either the requested amount of data is available or the timeout is hit.

Parameters

[in]	ctx	the library context
[in]	channel	the channel to read from
[in]	size	the number of bytes to read
[out]	data	the data read from the target (allocated by the user)
[out]	size_read	the number of bytes actually read from the target. Only those bytes may be considered valid inside data!
[in]	timeout	the timeout in milliseconds (ms) after which this function gives up reading, i.e. the maximum blocking time

Returns

0 if the call was successful and size bytes have been read

-ETIMEDOUT if the call timed out (some data might still have been read, see size_read)

any other value indicates an error

Note: You need to allocate sufficient space to read size bytes into data before calling this function.

See also

glip_read()

int glip_write	(	struct glip_ctx *	ctx,
		uint32_t	channel,
		size_t	size,
		uint8_t *	data,
		size_t *	size_written
	)

Write data to the target FIFO on a given channel

Request the transfer of size bytes of data to the target FIFO of channel channel. The actual number of written bytes is returned as size_written. Always check if all data was transferred, and repeat the transfer if this is not the case.

This function returns 0 if the call was successful; a nonzero return value indicates an error.

This function behaves like you would expect from a FIFO with no latency guarantees. This function is non-blocking. There are no write acknowledgements; the data is scheduled to be transferred "soon", whereas the definition of "soon" depends on the used backend. The backend is free to do with the data whatever it wants, as long as the following guarantees are obeyed:

• size_written bytes of data will eventually reach the target device
• the data ordering is preserved; the first byte written will be the first byte read from the FIFO

All data transfer is big endian. This means for a 2 byte wide FIFO (check the FIFO width with glip_get_fifo_width()) the first byte written will be the MSB in the FIFO, the second byte written will be the LSB.

Parameters

[in]	ctx	the library context
[in]	channel	the channel to write to
[in]	size	the number of bytes to write (length of data)
[in]	data	the data to write
[out]	size_written	the number of bytes actually written; repeat the transfer for the remaining data if

Returns

0 if the call was successful

any other value indicates an error

See also

glip_write_b()

int glip_write_b	(	struct glip_ctx *	ctx,
		uint32_t	channel,
		size_t	size,
		uint8_t *	data,
		size_t *	size_written,
		unsigned int	timeout
	)

Blocking write to the target FIFO on a given channel

This function is the blocking version of glip_write(). The function returns not before either all data is written (i.e. size bytes) or timeout milliseconds passed.

Parameters

[in]	ctx	the library context
[in]	channel	the channel to write to
[in]	size	the number of bytes to write (length of data)
[in]	data	the data to write
[out]	size_written	the number of bytes actually written; repeat the transfer for the remaining data if
[in]	timeout	the timeout in milliseconds (ms) after which this function gives up writing, i.e. the maximum blocking time

Returns

0 if the call was successful and size bytes have been written

-ETIMEDOUT if the call timed out (some data might still have been written, see size_written)

any other value indicates an error

See also

glip_write()