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