How to document dimension units for virtual files?

How to document dimension units for virtual files?

[Michael Holzheu]

For the s390 hypervisor filesystem (s390_hypfs) we export performance
and status information to user space. In order to make parsing for
programs as easy as possilbe, we export exactly one value in one file
without adding the dimension unit to the output string.

For example:

cat /hypfs/cpus/onlinetime
476362365

cat /hypfs/memory
900620

As far as I know that is the recommended way of exporting such data
to user space, right?

The question is how to provide the dimension unit information to
the user.

I see three possibilites:

1. Write dimension unit into the output string (e.g. "476362365 kB"),
which makes parsing a bit more complicated.

2. Encode dimension unit into filename (e.g. onlinetime_ms or memory_kb)

3. Document dimension unit somewhere. In that case we need some central
place to provide such information. E.g. in the Documentation directory of
the linux kernel.

So, what is the recommended way?

Thanks!

Michael

Re: How to document dimension units for virtual files?

[Ingo Oeser]

Hi Michael,

On Monday, 23. October 2006 14:32, Michael Holzheu wrote:
> The question is how to provide the dimension unit information to
> the user.
> 
> I see three possibilites:
> 
> 1. Write dimension unit into the output string (e.g. "476362365 kB"),
> which makes parsing a bit more complicated.
> 
> 2. Encode dimension unit into filename (e.g. onlinetime_ms or memory_kb)

This is the recommended one.
- simple to implement and understand on both sides

- if you change units, you notice breaking userspace immediately
  and can even notice it being used in closed source tools 
  with a simple strace

- no parsing involved, as the author of the user space tool 
  usually assumes the unit implicitly (like "programming by contract", where
  the "contract" is the filename, which is quite easy to check for.

- you can keep a legacy interface with neglible effort and code wastage

- many advantages I forgot :-)

> 3. Document dimension unit somewhere. In that case we need some central
> place to provide such information. E.g. in the Documentation directory of
> the linux kernel.

Regards

Ingo Oeser

Re: How to document dimension units for virtual files?

[Michael Holzheu]

Hi Ingo,

Ingo Oeser <ioe-lkml@rameria.de> wrote on 10/23/2006 09:03:32 PM:

[snip]

> > 2. Encode dimension unit into filename (e.g. onlinetime_ms or
memory_kb)
>
> This is the recommended one.
> - simple to implement and understand on both sides
>
> - if you change units, you notice breaking userspace immediately
>   and can even notice it being used in closed source tools
>   with a simple strace
>
> - no parsing involved, as the author of the user space tool
>   usually assumes the unit implicitly (like "programming by contract",
where
>   the "contract" is the filename, which is quite easy to check for.
>
> - you can keep a legacy interface with neglible effort and code wastage
>
> - many advantages I forgot :-)
>

I also think that this is the best solution. It would be nice to have
that documented somewhere. Maybe in the Documentation directory
something like:

Howto export data in virtual files
==================================

If you want to export data to userspace via virtual filesystems
like procfs, sysfs, debugfs etc., the following rules are recommended:

- Export only one value in one virtual file.
- Data format should be as simple as possible.
- Use ASCII formated strings, no binary data if possible.
- If data has dimension units, encode that in the filename.
  Please use the following suffixes:
  * kb: Kilobytes
  * mb: Megabytes
  * ms: Milliseconds
  * us: Microseconds
  * ns: Nanoseconds
  * ...

Examples:
---------
> ls /sys/mydata
memory_kb
online_time_ms

> cat /sys/mydata/memory_kb
4769

Michael

Re: How to document dimension units for virtual files?

[Arnd Bergmann]

On Tuesday 24 October 2006 16:15, Michael Holzheu wrote:
> If you want to export data to userspace via virtual filesystems
> like procfs, sysfs, debugfs etc., the following rules are recommended:
>
> - Export only one value in one virtual file.
> - Data format should be as simple as possible.
> - Use ASCII formated strings, no binary data if possible.
> - If data has dimension units, encode that in the filename.
>   Please use the following suffixes:
>   * kb: Kilobytes
>   * mb: Megabytes
>   * ms: Milliseconds
>   * us: Microseconds
>   * ns: Nanoseconds
>   * ...

For larger units like kb or mb, why bother at all?
You can just make that a 64 bit number and give an exact value.
You should also be sure to use a correct unit, i.e.
KiB for 1024 bytes and kB for 1000 bytes.

	Arnd <><

Re: How to document dimension units for virtual files?

[Pavel Machek]

Hi!

> > > 2. Encode dimension unit into filename (e.g. onlinetime_ms or
> memory_kb)
> >
> > This is the recommended one.
> > - simple to implement and understand on both sides
> >
> > - if you change units, you notice breaking userspace immediately
> >   and can even notice it being used in closed source tools
> >   with a simple strace
> >
> > - no parsing involved, as the author of the user space tool
> >   usually assumes the unit implicitly (like "programming by contract",
> where
> >   the "contract" is the filename, which is quite easy to check for.
> >
> > - you can keep a legacy interface with neglible effort and code wastage
> >
> > - many advantages I forgot :-)
> >
> 
> I also think that this is the best solution. It would be nice to have
> that documented somewhere. Maybe in the Documentation directory
> something like:
> 
> Howto export data in virtual files
> ==================================
> 
> If you want to export data to userspace via virtual filesystems
> like procfs, sysfs, debugfs etc., the following rules are recommended:

...yes please... such patch would be nice.

> - Export only one value in one virtual file.
> - Data format should be as simple as possible.
> - Use ASCII formated strings, no binary data if possible.
> - If data has dimension units, encode that in the filename.
>   Please use the following suffixes:
>   * kb: Kilobytes
>   * mb: Megabytes

just use B for bytes....

-- 
Thanks for all the (sleeping) penguins.

Re: How to document dimension units for virtual files?

[Michael Holzheu]

Pavel, Ingo,

Pavel Machek <pavel@ucw.cz> wrote on 10/28/2006 07:40:48 PM:
> Hi!
> 
> > > > 2. Encode dimension unit into filename (e.g. onlinetime_ms or
> > memory_kb)
> > >
> > > This is the recommended one.
> > > - simple to implement and understand on both sides
> > >

[snip]

> > I also think that this is the best solution. It would be nice to have
> > that documented somewhere. Maybe in the Documentation directory
> > something like:
> > 
> > Howto export data in virtual files
> > ==================================
> > 
> > If you want to export data to userspace via virtual filesystems
> > like procfs, sysfs, debugfs etc., the following rules are recommended:
> 
> ...yes please... such patch would be nice.

What about the following ...

Michael

---

 Documentation/filesystems/00-INDEX   |    2 +
 Documentation/filesystems/ExportData |   47 +++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff -Naur linux-2.6.18/Documentation/filesystems/00-INDEX linux-2.6.18-exp-data-doc/Documentation/filesystems/00-INDEX
--- linux-2.6.18/Documentation/filesystems/00-INDEX	2006-09-20 10:50:34.000000000 +0200
+++ linux-2.6.18-exp-data-doc/Documentation/filesystems/00-INDEX	2006-11-08 17:45:31.000000000 +0100
@@ -1,5 +1,7 @@
 00-INDEX
 	- this file (info on some of the filesystems supported by linux).
+ExportData
+	- recommendation of how to export data via virtual File Systems.
 Exporting
 	- explanation of how to make filesystems exportable.
 Locking
diff -Naur linux-2.6.18/Documentation/filesystems/ExportData linux-2.6.18-exp-data-doc/Documentation/filesystems/ExportData
--- linux-2.6.18/Documentation/filesystems/ExportData	1970-01-01 01:00:00.000000000 +0100
+++ linux-2.6.18-exp-data-doc/Documentation/filesystems/ExportData	2006-11-08 17:44:59.000000000 +0100
@@ -0,0 +1,47 @@
+
+Export data via virtual File Systems
+====================================
+
+If you want to export data to userspace via virtual filesystems
+like procfs, sysfs, debugfs etc., the following rules are recommended:
+
+- Export only one value in one virtual file.
+- Data format should be as simple as possible.
+- Use ASCII formated strings, no binary data if possible.
+- If data has dimension units, encode that in the filename.
+
+Please use the following prefixes, when dimension units are required (According
+to IEC 60027-2 and SI/International System of Units):
+
+Storage size (SI prefixes)
+--------------------------
+* kB: kilobyte (10^3 Byte)
+* MB: megabyte (10^6 Byte)
+* GB: gigabyte (10^9 Byte)
+* TB: terabyte (10^12 Byte)
+* PB: petabyte (10^15 Byte)
+
+Storage size (Binary prefixes)
+------------------------------
+* KiB: kibibyte (2^10 Byte)
+* MiB: mebibyte (2^20 Byte)
+* GiB: gibibyte (2^30 Byte)
+* TiB: tebibyte (2^40 Byte)
+* PiB: pebibyte (2^50 Byte)
+
+Time (SI pefixes)
+-----------------
+* s:  Second
+* ms: Millisecond (10^-3 Seconds)
+* us: Microsecond (10^-6 Seconds)
+* ns: Nanosecond (10^-9 Seconds)
+
+Examples:
+---------
+> ls /sys/kernel/debug/sysinfo
+free_mem_KiB
+online_time_ms
+cpu_time_us
+
+> cat /sys/kernel/debug/free_mem_KiB
+147536

Re: How to document dimension units for virtual files?

[Randy Dunlap]

On Wed, 8 Nov 2006 17:54:12 +0100 Michael Holzheu wrote:

> Pavel, Ingo,
> 
> Pavel Machek <pavel@ucw.cz> wrote on 10/28/2006 07:40:48 PM:
> > Hi!
> > 
> > > > > 2. Encode dimension unit into filename (e.g. onlinetime_ms or
> > > memory_kb)
> > > >
> > > > This is the recommended one.
> > > > - simple to implement and understand on both sides
> > > >
> 
> [snip]
> 
> > > I also think that this is the best solution. It would be nice to have
> > > that documented somewhere. Maybe in the Documentation directory
> > > something like:
> > > 
> > > Howto export data in virtual files
> > > ==================================
> > > 
> > > If you want to export data to userspace via virtual filesystems
> > > like procfs, sysfs, debugfs etc., the following rules are recommended:
> > 
> > ...yes please... such patch would be nice.
> 
> What about the following ...
> 
> Michael
> 
> ---
> 
>  Documentation/filesystems/00-INDEX   |    2 +
>  Documentation/filesystems/ExportData |   47 +++++++++++++++++++++++++++++++++++
>  2 files changed, 49 insertions(+)
> 
> diff -Naur linux-2.6.18/Documentation/filesystems/00-INDEX linux-2.6.18-exp-data-doc/Documentation/filesystems/00-INDEX
> --- linux-2.6.18/Documentation/filesystems/00-INDEX	2006-09-20 10:50:34.000000000 +0200
> +++ linux-2.6.18-exp-data-doc/Documentation/filesystems/00-INDEX	2006-11-08 17:45:31.000000000 +0100
> @@ -1,5 +1,7 @@
>  00-INDEX
>  	- this file (info on some of the filesystems supported by linux).
> +ExportData
> +	- recommendation of how to export data via virtual File Systems.
>  Exporting
>  	- explanation of how to make filesystems exportable.
>  Locking
> diff -Naur linux-2.6.18/Documentation/filesystems/ExportData linux-2.6.18-exp-data-doc/Documentation/filesystems/ExportData
> --- linux-2.6.18/Documentation/filesystems/ExportData	1970-01-01 01:00:00.000000000 +0100
> +++ linux-2.6.18-exp-data-doc/Documentation/filesystems/ExportData	2006-11-08 17:44:59.000000000 +0100
> @@ -0,0 +1,47 @@
> +
> +Export data via virtual File Systems
> +====================================
> +
> +If you want to export data to userspace via virtual filesystems
> +like procfs, sysfs, debugfs etc., the following rules are recommended:
> +
> +- Export only one value in one virtual file.

I don't think that makes sense for procfs.  It's too late,
but even it weren't, we don't need a large increase in the number
of procfs files.

And debugfs shouldn't be constrained either.
It's not a regular user interface like sysfs is.

> +- Data format should be as simple as possible.
> +- Use ASCII formated strings, no binary data if possible.

*              formatted

> +- If data has dimension units, encode that in the filename.
> +
> +Please use the following prefixes, when dimension units are required (According
> +to IEC 60027-2 and SI/International System of Units):
> +
> +Storage size (SI prefixes)
> +--------------------------
> +* kB: kilobyte (10^3 Byte)
> +* MB: megabyte (10^6 Byte)
> +* GB: gigabyte (10^9 Byte)
> +* TB: terabyte (10^12 Byte)
> +* PB: petabyte (10^15 Byte)
> +
> +Storage size (Binary prefixes)
> +------------------------------
> +* KiB: kibibyte (2^10 Byte)
> +* MiB: mebibyte (2^20 Byte)
> +* GiB: gibibyte (2^30 Byte)
> +* TiB: tebibyte (2^40 Byte)
> +* PiB: pebibyte (2^50 Byte)
> +
> +Time (SI pefixes)
> +-----------------
> +* s:  Second
> +* ms: Millisecond (10^-3 Seconds)
> +* us: Microsecond (10^-6 Seconds)
> +* ns: Nanosecond (10^-9 Seconds)
> +
> +Examples:
> +---------
> +> ls /sys/kernel/debug/sysinfo
> +free_mem_KiB
> +online_time_ms
> +cpu_time_us
> +
> +> cat /sys/kernel/debug/free_mem_KiB
> +147536
> -

---
~Randy

Re: How to document dimension units for virtual files?

[Jörn Engel]

On Wed, 8 November 2006 17:54:12 +0100, Michael Holzheu wrote:
> 
> What about the following ...

Awesome.  The next time someone flames me over this subject, I can
simly refer to this file.

One could nitpick that a) this applies to any interface, so it also
includes kernel command line and module parameters and b) there are
existing interfaces that interpret "kb" as 2^10 bytes, etc.  Maybe
this could be noted somehow, but it's not too important imho.

Acked-by: Joern Engel <joern@wh.fh-wedel.de>

> 
>  Documentation/filesystems/00-INDEX   |    2 +
>  Documentation/filesystems/ExportData |   47 +++++++++++++++++++++++++++++++++++
>  2 files changed, 49 insertions(+)
> 
> diff -Naur linux-2.6.18/Documentation/filesystems/00-INDEX linux-2.6.18-exp-data-doc/Documentation/filesystems/00-INDEX
> --- linux-2.6.18/Documentation/filesystems/00-INDEX	2006-09-20 10:50:34.000000000 +0200
> +++ linux-2.6.18-exp-data-doc/Documentation/filesystems/00-INDEX	2006-11-08 17:45:31.000000000 +0100
> @@ -1,5 +1,7 @@
>  00-INDEX
>  	- this file (info on some of the filesystems supported by linux).
> +ExportData
> +	- recommendation of how to export data via virtual File Systems.
>  Exporting
>  	- explanation of how to make filesystems exportable.
>  Locking
> diff -Naur linux-2.6.18/Documentation/filesystems/ExportData linux-2.6.18-exp-data-doc/Documentation/filesystems/ExportData
> --- linux-2.6.18/Documentation/filesystems/ExportData	1970-01-01 01:00:00.000000000 +0100
> +++ linux-2.6.18-exp-data-doc/Documentation/filesystems/ExportData	2006-11-08 17:44:59.000000000 +0100
> @@ -0,0 +1,47 @@
> +
> +Export data via virtual File Systems
> +====================================
> +
> +If you want to export data to userspace via virtual filesystems
> +like procfs, sysfs, debugfs etc., the following rules are recommended:
> +
> +- Export only one value in one virtual file.
> +- Data format should be as simple as possible.
> +- Use ASCII formated strings, no binary data if possible.
> +- If data has dimension units, encode that in the filename.
> +
> +Please use the following prefixes, when dimension units are required (According
> +to IEC 60027-2 and SI/International System of Units):
> +
> +Storage size (SI prefixes)
> +--------------------------
> +* kB: kilobyte (10^3 Byte)
> +* MB: megabyte (10^6 Byte)
> +* GB: gigabyte (10^9 Byte)
> +* TB: terabyte (10^12 Byte)
> +* PB: petabyte (10^15 Byte)
> +
> +Storage size (Binary prefixes)
> +------------------------------
> +* KiB: kibibyte (2^10 Byte)
> +* MiB: mebibyte (2^20 Byte)
> +* GiB: gibibyte (2^30 Byte)
> +* TiB: tebibyte (2^40 Byte)
> +* PiB: pebibyte (2^50 Byte)
> +
> +Time (SI pefixes)
> +-----------------
> +* s:  Second
> +* ms: Millisecond (10^-3 Seconds)
> +* us: Microsecond (10^-6 Seconds)
> +* ns: Nanosecond (10^-9 Seconds)
> +
> +Examples:
> +---------
> +> ls /sys/kernel/debug/sysinfo
> +free_mem_KiB
> +online_time_ms
> +cpu_time_us
> +
> +> cat /sys/kernel/debug/free_mem_KiB
> +147536
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/

Jörn

-- 
Courage is not the absence of fear, but rather the judgement that
something else is more important than fear.
-- Ambrose Redmoon

Re: How to document dimension units for virtual files?

[Henrique de Moraes Holschuh]

On Wed, 08 Nov 2006, Michael Holzheu wrote:
> +- If data has dimension units, encode that in the filename.

Can we please encode units in the filename using a separator other than "_"?
the reason for this is that _ is already_used_to_separate_words in the
entries, and it gets difficult to know if something is part of the entry
name or an unit.

Please consider using ":" to separate units and other specific qualifiers
(e.g. led colors) from the main attribute name.  This helps userspace
applications to behave better when faced with stuff like "a_b_c:unit1" and
"a_b_c:unit2" at the same time.

That said, AFAIK using units is explicitly discouraged on hwmon-style sysfs
classes.  The recent thread about a battery class illustrates this.  Please
keep this in mind.

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: How to document dimension units for virtual files?

[Michael Holzheu]

Randy,

Randy Dunlap <randy.dunlap@oracle.com> wrote on 11/08/2006 06:04:54 PM:

> On Wed, 8 Nov 2006 17:54:12 +0100 Michael Holzheu wrote:

[snip]

> 01:00:00.000000000 +0100
> > +++ linux-2.6.18-exp-data-doc/Documentation/filesystems/ExportData
> 2006-11-08 17:44:59.000000000 +0100
> > @@ -0,0 +1,47 @@
> > +
> > +Export data via virtual File Systems
> > +====================================
> > +
> > +If you want to export data to userspace via virtual filesystems
> > +like procfs, sysfs, debugfs etc., the following rules are recommended:
> > +
> > +- Export only one value in one virtual file.
>
> I don't think that makes sense for procfs.  It's too late,
> but even it weren't, we don't need a large increase in the number
> of procfs files.
>
> And debugfs shouldn't be constrained either.
> It's not a regular user interface like sysfs is.
>

Ok, fine:

If you want to export data to userspace via a virtual filesystem
like sysfs, the following rules are recommended:

....

Michael

Re: How to document dimension units for virtual files?

[Michael Holzheu]

Jörn Engel <joern@wohnheim.fh-wedel.de> wrote on 11/08/2006 06:09:16 PM:

> On Wed, 8 November 2006 17:54:12 +0100, Michael Holzheu wrote:
> >
> > What about the following ...
>
> Awesome.  The next time someone flames me over this subject, I can
> simly refer to this file.
>
> One could nitpick that a) this applies to any interface, so it also
> includes kernel command line and module parameters and b) there are
> existing interfaces that interpret "kb" as 2^10 bytes, etc.  Maybe
> this could be noted somehow, but it's not too important imho.
>

a) Right, that is a more general "problem". But I am not sure, if I want
to solve/decide that.
b) I wanted to document the recommendations, I didn't want to
document what currently is done.

Michael

Re: How to document dimension units for virtual files?

[Michael Holzheu]

Henrique,

Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote on 11/08/2006 07:01:54
PM:
> On Wed, 08 Nov 2006, Michael Holzheu wrote:
> Please consider using ":" to separate units and other specific qualifiers
> (e.g. led colors) from the main attribute name.  This helps userspace
> applications to behave better when faced with stuff like "a_b_c:unit1"
and
> "a_b_c:unit2" at the same time.

":" is probably not a good idea.  I think it is treated by the bash as a
special
character. Try:

# touch test:ms
# ls test <press tab>
# ls test\:ms

Michael

Re: How to document dimension units for virtual files?

[Henrique de Moraes Holschuh]

On Wed, 08 Nov 2006, Michael Holzheu wrote:
> > Please consider using ":" to separate units and other specific
> > qualifiers (e.g. led colors) from the main attribute name.  This helps
> > userspace applications to behave better when faced with stuff like
> > "a_b_c:unit1"
> and
> > "a_b_c:unit2" at the same time.
> 
> ":" is probably not a good idea.  I think it is treated by the bash as a
> special character. Try:

We could use some other char (but in that case, it is best to change what
the led sysfs class is doing, they are already using ":", and that's why I
suggested ":").  As long as it is not "_"...

That said, is it just a problem for the bash completion or does it *really*
process the : to be something else?

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: How to document dimension units for virtual files?

[Pavel Machek]

Hi!

> What about the following ...

Looks good to me.

> +> ls /sys/kernel/debug/sysinfo
> +free_mem_KiB
> +online_time_ms
> +cpu_time_us
> +
> +> cat /sys/kernel/debug/free_mem_KiB
> +147536

Someone had idea of free_mem:KiB ... which is quite neat.

Anyway, Greg's opinion was that we should just document units in
documentation and not pollute names with that. I'm not sure if it
works for battery (because of current:mA vs. current:mW confusion).

								Pavel
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

Re: How to document dimension units for virtual files?

[Greg KH]

On Wed, Nov 08, 2006 at 07:27:56PM +0100, Michael Holzheu wrote:
> If you want to export data to userspace via a virtual filesystem
> like sysfs, the following rules are recommended:

Um, does this mean you expect us to change all of the currently existing
sysfs file names?  And people get mad at me when I just move sysfs
symlinks around...

Look at the hwmon drivers, and the documentation in
Documentation/hwmon/sysfs-interface for a description of how we have
been documenting this already.

In short, I don't really think we need to encode the units in the file
name, somehow we have done pretty well without it so far :)

thanks,

greg k-h

Re: How to document dimension units for virtual files?

[Michael Holzheu]

Greg,

Greg KH <greg@kroah.com> wrote on 11/10/2006 07:53:36 AM:

> On Wed, Nov 08, 2006 at 07:27:56PM +0100, Michael Holzheu wrote:
> > If you want to export data to userspace via a virtual filesystem
> > like sysfs, the following rules are recommended:
>
> Um, does this mean you expect us to change all of the currently existing
> sysfs file names?  And people get mad at me when I just move sysfs
> symlinks around...

No, of course we should not change existing kernel interfaces.

> Look at the hwmon drivers, and the documentation in
> Documentation/hwmon/sysfs-interface for a description of how we have
> been documenting this already.

Yes, it is an option to document units in seperate files. But I personally
think,
that this is only the second best solution. Especially since normally
documentation is not read.

>
> In short, I don't really think we need to encode the units in the file
> name, somehow we have done pretty well without it so far :)

Why not trying to make things better than they used to be?

At least for our s390_hypfs I would like to use the suggested naming
scheme. It is new and therefore not burdened with other naming
conventions. Ok?

So, no "Documentation/filesystems/ExportData" patch?

Michael

Re: How to document dimension units for virtual files?

[Kyle Moffett]

On Nov 09, 2006, at 18:15:33, Pavel Machek wrote:
> Anyway, Greg's opinion was that we should just document units in  
> documentation and not pollute names with that. I'm not sure if it  
> works for battery (because of current:mA vs. current:mW confusion).

Well, IMO you should never have "current:mW" in any form whatsoever  
anyways.  Electrically it makes no sense; it's like saying  
"height:grams".  Watts are an indication of power emitted or consumed  
per unit time (as opposed to current/amperage which counts only the  
number of electrons and not the change in energy), so perhaps  
"power_flow:mW" or "power_consumption:mW" would make more sense?

I can conceivably see a need for a "current:mJ_per_s" versus  
"current:mW" depending on the hardware-reported units, but never both  
at the same time.

Cheers,
Kyle Moffett

Re: How to document dimension units for virtual files?

[Sanjoy Mahajan]

Kyle Moffett <mrmacman_g4@mac.com> writes:
> Well, IMO you should never have "current:mW" in any form whatsoever
> anyways.  Electrically it makes no sense; it's like saying
> "height:grams".  

Agreed!

> Watts are an indication of power emitted or consumed per unit time
> (as opposed to current/amperage which counts only the number of
> electrons and not the change in energy), so perhaps "power_flow:mW"
> or "power_consumption:mW" would make more sense?

Current is flow of charge, in other words, charge per time.  Flow has
the notion of "per time" built into it.  So "power flow" contains an
extra "per time" compared to what you're looking for.  Power, being
energy per time, is already a flow (it's a flow of energy).

Perhaps because I'm writing a textbook on _The Art of Approximation_
(and finding formulas using dimensions is a main part of the art), I
like to distinguish a quantity's dimensions from its units.  The
dimensions are universal, like energy or length or power; the units
are their implementation in a particular system of measurement.  In
the SI system of units (a.k.a. the metric system), energy is measured
in Joules, time in seconds, and power in Joules/seconds or Watts.

So all of the following make sense:

* "Power:mW"
* "energy flow: mW" (more verbose but equivalent)
* "energy flow: mJ/s" (even more verbose but also equivalent)

> I can conceivably see a need for a "current:mJ_per_s" versus
> "current:mW" depending on the hardware-reported units, but never
> both at the same time.

I got lost here.  mJ/s is the same as mW, so with either current:mW or
current:mJ/s you're back in the soup of measuring current using units
of power.  If the hardware reports current, use "current: mA".  If the
hardware reports power, use "power: mW".  Then applications can easily
find out what's being reported and use it accordingly.

-Sanjoy

`Never underestimate the evil of which men of power are capable.'
         --Bertrand Russell, _War Crimes in Vietnam_, chapter 1.

Re: How to document dimension units for virtual files?

[Kyle Moffett]

On Nov 10, 2006, at 10:41:09, Sanjoy Mahajan wrote:
>> Watts are an indication of power emitted or consumed per unit time  
>> (as opposed to current/amperage which counts only the number of  
>> electrons and not the change in energy), so perhaps  
>> "power_flow:mW" or "power_consumption:mW" would make more sense?
>
> So all of the following make sense:
>
> * "Power:mW"
> * "energy flow: mW" (more verbose but equivalent)
> * "energy flow: mJ/s" (even more verbose but also equivalent)

In this case the name is a sysfs file to indicate the load on the  
battery; so spaces are frowned upon and "load:mW" would probably work  
the best.

>> I can conceivably see a need for a "current:mJ_per_s" versus  
>> "current:mW" depending on the hardware-reported units, but never  
>> both at the same time.
>
> I got lost here.  mJ/s is the same as mW, so with either current:mW  
> or current:mJ/s you're back in the soup of measuring current using  
> units of power

Whoops; sorry, I was writing this too early in the morning without my  
caffeine and got myself turned around.  What I _meant_ to say was this:

"I conceivably see a need for a "load:mC_s" versus "load:mW",  
depending on the hardware-reported units, but never both at the same  
time."

Essentially if the hardware reports units of milli-watts or milli- 
Calories-per-second or whatever, then we should report that directly  
and let userspace convert as appropriate; keeping the floating-point  
out of the kernel.

Cheers,
Kyle Moffett

Re: How to document dimension units for virtual files?

[Pavel Machek]

Hi!

> > If you want to export data to userspace via a virtual filesystem
> > like sysfs, the following rules are recommended:
> 
> Um, does this mean you expect us to change all of the currently existing
> sysfs file names?  And people get mad at me when I just move sysfs
> symlinks around...
> 
> Look at the hwmon drivers, and the documentation in
> Documentation/hwmon/sysfs-interface for a description of how we have
> been documenting this already.
> 
> In short, I don't really think we need to encode the units in the file
> name, somehow we have done pretty well without it so far :)

Well, problem is that some notebooks have battery capacity in mAh, and
some in mWh, and you can't convert between those.

We could do something like 

battery_stored_energy and battery_stored_current
                 (mWh)                      (mAh)

...but it looks ugly, and battery_capacity:mAh does not sound that bad
for a new interface.
								Pavel
-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

Re: How to document dimension units for virtual files?

[Greg KH]

On Fri, Nov 10, 2006 at 11:03:48AM +0100, Michael Holzheu wrote:
> At least for our s390_hypfs I would like to use the suggested naming
> scheme. It is new and therefore not burdened with other naming
> conventions. Ok?
> 
> So, no "Documentation/filesystems/ExportData" patch?

For now, I would not think so.  Just document the file units in the
Documentation/ABI/ directory and you should be fine.

thanks,

greg k-h

Re: How to document dimension units for virtual files?

[Henrique de Moraes Holschuh]

On Mon, 13 Nov 2006, Pavel Machek wrote:
> We could do something like 
> 
> battery_stored_energy and battery_stored_current
>                  (mWh)                      (mAh)

"Energy" and "charge", please.  You cannot store "current", it is an unit
used to measure flows.  Anyway, we are just repeating arguments that were
made already in the battery thread...

And, please let's follow the SBS spec naming if possible for the attributes.
They put a lot of thought on the way they named things.  Again, this is
already in the battery thread...

> ...but it looks ugly, and battery_capacity:mAh does not sound that bad
> for a new interface.

Indeed, battery_capacity:mWh and battery_capacity:mAh would work just fine
and it does look better.  But unless Greg changes his mind, it looks like we
shall do without units in the filenames, which will also work just fine, if
small enough units are choosen...

-- 
  "One disk to rule them all, One disk to find them. One disk to bring
  them all and in the darkness grind them. In the Land of Redmond
  where the shadows lie." -- The Silicon Valley Tarot
  Henrique Holschuh

Re: How to document dimension units for virtual files?

[Michael Holzheu]

Henrique de Moraes Holschuh <hmh@hmh.eng.br> wrote on 11/13/2006 06:46:21
PM:
> and it does look better.  But unless Greg changes his mind, it looks like
we
> shall do without units in the filenames, which will also work just fine,
if
> small enough units are choosen...
>

As Arnd already said, at least for memory sizes this will work perfectly.
There is no
smaller unit than a byte :-)

Michael