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
Changes since v1:
- fix typos
- add missing "" in doc
- add missing goto statements in usbg_import_*()
- move unmerged libconfig functions usage to separate series
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
