diff --git a/Documentation/parameters.txt b/Documentation/parameters.txt deleted file mode 100644 index 9381cd2..0000000 --- a/Documentation/parameters.txt +++ /dev/null @@ -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. - diff --git a/lib/parameter.c b/lib/parameter.c index 6d8ac48..1f683b2 100644 --- a/lib/parameter.c +++ b/lib/parameter.c @@ -20,6 +20,10 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * @file + * @brief Handling device specific parameters + */ #include #include #include @@ -125,3 +129,66 @@ 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. + +*/