Re: [PATCH] adding example with xfs_info output decryption

[Roman Ovchinnikov <coolthecold@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 6308 bytes --]



On Tue, Jul 26, 2011 at 11:02 PM, Alex Elder <aelder@sgi.com> wrote:
> On Fri, 2011-07-22 at 11:52 -0400, Christoph Hellwig wrote:
>> On Mon, May 23, 2011 at 02:34:54AM +0400, CoolCold wrote:
>> > Basing on irc discussions and questions about reading xfs_info output
>> > I've added example in xfs_growfs manpage.
>>
>> Alex, Dave, Eric, do you guys have any comments on this?  Language
>> nitpicks from the native speakers?  Otherwise I'd be inclined to put it
>> in.
>>
>> > Signed-off-by: Roman Ovchinnikov <coolthecold@gmail.com>
>
> I had to dust off my troff command knowledge to review this.
> It has been many years...
I was testing how manpage will look with "man man/man8/xfs_growfs.8", works for me.

>
> Christoph prompted to review this from a native speaker's
> point of view though, so I do that here.  I do end up
> with a question for others to try to resolve.
>
> I think what you are doing (adding the example) is a good idea
> to help clarify things in any case.
Thanks!
>
>> > ---
>> >  man/man8/xfs_growfs.8 |   34 ++++++++++++++++++++++++++++++++++
>> >  1 files changed, 34 insertions(+), 0 deletions(-)
>> >
>> > diff --git a/man/man8/xfs_growfs.8 b/man/man8/xfs_growfs.8
>> > index 02793ae..c782fc1 100644
>> > --- a/man/man8/xfs_growfs.8
>> > +++ b/man/man8/xfs_growfs.8
>> > @@ -1,3 +1,14 @@
>> > +.\" Verbatim blocks taken from openssl req manpage content
>> > +.de Vb \" Begin verbatim text
>> > +.ft CW
>> > +.nf
>> > +.ne \\$1
>> > +..
>> > +.de Ve \" End verbatim text
>> > +.ft R
>> > +.fi
>> > +..
>> > +
>> >  .TH xfs_growfs 8
>> >  .SH NAME
>> >  xfs_growfs, xfs_info \- expand an XFS filesystem
>> > @@ -105,6 +116,7 @@ this is specified with
>> >  Specifies that no change to the filesystem is to be made.
>> >  The filesystem geometry is printed, and argument checking is performed,
>> >  but no growth occurs.
>> > +.B See output examples below.
>> >  .TP
>> >  .BI "\-r | \-R " size
>> >  Specifies that the real-time section of the filesystem should be grown. If the
>> > @@ -152,6 +164,28 @@ reside. In order to grow a filesystem, it is
>> > necessary to provide added
>> >  space for it to occupy. Therefore there must be at least one spare new
>> >  disk partition available. Adding the space is often done through the use
>> >  of a logical volume manager.
>> > +.SH "EXAMPLES"
>> > +
>> > +Examining xfs_info output.
>
> How about, "Understanding xfs_info output"
>
>> > +.PP
>> > +Let's assume one have the next xfs_info output:
>> > +.PP
>> > +.Vb 1
>
> Maybe you could add something indicating how the command was issued.
> I.e.:
>
>    \&# xfs_info /dev/sda
Okay.

>
>> > +\& meta-data=/dev/sda      isize=256    agcount=32, agsize=16777184 blks
>> > +\&          =              sectsz=512   attr=2
>> > +\& data     =              bsize=4096   blocks=536869888, imaxpct=5
>> > +\&          =              sunit=32     swidth=128 blks
>> > +\& naming   =version 2     bsize=4096
>> > +\& log      =internal      bsize=4096   blocks=32768, version=2
>> > +\&          =              sectsz=512   sunit=32 blks, lazy-count=1
>> > +\& realtime =none          extsz=524288 blocks=0, rtextents=0
>
> I think you should drop the space character after each '&' above.
> The way you have it puts a slight indent in the output.
Personally I like indentation here, to make the text look like "quote", and may be I'd add one more space

>
>> > +.Ve
>> > +.PP
>> > +
>> > +Here, data section block size (bsize) is 4096 bytes. Therefore
>> > +"sunit=32 swidth=128 blks" means stripe unit is 32*4096 bytes = 128 kibibytes
>> > +and stripe width is 128*4096 bytes = 512 kibibytes. Filesystem is striped
>> > +over 4 ( 128 / 32 ) stripes.
>
> I'll just write what I think it should be rather than trying
> to show lots of little changes:
>
>  Here, the data section of the output indicates "bsize=4096",
>  meaning the data block size for this filesystem is 4096 bytes.
>  This section also shows "sunit=32 swidth=128 blks", which means
>  the stripe unit is 32*4096 bytes = 128 kibibytes and the stripe
>  width is 128*4096 bytes = 512 kibibytes.
>
> The last sentence I'm not sure I agree with.  I think you're
> trying to explain the relationship between a stripe width
> and stripe unit, and the components that make up a stripe.
> Your use of the term "stripe" doesn't match what I take
> to be its meaning.  I'm not saying my meaning is right, but
> I'd like to make sure we have agreement on these terms.
Generally I was trying to fact out units of measurement - as,say, mkfs.xfs manpage describes option parameters as 512 bytes blocks/just bytes to be specified when calling mkfs.xfs, and when someone gets xfs_info output for that mount point it really differs from parameters he passed to mkfs.xfs (at least at first sight).
>
> Given that, I would re-state your last sentence (using my
> terminology as):
>
>  A single stripe of this filesystem therefore consists
>  of four stripe units (128 blocks / 32 blocks per unit).
>
> I.e., my meaning says that  a "stripe" is "stripe width"
> blocks wide, made up of four "stripe units", each of which
> is 32 blocks, where a block is 4096 bytes.
>
> I think you are using the term "stripe" to represent what
> I'm calling the "stripe unit".
>
> Perhaps someone else can help ensure we're using
> terms with meaning consistent with how XFS has used
> them historically.
I've checked manpage for mkfs.xfs and it operates with terms "stripe unit" & "stripe width" in your understanding, so I think this is historically proper way to think about stripes.

>
>                                        -Alex
>
>
>> >  .SH SEE ALSO
>> >  .BR mkfs.xfs (8),
>> >  .BR md (4),
>
>

So, I've updated patch (now it mostly contains your text), but left
indentation. Patch is attached and url for it is http://web.coolcold.org/data/0001-adding-example-with-xfs_info-decryption-v2.patch

I'm new to all this public patch-through-email process, should I start
new mail thread with new patch text inside message?




-- 
Best regards,
[COOLCOLD-RIPN]

[-- Attachment #2: 0001-adding-example-with-xfs_info-decryption-v2.patch --]
[-- Type: application/octet-stream, Size: 2502 bytes --]

From 1bd4906c7d8928cb1571667a8a331e6ad2c69daa Mon Sep 17 00:00:00 2001
From: Roman Ovchinnikov <coolthecold@gmail.com>
Date: Sat, 21 May 2011 04:05:33 +0400
Subject: [PATCH] adding example with xfs_info decryption, v2


Signed-off-by: Roman Ovchinnikov <coolthecold@gmail.com>
---
 man/man8/xfs_growfs.8 |   37 +++++++++++++++++++++++++++++++++++++
 1 files changed, 37 insertions(+), 0 deletions(-)

diff --git a/man/man8/xfs_growfs.8 b/man/man8/xfs_growfs.8
index 02793ae..e5f825a 100644
--- a/man/man8/xfs_growfs.8
+++ b/man/man8/xfs_growfs.8
@@ -1,3 +1,14 @@
+.\" Verbatim blocks taken from openssl req manpage content
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+
 .TH xfs_growfs 8
 .SH NAME
 xfs_growfs, xfs_info \- expand an XFS filesystem
@@ -105,6 +116,7 @@ this is specified with
 Specifies that no change to the filesystem is to be made.
 The filesystem geometry is printed, and argument checking is performed,
 but no growth occurs.
+.B See output examples below.
 .TP
 .BI "\-r | \-R " size
 Specifies that the real-time section of the filesystem should be grown. If the
@@ -152,6 +164,31 @@ reside. In order to grow a filesystem, it is necessary to provide added
 space for it to occupy. Therefore there must be at least one spare new
 disk partition available. Adding the space is often done through the use
 of a logical volume manager.
+.SH "EXAMPLES"
+
+Understanding xfs_info output.
+.PP
+Let's assume one have the next xfs_info /dev/sda output:
+.PP
+.Vb 1
+\& meta-data=/dev/sda      isize=256    agcount=32, agsize=16777184 blks
+\&          =              sectsz=512   attr=2
+\& data     =              bsize=4096   blocks=536869888, imaxpct=5
+\&          =              sunit=32     swidth=128 blks
+\& naming   =version 2     bsize=4096
+\& log      =internal      bsize=4096   blocks=32768, version=2
+\&          =              sectsz=512   sunit=32 blks, lazy-count=1
+\& realtime =none          extsz=524288 blocks=0, rtextents=0
+.Ve
+.PP
+
+Here, the data section of the output indicates "bsize=4096",
+meaning the data block size for this filesystem is 4096 bytes.
+This section also shows "sunit=32 swidth=128 blks", which means
+the stripe unit is 32*4096 bytes = 128 kibibytes and the stripe
+width is 128*4096 bytes = 512 kibibytes.
+A single stripe of this filesystem therefore consists
+of four stripe units (128 blocks / 32 blocks per unit).
 .SH SEE ALSO
 .BR mkfs.xfs (8),
 .BR md (4),
-- 
1.7.2.5


[-- Attachment #3: Type: text/plain, Size: 121 bytes --]

_______________________________________________
xfs mailing list
xfs@oss.sgi.com
http://oss.sgi.com/mailman/listinfo/xfs