VE Offloading API functions. More...

Functions
int	veo_api_version ()
	return the API version of the VE Offload implementation More...

veo_proc_handle *	veo_proc__create (const char ossock, const char vedev, const char *binname)
	lower level function to create a VE process More...

veo_proc_handle *	veo_proc_create_static (int venode, const char *veobin)
	create a VE process with non-default veorun binary More...

veo_proc_handle *	veo_proc_create (int venode)
	create a VE process More...

int	veo_proc_destroy (veo_proc_handle *proc)
	destroy a VE process More...

uint64_t	veo_load_library (veo_proc_handle proc, const char libname)
	load a VE library More...

uint64_t	veo_get_sym (veo_proc_handle proc, uint64_t libhdl, const char symname)
	find a symbol in VE program More...

veo_thr_ctxt *	veo_context_open (veo_proc_handle *proc)
	open a VEO context More...

veo_thr_ctxt *	veo_context_open_with_attr (veo_proc_handle proc, veo_thr_ctxt_attr tca)
	open a VEO context with attributes. More...

int	veo_context_close (veo_thr_ctxt *ctx)
	close a VEO context More...

int	veo_get_context_state (veo_thr_ctxt *ctx)
	get VEO context state More...

uint64_t	veo_call_async (veo_thr_ctxt ctx, uint64_t addr, veo_args args)
	request a VE thread to call a function More...

uint64_t	veo_call_async_by_name (veo_thr_ctxt ctx, uint64_t libhdl, const char symname, veo_args *args)
	request a VE thread to call a function More...

uint64_t	veo_call_async_vh (veo_thr_ctxt ctx, uint64_t(func)(void ), void arg)
	call a VH function asynchronously More...

int	veo_call_peek_result (veo_thr_ctxt ctx, uint64_t reqid, uint64_t retp)
	pick up a resutl from VE function if it has finished More...

int	veo_call_wait_result (veo_thr_ctxt ctx, uint64_t reqid, uint64_t retp)
	pick up a resutl from VE function More...

int	veo_alloc_mem (veo_proc_handle h, uint64_t addr, const size_t size)
	Allocate a VE memory buffer. More...

int	veo_free_mem (veo_proc_handle *h, uint64_t addr)
	Free a VE memory buffer. More...

int	veo_read_mem (veo_proc_handle h, void dst, uint64_t src, size_t size)
	Read VE memory. More...

int	veo_write_mem (veo_proc_handle h, uint64_t dst, const void src, size_t size)
	Write VE memory. More...

uint64_t	veo_async_read_mem (veo_thr_ctxt ctx, void dst, uint64_t src, size_t size)
	Asynchronously read VE memory. More...

uint64_t	veo_async_write_mem (veo_thr_ctxt ctx, uint64_t dst, const void src, size_t size)
	Asynchronously write VE memory. More...

veo_args *	veo_args_alloc (void)
	allocate VEO arguments object (veo_args) More...

int	veo_args_set_i64 (veo_args *ca, int argnum, int64_t val)
	set a 64-bit integer argument More...

int	veo_args_set_u64 (veo_args *ca, int argnum, uint64_t val)
	set a 64-bit uunsigned integer argument More...

int	veo_args_set_i32 (veo_args *ca, int argnum, int32_t val)
	set a 32-bit integer argument More...

int	veo_args_set_u32 (veo_args *ca, int argnum, uint32_t val)
	set a 32-bit unsigned integer argument More...

int	veo_args_set_i16 (veo_args *ca, int argnum, int16_t val)
	set a 16-bit integer argument More...

int	veo_args_set_u16 (veo_args *ca, int argnum, uint16_t val)
	set a 16-bit unsigned integer argument More...

int	veo_args_set_i8 (veo_args *ca, int argnum, int8_t val)
	set a 8-bit integer argument More...

int	veo_args_set_u8 (veo_args *ca, int argnum, uint8_t val)
	set a 8-bit unsigned integer argument More...

int	veo_args_set_double (veo_args *ca, int argnum, double val)
	set a double precision floating point number argument More...

int	veo_args_set_float (veo_args *ca, int argnum, float val)
	set a single precision floating point number argument More...

int	veo_args_set_stack (veo_args ca, enum veo_args_intent inout, int argnum, char buff, size_t len)
	set VEO function calling argument pointing to buffer on stack More...

void	veo_args_clear (veo_args *ca)
	clear arguments set in VEO arguments object More...

void	veo_args_free (veo_args *ca)
	free VEO arguments object More...

const char *	veo_version_string ()
	VEO version. More...

veo_thr_ctxt_attr *	veo_alloc_thr_ctxt_attr (void)
	allocate and initialize VEO thread context attributes object (veo_thr_ctxt_attr). More...

int	veo_free_thr_ctxt_attr (veo_thr_ctxt_attr *tca)
	free VEO thread context attributes object. More...

int	veo_set_thr_ctxt_stacksize (veo_thr_ctxt_attr *tca, size_t stack_sz)
	set stack size of VE thread which executes a VE function. More...

int	veo_get_thr_ctxt_stacksize (veo_thr_ctxt_attr tca, size_t stack_sz)
	get stack size of VE thread which executes a VE function. More...

Detailed Description

VE Offloading API functions.

To use VEO API functions, include "ve_offload.h" header.

Function Documentation

int veo_api_version ( )

return the API version of the VE Offload implementation

Return values

integer value with API version

veo_proc_handle* veo_proc__create	(	const char *	ossock,
		const char *	vedev,
		const char *	binname
	)

lower level function to create a VE process

Parameters

ossock	path to VE OS socket
vedev	path to VE device file
binname	VE alternative veorun binary path

Returns: pointer to VEO process handle upon success

Return values

NULL	VE process creation failed.

veo_proc_handle* veo_proc_create_static	(	int	venode,
		const char *	veobin
	)

create a VE process with non-default veorun binary

A VE process is created on the VE node specified by venode. If venode is -1, a VE process is created on the VE node specified by environment variable VE_NODE_NUMBER. If venode is -1 and environment variable VE_NODE_NUMBER is not set, a VE process is created on the VE node #0

A user executes the program which invokes this function through the job scheduler, the value specified by venode will be treated as a logical VE node number. It will be translated into physical VE node number assigned by the job scheduler. If venode is -1, the first VE node of the VE nodes assigned by the job scheduler is used.

Parameters

venode	VE node number
veobin	VE alternative veorun binary path

Returns: pointer to VEO process handle upon success

Return values

NULL	VE process creation failed.

veo_proc_handle* veo_proc_create ( int venode )

create a VE process

A VE process is created on the VE node specified by venode. If venode is -1, a VE process is created on the VE node specified by environment variable VE_NODE_NUMBER. If venode is -1 and environment variable VE_NODE_NUMBER is not set, a VE process is created on the VE node #0

A user executes the program which invokes this function through the job scheduler, the value specified by venode will be treated as a logical VE node number. It will be translated into physical VE node number assigned by the job scheduler. If venode is -1, the first VE node of the VE nodes assigned by the job scheduler is used.

Parameters

venode VE node number

Returns: pointer to VEO process handle upon success

Return values

NULL	VE process creation failed.

int veo_proc_destroy ( veo_proc_handle * proc )

destroy a VE process

Parameters

proc	pointer to VEO process handle

Return values

0	VEO process handle is successfully destroyed.
-1	VEO process handle destruction failed.

uint64_t veo_load_library	(	veo_proc_handle *	proc,
		const char *	libname
	)

load a VE library

Parameters

proc	VEO process handle
libname	a library file name to load

Returns: a handle for the library

Return values

0	library loading request failed.

uint64_t veo_get_sym	(	veo_proc_handle *	proc,
		uint64_t	libhdl,
		const char *	symname
	)

find a symbol in VE program

Parameters

proc	VEO process handle
libhdl	a library handle
symname	symbol name to find

Returns: VEMVA of the symbol upon success.

Return values

0	failed to find symbol.

veo_thr_ctxt* veo_context_open ( veo_proc_handle * proc )

open a VEO context

Create a new VEO context, a pseudo thread and VE thread for the context. All attributes which veo_context_open_with_attr() can specify have default value.

Parameters

proc	VEO process handle

Returns: a pointer to VEO thread context upon success.

Return values

NULL	failed to create a VEO context.

veo_thr_ctxt* veo_context_open_with_attr	(	veo_proc_handle *	proc,
		veo_thr_ctxt_attr *	tca
	)

open a VEO context with attributes.

Create a new VEO context, a pseudo thread and VE thread for the context.

Parameters

proc	VEO process handle
tca	veo_thr_ctxt_attr object

Returns: a pointer to VEO thread context upon success.

Return values

NULL	failed to create a VEO context.

int veo_context_close ( veo_thr_ctxt * ctx )

close a VEO context

Parameters

ctx	a VEO context to close

Return values

0	VEO context is successfully closed.
non-zero	failed to close VEO context.

int veo_get_context_state ( veo_thr_ctxt * ctx )

get VEO context state

Parameters

ctx	a VEO context

Returns: the state of the VEO context state.

Return values

VEO_STATE_RUNNING	VEO context is running.
VEO_STATE_SYSCALL	VEO context is handling a system call from VE.
VEO_STATE_BLOCKED	VEO context is blocked.
VEO_STATE_EXIT	VEO context exited.

uint64_t veo_call_async	(	veo_thr_ctxt *	ctx,
		uint64_t	addr,
		veo_args *	args
	)

request a VE thread to call a function

Parameters

ctx	VEO context to execute the function on VE.
addr	VEMVA of the function to call
args	arguments to be passed to the function

Returns: request ID

Return values

VEO_REQUEST_ID_INVALID request failed.

uint64_t veo_call_async_by_name	(	veo_thr_ctxt *	ctx,
		uint64_t	libhdl,
		const char *	symname,
		veo_args *	args
	)

request a VE thread to call a function

Parameters

ctx	VEO context to execute the function on VE.
libhdl	a library handle
symname	symbol name to find
args	arguments to be passed to the function

Returns: request ID

Return values

VEO_REQUEST_ID_INVALID request failed.

uint64_t veo_call_async_vh	(	veo_thr_ctxt *	ctx,
		uint64_t()(void )	func,
		void *	arg
	)

call a VH function asynchronously

Parameters

ctx	VEO context in which to execute the function.
func	address of VH function to call
arg	pointer to arguments structure for the function

Returns: request ID

Return values

VEO_REQUEST_ID_INVALID if request failed.

int veo_call_peek_result	(	veo_thr_ctxt *	ctx,
		uint64_t	reqid,
		uint64_t *	retp
	)

pick up a resutl from VE function if it has finished

Parameters

ctx	VEO context
reqid	request ID
retp	pointer to buffer to store the return value from the function.

Return values

VEO_COMMAND_OK	function is successfully returned.
VEO_COMMAND_EXCEPTION	an exception occurred on function.
VEO_COMMAND_ERROR	an error occurred on function.
VEO_COMMAND_UNFINISHED	function is not finished.
-1	internal error.

int veo_call_wait_result	(	veo_thr_ctxt *	ctx,
		uint64_t	reqid,
		uint64_t *	retp
	)

pick up a resutl from VE function

Parameters

ctx	VEO context
reqid	request ID
retp	pointer to buffer to store the return value from the function.

Return values

VEO_COMMAND_OK	function is successfully returned.
VEO_COMMAND_EXCEPTION	an exception occurred on execution.
VEO_COMMAND_ERROR	an error occurred on execution.
VEO_COMMAND_UNFINISHED	function is not finished.
-1	internal error.

int veo_alloc_mem	(	veo_proc_handle *	h,
		uint64_t *	addr,
		const size_t	size
	)

Allocate a VE memory buffer.

Parameters

h	VEO process handle
addr	[out] VEMVA address
size	[in] size in bytes

Return values

0	memory allocation succeeded.
-1	memory allocation failed.
-2	internal error.

int veo_free_mem	(	veo_proc_handle *	h,
		uint64_t	addr
	)

Free a VE memory buffer.

Parameters

h	VEO process handle
addr	[in] VEMVA address

Return values

0	memory is successfully freed.
-1	internal error.

int veo_read_mem	(	veo_proc_handle *	h,
		void *	dst,
		uint64_t	src,
		size_t	size
	)

Read VE memory.

Parameters

h	VEO process handle
dst	destination VHVA
src	source VEMVA
size	size in byte

Returns: zero upon success; negative upon failure.

int veo_write_mem	(	veo_proc_handle *	h,
		uint64_t	dst,
		const void *	src,
		size_t	size
	)

Write VE memory.

Parameters

h	VEO process handle
dst	destination VEMVA
src	source VHVA
size	size in byte

Returns: zero upon success; negative upon failure.

uint64_t veo_async_read_mem	(	veo_thr_ctxt *	ctx,
		void *	dst,
		uint64_t	src,
		size_t	size
	)

Asynchronously read VE memory.

Parameters

ctx	VEO context
dst	destination VHVA
src	source VEMVA
size	size in byte

Returns: request ID

Return values

VEO_REQUEST_ID_INVALID request failed.

uint64_t veo_async_write_mem	(	veo_thr_ctxt *	ctx,
		uint64_t	dst,
		const void *	src,
		size_t	size
	)

Asynchronously write VE memory.

Parameters

ctx	VEO context
dst	destination VEMVA
src	source VHVA
size	size in byte

Returns: request ID

Return values

VEO_REQUEST_ID_INVALID request failed.

veo_args* veo_args_alloc ( void )

allocate VEO arguments object (veo_args)

Returns: pointer to veo_args

Return values

NULL	the allocation of veo_args failed.

int veo_args_set_i64	(	veo_args *	ca,
		int	argnum,
		int64_t	val
	)

set a 64-bit integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_u64	(	veo_args *	ca,
		int	argnum,
		uint64_t	val
	)

set a 64-bit uunsigned integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_i32	(	veo_args *	ca,
		int	argnum,
		int32_t	val
	)

set a 32-bit integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_u32	(	veo_args *	ca,
		int	argnum,
		uint32_t	val
	)

set a 32-bit unsigned integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_i16	(	veo_args *	ca,
		int	argnum,
		int16_t	val
	)

set a 16-bit integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_u16	(	veo_args *	ca,
		int	argnum,
		uint16_t	val
	)

set a 16-bit unsigned integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_i8	(	veo_args *	ca,
		int	argnum,
		int8_t	val
	)

set a 8-bit integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_u8	(	veo_args *	ca,
		int	argnum,
		uint8_t	val
	)

set a 8-bit unsigned integer argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_double	(	veo_args *	ca,
		int	argnum,
		double	val
	)

set a double precision floating point number argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_float	(	veo_args *	ca,
		int	argnum,
		float	val
	)

set a single precision floating point number argument

Parameters

ca	veo_args
argnum	the argnum-th argument
val	value to be set

Returns: zero upon success; negative upon failure.

int veo_args_set_stack	(	veo_args *	ca,
		enum veo_args_intent	inout,
		int	argnum,
		char *	buff,
		size_t	len
	)

set VEO function calling argument pointing to buffer on stack

Parameters

ca	pointer to veo_args object
inout	intent of argument. VEO_INTENT_IN, VEO_INTENT_OUT, VEO_INTENT_INOUT are supported
argnum	argument number that is being set
buff	char pointer to buffer that will be copied to the VE stack
len	length of buffer that is copied to the VE stack

Return values

0	argumen is successfully set.
-1	an error occurred.

The buffer is copied to the stack and will look to the VE callee like a local variable of the caller function. Use this to pass structures to the VE "kernel" function. The size of arguments passed on the stack is limited to 63MB, since the size of the initial stack is 64MB. Allocate and use memory buffers on heap when you have huge argument arrays to pass.

void veo_args_clear ( veo_args * ca )

clear arguments set in VEO arguments object

Parameters

ca	veo_args object

void veo_args_free ( veo_args * ca )

free VEO arguments object

Parameters

ca	veo_args object

const char* veo_version_string ( )

VEO version.

Returns: pointer to VEO version string

veo_thr_ctxt_attr* veo_alloc_thr_ctxt_attr ( void )

allocate and initialize VEO thread context attributes object (veo_thr_ctxt_attr).

Returns: pointer to veo_thr_ctxt_attr

Return values

NULL	the allocation of veo_thr_ctxt_attr failed.

int veo_free_thr_ctxt_attr ( veo_thr_ctxt_attr * tca )

free VEO thread context attributes object.

   freeing a VEO thread context attributes object has no effect on VEO
   thread contexts that were created using that object.

Parameters

tca	veo_thr_ctxt_attr object

Return values

0	VEO thread context attributes are successfully freed.
-1	VEO thread context attributes de-allocation failed.

int veo_set_thr_ctxt_stacksize	(	veo_thr_ctxt_attr *	tca,
		size_t	stack_sz
	)

set stack size of VE thread which executes a VE function.

Parameters

tca	veo_thr_ctxt_attr object
stack_sz	stack size of VE thread

Returns: 0 upon success; -1 upon failure.

int veo_get_thr_ctxt_stacksize	(	veo_thr_ctxt_attr *	tca,
		size_t *	stack_sz
	)

get stack size of VE thread which executes a VE function.

Parameters

tca	veo_thr_ctxt_attr object
stack_sz	pointer to store stack size of VE thread.

Returns: 0 upon success; -1 upon failure.

Functions

Detailed Description

Function Documentation