zx/
pmt.rs

1// Copyright 2022 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
5//! Type-safe bindings for Zircon pmt objects.
6
7use crate::{ok, sys, AsHandleRef, Handle, HandleBased, HandleRef, Status};
8use std::mem;
9
10/// An object representing a Zircon Pinned Memory Token.
11/// See [PMT Documentation](https://fuchsia.dev/fuchsia-src/reference/kernel_objects/pinned_memory_token) for details.
12///
13/// As essentially a subtype of `Handle`, it can be freely interconverted.
14#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
15#[repr(transparent)]
16pub struct Pmt(Handle);
17impl_handle_based!(Pmt);
18
19impl Pmt {
20    // Unpins a Pinned Memory Token.
21    // Wraps the
22    // [`zx_pmt_unpin`](https://fuchsia.dev/fuchsia-src/reference/syscalls/pmt_unpin) system call to unpin a pmt.
23    pub fn unpin(self) -> Result<(), Status> {
24        let status = unsafe { sys::zx_pmt_unpin(self.raw_handle()) };
25
26        // According to the syscall documentation, after calling `zx_pmt_unpin`,
27        // the pmt handle cannot be used anymore, not even for `zx_handle_close`.
28        // This is also true even if the function returns an error.
29        mem::forget(self);
30
31        ok(status)?;
32        Ok(())
33    }
34}
35
36#[cfg(test)]
37mod tests {
38    use super::*;
39    use crate::Vmo;
40
41    #[test]
42    fn pmt_unpin_invalid_handle() {
43        let pmt = Pmt::from(Handle::invalid());
44        let status = pmt.unpin();
45        assert_eq!(status, Err(Status::BAD_HANDLE));
46    }
47
48    #[test]
49    fn pmt_unpin_wrong_handle() {
50        let vmo = Vmo::create(0).unwrap();
51        let pmt = unsafe { Pmt::from(Handle::from_raw(vmo.into_raw())) };
52
53        let status = pmt.unpin();
54        assert_eq!(status, Err(Status::WRONG_TYPE));
55    }
56}