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
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* @brief Handling device specific parameters
|
||||
*/
|
||||
#include <common.h>
|
||||
#include <param.h>
|
||||
#include <errno.h>
|
||||
|
@ -125,3 +129,66 @@ int dev_add_param(struct device_d *dev, struct param_d *newparam)
|
|||
|
||||
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