xfs
[Top] [All Lists]

Re: [PATCH] adding example with xfs_info output decryption

To: aelder@xxxxxxx
Subject: Re: [PATCH] adding example with xfs_info output decryption
From: Roman Ovchinnikov <coolthecold@xxxxxxxxx>
Date: Wed, 27 Jul 2011 13:13:43 +0400
Cc: Christoph Hellwig <hch@xxxxxxxxxxxxx>, xfs@xxxxxxxxxxx
Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=date:from:x-priority:message-id:to:cc:subject:in-reply-to :references:mime-version:content-type; bh=jG0vb9yC5a7/3MgyLFxnZEqJT7nADPZ2YHBCUqBjgAg=; b=APA+H81gj6zBiJFJOGCtltCK0Pd1P7P1xhdzxLJtN7hZGI8SdhoRDNC336igUkflce pG5zSAKloI13NIpfdu0siE0bf/k5yakXGwNZyUv4I5exbhZgt3RhjS5meWpGQMEgZCr1 5RYt3SMjFoFQiCnzQKts/hRulGw8L5IsY96+k=
In-reply-to: <1311706943.2890.42.camel@doink>
References: <BANLkTikjPhKNBVUamccXbAropDw=oBSRgg@xxxxxxxxxxxxxx> <20110722155200.GA31867@xxxxxxxxxxxxx> <1311706943.2890.42.camel@doink>

On Tue, Jul 26, 2011 at 11:02 PM, Alex Elder <aelder@xxxxxxx> 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@xxxxxxxxx>
>
> 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: 0001-adding-example-with-xfs_info-decryption-v2.patch
Description: Binary data

<Prev in Thread] Current Thread [Next in Thread>