libteec: implement OCALL support during function invocation

OCALLs allow a TA to invoke functions on their CA with parameters, if
desired.

The flow begins when a CA calls TEEC_InvokeFunction. If the TEE context was
initialized with the OCALL setting, libteec includes an additional
parameter, the OCALL parameter, in the function invocation IOCTL. The
presence of the OCALL parameter lets the kernel driver know that an OCALL
may result from the invocation.

If an OCALL does arrive from the TA, the OCALL parameter includes
information about the OCALL, including the ID of the function that libteec
must handle. These are: allocate shared memory, free shared memory, and
invoke a function on the CA.

If either of the first two functions arrive at libteec, the library handles
these on behalf of the CA, allocating and freeing shared memory as
necessary.

When the third function arrives, libteec processes the OCALL's parameters.
These will have temporarily replaced the parameters of the original
function invocation. Additionally, the 'func' element of the IOCTL
parameters will have been modified to carry the command ID that the TA
requests that the CA execute on its behalf.

The library passes this ID along with the parameters and arbitrary data
pointers configured via the settings API to the CA-provided OCALL handler.

After the handler is finished processing the request, libteec performs
minor post-processing on the parameters and calls back into the driver to
let it know that the OCALL has been handled.

It is possible for a TA to invoke multiple OCALLs in the same originating
function invocation.

Signed-off-by: Hernan Gatta <hegatta@microsoft.com>

libteec/include/linux/tee.h

@@ -45,6 +45,7 @@
 /* Flags relating to shared memory */
 #define TEE_IOCTL_SHM_MAPPED	0x1	/* memory mapped in normal world */
 #define TEE_IOCTL_SHM_DMA_BUF	0x2	/* dma-buf handle on shared memory */
+#define TEE_IOCTL_SHM_OCALL	0x4	/* memory used for an OCALL */
 
 #define TEE_MAX_ARG_SIZE	1024
 
@@ -168,9 +169,14 @@ struct tee_ioctl_shm_register_fd_data {
 /* Meta parameter carrying extra information about the message. */
 #define TEE_IOCTL_PARAM_ATTR_META		0x100
 
+/* Parameter carrying information about an OCALL reply or request. */
+#define TEE_IOCTL_PARAM_ATTR_OCALL		0x200
+
 /* Mask of all known attr bits */
 #define TEE_IOCTL_PARAM_ATTR_MASK \
-	(TEE_IOCTL_PARAM_ATTR_TYPE_MASK | TEE_IOCTL_PARAM_ATTR_META)
+	(TEE_IOCTL_PARAM_ATTR_TYPE_MASK | \
+	 TEE_IOCTL_PARAM_ATTR_META      | \
+	 TEE_IOCTL_PARAM_ATTR_OCALL)
 
 /*
  * Matches TEEC_LOGIN_* in GP TEE Client API
@@ -244,6 +250,54 @@ struct tee_ioctl_open_session_arg {
 #define TEE_IOC_OPEN_SESSION	_IOR(TEE_IOC_MAGIC, TEE_IOC_BASE + 2, \
 				     struct tee_ioctl_buf_data)
 
+/*
+ * Command sent to the CA to request allocation of shared memory to carry the
+ * parameters of an OCALL
+ *
+ * [in]  param[0].u.value.b		requested memory size
+ * [out] param[0].u.value.c		SHM ID
+ *
+ * Note: [in] means from driver to CA, [out], from CA to driver.
+ */
+#define TEE_IOCTL_OCALL_CMD_SHM_ALLOC	1
+
+/*
+ * Command sent to the CA to free previously allocated shared memory.
+ *
+ * [in] param[0].u.value.c		SHM ID
+ *
+ * Note: [in] means from driver to CA.
+ */
+#define TEE_IOCTL_OCALL_CMD_SHM_FREE	2
+
+/*
+ * Command sent to the CA to execute an OCALL by Id.
+ *
+ * [any] param[0..3].u.*		carry OCALL parameters
+ */
+#define TEE_IOCTL_OCALL_CMD_INVOKE	3
+
+/*
+ * Join the Id of the function that the TEE Client API must execute on behalf of
+ * the CA with the Id of the command that the CA must execute
+ *
+ * As an example, TEE_IOCTL_OCALL_MAKE_PAIR(TEE_IOCTL_OCALL_CMD_INVOKE, 10)
+ * means that the Client API must forward a function invocation to a CA-provided
+ * handler, and the handler must execute command Id '10', whose meaning is up to
+ * the user-defined contract between the CA & TA.
+ */
+#define TEE_IOCTL_OCALL_MAKE_PAIR(func, cmd)	\
+	(((__u64)(func) << 32) | (__u32)(cmd))
+
+/*
+ * Get the Id of the function that the TEE Client API must execute on behalf of
+ * the CA
+ */
+#define TEE_IOCTL_OCALL_GET_FUNC(x)		((__u32)((x) >> 32))
+
+/* Get the Id of the command that the CA must execute */
+#define TEE_IOCTL_OCALL_GET_CMD(x)		((__u32)(x))
+
 /**
  * struct tee_ioctl_invoke_func_arg - Invokes a function in a Trusted
  * Application