Предлагаем погрузиться в мир Human Interface Device (HID) в контексте операционной системы реального времени «Нейтрино». В статье мы расскажем про архитектуру HID и коснемся практических аспектов создания драйверов для устройств ввода.

Кроме того, затронем вопросы системной разработки и изучения драйверного API для встраиваемых систем реального времени. Расскажем, почему создание драйверов для взаимодействия с HID-устройствами является достаточно важным, но, при этом, достаточно простым процессом.

Общее представление архитектуры HID драйверов

Для того чтобы полностью раскрыть потенциал HID-устройств, требуется изучить их природу и механизмы взаимодействия.

HID подразумевает стандарт, который определяет протокол обмена данными между устройствами ввода. Он сыграл ключевую роль в вычислительных системах. Помог обеспечить универсальное и простое взаимодействие между пользователем, различным оборудованием и компьютером: от клавиатур до геймпадов, от мышей до сенсорных экранов. Все это создает интерфейс между человеком и машиной.

Чтобы можно было классифицировать HID-устройство из обилия оборудования, способного работать в соответствии с определенными правилами, была разработана спецификация с учетом следующих принципов:

• Минимизация объема программного кода, необходимого для функционирования устройства.
• Возможность программного обеспечения верифицировать информацию, поступающую от устройства.
• Проектирование протокола с возможностью расширения и стабильной работой. Сам протокол состоит из дескриптора репорта и отчетов.

Ниже перечислены основные характеристики и требования к функционированию HID-устройства:

1. Скорость передачи данных: в контексте USB существуют полноскоростное и низкоскоростное HID-устройства. Первые способны передавать до 60 000 байт в секунду, что соответствует 64 байтам в каждом кадре длительностью 1 мс, а вторые имеют скорость передачи 800 байт в секунду, что соответствует 8 байтам каждые 10 мс.
2. HID-устройство может устанавливать частоту своего опроса для проверки наличия новых данных для передачи;
3. Обмен данными с использованием протокола репортов: вся связь с HID-устройством осуществляется через структуру, называемую "дескриптор репорта" (report descriptor). Дескриптор репорта может содержать до 65 535 байт данных и имеет гибкую структуру для его модифицирования.
4. HID-устройство должно содержать дескриптор устройства и один или более дескрипторов репорта;
5. Поддержка управляющих запросов.

Для разработчика HID-драйвера важно реализовать поддержку структур, описывающих HID-интерфейс, и обеспечить обмен данными.

В нашей ОС общая структура взаимодействия устройств ввода с системой выглядит так:

HID-драйвер состоит из дескриптора модуля драйвера и интерфейса организации драйвера. Их взаимное расположение в архитектуре имеет вид:

HID-драйвер представляет собой программный модуль, который обеспечивает взаимодействие между HID-менеджером и HID-устройствами.

Драйвер принимает на себя задачу интерпретации данных, поступающих от HID-устройства, для их правильного восприятия HID-менеджером. Это подразумевает не только определение стандартных действий пользователя (клик мыши, нажатие клавиши на клавиатуре), но и предоставление удобного интерфейса для управления HID-устройством.

Как уже было сказано выше, HID-драйвер напрямую "общается" с устройством, что позволяет быстро реагировать на контакт пользователя с устройством ввода.

HID-драйвер изнутри

Для детального понимания из чего же состоит HID-драйвер разберем его составляющие:

1. io_hid_dll_entry_t – структура, определяющая модуль драйвера:

   
   

     #include <sys/io-hid.h>
   
     typedef struct _io_hid_dll_entry
     {
         char    *name;
         int     nfuncs;
         int     (*init)( void *dll_hdl, dispatch_t *dpp,
                          io_hid_self_t *ioh, char *args );
         int     (*shutdown)( void *dll_hdl );
     } io_hid_dll_entry_t;

   
   

   Она включает поля name (имя драйвера), nfuncs (количество функций модуля драйвера), init и shutdown (функции инициализации и деинициализации).

   
   

2. io_hid_registrant_funcs_t – структура, определяющая интерфейс драйвера:

   
   

     #include <sys/io-hid.h>
   
     typedef struct _io_hid_registrant_funcs
     {
         _Uint32t    nfuncs;
         int         (*client_attach)( int reg_hdl, void *user );
         int         (*client_detach)( int reg_hdl, void *user );
         /* … */
     } io_hid_registrant_funcs_t;

   
   

   io_hid_registrant_funcs_t содержит набор функций для взаимодействия HID-драйвера с HID-устройством, иначе – управляющие запросы. Каждая функция вызывается по определенном запросу от HID-менеджера. Например, client_attach/client_detach вызываются в том случае, когда клиент подключается/отключается к/от io-hid. Более подробно изучить назначение каждого управляющего запроса можно тут.

   
   

Теперь мы имеем представление о том, что из чего состоит HID-драйвер. Остается узнать, как он должен функционировать, и написать код, к примеру, для подключаемой по RS-232 мыши.

Имплементация HID-Драйвера

Заполняем структуру io_hid_dll_entry_t

#include <sys/io-hid.h>

io_hid_dll_entry_t io_hid_dll_entry = {
    "devh-sample",
    _IO_HID_DLL_NFUNCS,
    init,
    stop
};

name будет использоваться для определения библиотеки при монтировании в io-hid. Префикс “devh-” является обязательным и обусловлен процессом парсинга HID-менеджером имен драйверов. _IO_HID_DLL_NENTRY – макрос для определения количества функций в структуре io_hid_dll_entry_t.

io-hid -d sample &

io-hid &
mount -T io-hid devh-sample.so

Заведем глобальную структуру для хранения выделяемых/предоставляемых ресурсов и структуру для регистрации управляющего дескриптора:

typedef struct _ctrl
{
    void                *dll_hdl;
    io_hid_self_t       *ioh;
    char                *path;
    pthread_t           tid;
    int                 fd;
} ctrl_t;

typedef struct _sample
{
    int                 hid_hdl;
} sample_t;

ctrl_t  Ctrl;

Управляющий дескриптор будет передаваться в управляющие вызовы, где будем заполнять необходимые поля или использовать их, но в первую очередь она необходима для хранения зарегистрированного дескриптора модуля драйвера (hid_hdl).

В этих структурах можно объявлять н-ое количество полей. В нашем примере содержатся базово необходимые поля для реализации драйвера.

io_hid_dll_entry_t :: init

Выше упомянуто, что это инициализирующая функция. Она вызывается при монтировании библиотеки в io-hid.
В ней необходимо выполнить следующие шаги:

• Обработать опции (в нашем случае реализуем одну опцию – путь к менеджеру ресурсов serial-порта):

  
  

  char *opts[] = {
      "path",
      NULL
  };
  
  int start_driver( char *options )
  {
      char *value;
  
      Ctrl.path = "/dev/ser1";
  
      while ( options && *options != '\0' )
      {
          switch ( getsubopt( &options, opts, &value ) )
          {
              case 0:
                  if ( value != NULL )
                      Ctrl.path = value;
                  break;
              default:
                  break;
          }
      }
  
      return (EOK);
  }

  
  

• Заполнить hidd_device_ident_t и io_hid_registrant_t, а также зарегистрировать дескриптор отчета:

  
  

  static unsigned char rdesc[] = {
      /* ... */
  };
  
  int get_report_descriptor ( sample_t *sample )
  {
      hidd_device_ident_t device_ident;
      io_hid_registrant_t dev;
      int                 sample_hdl;
  
      int result = EOK;
  
      device_ident.vendor_id = 0;
      device_ident.product_id = 0;
      device_ident.version = 0x100;
  
      dev.flags = 0;
      dev.device_ident = &device_ident;
      dev.desc = rdesc;
      dev.dlen = sizeof (rdesc);
      dev.user_hdl = sample;
  
      dev.funcs = &sample_funcs;
  
      result = (*Ctrl.ioh->reg)( Ctrl.dll_hdl, &dev, &sample_hdl );
      if ( result == EOK )
          sample->hid_hdl = sample_hdl;
  
      return (result);
  }

  
  

  В hidd_device_ident_t объявляется информация об устройстве ввода, которая потом передается io_hid_registrant_t – регистрирующую дескриптор устройства.

  
  

• Создать поток для получения данных:

  
  

  void *event_hdl_polling( void *data )
  {
      sample_t            *sample;
      uint8_t             buffer[256];
      int                 count, i;
      uint32_t            packet_len;
  
      sample = (sample_t *)data;
  
      memset( buffer, 0, sizeof( uint8_t ) * 256 );
  
      for ( ;; )
      {  
          memset( buffer, 0, sizeof( uint8_t ) * 256 );
  
          count = read( Ctrl.fd, buffer, sizeof( uint8_t ) * 256 );
          if ( count > 0 )
          {
              /* 
               * Здесь необходима реализация обработки принятых
               * данных в соответствии с протоколом устройства,
               * заложенным производителем
               */
  
              /* ... */
  
              /* Когда обработали данные отправляем их в io-hid */
              (*Ctrl.ioh->send_report)( sample->hid_hdl,
                                        (uint8_t *)buffer,
                                        (uint32_t)packet_len );
          }
      }
  
      return NULL;
  }

  
  

Тогда функция инициализации будет иметь следующий вид:

int init( void *dll_hdl, dispatch_t *dpp, io_hid_self_t *ioh, char *args )
{
    pthread_attr_t      attr;
    sample_t            sample;

    int result = EOK;

    Ctrl.dll_hdl = dll_hdl;
    Ctrl.ioh     = ioh;

    ThreadCtl( _NTO_TCTL_IO, 0 );

    memset( &Ctrl, 0, sizeof( Ctrl ) );

    start_driver( args );

    if ( (Ctrl.fd = open( Ctrl.path, O_RDONLY )) == -1 )
        return (EXIT_FAILURE);

    get_report_descriptor( &sample );

    pthread_attr_init( &attr );

    result = pthread_create( &Ctrl.tid, &attr,
                                (void *)event_hdl_polling, &sample );

    if ( result != EOK )
        return (EXIT_FAILURE);

    return (EOK);
}

static unsigned char rdesc[] = {
    0x05, 0x01,     // Usage Page(Generic Desktop)
    0x09, 0x02,     // Usage (Mouse)
    0xa1, 0x01,     // Collection(Application)
    0x09, 0x01,         // Usage(Pointer)
    0xa1, 0x00,         // Collection(Physical)
    0x05, 0x09,             // Usage Page(Button)
    0x19, 0x01,             // Usage Min(1)
    0x29, 0x03,             // Usage Max(3)
    0x15, 0x00,             // Logical Min(0)
    0x25, 0x01,             // Logical Max(1)
    0x95, 0x03,             // Report Count(3)
    0x75, 0x01,             // Report Size(1)
    0x81, 0x02,             // Input(Data,Variable,Absolute)
    0x95, 0x01,             // Report Count(1)
    0x75, 0x05,             // Report Size(5)
    0x81, 0x03,             // Input(Cnst,Variable,Absolute)
    0x05, 0x01,             // Usage Page(Generic Desktop)
    0x09, 0x30,             // Usage(X)
    0x09, 0x31,             // Usage(Y)
    0x15, 0x81,             // Logical Min(-127)
    0x25, 0x7F,             // Logical Max(127)
    0x75, 0x08,             // Report Size(8)
    0x95, 0x02,             // Report Count(2)
    0x81, 0x06,             // Input(Data,Variable,Rel)
    0xc0,               // End Collection
    0xc0            // End Collection
};

io_hid_dll_entry_t :: stop

При демонтировании библиотеки необходимо освободить все выделенные в init ресурсы. В нашем случае следует завершить поток и закрыть дескриптор менеджера ресурсов.

int stop( void *dll_hdl )
{
    pthread_cancel( Ctrl.tid );
    pthread_join( Ctrl.tid, NULL );
    close( Ctrl.fd );

    return (EOK);
}

Заполняем структуру io_hid_registrant_funcs_t

Внимательный читатель, возможно, заметил, что при заполнении io_hid_registrant_t мы не рассказали про sample_funcs. Выше упоминалось про структуру io_hid_registrant_funcs_t – sample_funcs является ею.

Сначала реализуем управляющие функции. Если функции не будут выполнять никаких действий, то необходима stub реализация с кодом возврата EOK. Например:

int client_attach( int reg_hdl, void *user )
{
    return (EOK);
}

В нашем примере все функции реализованы заглушками.

Заполняем io_hid_registrant_funcs_t макросом _IO_HID_REG_NFUNCS и функциями:

#include <sys/io-hid.h>

static io_hid_registrant_funcs_t sample_funcs = {
    _IO_HID_REG_NFUNCS,
    client_attach,
    client_detach,
    rbuffer_alloc,
    rbuffer_free,
    report_read,
    report_write,
    get_idle,
    set_idle,
    get_protocol,
    set_protocol,
    get_string,
    get_indexed_string,
    reset,
};

В итоге получаем шаблон драйвера для мыши RS-232, нуждающегося лишь в реализации обработки входных данных.

Схема работы типичного HID-драйвера будет выглядеть так:

С примерами реально работающих драйверов вы можете ознакомиться по ссылке. Там представлены HID-драйвера для USB-тачскринов Egalax и GPIO-клавиатур.

Вместо заключения

В этой статье мы постарались кратко и доступно описать процесс реализации HID-драйверов для операционной системы реального времени Нейтрино. Подробную информацию про драйверное API вы можете найти по ссылке.

Стоит добавить, что в данном примере мы разобрали частный случай взаимодействия с устройством. Если присутствует готовый инструмент (менеджер ресурсов) для управления ресурсами интерфейса (I2C, SPI, etc.), то оптимальным способом будет использовать его. В противном случае от разработчика потребуется реализовать обработку прерываний с чтением регистров.

Подписывайтесь на наш канал, чтобы быть в курсе свежих новостей