optee_utee/parameter/
deprecated.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Legacy raw-pointer-based parameter API (deprecated).
19//!
20//! The types in this module use raw `*mut TEE_Param` pointers and require
21//! manual unsafe casts at every call site. **New code should use the typed
22//! wrappers** instead:
23//!
24//! | Legacy type | Replacement |
25//! |---|---|
26//! | [`Parameters`] | Use [`FromRawParameters`] with a 4-tuple of typed wrappers (e.g. `(ParameterNone, ParameterMemrefInput, ParameterValueOutput, ParameterMemrefOutput)`) |
27//! | [`Parameter`] | Use the concrete types: [`ParameterValueInput`](crate::ParameterValueInput), [`ParameterValueOutput`](crate::ParameterValueOutput), [`ParameterMemrefInput`](crate::ParameterMemrefInput), etc. |
28//! | [`ParamValue`] | Use the concrete types: [`ParameterValueInput`](crate::ParameterValueInput), [`ParameterValueOutput`](crate::ParameterValueOutput), [`ParameterValueInout`](crate::ParameterValueInout), and the traits: [`ParameterValueRead`](crate::ParameterValueRead) and [`ParameterValueWrite`](crate::ParameterValueWrite) |
29//! | [`ParamMemref`] | Use the concrete types: [`ParameterMemrefInput`](crate::ParameterMemrefInput), [`ParameterMemrefOutput`](crate::ParameterMemrefOutput), [`ParameterMemrefInout`](crate::ParameterMemrefInout), and the traits: [`ParameterMemrefRead`](crate::ParameterMemrefRead) and [`ParameterMemrefWrite`](crate::ParameterMemrefWrite) |
30//!
31//! # Example migration
32//!
33//! **Old (deprecated) code:**
34//!
35//! ```rust,ignore
36//! fn invoke_command(cmd_id: u32, params: &mut Parameters) -> Result<()> {
37//!     let mut p0 = unsafe { params.0.as_memref()? };
38//!     // extra codes here...
39//!     let data = p0.buffer();
40//!     data.copy_from_slice(&output);
41//!     p0.set_updated_size(output.len());
42//! }
43//! ```
44//!
45//! **New code:**
46//!
47//! ```rust,ignore
48//! use optee_utee::prelude::*;
49//!
50//! fn invoke_command(cmd_id: u32, params: &mut (ParameterMemrefInout, ...)) -> Result<()> {
51//!     let p0 = &mut params.0;
52//!     // extra codes here...
53//!     p0.write_at(0, output)
54//! }
55//! ```
56
57use super::{ParamType, RawParamTypes, RawParams};
58use crate::{Error, ErrorKind, FromRawParameters, Result, raw};
59use core::{marker, slice};
60
61/// # Deprecated
62///
63/// Use the typed wrappers with [`super::FromRawParameters`] instead. See the
64/// [module-level documentation](self) for migration examples.
65pub struct Parameters(pub Parameter, pub Parameter, pub Parameter, pub Parameter);
66
67impl Parameters {
68    pub fn from_raw(tee_params: &mut RawParams, param_types: u32) -> Self {
69        let (f0, f1, f2, f3) = ParamTypes::from(param_types).into_flags();
70        let p0 = Parameter::from_raw(&mut tee_params[0], f0);
71        let p1 = Parameter::from_raw(&mut tee_params[1], f1);
72        let p2 = Parameter::from_raw(&mut tee_params[2], f2);
73        let p3 = Parameter::from_raw(&mut tee_params[3], f3);
74
75        Parameters(p0, p1, p2, p3)
76    }
77}
78
79/// # Deprecated
80///
81/// Use [`super::value::ParameterValueRead`] (for `get_a/get_b`) and
82/// [`super::value::ParameterValueWrite`] (for `set_a/set_b`) on the typed
83/// wrappers ([`super::value::ParameterValueInput`], etc.) instead.
84pub struct ParamValue<'parameter> {
85    raw: *mut raw::Value,
86    param_type: ParamType,
87    _marker: marker::PhantomData<&'parameter mut u32>,
88}
89
90impl<'parameter> ParamValue<'parameter> {
91    pub fn a(&self) -> u32 {
92        unsafe { (*self.raw).a }
93    }
94
95    pub fn b(&self) -> u32 {
96        unsafe { (*self.raw).b }
97    }
98
99    pub fn set_a(&mut self, a: u32) {
100        unsafe {
101            (*self.raw).a = a;
102        }
103    }
104
105    pub fn set_b(&mut self, b: u32) {
106        unsafe {
107            (*self.raw).b = b;
108        }
109    }
110
111    pub fn param_type(&self) -> ParamType {
112        self.param_type
113    }
114}
115
116/// Lightweight accessor for a memory-reference TEE parameter.
117///
118/// # Deprecated
119///
120/// Use [`super::memref::ParameterMemrefRead`] (for `read_to_vec`, `read_at`)
121/// and [`super::memref::ParameterMemrefWrite`] (for `set_updated_size`,
122/// `set_output`, `write_at`) on the typed wrappers instead.
123pub struct ParamMemref<'parameter> {
124    raw: *mut raw::Memref,
125    param_type: ParamType,
126    _marker: marker::PhantomData<&'parameter mut [u8]>,
127}
128
129impl<'parameter> ParamMemref<'parameter> {
130    pub fn buffer(&mut self) -> &mut [u8] {
131        unsafe { slice::from_raw_parts_mut((*self.raw).buffer as *mut u8, (*self.raw).size) }
132    }
133
134    pub fn param_type(&self) -> ParamType {
135        self.param_type
136    }
137
138    pub fn raw(&mut self) -> *mut raw::Memref {
139        self.raw
140    }
141
142    pub fn set_updated_size(&mut self, size: usize) {
143        unsafe { (*self.raw).size = size };
144    }
145}
146
147/// # Deprecated
148///
149/// Use the concrete typed wrappers
150/// ([`super::value::ParameterValueInput`], [`super::memref::ParameterMemrefInput`], etc.)
151/// instead. They encode the parameter type in the Rust type system, making
152/// mismatched-type errors impossible at compile time.
153pub struct Parameter {
154    pub raw: *mut raw::TEE_Param,
155    pub param_type: ParamType,
156}
157
158impl Parameter {
159    pub fn from_raw(ptr: *mut raw::TEE_Param, param_type: ParamType) -> Self {
160        Self {
161            raw: ptr,
162            param_type,
163        }
164    }
165
166    /// # Safety
167    ///
168    /// The caller must ensure that the raw pointer is valid and points to a
169    /// properly initialized `TEE_Param`.
170    pub unsafe fn as_value(&mut self) -> Result<ParamValue<'_>> {
171        match self.param_type {
172            ParamType::ValueInput | ParamType::ValueInout | ParamType::ValueOutput => {
173                Ok(ParamValue {
174                    raw: unsafe { &mut (*self.raw).value },
175                    param_type: self.param_type,
176                    _marker: marker::PhantomData,
177                })
178            }
179            _ => Err(Error::new(ErrorKind::BadParameters)),
180        }
181    }
182
183    /// # Safety
184    ///
185    /// The caller must ensure that the raw pointer is valid and points to a
186    /// properly initialized `TEE_Param`.
187    pub unsafe fn as_memref(&mut self) -> Result<ParamMemref<'_>> {
188        match self.param_type {
189            ParamType::MemrefInout | ParamType::MemrefInput | ParamType::MemrefOutput => {
190                Ok(ParamMemref {
191                    raw: unsafe { &mut (*self.raw).memref },
192                    param_type: self.param_type,
193                    _marker: marker::PhantomData,
194                })
195            }
196            _ => Err(Error::new(ErrorKind::BadParameters)),
197        }
198    }
199
200    pub fn raw(&self) -> *mut raw::TEE_Param {
201        self.raw
202    }
203}
204
205/// # Deprecated
206///
207/// Use the typed wrappers with [`super::FromRawParameters`] instead; they
208/// extract the types implicitly via `TEE_PARAM_TYPE_GET`.
209pub struct ParamTypes(u32);
210
211impl ParamTypes {
212    pub fn into_flags(&self) -> (ParamType, ParamType, ParamType, ParamType) {
213        (
214            (0x000fu32 & self.0).into(),
215            ((0x00f0u32 & self.0) >> 4).into(),
216            ((0x0f00u32 & self.0) >> 8).into(),
217            ((0xf000u32 & self.0) >> 12).into(),
218        )
219    }
220}
221
222impl From<u32> for ParamTypes {
223    fn from(value: u32) -> Self {
224        ParamTypes(value)
225    }
226}
227
228impl<'a> FromRawParameters<'a> for Parameters {
229    unsafe fn from_raw(raw_types: RawParamTypes, raw_params: &'a mut RawParams) -> Result<Self> {
230        Ok(Self::from_raw(raw_params, raw_types))
231    }
232}
optee_utee/parameter/deprecated.rs

optee_utee/parameter/
deprecated.rs
