First Publicly Shared Version of ODKiTEE v15

serialization/shared_memory_interface.h

@@ -0,0 +1,117 @@
+/*
+ * 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_