On Fri, Jul 17, 2020 at 01:45:40AM +0000, Satya Tangirala wrote: > Update fscrypt documentation to reflect the addition of direct I/O support > and document the necessary conditions for direct I/O on encrypted files. > > Signed-off-by: Satya Tangirala <satyat@xxxxxxxxxx> > --- > Documentation/filesystems/fscrypt.rst | 20 ++++++++++++++++++-- > 1 file changed, 18 insertions(+), 2 deletions(-) > > diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst > index f3d87a1a0a7f..95c76a5f0567 100644 > --- a/Documentation/filesystems/fscrypt.rst > +++ b/Documentation/filesystems/fscrypt.rst > @@ -1049,8 +1049,10 @@ astute users may notice some differences in behavior: > may be used to overwrite the source files but isn't guaranteed to be > effective on all filesystems and storage devices. > > -- Direct I/O is not supported on encrypted files. Attempts to use > - direct I/O on such files will fall back to buffered I/O. > +- Direct I/O is supported on encrypted files only under some circumstances > + (see `Direct I/O support`_ for details). When these circumstances are not > + met, attempts to use direct I/O on such files will fall back to buffered > + I/O. Nit: "such files" => "encrypted files". Nit: most of the text in this file is formatted with textwidth=70. > > - The fallocate operations FALLOC_FL_COLLAPSE_RANGE and > FALLOC_FL_INSERT_RANGE are not supported on encrypted files and will > @@ -1257,6 +1259,20 @@ without the key is subject to change in the future. It is only meant > as a way to temporarily present valid filenames so that commands like > ``rm -r`` work as expected on encrypted directories. > > +Direct I/O support > +------------------ > + > +Direct I/O on encrypted files is supported through blk-crypto. In > +particular, this means the kernel must have CONFIG_BLK_INLINE_ENCRYPTION > +enabled, the filesystem must have had the 'inlinecrypt' mount option > +specified, and either hardware inline encryption must be present, or > +CONFIG_BLK_INLINE_ENCRYPTION_FALLBACK must have been enabled. Further, > +any I/O must be aligned to the filesystem block size (*not* necessarily > +the same as the block device's block size) - in particular, any userspace > +buffer into which data is read/written from must also be aligned to the > +filesystem block size. If any of these conditions isn't met, attempts to do > +direct I/O on an encrypted file will fall back to buffered I/O. This is placing "Direct I/O support" as a subsection of the "Implementation details" section. But the direct I/O support is more than just an implementation detail. How about moving it to a top-level section? I'd probably put it between "Access semantics" and "Encryption policy enforcement". - Eric
