qcomtee_object.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2/*
  3 * Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
  4 */
  5
  6#ifndef QCOMTEE_OBJECT_H
  7#define QCOMTEE_OBJECT_H
  8
  9#include <linux/completion.h>
 10#include <linux/kref.h>
 11#include <linux/slab.h>
 12#include <linux/workqueue.h>
 13
 14struct qcomtee_object;
 15
 16/**
 17 * DOC: Overview
 18 *
 19 * qcomtee_object provides object refcounting, ID allocation for objects hosted
 20 * in the kernel, and necessary message marshaling for Qualcomm TEE (QTEE).
 21 *
 22 * To invoke an object in QTEE, the user calls qcomtee_object_do_invoke()
 23 * while passing an instance of &struct qcomtee_object and the requested
 24 * operation + arguments.
 25 *
 26 * After boot, QTEE provides a static object %ROOT_QCOMTEE_OBJECT (type of
 27 * %QCOMTEE_OBJECT_TYPE_ROOT). The root object is invoked to pass the user's
 28 * credentials and obtain other instances of &struct qcomtee_object (type of
 29 * %QCOMTEE_OBJECT_TYPE_TEE) that represent services and TAs in QTEE;
 30 * see &enum qcomtee_object_type.
 31 *
 32 * The objects received from QTEE are refcounted. So the owner of these objects
 33 * can issue qcomtee_object_get() to increase the refcount and pass objects
 34 * to other clients, or issue qcomtee_object_put() to decrease the refcount
 35 * and release the resources in QTEE.
 36 *
 37 * The kernel can host services accessible to QTEE. A driver should embed
 38 * an instance of &struct qcomtee_object in the struct it wants to export to
 39 * QTEE (this is called a callback object). It issues qcomtee_object_user_init()
 40 * to set the dispatch() operation for the callback object and set its type
 41 * to %QCOMTEE_OBJECT_TYPE_CB.
 42 *
 43 * core.c holds an object table for callback objects. An object ID is assigned
 44 * to each callback object, which is an index to the object table. QTEE uses
 45 * these IDs to reference or invoke callback objects.
 46 *
 47 * If QTEE invokes a callback object in the kernel, the dispatch() operation is
 48 * called in the context of the thread that originally called
 49 * qcomtee_object_do_invoke().
 50 */
 51
 52/**
 53 * enum qcomtee_object_type - Object types.
 54 * @QCOMTEE_OBJECT_TYPE_TEE: object hosted on QTEE.
 55 * @QCOMTEE_OBJECT_TYPE_CB: object hosted on kernel.
 56 * @QCOMTEE_OBJECT_TYPE_ROOT: 'primordial' object.
 57 * @QCOMTEE_OBJECT_TYPE_NULL: NULL object.
 58 *
 59 * The primordial object is used for bootstrapping the IPC connection between
 60 * the kernel and QTEE. It is invoked by the kernel when it wants to get a
 61 * 'client env'.
 62 */
 63enum qcomtee_object_type {
 64	QCOMTEE_OBJECT_TYPE_TEE,
 65	QCOMTEE_OBJECT_TYPE_CB,
 66	QCOMTEE_OBJECT_TYPE_ROOT,
 67	QCOMTEE_OBJECT_TYPE_NULL,
 68};
 69
 70/**
 71 * enum qcomtee_arg_type - Type of QTEE argument.
 72 * @QCOMTEE_ARG_TYPE_INV: invalid type.
 73 * @QCOMTEE_ARG_TYPE_OB: output buffer (OB).
 74 * @QCOMTEE_ARG_TYPE_OO: output object (OO).
 75 * @QCOMTEE_ARG_TYPE_IB: input buffer (IB).
 76 * @QCOMTEE_ARG_TYPE_IO: input object (IO).
 77 *
 78 * Use the invalid type to specify the end of the argument array.
 79 */
 80enum qcomtee_arg_type {
 81	QCOMTEE_ARG_TYPE_INV = 0,
 82	QCOMTEE_ARG_TYPE_OB,
 83	QCOMTEE_ARG_TYPE_OO,
 84	QCOMTEE_ARG_TYPE_IB,
 85	QCOMTEE_ARG_TYPE_IO,
 86	QCOMTEE_ARG_TYPE_NR,
 87};
 88
 89/**
 90 * define QCOMTEE_ARGS_PER_TYPE - Maximum arguments of a specific type.
 91 *
 92 * The QTEE transport protocol limits the maximum number of arguments of
 93 * a specific type (i.e., IB, OB, IO, and OO).
 94 */
 95#define QCOMTEE_ARGS_PER_TYPE 16
 96
 97/* Maximum arguments that can fit in a QTEE message, ignoring the type. */
 98#define QCOMTEE_ARGS_MAX (QCOMTEE_ARGS_PER_TYPE * (QCOMTEE_ARG_TYPE_NR - 1))
 99
100struct qcomtee_buffer {
101	union {
102		void *addr;
103		void __user *uaddr;
104	};
105	size_t size;
106};
107
108/**
109 * struct qcomtee_arg - Argument for QTEE object invocation.
110 * @type: type of argument as &enum qcomtee_arg_type.
111 * @flags: extra flags.
112 * @b: address and size if the type of argument is a buffer.
113 * @o: object instance if the type of argument is an object.
114 *
115 * &qcomtee_arg.flags only accepts %QCOMTEE_ARG_FLAGS_UADDR for now, which
116 * states that &qcomtee_arg.b contains a userspace address in uaddr.
117 */
118struct qcomtee_arg {
119	enum qcomtee_arg_type type;
120/* 'b.uaddr' holds a __user address. */
121#define QCOMTEE_ARG_FLAGS_UADDR BIT(0)
122	unsigned int flags;
123	union {
124		struct qcomtee_buffer b;
125		struct qcomtee_object *o;
126	};
127};
128
129static inline int qcomtee_args_len(struct qcomtee_arg *args)
130{
131	int i = 0;
132
133	while (args[i].type != QCOMTEE_ARG_TYPE_INV)
134		i++;
135	return i;
136}
137
138/* Context is busy (callback is in progress). */
139#define QCOMTEE_OIC_FLAG_BUSY BIT(1)
140/* Context needs to notify the current object. */
141#define QCOMTEE_OIC_FLAG_NOTIFY BIT(2)
142/* Context has shared state with QTEE. */
143#define QCOMTEE_OIC_FLAG_SHARED BIT(3)
144
145/**
146 * struct qcomtee_object_invoke_ctx - QTEE context for object invocation.
147 * @ctx: TEE context for this invocation.
148 * @flags: flags for the invocation context.
149 * @errno: error code for the invocation.
150 * @object: current object invoked in this callback context.
151 * @u: array of arguments for the current invocation (+1 for ending arg).
152 * @in_msg: inbound buffer shared with QTEE.
153 * @out_msg: outbound buffer shared with QTEE.
154 * @in_shm: TEE shm allocated for inbound buffer.
155 * @out_shm: TEE shm allocated for outbound buffer.
156 * @data: extra data attached to this context.
157 */
158struct qcomtee_object_invoke_ctx {
159	struct tee_context *ctx;
160	unsigned long flags;
161	int errno;
162
163	struct qcomtee_object *object;
164	struct qcomtee_arg u[QCOMTEE_ARGS_MAX + 1];
165
166	struct qcomtee_buffer in_msg;
167	struct qcomtee_buffer out_msg;
168	struct tee_shm *in_shm;
169	struct tee_shm *out_shm;
170
171	void *data;
172};
173
174static inline struct qcomtee_object_invoke_ctx *
175qcomtee_object_invoke_ctx_alloc(struct tee_context *ctx)
176{
177	struct qcomtee_object_invoke_ctx *oic;
178
179	oic = kzalloc(sizeof(*oic), GFP_KERNEL);
180	if (oic)
181		oic->ctx = ctx;
182	return oic;
183}
184
185/**
186 * qcomtee_object_do_invoke() - Submit an invocation for an object.
187 * @oic: context to use for the current invocation.
188 * @object: object being invoked.
189 * @op: requested operation on the object.
190 * @u: array of arguments for the current invocation.
191 * @result: result returned from QTEE.
192 *
193 * The caller is responsible for keeping track of the refcount for each object,
194 * including @object. On return, the caller loses ownership of all input
195 * objects of type %QCOMTEE_OBJECT_TYPE_CB.
196 *
197 * @object can be of %QCOMTEE_OBJECT_TYPE_ROOT or %QCOMTEE_OBJECT_TYPE_TEE.
198 *
199 * Return: On success, returns 0; on failure, returns < 0.
200 */
201int qcomtee_object_do_invoke(struct qcomtee_object_invoke_ctx *oic,
202			     struct qcomtee_object *object, u32 op,
203			     struct qcomtee_arg *u, int *result);
204
205/**
206 * struct qcomtee_object_operations - Callback object operations.
207 * @release: release the object if QTEE is not using it.
208 * @dispatch: dispatch the operation requested by QTEE.
209 * @notify: report the status of any pending response submitted by @dispatch.
210 */
211struct qcomtee_object_operations {
212	void (*release)(struct qcomtee_object *object);
213	int (*dispatch)(struct qcomtee_object_invoke_ctx *oic,
214			struct qcomtee_object *object, u32 op,
215			struct qcomtee_arg *args);
216	void (*notify)(struct qcomtee_object_invoke_ctx *oic,
217		       struct qcomtee_object *object, int err);
218};
219
220/**
221 * struct qcomtee_object - QTEE or kernel object.
222 * @name: object name.
223 * @refcount: reference counter.
224 * @object_type: object type as &enum qcomtee_object_type.
225 * @info: extra information for the object.
226 * @ops: callback operations for objects of type %QCOMTEE_OBJECT_TYPE_CB.
227 * @work: work for async operations on the object.
228 *
229 * @work is used for releasing objects of %QCOMTEE_OBJECT_TYPE_TEE type.
230 */
231struct qcomtee_object {
232	const char *name;
233	struct kref refcount;
234
235	enum qcomtee_object_type object_type;
236	struct object_info {
237		unsigned long qtee_id;
238		/* TEE context for QTEE object async requests. */
239		struct tee_context *qcomtee_async_ctx;
240	} info;
241
242	struct qcomtee_object_operations *ops;
243	struct work_struct work;
244};
245
246/* Static instances of qcomtee_object objects. */
247#define NULL_QCOMTEE_OBJECT ((struct qcomtee_object *)(0))
248extern struct qcomtee_object qcomtee_object_root;
249#define ROOT_QCOMTEE_OBJECT (&qcomtee_object_root)
250
251static inline enum qcomtee_object_type
252typeof_qcomtee_object(struct qcomtee_object *object)
253{
254	if (object == NULL_QCOMTEE_OBJECT)
255		return QCOMTEE_OBJECT_TYPE_NULL;
256	return object->object_type;
257}
258
259static inline const char *qcomtee_object_name(struct qcomtee_object *object)
260{
261	if (object == NULL_QCOMTEE_OBJECT)
262		return "null";
263
264	if (!object->name)
265		return "no-name";
266	return object->name;
267}
268
269/**
270 * qcomtee_object_user_init() - Initialize an object for the user.
271 * @object: object to initialize.
272 * @ot: type of object as &enum qcomtee_object_type.
273 * @ops: instance of callbacks.
274 * @fmt: name assigned to the object.
275 *
276 * Return: On success, returns 0; on failure, returns < 0.
277 */
278int qcomtee_object_user_init(struct qcomtee_object *object,
279			     enum qcomtee_object_type ot,
280			     struct qcomtee_object_operations *ops,
281			     const char *fmt, ...) __printf(4, 5);
282
283/* Object release is RCU protected. */
284int qcomtee_object_get(struct qcomtee_object *object);
285void qcomtee_object_put(struct qcomtee_object *object);
286
287#define qcomtee_arg_for_each(i, args) \
288	for (i = 0; args[i].type != QCOMTEE_ARG_TYPE_INV; i++)
289
290/* Next argument of type @type after index @i. */
291int qcomtee_next_arg_type(struct qcomtee_arg *u, int i,
292			  enum qcomtee_arg_type type);
293
294/* Iterate over argument of given type. */
295#define qcomtee_arg_for_each_type(i, args, at)       \
296	for (i = qcomtee_next_arg_type(args, 0, at); \
297	     args[i].type != QCOMTEE_ARG_TYPE_INV;   \
298	     i = qcomtee_next_arg_type(args, i + 1, at))
299
300#define qcomtee_arg_for_each_input_buffer(i, args) \
301	qcomtee_arg_for_each_type(i, args, QCOMTEE_ARG_TYPE_IB)
302#define qcomtee_arg_for_each_output_buffer(i, args) \
303	qcomtee_arg_for_each_type(i, args, QCOMTEE_ARG_TYPE_OB)
304#define qcomtee_arg_for_each_input_object(i, args) \
305	qcomtee_arg_for_each_type(i, args, QCOMTEE_ARG_TYPE_IO)
306#define qcomtee_arg_for_each_output_object(i, args) \
307	qcomtee_arg_for_each_type(i, args, QCOMTEE_ARG_TYPE_OO)
308
309struct qcomtee_object *
310qcomtee_object_get_client_env(struct qcomtee_object_invoke_ctx *oic);
311
312struct qcomtee_object *
313qcomtee_object_get_service(struct qcomtee_object_invoke_ctx *oic,
314			   struct qcomtee_object *client_env, u32 uid);
315
316#endif /* QCOMTEE_OBJECT_H */