_wlan_fullmac_mlme_c_rustc_static/
lib.rs

Help
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
5use fidl_fuchsia_wlan_fullmac as fidl_fullmac;
6use log::error;
7use std::ffi::c_void;
8use wlan_ffi_transport::completers::Completer;
9use wlan_fullmac_mlme::device::FullmacDevice;
10use wlan_fullmac_mlme::{start_and_serve_on_separate_thread, FullmacMlmeHandle};
11
12/// Starts and runs the FullMAC MLME and SME futures on a separate thread. MLME will call the given
13/// `run_shutdown_completer` when it exits.
14///
15/// # Safety
16///
17/// This function is unsafe for the following reasons:
18///
19///   - This function cannot guarantee `fullmac_client_end_handle` is a valid handle.
20///   - This function cannot guarantee `run_shutdown_completer` is thread-safe.
21///   - This function cannot guarantee `shutdown_completer` points to a valid object when
22///     `run_shutdown_completer` is called.
23///
24/// By calling this function, the caller promises the following:
25///
26///   - The `fullmac_client_end_handle` is a valid handle.
27///   - The `run_shutdown_completer` function is thread-safe.
28///   - The `shutdown_completer` pointer will point to a valid object at least until
29///     `run_shutdown_completer` is called.
30///
31/// It is additionally the caller's responsibility to deallocate the returned FullmacMlmeHandle.
32/// The caller promises that they will eventually call `delete_fullmac_mlme` on the returned
33/// FullmacMlmeHandle.
34#[no_mangle]
35pub unsafe extern "C" fn start_fullmac_mlme(
36    fullmac_client_end_handle: zx::sys::zx_handle_t,
37    shutdown_completer: *mut c_void,
38    run_shutdown_completer: unsafe extern "C" fn(
39        shutdown_completer: *mut c_void,
40        status: zx::sys::zx_status_t,
41    ),
42) -> *mut FullmacMlmeHandle {
43    let fullmac_impl_sync_proxy = {
44        // Safety: This is safe because the caller promises `fullmac_client_end_handle`
45        // is a valid handle.
46        let handle = unsafe { fidl::Handle::from_raw(fullmac_client_end_handle) };
47        let channel = fidl::Channel::from(handle);
48        fidl_fullmac::WlanFullmacImpl_SynchronousProxy::new(channel)
49    };
50
51    // Safety: The provided closure is safe to send to another thread because shutdown_completer
52    // and run_shutdown_completer are thread-safe.
53    let shutdown_completer = unsafe {
54        Completer::new_unchecked(move |status| {
55            // Safety: This is safe because the caller of this function promised
56            // `run_shutdown_completer` is thread-safe and `shutdown_completer` is valid until
57            // its called.
58            run_shutdown_completer(shutdown_completer, status);
59        })
60    };
61
62    let device = FullmacDevice::new(fullmac_impl_sync_proxy);
63    match start_and_serve_on_separate_thread(device, shutdown_completer) {
64        Ok(mlme) => Box::into_raw(Box::new(mlme)),
65        Err(e) => {
66            error!("Failed to start FullMAC MLME: {}", e);
67            std::ptr::null_mut()
68        }
69    }
70}
71
72/// Request that the FullMAC MLME stops. This is non-blocking.
73///
74/// It is assumed that |mlme| is valid (i.e., the user has not called
75/// |delete_fullmac_mlme_handle| yet.
76///
77/// This should be synchronized with calls to |start_fullmac_mlme| and
78/// |delete_fullmac_mlme_handle|.
79///
80/// TODO(https://fxbug.dev/368323681): Consider replacing |stop_fullmac_mlme| and
81/// |delete_fullmac_mlme| with an internal FIDL protocol.
82#[no_mangle]
83pub extern "C" fn stop_fullmac_mlme(mlme: &mut FullmacMlmeHandle) {
84    mlme.request_stop();
85}
86
87/// Takes ownership of and deallocates the passed FullmacMlmeHandle.
88///
89/// If |mlme| is non-null, this will join the FullMAC MLME thread and block the calling thread
90/// until FullMAC MLME has exited.
91///
92/// If the user has not called |stop_fullmac_mlme| before |delete_fullmac_mlme_handle|, this will
93/// request that the FullMAC MLME thread stop before joining thread to avoid blocking forever.
94///
95/// TODO(https://fxbug.dev/368323681): Consider replacing |stop_fullmac_mlme| and
96/// |delete_fullmac_mlme| with an internal FIDL protocol.
97///
98/// # Safety
99///
100/// This fn accepts a raw pointer that is held by the FFI caller as a handle to
101/// the MLME. This API is fundamentally unsafe, and relies on the caller to
102/// pass the correct pointer and make no further calls on it later.
103#[no_mangle]
104pub unsafe extern "C" fn delete_fullmac_mlme_handle(mlme: *mut FullmacMlmeHandle) {
105    if !mlme.is_null() {
106        let mlme = Box::from_raw(mlme);
107        mlme.delete();
108    }
109}
_wlan_fullmac_mlme_c_rustc_static/lib.rs

_wlan_fullmac_mlme_c_rustc_static/
lib.rs
