Gen TEE Driver SHM suballocator APIs

from linux/tee_drv.h (in optee branch until Gen Tee Driver is in upstream):

1. Jens has done a good job to encapsulate "tee_shm" class.
2. The public header is the linux/tee_drv.h, but the private interface is in drivers/tee/tee_private.h:
   

   /**
    * struct tee_shm - shared memory object
    * @teedev: device used to allocate the object
    * @ctx:    context using the object, if NULL the context is gone
    * @link    link element to traverse list of shm objects in a ctx
    * @paddr:  physical address of the shared memory
    * @kaddr:  virtual address of the shared memory
    * @size:   size of shared memory
    * @dmabuf: dmabuf used to for exporting to user space
    * @flags:  defined by TEE_SHM_* in tee_drv.h
    * @id:     unique id of a shared memory object on this device
    */
   struct tee_shm {
       struct tee_device *teedev;
       struct tee_context *ctx;
       struct list_head link;
       phys_addr_t paddr;
       void *kaddr;
       size_t size;
       struct dma_buf *dmabuf;
       u32 flags;
       int id;
   };
   

3. Public API is defined as follows:

 /**
 * struct tee_shm_pool_mem_info - holds information needed to create a shared
 * memory pool
 * @vaddr:      Virtual address of start of pool
 * @paddr:      Physical address of start of pool
 * @size:       Size in bytes of the pool
 */
struct tee_shm_pool_mem_info {
        unsigned long vaddr;
        phys_addr_t paddr;
        size_t size;
};

/**
 * tee_shm_pool_alloc_res_mem() - Create a shared memory pool from reserved
 * memory range
 * @dev:         Device allocating the pool
 * @priv_info:   Information for driver private shared memory pool
 * @dmabuf_info: Information for dma-buf shared memory pool
 *
 * Start and end of pools will must be page aligned.
 *
 * Allocation with the flag TEE_SHM_DMA_BUF set will use the range supplied
 * in @dmabuf, others will use the range provided by @priv.
 *
 * @returns pointer to a 'struct tee_shm_pool' or an ERR_PTR on failure.
 */
struct tee_shm_pool *
tee_shm_pool_alloc_res_mem(struct device *dev,
                           struct tee_shm_pool_mem_info *priv_info,
                           struct tee_shm_pool_mem_info *dmabuf_info);

 /**
 * tee_shm_pool_free() - Free a shared memory pool
 * @pool:       The shared memory pool to free
 *
 * There must be no remaining shared memory allocated from this pool when
 * this function is called.
 */
void tee_shm_pool_free(struct tee_shm_pool *pool);

 /**
 * tee_shm_alloc() - Allocate shared memory
 * @ctx:        Context that allocates the shared memory
 * @size:       Requested size of shared memory
 * @flags:      Flags setting properties for the requested shared memory.
 *
 * Memory allocated as global shared memory is automatically freed when the
 * TEE file pointer is closed. The @flags field uses the bits defined by
 * TEE_SHM_* above. TEE_SHM_MAPPED must currently always be set. If
 * TEE_SHM_DMA_BUF global shared memory will be allocated and associated
 * with a dma-buf handle, else driver private memory.
 *
 * @returns a pointer to 'struct tee_shm'
 */
struct tee_shm *

      tee_shm_alloc(struct tee_context *ctx, size_t size, u32 flags);

/**
 * tee_shm_free() - Free shared memory
 * @shm:        Handle to shared memory to free
 */
void tee_shm_free(struct tee_shm *shm);

/**
 * tee_shm_put() - Decrease reference count on a shared memory handle
 * @shm:        Shared memory handle
 */
void tee_shm_put(struct tee_shm *shm);

/**
 * tee_shm_va2pa() - Get physical address of a virtual address
 * @shm:        Shared memory handle
 * @va:         Virtual address to tranlsate
 * @pa:         Returned physical address
 * @returns 0 on success and < 0 on failure
 */
int tee_shm_va2pa(struct tee_shm *shm, void *va, phys_addr_t *pa);

/**
 * tee_shm_pa2va() - Get virtual address of a physical address
 * @shm:        Shared memory handle
 * @pa:         Physical address to tranlsate
 * @va:         Returned virtual address
 * @returns 0 on success and < 0 on failure
 */
int tee_shm_pa2va(struct tee_shm *shm, phys_addr_t pa, void **va);

/**
 * tee_shm_get_va() - Get virtual address of a shared memory plus an offset
 * @shm:        Shared memory handle
 * @offs:       Offset from start of this shared memory
 * @returns virtual address of the shared memory + offs if offs is within
 *      the bounds of this shared memory, else an ERR_PTR
 */
void *tee_shm_get_va(struct tee_shm *shm, size_t offs);

/**
 * tee_shm_get_pa() - Get physical address of a shared memory plus an offset
 * @shm:        Shared memory handle
 * @offs:       Offset from start of this shared memory
 * @pa:         Physical address to return
 * @returns 0 if offs is within the bounds of this shared memory, else an
 *      error code.
 */
int tee_shm_get_pa(struct tee_shm *shm, size_t offs, phys_addr_t *pa);

/**
 * tee_shm_get_id() - Get id of a shared memory object
 * @shm:        Shared memory handle
 * @returns id
 */
int tee_shm_get_id(struct tee_shm *shm);

/**
 * tee_shm_get_from_id() - Find shared memory object and increase referece count
 * @ctx:        Context owning the shared memory
 * @id:         Id of shared memory object
 * @returns a pointer to 'struct tee_shm' on success or an ERR_PTR on failure
 */
struct tee_shm *tee_shm_get_from_id(struct tee_context *ctx, int id);