[PATCH] xfsdocs: updates to XFS User Guide

Eric Sandeen sandeen at sandeen.net
Fri Jul 2 13:52:29 CDT 2010 

On 07/02/2010 02:14 AM, Lachlan McIlroy wrote:
> Hi all, it's been a while since I posted here!
> 
> Various updates to chapters 1,2,4 and 5 of the XFS User Guide.
> 
> Fixed various spelling/grammar mistakes, updated outdated and/or
> incorrect facts, added some new slides for delayed allocation and
> direct i/o and fixed some XML formatting for command line examples.

Thanks!  I'd been feeling bad about not updating this ;)

Some comments below.

> Lachlan
> 
> 
> diff --git a/XFS_User_Guide/en-US/XFS-Background.xml b/XFS_User_Guide/en-US/XFS-Background.xml
> index e20f6e0..bdf6910 100644
> --- a/XFS_User_Guide/en-US/XFS-Background.xml
> +++ b/XFS_User_Guide/en-US/XFS-Background.xml
> @@ -195,12 +195,12 @@
>  			</listitem>
>  			<listitem>
>  				<para>
> -					Large filesystems: one terabyte, 2<superscript>40</superscript>, on 32 bit systems; unlimited on 64 bit systems
> +					Large files: up to 9 ExaBytes.
>  				</para>
>  			</listitem>
>  			<listitem>
>  				<para>
> -					Large files: one terabyte, 2<superscript>40</superscript>, on 32 bit systems; 2<superscript>63</superscript> on 64 bit systems
> +					Large filesystems: up to 18 ExaBytes.
>  				</para>

*shrug* I guess it's ok to remove the 32-bit specification, but why?
(not that they had corect numbers before ...)


> diff --git a/XFS_User_Guide/en-US/XFS-Overview.xml b/XFS_User_Guide/en-US/XFS-Overview.xml
> index 1762b39..796729b 100644
> --- a/XFS_User_Guide/en-US/XFS-Overview.xml
> +++ b/XFS_User_Guide/en-US/XFS-Overview.xml
> @@ -52,7 +52,7 @@
>  		<itemizedlist>
>  		<listitem><para>Filesystem blocks are comprised of one or more device-level sectors.</para></listitem>
>  		</itemizedlist>
> -		<para>The page management implementation in Linux limits the FSB size to the page size</para>
> +		<para>The page management implementation in Linux limits the maximum FSB size to the page size</para>
>  		<itemizedlist>
>  		<listitem><para>4KB on ia32 and x86_64 architectures</para></listitem>
>  		<listitem><para>16KB on ia64</para></listitem>
> @@ -66,13 +66,19 @@
>  		<title>Extents</title>
>  		<para>An extent is a set of one or more contiguous FSBs that define a region in the filesystem for file data or metadata</para>
>  		<itemizedlist>
> -		<listitem><para>A single extent can be up to 8GB in length</para></listitem>
> +		<listitem><para>A single extent can be up to 4GB in length</para></listitem>

I'm sure you're right but just for my sanity can you remind me
when/why/if this changed?


> diff --git a/XFS_User_Guide/en-US/XFS-mkfs.xml b/XFS_User_Guide/en-US/XFS-mkfs.xml
> index ce26572..adb12bd 100644
> --- a/XFS_User_Guide/en-US/XFS-mkfs.xml
> +++ b/XFS_User_Guide/en-US/XFS-mkfs.xml
> @@ -5,7 +5,7 @@
>  	<title>mkfs</title>
>  	<section>
>  		<title>Creating XFS Filesystems</title>
> -		<para>mkfs.xfs supports a large number of options for configuration a large number of different XFS filesystems</para>
> +		<para>mkfs.xfs supports a large number of options for configurating many different XFS filesystems</para>

s/configurating/configuring/ ?


> @@ -103,9 +108,8 @@
>  		<itemizedlist>
>  		<listitem><para>15K RPM disk or battery-backed memory</para></listitem>
>  		</itemizedlist>
> -		<para><command>mkfs.xfs -l logdev=log_device device</command></para>
> -		<para><command>mount -o logdev=log_device device path</command></para>
> -		<para>XXX Image goes here</para>

hm probably need to pull in those images some day :(

> diff --git a/XFS_User_Guide/en-US/XFS-mount.xml b/XFS_User_Guide/en-US/XFS-mount.xml
> index e175f95..91cd4dc 100644
> --- a/XFS_User_Guide/en-US/XFS-mount.xml
> +++ b/XFS_User_Guide/en-US/XFS-mount.xml
> @@ -25,37 +25,41 @@
>  	<section>
>  		<title>Mount Options - Log &amp; Realtime Devices</title>
>  		<para>Use an external log (metadata journal) device:</para>
> -		<para><command>mount -o logdev=log_device device mountpoint</command></para>
> +		<para><command>mount -o logdev=<replaceable>log_device</replaceable> <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></command></para>
>  		<para>Use an external log (metadata journal) and real-time device:</para>
> -		<para><command>mount -o logdev=log_device,rtdev=rt_device device mountpoint</command></para>
> +		<para><command>mount -o logdev=<replaceable>log_device</replaceable>,rtdev=<replaceable>rt_device</replaceable> <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></command></para>
>  	</section>
>  	<section>
> -		<title>Mount Options - 64bit Inodes</title>
> -		<para>By default XFS uses 32bit inodes</para>
> -		<itemizedlist>
> -		<listitem><para>The inode’s number roughly equates to its location on disk
> +		<title>Mount Options - 32 or 64 bit Inodes?</title>

Hm the other <title>s for mount options don't ask questions ...

> +		<para>The inode’s number roughly equates to its location on disk

hm, really, it exactly equates, but whatever ;)

>  			<itemiz>  		</itemizedlist>
>  		<para>See</para>
>  		<itemizedlist>
> @@ -170,12 +179,13 @@
>  	<section>
>  		<title>Mount Options - User/Group/Project Quotas</title>
>  		<para>User disk quota accounting enabled, and limits (optionally) enforced.</para>
> -		<para><command>mount -o uquota device mountpoint</command></para>
> +		<para><command>mount -o uquota <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></command></para>
>  		<para>Group disk quota accounting enabled, and limits (optionally) enforced.</para>
> -		<para><command>mount -o grpquota device mountpoint</command></para>
> +		<para><command>mount -o grpquota <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></command></para>
>  		<para>Project quota accounting enabled, and limits (optionally) enforced.</para>
> -		<para><command>mount -o prjquota device mountpoint</command></para>
> -		<para>Can optionally specify <command>uqnoenforce, gqnoenforce</command> and 
> -		      <command>pqnoenforce</command> to use soft limits.</para>
> +		<para><command>mount -o prjquota <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></command></para>
> +		<para>Can optionally specify <command>uqnoenforce</command>, 
> +			<command>gqnoenforce</command> and <command>pqnoenforce</command> 
> +			to use soft limits.</para>
>  	</section>
>  </chapter>
> 
> _______________________________________________
> xfs mailing list
> xfs at oss.sgi.com
> http://oss.sgi.com/mailman/listinfo/xfs

edlist>
>  			<listitem><para>Combination of allocation group, cluster and block</para></listitem>
>  			</itemizedlist>
> -		</para></listitem>
> -		<listitem><para>Inode on Linux is 32bit on 32bit machines
> +		</para>
> +		<para>32 bit inodes (default):</para>
> +		<itemizedlist>
> +		<listitem><para>Must use 32bit inodes on 32bit machines

I don't think this is true anymore?  Christoph?


> @@ -65,8 +69,8 @@
>  		<para>Specify the stripe unit and width for a RAID device or a stripe volume.</para>
>  		<para>Values must be specified in 512-byte block units.</para>
>  		<para>For example, to use a stripe unit of 1MB and a stripe width of 8MB:</para>
> -		<para><command>mount -o sunit=2048,swidth=16384 device mountpoint</command></para>
> -		<para><command>swalloc</command> option</para>
> +		<para><command>mount -o sunit=2048,swidth=16384 <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></command></para>
> +		<para><command>swalloc</command> mount option</para>

hmm next time sending a patch just for the <replaceable> changes would
make review easier ...


> -		<para><command>ikeep</command></para>
> +		<para><command>ikeep</command> (default)</para>
>  		<itemizedlist>
>  		<listitem><para>When inode clusters are emptied of inodes, keep them around on the disk.</para></listitem>
> +		<listitem><para>Use the <command>noikeep</command> option to force empty inode clusters to be returned to
> +			the free space pool.</para></listitem>

wait, ikeep isn't the default.....


> -		<listitem><para>Filesystem will attempt to determine is barriers are supported and will 
> +		<listitem><para>Filesystem will attempt to determine if barriers are supported and will 
>  				issue a warning to the syslog if they are not</para></listitem>
>  		<listitem><para>The <command>nobarrier</command> option disables write barriers</para></listitem>
> +		<listitem><para>Barriers should be disabled when using a RAID with battery backed controller
> +			cache (but only if the individual disk write caches are disabled)</para></listitem>

we've been going back and forth on that a little, we lose queue ordering
barriers too with nobarrier ...


-Eric

More information about the xfs mailing list