Commit | Line | Data |
---|---|---|
95ec8dab MW |
1 | Direct Access for files |
2 | ----------------------- | |
3 | ||
4 | Motivation | |
5 | ---------- | |
6 | ||
7 | The page cache is usually used to buffer reads and writes to files. | |
8 | It is also used to provide the pages which are mapped into userspace | |
9 | by a call to mmap. | |
10 | ||
11 | For block devices that are memory-like, the page cache pages would be | |
12 | unnecessary copies of the original storage. The DAX code removes the | |
13 | extra copy by performing reads and writes directly to the storage device. | |
14 | For file mappings, the storage device is mapped directly into userspace. | |
15 | ||
16 | ||
17 | Usage | |
18 | ----- | |
19 | ||
20 | If you have a block device which supports DAX, you can make a filesystem | |
21 | on it as usual. When mounting it, use the -o dax option manually | |
22 | or add 'dax' to the options in /etc/fstab. | |
23 | ||
24 | ||
25 | Implementation Tips for Block Driver Writers | |
26 | -------------------------------------------- | |
27 | ||
28 | To support DAX in your block driver, implement the 'direct_access' | |
29 | block device operation. It is used to translate the sector number | |
30 | (expressed in units of 512-byte sectors) to a page frame number (pfn) | |
31 | that identifies the physical page for the memory. It also returns a | |
32 | kernel virtual address that can be used to access the memory. | |
33 | ||
34 | The direct_access method takes a 'size' parameter that indicates the | |
35 | number of bytes being requested. The function should return the number | |
36 | of bytes that can be contiguously accessed at that offset. It may also | |
37 | return a negative errno if an error occurs. | |
38 | ||
39 | In order to support this method, the storage must be byte-accessible by | |
40 | the CPU at all times. If your device uses paging techniques to expose | |
41 | a large amount of memory through a smaller window, then you cannot | |
42 | implement direct_access. Equally, if your device can occasionally | |
43 | stall the CPU for an extended period, you should also not attempt to | |
44 | implement direct_access. | |
45 | ||
46 | These block devices may be used for inspiration: | |
47 | - axonram: Axon DDR2 device driver | |
48 | - brd: RAM backed block device driver | |
49 | - dcssblk: s390 dcss block device driver | |
50 | ||
51 | ||
52 | Implementation Tips for Filesystem Writers | |
53 | ------------------------------------------ | |
54 | ||
55 | Filesystem support consists of | |
56 | - adding support to mark inodes as being DAX by setting the S_DAX flag in | |
57 | i_flags | |
58 | - implementing the direct_IO address space operation, and calling | |
59 | dax_do_io() instead of blockdev_direct_IO() if S_DAX is set | |
60 | - implementing an mmap file operation for DAX files which sets the | |
61 | VM_MIXEDMAP flag on the VMA, and setting the vm_ops to include handlers | |
62 | for fault and page_mkwrite (which should probably call dax_fault() and | |
63 | dax_mkwrite(), passing the appropriate get_block() callback) | |
64 | - calling dax_truncate_page() instead of block_truncate_page() for DAX files | |
25726bc1 | 65 | - calling dax_zero_page_range() instead of zero_user() for DAX files |
95ec8dab MW |
66 | - ensuring that there is sufficient locking between reads, writes, |
67 | truncates and page faults | |
68 | ||
69 | The get_block() callback passed to the DAX functions may return | |
70 | uninitialised extents. If it does, it must ensure that simultaneous | |
71 | calls to get_block() (for example by a page-fault racing with a read() | |
72 | or a write()) work correctly. | |
73 | ||
74 | These filesystems may be used for inspiration: | |
75 | - ext2: the second extended filesystem, see Documentation/filesystems/ext2.txt | |
923ae0ff | 76 | - ext4: the fourth extended filesystem, see Documentation/filesystems/ext4.txt |
95ec8dab MW |
77 | |
78 | ||
79 | Shortcomings | |
80 | ------------ | |
81 | ||
82 | Even if the kernel or its modules are stored on a filesystem that supports | |
83 | DAX on a block device that supports DAX, they will still be copied into RAM. | |
84 | ||
d92576f1 MW |
85 | The DAX code does not work correctly on architectures which have virtually |
86 | mapped caches such as ARM, MIPS and SPARC. | |
87 | ||
95ec8dab MW |
88 | Calling get_user_pages() on a range of user memory that has been mmaped |
89 | from a DAX file will fail as there are no 'struct page' to describe | |
90 | those pages. This problem is being worked on. That means that O_DIRECT | |
91 | reads/writes to those memory ranges from a non-DAX file will fail (note | |
92 | that O_DIRECT reads/writes _of a DAX file_ do work, it is the memory | |
93 | that is being accessed that is key here). Other things that will not | |
94 | work include RDMA, sendfile() and splice(). |