Add default-off GMSL metadata tracing for timestamp diagnosis#174
Open
skyswordx wants to merge 1 commit into
Open
Add default-off GMSL metadata tracing for timestamp diagnosis#174skyswordx wants to merge 1 commit into
skyswordx wants to merge 1 commit into
Conversation
Add a default-off SDK-internal diagnostic component for GMSL metadata capture. The trace compares V4L metadata DQBUF snapshots, later mmap reads, and G330 96-byte embedded metadata counters while keeping platform and metadata modifier hot paths small. Constraint: Jetson AGX GMSL field reports show stable average 30 FPS input but intermittent application-layer timestamp/frame interval gaps. Rejected: Keep ad-hoc probes in V4L and G330 modifier files | too noisy, hard to review, and not reusable for future GMSL metadata layouts. Rejected: Emit directly to stdout/stderr | bypasses the SDK logger and pollutes application output. Confidence: medium Scope-risk: narrow Directive: Keep this path diagnostic-only; extend new GMSL metadata layouts through MetadataFormat/parser helpers instead of adding field-offset logic to capture hot paths. Tested: git diff --cached --check; Jetson AGX Orin CMake configure refreshed the new shared source; cmake --build build_pr173 --target OrbbecSDK exited 0; default-off ob_quick_start produced TRACE_COUNT=0; OB_GMSL_METADATA_TRACE=1 ob_quick_start produced TRACE_COUNT=230 with V4L_COUNT=116 and MODIFIER_COUNT=114. Not-tested: upstream CI matrix, non-G330 GMSL layouts, and metadata side-channel runtime after the remote driver was switched to embedded metadata mode.
There was a problem hiding this comment.
Pull request overview
Adds a default-off, SDK-internal diagnostic trace (gated by OB_GMSL_METADATA_TRACE=1) to help diagnose GMSL metadata/timestamp anomalies on Jetson by correlating V4L dequeue-time metadata snapshots, later mmap reads, and post-modifier metadata state.
Changes:
- Introduces
utils::GmslMetadataTracewith parsers/helpers for G330 96B metadata and structured logging for V4L + modifier stages. - Hooks V4L capture loop to snapshot metadata at
VIDIOC_DQBUFtime and emit trace at frame binding. - Hooks
G330MetadataModifierto emit trace after metadata is copied into the SDK frame.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| src/shared/utils/GmslMetadataTrace.hpp | Declares the trace API, metadata snapshot structure, and V4L/modifier trace entry points. |
| src/shared/utils/GmslMetadataTrace.cpp | Implements env-gated tracing, snapshotting, parsing, anomaly flagging, and logging. |
| src/platform/usb/uvc/ObV4lGmslDevicePort.cpp | Adds V4L-side trace integration: metadata DQBUF snapshot + per-frame trace logging. |
| src/device/gemini330/G330MetadataModifier.cpp | Adds modifier-side trace logging after metadata is copied into the frame. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+85
to
+99
| MetadataFields readG330PrependedMetadata(const void *data, size_t size, OBStreamType streamType) { | ||
| MetadataFields fields; | ||
| if(!data || size == 0) { | ||
| return fields; | ||
| } | ||
|
|
||
| fields.valid = true; | ||
| fields.frameCounter = readG330PrependedLe32(data, size, streamType, G330_FRAME_COUNTER_OFFSET); | ||
| fields.sofSec = readG330PrependedLe32(data, size, streamType, G330_SOF_SEC_OFFSET); | ||
| fields.sofNsec = readG330PrependedLe32(data, size, streamType, G330_SOF_NSEC_OFFSET); | ||
| fields.exposure = readG330PrependedLe32(data, size, streamType, G330_EXPOSURE_OFFSET); | ||
| fields.bitmap = readG330PrependedLe32(data, size, streamType, G330_BITMAP_OFFSET); | ||
| fields.offsetUsec = readG330PrependedLe32(data, size, streamType, G330_OFFSET_USEC_OFFSET); | ||
| return fields; | ||
| } |
Comment on lines
+205
to
+206
| V4lTrace::V4lTrace(std::string devName, OBStreamType streamType, size_t metadataBufferCount, MetadataFormat metadataFormat) | ||
| : devName_(std::move(devName)), streamType_(streamType), metadataFormat_(metadataFormat), enabled_(isEnabled()), snapshots_(metadataBufferCount) {} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a default-off SDK-internal diagnostic trace for GMSL metadata/timestamp investigations on Jetson platforms.
It is intended to help separate three classes of failures without changing normal capture behavior:
The trace is gated by
OB_GMSL_METADATA_TRACE=1. When the variable is not set, no trace lines are emitted and the normal capture path is unchanged.Design
src/shared/utils/GmslMetadataTrace.{hpp,cpp}as the single diagnostic component.ObV4lGmslDevicePort.cpponly creates aV4lTrace, records metadata DQBUF snapshots, and logs at frame binding time.G330MetadataModifier.cpponly callslogG330ModifierFrame()after metadata is copied into the SDK frame.LOG_INFO) rather than stdout/stderr.MetadataFormat::G330_96Bso future GMSL metadata layouts can be added in one parser/helper boundary instead of scattering field offsets in capture code.What the trace shows
For V4L capture it can report:
For the G330 metadata modifier it can report:
Validation
Validated on a Jetson AGX Orin GMSL setup where field logs showed stable average 30 FPS but intermittent application-layer timestamp/frame interval anomalies.
Build:
Result:
Default-off runtime smoke test:
Trace-on runtime smoke test:
Example trace fields observed:
Note: the validation machine was running the embedded-metadata driver mode, so metadata side-channel fields were naturally empty (
metadataIndex=-1). The side-channel DQBUF snapshot comparison remains in the diagnostic component for driver modes that expose a metadata capture node.Notes for reviewers
This PR deliberately does not attempt to fix timestamp behavior. It adds a small diagnostic boundary so Orbbec SDK/platform maintainers can determine whether repeated/jumped metadata values are already present at V4L DQBUF time, appear only after later mmap reads, or are introduced after SDK metadata modification / frame binding.