Buffer.h File Reference

#include <stdint.h>
#include <stdlib.h>
#include "temu-c/Support/Attributes.h"

Include dependency graph for Buffer.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	temu_Buff

Macros
#define	TEMU_BUFF_DEFINED

Functions
TEMU_API temu_Buff	temu_buffCreate (uint32_t size)
TEMU_API temu_Buff	temu_buffCopy (const temu_Buff *B)
TEMU_API void	temu_buffDispose (temu_Buff *B)
TEMU_API uint8_t *	temu_buffWritableData (temu_Buff *B)
const TEMU_API uint8_t *	temu_buffReadableData (const temu_Buff *B)
TEMU_API uint32_t	temu_buffLen (const temu_Buff *B)
TEMU_API void	temu_buffRemoveHead (temu_Buff *B, uint32_t len)
TEMU_API void	temu_buffRemoveTail (temu_Buff *B, uint32_t len)

Macro Definition Documentation

TEMU_BUFF_DEFINED

#define TEMU_BUFF_DEFINED

Copy-On-Write (COW) buffer. The content is private and should not be manipulated directly.

NOTE: The COW buffers are currently an EXPERIMENTAL feature. The API may change. Further, the temu_Buff type itself may change without notice in future versions of TEMU. The type is internal for the buffer API, but is exposed as a struct here to save on memory allocations when creating a temporary buffer object copy on the stack.

The COW buffer objects are suitable for network simulation. Where a receiver may need to queue up multiple received packets.

Currently, there is no way to prepend or append (e.g. injecting extra headers). However, it is possible to delete bytes from the head of the buffer without causing copies of the actual buffered data. This is enough to support efficient SpaceWire simulation.

Typically a device model would use the buffers in this way:

// Transaction start
void
startTransaction(mydevice_t *dev)
{
  temu_Buff buffer = temu_buffCreate(dev->DataLengthRegister);
  uint8_t *bufferData = temu_buffWritableData(&buffer);
  dev->memspace.Iface->readBytes(dev->memspace.Obj,
                                 bufferData,
                                 dev->DataPtrRegister,
                                 dev->DataLengthRegister,
                                 0); // Data in bytes
  sendData(dev->receiver, &buffer);
  temu_buffDispose(&buffer);
}
 
// RECEIVER functionality
void
receive(myreceiver_t *receiver, const temu_Buff *buff)
{
  temu_Buff buffer = temu_buffCopy(buff);
  enqueue(receiver, buffer);
  temu_eventPostNs(receiver->Super.Queue, receiver->HandleDataEventID,
                   1000, teST_Cpu)
}
 
void
event(temu_Event *ev)
{
  myreceiver_t *receiver = ev->Obj;
  temu_Buff buffer = dequeue(receiver);
  const uint8_t *data temu_buffReadabledata(&buffer);
  uint32_t bufflen = temu_buffLen(&buffer);
  // ...
  temu_buffDispose(buffer);
}

Function Documentation

temu_buffCopy()

TEMU_API temu_Buff temu_buffCopy

(

const temu_Buff *

B

)

Copy COW buffer. This will make a new buff object, but the underlying data will not be copied.

Parameters

B	The buffer to copy.

Returns

Buffer object referring to the same data as B.

temu_buffCreate()

TEMU_API temu_Buff temu_buffCreate

(

uint32_t

size

)

Create a new COW buffer of size bytes.

Parameters

size	Size of buffer in bytes

Returns

Buffer object.

temu_buffDispose()

TEMU_API void temu_buffDispose

(

temu_Buff *

B

)

Delete buffer. The buffer B will be deleted. If there are no more copies of the buffer data anywhere, the data will be deallocated.

Parameters

B	buffer to delete.

temu_buffLen()

TEMU_API uint32_t temu_buffLen

(

const temu_Buff *

B

)

Get buffer length

Parameters

B

buffer

Returns

Length of buffer in bytes

temu_buffReadableData()

const TEMU_API uint8_t* temu_buffReadableData

(

const temu_Buff *

B

)

Get a pointer to readable buffer data

The pointer to the readable data will be returned.

Parameters

B	Buffer to get read pointer from

Returns

Pointer to data buffer.

temu_buffRemoveHead()

TEMU_API void temu_buffRemoveHead	(	temu_Buff *	B,
		uint32_t	len
	)

Remove len bytes from the start of the buffer.

Removing bytes from the buffer start will not change the underlying buffer object. And is not seen as a write for the purpose of the data block.

This does not affect other copies of this buffer.

Parameters

B	buffer to remove data from
len	Number of bytes to remove.

temu_buffRemoveTail()

TEMU_API void temu_buffRemoveTail	(	temu_Buff *	B,
		uint32_t	len
	)

Remove len bytes from the end of the buffer.

Removing bytes from the buffer tail will not change the underlying buffer object. And is not seen as a write for the purpose of the data block.

This does not affect other copies of this buffer.

Parameters

B	buffer to remove data from
len	Number of bytes to remove.

temu_buffWritableData()

TEMU_API uint8_t* temu_buffWritableData

(

temu_Buff *

B

)

Get a pointer to writable data.

If the data have more than one reference, a new copy of the data will be created.

Parameters

B	Buffer to get data pointer from.

Returns

Pointer to writable data.