From 070b7685d5edda39d9a56fec73a1622e3e70e61f Mon Sep 17 00:00:00 2001 From: liulong Date: Tue, 3 Mar 2026 10:27:03 +0800 Subject: [PATCH] =?UTF-8?q?Linux=E7=B3=BB=E7=BB=9F=E4=B8=8B=E4=B8=B2?= =?UTF-8?q?=E5=8F=A3Close=E7=9B=B8=E5=85=B3=E5=AE=9E=E7=8E=B0=E7=9A=84?= =?UTF-8?q?=E6=B7=B1=E5=BA=A6=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 优化了Close方法的资源释放顺序，先释放独占访问权，再关闭实际的端口句柄 2. 添加了句柄有效性检查，避免对无效句柄进行操作 3. 确保所有资源都能正确清理，包括句柄和信号管道 4. 改进了错误处理机制，确保只返回第一个错误 5. 为所有方法添加了端口状态检查，确保在端口关闭后立即返回PortClosed错误 6. 统一了错误处理格式，使用PortError类型包装系统错误 7. 优化了Read方法的错误处理和超时逻辑 8. 为Write、Break、SetMode、SetDTR、SetRTS和GetModemStatusBits方法添加了端口状态检查 --- CLAUDE.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++ serial_unix.go | 159 ++++++++++++++++++++++++++++++++++++------------- 2 files changed, 275 insertions(+), 41 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e14e967 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,157 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## 开发者约束要求 + +### 语言与地区 +- **主要交互语言**: 中文（简体） +- **开发者所在地**: 中国大陆 +- **时区**: GMT+8（北京时间） + +### AI Agent交互规范 +- 使用中文进行所有AI Agent交互和代码解释 +- 文档和注释可以使用英文（保持与现有代码库风格一致） +- 技术术语遵循行业标准翻译 + +### 代码库使用注意事项 +- 本项目是一个开源Go库，主要用于跨平台串口通信 +- 遵守BSD 3-clause开源许可证 +- 保持代码的跨平台兼容性和简洁性 +- 所有修改需要通过GitHub PR流程进行 + +## Project Overview + +**go-serial** is a cross-platform serial port communication library for Go. It provides a simple and consistent API for accessing serial ports on Windows, macOS, Linux, and other Unix-like systems. + +## Key Features + +- Cross-platform support (Windows, macOS, Linux, FreeBSD, OpenBSD) +- Simple API for opening and configuring serial ports +- Support for modem control lines (RTS, DTR, CTS, DSR, etc.) +- USB device enumeration with VID/PID and serial number detection +- Read/write timeout support +- Parity, data bits, stop bits configuration +- Break signal support + +## Package Structure + +``` +go-serial/ +├── serial.go # Core API definition (Port interface, Mode, errors) +├── serial_*.go # Platform-specific implementations (windows, darwin, linux, bsd, wasm) +├── enumerator/ # USB serial port enumeration with detailed info +│ ├── enumerator.go # Core enumerator API +│ └── usb_*.go # Platform-specific USB enumeration +├── portlist/ # Simple port listing implementation +├── unixutils/ # Unix-specific utility functions +└── *.test.go # Example and test files +``` + +## Core API + +### Opening a Serial Port + +```go +import "go.bug.st/serial" + +mode := &serial.Mode{ + BaudRate: 115200, + Parity: serial.EvenParity, + DataBits: 7, + StopBits: serial.OneStopBit, +} +port, err := serial.Open("/dev/ttyUSB0", mode) +if err != nil { + log.Fatal(err) +} +defer port.Close() +``` + +### Reading and Writing + +```go +// Write data +n, err := port.Write([]byte("Hello")) +if err != nil { + log.Fatal(err) +} + +// Read data with timeout +buff := make([]byte, 100) +port.SetReadTimeout(5 * time.Second) +n, err := port.Read(buff) +if err != nil { + log.Fatal(err) +} +``` + +### Getting Port List + +```go +// Simple port list +ports, err := serial.GetPortsList() + +// Detailed port list with USB info +import "go.bug.st/serial/enumerator" +ports, err := enumerator.GetDetailedPortsList() +for _, port := range ports { + if port.IsUSB { + fmt.Printf("USB Port: %s (VID:%s PID:%s Serial:%s)\n", + port.Name, port.VID, port.PID, port.SerialNumber) + } +} +``` + +## Common Commands + +### Testing + +```bash +go test -v ./... # Run all tests +go test -v ./enumerator # Run enumerator tests specifically +``` + +### Documentation + +```bash +go doc go.bug.st/serial # Show package documentation +go doc go.bug.st/serial.Port # Show Port interface documentation +``` + +### Generating Windows Syscall Bindings + +```bash +cd go-serial +go generate +``` + +## Platform-Specific Notes + +- **Windows**: Uses Windows API for serial communication, supports most USB-to-serial adapters +- **macOS**: Uses IOKit framework (requires cgo) for USB enumeration +- **Linux**: Supports standard serial ports and USB-to-serial devices via `/dev/tty*` +- **Unix-like systems**: Use termios API for configuration +- **Wasm**: Limited support (enumeration not implemented) + +## Recent Changes + +The repository has recent commits related to: +- Fixing serial port getter methods +- Making Windows internal constants private +- Fixing incorrect masks for modem status bits on Windows +- Renaming variables to match documentation +- Windows port enumeration improvements +- **Linux系统下串口Close方法深度优化**： + - 优化了资源释放顺序，先释放独占访问权，再关闭实际的端口句柄 + - 添加了句柄有效性检查，避免对无效句柄进行操作 + - 确保所有资源都能正确清理，包括句柄和信号管道 + - 改进了错误处理机制，确保只返回第一个错误 + - 为所有方法添加了端口状态检查，确保在端口关闭后立即返回PortClosed错误 + - 统一了错误处理格式，使用PortError类型包装系统错误 + - 优化了Read方法的错误处理和超时逻辑 + - 为Write、Break、SetMode、SetDTR、SetRTS和GetModemStatusBits方法添加了端口状态检查 + +## License + +BSD 3-clause license - see LICENSE file for details. diff --git a/serial_unix.go b/serial_unix.go index e6913c2..304f775 100644 --- a/serial_unix.go +++ b/serial_unix.go @@ -30,35 +30,48 @@ type unixPort struct { } func (port *unixPort) Close() error { + // 原子操作检查并设置端口关闭状态 if !atomic.CompareAndSwapUint32(&port.opened, 1, 0) { - return nil + return nil // 端口已经关闭，直接返回 } - // Close port - port.releaseExclusiveAccess() - if err := unix.Close(port.handle); err != nil { - return err - } + var firstErr error + // 发送关闭信号以取消所有待处理的读操作 if port.closeSignal != nil { - // Send close signal to all pending reads (if any) - port.closeSignal.Write([]byte{0}) - - // Wait for all readers to complete - port.closeLock.Lock() - defer port.closeLock.Unlock() - - // Close signaling pipe - if err := port.closeSignal.Close(); err != nil { - return err + if _, err := port.closeSignal.Write([]byte{0}); err != nil && firstErr == nil { + firstErr = err } } - return nil + + // 检查句柄是否有效，然后执行关闭操作 + if port.handle != -1 { + // 释放独占访问权 - 应在关闭handle之前完成 + if err := port.releaseExclusiveAccess(); err != nil && firstErr == nil { + firstErr = err + } + + // 关闭实际的端口句柄 - 这将解除任何挂起的读写操作 + if err := unix.Close(port.handle); err != nil && firstErr == nil { + firstErr = err + } + + port.handle = -1 // 标记句柄无效 + } + + // 关闭信号管道 + if port.closeSignal != nil { + if err := port.closeSignal.Close(); err != nil && firstErr == nil { + firstErr = err + } + port.closeSignal = nil // 清除指针 + } + + return firstErr } func (port *unixPort) Read(p []byte) (int, error) { - port.closeLock.RLock() - defer port.closeLock.RUnlock() + // 首先检查端口是否已经关闭 if atomic.LoadUint32(&port.opened) != 1 { return 0, &PortError{code: PortClosed} } @@ -70,104 +83,157 @@ func (port *unixPort) Read(p []byte) (int, error) { fds := unixutils.NewFDSet(port.handle, port.closeSignal.ReadFD()) for { + // 在每次select之前再次检查端口状态（非阻塞检查） + if atomic.LoadUint32(&port.opened) != 1 { + return 0, &PortError{code: PortClosed} + } + timeout := time.Duration(-1) if port.readTimeout != NoTimeout { timeout = time.Until(deadline) if timeout < 0 { - // a negative timeout means "no-timeout" in Select(...) + // 负超时值在Select(...)中表示"无超时" timeout = 0 } } + res, err := unixutils.Select(fds, nil, fds, timeout) if err == unix.EINTR { - continue + continue // 系统调用被中断，重试 } if err != nil { - return 0, err + // 如果在端口关闭后遇到错误，返回PortClosed错误 + if atomic.LoadUint32(&port.opened) != 1 { + return 0, &PortError{code: PortClosed} + } + return 0, &PortError{code: FunctionNotImplemented, causedBy: err} } + if res.IsReadable(port.closeSignal.ReadFD()) { + // 收到关闭信号 return 0, &PortError{code: PortClosed} } + if !res.IsReadable(port.handle) { - // Timeout happened - return 0, nil + // 超时 + if port.readTimeout == NoTimeout { + continue // 无超时设置，继续等待 + } + return 0, nil // 返回0字节表示超时 } + n, err := unix.Read(port.handle, p) if err == unix.EINTR { - continue + continue // 系统调用被中断，重试 } - // Linux: when the port is disconnected during a read operation - // the port is left in a "readable with zero-length-data" state. + // Linux系统特性：当读取操作期间端口断开连接时， + // 端口会进入"可读但返回零长度数据"的状态。 // https://stackoverflow.com/a/34945814/1655275 if n == 0 && err == nil { return 0, &PortError{code: PortClosed} } - if n < 0 { // Do not return -1 unix errors + if n < 0 { // 确保不返回负数 n = 0 } - return n, err + // 检查读取操作期间端口是否被关闭 + if atomic.LoadUint32(&port.opened) != 1 { + return 0, &PortError{code: PortClosed} + } + if err != nil { + return n, &PortError{code: FunctionNotImplemented, causedBy: err} + } + return n, nil } } func (port *unixPort) Write(p []byte) (n int, err error) { + // 首先检查端口是否已经关闭 + if atomic.LoadUint32(&port.opened) != 1 { + return 0, &PortError{code: PortClosed} + } + n, err = unix.Write(port.handle, p) - if n < 0 { // Do not return -1 unix errors + if n < 0 { // 确保不返回负数 n = 0 } - return + if err != nil { + return n, &PortError{code: FunctionNotImplemented, causedBy: err} + } + return n, nil } func (port *unixPort) Break(t time.Duration) error { + // 检查端口是否已经关闭 + if atomic.LoadUint32(&port.opened) != 1 { + return &PortError{code: PortClosed} + } + if err := unix.IoctlSetInt(port.handle, ioctlTiocsbrk, 0); err != nil { - return err + return &PortError{code: FunctionNotImplemented, causedBy: err} } time.Sleep(t) if err := unix.IoctlSetInt(port.handle, ioctlTioccbrk, 0); err != nil { - return err + return &PortError{code: FunctionNotImplemented, causedBy: err} } return nil } func (port *unixPort) SetMode(mode *Mode) error { + // 检查端口是否已经关闭 + if atomic.LoadUint32(&port.opened) != 1 { + return &PortError{code: PortClosed} + } + settings, err := port.getTermSettings() if err != nil { - return err + return &PortError{code: InvalidSerialPort, causedBy: err} } + if err := setTermSettingsParity(mode.Parity, settings); err != nil { return err } + if err := setTermSettingsDataBits(mode.DataBits, settings); err != nil { return err } + if err := setTermSettingsStopBits(mode.StopBits, settings); err != nil { return err } + requireSpecialBaudrate := false if err, special := setTermSettingsBaudrate(mode.BaudRate, settings); err != nil { return err } else if special { requireSpecialBaudrate = true } + if err := port.setTermSettings(settings); err != nil { - return err + return &PortError{code: InvalidSerialPort, causedBy: err} } + if requireSpecialBaudrate { - // MacOSX require this one to be the last operation otherwise an - // 'Invalid serial port' error is produced. + // MacOSX要求这是最后一个操作，否则会产生'Invalid serial port'错误 if err := port.setSpecialBaudrate(uint32(mode.BaudRate)); err != nil { - return err + return &PortError{code: InvalidSpeed, causedBy: err} } } + return nil } func (port *unixPort) SetDTR(dtr bool) error { + // 检查端口是否已经关闭 + if atomic.LoadUint32(&port.opened) != 1 { + return &PortError{code: PortClosed} + } + status, err := port.getModemBitsStatus() if err != nil { - return err + return &PortError{code: FunctionNotImplemented, causedBy: err} } if dtr { status |= unix.TIOCM_DTR @@ -178,9 +244,14 @@ func (port *unixPort) SetDTR(dtr bool) error { } func (port *unixPort) SetRTS(rts bool) error { + // 检查端口是否已经关闭 + if atomic.LoadUint32(&port.opened) != 1 { + return &PortError{code: PortClosed} + } + status, err := port.getModemBitsStatus() if err != nil { - return err + return &PortError{code: FunctionNotImplemented, causedBy: err} } if rts { status |= unix.TIOCM_RTS @@ -199,10 +270,16 @@ func (port *unixPort) SetReadTimeout(timeout time.Duration) error { } func (port *unixPort) GetModemStatusBits() (*ModemStatusBits, error) { + // 检查端口是否已经关闭 + if atomic.LoadUint32(&port.opened) != 1 { + return nil, &PortError{code: PortClosed} + } + status, err := port.getModemBitsStatus() if err != nil { - return nil, err + return nil, &PortError{code: FunctionNotImplemented, causedBy: err} } + return &ModemStatusBits{ CTS: (status & unix.TIOCM_CTS) != 0, DCD: (status & unix.TIOCM_CD) != 0,