ndk: Add bindings for ASharedMemory (#427)

`ASharedMemory` allows allocating shared memory as a file descriptor
that can be `mmap`ed or shared to other processes via parcels or Unix
domain sockets.

Its Java counterpart is `android.os.SharedMemory` from which (when
available as a JNI `jobject`) an owned file descriptor clone can be
created to access the memory object in native code.

Common Rust traits such as `FromRawFd` are provided so that a
`SharedMemory` object can also be created from a received file
descriptor.

Author: MarijnS95

ndk/CHANGELOG.md

@@ -26,6 +26,7 @@
 - **Breaking:** Upgrade to [`ndk-sys 0.5.0`](../ndk-sys/CHANGELOG.md#050-beta0-2023-08-15). (#420)
 - **Breaking:** bitmap: Provide detailed implementation for `AndroidBitmapInfoFlags`. (#424)
 - native_window: Add `set_buffers_transform()`, `try_allocate_buffers()` and `set_frame_rate*()`. (#425)
+- Add bindings for `ASharedMemory`. (#427)
 - hardware_buffer: Add `id()` to retrieve a system-wide unique identifier for a `HardwareBuffer`. (#428)
 - **Breaking:** bitmap: Strip `Android` prefix from structs and enums, and `Bitmap` from `Result`. (#430)
 - **Breaking:** `raw-window-handle 0.5` support is now behind an _optional_ `rwh_05` crate feature and `raw-window-handle` `0.4` and `0.6` support is provided via the new `rwh_04` and (default-enabled) `rwh_06` crate features. (#434)

ndk/Cargo.toml

@@ -51,6 +51,10 @@ package = "ndk-sys"
 path = "../ndk-sys"
 version = "0.5.0-beta.0"
 
+[dev-dependencies]
+# Only for use in documentation and doc-tests
+libc = "0.2"
+
 [package.metadata.docs.rs]
 features = ["jni", "all"]
 rustdoc-args = ["--cfg", "docsrs"]

ndk/src/lib.rs

@@ -26,6 +26,7 @@ pub mod media;
 pub mod media_error;
 pub mod native_activity;
 pub mod native_window;
+pub mod shared_memory;
 pub mod surface_texture;
 pub mod trace;
 mod utils;

ndk/src/shared_memory.rs

@@ -0,0 +1,153 @@
+//! Bindings for [`ASharedMemory`]
+//!
+//! [`ASharedMemory`]: https://developer.android.com/ndk/reference/group/memory
+#![cfg(feature = "api-level-26")]
+
+use std::{
+    ffi::CStr,
+    io::{Error, Result},
+    // TODO: Import from std::os::fd::{} since Rust 1.66
+    os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd},
+    ptr,
+};
+
+#[cfg(feature = "api-level-27")]
+use jni_sys::{jobject, JNIEnv};
+
+/// Enables the creation, mapping, and protection control over anonymous shared memory.
+#[derive(Debug)]
+#[doc(alias = "ASharedMemory")]
+pub struct SharedMemory(OwnedFd);
+
+impl SharedMemory {
+    /// Create a shared memory region.
+    ///
+    /// Creates shared memory region and returns a file descriptor. The resulting file descriptor
+    /// can be `mmap`'ed to process memory space with `PROT_READ | PROT_WRITE | PROT_EXEC`. Access
+    /// to this shared memory region can be restricted with [`set_prot()`][Self::set_prot()].
+    ///
+    /// Use [`android.os.ParcelFileDescriptor`] to pass the file descriptor to another process.
+    /// File descriptors may also be sent to other processes over a Unix domain socket with
+    /// `sendmsg` and `SCM_RIGHTS`. See `sendmsg(3)` and `cmsg(3)` man pages for more information.
+    ///
+    /// If you intend to share this file descriptor with a child process after calling `exec(3)`,
+    /// note that you will need to use `fcntl(2)` with `F_SETFD` to clear the `FD_CLOEXEC` flag for
+    /// this to work on all versions of Android.
+    ///
+    /// [`android.os.ParcelFileDescriptor`]: https://developer.android.com/reference/android/os/ParcelFileDescriptor
+    #[doc(alias = "ASharedMemory_create")]
+    pub fn create(name: Option<&CStr>, size: usize) -> Result<Self> {
+        let fd =
+            unsafe { ffi::ASharedMemory_create(name.map_or(ptr::null(), |p| p.as_ptr()), size) };
+        if fd < 0 {
+            Err(Error::last_os_error())
+        } else {
+            Ok(unsafe { Self::from_raw_fd(fd) })
+        }
+    }
+
+    /// Returns a `dup`'d FD from the given Java [`android.os.SharedMemory`] object.
+    ///
+    /// The returned file descriptor has all the same properties & capabilities as the FD returned
+    /// from [`create()`][Self::create()], however the protection flags will be the same as those
+    /// of the [`android.os.SharedMemory`] object.
+    ///
+    /// [`android.os.SharedMemory`]: https://developer.android.com/reference/android/os/SharedMemory
+    #[cfg(feature = "api-level-27")]
+    #[doc(alias = "ASharedMemory_dupFromJava")]
+    #[allow(clippy::not_unsafe_ptr_arg_deref)]
+    pub fn dup_from_java(env: *mut JNIEnv, shared_memory: jobject) -> Result<Self> {
+        let fd = unsafe { ffi::ASharedMemory_dupFromJava(env, shared_memory) };
+        if fd < 0 {
+            Err(Error::last_os_error())
+        } else {
+            Ok(unsafe { Self::from_raw_fd(fd) })
+        }
+    }
+
+    /// Get the size of the shared memory region.
+    #[doc(alias = "ASharedMemory_getSize")]
+    pub fn size(&self) -> usize {
+        unsafe { ffi::ASharedMemory_getSize(self.as_raw_fd()) }
+    }
+
+    /// Restrict access of shared memory region.
+    ///
+    /// This function restricts access of a shared memory region. Access can only be removed. The
+    /// effect applies globally to all file descriptors in all processes across the system that
+    /// refer to this shared memory region. Existing memory mapped regions are not affected.
+    ///
+    /// It is a common use case to create a shared memory region, map it read/write locally to
+    /// initialize content, and then send the shared memory to another process with read only
+    /// access. Code example as below:
+    ///
+    /// ```no_run
+    /// # use ndk::shared_memory::SharedMemory;
+    /// # // TODO: Import from std::os::fd::{} since Rust 1.66
+    /// # use std::os::unix::io::AsRawFd;
+    /// # use std::ffi::CStr;
+    /// # unsafe {
+    /// let mem = SharedMemory::create(Some(CStr::from_bytes_with_nul_unchecked(b"memory\0")), 127).unwrap();
+    /// // By default it has PROT_READ | PROT_WRITE | PROT_EXEC.
+    /// let size = mem.size();
+    /// let buffer = libc::mmap(
+    ///     std::ptr::null_mut(),
+    ///     size,
+    ///     libc::PROT_READ | libc::PROT_WRITE,
+    ///     libc::MAP_SHARED,
+    ///     mem.as_raw_fd(),
+    ///     0,
+    /// );
+    /// let buffer_slice = std::slice::from_raw_parts_mut(buffer.cast(), size);
+    ///
+    /// // trivially initialize content
+    /// buffer_slice[..7].copy_from_slice(b"hello!\0");
+    ///
+    /// // Existing mappings will retain their protection flags (PROT_WRITE here) after set_prod()
+    /// // unless it is unmapped:
+    /// libc::munmap(buffer, size);
+    ///
+    /// // limit access to read only
+    /// mem.set_prot(libc::PROT_READ);
+    ///
+    /// // share fd with another process here and the other process can only map with PROT_READ.
+    /// # }
+    /// ```
+    #[doc(alias = "ASharedMemory_setProt")]
+    pub fn set_prot(&self, prot: i32) -> Result<()> {
+        let status = unsafe { ffi::ASharedMemory_setProt(self.as_raw_fd(), prot) };
+        if status < 0 {
+            Err(Error::last_os_error())
+        } else {
+            Ok(())
+        }
+    }
+}
+
+impl AsFd for SharedMemory {
+    fn as_fd(&self) -> BorrowedFd<'_> {
+        self.0.as_fd()
+    }
+}
+
+impl AsRawFd for SharedMemory {
+    fn as_raw_fd(&self) -> RawFd {
+        self.0.as_raw_fd()
+    }
+}
+
+impl IntoRawFd for SharedMemory {
+    fn into_raw_fd(self) -> RawFd {
+        self.0.into_raw_fd()
+    }
+}
+
+impl FromRawFd for SharedMemory {
+    /// # Safety
+    ///
+    /// The resource pointed to by `fd` must be open and suitable for assuming
+    /// ownership. The resource must not require any cleanup other than `close`.
+    unsafe fn from_raw_fd(fd: RawFd) -> Self {
+        Self(OwnedFd::from_raw_fd(fd))
+    }
+}