Generic Packet Router (GPR) APIs

Public APIs

This file contains GPR APIs.

Copyright (c) Qualcomm Innovation Center, Inc. All rights reserved. SPDX-License-Identifier: BSD-3-Clause

Defines

GPR_HEAP_INDEX_DEFAULT

GPR_HEAP_INDEX_1

Typedefs

typedef uint8_t gpr_heap_index_t

typedef uint32_t (*gpr_callback_fn_t)(gpr_packet_t *packet, void *callback_data)

Prototype of a packet callback function.

Associated data types

#gpr_packet_t

Otherwise, an error (see) — The packet ownership is returned to the caller.

Param packet:

[in] Pointer to the incoming packet. The packet is guaranteed to have a non-NULL value.

Param callback_data:

[in] Client-supplied data pointer that the service provided at registration time.

Return:

#AR_EOK — When successful, indicates that the callee has taken ownership of the packet.

typedef struct gpr_packet_pool_info_v2_t gpr_packet_pool_info_v2_t

typedef struct gpr_cmd_gpr_packet_pool_info_t gpr_cmd_gpr_packet_pool_info_t

typedef struct gpr_cmd_alloc_ext_v2_t gpr_cmd_alloc_ext_v2_t

Functions

GPR_EXTERNAL uint32_t gpr_init (void)

Performs external initialization of the GPR infrastructure.

Each supported domain calls this function once during system bring-up or during runtime to initialize the GPR infrastructure for that domain. The GPR infrastructure must be initialized before any other GPR APIs can be called.

#include “gpr_api.h”

Dependencies

None.

int32_t rc = gpr_init(); if ( rc ) { printf( “Could not initialize the GPR infrastructure” ); }

Returns:

#AR_EOK — When successful.

GPR_EXTERNAL uint32_t gpr_init_domain (uint32_t domain_id)

To initialize GPR with particular domain.

Dependencies

None.

Returns:

#AR_EOK — When successful.

GPR_EXTERNAL uint32_t gpr_deinit (void)

Performs external deinitialization of the GPR infrastructure.

Each supported domain calls this function once during system shutdown or during runtime to deinitialize the GPR infrastructure for that domain. No functions except for gpr_init() can be called after the GPR infrastructure is deinitialized.

#include “gpr_api.h”

Dependencies

None.

int32_t rc = gpr_deinit(); if ( rc ) { printf( “Could not deinitialize the GPR infrastructure” ); }

Returns:

#AR_EOK — When successful.

struct gpr_packet_pool_info_v2_t

#include <gpr_api.h>

Public Members

gpr_heap_index_t heap_index

uint8_t is_dynamic

uint16_t reserved

uint32_t num_packets

uint32_t packet_size

struct gpr_cmd_gpr_packet_pool_info_t

#include <gpr_api.h>

Contains the packet pool information for __gpr_cmd_get_gpr_packet_info().

Public Members

uint32_t bytes_per_min_size_packet

Minimum size (in bytes) of a GPR packet.

uint32_t num_min_size_packets

Number of packets of the minimum size allocated at initialization.

uint32_t bytes_per_max_size_packet

Maximum size (in bytes) of a GPR packet.

uint32_t num_max_size_packets

Number of packets of the maximum size allocated at initialization.

struct gpr_cmd_alloc_ext_t

#include <gpr_api.h>

Contains the allocated packet information for __gpr_cmd_alloc_ext().

Public Members

uint8_t src_domain_id

Domain ID of the sender service.

uint32_t src_port

Registered unique ID of the sender service.

uint8_t dst_domain_id

Domain ID of the receiver service.

uint32_t dst_port

Registered unique ID of the receiver service.

uint8_t client_data

Reserved for use by client.

uint32_t token

Value attached by the sender to determine when command messages are processed by the receiver after they receive response messages.

uint32_t opcode

Defines both the action and the payload structure to the receiver.

uint32_t payload_size

Actual number of bytes required for the payload.

gpr_packet_t **ret_packet

Double pointer to the formatted packet returned by the function.

struct gpr_cmd_alloc_ext_v2_t

#include <gpr_api.h>

Contains the allocated packet information for __gpr_cmd_alloc_ext_v2().

Public Members

uint8_t src_domain_id

Domain ID of the sender service.

uint32_t src_port

Registered unique ID of the sender service.

uint8_t dst_domain_id

Domain ID of the receiver service.

uint32_t dst_port

Registered unique ID of the receiver service.

uint8_t client_data

Reserved for use by client.

uint32_t token

Value attached by the sender to determine when command messages are processed by the receiver after they receive response messages.

gpr_heap_index_t heap_index

heap index of the packet pool. ‘0’ is default value. Must be set to 0 if not applicable.

uint32_t opcode

Defines both the action and the payload structure to the receiver.

uint32_t payload_size

Actual number of bytes required for the payload.

gpr_packet_t **ret_packet

Double pointer to the formatted packet returned by the function.

struct gpr_cmd_alloc_send_t

#include <gpr_api.h>

Contains the allocated packet information for __gpr_cmd_alloc_send().

Public Members

uint8_t src_domain_id

Domain ID of the sender service.

uint32_t src_port

Registered unique ID of the sender service.

uint8_t dst_domain_id

Domain ID of the receiver service.

uint32_t dst_port

Registered unique ID of the receiver service.

uint8_t client_data

Reserved for use by the client.

uint32_t token

Value attached by the sender to determine when command messages have been processed by the receiver after having received response messages.

uint32_t opcode

Operation code defines both the action and the payload structure to the receiver.

uint32_t payload_size

Actual number of bytes needed for the payload.

void *payload

Pointer to the payload to send.

Datalink APIs

This file contains IPC APIs.

Copyright (c) Qualcomm Innovation Center, Inc. All rights reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef struct gpr_to_ipc_vtbl_t gpr_to_ipc_vtbl_t

typedef struct ipc_to_gpr_vtbl_t ipc_to_gpr_vtbl_t

typedef uint32_t (*ipc_dl_init_fn_t)(uint32_t src_domain_id, uint32_t dest_domain_id, const gpr_to_ipc_vtbl_t *p_gpr_to_ipc_vtbl, ipc_to_gpr_vtbl_t **pp_ipc_to_gpr_vtbl)

Initializes a data link or IPC layer that communicates between two domains.

#include “ipc_dl_api.h”

Associated data types

gpr_to_ipc_vtbl_t ipc_to_gpr_vtbl_t

Detailed description

This function is called for each data link layer during GPR initialization. It sets up all the necessary function handlers to receive and send packets in the GPR and data link layers.

The GPR registers callback functions to each data link layer, and in turn, a data link layer registers its callback functions with the GPR.

Dependencies

None.

Example of initializing a datalink layer to communicate between two domains - ADSP and APPS.

Datalink layer entry point function. GPR_EXTERNAL uint32_t ipc_datalink_init(uint32_t src_domain_id, uint32_t dest_domain_id, const gpr_to_ipc_vtbl_t *p_gpr_to_ipc_vtbl, ipc_to_gpr_vtbl_t ** pp_ipc_to_gpr_vtbl);

Functions are defined in gpr. static gpr_to_ipc_vtbl_t gpr_to_datalink_vtbl = {gpr_receive, gpr_send_done, };

Functions are defined inside the datalink layer and to be populated and sent back to gpr in the ipc_datalink_init function. static ipc_to_gpr_vtbl_t datalink_layer_to_gpr_vtbl = {datalink_send, datalink_receive_done, };

int main() { uint32_t src_domain_id = GPR_IDS_DOMAIN_ID_ADSP_V; uin32_t dest_domain_id = GPR_IDS_DOMAIN_ID_APPS_V;

rc = ipc_datalink_init(src_domain_id, dest_domain_id, &gpr_to_datalink_vtbl, &datalink_layer_to_gpr_vtbl); if (rc) { AR_MSG(DBG_ERROR_PRIO, “Initialization failed for destination domain id %lu”, dest_domain_id); } return rc; }

Param src_domain_id:

[in] Domain ID of the source.

Param dest_domain_id:

[in] Domain ID of the destination with which the given src_domain_id is to establish communication.

Param p_gpr_to_ipc_vtbl:

[in] Pointer to the function table that contains the callback functions the GPR provides to each IPC data link layer during initialization. This function table argument is defined as a constant because the same GPR callback functions are sent to each data link layer.

Param pp_ipc_to_gpr_vtbl:

[out] Double pointer to the function table that contains the functions each IPC data link layer provides to the GPR. It is populated by each data link during initialization.

Return:

#AR_EOK — When successful.

typedef uint32_t (*ipc_dl_deinit_fn_t)(uint32_t src_domain_id, uint32_t dest_domain_id)

Deinitializes a data link or IPC layer that was set up to communicate between two domains.

#include “ipc_dl_api.h”

Detailed description

This function is called for each data link layer during GPR deinitialization.

Dependencies

None.

Example of deinitializing a datalink layer to close communication between two domains - ADSP and APPS.

GPR_EXTERNAL uint32_t ipc_datalink_deinit (uint32_t src_domain_id, uint32_t dest_domain_id);

int main() { uint32_t src_domain_id = GPR_IDS_DOMAIN_ID_ADSP_V; uin32_t dest_domain_id = GPR_IDS_DOMAIN_ID_APPS_V;

rc = ipc_datalink_deinit(src_domain_id,dest_domain_id); if (rc) { AR_MSG(DBG_ERROR_PRIO, “Deinitialization failed for destination domain id %lu”, dest_domain_id); } return rc; }

Param src_domain_id:

[in] Domain ID of the source.

Param dest_domain_id:

[in] Domain ID of the destination with which the src_domain_id must close communication.

Return:

#AR_EOK — When successful.

struct gpr_to_ipc_vtbl_t

#include <ipc_dl_api.h>

Table of callback functions exposed by the GPR to the IPC data link layers. The GPR sends this table to the data link layers during data link layer initialization.

Public Members

uint32_t (*receive)(void *buf, uint32_t length)

Prototype of the receive() callback function for the GPR.

Detailed description

When the data link layer receives a packet, it calls this GPR function to handle and route the packet to its final destination.

Dependencies

None.

Param buf:

[in] Pointer to the packet.

Param length:

[in] Size of the packet.

Return:

#AR_EOK — When successful.

uint32_t (*send_done)(void *buf, uint32_t length)

Prototype of the send_done() callback function for the GPR.

Detailed description

When the data link layer finishes sending a packet, it uses this function to signal the GPR to free the packet.

Dependencies

None.

Param buf:

[in] Pointer to the packet.

Param length:

[in] Size of the packet.

Return:

#AR_EOK — When successful.

struct ipc_to_gpr_vtbl_t

#include <ipc_dl_api.h>

Table of functions exposed by data link layers to the GPR. The functions must be populated by every data link layer when gpr_init() calls for data link layer initialization.

Public Members

uint32_t (*send)(uint32_t domain_id, void *buf, uint32_t length)

Prototype of the send() function for a data link layer.

Detailed description

When the GPR sends a packet to a destination domain, it calls this function of the corresponding data link layer.

Dependencies

None.

Param domain_id:

[in] ID of the domain to which packet is being sent.

Param buf:

[in] Pointer to the packet.

Param length:

[in] Size of the packet.

Return:

#AR_EOK — When successful.

uint32_t (*receive_done)(uint32_t domain_id, void *buf)

Prototype of the receive_done() function for a data link layer.

Detailed description

When the GPR finishes processing a packet it received from the data link layer, it returns the packet to the data link layer for it to free the buffer.

Dependencies

None.

Param domain_id:

[in] ID of the domain from which packet was sent.

Param buf:

[in] Pointer to the packet.

Return:

#AR_EOK — When successful.