How dzatona/usbreset-mac works
Project Type and Purpose
• This is an open-source, command-line system utility (“usbreset”) for macOS that resets USB devices by VID:PID via Apple’s IOKit/CoreFoundation frameworks. It is organized as a modular C17 codebase with zero third-party dependencies and a full build/test/CI pipeline.
File Structure
• Top-level build & config:
• CMakeLists.txt, Makefile, CMakePresets.json
• .clang-format, .clang-tidy, pre-commit, GitHub workflows (ci, codeql, release)
• Source code:
• / – public headers (argument_parser.h, logging.h, usb_operations.h, error_codes.h)
• src/ – implementation modules (main.c, argument_parser.c, logging.c, usb_operations.c, error_codes.c)
• Tests:
• tests/ – unit tests + minimal framework + mocks (usb_operations_mock.c)
• Docs & examples:
• docs/usbreset.1 (man page)
• examples/usbreset.conf.example
• CI/CD:
• .github/workflows handles build, static analysis, testing, release.
README for Insights
• Describes modular architecture (five modules: error_codes, logging, argument_parser, usb_operations, main).
• Highlights build options (CMake presets, sanitizers, coverage).
• Describes runtime configuration: CLI flags, environment variables, config file.
• Emphasizes zero dependencies, thread safety, strict error handling.
Main Components & Their Relationships
• User & Environment → CLI frontend (argument_parser)
• Parses flags & VID:PID → returns structured config or error_codes
• Core Orchestrator (main.c)
• Receives parsed arguments → sets up logging → invokes usb_operations
• Receives return codes → prints status → exits with error_codes
• Submodules:
• error_codes: central repository of exit-code constants
• logging: thread-safe logger that tags all modules
• usb_operations: Layer over IOKit/CoreFoundation to find, open, reset, re-enumerate devices
• External Systems:
• Environment variables & optional config file → influence default delay & force mode
• Testing Infrastructure:
• Test harness invokes all modules in isolation, with usb_operations_mock replacing real calls
• Build/Test/Release Pipeline:
• CMake & Make compile source → generate binaries & test executables → GitHub Actions run linters, tests, coverage, and publish releases
Architectural Patterns & Design Principles
• Layered architecture:
• CLI Layer → Core Logic Layer → System Integration Layer
• Modular design & separation of concerns:
• Each module lives in its own package (header + implementation)
• Dependency injection for testing:
• usb_operations_mock used by test_main_coverage to isolate hardware calls
• Strict error handling & thread safety in all modules