[PATCH 00/16] Add import from/export to file functionality

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Dear Matt,

This quite big series adds new part of libusbg API which allows to
import/export gadget/function/configuration from/to file.

Motivation:

Libusbg allows to create a binary file which set up custom
gadget. This is useful but if we have to create custom binary for
each gadget we wast a lot of work which kernel people put to separate
code from configuration. This leads us to main idea of gadget
schemes. Allow to create simple, human readable config file which
library will be able to translate into usb gadget.

Description:

Gadget schemes is idea of describing gadget/function/configuration in
config file. To not reinvent the wheel I have used existing library
libconfig [1]. This means that the syntax is similar to this described
in documentation of libconfig.

I have extended the library with set of usbg_export_*() functions
which allows to export selected gadget to given FILE. There is also
set of complementary usbg_import_*() functions which allows to read
scheme of gadget/function/config from file and create it using
configfs.

To avoid name conflict I have used the convention that
usbg_import_gadget() function takes name of new gadget as parameter
and usbg_export_gadget() doesn't export gadget name to scheme
file. Similar idea is used in configuration and functions.

Base convention of gadget schemes is simple: if something is not set
in scheme file, default values provided by kernel are used. Moreover
configfs has some attributes which are read only. To allow to store
them in scheme file they are ignored by import functions.

Usage of libconfig and whole design of gadget schemes allows us to use
include directive in gadget definition to import complicated
configurations or functions.

Syntax and detailed rules of using schemes has been described in
gadget_schemes.txt in commit:

 libusbg: doc: Add document about gadget schemes

Example:

I have used the gadget-acm-ecm example to create a gadget and then
exported it and imported.  Gadget exported using usbg_export_gadget():

$ gadget-export g1 g1.schema
$ cat g1.schema

attrs =
{
    bcdUSB = 0x200
    bDeviceClass = 0x0
    bDeviceSubClass = 0x0
    bDeviceProtocol = 0x0
    bMaxPacketSize0 = 0x40
    idVendor = 0x1D6B
    idProduct = 0x104
    bcdDevice = 0x1
}
strings = (
    {
        lang = 0x409
        manufacturer = "Foo Inc."
        product = "Bar Gadget"
        serialnumber = "0123456789"
    } )
functions =
{
    acm_usb0 =
    {
        instance = "usb0"
        type = "acm"
        attrs =
        {
            port_num = 0
        }
    }
    acm_usb1 =
    {
        instance = "usb1"
        type = "acm"
        attrs =
        {
            port_num = 1
        }
    }
    ecm_usb0 =
    {
        instance = "usb0"
        type = "ecm"
        attrs =
        {
            dev_addr = "aa:bb:f9:ca:76:fb"
            host_addr = "a2:ad:a2:3f:c8:6f"
            qmult = 5
        }
    }
}
configs = (
    {
        id = 1
        name = "The only one"
        attrs =
        {
            bmAttributes = 0x80
            bMaxPower = 0x2
        }
        strings = (
            {
                lang = 0x409
                configuration = "CDC 2xACM+ECM"
            } )
        functions = (
            {
                name = "acm.GS0"
                function = "acm_usb0"
            },
            {
                name = "acm.GS1"
                function = "acm_usb1"
            },
            {
                name = "ecm.usb0"
                function = "ecm_usb0"
            } )
    } )

This is quite verbose because it contains read only attributes and
some default ones. This file can be shorten to:

attrs =
{
    bcdUSB = 0x200
    bMaxPacketSize0 = 0x40
    idVendor = 0x1D6B
    idProduct = 0x104
    bcdDevice = 0x1
}
strings = (
    {
        lang = 0x409
        manufacturer = "Foo Inc."
        product = "Bar Gadget"
        serialnumber = "0123456789"
    } )
functions =
{
    acm_usb0 =
    {
        instance = "usb0"
        type = "acm"
    }
    acm_usb1 =
    {
        instance = "usb1"
        type = "acm"
    }
    ecm_usb0 =
    {
        instance = "usb0"
        type = "ecm"
        attrs =
        {
            dev_addr = "aa:bb:f9:ca:76:fb"
            host_addr = "a2:ad:a2:3f:c8:6f"
            qmult = 5
        }
    }
}
configs = (
    {
        id = 1
        name = "The only one"
        strings = (
            {
                lang = 0x409
                configuration = "CDC 2xACM+ECM"
            } )
        functions = (
            {
                name = "acm.GS0"
                function = "acm_usb0"
            },
            {
                name = "acm.GS1"
                function = "acm_usb1"
            },
            {
                name = "ecm.usb0"
                function = "ecm_usb0"
            } )
    } )

Remarks:

Current version of libconfig has no possibility to select output
format details. I have created a patch and set up github pull request
and this patch is waiting for maintainer review[2], so results of
usbg_export_*() may be slightly different in format but both layouts
are acceptable by import functions.

Summary:

I have created a pull request also for this series:

https://github.com/libusbg/libusbg/pull/8

Feel free to provide your comments about the whole idea and also about
its implementation.

Footnotes:
1 - http://www.hyperrealm.com/libconfig/
2 - https://github.com/hyperrealm/libconfig/pull/13

--
BR's
Krzysztof Opasiak
Samsung R&D Institute Poland
Samsung Electronics
k.opasiak@xxxxxxxxxxx

Krzysztof Opasiak (16):
  libusbg: Add dependency to libconfig
  libusbg: Add guards for libconfig version
  libusbg: Add label field to usbg_function structure
  libusbg: Add export function functionality
  libusbg: Add export config functionality
  libusbg: Add export gadget functionality
  libusbg: examples: Add sample application to export gadget
  libusbg: Add error which may happen during parsing
  libusbg: Allow to store error information in usbg_gadget
  libusbg: Add import function functionality
  libusbg: Add import config functionality
  libusbg: Allow to store error information in usbg_state
  libusbg: Add import gadget functionality
  libusbg: Add functions to get import error text and line
  libusbg: examples: Add gadget-import sample app
  libusbg: doc: Add document about gadget schemes

 configure.ac             |    1 +
 doc/gadget_schemes.txt   |  301 ++++++++
 examples/Makefile.am     |    4 +-
 examples/gadget-export.c |   81 +++
 examples/gadget-import.c |   79 ++
 include/usbg/usbg.h      |  110 +++
 libusbg.pc.in            |    2 +-
 src/Makefile.am          |    4 +-
 src/usbg.c               | 1822 +++++++++++++++++++++++++++++++++++++++++++++-
 9 files changed, 2400 insertions(+), 4 deletions(-)
 create mode 100644 doc/gadget_schemes.txt
 create mode 100644 examples/gadget-export.c
 create mode 100644 examples/gadget-import.c

-- 
1.7.9.5

--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Linux Media]     [Linux Input]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [Old Linux USB Devel Archive]

  Powered by Linux