使用单个 I/O 线程的 Linux 串口 / Linux UART with one I/O thread. More...

#include <linux_uart.hpp>

Inheritance diagram for LibXR::LinuxUART:

Collaboration diagram for LibXR::LinuxUART:

Public Member Functions
	LinuxUART (const char *dev_path, unsigned int baudrate=115200, Parity parity=Parity::NO_PARITY, uint8_t data_bits=8, uint8_t stop_bits=1, uint32_t tx_queue_size=5, size_t buffer_size=512, size_t thread_stack_size=65536)
	通过设备路径构造串口 / Construct a UART by device path.

	LinuxUART (const std::string &vid, const std::string &pid, unsigned int baudrate=115200, Parity parity=Parity::NO_PARITY, uint8_t data_bits=8, uint8_t stop_bits=1, uint32_t tx_queue_size=5, size_t buffer_size=512, size_t thread_stack_size=65536)
	通过 USB VID/PID 构造串口 / Construct a UART by USB VID/PID.

	LinuxUART (const std::string &vid, const std::string &pid, const std::string &control_interface_name, unsigned int baudrate=115200, Parity parity=Parity::NO_PARITY, uint8_t data_bits=8, uint8_t stop_bits=1, uint32_t tx_queue_size=5, size_t buffer_size=512, size_t thread_stack_size=65536)
	按 USB 控制接口名称构造串口 / Construct a UART by USB control interface.

	LinuxUART (const std::string &vid, const std::string &pid, const std::string &control_interface_name, const std::string &serial, unsigned int baudrate=115200, Parity parity=Parity::NO_PARITY, uint8_t data_bits=8, uint8_t stop_bits=1, uint32_t tx_queue_size=5, size_t buffer_size=512, size_t thread_stack_size=65536)
	按 USB 接口和序列号构造串口 / Construct a UART by USB interface and serial.

std::string	GetByPathForTTY (const std::string &tty_name)
	查找设备的稳定路径 / Find a stable path for a TTY.

void	SetLowLatency (int fd)
	尝试启用设备低延迟选项 / Try to enable the device low-latency option.

ErrorCode	SetConfig (UART::Configuration config, bool=false) override
	提交串口配置请求 / Submit a UART configuration request.

Public Member Functions inherited from LibXR::UART
template<typename ReadPortType = ReadPort, typename WritePortType = WritePort>
	UART (ReadPortType read_port, WritePortType write_port)
	UART 构造函数 / UART constructor.

template<typename OperationType , typename = std::enable_if_t<std::is_base_of_v< WriteOperation, std::decay_t<OperationType>>>>
ErrorCode	Write (ConstRawData data, OperationType &&op, bool in_isr=false)

template<typename OperationType , typename = std::enable_if_t<std::is_base_of_v< ReadOperation, std::decay_t<OperationType>>>>
ErrorCode	Read (RawData data, OperationType &&op, bool in_isr=false)

Static Public Member Functions
static bool	FindUSBTTYByVidPid (const std::string &target_vid, const std::string &target_pid, std::string &tty_path)
	查找匹配的 USB 串口设备 / Find a matching USB TTY device.

static bool	FindUSBTTYByVidPid (const std::string &target_vid, const std::string &target_pid, const std::string &target_control_interface_name, std::string &tty_path)
	查找匹配的 USB 串口设备 / Find a matching USB TTY device.

static bool	FindUSBTTYByVidPid (const std::string &target_vid, const std::string &target_pid, const std::string &target_control_interface_name, const std::string &target_serial, std::string &tty_path)
	查找匹配的 USB 串口设备 / Find a matching USB TTY device.

Friends
class	Detail::LinuxUARTReadPort

Additional Inherited Members
Public Types inherited from LibXR::UART
enum class	Parity : uint8_t { NO_PARITY = 0 , EVEN = 1 , ODD = 2 }
	奇偶校验模式 / Parity mode More...

Public Attributes inherited from LibXR::UART
ReadPort *	read_port_
	读取端口 / Read port

WritePort *	write_port_
	写入端口 / Write port

Detailed Description

使用单个 I/O 线程的 Linux 串口 / Linux UART with one I/O thread.

支持设备路径和 USB VID/PID、控制接口名称、序列号匹配。线程统一负责打开、关闭、接收、发送、配置和重连，读写端口的通知只唤醒该线程。 Supports device paths or USB VID/PID, control-interface name, and serial matching. One thread handles open, close, RX, TX, configuration, and reconnect. Port callbacks only wake that thread.

Note: 写完成表示数据已被 Linux 接收。短写保留剩余部分；部分发送后断线会以 FAILED 结束该请求，尚未发送的后续请求保留到重连。接收队列满时暂停读取设备。 Writes complete on kernel acceptance. Short writes retain the suffix; a disconnect after partial transmission fails that request and retains later requests for reconnect. Full RX queues pause device reads.

Precondition: 读写操作遵守端口约定。对象用于长期运行，线程结束前须保持对象和端口有效。 Follow the port contracts. Keep this startup-lifetime object and its ports valid for the lifetime of the I/O thread.

Definition at line 73 of file linux_uart.hpp.

Constructor & Destructor Documentation

◆ LinuxUART() [1/4]

LibXR::LinuxUART::LinuxUART	(	const char *	dev_path,
		unsigned int	baudrate = 115200,
		Parity	parity = Parity::NO_PARITY,
		uint8_t	data_bits = 8,
		uint8_t	stop_bits = 1,
		uint32_t	tx_queue_size = 5,
		size_t	buffer_size = 512,
		size_t	thread_stack_size = 65536 )

inline

通过设备路径构造串口 / Construct a UART by device path.

Parameters

dev_path	设备路径 / Device path.
baudrate	初始波特率，必须大于零 / Positive initial baud rate.
parity	奇偶校验方式 / Parity mode.
data_bits	数据位数，范围 5 至 8 / Data bits, from 5 to 8.
stop_bits	停止位数，1 或 2 / Stop bits, 1 or 2.
tx_queue_size	请求队列容量，必须大于零 / Positive TX request capacity.
buffer_size	每个方向的字节队列容量，必须大于零 / Positive per-direction capacity.
thread_stack_size	I/O 线程栈大小，单位为字节 / I/O thread stack size in bytes.

Note: 路径不存在时等待；路径存在后等待线程首次尝试打开设备，失败由线程继续重连。 Waits for the path, then for the thread's first open attempt. Failure is recovered by the thread's reconnect loop.

Definition at line 101 of file linux_uart.hpp.

      : UART(&_read_port, &_write_port),
        rx_buff_(new uint8_t[buffer_size]),
        buff_size_(buffer_size),
        config_{baudrate, parity, data_bits, stop_bits},
        _read_port(buffer_size, *this),
        _write_port(tx_queue_size, buffer_size)
  {
    ASSERT(buff_size_ > 0);
    ASSERT(tx_queue_size > 0);
 
    while (!std::filesystem::exists(dev_path))
    {
      XR_LOG_WARN("Cannot find UART device: %s, retrying...", dev_path);
      Thread::Sleep(100);
    }
 
    device_path_ = GetByPathForTTY(dev_path);
 
    StartIoOwner(thread_stack_size);
  }

◆ LinuxUART() [2/4]

LibXR::LinuxUART::LinuxUART	(	const std::string &	vid,
		const std::string &	pid,
		unsigned int	baudrate = 115200,
		Parity	parity = Parity::NO_PARITY,
		uint8_t	data_bits = 8,
		uint8_t	stop_bits = 1,
		uint32_t	tx_queue_size = 5,
		size_t	buffer_size = 512,
		size_t	thread_stack_size = 65536 )

inline

通过 USB VID/PID 构造串口 / Construct a UART by USB VID/PID.

Parameters

vid	USB 厂商 ID 字符串 / USB vendor ID string.
pid	USB 产品 ID 字符串 / USB product ID string.
baudrate	初始波特率，必须大于零 / Positive initial baud rate.
parity	奇偶校验方式 / Parity mode.
data_bits	数据位数，范围 5 至 8 / Data bits, from 5 to 8.
stop_bits	停止位数，1 或 2 / Stop bits, 1 or 2.
tx_queue_size	请求队列容量，必须大于零 / Positive TX request capacity.
buffer_size	每个方向的字节队列容量，必须大于零 / Positive per-direction capacity.
thread_stack_size	I/O 线程栈大小，单位为字节 / I/O thread stack size in bytes.

Definition at line 139 of file linux_uart.hpp.

      : LinuxUART(vid, pid, "", "", baudrate, parity, data_bits, stop_bits, tx_queue_size,
                  buffer_size, thread_stack_size)
  {
  }

◆ LinuxUART() [3/4]

LibXR::LinuxUART::LinuxUART	(	const std::string &	vid,
		const std::string &	pid,
		const std::string &	control_interface_name,
		unsigned int	baudrate = 115200,
		Parity	parity = Parity::NO_PARITY,
		uint8_t	data_bits = 8,
		uint8_t	stop_bits = 1,
		uint32_t	tx_queue_size = 5,
		size_t	buffer_size = 512,
		size_t	thread_stack_size = 65536 )

inline

按 USB 控制接口名称构造串口 / Construct a UART by USB control interface.

Parameters

vid	USB 厂商 ID 字符串 / USB vendor ID string.
pid	USB 产品 ID 字符串 / USB product ID string.
control_interface_name	控制接口名称，空值不限制 / Control interface, empty for any.
baudrate	初始波特率，必须大于零 / Positive initial baud rate.
parity	奇偶校验方式 / Parity mode.
data_bits	数据位数，范围 5 至 8 / Data bits, from 5 to 8.
stop_bits	停止位数，1 或 2 / Stop bits, 1 or 2.
tx_queue_size	请求队列容量，必须大于零 / Positive TX request capacity.
buffer_size	每个方向的字节队列容量，必须大于零 / Positive per-direction capacity.
thread_stack_size	I/O 线程栈大小，单位为字节 / I/O thread stack size in bytes.

Definition at line 163 of file linux_uart.hpp.

      : LinuxUART(vid, pid, control_interface_name, "", baudrate, parity, data_bits,
                  stop_bits, tx_queue_size, buffer_size, thread_stack_size)
  {
  }

◆ LinuxUART() [4/4]

LibXR::LinuxUART::LinuxUART	(	const std::string &	vid,
		const std::string &	pid,
		const std::string &	control_interface_name,
		const std::string &	serial,
		unsigned int	baudrate = 115200,
		Parity	parity = Parity::NO_PARITY,
		uint8_t	data_bits = 8,
		uint8_t	stop_bits = 1,
		uint32_t	tx_queue_size = 5,
		size_t	buffer_size = 512,
		size_t	thread_stack_size = 65536 )

inline

按 USB 接口和序列号构造串口 / Construct a UART by USB interface and serial.

Parameters

vid	USB 厂商 ID 字符串 / USB vendor ID string.
pid	USB 产品 ID 字符串 / USB product ID string.
control_interface_name	控制接口名称，空值不限制 / Control interface, empty for any.
serial	设备序列号，空值不限制 / Device serial number, empty for any.
baudrate	初始波特率，必须大于零 / Positive initial baud rate.
parity	奇偶校验方式 / Parity mode.
data_bits	数据位数，范围 5 至 8 / Data bits, from 5 to 8.
stop_bits	停止位数，1 或 2 / Stop bits, 1 or 2.
tx_queue_size	请求队列容量，必须大于零 / Positive TX request capacity.
buffer_size	每个方向的字节队列容量，必须大于零 / Positive per-direction capacity.
thread_stack_size	I/O 线程栈大小，单位为字节 / I/O thread stack size in bytes.

Note: 等待匹配设备出现；多个匹配时按路径排序选择首项。CDC ACM 匹配控制接口名称。 Waits for a match; selects the first sorted path on ambiguity. CDC ACM matching uses the control-interface name.

Definition at line 192 of file linux_uart.hpp.

      : UART(&_read_port, &_write_port),
        rx_buff_(new uint8_t[buffer_size]),
        buff_size_(buffer_size),
        config_{baudrate, parity, data_bits, stop_bits},
        _read_port(buffer_size, *this),
        _write_port(tx_queue_size, buffer_size)
  {
    ASSERT(tx_queue_size > 0);
    ASSERT(buff_size_ > 0);
    while (!FindUSBTTYByVidPid(vid, pid, control_interface_name, serial, device_path_))
    {
      XR_LOG_WARN(
          "Cannot find USB TTY device with VID=%s PID=%s SERIAL=%s CONTROL_INTERFACE=%s, "
          "retrying...",
          vid.c_str(), pid.c_str(), serial.empty() ? "*" : serial.c_str(),
          control_interface_name.empty() ? "*" : control_interface_name.c_str());
      Thread::Sleep(100);
    }
 
    XR_LOG_PASS("Found USB TTY: %s", device_path_.c_str());
 
    if (std::filesystem::exists(device_path_) == false)
    {
      XR_LOG_ERROR("Cannot find UART device: %s", device_path_.c_str());
      REQUIRE(false);
      return;
    }
 
    device_path_ = GetByPathForTTY(device_path_);
 
    StartIoOwner(thread_stack_size);
  }

Member Function Documentation

◆ FindUSBTTYByVidPid() [1/3]

static bool LibXR::LinuxUART::FindUSBTTYByVidPid	(	const std::string &	target_vid,
		const std::string &	target_pid,
		const std::string &	target_control_interface_name,
		const std::string &	target_serial,
		std::string &	tty_path )

inlinestatic

查找匹配的 USB 串口设备 / Find a matching USB TTY device.

Returns: 找到匹配路径时返回 true / True when a matching path is found.

Definition at line 287 of file linux_uart.hpp.

  {
    struct udev* udev = udev_new();
    if (!udev)
    {
      XR_LOG_ERROR("Cannot create udev context");
      return false;
    }
 
    struct udev_enumerate* enumerate = udev_enumerate_new(udev);
    udev_enumerate_add_match_subsystem(enumerate, "tty");
    udev_enumerate_scan_devices(enumerate);
 
    struct udev_list_entry* devices = udev_enumerate_get_list_entry(enumerate);
    struct udev_list_entry* entry = nullptr;
    std::vector<std::string> matches;
 
    udev_list_entry_foreach(entry, devices)
    {
      const char* path = udev_list_entry_get_name(entry);
      struct udev_device* tty_dev = udev_device_new_from_syspath(udev, path);
      if (!tty_dev)
      {
        continue;
      }
 
      struct udev_device* usb_dev =
          udev_device_get_parent_with_subsystem_devtype(tty_dev, "usb", "usb_device");
      struct udev_device* usb_interface =
          udev_device_get_parent_with_subsystem_devtype(tty_dev, "usb", "usb_interface");
 
      if (usb_dev)
      {
        const char* vid = udev_device_get_sysattr_value(usb_dev, "idVendor");
        const char* pid = udev_device_get_sysattr_value(usb_dev, "idProduct");
        const char* serial = udev_device_get_sysattr_value(usb_dev, "serial");
        const char* control_interface_name = nullptr;
        if (usb_interface)
        {
          // Linux cdc_acm 的 tty 父节点对应 CDC 控制接口。
          // The parent of a Linux cdc_acm TTY is the CDC control interface.
          control_interface_name =
              udev_device_get_sysattr_value(usb_interface, "interface");
        }
 
        if (vid && pid && target_vid == vid && target_pid == pid &&
            (target_serial.empty() || (serial && target_serial == serial)) &&
            (target_control_interface_name.empty() ||
             (control_interface_name &&
              target_control_interface_name == control_interface_name)))
        {
          const char* devnode = udev_device_get_devnode(tty_dev);
          if (devnode)
          {
            matches.emplace_back(devnode);
          }
        }
      }
 
      udev_device_unref(tty_dev);
    }
 
    udev_enumerate_unref(enumerate);
    udev_unref(udev);
    if (matches.empty())
    {
      return false;
    }
 
    std::sort(matches.begin(), matches.end());
    tty_path = matches.front();
 
    if (matches.size() > 1)
    {
      XR_LOG_WARN(
          "Multiple USB TTY devices found with VID=%s PID=%s SERIAL=%s "
          "CONTROL_INTERFACE=%s, using %s. Specify serial or control interface name to "
          "disambiguate.",
          target_vid.c_str(), target_pid.c_str(),
          target_serial.empty() ? "*" : target_serial.c_str(),
          target_control_interface_name.empty() ? "*"
                                                : target_control_interface_name.c_str(),
          tty_path.c_str());
    }
 
    return true;
  }

◆ FindUSBTTYByVidPid() [2/3]

static bool LibXR::LinuxUART::FindUSBTTYByVidPid	(	const std::string &	target_vid,
		const std::string &	target_pid,
		const std::string &	target_control_interface_name,
		std::string &	tty_path )

inlinestatic

查找匹配的 USB 串口设备 / Find a matching USB TTY device.

Returns: 找到匹配路径时返回 true / True when a matching path is found.

Definition at line 274 of file linux_uart.hpp.

  {
    return FindUSBTTYByVidPid(target_vid, target_pid, target_control_interface_name, "",
                              tty_path);
  }

◆ FindUSBTTYByVidPid() [3/3]

static bool LibXR::LinuxUART::FindUSBTTYByVidPid	(	const std::string &	target_vid,
		const std::string &	target_pid,
		std::string &	tty_path )

inlinestatic

查找匹配的 USB 串口设备 / Find a matching USB TTY device.

Returns: 找到匹配路径时返回 true / True when a matching path is found.

Definition at line 264 of file linux_uart.hpp.

  {
    return FindUSBTTYByVidPid(target_vid, target_pid, "", "", tty_path);
  }

◆ GetByPathForTTY()

std::string LibXR::LinuxUART::GetByPathForTTY ( const std::string & tty_name )

inline

查找设备的稳定路径 / Find a stable path for a TTY.

Parameters

tty_name 原始设备路径 / Original device path.

Returns: 匹配的 by-path 链接，未找到时返回原路径 / Matching by-path link, or original path.

Definition at line 236 of file linux_uart.hpp.

  {
    const std::string BASE = "/dev/serial/by-path";
    if (strncmp(tty_name.c_str(), BASE.c_str(), BASE.length()) == 0 ||
        !std::filesystem::exists(BASE))
    {
      return tty_name;
    }
    for (const auto& entry : std::filesystem::directory_iterator(BASE))
    {
      std::error_code ec;
      const auto full = std::filesystem::canonical(entry.path(), ec);
      if (ec)
      {
        continue;
      }
      if (full == tty_name)
      {
        return entry.path().string();  // 返回稳定链接 / Return the stable link.
      }
    }
    return tty_name;  // 保留原路径 / Keep the original path.
  }

◆ SetConfig()

ErrorCode LibXR::LinuxUART::SetConfig	(	UART::Configuration	config,
		bool	= false )

inlineoverridevirtual

提交串口配置请求 / Submit a UART configuration request.

Parameters

config 目标配置 / Requested configuration.

Returns: 接纳返回 OK，已有待处理配置返回 BUSY，参数无效返回 ARG_ERR。 OK on admission, BUSY for an occupied slot, ARG_ERR for invalid parameters.

Note: OK 不表示已经生效。线程等待当前部分写入结束及内核输出队列排空后应用。断线时保留请求，重连时使用新配置；应用失败继续保留请求。 OK does not mean applied. The thread finishes the partial front and drains kernel output before applying. Pending configuration survives disconnect or application failure and is used on reopen.

Implements LibXR::UART.

Definition at line 406 of file linux_uart.hpp.

  {
    if (ValidateConfig(config) != ErrorCode::OK)
    {
      return ErrorCode::ARG_ERR;
    }
 
    uint8_t expected = static_cast<uint8_t>(ConfigState::EMPTY);
    if (!config_state_.compare_exchange_strong(
            expected, static_cast<uint8_t>(ConfigState::RESERVED),
            std::memory_order_acq_rel, std::memory_order_acquire))
    {
      return ErrorCode::BUSY;
    }
 
    requested_config_ = config;
    config_state_.store(static_cast<uint8_t>(ConfigState::PUBLISHED),
                        std::memory_order_release);
    NotifyIoOwner();
    return ErrorCode::OK;
  }

◆ SetLowLatency()

void LibXR::LinuxUART::SetLowLatency ( int fd )

inline

尝试启用设备低延迟选项 / Try to enable the device low-latency option.

Parameters

fd	已打开的设备描述符 / Open device descriptor.

Note: 仅在线程处理配置时调用，不支持该选项的设备直接跳过。 Called during owner-side configuration; skips unsupported devices.

Definition at line 384 of file linux_uart.hpp.

  {
    struct serial_struct serinfo{};
    if (ioctl(fd, TIOCGSERIAL, &serinfo) != 0)
    {
      return;
    }
    serinfo.flags |= ASYNC_LOW_LATENCY;
    ioctl(fd, TIOCSSERIAL, &serinfo);
  }

Friends And Related Symbol Documentation

◆ Detail::LinuxUARTReadPort

friend class Detail::LinuxUARTReadPort

friend

Definition at line 75 of file linux_uart.hpp.

The documentation for this class was generated from the following file:

driver/linux/linux_uart.hpp

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ LinuxUART() [1/4]

◆ LinuxUART() [2/4]

◆ LinuxUART() [3/4]

◆ LinuxUART() [4/4]

Member Function Documentation

◆ FindUSBTTYByVidPid() [1/3]

◆ FindUSBTTYByVidPid() [2/3]

◆ FindUSBTTYByVidPid() [3/3]

◆ GetByPathForTTY()

◆ SetConfig()

◆ SetLowLatency()

Friends And Related Symbol Documentation

◆ Detail::LinuxUARTReadPort