blob: 15a15e8f0d84a5f15cd80e167e8b2ddcf7e4126b [file] [edit]
// Copyright 2026 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//! Helper routines for locating, spawning, and supervising the `ffx-uart-driver` executable.
//!
//! Manages driver binary resolution in host tool directories, background daemon process
//! spawning with redirected stdio, startup polling, log directory resolution, and graceful
//! or forceful process termination.
use crate::metadata::{
ConnectionMetadata, ConnectionStatus, UartProtocol, delete_metadata, get_socket_path,
read_metadata,
};
use crate::sys::{
DaemonLiveness, check_daemon_liveness, get_peer_pid, is_driver_running,
read_metrics_from_control_socket,
};
use fho::{Result, bug, user_error};
use nix::sys::signal::{Signal, kill};
use nix::unistd::Pid;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
pub const DAEMON_START_POLL_TIMEOUT: Duration = Duration::from_secs(5);
pub const DAEMON_START_POLL_INTERVAL: Duration = Duration::from_millis(50);
pub const DAEMON_SPAWN_ETXTBSY_MAX_RETRIES: u32 = 40;
pub const DAEMON_SPAWN_ETXTBSY_RETRY_DELAY: Duration = Duration::from_millis(5);
pub const SIGTERM_TIMEOUT: Duration = Duration::from_secs(1);
pub const SIGKILL_TIMEOUT: Duration = Duration::from_millis(200);
pub const SOCKET_PROBE_TIMEOUT: Duration = Duration::from_millis(100);
pub const MACOS_MAX_UNIX_PATH_LEN: usize = 104;
pub const LINUX_MAX_UNIX_PATH_LEN: usize = 108;
pub fn locate_driver(context: &ffx_config::EnvironmentContext) -> PathBuf {
if let Ok(path) = ffx_config::get_host_tool(context, "ffx-uart-driver") {
if path.exists() {
return path;
}
}
if let Ok(current_exe) = std::env::current_exe() {
if let Some(dir) = current_exe.parent() {
let fallback = dir.join("ffx-uart-driver");
if fallback.exists() {
return fallback;
}
}
}
PathBuf::from("ffx-uart-driver")
}
pub async fn wait_for_daemon_started(
context: &ffx_config::EnvironmentContext,
target: &str,
log_path: &Path,
) -> Result<u32> {
let start = Instant::now();
while start.elapsed() < DAEMON_START_POLL_TIMEOUT {
if let Some(pid) = check_startup_status(context, target, log_path)? {
return Ok(pid);
}
fuchsia_async::Timer::new(DAEMON_START_POLL_INTERVAL).await;
}
handle_startup_timeout(context, target, log_path).await
}
pub async fn terminate_process(pid: u32) -> Result<()> {
if pid <= 1 || pid > i32::MAX as u32 {
log::warn!("Refusing to terminate invalid process ID {}.", pid);
return Ok(());
}
let nix_pid = Pid::from_raw(pid as i32);
if let Err(nix::errno::Errno::EPERM) = kill(nix_pid, None) {
return Err(user_error!("Permission denied to terminate process {}", pid));
}
let _ = kill(nix_pid, Signal::SIGTERM);
if wait_for_process_exit(pid, SIGTERM_TIMEOUT).await {
return Ok(());
}
let _ = kill(nix_pid, Signal::SIGKILL);
if wait_for_process_exit(pid, SIGKILL_TIMEOUT).await {
return Ok(());
}
if is_driver_running(pid) { Err(user_error!("Failed to kill process {}", pid)) } else { Ok(()) }
}
pub async fn wait_for_process_exit(pid: u32, timeout: Duration) -> bool {
let start = Instant::now();
while start.elapsed() < timeout {
if !is_driver_running(pid) {
return true;
}
fuchsia_async::Timer::new(DAEMON_START_POLL_INTERVAL).await;
}
!is_driver_running(pid)
}
pub fn check_startup_status(
context: &ffx_config::EnvironmentContext,
target: &str,
log_path: &Path,
) -> Result<Option<u32>> {
match read_metadata(context, target) {
Ok(Some(meta)) => {
if meta.pid == 0 {
// Metadata file is transiently empty or partially written during startup;
// continue polling until timeout.
return Ok(None);
}
if !is_driver_running(meta.pid) {
return match meta.status {
ConnectionStatus::Error(reason) => Err(user_error!(
"Daemon failed to start: {}. Check driver logs at: {}",
reason,
log_path.display()
)),
_ => Err(user_error!(
"ffx-uart-driver started but exited immediately. Check driver logs at: {}",
log_path.display()
)),
};
}
match meta.status {
ConnectionStatus::Connected => Ok(Some(meta.pid)),
ConnectionStatus::Error(reason) => {
Err(user_error!("Connection failed: {}", reason))
}
ConnectionStatus::Connecting => Ok(None),
}
}
Ok(None) | Err(_) => Ok(None),
}
}
pub async fn handle_startup_timeout(
context: &ffx_config::EnvironmentContext,
target: &str,
log_path: &Path,
) -> Result<u32> {
match read_metadata(context, target) {
Ok(Some(meta)) => {
if is_driver_running(meta.pid) {
let socket_path = get_socket_path(context, target)?;
let control_socket_path =
socket_path.with_extension(uart_driver_api::CONTROL_SOCKET_EXTENSION);
let metrics_msg = if let Some(metrics) =
read_metrics_from_control_socket(&control_socket_path).await
{
format!(
" (stuck in 'Connecting' state with {} handshake failures)",
metrics.handshake_failures
)
} else {
" (stuck in 'Connecting' state)".to_string()
};
Err(user_error!(
"Timed out waiting for connection to be established for target {}{}.\n\
The target may not be responding. Check driver logs at: {}",
target,
metrics_msg,
log_path.display()
))
} else {
Err(user_error!(
"ffx-uart-driver started but exited. Check driver logs at: {}",
log_path.display()
))
}
}
_ => {
Err(user_error!("Timed out waiting for ffx-uart-driver to start for target {}", target))
}
}
}
pub fn get_or_create_log_dir(context: &ffx_config::EnvironmentContext) -> Result<PathBuf> {
let mut log_dir = match context.get::<PathBuf, _>("shared_data") {
Ok(p) => p,
Err(_) => context.get_shared_data_path().map_err(|e| bug!("{e:?}"))?,
};
log_dir.push("ffx_uart");
if !log_dir.exists() {
fs::create_dir_all(&log_dir).map_err(|e| bug!("{e:?}"))?;
}
Ok(log_dir)
}
pub fn get_driver_log_path(log_dir: &Path, socket_path: &Path) -> PathBuf {
let log_id = uart_driver_api::get_log_id_from_socket_path(socket_path);
uart_driver_api::get_driver_log_file_path(log_dir, log_id, 0)
}
pub fn validate_socket_path_len(path: &Path) -> Result<()> {
let path_len = path.to_string_lossy().as_bytes().len();
let max_len =
if cfg!(target_os = "macos") { MACOS_MAX_UNIX_PATH_LEN } else { LINUX_MAX_UNIX_PATH_LEN };
if path_len >= max_len {
return Err(user_error!(
"UNIX socket path exceeds limit ({} bytes, max {} bytes for OS)",
path_len,
max_len
));
}
Ok(())
}
pub async fn wait_for_parent_exit(mut child: std::process::Child) -> Result<()> {
let status = tokio::time::timeout(
DAEMON_START_POLL_TIMEOUT,
fuchsia_async::unblock(move || child.wait()),
)
.await
.map_err(|_| user_error!("Timed out waiting for driver parent process to exit"))?
.map_err(|e| user_error!("Failed to wait for driver parent process: {:?}", e))?;
if !status.success() {
return Err(user_error!("Driver parent process exited with error: {:?}", status));
}
Ok(())
}
pub fn build_driver_daemon_command(
driver_path: &Path,
context: &ffx_config::EnvironmentContext,
log_level: Option<&str>,
target: &str,
baud: std::num::NonZeroU32,
socket_path: &Path,
log_dir: &Path,
no_retry: bool,
) -> std::process::Command {
let mut cmd = std::process::Command::new(driver_path);
if let Some(isolate_root) = context.env_kind().isolate_root() {
cmd.env("FFX_ISOLATE_DIR", isolate_root);
}
if let Some(level) = log_level {
cmd.arg("--log-level").arg(level);
}
cmd.arg("uart-driver")
.arg("--target")
.arg(target)
.arg("--baud")
.arg(baud.to_string())
.arg("--socket")
.arg(socket_path)
.arg("--log-dir")
.arg(log_dir)
.arg("--background");
if no_retry {
cmd.arg("--no-retry");
}
cmd
}
pub async fn spawn_driver_daemon(
driver_path: &Path,
context: &ffx_config::EnvironmentContext,
log_level: Option<&str>,
target: &str,
baud: std::num::NonZeroU32,
socket_path: &Path,
log_dir: &Path,
no_retry: bool,
) -> Result<()> {
let mut cmd = build_driver_daemon_command(
driver_path,
context,
log_level,
target,
baud,
socket_path,
log_dir,
no_retry,
);
log::info!("Spawning UART driver: {:?}", cmd);
let mut attempts = 0;
let child = loop {
match cmd.spawn() {
Ok(child) => break child,
Err(e)
if (e.kind() == std::io::ErrorKind::ExecutableFileBusy
|| e.raw_os_error() == Some(nix::libc::ETXTBSY))
&& attempts < DAEMON_SPAWN_ETXTBSY_MAX_RETRIES =>
{
attempts += 1;
fuchsia_async::Timer::new(DAEMON_SPAWN_ETXTBSY_RETRY_DELAY).await;
}
Err(e) => return Err(user_error!("Failed to spawn ffx-uart-driver: {:?}", e)),
}
};
wait_for_parent_exit(child).await
}
pub fn cleanup_target_files(context: &ffx_config::EnvironmentContext, target: &str) {
if let Err(e) = delete_metadata(context, target) {
log::warn!("Failed to delete metadata for target {target}: {:?}", e);
}
if let Ok(socket_path) = get_socket_path(context, target) {
if socket_path.exists() {
if let Err(e) = fs::remove_file(&socket_path) {
log::warn!("Failed to remove socket file at {}: {:?}", socket_path.display(), e);
}
}
let control_path = socket_path.with_extension(uart_driver_api::CONTROL_SOCKET_EXTENSION);
if control_path.exists() {
if let Err(e) = fs::remove_file(&control_path) {
log::warn!(
"Failed to remove control socket file at {}: {:?}",
control_path.display(),
e
);
}
}
}
}
pub async fn get_active_connections(
context: &ffx_config::EnvironmentContext,
) -> Result<Vec<ConnectionMetadata>> {
let mut list_entries = Vec::new();
let mut shared_path = match context.get::<PathBuf, _>("shared_data") {
Ok(p) => p,
Err(_) => context.get_shared_data_path().map_err(|e| bug!("{e:?}"))?,
};
shared_path.push("ffx_uart");
if shared_path.exists() {
if let Ok(entries) = fs::read_dir(&shared_path) {
for entry in entries.flatten() {
let path = entry.path();
if !path.is_dir() {
if let Some(filename) = path.file_name().and_then(|f| f.to_str()) {
let dot_ext = format!(".{}", uart_driver_api::UNIX_SOCKET_EXTENSION);
if let Some(rest) = filename.strip_prefix("ffx_uart_") {
if let Some(target_id) = rest.strip_suffix(&dot_ext) {
if !target_id.is_empty() {
if let Some(meta) =
inspect_active_socket(context, &path, target_id).await
{
list_entries.push(meta);
}
}
}
}
}
}
}
}
}
Ok(list_entries)
}
pub async fn inspect_active_socket(
context: &ffx_config::EnvironmentContext,
path: &Path,
target_id: &str,
) -> Option<ConnectionMetadata> {
let meta_path = path.with_extension(uart_driver_api::METADATA_FILE_EXTENSION);
let control_socket_path = path.with_extension(uart_driver_api::CONTROL_SOCKET_EXTENSION);
if meta_path.exists() {
read_and_validate_active_metadata(context, &meta_path, &control_socket_path, target_id)
.await
} else {
probe_unregistered_active_socket(context, path, &control_socket_path, target_id).await
}
}
pub async fn read_and_validate_active_metadata(
_context: &ffx_config::EnvironmentContext,
meta_path: &Path,
control_socket_path: &Path,
target_id: &str,
) -> Option<ConnectionMetadata> {
let content = fs::read_to_string(meta_path).ok()?;
let mut meta = serde_json::from_str::<ConnectionMetadata>(&content).ok()?;
meta.id = Some(target_id.to_string());
if check_daemon_liveness(meta.pid, control_socket_path).await != DaemonLiveness::Alive {
return None;
}
Some(meta)
}
pub async fn probe_unregistered_active_socket(
context: &ffx_config::EnvironmentContext,
path: &Path,
control_socket_path: &Path,
target_id: &str,
) -> Option<ConnectionMetadata> {
let probe_target = if control_socket_path.exists() { control_socket_path } else { path };
let stream =
tokio::time::timeout(SOCKET_PROBE_TIMEOUT, tokio::net::UnixStream::connect(probe_target))
.await
.ok()?
.ok()?;
let std_stream = stream.into_std().ok()?;
let pid = get_peer_pid(&std_stream).ok()?;
if check_daemon_liveness(pid, control_socket_path).await != DaemonLiveness::Alive {
return None;
}
let target = uart_driver_api::socket_path_to_target_path(path, context);
Some(ConnectionMetadata {
pid,
target,
status: ConnectionStatus::Connected,
id: Some(target_id.to_string()),
baud: None,
protocol: UartProtocol::Unknown,
log_level: None,
nodename: None,
serial: None,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[fuchsia::test]
fn test_validate_socket_path_len() {
let short_path = Path::new("/tmp/test.sock");
assert!(validate_socket_path_len(short_path).is_ok());
let oversized = PathBuf::from(format!("/tmp/{}", "a".repeat(200)));
assert!(validate_socket_path_len(&oversized).is_err());
}
#[fuchsia::test]
fn test_get_driver_log_path() {
let log_dir = Path::new("/tmp/logs");
let sock_path = Path::new("/tmp/ffx_uart_12345.sock");
let log_path = get_driver_log_path(log_dir, sock_path);
assert!(log_path.starts_with(log_dir));
assert!(log_path.to_string_lossy().ends_with(".0.log"));
}
#[fuchsia::test]
fn test_build_driver_daemon_command() {
let env = ffx_config::test_init().unwrap();
let driver_path = Path::new("/bin/ffx-uart-driver");
let socket_path = Path::new("/tmp/test.sock");
let log_dir = Path::new("/tmp/logs");
let cmd = build_driver_daemon_command(
driver_path,
&env.context,
Some("debug"),
"/dev/ttyUSB0",
std::num::NonZeroU32::new(115200).unwrap(),
socket_path,
log_dir,
true,
);
let args: Vec<String> = cmd.get_args().map(|a| a.to_string_lossy().into_owned()).collect();
assert!(args.contains(&"--log-level".to_string()));
assert!(args.contains(&"debug".to_string()));
assert!(args.contains(&"uart-driver".to_string()));
assert!(args.contains(&"--target".to_string()));
assert!(args.contains(&"/dev/ttyUSB0".to_string()));
assert!(args.contains(&"--baud".to_string()));
assert!(args.contains(&"115200".to_string()));
assert!(args.contains(&"--socket".to_string()));
assert!(args.contains(&"/tmp/test.sock".to_string()));
assert!(args.contains(&"--log-dir".to_string()));
assert!(args.contains(&"/tmp/logs".to_string()));
assert!(args.contains(&"--background".to_string()));
assert!(args.contains(&"--no-retry".to_string()));
}
#[fuchsia::test]
fn test_check_startup_status_transient_empty_metadata_returns_none() {
let temp = tempfile::tempdir().unwrap();
let env = ffx_config::test_env()
.runtime_config("shared_data", temp.path().to_str().unwrap())
.build()
.unwrap();
let target = "/dev/ttyUSB0";
let meta_path = crate::metadata::get_metadata_path(&env.context, target).unwrap();
if let Some(parent) = meta_path.parent() {
fs::create_dir_all(parent).unwrap();
}
fs::write(&meta_path, b"").unwrap();
let log_path = temp.path().join("driver.log");
assert_eq!(check_startup_status(&env.context, target, &log_path).unwrap(), None);
}
}