IOVirtual device

Detailed Description

Overview.

The IOVirtual is an IODevice used mainly for unit testing.

It allows to emulate the behavior of connected IODevices. Each IOVirtual device has a number of gates, that allow it to be connected to other IOVirtual devices. When two or more IOVirtual devices are connected, writing to one of them will cause the data to be received by all the others.

Creating and destroying IOVirtual devices.

All IOVirtual device objects are created at runtime, by a call to IOVIRTUAL_Create function. This call allocates memory for a new IOVIRTUAL device descriptor (plus additional memory for data buffer). Such IOVirtual device is then ready to operate as a regular IODevice object. When done using, all IOVirtual devices should be destroyed to free allocated memory, by a call to IOVIRTUAL_Destroy function.

Using IOVirtual devices.

Once created, the IOVirtual devices are usually being connected to each other. This is done by a call to IOVIRTUAL_Connect. A complementary IOVIRTUAL_Disconnect function is also provided, allowing to disconnect the devices.

A typical usage scenario is presented below:

// declare IOVirtual devices just as any other IODevices
IODevice vio1, vio2;
char buf[5];

// crete IOVirtual devices with 64 bytes long buffers and one gate
vio1 = IOVIRTUAL_Create(64, 1);
vio2 = IOVIRTUAL_Create(64, 1);

// connect IOVirtual devices together to allow data to be passed between them
IOVIRTUAL_Connect(vio1,vio2);

// Initialize IOVirtual devices just like any other IODevices
IODEV_Init(vio1);
IODEV_EnableWrite(vio1);
IODEV_Init(vio2);
IODEV_EnableRead(vio2);

// Use IOVirtual devices just like any other IODevices
IODEV_Write(vio1, "hello", 5, 0);
IODEV_Read(vio2, buf, 5, 0);

// buf should now contain the "hello" string

// Deinitialze IOVirtual devices just like any other IODevice
IODEV_Deinit(vio1);
IODEV_Deinit(vio2);

// When done using IOVirtual devices - destroy them
IOVIRTUAL_Destroy(vio1);
IOVIRTUAL_Destroy(vio2);

Functions
IODevice	IOVIRTUAL_Create (size_t buf_size, int number_of_gates)
void	IOVIRTUAL_Destroy (IODevice iodevice)
HALRESULT	IOVIRTUAL_Connect (IODevice iodev1, IODevice iodev2)
HALRESULT	IOVIRTUAL_Disconnect (IODevice iodev1, IODevice iodev2)

Function Documentation

IODevice IOVIRTUAL_Create	(	size_t	buf_size,
		int	number_of_gates
	)

Creates a new virtual IODevice.

Parameters

buf_size	size of the data buffer (in bytes)
number_of_gates	number of gates to connect other IOVirtual devices

Returns

new virtual IODevice or NULL if creation failed

void IOVIRTUAL_Destroy

(

IODevice

iodevice

)

Destroys a virtual IODevice and frees all memory allocated for it. Note, that this function should NOT be used to free other types of IODevices.

Parameters

iodevice

virtual IODevice

HALRESULT IOVIRTUAL_Connect	(	IODevice	iodev1,
		IODevice	iodev2
	)

Connects IOVirtual devices together.

Parameters

iodev1	first IOVirtual device
iodev2	second IOVirtual device

Return values

HALRESULT_OK	if the devices were connected
HALRESULT_NOT_ENOUGH_GATES	if one (or both) of the devices has no more free gates for connecting

HALRESULT IOVIRTUAL_Disconnect	(	IODevice	iodev1,
		IODevice	iodev2
	)

Disconnects IOVirtual devices.