Move the parameter's documentation where it belongs to
Signed-off-by: Juergen Beisert <j.beisert@pengutronix.de>
This commit is contained in:
parent
e217509033
commit
afd482e833
|
@ -1,52 +0,0 @@
|
||||||
---------- Device parameters --------------
|
|
||||||
|
|
||||||
Devices have several parameters. In case of a network device this may be the
|
|
||||||
ip address, networking mask or similar and users need access to these
|
|
||||||
parameters. in U-Boot this is solved with device paramters. Device parameters
|
|
||||||
are always strings, although there are functions to interpret them as
|
|
||||||
something else. hush users can access parameters as a local variable which
|
|
||||||
have a dot (.) in them. So setting the ip address of the first ethernet
|
|
||||||
device is a matter of typing 'eth0.ip=192.168.0.7' on the console and can
|
|
||||||
then be read back with 'echo $eth0.ip'. The devinfo command shows a summary
|
|
||||||
about all devices currently present. If called with a device id as parameter
|
|
||||||
it shows the parameters available for a device.
|
|
||||||
|
|
||||||
Device parameters programming API
|
|
||||||
---------------------------------
|
|
||||||
|
|
||||||
struct param_d {
|
|
||||||
char* (*get)(struct device_d *, struct param_d *param);
|
|
||||||
int (*set)(struct device_d *, struct param_d *param, const char *val);
|
|
||||||
ulong flags;
|
|
||||||
char *name;
|
|
||||||
struct param_d *next;
|
|
||||||
char *value;
|
|
||||||
};
|
|
||||||
|
|
||||||
int dev_add_param(struct device_d *dev, struct param_d *par);
|
|
||||||
|
|
||||||
This function adds a new parameter to a device. At least the name field in
|
|
||||||
the new parameter struct has to be initialized. The 'get' and 'set' fields
|
|
||||||
can be set to NULL in which case the framework handles them. It is also
|
|
||||||
allowed to implement only one of the get/set functions. Care must be taken
|
|
||||||
with the initial value of the parameter. If the framework handles the set
|
|
||||||
function it will try to free the value of the parameter. If this is a
|
|
||||||
static array bad things will happen. A parameter can have the flag
|
|
||||||
PARAM_FLAG_RO which means that the parameter is readonly. It is perfectly ok
|
|
||||||
then to point the value to a static array.
|
|
||||||
|
|
||||||
const char *dev_get_param(struct device_d *dev, const char *name);
|
|
||||||
|
|
||||||
This function returns a pointer to the value of the parameter specified
|
|
||||||
with dev and name.
|
|
||||||
If the framework handles the get/set functions the parameter value strings
|
|
||||||
are alloceted with malloc and freed with free when another value is set for
|
|
||||||
this parameter. Drivers implementing set/get themselves are allowed to
|
|
||||||
return values in static arrays. This means that the pointers returned from
|
|
||||||
dev_get_param() are only valid until the next call to dev_get_param. If this
|
|
||||||
is not long enough strdup() or similar must be used.
|
|
||||||
|
|
||||||
int dev_set_param(struct device_d *dev, const char *name, const char *val);
|
|
||||||
|
|
||||||
Set the value of a parameter.
|
|
||||||
|
|
|
@ -20,6 +20,10 @@
|
||||||
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @file
|
||||||
|
* @brief Handling device specific parameters
|
||||||
|
*/
|
||||||
#include <common.h>
|
#include <common.h>
|
||||||
#include <param.h>
|
#include <param.h>
|
||||||
#include <errno.h>
|
#include <errno.h>
|
||||||
|
@ -125,3 +129,66 @@ int dev_add_param(struct device_d *dev, struct param_d *newparam)
|
||||||
|
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** @page dev_params Device parameters
|
||||||
|
|
||||||
|
@section params_devices Devices can have several parameters.
|
||||||
|
|
||||||
|
In case of a network device this may be the IP address, networking mask or
|
||||||
|
similar and users need access to these parameters. In U-Boot this is solved
|
||||||
|
with device paramters. Device parameters are always strings, although there
|
||||||
|
are functions to interpret them as something else. 'hush' users can access
|
||||||
|
parameters as a local variable which have a dot (.) in them. So setting the
|
||||||
|
IP address of the first ethernet device is a matter of typing
|
||||||
|
'eth0.ip=192.168.0.7' on the console and can then be read back with
|
||||||
|
'echo $eth0.ip'. The @ref devinfo_command command shows a summary about all
|
||||||
|
devices currently present. If called with a device id as parameter it shows the
|
||||||
|
parameters available for a device.
|
||||||
|
|
||||||
|
@section params_programming Device parameters programming API
|
||||||
|
|
||||||
|
@code
|
||||||
|
struct param_d {
|
||||||
|
char* (*get)(struct device_d *, struct param_d *param);
|
||||||
|
int (*set)(struct device_d *, struct param_d *param, const char *val);
|
||||||
|
ulong flags;
|
||||||
|
char *name;
|
||||||
|
struct param_d *next;
|
||||||
|
char *value;
|
||||||
|
};
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
@code
|
||||||
|
int dev_add_param(struct device_d *dev, struct param_d *newparam);
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
This function adds a new parameter to a device. At least the name field in
|
||||||
|
the new parameter struct has to be initialized. The 'get' and 'set' fields
|
||||||
|
can be set to NULL in which case the framework handles them. It is also
|
||||||
|
allowed to implement only one of the get/set functions. Care must be taken
|
||||||
|
with the initial value of the parameter. If the framework handles the set
|
||||||
|
function it will try to free the value of the parameter. If this is a
|
||||||
|
static array bad things will happen. A parameter can have the flag
|
||||||
|
PARAM_FLAG_RO which means that the parameter is readonly. It is perfectly ok
|
||||||
|
then to point the value to a static array.
|
||||||
|
|
||||||
|
@code
|
||||||
|
const char *dev_get_param(struct device_d *dev, const char *name);
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
This function returns a pointer to the value of the parameter specified
|
||||||
|
with dev and name.
|
||||||
|
If the framework handles the get/set functions the parameter value strings
|
||||||
|
are alloceted with malloc and freed with free when another value is set for
|
||||||
|
this parameter. Drivers implementing set/get themselves are allowed to
|
||||||
|
return values in static arrays. This means that the pointers returned from
|
||||||
|
dev_get_param() are only valid until the next call to dev_get_param. If this
|
||||||
|
is not long enough strdup() or similar must be used.
|
||||||
|
|
||||||
|
@code
|
||||||
|
int dev_set_param(struct device_d *dev, const char *name, const char *val);
|
||||||
|
@endcode
|
||||||
|
|
||||||
|
Set the value of a parameter.
|
||||||
|
|
||||||
|
*/
|
||||||
|
|
Loading…
Reference in New Issue