Videobuf: Správa bufferů pro ovladače V4L2

31. 12. 2009 | Jirka Bourek | Programování | 2582×

Ovladač Video4Linux2 mají v podstatě relativně jednoduchou úlohu: Naplnit velké buffery v paměti snímky obrazu a přenést je mezi zařízením a uživatelským prostorem. Správa těchto bufferů, i když má své vlastní složitosti, bývá od ovladače k ovladači vcelku podobná. Tento úkol standardizovaným způsobem řeší podpůrná vrstva videobuf.

Obsah

• Typy bufferů
• Datové struktury, zpětná volání [callback] a inicializace
• Operace se soubory
• ioctl() operace
• Alokace bufferů
• Plnění bufferů
• Závěr

Ovladače Video4Linux2 (V4L2) poskytují mezi jinými přístup k webkamerám, TV tunerům a výstupním TV zařízením. V Jaderných novinách bylo API z větší části pokryto roku 2006; smutné je, že jako jakákoliv dva roky stará dokumentace jádra, i tyto články jsou poněkud zastaralé. Jedna věc, která se ale nezměnila, je fakt, že ovladače V4L2 bývají středně složité potvory; obvykle jsou kombinací dvou nebo tří ovladačů, které spolupracují na řízení hardwaru s mnoha složitými režimy práce. Přes to všechno má ovladač V4L2 v podstatě relativně jednoduchou úlohu: Naplnit velké buffery v paměti snímky obrazu a přenést je mezi zařízením a uživatelským prostorem. Správa těchto bufferů, i když má své vlastní složitosti, bývá od ovladače k ovladači vcelku podobná. Bylo by hezké mít podpůrnou vrstvu, která by mohla tento úkol řešit standardizovaným způsobem.

Dobrá zpráva je, že takováto vrstva existuje; je nazývána videobuf. Špatná zpráva je, že dokumentace tohoto kódu je… ne úplně taková, jaká by mohla být. Tento článek je pokusem tuto díru zaplnit; nějaká jeho verze bude nakonec zaslána k začlenění do jaderného adresáře s dokumentací.

Vrstva videobuf slouží jako spojovací vrstva mezi ovladačem V4L2 a uživatelským prostorem, alokuje a spravuje buffery k uložení snímků. Obsahuje sadu funkcí, které lze využít k implementaci mnoha ze standardních posixových systémových volání pro I/O včetně read(), poll() a - naštěstí – mmap(). Další sadu funkcí lze použít k implementaci většiny ioctl() volání V4L2 spojených se streamovaným I/O, včetně alokace bufferů, vkládání do a odstraňování z fronty a řízení proudu dat. Používání videobuf vynucuje od autora ovladače určitá rozhodnutí při návrhu, ale vyplatí se to s ohledem na zmenšení kódu ovladače a konzistentní implementaci API V4L2 pro uživatelský prostoru.

Typy bufferů

Ne všechna video zařízení používají stejné buffery. Ve skutečnosti jsou (přinejmenším) tři běžné variace:

• Buffery, které nejsou spojité ani ve fyzickém adresovém prostoru, ani v (jaderném) prostoru virtuálních adres. Takové jsou všechny buffery pro uživatelský prostor, ale je velmi užitečné alokovat takto i buffery v jaderném prostoru, když je to možné. Bohužel to vždy možné není, pracovat s tímto bufferem obvykle vyžaduje, aby hardware uměl používat DMA operace rozsyp/sesbírej [scatter/gather].

• Buffery, které nejsou fyzicky spojité, ale virtuálně spojité jsou; jinými slovy buffery alokované pomocí vmalloc(). Tyto buffery je pro DMA operace stejně obtížné používat, ale mohou být užitečné v situacích, kde DMA není k dispozici, ale virtuálně spojité buffery se hodí.

• Buffery, které jsou fyzicky spojité. Alokace takového bufferu může být nespolehlivá na systému s fragmentovanou pamětí, ale jednodušší DMA řadiče nic jiného použít neumí.

Videobuf může pracovat se všemi třemi typy bufferu, ale autor ovladače si jeden musí vybrat hned zpočátku a ovladač navrhnout podle tohoto rozhodnutí.

Datové struktury, zpětná volání [callback] a inicializace

V závislosti na tom, které se používají buffery, by měl ovladač vkládat jeden z následujících souborů:

<media/videobuf-dma-sg.h>
<media/videobuf-vmalloc.h>
<media/videobuf-dma-contig.h>

Datové struktury ovladače popisující zařízení V4L2 by měly obsahovat instanci struct videobuf_queue pro správu fronty bufferů, společně s list_head pro frontu dostupných bufferů. Také je potřeba bezpečně přerušitelný [interrupt-safe] spinlock, který bude chránit (přinejmenším) frontu.

Dalším krokem je napsat čtyři jednoduchá zpětná volání, která videobuf pomáhají se správou bufferů:

struct videobuf_queue_ops {
    int (*buf_setup)(struct videobuf_queue *q,
                     unsigned int *count, unsigned int *size);
    int (*buf_prepare)(struct videobuf_queue *q,
                       struct videobuf_buffer *vb,
                       enum v4l2_field field);
    void (*buf_queue)(struct videobuf_queue *q,
                      struct videobuf_buffer *vb);
    void (*buf_release)(struct videobuf_queue *q,
                        struct videobuf_buffer *vb);
};

Funkce buf_setup() se volá na začátku I/O procesu, když se inicializuje proudový přenos; jejím účelem je říci videobuf o I/O proudu. Parametr count je navrhovaný počet bufferů, které se mají použít; ovladač by měl kontrolovat, jestli je rozumný, a v případě potřeby ho upravit. Praktické pravidlo je, že pro funkční proudový přenos jsou potřeba alespoň dva buffery a obvykle existuje maximum (které nemůže překročit 32), které pro každé zařízení dává smysl. Parametr size by měl být nastaven na očekávanou (maximální) velikost každého snímku dat.

Každý buffer (v podobě ukazatele na struct videobuf_buffer) bude předán buf_prepare(), která by měla správně nastavit pole size, width, height a field bufferu. Jestliže je pole state nastaveno na VIDEOBUF_NEEDS_INIT, měl by ho ovladač předat:

int videobuf_iolock(struct videobuf_queue* q, struct videobuf_buffer *vb,
                    struct v4l2_framebuffer *fbuf);

Mezi jinými věcmi toto volání obvykle alokuje pro buffer paměť. Nakonec by funkce buf_setup měla nastavit state (stav) bufferu na VIDEOBUF_PREPARED.

Když je buffer naplánován pro I/O, je předán buf_queue(), která by ho měla přidat na seznam dostupných bufferů a nastavit jeho stav na VIDEOBUF_QUEUED. Tato funkce je volána s tím, že je držen spinlock fronty; pokud se ho pokusí získat také, věci se se skřípěním zastaví. Ano, zde autor hovoří ze zkušenosti. Také berte na vědomí, že videobuf může čekat na první buffer ve frontě; vložit před něj další buffery by také mohlo práci zkazit. Proto pro řazení bufferů do fronty použijte list_add_tail().

A nakonec je buf_release() voláno, když již buffer nemá být nadále používán. Ovladač by měl zajistit, že v bufferu neprobíhá žádné I/O, a předat ho odpovídající funkci k uvolnění:

/* Ovladače rozsyp sesbírej */
int videobuf_dma_unmap(struct videobuf_queue *q,
                       struct videobuf_dmabuf *dma);
int videobuf_dma_free(struct videobuf_dmabuf *dma);

/* Ovladače vmalloc */
void videobuf_vmalloc_free (struct videobuf_buffer *buf);

/* Spojité ovladače */
void videobuf_dma_contig_free(struct videobuf_queue *q,
                              struct videobuf_buffer *buf);

Jeden způsob, jak se ujistit, že se buffer již nepoužívá pro I/O, je předat ho:

int videobuf_waiton(struct videobuf_buffer *vb, int non_blocking, int intr);

vb je zde buffer, non_blocking určuje, jestli se má použít neblokující I/O (v případě buf_release() by měl být nulový), a intr řídí, jestli se používá přerušitelné čekání.

Operace se soubory

V tomto bodě je většina práce hotova; větší část zbytku je vložení volání videobuf do implementace ostatních zpětných volání ovladače. První krok je ve funkci open(), která musí inicializovat frontu videobuf. Kterou funkci použít, závisí na typu použitého bufferu:

void videobuf_queue_sg_init(struct videobuf_queue *q,
                            struct videobuf_queue_ops *ops,
                            struct device *dev,
                            spinlock_t *irqlock,
                            enum v4l2_buf_type type,
                            enum v4l2_field field,
                            unsigned int msize,
                            void *priv);

void videobuf_queue_vmalloc_init(struct videobuf_queue *q,
                            struct videobuf_queue_ops *ops,
                            void *dev,
                            spinlock_t *irqlock,
                            enum v4l2_buf_type type,
                            enum v4l2_field field,
                            unsigned int msize,
                            void *priv);

void videobuf_queue_dma_contig_init(struct videobuf_queue *q,
                                   struct videobuf_queue_ops *ops,
                                   struct device *dev,
                                   spinlock_t *irqlock,
                                   enum v4l2_buf_type type,
                                   enum v4l2_field field,
                                   unsigned int msize,
                                   void *priv);

Ve všech případech jsou parametry stejné:

• q je struktura fronty pro zařízení,
• ops je sada zpětných volání popsaných výše,
• dev je struktura device pro video zařízení,
• irqlock je bezpečně přerušitelný spinlock, který chrání přístup k datovým strukturám,
• type je typ bufferu, který zařízení používá (kamery například použijí V4L2_BUF_TYPE_VIDEO_CAPTURE),
• field popisuje, které pole je zachytáváno (pro progresivní zařízení často V4L2_FIELD_NONE),
• msize je velikost obalovací struktury použité okolo struct videobuf_buffer a
• priv je privátní ukazatel na data, který se objevuje v poli priv_data struct videobuf_queue.

Všimněte si, že jsou to void funkce, které jsou zjevně imunní vůči selhání.

void *dev ve videobuf_queue_vmalloc_init() je poněkud anomální; autor článku (Jonathan Corbet) zaslal patch, který ho mění na struct device *. Ukazatel ops by měl ve skutečnosti být const; to se pravděpodobně změní v 2.6.33.

Zachytávací ovladače V4L2 mohou být napsány tak, aby podporovaly kterékoliv z dvou API: Systémové volání read() a poněkud komplikovanější mechanismus pro proudové přenosy. Obecné pravidlo je, že je potřeba podporovat obě, aby se zajistilo, že budou všechny aplikace schopny se zařízením pracovat. Videobuf zjednodušuje možnosti, jak to udělat se stejným kódem. K implementaci read() ovladač musí pouze volat jednu z:

ssize_t videobuf_read_one(struct videobuf_queue *q,
                          char __user *data, size_t count, 
                          loff_t *ppos, int nonblocking);

ssize_t videobuf_read_stream(struct videobuf_queue *q,
                             char __user *data, size_t count, 
                             loff_t *ppos, int vbihack, int nonblocking);

Každá z těchto funkcí načte data snímku do data a vrátí počet skutečně přečtených; rozdíl je v tom, že videobuf_read_one() přečte jediný snímek, zatímco videobuf_read_stream() přečte několik snímků, pokud to bude zapotřebí, aby se přenesl počet bytů count, který aplikace požaduje. Typická implementace read() ovladače spustí zachytávající engine, zavolá jednu z funkcí výše a nakonec před návratem engine ukončí (i když chytřejší implementace by mohla engine nechat ještě chvíli běžet s očekáváním, že v blízké budoucnosti přijde další volání read()).

Funkci poll() lze obvykle implementovat přímým voláním:

unsigned int videobuf_poll_stream(struct file *file,
                                  struct videobuf_queue *q,
                                  poll_table *wait);

Všimněte si, že skutečná čekací fronta, která se nakonec použije, bude ta spojená s prvním dostupným bufferem.

Když se provádí proudové I/O na bufferech v jaderném prostoru, musí ovladač podporovat systémové volání mmap(), které umožňuje uživatelskému prostoru přistupovat k datům. V mnoha ovladačích V4L2 se často složitá implementace mmap() zjednodušuje na jediné volání:

int videobuf_mmap_mapper(struct videobuf_queue *q,
                         struct vm_area_struct *vma);

Všechno ostatní je řešeno v kódu videobuf.

Funkce release() vyžaduje dvě oddělená volání videobuf:

void videobuf_stop(struct videobuf_queue *q);
int videobuf_mmap_free(struct videobuf_queue *q);

Volání videobuf_stop() ukončí probíhající I/O – i když je stále na ovladači, aby zastavil zachytávající engine. Volání videobuf_mmap_free() se ujistí, že jsou všechny buffery odmapovány; pokud ano, všechny jsou předány zpětnému volání buf_release(). Pokud zůstávají nějaké namapované buffery, vrátí videobuf_mmap_free() chybový kód. Účelem je zjevně to, aby uzavření popisovače souboru selhalo, když jsou buffery stále namapovány – ale všechny ovladače v jádře 2.6.32 návratovou hodnotu vesele ignorují.

ioctl() operace

API V4L2 zahrnuje velmi dlouhý seznam zpětných volání reagujících na ioctl() příkazy, které jsou zpřístupněny uživatelskému prostoru. Mnoho z nich – ty spojené se streamovaným I/O – se téměř okamžitě mění ve volání videobuf. Relevantní pomocné funkce jsou:

int videobuf_reqbufs(struct videobuf_queue *q,
                     struct v4l2_requestbuffers *req);
int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b);
int videobuf_qbuf(struct videobuf_queue *q, struct v4l2_buffer *b);
int videobuf_dqbuf(struct videobuf_queue *q, struct v4l2_buffer *b, 
                   int nonblocking);
int videobuf_streamon(struct videobuf_queue *q);
int videobuf_streamoff(struct videobuf_queue *q);
int videobuf_cgmbuf(struct videobuf_queue *q, struct video_mbuf *mbuf, 
                    int count);

Například volání VIDIOC_REQBUF se mění na volání zpětného volání vidioc_reqbufs() v ovladači, který následně většinou potřebuje pouze nalézt odpovídající ukazatel na struct videobuf_queue a předat ho videobuf_reqbufs() Tyto podpůrné funkce mohou nahradit velkou část kódu pro správu bufferů v mnoha ovladačích V4L2.

Funkce vidioc_streamon() a vidioc_streamoff() jsou samozřejmě o něco složitější, protože se musí také vyrovnat se zapínáním a vypínáním zachytávajícího enginu. videobuf_cgmbuf() volaná z funkce vidiocgmbuf() v ovladači existuje pouze v případě, že byl zapnut modul kompatibility s V4L1 pomocí CONFIG_VIDEO_V4L1_COMPAT, takže jeho použití musí být obaleno direktivami #ifdef.

Alokace bufferů

Zatím jsme mluvili o bufferech, ale nedívali jsme se na to, jak jsou alokovány. Případ s rozsyp/sesbírej je na této frontě ten nejsložitější. U alokace může ovladač nechat alokaci bufferu zcela na vrstvě videobuf; v takovém případě jsou buffery alokovány pomocí vmalloc_32 a budou velmi roztříštěné. Pokud aplikace používá buffery v uživatelském prostoru, není žádná alokace zapotřebí; vrstva videobuf zajistí volání get_user_pages() a seznam pro rozsypání [scatterlist] zaplní takto.

Pokud ovladač potřebuje alokovat paměť sám, měl by to dělat ve funkci vidioc_reqbufs() po volání videobuf_reqbufs(). První krok je volání:

struct videobuf_dmabuf *videobuf_to_dma(struct videobuf_buffer *buf);

Vrácená struktura videobuf_dmabuf (definovaná v <media/videobuf-dma-sg.h>) obsahuje pár relevantních polí:

struct scatterlist  *sglist;
int                 sglen;

Ovladač musí alokovat pole scatterlist vhodné velikosti a nahrát do něj ukazatele na části alokovaného bufferu; sglen by mělo být nastaveno na délku pole.

Ovladače používající metodu vmalloc() se nemusí (a nemohou) zabývat alokací bufferu vůbec; videobuf tyto detaily vyřeší. Totéž platí pro ovladače se spojitým DMA; videobuf alokuje buffer (funkcí dma_alloc_coherent()), když to uzná za vhodné. To znamená, že se tyto ovladače kdykoliv mohou pokusit o alokace vysokých řádů, což je operace, která nemusí vždy uspět. Některé ovladače používají triky, kterými alokují DMA prostor při bootu systému; videobuf v současnosti s těmito ovladači nepracuje dobře.

Plnění bufferů

Poslední část implementace nemá žádné přímé zpětné volání – je to ta část kódu, která vkládá data snímku do bufferů, většinou v reakci na přerušení od zařízení. Pro všechny typy ovladačů tento proces funguje přibližně takto:

1. Získat další dostupný buffer a ujistit se, že na něj opravdu někdo čeká.

2. Získat ukazatel na paměť a vložit tam obrazová data.

3. Označit buffer jako hotový a probudit proces, který na něj čeká.

Krok (1) výše je zajištěn pohledem na strukturu list_head, kterou spravuje ovladač – tu, která byla zaplněna zpětným voláním buf_queue(). Protože zapnutí enginu a zařazení bufferů do fronty probíhá v různých krocích, je možné, aby engine běžel bez dostupných ovladačů – obzvláště v případě vmalloc(). Ovladač by tedy měl být připraven na to, že seznam bude prázdný. Stejně tak je možné, že o buffer ještě nikdo nemá zájem; ovladač by ho neměl odstraňovat ze seznamu nebo ho vyplňovat, pokud na něj nečeká nějaký proces. Tento test lze provést prozkoumáním pole done (struktura wait_queue_head_t) pomocí waitqueue_active().

U ovladačů rozsyp/sesbírej lze potřebné ukazatele na paměť nalézt ve struktuře scatterlist popsané výše. Ovladače používající metodu vmalloc() mohou získat ukazatel do paměti pomocí:

void *videobuf_to_vmalloc(struct videobuf_buffer *buf);

U spojitých DMA ovladačů je potřeba použít funkci:

dma_addr_t videobuf_to_dma_contig(struct videobuf_buffer *buf);

API pro spojité DMA má své vlastní způsoby, jak před ovladači ukrýt adresu DMA bufferu v jaderném prostoru.

Posledním krokem je nastavit pole size relevantní struktury videobuf_buffer na skutečnou velikost zachyceného obrazu, nastavit state na VIDEOBUF_DONE a následně zavolat wake_up na frontu done. Odtud dál buffer vlastní vrstva videobuf a ovladač by se ho již neměl dotýkat.

Závěr

Tento článek pokryl většinu aspektů API videobuf. Vývojáři, kteří mají zájem o další informace, se mohou podívat na relevantní hlavičkové soubory; je v nich několik nízkoúrovňových funkcí, o kterých se zde nemluvilo. Za pozornost také stojí ovladač vivi (drivers/media/video/vivi.c), který je spravován jako příklad, jak mají být psány ovladače V4L2. Vivi používá pouze API vmalloc(), ale to je pro začátek dost dobré. Také si všimněte, že všechna tato volání jsou exportována jako pouze-GPL, takže nejsou dostupná jaderným ovladačům, které nejsou pod GPL.

       

Komentáře

[dan.h]

Jelikož je V4L v configu kernelu uveden trochu podivně v podpoře médií, tak mi trvalo dlouho, než jsem přišel na to, proč mi při loadnutí framebuffer driveru ke grafickmu chipu spadnul obraz (jádro ale běželo dál) - neměl jsem zaškrtnuté V4L při kompilaci. Kupodivu drivery k framebufferům jednotlivých grafických chipů si V4L nezaškrtly jako závislost. Jinak pěkný článek.

[Marek Chlup]

Pro zpracování dvou video analogových signálů (naráz v terénu) jsem pořídil 2x levné USB capture zařízení "Leadtek WinFast VC100 U Video Editor USB 2.0".

Pro funkčnost v Linuxu na jádře 2.6.32 bylo třeba u ovladače em28xx doplnit "usb device id" pro VC100 a sdělit, že jde o "EM2861_BOARD_YAKUMO_MOVIE_MIXER" a ovladač překompilovat.

Zachytávání jednoho videa funguje v celku k mé spokojenosti - jen asi na spodku obrazu je několika pixelový zelený proužek, ale to pro mé účely není velká závada. Zachytávání audia jsem zkoušel letmo jelikož jej nepotřebuji - někde asi jsem dělal chybu jelikož se mi nedařilo.

Co mi však vadí je, že nemohu zachytávat dva videosignály naráz. Mohu připojit do systému obě VC100 zařízení naráz, mohu zachytávat video z jednoho zařízení přerušit ho a pak zachytávat z druhého. Žel nejde to naráz z obou. Respektive podařilo se mi to ve vlc naráz z obou, ale jen při nízkém rozlišení. Pokud jsem však požadoval zachytávání při rozlišení 640x480 tak mi to naráz nešlo a nadávalo to něco kolem nějakého bufferu (zařízení nyní u sebe nemám a tedy nevím přesnou hlášku).

Existuje nějaký obecný problém u V4L2 při snaze zachytávat video ze dvou stejných zařízení připojených do systému? Dá se předpokládat, že můj problém bude hlavně způsoben nedokonalým ovladačem tohoto konkrétního zařízení v jádře? Může někdo poradit nějaké (celkem levné) zařízení pro USB, kde bych uvedené problémy neměl?

Děkuji za případné reakce a omlouvám se, jelikož otázka na tento problém asi není nejvhodnější pod tímto článkem, přestože laicky tuším, že s probíranou problematikou bude dosti souviset.

[Ondrej 'SanTiago' Zajicek]

Zachytavat video signal pri 25 Hz a 640x480 je docela znacny datovy tok. Ani bych se nedivil, kdyby USB sbernice pri dvou takovych streamech proste nestihala.

[Marek Chlup]

Zkusím si pohrát se snímkováním, ale mám obavu, že zde problém nebude - i když to, že mi to při nižším rozlišení šlo, naznačuje, že možná pravdu máte...

Zde například prodávají USB zařízení "Model 2255 - 4 Channel USB Frame Grabber", kde uvádějí, že zvládá 60 snímku/s při NTSC či PAL rozlišení: http://www.sensoray.com/products/2255data.htm Sběrnice USB by to tedy měla zvládat (i když velikost proudu dat ovlivňují ještě různé možnosti při kódování barev). Žel zařízení na které odkazuji, je velmi drahé - 515 USD.

Děkuji za reakci.