Synx APIs
Synx
Classes | Macros | Enumerations
synx.h File Reference

The Synx API. More...

#include <stdint.h>

Go to the source code of this file.

Classes

struct  synx_session
 
struct  synx_initialization_params
 
struct  synx_create_params
 
struct  synx_callback_params
 
struct  synx_import_indv_params
 
struct  synx_import_arr_params
 
struct  synx_import_params
 
struct  synx_merge_params
 

Macros

#define SYNX_INLINE
 
#define SYNX_API   SYNX_DLL_IMPORT
 
#define SYNX_DEVICE_NAME   "synx_device"
 
#define SYNX_SUCCESS   0
 
#define SYNX_NOMEM   ENOMEM
 
#define SYNX_NOSUPPORT   EPERM
 
#define SYNX_NOPERM   EPERM
 
#define SYNX_TIMEOUT   ETIMEDOUT
 
#define SYNX_ALREADY   EALREADY
 
#define SYNX_NOENT   ENOENT
 
#define SYNX_INVALID   EINVAL
 
#define SYNX_ERROR_FAILED   EPERM
 
#define SYNX_NO_TIMEOUT   ((uint64_t)-1)
 
#define SYNX_INVALID_HANDLE   0
 

Enumerations

enum  synx_client_id { SYNX_CLIENT_NATIVE = 0, SYNX_CLIENT_MAX }
 
enum  synx_init_flags { SYNX_INIT_DEFAULT = 0x00, SYNX_INIT_MAX = 0x01 }
 
: Client session name

struct synx_initialization_params - Session params.

     Only first 64 bytes are accepted, rest will be ignored.

: Client identifier. : Synx initialization flags.

enum  synx_create_flags { SYNX_CREATE_LOCAL_FENCE = 0x01, SYNX_CREATE_GLOBAL_FENCE = 0x02, SYNX_CREATE_DMA_FENCE = 0x04, SYNX_CREATE_CSL_FENCE = 0x08 }
 

: Optional parameter associating a name with the synx

struct synx_create_params - Synx creation parameters.

        object for debug purposes.
        Only first 64 bytes are accepted,
        rest will be ignored.

: Pointer to synx object handle. (filled by function) : Pointer to external dma fence or csl fence. (NOT SUPPORTED) : Synx create flags for customization.

enum  synx_signal_status { SYNX_STATE_SIGNALED_SUCCESS = 2, SYNX_STATE_SIGNALED_CANCEL = 4, SYNX_STATE_SIGNALED_MAX = 64 }
 
enum  synx_import_flags {
  SYNX_IMPORT_LOCAL_FENCE = 0x01, SYNX_IMPORT_GLOBAL_FENCE = 0x02, SYNX_IMPORT_SYNX_FENCE = 0x04, SYNX_IMPORT_DMA_FENCE = 0x08,
  SYNX_IMPORT_EX_RELEASE = 0x10
}
 
enum  synx_import_type { SYNX_IMPORT_INDV_PARAMS = 0x01, SYNX_IMPORT_ARR_PARAMS = 0x02 }
 
enum  synx_merge_flags { SYNX_MERGE_LOCAL_FENCE = 0x01, SYNX_MERGE_GLOBAL_FENCE = 0x02, SYNX_MERGE_NOTIFY_ON_ALL = 0x04, SYNX_MERGE_NOTIFY_ON_ANY = 0x08 }
 
enum  synx_status {
  SYNX_STATUS_INVALID = 0, SYNX_STATUS_UNSIGNALED, SYNX_STATUS_SIGNALED_SUCCESS, SYNX_STATUS_SIGNALED_ERROR,
  SYNX_STATUS_SIGNALED_CANCEL, SYNX_STATUS_SIGNALED_EXTERNAL, SYNX_STATUS_SIGNALED_SSR, SYNX_STATUS_TIMEOUT
}
 
typedef void(* synx_user_callback) (uint32_t h_synx, int status, void *data)
 
SYNX_API struct synx_session * synx_initialize (struct synx_initialization_params *pParam)
 : Initializes a new client session. More...
 
SYNX_API int32_t synx_uninitialize (struct synx_session *pSession)
 : Destroys the client session. Every initialized session should be uninitialized. More...
 
SYNX_API int32_t synx_create (struct synx_session *pSession, struct synx_create_params *pParam)
 : Creates a synx object. More...
 
SYNX_API int32_t synx_get_status (struct synx_session *pSession, uint32_t hSynx)
 : Returns the status of the synx object. This API should not be used in polling mode to check if the handle is signaled or not, client needs to explicitly wait using synx_wait() or synx_async_wait() More...
 
SYNX_API int32_t synx_release (struct synx_session *pSession, uint32_t hSynx)
 : Releases the synx object. Every created, imported or merged synx object should be released. More...
 
SYNX_API int32_t synx_signal (struct synx_session *pSession, uint32_t hSynx, enum synx_signal_status state)
 : Signals a synx object with the status argument. More...
 
SYNX_API int32_t synx_wait (struct synx_session *pSession, uint32_t hSynx, uint64_t timeout_ms)
 : Waits for a synx object synchronously More...
 
SYNX_API int32_t synx_async_wait (struct synx_session *pSession, struct synx_callback_params *pParams)
 : Registers a callback with a synx object. More...
 
SYNX_API int32_t synx_cancel_async_wait (struct synx_session *pSession, struct synx_callback_params *pParams)
 : De-registers a callback with a synx object More...
 
SYNX_API int32_t synx_merge (struct synx_session *pSession, struct synx_merge_params *pParams)
 : Merges multiple synx objects. More...
 
SYNX_API int32_t synx_import (struct synx_session *pSession, struct synx_import_params *pParams)
 : Imports (looks up) synx object from given handle or fence. More...
 
SYNX_API int32_t synx_get_fd (struct synx_session *pSession, uint32_t hSynx)
 : Obtain an fd for the synx object(Not supported for DSP) More...
 

Detailed Description

The Synx API.

Macro Definition Documentation

◆ SYNX_INVALID_HANDLE

#define SYNX_INVALID_HANDLE   0

SYNX_INVALID_HANDLE : client can assign the synx handle variable with this value when it doesn't hold a valid synx handle

◆ SYNX_SUCCESS

#define SYNX_SUCCESS   0

Error codes returned from framework

Return codes are mapped to platform specific return values.

Typedef Documentation

◆ synx_user_callback

typedef void(* synx_user_callback) (uint32_t h_synx, int status, void *data)

synx_user_callback - Callback function registered by clients.

User callback registered for non-blocking wait. Dispatched with status of synx object if it is signaled or SYNX_STATUS_TIMEOUT in case of timeout.

Enumeration Type Documentation

◆ synx_client_id

enum synx_client_id

enum synx_client_id : Unique identifier of the supported clients.

: Native Client to be passed during session initialization.

◆ synx_create_flags

enum synx_create_flags

enum synx_create_flags - Flags passed during synx_create call.

SYNX_CREATE_LOCAL_FENCE : Instructs the framework to create local synx object, for local synchronization i.e within core. SYNX_CREATE_GLOBAL_FENCE : Instructs the framework to create global synx object, for global synchronization i.e across cores. SYNX_CREATE_DMA_FENCE : Create a synx object by wrapping the provided dma fence. Need to pass the fd backed by the SyncFile through fence variable if this flag is set. (NOT SUPPORTED) SYNX_CREATE_CSL_FENCE : Create a synx object with provided csl fence. Establishes interop with the csl fence through bind operations. (NOT SUPPORTED)

◆ synx_import_flags

enum synx_import_flags

enum synx_import_flags - Import flags SYNX_IMPORT_LOCAL_FENCE : Instructs the framework to create local synx object for local synchronization i.e. within same core. SYNX_IMPORT_GLOBAL_FENCE : Instructs the framework to create global synx object for global synchronization i.e. across supported cores. SYNX_IMPORT_SYNX_FENCE : Import native Synx handle for synchronization. Need to pass the Synx handle ptr through fence variable if this flag is set. Client must pass: a. SYNX_IMPORT_SYNX_FENCE|SYNX_IMPORT_LOCAL_FENCE to import a synx handle as local synx handle. b. SYNX_IMPORT_SYNX_FENCE|SYNX_IMPORT_GLOBAL_FENCE to import a synx handle as global synx handle. SYNX_IMPORT_DMA_FENCE : Import dma fence and create Synx handle for interop Need to pass the dma_fence fd ptr through fence variable if this flag is set. Client must pass: a. SYNX_IMPORT_DMA_FENCE|SYNX_IMPORT_LOCAL_FENCE to import a dma fence and create local synx handle for interop. b. SYNX_IMPORT_GLOBAL_FENCE|SYNX_IMPORT_DMA_FENCE to import a dma fence and create global synx handle for interop. (Not supported on DSP) SYNX_IMPORT_EX_RELEASE : Flag to inform relaxed invocation where release call need not be called by client on this handle after import. (NOT SUPPORTED)

◆ synx_import_type

enum synx_import_type

SYNX_IMPORT_INDV_PARAMS : Import filled with synx_import_indv_params struct. SYNX_IMPORT_ARR_PARAMS : Import filled with synx_import_arr_params struct.

◆ synx_init_flags

enum synx_init_flags

enum synx_init_flags - Session initialization flag. : Intialization flag to be passed while initializing session. : Used for internal checks.

◆ synx_merge_flags

enum synx_merge_flags

SYNX_MERGE_LOCAL_FENCE : Create local composite synx object. To be passed along with SYNX_MERGE_NOTIFY_ON_ALL. SYNX_MERGE_GLOBAL_FENCE : Create global composite synx object. To be passed along with SYNX_MERGE_NOTIFY_ON_ALL. SYNX_MERGE_NOTIFY_ON_ALL : Notify on signaling of ALL synx objects. Client must pass: a. SYNX_MERGE_LOCAL_FENCE|SYNX_MERGE_NOTIFY_ON_ALL to create local composite synx object and notify it when all child synx objects are signaled. b. SYNX_MERGE_GLOBAL_FENCE|SYNX_MERGE_NOTIFY_ON_ALL to create global composite synx object and notify it when all child synx objects are signaled. SYNX_MERGE_NOTIFY_ON_ANY : Notify on signaling of ANY object. (NOT SUPPORTED)

◆ synx_signal_status

enum synx_signal_status

enum synx_signal_status - Signal status.

SYNX_STATE_SIGNALED_SUCCESS : Signal success. SYNX_STATE_SIGNALED_CANCEL : Signal cancellation. SYNX_STATE_SIGNALED_MAX : Clients can send custom notification beyond the max value (only positive). Clients should not pass SYNX_STATE_SIGNALED_MAX, only values greater than SYNX_STATE_SIGNALED_MAX are to be used for sending custom notification.

◆ synx_status

enum synx_status

enum synx_signal_status - Signal status.

SYNX_STATE_SIGNALED_SUCCESS : Signal success. SYNX_STATE_SIGNALED_CANCEL : Signal cancellation. SYNX_STATE_SIGNALED_MAX : Clients can send custom notification beyond the max value (only positive). Clients should not pass SYNX_STATE_SIGNALED_MAX, only values greater than SYNX_STATE_SIGNALED_MAX are to be used for sending custom notification.

Function Documentation

◆ synx_async_wait()

SYNX_API int32_t synx_async_wait ( struct synx_session *  pSession,
struct synx_callback_params *  pParams 
)

: Registers a callback with a synx object.

Clients can register maximum of 64 callback functions per synx session.

Parameters
pSession: Session ptr (returned from synx_initialize)
pParams: Callback params. cancel_cb_func in callback params is optional.
Returns
Status of operation. Negative in case of error. SYNX_SUCCESS otherwise.

◆ synx_cancel_async_wait()

SYNX_API int32_t synx_cancel_async_wait ( struct synx_session *  pSession,
struct synx_callback_params *  pParams 
)

: De-registers a callback with a synx object

This API will only cancel one instance of callback function(mapped with userdata and h_synx) provided in cb_func of callback params.

Parameters
pSession: Session ptr (returned from synx_initialize)
pParams: Callback params.
Returns
Status of operation.-SYNX_ALREADY if object has already been signaled or timedout, and cannot be cancelled. Negative in case of error. SYNX_SUCCESS otherwise.

◆ synx_create()

SYNX_API int32_t synx_create ( struct synx_session *  pSession,
struct synx_create_params *  pParam 
)

: Creates a synx object.

Creates a new synx obj and returns the handle to client. There can be maximum of 4095 global synx handles or local synx handles across sessions.

Parameters
pSession: Session ptr (returned from synx_initialize)
pParam: Pointer to create params.
Returns
Status of operation. Negative in case of error. SYNX_SUCCESS otherwise.

◆ synx_get_fd()

SYNX_API int32_t synx_get_fd ( struct synx_session *  pSession,
uint32_t  hSynx 
)

: Obtain an fd for the synx object(Not supported for DSP)

The platform native fence is wrapped and returned through fence fd, which could be shared with other processes through binder interface. It is client's reponsibility to destroy fd once used.

Parameters
pSession: Session ptr (returned from synx_initialize)
hSynx: Synx object handle
Returns
File Decriptor on success. Negative in case of error.

◆ synx_get_status()

SYNX_API int32_t synx_get_status ( struct synx_session *  pSession,
uint32_t  hSynx 
)

: Returns the status of the synx object. This API should not be used in polling mode to check if the handle is signaled or not, client needs to explicitly wait using synx_wait() or synx_async_wait()

Parameters
pSession: Session ptr (returned from synx_initialize)
hSynx: Synx object handle.
Returns
Status of the synx object(same as synx_status enum).

◆ synx_import()

SYNX_API int32_t synx_import ( struct synx_session *  pSession,
struct synx_import_params *  pParams 
)

: Imports (looks up) synx object from given handle or fence.

Parameters
pSession: Session ptr (returned from synx_initialize)
pParams: Pointer to import params
Returns
Status of operation. Negative in case of error. SYNX_SUCCESS otherwise.

◆ synx_initialize()

SYNX_API struct synx_session* synx_initialize ( struct synx_initialization_params *  pParam)

: Initializes a new client session.

Parameters
params: Pointer to session init params
Returns
Client session pointer on success. NULL in case of failure.

◆ synx_merge()

SYNX_API int32_t synx_merge ( struct synx_session *  pSession,
struct synx_merge_params *  pParams 
)

: Merges multiple synx objects.

This function will merge multiple synx objects into a synx group. Subsequently composite merged synx objects can also be merged(Not supported for DSP).

Parameters
pSession: Session ptr (returned from synx_initialize)
pParams: Merge params
Returns
Status of operation. Negative in case of error. SYNX_SUCCESS otherwise.

◆ synx_release()

SYNX_API int32_t synx_release ( struct synx_session *  pSession,
uint32_t  hSynx 
)

: Releases the synx object. Every created, imported or merged synx object should be released.

Parameters
pSession: Session ptr (returned from synx_initialize)
hSynx: Synx object handle to be destroyed
Returns
Status of operation. SYNX_ERROR_FAILED in case of error. SYNX_SUCCESS otherwise.

◆ synx_signal()

SYNX_API int32_t synx_signal ( struct synx_session *  pSession,
uint32_t  hSynx,
enum synx_signal_status  state 
)

: Signals a synx object with the status argument.

This function will signal the synx object referenced by h_synx and invoke any external binding synx objs. The status parameter will indicate whether the entity performing the signaling wants to convey an error case or a success case.

Parameters
pSession: Session ptr (returned from synx_initialize)
hSynx: Synx object handle
status: Status of signaling.
Returns
Status of operation. Negative in case of error. SYNX_SUCCESS otherwise.

◆ synx_uninitialize()

SYNX_API int32_t synx_uninitialize ( struct synx_session *  pSession)

: Destroys the client session. Every initialized session should be uninitialized.

Parameters
pSession: Session ptr (returned from synx_initialize)
Returns
Status of operation. Negative in case of error. SYNX_SUCCESS otherwise.

◆ synx_wait()

SYNX_API int32_t synx_wait ( struct synx_session *  pSession,
uint32_t  hSynx,
uint64_t  timeout_ms 
)

: Waits for a synx object synchronously

Does a wait on the synx object identified by h_synx for a maximum of timeout_ms milliseconds. Must not be called from interrupt context as this API can sleep. Will return status(enum synx_status) if handle was signaled.

Parameters
pSession: Session ptr (returned from synx_initialize)
hSynx: Synx object handle to be waited upon
timeout_ms: Timeout in ms
Returns
Signal status. -SYNX_INVAL if synx object is in bad state or arguments are invalid, -SYNX_TIMEOUT if wait times out. SYNX_ERROR_FAILED in case of error.