--- /dev/null
+ 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 <gadget_module> [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 <gadget name>
+ $ mkdir configs/<config name>.<config number>
+ $ mkdir functions/<fucion type>.<instance name>
+ $ ln -s functions/<fucion> configs/<configuration>
+ $ echo <udc name> > 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 <variable>=<value>
+
+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 <variable> <value>
+
+Used for variables which contains a list. Removes a value from list
+represented by variable.
+
+ $ gt settings detach <variable> <value>
+
+
+ ==== 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 <gadget name> [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 <gadget name>
+
+Prints to standard output names of attributes and their current values. If
+attr has not been given, all attributes are printed.
+
+ $ gt get <gadget name> [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 <gadget_name> <attr>=<val>
+
+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> --gadget=<gadget> - specifies gadget to enable
+-u=<udc> --udc=<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> --udc=<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=<gadget_file> loads gadget from file instead of from paths
+--stdin loads gadget from stdin
+--path=<path> loads gadget located in some path instead of from standard paths
+
+ $ gt load <name> [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=<gadget_file> stores in file
+--stdout prints the configuration to standard output
+--path=<path> stores gadget in given path instead of default
+
+ $ gt save <gadget> [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 <name> [template_attr]
+
+Sets givent attributes to new values.
+
+ $ gt template set <name> <attr>=<val>
+
+Removes gadget template with specified name.
+
+ $ gt template rm <name>
+
+ === 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 <gadget name> <config name> [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 <gadget name> <config name>
+
+Prints to standard output names of attributes and their current values. If
+attr has not been given, all attributes are printed.
+
+ $ gt config get <gadget name> <config name> [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 <gadget name> <config name> <attr>=<val>
+
+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 <gadget name> [config name]
+
+Appends specified function to configuration. Function can be specified as
+<type> <instance> or directly as <type>.<instance>
+
+ $ gt config add <gadget name> <conf name> <func type> <func name>
+ $ gt config add <gadget name> <conf name> <function>
+
+Removes specified function from configuration. Function can be specified as
+<type> <instance> or directly as <type>.<instance>
+
+ $ gt config del <gadget name> <conf name> <func type> <func name>
+ $ gt config del <gadget name> <conf name> <function>
+
+ ==== 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=<config_file> loads gadget from file instead of from paths
+--stdin loads config from stdin
+--path=<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 <name> <gadget name> [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=<config_file> stores in file
+--stdout prints the configuration to standard output
+--path=<path> stores config in given path instead of default
+
+ $ gt config save <gadget> <config> [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 <name> [template_attr]
+
+Sets givent attributes to new values.
+
+ $ gt config template set <name> <attr>=<val>
+
+Removes config template with specified name.
+
+ $ gt config template rm <name>
+
+ === 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 <gadget name> <func type> <func name> [attr=val]
+ $ gt func create <gadget name> <function>
+
+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 <gadget name> <func type> <func name>
+ $ gt func rm <gadget name> <function>
+
+Prints to standard output names of attributes and their current values. If
+attr has not been given, all attributes are printed.
+
+ $ gt func get <gadget name> <func type> <func name> [attr]
+ $ gt func get <gadget name> <function> [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 <gadget name> <func type> <func name> <attr>=<val>
+ $ gt func set <gadget name> <funcition> <attr>=<val>
+
+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 <gadget name> [<func type> <func name>]
+ $ gt func <gadget name> [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=<func file> loads gadget from file instead of from paths
+--stdin loads function from stdin
+--path=<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 <name> <gadget name> [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=<gadget_file> stores in file
+--stdout prints the function to standard output
+--path=<path> stores function in given path instead of default
+
+ $ gt func save <gadget> <function> [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 <name> [template_attr]
+
+Sets givent attributes to new values.
+
+ $ gt func template set <name> <attr>=<val>
+
+Removes config template with specified name.
+
+ $ gt func template rm <name>
projects / platform / upstream / gt.git / commitdiff