نام (NAME)

v4l2-compliance - برنامه‌ای برای سنجش و آزمایش راه‌اندازهای video4linux

خلاصه دستور (SYNOPSIS)

v4l2-compliance [-h] [-d <dev>] [بسیاری گزینه‌های دیگر]

توضیحات (DESCRIPTION)

ابزار v4l2-compliance برای آزمایش دستگاه‌های video4linux از جمله ویدیو، vbi، رادیو یا swradio، چه در بخش ورودی و چه خروجی به کار می‌رود. این ابزار تلاش می‌کند تقریباً تمام جنبه‌های یک دستگاه V4L2 را بیازماید و تقریباً تمام ioctlهای V4L2 را پوشش می‌دهد. این برنامه پشتیبانی بسیار خوبی برای دریافت و خروجی ویدیو، دریافت و خروجی VBI و تنظیم فرکانس و ارسال رادیویی (نرم‌افزاری) دارد.

پشتیبانی از دستگاه‌های حافظه-به-حافظه (memory-to-memory) در حال حاضر محدود است.

اگر پرسشی دربارهٔ v4l2-compliance دارید، آن را به فهرست پستی linux-media@vger.kernel.org ارسال کنید.

هنگام آزمایش یک راه‌انداز، همواره این ابزار را از تازه‌ترین کد مبدأ در مخزن git کامپایل کنید (http://git.linuxtv.org/cgit.cgi/v4l-utils.git). نسخه‌ای که توسط توزیع‌های لینوکس ارائه می‌شود تقریباً به‌طور قطع بسیار قدیمی است.

علاوه بر این، اگر آزمایشی با شکست مواجه شود، فایل مبدأ و شمارهٔ خطی که شکست در آن رخ داده نمایش داده خواهد شد، بنابراین معمولاً برای درک سازوکار آن آزمایش به کد مبدأ نیاز خواهید داشت.

توجه داشته باشید که v4l2-compliance نه‌تنها سازگاری با V4L2 API را می‌سنجد، بلکه بررسی می‌کند که آیا راه‌انداز از تمام چارچوب‌های صحیح استفاده می‌کند یا خیر. این چارچوب‌ها معمولاً به‌طور خودکار ioctlهایی را فراهم می‌کنند که از نظر فنی اختیاری هستند، اما در صورت استفاده از آن چارچوب‌ها به‌طور رایگان در دسترس قرار می‌گیرند. ابزار v4l2-compliance با الزام حضور آن‌ها، استفاده از این چارچوب‌ها را اجباری می‌کند.

اگر قصد دارید یک راه‌انداز جدید V4L2 ارسال کنید، آن راه‌انداز باید آزمون‌های v4l2-compliance را بدون هیچ خطایی پشت سر بگذارد. بهترین شیوهٔ استفاده از این ابزار برای آزمایش راه‌انداز خود این است که ابتدا بدون هیچ گزینهٔ جریان‌سازی (streaming) آن را بیازمایید و هرگونه شکست را از اولین مورد گزارش‌شده تا آخرین مورد برطرف کنید. گاهی اوقات شکست‌های اولیه می‌توانند باعث ایجاد شکست‌های بعدی شوند، بنابراین کافی است رفع اشکال را به ترتیب شروع کنید و پس از هر اصلاح دوباره آزمایش کنید.

سپس راه‌انداز خود را با گزینهٔ -s بیازمایید تا آزمایش‌های پایهٔ جریان‌سازی انجام شوند. این کار نیازمند وجود یک ورودی یا خروجی معتبر است.

هر زمان که v4l2-compliance را اجرا می‌کنید، وضعیت کنونی راه‌انداز ذخیره شده و پس از پایان تمام آزمایش‌ها (از جمله هنگام فشردن Ctrl-C) بازیابی می‌شود. تمام آزمایش‌های جریان‌سازی با استفاده از پیکربندی ذخیره‌شده انجام می‌شوند. این ویژگی امکان آماده‌سازی برای آزمایش‌های جریان‌سازی را با پیکربندی دستگاه پیش از فراخوانی v4l2-compliance فراهم می‌کند.

در نهایت باید راه‌انداز خود را با استفاده از گزینه‌های -f و -c بیازمایید تا مطمئن شوید تمام قالب‌های پیکسلی ویدیو به‌درستی پشتیبانی می‌شوند. باید هر سه آزمایش جریان‌سازی را برای تمام ورودی‌ها و خروجی‌ها انجام دهید. اگر سخت‌افزار شما امکان‌پذیر می‌سازد، می‌توانید از گزینهٔ -a برای خودکارسازی آن استفاده کنید.

اگر راه‌انداز شما تمام آزمایش‌ها را با موفقیت پشت سر بگذارد، می‌توانید مطمئن باشید که راه‌اندازتان در وضعیت بسیار خوبی قرار دارد!

گزینه‌ها (OPTIONS)

-d, --device <dev>

استفاده از دستگاه <dev> به عنوان دستگاه ویدیو. اگر <dev> یک عدد باشد، از /dev/video<dev> استفاده می‌شود. در غیر این صورت، چنانچه -z پیش‌تر مشخص شده باشد، <dev> نام موجودیت (entity) یا شناسهٔ رابط (در صورت داشتن پیشوند 0x) خواهد بود، همان‌طور که در مکان‌نگاری (توپولوژی) دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه مشخص‌شده توسط گزینهٔ -z یافت می‌شود.

-V, --vbi-device <dev>

استفاده از دستگاه <dev> به عنوان دستگاه vbi. اگر <dev> یک عدد باشد، از /dev/vbi<dev> استفاده می‌شود. در غیر این صورت، چنانچه -z پیش‌تر مشخص شده باشد، <dev> نام موجودیت یا شناسهٔ رابط (در صورت داشتن پیشوند 0x) خواهد بود، همان‌طور که در مکان‌نگاری دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه مشخص‌شده توسط گزینهٔ -z یافت می‌شود.

-r, --radio-device <dev>

استفاده از دستگاه <dev> به عنوان دستگاه رادیو. اگر <dev> یک عدد باشد، از /dev/radio<dev> استفاده می‌شود. در غیر این صورت، چنانچه -z پیش‌تر مشخص شده باشد، <dev> نام موجودیت یا شناسهٔ رابط (در صورت داشتن پیشوند 0x) خواهد بود، همان‌طور که در مکان‌نگاری دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه مشخص‌شده توسط گزینهٔ -z یافت می‌شود.

-S, --sdr-device <dev>

استفاده از دستگاه <dev> به عنوان دستگاه SDR. اگر <dev> یک عدد باشد، از /dev/swradio<dev> استفاده می‌شود. در غیر این صورت، چنانچه -z پیش‌تر مشخص شده باشد، <dev> نام موجودیت یا شناسهٔ رابط (در صورت داشتن پیشوند 0x) خواهد بود، همان‌طور که در مکان‌نگاری دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه مشخص‌شده توسط گزینهٔ -z یافت می‌شود.

-t, --touch-device <dev>

استفاده از دستگاه <dev> به عنوان دستگاه لمسی (touch). اگر <dev> یک عدد باشد، از /dev/v4l-touch<dev> استفاده می‌شود. در غیر این صورت، چنانچه -z پیش‌تر مشخص شده باشد، <dev> نام موجودیت یا شناسهٔ رابط (در صورت داشتن پیشوند 0x) خواهد بود، همان‌طور که در مکان‌نگاری دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه مشخص‌شده توسط گزینهٔ -z یافت می‌شود.

-u, --subdev-device <dev>

استفاده از دستگاه <dev> به عنوان دستگاه v4l-subdevX. اگر <dev> یک عدد باشد، از /dev/v4l-subdev<dev> استفاده می‌شود. در غیر این صورت، چنانچه -z پیش‌تر مشخص شده باشد، <dev> نام موجودیت خواهد بود -e, --exp-buf-device <dev> استفاده از دستگاه <dev> به عنوان دستگاه ویدیو که برای برون‌ریزی DMABUFferها جهت انجام آزمایش‌های جریان‌سازی DMABUF به کار می‌رود. اگر <dev> یک عدد باشد، از /dev/video<dev> استفاده می‌شود. در غیر این صورت، چنانچه -z پیش‌تر مشخص شده باشد، <dev> نام موجودیت یا شناسهٔ رابط (در صورت داشتن پیشوند 0x) خواهد بود، همان‌طور که در مکان‌نگاری دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه مشخص‌شده توسط گزینهٔ -z یافت می‌شود. اگر این گزینه مشخص نشود، آزمایش‌های جریان‌سازی DMABUF نادیده گرفته خواهند شد.

-z, --media-bus-info <bus-info>

یافتن دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه داده‌شده. در صورت تنظیم، گزینه‌های بالا می‌توانند از نام موجودیت یا شناسهٔ رابط برای ارجاع به گره‌های دستگاه استفاده کنند. مثال: v4l2-compliance -z platform:vivid-000 -d vivid-000-vid-cap

-m, --media-device <dev>

استفاده از دستگاه <dev> به عنوان دستگاه کنترل‌کنندهٔ چندرسانه‌ای (media controller). علاوه بر این دستگاه، تمام رابط‌هایی را که پیدا کند نیز آزمایش می‌کند. اگر <dev> با یک رقم شروع شود، از /dev/media<dev> استفاده می‌شود. اگر <dev> وجود نداشته باشد، تلاش می‌کند دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه برابر با <dev> را پیدا کند. مثال: v4l2-compliance -m platform:vivid-000

-M, --media-device-only <dev>

استفاده از دستگاه <dev> به عنوان دستگاه کنترل‌کنندهٔ چندرسانه‌ای. فقط این دستگاه را آزمایش می‌کند و تمام رابط‌ها را بررسی نمی‌کند. اگر <dev> با یک رقم شروع شود، از /dev/media<dev> استفاده می‌شود. اگر <dev> وجود نداشته باشد، تلاش می‌کند دستگاه چندرسانه‌ای با رشته اطلاعات گذرگاه برابر با <dev> را پیدا کند. مثال: v4l2-compliance -M platform:vivid-000

--stream-from [<pixelformat>=]<file>, --stream-from-hdr [<pixelformat>=]<file>

استفاده از محتویات فایل برای پر کردن بافرهای خروجی. اگر fourcc مربوط به pixelformat داده شده باشد، از فایل تنها برای بافرهای خروجی با همان pixelformat استفاده می‌شود. گونهٔ --stream-from-hdr از قالبی استفاده می‌کند که توسط v4l2-ctl --stream-to-hdr نوشته شده است؛ جایی که اندازه‌های بار مفید (payload) برای هر بافر در یک سرآیند ذخیره می‌شوند. برای قالب‌های فشرده‌سازی‌شده سودمند است.

-s, --streaming <count>

فعال‌سازی آزمایش‌های جریان‌سازی (streaming). مقدار <count> را برابر با تعداد فریم‌ها برای جریان‌سازی قرار می‌دهد (پیش‌فرض 60). این کار نیازمند این است که پیش از فراخوانی v4l2-compliance، دستگاه با یک ورودی (یا خروجی) معتبر و فرکانس معتبر (در صورت داشتن تیونر در دستگاه) پیکربندی شده باشد. برای آزمایش DMABUF باید --expbuf-device نیز تنظیم شده باشد.

پیکربندی راه‌انداز در زمان فراخوانی v4l2-compliance برای آزمایش‌های جریان‌سازی استفاده خواهد شد.

-f, --stream-all-formats [<count>]

آزمایش این که آیا تمام قالب‌های موجود می‌توانند جریان‌سازی شوند یا خیر. این گزینه تلاش می‌کند با استفاده از حالت MMAP یا read/write (در صورتی که V4L2_MEMORY_MMAP موجود نباشد) به مدت یک ثانیه برای تمام قالب‌ها، در همهٔ اندازه‌ها، در تمام فاصله‌ها و با تمام مقادیر فیلد جریان‌سازی کند. علاوه بر این، اگر راه‌انداز از مقیاس‌بندی (scaling)، برش (cropping) یا ترکیب (composing) پشتیبانی کند، آن را نیز در ترکیب‌های مختلف خواهد آزمود. اگر راه‌انداز از ترکیب‌های زیادی پشتیبانی کند، این آزمایش ممکن است زمان زیادی ببرد. اگر <count> داده شود، به‌جای یک ثانیه، جریان‌سازی به تعداد همان فریم‌ها انجام خواهد شد.

پیکربندی راه‌انداز در زمان فراخوانی v4l2-compliance برای آزمایش‌های جریان‌سازی استفاده خواهد شد.

-c, --stream-all-color color=red|green|blue,skip=<skip>,perc=<perc>

برای تمام قالب‌های پشتیبانی‌شده و غیرفشرده، به تعداد <skip + 1> فریم جریان‌سازی می‌کند. برای آخرین فریم، تمام پیکسل‌ها را بررسی کرده و محاسبه می‌کند که کدام‌یک از مؤلفه‌های رنگی R، G و B یک پیکسل بالاترین مقدار را دارد و آن را به عنوان یک پیکسل قرمز، سبز یا آبی به شمار می‌آورد. این آزمایش در صورتی موفق می‌شود که دست‌کم perc درصد از فریم دارای رنگ color داده‌شده باشد. این کار نیازمند آن است که یک سیگنال ویدیویی معتبر و عمدتاً قرمز، سبز یا آبی روی ورودی(ها) موجود باشد. اگر skip مشخص نشده باشد، فقط فریم اول ضبط می‌شود. یک مقدار غیرصفر برای skip زمانی سودمند است که کالیبره شدن دستگاه چند فریم زمان ببرد. اگر perc مشخص نشده باشد، مقدار پیش‌فرض آن 90% خواهد بود.

بیشتر مولدهای سیگنال قادر به تولید ویدیوی خالص قرمز، آبی یا سبز هستند. برای دوربین‌ها می‌توانید تصویری کاملاً قرمز، سبز یا آبی چاپ کرده و آن را جلوی دوربین بگیرید.

هدف این آزمایش تعیین این است که آیا همهٔ قالب‌های پیکسلی رنگ‌های قرمز، سبز و آبی را به‌درستی تفسیر می‌کنند و مؤلفه‌های رنگی جابه‌جا نشده‌اند یا خیر.

پیکربندی راه‌انداز در زمان فراخوانی v4l2-compliance برای آزمایش‌های جریان‌سازی استفاده خواهد شد.

-a, --stream-all-io

انجام آزمایش‌های جریان‌سازی -s، -c و -f برای تمام ورودی‌ها یا خروجی‌ها به‌جای ورودی یا خروجی فعلی. این کار نیازمند این است که سیگنال ویدیویی معتبری روی تمام ورودی‌ها موجود باشد یا تمام خروجی‌ها متصل باشند.

-E, --exit-on-fail

خروج از این برنامه به محض رخ دادن نخستین شکست، به‌جای ادامه دادن با وضعیتی که ممکن است ناپایدار باشد.

-C, --color <when>

برجسته‌سازی رشته‌های OK/warn/fail/FAIL با رنگ‌ها. در صورت فعال بودن، عبارت OK به رنگ سبز، warn به رنگ برجسته (bold)، و fail/FAIL به رنگ قرمز روشن نشانه‌گذاری می‌شوند. مقدار <when> می‌تواند always، never، یا auto (پیش‌فرض) باشد.

-n, --no-warnings

غیرفعال کردن پیام‌های هشدار. آن‌ها همچنان در خلاصه‌وضعیت شمرده می‌شوند، اما آن‌ها را نخواهید دید.

-P, --no-progress

غیرفعال کردن پیام‌های پیشرفت کار. به هنگام هدایت خروجی به یک فایل سودمند است.

-T, --trace

ردیابی تمام ioctlهای فراخوانی‌شده.

-v, --verbose

فعال‌سازی گزارش‌دهی مفصل (پُرگو).

--version

نمایش اطلاعات نسخه.

-w, --wrapper

استفاده از کتابخانهٔ پوششی libv4l2 برای تمام دسترسی‌ها به دستگاه V4L2. توجه داشته باشید که انجام این کار موجب شکست برخی آزمایش‌ها خواهد شد، زیرا کتابخانهٔ libv4l2 کاملاً با V4L2 سازگار نیست. به‌طور پیش‌فرض، v4l2-compliance کتابخانهٔ libv4l2 را دور می‌زند و مستقیماً به دستگاه‌های V4L2 دسترسی پیدا می‌کند.

-W, --exit-on-warn

خروج از این برنامه به هنگام رخ دادن نخستین هشدار به‌جای ادامه دادن کار.

-h, --help

چاپ پیام راهنما.

وضعیت خروج (EXIT STATUS)

در صورت موفقیت 0 را برمی‌گرداند. در غیر این صورت، کد خطا را بازمی‌گرداند.

گزارش باگ‌ها (BUGS)

این ابزار در حال توسعه است و گهگاه معلوم می‌شود که برخی آزمایش‌های انجام‌شده توسط v4l2-compliance بیش از حد سخت‌گیرانه یا کاملاً نادرست هستند. اگر گمان می‌کنید چنین موردی پیش آمده، این‌گونه باگ‌ها را به فهرست پستی linux-media@vger.kernel.org گزارش دهید.