optee_ffa.h

  1/* SPDX-License-Identifier: BSD-2-Clause */
  2/*
  3 * Copyright (c) 2019-2021, 2023 Linaro Limited
  4 */
  5
  6/*
  7 * This file is exported by OP-TEE and is kept in sync between secure world
  8 * and normal world drivers. We're using ARM FF-A 1.0 specification.
  9 */
 10
 11#ifndef __OPTEE_FFA_H
 12#define __OPTEE_FFA_H
 13
 14#include <linux/arm_ffa.h>
 15
 16/*
 17 * Normal world sends requests with FFA_MSG_SEND_DIRECT_REQ and
 18 * responses are returned with FFA_MSG_SEND_DIRECT_RESP for normal
 19 * messages.
 20 *
 21 * All requests with FFA_MSG_SEND_DIRECT_REQ and FFA_MSG_SEND_DIRECT_RESP
 22 * are using the AArch32 SMC calling convention with register usage as
 23 * defined in FF-A specification:
 24 * w0:    Function ID (0x8400006F or 0x84000070)
 25 * w1:    Source/Destination IDs
 26 * w2:    Reserved (MBZ)
 27 * w3-w7: Implementation defined, free to be used below
 28 */
 29
 30#define OPTEE_FFA_VERSION_MAJOR	1
 31#define OPTEE_FFA_VERSION_MINOR	0
 32
 33#define OPTEE_FFA_BLOCKING_CALL(id)	(id)
 34#define OPTEE_FFA_YIELDING_CALL_BIT	31
 35#define OPTEE_FFA_YIELDING_CALL(id)	((id) | BIT(OPTEE_FFA_YIELDING_CALL_BIT))
 36
 37/*
 38 * Returns the API version implemented, currently follows the FF-A version.
 39 * Call register usage:
 40 * w3:    Service ID, OPTEE_FFA_GET_API_VERSION
 41 * w4-w7: Not used (MBZ)
 42 *
 43 * Return register usage:
 44 * w3:    OPTEE_FFA_VERSION_MAJOR
 45 * w4:    OPTEE_FFA_VERSION_MINOR
 46 * w5-w7: Not used (MBZ)
 47 */
 48#define OPTEE_FFA_GET_API_VERSION	OPTEE_FFA_BLOCKING_CALL(0)
 49
 50/*
 51 * Returns the revision of OP-TEE.
 52 *
 53 * Used by non-secure world to figure out which version of the Trusted OS
 54 * is installed. Note that the returned revision is the revision of the
 55 * Trusted OS, not of the API.
 56 *
 57 * Call register usage:
 58 * w3:    Service ID, OPTEE_FFA_GET_OS_VERSION
 59 * w4-w7: Unused (MBZ)
 60 *
 61 * Return register usage:
 62 * w3:    CFG_OPTEE_REVISION_MAJOR
 63 * w4:    CFG_OPTEE_REVISION_MINOR
 64 * w5:    TEE_IMPL_GIT_SHA1 (or zero if not supported)
 65 */
 66#define OPTEE_FFA_GET_OS_VERSION	OPTEE_FFA_BLOCKING_CALL(1)
 67
 68/*
 69 * Exchange capabilities between normal world and secure world.
 70 *
 71 * Currently there are no defined capabilities. When features are added new
 72 * capabilities may be added.
 73 *
 74 * Call register usage:
 75 * w3:    Service ID, OPTEE_FFA_EXCHANGE_CAPABILITIES
 76 * w4-w7: Not used (MBZ)
 77 *
 78 * Return register usage:
 79 * w3:    Error code, 0 on success
 80 * w4:    Bit[7:0]:  Number of parameters needed for RPC to be supplied
 81 *                   as the second MSG arg struct for
 82 *                   OPTEE_FFA_YIELDING_CALL_WITH_ARG.
 83 *        Bit[31:8]: Reserved (MBZ)
 84 * w5:	  Bitfield of OP-TEE capabilities OPTEE_FFA_SEC_CAP_*
 85 * w6:	  The maximum secure world notification number
 86 * w7:	  Not used (MBZ)
 87 */
 88/*
 89 * Secure world supports giving an offset into the argument shared memory
 90 * object, see also OPTEE_FFA_YIELDING_CALL_WITH_ARG
 91 */
 92#define OPTEE_FFA_SEC_CAP_ARG_OFFSET	BIT(0)
 93/* OP-TEE supports asynchronous notification via FF-A */
 94#define OPTEE_FFA_SEC_CAP_ASYNC_NOTIF	BIT(1)
 95/* OP-TEE supports probing for RPMB device if needed */
 96#define OPTEE_FFA_SEC_CAP_RPMB_PROBE	BIT(2)
 97/* OP-TEE supports Protected Memory for secure data path */
 98#define OPTEE_FFA_SEC_CAP_PROTMEM	BIT(3)
 99
100#define OPTEE_FFA_EXCHANGE_CAPABILITIES OPTEE_FFA_BLOCKING_CALL(2)
101
102/*
103 * Unregister shared memory
104 *
105 * Call register usage:
106 * w3:    Service ID, OPTEE_FFA_YIELDING_CALL_UNREGISTER_SHM
107 * w4:    Shared memory handle, lower bits
108 * w5:    Shared memory handle, higher bits
109 * w6-w7: Not used (MBZ)
110 *
111 * Return register usage:
112 * w3:    Error code, 0 on success
113 * w4-w7: Not used (MBZ)
114 */
115#define OPTEE_FFA_UNREGISTER_SHM	OPTEE_FFA_BLOCKING_CALL(3)
116
117/*
118 * Inform OP-TEE that the normal world is able to receive asynchronous
119 * notifications.
120 *
121 * Call register usage:
122 * w3:    Service ID, OPTEE_FFA_ENABLE_ASYNC_NOTIF
123 * w4:	  Notification value to request bottom half processing, should be
124 *	  less than OPTEE_FFA_MAX_ASYNC_NOTIF_VALUE
125 * w5-w7: Not used (MBZ)
126 *
127 * Return register usage:
128 * w3:    Error code, 0 on success
129 * w4-w7: Not used (MBZ)
130 */
131#define OPTEE_FFA_ENABLE_ASYNC_NOTIF	OPTEE_FFA_BLOCKING_CALL(5)
132
133#define OPTEE_FFA_MAX_ASYNC_NOTIF_VALUE	64
134
135/*
136 * Release Protected memory
137 *
138 * Call register usage:
139 * w3:    Service ID, OPTEE_FFA_RECLAIM_PROTMEM
140 * w4:    Shared memory handle, lower bits
141 * w5:    Shared memory handle, higher bits
142 * w6-w7: Not used (MBZ)
143 *
144 * Return register usage:
145 * w3:    Error code, 0 on success
146 * w4-w7: Note used (MBZ)
147 */
148#define OPTEE_FFA_RELEASE_PROTMEM	OPTEE_FFA_BLOCKING_CALL(8)
149
150/*
151 * Call with struct optee_msg_arg as argument in the supplied shared memory
152 * with a zero internal offset and normal cached memory attributes.
153 * Register usage:
154 * w3:    Service ID, OPTEE_FFA_YIELDING_CALL_WITH_ARG
155 * w4:    Lower 32 bits of a 64-bit Shared memory handle
156 * w5:    Upper 32 bits of a 64-bit Shared memory handle
157 * w6:    Offset into shared memory pointing to a struct optee_msg_arg
158 *	  right after the parameters of this struct (at offset
159 *	  OPTEE_MSG_GET_ARG_SIZE(num_params) follows a struct optee_msg_arg
160 *	  for RPC, this struct has reserved space for the number of RPC
161 *	  parameters as returned by OPTEE_FFA_EXCHANGE_CAPABILITIES.
162 *	  MBZ unless the bit OPTEE_FFA_SEC_CAP_ARG_OFFSET is received with
163 *	  OPTEE_FFA_EXCHANGE_CAPABILITIES.
164 * w7:    Not used (MBZ)
165 * Resume from RPC. Register usage:
166 * w3:    Service ID, OPTEE_FFA_YIELDING_CALL_RESUME
167 * w4-w6: Not used (MBZ)
168 * w7:    Resume info
169 *
170 * Normal return (yielding call is completed). Register usage:
171 * w3:    Error code, 0 on success
172 * w4:    OPTEE_FFA_YIELDING_CALL_RETURN_DONE
173 * w5-w7: Not used (MBZ)
174 *
175 * RPC interrupt return (RPC from secure world). Register usage:
176 * w3:    Error code == 0
177 * w4:    Any defined RPC code but OPTEE_FFA_YIELDING_CALL_RETURN_DONE
178 * w5-w6: Not used (MBZ)
179 * w7:    Resume info
180 *
181 * Possible error codes in register w3:
182 * 0:                       Success
183 * FFA_DENIED:              w4 isn't one of OPTEE_FFA_YIELDING_CALL_START
184 *                          OPTEE_FFA_YIELDING_CALL_RESUME
185 *
186 * Possible error codes for OPTEE_FFA_YIELDING_CALL_START,
187 * FFA_BUSY:               Number of OP-TEE OS threads exceeded,
188 *                         try again later
189 * FFA_DENIED:             RPC shared memory object not found
190 * FFA_INVALID_PARAMETER:  Bad shared memory handle or offset into the memory
191 *
192 * Possible error codes for OPTEE_FFA_YIELDING_CALL_RESUME
193 * FFA_INVALID_PARAMETER:  Bad resume info
194 */
195#define OPTEE_FFA_YIELDING_CALL_WITH_ARG	OPTEE_FFA_YIELDING_CALL(0)
196#define OPTEE_FFA_YIELDING_CALL_RESUME		OPTEE_FFA_YIELDING_CALL(1)
197
198#define OPTEE_FFA_YIELDING_CALL_RETURN_DONE		0
199#define OPTEE_FFA_YIELDING_CALL_RETURN_RPC_CMD		1
200#define OPTEE_FFA_YIELDING_CALL_RETURN_INTERRUPT	2
201
202#endif /*__OPTEE_FFA_H*/