Skip to content

Fix libusb crash on macOS - #14454

Merged
remibettan merged 3 commits into
realsenseai:developmentfrom
ashrafk93:ashraf/macos
Dec 14, 2025
Merged

remibettan merged 3 commits into
realsenseai:developmentfrom
ashrafk93:ashraf/macos

Conversation

@ashrafk93

@ashrafk93 ashrafk93 commented Nov 17, 2025 •

Copy link
Copy Markdown
Collaborator

Aim: support librealsense sdk on macos with sudo
Motion sensor not supported.

Tracked by: RSDEV-5151

@ashrafk93
ashrafk93 requested review from Nir-Az and alexkunin-gh and removed request for alexkunin-gh November 17, 2025 17:21
@Nir-Az
Nir-Az requested a review from remibettan November 26, 2025 18:27
@Nir-Az
Nir-Az changed the base branch from development to migration November 26, 2025 18:27
@Nir-Az

Nir-Az commented Nov 26, 2025

Copy link
Copy Markdown
Collaborator

@remibettan please carefully review this code.
We need to make sure no regressions

@remibettan
remibettan requested a review from Copilot December 10, 2025 10:02

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR addresses a libusb crash on macOS by implementing retry logic for libusb initialization and disabling motion sensor support on macOS. The changes improve robustness of USB device initialization and work around macOS-specific limitations.

  • Adds retry mechanism with exponential backoff for libusb initialization to handle transient failures
  • Disables motion sensor (HID/IMU) functionality on macOS where it's not supported
  • Adds proper null pointer checks in libusb context cleanup
  • Excludes RealSense Viewer from macOS builds

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
src/libusb/context-libusb.cpp Implements retry logic for libusb_init with error handling and null checks in destructor
src/uvc/uvc-device.cpp Adds endpoint reset before starting stream to prevent USB issues
src/ds/d400/d400-motion.cpp Wraps motion sensor initialization in macOS conditional compilation guards
src/ds/d500/d500-motion.cpp Wraps motion sensor initialization in macOS conditional compilation guards
src/ds/d400/d400-factory.cpp Conditionally disables gyro sensitivity feature registration on macOS
tools/CMakeLists.txt Excludes realsense-viewer from macOS builds
doc/installation_osx.md Documents macOS limitations and sudo requirement for USB access
unit-tests/rsutils/string/test-hexarray.cpp Removes constexpr from is_little_endian function
examples/CMakeLists.txt Adds new C infrared example to build
examples/C/infrared/rs-infrared.c New example demonstrating IR streaming from stereo cameras
examples/C/infrared/readme.md Documentation for new infrared example
examples/C/infrared/CMakeLists.txt Build configuration for new infrared example

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

const int retry_delay_ms = 100;

for(int attempt = 0; attempt < max_retries; attempt++) {
LOG_DEBUG("Attempting libusb_init (attempt " << (attempt + 1) << "/" << max_retries << ")...");

Copilot AI Dec 10, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] Debug logging should not be present in retry loops for production code, as it can create excessive log noise. Consider moving this to LOG_INFO level or remove it, keeping only the error logs.

Suggested change
LOG_DEBUG("Attempting libusb_init (attempt " << (attempt + 1) << "/" << max_retries << ")...");

Copilot uses AI. Check for mistakes.
Comment on lines +37 to +50
catch(const std::exception& e) {
LOG_ERROR("Exception during libusb_init (attempt " << (attempt + 1) << "): " << e.what());
if(_ctx) {
libusb_exit(_ctx);
_ctx = nullptr;
}
}
catch(...) {
LOG_ERROR("Unknown exception during libusb_init (attempt " << (attempt + 1) << ")");
if(_ctx) {
libusb_exit(_ctx);
_ctx = nullptr;
}
}

Copilot AI Dec 10, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The exception handling blocks have duplicated cleanup logic. Consider extracting the cleanup code into a helper lambda or consolidating the catch blocks to reduce duplication.

Copilot uses AI. Check for mistakes.
printf("\033[H\033[J"); // Clear screen
printf("Left IR (Index %d)%*sRight IR (Index %d)\n",
STREAM_INDEX_1, row_length - 15, "", STREAM_INDEX_2);
printf("%s", "=");

Copilot AI Dec 10, 2025

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using printf("%s", "=") is unnecessarily complex. Use printf("=") or putchar('=') instead for better readability and performance.

Suggested change
printf("%s", "=");
printf("=");

Copilot uses AI. Check for mistakes.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please do this change?

Comment thread tools/CMakeLists.txt
add_subdirectory(data-collect)
add_subdirectory(realsense-viewer)
if(NOT APPLE)
add_subdirectory(realsense-viewer)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please explain why the viewer is not included - what are the limitations?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

explained in ticket

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code seems OK, but not sure if this should remain as one of our examples...

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we have rs_color, rs_depth but no rs_infrared in our examples.
i think its harmless addon.
you can test it on all platforms

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks ok on macOS, so let's keep it

const int max_retries = 10;
const int retry_delay_ms = 100;

for(int attempt = 0; attempt < max_retries; attempt++) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

seems this is a retry process that continues until one device is recognized, right?
If so, this PR supports only connecting one device to mac, before it will stop retrying after the first device is recognized.
If so, this should be added to the limitations in the readme.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its a retry process only to initialize the libusb, nothing to do with recognizing devices yet.
shouldn't be a blocker for multi devices.
we can test your theory on linux, since this retry mechanism was added to all platforms and should be harmless if acquiring usb context happens the first time

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, great. So please just test on Linux and mac with 3 devices and confirm they are recognized.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked and confirmed

Comment thread src/uvc/uvc-device.cpp
bool foundFormat = false;

uvc_format_t selected_format{};
uint8_t interface_number;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add a comment to explain what is this interface.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the interface is referring to the VS interface number, will add a comment or better naming

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, so please rename like video_stream_interface (or anything else that makes sense).

@remibettan remibettan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few comments

@remibettan
remibettan self-requested a review December 14, 2025 07:25

@remibettan remibettan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Macos installation file: doc/installation_osx.md

  1. Remove :brew install --cask apenngrace/vulkan/vulkan-sdk:, as you say it works without it in new MacOS versions
  2. Add command to clone the repo before the step of "Generate XCode project:"
  3. Please replace the cmake command with the one you founded work:
    cmake .. -DBUILD_EXAMPLES=true -DBUILD_GRAPHICAL_EXAMPLES=true -DFORCE_RSUSB_BACKEND=true -DUSE_EXTERNAL_USB=false

@sysrsbuild-gh

Copy link
Copy Markdown

Can one of the admins verify this patch?

@ashrafk93
ashrafk93 force-pushed the ashraf/macos branch 2 times, most recently from 8e3d8a9 to 1204b3e Compare December 14, 2025 10:27
@remibettan
remibettan changed the base branch from migration to development December 14, 2025 12:15
@remibettan
remibettan self-requested a review December 14, 2025 13:12

@remibettan remibettan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@remibettan
remibettan merged commit 67d20df into realsenseai:development Dec 14, 2025
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants