HOST API

shmem_host_heap.h

Functions

SHMEM_HOST_API void * shmem_malloc (size_t size)

allocate size bytes and returns a pointer to the allocated memory. The memory is not initialized. If size is 0, then shmem_malloc() returns NULL.

Parameters:

size – [in] bytes to be allocated

Returns:

pointer to the allocated memory.

SHMEM_HOST_API void * shmem_calloc (size_t nmemb, size_t size)

allocate memory for an array of nmemb elements of size bytes each and returns a pointer to the allocated memory. The memory is set to zero. If nmemb or size is 0, then shmem_calloc() returns either NULL.

Parameters:

  • nmemb – [in] elements count

  • size – [in] each element size in bytes

Returns:

pointer to the allocated memory.

SHMEM_HOST_API void * shmem_align (size_t alignment, size_t size)

allocate size bytes and returns a pointer to the allocated memory. The memory address will be a multiple of alignment, which must be a power of two.

Parameters:

  • alignment – [in] memory address alignment

  • size – [in] bytes allocated

Returns:

pointer to the allocated memory.

SHMEM_HOST_API void shmem_free (void *ptr)

Free the memory space pointed to by ptr, which must have been returned by a previous call to shmem_malloc(), shmem_calloc() or shmem_align(). If ptr is NULL, no operation is performed.

Parameters:

ptr – [in] point to memory block to be free.

shmem_host_init.h

Functions

SHMEM_HOST_API int shmem_init_status ()

Query the current initialization status.

Returns:

Returns initialization status. Returning SHMEM_STATUS_IS_INITIALIZED indicates that initialization is complete. All return types can be found in shmem_init_status_t.

SHMEM_HOST_API int shmem_set_attr (int my_rank, int n_ranks, uint64_t local_mem_size, const char *ip_port, shmem_init_attr_t **attributes)

Set the default attributes to be used in shmem_init_attr().

Parameters:

  • my_rank – [in] Current rank

  • n_ranks – [in] Total number of ranks

  • local_mem_size – [in] The size of shared memory currently occupied by current rank

  • ip_port – [in] The ip and port number of the sever, e.g. tcp://ip:port Security warning: ip_port should be a null-terminated C string, unless it may result in out-of-bounds memory access

  • attributes – [out] Pointer to the default attributes used for initialization

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int shmem_set_data_op_engine_type (shmem_init_attr_t *attributes, data_op_engine_type_t value)

Modify the data operation engine type in the attributes that will be used for initialization. If this method is not used, the default data_op_engine_type value is SHMEM_DATA_OP_MTE if method shmem_set_attr() is used after this method, the data_op_engine_type param will be overwritten by the default value.

Parameters:

  • attributes – [in/out] Pointer to the attributes to modify the data operation engine type

  • value – [in] Value of data operation engine type

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int shmem_set_timeout (shmem_init_attr_t *attributes, uint32_t value)

Modify the timeout in the attributes that will be used for initialization. If this method is not used, the default timeout value is 120 if method shmem_set_attr() is used after this method, the timeout param will be overwritten by the default value.

Parameters:

  • attributes – [in/out] Pointer to the attributes to modify the data operation engine type

  • value – [in] Value of timeout

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int shmem_get_uniqueid (shmem_uniqueid_t *uid)

get the unique id and return it by intput argument uid. This function need run with PTA.

Parameters:

uid – [out] a ptr to uid generate by shmem

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int shmem_set_attr_uniqueid_args (int rank_id, int nranks, const shmem_uniqueid_t *uid, shmem_init_attr_t *attr)

init process with unique id. This function need run with PTA.

Parameters:

  • rank_id – [in] current rank id

  • nranks – [in] total ranks

  • uid – [in] a ptr to uid, generated by shmem_get_uniqueid

  • attr – [out] a ptr to shmem_init_attr_t

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int shmem_init_attr (shmem_init_attr_t *attributes)

Initialize the resources required for SHMEM task based on attributes. Attributes can be created by users or obtained by calling shmem_set_attr(). if the self-created attr structure is incorrect, the initialization will fail. It is recommended to build the attributes by shmem_set_attr().

Parameters:

attributes – [in] Pointer to the user-defined attributes.

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int32_t shmem_set_config_store_tls_key (const char *tls_pk, const uint32_t tls_pk_len, const char *tls_pk_pw, const uint32_t tls_pk_pw_len, const shmem_decrypt_handler decrypt_handler)

Set the TLS private key and password, and register a decrypt key password handler.

Parameters:

  • tls_pk – the content of tls private key

  • tls_pk_len – length of tls private key

  • tls_pk_pw – the content of tls private key password

  • tls_pk_pw_len – length of tls private key password

  • decrypt_handler – decrypt function pointer

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int32_t shmem_set_extern_logger (void(*func)(int level, const char *msg))

Set the log print function for the SHMEM library.

Parameters:

func – the logging function, takes level and msg as parameter

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int32_t shmem_set_log_level (int level)

Set the logging level.

Parameters:

level – the logging level. 0-debug, 1-info, 2-warn, 3-error

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int32_t shmem_set_conf_store_tls (bool enable, const char *tls_info, const uint32_t tls_info_len)

Initialize the config store tls info.

Parameters:

  • enable – whether to enable tls

  • tls_info – the format describle in memfabric SECURITYNOTE.md, if disabled tls_info won’t be use

  • tls_info_len – length of tls_info, if disabled tls_info_len won’t be use

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API int shmem_finalize ()

Release all resources used by the SHMEM library.

Returns:

Returns 0 on success or an error code on failure

SHMEM_HOST_API void shmem_info_get_version (int *major, int *minor)

returns the major and minor version.

Parameters:

  • major – [OUT] major version

  • minor – [OUT] minor version

SHMEM_HOST_API void shmem_info_get_name (char *name)

returns the vendor defined name string.

Parameters:

name – [OUT] name

SHMEM_HOST_API void shmem_global_exit (int status)

exit all ranks.

Parameters:

status – [IN] name

shmem_host_rma.h

Enums

enum [anonymous]

Values:

enumerator NO_NBI
enumerator NBI

Functions

SHMEM_HOST_API void * shmem_ptr (void *ptr, int pe)

Translate an local symmetric address to remote symmetric address on the specified PE. Firstly, check whether the input address is legal on local PE. Then translate it into remote address on specified PE. Otherwise, returns a null pointer.

Parameters:

  • ptr – [in] Symmetric address on local PE.

  • pe – [in] The number of the remote PE.

Returns:

If the input address is legal, returns a remote symmetric address on the specified PE that can be accessed using memory loads and stores. Otherwise, a null pointer is returned.

SHMEM_HOST_API int shmem_mte_set_ub_params (uint64_t offset, uint32_t ub_size, uint32_t event_id)

Set necessary parameters for put or get.

Parameters:

  • offset – [in] The start address on UB.

  • ub_size – [in] The Size of Temp UB Buffer.

  • event_id – [in] Sync ID for put or get.

Returns:

Returns 0 on success or an error code on failure.

SHMEM_HOST_API void shmem_put_NAME_mem (TYPE *dest, TYPE *source, size_t nelems, int pe)

Synchronous interface. Copy a contiguous data on local PE to symmetric address on the specified PE.

Parameters:

  • dest – [in] Pointer on Symmetric memory of the destination data.

  • source – [in] Pointer on local device of the source data.

  • nelems – [in] Number of elements in the destination and source arrays.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_put_NAME_mem_nbi (TYPE *dest, TYPE *source, size_t nelems, int pe)

Asynchronous interface. Copy a contiguous data on local PE to symmetric address on the specified PE.

Parameters:

  • dest – [in] Pointer on Symmetric memory of the destination data.

  • source – [in] Pointer on local device of the source data.

  • nelems – [in] Number of elements in the destination and source arrays.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_get_NAME_mem (TYPE *dest, TYPE *source, size_t nelems, int pe)

Synchronous interface. Copy contiguous data on symmetric memory from the specified PE to address on the local PE.

Parameters:

  • dest – [in] Pointer on Symmetric memory of the destination data.

  • source – [in] Pointer on local device of the source data.

  • nelems – [in] Number of elements in the destination and source arrays.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_get_NAME_mem_nbi (TYPE *dest, TYPE *source, size_t nelems, int pe)

Asynchronous interface. Copy contiguous data on symmetric memory from the specified PE to address on the local PE.

Parameters:

  • dest – [in] Pointer on Symmetric memory of the destination data.

  • source – [in] Pointer on local device of the source data.

  • nelems – [in] Number of elements in the destination and source arrays.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_put_NAME_signal (TYPE *dst, TYPE *src, size_t elem_size, uint8_t *sig_addr, int32_t signalint sig_opint pe)

Synchronous interface. Copy a contiguous data on local UB to symmetric address on the specified PE.

Parameters:

  • dst – [in] Pointer on local device of the destination data.

  • src – [in] Pointer on Symmetric memory of the source data.

  • elem_size – [in] Number of elements in the dest and source arrays.

  • sig_addr – [in] Symmetric address of the signal word to be updated.

  • signal – [in] The value used to update sig_addr.

  • sig_op – [in] Operation used to update sig_addr with signal. Supported operations: SHMEM_SIGNAL_SET/SHMEM_SIGNAL_ADD

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_put_NAME_signal_nbi (TYPE *dst, TYPE *src, size_t elem_size, uint8_t *sig_addr, int32_t signalint sig_opint pe)

Asynchronous interface. Copy a contiguous data on local PE to symmetric address on the specified PE.

Parameters:

  • dst – [in] Pointer on local device of the destination data.

  • src – [in] Pointer on Symmetric memory of the source data.

  • elem_size – [in] Number of elements in the dest and source arrays.

  • sig_addr – [in] Symmetric address of the signal word to be updated.

  • signal – [in] The value used to update sig_addr.

  • sig_op – [in] Operation used to update sig_addr with signal. Supported operations: SHMEM_SIGNAL_SET/SHMEM_SIGNAL_ADD

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_NAME_p (TYPE *dst, const TYPEvalue, int pe)

Provide a low latency put capability for single element of most basic types.

Parameters:

  • dst – [in] Symmetric address of the destination data on local PE.

  • value – [in] The element to be put.

  • pe – [in] The number of the remote PE.

SHMEM_HOST_API TYPE shmem_NAME_g (TYPE *src, int32_t pe)

Provide a low latency put capability for single element of most basic types.

Parameters:

  • src – [in] Symmetric address of the destination data on local PE.

  • pe – [in] The number of the remote PE.

SHMEM_HOST_API void shmem_putmem (void *dst, void *src, size_t elem_size, int32_t pe)

Synchronous interface. Copy contiguous data on symmetric memory from local PE to address on the specified PE.

Parameters:

  • dst – [in] Pointer on Symmetric addr of local PE.

  • src – [in] Pointer on local memory of the source data.

  • elem_size – [in] size of elements in the destination and source addr.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_getmem (void *dst, void *src, size_t elem_size, int32_t pe)

Synchronous interface. Copy contiguous data on symmetric memory from the specified PE to address on the local PE.

Parameters:

  • dst – [in] Pointer on local device of the destination data.

  • src – [in] Pointer on Symmetric memory of the source data.

  • elem_size – [in] size of elements in the destination and source addr.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_putmem_nbi (void *dst, void *src, size_t elem_size, int32_t pe)

Asynchronous interface. Copy contiguous data on symmetric memory from the specified PE to address on the local PE.

Parameters:

  • dst – [in] Pointer on Symmetric addr of local PE.

  • src – [in] Pointer on local memory of the source data.

  • elem_size – [in] size of elements in the destination and source addr.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_getmem_nbi (void *dst, void *src, size_t elem_size, int32_t pe)

Asynchronous interface. Copy contiguous data on symmetric memory from the specified PE to address on the local PE.

Parameters:

  • dst – [in] Pointer on local device of the destination data.

  • src – [in] Pointer on Symmetric memory of the source data.

  • elem_size – [in] size of elements in the destination and source addr.

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_putmem_signal_nbi (void *dst, void *src, size_t elem_size, void *sig_addr, int32_t signal, int sig_op, int pe)

Asynchronous interface. Copy a contiguous data on local UB to symmetric address on the specified PE.

Parameters:

  • dst – [in] Pointer on local device of the destination data.

  • src – [in] Pointer on Symmetric memory of the source data.

  • elem_size – [in] Number of elements in the dest and source arrays.

  • sig_addr – [in] Symmetric address of the signal word to be updated.

  • signal – [in] The value used to update sig_addr.

  • sig_op – [in] Operation used to update sig_addr with signal. Supported operations: SHMEM_SIGNAL_SET/SHMEM_SIGNAL_ADD

  • pe – [in] PE number of the remote PE.

SHMEM_HOST_API void shmem_putmem_signal (void *dst, void *src, size_t elem_size, void *sig_addr, int32_t signal, int sig_op, int pe)

Synchronous interface. Copy a contiguous data on local UB to symmetric address on the specified PE.

Parameters:

  • dst – [in] Pointer on local device of the destination data.

  • src – [in] Pointer on Symmetric memory of the source data.

  • elem_size – [in] Number of elements in the dest and source arrays.

  • sig_addr – [in] Symmetric address of the signal word to be updated.

  • signal – [in] The value used to update sig_addr.

  • sig_op – [in] Operation used to update sig_addr with signal. Supported operations: SHMEM_SIGNAL_SET/SHMEM_SIGNAL_ADD

  • pe – [in] PE number of the remote PE.

shmem_host_sync.h

Functions

SHMEM_HOST_API uint64_t shmemx_get_ffts_config ()

Get runtime ffts config. This config should be passed to MIX Kernel and set by MIX Kernel using shmemx_set_ffts. Refer to shmemx_set_ffts for more details.

Returns:

ffts config

SHMEM_HOST_API void shmem_handle_wait (shmem_handle_t handle, aclrtStream stream)

shmem_host_team.h

Functions

SHMEM_HOST_API int shmem_team_split_strided (shmem_team_t parent_team, int pe_start, int pe_stride, int pe_size, shmem_team_t *new_team)

Collective Interface. Creates a new SHMEM team from an existing parent team.

Parameters:

  • parent_team – [in] A team handle.

  • pe_start – [in] The first PE number of the subset of PEs from the parent team.

  • pe_stride – [in] The stride between team PE numbers in the parent team.

  • pe_size – [in] The total number of PEs in new team.

  • new_team – [out] A team handle.

Returns:

0 on successful creation of new_team; otherwise nonzero.

SHMEM_HOST_API int shmem_team_split_2d (shmem_team_t parent_team, int x_range, shmem_team_t *x_team, shmem_team_t *y_team)

Collective Interface. Split team from an existing parent team based on a 2D Cartsian Space.

Parameters:

  • parent_team – [in] A team handle.

  • x_range – [in] represents the number of elements in the first dimensions

  • x_team – [in] A new x-axis team after team split.

  • y_team – [in] A new y-axis team after team split.

Returns:

0 on successful creation of new_team; otherwise nonzero.

SHMEM_HOST_API int shmem_team_translate_pe (shmem_team_t src_team, int src_pe, shmem_team_t dest_team)

Translate a given PE number in one team into the corresponding PE number in another team.

Parameters:

  • src_team – [in] A SHMEM team handle.

  • src_pe – [in] The PE number in src_team.

  • dest_team – [in] A SHMEM team handle.

Returns:

The number of PEs in the specified team. If the team handle is SHMEM_TEAM_INVALID, returns -1.

SHMEM_HOST_API void shmem_team_destroy (shmem_team_t team)

Collective Interface. Destroys the team referenced by the team handle.

Parameters:

team – [in] A team handle.

SHMEM_HOST_API int shmem_my_pe (void)

Returns the PE number of the local PE.

Returns:

Integer between 0 and npes - 1

SHMEM_HOST_API int shmem_n_pes (void)

Returns the number of PEs running in the program.

Returns:

Number of PEs in the program.

SHMEM_HOST_API int shmem_team_my_pe (shmem_team_t team)

Returns the number of the calling PE in the specified team.

Parameters:

team – [in] A team handle.

Returns:

The number of the calling PE within the specified team. If the team handle is SHMEM_TEAM_INVALID, returns -1.

SHMEM_HOST_API int shmem_team_n_pes (shmem_team_t team)

Returns the number of PEs in the specified team.

Parameters:

team – [in] A team handle.

Returns:

The number of PEs in the specified team. If the team handle is SHMEM_TEAM_INVALID, returns -1.

SHMEM_HOST_API int shmem_team_get_config (shmem_team_t team, shmem_team_config_t *config)

return team config which pass in as team created

Parameters:

  • team – [IN] team handle

  • config – [OUT] the config associated with team, reserved for future use