gsl/api/gsl_intf.h
Structures
gsl_key_value_pair
a single entry in a key vector
Members
uint32_t
key
uint32_t
value
gsl_key_vector
a complete key vector
Members
uint32_t
number of key value pairs
struct gsl_key_value_pair *
vector of key value pairs
gsl_key_vector_array
a key vector with a zero sized array.
Members
uint32_t
number of keys
struct gsl_key_value_pair
array of key value pairs.
gsl_key_vector_list
a key vector list
Members
uint32_t
number of key vectors in the key vector list
uint32_t
list of key vectors in the format of [#keys, kvPair+,…, #keys, kvPair+]
struct gsl_key_vector_array *
gsl_tag_key_vector
a tag key vector with a zero sized array
Members
uint32_t
the module tag identifier
uint32_t
graph key value pair
struct gsl_key_value_pair
gsl_tag_key_vector_list
a tag key vector list
Members
uint32_t
number of key vectors in the key vector list
uint32_t
list of key vectors in the format of [#keys, kvPair+,…, #keys, kvPair+]
struct gsl_tag_key_vector *
gsl_cmd_properties
Command payload for GSL_CMD_STOP ioctl.
Members
struct gsl_key_vector
graph key vector to limit the scope of the operation
uint32_t
property ID of the subgraph(s)
uint32_t
number of values for the subgraph property ID
uint32_t *
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
uint32_t
max number of bytes in a single buffer.
uint32_t
number of buffers GSL will use for data exchange
uint32_t
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.
uint32_t
TBD, currently not supported.
uint32_t
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.
uint32_t
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.
uint32_t
Optional field for passing platform specific data to GSL, this can be used for example to communicate some heap properties to osal layer.
uint32_t
gsl_cmd_graph_select
Cmd payload for GSL_CMD_ADD_GRAPH and GSL_CMD_CHANGE_GRAPH.
Members
struct gsl_key_vector
Used to lookup the new graph.
struct gsl_key_vector
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
struct gsl_key_vector
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
uint8_t *
buffer address
uint64_t
per buffer metadata
gsl_cmd_get_shmem_buf_info
Members
uint32_t
buffer size, all buffers have the same size
uint32_t
number of buffers
struct gsl_shmem_buf *
list of buffs, containts num_buffs entries
gsl_cmd_register_custom_event
Cmd payload for GSL_CMD_REGISTER_CUSTOM_EVENT.
Members
uint32_t
Valid instance ID of module.
uint32_t
Valid event ID of the module.
uint32_t
Size of the event config data based upon the module_instance_id/event_id combination.
uint32_t
1 - to register the event 0 - to de-register the event
uint8_t
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
uint32_t
Full file path name length.
char
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
uint32_t
Number of ACDB files.
struct gsl_acdb_file
Array of ACDB file full paths.
gsl_init_data
Argument for gsl_init.
Members
struct gsl_acdb_data_files *
acdb files to pass to acdb, setting this NULL means acdb_addr will be used to acces the data
struct gsl_acdb_file *
path of acdb delta file
const void *
acdb image address
uint32_t
indicates number of times GSL should check that spf is ready, gsl_init call is blocked until spf is ready.
uint32_t
Amount of time in ms that GSL waits before re-attempting to check Spf readiness.
gsl_extern_alloc_buff_info
Members
uint64_t
unique handle identifying external mem allocation
uint32_t
size in bytes of the allocation
uint32_t
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
uint64_t
timestamp in micro-secs
uint32_t
bitmasked flags for e.g.
uint32_t
size of buffer in bytes
uint8_t *
data buffer.
uint32_t
size of metadata buffer in bytes
uint8_t *
metadata buffer.
struct gsl_extern_alloc_buff_info
extern mem mode info
gsl_module_id_info_entry
Maps the modules instance id to module id for a single module.
Members
uint32_t
module id
uint32_t
globally unique module instance id
gsl_module_id_info
Used to return the module info data to client.
Members
uint32_t
number entries in module list below
struct gsl_module_id_info_entry
module list
gsl_tag_module_info_entry
Structure mapping the tag_id to module info (mid and miid)
Members
uint32_t
tag id of the module
uint32_t
number of modules matching the tag_id
struct gsl_module_id_info_entry
module list
gsl_tag_module_info
Used to return tags and module info data to client given a graph key vector.
Members
uint32_t
number of tags
uint8_t
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
uint32_t
tag that was used to read/write this buffer
uint32_t
data buffer status as defined in ar_osal_error.h
uint32_t
meta-data status as defined in ar_osal_error.h
struct gsl_buff
buffer that was passed to gsl_read/gsl_write
gsl_event_eos_payload
Event payload passed to client with GSL_EVENT_ID_EOS.
Members
uint32_t
module instance id from which the EOS event was raised, Invalid (0) when dropped.
enum gsl_eos_render_status_t
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
uint32_t
Number of graph handles.
gsl_handle_t *
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
uint32_t
identifies the module which generated event
uint32_t
identifies the event, in case of GSL internal events it will hold a value from enum gsl_event_id
uint32_t
size of payload below
void *
payload associated with the event if any
gsl_cshm_info
Members
gsl_cshm_cache_type_t
Cached or uncached memory type.
gsl_subsystem_t
Allows rouing shared memory access across multiple DSPs.
int32_t
Flags for shared memory allocation.
uint64_t
File descriptor for mapped memory region.
gsl_mem_id_t
Unique GSL memory identifier.
Functions
gsl_get_version
Returns the GSL version.
uint32_t *
the major version is incremented whenever the current version is NOT backwards compatible with previous version
uint32_t *
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.
struct gsl_init_data *
data used during initialization
gsl_cshm_init
Initialize GSL cshm, must be called before any other cshm calls.
uint32_t
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()
gsl_deinit
De-initialize GSL, no GSL APIs should be called after this.
gsl_register_global_event_cb
Register a global callback function for GSL.
gsl_global_cb_func_ptr
callback function pointer used to notify global events such as SSR
void *
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.
const struct gsl_key_vector *
used to identify the graph.
const struct gsl_key_vector *
OPTIONAL used to identify calibration data to be sent to the graph, setting to NULL means dont send any calibration
gsl_handle_t *
graph handle on success, null otherwise
gsl_close
Close a graph that was specified using the graph_handle.
gsl_handle_t
Handle of the graph to close
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
gsl_handle_t
graph handle returned from gsl_open
const struct gsl_key_vector *
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().
const struct gsl_key_vector *
used to identify the cal data.
gsl_set_config
Set a configuration payload on a specified graph, the payload is stored in acdb.
gsl_handle_t
graph handle returned from gsl_open
const struct gsl_key_vector *
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.
uint32_t
identifies a capability in acdb
const struct gsl_key_vector *
identifies a payload in the database
gsl_set_custom_config
Set a custom configuration parameter on a specified graph, the payload is provided from the caller.
gsl_handle_t
graph handle returned from gsl_open
const uint8_t *
custom caller defined payload that will get sent to the module, payload structure shall be always according to OOB sturcutre format defined by SPF
const uint32_t
the size of the payload buffer
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.
gsl_handle_t
graph handle returned from gsl_open
uint32_t
identifies a module instance matching the tag ID
const uint8_t *
custom caller defined payload that gets sent to the module, payload structure shall be always according to format defined by SPF
const size_t
the size of the payload buffer
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.
gsl_handle_t
graph handle returned from gsl_open
uint32_t
identifies a module instance matching the tag ID
const uint8_t *
custom caller defined payload that gets sent to the module, payload structure shall be always according to format defined by SPF
const uint32_t
the size of the payload buffer
gsl_get_custom_config
Get the configuration parameter for a specified graph, caller provides a payload.
gsl_handle_t
returned from gsl_open
uint8_t *
Buffer that contains the module ids and param ids along with empty areas that will be filled with parameter data
uint32_t
holds the size of the client buffer passed in for payload. On return will hold actual bytes written.
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
gsl_handle_t
returned from gsl_open
uint32_t
tag used by GSL to lookup the MIDs
uint8_t *
Buffer that contains param ids along with empty areas that will be filled with parameter data
uint32_t *
holds the size of the client buffer passed in for payload. On return will hold actual bytes written.
gsl_ioctl
Send commands to GSL for controlling Graphs in Spf.
gsl_handle_t
graph handle returned from gsl_open
enum gsl_cmd_id
identifies the command
void *
command specific parameters
size_t
size of cmd_payload
gsl_read
Receive data buffers from Spf.
gsl_handle_t
graph handle returned from gsl_open
uint32_t
used to identify the module in Spf to read buffers from
struct gsl_buff *
buffer where data will be copied to
uint32_t *
actual number of bytes filled into the buffer by GSL
gsl_write
Write data buffers to Spf.
gsl_handle_t
graph handle returned from gsl_open
uint32_t
used to identify the module in Spf to write buffers to
struct gsl_buff *
buffer containing data that will be written
uint32_t *
actual number of bytes consumed by GSL
gsl_register_event_cb
Register an event callback function with Spf.
gsl_handle_t
graph handle returned from gsl_open
gsl_cb_func_ptr
pointer to callback function
void *
opaque data that will be passed to client in the callback
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
const struct gsl_key_vector *
graph key vector
uint32_t
used to identify a certain capability
struct gsl_key_vector *
tag key vector used to identify a specific payload in acdb
uint8_t *
pointer to a buffer where the payload will be copied to
size_t *
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.
gsl_get_tagged_module_info
Query database for module_iid to module_id mapping data.
const struct gsl_key_vector *
graph key vector
uint32_t
identifies a set of modules in ACDB that were tagged with with this tag by system designer
struct gsl_module_id_info **
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.
uint32_t *
holds the size of the data written to the module_info buffer
gsl_get_tags_with_module_info
Query database for all tags and corresponding module_iid and module_id mapping given a graph key vector.
const struct gsl_key_vector *
graph key vector
void *
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”
size_t *
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
gsl_enable_acdb_persistence
enable persistence for cals set to ACDB
uint8_t
1 means enable, 0 is disable
gsl_set_cal_data_to_acdb
Store custom calibration to ACDB.
const struct gsl_key_vector *
graph key vector
const struct gsl_key_vector *
tag key vector used to identify an entry in acdb
uint8_t *
pointer to a buffer containing custom calibration
uint32_t
holds the size of the client buffer passed in for payload
gsl_get_cal_data_from_acdb
Retrieve custom calibration from ACDB.
const struct gsl_key_vector *
graph key vector
const struct gsl_key_vector *
tag key vector used to identify an entry in acdb
uint32_t
The number of module instances in the param_list
uint8_t *
List of module instances plus their parameters to get data for
void *
pointer to a buffer of returned payload_size to hold returned calibration
uint32_t *
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
gsl_set_tag_data_to_acdb
Store custom tag to ACDB.
const struct gsl_key_vector *
graph key vector
uint32_t
tag ID to be set
const struct gsl_key_vector *
tag key vector used to identify an entry in acdb
uint8_t *
pointer to a buffer containing custom tag data
uint32_t
holds the size of the client buffer passed in for payload
gsl_get_tag_data_from_acdb
Retrieve custom tag from ACDB.
const struct gsl_key_vector *
graph key vector
uint32_t
tag ID for data to retrieve
const struct gsl_key_vector *
tag key vector used to identify an entry in acdb
uint32_t
The number of module instances in the param_list
uint8_t *
List of module instances plus their parameters to get data for
void *
pointer to a buffer of returned payload_size to hold returned tag data
uint32_t *
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
gsl_set_temp_path_to_acdb
Updates the read/write temporary path that AML uses for the reinit/delta persistence functionality.
Command ID is ACDB_CMD_SET_TEMP_PATH.
a null terminated char array of under 255 chars
- 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.
gsl_handle_t
graph handle
enum gsl_data_dir
indicates whether to return the write or read buffer counts
uint32_t *
An ever increasing count of buffers, the number wraps back to zero once it reaches SIZE_MAX
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.
gsl_handle_t
graph handle
enum gsl_data_dir
indicates whether to return write or read available buffer size
uint32_t *
buffer size (in bytes) ready to be written (playback) / read (capture)
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
const uint32_t
client defined module_id against which data is stored in acdb
const struct gsl_key_vector *
OPTIONAL key vector used to look up data
void *
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
uint32_t *
on input it containes the size of data_payload, on output will have the size actually written
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
const struct gsl_key_vector *
GKV to find tag & TKV pairs in ACDB for
struct gsl_tag_key_vector_list *
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.
gsl_get_graph_ckvs
Get all CKVs for given GKV.
Queries for all SPF module calibration key vectors under a given graph key vector.
const struct gsl_key_vector *
GKV to find CKVs in ACDB for
struct gsl_key_vector_list *
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.
gsl_get_driver_module_kvs
Get KVs used by driver module.
Queries ACDB for all driver key vectors used by a particular driver module
uint32_t
uint32_t identifying the driver module
struct gsl_key_vector_list *
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.
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.
uint32_t *
pointer to the set of key IDs to query. Client-managed
const uint32_t
number of entries in key_ids
struct gsl_key_vector_list *
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.
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.
const struct gsl_key_vector *
GKV to find alias for
char *
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.
uint32_t *
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
gsl_add_database
add acdb database
Extends the database by adding database files (*.acdb and *.qwsp) at runtime.
struct gsl_acdb_data_files *
A list of database file paths containing *.acdb and *.qwsp
struct gsl_acdb_file *
The delta data file path and temp files
acdb_handle: A handle to the database provided
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
gsl_acdb_handle_t
A handle to the database to remove
gsl_cshm_alloc
Allocates shared memory for external clients.
Send APM_CMD_GLOBAL_SHARED_MEM_MAP_REGIONS commands to SPF to map allocated memory.
uint32_t
number of bytes to be allocated
info: properties of shared memory to be allocated. fd and mem_id of allocated memory
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.
gsl_mem_id_t
identifier to shared memory to be deallocated
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.
gsl_mem_id_t
identifier to shared memory to be deallocated
uint32_t
Offset (in bytes) from where the chunk of memory starts. This is relative to the beginning of the total shared memory allocated
uint32_t
Size of the chunk of memory.
uint32_t
Module Instance ID of the module to which this call is intended for. In case of invalid/inactive miid, error is returned.
uint32_t
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.