Nut upsdev - Aug 2006 - upsdrv_print_ups_list and afferant reflections

Hello ups-dev

Arnaud asked me to add a function upsdrv_print_ups_list the drivers

upsdrv_print_ups_list : why

This function would print the vendorId and the productId of the UPS
supported by the driver (for USB driver at least). It could then be
parsed by a tool (that I'll have to make too), whose the goal would be
to automagically generate 4 sort of file :
 - fdi file for HAL
 - udev rules file for udev
 - hotplug usermap for hotplug
 - Html array to have a compatibility list

This way, one just have to modify a table in the driver to says which
UPS it support and then to run this tool, and no more have to manually
create those 4 files.

In the same time, we could create a structure that contains the
VendorId and ProductId supported, and introduce then a generic way to
make a claim function.

For the moment, some claim function just look at the VendorId. But a
vendor can do other things than UPS, or make a new UPS that don't use
the same USB protocol as the last UPS this vendor created, leading to
a subdriver that claim an hardware it cannot support. Having a list of
supported UPS and looking for match as well in VendorId and in
ProductId solve this problem.

But it bring another problem (life is never simple ;-) : What if a
producer make a new product under a new ProductId, but this product
can perfectly be managed by the subdriver ? Would the users have to
manually modify the sources of the subdriver to add this productId and
compile NUT again ? Or would they need to wait the next release for us
just to add a line in a driver ?

A way to solve it would be to externalize this information out of the
driver, to allow users to modify it. But, as pointed out Arnaud, it
first can be dangerous if a user make a mistake, and secondly, if a
user find a couple of VendorId ProductId that is in fact supported by
a subdriver but not in the list yet, there are chances that this user
would not tell us about it (and then we won't add it in the next
release).

As a compromise, I propose to let the information in the drivers, but
to add a way to force newhidups to use a specific subdriver without
using the claim function.
This way, as user cannot modify it easily, we have more chance he or
she will ask the question on the list. if we would find that this UPS
is supported but not added in the list yet, we will add it in future
release (for the benefit of all users), and until the next release is
out, we can answer the user that he or she can force the use of this
subdriver without any risk.

Do you have any comment about it ? reactions ?

Your faithfully,

Jonathan Dion

On 8/2/06, Jonathan Dion <dion.jonathan@gmail.com>
wrote:
> Hello ups-dev
>
> Arnaud asked me to add a function upsdrv_print_ups_list the drivers
>
> upsdrv_print_ups_list : why
>
> This function would print the vendorId and the productId of the UPS
> supported by the driver (for USB driver at least). It could then be
> parsed by a tool (that I'll have to make too), whose the goal would be
> to automagically generate 4 sort of file :
>  - fdi file for HAL
>  - udev rules file for udev
>  - hotplug usermap for hotplug
>  - Html array to have a compatibility list
>
> This way, one just have to modify a table in the driver to says which
> UPS it support and then to run this tool, and no more have to manually
> create those 4 files.
That sounds like a good idea. I was pondering how we could do this
another way, where drivers.list is the source file, and it generates
matching code for individual drivers, but your way allows us to
extract information from drivers contained in binary packages.

I assume you would have the output parsable by your new configuration
file library?

Another thing to consider is to have a "matching score", where some
drivers have higher confidence that they can handle a certain VID/PID,
but less confidence if they only match the VID. The override could be
done by lowering the minimum required match confidence level.

-- 
- Charles Lepple

Jonathan Dion wrote:
> 
> Hello ups-dev
> 
> Arnaud asked me to add a function upsdrv_print_ups_list the drivers
> 
> upsdrv_print_ups_list : why
> 
> This function would print the vendorId and the productId of the UPS
> supported by the driver (for USB driver at least). It could then be
> parsed by a tool (that I'll have to make too), whose the goal would be
> to automagically generate 4 sort of file :
>  - fdi file for HAL
>  - udev rules file for udev
>  - hotplug usermap for hotplug
>  - Html array to have a compatibility list
I don't see how this last one (the compatibility list) can be
generated from the vendorId and productId. Shouldn't compatibility be
based on devices that have been reported to work by users, rather than
what the driver writer thought? Some manufacturers use the same
productId for many different devices, some of which work better than
others. 
 
> This way, one just have to modify a table in the driver to says which
> UPS it support and then to run this tool, and no more have to manually
> create those 4 files.
> 
> In the same time, we could create a structure that contains the
> VendorId and ProductId supported, and introduce then a generic way to
> make a claim function.
When I designed the claim function, I made it a function on purpose
(rather than a data structure). The reason is that there will
invariably be future cases where compatibility cannot be decided based
on simple pre-set criteria, such as vendorId and productId.
 
> For the moment, some claim function just look at the VendorId. But a
> vendor can do other things than UPS, or make a new UPS that don't use
> the same USB protocol as the last UPS this vendor created, leading to
> a subdriver that claim an hardware it cannot support. Having a list of
> supported UPS and looking for match as well in VendorId and in
> ProductId solve this problem.
The reason I did not add ProductId's to all the claim functions was
because I did not want to break drivers that previously worked. We had
never compiled a complete list of ProductId's for a given vendor. 
 
In any case, the problem would not be fully solved, as there can be
many devices with identical ProductId's, but different driver
details. Also, if the user wants to select a specific device (say,
they have several HID devices by APC, only one of which is a UPS),
then can always use the regular expression mechanism in the
configuration file (vendor, product, serial, bus) to select the
specific device they want.  
> But it bring another problem (life is never simple ;-) : What if a
> producer make a new product under a new ProductId, but this product
> can perfectly be managed by the subdriver ? 
Exactly.
> Would the users have to manually modify the sources of the subdriver
> to add this productId and compile NUT again ? Or would they need to
> wait the next release for us just to add a line in a driver ?
Currently they would have to modify the source, if the productId was
hard-wired. 
> A way to solve it would be to externalize this information out of the
> driver, to allow users to modify it. 
In my opinion, this is a bad idea (see above for why "claim" is a
function, and not a data structure).
> But, as pointed out Arnaud, it first can be dangerous if a user make
> a mistake, and secondly, if a user find a couple of VendorId
> ProductId that is in fact supported by a subdriver but not in the
> list yet, there are chances that this user would not tell us about
> it (and then we won't add it in the next release).
>  
> As a compromise, I propose to let the information in the drivers, but
> to add a way to force newhidups to use a specific subdriver without
> using the claim function.
That is probably a good idea. A "subdriver" argument would be
sufficient. It would be easy to modify the "claim" mechanism. However,
when doing this, subdrivers should get nicknames, i.e., 
"./newhidups -x subdriver=apc" would look a lot better than
"./newhidups -x subdriver=APC/CyberPower HID 0.9".
Also, if the user selects a subdriver that doesn't exist (or --help),
a list of available subdrivers should be printed.
> This way, as user cannot modify it easily, we have more chance he or
> she will ask the question on the list. if we would find that this UPS
> is supported but not added in the list yet, we will add it in future
> release (for the benefit of all users), and until the next release is
> out, we can answer the user that he or she can force the use of this
> subdriver without any risk.
> 
> Do you have any comment about it ? reactions ?
> 
> Your faithfully,
> 
> Jonathan Dion
> 
> _______________________________________________
> Nut-upsdev mailing list
> Nut-upsdev@lists.alioth.debian.org
> http://lists.alioth.debian.org/mailman/listinfo/nut-upsdev
>