DMA-Helper Functions
[Point-to-Point Communication]

Collaboration diagram for DMA-Helper Functions:

Detailed Description

Functions wrapping DMA-Transfers.

The Cell Broadband Engine uses Direct Memory Access (DMA) for communication. Therefore data of a MOC-message is transfered using DMA operations. Because programming DMA is rather complex, some functions are provided to hide this complexity. One DMA-call can only tranfer a maximum of 16KByte of data and the data-size has to be a multiple of 16 byte. The provided functions split the data into multiple DMA-calls if needed. If the data-size requires it, an intermediate buffer is used into which a separate DMA-Call transfers 16 byte containing the piece of data not fitting into the 16-byte scheme. Then only the needed bytes are copied into the receive-buffer. But the latter only works for a get-operation.

The internal DMA-functions are also made publicly available via wrapping-function (see chapter Direct Memory Access) which provide parameter checks.

PPU-only

int IMOC_get_data (void *target, uint64_t source, uint32_t size, int dest)

Internal wrapper-function for a blocking DMA-get operation.

int IMOC_put_data (void *source, uint64_t target, uint32_t size, int dest)

Internal wrapper-function for a blocking DMA-put operation.

int IMOC_iget_data (void *target, uint64_t source, uint32_t size, uint32_t dest, imoc_dma_request *request)

Internal wrapper-function for a non-blocking DMA-get operation.

int IMOC_iput_data (void *source, uint64_t target, uint32_t size, uint32_t dest, imoc_dma_request *request)

Internal wrapper-function for a non-blocking DMA-put operation.

int IMOC_wait_dma (imoc_dma_request *request)

Waits till a IMOC_iget_data or IMOC_iput_data is completed.

int IMOC_test_dma (imoc_dma_request *request, int *flag)

Tests if a IMOC_iget_data or IMOC_iput_data is completed.

int moc_tag_reserve (unsigned int speid)

Reserves a tag on the ppu, for communication with a given spu.

int moc_tag_release (unsigned int speid, int tag)

Releases a reserved tag.

SPU-only

int IMOC_get_data (void *target, uint64_t source, uint32_t size)

Internal wrapper-function for a blocking DMA-get operation.

int IMOC_put_data (void *source, uint64_t target, uint32_t size)

Internal wrapper-function for a blocking DMA-put operation.

int IMOC_iget_data (void *target, uint64_t source, uint32_t size, imoc_dma_request *request)

Internal wrapper-function for a non-blocking DMA-get operation.

int IMOC_iput_data (void *source, uint64_t target, uint32_t size, imoc_dma_request *request)

Internal wrapper-function for a blocking DMA-put operation.

Function Documentation

int IMOC_get_data	(	void *	target,
		uint64_t	source,
		uint32_t	size
	)

Internal wrapper-function for a blocking DMA-get operation.

Data can be of any size, constraints of low-level DMA-functions are dealt by this function. However data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, but copies only size bytes of it to target. This means however that up to 15 bytes are read from an invalid location. As it is never written to them this should always be safe.

Parameters:

	target	in ls-address of buffer
	source	in ea-address of data
	size	in size of data in byte

Returns:: 0 when success otherwise error-code

Definition at line 8 of file imoc_dma-get_spu.c.

References MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, and MOC_SUCCESS.

int IMOC_get_data	(	void *	target,
		uint64_t	source,
		uint32_t	size,
		int	dest
	)

Internal wrapper-function for a blocking DMA-get operation.

Data can be of any size, constraints of low-level DMA-functions are dealt by this function. However data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, but copies only size bytes of it to target. This means however that up to 15 bytes are read from an invalid location. As it is never written to them this should always be safe.

On the ppu the system for tag reservation is not present, so a hardcoded tag is used. It has also to be noted that the dma calls are actually initiated on the spu by the ppu.

Parameters:

	target	in local-address of buffer
	source	in ea-address of data
	size	in size of data in byte
	dest	in id of source spe

Returns:: 0 when success otherwise error-code

Definition at line 9 of file imoc_dma-get_ppu.c.

References __attribute__(), MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, moc_ppu_thread_count, moc_spu_thread_list, and MOC_SUCCESS.

Referenced by MOC_Get_data(), and MOC_Recv().

Here is the call graph for this function:

Here is the caller graph for this function:

int IMOC_iget_data	(	void *	target,
		uint64_t	source,
		uint32_t	size,
		imoc_dma_request *	request
	)

Internal wrapper-function for a non-blocking DMA-get operation.

Data can be of any size, constraints of low-level DMA-functions are dealt by this function. However data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, but copies only size bytes of it to target. This means however that up to 15 bytes are read from an invalid location. As it is never written to them this should always be safe.

Parameters:

	target	in ls-address of buffer
	source	in ea-address of data
	size	in size of data in byte
	request	out request-handle

Returns:: 0 when success otherwise error-code

Definition at line 10 of file imoc_dma-iget_spu.c.

References imoc_dma_request_struct::buffer, MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, MOC_SUCCESS, imoc_dma_request_struct::remainder, imoc_dma_request_struct::size, imoc_dma_request_struct::tag_id, and imoc_dma_request_struct::target.

int IMOC_iget_data	(	void *	target,
		uint64_t	source,
		uint32_t	size,
		uint32_t	dest,
		imoc_dma_request *	request
	)

Internal wrapper-function for a non-blocking DMA-get operation.

Data can be of any size, constraints of low-level DMA-functions are dealt by this function. However data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, but copies only size bytes of it to target. This means however that up to 15 bytes are read from an invalid location. As it is never written to them this should always be safe.

On the ppu the system for tag reservation is not present, so a hardcoded tag is used. It has also to be noted that the dma calls are actually initiated on the spu by the ppu.

Parameters:

	target	in local-address of buffer
	source	in ea-address of data
	size	in size of data in byte
	dest	in id of source spe
	request	out request-handle

Returns:: 0 when success otherwise error-code

Definition at line 10 of file imoc_dma-iget_ppu.c.

References imoc_dma_request_struct::buffer, imoc_dma_request_struct::dest, MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, moc_ppu_thread_count, moc_spu_thread_list, MOC_SUCCESS, moc_tag_reserve(), imoc_dma_request_struct::remainder, imoc_dma_request_struct::size, imoc_dma_request_struct::tag_id, and imoc_dma_request_struct::target.

Referenced by MOC_IGet_data().

Here is the call graph for this function:

Here is the caller graph for this function:

int IMOC_iput_data	(	void *	source,
		uint64_t	target,
		uint32_t	size,
		imoc_dma_request *	request
	)

Internal wrapper-function for a blocking DMA-put operation.

Data-size should be a multiple of 16 because of low-level constraints, but there is no upper limit of transfer-size. Data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, and copies it to target. This means however that up to 15 bytes are written to and invalid location, so if one wants to use it with invalid sizes precautions have to be taken in order to make it safe.

Parameters:

	source	in ls-address of data
	target	in ea-address of buffer
	size	in size of data in byte
	request	out request-handle

Returns:: 0 when success otherwise error-code

Definition at line 10 of file imoc_dma-iput_spu.c.

References MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, MOC_SUCCESS, imoc_dma_request_struct::remainder, and imoc_dma_request_struct::tag_id.

int IMOC_iput_data	(	void *	source,
		uint64_t	target,
		uint32_t	size,
		uint32_t	dest,
		imoc_dma_request *	request
	)

Internal wrapper-function for a non-blocking DMA-put operation.

Data-size should be a multiple of 16 because of low-level constraints, but there is no upper limit of transfer-size. Data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, and copies it to target. This means however that up to 15 bytes are written to and invalid location, so if one wants to use it with invalid sizes precautions have to be taken in order to make it safe.

On the ppu the system for tag reservation is not present, so a hardcoded tag is used. It has also to be noted that the dma calls are actually initiated on the spu by the ppu.

Parameters:

	source	in local-address of data
	target	in ea-address of buffer
	size	in size of data in byte
	dest	in id of source spe
	request	out request-handle

Returns:: 0 when success otherwise error-code

Definition at line 19 of file imoc_dma-iput_ppu.c.

References imoc_dma_request_struct::dest, MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, moc_ppu_thread_count, moc_spu_thread_list, MOC_SUCCESS, moc_tag_reserve(), imoc_dma_request_struct::remainder, imoc_dma_request_struct::size, imoc_dma_request_struct::tag_id, and imoc_dma_request_struct::target.

Referenced by MOC_IPut_data().

Here is the call graph for this function:

Here is the caller graph for this function:

int IMOC_put_data	(	void *	source,
		uint64_t	target,
		uint32_t	size
	)

Internal wrapper-function for a blocking DMA-put operation.

Data-size should be a multiple of 16 because of low-level constraints, but there is no upper limit of transfer-size. Data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, and copies it to target. This means however that up to 15 bytes are written to and invalid location, so if one wants to use it with invalid sizes precautions have to be taken in order to make it safe.

Parameters:

	source	in ls-address of data
	target	in ea-address of buffer
	size	in size of data in byte

Returns:: 0 when success otherwise error-code

Definition at line 8 of file imoc_dma-put_spu.c.

References MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, and MOC_SUCCESS.

int IMOC_put_data	(	void *	source,
		uint64_t	target,
		uint32_t	size,
		int	dest
	)

Internal wrapper-function for a blocking DMA-put operation.

Data-size should be a multiple of 16 because of low-level constraints, but there is no upper limit of transfer-size. Data-addresses have to be at least 16-byte aligned.

This function actually always reads a multiple of 16 from the source, and copies it to target. This means however that up to 15 bytes are written to and invalid location, so if one wants to use it with invalid sizes precautions have to be taken in order to make it safe.

On the ppu the system for tag reservation is not present, so a hardcoded tag is used. It has also to be noted that the dma calls are actually initiated on the spu by the ppu.

Parameters:

	source	in local-address of data
	target	in ea-address of buffer
	size	in size of data in byte
	dest	in id of source spe

Returns:: 0 when success otherwise error-code

Definition at line 9 of file imoc_dma-put_ppu.c.

References MAX_DMA_CALL_SIZE, MOC_ERR_INTERN, moc_ppu_thread_count, moc_spu_thread_list, and MOC_SUCCESS.

Referenced by MOC_Bsend(), and MOC_Put_data().

Here is the caller graph for this function:

int IMOC_test_dma	(	imoc_dma_request *	request,
		int *	flag
	)

Tests if a IMOC_iget_data or IMOC_iput_data is completed.

Parameters:

	request	in request-handle
	flag	out true if operation is completed

Returns:: 0 when success otherwise error-code

Definition at line 9 of file imoc_dma-test_ppu.c.

References imoc_dma_request_struct::buffer, imoc_dma_request_struct::dest, MOC_ERR_INTERN, moc_ppu_thread_count, moc_spu_thread_list, MOC_SUCCESS, moc_tag_release(), imoc_dma_request_struct::remainder, imoc_dma_request_struct::size, moc_spu_thread_struct::speid, imoc_dma_request_struct::tag_id, and imoc_dma_request_struct::target.

Referenced by MOC_Test(), and MOC_Test_data().

Here is the call graph for this function:

Here is the caller graph for this function:

int IMOC_wait_dma ( imoc_dma_request * request )

Waits till a IMOC_iget_data or IMOC_iput_data is completed.

Parameters:

request

in request-handle

Returns:: 0 when success otherwise error-code

Definition at line 9 of file imoc_dma-wait_ppu.c.

References imoc_dma_request_struct::buffer, imoc_dma_request_struct::dest, MOC_ERR_INTERN, moc_ppu_thread_count, moc_spu_thread_list, MOC_SUCCESS, moc_tag_release(), imoc_dma_request_struct::remainder, imoc_dma_request_struct::size, moc_spu_thread_struct::speid, imoc_dma_request_struct::tag_id, and imoc_dma_request_struct::target.

Referenced by MOC_Wait(), and MOC_Wait_data().

Here is the call graph for this function:

Here is the caller graph for this function:

int moc_tag_release	(	unsigned int	speid,
		int	tag
	)

Releases a reserved tag.

Parameters:

	speid	id of spu for which the tag was reserved
	tag	tag to be released

Returns:: 0 when success otherwise error-code

Definition at line 32 of file imoc_dma-tags_ppu.c.

References MOC_ERR_INTERN, MOC_SUCCESS, and tags.

Referenced by IMOC_test_dma(), and IMOC_wait_dma().

Here is the caller graph for this function:

int moc_tag_reserve ( unsigned int speid )

Reserves a tag on the ppu, for communication with a given spu.

Parameters:

speid

id of spu to communicate with

Returns:: tag (0-14) when success otherwise error code

Definition at line 14 of file imoc_dma-tags_ppu.c.

References MOC_ERR_INTERN, and tags.

Referenced by IMOC_iget_data(), and IMOC_iput_data().

Here is the caller graph for this function:


PPU-only
int	IMOC_get_data (void *target, uint64_t source, uint32_t size, int dest)
	Internal wrapper-function for a blocking DMA-get operation.
int	IMOC_put_data (void *source, uint64_t target, uint32_t size, int dest)
	Internal wrapper-function for a blocking DMA-put operation.
int	IMOC_iget_data (void target, uint64_t source, uint32_t size, uint32_t dest, imoc_dma_request request)
	Internal wrapper-function for a non-blocking DMA-get operation.
int	IMOC_iput_data (void source, uint64_t target, uint32_t size, uint32_t dest, imoc_dma_request request)
	Internal wrapper-function for a non-blocking DMA-put operation.
int	IMOC_wait_dma (imoc_dma_request *request)
	Waits till a IMOC_iget_data or IMOC_iput_data is completed.
int	IMOC_test_dma (imoc_dma_request request, int flag)
	Tests if a IMOC_iget_data or IMOC_iput_data is completed.
int	moc_tag_reserve (unsigned int speid)
	Reserves a tag on the ppu, for communication with a given spu.
int	moc_tag_release (unsigned int speid, int tag)
	Releases a reserved tag.
SPU-only
int	IMOC_get_data (void *target, uint64_t source, uint32_t size)
	Internal wrapper-function for a blocking DMA-get operation.
int	IMOC_put_data (void *source, uint64_t target, uint32_t size)
	Internal wrapper-function for a blocking DMA-put operation.
int	IMOC_iget_data (void target, uint64_t source, uint32_t size, imoc_dma_request request)
	Internal wrapper-function for a non-blocking DMA-get operation.
int	IMOC_iput_data (void source, uint64_t target, uint32_t size, imoc_dma_request request)
	Internal wrapper-function for a blocking DMA-put operation.

DMA-Helper Functions [Point-to-Point Communication]

Detailed Description

PPU-only

SPU-only

Function Documentation

DMA-Helper Functions
[Point-to-Point Communication]