FunctionFS descriptors and strings support

[andrzejtp]

While not strictly related to composing a gadget with ConfigFS, creating the descriptors and strings is an important step of creating custom USB gadget functions on top of FunctionFS. As such, they are a perfect target for the Gadget Tool.

Following the idea of keeping the state in a place external to gt (configfs in case of gadgets' state), the state of descriptors and strings is kept in external binary files, whose filename is specified the usual way: either explicitly with --state= or using default values.

Descriptors (interface and endpoint) and strings (languages and strings proper) are created either on the command line, or by reading from declarative config files.

Example invocation to store the descriptors in my-descs.bin:

gt ffs interface create --state=my-descs.bin number=0 cls=6 subcls=1 protocol=1 str_idx=1 speed=fs
gt ffs interface create --state=my-descs.bin number=0 cls=6 subcls=1 protocol=1 str_idx=1 speed=hs

gt ffs endpoint create --state=my-descs.bin speed=fs number=0 address=0x81 type=BULK max=64 interval=0
gt ffs endpoint create --state=my-descs.bin speed=fs number=0 address=0x02 type=BULK max=64 interval=0
gt ffs endpoint create --state=my-descs.bin speed=fs number=0 address=0x83 type=INTR max=64 interval=6

gt ffs endpoint create --state=my-descs.bin speed=hs number=0 address=0x81 type=BULK max=512 interval=0
gt ffs endpoint create --state=my-descs.bin speed=hs number=0 address=0x02 type=BULK max=512 interval=0
gt ffs endpoint create --state=my-descs.bin speed=hs number=0 address=0x83 type=INTR max=64 interval=6

The equivalent can be achieved with this config file:

fs : {
	interfaces = (
		{
			cls = 6
			subcls = 1
			protocol = 1
			str_idx = 1
			endpoints = (
				{ address = 0x81, type = 2, max = 64, interval = 0 },
				{ address = 0x02, type = 2, max = 64, interval = 0 },
				{ address = 0x83, type = 3, max = 64, interval = 6 }
			)
		}
	)
}

hs : {
	interfaces = (
		{
			cls = 6
			subcls = 1
			protocol = 1
			str_idx = 1
			endpoints = (
				{ address = 0x81, type = 2, max = 512, interval = 0 },
				{ address = 0x02, type = 2, max = 512, interval = 0 },
				{ address = 0x83, type = 3, max = 64, interval = 6 }
			)
		}
	)
}

and this command line:

gt ffs descriptors load --state=my-gadget.bin --file=my-gadget.descs 

Strings are created or loaded in a similar fashion:

gt ffs language create  --state=my-strings.bin code=0x409
gt ffs string create --state=my-strings.bin lang=0x409 str=ABC

or with a config file:

languages = (
	{
		code = 0x409
		strs = ( "MTP Device" )
	}
)

and this command line:

gt ffs strings load --state=my-strings.bin my-gadget.strs

One thing to note with strings is that two assumptions have been made:

1. The first language created defines the number of strings all languages must provide
2. The (currently) last language can be incomplete to allow completing it with subsequent invocations of gt, as each invocation adds one string only.

[kopasiak]

HI Andrzej,

after some review I've realized that we have two issues in this file format (or actually the same issue in two instances)

1. there is sth called IAD (Interface association descriptor) which is supported by functionfs but I don't see a way how to include it in the file format that you proposed

2. In super speed we have endpoint companion descriptor which has to follow the endpoint descriptor and I don't see how we could fit that in the proposed file format

[pabs3]

@andrzejtp did you get a chance to revise the changes for @kopasiak's comments?

[andrzejtp]

Hi Paul, Unfortunately not. It is likely I will not have time until September. Andrzej W dniu 13.07.2021 o 05:37, Paul Wise pisze:

…

@andrzejtp <https://github.com/andrzejtp> did you get a chance to revise the changes for @kopasiak <https://github.com/kopasiak>'s comments? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#8 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALETVHII4KSQ5KBD6FI5VG3TXOYIZANCNFSM4HSJLROQ>.

[pabs3]

@andrzejtp here is a ping in case you have time for this.