Accediendo a los registros propietarios de un CMOS de Omnivision a través de la interfaz USB 2.0 - El código fuente

Traducción del original en catalán. Léela en: CatalàEnglish

camerachip.jpg
Omnivision 2610

Para que no suene tanto a japonés lo que digo lo intentaré explicar por partes. Se trata de hacer lo que planteaba en el artículo: Problema amb OVTDTool: Omnivision 2610 ECX. O sea, que disponemos de un kit de desarrollo de la cámara Omnivision OV2610 que lleva un sensor de imágenes CMOS y un chip Cypress que comunica el sensor CMOS con el PC a través de una interfaz USB 2.0. Así pues para acceder a los registros propietarios del CMOS se tiene que hacer usando 'usb vendor requests'. Es decir, enviar paquetes de 'request' al chip de USB indicando que queremos acceder a registros propietarios del CMOS. Cuando hablo de registros propietarios lo que quiero decir es que no son registros estándar USB 2.0 sino que son específicos del fabricante para este producto.

En este caso lo que esto nos permite hacer es activar/desactivar funciones de autoajuste: AGC (auto gain control), AWB (auto white balance), etc. también podemos hacer otras cosas como fijar parámetros que por defecto tienen otros valores, como la luminosidad, contraste, componentes de color RGB, etc. O sea, que podemos hacer trabajar la cámara (sensor CMOS) como a nosotros nos interese.

Un poco de teoría para saber lo que tenemos que hacer

Para entender cómo funciona la tecnología USB si no queréis comprar ningún libro hay una web que lo explica de una forma extraordinaria: USB in a NutShell ( pdf ). Allí podréis ver que hay unos elementos lógicos dentro de los dispositivos USB que se llaman ENDPOINTS concretamente hay un tipo de ENDPOINTS que se llaman "Control Transfers" estos son los que se usan para enviar comandos de configuración. Funcionalidades de los ENDPOINT de tipo CONTROL TRANSFER sería:

Las transferencias de control se usan normalmente para operaciones de comando y estado. Son esenciales para configurar un dispositivo USB con todas las funciones de enumeración realizándose mediante transferencias de control. Normalmente son paquetes a ráfagas y aleatorios que inicia el host y usan entrega de mejor esfuerzo. La longitud de paquete de las transferencias de control en dispositivos de baja velocidad debe ser de 8 bytes, los dispositivos de alta velocidad permiten un tamaño de paquete de 8, 16, 32 o 64 bytes y los dispositivos de velocidad completa deben tener un tamaño de paquete de 64 bytes.

Así pues estos son los paquetes de más bajo nivel que tenemos que generar para configurar el dispositivo. Como lo que queremos es no complicarnos tanto la vida lo que hacemos es procurar generar estos paquetes desde capas más elevadas y así no bajar tanto de nivel en problemas que no son el nuestro. Por ejemplo, retransmisiones, confirmaciones de recepción, control de ventanas de envío, etc. Por tanto, lo que nos interesará es el concepto de "USB Descriptors":

Todos los dispositivos USB tienen una jerarquía de descriptores que describen al host información como qué es el dispositivo, quién lo fabrica, qué versión de USB soporta, de cuántas formas se puede configurar, el número de endpoints y sus tipos etc

Concretamente los descriptores se organizan según la siguiente jerarquía:

desctree.gif

Tamaño Original

Como podemos observar en el gráfico el descriptor que nos interesa es el "Endpoint Descriptor" que son los que nos permiten acceder a los CONTROL TRANSFERs que he comentado antes. Si miramos la estructura de datos que define un ENDPOINT DESCRIPTOR podemos observar que tiene un campo de 8 bits llamado "bmAttributes" en este campo los primeros dos bits nos permiten definir el "Transfer Type" y de aquí podemos extraer que el valor que nos interesa es "00" para estos dos bits, o sea, "CONTROL". Con esto le estaremos diciendo al paquete que sea del tipo CONTROL TRANSFER cuando salga del ENDPOINT.

Para poder configurar nuestro paquete no nos queda más remedio que seguir escalando en el stack hasta llegar a los "Setup packets":

Todo dispositivo USB debe responder a los paquetes de setup en el pipe por defecto. Los paquetes de setup se usan para la detección y configuración del dispositivo y llevan a cabo funciones comunes como establecer la dirección del dispositivo USB, solicitar un descriptor de dispositivo o comprobar el estado de un endpoint.

Y aquí tenemos lo que queríamos, el formato del paquete que realmente queremos enviar como podemos ver se trata de un paquete muy sencillo de solo 8 bytes, que tenemos que configurar bit a bit. El primer campo de 8 bits: bmRequestType sirve para definir el tipo de request que vamos a hacer, estos 8 bits se dividen en 3 grupos y hay que escoger los grupos de bits adecuados para nuestra petición. O sea:

  • 1er grupo: Data Phase Transfer Direction (1bit) 0 Host to device y 1 Device to Host
  • 2on grupo: Type (2 bits) 00 Standard, 01 Class, 10 Vendor, 11 reserved. Para nuestro caso el que nos interesa sería el 10 Vendor, porque queremos acceder a registros no estándar USB sino propietarios del fabricante del CMOS.
  • 3er grupo: Recipient (5 bits) 00000 Device, 00001 Interface, 00010 Endpoint, 00011 Ohter, el resto están reservados. Para nuestro caso el que nos interesa es el 00000 Device.

Hasta aquí tenemos los primeros 8 bits definidos, o sea: 0xc0 (11000000) 'leamos' del device y 0x40 (1000000) 'escribimos' al device. Estos serían los valores que hay que recordar. Los otros 4 campos:

  • bRequest (8bits) pondremos el registro con valor 0x2 para escribir y con valor 0x3 para leer. Hay que fijarse en el datasheet de vuestro producto para saber exactamente lo que queréis poner en este campo, ya que esto como ya he dicho, son comandos específicos del fabricante.
  • wValue (16bits) aquí pondremos el valor que queremos que tenga el registro que queremos escribir.
  • wIndex (16bits) indicamos el registro que queremos acceder, ya sea para escribir o para leer
  • wLength (16bits) longitud del mensaje que queremos recibir cuando leemos. Normalmente son 8 o 16 bits. Suelen ser valores fijos, cuando estamos hablando de registros propietarios del vendedor.

Hasta aquí la teoría. Todo parece muy confuso por lo tanto, aprovecho para volver a recomendar el leerse y comprender profundamente el documento que he referenciado. He explicado todo esto porque si no sería imposible entender qué queremos hacer realmente. Ya que en la práctica todo acaba resumiéndose a unas pocas líneas de código.

Objetivo práctico

Como ya sabemos lo que queremos hacer, ahora solo falta saber cómo lo tenemos que hacer. Lo primero que nos hace falta es hacer un programa que nos permita acceder directamente al dispositivo a bajo nivel y nos dé una interfaz a nivel de usuario para acceder a las funciones concretas de esto se le llama un driver. Cosa que no parece que nos interese demasiado hacer porque ya tenemos uno de driver y ya va bastante bien, no se trata de reprogramarlo. Así pues como no tenemos las funciones de espacio de usuario de nuestro driver documentadas este se nos queda pequeño. Lo que podríamos hacer es programar un filter driver, estos solo funcionan en arquitecturas basadas en NT (2K, XP y 2k3) lo que hacen es colocarse sobre el driver existente y cambiar su comportamiento solo en algunos aspectos y cuando alguna aplicación de espacio de usuario lo requiere, así pues para el resto de aplicaciones son transparentes y estas pueden trabajar con el driver nativo sin problemas.

Obviamente esto también puede representar un trabajo enorme y más para alguien que no domina el DDK (Device Drivers Kit) de M$ y la arquitectura WDM (Windows Driver Model). Pero he encontrado una librería de espacio de usuario para acceder de forma genérica a dispositivos USB y además esta implementa un filter driver que puede instalarse sobre el driver genérico del dispositivo. Eso nos permite programar con 4 líneas lo que queramos y tener el driver genérico del fabricante con el que funcionan todos los programas disponibles para este.

Para nuestro problema solo tenemos que hacer 4 líneas en C invocando la librería que he nombrado y ella misma ya se encarga de trabajar contra el filter driver. Además tenemos completamente especificada la API de esta librería. Si todo esto os parece poco os puedo decir que se basa en un proyecto multiplataforma Unix y que el código es 100% portable con muy pocas modificaciones. Además con licencia GPL, claro. Así pues aquí tenéis el gran hallazgo libusb-win32. De serie veréis que trae una aplicación que nos descubre los dispositivos USB conectados a nuestro sistema. Es un buen ejemplo para empezar a familiarizarse con cómo usar la librería.

NOTA: las libusb-win32 también nos permiten crear drivers en espacio de usuario y no solo trabajar con filter drivers, solo tenemos que programar nuestro código usando la API del driver genérico que implementan.

Cómo trabajar con libusb-win32

Lo primero que tenéis que hacer es bajaros esto libusb-win32-filter-bin-0.1.10.1.exe (local) lo instaláis sin ningún dispositivo USB conectado al sistema, si puede ser. Esto lo que hará es instalaros el filter driver, si no lo veis tranquilos no es trivial, -pensad que no es un driver sino que está sobre el mismo- y 3 archivos .lib uno para usar a través del compilador GCC, otro para el compilador de Borland (BCC) y finalmente para el Visual Studio (MSVC). El último caso ha sido mi caso. También nos instala un archivo llamado usb.h que es el que tenemos que usar para compilar nuestro programa y no el usb.h que trae el DDK. Así pues id con cuidado al definir las dependencias del compilador y el linkador del MSVC.

Yo he instalado el paquete en c:\drivers\libusb, esto lo comento porque a continuación os pongo unas capturas de pantalla de cómo he modificado los 'settings' del proyecto de MSVC para que este sea capaz de compilar y linkar mi programa.

Dentro del MSVC si vamos a Project -> Settings:

captura3.png
Settings

Podemos definir los includes especiales de nuestro proyecto, necesarios para el proceso de compilación:

captura1.png
Settings de compilación

Y las librerías a usar en el proceso de linkado:

captura2.png
Settings del proceso de linkado

Ahora ya somos capaces de hacer un programa que trabaje con las libusb-win32, solo tenemos que añadir el #include <usb.h> al principio de nuestro código y a disfrutar de la API de las libusb.

Pongamos la teoría en práctica

En pocas palabras vamos a escribir el código que me hacía falta, después de tanta historia. Vamos por pasos, lo primero que hay que hacer es saber cómo inicializar el dispositivo y buscar los dispositivos USB conectados al sistema:

captura5.png
Código

Una vez tenemos la lista de dispositivos USB conectados al sistema iteramos por los mismos en busca de nuestra cámara. Como no espero tener más de una cámara conectada al mismo ordenador no lo he tenido en cuenta en el código. Lo que he hecho es coger una aplicación de análisis de buses USB y descubrir el identificador del fabricante (idVendor) y del producto (idProduct). En mi caso: idVendor = 0x05a9 (Omnvision) e idProduct = 0x2800 (OV2610). Así pues buscamos esto:

captura6.png
Código

Una vez hemos identificado nuestro dispositivo llega la hora de poner en práctica todo lo que habíamos aprendido hace un rato. Así pues vamos a construir nuestros paquetes de control (setup packets) que acceden a registros propios del fabricante. En este ejemplo lo que hago es acceder al registro número 0x13 y guardar su valor en el buffer, después lo muestro por pantalla. Después modificamos el valor de registro 0x13 y le damos el valor 0x15 seguidamente lo volvemos a leer y a mostrar por pantalla para comprobar que ha cambiado de valor.

captura7.png
Código

Para saber qué hay en cada registro, qué valores puede tener y qué significan, tenéis que buscarlo en la documentación de cada fabricante. En mi caso esto lo he encontrado en el datasheet del CMOS de Omnivision que es de las pocas cosas que nos dio el fabricante al comprar el 'development kit'.

El código lo he comentado muchísimo por lo tanto, considero que queda más que claro cómo funciona el mismo. Si lo queréis descargar: ov.c. Si queréis el ejecutable directamente para probarlo: ov.exe, aunque dudo que os sirva de algo ya que este .exe solo funciona con el development kit que he usado.

La salida del programa es la siguiente:

captura8.png
Código

Podemos comprobar cómo el valor anterior del registro 0x13 es 0xcf y cómo nuestro programa cambia el valor a 0x15, así pues. ¡¡¡FUNCIONA!!!

Conclusiones

Podéis comprobar cómo todo el 'rollo' de teoría inicial sirve para entender cómo tenemos que formar las peticiones usb_vendor_msg() de la librería libusb-win32. Sin comprender cómo funciona la arquitectura USB a fondo era imposible saber cómo se tenían que formar estas peticiones. De hecho, os tengo que confesar que yo lo que hice fue aplicar ingeniería inversa ya que disponía de una herramienta de debugging del producto (OVTDTool.exe) que me permitía acceder a estos registros y después gracias a un asistente de creación de drivers -Jungo- pude poner en práctica la teoría que he explicado. El problema era que este software no me permitía crear filter drivers que trabajaran con el driver que ya tenía de la cámara y me obligaba a crear mi propio driver desde 0.

Así pues, a grandes problemas grandes soluciones y después de continuar formándome descubrí este gran invento de los 'filter drivers' y el que ya me hizo ver la luz fue la librería libusb-win32 que me ha permitido con muy poco tiempo encontrar la salida a este 'aparentemente complicado problema'. Ahora se puede ver que no lo era tanto.