fidl_driver/
encoding.rs

1// Copyright 2024 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use fidl::encoding::{
6    Context, Decode, Decoder, DefaultFuchsiaResourceDialect, Depth, Encode, Encoder,
7    ResourceTypeMarker, TypeMarker, ALLOC_ABSENT_U32, ALLOC_PRESENT_U32,
8};
9
10use fdf::{Channel, MixedHandle, MixedHandleType};
11use zx::{
12    AsHandleRef, Handle, HandleBased, HandleDisposition, HandleInfo, HandleOp, ObjectType, Rights,
13    Status,
14};
15
16use std::marker::PhantomData;
17
18use crate::endpoints::DriverClientEnd;
19
20#[derive(Debug, Clone)]
21pub struct DriverEndpoint<T>(PhantomData<DriverClientEnd<T>>);
22
23unsafe impl<T: 'static> TypeMarker for DriverEndpoint<T> {
24    type Owned = DriverClientEnd<T>;
25
26    fn inline_align(_context: Context) -> usize {
27        4
28    }
29
30    fn inline_size(_context: Context) -> usize {
31        4
32    }
33}
34
35impl<T: 'static> ResourceTypeMarker for DriverEndpoint<T> {
36    type Borrowed<'a> = DriverClientEnd<T>;
37
38    fn take_or_borrow(value: &mut Self::Owned) -> Self::Borrowed<'_> {
39        DriverClientEnd(value.0.take(), PhantomData)
40    }
41}
42
43impl<T: 'static> Decode<DriverEndpoint<T>, DefaultFuchsiaResourceDialect> for DriverClientEnd<T> {
44    fn new_empty() -> Self {
45        Self(None, PhantomData)
46    }
47
48    unsafe fn decode(
49        &mut self,
50        decoder: &mut Decoder<'_, DefaultFuchsiaResourceDialect>,
51        offset: usize,
52        _depth: Depth,
53    ) -> fidl::Result<()> {
54        match decoder.read_num::<u32>(offset) {
55            ALLOC_PRESENT_U32 => {}
56            ALLOC_ABSENT_U32 => return Err(fidl::Error::NotNullable),
57            _ => return Err(fidl::Error::InvalidPresenceIndicator),
58        }
59        // Take what the decoder thinks is a NONE-type zircon handle and validate that it's
60        // a driver handle and use that.
61        let handle = decoder.take_next_handle(ObjectType::NONE, Rights::empty())?.into_raw();
62        let mixed_handle = unsafe { MixedHandle::try_from_raw(handle) };
63        match mixed_handle.map(MixedHandle::resolve) {
64            None => (),
65            Some(MixedHandleType::Driver(driver_handle)) => {
66                // SAFETY: we own this handle as the receiver of the fidl message that contained it.
67                self.0 = unsafe { Some(Channel::from_driver_handle(driver_handle)) };
68            }
69            _ => {
70                // The handle was present but not a driver handle, so is not valid.
71                return Err(fidl::Error::Invalid);
72            }
73        }
74        Ok(())
75    }
76}
77
78unsafe impl<T: 'static> Encode<DriverEndpoint<T>, DefaultFuchsiaResourceDialect>
79    for DriverClientEnd<T>
80{
81    unsafe fn encode(
82        self,
83        encoder: &mut Encoder<'_, DefaultFuchsiaResourceDialect>,
84        offset: usize,
85        _depth: Depth,
86    ) -> fidl::Result<()> {
87        let Some(channel) = self.0 else {
88            return Err(fidl::Error::NotNullable);
89        };
90        // SAFETY: we are taking the handle and converting it into what looks like a zircon
91        // handle for the benefit of the fidl encoding library. If something tries to close it,
92        // it will cause an error and leak the driver handle but it will not cause any other
93        // unsoundness.
94        let handle =
95            unsafe { fidl::Handle::from_raw(channel.into_driver_handle().into_raw().get()) };
96
97        // SAFETY: the caller is responsible for ensuring that there's enough space for this
98        // value.
99        unsafe { encoder.write_num(ALLOC_PRESENT_U32, offset) };
100        encoder.push_next_handle(HandleDisposition::new(
101            HandleOp::Move(handle),
102            ObjectType::NONE,
103            Rights::empty(),
104            Status::OK,
105        ));
106        Ok(())
107    }
108}
109
110/// Converts the handle to a [`HandleInfo`], with [`DriverHandle`]s being represented as
111/// a valid driver handle but [`ObjectType::NONE`].
112///
113/// This uses [`Handle::basic_info`] to get the object type and rights for a zircon
114/// handle, so may return an error if that fails.
115///
116/// # Safety
117///
118/// The caller is responsible for making sure that the handle is either converted
119/// back to a [`MixedHandle`] or the correct cleanup happens, or an error or leak
120/// may happen when the [`HandleInfo`] is dropped.
121pub unsafe fn mixed_into_handle_info(this: Option<MixedHandle>) -> Result<HandleInfo, Status> {
122    use MixedHandleType::*;
123    let Some(this) = this else {
124        return Ok(HandleInfo::new(Handle::invalid(), ObjectType::NONE, Rights::empty()));
125    };
126    match this.resolve() {
127        Zircon(handle) => {
128            let basic_info = handle.basic_info()?;
129            Ok(HandleInfo::new(handle, basic_info.object_type, basic_info.rights))
130        }
131        Driver(handle) => {
132            // SAFETY: we are wrapping the technically invalid handle in a `ManuallyDrop`
133            // to prevent it from being dropped.
134            Ok(HandleInfo::new(
135                unsafe { Handle::from_raw(handle.into_raw().get()) },
136                ObjectType::NONE,
137                Rights::empty(),
138            ))
139        }
140    }
141}
142
143/// Converts a [`HandleDisposition`] to a [`MixedHandle`], relying on the bit pattern of
144/// the handle to correctly identify [`Handle`] vs. [`fdf::DriverHandle`].
145///
146/// # Panics
147///
148/// This panics if the handle's op is not [`zx::HandleOp::Move`]
149pub fn mixed_from_handle_disposition(
150    mut handle: HandleDisposition<'static>,
151) -> Option<MixedHandle> {
152    use zx::HandleOp::*;
153    match handle.take_op() {
154        Move(handle) => MixedHandle::from_zircon_handle(handle),
155        Duplicate(_) => {
156            panic!("tried to convert a duplicate HandleDisposition into a driver MixedHandle")
157        }
158    }
159}
160
161#[cfg(test)]
162mod tests {
163    use fdf::DriverHandle;
164    use zx::Port;
165
166    use super::*;
167
168    /// Creates a valid `DriverHandle` by creating a driver channel pair and returning one of them.
169    fn make_driver_handle() -> DriverHandle {
170        let (left, right) = fdf::Channel::<()>::create();
171        drop(right);
172        left.into_driver_handle()
173    }
174
175    #[test]
176    fn driver_handle_info() {
177        let handle = MixedHandle::from(make_driver_handle());
178        let handle_info = unsafe { mixed_into_handle_info(Some(handle)).unwrap() };
179        assert_eq!(handle_info.object_type, ObjectType::NONE);
180        assert_eq!(handle_info.rights, Rights::empty());
181        // take the handle back to a mixed handle so it gets dropped properly
182        MixedHandle::from_zircon_handle(handle_info.handle).unwrap();
183    }
184
185    #[test]
186    fn driver_handle_disposition() {
187        let handle_disposition = HandleDisposition::new(
188            HandleOp::Move(unsafe { Handle::from_raw(make_driver_handle().into_raw().get()) }),
189            ObjectType::NONE,
190            Rights::empty(),
191            Status::OK,
192        );
193        mixed_from_handle_disposition(handle_disposition).unwrap();
194    }
195
196    #[test]
197    fn zircon_handle_info() {
198        let handle = MixedHandle::from_zircon_handle(Port::create().into()).unwrap();
199        let handle_info = unsafe { mixed_into_handle_info(Some(handle)).unwrap() };
200        assert_eq!(handle_info.object_type, ObjectType::PORT);
201        assert_eq!(
202            handle_info.rights,
203            Rights::DUPLICATE | Rights::TRANSFER | Rights::READ | Rights::WRITE | Rights::INSPECT
204        );
205        // take the handle back to a mixed handle so it gets dropped properly
206        MixedHandle::from_zircon_handle(handle_info.handle).unwrap();
207    }
208
209    #[test]
210    fn zircon_handle_disposition() {
211        let handle_disposition = HandleDisposition::new(
212            HandleOp::Move(Port::create().into()),
213            ObjectType::PORT,
214            Rights::DUPLICATE | Rights::TRANSFER | Rights::READ | Rights::WRITE | Rights::INSPECT,
215            Status::OK,
216        );
217        mixed_from_handle_disposition(handle_disposition).unwrap();
218    }
219}
fidl_driver/encoding.rs

fidl_driver/
encoding.rs
