/*
 * Copyright 2020 Google LLC. All Rights Reserved. This file and proprietary
 * source code may only be used and distributed under the Widevine Master
 * License Agreement.
 */

#ifndef ODKITEE_SHARED_MEMORY_INTERFACE_H_
#define ODKITEE_SHARED_MEMORY_INTERFACE_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

/*
 * This is the interface to shared memory that must be implemented in
 * a port for a specific trusted OS. The interface defines functions
 * to allocate, access and free regions of shared memory.
 *
 * Shared memory regions are defined by an address and a size. Regions
 * are allocated by specifying an integer |region_id| that is used to
 * correlate remote and local mappings. When a region is created, the
 * implementation returns an ODK_SharedHandle which is used by callers
 * when accessing the region.
 *
 * Each shared memory implementation defines its own _ODK_SharedHandle
 * struct to hold the data needed to represent a shared memory region.
 */
typedef struct _ODK_SharedHandle ODK_SharedHandle;

/*
 * Shared memory regions are identified with an id that correlates the
 * remote and local mappings.
 */
typedef uint16_t ODK_SharedRegionId;

/*
 * Note that the shared memory implementation must be initialized
 * prior to calling any OEMCrypto API functions because it needs to be
 * available when communicating with the TEE. Typically it would be
 * initialized on service startup.
 */

/*
 * Initialize the shared memory implementation, must be called prior
 * to using any other ODK_SharedMemory functions. This function will
 * be called by the dispatcher on the TEE side at startup. On the REE
 * side it must be called by the service that is calling OEMCrypto
 * because the communication with the TEE needs to be established
 * before any OEMCrypto calls are made.
 */
void ODK_SharedMemory_Initialize(void);

/*
 * Terminate the shared memory implementation, releasing any resources
 * in use.
 */
void ODK_SharedMemory_Terminate(void);

/*
 * Allocate a region of shared memory of |size| bytes. Regions are
 * allocated based on a specified id that is used to correlate remote
 * and local mappings.  The shared memory region must remain mapped
 * until released by ODK_SharedMemory_Free.
 *
 * Parameters:
 *     region_id - identifies the region to allocate
 *     size - the size of the memory region to allocate
 *
 * Returns:
 *     A pointer to an ODK_SharedHandle which refers to the allocated
 *     shared memory, or NULL if allocation fails. The memory for the
 *     handle is owned by the implementation. The handle must remain
 *     valid for as long as the shared memory region is allocated.
 */
ODK_SharedHandle* ODK_SharedMemory_Allocate(ODK_SharedRegionId region_id,
                                            size_t size);

/*
 * Return the address that a shared memory handle is mapped to.
 *
 * Parameters:
 *     handle - the shared handle for which an address is requested
 *
 * Returns:
 *     The address of the shared memory region refered by |handle|
 */
uint8_t* ODK_SharedMemory_GetAddress(ODK_SharedHandle* handle);

/*
 * Return the size of a shared memory region
 *
 * Parameters:
 *     handle - the shared handle for which the region size is requested
 *
 * Returns:
 *     The size of the shared memory region refered by |handle|
 */
size_t ODK_SharedMemory_GetSize(ODK_SharedHandle* handle);

/*
 * Release a handle for a previously allocated region of shared memory.
 * The memory is unmapped and any associated resources are released.
 *
 * Parameters:
 *     address - the address of the shared memory region to release
 */
void ODK_SharedMemory_Free(ODK_SharedHandle* handle);

#ifdef __cplusplus
}  // extern "C"
#endif

#endif //ODKITEE_SHARED_MEMORY_INTERFACE_H_