Re: [PATCH 0/2] ext4: even more documentation fixes
On 10/4/18 5:59 PM, Darrick J. Wong wrote: > Hi all, > > This series fixes some problems that were brought up during review for > the XFS documentation which I hadn't known about when pushing the ext4 > documentation during the 4.19 cycle. > > The first patch moves the ext4 mount option and sysfs knob information > into the Linux administration guide. > > The second patch moves the ext4 Data Structures & Algorithms book up a > level since it's a self-contained documentation book. > > I've built the docs and put them here, in case you hate reading rst: > https://djwong.org/docs/kdoc/filesystems/ext4/index.html > > The patchset should apply cleanly against 4.19-rc6. Comments and > questions are, as always, welcome. Hi Darrick, I don't see patch 2/2 anywhere (my inbox, email archives)... -- ~Randy
[PATCH] docs: improve readability for people with poorer eyesight
Hi,
So my eyesight still hasn't fully recovered, so in the meantime it's
been difficult to read the online documentation. Here's some stylesheet
overrides I've been using to make it easier for me to read them:
https://djwong.org/docs/kdoc/index.html
---
From: Darrick J. Wong
My eyesight is not in good shape, which means that I have difficulty
reading the online Linux documentation. Specifically, body text is
oddly small compared to list items and the contrast of various text
elements is too low for me to be able to see easily.
Therefore, alter the HTML theme overrides to make the text larger and
increase the contrast for better visibility, and trust the typeface
choices of the reader's browser.
For the PDF output, increase the text size, use a sans-serif typeface
for sans-serif text, and use a serif typeface for "roman" serif text.
Signed-off-by: Darrick J. Wong
---
Documentation/conf.py |6 ++--
Documentation/sphinx-static/theme_overrides.css | 38 +++
2 files changed, 41 insertions(+), 3 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index e45d4d2b5adb..03dd6dc135ea 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -259,7 +259,7 @@ latex_elements = {
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
-'pointsize': '8pt',
+'pointsize': '11pt',
# Latex figure (float) alignment
#'figure_align': 'htbp',
@@ -272,8 +272,8 @@ latex_elements = {
'preamble': '''
% Use some font with UTF-8 support with XeLaTeX
\\usepackage{fontspec}
-\\setsansfont{DejaVu Serif}
-\\setromanfont{DejaVu Sans}
+\\setsansfont{DejaVu Sans}
+\\setromanfont{DejaVu Serif}
\\setmonofont{DejaVu Sans Mono}
'''
diff --git a/Documentation/sphinx-static/theme_overrides.css
b/Documentation/sphinx-static/theme_overrides.css
index 522b6d4c49d4..e21e36cd6761 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -4,6 +4,44 @@
*
*/
+/* Improve contrast and increase size for easier reading. */
+
+body {
+ font-family: serif;
+ color: black;
+ font-size: 100%;
+}
+
+h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
+ font-family: sans-serif;
+}
+
+.wy-menu-vertical li.current a {
+ color: #505050;
+}
+
+.wy-menu-vertical li.on a, .wy-menu-vertical li.current > a {
+ color: #303030;
+}
+
+div[class^="highlight"] pre {
+ font-family: monospace;
+ color: black;
+ font-size: 100%;
+}
+
+.wy-menu-vertical {
+ font-family: sans-serif;
+}
+
+.c {
+ font-style: normal;
+}
+
+p {
+ font-size: 100%;
+}
+
/* Interim: Code-blocks with line nos - lines and line numbers don't line up.
* see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
*/
[PATCH 1/2] docs: move ext4 administrative docs to admin-guide/
From: Darrick J. Wong Move the ext4 mount option and other administrative stuff to the Linux administrator's guide. Signed-off-by: Darrick J. Wong --- Documentation/admin-guide/ext4.rst | 574 ++ Documentation/admin-guide/index.rst |1 Documentation/conf.py|2 Documentation/filesystems/ext4/ext4.rst | 574 -- Documentation/filesystems/ext4/index.rst |1 5 files changed, 577 insertions(+), 575 deletions(-) create mode 100644 Documentation/admin-guide/ext4.rst delete mode 100644 Documentation/filesystems/ext4/ext4.rst diff --git a/Documentation/admin-guide/ext4.rst b/Documentation/admin-guide/ext4.rst new file mode 100644 index ..e506d3dae510 --- /dev/null +++ b/Documentation/admin-guide/ext4.rst @@ -0,0 +1,574 @@ +.. SPDX-License-Identifier: GPL-2.0 + + +ext4 General Information + + +Ext4 is an advanced level of the ext3 filesystem which incorporates +scalability and reliability enhancements for supporting large filesystems +(64 bit) in keeping with increasing disk capacities and state-of-the-art +feature requirements. + +Mailing list: linux-e...@vger.kernel.org +Web site: http://ext4.wiki.kernel.org + + +Quick usage instructions + + +Note: More extensive information for getting started with ext4 can be +found at the ext4 wiki site at the URL: +http://ext4.wiki.kernel.org/index.php/Ext4_Howto + + - The latest version of e2fsprogs can be found at: + +https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/ + + or + +http://sourceforge.net/project/showfiles.php?group_id=2406 + + or grab the latest git repository from: + + https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git + + - Create a new filesystem using the ext4 filesystem type: + +# mke2fs -t ext4 /dev/hda1 + +Or to configure an existing ext3 filesystem to support extents: + + # tune2fs -O extents /dev/hda1 + +If the filesystem was created with 128 byte inodes, it can be +converted to use 256 byte for greater efficiency via: + +# tune2fs -I 256 /dev/hda1 + + - Mounting: + + # mount -t ext4 /dev/hda1 /wherever + + - When comparing performance with other filesystems, it's always +important to try multiple workloads; very often a subtle change in a +workload parameter can completely change the ranking of which +filesystems do well compared to others. When comparing versus ext3, +note that ext4 enables write barriers by default, while ext3 does +not enable write barriers by default. So it is useful to use +explicitly specify whether barriers are enabled or not when via the +'-o barriers=[0|1]' mount option for both ext3 and ext4 filesystems +for a fair comparison. When tuning ext3 for best benchmark numbers, +it is often worthwhile to try changing the data journaling mode; '-o +data=writeback' can be faster for some workloads. (Note however that +running mounted with data=writeback can potentially leave stale data +exposed in recently written files in case of an unclean shutdown, +which could be a security exposure in some situations.) Configuring +the filesystem with a large journal can also be helpful for +metadata-intensive workloads. + +Features + + +Currently Available +--- + +* ability to use filesystems > 16TB (e2fsprogs support not available yet) +* extent format reduces metadata overhead (RAM, IO for access, transactions) +* extent format more robust in face of on-disk corruption due to magics, +* internal redundancy in tree +* improved file allocation (multi-block alloc) +* lift 32000 subdirectory limit imposed by i_links_count[1] +* nsec timestamps for mtime, atime, ctime, create time +* inode version field on disk (NFSv4, Lustre) +* reduced e2fsck time via uninit_bg feature +* journal checksumming for robustness, performance +* persistent file preallocation (e.g for streaming media, databases) +* ability to pack bitmaps and inode tables into larger virtual groups via the + flex_bg feature +* large file support +* inode allocation using large virtual block groups via flex_bg +* delayed allocation +* large block (up to pagesize) support +* efficient new ordered mode in JBD2 and ext4 (avoid using buffer head to force + the ordering) + +[1] Filesystems with a block size of 1k may see a limit imposed by the +directory hash tree having a maximum depth of two. + +Options +=== + +When mounting an ext4 filesystem, the following option are accepted: +(*) == default + + ro +Mount filesystem read only. Note that ext4 will replay the journal (and +thus write to the partition) even when mounted "read only". The mount +options "ro,noload" can be used to prevent writes to the filesystem. + + journal_checksum +Enable checksumming of the journal transactions.
[PATCH 0/2] ext4: even more documentation fixes
Hi all, This series fixes some problems that were brought up during review for the XFS documentation which I hadn't known about when pushing the ext4 documentation during the 4.19 cycle. The first patch moves the ext4 mount option and sysfs knob information into the Linux administration guide. The second patch moves the ext4 Data Structures & Algorithms book up a level since it's a self-contained documentation book. I've built the docs and put them here, in case you hate reading rst: https://djwong.org/docs/kdoc/filesystems/ext4/index.html The patchset should apply cleanly against 4.19-rc6. Comments and questions are, as always, welcome. --D
[PATCH 2/2] docs/vm: split memory hotplug notifier description to Documentation/core-api
The memory hotplug notifier description is about kernel internals rather
than admin/user visible API. Place it appropriately.
Signed-off-by: Mike Rapoport
---
Documentation/admin-guide/mm/memory-hotplug.rst| 83 -
Documentation/core-api/index.rst | 2 +
Documentation/core-api/memory-hotplug-notifier.rst | 84 ++
3 files changed, 86 insertions(+), 83 deletions(-)
create mode 100644 Documentation/core-api/memory-hotplug-notifier.rst
diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst
b/Documentation/admin-guide/mm/memory-hotplug.rst
index a33090c..0b9c83e 100644
--- a/Documentation/admin-guide/mm/memory-hotplug.rst
+++ b/Documentation/admin-guide/mm/memory-hotplug.rst
@@ -31,7 +31,6 @@ be changed often.
6.1 Memory offline and ZONE_MOVABLE
6.2. How to offline memory
7. Physical memory remove
- 8. Memory hotplug event notifier
9. Future Work List
@@ -414,88 +413,6 @@ Need more implementation yet
- Notification completion of remove works by OS to firmware.
- Guard from remove if not yet.
-Memory hotplug event notifier
-=
-
-Hotplugging events are sent to a notification queue.
-
-There are six types of notification defined in ``include/linux/memory.h``:
-
-MEM_GOING_ONLINE
- Generated before new memory becomes available in order to be able to
- prepare subsystems to handle memory. The page allocator is still unable
- to allocate from the new memory.
-
-MEM_CANCEL_ONLINE
- Generated if MEMORY_GOING_ONLINE fails.
-
-MEM_ONLINE
- Generated when memory has successfully brought online. The callback may
- allocate pages from the new memory.
-
-MEM_GOING_OFFLINE
- Generated to begin the process of offlining memory. Allocations are no
- longer possible from the memory but some of the memory to be offlined
- is still in use. The callback can be used to free memory known to a
- subsystem from the indicated memory block.
-
-MEM_CANCEL_OFFLINE
- Generated if MEMORY_GOING_OFFLINE fails. Memory is available again from
- the memory block that we attempted to offline.
-
-MEM_OFFLINE
- Generated after offlining memory is complete.
-
-A callback routine can be registered by calling::
-
- hotplug_memory_notifier(callback_func, priority)
-
-Callback functions with higher values of priority are called before callback
-functions with lower values.
-
-A callback function must have the following prototype::
-
- int callback_func(
-struct notifier_block *self, unsigned long action, void *arg);
-
-The first argument of the callback function (self) is a pointer to the block
-of the notifier chain that points to the callback function itself.
-The second argument (action) is one of the event types described above.
-The third argument (arg) passes a pointer of struct memory_notify::
-
- struct memory_notify {
- unsigned long start_pfn;
- unsigned long nr_pages;
- int status_change_nid_normal;
- int status_change_nid_high;
- int status_change_nid;
- }
-
-- start_pfn is start_pfn of online/offline memory.
-- nr_pages is # of pages of online/offline memory.
-- status_change_nid_normal is set node id when N_NORMAL_MEMORY of nodemask
- is (will be) set/clear, if this is -1, then nodemask status is not changed.
-- status_change_nid_high is set node id when N_HIGH_MEMORY of nodemask
- is (will be) set/clear, if this is -1, then nodemask status is not changed.
-- status_change_nid is set node id when N_MEMORY of nodemask is (will be)
- set/clear. It means a new(memoryless) node gets new memory by online and a
- node loses all memory. If this is -1, then nodemask status is not changed.
-
- If status_changed_nid* >= 0, callback should create/discard structures for
the
- node if necessary.
-
-The callback routine shall return one of the values
-NOTIFY_DONE, NOTIFY_OK, NOTIFY_BAD, NOTIFY_STOP
-defined in ``include/linux/notifier.h``
-
-NOTIFY_DONE and NOTIFY_OK have no effect on the further processing.
-
-NOTIFY_BAD is used as response to the MEM_GOING_ONLINE, MEM_GOING_OFFLINE,
-MEM_ONLINE, or MEM_OFFLINE action to cancel hotplugging. It stops
-further processing of the notification queue.
-
-NOTIFY_STOP stops further processing of the notification queue.
-
Future Work
===
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 165d7688..4f8a426 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -32,6 +32,8 @@ Core utilities
gfp_mask-from-fs-io
timekeeping
boot-time-mm
+ memory-hotplug-notifier
+
Interfaces for kernel debugging
===
diff --git a/Documentation/core-api/memory-hotplug-notifier.rst
b/Documentation/core-api/memory-hotplug-notifier.rst
new file mode 100644
index 000..35347cc
--- /dev/null
+++ b/Documentation/core-api/memory-hotplug-notifier.rst
@@ -0,0 +1,84 @@
+..
[PATCH 1/2] docs: move memory hotplug description into admin-guide/mm
The memory hotplug description in Documentation/memory-hotplug.txt is
already formatted as ReST and can be easily added to admin-guide/mm
section.
While on it, slightly update formatting to make it consistent with the
doc-guide.
Signed-off-by: Mike Rapoport
---
Documentation/admin-guide/mm/index.rst | 1 +
.../mm/memory-hotplug.rst} | 73 +++---
2 files changed, 38 insertions(+), 36 deletions(-)
rename Documentation/{memory-hotplug.txt => admin-guide/mm/memory-hotplug.rst}
(92%)
diff --git a/Documentation/admin-guide/mm/index.rst
b/Documentation/admin-guide/mm/index.rst
index ceead68..8edb35f 100644
--- a/Documentation/admin-guide/mm/index.rst
+++ b/Documentation/admin-guide/mm/index.rst
@@ -29,6 +29,7 @@ the Linux memory management.
hugetlbpage
idle_page_tracking
ksm
+ memory-hotplug
numa_memory_policy
pagemap
soft-dirty
diff --git a/Documentation/memory-hotplug.txt
b/Documentation/admin-guide/mm/memory-hotplug.rst
similarity index 92%
rename from Documentation/memory-hotplug.txt
rename to Documentation/admin-guide/mm/memory-hotplug.rst
index 7f49ebf..a33090c 100644
--- a/Documentation/memory-hotplug.txt
+++ b/Documentation/admin-guide/mm/memory-hotplug.rst
@@ -1,3 +1,5 @@
+.. _admin_guide_memory_hotplug:
+
==
Memory Hotplug
==
@@ -9,10 +11,12 @@ This document is about memory hotplug including how-to-use
and current status.
Because Memory Hotplug is still under development, contents of this text will
be changed often.
+.. contents:: :local:
+
.. CONTENTS
1. Introduction
-1.1 purpose of memory hotplug
+1.1 Purpose of memory hotplug
1.2. Phases of memory hotplug
1.3. Unit of Memory online/offline operation
2. Kernel Configuration
@@ -35,13 +39,13 @@ be changed often.
(1) x86_64's has special implementation for memory hotplug.
This text does not describe it.
-(2) This text assumes that sysfs is mounted at /sys.
+(2) This text assumes that sysfs is mounted at ``/sys``.
Introduction
-purpose of memory hotplug
+Purpose of memory hotplug
-
Memory Hotplug allows users to increase/decrease the amount of memory.
@@ -57,7 +61,6 @@ hardware which supports memory power management.
Linux memory hotplug is designed for both purpose.
-
Phases of memory hotplug
@@ -92,7 +95,6 @@ phase by hand.
(However, if you writes udev's hotplug scripts for memory hotplug, these
phases can be execute in seamless way.)
-
Unit of Memory online/offline operation
---
@@ -107,10 +109,9 @@ unit upon which memory online/offline operations are to be
performed. The
default size of a memory block is the same as memory section size unless an
architecture specifies otherwise. (see :ref:`memory_hotplug_sysfs_files`.)
-To determine the size (in bytes) of a memory block please read this file:
-
-/sys/devices/system/memory/block_size_bytes
+To determine the size (in bytes) of a memory block please read this file::
+ /sys/devices/system/memory/block_size_bytes
Kernel Configuration
@@ -119,22 +120,22 @@ To use memory hotplug feature, kernel must be compiled
with following
config options.
- For all memory hotplug:
-- Memory model -> Sparse Memory (CONFIG_SPARSEMEM)
-- Allow for memory hot-add (CONFIG_MEMORY_HOTPLUG)
+- Memory model -> Sparse Memory (``CONFIG_SPARSEMEM``)
+- Allow for memory hot-add (``CONFIG_MEMORY_HOTPLUG``)
- To enable memory removal, the following are also necessary:
-- Allow for memory hot remove(CONFIG_MEMORY_HOTREMOVE)
-- Page Migration (CONFIG_MIGRATION)
+- Allow for memory hot remove(``CONFIG_MEMORY_HOTREMOVE``)
+- Page Migration (``CONFIG_MIGRATION``)
- For ACPI memory hotplug, the following are also necessary:
-- Memory hotplug (under ACPI Support menu) (CONFIG_ACPI_HOTPLUG_MEMORY)
+- Memory hotplug (under ACPI Support menu) (``CONFIG_ACPI_HOTPLUG_MEMORY``)
- This option can be kernel module.
- As a related configuration, if your box has a feature of NUMA-node hotplug
via ACPI, then this option is necessary too.
- ACPI0004,PNP0A05 and PNP0A06 Container Driver (under ACPI Support menu)
- (CONFIG_ACPI_CONTAINER).
+ (``CONFIG_ACPI_CONTAINER``).
This option can be kernel module too.
@@ -145,10 +146,11 @@ sysfs files for memory hotplug
==
All memory blocks have their device information in sysfs. Each memory block
-is described under /sys/devices/system/memory as:
+is described under ``/sys/devices/system/memory`` as::
/sys/devices/system/memory/memoryXXX
- (XXX is the memory block id.)
+
+where XXX is the memory block id.
For the memory block covered by the sysfs directory. It is expected that all
memory sections
[PATCH 0/2] docs: ReSTify memory-hotplug description
Hi,
Recently I've noticed that Documentation/memory-hotplug.txt is
1) mostly formatted
2) in a wrong place
These patches split the memory-hotplug.txt to two parts: user/admin
interface and memory hotplug notifier API and place these parts in the
correct places, with some formatting changes.
Mike Rapoport (2):
docs: move memory hotplug description into admin-guide/mm
docs/vm: split memory hotplug notifier description to Documentation/core-api
Documentation/admin-guide/mm/index.rst | 1 +
.../mm/memory-hotplug.rst} | 152 +
Documentation/core-api/index.rst | 2 +
Documentation/core-api/memory-hotplug-notifier.rst | 84
4 files changed, 122 insertions(+), 117 deletions(-)
rename Documentation/{memory-hotplug.txt => admin-guide/mm/memory-hotplug.rst}
(77%)
create mode 100644 Documentation/core-api/memory-hotplug-notifier.rst
--
2.7.4
