From: ira.weiny@intel.com
To: linux-kernel@vger.kernel.org
Cc: Ira Weiny <ira.weiny@intel.com>,
Alexander Viro <viro@zeniv.linux.org.uk>,
"Darrick J. Wong" <darrick.wong@oracle.com>,
Dan Williams <dan.j.williams@intel.com>,
Dave Chinner <david@fromorbit.com>,
Christoph Hellwig <hch@lst.de>,
"Theodore Y. Ts'o" <tytso@mit.edu>, Jan Kara <jack@suse.cz>,
linux-ext4@vger.kernel.org, linux-xfs@vger.kernel.org,
linux-fsdevel@vger.kernel.org
Subject: [PATCH V4 13/13] Documentation/dax: Update Usage section
Date: Thu, 20 Feb 2020 16:41:34 -0800 [thread overview]
Message-ID: <20200221004134.30599-14-ira.weiny@intel.com> (raw)
In-Reply-To: <20200221004134.30599-1-ira.weiny@intel.com>
From: Ira Weiny <ira.weiny@intel.com>
Update the Usage section to reflect the new individual dax selection
functionality.
Signed-off-by: Ira Weiny <ira.weiny@intel.com>
---
Documentation/filesystems/dax.txt | 84 ++++++++++++++++++++++++++++++-
1 file changed, 82 insertions(+), 2 deletions(-)
diff --git a/Documentation/filesystems/dax.txt b/Documentation/filesystems/dax.txt
index 679729442fd2..32e37c550f76 100644
--- a/Documentation/filesystems/dax.txt
+++ b/Documentation/filesystems/dax.txt
@@ -20,8 +20,88 @@ Usage
If you have a block device which supports DAX, you can make a filesystem
on it as usual. The DAX code currently only supports files with a block
size equal to your kernel's PAGE_SIZE, so you may need to specify a block
-size when creating the filesystem. When mounting it, use the "-o dax"
-option on the command line or add 'dax' to the options in /etc/fstab.
+size when creating the filesystem.
+
+Enabling DAX on an individual file basis (XFS)
+----------------------------------------------
+
+There are 2 per file dax flags. One is a physical configuration setting and
+the other a currently enabled state.
+
+The physical configuration setting is maintained on individual file and
+directory inodes. It is preserved within the file system. This 'physical'
+config setting can be set using an ioctl and/or an application such as "xfs_io
+-c 'chattr [-+]x'". Files and directories automatically inherit their physical
+dax setting from their parent directory when created. Therefore, setting the
+physical dax setting at directory creation time can be used to set a default
+behavior for that sub-tree. Doing so on the root directory acts to set a
+default for the entire file system.
+
+To clarify inheritance here are 3 examples:
+
+Example A:
+
+mkdir -p a/b/c
+xfs_io 'chattr +x' a
+mkdir a/b/c/d
+mkdir a/e
+
+ dax: a,e
+ no dax: b,c,d
+
+Example B:
+
+mkdir a
+xfs_io 'chattr +x' a
+mkdir -p a/b/c/d
+
+ dax: a,b,c,d
+ no dax:
+
+Example C:
+
+mkdir -p a/b/c
+xfs_io 'chattr +x' c
+mkdir a/b/c/d
+
+ dax: c,d
+ no dax: a,b
+
+
+The current inode enabled state is set when a file inode is loaded and it is
+determined that the underlying media supports dax.
+
+statx can be used to query the file's current enabled state. NOTE that a
+directory will never be operating in a dax state. Therefore, the dax config
+state must be queried to see what config state a file or sub-directory will
+inherit from a directory.
+
+NOTE: Setting a file or directory's config state with xfs_io is possible even
+if the underlying media does not support dax.
+
+
+Enabling dax on a file system wide basis ('-o dax' mount option)
+----------------------------------------------------------------
+
+The physical dax configuration of all files can be overridden using a mount
+option. In summary:
+
+ (physical flag || mount option) && capable device == dax in effect
+ ( <xfs_io> || <'-o dax'> ) && capable device == <statx dax true>
+
+To enable the mount override, use "-o dax" on the command line or add
+'dax' to the options in /etc/fstab
+
+Using the mount option does not change the physical configured state of
+individual files. Therefore, remounting _without_ the mount option will allow
+the file system to set file's enabled state directly based on their config
+setting.
+
+NOTE: Setting a file or directory's physical config state is possible while the
+file system is mounted with the dax override. However, the file's enabled
+state will continue to be overridden and "dax enabled" until the mount option
+is removed and a remount performed. At that point the file's physical config
+state dictates the enabled state.
Implementation Tips for Block Driver Writers
--
2.21.0
next prev parent reply other threads:[~2020-02-21 0:41 UTC|newest]
Thread overview: 54+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-21 0:41 [PATCH V4 00/13] Enable per-file/per-directory DAX operations V4 ira.weiny
2020-02-21 0:41 ` [PATCH V4 01/13] fs/xfs: Remove unnecessary initialization of i_rwsem ira.weiny
2020-02-21 1:26 ` Dave Chinner
2020-02-27 17:52 ` Ira Weiny
2020-02-21 0:41 ` [PATCH V4 02/13] fs/xfs: Clarify lockdep dependency for xfs_isilocked() ira.weiny
2020-02-21 1:34 ` Dave Chinner
2020-02-21 23:00 ` Ira Weiny
2020-02-21 0:41 ` [PATCH V4 03/13] fs: Remove unneeded IS_DAX() check ira.weiny
2020-02-21 1:42 ` Dave Chinner
2020-02-21 23:04 ` Ira Weiny
2020-02-21 17:42 ` Christoph Hellwig
2020-02-21 0:41 ` [PATCH V4 04/13] fs/stat: Define DAX statx attribute ira.weiny
2020-02-21 0:41 ` [PATCH V4 05/13] fs/xfs: Isolate the physical DAX flag from enabled ira.weiny
2020-02-21 0:41 ` [PATCH V4 06/13] fs/xfs: Create function xfs_inode_enable_dax() ira.weiny
2020-02-22 0:28 ` Darrick J. Wong
2020-02-23 15:07 ` Ira Weiny
2020-02-21 0:41 ` [PATCH V4 07/13] fs: Add locking for a dynamic address space operations state ira.weiny
2020-02-21 17:44 ` Christoph Hellwig
2020-02-21 22:44 ` Dave Chinner
2020-02-21 23:26 ` Dan Williams
2020-02-24 17:56 ` Christoph Hellwig
2020-02-25 0:09 ` Dave Chinner
2020-02-25 17:36 ` Christoph Hellwig
2020-02-25 19:37 ` Jeff Moyer
2020-02-26 9:28 ` Jonathan Halliday
2020-02-26 11:31 ` Jan Kara
2020-02-26 11:56 ` Jonathan Halliday
2020-02-26 16:10 ` Ira Weiny
2020-02-26 16:46 ` Dan Williams
2020-02-26 17:20 ` Jan Kara
2020-02-26 17:54 ` Dan Williams
2020-02-25 21:03 ` Ira Weiny
2020-02-26 11:17 ` Jan Kara
2020-02-26 15:57 ` Ira Weiny
2020-02-22 0:33 ` Darrick J. Wong
2020-02-23 15:03 ` Ira Weiny
2020-02-21 0:41 ` [PATCH V4 08/13] fs: Prevent DAX state change if file is mmap'ed ira.weiny
2020-02-21 0:41 ` [PATCH V4 09/13] fs/xfs: Add write aops lock to xfs layer ira.weiny
2020-02-22 0:31 ` Darrick J. Wong
2020-02-23 15:04 ` Ira Weiny
2020-02-24 0:34 ` Dave Chinner
2020-02-24 19:57 ` Ira Weiny
2020-02-24 22:32 ` Dave Chinner
2020-02-25 21:12 ` Ira Weiny
2020-02-25 22:59 ` Dave Chinner
2020-02-26 18:02 ` Ira Weiny
2020-02-21 0:41 ` [PATCH V4 10/13] fs/xfs: Clean up locking in dax invalidate ira.weiny
2020-02-21 17:45 ` Christoph Hellwig
2020-02-21 18:06 ` Ira Weiny
2020-02-21 0:41 ` [PATCH V4 11/13] fs/xfs: Allow toggle of effective DAX flag ira.weiny
2020-02-21 0:41 ` [PATCH V4 12/13] fs/xfs: Remove xfs_diflags_to_linux() ira.weiny
2020-02-21 0:41 ` ira.weiny [this message]
2020-02-26 22:48 ` [PATCH V4 00/13] Enable per-file/per-directory DAX operations V4 Jeff Moyer
2020-02-27 2:43 ` Ira Weiny
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200221004134.30599-14-ira.weiny@intel.com \
--to=ira.weiny@intel.com \
--cc=dan.j.williams@intel.com \
--cc=darrick.wong@oracle.com \
--cc=david@fromorbit.com \
--cc=hch@lst.de \
--cc=jack@suse.cz \
--cc=linux-ext4@vger.kernel.org \
--cc=linux-fsdevel@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-xfs@vger.kernel.org \
--cc=tytso@mit.edu \
--cc=viro@zeniv.linux.org.uk \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).