LibXR::LinuxUART Class Reference

Linux UART 串口驱动实现 / Linux UART driver implementation. 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)
	通过设备路径构造 UART / Construct 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 构造 UART / Construct 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 VID/PID/control interface name 构造 UART Construct UART by USB VID/PID/control interface name
	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 VID/PID/control interface name/serial 构造 UART Construct UART by USB VID/PID/control interface name/serial
std::string	GetByPathForTTY (const std::string &tty_name)
void	SetLowLatency (int fd)
ErrorCode	SetConfig (UART::Configuration config) override
	设置 UART 配置 / Sets the UART configuration
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)
static bool	FindUSBTTYByVidPid (const std::string &target_vid, const std::string &target_pid, const std::string &target_control_interface_name, std::string &tty_path)
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)
static ErrorCode	ReadFun (ReadPort &, bool)
static ErrorCode	WriteFun (WritePort &port, bool)

Private Member Functions
void	RxLoop ()
void	TxLoop ()

Private Attributes
int	fd_ = -1
bool	connected_ = true
Configuration	config_
std::string	device_path_
Thread	rx_thread_
Thread	tx_thread_
uint8_t *	rx_buff_ = nullptr
uint8_t *	tx_buff_ = nullptr
size_t	buff_size_ = 0
Semaphore	write_sem_
Mutex	read_mutex_
ReadPort	_read_port
WritePort	_write_port

Additional Inherited Members
Public Types inherited from LibXR::UART
enum class	Parity : uint8_t { NO_PARITY = 0 , EVEN = 1 , ODD = 2 }
	奇偶校验模式 / Parity mode More...
Data Fields inherited from LibXR::UART
ReadPort *	read_port_
	读取端口 / Read port
WritePort *	write_port_
	写入端口 / Write port

Detailed Description

Linux UART 串口驱动实现 / Linux UART driver implementation.

支持按设备路径或 USB VID/PID(/control interface name[/serial]) 自动发现并创建 UART 通道。 Supports UART creation by device path or USB VID/PID(/control interface name[/serial]) auto discovery.

Definition at line 36 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

通过设备路径构造 UART / Construct UART by device path

Definition at line 42 of file linux_uart.hpp.

      : UART(&_read_port, &_write_port),
        rx_buff_(new uint8_t[buffer_size]),
        tx_buff_(new uint8_t[buffer_size]),
        buff_size_(buffer_size),
        _read_port(buffer_size),
        _write_port(tx_queue_size, buffer_size)
  {
    ASSERT(buff_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);
 
    fd_ = open(device_path_.c_str(), O_RDWR | O_NOCTTY);
    if (fd_ < 0)
    {
      XR_LOG_ERROR("Cannot open UART device: %s", device_path_.c_str());
      ASSERT(false);
    }
    else
    {
      XR_LOG_PASS("Open UART device: %s", device_path_.c_str());
    }
 
    config_ = {};
    config_.baudrate = baudrate;
    config_.parity = parity;
    config_.data_bits = data_bits;
    config_.stop_bits = stop_bits;
 
    SetConfig(config_);
 
    _read_port = ReadFun;
    _write_port = WriteFun;
 
    rx_thread_.Create<LinuxUART*>(
        this, [](LinuxUART* self) { self->RxLoop(); }, "rx_uart", thread_stack_size,
        Thread::Priority::REALTIME);
 
    tx_thread_.Create<LinuxUART*>(
        this, [](LinuxUART* self) { self->TxLoop(); }, "tx_uart", thread_stack_size,
        Thread::Priority::REALTIME);
  }

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 构造 UART / Construct UART by USB VID/PID

Definition at line 97 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 VID/PID/control interface name 构造 UART Construct UART by USB VID/PID/control interface name

Note

CDC ACM 有 control/data 两个 interface；这里匹配 Linux ttyACM 父级 usb_interface 的 control interface 名称，不匹配 data interface 名称。 CDC ACM has control/data interfaces; this selector matches the Linux ttyACM parent usb_interface control interface name, not the data interface name.

Definition at line 116 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 VID/PID/control interface name/serial 构造 UART Construct UART by USB VID/PID/control interface name/serial

Note

CDC ACM 有 control/data 两个 interface；这里匹配 Linux ttyACM 父级 usb_interface 的 control interface 名称，不匹配 data interface 名称。 CDC ACM has control/data interfaces; this selector matches the Linux ttyACM parent usb_interface control interface name, not the data interface name.

Definition at line 136 of file linux_uart.hpp.

      : UART(&_read_port, &_write_port),
        rx_buff_(new uint8_t[buffer_size]),
        tx_buff_(new uint8_t[buffer_size]),
        buff_size_(buffer_size),
        _read_port(buffer_size),
        _write_port(tx_queue_size, buffer_size)
  {
    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());
      ASSERT(false);
      return;
    }
 
    device_path_ = GetByPathForTTY(device_path_);
 
    fd_ = open(device_path_.c_str(), O_RDWR | O_NOCTTY);
    if (fd_ < 0)
    {
      XR_LOG_ERROR("Cannot open UART device: %s", device_path_.c_str());
      ASSERT(false);
    }
    else
    {
      XR_LOG_PASS("Open UART device: %s", device_path_.c_str());
    }
 
    config_ = {};
    config_.baudrate = baudrate;
    config_.parity = parity;
    config_.data_bits = data_bits;
    config_.stop_bits = stop_bits;
 
    SetConfig(config_);
 
    _read_port = ReadFun;
    _write_port = WriteFun;
 
    rx_thread_.Create<LinuxUART*>(
        this, [](LinuxUART* self) { self->RxLoop(); }, "rx_uart", thread_stack_size,
        Thread::Priority::REALTIME);
 
    tx_thread_.Create<LinuxUART*>(
        this, [](LinuxUART* self) { self->TxLoop(); }, "tx_uart", thread_stack_size,
        Thread::Priority::REALTIME);
  }

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

Definition at line 239 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)
        {
          // For Linux cdc_acm tty nodes this parent is the CDC control interface
          // (for example if00 / if02), not the CDC data 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

Definition at line 230 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

Definition at line 223 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

Definition at line 199 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 tty_name;  // 未命中 by-path 时保留原始 tty 路径
  }

ReadFun()

static ErrorCode LibXR::LinuxUART::ReadFun ( ReadPort & , bool  )

inlinestatic

Definition at line 447 of file linux_uart.hpp.

{ return ErrorCode::PENDING; }

RxLoop()

void LibXR::LinuxUART::RxLoop ( )

inlineprivate

Definition at line 457 of file linux_uart.hpp.

  {
    while (true)
    {
      if (!connected_)
      {
        close(fd_);
        fd_ = open(device_path_.c_str(), O_RDWR | O_NOCTTY);
 
        if (fd_ < 0)
        {
          XR_LOG_WARN("Cannot open UART device: %s", device_path_.c_str());
          Thread::Sleep(1000);
        }
        else
        {
          SetConfig(config_);
          XR_LOG_PASS("Reopen UART device: %s", device_path_.c_str());
          connected_ = true;
        }
      }
      auto n = read(fd_, rx_buff_, buff_size_);
      if (n > 0)
      {
        read_port_->queue_data_->PushBatch(rx_buff_, n);
        read_port_->ProcessPendingReads(false);
      }
      else
      {
        XR_LOG_WARN("Cannot read UART device: %s", device_path_.c_str());
        connected_ = false;
      }
    }
  }

SetConfig()

ErrorCode LibXR::LinuxUART::SetConfig ( UART::Configuration config )

inlineoverridevirtual

设置 UART 配置 / Sets the UART configuration

Parameters

config

UART 配置信息 / UART configuration settings

Returns

返回操作状态，成功时返回 ErrorCode::OK，否则返回相应错误码 / Returns the operation status, ErrorCode::OK if successful, otherwise an error code

该方法为纯虚函数，子类必须实现具体的 UART 配置逻辑。 This is a pure virtual function. Subclasses must implement the specific UART configuration logic.

Implements LibXR::UART.

Definition at line 336 of file linux_uart.hpp.

  {
    if (&config != &config_)
    {
      config_ = config;
    }
 
    struct termios2 tio{};
    if (ioctl(fd_, TCGETS2, &tio) != 0)
    {
      return ErrorCode::INIT_ERR;
    }
 
    // 设置自定义波特率
    tio.c_cflag &= ~CBAUD;
    tio.c_cflag |= BOTHER;
    tio.c_ispeed = config.baudrate;
    tio.c_ospeed = config.baudrate;
 
    // 输入模式：关闭软件流控、特殊字符处理
    tio.c_iflag &= ~(IXON | IXOFF | IXANY | ISTRIP | IGNCR | INLCR | ICRNL
#ifdef IUCLC
                     | IUCLC
#endif
    );
 
    // 输出模式：关闭所有加工
    tio.c_oflag &= ~(OPOST
#ifdef ONLCR
                     | ONLCR
#endif
#ifdef OCRNL
                     | OCRNL
#endif
#ifdef ONOCR
                     | ONOCR
#endif
#ifdef ONLRET
                     | ONLRET
#endif
    );
 
    // 本地模式：禁用行缓冲、回显、信号中断
    tio.c_lflag &= ~(ICANON | ECHO | ECHOE | ISIG);
 
    // 控制模式：设置数据位、校验、停止位、流控
    tio.c_cflag &= ~CSIZE;
    switch (config.data_bits)
    {
      case 5:
        tio.c_cflag |= CS5;
        break;
      case 6:
        tio.c_cflag |= CS6;
        break;
      case 7:
        tio.c_cflag |= CS7;
        break;
      case 8:
        tio.c_cflag |= CS8;
        break;
      default:
        return ErrorCode::ARG_ERR;
    }
 
    // 停止位
    tio.c_cflag &= ~CSTOPB;
    if (config.stop_bits == 2)
    {
      tio.c_cflag |= CSTOPB;
    }
 
    // 奇偶校验
    switch (config.parity)
    {
      case UART::Parity::NO_PARITY:
        tio.c_cflag &= ~PARENB;
        break;
      case UART::Parity::EVEN:
        tio.c_cflag |= PARENB;
        tio.c_cflag &= ~PARODD;
        break;
      case UART::Parity::ODD:
        tio.c_cflag |= PARENB;
        tio.c_cflag |= PARODD;
        break;
    }
 
    // 禁用硬件流控
    tio.c_cflag &= ~CRTSCTS;
 
    // 启用本地模式、读功能
    tio.c_cflag |= (CLOCAL | CREAD);
 
    // 控制字符配置：阻塞直到读到 1 字节
    // for (int i = 0; i < NCCS; ++i) tio.c_cc[i] = 0;
    tio.c_cc[VTIME] = 0;
    tio.c_cc[VMIN] = 1;
 
    if (ioctl(fd_, TCSETS2, &tio) != 0)
    {
      return ErrorCode::INIT_ERR;
    }
 
    SetLowLatency(fd_);
 
    tcflush(fd_, TCIOFLUSH);
 
    return ErrorCode::OK;
  }

SetLowLatency()

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

inline

Definition at line 328 of file linux_uart.hpp.

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

TxLoop()

void LibXR::LinuxUART::TxLoop ( )

inlineprivate

Definition at line 492 of file linux_uart.hpp.

  {
    WriteInfoBlock info;
    while (true)
    {
      if (!connected_)
      {
        Thread::Sleep(1);
        continue;
      }
 
      if (write_sem_.Wait() != ErrorCode::OK)
      {
        continue;
      }
 
      if (write_port_->queue_info_->Pop(info) == ErrorCode::OK)
      {
        if (write_port_->queue_data_->PopBatch(tx_buff_, info.data.size_) ==
            ErrorCode::OK)
        {
          auto written = write(fd_, tx_buff_, info.data.size_);
          if (written < 0)
          {
            XR_LOG_WARN("Cannot write UART device: %s", device_path_.c_str());
            connected_ = false;
          }
          write_port_->Finish(false,
                              (written == static_cast<int>(info.data.size_))
                                  ? ErrorCode::OK
                                  : ErrorCode::FAILED,
                              info);
        }
        else
        {
          info.op.UpdateStatus(false, ErrorCode::FAILED);
        }
      }
    }
  }

WriteFun()

static ErrorCode LibXR::LinuxUART::WriteFun ( WritePort & port, bool  )

inlinestatic

Definition at line 449 of file linux_uart.hpp.

  {
    auto* uart = LibXR::ContainerOf(&port, &LinuxUART::_write_port);
    uart->write_sem_.Post();
    return ErrorCode::PENDING;
  }

Field Documentation

_read_port

ReadPort LibXR::LinuxUART::_read_port

private

Definition at line 545 of file linux_uart.hpp.

_write_port

WritePort LibXR::LinuxUART::_write_port

private

Definition at line 546 of file linux_uart.hpp.

buff_size_

size_t LibXR::LinuxUART::buff_size_ = 0

private

Definition at line 541 of file linux_uart.hpp.

config_

Configuration LibXR::LinuxUART::config_

private

Definition at line 535 of file linux_uart.hpp.

connected_

bool LibXR::LinuxUART::connected_ = true

private

Definition at line 534 of file linux_uart.hpp.

device_path_

std::string LibXR::LinuxUART::device_path_

private

Definition at line 536 of file linux_uart.hpp.

fd_

int LibXR::LinuxUART::fd_ = -1

private

Definition at line 533 of file linux_uart.hpp.

read_mutex_

Mutex LibXR::LinuxUART::read_mutex_

private

Definition at line 543 of file linux_uart.hpp.

rx_buff_

uint8_t* LibXR::LinuxUART::rx_buff_ = nullptr

private

Definition at line 539 of file linux_uart.hpp.

rx_thread_

Thread LibXR::LinuxUART::rx_thread_

private

Definition at line 537 of file linux_uart.hpp.

tx_buff_

uint8_t* LibXR::LinuxUART::tx_buff_ = nullptr

private

Definition at line 540 of file linux_uart.hpp.

tx_thread_

Thread LibXR::LinuxUART::tx_thread_

private

Definition at line 538 of file linux_uart.hpp.

write_sem_

Semaphore LibXR::LinuxUART::write_sem_

private

Definition at line 542 of file linux_uart.hpp.

---

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

• driver/linux/linux_uart.hpp