> ## Documentation Index > Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt > Use this file to discover all available pages before exploring further. # GSL Interface > Defines public APIs for Graph Service Layer (GSL) **Header:** `gsl/api/gsl_intf.h` ## Structures ### `gsl_key_value_pair` a single entry in a key vector **Members** key value ### `gsl_key_vector` a complete key vector **Members** number of key value pairs vector of key value pairs ### `gsl_key_vector_array` a key vector with a zero sized array. **Members** number of keys array of key value pairs. ### `gsl_key_vector_list` a key vector list **Members** number of key vectors in the key vector list list of key vectors in the format of \[#keys, kvPair+,..., #keys, kvPair+] ### `gsl_tag_key_vector` a tag key vector with a zero sized array **Members** the module tag identifier graph key value pair ### `gsl_tag_key_vector_list` a tag key vector list **Members** number of key vectors in the key vector list list of key vectors in the format of \[#keys, kvPair+,..., #keys, kvPair+] ### `gsl_cmd_properties` Command payload for GSL\_CMD\_STOP ioctl. **Members** graph key vector to limit the scope of the operation property ID of the subgraph(s) number of values for the subgraph property ID Pointer to property values\[num\_property\_values]. ### `gsl_cmd_configure_read_write_params` Cmd payload for GSL\_CMD\_CONFIGURE\_WRITE\_PARAMS and GSL\_CMD\_CONFIGURE\_READ\_PARAMS. **Members** max number of bytes in a single buffer. number of buffers GSL will use for data exchange In case of write, wait till number of bytes received from client goes ABOVE this value before issuing START to SPF In case of read, wait till client has read this many bytes before issuing START to SPF Set to 0 for immediate start. TBD, currently not supported. Bitfield used to indicate attributes for data transfers, below are the defined fields: data\_mode(Bits 0,1,2): One of GSL\_DATA\_MODE\_SHMEM, GSL\_DATA\_MODE\_BLOCKING, GSL\_DATA\_MODE\_NON\_BLOCKING, GSL\_DATA\_MODE\_PUSH\_PULL, GSL\_DATA\_MODE\_EXTERN\_MEM datapath\_setup(Bits 3,4): one of GSL\_DATAPATH\_SETUP\_DEFAULT, GSL\_DATAPATH\_SETUP\_ALLOC\_SHMEM\_ONLY, GSL\_DATAPATH\_SETUP\_SPF\_PROVISION\_ONLY. Optional tag used to queue read buffers before first gsl\_graph\_read When set to 0, buffers are not queued until first gsl\_graph\_read call. Optional field for passing platform specific data to GSL, this can be used for example to communicate some heap properties to osal layer. ### `gsl_cmd_graph_select` Cmd payload for GSL\_CMD\_ADD\_GRAPH and GSL\_CMD\_CHANGE\_GRAPH. **Members** Used to lookup the new graph. Used to lookup the calibration data that will be set on the new graph. ### `gsl_cmd_remove_graph` Cmd payload for GSL\_CMD\_REMOVE\_GRAPH. **Members** Used to lookup the graph that will be removed. ### `gsl_shmem_buf` Cmd payload for GSL\_CMD\_GET\_WRITE\_BUFF\_INFO and GSL\_CMD\_GET\_READ\_BUFF\_INFO. **Members** buffer address per buffer metadata ### `gsl_cmd_get_shmem_buf_info` **Members** buffer size, all buffers have the same size number of buffers list of buffs, containts num\_buffs entries ### `gsl_cmd_register_custom_event` Cmd payload for GSL\_CMD\_REGISTER\_CUSTOM\_EVENT. **Members** Valid instance ID of module. Valid event ID of the module. Size of the event config data based upon the module\_instance\_id/event\_id combination. 1 - to register the event 0 - to de-register the event module specifc event registration payload ### `gsl_acdb_file` Holds the path of single acdb file, this struct should be bitwise matching against what ACDB APIs expect. **Members** Full file path name length. Array that holds the ACDB file path and name, which cannot exceed 256 characters, including the NULL-termiated character. ### `gsl_acdb_data_files` Holds list of ACDB files, this struct should be bitwise matching against what ACDB APIs expect. **Members** Number of ACDB files. Array of ACDB file full paths. ### `gsl_init_data` Argument for gsl\_init. **Members** acdb files to pass to acdb, setting this NULL means acdb\_addr will be used to acces the data path of acdb delta file acdb image address indicates number of times GSL should check that spf is ready, gsl\_init call is blocked until spf is ready. Amount of time in ms that GSL waits before re-attempting to check Spf readiness. ### `gsl_extern_alloc_buff_info` **Members** unique handle identifying external mem allocation size in bytes of the allocation offset of data buffer within the allocation in bytes ### `gsl_buff` Struct for passing buffer info to gsl\_read and gsl\_write, also used as a return payload for GSL\_EVENT\_ID\_READ\_DONE and GSL\_EVENT\_ID\_WRITE\_DONE. **Members** timestamp in micro-secs bitmasked flags for e.g. size of buffer in bytes data buffer. size of metadata buffer in bytes metadata buffer. extern mem mode info ### `gsl_module_id_info_entry` Maps the modules instance id to module id for a single module. **Members** module id globally unique module instance id ### `gsl_module_id_info` Used to return the module info data to client. **Members** number entries in module list below module list ### `gsl_tag_module_info_entry` Structure mapping the tag\_id to module info (mid and miid) **Members** tag id of the module number of modules matching the tag\_id module list ### `gsl_tag_module_info` Used to return tags and module info data to client given a graph key vector. **Members** number of tags variable payload of type struct gsl\_tag\_module\_info\_entry ### `gsl_event_read_write_done_payload` Event payload passed to client with GSL\_EVENT\_ID\_READ\_DONE and GSL\_EVENT\_ID\_WRITE\_DONE events. **Members** tag that was used to read/write this buffer data buffer status as defined in ar\_osal\_error.h meta-data status as defined in ar\_osal\_error.h buffer that was passed to gsl\_read/gsl\_write ### `gsl_event_eos_payload` Event payload passed to client with GSL\_EVENT\_ID\_EOS. **Members** module instance id from which the EOS event was raised, Invalid (0) when dropped. Indicates whether the final sample was rendered or dropped. ### `gsl_global_event_svc_dn_payload` Event payload passed to client with GSL\_GLOBAL\_EVENT\_AUDIO\_SVC\_DN. **Members** Number of graph handles. List of graph handles impacted by the audio svc going down, client is responsible to close these and re-open them once it receives the audio svc up notification. ### `gsl_event_cb_params` data that will be passed to client in the event callback **Members** identifies the module which generated event identifies the event, in case of GSL internal events it will hold a value from enum gsl\_event\_id size of payload below payload associated with the event if any ### `gsl_cshm_info` **Members** Cached or uncached memory type. Allows rouing shared memory access across multiple DSPs. Flags for shared memory allocation. File descriptor for mapped memory region. Unique GSL memory identifier. ## Functions ### `gsl_get_version` Returns the GSL version. ```cpp theme={null} void gsl_get_version(uint32_t *major, uint32_t *minor) ``` **Parameters** the major version is incremented whenever the current version is NOT backwards compatible with previous version the minor version is incremented whenever the current version has additional features to the previous version but is backwards compatible with it ### `gsl_init` Initialize GSL, must be called before any other GSL calls. ```cpp theme={null} int32_t gsl_init(struct gsl_init_data *init_data) ``` **Parameters** data used during initialization ### `gsl_cshm_init` Initialize GSL cshm, must be called before any other cshm calls. ```cpp theme={null} int32_t gsl_cshm_init(uint32_t num_client) ``` **Parameters** number of clients to be intialized with. If 0, then default value of CSHM\_DEFAULT\_INIT\_CLIENT\_NUM will be used. ### `gsl_cshm_deinit` De-Initialize GSL cshm, must be called after gsl\_deinit() ```cpp theme={null} int32_t gsl_cshm_deinit(void) ``` ### `gsl_deinit` De-initialize GSL, no GSL APIs should be called after this. ```cpp theme={null} void gsl_deinit(void) ``` ### `gsl_register_global_event_cb` Register a global callback function for GSL. ```cpp theme={null} int32_t gsl_register_global_event_cb(gsl_global_cb_func_ptr global_cb, void *client_data) ``` **Parameters** callback function pointer used to notify global events such as SSR opaque client data that will be passed back to client whenever the callback is invoked ### `gsl_open` Load a graph that is specified using graph\_key\_vector to the DSP. Does not reload graphs which are already loaded. ```cpp theme={null} int32_t gsl_open(const struct gsl_key_vector *graph_key_vect, const struct gsl_key_vector *cal_key_vect, gsl_handle_t *graph_handle) ``` **Parameters** used to identify the graph. OPTIONAL used to identify calibration data to be sent to the graph, setting to NULL means dont send any calibration graph handle on success, null otherwise **Returns** GSL\_EOK on success, error code otherwise ### `gsl_close` Close a graph that was specified using the graph\_handle. ```cpp theme={null} int32_t gsl_close(gsl_handle_t graph_handle) ``` **Parameters** Handle of the graph to close **Returns** GSL\_EOK on success, error code otherwise ### `gsl_set_cal` Push calibration data for a given graph to DSP, Must be called before a graph is started. This API need not be called in the case of GSL\_CMD\_CHANGE\_GRAPH as the calibration will be set during the graph change operation itself ```cpp theme={null} int32_t gsl_set_cal(gsl_handle_t graph_handle, const struct gsl_key_vector *graph_key_vect, const struct gsl_key_vector *cal_key_vect) ``` **Parameters** graph handle returned from gsl\_open OPTIONAL identifies the portion of the graph to which this calibration needs to be applied to. For SSMD scenarios, graph\_handle can contain more than one graph key vector. In such cases, clients can provide specific graph key vector to which this calibration needs to be set. The graph\_key\_vector input should match to one of the GKVs that the graph\_handle has. If this parameter is NULL, then GSL sets the prior\_ckv to the one that was given during gsl\_open(). used to identify the cal data. **Returns** EOK on success, error code otherwise ### `gsl_set_config` Set a configuration payload on a specified graph, the payload is stored in acdb. ```cpp theme={null} int32_t gsl_set_config(gsl_handle_t graph_handle, const struct gsl_key_vector *graph_key_vect, uint32_t tag, const struct gsl_key_vector *tag_key_vect) ``` **Parameters** graph handle returned from gsl\_open OPTIONAL identifies the portion of the graph to which this config needs to be applied. For SSMD scenarios, graph\_handle can contain more than one graph key vector. In such cases, clients can provide specific graph key vector to which this calibration needs to be set. The graph\_key\_vector input should match to one of the GKVs that the graph\_handle has. identifies a capability in acdb identifies a payload in the database **Returns** EOK on success, error code otherwise ### `gsl_set_custom_config` Set a custom configuration parameter on a specified graph, the payload is provided from the caller. ```cpp theme={null} int32_t gsl_set_custom_config(gsl_handle_t graph_handle, const uint8_t *payload, const uint32_t payload_size) ``` **Parameters** graph handle returned from gsl\_open custom caller defined payload that will get sent to the module, payload structure shall be always according to OOB sturcutre format defined by SPF the size of the payload buffer **Returns** EOK on success, error code otherwise ### `gsl_set_tagged_custom_config` Set a custom configuration parameter on a specified graph, the payload is provided from the caller. Caller also provides tag ID so gsl can look up ACDB for the module IID to which this payload needs to be sent to. ```cpp theme={null} int32_t gsl_set_tagged_custom_config(gsl_handle_t graph_handle, uint32_t tag, const uint8_t *payload, const size_t payload_size) ``` **Parameters** graph handle returned from gsl\_open identifies a module instance matching the tag ID custom caller defined payload that gets sent to the module, payload structure shall be always according to format defined by SPF the size of the payload buffer **Returns** EOK on success, error code otherwise ### `gsl_set_tagged_custom_config_persist` Persistent set a custom configuration parameter on a specified graph, the payload is provided from the caller. Caller also provides tag ID so gsl can look up ACDB for the module IID to which this payload needs to be sent to. LIMITATION: The payload can contain only a single PID that is destined to a single MID. ```cpp theme={null} int32_t gsl_set_tagged_custom_config_persist(gsl_handle_t graph_handle, uint32_t tag, const uint8_t *payload, const uint32_t payload_size) ``` **Parameters** graph handle returned from gsl\_open identifies a module instance matching the tag ID custom caller defined payload that gets sent to the module, payload structure shall be always according to format defined by SPF the size of the payload buffer **Returns** EOK on success, error code otherwise ### `gsl_get_custom_config` Get the configuration parameter for a specified graph, caller provides a payload. ```cpp theme={null} int32_t gsl_get_custom_config(gsl_handle_t graph_handle, uint8_t *payload, uint32_t size) ``` **Parameters** returned from gsl\_open Buffer that contains the module ids and param ids along with empty areas that will be filled with parameter data holds the size of the client buffer passed in for payload. On return will hold actual bytes written. **Returns** EOK on success, error code otherwise. Note that EOK does not mean we got valid data, it is possible that the buffer did not contain enough space for a given parameter. The client should check the error codes inside the buffer before reading the data. ### `gsl_get_tagged_custom_config` Get the configuration parameter for a specified graph from the module that is specified by a tag, caller provides a payload with the PIDs populated. GSL will populate the MIDS into the payload. LIMITATION: Only a single parameter on a single module can be looked up at a time ```cpp theme={null} int32_t gsl_get_tagged_custom_config(gsl_handle_t graph_handle, uint32_t tag, uint8_t *payload, uint32_t *size) ``` **Parameters** returned from gsl\_open tag used by GSL to lookup the MIDs Buffer that contains param ids along with empty areas that will be filled with parameter data holds the size of the client buffer passed in for payload. On return will hold actual bytes written. **Returns** EOK on success, error code otherwise. Note that EOK does not mean we got valid data, it is possible that the buffer did not contain enough space for a given parameter. The client should check the error codes inside the buffer before reading the data. ### `gsl_ioctl` Send commands to GSL for controlling Graphs in Spf. ```cpp theme={null} int32_t gsl_ioctl(gsl_handle_t graph_handle, enum gsl_cmd_id cmd_id, void *cmd_payload, size_t cmd_payload_sz) ``` **Parameters** graph handle returned from gsl\_open identifies the command command specific parameters size of cmd\_payload **Returns** EOK on success, error code otherwise ### `gsl_read` Receive data buffers from Spf. ```cpp theme={null} int32_t gsl_read(gsl_handle_t graph_handle, uint32_t tag, struct gsl_buff *buff, uint32_t *filled_size) ``` **Parameters** graph handle returned from gsl\_open used to identify the module in Spf to read buffers from buffer where data will be copied to actual number of bytes filled into the buffer by GSL **Returns** EOK on success, AR\_EABORTED when buffer is not queued to spf because of graph close, stop, or flush (non-fatal error), error code otherwise ### `gsl_write` Write data buffers to Spf. ```cpp theme={null} int32_t gsl_write(gsl_handle_t graph_handle, uint32_t tag, struct gsl_buff *buff, uint32_t *consumed_size) ``` **Parameters** graph handle returned from gsl\_open used to identify the module in Spf to write buffers to buffer containing data that will be written actual number of bytes consumed by GSL **Returns** EOK on success, AR\_EABORTED when buffer is not queued to spf because of graph close, stop, or flush (non-fatal error), error code otherwise ### `gsl_register_event_cb` Register an event callback function with Spf. ```cpp theme={null} int32_t gsl_register_event_cb(gsl_handle_t graph_handle, gsl_cb_func_ptr cb, void *client_data) ``` **Parameters** graph handle returned from gsl\_open pointer to callback function opaque data that will be passed to client in the callback **Returns** EOK on success, error code otherwise ### `gsl_get_tagged_data` Query database for data associated with a given tag and tkv. This API is used to get spf module data in the form ```cpp theme={null} int32_t gsl_get_tagged_data(const struct gsl_key_vector *graph_key_vect, uint32_t tag, struct gsl_key_vector *tag_key_vect, uint8_t *payload, size_t *payload_size) ``` **Parameters** graph key vector used to identify a certain capability tag key vector used to identify a specific payload in acdb pointer to a buffer where the payload will be copied to holds the size of the client buffer passed in for payload and on return will hold the size of the actual data written to the buffer. **Returns** EOK on success, error code otherwise. In-case the provided payload\_size is not big enough to hold output data the error code AR\_ENEEDMORE will be returned and payload\_size will be set to expected size. ### `gsl_get_tagged_module_info` Query database for module\_iid to module\_id mapping data. ```cpp theme={null} int32_t gsl_get_tagged_module_info(const struct gsl_key_vector *graph_key_vect, uint32_t tag, struct gsl_module_id_info **module_info, uint32_t *module_info_size) ``` **Parameters** graph key vector identifies a set of modules in ACDB that were tagged with with this tag by system designer module info will be copied here. GSL dynamically allocates memory to hold module\_info for the num\_modules matching the tag. Client is responsible to free the memory after use. holds the size of the data written to the module\_info buffer **Returns** EOK on success, error code otherwise. ### `gsl_get_tags_with_module_info` Query database for all tags and corresponding module\_iid and module\_id mapping given a graph key vector. ```cpp theme={null} int32_t gsl_get_tags_with_module_info(const struct gsl_key_vector *graph_key_vect, void *tag_module_info, size_t *tag_module_info_size) ``` **Parameters** graph key vector tag module info will be copied here. GSL clients would call this API twice, first call tag\_module\_info is set to NULL and GSL fills only the size - \*tag\_module\_info\_size. GSL clients then allocate memory set it to tag\_module\_info and call the API again for the second time and the tag module info gets copied into that memory. The payload is in the format "struct gsl\_tag\_module\_info" used to provide the size (in bytes) of tag\_module\_info from client and output the expected size from gsl in-case size passed from client was too small **Returns** EOK on success, error code otherwise. ### `gsl_enable_acdb_persistence` enable persistence for cals set to ACDB ```cpp theme={null} int32_t gsl_enable_acdb_persistence(uint8_t enable_flag) ``` **Parameters** 1 means enable, 0 is disable **Returns** EOK on success, error code otherwise ### `gsl_set_cal_data_to_acdb` Store custom calibration to ACDB. ```cpp theme={null} int32_t gsl_set_cal_data_to_acdb(const struct gsl_key_vector *graph_key_vect, const struct gsl_key_vector *cal_key_vect, uint8_t *payload, uint32_t payload_size) ``` **Parameters** graph key vector tag key vector used to identify an entry in acdb pointer to a buffer containing custom calibration holds the size of the client buffer passed in for payload **Returns** EOK on success, error code otherwise ### `gsl_get_cal_data_from_acdb` Retrieve custom calibration from ACDB. ```cpp theme={null} int32_t gsl_get_cal_data_from_acdb(const struct gsl_key_vector *graph_key_vect, const struct gsl_key_vector *cal_key_vect, uint32_t num_modules, uint8_t *param_list, void *payload, uint32_t *payload_size) ``` **Parameters** graph key vector tag key vector used to identify an entry in acdb The number of module instances in the param\_list List of module instances plus their parameters to get data for pointer to a buffer of returned payload\_size to hold returned calibration holds the size of the client buffer passed in for payload. Client will call this API twice, once to fill this payload size and the second time to fill payload, with memory of returned payload\_size allocated for payload **Returns** EOK on success, error code otherwise ### `gsl_set_tag_data_to_acdb` Store custom tag to ACDB. ```cpp theme={null} int32_t gsl_set_tag_data_to_acdb(const struct gsl_key_vector *graph_key_vect, uint32_t tag_id, const struct gsl_key_vector *tag_key_vect, uint8_t *payload, uint32_t payload_size) ``` **Parameters** graph key vector tag ID to be set tag key vector used to identify an entry in acdb pointer to a buffer containing custom tag data holds the size of the client buffer passed in for payload **Returns** EOK on success, error code otherwise ### `gsl_get_tag_data_from_acdb` Retrieve custom tag from ACDB. ```cpp theme={null} int32_t gsl_get_tag_data_from_acdb(const struct gsl_key_vector *graph_key_vect, uint32_t tag_id, const struct gsl_key_vector *tag_key_vect, uint32_t num_modules, uint8_t *param_list, void *payload, uint32_t *payload_size) ``` **Parameters** graph key vector tag ID for data to retrieve tag key vector used to identify an entry in acdb The number of module instances in the param\_list List of module instances plus their parameters to get data for pointer to a buffer of returned payload\_size to hold returned tag data holds the size of the client buffer passed in for payload. Client will call this API twice, once to fill this payload size and the second time to fill payload, with memory of returned payload\_size allocated for payload **Returns** EOK on success, error code otherwise ### `gsl_set_temp_path_to_acdb` Updates the read/write temporary path that AML uses for the reinit/delta persistence functionality. ```cpp theme={null} int32_t gsl_set_temp_path_to_acdb(uint32_t path_length, const char *temp_path) ``` **Parameters** Command ID is ACDB\_CMD\_SET\_TEMP\_PATH. a null terminated char array of under 255 chars **Returns** * AR\_EOK Command executed successfully. AR\_EBADPARAM Invalid input parameters were provided. AR\_EFAILED Command execution failed. ### `gsl_get_processed_buff_cnt` Get an ever increasing count of data buffers processed by GSL. For playback case returns the number of buffers acked by Spf. For capture case returns the number of buffers received from Spf. ```cpp theme={null} int32_t gsl_get_processed_buff_cnt(gsl_handle_t graph_handle, enum gsl_data_dir dir, uint32_t *cnt) ``` **Parameters** graph handle indicates whether to return the write or read buffer counts An ever increasing count of buffers, the number wraps back to zero once it reaches SIZE\_MAX **Returns** AR\_EOK in success, error code otherwise ### `gsl_get_avail_buffer_size` Get the size of available buffer (in bytes) ready to be written (playback) / read (capture) For playback case, returns the size of empty buffer (in bytes) for GSL clients to write. For capture case, returns the size of buffer (in bytes) that GSL clients can queue to SPF for read. ```cpp theme={null} int32_t gsl_get_avail_buffer_size(gsl_handle_t graph_handle, enum gsl_data_dir dir, uint32_t *bytes) ``` **Parameters** graph handle indicates whether to return write or read available buffer size buffer size (in bytes) ready to be written (playback) / read (capture) **Returns** AR\_EOK in success, error code otherwise. ### `gsl_get_driver_data` Get driver data. This API is to be called by GSL clients for querying any driver specific data that they stored in ACDB ```cpp theme={null} int32_t gsl_get_driver_data(const uint32_t module_id, const struct gsl_key_vector *key_vect, void *data_payload, uint32_t *data_payload_size) ``` **Parameters** client defined module\_id against which data is stored in acdb OPTIONAL key vector used to look up data buffer where data will be returned, client is responsible to allocate memory for this buffer. If this is set to NULL the size of the output data will be returned in data\_payload\_size on input it containes the size of data\_payload, on output will have the size actually written **Returns** AR\_EOK in success, error code otherwise ### `gsl_get_graph_tkvs` Get all tag/TKV variations. Retrieves all tag and tag key vector variations which are defined for a given graph key vector in ACDB ```cpp theme={null} int32_t gsl_get_graph_tkvs(const struct gsl_key_vector *graph_key_vect, struct gsl_tag_key_vector_list *data_payload) ``` **Parameters** GKV to find tag & TKV pairs in ACDB for buffer where data will be returned, client is responsible to allocate memory for this buffer. If data\_payload->key\_vector\_list is set to NULL, the size of the output data will be returned in data\_payload->list\_size. **Returns** AR\_EOK in success, error code otherwise ### `gsl_get_graph_ckvs` Get all CKVs for given GKV. Queries for all SPF module calibration key vectors under a given graph key vector. ```cpp theme={null} int32_t gsl_get_graph_ckvs(const struct gsl_key_vector *graph_key_vect, struct gsl_key_vector_list *data_payload) ``` **Parameters** GKV to find CKVs in ACDB for buffer where data will be returned, client is responsible to allocate memory for this buffer. If data\_payload->key\_vector\_list is set to NULL, the size of the output data will be returned in data\_payload->list\_size. **Returns** AR\_EOK in success, error code otherwise ### `gsl_get_driver_module_kvs` Get KVs used by driver module. Queries ACDB for all driver key vectors used by a particular driver module ```cpp theme={null} int32_t gsl_get_driver_module_kvs(uint32_t driver_id, struct gsl_key_vector_list *data_payload) ``` **Parameters** uint32\_t identifying the driver module buffer where data will be returned, client is responsible to allocate memory for this buffer. If data\_payload->key\_vector\_list is set to NULL, the size of the output data will be returned in data\_payload->list\_size. **Returns** AR\_EOK in success, error code otherwise ### `gsl_get_supported_gkvs` Get all GKVs that contain the provided key IDs as a subset. Queries ACDB for all graph key vectors that contain the provided key ids as a subset. A graph key vector supports certain capabiliies if it matches the key id subset. If the subset contains zero keys, this api will return all the graph key vectors defined in ACDB. ```cpp theme={null} int32_t gsl_get_supported_gkvs(uint32_t *key_ids, const uint32_t num_key_ids, struct gsl_key_vector_list *data_payload) ``` **Parameters** pointer to the set of key IDs to query. Client-managed number of entries in key\_ids buffer where data will be returned, client is responsible to allocate memory for this buffer. If data\_payload->key\_vector\_list is set to NULL, the size of the output data will be returned in data\_payload->list\_size. **Returns** AR\_EOK in success, error code otherwise ### `gsl_get_graph_alias` get human-readable alias for a GKV Retrieves an alias of the graph key vector for readability. The alias includes the the usecase ID followed by a human readable graph key vector with names for keys and values. The string length is limited to 255 bytes. API is to be called twice: once to get the size, and once to get the string. ```cpp theme={null} int32_t gsl_get_graph_alias(const struct gsl_key_vector *graph_key_vect, char *alias, uint32_t *alias_len) ``` **Parameters** GKV to find alias for string containing the alias. Client is responsible to allocate memory for this buffer. If this is set to NULL the size of the output data will be returned in alias\_len. The length of the string including the null terminating character. on input it containes the allocated size of alias, on output will have the size actually written **Returns** AR\_EOK in success, error code otherwise ### `gsl_add_database` add acdb database Extends the database by adding database files (\*.acdb and \*.qwsp) at runtime. ```cpp theme={null} int32_t gsl_add_database(struct gsl_acdb_data_files *acdb_data_files, struct gsl_acdb_file *writable_file_path, gsl_acdb_handle_t *acdb_handle) ``` **Parameters** A list of database file paths containing \*.acdb and \*.qwsp The delta data file path and temp files acdb\_handle: A handle to the database provided **Returns** AR\_EOK in success, error code otherwise ### `gsl_remove_database` remove acdb database Shrinks the database by removing all data associated with the given database handle at runtime. This includes database files (\*.qwsp and .acdb) and heap data ```cpp theme={null} int32_t gsl_remove_database(gsl_acdb_handle_t acdb_handle) ``` **Parameters** A handle to the database to remove **Returns** AR\_EOK in success, error code otherwise ### `gsl_cshm_alloc` Allocates shared memory for external clients. Send APM\_CMD\_GLOBAL\_SHARED\_MEM\_MAP\_REGIONS commands to SPF to map allocated memory. ```cpp theme={null} int32_t gsl_cshm_alloc(uint32_t size, gsl_cshm_info_t *info) ``` **Parameters** number of bytes to be allocated info: properties of shared memory to be allocated. fd and mem\_id of allocated memory **Returns** AR\_EOK in success, error code otherwise ### `gsl_cshm_dealloc` Deallocates shared memory for external clients. Send APM\_CMD\_GLOBAL\_SHARED\_MEM\_UNMAP\_REGIONS commands to SPF to unmap memory to be deallocated. ```cpp theme={null} int32_t gsl_cshm_dealloc(gsl_mem_id_t mem_id) ``` **Parameters** identifier to shared memory to be deallocated **Returns** AR\_EOK in success, error code otherwise ### `gsl_cshm_msg` Send notification to module running in SPF w\.r.t particular operation on shared memory block. Operation is opaque to gsl. AR\_SPF\_MSG\_GLOBAL\_SH\_MEM commands to SPF to forwards it to custom module. ```cpp theme={null} int32_t gsl_cshm_msg(gsl_mem_id_t mem_id, uint32_t offset, uint32_t length, uint32_t miid, uint32_t prop_flag) ``` **Parameters** identifier to shared memory to be deallocated Offset (in bytes) from where the chunk of memory starts. This is relative to the beginning of the total shared memory allocated Size of the chunk of memory. Module Instance ID of the module to which this call is intended for. In case of invalid/inactive miid, error is returned. Flags to provide additional information for this call Bit 0 – Release memory Bit used to convey if client wants the module to release/stop using a chunk of previously informed memory. 0 – Default. Not a release message. 1 – Here, if length is zero, module is asked to release entire memory mapped to it with mem\_id. If length is non-zero, the module is asked to release this chunck only. **Returns** AR\_EOK in success, error code otherwise ## Type Definitions ### `gsl_handle_t` opaque handle that is returned to client ```cpp theme={null} typedef void * gsl_handle_t ``` ### `gsl_acdb_handle_t` opaque acdb handle that is returned to client ```cpp theme={null} typedef void * gsl_acdb_handle_t ``` ### `gsl_global_cb_func_ptr` callback used to notify global events to client. ```cpp theme={null} typedef uint32_t(* gsl_global_cb_func_ptr ``` ### `gsl_cb_func_ptr` Callback function signature for events to client. ```cpp theme={null} typedef void(* gsl_cb_func_ptr ``` ### `gsl_mem_id_t` ```cpp theme={null} typedef uint32_t gsl_mem_id_t ``` ### `gsl_cshm_cache_type_t` ```cpp theme={null} typedef enum gsl_cshm_cache_type gsl_cshm_cache_type_t ``` ### `gsl_subsystem_t` ```cpp theme={null} typedef enum gsl_subsystem gsl_subsystem_t ``` ### `gsl_cshm_info_t` ```cpp theme={null} typedef struct gsl_cshm_info gsl_cshm_info_t ``` ## Enumerations ### `gsl_cmd_id` Commands that can be passed to gsl\_ioctl. #### Values | Name | Value | Description | | --------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GSL_CMD_START` | = 0x0 | Start a graph. | | `GSL_CMD_PREPARE` | = 0x1 | Optional, can be called before GSL\_CMD\_START to start initializing modules in the DSP. | | `GSL_CMD_FLUSH` | = 0x3 | Flush a graph, causes graph to drop all unprocessed buffers. | | `GSL_CMD_STOP` | = 0x4 | Stop graph, stop processing data and reset to initial state Optional Payload: struct gsl\_cmd\_properties GRAPH\_STOP is issued only to those subgraphs with matching property\_ID and property\_values. | | `GSL_CMD_ADD_GRAPH` | = 0x5 | Add a new graph to an existing graph based on a new graph key vector. | | `GSL_CMD_REMOVE_GRAPH` | = 0x6 | Remove existing graph based on a graph key vector Payload: struct gsl\_cmd\_remove\_graph. | | `GSL_CMD_CHANGE_GRAPH` | = 0x7 | Modify existing graph based on a new graph key vector Payload: struct gsl\_cmd\_graph\_select. | | `GSL_CMD_QUERY_GRAPH_DELAY` | = 0x8 | Get the path delay associated with a graph. | | `GSL_CMD_CONFIGURE_WRITE_PARAMS` | = 0xA | Configure parameters used for write data exchange Payload: struct gsl\_cmd\_configure\_read\_write\_params. | | `GSL_CMD_CONFIGURE_READ_PARAMS` | = 0xB | Configure parameters used for read data exchange Payload: struct gsl\_cmd\_configure\_read\_write\_params. | | `GSL_CMD_EOS` | = 0xC | Insert EOS marker in playback data stream, the EOS marker is inserted in the stream immediately after all the data successfully written to GSL. | | `GSL_CMD_GET_WRITE_BUFF_INFO` | = 0xD | Get buffer pointers and sizes for use in shared memory mode write operations Payload: struct gsl\_cmd\_get\_shmem\_buf\_info will be sent from client and will get written to by GSL. | | `GSL_CMD_GET_READ_BUFF_INFO` | = 0xE | Get buffer pointers and sizes for use in shared memory mode read operations Payload: struct gsl\_cmd\_get\_shmem\_buf\_info will be sent from client and will get written to by GSL. | | `GSL_CMD_GET_WRITE_POS_BUFF_INFO` | = 0xF | Get pointer and size of position buffer used to synchronize writes in push/pull mode Payload: struct gsl\_cmd\_get\_shmem\_buf\_info will be sent from client and will get written to by GSL. | | `GSL_CMD_GET_READ_POS_BUFF_INFO` | = 0x10 | Get pointer and size of position buffer used to synchronize reads in push/pull mode Payload: struct gsl\_cmd\_get\_shmem\_buf\_info will be sent from client and will get written to by GSL. | | `GSL_CMD_REGISTER_CUSTOM_EVENT` | = 0x11 | Register a custom event with a spf module Payload: struct gsl\_cmd\_register\_custom\_event. | | `GSL_CMD_FREE_READ_BUFF` | = 0x12 | Free all read buffers for a graph. | | `GSL_CMD_FREE_WRITE_BUFF` | = 0x13 | Free all write buffers for a graph. | | `GSL_CMD_SUSPEND` | = 0x14 | Suspend graph, stop processing data but does not reset to initial state If a subgraph is shared with multiple graphs then :-. | | `GSL_CMD_CLOSE_WITH_PROPS` | = 0x15 | Close subset of subgraphs in the graph based on properties Payload: struct gsl\_cmd\_properties GRAPH\_STOP is issued only to those subgraphs with matching property\_ID and property\_values. | | `GSL_CMD_MAX` | | | ### `gsl_event_id` Events that will be notified to client from GSL. #### Values | Name | Value | Description | | --------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GSL_EVENT_ID_EOS` | = 0x0 | End of stream event, indicates that all data written to GSL prior to client calling GSL\_CMD\_EOS has been played out Payload: struct gsl\_event\_eos\_payload. | | `GSL_EVENT_ID_READ_DONE` | = 0x1 | Indicates buffer provided as part of read call has been filled Payload: struct gsl\_event\_read\_write\_done\_payload. | | `GSL_EVENT_ID_WRITE_DONE` | = 0x2 | Indicates buffer provided as part of write has been consumed Payload: struct gsl\_event\_read\_write\_done\_payload. | | `GSL_EVENT_ID_BUFFER_AVAIL` | = 0x3 | Sent in non-blocking mode only, indicates that buffer has become available for client to write to. | | `GSL_EVENT_ID_MAX` | | | ### `gsl_global_event_ids` Global events that can be raised through the global callback. #### Values | Name | Value | Description | | ------------------------------- | ----- | -------------------------------------------------------------------------------------------- | | `GSL_GLOBAL_EVENT_AUDIO_SVC_UP` | | Indicates that an audio service is up, this can happen for example due to restart after SSR. | | `GSL_GLOBAL_EVENT_AUDIO_SVC_DN` | | Indicates that an audio service is down, this can happen for example due to SSR. | | `GSL_GLOBAL_EVENT_MAX` | | | ### `gsl_data_dir` Identifies data direction. #### Values | Name | Value | Description | | -------------------- | ----- | ---------------------------------------------- | | `GSL_DATA_DIR_READ` | | Indicates data is provided from gsl to client. | | `GSL_DATA_DIR_WRITE` | | Indicates data is provided from client to gsl. | ### `gsl_eos_render_status_t` EOS rendered status returned from Spf. #### Values | Name | Value | Description | | ------------------ | ----- | ----------- | | `GSL_EOS_RENDERED` | | | | `GSL_EOS_DROPPED` | | | ### `gsl_cshm_cache_type` #### Values | Name | Value | Description | | ------------------- | ----- | ----------- | | `GSL_CSHM_CACHED` | = 1 | 0 cached. | | `GSL_CSHM_UNCACHED` | | 1 uncached. | ### `gsl_subsystem` #### Values | Name | Value | Description | | -------------------- | ----- | ------------------------------------------------- | | `GSL_SS_INVALID` | = 0 | Invalid sub system. | | `GSL_SS_MODEM_DSP` | = 1 | Used for MODEM DSP sub system. | | `GSL_SS_APPS` | = 2 | Used for APPS sub system. | | `GSL_SS_SENSOR_DSP` | = 3 | Used for SENSOR DSP sub system. | | `GSL_SS_COMPUTE_DSP` | = 4 | Used for COMPUTE DSP sub system. | | `GSL_SS_CC_DSP` | = 5 | Used for Companion chip DSP (CC\_DSP) sub system. | | `GSL_SS_ADSP` | = 6 | Used for ADSP sub system. | ## Macros ### `GSL_MAX_NUM_OF_ACDB_FILES` maximum number of acdb files ```c theme={null} #define GSL_MAX_NUM_OF_ACDB_FILES 20 ``` ### `GSL_MAX_LEN_OF_ACDB_FILENAME` maxumum lengh of filename ```c theme={null} #define GSL_MAX_LEN_OF_ACDB_FILENAME 256 ``` ### `GSL_ATTRIBUTES_DATA_MODE_MASK` keep 3 bits for specifying the data mode ```c theme={null} #define GSL_ATTRIBUTES_DATA_MODE_MASK 0x7 ``` ### `GSL_DATA_MODE_SHMEM` shared memory mode ```c theme={null} #define GSL_DATA_MODE_SHMEM 0x0 ``` ### `GSL_DATA_MODE_BLOCKING` heap memory mode blocking ```c theme={null} #define GSL_DATA_MODE_BLOCKING 0x1 ``` ### `GSL_DATA_MODE_NON_BLOCKING` heap memory mode non-blocking ```c theme={null} #define GSL_DATA_MODE_NON_BLOCKING 0x2 ``` ### `GSL_DATA_MODE_PUSH_PULL` push-pull mode ```c theme={null} #define GSL_DATA_MODE_PUSH_PULL 0x3 ``` ### `GSL_DATA_MODE_EXTERN_MEM` external memory mode ```c theme={null} #define GSL_DATA_MODE_EXTERN_MEM 0x4 ``` ### `GSL_ATTRIBUTES_DATAPATH_SETUP_MASK` shift amount for datapath setup flags ```c theme={null} #define GSL_ATTRIBUTES_DATAPATH_SETUP_MASK 0x18 ``` ### `GSL_ATTRIBUTES_DATAPATH_SETUP_SHIFT` use these flags when it is necessary to separate the allocation of memory buffers from sharing those buffers with DSP Example: opening graph with no GKV and push pull mode, the endpoint IID for the use case is not yet known, so cannot send shmem to DSP. ```c theme={null} #define GSL_ATTRIBUTES_DATAPATH_SETUP_SHIFT 3 ``` ### `GSL_DATAPATH_SETUP_DEFAULT` allocate buffers, do not set up shmem on SPF endpoint ```c theme={null} #define GSL_DATAPATH_SETUP_DEFAULT 0x0 ``` ### `GSL_DATAPATH_SETUP_ALLOC_SHMEM_ONLY` set up shmem on SPF endpoint only GSL ignores other params sent when this flag is used, since the datapath must be configured with ALLOC\_SHMEM\_ONLY before calling with this flag ```c theme={null} #define GSL_DATAPATH_SETUP_ALLOC_SHMEM_ONLY 0x1 ``` ### `GSL_DATAPATH_SETUP_SPF_PROVISION_ONLY` used to indicate a given buffer is the final buffer, client will get notified once the buffer has been rendered ```c theme={null} #define GSL_DATAPATH_SETUP_SPF_PROVISION_ONLY 0x2 ``` ### `GSL_BUFF_FLAG_EOS` true if buffer has a valid timestamp ```c theme={null} #define GSL_BUFF_FLAG_EOS 0x1 ``` ### `GSL_BUFF_FLAG_TS_VALID` used to indicate a buffer is the last in a frame ```c theme={null} #define GSL_BUFF_FLAG_TS_VALID 0x2 ``` ### `GSL_BUFF_FLAG_EOF` used to indicate a buffer is media format, when this flag is set, buffer will contain the media format data only ```c theme={null} #define GSL_BUFF_FLAG_EOF 0x4 ``` ### `GSL_BUFF_FLAG_MEDIA_FORMAT` ```c theme={null} #define GSL_BUFF_FLAG_MEDIA_FORMAT 0x8 ``` ### `GSL_EVENT_SRC_MODULE_ID_GSL` The source module\_id for events originating from GSL and not from Spf. ```c theme={null} #define GSL_EVENT_SRC_MODULE_ID_GSL 0x2001 /* DO NOT CHANGE */ ```