mem_util/
lib.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//! Utilities for working with the `fuchsia.mem` FIDL library.
6
7use std::borrow::Cow;
8use {fidl_fuchsia_io as fio, fidl_fuchsia_mem as fmem, zx_status as zxs};
9
10/// Open `path` from given `parent` directory, returning an [`fmem::Data`] of the contents.
11///
12/// Prioritizes returning an [`fmem::Data::Buffer`] if it can be done by reusing a VMO handle
13/// from the directory's server.
14pub async fn open_file_data(
15    parent: &fio::DirectoryProxy,
16    path: &str,
17) -> Result<fmem::Data, FileError> {
18    let file = fuchsia_fs::directory::open_file_async(parent, path, fio::PERM_READABLE)?;
19    match file
20        .get_backing_memory(fio::VmoFlags::READ)
21        .await
22        .map_err(|e| {
23            // Don't swallow the root cause of the error without a trace. It may
24            // be impossible to correlate resulting error to its root cause
25            // otherwise.
26            log::debug!("error for path={}: {}:", path, e);
27            FileError::GetBufferError(e)
28        })?
29        .map_err(zxs::Status::from_raw)
30    {
31        Ok(vmo) => {
32            let size = vmo.get_content_size().expect("failed to get VMO size");
33            Ok(fmem::Data::Buffer(fmem::Buffer { vmo, size }))
34        }
35        Err(e) => {
36            let _: zxs::Status = e;
37            // we still didn't get a VMO handle, fallback to reads over the channel
38            let bytes = fuchsia_fs::file::read(&file).await?;
39            Ok(fmem::Data::Bytes(bytes))
40        }
41    }
42}
43
44/// Errors that can occur when operating on `DirectoryProxy`s and `FileProxy`s.
45#[derive(Debug, thiserror::Error)]
46pub enum FileError {
47    #[error("Failed to open a File.")]
48    OpenError(#[from] fuchsia_fs::node::OpenError),
49
50    #[error("Couldn't read a file")]
51    ReadError(#[from] fuchsia_fs::file::ReadError),
52
53    #[error("FIDL call to retrieve a file's buffer failed")]
54    GetBufferError(#[source] fidl::Error),
55}
56
57/// Retrieve the bytes in `data`, returning a reference if it's a `Data::Bytes` and a copy of
58/// the bytes read from the VMO if it's a `Data::Buffer`.
59pub fn bytes_from_data(data: &fmem::Data) -> Result<Cow<'_, [u8]>, DataError> {
60    Ok(match data {
61        fmem::Data::Buffer(buf) => {
62            let size = buf.size as usize;
63            let mut raw_bytes = vec![0; size];
64            buf.vmo.read(&mut raw_bytes, 0).map_err(DataError::VmoReadError)?;
65            Cow::Owned(raw_bytes)
66        }
67        fmem::Data::Bytes(b) => Cow::Borrowed(b),
68        fmem::DataUnknown!() => return Err(DataError::UnrecognizedDataVariant),
69    })
70}
71
72/// Errors that can occur when operating on `fuchsia.mem.Data` values.
73#[derive(Debug, thiserror::Error, PartialEq, Eq)]
74pub enum DataError {
75    #[error("Couldn't read from VMO")]
76    VmoReadError(#[source] zxs::Status),
77
78    #[error("Encountered an unrecognized variant of fuchsia.mem.Data")]
79    UnrecognizedDataVariant,
80}
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85    use futures::StreamExt;
86    use std::sync::Arc;
87    use vfs::directory::entry::{DirectoryEntry, EntryInfo, GetEntryInfo, OpenRequest};
88    use vfs::execution_scope::ExecutionScope;
89    use vfs::file::vmo::read_only;
90    use vfs::file::{FileLike, FileOptions};
91    use vfs::object_request::Representation;
92    use vfs::{pseudo_directory, ObjectRequestRef};
93    use zx_status::Status;
94
95    #[fuchsia::test]
96    async fn bytes_from_read_only() {
97        let fs = pseudo_directory! {
98            // `read_only` is a vmo file, returns the buffer in OnOpen
99            "foo" => read_only("hello, world!"),
100        };
101        let directory = vfs::directory::serve_read_only(fs);
102
103        let data = open_file_data(&directory, "foo").await.unwrap();
104        match bytes_from_data(&data).unwrap() {
105            Cow::Owned(b) => assert_eq!(b, b"hello, world!"),
106            _ => panic!("must produce an owned value from reading contents of fmem::Data::Buffer"),
107        }
108    }
109
110    /// Test that we get a VMO when the server supports `File/GetBackingMemory`.
111    #[fuchsia::test]
112    async fn bytes_from_vmo_from_get_buffer() {
113        let vmo_data = b"hello, world!";
114        let fs = pseudo_directory! {
115            "foo" => read_only(vmo_data),
116        };
117        let directory = vfs::directory::serve_read_only(fs);
118
119        let data = open_file_data(&directory, "foo").await.unwrap();
120        match bytes_from_data(&data).unwrap() {
121            Cow::Owned(b) => assert_eq!(b, vmo_data),
122            _ => panic!("must produce an owned value from reading contents of fmem::Data::Buffer"),
123        }
124    }
125
126    /// Test that we correctly fall back to reading through FIDL calls in a channel if the server
127    /// doesn't support returning a VMO.
128    #[fuchsia::test]
129    async fn bytes_from_channel_fallback() {
130        // This test File does not handle `File/GetBackingMemory` request, but will return
131        // b"hello, world!" on File/Read`.
132        struct NonVMOTestFile;
133
134        impl DirectoryEntry for NonVMOTestFile {
135            fn open_entry(self: Arc<Self>, request: OpenRequest<'_>) -> Result<(), Status> {
136                request.open_file(self)
137            }
138        }
139
140        impl GetEntryInfo for NonVMOTestFile {
141            fn entry_info(&self) -> EntryInfo {
142                EntryInfo::new(fio::INO_UNKNOWN, fio::DirentType::File)
143            }
144        }
145
146        impl vfs::node::Node for NonVMOTestFile {
147            async fn get_attributes(
148                &self,
149                _requested_attributes: fio::NodeAttributesQuery,
150            ) -> Result<fio::NodeAttributes2, Status> {
151                Err(Status::NOT_SUPPORTED)
152            }
153        }
154
155        impl FileLike for NonVMOTestFile {
156            fn open(
157                self: Arc<Self>,
158                scope: ExecutionScope,
159                _options: FileOptions,
160                object_request: ObjectRequestRef<'_>,
161            ) -> Result<(), Status> {
162                struct Connection;
163                impl Representation for Connection {
164                    type Protocol = fio::FileMarker;
165
166                    async fn get_representation(
167                        &self,
168                        _requested_attributes: fio::NodeAttributesQuery,
169                    ) -> Result<fio::Representation, Status> {
170                        unreachable!()
171                    }
172
173                    async fn node_info(&self) -> Result<fio::NodeInfoDeprecated, Status> {
174                        unreachable!()
175                    }
176                }
177                let connection = Connection;
178                let object_request = object_request.take();
179                scope.spawn(async move {
180                    if let Ok(mut file_requests) =
181                        object_request.into_request_stream(&connection).await
182                    {
183                        let mut have_sent_bytes = false;
184                        while let Some(Ok(request)) = file_requests.next().await {
185                            match request {
186                                fio::FileRequest::GetBackingMemory { flags: _, responder } => {
187                                    responder.send(Err(Status::NOT_SUPPORTED.into_raw())).unwrap()
188                                }
189                                fio::FileRequest::Read { count: _, responder } => {
190                                    let to_send: &[u8] = if !have_sent_bytes {
191                                        have_sent_bytes = true;
192                                        b"hello, world!"
193                                    } else {
194                                        &[]
195                                    };
196                                    responder.send(Ok(to_send)).unwrap();
197                                }
198                                unexpected => unimplemented!("{:#?}", unexpected),
199                            }
200                        }
201                    }
202                });
203                Ok(())
204            }
205        }
206
207        let fs = pseudo_directory! {
208            "foo" => Arc::new(NonVMOTestFile),
209        };
210        let directory = vfs::directory::serve_read_only(fs);
211
212        let data = open_file_data(&directory, "foo").await.unwrap();
213        let data = bytes_from_data(&data).unwrap();
214        assert_eq!(
215            data,
216            Cow::Borrowed(b"hello, world!"),
217            "must produce a borrowed value from fmem::Data::Bytes"
218        );
219    }
220}
mem_util/lib.rs

mem_util/
lib.rs
