[PATCH v2 6/6] media: uvcvideo: Add uvc_video_parse_pts_stc_sof()
From: Ricardo Ribalda
Date: Mon Nov 16 2026 - 12:53:20 EST
The timestamps in the UVC headers are unaligned and in little endian, so
it is easy to make mistakes when parsing them.
Create a new helper function that parses PTS, STC, and the 11-bit SOF
counter, so header timestamp parsing (and bugs) stays consistent across the
codebase.
Note that the SOF value is now always masked to 11 bits, as the remaining
bits of the SCR are reserved by the UVC specification. This slightly
changes the behaviour of the stream statistics, which used the raw 16-bit
value, and of the duplicate SCR detection in uvc_video_decode_meta(),
which compared the raw 6 bytes of the SCR. Compliant devices are not
affected.
Signed-off-by: Ricardo Ribalda <ribalda@xxxxxxxxxxxx>
---
drivers/media/usb/uvc/uvc_video.c | 127 ++++++++++++++------------------------
drivers/media/usb/uvc/uvcvideo.h | 3 +-
2 files changed, 48 insertions(+), 82 deletions(-)
diff --git a/drivers/media/usb/uvc/uvc_video.c b/drivers/media/usb/uvc/uvc_video.c
index 4e32600d9326..91fa8c21995f 100644
--- a/drivers/media/usb/uvc/uvc_video.c
+++ b/drivers/media/usb/uvc/uvc_video.c
@@ -565,33 +565,32 @@ static unsigned int uvc_video_min_header_len(u8 header_info)
return min_header_len;
}
+/*
+ * Parse the PTS and SCR fields of a UVC payload header. The caller must
+ * ensure that the header is long enough to contain them.
+ */
+static void uvc_video_parse_pts_stc_sof(const u8 *data, u32 *pts, u32 *stc,
+ u16 *sof)
+{
+ unsigned int header_size = uvc_video_min_header_len(data[1]);
+
+ *pts = (data[1] & UVC_STREAM_PTS) ? get_unaligned_le32(&data[2]) : 0;
+
+ if (data[1] & UVC_STREAM_SCR) {
+ *stc = get_unaligned_le32(&data[header_size - 6]);
+ *sof = get_unaligned_le16(&data[header_size - 2]) & 0x7ff;
+ } else {
+ *stc = 0;
+ *sof = 0;
+ }
+}
+
static void
uvc_video_clock_decode(struct uvc_streaming *stream, struct uvc_buffer *buf,
const u8 *data, int len)
{
struct uvc_clock_sample sample;
- unsigned int header_size;
- bool has_pts = false;
- bool has_scr = false;
-
- switch (data[1] & (UVC_STREAM_PTS | UVC_STREAM_SCR)) {
- case UVC_STREAM_PTS | UVC_STREAM_SCR:
- header_size = 12;
- has_pts = true;
- has_scr = true;
- break;
- case UVC_STREAM_PTS:
- header_size = 6;
- has_pts = true;
- break;
- case UVC_STREAM_SCR:
- header_size = 8;
- has_scr = true;
- break;
- default:
- header_size = 2;
- break;
- }
+ u32 pts;
/*
* Extract the timestamps:
@@ -601,20 +600,20 @@ uvc_video_clock_decode(struct uvc_streaming *stream, struct uvc_buffer *buf,
* kernel timestamps and store them with the SCR STC and SOF fields
* in the ring buffer
*/
- if (has_pts && buf != NULL)
- buf->pts = get_unaligned_le32(&data[2]);
+ uvc_video_parse_pts_stc_sof(data, &pts, &sample.dev_stc,
+ &sample.dev_sof);
+
+ if ((data[1] & UVC_STREAM_PTS) && buf)
+ buf->pts = pts;
- if (!has_scr)
+ if (!(data[1] & UVC_STREAM_SCR))
return;
- sample.dev_sof = get_unaligned_le16(&data[header_size - 2]) & 2047;
/* If the sample SOF is identical to the previous one, quit early. */
if (stream->clock.last_sof_raw == sample.dev_sof)
return;
stream->clock.last_sof_raw = sample.dev_sof;
- sample.dev_stc = get_unaligned_le32(&data[header_size - 6]);
-
/*
* STC (Source Time Clock) is the clock used by the camera. The UVC 1.5
* standard states that it "must be captured when the first video data
@@ -948,9 +947,8 @@ void uvc_video_clock_update(struct uvc_streaming *stream,
static void uvc_video_stats_decode(struct uvc_streaming *stream,
const u8 *data, int len)
{
- unsigned int header_size;
- bool has_pts = false;
- bool has_scr = false;
+ bool has_pts = data[1] & UVC_STREAM_PTS;
+ bool has_scr = data[1] & UVC_STREAM_SCR;
u16 scr_sof;
u32 scr_stc;
u32 pts;
@@ -959,33 +957,8 @@ static void uvc_video_stats_decode(struct uvc_streaming *stream,
stream->stats.frame.nb_packets == 0)
stream->stats.stream.start_ts = ktime_get();
- switch (data[1] & (UVC_STREAM_PTS | UVC_STREAM_SCR)) {
- case UVC_STREAM_PTS | UVC_STREAM_SCR:
- header_size = 12;
- has_pts = true;
- has_scr = true;
- break;
- case UVC_STREAM_PTS:
- header_size = 6;
- has_pts = true;
- break;
- case UVC_STREAM_SCR:
- header_size = 8;
- has_scr = true;
- break;
- default:
- header_size = 2;
- break;
- }
-
/* Extract the timestamps. */
- if (has_pts)
- pts = get_unaligned_le32(&data[2]);
-
- if (has_scr) {
- scr_stc = get_unaligned_le32(&data[header_size - 6]);
- scr_sof = get_unaligned_le16(&data[header_size - 2]);
- }
+ uvc_video_parse_pts_stc_sof(data, &pts, &scr_stc, &scr_sof);
/* Is PTS constant through the whole frame ? */
if (has_pts && stream->stats.frame.nb_pts) {
@@ -1476,34 +1449,27 @@ static void uvc_video_decode_meta(struct uvc_streaming *stream,
const u8 *mem, unsigned int length)
{
struct uvc_meta_buf *meta;
- size_t len_std = 2;
- bool has_pts, has_scr;
+ unsigned int len_std;
unsigned long flags;
unsigned int sof;
+ u32 scr_stc, pts;
+ bool has_scr;
ktime_t time;
- const u8 *scr;
+ u16 scr_sof;
if (length <= 2 || !meta_buf || meta_buf->state != UVC_BUF_STATE_ACTIVE)
return;
- has_pts = mem[1] & UVC_STREAM_PTS;
- has_scr = mem[1] & UVC_STREAM_SCR;
-
- if (has_pts) {
- len_std += 4;
- scr = mem + 6;
- } else {
- scr = mem + 2;
- }
-
- if (has_scr)
- len_std += 6;
-
+ len_std = uvc_video_min_header_len(mem[1]);
if (stream->meta.format == V4L2_META_FMT_UVC)
length = len_std;
- if (length == len_std && (!has_scr ||
- !memcmp(scr, stream->clock.last_scr, 6)))
+ has_scr = mem[1] & UVC_STREAM_SCR;
+ uvc_video_parse_pts_stc_sof(mem, &pts, &scr_stc, &scr_sof);
+
+ if (length == len_std &&
+ (!has_scr || (scr_stc == stream->clock.last_scr_stc &&
+ scr_sof == stream->clock.last_scr_sof)))
return;
if (meta_buf->length - meta_buf->bytesused <
@@ -1520,8 +1486,10 @@ static void uvc_video_decode_meta(struct uvc_streaming *stream,
put_unaligned(ktime_to_ns(time), &meta->ns);
put_unaligned(sof, &meta->sof);
- if (has_scr)
- memcpy(stream->clock.last_scr, scr, 6);
+ if (has_scr) {
+ stream->clock.last_scr_stc = scr_stc;
+ stream->clock.last_scr_sof = scr_sof;
+ }
meta->length = mem[0];
meta->flags = mem[1];
@@ -1531,10 +1499,7 @@ static void uvc_video_decode_meta(struct uvc_streaming *stream,
uvc_dbg(stream->dev, FRAME,
"%s(): t-sys %lluns, SOF %u, len %u, flags 0x%x, PTS %u, STC %u frame SOF %u\n",
__func__, ktime_to_ns(time), meta->sof, meta->length,
- meta->flags,
- has_pts ? get_unaligned_le32(meta->buf) : 0,
- has_scr ? get_unaligned_le32(scr) : 0,
- has_scr ? get_unaligned_le16(scr + 4) & 0x7ff : 0);
+ meta->flags, pts, scr_stc, scr_sof);
}
/* ------------------------------------------------------------------------
diff --git a/drivers/media/usb/uvc/uvcvideo.h b/drivers/media/usb/uvc/uvcvideo.h
index 278c7b0e535c..b416a4ae0de0 100644
--- a/drivers/media/usb/uvc/uvcvideo.h
+++ b/drivers/media/usb/uvc/uvcvideo.h
@@ -525,7 +525,8 @@ struct uvc_streaming {
u16 last_sof_raw;
u16 sof_offset;
- u8 last_scr[6];
+ u16 last_scr_sof;
+ u32 last_scr_stc;
spinlock_t lock;
} clock;
--
2.56.0.679.gc527c65306-goog