From a21908edf5d9c8f15754e86e22e49389cb2bb1b9 Mon Sep 17 00:00:00 2001 From: Krzysztof Opasiak Date: Tue, 29 Oct 2013 14:25:18 +0100 Subject: [PATCH] First approach to design of gadget tool. Adds a document which describes reasons of this project, goal to achieve and proposed command line calls. Change-Id: I65f5e5a59d5b1b0ef7040755f207f32ccd2e021c Signed-off-by: Krzysztof Opasiak --- design_doc/BigPicture.txt | 413 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 413 insertions(+) create mode 100644 design_doc/BigPicture.txt diff --git a/design_doc/BigPicture.txt b/design_doc/BigPicture.txt new file mode 100644 index 0000000..f559ce0 --- /dev/null +++ b/design_doc/BigPicture.txt @@ -0,0 +1,413 @@ + Author: Opasiak Krzysztof + k.opasiak (at) samsung.com + + + + === Gadget Tool === + + ==== The Big Picture ==== + + +======================================== +Content: + 1. Problem Description + 2. Goals + 3. Proposed command line calls + 4. Detailed description + +======================================== + + 1. Problem Description + + Till intruduction of ConfigFS composite gadget in Linux kernel USB +gadgets could be only statically formed. This means that each USB gadget have +it's own module wher set of function was defined by programmer while writting +this module. To run such gadget user could simply: + + $ modprobe [additional options] + +The usage of the old convention was easy but unflexible. User could not form +custom gadget without writting a new module. + + ConfigFS has separated code of functions and configuration. This means +that there is a set of modules which implements each one USB function and the +gadget is build in runtime by creating directories, files and symbolic links. +To set up a gadget using Config FS user need to execute at least: + + $ cd $CONFIGFS_HOME + $ mkdir + $ mkdir configs/. + $ mkdir functions/. + $ ln -s functions/ configs/ + $ echo > UDC + +Gadget creation is quite easy but it needs five times more commands than +without using ConfigFS! Users are lazy so they will use a method which needs +less work. + +Current state is a consequence of ConfigFS design goals. One of the requirements +was to allow user configure gadget without any external tool. The kernel goal +has been reached, gadget can be configured without any tools but it's not a +comfortabale method for end users. That's why I decided to create this tool, +make linux users life better. Let's create better solutions together! + +======================================== + + 2. Goals + + The main goal is to allow user set up an USB gadget using only one +commandjust like using modprobe. This goal is absolutly a must and it has to be +achieved. + Second goal is to wrap file system operations (mkdir, ln -s echo etc.) +with gadget specific commands. It would be great if a user could simply set +some parameters of configuration/device/function with dedicated command line +calls instead of direct manipulation on config file system. + Third goal is to allow user share gadgets with other users with simply +provideing them some file. This will allow linux distributiors to provide a set +of standard gadget configurations and to achieve first goal. + Fourth goal is to allow user share their functions and configurations. +This goal is not so important as third goal but it's a nice feature to allow +user to share not only whole gadget but also a part of it. + +======================================== + + 3. Proposed command line calls + + === 3.1 Gadget tool settings and MIX === + + ==== 3.1.1 Commands ==== + +Shows the list of available udc + + $ gt udc + +Sets the variable to a given value + + $ gt settings set = + +Get's the value of all variable or variables passed as parameters + + $ gt settings get [variable] + +Used for variables which contains a list. Appends the value to the list +represented by variable + + $ gt settings append + +Used for variables which contains a list. Removes a value from list +represented by variable. + + $ gt settings detach + + + ==== 3.1.2 Settings variable list ==== + +UDC on which gadgets should be enabled by default. +If unset and only one udc is availiable that one is taken as default + + default-udc + +Path where config fs has been mounted + + config-fs-path + +List of paths which where gt should look for gadgets, configs and functions + + lookup-path + +Path where templates should be stored. Default could be /etc/gt/templates + + default-template-path + +Default gadget to be load. By setting value of this variable user can sibly +write gt load and $default-gadget will be loaded and enabled. + + default-gadget + + === 3.2 Gadget === + + ==== 3.2.1 Gadget view, creation and manipulation ==== + +Creates a gadget with a specified name and sets its attributes to given +values. +Options: +-f --force - override the gadget if gadget with this name already exist + + $ gt create [attr=val] + +Removes a gadget with given name. Gadget should not contain any configuration +or function, unless -r --recursive option is used. +Options: +-f --force - disable gadget before removing if gadget is enabled +-r --recursive - recursively removes all configurations and functions if any + + $ gt rm + +Prints to standard output names of attributes and their current values. If +attr has not been given, all attributes are printed. + + $ gt get [attr] + +Sets givent attributes to new values. If an attribute should be created the +name should be completed with / and it's value set to 1, or to 0 +if attr should be removed. For example gt set gadget1 strings/0x415/=1 creates +a directory 0x415 in strings directory, and then you can simply set values of +attributes below that directory - gt set gadget1 +strings/0x415/manofacturer="Polski producent" + + $ gt set = + +Enables gadget on udc. If gadget has not been specified and only one exist +than one is taken. If more than one gadget exist including default one the +default is taken, else command faill due to ambigous gadget. That same rule is +used while choosing an udc. +Options: +-g= --gadget= - specifies gadget to enable +-u= --udc= - specifies udc to enable gadget on it + + $ gt enable + +Disable gadget. If gadget has been specified it is disabled, otherwise: if +only one gadget exist it is used, if more than one gadget exist including +default gadget, the default is disabled else error due to ambigous gadget name +unless -u or --udc option was used. +Options: +-u= --udc= - disables a gadget which is active at given udc + + $ gt disable [gadget] + +If no gadget specified shows the list of gadgets, otherwise shows the gadget +name, list of configurations and list of functions. +Options: +-v --verbose - shows not only the name of gadget but also it's attributes +-r --recursive - shows the details about each function and configuration +attributes + + $ gt gadget [gadget] + + ==== 3.2.1 Gadget template manipulation ==== + +If no name specified shows the list of templates, otherwise shows the template +name, list of configurations and list of functions. +Options: +-v --verbose - shows not only the name of gadget but also it's attributes +-r --recursive - shows the details about each function and configuration +attributes + + $ gt template [name] + +Loads the gadget settings related to name, creates and enables the created +gadget. +Options: +-o --off Don't enable gadget after load +--file= loads gadget from file instead of from paths +--stdin loads gadget from stdin +--path= loads gadget located in some path instead of from standard paths + + $ gt load [gadget name] + +Stores the gadget configuration in system templates as name. If name not +specified gadget's name is used. Sets the template attributes to given values. +Options: +-f --force override gadget template if exist +--file= stores in file +--stdout prints the configuration to standard output +--path= stores gadget in given path instead of default + + $ gt save [name] [template_attr=val] + +Prints to standard output names of template attributes and their current +values. If attr has not been given, all attributes are printed. + + $ gt template get [template_attr] + +Sets givent attributes to new values. + + $ gt template set = + +Removes gadget template with specified name. + + $ gt template rm + + === 3.3 Configuration === + + ==== 3.3.1 Configuration view, creation and manipulation ==== + +Creates a configuration in given gadget and sets its attributes to given +values. +Options: +-f --force - override the config if config with this name already exist + + $ gt config create [attr=val] + +Removes a config from gadget. Config should not contain any functions, +unless -r --recursive option is used. +Options: +-f --force - disable gadget before removing if gadget is enabled +-r --recursive - recursively removes all functions if any + + $ gt config rm + +Prints to standard output names of attributes and their current values. If +attr has not been given, all attributes are printed. + + $ gt config get [attr] + +Sets givent attributes to new values. If an attribute should be created the +name should be completed with / and it's value set to 1, or to 0 +if attr should be removed. For example gt config set gadget1 c.1 +strings/0x415/=1 creates a directory 0x415 in strings directory, and then you +can simply set values of attributes below that directory - gt config set +gadget1 strings/0x415/configuration="Konfiguracja" + + $ gt config set = + +If no config specified shows the list of configs, otherwise shows the config +name and list of functions. +Options: +-v --verbose - shows not only the name of config but also it's attributes +-r --recursive - shows the details about each function + + $ gt config [config name] + +Appends specified function to configuration. Function can be specified as + or directly as . + + $ gt config add + $ gt config add + +Removes specified function from configuration. Function can be specified as + or directly as . + + $ gt config del + $ gt config del + + ==== 3.3.1 Config template manipulation ==== + +If no name specified shows the list of templates, otherwise shows the template +name and list of functions. +Options: +-v --verbose - shows not only the name of config but also it's attributes +-r --recursive - shows the details about each function and attributes + + $ gt config template [name] + +Loads the config settings related to name. +Options: +--file= loads gadget from file instead of from paths +--stdin loads config from stdin +--path= loads config located in some path instead of from standard paths +-r --recursive loads also function which this config contains +-f --force overrides functions if functions with such names already exist + + $ gt config load [config name] + +Stores the configuration and it's function in system templates as name. +If name not specified config name is used. Sets the template attributes to +given values. +Options: +-f --force override gadget template if exist +--file= stores in file +--stdout prints the configuration to standard output +--path= stores config in given path instead of default + + $ gt config save [name] [template_attr=val] + +Prints to standard output names of template attributes and their current +values. If attr has not been given, all attributes are printed. + + $ gt config template get [template_attr] + +Sets givent attributes to new values. + + $ gt config template set = + +Removes config template with specified name. + + $ gt config template rm + + === 3.4 Function === + + ==== 3.4.1 Function view, creation and manipulation ==== + +Creates a function in given gadget and sets its attributes to given +values. +Options: +-f --force - override the function if function with this name already exist + + $ gt func create [attr=val] + $ gt func create + +Removes a config from gadget. Config should not contain any functions, +unless -r --recursive option is used. +Options: +-f --force - disable gadget before removing if gadget is enabled + + $ gt func rm + $ gt func rm + +Prints to standard output names of attributes and their current values. If +attr has not been given, all attributes are printed. + + $ gt func get [attr] + $ gt func get [attr] + +Sets givent attributes to new values. If an attribute should be created the +name should be completed with / and it's value set to 1, or to 0 +if attr should be removed. For example gt func set gadget1 mass_storage.f1 +lun.1/=1 creates a directory lun.1 in function directory, and then you can +simply set values of attributes below that directory - gt func set gadget1 +mass_storage.f1 lun.1/file=/root/some_image.img + + $ gt func set = + $ gt func set = + +If no function specified shows the list of functions, otherwise shows the +function name and list of first level attributes. +Options: +-v --verbose - shows all levels of atributes + + $ gt func [ ] + $ gt func [function] + + === 3.4.2 Function template manipulation ==== + +If no function specified shows the list of functions, otherwise shows the +function name and list of first level attributes. +Options: +-v --verbose - shows all levels of atributes + + $ gt func template [name] + +Loads the function related to name. +Options: +--file= loads gadget from file instead of from paths +--stdin loads function from stdin +--path= loads function located in some path instead of standard paths +-f --force overrides function if function with such names already exist + + $ gt func load [func name] + +Stores the configuration and it's function in system templates as name. +If name not specified function is used. Sets the template attributes to +given values. +Options: +-f --force override func template if exist +--file= stores in file +--stdout prints the function to standard output +--path= stores function in given path instead of default + + $ gt func save [name] [template_attr=val] + +Prints to standard output names of template attributes and their current +values. If attr has not been given, all attributes are printed. + + $ gt func template get [template_attr] + +Sets givent attributes to new values. + + $ gt func template set = + +Removes config template with specified name. + + $ gt func template rm -- 2.7.4