* [PATCH v4 09/28] docs: fb: convert docs to ReST and rename to *.rst
[not found] <cover.1560361364.git.mchehab+samsung@kernel.org>
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 12/28] docs: kbuild: " Mauro Carvalho Chehab
` (3 subsequent siblings)
4 siblings, 0 replies; 12+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Bartlomiej Zolnierkiewicz, Maik Broemme,
Thomas Winischhofer, Sudip Mukherjee, Teddy Wang, Bernie Thompson,
Michal Januszewski, Greg Kroah-Hartman, Jiri Slaby, dri-devel,
linux-fbdev
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Also, removed the Maintained by, as requested by Geert.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/fb/{api.txt => api.rst} | 29 +-
Documentation/fb/{arkfb.txt => arkfb.rst} | 8 +-
.../fb/{aty128fb.txt => aty128fb.rst} | 35 +-
.../fb/{cirrusfb.txt => cirrusfb.rst} | 47 +-
.../fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} | 57 +--
.../fb/{deferred_io.txt => deferred_io.rst} | 28 +-
Documentation/fb/{efifb.txt => efifb.rst} | 18 +-
.../fb/{ep93xx-fb.txt => ep93xx-fb.rst} | 27 +-
Documentation/fb/{fbcon.txt => fbcon.rst} | 177 +++----
.../fb/{framebuffer.txt => framebuffer.rst} | 80 ++--
Documentation/fb/{gxfb.txt => gxfb.rst} | 24 +-
Documentation/fb/index.rst | 50 ++
.../fb/{intel810.txt => intel810.rst} | 79 ++--
Documentation/fb/{intelfb.txt => intelfb.rst} | 62 +--
.../fb/{internals.txt => internals.rst} | 24 +-
Documentation/fb/{lxfb.txt => lxfb.rst} | 25 +-
Documentation/fb/matroxfb.rst | 443 ++++++++++++++++++
Documentation/fb/matroxfb.txt | 413 ----------------
.../fb/{metronomefb.txt => metronomefb.rst} | 8 +-
Documentation/fb/{modedb.txt => modedb.rst} | 44 +-
Documentation/fb/pvr2fb.rst | 66 +++
Documentation/fb/pvr2fb.txt | 65 ---
Documentation/fb/{pxafb.txt => pxafb.rst} | 81 +++-
Documentation/fb/{s3fb.txt => s3fb.rst} | 8 +-
.../fb/{sa1100fb.txt => sa1100fb.rst} | 23 +-
Documentation/fb/sh7760fb.rst | 130 +++++
Documentation/fb/sh7760fb.txt | 131 ------
Documentation/fb/{sisfb.txt => sisfb.rst} | 40 +-
Documentation/fb/{sm501.txt => sm501.rst} | 7 +-
Documentation/fb/{sm712fb.txt => sm712fb.rst} | 18 +-
Documentation/fb/sstfb.rst | 207 ++++++++
Documentation/fb/sstfb.txt | 174 -------
Documentation/fb/{tgafb.txt => tgafb.rst} | 30 +-
.../fb/{tridentfb.txt => tridentfb.rst} | 36 +-
Documentation/fb/{udlfb.txt => udlfb.rst} | 55 ++-
Documentation/fb/{uvesafb.txt => uvesafb.rst} | 128 ++---
Documentation/fb/{vesafb.txt => vesafb.rst} | 121 ++---
Documentation/fb/viafb.rst | 297 ++++++++++++
Documentation/fb/viafb.txt | 252 ----------
.../fb/{vt8623fb.txt => vt8623fb.rst} | 10 +-
MAINTAINERS | 10 +-
drivers/tty/Kconfig | 2 +-
drivers/video/fbdev/Kconfig | 24 +-
drivers/video/fbdev/matrox/matroxfb_base.c | 2 +-
drivers/video/fbdev/pxafb.c | 2 +-
drivers/video/fbdev/sh7760fb.c | 2 +-
47 files changed, 1944 insertions(+), 1657 deletions(-)
rename Documentation/fb/{api.txt => api.rst} (97%)
rename Documentation/fb/{arkfb.txt => arkfb.rst} (92%)
rename Documentation/fb/{aty128fb.txt => aty128fb.rst} (61%)
rename Documentation/fb/{cirrusfb.txt => cirrusfb.rst} (75%)
rename Documentation/fb/{cmap_xfbdev.txt => cmap_xfbdev.rst} (50%)
rename Documentation/fb/{deferred_io.txt => deferred_io.rst} (86%)
rename Documentation/fb/{efifb.txt => efifb.rst} (75%)
rename Documentation/fb/{ep93xx-fb.txt => ep93xx-fb.rst} (85%)
rename Documentation/fb/{fbcon.txt => fbcon.rst} (69%)
rename Documentation/fb/{framebuffer.txt => framebuffer.rst} (92%)
rename Documentation/fb/{gxfb.txt => gxfb.rst} (60%)
create mode 100644 Documentation/fb/index.rst
rename Documentation/fb/{intel810.txt => intel810.rst} (83%)
rename Documentation/fb/{intelfb.txt => intelfb.rst} (73%)
rename Documentation/fb/{internals.txt => internals.rst} (82%)
rename Documentation/fb/{lxfb.txt => lxfb.rst} (60%)
create mode 100644 Documentation/fb/matroxfb.rst
delete mode 100644 Documentation/fb/matroxfb.txt
rename Documentation/fb/{metronomefb.txt => metronomefb.rst} (98%)
rename Documentation/fb/{modedb.txt => modedb.rst} (87%)
create mode 100644 Documentation/fb/pvr2fb.rst
delete mode 100644 Documentation/fb/pvr2fb.txt
rename Documentation/fb/{pxafb.txt => pxafb.rst} (78%)
rename Documentation/fb/{s3fb.txt => s3fb.rst} (94%)
rename Documentation/fb/{sa1100fb.txt => sa1100fb.rst} (64%)
create mode 100644 Documentation/fb/sh7760fb.rst
delete mode 100644 Documentation/fb/sh7760fb.txt
rename Documentation/fb/{sisfb.txt => sisfb.rst} (85%)
rename Documentation/fb/{sm501.txt => sm501.rst} (65%)
rename Documentation/fb/{sm712fb.txt => sm712fb.rst} (59%)
create mode 100644 Documentation/fb/sstfb.rst
delete mode 100644 Documentation/fb/sstfb.txt
rename Documentation/fb/{tgafb.txt => tgafb.rst} (71%)
rename Documentation/fb/{tridentfb.txt => tridentfb.rst} (70%)
rename Documentation/fb/{udlfb.txt => udlfb.rst} (77%)
rename Documentation/fb/{uvesafb.txt => uvesafb.rst} (52%)
rename Documentation/fb/{vesafb.txt => vesafb.rst} (57%)
create mode 100644 Documentation/fb/viafb.rst
delete mode 100644 Documentation/fb/viafb.txt
rename Documentation/fb/{vt8623fb.txt => vt8623fb.rst} (85%)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 83e64d779887..581d8888e829 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -5046,7 +5046,7 @@
vector=percpu: enable percpu vector domain
video= [FB] Frame buffer configuration
- See Documentation/fb/modedb.txt.
+ See Documentation/fb/modedb.rst.
video.brightness_switch_enabled= [0,1]
If set to 1, on receiving an ACPI notify event
diff --git a/Documentation/fb/api.txt b/Documentation/fb/api.rst
similarity index 97%
rename from Documentation/fb/api.txt
rename to Documentation/fb/api.rst
index d52cf1e3b975..79ec33dded74 100644
--- a/Documentation/fb/api.txt
+++ b/Documentation/fb/api.rst
@@ -1,5 +1,6 @@
- The Frame Buffer Device API
- ---------------------------
+===========================
+The Frame Buffer Device API
+===========================
Last revised: June 21, 2011
@@ -21,13 +22,13 @@ deal with different behaviours.
---------------
Device and driver capabilities are reported in the fixed screen information
-capabilities field.
+capabilities field::
-struct fb_fix_screeninfo {
+ struct fb_fix_screeninfo {
...
__u16 capabilities; /* see FB_CAP_* */
...
-};
+ };
Application should use those capabilities to find out what features they can
expect from the device and driver.
@@ -151,9 +152,9 @@ fb_fix_screeninfo and fb_var_screeninfo structure respectively.
struct fb_fix_screeninfo stores device independent unchangeable information
about the frame buffer device and the current format. Those information can't
be directly modified by applications, but can be changed by the driver when an
-application modifies the format.
+application modifies the format::
-struct fb_fix_screeninfo {
+ struct fb_fix_screeninfo {
char id[16]; /* identification string eg "TT Builtin" */
unsigned long smem_start; /* Start of frame buffer mem */
/* (physical address) */
@@ -172,13 +173,13 @@ struct fb_fix_screeninfo {
/* specific chip/card we have */
__u16 capabilities; /* see FB_CAP_* */
__u16 reserved[2]; /* Reserved for future compatibility */
-};
+ };
struct fb_var_screeninfo stores device independent changeable information
about a frame buffer device, its current format and video mode, as well as
-other miscellaneous parameters.
+other miscellaneous parameters::
-struct fb_var_screeninfo {
+ struct fb_var_screeninfo {
__u32 xres; /* visible resolution */
__u32 yres;
__u32 xres_virtual; /* virtual resolution */
@@ -216,7 +217,7 @@ struct fb_var_screeninfo {
__u32 rotate; /* angle we rotate counter clockwise */
__u32 colorspace; /* colorspace for FOURCC-based modes */
__u32 reserved[4]; /* Reserved for future compatibility */
-};
+ };
To modify variable information, applications call the FBIOPUT_VSCREENINFO
ioctl with a pointer to a fb_var_screeninfo structure. If the call is
@@ -255,14 +256,14 @@ monochrome, grayscale or pseudocolor visuals, although this is not required.
- For truecolor and directcolor formats, applications set the grayscale field
to zero, and the red, blue, green and transp fields to describe the layout of
- color components in memory.
+ color components in memory::
-struct fb_bitfield {
+ struct fb_bitfield {
__u32 offset; /* beginning of bitfield */
__u32 length; /* length of bitfield */
__u32 msb_right; /* != 0 : Most significant bit is */
/* right */
-};
+ };
Pixel values are bits_per_pixel wide and are split in non-overlapping red,
green, blue and alpha (transparency) components. Location and size of each
diff --git a/Documentation/fb/arkfb.txt b/Documentation/fb/arkfb.rst
similarity index 92%
rename from Documentation/fb/arkfb.txt
rename to Documentation/fb/arkfb.rst
index e8487a9d6a05..aeca8773dd7e 100644
--- a/Documentation/fb/arkfb.txt
+++ b/Documentation/fb/arkfb.rst
@@ -1,6 +1,6 @@
-
- arkfb - fbdev driver for ARK Logic chips
- ========================================
+========================================
+arkfb - fbdev driver for ARK Logic chips
+========================================
Supported Hardware
@@ -47,7 +47,7 @@ Missing Features
(alias TODO list)
* secondary (not initialized by BIOS) device support
- * big endian support
+ * big endian support
* DPMS support
* MMIO support
* interlaced mode variant
diff --git a/Documentation/fb/aty128fb.txt b/Documentation/fb/aty128fb.rst
similarity index 61%
rename from Documentation/fb/aty128fb.txt
rename to Documentation/fb/aty128fb.rst
index b605204fcfe1..3f107718f933 100644
--- a/Documentation/fb/aty128fb.txt
+++ b/Documentation/fb/aty128fb.rst
@@ -1,8 +1,9 @@
-[This file is cloned from VesaFB/matroxfb]
-
+=================
What is aty128fb?
=================
+.. [This file is cloned from VesaFB/matroxfb]
+
This is a driver for a graphic framebuffer for ATI Rage128 based devices
on Intel and PPC boxes.
@@ -24,15 +25,15 @@ How to use it?
==============
Switching modes is done using the video=aty128fb:<resolution>... modedb
-boot parameter or using `fbset' program.
+boot parameter or using `fbset` program.
-See Documentation/fb/modedb.txt for more information on modedb
+See Documentation/fb/modedb.rst for more information on modedb
resolutions.
You should compile in both vgacon (to boot if you remove your Rage128 from
box) and aty128fb (for graphics mode). You should not compile-in vesafb
-unless you have primary display on non-Rage128 VBE2.0 device (see
-Documentation/fb/vesafb.txt for details).
+unless you have primary display on non-Rage128 VBE2.0 device (see
+Documentation/fb/vesafb.rst for details).
X11
@@ -48,16 +49,18 @@ Configuration
=============
You can pass kernel command line options to vesafb with
-`video=aty128fb:option1,option2:value2,option3' (multiple options should
-be separated by comma, values are separated from options by `:').
+`video=aty128fb:option1,option2:value2,option3` (multiple options should
+be separated by comma, values are separated from options by `:`).
Accepted options:
-noaccel - do not use acceleration engine. It is default.
-accel - use acceleration engine. Not finished.
-vmode:x - chooses PowerMacintosh video mode <x>. Deprecated.
-cmode:x - chooses PowerMacintosh colour mode <x>. Deprecated.
-<XxX@X> - selects startup videomode. See modedb.txt for detailed
- explanation. Default is 640x480x8bpp.
+========= =======================================================
+noaccel do not use acceleration engine. It is default.
+accel use acceleration engine. Not finished.
+vmode:x chooses PowerMacintosh video mode <x>. Deprecated.
+cmode:x chooses PowerMacintosh colour mode <x>. Deprecated.
+<XxX@X> selects startup videomode. See modedb.txt for detailed
+ explanation. Default is 640x480x8bpp.
+========= =======================================================
Limitations
@@ -65,8 +68,8 @@ Limitations
There are known and unknown bugs, features and misfeatures.
Currently there are following known bugs:
- + This driver is still experimental and is not finished. Too many
+
+ - This driver is still experimental and is not finished. Too many
bugs/errata to list here.
---
Brad Douglas <brad@neruo.com>
diff --git a/Documentation/fb/cirrusfb.txt b/Documentation/fb/cirrusfb.rst
similarity index 75%
rename from Documentation/fb/cirrusfb.txt
rename to Documentation/fb/cirrusfb.rst
index f75950d330a4..8c3e6c6cb114 100644
--- a/Documentation/fb/cirrusfb.txt
+++ b/Documentation/fb/cirrusfb.rst
@@ -1,32 +1,32 @@
+============================================
+Framebuffer driver for Cirrus Logic chipsets
+============================================
- Framebuffer driver for Cirrus Logic chipsets
- Copyright 1999 Jeff Garzik <jgarzik@pobox.com>
+Copyright 1999 Jeff Garzik <jgarzik@pobox.com>
-
-{ just a little something to get people going; contributors welcome! }
-
+.. just a little something to get people going; contributors welcome!
Chip families supported:
- SD64
- Piccolo
- Picasso
- Spectrum
- Alpine (GD-543x/4x)
- Picasso4 (GD-5446)
- GD-5480
- Laguna (GD-546x)
+ - SD64
+ - Piccolo
+ - Picasso
+ - Spectrum
+ - Alpine (GD-543x/4x)
+ - Picasso4 (GD-5446)
+ - GD-5480
+ - Laguna (GD-546x)
Bus's supported:
- PCI
- Zorro
+ - PCI
+ - Zorro
Architectures supported:
- i386
- Alpha
- PPC (Motorola Powerstack)
- m68k (Amiga)
+ - i386
+ - Alpha
+ - PPC (Motorola Powerstack)
+ - m68k (Amiga)
@@ -34,10 +34,9 @@ Default video modes
-------------------
At the moment, there are two kernel command line arguments supported:
-mode:640x480
-mode:800x600
- or
-mode:1024x768
+- mode:640x480
+- mode:800x600
+- mode:1024x768
Full support for startup video modes (modedb) will be integrated soon.
@@ -93,5 +92,3 @@ Version 1.9.4
Version 1.9.3
-------------
* Bundled with kernel 2.3.14-pre1 or later.
-
-
diff --git a/Documentation/fb/cmap_xfbdev.txt b/Documentation/fb/cmap_xfbdev.rst
similarity index 50%
rename from Documentation/fb/cmap_xfbdev.txt
rename to Documentation/fb/cmap_xfbdev.rst
index 55e1f0a3d2b4..5db5e9787361 100644
--- a/Documentation/fb/cmap_xfbdev.txt
+++ b/Documentation/fb/cmap_xfbdev.rst
@@ -1,26 +1,29 @@
+==========================
Understanding fbdev's cmap
---------------------------
+==========================
These notes explain how X's dix layer uses fbdev's cmap structures.
-*. example of relevant structures in fbdev as used for a 3-bit grayscale cmap
-struct fb_var_screeninfo {
- .bits_per_pixel = 8,
- .grayscale = 1,
- .red = { 4, 3, 0 },
- .green = { 0, 0, 0 },
- .blue = { 0, 0, 0 },
-}
-struct fb_fix_screeninfo {
- .visual = FB_VISUAL_STATIC_PSEUDOCOLOR,
-}
-for (i = 0; i < 8; i++)
+- example of relevant structures in fbdev as used for a 3-bit grayscale cmap::
+
+ struct fb_var_screeninfo {
+ .bits_per_pixel = 8,
+ .grayscale = 1,
+ .red = { 4, 3, 0 },
+ .green = { 0, 0, 0 },
+ .blue = { 0, 0, 0 },
+ }
+ struct fb_fix_screeninfo {
+ .visual = FB_VISUAL_STATIC_PSEUDOCOLOR,
+ }
+ for (i = 0; i < 8; i++)
info->cmap.red[i] = (((2*i)+1)*(0xFFFF))/16;
-memcpy(info->cmap.green, info->cmap.red, sizeof(u16)*8);
-memcpy(info->cmap.blue, info->cmap.red, sizeof(u16)*8);
+ memcpy(info->cmap.green, info->cmap.red, sizeof(u16)*8);
+ memcpy(info->cmap.blue, info->cmap.red, sizeof(u16)*8);
-*. X11 apps do something like the following when trying to use grayscale.
-for (i=0; i < 8; i++) {
+- X11 apps do something like the following when trying to use grayscale::
+
+ for (i=0; i < 8; i++) {
char colorspec[64];
memset(colorspec,0,64);
sprintf(colorspec, "rgb:%x/%x/%x", i*36,i*36,i*36);
@@ -28,26 +31,26 @@ for (i=0; i < 8; i++) {
printf("Can't get color %s\n",colorspec);
XAllocColor(outputDisplay, testColormap, &wantedColor);
grays[i] = wantedColor;
-}
+ }
+
There's also named equivalents like gray1..x provided you have an rgb.txt.
Somewhere in X's callchain, this results in a call to X code that handles the
colormap. For example, Xfbdev hits the following:
-xc-011010/programs/Xserver/dix/colormap.c:
+xc-011010/programs/Xserver/dix/colormap.c::
-FindBestPixel(pentFirst, size, prgb, channel)
+ FindBestPixel(pentFirst, size, prgb, channel)
-dr = (long) pent->co.local.red - prgb->red;
-dg = (long) pent->co.local.green - prgb->green;
-db = (long) pent->co.local.blue - prgb->blue;
-sq = dr * dr;
-UnsignedToBigNum (sq, &sum);
-BigNumAdd (&sum, &temp, &sum);
+ dr = (long) pent->co.local.red - prgb->red;
+ dg = (long) pent->co.local.green - prgb->green;
+ db = (long) pent->co.local.blue - prgb->blue;
+ sq = dr * dr;
+ UnsignedToBigNum (sq, &sum);
+ BigNumAdd (&sum, &temp, &sum);
co.local.red are entries that were brought in through FBIOGETCMAP which come
directly from the info->cmap.red that was listed above. The prgb is the rgb
that the app wants to match to. The above code is doing what looks like a least
squares matching function. That's why the cmap entries can't be set to the left
hand side boundaries of a color range.
-
diff --git a/Documentation/fb/deferred_io.txt b/Documentation/fb/deferred_io.rst
similarity index 86%
rename from Documentation/fb/deferred_io.txt
rename to Documentation/fb/deferred_io.rst
index 748328370250..7300cff255a3 100644
--- a/Documentation/fb/deferred_io.txt
+++ b/Documentation/fb/deferred_io.rst
@@ -1,5 +1,6 @@
+===========
Deferred IO
------------
+===========
Deferred IO is a way to delay and repurpose IO. It uses host memory as a
buffer and the MMU pagefault as a pretrigger for when to perform the device
@@ -16,7 +17,7 @@ works:
- app continues writing to that page with no additional cost. this is
the key benefit.
- the workqueue task comes in and mkcleans the pages on the list, then
- completes the work associated with updating the framebuffer. this is
+ completes the work associated with updating the framebuffer. this is
the real work talking to the device.
- app tries to write to the address (that has now been mkcleaned)
- get pagefault and the above sequence occurs again
@@ -47,29 +48,32 @@ How to use it: (for fbdev drivers)
----------------------------------
The following example may be helpful.
-1. Setup your structure. Eg:
+1. Setup your structure. Eg::
-static struct fb_deferred_io hecubafb_defio = {
- .delay = HZ,
- .deferred_io = hecubafb_dpy_deferred_io,
-};
+ static struct fb_deferred_io hecubafb_defio = {
+ .delay = HZ,
+ .deferred_io = hecubafb_dpy_deferred_io,
+ };
The delay is the minimum delay between when the page_mkwrite trigger occurs
and when the deferred_io callback is called. The deferred_io callback is
explained below.
-2. Setup your deferred IO callback. Eg:
-static void hecubafb_dpy_deferred_io(struct fb_info *info,
- struct list_head *pagelist)
+2. Setup your deferred IO callback. Eg::
+
+ static void hecubafb_dpy_deferred_io(struct fb_info *info,
+ struct list_head *pagelist)
The deferred_io callback is where you would perform all your IO to the display
device. You receive the pagelist which is the list of pages that were written
to during the delay. You must not modify this list. This callback is called
from a workqueue.
-3. Call init
+3. Call init::
+
info->fbdefio = &hecubafb_defio;
fb_deferred_io_init(info);
-4. Call cleanup
+4. Call cleanup::
+
fb_deferred_io_cleanup(info);
diff --git a/Documentation/fb/efifb.txt b/Documentation/fb/efifb.rst
similarity index 75%
rename from Documentation/fb/efifb.txt
rename to Documentation/fb/efifb.rst
index 1a85c1bdaf38..04840331a00e 100644
--- a/Documentation/fb/efifb.txt
+++ b/Documentation/fb/efifb.rst
@@ -1,6 +1,6 @@
-
+==============
What is efifb?
-===============
+==============
This is a generic EFI platform driver for Intel based Apple computers.
efifb is only for EFI booted Intel Macs.
@@ -8,16 +8,17 @@ efifb is only for EFI booted Intel Macs.
Supported Hardware
==================
-iMac 17"/20"
-Macbook
-Macbook Pro 15"/17"
-MacMini
+- iMac 17"/20"
+- Macbook
+- Macbook Pro 15"/17"
+- MacMini
How to use it?
==============
efifb does not have any kind of autodetection of your machine.
-You have to add the following kernel parameters in your elilo.conf:
+You have to add the following kernel parameters in your elilo.conf::
+
Macbook :
video=efifb:macbook
MacMini :
@@ -29,9 +30,10 @@ You have to add the following kernel parameters in your elilo.conf:
Accepted options:
+======= ===========================================================
nowc Don't map the framebuffer write combined. This can be used
to workaround side-effects and slowdowns on other CPU cores
when large amounts of console data are written.
+======= ===========================================================
---
Edgar Hucek <gimli@dark-green.com>
diff --git a/Documentation/fb/ep93xx-fb.txt b/Documentation/fb/ep93xx-fb.rst
similarity index 85%
rename from Documentation/fb/ep93xx-fb.txt
rename to Documentation/fb/ep93xx-fb.rst
index 5af1bd9effae..6f7767926d1a 100644
--- a/Documentation/fb/ep93xx-fb.txt
+++ b/Documentation/fb/ep93xx-fb.rst
@@ -4,7 +4,7 @@ Driver for EP93xx LCD controller
The EP93xx LCD controller can drive both standard desktop monitors and
embedded LCD displays. If you have a standard desktop monitor then you
-can use the standard Linux video mode database. In your board file:
+can use the standard Linux video mode database. In your board file::
static struct ep93xxfb_mach_info some_board_fb_info = {
.num_modes = EP93XXFB_USE_MODEDB,
@@ -12,7 +12,7 @@ can use the standard Linux video mode database. In your board file:
};
If you have an embedded LCD display then you need to define a video
-mode for it as follows:
+mode for it as follows::
static struct fb_videomode some_board_video_modes[] = {
{
@@ -23,11 +23,11 @@ mode for it as follows:
Note that the pixel clock value is in pico-seconds. You can use the
KHZ2PICOS macro to convert the pixel clock value. Most other values
-are in pixel clocks. See Documentation/fb/framebuffer.txt for further
+are in pixel clocks. See Documentation/fb/framebuffer.rst for further
details.
The ep93xxfb_mach_info structure for your board should look like the
-following:
+following::
static struct ep93xxfb_mach_info some_board_fb_info = {
.num_modes = ARRAY_SIZE(some_board_video_modes),
@@ -37,7 +37,7 @@ following:
};
The framebuffer device can be registered by adding the following to
-your board initialisation function:
+your board initialisation function::
ep93xx_register_fb(&some_board_fb_info);
@@ -50,6 +50,7 @@ to configure the controller. The video attributes flags are fully
documented in section 7 of the EP93xx users' guide. The following
flags are available:
+=============================== ==========================================
EP93XXFB_PCLK_FALLING Clock data on the falling edge of the
pixel clock. The default is to clock
data on the rising edge.
@@ -62,10 +63,12 @@ EP93XXFB_SYNC_HORIZ_HIGH Horizontal sync is active high. By
EP93XXFB_SYNC_VERT_HIGH Vertical sync is active high. By
default the vertical sync is active high.
+=============================== ==========================================
The physical address of the framebuffer can be controlled using the
following flags:
+=============================== ======================================
EP93XXFB_USE_SDCSN0 Use SDCSn[0] for the framebuffer. This
is the default setting.
@@ -74,6 +77,7 @@ EP93XXFB_USE_SDCSN1 Use SDCSn[1] for the framebuffer.
EP93XXFB_USE_SDCSN2 Use SDCSn[2] for the framebuffer.
EP93XXFB_USE_SDCSN3 Use SDCSn[3] for the framebuffer.
+=============================== ======================================
==================
Platform callbacks
@@ -87,7 +91,7 @@ blanked or unblanked.
The setup and teardown devices pass the platform_device structure as
an argument. The fb_info and ep93xxfb_mach_info structures can be
-obtained as follows:
+obtained as follows::
static int some_board_fb_setup(struct platform_device *pdev)
{
@@ -101,17 +105,17 @@ obtained as follows:
Setting the video mode
======================
-The video mode is set using the following syntax:
+The video mode is set using the following syntax::
video=XRESxYRES[-BPP][@REFRESH]
If the EP93xx video driver is built-in then the video mode is set on
-the Linux kernel command line, for example:
+the Linux kernel command line, for example::
video=ep93xx-fb:800x600-16@60
If the EP93xx video driver is built as a module then the video mode is
-set when the module is installed:
+set when the module is installed::
modprobe ep93xx-fb video=320x240
@@ -121,13 +125,14 @@ Screenpage bug
At least on the EP9315 there is a silicon bug which causes bit 27 of
the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
-an unofficial errata for this bug at:
+an unofficial errata for this bug at::
+
http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2
By default the EP93xx framebuffer driver checks if the allocated physical
address has bit 27 set. If it does, then the memory is freed and an
error is returned. The check can be disabled by adding the following
-option when loading the driver:
+option when loading the driver::
ep93xx-fb.check_screenpage_bug=0
diff --git a/Documentation/fb/fbcon.txt b/Documentation/fb/fbcon.rst
similarity index 69%
rename from Documentation/fb/fbcon.txt
rename to Documentation/fb/fbcon.rst
index 60a5ec04e8f0..cfb9f7c38f18 100644
--- a/Documentation/fb/fbcon.txt
+++ b/Documentation/fb/fbcon.rst
@@ -1,39 +1,41 @@
+=======================
The Framebuffer Console
=======================
- The framebuffer console (fbcon), as its name implies, is a text
+The framebuffer console (fbcon), as its name implies, is a text
console running on top of the framebuffer device. It has the functionality of
any standard text console driver, such as the VGA console, with the added
features that can be attributed to the graphical nature of the framebuffer.
- In the x86 architecture, the framebuffer console is optional, and
+In the x86 architecture, the framebuffer console is optional, and
some even treat it as a toy. For other architectures, it is the only available
display device, text or graphical.
- What are the features of fbcon? The framebuffer console supports
+What are the features of fbcon? The framebuffer console supports
high resolutions, varying font types, display rotation, primitive multihead,
etc. Theoretically, multi-colored fonts, blending, aliasing, and any feature
made available by the underlying graphics card are also possible.
A. Configuration
+================
- The framebuffer console can be enabled by using your favorite kernel
+The framebuffer console can be enabled by using your favorite kernel
configuration tool. It is under Device Drivers->Graphics Support->Frame
buffer Devices->Console display driver support->Framebuffer Console Support.
Select 'y' to compile support statically or 'm' for module support. The
module will be fbcon.
- In order for fbcon to activate, at least one framebuffer driver is
+In order for fbcon to activate, at least one framebuffer driver is
required, so choose from any of the numerous drivers available. For x86
systems, they almost universally have VGA cards, so vga16fb and vesafb will
always be available. However, using a chipset-specific driver will give you
more speed and features, such as the ability to change the video mode
dynamically.
- To display the penguin logo, choose any logo available in Graphics
+To display the penguin logo, choose any logo available in Graphics
support->Bootup logo.
- Also, you will need to select at least one compiled-in font, but if
+Also, you will need to select at least one compiled-in font, but if
you don't do anything, the kernel configuration tool will select one for you,
usually an 8x16 font.
@@ -44,6 +46,7 @@ fortunate to have a driver that does not alter the graphics chip, then you
will still get a VGA console.
B. Loading
+==========
Possible scenarios:
@@ -72,33 +75,33 @@ Possible scenarios:
C. Boot options
- The framebuffer console has several, largely unknown, boot options
- that can change its behavior.
+ The framebuffer console has several, largely unknown, boot options
+ that can change its behavior.
1. fbcon=font:<name>
- Select the initial font to use. The value 'name' can be any of the
- compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
- PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
+ Select the initial font to use. The value 'name' can be any of the
+ compiled-in fonts: 10x18, 6x10, 7x14, Acorn8x8, MINI4x6,
+ PEARL8x8, ProFont6x11, SUN12x22, SUN8x16, VGA8x16, VGA8x8.
Note, not all drivers can handle font with widths not divisible by 8,
- such as vga16fb.
+ such as vga16fb.
2. fbcon=scrollback:<value>[k]
- The scrollback buffer is memory that is used to preserve display
- contents that has already scrolled past your view. This is accessed
- by using the Shift-PageUp key combination. The value 'value' is any
- integer. It defaults to 32KB. The 'k' suffix is optional, and will
- multiply the 'value' by 1024.
+ The scrollback buffer is memory that is used to preserve display
+ contents that has already scrolled past your view. This is accessed
+ by using the Shift-PageUp key combination. The value 'value' is any
+ integer. It defaults to 32KB. The 'k' suffix is optional, and will
+ multiply the 'value' by 1024.
3. fbcon=map:<0123>
- This is an interesting option. It tells which driver gets mapped to
- which console. The value '0123' is a sequence that gets repeated until
- the total length is 64 which is the number of consoles available. In
- the above example, it is expanded to 012301230123... and the mapping
- will be:
+ This is an interesting option. It tells which driver gets mapped to
+ which console. The value '0123' is a sequence that gets repeated until
+ the total length is 64 which is the number of consoles available. In
+ the above example, it is expanded to 012301230123... and the mapping
+ will be::
tty | 1 2 3 4 5 6 7 8 9 ...
fb | 0 1 2 3 0 1 2 3 0 ...
@@ -126,20 +129,20 @@ C. Boot options
4. fbcon=rotate:<n>
- This option changes the orientation angle of the console display. The
- value 'n' accepts the following:
+ This option changes the orientation angle of the console display. The
+ value 'n' accepts the following:
- 0 - normal orientation (0 degree)
- 1 - clockwise orientation (90 degrees)
- 2 - upside down orientation (180 degrees)
- 3 - counterclockwise orientation (270 degrees)
+ - 0 - normal orientation (0 degree)
+ - 1 - clockwise orientation (90 degrees)
+ - 2 - upside down orientation (180 degrees)
+ - 3 - counterclockwise orientation (270 degrees)
The angle can be changed anytime afterwards by 'echoing' the same
numbers to any one of the 2 attributes found in
/sys/class/graphics/fbcon:
- rotate - rotate the display of the active console
- rotate_all - rotate the display of all consoles
+ - rotate - rotate the display of the active console
+ - rotate_all - rotate the display of all consoles
Console rotation will only become available if Framebuffer Console
Rotation support is compiled in your kernel.
@@ -177,9 +180,9 @@ Before going on to how to attach, detach and unload the framebuffer console, an
illustration of the dependencies may help.
The console layer, as with most subsystems, needs a driver that interfaces with
-the hardware. Thus, in a VGA console:
+the hardware. Thus, in a VGA console::
-console ---> VGA driver ---> hardware.
+ console ---> VGA driver ---> hardware.
Assuming the VGA driver can be unloaded, one must first unbind the VGA driver
from the console layer before unloading the driver. The VGA driver cannot be
@@ -187,9 +190,9 @@ unloaded if it is still bound to the console layer. (See
Documentation/console/console.txt for more information).
This is more complicated in the case of the framebuffer console (fbcon),
-because fbcon is an intermediate layer between the console and the drivers:
+because fbcon is an intermediate layer between the console and the drivers::
-console ---> fbcon ---> fbdev drivers ---> hardware
+ console ---> fbcon ---> fbdev drivers ---> hardware
The fbdev drivers cannot be unloaded if bound to fbcon, and fbcon cannot
be unloaded if it's bound to the console layer.
@@ -204,12 +207,12 @@ So, how do we unbind fbcon from the console? Part of the answer is in
Documentation/console/console.txt. To summarize:
Echo a value to the bind file that represents the framebuffer console
-driver. So assuming vtcon1 represents fbcon, then:
+driver. So assuming vtcon1 represents fbcon, then::
-echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to
- console layer
-echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from
- console layer
+ echo 1 > sys/class/vtconsole/vtcon1/bind - attach framebuffer console to
+ console layer
+ echo 0 > sys/class/vtconsole/vtcon1/bind - detach framebuffer console from
+ console layer
If fbcon is detached from the console layer, your boot console driver (which is
usually VGA text mode) will take over. A few drivers (rivafb and i810fb) will
@@ -223,19 +226,19 @@ restored properly. The following is one of the several methods that you can do:
2. In your kernel configuration, ensure that CONFIG_FRAMEBUFFER_CONSOLE is set
to 'y' or 'm'. Enable one or more of your favorite framebuffer drivers.
-3. Boot into text mode and as root run:
+3. Boot into text mode and as root run::
vbetool vbestate save > <vga state file>
- The above command saves the register contents of your graphics
- hardware to <vga state file>. You need to do this step only once as
- the state file can be reused.
+ The above command saves the register contents of your graphics
+ hardware to <vga state file>. You need to do this step only once as
+ the state file can be reused.
-4. If fbcon is compiled as a module, load fbcon by doing:
+4. If fbcon is compiled as a module, load fbcon by doing::
modprobe fbcon
-5. Now to detach fbcon:
+5. Now to detach fbcon::
vbetool vbestate restore < <vga state file> && \
echo 0 > /sys/class/vtconsole/vtcon1/bind
@@ -243,7 +246,7 @@ restored properly. The following is one of the several methods that you can do:
6. That's it, you're back to VGA mode. And if you compiled fbcon as a module,
you can unload it by 'rmmod fbcon'.
-7. To reattach fbcon:
+7. To reattach fbcon::
echo 1 > /sys/class/vtconsole/vtcon1/bind
@@ -266,82 +269,82 @@ the following:
Variation 1:
- a. Before detaching fbcon, do
+ a. Before detaching fbcon, do::
- vbetool vbemode save > <vesa state file> # do once for each vesafb mode,
- # the file can be reused
+ vbetool vbemode save > <vesa state file> # do once for each vesafb mode,
+ # the file can be reused
b. Detach fbcon as in step 5.
- c. Attach fbcon
+ c. Attach fbcon::
- vbetool vbestate restore < <vesa state file> && \
+ vbetool vbestate restore < <vesa state file> && \
echo 1 > /sys/class/vtconsole/vtcon1/bind
Variation 2:
- a. Before detaching fbcon, do:
+ a. Before detaching fbcon, do::
+
echo <ID> > /sys/class/tty/console/bind
-
- vbetool vbemode get
+ vbetool vbemode get
b. Take note of the mode number
b. Detach fbcon as in step 5.
- c. Attach fbcon:
+ c. Attach fbcon::
- vbetool vbemode set <mode number> && \
- echo 1 > /sys/class/vtconsole/vtcon1/bind
+ vbetool vbemode set <mode number> && \
+ echo 1 > /sys/class/vtconsole/vtcon1/bind
Samples:
========
Here are 2 sample bash scripts that you can use to bind or unbind the
-framebuffer console driver if you are on an X86 box:
+framebuffer console driver if you are on an X86 box::
----------------------------------------------------------------------------
-#!/bin/bash
-# Unbind fbcon
+ #!/bin/bash
+ # Unbind fbcon
-# Change this to where your actual vgastate file is located
-# Or Use VGASTATE=$1 to indicate the state file at runtime
-VGASTATE=/tmp/vgastate
+ # Change this to where your actual vgastate file is located
+ # Or Use VGASTATE=$1 to indicate the state file at runtime
+ VGASTATE=/tmp/vgastate
-# path to vbetool
-VBETOOL=/usr/local/bin
+ # path to vbetool
+ VBETOOL=/usr/local/bin
-for (( i = 0; i < 16; i++))
-do
- if test -x /sys/class/vtconsole/vtcon$i; then
- if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
- = 1 ]; then
+ for (( i = 0; i < 16; i++))
+ do
+ if test -x /sys/class/vtconsole/vtcon$i; then
+ if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
+ = 1 ]; then
if test -x $VBETOOL/vbetool; then
echo Unbinding vtcon$i
$VBETOOL/vbetool vbestate restore < $VGASTATE
echo 0 > /sys/class/vtconsole/vtcon$i/bind
fi
- fi
- fi
-done
+ fi
+ fi
+ done
---------------------------------------------------------------------------
-#!/bin/bash
-# Bind fbcon
-for (( i = 0; i < 16; i++))
-do
- if test -x /sys/class/vtconsole/vtcon$i; then
- if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
- = 1 ]; then
+::
+
+ #!/bin/bash
+ # Bind fbcon
+
+ for (( i = 0; i < 16; i++))
+ do
+ if test -x /sys/class/vtconsole/vtcon$i; then
+ if [ `cat /sys/class/vtconsole/vtcon$i/name | grep -c "frame buffer"` \
+ = 1 ]; then
echo Unbinding vtcon$i
echo 1 > /sys/class/vtconsole/vtcon$i/bind
- fi
- fi
-done
----------------------------------------------------------------------------
+ fi
+ fi
+ done
---
Antonino Daplas <adaplas@pol.net>
diff --git a/Documentation/fb/framebuffer.txt b/Documentation/fb/framebuffer.rst
similarity index 92%
rename from Documentation/fb/framebuffer.txt
rename to Documentation/fb/framebuffer.rst
index 58c5ae2e9f59..7fe087310c82 100644
--- a/Documentation/fb/framebuffer.txt
+++ b/Documentation/fb/framebuffer.rst
@@ -1,7 +1,7 @@
- The Frame Buffer Device
- -----------------------
+=======================
+The Frame Buffer Device
+=======================
-Maintained by Geert Uytterhoeven <geert@linux-m68k.org>
Last revised: May 10, 2001
@@ -26,7 +26,7 @@ other device in /dev. It's a character device using major 29; the minor
specifies the frame buffer number.
By convention, the following device nodes are used (numbers indicate the device
-minor numbers):
+minor numbers)::
0 = /dev/fb0 First frame buffer
1 = /dev/fb1 Second frame buffer
@@ -34,15 +34,15 @@ minor numbers):
31 = /dev/fb31 32nd frame buffer
For backwards compatibility, you may want to create the following symbolic
-links:
+links::
/dev/fb0current -> fb0
/dev/fb1current -> fb1
and so on...
-The frame buffer devices are also `normal' memory devices, this means, you can
-read and write their contents. You can, for example, make a screen snapshot by
+The frame buffer devices are also `normal` memory devices, this means, you can
+read and write their contents. You can, for example, make a screen snapshot by::
cp /dev/fb0 myfile
@@ -54,11 +54,11 @@ Application software that uses the frame buffer device (e.g. the X server) will
use /dev/fb0 by default (older software uses /dev/fb0current). You can specify
an alternative frame buffer device by setting the environment variable
$FRAMEBUFFER to the path name of a frame buffer device, e.g. (for sh/bash
-users):
+users)::
export FRAMEBUFFER=/dev/fb1
-or (for csh users):
+or (for csh users)::
setenv FRAMEBUFFER /dev/fb1
@@ -90,9 +90,9 @@ which data structures they work. Here's just a brief overview:
possible).
- You can get and set parts of the color map. Communication is done with 16
- bits per color part (red, green, blue, transparency) to support all
- existing hardware. The driver does all the computations needed to apply
- it to the hardware (round it down to less bits, maybe throw away
+ bits per color part (red, green, blue, transparency) to support all
+ existing hardware. The driver does all the computations needed to apply
+ it to the hardware (round it down to less bits, maybe throw away
transparency).
All this hardware abstraction makes the implementation of application programs
@@ -113,10 +113,10 @@ much trouble...
3. Frame Buffer Resolution Maintenance
--------------------------------------
-Frame buffer resolutions are maintained using the utility `fbset'. It can
+Frame buffer resolutions are maintained using the utility `fbset`. It can
change the video mode properties of a frame buffer device. Its main usage is
-to change the current video mode, e.g. during boot up in one of your /etc/rc.*
-or /etc/init.d/* files.
+to change the current video mode, e.g. during boot up in one of your `/etc/rc.*`
+or `/etc/init.d/*` files.
Fbset uses a video mode database stored in a configuration file, so you can
easily add your own modes and refer to them with a simple identifier.
@@ -129,8 +129,8 @@ The X server (XF68_FBDev) is the most notable application program for the frame
buffer device. Starting with XFree86 release 3.2, the X server is part of
XFree86 and has 2 modes:
- - If the `Display' subsection for the `fbdev' driver in the /etc/XF86Config
- file contains a
+ - If the `Display` subsection for the `fbdev` driver in the /etc/XF86Config
+ file contains a::
Modes "default"
@@ -146,7 +146,7 @@ XFree86 and has 2 modes:
same virtual desktop size. The frame buffer device that's used is still
/dev/fb0current (or $FRAMEBUFFER), but the available resolutions are
defined by /etc/XF86Config now. The disadvantage is that you have to
- specify the timings in a different format (but `fbset -x' may help).
+ specify the timings in a different format (but `fbset -x` may help).
To tune a video mode, you can use fbset or xvidtune. Note that xvidtune doesn't
work 100% with XF68_FBDev: the reported clock values are always incorrect.
@@ -172,29 +172,29 @@ retrace, the electron beam is turned off (blanked).
The speed at which the electron beam paints the pixels is determined by the
dotclock in the graphics board. For a dotclock of e.g. 28.37516 MHz (millions
-of cycles per second), each pixel is 35242 ps (picoseconds) long:
+of cycles per second), each pixel is 35242 ps (picoseconds) long::
1/(28.37516E6 Hz) = 35.242E-9 s
-If the screen resolution is 640x480, it will take
+If the screen resolution is 640x480, it will take::
640*35.242E-9 s = 22.555E-6 s
to paint the 640 (xres) pixels on one scanline. But the horizontal retrace
-also takes time (e.g. 272 `pixels'), so a full scanline takes
+also takes time (e.g. 272 `pixels`), so a full scanline takes::
(640+272)*35.242E-9 s = 32.141E-6 s
-We'll say that the horizontal scanrate is about 31 kHz:
+We'll say that the horizontal scanrate is about 31 kHz::
1/(32.141E-6 s) = 31.113E3 Hz
A full screen counts 480 (yres) lines, but we have to consider the vertical
-retrace too (e.g. 49 `lines'). So a full screen will take
+retrace too (e.g. 49 `lines`). So a full screen will take::
(480+49)*32.141E-6 s = 17.002E-3 s
-The vertical scanrate is about 59 Hz:
+The vertical scanrate is about 59 Hz::
1/(17.002E-3 s) = 58.815 Hz
@@ -212,7 +212,7 @@ influenced by the moments at which the synchronization pulses occur.
The following picture summarizes all timings. The horizontal retrace time is
the sum of the left margin, the right margin and the hsync length, while the
vertical retrace time is the sum of the upper margin, the lower margin and the
-vsync length.
+vsync length::
+----------+---------------------------------------------+----------+-------+
| | ↑ | | |
@@ -256,7 +256,8 @@ The frame buffer device expects all horizontal timings in number of dotclocks
6. Converting XFree86 timing values info frame buffer device timings
--------------------------------------------------------------------
-An XFree86 mode line consists of the following fields:
+An XFree86 mode line consists of the following fields::
+
"800x600" 50 800 856 976 1040 600 637 643 666
< name > DCF HR SH1 SH2 HFL VR SV1 SV2 VFL
@@ -271,19 +272,27 @@ The frame buffer device uses the following fields:
- vsync_len: length of vertical sync
1) Pixelclock:
+
xfree: in MHz
+
fb: in picoseconds (ps)
pixclock = 1000000 / DCF
2) horizontal timings:
+
left_margin = HFL - SH2
+
right_margin = SH1 - HR
+
hsync_len = SH2 - SH1
3) vertical timings:
+
upper_margin = VFL - SV2
+
lower_margin = SV1 - VR
+
vsync_len = SV2 - SV1
Good examples for VESA timings can be found in the XFree86 source tree,
@@ -303,9 +312,10 @@ and to the following documentation:
- The manual pages for fbset: fbset(8), fb.modes(5)
- The manual pages for XFree86: XF68_FBDev(1), XF86Config(4/5)
- The mighty kernel sources:
- o linux/drivers/video/
- o linux/include/linux/fb.h
- o linux/include/video/
+
+ - linux/drivers/video/
+ - linux/include/linux/fb.h
+ - linux/include/video/
@@ -330,14 +340,14 @@ and on its mirrors.
The latest version of fbset can be found at
- http://www.linux-fbdev.org/
+ http://www.linux-fbdev.org/
+
+
+10. Credits
+-----------
-
-10. Credits
-----------
-
This readme was written by Geert Uytterhoeven, partly based on the original
-`X-framebuffer.README' by Roman Hodek and Martin Schaller. Section 6 was
+`X-framebuffer.README` by Roman Hodek and Martin Schaller. Section 6 was
provided by Frank Neumann.
The frame buffer device abstraction was designed by Martin Schaller.
diff --git a/Documentation/fb/gxfb.txt b/Documentation/fb/gxfb.rst
similarity index 60%
rename from Documentation/fb/gxfb.txt
rename to Documentation/fb/gxfb.rst
index 2f640903bbb2..5738709bccbb 100644
--- a/Documentation/fb/gxfb.txt
+++ b/Documentation/fb/gxfb.rst
@@ -1,7 +1,8 @@
-[This file is cloned from VesaFB/aty128fb]
-
+=============
What is gxfb?
-=================
+=============
+
+.. [This file is cloned from VesaFB/aty128fb]
This is a graphics framebuffer driver for AMD Geode GX2 based processors.
@@ -23,9 +24,9 @@ How to use it?
==============
Switching modes is done using gxfb.mode_option=<resolution>... boot
-parameter or using `fbset' program.
+parameter or using `fbset` program.
-See Documentation/fb/modedb.txt for more information on modedb
+See Documentation/fb/modedb.rst for more information on modedb
resolutions.
@@ -42,11 +43,12 @@ You can pass kernel command line options to gxfb with gxfb.<option>.
For example, gxfb.mode_option=800x600@75.
Accepted options:
-mode_option - specify the video mode. Of the form
- <x>x<y>[-<bpp>][@<refresh>]
-vram - size of video ram (normally auto-detected)
-vt_switch - enable vt switching during suspend/resume. The vt
- switch is slow, but harmless.
+================ ==================================================
+mode_option specify the video mode. Of the form
+ <x>x<y>[-<bpp>][@<refresh>]
+vram size of video ram (normally auto-detected)
+vt_switch enable vt switching during suspend/resume. The vt
+ switch is slow, but harmless.
+================ ==================================================
---
Andres Salomon <dilinger@debian.org>
diff --git a/Documentation/fb/index.rst b/Documentation/fb/index.rst
new file mode 100644
index 000000000000..d47313714635
--- /dev/null
+++ b/Documentation/fb/index.rst
@@ -0,0 +1,50 @@
+:orphan:
+
+============
+Frame Buffer
+============
+
+.. toctree::
+ :maxdepth: 1
+
+ api
+ arkfb
+ aty128fb
+ cirrusfb
+ cmap_xfbdev
+ deferred_io
+ efifb
+ ep93xx-fb
+ fbcon
+ framebuffer
+ gxfb
+ intel810
+ intelfb
+ internals
+ lxfb
+ matroxfb
+ metronomefb
+ modedb
+ pvr2fb
+ pxafb
+ s3fb
+ sa1100fb
+ sh7760fb
+ sisfb
+ sm501
+ sm712fb
+ sstfb
+ tgafb
+ tridentfb
+ udlfb
+ uvesafb
+ vesafb
+ viafb
+ vt8623fb
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/fb/intel810.txt b/Documentation/fb/intel810.rst
similarity index 83%
rename from Documentation/fb/intel810.txt
rename to Documentation/fb/intel810.rst
index a8e9f5bca6f3..eb86098db91f 100644
--- a/Documentation/fb/intel810.txt
+++ b/Documentation/fb/intel810.rst
@@ -1,26 +1,31 @@
+================================
Intel 810/815 Framebuffer driver
- Tony Daplas <adaplas@pol.net>
- http://i810fb.sourceforge.net
+================================
- March 17, 2002
+Tony Daplas <adaplas@pol.net>
- First Released: July 2001
- Last Update: September 12, 2005
-================================================================
+http://i810fb.sourceforge.net
+
+March 17, 2002
+
+First Released: July 2001
+Last Update: September 12, 2005
A. Introduction
+===============
This is a framebuffer driver for various Intel 810/815 compatible
graphics devices. These include:
- Intel 810
- Intel 810E
- Intel 810-DC100
- Intel 815 Internal graphics only, 100Mhz FSB
- Intel 815 Internal graphics only
- Intel 815 Internal graphics and AGP
+ - Intel 810
+ - Intel 810E
+ - Intel 810-DC100
+ - Intel 815 Internal graphics only, 100Mhz FSB
+ - Intel 815 Internal graphics only
+ - Intel 815 Internal graphics and AGP
B. Features
+============
- Choice of using Discrete Video Timings, VESA Generalized Timing
Formula, or a framebuffer specific database to set the video mode
@@ -45,10 +50,11 @@ B. Features
- Can concurrently run with xfree86 running with native i810 drivers
- Hardware Cursor Support
-
+
- Supports EDID probing either by DDC/I2C or through the BIOS
C. List of available options
+=============================
a. "video=i810fb"
enables the i810 driver
@@ -158,7 +164,7 @@ C. List of available options
(default = not set)
n. "dcolor"
- Use directcolor visual instead of truecolor for pixel depths greater
+ Use directcolor visual instead of truecolor for pixel depths greater
than 8 bpp. Useful for color tuning, such as gamma control.
Recommendation: do not set
@@ -167,35 +173,37 @@ C. List of available options
o. <xres>x<yres>[-<bpp>][@<refresh>]
The driver will now accept specification of boot mode option. If this
is specified, the options 'xres' and 'yres' will be ignored. See
- Documentation/fb/modedb.txt for usage.
+ Documentation/fb/modedb.rst for usage.
D. Kernel booting
+=================
Separate each option/option-pair by commas (,) and the option from its value
-with a colon (:) as in the following:
+with a colon (:) as in the following::
-video=i810fb:option1,option2:value2
+ video=i810fb:option1,option2:value2
Sample Usage
------------
-In /etc/lilo.conf, add the line:
+In /etc/lilo.conf, add the line::
-append="video=i810fb:vram:2,xres:1024,yres:768,bpp:8,hsync1:30,hsync2:55, \
- vsync1:50,vsync2:85,accel,mtrr"
+ append="video=i810fb:vram:2,xres:1024,yres:768,bpp:8,hsync1:30,hsync2:55, \
+ vsync1:50,vsync2:85,accel,mtrr"
This will initialize the framebuffer to 1024x768 at 8bpp. The framebuffer
will use 2 MB of System RAM. MTRR support will be enabled. The refresh rate
will be computed based on the hsync1/hsync2 and vsync1/vsync2 values.
IMPORTANT:
-You must include hsync1, hsync2, vsync1 and vsync2 to enable video modes
-better than 640x480 at 60Hz. HOWEVER, if your chipset/display combination
-supports I2C and has an EDID block, you can safely exclude hsync1, hsync2,
-vsync1 and vsync2 parameters. These parameters will be taken from the EDID
-block.
+ You must include hsync1, hsync2, vsync1 and vsync2 to enable video modes
+ better than 640x480 at 60Hz. HOWEVER, if your chipset/display combination
+ supports I2C and has an EDID block, you can safely exclude hsync1, hsync2,
+ vsync1 and vsync2 parameters. These parameters will be taken from the EDID
+ block.
E. Module options
+==================
The module parameters are essentially similar to the kernel
parameters. The main difference is that you need to include a Boolean value
@@ -206,31 +214,32 @@ Example, to enable MTRR, include "mtrr=1".
Sample Usage
------------
-Using the same setup as described above, load the module like this:
+Using the same setup as described above, load the module like this::
modprobe i810fb vram=2 xres=1024 bpp=8 hsync1=30 hsync2=55 vsync1=50 \
- vsync2=85 accel=1 mtrr=1
+ vsync2=85 accel=1 mtrr=1
-Or just add the following to a configuration file in /etc/modprobe.d/
+Or just add the following to a configuration file in /etc/modprobe.d/::
options i810fb vram=2 xres=1024 bpp=16 hsync1=30 hsync2=55 vsync1=50 \
vsync2=85 accel=1 mtrr=1
-and just do a
+and just do a::
modprobe i810fb
F. Setup
+=========
- a. Do your usual method of configuring the kernel.
+ a. Do your usual method of configuring the kernel
- make menuconfig/xconfig/config
+ make menuconfig/xconfig/config
b. Under "Code maturity level options" enable "Prompt for development
and/or incomplete code/drivers".
- c. Enable agpgart support for the Intel 810/815 on-board graphics.
+ c. Enable agpgart support for the Intel 810/815 on-board graphics.
This is required. The option is under "Character Devices".
d. Under "Graphics Support", select "Intel 810/815" either statically
@@ -242,7 +251,7 @@ F. Setup
set 'Enable DDC Support' to 'y'. To make this option appear, set
'use VESA Generalized Timing Formula' to 'y'.
- f. If you want a framebuffer console, enable it under "Console
+ f. If you want a framebuffer console, enable it under "Console
Drivers".
g. Compile your kernel.
@@ -253,6 +262,7 @@ F. Setup
patch to see the chipset in action (or inaction :-).
G. Acknowledgment:
+===================
1. Geert Uytterhoeven - his excellent howto and the virtual
framebuffer driver code made this possible.
@@ -269,10 +279,9 @@ G. Acknowledgment:
optimizations possible.
H. Home Page:
+==============
A more complete, and probably updated information is provided at
http://i810fb.sourceforge.net.
-###########################
Tony
-
diff --git a/Documentation/fb/intelfb.txt b/Documentation/fb/intelfb.rst
similarity index 73%
rename from Documentation/fb/intelfb.txt
rename to Documentation/fb/intelfb.rst
index feac4e4d6968..e2d0903f4efb 100644
--- a/Documentation/fb/intelfb.txt
+++ b/Documentation/fb/intelfb.rst
@@ -1,24 +1,28 @@
+=============================================================
Intel 830M/845G/852GM/855GM/865G/915G/945G Framebuffer driver
-================================================================
+=============================================================
A. Introduction
- This is a framebuffer driver for various Intel 8xx/9xx compatible
+===============
+
+This is a framebuffer driver for various Intel 8xx/9xx compatible
graphics devices. These would include:
- Intel 830M
- Intel 845G
- Intel 852GM
- Intel 855GM
- Intel 865G
- Intel 915G
- Intel 915GM
- Intel 945G
- Intel 945GM
- Intel 945GME
- Intel 965G
- Intel 965GM
+ - Intel 830M
+ - Intel 845G
+ - Intel 852GM
+ - Intel 855GM
+ - Intel 865G
+ - Intel 915G
+ - Intel 915GM
+ - Intel 945G
+ - Intel 945GM
+ - Intel 945GME
+ - Intel 965G
+ - Intel 965GM
B. List of available options
+=============================
a. "video=intelfb"
enables the intelfb driver
@@ -39,12 +43,12 @@ B. List of available options
(default = 4 MB)
d. "voffset=<value>"
- select at what offset in MB of the logical memory to allocate the
+ select at what offset in MB of the logical memory to allocate the
framebuffer memory. The intent is to avoid the memory blocks
used by standard graphics applications (XFree86). Depending on your
- usage, adjust the value up or down, (0 for maximum usage, 63/127 MB
- for the least amount). Note, an arbitrary setting may conflict
- with XFree86.
+ usage, adjust the value up or down, (0 for maximum usage, 63/127 MB
+ for the least amount). Note, an arbitrary setting may conflict
+ with XFree86.
Recommendation: do not set
(default = 48 MB)
@@ -80,18 +84,19 @@ B. List of available options
The default parameter (not named) is the mode.
C. Kernel booting
+=================
Separate each option/option-pair by commas (,) and the option from its value
-with an equals sign (=) as in the following:
+with an equals sign (=) as in the following::
-video=intelfb:option1,option2=value2
+ video=intelfb:option1,option2=value2
Sample Usage
------------
-In /etc/lilo.conf, add the line:
+In /etc/lilo.conf, add the line::
-append="video=intelfb:mode=800x600-32@75,accel,hwcursor,vram=8"
+ append="video=intelfb:mode=800x600-32@75,accel,hwcursor,vram=8"
This will initialize the framebuffer to 800x600 at 32bpp and 75Hz. The
framebuffer will use 8 MB of System RAM. hw acceleration of text and cursor
@@ -106,8 +111,9 @@ in this directory.
D. Module options
+==================
- The module parameters are essentially similar to the kernel
+The module parameters are essentially similar to the kernel
parameters. The main difference is that you need to include a Boolean value
(1 for TRUE, and 0 for FALSE) for those options which don't need a value.
@@ -116,23 +122,24 @@ Example, to enable MTRR, include "mtrr=1".
Sample Usage
------------
-Using the same setup as described above, load the module like this:
+Using the same setup as described above, load the module like this::
modprobe intelfb mode=800x600-32@75 vram=8 accel=1 hwcursor=1
-Or just add the following to a configuration file in /etc/modprobe.d/
+Or just add the following to a configuration file in /etc/modprobe.d/::
options intelfb mode=800x600-32@75 vram=8 accel=1 hwcursor=1
-and just do a
+and just do a::
modprobe intelfb
E. Acknowledgment:
+===================
1. Geert Uytterhoeven - his excellent howto and the virtual
- framebuffer driver code made this possible.
+ framebuffer driver code made this possible.
2. Jeff Hartmann for his agpgart code.
@@ -145,5 +152,4 @@ E. Acknowledgment:
6. Andrew Morton for his kernel patches maintenance.
-###########################
Sylvain
diff --git a/Documentation/fb/internals.txt b/Documentation/fb/internals.rst
similarity index 82%
rename from Documentation/fb/internals.txt
rename to Documentation/fb/internals.rst
index 9b2a2b2f3e57..696b50aa7c24 100644
--- a/Documentation/fb/internals.txt
+++ b/Documentation/fb/internals.rst
@@ -1,13 +1,19 @@
+=============================
+Frame Buffer device internals
+=============================
This is a first start for some documentation about frame buffer device
internals.
-Geert Uytterhoeven <geert@linux-m68k.org>, 21 July 1998
-James Simmons <jsimmons@user.sf.net>, Nov 26 2002
+Authors:
+
+- Geert Uytterhoeven <geert@linux-m68k.org>, 21 July 1998
+- James Simmons <jsimmons@user.sf.net>, Nov 26 2002
--------------------------------------------------------------------------------
- *** STRUCTURES USED BY THE FRAME BUFFER DEVICE API ***
+Structures used by the frame buffer device API
+==============================================
The following structures play a role in the game of frame buffer devices. They
are defined in <linux/fb.h>.
@@ -40,19 +46,18 @@ are defined in <linux/fb.h>.
Generic information, API and low level information about a specific frame
buffer device instance (slot number, board address, ...).
- - struct `par'
+ - struct `par`
Device dependent information that uniquely defines the video mode for this
particular piece of hardware.
---------------------------------------------------------------------------------
-
- *** VISUALS USED BY THE FRAME BUFFER DEVICE API ***
+Visuals used by the frame buffer device API
+===========================================
Monochrome (FB_VISUAL_MONO01 and FB_VISUAL_MONO10)
--------------------------------------------------
+--------------------------------------------------
Each pixel is either black or white.
@@ -70,7 +75,7 @@ The pixel value is broken up into red, green, and blue fields.
Direct color (FB_VISUAL_DIRECTCOLOR)
------------------------------------
-The pixel value is broken up into red, green, and blue fields, each of which
+The pixel value is broken up into red, green, and blue fields, each of which
are looked up in separate red, green, and blue lookup tables.
@@ -79,4 +84,3 @@ Grayscale displays
Grayscale and static grayscale are special variants of pseudo color and static
pseudo color, where the red, green and blue components are always equal to
each other.
-
diff --git a/Documentation/fb/lxfb.txt b/Documentation/fb/lxfb.rst
similarity index 60%
rename from Documentation/fb/lxfb.txt
rename to Documentation/fb/lxfb.rst
index 38b3ca6f6ca7..863e6b98fbae 100644
--- a/Documentation/fb/lxfb.txt
+++ b/Documentation/fb/lxfb.rst
@@ -1,7 +1,9 @@
-[This file is cloned from VesaFB/aty128fb]
-
+=============
What is lxfb?
-=================
+=============
+
+.. [This file is cloned from VesaFB/aty128fb]
+
This is a graphics framebuffer driver for AMD Geode LX based processors.
@@ -23,9 +25,9 @@ How to use it?
==============
Switching modes is done using lxfb.mode_option=<resolution>... boot
-parameter or using `fbset' program.
+parameter or using `fbset` program.
-See Documentation/fb/modedb.txt for more information on modedb
+See Documentation/fb/modedb.rst for more information on modedb
resolutions.
@@ -42,11 +44,12 @@ You can pass kernel command line options to lxfb with lxfb.<option>.
For example, lxfb.mode_option=800x600@75.
Accepted options:
-mode_option - specify the video mode. Of the form
- <x>x<y>[-<bpp>][@<refresh>]
-vram - size of video ram (normally auto-detected)
-vt_switch - enable vt switching during suspend/resume. The vt
- switch is slow, but harmless.
+================ ==================================================
+mode_option specify the video mode. Of the form
+ <x>x<y>[-<bpp>][@<refresh>]
+vram size of video ram (normally auto-detected)
+vt_switch enable vt switching during suspend/resume. The vt
+ switch is slow, but harmless.
+================ ==================================================
---
Andres Salomon <dilinger@debian.org>
diff --git a/Documentation/fb/matroxfb.rst b/Documentation/fb/matroxfb.rst
new file mode 100644
index 000000000000..f1859d98606e
--- /dev/null
+++ b/Documentation/fb/matroxfb.rst
@@ -0,0 +1,443 @@
+=================
+What is matroxfb?
+=================
+
+.. [This file is cloned from VesaFB. Thanks go to Gerd Knorr]
+
+
+This is a driver for a graphic framebuffer for Matrox devices on
+Alpha, Intel and PPC boxes.
+
+Advantages:
+
+ * It provides a nice large console (128 cols + 48 lines with 1024x768)
+ without using tiny, unreadable fonts.
+ * You can run XF{68,86}_FBDev or XFree86 fbdev driver on top of /dev/fb0
+ * Most important: boot logo :-)
+
+Disadvantages:
+
+ * graphic mode is slower than text mode... but you should not notice
+ if you use same resolution as you used in textmode.
+
+
+How to use it?
+==============
+
+Switching modes is done using the video=matroxfb:vesa:... boot parameter
+or using `fbset` program.
+
+If you want, for example, enable a resolution of 1280x1024x24bpp you should
+pass to the kernel this command line: "video=matroxfb:vesa:0x1BB".
+
+You should compile in both vgacon (to boot if you remove you Matrox from
+box) and matroxfb (for graphics mode). You should not compile-in vesafb
+unless you have primary display on non-Matrox VBE2.0 device (see
+Documentation/fb/vesafb.rst for details).
+
+Currently supported video modes are (through vesa:... interface, PowerMac
+has [as addon] compatibility code):
+
+
+Graphic modes
+-------------
+
+=== ======= ======= ======= ======= =======
+bpp 640x400 640x480 768x576 800x600 960x720
+=== ======= ======= ======= ======= =======
+ 4 0x12 0x102
+ 8 0x100 0x101 0x180 0x103 0x188
+ 15 0x110 0x181 0x113 0x189
+ 16 0x111 0x182 0x114 0x18A
+ 24 0x1B2 0x184 0x1B5 0x18C
+ 32 0x112 0x183 0x115 0x18B
+=== ======= ======= ======= ======= =======
+
+
+Graphic modes (continued)
+-------------------------
+
+=== ======== ======== ========= ========= =========
+bpp 1024x768 1152x864 1280x1024 1408x1056 1600x1200
+=== ======== ======== ========= ========= =========
+ 4 0x104 0x106
+ 8 0x105 0x190 0x107 0x198 0x11C
+ 15 0x116 0x191 0x119 0x199 0x11D
+ 16 0x117 0x192 0x11A 0x19A 0x11E
+ 24 0x1B8 0x194 0x1BB 0x19C 0x1BF
+ 32 0x118 0x193 0x11B 0x19B
+=== ======== ======== ========= ========= =========
+
+
+Text modes
+----------
+
+==== ======= ======= ======== ======== ========
+text 640x400 640x480 1056x344 1056x400 1056x480
+==== ======= ======= ======== ======== ========
+ 8x8 0x1C0 0x108 0x10A 0x10B 0x10C
+8x16 2, 3, 7 0x109
+==== ======= ======= ======== ======== ========
+
+You can enter these number either hexadecimal (leading `0x`) or decimal
+(0x100 = 256). You can also use value + 512 to achieve compatibility
+with your old number passed to vesafb.
+
+Non-listed number can be achieved by more complicated command-line, for
+example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32`.
+
+
+X11
+===
+
+XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel
+architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp
+works fine.
+
+Running another (accelerated) X-Server like XF86_SVGA works too. But (at least)
+XFree servers have big troubles in multihead configurations (even on first
+head, not even talking about second). Running XFree86 4.x accelerated mga
+driver is possible, but you must not enable DRI - if you do, resolution and
+color depth of your X desktop must match resolution and color depths of your
+virtual consoles, otherwise X will corrupt accelerator settings.
+
+
+SVGALib
+=======
+
+Driver contains SVGALib compatibility code. It is turned on by choosing textual
+mode for console. You can do it at boot time by using videomode
+2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0` does this work.
+Unfortunately, after SVGALib application exits, screen contents is corrupted.
+Switching to another console and back fixes it. I hope that it is SVGALib's
+problem and not mine, but I'm not sure.
+
+
+Configuration
+=============
+
+You can pass kernel command line options to matroxfb with
+`video=matroxfb:option1,option2:value2,option3` (multiple options should be
+separated by comma, values are separated from options by `:`).
+Accepted options:
+
+============ ===================================================================
+mem:X size of memory (X can be in megabytes, kilobytes or bytes)
+ You can only decrease value determined by driver because of
+ it always probe for memory. Default is to use whole detected
+ memory usable for on-screen display (i.e. max. 8 MB).
+disabled do not load driver; you can use also `off`, but `disabled`
+ is here too.
+enabled load driver, if you have `video=matroxfb:disabled` in LILO
+ configuration, you can override it by this (you cannot override
+ `off`). It is default.
+noaccel do not use acceleration engine. It does not work on Alphas.
+accel use acceleration engine. It is default.
+nopan create initial consoles with vyres = yres, thus disabling virtual
+ scrolling.
+pan create initial consoles as tall as possible (vyres = memory/vxres).
+ It is default.
+nopciretry disable PCI retries. It is needed for some broken chipsets,
+ it is autodetected for intel's 82437. In this case device does
+ not comply to PCI 2.1 specs (it will not guarantee that every
+ transaction terminate with success or retry in 32 PCLK).
+pciretry enable PCI retries. It is default, except for intel's 82437.
+novga disables VGA I/O ports. It is default if BIOS did not enable
+ device. You should not use this option, some boards then do not
+ restart without power off.
+vga preserve state of VGA I/O ports. It is default. Driver does not
+ enable VGA I/O if BIOS did not it (it is not safe to enable it in
+ most cases).
+nobios disables BIOS ROM. It is default if BIOS did not enable BIOS
+ itself. You should not use this option, some boards then do not
+ restart without power off.
+bios preserve state of BIOS ROM. It is default. Driver does not enable
+ BIOS if BIOS was not enabled before.
+noinit tells driver, that devices were already initialized. You should use
+ it if you have G100 and/or if driver cannot detect memory, you see
+ strange pattern on screen and so on. Devices not enabled by BIOS
+ are still initialized. It is default.
+init driver initializes every device it knows about.
+memtype specifies memory type, implies 'init'. This is valid only for G200
+ and G400 and has following meaning:
+
+ G200:
+ - 0 -> 2x128Kx32 chips, 2MB onboard, probably sgram
+ - 1 -> 2x128Kx32 chips, 4MB onboard, probably sgram
+ - 2 -> 2x256Kx32 chips, 4MB onboard, probably sgram
+ - 3 -> 2x256Kx32 chips, 8MB onboard, probably sgram
+ - 4 -> 2x512Kx16 chips, 8/16MB onboard, probably sdram only
+ - 5 -> same as above
+ - 6 -> 4x128Kx32 chips, 4MB onboard, probably sgram
+ - 7 -> 4x128Kx32 chips, 8MB onboard, probably sgram
+ G400:
+ - 0 -> 2x512Kx16 SDRAM, 16/32MB
+ - 2x512Kx32 SGRAM, 16/32MB
+ - 1 -> 2x256Kx32 SGRAM, 8/16MB
+ - 2 -> 4x128Kx32 SGRAM, 8/16MB
+ - 3 -> 4x512Kx32 SDRAM, 32MB
+ - 4 -> 4x256Kx32 SGRAM, 16/32MB
+ - 5 -> 2x1Mx32 SDRAM, 32MB
+ - 6 -> reserved
+ - 7 -> reserved
+
+ You should use sdram or sgram parameter in addition to memtype
+ parameter.
+nomtrr disables write combining on frame buffer. This slows down driver
+ but there is reported minor incompatibility between GUS DMA and
+ XFree under high loads if write combining is enabled (sound
+ dropouts).
+mtrr enables write combining on frame buffer. It speeds up video
+ accesses much. It is default. You must have MTRR support enabled
+ in kernel and your CPU must have MTRR (f.e. Pentium II have them).
+sgram tells to driver that you have Gxx0 with SGRAM memory. It has no
+ effect without `init`.
+sdram tells to driver that you have Gxx0 with SDRAM memory.
+ It is a default.
+inv24 change timings parameters for 24bpp modes on Millennium and
+ Millennium II. Specify this if you see strange color shadows
+ around characters.
+noinv24 use standard timings. It is the default.
+inverse invert colors on screen (for LCD displays)
+noinverse show true colors on screen. It is default.
+dev:X bind driver to device X. Driver numbers device from 0 up to N,
+ where device 0 is first `known` device found, 1 second and so on.
+ lspci lists devices in this order.
+ Default is `every` known device.
+nohwcursor disables hardware cursor (use software cursor instead).
+hwcursor enables hardware cursor. It is default. If you are using
+ non-accelerated mode (`noaccel` or `fbset -accel false`), software
+ cursor is used (except for text mode).
+noblink disables cursor blinking. Cursor in text mode always blinks (hw
+ limitation).
+blink enables cursor blinking. It is default.
+nofastfont disables fastfont feature. It is default.
+fastfont:X enables fastfont feature. X specifies size of memory reserved for
+ font data, it must be >= (fontwidth*fontheight*chars_in_font)/8.
+ It is faster on Gx00 series, but slower on older cards.
+grayscale enable grayscale summing. It works in PSEUDOCOLOR modes (text,
+ 4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters
+ displayed through putc/putcs. Direct accesses to framebuffer
+ can paint colors.
+nograyscale disable grayscale summing. It is default.
+cross4MB enables that pixel line can cross 4MB boundary. It is default for
+ non-Millennium.
+nocross4MB pixel line must not cross 4MB boundary. It is default for
+ Millennium I or II, because of these devices have hardware
+ limitations which do not allow this. But this option is
+ incompatible with some (if not all yet released) versions of
+ XF86_FBDev.
+dfp enables digital flat panel interface. This option is incompatible
+ with secondary (TV) output - if DFP is active, TV output must be
+ inactive and vice versa. DFP always uses same timing as primary
+ (monitor) output.
+dfp:X use settings X for digital flat panel interface. X is number from
+ 0 to 0xFF, and meaning of each individual bit is described in
+ G400 manual, in description of DAC register 0x1F. For normal
+ operation you should set all bits to zero, except lowest bit. This
+ lowest bit selects who is source of display clocks, whether G400,
+ or panel. Default value is now read back from hardware - so you
+ should specify this value only if you are also using `init`
+ parameter.
+outputs:XYZ set mapping between CRTC and outputs. Each letter can have value
+ of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter
+ corresponds to primary analog output, second letter to the
+ secondary analog output and third letter to the DVI output.
+ Default setting is 100 for cards below G400 or G400 without DFP,
+ 101 for G400 with DFP, and 111 for G450 and G550. You can set
+ mapping only on first card, use matroxset for setting up other
+ devices.
+vesa:X selects startup videomode. X is number from 0 to 0x1FF, see table
+ above for detailed explanation. Default is 640x480x8bpp if driver
+ has 8bpp support. Otherwise first available of 640x350x4bpp,
+ 640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
+ (80x25 text is always available).
+============ ===================================================================
+
+If you are not satisfied with videomode selected by `vesa` option, you
+can modify it with these options:
+
+============ ===================================================================
+xres:X horizontal resolution, in pixels. Default is derived from `vesa`
+ option.
+yres:X vertical resolution, in pixel lines. Default is derived from `vesa`
+ option.
+upper:X top boundary: lines between end of VSYNC pulse and start of first
+ pixel line of picture. Default is derived from `vesa` option.
+lower:X bottom boundary: lines between end of picture and start of VSYNC
+ pulse. Default is derived from `vesa` option.
+vslen:X length of VSYNC pulse, in lines. Default is derived from `vesa`
+ option.
+left:X left boundary: pixels between end of HSYNC pulse and first pixel.
+ Default is derived from `vesa` option.
+right:X right boundary: pixels between end of picture and start of HSYNC
+ pulse. Default is derived from `vesa` option.
+hslen:X length of HSYNC pulse, in pixels. Default is derived from `vesa`
+ option.
+pixclock:X dotclocks, in ps (picoseconds). Default is derived from `vesa`
+ option and from `fh` and `fv` options.
+sync:X sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
+ If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
+ generated. If bit 5 (value 0x20) is set, sync on green is turned
+ on. Do not forget that if you want sync on green, you also probably
+ want composite sync.
+ Default depends on `vesa`.
+depth:X Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
+ `vesa`.
+============ ===================================================================
+
+If you know capabilities of your monitor, you can specify some (or all) of
+`maxclk`, `fh` and `fv`. In this case, `pixclock` is computed so that
+pixclock <= maxclk, real_fh <= fh and real_fv <= fv.
+
+============ ==================================================================
+maxclk:X maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
+ `don`t care`.
+fh:X maximum horizontal synchronization frequency. X can be specified
+ in kHz or Hz. Default is `don't care`.
+fv:X maximum vertical frequency. X must be specified in Hz. Default is
+ 70 for modes derived from `vesa` with yres <= 400, 60Hz for
+ yres > 400.
+============ ==================================================================
+
+
+Limitations
+===========
+
+There are known and unknown bugs, features and misfeatures.
+Currently there are following known bugs:
+
+ - SVGALib does not restore screen on exit
+ - generic fbcon-cfbX procedures do not work on Alphas. Due to this,
+ `noaccel` (and cfb4 accel) driver does not work on Alpha. So everyone
+ with access to `/dev/fb*` on Alpha can hang machine (you should restrict
+ access to `/dev/fb*` - everyone with access to this device can destroy
+ your monitor, believe me...).
+ - 24bpp does not support correctly XF-FBDev on big-endian architectures.
+ - interlaced text mode is not supported; it looks like hardware limitation,
+ but I'm not sure.
+ - Gxx0 SGRAM/SDRAM is not autodetected.
+ - If you are using more than one framebuffer device, you must boot kernel
+ with 'video=scrollback:0'.
+ - maybe more...
+
+And following misfeatures:
+
+ - SVGALib does not restore screen on exit.
+ - pixclock for text modes is limited by hardware to
+
+ - 83 MHz on G200
+ - 66 MHz on Millennium I
+ - 60 MHz on Millennium II
+
+ Because I have no access to other devices, I do not know specific
+ frequencies for them. So driver does not check this and allows you to
+ set frequency higher that this. It causes sparks, black holes and other
+ pretty effects on screen. Device was not destroyed during tests. :-)
+ - my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
+ (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
+ But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
+ them (maybe that chip overheats, but it has a very big cooler (G100 has
+ none), so it should work).
+ - special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
+ G16V16 are not supported
+ - color keying is not supported
+ - feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
+ by BIOS)
+ - DDC (monitor detection) is supported through dualhead driver
+ - some check for input values are not so strict how it should be (you can
+ specify vslen=4000 and so on).
+ - maybe more...
+
+And following features:
+
+ - 4bpp is available only on Millennium I and Millennium II. It is hardware
+ limitation.
+ - selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
+ option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
+ else selects 5:6:5 mode.
+ - text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
+ instead of one of 16M colors). It is due to hardware limitation of
+ Millennium I/II and SVGALib compatibility.
+
+
+Benchmarks
+==========
+It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
+time for draw 6144000 characters on screen through /dev/vcsa
+(for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
+16 seconds, i.e. 187 MBps).
+Times were obtained from one older version of driver, now they are about 3%
+faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
+PCI slot, G200 in AGP 2x slot. I did not test vgacon::
+
+ NOACCEL
+ 8x16 12x22
+ Millennium I G200 Millennium I G200
+ 8bpp 16.42 9.54 12.33 9.13
+ 16bpp 21.00 15.70 19.11 15.02
+ 24bpp 36.66 36.66 35.00 35.00
+ 32bpp 35.00 30.00 33.85 28.66
+
+ ACCEL, nofastfont
+ 8x16 12x22 6x11
+ Millennium I G200 Millennium I G200 Millennium I G200
+ 8bpp 7.79 7.24 13.55 7.78 30.00 21.01
+ 16bpp 9.13 7.78 16.16 7.78 30.00 21.01
+ 24bpp 14.17 10.72 18.69 10.24 34.99 21.01
+ 32bpp 16.15 16.16 18.73 13.09 34.99 21.01
+
+ ACCEL, fastfont
+ 8x16 12x22 6x11
+ Millennium I G200 Millennium I G200 Millennium I G200
+ 8bpp 8.41 6.01 6.54 4.37 16.00 10.51
+ 16bpp 9.54 9.12 8.76 6.17 17.52 14.01
+ 24bpp 15.00 12.36 11.67 10.00 22.01 18.32
+ 32bpp 16.18 18.29* 12.71 12.74 24.44 21.00
+
+ TEXT
+ 8x16
+ Millennium I G200
+ TEXT 3.29 1.50
+
+ * Yes, it is slower than Millennium I.
+
+
+Dualhead G400
+=============
+Driver supports dualhead G400 with some limitations:
+ + secondary head shares videomemory with primary head. It is not problem
+ if you have 32MB of videoram, but if you have only 16MB, you may have
+ to think twice before choosing videomode (for example twice 1880x1440x32bpp
+ is not possible).
+ + due to hardware limitation, secondary head can use only 16 and 32bpp
+ videomodes.
+ + secondary head is not accelerated. There were bad problems with accelerated
+ XFree when secondary head used to use acceleration.
+ + secondary head always powerups in 640x480@60-32 videomode. You have to use
+ fbset to change this mode.
+ + secondary head always powerups in monitor mode. You have to use fbmatroxset
+ to change it to TV mode. Also, you must select at least 525 lines for
+ NTSC output and 625 lines for PAL output.
+ + kernel is not fully multihead ready. So some things are impossible to do.
+ + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
+ and matroxfb_crtc2 into kernel.
+
+
+Dualhead G450
+=============
+Driver supports dualhead G450 with some limitations:
+ + secondary head shares videomemory with primary head. It is not problem
+ if you have 32MB of videoram, but if you have only 16MB, you may have
+ to think twice before choosing videomode.
+ + due to hardware limitation, secondary head can use only 16 and 32bpp
+ videomodes.
+ + secondary head is not accelerated.
+ + secondary head always powerups in 640x480@60-32 videomode. You have to use
+ fbset to change this mode.
+ + TV output is not supported
+ + kernel is not fully multihead ready, so some things are impossible to do.
+ + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
+ into kernel.
+
+Petr Vandrovec <vandrove@vc.cvut.cz>
diff --git a/Documentation/fb/matroxfb.txt b/Documentation/fb/matroxfb.txt
deleted file mode 100644
index b95f5bb522f2..000000000000
--- a/Documentation/fb/matroxfb.txt
+++ /dev/null
@@ -1,413 +0,0 @@
-[This file is cloned from VesaFB. Thanks go to Gerd Knorr]
-
-What is matroxfb?
-=================
-
-This is a driver for a graphic framebuffer for Matrox devices on
-Alpha, Intel and PPC boxes.
-
-Advantages:
-
- * It provides a nice large console (128 cols + 48 lines with 1024x768)
- without using tiny, unreadable fonts.
- * You can run XF{68,86}_FBDev or XFree86 fbdev driver on top of /dev/fb0
- * Most important: boot logo :-)
-
-Disadvantages:
-
- * graphic mode is slower than text mode... but you should not notice
- if you use same resolution as you used in textmode.
-
-
-How to use it?
-==============
-
-Switching modes is done using the video=matroxfb:vesa:... boot parameter
-or using `fbset' program.
-
-If you want, for example, enable a resolution of 1280x1024x24bpp you should
-pass to the kernel this command line: "video=matroxfb:vesa:0x1BB".
-
-You should compile in both vgacon (to boot if you remove you Matrox from
-box) and matroxfb (for graphics mode). You should not compile-in vesafb
-unless you have primary display on non-Matrox VBE2.0 device (see
-Documentation/fb/vesafb.txt for details).
-
-Currently supported video modes are (through vesa:... interface, PowerMac
-has [as addon] compatibility code):
-
-
-[Graphic modes]
-
-bpp | 640x400 640x480 768x576 800x600 960x720
-----+--------------------------------------------
- 4 | 0x12 0x102
- 8 | 0x100 0x101 0x180 0x103 0x188
- 15 | 0x110 0x181 0x113 0x189
- 16 | 0x111 0x182 0x114 0x18A
- 24 | 0x1B2 0x184 0x1B5 0x18C
- 32 | 0x112 0x183 0x115 0x18B
-
-
-[Graphic modes (continued)]
-
-bpp | 1024x768 1152x864 1280x1024 1408x1056 1600x1200
-----+------------------------------------------------
- 4 | 0x104 0x106
- 8 | 0x105 0x190 0x107 0x198 0x11C
- 15 | 0x116 0x191 0x119 0x199 0x11D
- 16 | 0x117 0x192 0x11A 0x19A 0x11E
- 24 | 0x1B8 0x194 0x1BB 0x19C 0x1BF
- 32 | 0x118 0x193 0x11B 0x19B
-
-
-[Text modes]
-
-text | 640x400 640x480 1056x344 1056x400 1056x480
------+------------------------------------------------
- 8x8 | 0x1C0 0x108 0x10A 0x10B 0x10C
-8x16 | 2, 3, 7 0x109
-
-You can enter these number either hexadecimal (leading `0x') or decimal
-(0x100 = 256). You can also use value + 512 to achieve compatibility
-with your old number passed to vesafb.
-
-Non-listed number can be achieved by more complicated command-line, for
-example 1600x1200x32bpp can be specified by `video=matroxfb:vesa:0x11C,depth:32'.
-
-
-X11
-===
-
-XF{68,86}_FBDev should work just fine, but it is non-accelerated. On non-intel
-architectures there are some glitches for 24bpp videomodes. 8, 16 and 32bpp
-works fine.
-
-Running another (accelerated) X-Server like XF86_SVGA works too. But (at least)
-XFree servers have big troubles in multihead configurations (even on first
-head, not even talking about second). Running XFree86 4.x accelerated mga
-driver is possible, but you must not enable DRI - if you do, resolution and
-color depth of your X desktop must match resolution and color depths of your
-virtual consoles, otherwise X will corrupt accelerator settings.
-
-
-SVGALib
-=======
-
-Driver contains SVGALib compatibility code. It is turned on by choosing textual
-mode for console. You can do it at boot time by using videomode
-2,3,7,0x108-0x10C or 0x1C0. At runtime, `fbset -depth 0' does this work.
-Unfortunately, after SVGALib application exits, screen contents is corrupted.
-Switching to another console and back fixes it. I hope that it is SVGALib's
-problem and not mine, but I'm not sure.
-
-
-Configuration
-=============
-
-You can pass kernel command line options to matroxfb with
-`video=matroxfb:option1,option2:value2,option3' (multiple options should be
-separated by comma, values are separated from options by `:').
-Accepted options:
-
-mem:X - size of memory (X can be in megabytes, kilobytes or bytes)
- You can only decrease value determined by driver because of
- it always probe for memory. Default is to use whole detected
- memory usable for on-screen display (i.e. max. 8 MB).
-disabled - do not load driver; you can use also `off', but `disabled'
- is here too.
-enabled - load driver, if you have `video=matroxfb:disabled' in LILO
- configuration, you can override it by this (you cannot override
- `off'). It is default.
-noaccel - do not use acceleration engine. It does not work on Alphas.
-accel - use acceleration engine. It is default.
-nopan - create initial consoles with vyres = yres, thus disabling virtual
- scrolling.
-pan - create initial consoles as tall as possible (vyres = memory/vxres).
- It is default.
-nopciretry - disable PCI retries. It is needed for some broken chipsets,
- it is autodetected for intel's 82437. In this case device does
- not comply to PCI 2.1 specs (it will not guarantee that every
- transaction terminate with success or retry in 32 PCLK).
-pciretry - enable PCI retries. It is default, except for intel's 82437.
-novga - disables VGA I/O ports. It is default if BIOS did not enable device.
- You should not use this option, some boards then do not restart
- without power off.
-vga - preserve state of VGA I/O ports. It is default. Driver does not
- enable VGA I/O if BIOS did not it (it is not safe to enable it in
- most cases).
-nobios - disables BIOS ROM. It is default if BIOS did not enable BIOS itself.
- You should not use this option, some boards then do not restart
- without power off.
-bios - preserve state of BIOS ROM. It is default. Driver does not enable
- BIOS if BIOS was not enabled before.
-noinit - tells driver, that devices were already initialized. You should use
- it if you have G100 and/or if driver cannot detect memory, you see
- strange pattern on screen and so on. Devices not enabled by BIOS
- are still initialized. It is default.
-init - driver initializes every device it knows about.
-memtype - specifies memory type, implies 'init'. This is valid only for G200
- and G400 and has following meaning:
- G200: 0 -> 2x128Kx32 chips, 2MB onboard, probably sgram
- 1 -> 2x128Kx32 chips, 4MB onboard, probably sgram
- 2 -> 2x256Kx32 chips, 4MB onboard, probably sgram
- 3 -> 2x256Kx32 chips, 8MB onboard, probably sgram
- 4 -> 2x512Kx16 chips, 8/16MB onboard, probably sdram only
- 5 -> same as above
- 6 -> 4x128Kx32 chips, 4MB onboard, probably sgram
- 7 -> 4x128Kx32 chips, 8MB onboard, probably sgram
- G400: 0 -> 2x512Kx16 SDRAM, 16/32MB
- 2x512Kx32 SGRAM, 16/32MB
- 1 -> 2x256Kx32 SGRAM, 8/16MB
- 2 -> 4x128Kx32 SGRAM, 8/16MB
- 3 -> 4x512Kx32 SDRAM, 32MB
- 4 -> 4x256Kx32 SGRAM, 16/32MB
- 5 -> 2x1Mx32 SDRAM, 32MB
- 6 -> reserved
- 7 -> reserved
- You should use sdram or sgram parameter in addition to memtype
- parameter.
-nomtrr - disables write combining on frame buffer. This slows down driver but
- there is reported minor incompatibility between GUS DMA and XFree
- under high loads if write combining is enabled (sound dropouts).
-mtrr - enables write combining on frame buffer. It speeds up video accesses
- much. It is default. You must have MTRR support enabled in kernel
- and your CPU must have MTRR (f.e. Pentium II have them).
-sgram - tells to driver that you have Gxx0 with SGRAM memory. It has no
- effect without `init'.
-sdram - tells to driver that you have Gxx0 with SDRAM memory.
- It is a default.
-inv24 - change timings parameters for 24bpp modes on Millennium and
- Millennium II. Specify this if you see strange color shadows around
- characters.
-noinv24 - use standard timings. It is the default.
-inverse - invert colors on screen (for LCD displays)
-noinverse - show true colors on screen. It is default.
-dev:X - bind driver to device X. Driver numbers device from 0 up to N,
- where device 0 is first `known' device found, 1 second and so on.
- lspci lists devices in this order.
- Default is `every' known device.
-nohwcursor - disables hardware cursor (use software cursor instead).
-hwcursor - enables hardware cursor. It is default. If you are using
- non-accelerated mode (`noaccel' or `fbset -accel false'), software
- cursor is used (except for text mode).
-noblink - disables cursor blinking. Cursor in text mode always blinks (hw
- limitation).
-blink - enables cursor blinking. It is default.
-nofastfont - disables fastfont feature. It is default.
-fastfont:X - enables fastfont feature. X specifies size of memory reserved for
- font data, it must be >= (fontwidth*fontheight*chars_in_font)/8.
- It is faster on Gx00 series, but slower on older cards.
-grayscale - enable grayscale summing. It works in PSEUDOCOLOR modes (text,
- 4bpp, 8bpp). In DIRECTCOLOR modes it is limited to characters
- displayed through putc/putcs. Direct accesses to framebuffer
- can paint colors.
-nograyscale - disable grayscale summing. It is default.
-cross4MB - enables that pixel line can cross 4MB boundary. It is default for
- non-Millennium.
-nocross4MB - pixel line must not cross 4MB boundary. It is default for
- Millennium I or II, because of these devices have hardware
- limitations which do not allow this. But this option is
- incompatible with some (if not all yet released) versions of
- XF86_FBDev.
-dfp - enables digital flat panel interface. This option is incompatible with
- secondary (TV) output - if DFP is active, TV output must be
- inactive and vice versa. DFP always uses same timing as primary
- (monitor) output.
-dfp:X - use settings X for digital flat panel interface. X is number from
- 0 to 0xFF, and meaning of each individual bit is described in
- G400 manual, in description of DAC register 0x1F. For normal operation
- you should set all bits to zero, except lowest bit. This lowest bit
- selects who is source of display clocks, whether G400, or panel.
- Default value is now read back from hardware - so you should specify
- this value only if you are also using `init' parameter.
-outputs:XYZ - set mapping between CRTC and outputs. Each letter can have value
- of 0 (for no CRTC), 1 (CRTC1) or 2 (CRTC2), and first letter corresponds
- to primary analog output, second letter to the secondary analog output
- and third letter to the DVI output. Default setting is 100 for
- cards below G400 or G400 without DFP, 101 for G400 with DFP, and
- 111 for G450 and G550. You can set mapping only on first card,
- use matroxset for setting up other devices.
-vesa:X - selects startup videomode. X is number from 0 to 0x1FF, see table
- above for detailed explanation. Default is 640x480x8bpp if driver
- has 8bpp support. Otherwise first available of 640x350x4bpp,
- 640x480x15bpp, 640x480x24bpp, 640x480x32bpp or 80x25 text
- (80x25 text is always available).
-
-If you are not satisfied with videomode selected by `vesa' option, you
-can modify it with these options:
-
-xres:X - horizontal resolution, in pixels. Default is derived from `vesa'
- option.
-yres:X - vertical resolution, in pixel lines. Default is derived from `vesa'
- option.
-upper:X - top boundary: lines between end of VSYNC pulse and start of first
- pixel line of picture. Default is derived from `vesa' option.
-lower:X - bottom boundary: lines between end of picture and start of VSYNC
- pulse. Default is derived from `vesa' option.
-vslen:X - length of VSYNC pulse, in lines. Default is derived from `vesa'
- option.
-left:X - left boundary: pixels between end of HSYNC pulse and first pixel.
- Default is derived from `vesa' option.
-right:X - right boundary: pixels between end of picture and start of HSYNC
- pulse. Default is derived from `vesa' option.
-hslen:X - length of HSYNC pulse, in pixels. Default is derived from `vesa'
- option.
-pixclock:X - dotclocks, in ps (picoseconds). Default is derived from `vesa'
- option and from `fh' and `fv' options.
-sync:X - sync. pulse - bit 0 inverts HSYNC polarity, bit 1 VSYNC polarity.
- If bit 3 (value 0x08) is set, composite sync instead of HSYNC is
- generated. If bit 5 (value 0x20) is set, sync on green is turned on.
- Do not forget that if you want sync on green, you also probably
- want composite sync.
- Default depends on `vesa'.
-depth:X - Bits per pixel: 0=text, 4,8,15,16,24 or 32. Default depends on
- `vesa'.
-
-If you know capabilities of your monitor, you can specify some (or all) of
-`maxclk', `fh' and `fv'. In this case, `pixclock' is computed so that
-pixclock <= maxclk, real_fh <= fh and real_fv <= fv.
-
-maxclk:X - maximum dotclock. X can be specified in MHz, kHz or Hz. Default is
- `don't care'.
-fh:X - maximum horizontal synchronization frequency. X can be specified
- in kHz or Hz. Default is `don't care'.
-fv:X - maximum vertical frequency. X must be specified in Hz. Default is
- 70 for modes derived from `vesa' with yres <= 400, 60Hz for
- yres > 400.
-
-
-Limitations
-===========
-
-There are known and unknown bugs, features and misfeatures.
-Currently there are following known bugs:
- + SVGALib does not restore screen on exit
- + generic fbcon-cfbX procedures do not work on Alphas. Due to this,
- `noaccel' (and cfb4 accel) driver does not work on Alpha. So everyone
- with access to /dev/fb* on Alpha can hang machine (you should restrict
- access to /dev/fb* - everyone with access to this device can destroy
- your monitor, believe me...).
- + 24bpp does not support correctly XF-FBDev on big-endian architectures.
- + interlaced text mode is not supported; it looks like hardware limitation,
- but I'm not sure.
- + Gxx0 SGRAM/SDRAM is not autodetected.
- + If you are using more than one framebuffer device, you must boot kernel
- with 'video=scrollback:0'.
- + maybe more...
-And following misfeatures:
- + SVGALib does not restore screen on exit.
- + pixclock for text modes is limited by hardware to
- 83 MHz on G200
- 66 MHz on Millennium I
- 60 MHz on Millennium II
- Because I have no access to other devices, I do not know specific
- frequencies for them. So driver does not check this and allows you to
- set frequency higher that this. It causes sparks, black holes and other
- pretty effects on screen. Device was not destroyed during tests. :-)
- + my Millennium G200 oscillator has frequency range from 35 MHz to 380 MHz
- (and it works with 8bpp on about 320 MHz dotclocks (and changed mclk)).
- But Matrox says on product sheet that VCO limit is 50-250 MHz, so I believe
- them (maybe that chip overheats, but it has a very big cooler (G100 has
- none), so it should work).
- + special mixed video/graphics videomodes of Mystique and Gx00 - 2G8V16 and
- G16V16 are not supported
- + color keying is not supported
- + feature connector of Mystique and Gx00 is set to VGA mode (it is disabled
- by BIOS)
- + DDC (monitor detection) is supported through dualhead driver
- + some check for input values are not so strict how it should be (you can
- specify vslen=4000 and so on).
- + maybe more...
-And following features:
- + 4bpp is available only on Millennium I and Millennium II. It is hardware
- limitation.
- + selection between 1:5:5:5 and 5:6:5 16bpp videomode is done by -rgba
- option of fbset: "fbset -depth 16 -rgba 5,5,5" selects 1:5:5:5, anything
- else selects 5:6:5 mode.
- + text mode uses 6 bit VGA palette instead of 8 bit (one of 262144 colors
- instead of one of 16M colors). It is due to hardware limitation of
- Millennium I/II and SVGALib compatibility.
-
-
-Benchmarks
-==========
-It is time to redraw whole screen 1000 times in 1024x768, 60Hz. It is
-time for draw 6144000 characters on screen through /dev/vcsa
-(for 32bpp it is about 3GB of data (exactly 3000 MB); for 8x16 font in
-16 seconds, i.e. 187 MBps).
-Times were obtained from one older version of driver, now they are about 3%
-faster, it is kernel-space only time on P-II/350 MHz, Millennium I in 33 MHz
-PCI slot, G200 in AGP 2x slot. I did not test vgacon.
-
-NOACCEL
- 8x16 12x22
- Millennium I G200 Millennium I G200
-8bpp 16.42 9.54 12.33 9.13
-16bpp 21.00 15.70 19.11 15.02
-24bpp 36.66 36.66 35.00 35.00
-32bpp 35.00 30.00 33.85 28.66
-
-ACCEL, nofastfont
- 8x16 12x22 6x11
- Millennium I G200 Millennium I G200 Millennium I G200
-8bpp 7.79 7.24 13.55 7.78 30.00 21.01
-16bpp 9.13 7.78 16.16 7.78 30.00 21.01
-24bpp 14.17 10.72 18.69 10.24 34.99 21.01
-32bpp 16.15 16.16 18.73 13.09 34.99 21.01
-
-ACCEL, fastfont
- 8x16 12x22 6x11
- Millennium I G200 Millennium I G200 Millennium I G200
-8bpp 8.41 6.01 6.54 4.37 16.00 10.51
-16bpp 9.54 9.12 8.76 6.17 17.52 14.01
-24bpp 15.00 12.36 11.67 10.00 22.01 18.32
-32bpp 16.18 18.29* 12.71 12.74 24.44 21.00
-
-TEXT
- 8x16
- Millennium I G200
-TEXT 3.29 1.50
-
-* Yes, it is slower than Millennium I.
-
-
-Dualhead G400
-=============
-Driver supports dualhead G400 with some limitations:
- + secondary head shares videomemory with primary head. It is not problem
- if you have 32MB of videoram, but if you have only 16MB, you may have
- to think twice before choosing videomode (for example twice 1880x1440x32bpp
- is not possible).
- + due to hardware limitation, secondary head can use only 16 and 32bpp
- videomodes.
- + secondary head is not accelerated. There were bad problems with accelerated
- XFree when secondary head used to use acceleration.
- + secondary head always powerups in 640x480@60-32 videomode. You have to use
- fbset to change this mode.
- + secondary head always powerups in monitor mode. You have to use fbmatroxset
- to change it to TV mode. Also, you must select at least 525 lines for
- NTSC output and 625 lines for PAL output.
- + kernel is not fully multihead ready. So some things are impossible to do.
- + if you compiled it as module, you must insert i2c-matroxfb, matroxfb_maven
- and matroxfb_crtc2 into kernel.
-
-
-Dualhead G450
-=============
-Driver supports dualhead G450 with some limitations:
- + secondary head shares videomemory with primary head. It is not problem
- if you have 32MB of videoram, but if you have only 16MB, you may have
- to think twice before choosing videomode.
- + due to hardware limitation, secondary head can use only 16 and 32bpp
- videomodes.
- + secondary head is not accelerated.
- + secondary head always powerups in 640x480@60-32 videomode. You have to use
- fbset to change this mode.
- + TV output is not supported
- + kernel is not fully multihead ready, so some things are impossible to do.
- + if you compiled it as module, you must insert matroxfb_g450 and matroxfb_crtc2
- into kernel.
-
---
-Petr Vandrovec <vandrove@vc.cvut.cz>
diff --git a/Documentation/fb/metronomefb.txt b/Documentation/fb/metronomefb.rst
similarity index 98%
rename from Documentation/fb/metronomefb.txt
rename to Documentation/fb/metronomefb.rst
index 237ca412582d..63e1d31a7e54 100644
--- a/Documentation/fb/metronomefb.txt
+++ b/Documentation/fb/metronomefb.rst
@@ -1,6 +1,9 @@
- Metronomefb
- -----------
+===========
+Metronomefb
+===========
+
Maintained by Jaya Kumar <jayakumar.lkml.gmail.com>
+
Last revised: Mar 10, 2008
Metronomefb is a driver for the Metronome display controller. The controller
@@ -33,4 +36,3 @@ the physical media.
Metronomefb uses the deferred IO interface so that it can provide a memory
mappable frame buffer. It has been tested with tinyx (Xfbdev). It is known
to work at this time with xeyes, xclock, xloadimage, xpdf.
-
diff --git a/Documentation/fb/modedb.txt b/Documentation/fb/modedb.rst
similarity index 87%
rename from Documentation/fb/modedb.txt
rename to Documentation/fb/modedb.rst
index 16aa08453911..3c2397293977 100644
--- a/Documentation/fb/modedb.txt
+++ b/Documentation/fb/modedb.rst
@@ -1,6 +1,6 @@
-
-
- modedb default video mode support
+=================================
+modedb default video mode support
+=================================
Currently all frame buffer device drivers have their own video mode databases,
@@ -18,7 +18,7 @@ When a frame buffer device receives a video= option it doesn't know, it should
consider that to be a video mode option. If no frame buffer device is specified
in a video= option, fbmem considers that to be a global video mode option.
-Valid mode specifiers (mode_option argument):
+Valid mode specifiers (mode_option argument)::
<xres>x<yres>[M][R][-<bpp>][@<refresh>][i][m][eDd]
<name>[-<bpp>][@<refresh>]
@@ -45,15 +45,18 @@ signals (e.g. HDMI and DVI-I). For other outputs it behaves like 'e'. If 'd'
is specified the output is disabled.
You can additionally specify which output the options matches to.
-To force the VGA output to be enabled and drive a specific mode say:
+To force the VGA output to be enabled and drive a specific mode say::
+
video=VGA-1:1280x1024@60me
-Specifying the option multiple times for different ports is possible, e.g.:
+Specifying the option multiple times for different ports is possible, e.g.::
+
video=LVDS-1:d video=HDMI-1:D
-***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo *****
+-----------------------------------------------------------------------------
What is the VESA(TM) Coordinated Video Timings (CVT)?
+=====================================================
From the VESA(TM) Website:
@@ -90,14 +93,14 @@ determined from its EDID. The version 1.3 of the EDID has extra 128-byte
blocks where additional timing information is placed. As of this time, there
is no support yet in the layer to parse this additional blocks.)
-CVT also introduced a new naming convention (should be seen from dmesg output):
+CVT also introduced a new naming convention (should be seen from dmesg output)::
<pix>M<a>[-R]
where: pix = total amount of pixels in MB (xres x yres)
- M = always present
- a = aspect ratio (3 - 4:3; 4 - 5:4; 9 - 15:9, 16:9; A - 16:10)
- -R = reduced blanking
+ M = always present
+ a = aspect ratio (3 - 4:3; 4 - 5:4; 9 - 15:9, 16:9; A - 16:10)
+ -R = reduced blanking
example: .48M3-R - 800x600 with reduced blanking
@@ -110,15 +113,15 @@ Note: VESA(TM) has restrictions on what is a standard CVT timing:
If one of the above are not satisfied, the kernel will print a warning but the
timings will still be calculated.
-***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo ***** oOo *****
+-----------------------------------------------------------------------------
-To find a suitable video mode, you just call
+To find a suitable video mode, you just call::
-int __init fb_find_mode(struct fb_var_screeninfo *var,
- struct fb_info *info, const char *mode_option,
- const struct fb_videomode *db, unsigned int dbsize,
- const struct fb_videomode *default_mode,
- unsigned int default_bpp)
+ int __init fb_find_mode(struct fb_var_screeninfo *var,
+ struct fb_info *info, const char *mode_option,
+ const struct fb_videomode *db, unsigned int dbsize,
+ const struct fb_videomode *default_mode,
+ unsigned int default_bpp)
with db/dbsize your non-standard video mode database, or NULL to use the
standard video mode database.
@@ -127,12 +130,13 @@ fb_find_mode() first tries the specified video mode (or any mode that matches,
e.g. there can be multiple 640x480 modes, each of them is tried). If that
fails, the default mode is tried. If that fails, it walks over all modes.
-To specify a video mode at bootup, use the following boot options:
+To specify a video mode at bootup, use the following boot options::
+
video=<driver>:<xres>x<yres>[-<bpp>][@refresh]
where <driver> is a name from the table below. Valid default modes can be
found in linux/drivers/video/modedb.c. Check your driver's documentation.
-There may be more modes.
+There may be more modes::
Drivers that support modedb boot options
Boot Name Cards Supported
diff --git a/Documentation/fb/pvr2fb.rst b/Documentation/fb/pvr2fb.rst
new file mode 100644
index 000000000000..fcf2c21c8fcf
--- /dev/null
+++ b/Documentation/fb/pvr2fb.rst
@@ -0,0 +1,66 @@
+===============
+What is pvr2fb?
+===============
+
+This is a driver for PowerVR 2 based graphics frame buffers, such as the
+one found in the Dreamcast.
+
+Advantages:
+
+ * It provides a nice large console (128 cols + 48 lines with 1024x768)
+ without using tiny, unreadable fonts (NOT on the Dreamcast)
+ * You can run XF86_FBDev on top of /dev/fb0
+ * Most important: boot logo :-)
+
+Disadvantages:
+
+ * Driver is largely untested on non-Dreamcast systems.
+
+Configuration
+=============
+
+You can pass kernel command line options to pvr2fb with
+`video=pvr2fb:option1,option2:value2,option3` (multiple options should be
+separated by comma, values are separated from options by `:`).
+
+Accepted options:
+
+========== ==================================================================
+font:X default font to use. All fonts are supported, including the
+ SUN12x22 font which is very nice at high resolutions.
+
+
+mode:X default video mode with format [xres]x[yres]-<bpp>@<refresh rate>
+ The following video modes are supported:
+ 640x640-16@60, 640x480-24@60, 640x480-32@60. The Dreamcast
+ defaults to 640x480-16@60. At the time of writing the
+ 24bpp and 32bpp modes function poorly. Work to fix that is
+ ongoing
+
+ Note: the 640x240 mode is currently broken, and should not be
+ used for any reason. It is only mentioned here as a reference.
+
+inverse invert colors on screen (for LCD displays)
+
+nomtrr disables write combining on frame buffer. This slows down driver
+ but there is reported minor incompatibility between GUS DMA and
+ XFree under high loads if write combining is enabled (sound
+ dropouts). MTRR is enabled by default on systems that have it
+ configured and that support it.
+
+cable:X cable type. This can be any of the following: vga, rgb, and
+ composite. If none is specified, we guess.
+
+output:X output type. This can be any of the following: pal, ntsc, and
+ vga. If none is specified, we guess.
+========== ==================================================================
+
+X11
+===
+
+XF86_FBDev has been shown to work on the Dreamcast in the past - though not yet
+on any 2.6 series kernel.
+
+Paul Mundt <lethal@linuxdc.org>
+
+Updated by Adrian McMenamin <adrian@mcmen.demon.co.uk>
diff --git a/Documentation/fb/pvr2fb.txt b/Documentation/fb/pvr2fb.txt
deleted file mode 100644
index 36bdeff585e2..000000000000
--- a/Documentation/fb/pvr2fb.txt
+++ /dev/null
@@ -1,65 +0,0 @@
-$Id: pvr2fb.txt,v 1.1 2001/05/24 05:09:16 mrbrown Exp $
-
-What is pvr2fb?
-===============
-
-This is a driver for PowerVR 2 based graphics frame buffers, such as the
-one found in the Dreamcast.
-
-Advantages:
-
- * It provides a nice large console (128 cols + 48 lines with 1024x768)
- without using tiny, unreadable fonts (NOT on the Dreamcast)
- * You can run XF86_FBDev on top of /dev/fb0
- * Most important: boot logo :-)
-
-Disadvantages:
-
- * Driver is largely untested on non-Dreamcast systems.
-
-Configuration
-=============
-
-You can pass kernel command line options to pvr2fb with
-`video=pvr2fb:option1,option2:value2,option3' (multiple options should be
-separated by comma, values are separated from options by `:').
-Accepted options:
-
-font:X - default font to use. All fonts are supported, including the
- SUN12x22 font which is very nice at high resolutions.
-
-
-mode:X - default video mode with format [xres]x[yres]-<bpp>@<refresh rate>
- The following video modes are supported:
- 640x640-16@60, 640x480-24@60, 640x480-32@60. The Dreamcast
- defaults to 640x480-16@60. At the time of writing the
- 24bpp and 32bpp modes function poorly. Work to fix that is
- ongoing
-
- Note: the 640x240 mode is currently broken, and should not be
- used for any reason. It is only mentioned here as a reference.
-
-inverse - invert colors on screen (for LCD displays)
-
-nomtrr - disables write combining on frame buffer. This slows down driver
- but there is reported minor incompatibility between GUS DMA and
- XFree under high loads if write combining is enabled (sound
- dropouts). MTRR is enabled by default on systems that have it
- configured and that support it.
-
-cable:X - cable type. This can be any of the following: vga, rgb, and
- composite. If none is specified, we guess.
-
-output:X - output type. This can be any of the following: pal, ntsc, and
- vga. If none is specified, we guess.
-
-X11
-===
-
-XF86_FBDev has been shown to work on the Dreamcast in the past - though not yet
-on any 2.6 series kernel.
-
---
-Paul Mundt <lethal@linuxdc.org>
-Updated by Adrian McMenamin <adrian@mcmen.demon.co.uk>
-
diff --git a/Documentation/fb/pxafb.txt b/Documentation/fb/pxafb.rst
similarity index 78%
rename from Documentation/fb/pxafb.txt
rename to Documentation/fb/pxafb.rst
index d143a0a749f9..90177f5e7e76 100644
--- a/Documentation/fb/pxafb.txt
+++ b/Documentation/fb/pxafb.rst
@@ -1,59 +1,82 @@
+================================
Driver for PXA25x LCD controller
================================
The driver supports the following options, either via
options=<OPTIONS> when modular or video=pxafb:<OPTIONS> when built in.
-For example:
+For example::
+
modprobe pxafb options=vmem:2M,mode:640x480-8,passive
-or on the kernel command line
+
+or on the kernel command line::
+
video=pxafb:vmem:2M,mode:640x480-8,passive
vmem: VIDEO_MEM_SIZE
+
Amount of video memory to allocate (can be suffixed with K or M
for kilobytes or megabytes)
mode:XRESxYRES[-BPP]
+
XRES == LCCR1_PPL + 1
+
YRES == LLCR2_LPP + 1
+
The resolution of the display in pixels
+
BPP == The bit depth. Valid values are 1, 2, 4, 8 and 16.
pixclock:PIXCLOCK
+
Pixel clock in picoseconds
left:LEFT == LCCR1_BLW + 1
+
right:RIGHT == LCCR1_ELW + 1
+
hsynclen:HSYNC == LCCR1_HSW + 1
+
upper:UPPER == LCCR2_BFW
+
lower:LOWER == LCCR2_EFR
+
vsynclen:VSYNC == LCCR2_VSW + 1
+
Display margins and sync times
color | mono => LCCR0_CMS
+
umm...
active | passive => LCCR0_PAS
+
Active (TFT) or Passive (STN) display
single | dual => LCCR0_SDS
+
Single or dual panel passive display
4pix | 8pix => LCCR0_DPD
+
4 or 8 pixel monochrome single panel data
-hsync:HSYNC
-vsync:VSYNC
+hsync:HSYNC, vsync:VSYNC
+
Horizontal and vertical sync. 0 => active low, 1 => active
high.
dpc:DPC
+
Double pixel clock. 1=>true, 0=>false
outputen:POLARITY
+
Output Enable Polarity. 0 => active low, 1 => active high
pixclockpol:POLARITY
+
pixel clock polarity
0 => falling edge, 1 => rising edge
@@ -76,44 +99,50 @@ Overlay Support for PXA27x and later LCD controllers
not for such purpose).
2. overlay framebuffer is allocated dynamically according to specified
- 'struct fb_var_screeninfo', the amount is decided by:
+ 'struct fb_var_screeninfo', the amount is decided by::
- var->xres_virtual * var->yres_virtual * bpp
+ var->xres_virtual * var->yres_virtual * bpp
bpp = 16 -- for RGB565 or RGBT555
- = 24 -- for YUV444 packed
- = 24 -- for YUV444 planar
- = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr)
- = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr)
+
+ bpp = 24 -- for YUV444 packed
+
+ bpp = 24 -- for YUV444 planar
+
+ bpp = 16 -- for YUV422 planar (1 pixel = 1 Y + 1/2 Cb + 1/2 Cr)
+
+ bpp = 12 -- for YUV420 planar (1 pixel = 1 Y + 1/4 Cb + 1/4 Cr)
NOTE:
a. overlay does not support panning in x-direction, thus
- var->xres_virtual will always be equal to var->xres
+ var->xres_virtual will always be equal to var->xres
b. line length of overlay(s) must be on a 32-bit word boundary,
- for YUV planar modes, it is a requirement for the component
+ for YUV planar modes, it is a requirement for the component
with minimum bits per pixel, e.g. for YUV420, Cr component
for one pixel is actually 2-bits, it means the line length
should be a multiple of 16-pixels
c. starting horizontal position (XPOS) should start on a 32-bit
- word boundary, otherwise the fb_check_var() will just fail.
+ word boundary, otherwise the fb_check_var() will just fail.
d. the rectangle of the overlay should be within the base plane,
- otherwise fail
+ otherwise fail
Applications should follow the sequence below to operate an overlay
framebuffer:
- a. open("/dev/fb[1-2]", ...)
+ a. open("/dev/fb[1-2]", ...)
b. ioctl(fd, FBIOGET_VSCREENINFO, ...)
c. modify 'var' with desired parameters:
+
1) var->xres and var->yres
2) larger var->yres_virtual if more memory is required,
usually for double-buffering
3) var->nonstd for starting (x, y) and color format
4) var->{red, green, blue, transp} if RGB mode is to be used
+
d. ioctl(fd, FBIOPUT_VSCREENINFO, ...)
e. ioctl(fd, FBIOGET_FSCREENINFO, ...)
f. mmap
@@ -124,19 +153,21 @@ Overlay Support for PXA27x and later LCD controllers
and lengths of each component within the framebuffer.
4. var->nonstd is used to pass starting (x, y) position and color format,
- the detailed bit fields are shown below:
+ the detailed bit fields are shown below::
- 31 23 20 10 0
- +-----------------+---+----------+----------+
- | ... unused ... |FOR| XPOS | YPOS |
- +-----------------+---+----------+----------+
+ 31 23 20 10 0
+ +-----------------+---+----------+----------+
+ | ... unused ... |FOR| XPOS | YPOS |
+ +-----------------+---+----------+----------+
FOR - color format, as defined by OVERLAY_FORMAT_* in pxafb.h
- 0 - RGB
- 1 - YUV444 PACKED
- 2 - YUV444 PLANAR
- 3 - YUV422 PLANAR
- 4 - YUR420 PLANAR
+
+ - 0 - RGB
+ - 1 - YUV444 PACKED
+ - 2 - YUV444 PLANAR
+ - 3 - YUV422 PLANAR
+ - 4 - YUR420 PLANAR
XPOS - starting horizontal position
+
YPOS - starting vertical position
diff --git a/Documentation/fb/s3fb.txt b/Documentation/fb/s3fb.rst
similarity index 94%
rename from Documentation/fb/s3fb.txt
rename to Documentation/fb/s3fb.rst
index 2c97770bdbaa..e809d69c21a7 100644
--- a/Documentation/fb/s3fb.txt
+++ b/Documentation/fb/s3fb.rst
@@ -1,6 +1,6 @@
-
- s3fb - fbdev driver for S3 Trio/Virge chips
- ===========================================
+===========================================
+s3fb - fbdev driver for S3 Trio/Virge chips
+===========================================
Supported Hardware
@@ -56,7 +56,7 @@ Missing Features
(alias TODO list)
* secondary (not initialized by BIOS) device support
- * big endian support
+ * big endian support
* Zorro bus support
* MMIO support
* 24 bpp mode support on more cards
diff --git a/Documentation/fb/sa1100fb.txt b/Documentation/fb/sa1100fb.rst
similarity index 64%
rename from Documentation/fb/sa1100fb.txt
rename to Documentation/fb/sa1100fb.rst
index f1b4220464df..67e2650e017d 100644
--- a/Documentation/fb/sa1100fb.txt
+++ b/Documentation/fb/sa1100fb.rst
@@ -1,17 +1,19 @@
-[This file is cloned from VesaFB/matroxfb]
-
+=================
What is sa1100fb?
=================
+.. [This file is cloned from VesaFB/matroxfb]
+
+
This is a driver for a graphic framebuffer for the SA-1100 LCD
controller.
Configuration
==============
-For most common passive displays, giving the option
+For most common passive displays, giving the option::
-video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value>
+ video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value>
on the kernel command line should be enough to configure the
controller. The bits per pixel (bpp) value should be 4, 8, 12, or
@@ -27,13 +29,12 @@ sa1100fb_init_fbinfo(), sa1100fb_activate_var(),
sa1100fb_disable_lcd_controller(), and sa1100fb_enable_lcd_controller()
will probably be necessary.
-Accepted options:
+Accepted options::
-bpp:<value> Configure for <value> bits per pixel
-lccr0:<value> Configure LCD control register 0 (11.7.3)
-lccr1:<value> Configure LCD control register 1 (11.7.4)
-lccr2:<value> Configure LCD control register 2 (11.7.5)
-lccr3:<value> Configure LCD control register 3 (11.7.6)
+ bpp:<value> Configure for <value> bits per pixel
+ lccr0:<value> Configure LCD control register 0 (11.7.3)
+ lccr1:<value> Configure LCD control register 1 (11.7.4)
+ lccr2:<value> Configure LCD control register 2 (11.7.5)
+ lccr3:<value> Configure LCD control register 3 (11.7.6)
---
Mark Huang <mhuang@livetoy.com>
diff --git a/Documentation/fb/sh7760fb.rst b/Documentation/fb/sh7760fb.rst
new file mode 100644
index 000000000000..c3266485f810
--- /dev/null
+++ b/Documentation/fb/sh7760fb.rst
@@ -0,0 +1,130 @@
+================================================
+SH7760/SH7763 integrated LCDC Framebuffer driver
+================================================
+
+0. Overview
+-----------
+The SH7760/SH7763 have an integrated LCD Display controller (LCDC) which
+supports (in theory) resolutions ranging from 1x1 to 1024x1024,
+with color depths ranging from 1 to 16 bits, on STN, DSTN and TFT Panels.
+
+Caveats:
+
+* Framebuffer memory must be a large chunk allocated at the top
+ of Area3 (HW requirement). Because of this requirement you should NOT
+ make the driver a module since at runtime it may become impossible to
+ get a large enough contiguous chunk of memory.
+
+* The driver does not support changing resolution while loaded
+ (displays aren't hotpluggable anyway)
+
+* Heavy flickering may be observed
+ a) if you're using 15/16bit color modes at >= 640x480 px resolutions,
+ b) during PCMCIA (or any other slow bus) activity.
+
+* Rotation works only 90degress clockwise, and only if horizontal
+ resolution is <= 320 pixels.
+
+Files:
+ - drivers/video/sh7760fb.c
+ - include/asm-sh/sh7760fb.h
+ - Documentation/fb/sh7760fb.rst
+
+1. Platform setup
+-----------------
+SH7760:
+ Video data is fetched via the DMABRG DMA engine, so you have to
+ configure the SH DMAC for DMABRG mode (write 0x94808080 to the
+ DMARSRA register somewhere at boot).
+
+ PFC registers PCCR and PCDR must be set to peripheral mode.
+ (write zeros to both).
+
+The driver does NOT do the above for you since board setup is, well, job
+of the board setup code.
+
+2. Panel definitions
+--------------------
+The LCDC must explicitly be told about the type of LCD panel
+attached. Data must be wrapped in a "struct sh7760fb_platdata" and
+passed to the driver as platform_data.
+
+Suggest you take a closer look at the SH7760 Manual, Section 30.
+(http://documentation.renesas.com/eng/products/mpumcu/e602291_sh7760.pdf)
+
+The following code illustrates what needs to be done to
+get the framebuffer working on a 640x480 TFT::
+
+ #include <linux/fb.h>
+ #include <asm/sh7760fb.h>
+
+ /*
+ * NEC NL6440bc26-01 640x480 TFT
+ * dotclock 25175 kHz
+ * Xres 640 Yres 480
+ * Htotal 800 Vtotal 525
+ * HsynStart 656 VsynStart 490
+ * HsynLenn 30 VsynLenn 2
+ *
+ * The linux framebuffer layer does not use the syncstart/synclen
+ * values but right/left/upper/lower margin values. The comments
+ * for the x_margin explain how to calculate those from given
+ * panel sync timings.
+ */
+ static struct fb_videomode nl6448bc26 = {
+ .name = "NL6448BC26",
+ .refresh = 60,
+ .xres = 640,
+ .yres = 480,
+ .pixclock = 39683, /* in picoseconds! */
+ .hsync_len = 30,
+ .vsync_len = 2,
+ .left_margin = 114, /* HTOT - (HSYNSLEN + HSYNSTART) */
+ .right_margin = 16, /* HSYNSTART - XRES */
+ .upper_margin = 33, /* VTOT - (VSYNLEN + VSYNSTART) */
+ .lower_margin = 10, /* VSYNSTART - YRES */
+ .sync = FB_SYNC_HOR_HIGH_ACT | FB_SYNC_VERT_HIGH_ACT,
+ .vmode = FB_VMODE_NONINTERLACED,
+ .flag = 0,
+ };
+
+ static struct sh7760fb_platdata sh7760fb_nl6448 = {
+ .def_mode = &nl6448bc26,
+ .ldmtr = LDMTR_TFT_COLOR_16, /* 16bit TFT panel */
+ .lddfr = LDDFR_8BPP, /* we want 8bit output */
+ .ldpmmr = 0x0070,
+ .ldpspr = 0x0500,
+ .ldaclnr = 0,
+ .ldickr = LDICKR_CLKSRC(LCDC_CLKSRC_EXTERNAL) |
+ LDICKR_CLKDIV(1),
+ .rotate = 0,
+ .novsync = 1,
+ .blank = NULL,
+ };
+
+ /* SH7760:
+ * 0xFE300800: 256 * 4byte xRGB palette ram
+ * 0xFE300C00: 42 bytes ctrl registers
+ */
+ static struct resource sh7760_lcdc_res[] = {
+ [0] = {
+ .start = 0xFE300800,
+ .end = 0xFE300CFF,
+ .flags = IORESOURCE_MEM,
+ },
+ [1] = {
+ .start = 65,
+ .end = 65,
+ .flags = IORESOURCE_IRQ,
+ },
+ };
+
+ static struct platform_device sh7760_lcdc_dev = {
+ .dev = {
+ .platform_data = &sh7760fb_nl6448,
+ },
+ .name = "sh7760-lcdc",
+ .id = -1,
+ .resource = sh7760_lcdc_res,
+ .num_resources = ARRAY_SIZE(sh7760_lcdc_res),
+ };
diff --git a/Documentation/fb/sh7760fb.txt b/Documentation/fb/sh7760fb.txt
deleted file mode 100644
index b994c3b10549..000000000000
--- a/Documentation/fb/sh7760fb.txt
+++ /dev/null
@@ -1,131 +0,0 @@
-SH7760/SH7763 integrated LCDC Framebuffer driver
-================================================
-
-0. Overview
------------
-The SH7760/SH7763 have an integrated LCD Display controller (LCDC) which
-supports (in theory) resolutions ranging from 1x1 to 1024x1024,
-with color depths ranging from 1 to 16 bits, on STN, DSTN and TFT Panels.
-
-Caveats:
-* Framebuffer memory must be a large chunk allocated at the top
- of Area3 (HW requirement). Because of this requirement you should NOT
- make the driver a module since at runtime it may become impossible to
- get a large enough contiguous chunk of memory.
-
-* The driver does not support changing resolution while loaded
- (displays aren't hotpluggable anyway)
-
-* Heavy flickering may be observed
- a) if you're using 15/16bit color modes at >= 640x480 px resolutions,
- b) during PCMCIA (or any other slow bus) activity.
-
-* Rotation works only 90degress clockwise, and only if horizontal
- resolution is <= 320 pixels.
-
-files: drivers/video/sh7760fb.c
- include/asm-sh/sh7760fb.h
- Documentation/fb/sh7760fb.txt
-
-1. Platform setup
------------------
-SH7760:
- Video data is fetched via the DMABRG DMA engine, so you have to
- configure the SH DMAC for DMABRG mode (write 0x94808080 to the
- DMARSRA register somewhere at boot).
-
- PFC registers PCCR and PCDR must be set to peripheral mode.
- (write zeros to both).
-
-The driver does NOT do the above for you since board setup is, well, job
-of the board setup code.
-
-2. Panel definitions
---------------------
-The LCDC must explicitly be told about the type of LCD panel
-attached. Data must be wrapped in a "struct sh7760fb_platdata" and
-passed to the driver as platform_data.
-
-Suggest you take a closer look at the SH7760 Manual, Section 30.
-(http://documentation.renesas.com/eng/products/mpumcu/e602291_sh7760.pdf)
-
-The following code illustrates what needs to be done to
-get the framebuffer working on a 640x480 TFT:
-
-====================== cut here ======================================
-
-#include <linux/fb.h>
-#include <asm/sh7760fb.h>
-
-/*
- * NEC NL6440bc26-01 640x480 TFT
- * dotclock 25175 kHz
- * Xres 640 Yres 480
- * Htotal 800 Vtotal 525
- * HsynStart 656 VsynStart 490
- * HsynLenn 30 VsynLenn 2
- *
- * The linux framebuffer layer does not use the syncstart/synclen
- * values but right/left/upper/lower margin values. The comments
- * for the x_margin explain how to calculate those from given
- * panel sync timings.
- */
-static struct fb_videomode nl6448bc26 = {
- .name = "NL6448BC26",
- .refresh = 60,
- .xres = 640,
- .yres = 480,
- .pixclock = 39683, /* in picoseconds! */
- .hsync_len = 30,
- .vsync_len = 2,
- .left_margin = 114, /* HTOT - (HSYNSLEN + HSYNSTART) */
- .right_margin = 16, /* HSYNSTART - XRES */
- .upper_margin = 33, /* VTOT - (VSYNLEN + VSYNSTART) */
- .lower_margin = 10, /* VSYNSTART - YRES */
- .sync = FB_SYNC_HOR_HIGH_ACT | FB_SYNC_VERT_HIGH_ACT,
- .vmode = FB_VMODE_NONINTERLACED,
- .flag = 0,
-};
-
-static struct sh7760fb_platdata sh7760fb_nl6448 = {
- .def_mode = &nl6448bc26,
- .ldmtr = LDMTR_TFT_COLOR_16, /* 16bit TFT panel */
- .lddfr = LDDFR_8BPP, /* we want 8bit output */
- .ldpmmr = 0x0070,
- .ldpspr = 0x0500,
- .ldaclnr = 0,
- .ldickr = LDICKR_CLKSRC(LCDC_CLKSRC_EXTERNAL) |
- LDICKR_CLKDIV(1),
- .rotate = 0,
- .novsync = 1,
- .blank = NULL,
-};
-
-/* SH7760:
- * 0xFE300800: 256 * 4byte xRGB palette ram
- * 0xFE300C00: 42 bytes ctrl registers
- */
-static struct resource sh7760_lcdc_res[] = {
- [0] = {
- .start = 0xFE300800,
- .end = 0xFE300CFF,
- .flags = IORESOURCE_MEM,
- },
- [1] = {
- .start = 65,
- .end = 65,
- .flags = IORESOURCE_IRQ,
- },
-};
-
-static struct platform_device sh7760_lcdc_dev = {
- .dev = {
- .platform_data = &sh7760fb_nl6448,
- },
- .name = "sh7760-lcdc",
- .id = -1,
- .resource = sh7760_lcdc_res,
- .num_resources = ARRAY_SIZE(sh7760_lcdc_res),
-};
-
-====================== cut here ======================================
diff --git a/Documentation/fb/sisfb.txt b/Documentation/fb/sisfb.rst
similarity index 85%
rename from Documentation/fb/sisfb.txt
rename to Documentation/fb/sisfb.rst
index 2e68e503e72f..8f4e502ea12e 100644
--- a/Documentation/fb/sisfb.txt
+++ b/Documentation/fb/sisfb.rst
@@ -1,4 +1,4 @@
-
+==============
What is sisfb?
==============
@@ -41,11 +41,11 @@ statement to add the parameters to the kernel command line. Please see lilo's
parameters are given with the modprobe (or insmod) command.
Example for sisfb as part of the static kernel: Add the following line to your
-lilo.conf:
+lilo.conf::
append="video=sisfb:mode:1024x768x16,mem:12288,rate:75"
-Example for sisfb as a module: Start sisfb by typing
+Example for sisfb as a module: Start sisfb by typing::
modprobe sisfb mode=1024x768x16 rate=75 mem=12288
@@ -57,7 +57,7 @@ described above or the vesa keyword instead of mode). If compiled as a module,
the parameter format reads mode=none or mode=1024x768x16 (or whatever mode you
want to use). Using a "=" for a ":" (and vice versa) is a huge difference!
Additionally: If you give more than one argument to the in-kernel sisfb, the
-arguments are separated with ",". For example:
+arguments are separated with ",". For example::
video=sisfb:mode:1024x768x16,rate:75,mem:12288
@@ -73,6 +73,7 @@ supported options including some explanation.
The desired display mode can be specified using the keyword "mode" with
a parameter in one of the following formats:
+
- XxYxDepth or
- XxY-Depth or
- XxY-Depth@Rate or
@@ -130,29 +131,30 @@ Configuration
(Some) accepted options:
-off - Disable sisfb. This option is only understood if sisfb is
- in-kernel, not a module.
-mem:X - size of memory for the console, rest will be used for DRI/DRM. X
- is in kilobytes. On 300 series, the default is 4096, 8192 or
+========= ==================================================================
+off Disable sisfb. This option is only understood if sisfb is
+ in-kernel, not a module.
+mem:X size of memory for the console, rest will be used for DRI/DRM. X
+ is in kilobytes. On 300 series, the default is 4096, 8192 or
16384 (each in kilobyte) depending on how much video ram the card
- has. On 315/330 series, the default is the maximum available ram
+ has. On 315/330 series, the default is the maximum available ram
(since DRI/DRM is not supported for these chipsets).
-noaccel - do not use 2D acceleration engine. (Default: use acceleration)
-noypan - disable y-panning and scroll by redrawing the entire screen.
- This is much slower than y-panning. (Default: use y-panning)
-vesa:X - selects startup videomode. X is number from 0 to 0x1FF and
- represents the VESA mode number (can be given in decimal or
+noaccel do not use 2D acceleration engine. (Default: use acceleration)
+noypan disable y-panning and scroll by redrawing the entire screen.
+ This is much slower than y-panning. (Default: use y-panning)
+vesa:X selects startup videomode. X is number from 0 to 0x1FF and
+ represents the VESA mode number (can be given in decimal or
hexadecimal form, the latter prefixed with "0x").
-mode:X - selects startup videomode. Please see above for the format of
- "X".
+mode:X selects startup videomode. Please see above for the format of
+ "X".
+========= ==================================================================
Boolean options such as "noaccel" or "noypan" are to be given without a
parameter if sisfb is in-kernel (for example "video=sisfb:noypan). If
sisfb is a module, these are to be set to 1 (for example "modprobe sisfb
noypan=1").
---
+
Thomas Winischhofer <thomas@winischhofer.net>
+
May 27, 2004
-
-
diff --git a/Documentation/fb/sm501.txt b/Documentation/fb/sm501.rst
similarity index 65%
rename from Documentation/fb/sm501.txt
rename to Documentation/fb/sm501.rst
index 187f3b3ccb6c..03e02c8042a7 100644
--- a/Documentation/fb/sm501.txt
+++ b/Documentation/fb/sm501.rst
@@ -1,6 +1,11 @@
+=======
+sm501fb
+=======
+
Configuration:
-You can pass the following kernel command line options to sm501 videoframebuffer:
+You can pass the following kernel command line options to sm501
+videoframebuffer::
sm501fb.bpp= SM501 Display driver:
Specify bits-per-pixel if not specified by 'mode'
diff --git a/Documentation/fb/sm712fb.txt b/Documentation/fb/sm712fb.rst
similarity index 59%
rename from Documentation/fb/sm712fb.txt
rename to Documentation/fb/sm712fb.rst
index c388442edf51..994dad3b0238 100644
--- a/Documentation/fb/sm712fb.txt
+++ b/Documentation/fb/sm712fb.rst
@@ -1,5 +1,6 @@
+================
What is sm712fb?
-=================
+================
This is a graphics framebuffer driver for Silicon Motion SM712 based processors.
@@ -15,13 +16,16 @@ You should not compile-in vesafb.
Currently supported video modes are:
-[Graphic modes]
+Graphic modes
+-------------
-bpp | 640x480 800x600 1024x768 1280x1024
-----+--------------------------------------------
- 8 | 0x301 0x303 0x305 0x307
- 16 | 0x311 0x314 0x317 0x31A
- 24 | 0x312 0x315 0x318 0x31B
+=== ======= ======= ======== =========
+bpp 640x480 800x600 1024x768 1280x1024
+=== ======= ======= ======== =========
+ 8 0x301 0x303 0x305 0x307
+ 16 0x311 0x314 0x317 0x31A
+ 24 0x312 0x315 0x318 0x31B
+=== ======= ======= ======== =========
Missing Features
================
diff --git a/Documentation/fb/sstfb.rst b/Documentation/fb/sstfb.rst
new file mode 100644
index 000000000000..8e8c1b940359
--- /dev/null
+++ b/Documentation/fb/sstfb.rst
@@ -0,0 +1,207 @@
+=====
+sstfb
+=====
+
+Introduction
+============
+
+This is a frame buffer device driver for 3dfx' Voodoo Graphics
+(aka voodoo 1, aka sst1) and Voodoo² (aka Voodoo 2, aka CVG) based
+video boards. It's highly experimental code, but is guaranteed to work
+on my computer, with my "Maxi Gamer 3D" and "Maxi Gamer 3d²" boards,
+and with me "between chair and keyboard". Some people tested other
+combinations and it seems that it works.
+The main page is located at <http://sstfb.sourceforge.net>, and if
+you want the latest version, check out the CVS, as the driver is a work
+in progress, I feel uncomfortable with releasing tarballs of something
+not completely working...Don't worry, it's still more than usable
+(I eat my own dog food)
+
+Please read the Bug section, and report any success or failure to me
+(Ghozlane Toumi <gtoumi@laposte.net>).
+BTW, If you have only one monitor , and you don't feel like playing
+with the vga passthrou cable, I can only suggest borrowing a screen
+somewhere...
+
+
+Installation
+============
+
+This driver (should) work on ix86, with "late" 2.2.x kernel (tested
+with x = 19) and "recent" 2.4.x kernel, as a module or compiled in.
+It has been included in mainstream kernel since the infamous 2.4.10.
+You can apply the patches found in `sstfb/kernel/*-2.{2|4}.x.patch`,
+and copy sstfb.c to linux/drivers/video/, or apply a single patch,
+`sstfb/patch-2.{2|4}.x-sstfb-yymmdd` to your linux source tree.
+
+Then configure your kernel as usual: choose "m" or "y" to 3Dfx Voodoo
+Graphics in section "console". Compile, install, have fun... and please
+drop me a report :)
+
+
+Module Usage
+============
+
+.. warning::
+
+ #. You should read completely this section before issuing any command.
+
+ #. If you have only one monitor to play with, once you insmod the
+ module, the 3dfx takes control of the output, so you'll have to
+ plug the monitor to the "normal" video board in order to issue
+ the commands, or you can blindly use sst_dbg_vgapass
+ in the tools directory (See Tools). The latest solution is pass the
+ parameter vgapass=1 when insmodding the driver. (See Kernel/Modules
+ Options)
+
+Module insertion
+----------------
+
+ #. insmod sstfb.o
+
+ you should see some strange output from the board:
+ a big blue square, a green and a red small squares and a vertical
+ white rectangle. why? the function's name is self-explanatory:
+ "sstfb_test()"...
+ (if you don't have a second monitor, you'll have to plug your monitor
+ directly to the 2D videocard to see what you're typing)
+
+ #. con2fb /dev/fbx /dev/ttyx
+
+ bind a tty to the new frame buffer. if you already have a frame
+ buffer driver, the voodoo fb will likely be /dev/fb1. if not,
+ the device will be /dev/fb0. You can check this by doing a
+ cat /proc/fb. You can find a copy of con2fb in tools/ directory.
+ if you don't have another fb device, this step is superfluous,
+ as the console subsystem automagicaly binds ttys to the fb.
+ #. switch to the virtual console you just mapped. "tadaaa" ...
+
+Module removal
+--------------
+
+ #. con2fb /dev/fbx /dev/ttyx
+
+ bind the tty to the old frame buffer so the module can be removed.
+ (how does it work with vgacon ? short answer : it doesn't work)
+
+ #. rmmod sstfb
+
+
+Kernel/Modules Options
+----------------------
+
+You can pass some options to the sstfb module, and via the kernel
+command line when the driver is compiled in:
+for module : insmod sstfb.o option1=value1 option2=value2 ...
+in kernel : video=sstfb:option1,option2:value2,option3 ...
+
+sstfb supports the following options:
+
+=============== =============== ===============================================
+Module Kernel Description
+=============== =============== ===============================================
+vgapass=0 vganopass Enable or disable VGA passthrou cable.
+vgapass=1 vgapass When enabled, the monitor will get the signal
+ from the VGA board and not from the voodoo.
+
+ Default: nopass
+
+mem=x mem:x Force frame buffer memory in MiB
+ allowed values: 0, 1, 2, 4.
+
+ Default: 0 (= autodetect)
+
+inverse=1 inverse Supposed to enable inverse console.
+ doesn't work yet...
+
+clipping=1 clipping Enable or disable clipping.
+clipping=0 noclipping With clipping enabled, all offscreen
+ reads and writes are discarded.
+
+ Default: enable clipping.
+
+gfxclk=x gfxclk:x Force graphic clock frequency (in MHz).
+ Be careful with this option, it may be
+ DANGEROUS.
+
+ Default: auto
+
+ - 50Mhz for Voodoo 1,
+ - 75MHz for Voodoo 2.
+
+slowpci=1 fastpci Enable or disable fast PCI read/writes.
+slowpci=1 slowpci Default : fastpci
+
+dev=x dev:x Attach the driver to device number x.
+ 0 is the first compatible board (in
+ lspci order)
+=============== =============== ===============================================
+
+Tools
+=====
+
+These tools are mostly for debugging purposes, but you can
+find some of these interesting:
+
+- `con2fb`, maps a tty to a fbramebuffer::
+
+ con2fb /dev/fb1 /dev/tty5
+
+- `sst_dbg_vgapass`, changes vga passthrou. You have to recompile the
+ driver with SST_DEBUG and SST_DEBUG_IOCTL set to 1::
+
+ sst_dbg_vgapass /dev/fb1 1 (enables vga cable)
+ sst_dbg_vgapass /dev/fb1 0 (disables vga cable)
+
+- `glide_reset`, resets the voodoo using glide
+ use this after rmmoding sstfb, if the module refuses to
+ reinsert.
+
+Bugs
+====
+
+- DO NOT use glide while the sstfb module is in, you'll most likely
+ hang your computer.
+- If you see some artefacts (pixels not cleaning and stuff like that),
+ try turning off clipping (clipping=0), and/or using slowpci
+- the driver don't detect the 4Mb frame buffer voodoos, it seems that
+ the 2 last Mbs wrap around. looking into that .
+- The driver is 16 bpp only, 24/32 won't work.
+- The driver is not your_favorite_toy-safe. this includes SMP...
+
+ [Actually from inspection it seems to be safe - Alan]
+
+- When using XFree86 FBdev (X over fbdev) you may see strange color
+ patterns at the border of your windows (the pixels lose the lowest
+ byte -> basically the blue component and some of the green). I'm unable
+ to reproduce this with XFree86-3.3, but one of the testers has this
+ problem with XFree86-4. Apparently recent Xfree86-4.x solve this
+ problem.
+- I didn't really test changing the palette, so you may find some weird
+ things when playing with that.
+- Sometimes the driver will not recognise the DAC, and the
+ initialisation will fail. This is specifically true for
+ voodoo 2 boards, but it should be solved in recent versions. Please
+ contact me.
+- The 24/32 is not likely to work anytime soon, knowing that the
+ hardware does ... unusual things in 24/32 bpp.
+- When used with another video board, current limitations of the linux
+ console subsystem can cause some troubles, specifically, you should
+ disable software scrollback, as it can oops badly ...
+
+Todo
+====
+
+- Get rid of the previous paragraph.
+- Buy more coffee.
+- test/port to other arch.
+- try to add panning using tweeks with front and back buffer .
+- try to implement accel on voodoo2, this board can actually do a
+ lot in 2D even if it was sold as a 3D only board ...
+
+Ghozlane Toumi <gtoumi@laposte.net>
+
+
+Date: 2002/05/09 20:11:45
+
+http://sstfb.sourceforge.net/README
diff --git a/Documentation/fb/sstfb.txt b/Documentation/fb/sstfb.txt
deleted file mode 100644
index 13db1075e4a5..000000000000
--- a/Documentation/fb/sstfb.txt
+++ /dev/null
@@ -1,174 +0,0 @@
-
-Introduction
-
- This is a frame buffer device driver for 3dfx' Voodoo Graphics
- (aka voodoo 1, aka sst1) and Voodoo² (aka Voodoo 2, aka CVG) based
- video boards. It's highly experimental code, but is guaranteed to work
- on my computer, with my "Maxi Gamer 3D" and "Maxi Gamer 3d²" boards,
- and with me "between chair and keyboard". Some people tested other
- combinations and it seems that it works.
- The main page is located at <http://sstfb.sourceforge.net>, and if
- you want the latest version, check out the CVS, as the driver is a work
- in progress, I feel uncomfortable with releasing tarballs of something
- not completely working...Don't worry, it's still more than usable
- (I eat my own dog food)
-
- Please read the Bug section, and report any success or failure to me
- (Ghozlane Toumi <gtoumi@laposte.net>).
- BTW, If you have only one monitor , and you don't feel like playing
- with the vga passthrou cable, I can only suggest borrowing a screen
- somewhere...
-
-
-Installation
-
- This driver (should) work on ix86, with "late" 2.2.x kernel (tested
- with x = 19) and "recent" 2.4.x kernel, as a module or compiled in.
- It has been included in mainstream kernel since the infamous 2.4.10.
- You can apply the patches found in sstfb/kernel/*-2.{2|4}.x.patch,
- and copy sstfb.c to linux/drivers/video/, or apply a single patch,
- sstfb/patch-2.{2|4}.x-sstfb-yymmdd to your linux source tree.
-
- Then configure your kernel as usual: choose "m" or "y" to 3Dfx Voodoo
- Graphics in section "console". Compile, install, have fun... and please
- drop me a report :)
-
-
-Module Usage
-
- Warnings.
- # You should read completely this section before issuing any command.
- # If you have only one monitor to play with, once you insmod the
- module, the 3dfx takes control of the output, so you'll have to
- plug the monitor to the "normal" video board in order to issue
- the commands, or you can blindly use sst_dbg_vgapass
- in the tools directory (See Tools). The latest solution is pass the
- parameter vgapass=1 when insmodding the driver. (See Kernel/Modules
- Options)
-
- Module insertion:
- # insmod sstfb.o
- you should see some strange output from the board:
- a big blue square, a green and a red small squares and a vertical
- white rectangle. why? the function's name is self-explanatory:
- "sstfb_test()"...
- (if you don't have a second monitor, you'll have to plug your monitor
- directly to the 2D videocard to see what you're typing)
- # con2fb /dev/fbx /dev/ttyx
- bind a tty to the new frame buffer. if you already have a frame
- buffer driver, the voodoo fb will likely be /dev/fb1. if not,
- the device will be /dev/fb0. You can check this by doing a
- cat /proc/fb. You can find a copy of con2fb in tools/ directory.
- if you don't have another fb device, this step is superfluous,
- as the console subsystem automagicaly binds ttys to the fb.
- # switch to the virtual console you just mapped. "tadaaa" ...
-
- Module removal:
- # con2fb /dev/fbx /dev/ttyx
- bind the tty to the old frame buffer so the module can be removed.
- (how does it work with vgacon ? short answer : it doesn't work)
- # rmmod sstfb
-
-
-Kernel/Modules Options
-
- You can pass some options to the sstfb module, and via the kernel
- command line when the driver is compiled in:
- for module : insmod sstfb.o option1=value1 option2=value2 ...
- in kernel : video=sstfb:option1,option2:value2,option3 ...
-
- sstfb supports the following options :
-
-Module Kernel Description
-
-vgapass=0 vganopass Enable or disable VGA passthrou cable.
-vgapass=1 vgapass When enabled, the monitor will get the signal
- from the VGA board and not from the voodoo.
- Default: nopass
-
-mem=x mem:x Force frame buffer memory in MiB
- allowed values: 0, 1, 2, 4.
- Default: 0 (= autodetect)
-
-inverse=1 inverse Supposed to enable inverse console.
- doesn't work yet...
-
-clipping=1 clipping Enable or disable clipping.
-clipping=0 noclipping With clipping enabled, all offscreen
- reads and writes are discarded.
- Default: enable clipping.
-
-gfxclk=x gfxclk:x Force graphic clock frequency (in MHz).
- Be careful with this option, it may be
- DANGEROUS.
- Default: auto
- 50Mhz for Voodoo 1,
- 75MHz for Voodoo 2.
-
-slowpci=1 fastpci Enable or disable fast PCI read/writes.
-slowpci=1 slowpci Default : fastpci
-
-dev=x dev:x Attach the driver to device number x.
- 0 is the first compatible board (in
- lspci order)
-
-Tools
-
- These tools are mostly for debugging purposes, but you can
- find some of these interesting :
- - con2fb , maps a tty to a fbramebuffer .
- con2fb /dev/fb1 /dev/tty5
- - sst_dbg_vgapass , changes vga passthrou. You have to recompile the
- driver with SST_DEBUG and SST_DEBUG_IOCTL set to 1
- sst_dbg_vgapass /dev/fb1 1 (enables vga cable)
- sst_dbg_vgapass /dev/fb1 0 (disables vga cable)
- - glide_reset , resets the voodoo using glide
- use this after rmmoding sstfb, if the module refuses to
- reinsert .
-
-Bugs
-
- - DO NOT use glide while the sstfb module is in, you'll most likely
- hang your computer.
- - If you see some artefacts (pixels not cleaning and stuff like that),
- try turning off clipping (clipping=0), and/or using slowpci
- - the driver don't detect the 4Mb frame buffer voodoos, it seems that
- the 2 last Mbs wrap around. looking into that .
- - The driver is 16 bpp only, 24/32 won't work.
- - The driver is not your_favorite_toy-safe. this includes SMP...
- [Actually from inspection it seems to be safe - Alan]
- - When using XFree86 FBdev (X over fbdev) you may see strange color
- patterns at the border of your windows (the pixels lose the lowest
- byte -> basically the blue component and some of the green). I'm unable
- to reproduce this with XFree86-3.3, but one of the testers has this
- problem with XFree86-4. Apparently recent Xfree86-4.x solve this
- problem.
- - I didn't really test changing the palette, so you may find some weird
- things when playing with that.
- - Sometimes the driver will not recognise the DAC, and the
- initialisation will fail. This is specifically true for
- voodoo 2 boards, but it should be solved in recent versions. Please
- contact me.
- - The 24/32 is not likely to work anytime soon, knowing that the
- hardware does ... unusual things in 24/32 bpp.
- - When used with another video board, current limitations of the linux
- console subsystem can cause some troubles, specifically, you should
- disable software scrollback, as it can oops badly ...
-
-Todo
-
- - Get rid of the previous paragraph.
- - Buy more coffee.
- - test/port to other arch.
- - try to add panning using tweeks with front and back buffer .
- - try to implement accel on voodoo2, this board can actually do a
- lot in 2D even if it was sold as a 3D only board ...
-
-ghoz.
-
---
-Ghozlane Toumi <gtoumi@laposte.net>
-
-
-$Date: 2002/05/09 20:11:45 $
-http://sstfb.sourceforge.net/README
diff --git a/Documentation/fb/tgafb.txt b/Documentation/fb/tgafb.rst
similarity index 71%
rename from Documentation/fb/tgafb.txt
rename to Documentation/fb/tgafb.rst
index 250083ada8fb..0c50d2134aa4 100644
--- a/Documentation/fb/tgafb.txt
+++ b/Documentation/fb/tgafb.rst
@@ -1,15 +1,14 @@
-$Id: tgafb.txt,v 1.1.2.2 2000/04/04 06:50:18 mato Exp $
-
+==============
What is tgafb?
-===============
+==============
This is a driver for DECChip 21030 based graphics framebuffers, a.k.a. TGA
cards, which are usually found in older Digital Alpha systems. The
following models are supported:
-ZLxP-E1 (8bpp, 2 MB VRAM)
-ZLxP-E2 (32bpp, 8 MB VRAM)
-ZLxP-E3 (32bpp, 16 MB VRAM, Zbuffer)
+- ZLxP-E1 (8bpp, 2 MB VRAM)
+- ZLxP-E2 (32bpp, 8 MB VRAM)
+- ZLxP-E3 (32bpp, 16 MB VRAM, Zbuffer)
This version is an almost complete rewrite of the code written by Geert
Uytterhoeven, which was based on the original TGA console code written by
@@ -18,7 +17,7 @@ Jay Estabrook.
Major new features since Linux 2.0.x:
* Support for multiple resolutions
- * Support for fixed-frequency and other oddball monitors
+ * Support for fixed-frequency and other oddball monitors
(by allowing the video mode to be set at boot time)
User-visible changes since Linux 2.2.x:
@@ -36,19 +35,22 @@ Configuration
=============
You can pass kernel command line options to tgafb with
-`video=tgafb:option1,option2:value2,option3' (multiple options should be
-separated by comma, values are separated from options by `:').
+`video=tgafb:option1,option2:value2,option3` (multiple options should be
+separated by comma, values are separated from options by `:`).
+
Accepted options:
-font:X - default font to use. All fonts are supported, including the
- SUN12x22 font which is very nice at high resolutions.
+========== ============================================================
+font:X default font to use. All fonts are supported, including the
+ SUN12x22 font which is very nice at high resolutions.
-mode:X - default video mode. The following video modes are supported:
- 640x480-60, 800x600-56, 640x480-72, 800x600-60, 800x600-72,
+mode:X default video mode. The following video modes are supported:
+ 640x480-60, 800x600-56, 640x480-72, 800x600-60, 800x600-72,
1024x768-60, 1152x864-60, 1024x768-70, 1024x768-76,
1152x864-70, 1280x1024-61, 1024x768-85, 1280x1024-70,
1152x864-84, 1280x1024-76, 1280x1024-85
-
+========== ============================================================
+
Known Issues
============
diff --git a/Documentation/fb/tridentfb.txt b/Documentation/fb/tridentfb.rst
similarity index 70%
rename from Documentation/fb/tridentfb.txt
rename to Documentation/fb/tridentfb.rst
index 45d9de5b13a3..7921c9dee78c 100644
--- a/Documentation/fb/tridentfb.txt
+++ b/Documentation/fb/tridentfb.rst
@@ -1,3 +1,7 @@
+=========
+Tridentfb
+=========
+
Tridentfb is a framebuffer driver for some Trident chip based cards.
The following list of chips is thought to be supported although not all are
@@ -17,6 +21,7 @@ limited comparing to the range if acceleration is disabled (see list
of parameters below).
Known bugs:
+
1. The driver randomly locks up on 3DImage975 chip with acceleration
enabled. The same happens in X11 (Xorg).
2. The ramdac speeds require some more fine tuning. It is possible to
@@ -26,28 +31,30 @@ Known bugs:
How to use it?
==============
-When booting you can pass the video parameter.
-video=tridentfb
+When booting you can pass the video parameter::
-The parameters for tridentfb are concatenated with a ':' as in this example.
+ video=tridentfb
-video=tridentfb:800x600-16@75,noaccel
+The parameters for tridentfb are concatenated with a ':' as in this example::
+
+ video=tridentfb:800x600-16@75,noaccel
The second level parameters that tridentfb understands are:
-noaccel - turns off acceleration (when it doesn't work for your card)
+======== =====================================================================
+noaccel turns off acceleration (when it doesn't work for your card)
-fp - use flat panel related stuff
-crt - assume monitor is present instead of fp
+fp use flat panel related stuff
+crt assume monitor is present instead of fp
-center - for flat panels and resolutions smaller than native size center the
+center for flat panels and resolutions smaller than native size center the
image, otherwise use
stretch
-memsize - integer value in KB, use if your card's memory size is misdetected.
+memsize integer value in KB, use if your card's memory size is misdetected.
look at the driver output to see what it says when initializing.
-memdiff - integer value in KB, should be nonzero if your card reports
+memdiff integer value in KB, should be nonzero if your card reports
more memory than it actually has. For instance mine is 192K less than
detection says in all three BIOS selectable situations 2M, 4M, 8M.
Only use if your video memory is taken from main memory hence of
@@ -56,12 +63,13 @@ memdiff - integer value in KB, should be nonzero if your card reports
at the bottom this might help by not letting change to that mode
anymore.
-nativex - the width in pixels of the flat panel.If you know it (usually 1024
+nativex the width in pixels of the flat panel.If you know it (usually 1024
800 or 1280) and it is not what the driver seems to detect use it.
-bpp - bits per pixel (8,16 or 32)
-mode - a mode name like 800x600-8@75 as described in
- Documentation/fb/modedb.txt
+bpp bits per pixel (8,16 or 32)
+mode a mode name like 800x600-8@75 as described in
+ Documentation/fb/modedb.rst
+======== =====================================================================
Using insane values for the above parameters will probably result in driver
misbehaviour so take care(for instance memsize=12345678 or memdiff=23784 or
diff --git a/Documentation/fb/udlfb.txt b/Documentation/fb/udlfb.rst
similarity index 77%
rename from Documentation/fb/udlfb.txt
rename to Documentation/fb/udlfb.rst
index c985cb65dd06..732b37db3504 100644
--- a/Documentation/fb/udlfb.txt
+++ b/Documentation/fb/udlfb.rst
@@ -1,6 +1,6 @@
-
+==============
What is udlfb?
-===============
+==============
This is a driver for DisplayLink USB 2.0 era graphics chips.
@@ -100,6 +100,7 @@ options udlfb fb_defio=0 console=1 shadow=1
Accepted boolean options:
+=============== ================================================================
fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel
module to track changed areas of the framebuffer by page faults.
Standard fbdev applications that use mmap but that do not
@@ -109,7 +110,7 @@ fb_defio Make use of the fb_defio (CONFIG_FB_DEFERRED_IO) kernel
more stable, and higher performance.
default: fb_defio=1
-console Allow fbcon to attach to udlfb provided framebuffers.
+console Allow fbcon to attach to udlfb provided framebuffers.
Can be disabled if fbcon and other clients
(e.g. X with --shared-vt) are in conflict.
default: console=1
@@ -119,6 +120,7 @@ shadow Allocate a 2nd framebuffer to shadow what's currently across
do not transmit. Spends host memory to save USB transfers.
Enabled by default. Only disable on very low memory systems.
default: shadow=1
+=============== ================================================================
Sysfs Attributes
================
@@ -126,34 +128,35 @@ Sysfs Attributes
Udlfb creates several files in /sys/class/graphics/fb?
Where ? is the sequential framebuffer id of the particular DisplayLink device
-edid If a valid EDID blob is written to this file (typically
- by a udev rule), then udlfb will use this EDID as a
- backup in case reading the actual EDID of the monitor
- attached to the DisplayLink device fails. This is
- especially useful for fixed panels, etc. that cannot
- communicate their capabilities via EDID. Reading
- this file returns the current EDID of the attached
- monitor (or last backup value written). This is
- useful to get the EDID of the attached monitor,
- which can be passed to utilities like parse-edid.
+======================== ========================================================
+edid If a valid EDID blob is written to this file (typically
+ by a udev rule), then udlfb will use this EDID as a
+ backup in case reading the actual EDID of the monitor
+ attached to the DisplayLink device fails. This is
+ especially useful for fixed panels, etc. that cannot
+ communicate their capabilities via EDID. Reading
+ this file returns the current EDID of the attached
+ monitor (or last backup value written). This is
+ useful to get the EDID of the attached monitor,
+ which can be passed to utilities like parse-edid.
-metrics_bytes_rendered 32-bit count of pixel bytes rendered
+metrics_bytes_rendered 32-bit count of pixel bytes rendered
-metrics_bytes_identical 32-bit count of how many of those bytes were found to be
- unchanged, based on a shadow framebuffer check
+metrics_bytes_identical 32-bit count of how many of those bytes were found to be
+ unchanged, based on a shadow framebuffer check
-metrics_bytes_sent 32-bit count of how many bytes were transferred over
- USB to communicate the resulting changed pixels to the
- hardware. Includes compression and protocol overhead
+metrics_bytes_sent 32-bit count of how many bytes were transferred over
+ USB to communicate the resulting changed pixels to the
+ hardware. Includes compression and protocol overhead
metrics_cpu_kcycles_used 32-bit count of CPU cycles used in processing the
- above pixels (in thousands of cycles).
+ above pixels (in thousands of cycles).
-metrics_reset Write-only. Any write to this file resets all metrics
- above to zero. Note that the 32-bit counters above
- roll over very quickly. To get reliable results, design
- performance tests to start and finish in a very short
- period of time (one minute or less is safe).
+metrics_reset Write-only. Any write to this file resets all metrics
+ above to zero. Note that the 32-bit counters above
+ roll over very quickly. To get reliable results, design
+ performance tests to start and finish in a very short
+ period of time (one minute or less is safe).
+======================== ========================================================
---
Bernie Thompson <bernie@plugable.com>
diff --git a/Documentation/fb/uvesafb.txt b/Documentation/fb/uvesafb.rst
similarity index 52%
rename from Documentation/fb/uvesafb.txt
rename to Documentation/fb/uvesafb.rst
index aa924196c366..d1c2523fbb33 100644
--- a/Documentation/fb/uvesafb.txt
+++ b/Documentation/fb/uvesafb.rst
@@ -1,4 +1,4 @@
-
+==========================================================
uvesafb - A Generic Driver for VBE2+ compliant video cards
==========================================================
@@ -49,7 +49,7 @@ The most important limitations are:
uvesafb can be compiled either as a module, or directly into the kernel.
In both cases it supports the same set of configuration options, which
-are either given on the kernel command line or as module parameters, e.g.:
+are either given on the kernel command line or as module parameters, e.g.::
video=uvesafb:1024x768-32,mtrr:3,ywrap (compiled into the kernel)
@@ -57,85 +57,90 @@ are either given on the kernel command line or as module parameters, e.g.:
Accepted options:
+======= =========================================================
ypan Enable display panning using the VESA protected mode
- interface. The visible screen is just a window of the
- video memory, console scrolling is done by changing the
- start of the window. This option is available on x86
- only and is the default option on that architecture.
+ interface. The visible screen is just a window of the
+ video memory, console scrolling is done by changing the
+ start of the window. This option is available on x86
+ only and is the default option on that architecture.
ywrap Same as ypan, but assumes your gfx board can wrap-around
- the video memory (i.e. starts reading from top if it
- reaches the end of video memory). Faster than ypan.
- Available on x86 only.
+ the video memory (i.e. starts reading from top if it
+ reaches the end of video memory). Faster than ypan.
+ Available on x86 only.
redraw Scroll by redrawing the affected part of the screen, this
- is the default on non-x86.
+ is the default on non-x86.
+======= =========================================================
(If you're using uvesafb as a module, the above three options are
- used a parameter of the scroll option, e.g. scroll=ypan.)
+used a parameter of the scroll option, e.g. scroll=ypan.)
-vgapal Use the standard VGA registers for palette changes.
+=========== ====================================================================
+vgapal Use the standard VGA registers for palette changes.
-pmipal Use the protected mode interface for palette changes.
- This is the default if the protected mode interface is
- available. Available on x86 only.
+pmipal Use the protected mode interface for palette changes.
+ This is the default if the protected mode interface is
+ available. Available on x86 only.
-mtrr:n Setup memory type range registers for the framebuffer
- where n:
- 0 - disabled (equivalent to nomtrr)
- 3 - write-combining (default)
+mtrr:n Setup memory type range registers for the framebuffer
+ where n:
- Values other than 0 and 3 will result in a warning and will be
- treated just like 3.
+ - 0 - disabled (equivalent to nomtrr)
+ - 3 - write-combining (default)
-nomtrr Do not use memory type range registers.
+ Values other than 0 and 3 will result in a warning and will be
+ treated just like 3.
+
+nomtrr Do not use memory type range registers.
vremap:n
- Remap 'n' MiB of video RAM. If 0 or not specified, remap memory
- according to video mode.
+ Remap 'n' MiB of video RAM. If 0 or not specified, remap memory
+ according to video mode.
-vtotal:n
- If the video BIOS of your card incorrectly determines the total
- amount of video RAM, use this option to override the BIOS (in MiB).
+vtotal:n If the video BIOS of your card incorrectly determines the total
+ amount of video RAM, use this option to override the BIOS (in MiB).
-<mode> The mode you want to set, in the standard modedb format. Refer to
- modedb.txt for a detailed description. When uvesafb is compiled as
- a module, the mode string should be provided as a value of the
- 'mode_option' option.
+<mode> The mode you want to set, in the standard modedb format. Refer to
+ modedb.txt for a detailed description. When uvesafb is compiled as
+ a module, the mode string should be provided as a value of the
+ 'mode_option' option.
-vbemode:x
- Force the use of VBE mode x. The mode will only be set if it's
- found in the VBE-provided list of supported modes.
- NOTE: The mode number 'x' should be specified in VESA mode number
- notation, not the Linux kernel one (eg. 257 instead of 769).
- HINT: If you use this option because normal <mode> parameter does
- not work for you and you use a X server, you'll probably want to
- set the 'nocrtc' option to ensure that the video mode is properly
- restored after console <-> X switches.
+vbemode:x Force the use of VBE mode x. The mode will only be set if it's
+ found in the VBE-provided list of supported modes.
+ NOTE: The mode number 'x' should be specified in VESA mode number
+ notation, not the Linux kernel one (eg. 257 instead of 769).
+ HINT: If you use this option because normal <mode> parameter does
+ not work for you and you use a X server, you'll probably want to
+ set the 'nocrtc' option to ensure that the video mode is properly
+ restored after console <-> X switches.
-nocrtc Do not use CRTC timings while setting the video mode. This option
- has any effect only if the Video BIOS is VBE 3.0 compliant. Use it
- if you have problems with modes set the standard way. Note that
- using this option implies that any refresh rate adjustments will
- be ignored and the refresh rate will stay at your BIOS default (60 Hz).
+nocrtc Do not use CRTC timings while setting the video mode. This option
+ has any effect only if the Video BIOS is VBE 3.0 compliant. Use it
+ if you have problems with modes set the standard way. Note that
+ using this option implies that any refresh rate adjustments will
+ be ignored and the refresh rate will stay at your BIOS default
+ (60 Hz).
-noedid Do not try to fetch and use EDID-provided modes.
+noedid Do not try to fetch and use EDID-provided modes.
-noblank Disable hardware blanking.
+noblank Disable hardware blanking.
-v86d:path
- Set path to the v86d executable. This option is only available as
- a module parameter, and not as a part of the video= string. If you
- need to use it and have uvesafb built into the kernel, use
- uvesafb.v86d="path".
+v86d:path Set path to the v86d executable. This option is only available as
+ a module parameter, and not as a part of the video= string. If you
+ need to use it and have uvesafb built into the kernel, use
+ uvesafb.v86d="path".
+=========== ====================================================================
Additionally, the following parameters may be provided. They all override the
EDID-provided values and BIOS defaults. Refer to your monitor's specs to get
the correct values for maxhf, maxvf and maxclk for your hardware.
+=========== ======================================
maxhf:n Maximum horizontal frequency (in kHz).
maxvf:n Maximum vertical frequency (in Hz).
maxclk:n Maximum pixel clock (in MHz).
+=========== ======================================
4. The sysfs interface
----------------------
@@ -146,27 +151,26 @@ additional information.
Driver attributes:
/sys/bus/platform/drivers/uvesafb
- - v86d (default: /sbin/v86d)
+ v86d
+ (default: /sbin/v86d)
+
Path to the v86d executable. v86d is started by uvesafb
if an instance of the daemon isn't already running.
Device attributes:
/sys/bus/platform/drivers/uvesafb/uvesafb.0
- - nocrtc
+ nocrtc
Use the default refresh rate (60 Hz) if set to 1.
- - oem_product_name
- - oem_product_rev
- - oem_string
- - oem_vendor
+ oem_product_name, oem_product_rev, oem_string, oem_vendor
Information about the card and its maker.
- - vbe_modes
+ vbe_modes
A list of video modes supported by the Video BIOS along with their
VBE mode numbers in hex.
- - vbe_version
+ vbe_version
A BCD value indicating the implemented VBE standard.
5. Miscellaneous
@@ -176,9 +180,9 @@ Uvesafb will set a video mode with the default refresh rate and timings
from the Video BIOS if you set pixclock to 0 in fb_var_screeninfo.
---
+
Michal Januszewski <spock@gentoo.org>
+
Last updated: 2017-10-10
Documentation of the uvesafb options is loosely based on vesafb.txt.
-
diff --git a/Documentation/fb/vesafb.txt b/Documentation/fb/vesafb.rst
similarity index 57%
rename from Documentation/fb/vesafb.txt
rename to Documentation/fb/vesafb.rst
index 413bb73235be..2ed0dfb661cf 100644
--- a/Documentation/fb/vesafb.txt
+++ b/Documentation/fb/vesafb.rst
@@ -1,4 +1,4 @@
-
+===============
What is vesafb?
===============
@@ -40,30 +40,35 @@ The graphic modes are NOT in the list which you get if you boot with
vga=ask and hit return. The mode you wish to use is derived from the
VESA mode number. Here are those VESA mode numbers:
- | 640x480 800x600 1024x768 1280x1024
-----+-------------------------------------
-256 | 0x101 0x103 0x105 0x107
-32k | 0x110 0x113 0x116 0x119
-64k | 0x111 0x114 0x117 0x11A
-16M | 0x112 0x115 0x118 0x11B
+====== ======= ======= ======== =========
+colors 640x480 800x600 1024x768 1280x1024
+====== ======= ======= ======== =========
+256 0x101 0x103 0x105 0x107
+32k 0x110 0x113 0x116 0x119
+64k 0x111 0x114 0x117 0x11A
+16M 0x112 0x115 0x118 0x11B
+====== ======= ======= ======== =========
+
The video mode number of the Linux kernel is the VESA mode number plus
-0x200.
-
+0x200:
+
Linux_kernel_mode_number = VESA_mode_number + 0x200
So the table for the Kernel mode numbers are:
- | 640x480 800x600 1024x768 1280x1024
-----+-------------------------------------
-256 | 0x301 0x303 0x305 0x307
-32k | 0x310 0x313 0x316 0x319
-64k | 0x311 0x314 0x317 0x31A
-16M | 0x312 0x315 0x318 0x31B
+====== ======= ======= ======== =========
+colors 640x480 800x600 1024x768 1280x1024
+====== ======= ======= ======== =========
+256 0x301 0x303 0x305 0x307
+32k 0x310 0x313 0x316 0x319
+64k 0x311 0x314 0x317 0x31A
+16M 0x312 0x315 0x318 0x31B
+====== ======= ======= ======== =========
To enable one of those modes you have to specify "vga=ask" in the
lilo.conf file and rerun LILO. Then you can type in the desired
-mode at the "vga=ask" prompt. For example if you like to use
+mode at the "vga=ask" prompt. For example if you like to use
1024x768x256 colors you have to say "305" at this prompt.
If this does not work, this might be because your BIOS does not support
@@ -72,10 +77,10 @@ Even if your board does, it might be the BIOS which does not. VESA BIOS
Extensions v2.0 are required, 1.2 is NOT sufficient. You will get a
"bad mode number" message if something goes wrong.
-1. Note: LILO cannot handle hex, for booting directly with
- "vga=mode-number" you have to transform the numbers to decimal.
+1. Note: LILO cannot handle hex, for booting directly with
+ "vga=mode-number" you have to transform the numbers to decimal.
2. Note: Some newer versions of LILO appear to work with those hex values,
- if you set the 0x in front of the numbers.
+ if you set the 0x in front of the numbers.
X11
===
@@ -120,62 +125,68 @@ Accepted options:
inverse use inverse color map
-ypan enable display panning using the VESA protected mode
- interface. The visible screen is just a window of the
- video memory, console scrolling is done by changing the
- start of the window.
- pro: * scrolling (fullscreen) is fast, because there is
+========= ======================================================================
+ypan enable display panning using the VESA protected mode
+ interface. The visible screen is just a window of the
+ video memory, console scrolling is done by changing the
+ start of the window.
+
+ pro:
+
+ * scrolling (fullscreen) is fast, because there is
no need to copy around data.
* You'll get scrollback (the Shift-PgUp thing),
the video memory can be used as scrollback buffer
- kontra: * scrolling only parts of the screen causes some
+
+ kontra:
+
+ * scrolling only parts of the screen causes some
ugly flicker effects (boot logo flickers for
example).
-ywrap Same as ypan, but assumes your gfx board can wrap-around
- the video memory (i.e. starts reading from top if it
- reaches the end of video memory). Faster than ypan.
+ywrap Same as ypan, but assumes your gfx board can wrap-around
+ the video memory (i.e. starts reading from top if it
+ reaches the end of video memory). Faster than ypan.
-redraw scroll by redrawing the affected part of the screen, this
- is the safe (and slow) default.
+redraw Scroll by redrawing the affected part of the screen, this
+ is the safe (and slow) default.
-vgapal Use the standard vga registers for palette changes.
- This is the default.
-pmipal Use the protected mode interface for palette changes.
+vgapal Use the standard vga registers for palette changes.
+ This is the default.
+pmipal Use the protected mode interface for palette changes.
-mtrr:n setup memory type range registers for the vesafb framebuffer
- where n:
- 0 - disabled (equivalent to nomtrr) (default)
- 1 - uncachable
- 2 - write-back
- 3 - write-combining
- 4 - write-through
+mtrr:n Setup memory type range registers for the vesafb framebuffer
+ where n:
- If you see the following in dmesg, choose the type that matches the
- old one. In this example, use "mtrr:2".
+ - 0 - disabled (equivalent to nomtrr) (default)
+ - 1 - uncachable
+ - 2 - write-back
+ - 3 - write-combining
+ - 4 - write-through
+
+ If you see the following in dmesg, choose the type that matches the
+ old one. In this example, use "mtrr:2".
...
-mtrr: type mismatch for e0000000,8000000 old: write-back new: write-combining
+mtrr: type mismatch for e0000000,8000000 old: write-back new:
+ write-combining
...
-nomtrr disable mtrr
+nomtrr disable mtrr
vremap:n
- remap 'n' MiB of video RAM. If 0 or not specified, remap memory
- according to video mode. (2.5.66 patch/idea by Antonino Daplas
- reversed to give override possibility (allocate more fb memory
- than the kernel would) to 2.4 by tmb@iki.fi)
+ Remap 'n' MiB of video RAM. If 0 or not specified, remap memory
+ according to video mode. (2.5.66 patch/idea by Antonino Daplas
+ reversed to give override possibility (allocate more fb memory
+ than the kernel would) to 2.4 by tmb@iki.fi)
-vtotal:n
- if the video BIOS of your card incorrectly determines the total
- amount of video RAM, use this option to override the BIOS (in MiB).
+vtotal:n If the video BIOS of your card incorrectly determines the total
+ amount of video RAM, use this option to override the BIOS (in MiB).
+========= ======================================================================
Have fun!
- Gerd
-
---
Gerd Knorr <kraxel@goldbach.in-berlin.de>
-Minor (mostly typo) changes
+Minor (mostly typo) changes
by Nico Schmoigl <schmoigl@rumms.uni-mannheim.de>
diff --git a/Documentation/fb/viafb.rst b/Documentation/fb/viafb.rst
new file mode 100644
index 000000000000..8eb7a3bb068c
--- /dev/null
+++ b/Documentation/fb/viafb.rst
@@ -0,0 +1,297 @@
+=======================================================
+VIA Integration Graphic Chip Console Framebuffer Driver
+=======================================================
+
+Platform
+--------
+ The console framebuffer driver is for graphics chips of
+ VIA UniChrome Family
+ (CLE266, PM800 / CN400 / CN300,
+ P4M800CE / P4M800Pro / CN700 / VN800,
+ CX700 / VX700, K8M890, P4M890,
+ CN896 / P4M900, VX800, VX855)
+
+Driver features
+---------------
+ Device: CRT, LCD, DVI
+
+ Support viafb_mode::
+
+ CRT:
+ 640x480(60, 75, 85, 100, 120 Hz), 720x480(60 Hz),
+ 720x576(60 Hz), 800x600(60, 75, 85, 100, 120 Hz),
+ 848x480(60 Hz), 856x480(60 Hz), 1024x512(60 Hz),
+ 1024x768(60, 75, 85, 100 Hz), 1152x864(75 Hz),
+ 1280x768(60 Hz), 1280x960(60 Hz), 1280x1024(60, 75, 85 Hz),
+ 1440x1050(60 Hz), 1600x1200(60, 75 Hz), 1280x720(60 Hz),
+ 1920x1080(60 Hz), 1400x1050(60 Hz), 800x480(60 Hz)
+
+ color depth: 8 bpp, 16 bpp, 32 bpp supports.
+
+ Support 2D hardware accelerator.
+
+Using the viafb module
+----------------------
+ Start viafb with default settings::
+
+ #modprobe viafb
+
+ Start viafb with user options::
+
+ #modprobe viafb viafb_mode=800x600 viafb_bpp=16 viafb_refresh=60
+ viafb_active_dev=CRT+DVI viafb_dvi_port=DVP1
+ viafb_mode1=1024x768 viafb_bpp=16 viafb_refresh1=60
+ viafb_SAMM_ON=1
+
+ viafb_mode:
+ - 640x480 (default)
+ - 720x480
+ - 800x600
+ - 1024x768
+
+ viafb_bpp:
+ - 8, 16, 32 (default:32)
+
+ viafb_refresh:
+ - 60, 75, 85, 100, 120 (default:60)
+
+ viafb_lcd_dsp_method:
+ - 0 : expansion (default)
+ - 1 : centering
+
+ viafb_lcd_mode:
+ 0 : LCD panel with LSB data format input (default)
+ 1 : LCD panel with MSB data format input
+
+ viafb_lcd_panel_id:
+ - 0 : Resolution: 640x480, Channel: single, Dithering: Enable
+ - 1 : Resolution: 800x600, Channel: single, Dithering: Enable
+ - 2 : Resolution: 1024x768, Channel: single, Dithering: Enable (default)
+ - 3 : Resolution: 1280x768, Channel: single, Dithering: Enable
+ - 4 : Resolution: 1280x1024, Channel: dual, Dithering: Enable
+ - 5 : Resolution: 1400x1050, Channel: dual, Dithering: Enable
+ - 6 : Resolution: 1600x1200, Channel: dual, Dithering: Enable
+
+ - 8 : Resolution: 800x480, Channel: single, Dithering: Enable
+ - 9 : Resolution: 1024x768, Channel: dual, Dithering: Enable
+ - 10: Resolution: 1024x768, Channel: single, Dithering: Disable
+ - 11: Resolution: 1024x768, Channel: dual, Dithering: Disable
+ - 12: Resolution: 1280x768, Channel: single, Dithering: Disable
+ - 13: Resolution: 1280x1024, Channel: dual, Dithering: Disable
+ - 14: Resolution: 1400x1050, Channel: dual, Dithering: Disable
+ - 15: Resolution: 1600x1200, Channel: dual, Dithering: Disable
+ - 16: Resolution: 1366x768, Channel: single, Dithering: Disable
+ - 17: Resolution: 1024x600, Channel: single, Dithering: Enable
+ - 18: Resolution: 1280x768, Channel: dual, Dithering: Enable
+ - 19: Resolution: 1280x800, Channel: single, Dithering: Enable
+
+ viafb_accel:
+ - 0 : No 2D Hardware Acceleration
+ - 1 : 2D Hardware Acceleration (default)
+
+ viafb_SAMM_ON:
+ - 0 : viafb_SAMM_ON disable (default)
+ - 1 : viafb_SAMM_ON enable
+
+ viafb_mode1: (secondary display device)
+ - 640x480 (default)
+ - 720x480
+ - 800x600
+ - 1024x768
+
+ viafb_bpp1: (secondary display device)
+ - 8, 16, 32 (default:32)
+
+ viafb_refresh1: (secondary display device)
+ - 60, 75, 85, 100, 120 (default:60)
+
+ viafb_active_dev:
+ This option is used to specify active devices.(CRT, DVI, CRT+LCD...)
+ DVI stands for DVI or HDMI, E.g., If you want to enable HDMI,
+ set viafb_active_dev=DVI. In SAMM case, the previous of
+ viafb_active_dev is primary device, and the following is
+ secondary device.
+
+ For example:
+
+ To enable one device, such as DVI only, we can use::
+
+ modprobe viafb viafb_active_dev=DVI
+
+ To enable two devices, such as CRT+DVI::
+
+ modprobe viafb viafb_active_dev=CRT+DVI;
+
+ For DuoView case, we can use::
+
+ modprobe viafb viafb_active_dev=CRT+DVI
+
+ OR::
+
+ modprobe viafb viafb_active_dev=DVI+CRT...
+
+ For SAMM case:
+
+ If CRT is primary and DVI is secondary, we should use::
+
+ modprobe viafb viafb_active_dev=CRT+DVI viafb_SAMM_ON=1...
+
+ If DVI is primary and CRT is secondary, we should use::
+
+ modprobe viafb viafb_active_dev=DVI+CRT viafb_SAMM_ON=1...
+
+ viafb_display_hardware_layout:
+ This option is used to specify display hardware layout for CX700 chip.
+
+ - 1 : LCD only
+ - 2 : DVI only
+ - 3 : LCD+DVI (default)
+ - 4 : LCD1+LCD2 (internal + internal)
+ - 16: LCD1+ExternalLCD2 (internal + external)
+
+ viafb_second_size:
+ This option is used to set second device memory size(MB) in SAMM case.
+ The minimal size is 16.
+
+ viafb_platform_epia_dvi:
+ This option is used to enable DVI on EPIA - M
+
+ - 0 : No DVI on EPIA - M (default)
+ - 1 : DVI on EPIA - M
+
+ viafb_bus_width:
+ When using 24 - Bit Bus Width Digital Interface,
+ this option should be set.
+
+ - 12: 12-Bit LVDS or 12-Bit TMDS (default)
+ - 24: 24-Bit LVDS or 24-Bit TMDS
+
+ viafb_device_lcd_dualedge:
+ When using Dual Edge Panel, this option should be set.
+
+ - 0 : No Dual Edge Panel (default)
+ - 1 : Dual Edge Panel
+
+ viafb_lcd_port:
+ This option is used to specify LCD output port,
+ available values are "DVP0" "DVP1" "DFP_HIGHLOW" "DFP_HIGH" "DFP_LOW".
+
+ for external LCD + external DVI on CX700(External LCD is on DVP0),
+ we should use::
+
+ modprobe viafb viafb_lcd_port=DVP0...
+
+Notes:
+ 1. CRT may not display properly for DuoView CRT & DVI display at
+ the "640x480" PAL mode with DVI overscan enabled.
+ 2. SAMM stands for single adapter multi monitors. It is different from
+ multi-head since SAMM support multi monitor at driver layers, thus fbcon
+ layer doesn't even know about it; SAMM's second screen doesn't have a
+ device node file, thus a user mode application can't access it directly.
+ When SAMM is enabled, viafb_mode and viafb_mode1, viafb_bpp and
+ viafb_bpp1, viafb_refresh and viafb_refresh1 can be different.
+ 3. When console is depending on viafbinfo1, dynamically change resolution
+ and bpp, need to call VIAFB specified ioctl interface VIAFB_SET_DEVICE
+ instead of calling common ioctl function FBIOPUT_VSCREENINFO since
+ viafb doesn't support multi-head well, or it will cause screen crush.
+
+
+Configure viafb with "fbset" tool
+---------------------------------
+
+ "fbset" is an inbox utility of Linux.
+
+ 1. Inquire current viafb information, type::
+
+ # fbset -i
+
+ 2. Set various resolutions and viafb_refresh rates::
+
+ # fbset <resolution-vertical_sync>
+
+ example::
+
+ # fbset "1024x768-75"
+
+ or::
+
+ # fbset -g 1024 768 1024 768 32
+
+ Check the file "/etc/fb.modes" to find display modes available.
+
+ 3. Set the color depth::
+
+ # fbset -depth <value>
+
+ example::
+
+ # fbset -depth 16
+
+
+Configure viafb via /proc
+-------------------------
+ The following files exist in /proc/viafb
+
+ supported_output_devices
+ This read-only file contains a full ',' separated list containing all
+ output devices that could be available on your platform. It is likely
+ that not all of those have a connector on your hardware but it should
+ provide a good starting point to figure out which of those names match
+ a real connector.
+
+ Example::
+
+ # cat /proc/viafb/supported_output_devices
+
+ iga1/output_devices, iga2/output_devices
+ These two files are readable and writable. iga1 and iga2 are the two
+ independent units that produce the screen image. Those images can be
+ forwarded to one or more output devices. Reading those files is a way
+ to query which output devices are currently used by an iga.
+
+ Example::
+
+ # cat /proc/viafb/iga1/output_devices
+
+ If there are no output devices printed the output of this iga is lost.
+ This can happen for example if only one (the other) iga is used.
+ Writing to these files allows adjusting the output devices during
+ runtime. One can add new devices, remove existing ones or switch
+ between igas. Essentially you can write a ',' separated list of device
+ names (or a single one) in the same format as the output to those
+ files. You can add a '+' or '-' as a prefix allowing simple addition
+ and removal of devices. So a prefix '+' adds the devices from your list
+ to the already existing ones, '-' removes the listed devices from the
+ existing ones and if no prefix is given it replaces all existing ones
+ with the listed ones. If you remove devices they are expected to turn
+ off. If you add devices that are already part of the other iga they are
+ removed there and added to the new one.
+
+ Examples:
+
+ Add CRT as output device to iga1::
+
+ # echo +CRT > /proc/viafb/iga1/output_devices
+
+ Remove (turn off) DVP1 and LVDS1 as output devices of iga2::
+
+ # echo -DVP1,LVDS1 > /proc/viafb/iga2/output_devices
+
+ Replace all iga1 output devices by CRT::
+
+ # echo CRT > /proc/viafb/iga1/output_devices
+
+
+Bootup with viafb
+-----------------
+
+Add the following line to your grub.conf::
+
+ append = "video=viafb:viafb_mode=1024x768,viafb_bpp=32,viafb_refresh=85"
+
+
+VIA Framebuffer modes
+=====================
+
+.. include:: viafb.modes
+ :literal:
diff --git a/Documentation/fb/viafb.txt b/Documentation/fb/viafb.txt
deleted file mode 100644
index 1cb2462a71ce..000000000000
--- a/Documentation/fb/viafb.txt
+++ /dev/null
@@ -1,252 +0,0 @@
-
- VIA Integration Graphic Chip Console Framebuffer Driver
-
-[Platform]
------------------------
- The console framebuffer driver is for graphics chips of
- VIA UniChrome Family(CLE266, PM800 / CN400 / CN300,
- P4M800CE / P4M800Pro / CN700 / VN800,
- CX700 / VX700, K8M890, P4M890,
- CN896 / P4M900, VX800, VX855)
-
-[Driver features]
-------------------------
- Device: CRT, LCD, DVI
-
- Support viafb_mode:
- CRT:
- 640x480(60, 75, 85, 100, 120 Hz), 720x480(60 Hz),
- 720x576(60 Hz), 800x600(60, 75, 85, 100, 120 Hz),
- 848x480(60 Hz), 856x480(60 Hz), 1024x512(60 Hz),
- 1024x768(60, 75, 85, 100 Hz), 1152x864(75 Hz),
- 1280x768(60 Hz), 1280x960(60 Hz), 1280x1024(60, 75, 85 Hz),
- 1440x1050(60 Hz), 1600x1200(60, 75 Hz), 1280x720(60 Hz),
- 1920x1080(60 Hz), 1400x1050(60 Hz), 800x480(60 Hz)
-
- color depth: 8 bpp, 16 bpp, 32 bpp supports.
-
- Support 2D hardware accelerator.
-
-[Using the viafb module]
--- -- --------------------
- Start viafb with default settings:
- #modprobe viafb
-
- Start viafb with user options:
- #modprobe viafb viafb_mode=800x600 viafb_bpp=16 viafb_refresh=60
- viafb_active_dev=CRT+DVI viafb_dvi_port=DVP1
- viafb_mode1=1024x768 viafb_bpp=16 viafb_refresh1=60
- viafb_SAMM_ON=1
-
- viafb_mode:
- 640x480 (default)
- 720x480
- 800x600
- 1024x768
- ......
-
- viafb_bpp:
- 8, 16, 32 (default:32)
-
- viafb_refresh:
- 60, 75, 85, 100, 120 (default:60)
-
- viafb_lcd_dsp_method:
- 0 : expansion (default)
- 1 : centering
-
- viafb_lcd_mode:
- 0 : LCD panel with LSB data format input (default)
- 1 : LCD panel with MSB data format input
-
- viafb_lcd_panel_id:
- 0 : Resolution: 640x480, Channel: single, Dithering: Enable
- 1 : Resolution: 800x600, Channel: single, Dithering: Enable
- 2 : Resolution: 1024x768, Channel: single, Dithering: Enable (default)
- 3 : Resolution: 1280x768, Channel: single, Dithering: Enable
- 4 : Resolution: 1280x1024, Channel: dual, Dithering: Enable
- 5 : Resolution: 1400x1050, Channel: dual, Dithering: Enable
- 6 : Resolution: 1600x1200, Channel: dual, Dithering: Enable
-
- 8 : Resolution: 800x480, Channel: single, Dithering: Enable
- 9 : Resolution: 1024x768, Channel: dual, Dithering: Enable
- 10: Resolution: 1024x768, Channel: single, Dithering: Disable
- 11: Resolution: 1024x768, Channel: dual, Dithering: Disable
- 12: Resolution: 1280x768, Channel: single, Dithering: Disable
- 13: Resolution: 1280x1024, Channel: dual, Dithering: Disable
- 14: Resolution: 1400x1050, Channel: dual, Dithering: Disable
- 15: Resolution: 1600x1200, Channel: dual, Dithering: Disable
- 16: Resolution: 1366x768, Channel: single, Dithering: Disable
- 17: Resolution: 1024x600, Channel: single, Dithering: Enable
- 18: Resolution: 1280x768, Channel: dual, Dithering: Enable
- 19: Resolution: 1280x800, Channel: single, Dithering: Enable
-
- viafb_accel:
- 0 : No 2D Hardware Acceleration
- 1 : 2D Hardware Acceleration (default)
-
- viafb_SAMM_ON:
- 0 : viafb_SAMM_ON disable (default)
- 1 : viafb_SAMM_ON enable
-
- viafb_mode1: (secondary display device)
- 640x480 (default)
- 720x480
- 800x600
- 1024x768
- ... ...
-
- viafb_bpp1: (secondary display device)
- 8, 16, 32 (default:32)
-
- viafb_refresh1: (secondary display device)
- 60, 75, 85, 100, 120 (default:60)
-
- viafb_active_dev:
- This option is used to specify active devices.(CRT, DVI, CRT+LCD...)
- DVI stands for DVI or HDMI, E.g., If you want to enable HDMI,
- set viafb_active_dev=DVI. In SAMM case, the previous of
- viafb_active_dev is primary device, and the following is
- secondary device.
-
- For example:
- To enable one device, such as DVI only, we can use:
- modprobe viafb viafb_active_dev=DVI
- To enable two devices, such as CRT+DVI:
- modprobe viafb viafb_active_dev=CRT+DVI;
-
- For DuoView case, we can use:
- modprobe viafb viafb_active_dev=CRT+DVI
- OR
- modprobe viafb viafb_active_dev=DVI+CRT...
-
- For SAMM case:
- If CRT is primary and DVI is secondary, we should use:
- modprobe viafb viafb_active_dev=CRT+DVI viafb_SAMM_ON=1...
- If DVI is primary and CRT is secondary, we should use:
- modprobe viafb viafb_active_dev=DVI+CRT viafb_SAMM_ON=1...
-
- viafb_display_hardware_layout:
- This option is used to specify display hardware layout for CX700 chip.
- 1 : LCD only
- 2 : DVI only
- 3 : LCD+DVI (default)
- 4 : LCD1+LCD2 (internal + internal)
- 16: LCD1+ExternalLCD2 (internal + external)
-
- viafb_second_size:
- This option is used to set second device memory size(MB) in SAMM case.
- The minimal size is 16.
-
- viafb_platform_epia_dvi:
- This option is used to enable DVI on EPIA - M
- 0 : No DVI on EPIA - M (default)
- 1 : DVI on EPIA - M
-
- viafb_bus_width:
- When using 24 - Bit Bus Width Digital Interface,
- this option should be set.
- 12: 12-Bit LVDS or 12-Bit TMDS (default)
- 24: 24-Bit LVDS or 24-Bit TMDS
-
- viafb_device_lcd_dualedge:
- When using Dual Edge Panel, this option should be set.
- 0 : No Dual Edge Panel (default)
- 1 : Dual Edge Panel
-
- viafb_lcd_port:
- This option is used to specify LCD output port,
- available values are "DVP0" "DVP1" "DFP_HIGHLOW" "DFP_HIGH" "DFP_LOW".
- for external LCD + external DVI on CX700(External LCD is on DVP0),
- we should use:
- modprobe viafb viafb_lcd_port=DVP0...
-
-Notes:
- 1. CRT may not display properly for DuoView CRT & DVI display at
- the "640x480" PAL mode with DVI overscan enabled.
- 2. SAMM stands for single adapter multi monitors. It is different from
- multi-head since SAMM support multi monitor at driver layers, thus fbcon
- layer doesn't even know about it; SAMM's second screen doesn't have a
- device node file, thus a user mode application can't access it directly.
- When SAMM is enabled, viafb_mode and viafb_mode1, viafb_bpp and
- viafb_bpp1, viafb_refresh and viafb_refresh1 can be different.
- 3. When console is depending on viafbinfo1, dynamically change resolution
- and bpp, need to call VIAFB specified ioctl interface VIAFB_SET_DEVICE
- instead of calling common ioctl function FBIOPUT_VSCREENINFO since
- viafb doesn't support multi-head well, or it will cause screen crush.
-
-
-[Configure viafb with "fbset" tool]
------------------------------------
- "fbset" is an inbox utility of Linux.
- 1. Inquire current viafb information, type,
- # fbset -i
-
- 2. Set various resolutions and viafb_refresh rates,
- # fbset <resolution-vertical_sync>
-
- example,
- # fbset "1024x768-75"
- or
- # fbset -g 1024 768 1024 768 32
- Check the file "/etc/fb.modes" to find display modes available.
-
- 3. Set the color depth,
- # fbset -depth <value>
-
- example,
- # fbset -depth 16
-
-
-[Configure viafb via /proc]
----------------------------
- The following files exist in /proc/viafb
-
- supported_output_devices
-
- This read-only file contains a full ',' separated list containing all
- output devices that could be available on your platform. It is likely
- that not all of those have a connector on your hardware but it should
- provide a good starting point to figure out which of those names match
- a real connector.
- Example:
- # cat /proc/viafb/supported_output_devices
-
- iga1/output_devices
- iga2/output_devices
-
- These two files are readable and writable. iga1 and iga2 are the two
- independent units that produce the screen image. Those images can be
- forwarded to one or more output devices. Reading those files is a way
- to query which output devices are currently used by an iga.
- Example:
- # cat /proc/viafb/iga1/output_devices
- If there are no output devices printed the output of this iga is lost.
- This can happen for example if only one (the other) iga is used.
- Writing to these files allows adjusting the output devices during
- runtime. One can add new devices, remove existing ones or switch
- between igas. Essentially you can write a ',' separated list of device
- names (or a single one) in the same format as the output to those
- files. You can add a '+' or '-' as a prefix allowing simple addition
- and removal of devices. So a prefix '+' adds the devices from your list
- to the already existing ones, '-' removes the listed devices from the
- existing ones and if no prefix is given it replaces all existing ones
- with the listed ones. If you remove devices they are expected to turn
- off. If you add devices that are already part of the other iga they are
- removed there and added to the new one.
- Examples:
- Add CRT as output device to iga1
- # echo +CRT > /proc/viafb/iga1/output_devices
-
- Remove (turn off) DVP1 and LVDS1 as output devices of iga2
- # echo -DVP1,LVDS1 > /proc/viafb/iga2/output_devices
-
- Replace all iga1 output devices by CRT
- # echo CRT > /proc/viafb/iga1/output_devices
-
-
-[Bootup with viafb]:
---------------------
- Add the following line to your grub.conf:
- append = "video=viafb:viafb_mode=1024x768,viafb_bpp=32,viafb_refresh=85"
-
diff --git a/Documentation/fb/vt8623fb.txt b/Documentation/fb/vt8623fb.rst
similarity index 85%
rename from Documentation/fb/vt8623fb.txt
rename to Documentation/fb/vt8623fb.rst
index f654576c56b7..ba1730937dd8 100644
--- a/Documentation/fb/vt8623fb.txt
+++ b/Documentation/fb/vt8623fb.rst
@@ -1,13 +1,13 @@
-
- vt8623fb - fbdev driver for graphics core in VIA VT8623 chipset
- ===============================================================
+===============================================================
+vt8623fb - fbdev driver for graphics core in VIA VT8623 chipset
+===============================================================
Supported Hardware
==================
- VIA VT8623 [CLE266] chipset and its graphics core
- (known as CastleRock or Unichrome)
+VIA VT8623 [CLE266] chipset and its graphics core
+(known as CastleRock or Unichrome)
I tested vt8623fb on VIA EPIA ML-6000
diff --git a/MAINTAINERS b/MAINTAINERS
index aa9a382d6da5..5ed1fc93969a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4808,7 +4808,7 @@ S: Maintained
W: http://plugable.com/category/projects/udlfb/
F: drivers/video/fbdev/udlfb.c
F: include/video/udlfb.h
-F: Documentation/fb/udlfb.txt
+F: Documentation/fb/udlfb.rst
DISTRIBUTED LOCK MANAGER (DLM)
M: Christine Caulfield <ccaulfie@redhat.com>
@@ -7957,7 +7957,7 @@ INTEL FRAMEBUFFER DRIVER (excluding 810 and 815)
M: Maik Broemme <mbroemme@libmpq.org>
L: linux-fbdev@vger.kernel.org
S: Maintained
-F: Documentation/fb/intelfb.txt
+F: Documentation/fb/intelfb.rst
F: drivers/video/fbdev/intelfb/
INTEL GPIO DRIVERS
@@ -14405,7 +14405,7 @@ M: Sudip Mukherjee <sudip.mukherjee@codethink.co.uk>
L: linux-fbdev@vger.kernel.org
S: Maintained
F: drivers/video/fbdev/sm712*
-F: Documentation/fb/sm712fb.txt
+F: Documentation/fb/sm712fb.rst
SIMPLE FIRMWARE INTERFACE (SFI)
M: Len Brown <lenb@kernel.org>
@@ -14475,7 +14475,7 @@ SIS FRAMEBUFFER DRIVER
M: Thomas Winischhofer <thomas@winischhofer.net>
W: http://www.winischhofer.net/linuxsisvga.shtml
S: Maintained
-F: Documentation/fb/sisfb.txt
+F: Documentation/fb/sisfb.rst
F: drivers/video/fbdev/sis/
F: include/video/sisfb.h
@@ -16682,7 +16682,7 @@ M: Michal Januszewski <spock@gentoo.org>
L: linux-fbdev@vger.kernel.org
W: https://github.com/mjanusz/v86d
S: Maintained
-F: Documentation/fb/uvesafb.txt
+F: Documentation/fb/uvesafb.rst
F: drivers/video/fbdev/uvesafb.*
VF610 NAND DRIVER
diff --git a/drivers/tty/Kconfig b/drivers/tty/Kconfig
index 3b1d312bb175..0e3e4dacbc12 100644
--- a/drivers/tty/Kconfig
+++ b/drivers/tty/Kconfig
@@ -95,7 +95,7 @@ config VT_HW_CONSOLE_BINDING
See <file:Documentation/console/console.txt> for more
information. For framebuffer console users, please refer to
- <file:Documentation/fb/fbcon.txt>.
+ <file:Documentation/fb/fbcon.rst>.
config UNIX98_PTYS
bool "Unix98 PTY support" if EXPERT
diff --git a/drivers/video/fbdev/Kconfig b/drivers/video/fbdev/Kconfig
index df4c40e28f05..2315a5b72d71 100644
--- a/drivers/video/fbdev/Kconfig
+++ b/drivers/video/fbdev/Kconfig
@@ -31,7 +31,7 @@ menuconfig FB
in the /dev directory, i.e. /dev/fb*.
You need an utility program called fbset to make full use of frame
- buffer devices. Please read <file:Documentation/fb/framebuffer.txt>
+ buffer devices. Please read <file:Documentation/fb/framebuffer.rst>
and the Framebuffer-HOWTO at
<http://www.munted.org.uk/programming/Framebuffer-HOWTO-1.3.html> for more
information.
@@ -241,7 +241,7 @@ config FB_CIRRUS
If you have a PCI-based system, this enables support for these
chips: GD-543x, GD-544x, GD-5480.
- Please read the file <file:Documentation/fb/cirrusfb.txt>.
+ Please read the file <file:Documentation/fb/cirrusfb.rst>.
Say N unless you have such a graphics board or plan to get one
before you next recompile the kernel.
@@ -615,7 +615,7 @@ config FB_UVESA
This driver generally provides more features than vesafb but
requires a userspace helper application called 'v86d'. See
- <file:Documentation/fb/uvesafb.txt> for more information.
+ <file:Documentation/fb/uvesafb.rst> for more information.
If unsure, say N.
@@ -630,7 +630,7 @@ config FB_VESA
This is the frame buffer device driver for generic VESA 2.0
compliant graphic cards. The older VESA 1.2 cards are not supported.
You will get a boot time penguin logo at no additional cost. Please
- read <file:Documentation/fb/vesafb.txt>. If unsure, say Y.
+ read <file:Documentation/fb/vesafb.rst>. If unsure, say Y.
config FB_EFI
bool "EFI-based Framebuffer Support"
@@ -828,7 +828,7 @@ config FB_PVR2
module load time. The parameters look like "video=pvr2:XXX", where
the meaning of XXX can be found at the end of the main source file
(<file:drivers/video/pvr2fb.c>). Please see the file
- <file:Documentation/fb/pvr2fb.txt>.
+ <file:Documentation/fb/pvr2fb.rst>.
config FB_OPENCORES
tristate "OpenCores VGA/LCD core 2.0 framebuffer support"
@@ -991,7 +991,7 @@ config FB_I810
module will be called i810fb.
For more information, please read
- <file:Documentation/fb/intel810.txt>
+ <file:Documentation/fb/intel810.rst>
config FB_I810_GTF
bool "use VESA Generalized Timing Formula"
@@ -1061,7 +1061,7 @@ config FB_INTEL
To compile this driver as a module, choose M here: the
module will be called intelfb.
- For more information, please read <file:Documentation/fb/intelfb.txt>
+ For more information, please read <file:Documentation/fb/intelfb.rst>
config FB_INTEL_DEBUG
bool "Intel driver Debug Messages"
@@ -1098,7 +1098,7 @@ config FB_MATROX
You can pass several parameters to the driver at boot time or at
module load time. The parameters look like "video=matroxfb:XXX", and
- are described in <file:Documentation/fb/matroxfb.txt>.
+ are described in <file:Documentation/fb/matroxfb.rst>.
config FB_MATROX_MILLENIUM
bool "Millennium I/II support"
@@ -1249,7 +1249,7 @@ config FB_ATY128
help
This driver supports graphics boards with the ATI Rage128 chips.
Say Y if you have such a graphics board and read
- <file:Documentation/fb/aty128fb.txt>.
+ <file:Documentation/fb/aty128fb.rst>.
To compile this driver as a module, choose M here: the
module will be called aty128fb.
@@ -1511,7 +1511,7 @@ config FB_VOODOO1
WARNING: Do not use any application that uses the 3D engine
(namely glide) while using this driver.
- Please read the <file:Documentation/fb/sstfb.txt> for supported
+ Please read the <file:Documentation/fb/sstfb.rst> for supported
options and other important info support.
config FB_VT8623
@@ -1543,7 +1543,7 @@ config FB_TRIDENT
There are also integrated versions of these chips called CyberXXXX,
CyberImage or CyberBlade. These chips are mostly found in laptops
but also on some motherboards including early VIA EPIA motherboards.
- For more information, read <file:Documentation/fb/tridentfb.txt>
+ For more information, read <file:Documentation/fb/tridentfb.rst>
Say Y if you have such a graphics board.
@@ -1783,7 +1783,7 @@ config FB_PXA_PARAMETERS
single model of flatpanel then you can safely leave this
option disabled.
- <file:Documentation/fb/pxafb.txt> describes the available parameters.
+ <file:Documentation/fb/pxafb.rst> describes the available parameters.
config PXA3XX_GCU
tristate "PXA3xx 2D graphics accelerator driver"
diff --git a/drivers/video/fbdev/matrox/matroxfb_base.c b/drivers/video/fbdev/matrox/matroxfb_base.c
index c76bef078c75..1a555f70923a 100644
--- a/drivers/video/fbdev/matrox/matroxfb_base.c
+++ b/drivers/video/fbdev/matrox/matroxfb_base.c
@@ -2502,7 +2502,7 @@ MODULE_PARM_DESC(nobios, "Disables ROM BIOS (0 or 1=disabled) (default=do not ch
module_param(noinit, int, 0);
MODULE_PARM_DESC(noinit, "Disables W/SG/SD-RAM and bus interface initialization (0 or 1=do not initialize) (default=0)");
module_param(memtype, int, 0);
-MODULE_PARM_DESC(memtype, "Memory type for G200/G400 (see Documentation/fb/matroxfb.txt for explanation) (default=3 for G200, 0 for G400)");
+MODULE_PARM_DESC(memtype, "Memory type for G200/G400 (see Documentation/fb/matroxfb.rst for explanation) (default=3 for G200, 0 for G400)");
module_param(mtrr, int, 0);
MODULE_PARM_DESC(mtrr, "This speeds up video memory accesses (0=disabled or 1) (default=1)");
module_param(sgram, int, 0);
diff --git a/drivers/video/fbdev/pxafb.c b/drivers/video/fbdev/pxafb.c
index d59c8a59f582..4282cb117b92 100644
--- a/drivers/video/fbdev/pxafb.c
+++ b/drivers/video/fbdev/pxafb.c
@@ -2068,7 +2068,7 @@ static int __init pxafb_setup_options(void)
#define pxafb_setup_options() (0)
module_param_string(options, g_options, sizeof(g_options), 0);
-MODULE_PARM_DESC(options, "LCD parameters (see Documentation/fb/pxafb.txt)");
+MODULE_PARM_DESC(options, "LCD parameters (see Documentation/fb/pxafb.rst)");
#endif
#else
diff --git a/drivers/video/fbdev/sh7760fb.c b/drivers/video/fbdev/sh7760fb.c
index 405715b60ec7..ab8fe838c776 100644
--- a/drivers/video/fbdev/sh7760fb.c
+++ b/drivers/video/fbdev/sh7760fb.c
@@ -6,7 +6,7 @@
* Manuel Lauss <mano@roarinelk.homelinux.net>
* (c) 2008 Nobuhiro Iwamatsu <iwamatsu.nobuhiro@renesas.com>
*
- * PLEASE HAVE A LOOK AT Documentation/fb/sh7760fb.txt!
+ * PLEASE HAVE A LOOK AT Documentation/fb/sh7760fb.rst!
*
* Thanks to Siegfried Schaefer <s.schaefer at schaefer-edv.de>
* for his original source and testing!
--
2.21.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v4 12/28] docs: kbuild: convert docs to ReST and rename to *.rst
[not found] <cover.1560361364.git.mchehab+samsung@kernel.org>
2019-06-12 17:52 ` [PATCH v4 09/28] docs: fb: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 14/28] docs: locking: " Mauro Carvalho Chehab
` (2 subsequent siblings)
4 siblings, 0 replies; 12+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: linux-wireless, linux-fbdev, Emmanuel Grumbach, Stanislaw Gruszka,
Vignesh Raghavendra, Greg Kroah-Hartman, bridge,
Benjamin Herrenschmidt, Palmer Dabbelt, alsa-devel, dri-devel,
Ofer Levi, Masahiro Yamada, Harry Wei, Paul Mackerras,
Miquel Raynal, Mauro Carvalho Chehab, linux-kbuild, linux-riscv,
Vincent Chen, Aurelien Jacquiot, Jonas Bonn, Alex Shi
The kbuild documentation clearly shows that the documents
there are written at different times: some use markdown,
some use their own peculiar logic to split sections.
Convert everything to ReST without affecting too much
the author's style and avoiding adding uneeded markups.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/README.rst | 2 +-
| 5 +-
Documentation/kbuild/index.rst | 27 +
Documentation/kbuild/issues.rst | 11 +
.../kbuild/{kbuild.txt => kbuild.rst} | 119 ++--
...nfig-language.txt => kconfig-language.rst} | 232 ++++----
...anguage.txt => kconfig-macro-language.rst} | 37 +-
.../kbuild/{kconfig.txt => kconfig.rst} | 136 +++--
.../kbuild/{makefiles.txt => makefiles.rst} | 530 +++++++++++-------
.../kbuild/{modules.txt => modules.rst} | 168 +++---
Documentation/kernel-hacking/hacking.rst | 4 +-
Documentation/process/coding-style.rst | 2 +-
Documentation/process/submit-checklist.rst | 2 +-
.../it_IT/kernel-hacking/hacking.rst | 4 +-
.../it_IT/process/coding-style.rst | 2 +-
.../it_IT/process/submit-checklist.rst | 2 +-
.../zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/process/submit-checklist.rst | 2 +-
Kconfig | 2 +-
arch/arc/plat-eznps/Kconfig | 2 +-
arch/c6x/Kconfig | 2 +-
arch/microblaze/Kconfig.debug | 2 +-
arch/microblaze/Kconfig.platform | 2 +-
arch/nds32/Kconfig | 2 +-
arch/openrisc/Kconfig | 2 +-
arch/powerpc/sysdev/Kconfig | 2 +-
arch/riscv/Kconfig | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/firmware/Kconfig | 2 +-
drivers/mtd/devices/Kconfig | 2 +-
drivers/net/ethernet/smsc/Kconfig | 6 +-
drivers/net/wireless/intel/iwlegacy/Kconfig | 4 +-
drivers/net/wireless/intel/iwlwifi/Kconfig | 2 +-
drivers/parport/Kconfig | 2 +-
drivers/scsi/Kconfig | 4 +-
drivers/staging/sm750fb/Kconfig | 2 +-
drivers/usb/misc/Kconfig | 4 +-
drivers/video/fbdev/Kconfig | 14 +-
net/bridge/netfilter/Kconfig | 2 +-
net/ipv4/netfilter/Kconfig | 2 +-
net/ipv6/netfilter/Kconfig | 2 +-
net/netfilter/Kconfig | 16 +-
net/tipc/Kconfig | 2 +-
scripts/Kbuild.include | 4 +-
scripts/Makefile.host | 2 +-
scripts/kconfig/symbol.c | 2 +-
.../tests/err_recursive_dep/expected_stderr | 14 +-
sound/oss/dmasound/Kconfig | 6 +-
48 files changed, 840 insertions(+), 561 deletions(-)
rename Documentation/kbuild/{headers_install.txt => headers_install.rst} (96%)
create mode 100644 Documentation/kbuild/index.rst
create mode 100644 Documentation/kbuild/issues.rst
rename Documentation/kbuild/{kbuild.txt => kbuild.rst} (72%)
rename Documentation/kbuild/{kconfig-language.txt => kconfig-language.rst} (85%)
rename Documentation/kbuild/{kconfig-macro-language.txt => kconfig-macro-language.rst} (94%)
rename Documentation/kbuild/{kconfig.txt => kconfig.rst} (80%)
rename Documentation/kbuild/{makefiles.txt => makefiles.rst} (83%)
rename Documentation/kbuild/{modules.txt => modules.rst} (84%)
diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst
index a582c780c3bd..cc6151fc0845 100644
--- a/Documentation/admin-guide/README.rst
+++ b/Documentation/admin-guide/README.rst
@@ -227,7 +227,7 @@ Configuring the kernel
"make tinyconfig" Configure the tiniest possible kernel.
You can find more information on using the Linux kernel config tools
- in Documentation/kbuild/kconfig.txt.
+ in Documentation/kbuild/kconfig.rst.
- NOTES on ``make config``:
diff --git a/Documentation/kbuild/headers_install.txt b/Documentation/kbuild/headers_install.rst
similarity index 96%
rename from Documentation/kbuild/headers_install.txt
rename to Documentation/kbuild/headers_install.rst
index f0153adb95e2..1ab7294e41ac 100644
--- a/Documentation/kbuild/headers_install.txt
+++ b/Documentation/kbuild/headers_install.rst
@@ -1,3 +1,4 @@
+=============================================
Exporting kernel headers for use by userspace
=============================================
@@ -22,14 +23,14 @@ older kernel.
The "make headers_install" command can be run in the top level directory of the
kernel source code (or using a standard out-of-tree build). It takes two
-optional arguments:
+optional arguments::
make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr
ARCH indicates which architecture to produce headers for, and defaults to the
current architecture. The linux/asm directory of the exported kernel headers
is platform-specific, to see a complete list of supported architectures use
-the command:
+the command::
ls -d include/asm-* | sed 's/.*-//'
diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst
new file mode 100644
index 000000000000..42d4cbe4460c
--- /dev/null
+++ b/Documentation/kbuild/index.rst
@@ -0,0 +1,27 @@
+:orphan:
+
+===================
+Kernel Build System
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ kconfig-language
+ kconfig-macro-language
+
+ kbuild
+ kconfig
+ makefiles
+ modules
+
+ headers_install
+
+ issues
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/kbuild/issues.rst b/Documentation/kbuild/issues.rst
new file mode 100644
index 000000000000..9fdded4b681c
--- /dev/null
+++ b/Documentation/kbuild/issues.rst
@@ -0,0 +1,11 @@
+Recursion issue #1
+------------------
+
+ .. include:: Kconfig.recursion-issue-01
+ :literal:
+
+Recursion issue #2
+------------------
+
+ .. include:: Kconfig.recursion-issue-02
+ :literal:
diff --git a/Documentation/kbuild/kbuild.txt b/Documentation/kbuild/kbuild.rst
similarity index 72%
rename from Documentation/kbuild/kbuild.txt
rename to Documentation/kbuild/kbuild.rst
index 9c230ea71963..e774e760522d 100644
--- a/Documentation/kbuild/kbuild.txt
+++ b/Documentation/kbuild/kbuild.rst
@@ -1,13 +1,19 @@
+======
+Kbuild
+======
+
+
Output files
+============
modules.order
---------------------------------------------------
+-------------
This file records the order in which modules appear in Makefiles. This
is used by modprobe to deterministically resolve aliases that match
multiple modules.
modules.builtin
---------------------------------------------------
+---------------
This file lists all modules that are built into the kernel. This is used
by modprobe to not fail when trying to load something builtin.
@@ -18,84 +24,90 @@ Unlike modinfo of a separate module, all fields are prefixed with module name.
Environment variables
+=====================
KCPPFLAGS
---------------------------------------------------
+---------
Additional options to pass when preprocessing. The preprocessing options
will be used in all cases where kbuild does preprocessing including
building C files and assembler files.
KAFLAGS
---------------------------------------------------
+-------
Additional options to the assembler (for built-in and modules).
AFLAGS_MODULE
---------------------------------------------------
+-------------
Additional module specific options to use for $(AS).
AFLAGS_KERNEL
---------------------------------------------------
+-------------
Additional options for $(AS) when used for assembler
code for code that is compiled as built-in.
KCFLAGS
---------------------------------------------------
+-------
Additional options to the C compiler (for built-in and modules).
CFLAGS_KERNEL
---------------------------------------------------
+-------------
Additional options for $(CC) when used to compile
code that is compiled as built-in.
CFLAGS_MODULE
---------------------------------------------------
+-------------
Additional module specific options to use for $(CC).
LDFLAGS_MODULE
---------------------------------------------------
+--------------
Additional options used for $(LD) when linking modules.
HOSTCFLAGS
---------------------------------------------------
+----------
Additional flags to be passed to $(HOSTCC) when building host programs.
HOSTCXXFLAGS
---------------------------------------------------
+------------
Additional flags to be passed to $(HOSTCXX) when building host programs.
HOSTLDFLAGS
---------------------------------------------------
+-----------
Additional flags to be passed when linking host programs.
HOSTLDLIBS
---------------------------------------------------
+----------
Additional libraries to link against when building host programs.
KBUILD_KCONFIG
---------------------------------------------------
+--------------
Set the top-level Kconfig file to the value of this environment
variable. The default name is "Kconfig".
KBUILD_VERBOSE
---------------------------------------------------
+--------------
Set the kbuild verbosity. Can be assigned same values as "V=...".
+
See make help for the full list.
+
Setting "V=..." takes precedence over KBUILD_VERBOSE.
KBUILD_EXTMOD
---------------------------------------------------
+-------------
Set the directory to look for the kernel source when building external
modules.
+
Setting "M=..." takes precedence over KBUILD_EXTMOD.
KBUILD_OUTPUT
---------------------------------------------------
+-------------
Specify the output directory when building the kernel.
+
The output directory can also be specified using "O=...".
+
Setting "O=..." takes precedence over KBUILD_OUTPUT.
KBUILD_DEBARCH
---------------------------------------------------
+--------------
For the deb-pkg target, allows overriding the normal heuristics deployed by
deb-pkg. Normally deb-pkg attempts to guess the right architecture based on
the UTS_MACHINE variable, and on some architectures also the kernel config.
@@ -103,44 +115,48 @@ The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian
architecture.
ARCH
---------------------------------------------------
+----
Set ARCH to the architecture to be built.
+
In most cases the name of the architecture is the same as the
directory name found in the arch/ directory.
+
But some architectures such as x86 and sparc have aliases.
-x86: i386 for 32 bit, x86_64 for 64 bit
-sh: sh for 32 bit, sh64 for 64 bit
-sparc: sparc32 for 32 bit, sparc64 for 64 bit
+
+- x86: i386 for 32 bit, x86_64 for 64 bit
+- sh: sh for 32 bit, sh64 for 64 bit
+- sparc: sparc32 for 32 bit, sparc64 for 64 bit
CROSS_COMPILE
---------------------------------------------------
+-------------
Specify an optional fixed part of the binutils filename.
CROSS_COMPILE can be a part of the filename or the full path.
CROSS_COMPILE is also used for ccache in some setups.
CF
---------------------------------------------------
+--
Additional options for sparse.
-CF is often used on the command-line like this:
+
+CF is often used on the command-line like this::
make CF=-Wbitwise C=2
INSTALL_PATH
---------------------------------------------------
+------------
INSTALL_PATH specifies where to place the updated kernel and system map
images. Default is /boot, but you can set it to other values.
INSTALLKERNEL
---------------------------------------------------
+-------------
Install script called when using "make install".
The default name is "installkernel".
The script will be called with the following arguments:
- $1 - kernel version
- $2 - kernel image file
- $3 - kernel map file
- $4 - default install path (use root directory if blank)
+ - $1 - kernel version
+ - $2 - kernel image file
+ - $3 - kernel map file
+ - $4 - default install path (use root directory if blank)
The implementation of "make install" is architecture specific
and it may differ from the above.
@@ -149,32 +165,33 @@ INSTALLKERNEL is provided to enable the possibility to
specify a custom installer when cross compiling a kernel.
MODLIB
---------------------------------------------------
+------
Specify where to install modules.
-The default value is:
+The default value is::
$(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE)
The value can be overridden in which case the default value is ignored.
INSTALL_MOD_PATH
---------------------------------------------------
+----------------
INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory
relocations required by build roots. This is not defined in the
makefile but the argument can be passed to make if needed.
INSTALL_MOD_STRIP
---------------------------------------------------
+-----------------
INSTALL_MOD_STRIP, if defined, will cause modules to be
stripped after they are installed. If INSTALL_MOD_STRIP is '1', then
the default option --strip-debug will be used. Otherwise,
INSTALL_MOD_STRIP value will be used as the options to the strip command.
INSTALL_HDR_PATH
---------------------------------------------------
+----------------
INSTALL_HDR_PATH specifies where to install user space headers when
executing "make headers_*".
-The default value is:
+
+The default value is::
$(objtree)/usr
@@ -184,65 +201,65 @@ The output directory is often set using "O=..." on the commandline.
The value can be overridden in which case the default value is ignored.
KBUILD_SIGN_PIN
---------------------------------------------------
+---------------
This variable allows a passphrase or PIN to be passed to the sign-file
utility when signing kernel modules, if the private key requires such.
KBUILD_MODPOST_WARN
---------------------------------------------------
+-------------------
KBUILD_MODPOST_WARN can be set to avoid errors in case of undefined
symbols in the final module linking stage. It changes such errors
into warnings.
KBUILD_MODPOST_NOFINAL
---------------------------------------------------
+----------------------
KBUILD_MODPOST_NOFINAL can be set to skip the final link of modules.
This is solely useful to speed up test compiles.
KBUILD_EXTRA_SYMBOLS
---------------------------------------------------
+--------------------
For modules that use symbols from other modules.
See more details in modules.txt.
ALLSOURCE_ARCHS
---------------------------------------------------
+---------------
For tags/TAGS/cscope targets, you can specify more than one arch
-to be included in the databases, separated by blank space. E.g.:
+to be included in the databases, separated by blank space. E.g.::
$ make ALLSOURCE_ARCHS="x86 mips arm" tags
-To get all available archs you can also specify all. E.g.:
+To get all available archs you can also specify all. E.g.::
$ make ALLSOURCE_ARCHS=all tags
KBUILD_ENABLE_EXTRA_GCC_CHECKS
---------------------------------------------------
+------------------------------
If enabled over the make command line with "W=1", it turns on additional
gcc -W... options for more extensive build-time checking.
KBUILD_BUILD_TIMESTAMP
---------------------------------------------------
+----------------------
Setting this to a date string overrides the timestamp used in the
UTS_VERSION definition (uname -v in the running kernel). The value has to
be a string that can be passed to date -d. The default value
is the output of the date command at one point during build.
KBUILD_BUILD_USER, KBUILD_BUILD_HOST
---------------------------------------------------
+------------------------------------
These two variables allow to override the user@host string displayed during
boot and in /proc/version. The default value is the output of the commands
whoami and host, respectively.
KBUILD_LDS
---------------------------------------------------
+----------
The linker script with full path. Assigned by the top-level Makefile.
KBUILD_VMLINUX_OBJS
---------------------------------------------------
+-------------------
All object files for vmlinux. They are linked to vmlinux in the same
order as listed in KBUILD_VMLINUX_OBJS.
KBUILD_VMLINUX_LIBS
---------------------------------------------------
+-------------------
All .a "lib" files for vmlinux. KBUILD_VMLINUX_OBJS and KBUILD_VMLINUX_LIBS
together specify all the object files used to link vmlinux.
diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.rst
similarity index 85%
rename from Documentation/kbuild/kconfig-language.txt
rename to Documentation/kbuild/kconfig-language.rst
index 864e740811da..2bc8a7803365 100644
--- a/Documentation/kbuild/kconfig-language.txt
+++ b/Documentation/kbuild/kconfig-language.rst
@@ -1,8 +1,12 @@
+================
+Kconfig Language
+================
+
Introduction
------------
The configuration database is a collection of configuration options
-organized in a tree structure:
+organized in a tree structure::
+- Code maturity level options
| +- Prompt for development and/or incomplete code/drivers
@@ -25,9 +29,9 @@ Menu entries
------------
Most entries define a config option; all other entries help to organize
-them. A single configuration option is defined like this:
+them. A single configuration option is defined like this::
-config MODVERSIONS
+ config MODVERSIONS
bool "Set version information on all module symbols"
depends on MODULES
help
@@ -52,10 +56,12 @@ applicable everywhere (see syntax).
Every config option must have a type. There are only two basic types:
tristate and string; the other types are based on these two. The type
definition optionally accepts an input prompt, so these two examples
- are equivalent:
+ are equivalent::
bool "Networking support"
- and
+
+ and::
+
bool
prompt "Networking support"
@@ -98,8 +104,10 @@ applicable everywhere (see syntax).
d) Hardware or infrastructure that everybody expects, such as CONFIG_NET
or CONFIG_BLOCK. These are rare exceptions.
-- type definition + default value:
+- type definition + default value::
+
"def_bool"/"def_tristate" <expr> ["if" <expr>]
+
This is a shorthand notation for a type definition plus a value.
Optionally dependencies for this default value can be added with "if".
@@ -107,11 +115,13 @@ applicable everywhere (see syntax).
This defines a dependency for this menu entry. If multiple
dependencies are defined, they are connected with '&&'. Dependencies
are applied to all other options within this menu entry (which also
- accept an "if" expression), so these two examples are equivalent:
+ accept an "if" expression), so these two examples are equivalent::
bool "foo" if BAR
default y if BAR
- and
+
+ and::
+
depends on BAR
bool "foo"
default y
@@ -124,6 +134,7 @@ applicable everywhere (see syntax).
times, the limit is set to the largest selection.
Reverse dependencies can only be used with boolean or tristate
symbols.
+
Note:
select should be used with care. select will force
a symbol to a value without visiting the dependencies.
@@ -139,24 +150,26 @@ applicable everywhere (see syntax).
symbol except that the "implied" symbol's value may still be set to n
from a direct dependency or with a visible prompt.
- Given the following example:
+ Given the following example::
- config FOO
+ config FOO
tristate
imply BAZ
- config BAZ
+ config BAZ
tristate
depends on BAR
The following values are possible:
+ === === ============= ==============
FOO BAR BAZ's default choice for BAZ
- --- --- ------------- --------------
+ === === ============= ==============
n y n N/m/y
m y m M/y/n
y y y Y/n
y n * N
+ === === ============= ==============
This is useful e.g. with multiple drivers that want to indicate their
ability to hook into a secondary subsystem while allowing the user to
@@ -208,9 +221,9 @@ Menu dependencies
Dependencies define the visibility of a menu entry and can also reduce
the input range of tristate symbols. The tristate logic used in the
expressions uses one more state than normal boolean logic to express the
-module state. Dependency expressions have the following syntax:
+module state. Dependency expressions have the following syntax::
-<expr> ::= <symbol> (1)
+ <expr> ::= <symbol> (1)
<symbol> '=' <symbol> (2)
<symbol> '!=' <symbol> (3)
<symbol1> '<' <symbol2> (4)
@@ -222,7 +235,7 @@ module state. Dependency expressions have the following syntax:
<expr> '&&' <expr> (7)
<expr> '||' <expr> (8)
-Expressions are listed in decreasing order of precedence.
+Expressions are listed in decreasing order of precedence.
(1) Convert the symbol into an expression. Boolean and tristate symbols
are simply converted into the respective expression values. All
@@ -255,15 +268,15 @@ Menu structure
--------------
The position of a menu entry in the tree is determined in two ways. First
-it can be specified explicitly:
+it can be specified explicitly::
-menu "Network device support"
+ menu "Network device support"
depends on NET
-config NETDEVICES
+ config NETDEVICES
...
-endmenu
+ endmenu
All entries within the "menu" ... "endmenu" block become a submenu of
"Network device support". All subentries inherit the dependencies from
@@ -275,17 +288,18 @@ dependencies. If a menu entry somehow depends on the previous entry, it
can be made a submenu of it. First, the previous (parent) symbol must
be part of the dependency list and then one of these two conditions
must be true:
+
- the child entry must become invisible, if the parent is set to 'n'
-- the child entry must only be visible, if the parent is visible
+- the child entry must only be visible, if the parent is visible::
-config MODULES
+ config MODULES
bool "Enable loadable module support"
-config MODVERSIONS
+ config MODVERSIONS
bool "Set version information on all module symbols"
depends on MODULES
-comment "module support disabled"
+ comment "module support disabled"
depends on !MODULES
MODVERSIONS directly depends on MODULES, this means it's only visible if
@@ -299,6 +313,7 @@ Kconfig syntax
The configuration file describes a series of menu entries, where every
line starts with a keyword (except help texts). The following keywords
end a menu entry:
+
- config
- menuconfig
- choice/endchoice
@@ -306,17 +321,17 @@ end a menu entry:
- menu/endmenu
- if/endif
- source
+
The first five also start the definition of a menu entry.
-config:
-
+config::
"config" <symbol>
<config options>
This defines a config symbol <symbol> and accepts any of above
attributes as options.
-menuconfig:
+menuconfig::
"menuconfig" <symbol>
<config options>
@@ -325,43 +340,43 @@ hint to front ends, that all suboptions should be displayed as a
separate list of options. To make sure all the suboptions will really
show up under the menuconfig entry and not outside of it, every item
from the <config options> list must depend on the menuconfig symbol.
-In practice, this is achieved by using one of the next two constructs:
+In practice, this is achieved by using one of the next two constructs::
-(1):
-menuconfig M
-if M
- config C1
- config C2
-endif
+ (1):
+ menuconfig M
+ if M
+ config C1
+ config C2
+ endif
-(2):
-menuconfig M
-config C1
- depends on M
-config C2
- depends on M
+ (2):
+ menuconfig M
+ config C1
+ depends on M
+ config C2
+ depends on M
In the following examples (3) and (4), C1 and C2 still have the M
dependency, but will not appear under menuconfig M anymore, because
-of C0, which doesn't depend on M:
+of C0, which doesn't depend on M::
-(3):
-menuconfig M
- config C0
-if M
- config C1
- config C2
-endif
+ (3):
+ menuconfig M
+ config C0
+ if M
+ config C1
+ config C2
+ endif
-(4):
-menuconfig M
-config C0
-config C1
- depends on M
-config C2
- depends on M
+ (4):
+ menuconfig M
+ config C0
+ config C1
+ depends on M
+ config C2
+ depends on M
-choices:
+choices::
"choice" [symbol]
<choice options>
@@ -387,7 +402,7 @@ definitions of that choice. If a [symbol] is associated to the choice,
then you may define the same choice (i.e. with the same entries) in another
place.
-comment:
+comment::
"comment" <prompt>
<comment options>
@@ -396,7 +411,7 @@ This defines a comment which is displayed to the user during the
configuration process and is also echoed to the output files. The only
possible options are dependencies.
-menu:
+menu::
"menu" <prompt>
<menu options>
@@ -407,7 +422,7 @@ This defines a menu block, see "Menu structure" above for more
information. The only possible options are dependencies and "visible"
attributes.
-if:
+if::
"if" <expr>
<if block>
@@ -416,13 +431,13 @@ if:
This defines an if block. The dependency expression <expr> is appended
to all enclosed menu entries.
-source:
+source::
"source" <prompt>
This reads the specified configuration file. This file is always parsed.
-mainmenu:
+mainmenu::
"mainmenu" <prompt>
@@ -452,20 +467,21 @@ that is defined in a common Kconfig file and selected by the relevant
architectures.
An example is the generic IOMAP functionality.
-We would in lib/Kconfig see:
+We would in lib/Kconfig see::
-# Generic IOMAP is used to ...
-config HAVE_GENERIC_IOMAP
+ # Generic IOMAP is used to ...
+ config HAVE_GENERIC_IOMAP
-config GENERIC_IOMAP
+ config GENERIC_IOMAP
depends on HAVE_GENERIC_IOMAP && FOO
-And in lib/Makefile we would see:
-obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
+And in lib/Makefile we would see::
-For each architecture using the generic IOMAP functionality we would see:
+ obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
-config X86
+For each architecture using the generic IOMAP functionality we would see::
+
+ config X86
select ...
select HAVE_GENERIC_IOMAP
select ...
@@ -484,25 +500,25 @@ Adding features that need compiler support
There are several features that need compiler support. The recommended way
to describe the dependency on the compiler feature is to use "depends on"
-followed by a test macro.
+followed by a test macro::
-config STACKPROTECTOR
+ config STACKPROTECTOR
bool "Stack Protector buffer overflow detection"
depends on $(cc-option,-fstack-protector)
...
If you need to expose a compiler capability to makefiles and/or C source files,
-CC_HAS_ is the recommended prefix for the config option.
+`CC_HAS_` is the recommended prefix for the config option::
-config CC_HAS_STACKPROTECTOR_NONE
+ config CC_HAS_STACKPROTECTOR_NONE
def_bool $(cc-option,-fno-stack-protector)
Build as module only
~~~~~~~~~~~~~~~~~~~~
To restrict a component build to module-only, qualify its config symbol
-with "depends on m". E.g.:
+with "depends on m". E.g.::
-config FOO
+ config FOO
depends on BAR && m
limits FOO to module (=m) or disabled (=n).
@@ -529,18 +545,18 @@ Simple Kconfig recursive issue
Read: Documentation/kbuild/Kconfig.recursion-issue-01
-Test with:
+Test with::
-make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig
+ make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig
Cumulative Kconfig recursive issue
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Read: Documentation/kbuild/Kconfig.recursion-issue-02
-Test with:
+Test with::
-make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig
+ make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig
Practical solutions to kconfig recursive issue
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -551,7 +567,9 @@ historical issues resolved through these different solutions.
a) Remove any superfluous "select FOO" or "depends on FOO"
b) Match dependency semantics:
+
b1) Swap all "select FOO" to "depends on FOO" or,
+
b2) Swap all "depends on FOO" to "select FOO"
The resolution to a) can be tested with the sample Kconfig file
@@ -566,8 +584,9 @@ Documentation/kbuild/Kconfig.recursion-issue-02.
Below is a list of examples of prior fixes for these types of recursive issues;
all errors appear to involve one or more select's and one or more "depends on".
+============ ===================================
commit fix
-====== ===
+============ ===================================
06b718c01208 select A -> depends on A
c22eacfe82f9 depends on A -> depends on B
6a91e854442c select A -> depends on A
@@ -590,6 +609,7 @@ d9f9ab51e55e select A -> depends on A
0c51a4d8abd6 depends on A -> select A (3)
e98062ed6dc4 select A -> depends on A (3)
91e5d284a7f1 select A -> (null)
+============ ===================================
(1) Partial (or no) quote of error.
(2) That seems to be the gist of that fix.
@@ -616,11 +636,11 @@ Semantics of Kconfig
~~~~~~~~~~~~~~~~~~~~
The use of Kconfig is broad, Linux is now only one of Kconfig's users:
-one study has completed a broad analysis of Kconfig use in 12 projects [0].
+one study has completed a broad analysis of Kconfig use in 12 projects [0]_.
Despite its widespread use, and although this document does a reasonable job
in documenting basic Kconfig syntax a more precise definition of Kconfig
semantics is welcomed. One project deduced Kconfig semantics through
-the use of the xconfig configurator [1]. Work should be done to confirm if
+the use of the xconfig configurator [1]_. Work should be done to confirm if
the deduced semantics matches our intended Kconfig design goals.
Having well defined semantics can be useful for tools for practical
@@ -628,42 +648,42 @@ evaluation of depenencies, for instance one such use known case was work to
express in boolean abstraction of the inferred semantics of Kconfig to
translate Kconfig logic into boolean formulas and run a SAT solver on this to
find dead code / features (always inactive), 114 dead features were found in
-Linux using this methodology [1] (Section 8: Threats to validity).
+Linux using this methodology [1]_ (Section 8: Threats to validity).
Confirming this could prove useful as Kconfig stands as one of the the leading
-industrial variability modeling languages [1] [2]. Its study would help
+industrial variability modeling languages [1]_ [2]_. Its study would help
evaluate practical uses of such languages, their use was only theoretical
and real world requirements were not well understood. As it stands though
only reverse engineering techniques have been used to deduce semantics from
-variability modeling languages such as Kconfig [3].
+variability modeling languages such as Kconfig [3]_.
-[0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
-[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
-[2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
-[3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
+.. [0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
+.. [1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
+.. [2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
+.. [3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
Full SAT solver for Kconfig
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Although SAT solvers [0] haven't yet been used by Kconfig directly, as noted in
-the previous subsection, work has been done however to express in boolean
+Although SAT solvers [4]_ haven't yet been used by Kconfig directly, as noted
+in the previous subsection, work has been done however to express in boolean
abstraction the inferred semantics of Kconfig to translate Kconfig logic into
-boolean formulas and run a SAT solver on it [1]. Another known related project
-is CADOS [2] (former VAMOS [3]) and the tools, mainly undertaker [4], which has
-been introduced first with [5]. The basic concept of undertaker is to exract
-variability models from Kconfig, and put them together with a propositional
-formula extracted from CPP #ifdefs and build-rules into a SAT solver in order
-to find dead code, dead files, and dead symbols. If using a SAT solver is
-desirable on Kconfig one approach would be to evaluate repurposing such efforts
-somehow on Kconfig. There is enough interest from mentors of existing projects
-to not only help advise how to integrate this work upstream but also help
-maintain it long term. Interested developers should visit:
+boolean formulas and run a SAT solver on it [5]_. Another known related project
+is CADOS [6]_ (former VAMOS [7]_) and the tools, mainly undertaker [8]_, which
+has been introduced first with [9]_. The basic concept of undertaker is to
+exract variability models from Kconfig, and put them together with a
+propositional formula extracted from CPP #ifdefs and build-rules into a SAT
+solver in order to find dead code, dead files, and dead symbols. If using a SAT
+solver is desirable on Kconfig one approach would be to evaluate repurposing
+such efforts somehow on Kconfig. There is enough interest from mentors of
+existing projects to not only help advise how to integrate this work upstream
+but also help maintain it long term. Interested developers should visit:
http://kernelnewbies.org/KernelProjects/kconfig-sat
-[0] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
-[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
-[2] https://cados.cs.fau.de
-[3] https://vamos.cs.fau.de
-[4] https://undertaker.cs.fau.de
-[5] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf
+.. [4] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
+.. [5] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
+.. [6] https://cados.cs.fau.de
+.. [7] https://vamos.cs.fau.de
+.. [8] https://undertaker.cs.fau.de
+.. [9] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf
diff --git a/Documentation/kbuild/kconfig-macro-language.txt b/Documentation/kbuild/kconfig-macro-language.rst
similarity index 94%
rename from Documentation/kbuild/kconfig-macro-language.txt
rename to Documentation/kbuild/kconfig-macro-language.rst
index 07da2ea68dce..35b3263b7e40 100644
--- a/Documentation/kbuild/kconfig-macro-language.txt
+++ b/Documentation/kbuild/kconfig-macro-language.rst
@@ -1,3 +1,7 @@
+======================
+Kconfig macro language
+======================
+
Concept
-------
@@ -7,7 +11,7 @@ targets and prerequisites. The other is a macro language for performing textual
substitution.
There is clear distinction between the two language stages. For example, you
-can write a makefile like follows:
+can write a makefile like follows::
APP := foo
SRC := foo.c
@@ -17,7 +21,7 @@ can write a makefile like follows:
$(CC) -o $(APP) $(SRC)
The macro language replaces the variable references with their expanded form,
-and handles as if the source file were input like follows:
+and handles as if the source file were input like follows::
foo: foo.c
gcc -o foo foo.c
@@ -26,7 +30,7 @@ Then, Make analyzes the dependency graph and determines the targets to be
updated.
The idea is quite similar in Kconfig - it is possible to describe a Kconfig
-file like this:
+file like this::
CC := gcc
@@ -34,7 +38,7 @@ file like this:
def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))
The macro language in Kconfig processes the source file into the following
-intermediate:
+intermediate::
config CC_HAS_FOO
def_bool y
@@ -69,7 +73,7 @@ variable. The righthand side of += is expanded immediately if the lefthand
side was originally defined as a simple variable. Otherwise, its evaluation is
deferred.
-The variable reference can take parameters, in the following form:
+The variable reference can take parameters, in the following form::
$(name,arg1,arg2,arg3)
@@ -141,7 +145,7 @@ Make vs Kconfig
Kconfig adopts Make-like macro language, but the function call syntax is
slightly different.
-A function call in Make looks like this:
+A function call in Make looks like this::
$(func-name arg1,arg2,arg3)
@@ -149,14 +153,14 @@ The function name and the first argument are separated by at least one
whitespace. Then, leading whitespaces are trimmed from the first argument,
while whitespaces in the other arguments are kept. You need to use a kind of
trick to start the first parameter with spaces. For example, if you want
-to make "info" function print " hello", you can write like follows:
+to make "info" function print " hello", you can write like follows::
empty :=
space := $(empty) $(empty)
$(info $(space)$(space)hello)
Kconfig uses only commas for delimiters, and keeps all whitespaces in the
-function call. Some people prefer putting a space after each comma delimiter:
+function call. Some people prefer putting a space after each comma delimiter::
$(func-name, arg1, arg2, arg3)
@@ -166,7 +170,7 @@ Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it
replaces ".c" with " .o".
In Make, a user-defined function is referenced by using a built-in function,
-'call', like this:
+'call', like this::
$(call my-func,arg1,arg2,arg3)
@@ -179,12 +183,12 @@ Likewise, $(info hello, world) prints "hello, world" to stdout. You could say
this is _useful_ inconsistency.
In Kconfig, for simpler implementation and grammatical consistency, commas that
-appear in the $( ) context are always delimiters. It means
+appear in the $( ) context are always delimiters. It means::
$(shell, echo hello, world)
is an error because it is passing two parameters where the 'shell' function
-accepts only one. To pass commas in arguments, you can use the following trick:
+accepts only one. To pass commas in arguments, you can use the following trick::
comma := ,
$(shell, echo hello$(comma) world)
@@ -195,7 +199,7 @@ Caveats
A variable (or function) cannot be expanded across tokens. So, you cannot use
a variable as a shorthand for an expression that consists of multiple tokens.
-The following works:
+The following works::
RANGE_MIN := 1
RANGE_MAX := 3
@@ -204,7 +208,7 @@ The following works:
int "foo"
range $(RANGE_MIN) $(RANGE_MAX)
-But, the following does not work:
+But, the following does not work::
RANGES := 1 3
@@ -213,7 +217,7 @@ But, the following does not work:
range $(RANGES)
A variable cannot be expanded to any keyword in Kconfig. The following does
-not work:
+not work::
MY_TYPE := tristate
@@ -223,7 +227,8 @@ not work:
Obviously from the design, $(shell command) is expanded in the textual
substitution phase. You cannot pass symbols to the 'shell' function.
-The following does not work as expected.
+
+The following does not work as expected::
config ENDIAN_FLAG
string
@@ -234,7 +239,7 @@ The following does not work as expected.
def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG)
Instead, you can do like follows so that any function call is statically
-expanded.
+expanded::
config CC_HAS_ENDIAN_FLAG
bool
diff --git a/Documentation/kbuild/kconfig.txt b/Documentation/kbuild/kconfig.rst
similarity index 80%
rename from Documentation/kbuild/kconfig.txt
rename to Documentation/kbuild/kconfig.rst
index 68c82914c0f3..88129af7e539 100644
--- a/Documentation/kbuild/kconfig.txt
+++ b/Documentation/kbuild/kconfig.rst
@@ -1,4 +1,8 @@
-This file contains some assistance for using "make *config".
+===================
+Kconfig make config
+===================
+
+This file contains some assistance for using `make *config`.
Use "make help" to list all of the possible configuration targets.
@@ -6,9 +10,8 @@ The xconfig ('qconf'), menuconfig ('mconf'), and nconfig ('nconf')
programs also have embedded help text. Be sure to check that for
navigation, search, and other general help text.
-======================================================================
General
---------------------------------------------------
+-------
New kernel releases often introduce new config symbols. Often more
important, new kernel releases may rename config symbols. When
@@ -17,51 +20,55 @@ this happens, using a previously working .config file and running
for you, so you may find that you need to see what NEW kernel
symbols have been introduced.
-To see a list of new config symbols, use
+To see a list of new config symbols, use::
cp user/some/old.config .config
make listnewconfig
and the config program will list any new symbols, one per line.
-Alternatively, you can use the brute force method:
+Alternatively, you can use the brute force method::
make oldconfig
scripts/diffconfig .config.old .config | less
-______________________________________________________________________
-Environment variables for '*config'
+----------------------------------------------------------------------
+
+Environment variables for `*config`
KCONFIG_CONFIG
---------------------------------------------------
+--------------
This environment variable can be used to specify a default kernel config
file name to override the default name of ".config".
KCONFIG_OVERWRITECONFIG
---------------------------------------------------
+-----------------------
If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not
break symlinks when .config is a symlink to somewhere else.
-CONFIG_
---------------------------------------------------
-If you set CONFIG_ in the environment, Kconfig will prefix all symbols
+`CONFIG_`
+---------
+If you set `CONFIG_` in the environment, Kconfig will prefix all symbols
with its value when saving the configuration, instead of using the default,
-"CONFIG_".
+`CONFIG_`.
+
+----------------------------------------------------------------------
-______________________________________________________________________
Environment variables for '{allyes/allmod/allno/rand}config'
KCONFIG_ALLCONFIG
---------------------------------------------------
+-----------------
(partially based on lkml email from/by Rob Landley, re: miniconfig)
+
--------------------------------------------------
+
The allyesconfig/allmodconfig/allnoconfig/randconfig variants can also
use the environment variable KCONFIG_ALLCONFIG as a flag or a filename
that contains config symbols that the user requires to be set to a
specific value. If KCONFIG_ALLCONFIG is used without a filename where
-KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", "make *config"
+KCONFIG_ALLCONFIG == "" or KCONFIG_ALLCONFIG == "1", `make *config`
checks for a file named "all{yes/mod/no/def/random}.config"
-(corresponding to the *config command that was used) for symbol values
+(corresponding to the `*config` command that was used) for symbol values
that are to be forced. If this file is not found, it checks for a
file named "all.config" to contain forced values.
@@ -74,43 +81,55 @@ This 'KCONFIG_ALLCONFIG' file is a config file which contains
(usually a subset of all) preset config symbols. These variable
settings are still subject to normal dependency checks.
-Examples:
+Examples::
+
KCONFIG_ALLCONFIG=custom-notebook.config make allnoconfig
-or
+
+or::
+
KCONFIG_ALLCONFIG=mini.config make allnoconfig
-or
+
+or::
+
make KCONFIG_ALLCONFIG=mini.config allnoconfig
These examples will disable most options (allnoconfig) but enable or
disable the options that are explicitly listed in the specified
mini-config files.
-______________________________________________________________________
+----------------------------------------------------------------------
+
Environment variables for 'randconfig'
KCONFIG_SEED
---------------------------------------------------
+------------
You can set this to the integer value used to seed the RNG, if you want
to somehow debug the behaviour of the kconfig parser/frontends.
If not set, the current time will be used.
KCONFIG_PROBABILITY
---------------------------------------------------
+-------------------
This variable can be used to skew the probabilities. This variable can
be unset or empty, or set to three different formats:
+
+ ======================= ================== =====================
KCONFIG_PROBABILITY y:n split y:m:n split
- -----------------------------------------------------------------
+ ======================= ================== =====================
unset or empty 50 : 50 33 : 33 : 34
N N : 100-N N/2 : N/2 : 100-N
[1] N:M N+M : 100-(N+M) N : M : 100-(N+M)
[2] N:M:L N : 100-N M : L : 100-(M+L)
+ ======================= ================== =====================
where N, M and L are integers (in base 10) in the range [0,100], and so
that:
+
[1] N+M is in the range [0,100]
+
[2] M+L is in the range [0,100]
-Examples:
+Examples::
+
KCONFIG_PROBABILITY=10
10% of booleans will be set to 'y', 90% to 'n'
5% of tristates will be set to 'y', 5% to 'm', 90% to 'n'
@@ -121,34 +140,36 @@ Examples:
10% of booleans will be set to 'y', 90% to 'n'
15% of tristates will be set to 'y', 15% to 'm', 70% to 'n'
-______________________________________________________________________
+----------------------------------------------------------------------
+
Environment variables for 'syncconfig'
KCONFIG_NOSILENTUPDATE
---------------------------------------------------
+----------------------
If this variable has a non-blank value, it prevents silent kernel
config updates (requires explicit updates).
KCONFIG_AUTOCONFIG
---------------------------------------------------
+------------------
This environment variable can be set to specify the path & name of the
"auto.conf" file. Its default value is "include/config/auto.conf".
KCONFIG_TRISTATE
---------------------------------------------------
+----------------
This environment variable can be set to specify the path & name of the
"tristate.conf" file. Its default value is "include/config/tristate.conf".
KCONFIG_AUTOHEADER
---------------------------------------------------
+------------------
This environment variable can be set to specify the path & name of the
"autoconf.h" (header) file.
Its default value is "include/generated/autoconf.h".
-======================================================================
+----------------------------------------------------------------------
+
menuconfig
---------------------------------------------------
+----------
SEARCHING for CONFIG symbols
@@ -158,7 +179,8 @@ Searching in menuconfig:
names, so you have to know something close to what you are
looking for.
- Example:
+ Example::
+
/hotplug
This lists all config symbols that contain "hotplug",
e.g., HOTPLUG_CPU, MEMORY_HOTPLUG.
@@ -166,48 +188,55 @@ Searching in menuconfig:
For search help, enter / followed by TAB-TAB (to highlight
<Help>) and Enter. This will tell you that you can also use
regular expressions (regexes) in the search string, so if you
- are not interested in MEMORY_HOTPLUG, you could try
+ are not interested in MEMORY_HOTPLUG, you could try::
/^hotplug
When searching, symbols are sorted thus:
+
- first, exact matches, sorted alphabetically (an exact match
is when the search matches the complete symbol name);
- then, other matches, sorted alphabetically.
+
For example: ^ATH.K matches:
+
ATH5K ATH9K ATH5K_AHB ATH5K_DEBUG [...] ATH6KL ATH6KL_DEBUG
[...] ATH9K_AHB ATH9K_BTCOEX_SUPPORT ATH9K_COMMON [...]
+
of which only ATH5K and ATH9K match exactly and so are sorted
first (and in alphabetical order), then come all other symbols,
sorted in alphabetical order.
-______________________________________________________________________
+----------------------------------------------------------------------
+
User interface options for 'menuconfig'
MENUCONFIG_COLOR
---------------------------------------------------
+----------------
It is possible to select different color themes using the variable
-MENUCONFIG_COLOR. To select a theme use:
+MENUCONFIG_COLOR. To select a theme use::
make MENUCONFIG_COLOR=<theme> menuconfig
-Available themes are:
- mono => selects colors suitable for monochrome displays
- blackbg => selects a color scheme with black background
- classic => theme with blue background. The classic look
- bluetitle => a LCD friendly version of classic. (default)
+Available themes are::
+
+ - mono => selects colors suitable for monochrome displays
+ - blackbg => selects a color scheme with black background
+ - classic => theme with blue background. The classic look
+ - bluetitle => a LCD friendly version of classic. (default)
MENUCONFIG_MODE
---------------------------------------------------
+---------------
This mode shows all sub-menus in one large tree.
-Example:
+Example::
+
make MENUCONFIG_MODE=single_menu menuconfig
+----------------------------------------------------------------------
-======================================================================
nconfig
---------------------------------------------------
+-------
nconfig is an alternate text-based configurator. It lists function
keys across the bottom of the terminal (window) that execute commands.
@@ -231,16 +260,16 @@ Searching in nconfig:
given string or regular expression (regex).
NCONFIG_MODE
---------------------------------------------------
+------------
This mode shows all sub-menus in one large tree.
-Example:
+Example::
make NCONFIG_MODE=single_menu nconfig
+----------------------------------------------------------------------
-======================================================================
xconfig
---------------------------------------------------
+-------
Searching in xconfig:
@@ -260,13 +289,12 @@ Searching in xconfig:
to return to the main menu.
-======================================================================
+----------------------------------------------------------------------
+
gconfig
---------------------------------------------------
+-------
Searching in gconfig:
There is no search command in gconfig. However, gconfig does
have several different viewing choices, modes, and options.
-
-###
diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.rst
similarity index 83%
rename from Documentation/kbuild/makefiles.txt
rename to Documentation/kbuild/makefiles.rst
index d65ad5746f94..9274cdcc9bd2 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.rst
@@ -1,8 +1,10 @@
+======================
Linux Kernel Makefiles
+======================
This document describes the Linux kernel Makefiles.
-=== Table of Contents
+.. Table of Contents
=== 1 Overview
=== 2 Who does what
@@ -54,9 +56,10 @@ This document describes the Linux kernel Makefiles.
=== 10 Credits
=== 11 TODO
-=== 1 Overview
+1 Overview
+==========
-The Makefiles have five parts:
+The Makefiles have five parts::
Makefile the top Makefile.
.config the kernel configuration file.
@@ -85,7 +88,8 @@ scripts/Makefile.* contains all the definitions/rules etc. that
are used to build the kernel based on the kbuild makefiles.
-=== 2 Who does what
+2 Who does what
+===============
People have four different relationships with the kernel Makefiles.
@@ -110,7 +114,8 @@ These people need to know about all aspects of the kernel Makefiles.
This document is aimed towards normal developers and arch developers.
-=== 3 The kbuild files
+3 The kbuild files
+==================
Most Makefiles within the kernel are kbuild Makefiles that use the
kbuild infrastructure. This chapter introduces the syntax used in the
@@ -122,7 +127,8 @@ file will be used.
Section 3.1 "Goal definitions" is a quick intro, further chapters provide
more details, with real examples.
---- 3.1 Goal definitions
+3.1 Goal definitions
+--------------------
Goal definitions are the main part (heart) of the kbuild Makefile.
These lines define the files to be built, any special compilation
@@ -130,7 +136,8 @@ more details, with real examples.
The most simple kbuild makefile contains one line:
- Example:
+ Example::
+
obj-y += foo.o
This tells kbuild that there is one object in that directory, named
@@ -139,14 +146,16 @@ more details, with real examples.
If foo.o shall be built as a module, the variable obj-m is used.
Therefore the following pattern is often used:
- Example:
+ Example::
+
obj-$(CONFIG_FOO) += foo.o
$(CONFIG_FOO) evaluates to either y (for built-in) or m (for module).
If CONFIG_FOO is neither y nor m, then the file will not be compiled
nor linked.
---- 3.2 Built-in object goals - obj-y
+3.2 Built-in object goals - obj-y
+---------------------------------
The kbuild Makefile specifies object files for vmlinux
in the $(obj-y) lists. These lists depend on the kernel
@@ -167,14 +176,16 @@ more details, with real examples.
order may e.g. change the order in which your SCSI
controllers are detected, and thus your disks are renumbered.
- Example:
+ Example::
+
#drivers/isdn/i4l/Makefile
# Makefile for the kernel ISDN subsystem and device drivers.
# Each configuration option enables a list of files.
obj-$(CONFIG_ISDN_I4L) += isdn.o
obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
---- 3.3 Loadable module goals - obj-m
+3.3 Loadable module goals - obj-m
+---------------------------------
$(obj-m) specifies object files which are built as loadable
kernel modules.
@@ -183,7 +194,8 @@ more details, with real examples.
files. In the case of one source file, the kbuild makefile
simply adds the file to $(obj-m).
- Example:
+ Example::
+
#drivers/isdn/i4l/Makefile
obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o
@@ -195,7 +207,8 @@ more details, with real examples.
module from, so you have to tell it by setting a $(<module_name>-y)
variable.
- Example:
+ Example::
+
#drivers/isdn/i4l/Makefile
obj-$(CONFIG_ISDN_I4L) += isdn.o
isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o
@@ -205,10 +218,11 @@ more details, with real examples.
"$(LD) -r" on the list of these files to generate isdn.o.
Due to kbuild recognizing $(<module_name>-y) for composite objects,
- you can use the value of a CONFIG_ symbol to optionally include an
+ you can use the value of a `CONFIG_` symbol to optionally include an
object file as part of a composite object.
- Example:
+ Example::
+
#fs/ext2/Makefile
obj-$(CONFIG_EXT2_FS) += ext2.o
ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \
@@ -225,12 +239,14 @@ more details, with real examples.
kbuild will build an ext2.o file for you out of the individual
parts and then link this into built-in.a, as you would expect.
---- 3.4 Objects which export symbols
+3.4 Objects which export symbols
+--------------------------------
No special notation is required in the makefiles for
modules exporting symbols.
---- 3.5 Library file goals - lib-y
+3.5 Library file goals - lib-y
+------------------------------
Objects listed with obj-* are used for modules, or
combined in a built-in.a for that specific directory.
@@ -247,18 +263,21 @@ more details, with real examples.
and to be part of a library. Therefore the same directory
may contain both a built-in.a and a lib.a file.
- Example:
+ Example::
+
#arch/x86/lib/Makefile
lib-y := delay.o
This will create a library lib.a based on delay.o. For kbuild to
actually recognize that there is a lib.a being built, the directory
shall be listed in libs-y.
+
See also "6.4 List directories to visit when descending".
- Use of lib-y is normally restricted to lib/ and arch/*/lib.
+ Use of lib-y is normally restricted to `lib/` and `arch/*/lib`.
---- 3.6 Descending down in directories
+3.6 Descending down in directories
+----------------------------------
A Makefile is only responsible for building objects in its own
directory. Files in subdirectories should be taken care of by
@@ -270,7 +289,8 @@ more details, with real examples.
ext2 lives in a separate directory, and the Makefile present in fs/
tells kbuild to descend down using the following assignment.
- Example:
+ Example::
+
#fs/Makefile
obj-$(CONFIG_EXT2_FS) += ext2/
@@ -281,11 +301,12 @@ more details, with real examples.
the directory, it is the Makefile in the subdirectory that
specifies what is modular and what is built-in.
- It is good practice to use a CONFIG_ variable when assigning directory
+ It is good practice to use a `CONFIG_` variable when assigning directory
names. This allows kbuild to totally skip the directory if the
- corresponding CONFIG_ option is neither 'y' nor 'm'.
+ corresponding `CONFIG_` option is neither 'y' nor 'm'.
---- 3.7 Compilation flags
+3.7 Compilation flags
+---------------------
ccflags-y, asflags-y and ldflags-y
These three flags apply only to the kbuild makefile in which they
@@ -297,7 +318,8 @@ more details, with real examples.
ccflags-y specifies options for compiling with $(CC).
- Example:
+ Example::
+
# drivers/acpi/acpica/Makefile
ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA
ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT
@@ -308,13 +330,15 @@ more details, with real examples.
asflags-y specifies options for assembling with $(AS).
- Example:
+ Example::
+
#arch/sparc/kernel/Makefile
asflags-y := -ansi
ldflags-y specifies options for linking with $(LD).
- Example:
+ Example::
+
#arch/cris/boot/compressed/Makefile
ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds
@@ -325,18 +349,19 @@ more details, with real examples.
Options specified using subdir-* are added to the commandline before
the options specified using the non-subdir variants.
- Example:
+ Example::
+
subdir-ccflags-y := -Werror
CFLAGS_$@, AFLAGS_$@
-
CFLAGS_$@ and AFLAGS_$@ only apply to commands in current
kbuild makefile.
$(CFLAGS_$@) specifies per-file options for $(CC). The $@
part has a literal value which specifies the file that it is for.
- Example:
+ Example::
+
# drivers/scsi/Makefile
CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
@@ -347,24 +372,27 @@ more details, with real examples.
$(AFLAGS_$@) is a similar feature for source files in assembly
languages.
- Example:
+ Example::
+
# arch/arm/kernel/Makefile
AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET)
AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312
AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt
---- 3.9 Dependency tracking
+3.9 Dependency tracking
+-----------------------
Kbuild tracks dependencies on the following:
- 1) All prerequisite files (both *.c and *.h)
- 2) CONFIG_ options used in all prerequisite files
+ 1) All prerequisite files (both `*.c` and `*.h`)
+ 2) `CONFIG_` options used in all prerequisite files
3) Command-line used to compile target
Thus, if you change an option to $(CC) all affected files will
be re-compiled.
---- 3.10 Special Rules
+3.10 Special Rules
+------------------
Special rules are used when the kbuild infrastructure does
not provide the required support. A typical example is
@@ -379,43 +407,47 @@ more details, with real examples.
Two variables are used when defining special rules:
- $(src)
- $(src) is a relative path which points to the directory
- where the Makefile is located. Always use $(src) when
- referring to files located in the src tree.
+ $(src)
+ $(src) is a relative path which points to the directory
+ where the Makefile is located. Always use $(src) when
+ referring to files located in the src tree.
- $(obj)
- $(obj) is a relative path which points to the directory
- where the target is saved. Always use $(obj) when
- referring to generated files.
+ $(obj)
+ $(obj) is a relative path which points to the directory
+ where the target is saved. Always use $(obj) when
+ referring to generated files.
+
+ Example::
- Example:
#drivers/scsi/Makefile
$(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl
$(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl
- This is a special rule, following the normal syntax
- required by make.
- The target file depends on two prerequisite files. References
- to the target file are prefixed with $(obj), references
- to prerequisites are referenced with $(src) (because they are not
- generated files).
-
- $(kecho)
- echoing information to user in a rule is often a good practice
- but when execution "make -s" one does not expect to see any output
- except for warnings/errors.
- To support this kbuild defines $(kecho) which will echo out the
- text following $(kecho) to stdout except if "make -s" is used.
-
- Example:
+ This is a special rule, following the normal syntax
+ required by make.
+
+ The target file depends on two prerequisite files. References
+ to the target file are prefixed with $(obj), references
+ to prerequisites are referenced with $(src) (because they are not
+ generated files).
+
+ $(kecho)
+ echoing information to user in a rule is often a good practice
+ but when execution "make -s" one does not expect to see any output
+ except for warnings/errors.
+ To support this kbuild defines $(kecho) which will echo out the
+ text following $(kecho) to stdout except if "make -s" is used.
+
+ Example::
+
#arch/blackfin/boot/Makefile
$(obj)/vmImage: $(obj)/vmlinux.gz
$(call if_changed,uimage)
@$(kecho) 'Kernel: $@ is ready'
---- 3.11 $(CC) support functions
+3.11 $(CC) support functions
+----------------------------
The kernel may be built with several different versions of
$(CC), each supporting a unique set of features and options.
@@ -425,10 +457,11 @@ more details, with real examples.
as-option
as-option is used to check if $(CC) -- when used to compile
- assembler (*.S) files -- supports the given option. An optional
+ assembler (`*.S`) files -- supports the given option. An optional
second option may be specified if the first option is not supported.
- Example:
+ Example::
+
#arch/sh/Makefile
cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),)
@@ -437,6 +470,21 @@ more details, with real examples.
The second argument is optional, and if supplied will be used
if first argument is not supported.
+ cc-ldoption
+ cc-ldoption is used to check if $(CC) when used to link object files
+ supports the given option. An optional second option may be
+ specified if first option are not supported.
+
+ Example::
+
+ #arch/x86/kernel/Makefile
+ vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv)
+
+ In the above example, vsyscall-flags will be assigned the option
+ -Wl$(comma)--hash-style=sysv if it is supported by $(CC).
+ The second argument is optional, and if supplied will be used
+ if first argument is not supported.
+
as-instr
as-instr checks if the assembler reports a specific instruction
and then outputs either option1 or option2
@@ -447,7 +495,8 @@ more details, with real examples.
cc-option is used to check if $(CC) supports a given option, and if
not supported to use an optional second option.
- Example:
+ Example::
+
#arch/x86/Makefile
cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586)
@@ -461,7 +510,8 @@ more details, with real examples.
cc-option-yn is used to check if gcc supports a given option
and return 'y' if supported, otherwise 'n'.
- Example:
+ Example::
+
#arch/ppc/Makefile
biarch := $(call cc-option-yn, -m32)
aflags-$(biarch) += -a32
@@ -479,7 +529,8 @@ more details, with real examples.
because gcc 4.4 and later accept any unknown -Wno-* option and only
warn about it if there is another warning in the source file.
- Example:
+ Example::
+
KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable)
In the above example, -Wno-unused-but-set-variable will be added to
@@ -490,7 +541,8 @@ more details, with real examples.
if version expression is true, or the fifth (if given) if the version
expression is false.
- Example:
+ Example::
+
#fs/reiserfs/Makefile
ccflags-y := $(call cc-ifversion, -lt, 0402, -O1)
@@ -515,7 +567,8 @@ more details, with real examples.
build (host arch is different from target arch). And if CROSS_COMPILE
is already set then leave it with the old value.
- Example:
+ Example::
+
#arch/m68k/Makefile
ifneq ($(SUBARCH),$(ARCH))
ifeq ($(CROSS_COMPILE),)
@@ -523,7 +576,8 @@ more details, with real examples.
endif
endif
---- 3.12 $(LD) support functions
+3.12 $(LD) support functions
+----------------------------
ld-option
ld-option is used to check if $(LD) supports the supplied option.
@@ -531,12 +585,14 @@ more details, with real examples.
The second argument is an optional option that can be used if the
first option is not supported by $(LD).
- Example:
+ Example::
+
#Makefile
LDFLAGS_vmlinux += $(call ld-option, -X)
-=== 4 Host Program support
+4 Host Program support
+======================
Kbuild supports building executables on the host for use during the
compilation stage.
@@ -550,21 +606,24 @@ This can be done in two ways. Either add the dependency in a rule,
or utilise the variable $(always).
Both possibilities are described in the following.
---- 4.1 Simple Host Program
+4.1 Simple Host Program
+-----------------------
In some cases there is a need to compile and run a program on the
computer where the build is running.
The following line tells kbuild that the program bin2hex shall be
built on the build host.
- Example:
+ Example::
+
hostprogs-y := bin2hex
Kbuild assumes in the above example that bin2hex is made from a single
c-source file named bin2hex.c located in the same directory as
the Makefile.
---- 4.2 Composite Host Programs
+4.2 Composite Host Programs
+---------------------------
Host programs can be made up based on composite objects.
The syntax used to define composite objects for host programs is
@@ -572,7 +631,8 @@ Both possibilities are described in the following.
$(<executable>-objs) lists all objects used to link the final
executable.
- Example:
+ Example::
+
#scripts/lxdialog/Makefile
hostprogs-y := lxdialog
lxdialog-objs := checklist.o lxdialog.o
@@ -580,16 +640,19 @@ Both possibilities are described in the following.
Objects with extension .o are compiled from the corresponding .c
files. In the above example, checklist.c is compiled to checklist.o
and lxdialog.c is compiled to lxdialog.o.
+
Finally, the two .o files are linked to the executable, lxdialog.
Note: The syntax <executable>-y is not permitted for host-programs.
---- 4.3 Using C++ for host programs
+4.3 Using C++ for host programs
+-------------------------------
kbuild offers support for host programs written in C++. This was
introduced solely to support kconfig, and is not recommended
for general use.
- Example:
+ Example::
+
#scripts/kconfig/Makefile
hostprogs-y := qconf
qconf-cxxobjs := qconf.o
@@ -600,13 +663,15 @@ Both possibilities are described in the following.
If qconf is composed of a mixture of .c and .cc files, then an
additional line can be used to identify this.
- Example:
+ Example::
+
#scripts/kconfig/Makefile
hostprogs-y := qconf
qconf-cxxobjs := qconf.o
qconf-objs := check.o
---- 4.4 Controlling compiler options for host programs
+4.4 Controlling compiler options for host programs
+--------------------------------------------------
When compiling host programs, it is possible to set specific flags.
The programs will always be compiled utilising $(HOSTCC) passed
@@ -614,27 +679,31 @@ Both possibilities are described in the following.
To set flags that will take effect for all host programs created
in that Makefile, use the variable HOST_EXTRACFLAGS.
- Example:
+ Example::
+
#scripts/lxdialog/Makefile
HOST_EXTRACFLAGS += -I/usr/include/ncurses
To set specific flags for a single file the following construction
is used:
- Example:
+ Example::
+
#arch/ppc64/boot/Makefile
HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE)
It is also possible to specify additional options to the linker.
- Example:
+ Example::
+
#scripts/kconfig/Makefile
HOSTLDLIBS_qconf := -L$(QTDIR)/lib
When linking qconf, it will be passed the extra option
"-L$(QTDIR)/lib".
---- 4.5 When host programs are actually built
+4.5 When host programs are actually built
+-----------------------------------------
Kbuild will only build host-programs when they are referenced
as a prerequisite.
@@ -642,7 +711,8 @@ Both possibilities are described in the following.
(1) List the prerequisite explicitly in a special rule.
- Example:
+ Example::
+
#drivers/pci/Makefile
hostprogs-y := gen-devlist
$(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist
@@ -653,11 +723,13 @@ Both possibilities are described in the following.
the host programs in special rules must be prefixed with $(obj).
(2) Use $(always)
+
When there is no suitable special rule, and the host program
shall be built when a makefile is entered, the $(always)
variable shall be used.
- Example:
+ Example::
+
#scripts/lxdialog/Makefile
hostprogs-y := lxdialog
always := $(hostprogs-y)
@@ -665,11 +737,13 @@ Both possibilities are described in the following.
This will tell kbuild to build lxdialog even if not referenced in
any rule.
---- 4.6 Using hostprogs-$(CONFIG_FOO)
+4.6 Using hostprogs-$(CONFIG_FOO)
+---------------------------------
A typical pattern in a Kbuild file looks like this:
- Example:
+ Example::
+
#scripts/Makefile
hostprogs-$(CONFIG_KALLSYMS) += kallsyms
@@ -679,7 +753,8 @@ Both possibilities are described in the following.
like hostprogs-y. But only hostprogs-y is recommended to be used
when no CONFIG symbols are involved.
-=== 5 Kbuild clean infrastructure
+5 Kbuild clean infrastructure
+=============================
"make clean" deletes most generated files in the obj tree where the kernel
is compiled. This includes generated files such as host programs.
@@ -691,7 +766,8 @@ generated by kbuild are deleted all over the kernel src tree when
Additional files can be specified in kbuild makefiles by use of $(clean-files).
- Example:
+ Example::
+
#lib/Makefile
clean-files := crc32table.h
@@ -701,7 +777,8 @@ Makefile, except if prefixed with $(objtree).
To delete a directory hierarchy use:
- Example:
+ Example::
+
#scripts/package/Makefile
clean-dirs := $(objtree)/debian/
@@ -711,7 +788,8 @@ subdirectories.
To exclude certain files from make clean, use the $(no-clean-files) variable.
This is only a special case used in the top level Kbuild file:
- Example:
+ Example::
+
#Kbuild
no-clean-files := $(bounds-file) $(offsets-file)
@@ -719,7 +797,8 @@ Usually kbuild descends down in subdirectories due to "obj-* := dir/",
but in the architecture makefiles where the kbuild infrastructure
is not sufficient this sometimes needs to be explicit.
- Example:
+ Example::
+
#arch/x86/boot/Makefile
subdir- := compressed/
@@ -729,7 +808,8 @@ directory compressed/ when "make clean" is executed.
To support the clean infrastructure in the Makefiles that build the
final bootimage there is an optional target named archclean:
- Example:
+ Example::
+
#arch/x86/Makefile
archclean:
$(Q)$(MAKE) $(clean)=arch/x86/boot
@@ -745,7 +825,8 @@ is not operational at that point.
Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will
be visited during "make clean".
-=== 6 Architecture Makefiles
+6 Architecture Makefiles
+========================
The top level Makefile sets up the environment and does the preparation,
before starting to descend down in the individual directories.
@@ -756,6 +837,7 @@ To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines
a few targets.
When kbuild executes, the following steps are followed (roughly):
+
1) Configuration of the kernel => produce .config
2) Store kernel version in include/linux/version.h
3) Updating all other prerequisites to the target prepare:
@@ -773,37 +855,45 @@ When kbuild executes, the following steps are followed (roughly):
- Preparing initrd images and the like
---- 6.1 Set variables to tweak the build to the architecture
+6.1 Set variables to tweak the build to the architecture
+--------------------------------------------------------
- LDFLAGS Generic $(LD) options
+ LDFLAGS
+ Generic $(LD) options
Flags used for all invocations of the linker.
Often specifying the emulation is sufficient.
- Example:
+ Example::
+
#arch/s390/Makefile
LDFLAGS := -m elf_s390
+
Note: ldflags-y can be used to further customise
the flags used. See chapter 3.7.
- LDFLAGS_vmlinux Options for $(LD) when linking vmlinux
+ LDFLAGS_vmlinux
+ Options for $(LD) when linking vmlinux
LDFLAGS_vmlinux is used to specify additional flags to pass to
the linker when linking the final vmlinux image.
LDFLAGS_vmlinux uses the LDFLAGS_$@ support.
- Example:
+ Example::
+
#arch/x86/Makefile
LDFLAGS_vmlinux := -e stext
- OBJCOPYFLAGS objcopy flags
+ OBJCOPYFLAGS
+ objcopy flags
When $(call if_changed,objcopy) is used to translate a .o file,
the flags specified in OBJCOPYFLAGS will be used.
$(call if_changed,objcopy) is often used to generate raw binaries on
vmlinux.
- Example:
+ Example::
+
#arch/s390/Makefile
OBJCOPYFLAGS := -O binary
@@ -814,30 +904,34 @@ When kbuild executes, the following steps are followed (roughly):
In this example, the binary $(obj)/image is a binary version of
vmlinux. The usage of $(call if_changed,xxx) will be described later.
- KBUILD_AFLAGS $(AS) assembler flags
+ KBUILD_AFLAGS
+ $(AS) assembler flags
Default value - see top level Makefile
Append or modify as required per architecture.
- Example:
+ Example::
+
#arch/sparc64/Makefile
KBUILD_AFLAGS += -m64 -mcpu=ultrasparc
- KBUILD_CFLAGS $(CC) compiler flags
+ KBUILD_CFLAGS
+ $(CC) compiler flags
Default value - see top level Makefile
Append or modify as required per architecture.
Often, the KBUILD_CFLAGS variable depends on the configuration.
- Example:
+ Example::
+
#arch/x86/boot/compressed/Makefile
cflags-$(CONFIG_X86_32) := -march=i386
cflags-$(CONFIG_X86_64) := -mcmodel=small
KBUILD_CFLAGS += $(cflags-y)
Many arch Makefiles dynamically run the target C compiler to
- probe supported options:
+ probe supported options::
#arch/x86/Makefile
@@ -853,32 +947,39 @@ When kbuild executes, the following steps are followed (roughly):
The first example utilises the trick that a config option expands
to 'y' when selected.
- KBUILD_AFLAGS_KERNEL $(AS) options specific for built-in
+ KBUILD_AFLAGS_KERNEL
+ $(AS) options specific for built-in
$(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile
resident kernel code.
- KBUILD_AFLAGS_MODULE Options for $(AS) when building modules
+ KBUILD_AFLAGS_MODULE
+ Options for $(AS) when building modules
$(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that
are used for $(AS).
+
From commandline AFLAGS_MODULE shall be used (see kbuild.txt).
- KBUILD_CFLAGS_KERNEL $(CC) options specific for built-in
+ KBUILD_CFLAGS_KERNEL
+ $(CC) options specific for built-in
$(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile
resident kernel code.
- KBUILD_CFLAGS_MODULE Options for $(CC) when building modules
+ KBUILD_CFLAGS_MODULE
+ Options for $(CC) when building modules
$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
are used for $(CC).
From commandline CFLAGS_MODULE shall be used (see kbuild.txt).
- KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules
+ KBUILD_LDFLAGS_MODULE
+ Options for $(LD) when linking modules
$(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options
used when linking modules. This is often a linker script.
+
From commandline LDFLAGS_MODULE shall be used (see kbuild.txt).
KBUILD_ARFLAGS Options for $(AR) when creating archives
@@ -894,7 +995,8 @@ When kbuild executes, the following steps are followed (roughly):
means for an architecture to override the defaults.
---- 6.2 Add prerequisites to archheaders:
+6.2 Add prerequisites to archheaders
+------------------------------------
The archheaders: rule is used to generate header files that
may be installed into user space by "make header_install" or
@@ -907,13 +1009,15 @@ When kbuild executes, the following steps are followed (roughly):
architecture itself.
---- 6.3 Add prerequisites to archprepare:
+6.3 Add prerequisites to archprepare
+------------------------------------
The archprepare: rule is used to list prerequisites that need to be
built before starting to descend down in the subdirectories.
This is usually used for header files containing assembler constants.
- Example:
+ Example::
+
#arch/arm/Makefile
archprepare: maketools
@@ -923,7 +1027,8 @@ When kbuild executes, the following steps are followed (roughly):
generating offset header files.
---- 6.4 List directories to visit when descending
+6.4 List directories to visit when descending
+---------------------------------------------
An arch Makefile cooperates with the top Makefile to define variables
which specify how to build the vmlinux file. Note that there is no
@@ -931,28 +1036,34 @@ When kbuild executes, the following steps are followed (roughly):
machinery is all architecture-independent.
- head-y, init-y, core-y, libs-y, drivers-y, net-y
+ head-y, init-y, core-y, libs-y, drivers-y, net-y
+ $(head-y) lists objects to be linked first in vmlinux.
- $(head-y) lists objects to be linked first in vmlinux.
- $(libs-y) lists directories where a lib.a archive can be located.
- The rest list directories where a built-in.a object file can be
- located.
+ $(libs-y) lists directories where a lib.a archive can be located.
- $(init-y) objects will be located after $(head-y).
- Then the rest follows in this order:
- $(core-y), $(libs-y), $(drivers-y) and $(net-y).
+ The rest list directories where a built-in.a object file can be
+ located.
- The top level Makefile defines values for all generic directories,
- and arch/$(ARCH)/Makefile only adds architecture-specific directories.
+ $(init-y) objects will be located after $(head-y).
+
+ Then the rest follows in this order:
+
+ $(core-y), $(libs-y), $(drivers-y) and $(net-y).
+
+ The top level Makefile defines values for all generic directories,
+ and arch/$(ARCH)/Makefile only adds architecture-specific
+ directories.
+
+ Example::
- Example:
#arch/sparc64/Makefile
core-y += arch/sparc64/kernel/
libs-y += arch/sparc64/prom/ arch/sparc64/lib/
drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/
---- 6.5 Architecture-specific boot images
+6.5 Architecture-specific boot images
+-------------------------------------
An arch Makefile specifies goals that take the vmlinux file, compress
it, wrap it in bootstrapping code, and copy the resulting files
@@ -970,7 +1081,8 @@ When kbuild executes, the following steps are followed (roughly):
arch/$(ARCH)/Makefile, and use the full path when calling down
into the arch/$(ARCH)/boot/Makefile.
- Example:
+ Example::
+
#arch/x86/Makefile
boot := arch/x86/boot
bzImage: vmlinux
@@ -983,7 +1095,8 @@ When kbuild executes, the following steps are followed (roughly):
but executing "make help" will list all relevant targets.
To support this, $(archhelp) must be defined.
- Example:
+ Example::
+
#arch/x86/Makefile
define archhelp
echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)'
@@ -997,25 +1110,30 @@ When kbuild executes, the following steps are followed (roughly):
Add a new prerequisite to all: to select a default goal different
from vmlinux.
- Example:
+ Example::
+
#arch/x86/Makefile
all: bzImage
When "make" is executed without arguments, bzImage will be built.
---- 6.6 Building non-kbuild targets
+6.6 Building non-kbuild targets
+-------------------------------
extra-y
-
extra-y specifies additional targets created in the current
- directory, in addition to any targets specified by obj-*.
+ directory, in addition to any targets specified by `obj-*`.
Listing all targets in extra-y is required for two purposes:
+
1) Enable kbuild to check changes in command lines
+
- When $(call if_changed,xxx) is used
+
2) kbuild knows what files to delete during "make clean"
- Example:
+ Example::
+
#arch/x86/kernel/Makefile
extra-y := head.o init_task.o
@@ -1023,16 +1141,17 @@ When kbuild executes, the following steps are followed (roughly):
shall be built, but shall not be linked as part of built-in.a.
---- 6.7 Commands useful for building a boot image
+6.7 Commands useful for building a boot image
+---------------------------------------------
- Kbuild provides a few macros that are useful when building a
- boot image.
+ Kbuild provides a few macros that are useful when building a
+ boot image.
if_changed
-
if_changed is the infrastructure used for the following commands.
- Usage:
+ Usage::
+
target: source(s) FORCE
$(call if_changed,ld/objcopy/gzip/...)
@@ -1050,12 +1169,16 @@ When kbuild executes, the following steps are followed (roughly):
Note: It is a typical mistake to forget the FORCE prerequisite.
Another common pitfall is that whitespace is sometimes
significant; for instance, the below will fail (note the extra space
- after the comma):
+ after the comma)::
+
target: source(s) FORCE
- #WRONG!# $(call if_changed, ld/objcopy/gzip/...)
- Note: if_changed should not be used more than once per target.
+ **WRONG!** $(call if_changed, ld/objcopy/gzip/...)
+
+ Note:
+ if_changed should not be used more than once per target.
It stores the executed command in a corresponding .cmd
+
file and multiple calls would result in overwrites and
unwanted results when the target is up to date and only the
tests on changed commands trigger execution of commands.
@@ -1063,7 +1186,8 @@ When kbuild executes, the following steps are followed (roughly):
ld
Link target. Often, LDFLAGS_$@ is used to set specific options to ld.
- Example:
+ Example::
+
#arch/x86/boot/Makefile
LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary
LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext
@@ -1077,12 +1201,15 @@ When kbuild executes, the following steps are followed (roughly):
LDFLAGS_$@ syntax - one for each potential target.
$(targets) are assigned all potential targets, by which kbuild knows
the targets and will:
+
1) check for commandline changes
2) delete target during make clean
The ": %: %.o" part of the prerequisite is a shorthand that
frees us from listing the setup.o and bootsect.o files.
- Note: It is a common mistake to forget the "targets :=" assignment,
+
+ Note:
+ It is a common mistake to forget the "targets :=" assignment,
resulting in the target file being recompiled for no
obvious reason.
@@ -1094,7 +1221,8 @@ When kbuild executes, the following steps are followed (roughly):
gzip
Compress target. Use maximum compression to compress target.
- Example:
+ Example::
+
#arch/x86/boot/compressed/Makefile
$(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE
$(call if_changed,gzip)
@@ -1105,26 +1233,30 @@ When kbuild executes, the following steps are followed (roughly):
in an init section in the image. Platform code *must* copy the
blob to non-init memory prior to calling unflatten_device_tree().
- To use this command, simply add *.dtb into obj-y or targets, or make
- some other target depend on %.dtb
+ To use this command, simply add `*.dtb` into obj-y or targets, or make
+ some other target depend on `%.dtb`
- A central rule exists to create $(obj)/%.dtb from $(src)/%.dts;
+ A central rule exists to create `$(obj)/%.dtb` from `$(src)/%.dts`;
architecture Makefiles do no need to explicitly write out that rule.
- Example:
+ Example::
+
targets += $(dtb-y)
DTC_FLAGS ?= -p 1024
---- 6.8 Custom kbuild commands
+6.8 Custom kbuild commands
+--------------------------
When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand
of a command is normally displayed.
To enable this behaviour for custom commands kbuild requires
- two variables to be set:
- quiet_cmd_<command> - what shall be echoed
- cmd_<command> - the command to execute
+ two variables to be set::
+
+ quiet_cmd_<command> - what shall be echoed
+ cmd_<command> - the command to execute
+
+ Example::
- Example:
#
quiet_cmd_image = BUILD $@
cmd_image = $(obj)/tools/build $(BUILDFLAGS) \
@@ -1135,9 +1267,9 @@ When kbuild executes, the following steps are followed (roughly):
$(call if_changed,image)
@echo 'Kernel: $@ is ready'
- When updating the $(obj)/bzImage target, the line
+ When updating the $(obj)/bzImage target, the line:
- BUILD arch/x86/boot/bzImage
+ BUILD arch/x86/boot/bzImage
will be displayed with "make KBUILD_VERBOSE=0".
@@ -1148,9 +1280,10 @@ When kbuild executes, the following steps are followed (roughly):
arch/$(ARCH)/kernel/vmlinux.lds is used.
The script is a preprocessed variant of the file vmlinux.lds.S
located in the same directory.
- kbuild knows .lds files and includes a rule *lds.S -> *lds.
+ kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`.
+
+ Example::
- Example:
#arch/x86/kernel/Makefile
always := vmlinux.lds
@@ -1162,17 +1295,19 @@ When kbuild executes, the following steps are followed (roughly):
The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the
specified options when building the target vmlinux.lds.
- When building the *.lds target, kbuild uses the variables:
- KBUILD_CPPFLAGS : Set in top-level Makefile
- cppflags-y : May be set in the kbuild makefile
- CPPFLAGS_$(@F) : Target-specific flags.
- Note that the full filename is used in this
- assignment.
+ When building the `*.lds` target, kbuild uses the variables::
- The kbuild infrastructure for *lds files is used in several
+ KBUILD_CPPFLAGS : Set in top-level Makefile
+ cppflags-y : May be set in the kbuild makefile
+ CPPFLAGS_$(@F) : Target-specific flags.
+ Note that the full filename is used in this
+ assignment.
+
+ The kbuild infrastructure for `*lds` files is used in several
architecture-specific files.
---- 6.10 Generic header files
+6.10 Generic header files
+-------------------------
The directory include/asm-generic contains the header files
that may be shared between individual architectures.
@@ -1180,7 +1315,8 @@ When kbuild executes, the following steps are followed (roughly):
to list the file in the Kbuild file.
See "7.2 generic-y" for further info on syntax etc.
---- 6.11 Post-link pass
+6.11 Post-link pass
+-------------------
If the file arch/xxx/Makefile.postlink exists, this makefile
will be invoked for post-link objects (vmlinux and modules.ko)
@@ -1195,15 +1331,17 @@ When kbuild executes, the following steps are followed (roughly):
For example, powerpc uses this to check relocation sanity of
the linked vmlinux file.
-=== 7 Kbuild syntax for exported headers
+7 Kbuild syntax for exported headers
+------------------------------------
The kernel includes a set of headers that is exported to userspace.
Many headers can be exported as-is but other headers require a
minimal pre-processing before they are ready for user-space.
The pre-processing does:
+
- drop kernel-specific annotations
- drop include of compiler.h
-- drop all sections that are kernel internal (guarded by ifdef __KERNEL__)
+- drop all sections that are kernel internal (guarded by `ifdef __KERNEL__`)
All headers under include/uapi/, include/generated/uapi/,
arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/
@@ -1213,40 +1351,45 @@ A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and
arch/<arch>/include/asm/ to list asm files coming from asm-generic.
See subsequent chapter for the syntax of the Kbuild file.
---- 7.1 no-export-headers
+7.1 no-export-headers
+---------------------
no-export-headers is essentially used by include/uapi/linux/Kbuild to
avoid exporting specific headers (e.g. kvm.h) on architectures that do
not support it. It should be avoided as much as possible.
---- 7.2 generic-y
+7.2 generic-y
+-------------
If an architecture uses a verbatim copy of a header from
include/asm-generic then this is listed in the file
arch/$(ARCH)/include/asm/Kbuild like this:
- Example:
+ Example::
+
#arch/x86/include/asm/Kbuild
generic-y += termios.h
generic-y += rtc.h
During the prepare phase of the build a wrapper include
- file is generated in the directory:
+ file is generated in the directory::
arch/$(ARCH)/include/generated/asm
When a header is exported where the architecture uses
the generic header a similar wrapper is generated as part
- of the set of exported headers in the directory:
+ of the set of exported headers in the directory::
usr/include/asm
The generated wrapper will in both cases look like the following:
- Example: termios.h
+ Example: termios.h::
+
#include <asm-generic/termios.h>
---- 7.3 generated-y
+7.3 generated-y
+---------------
If an architecture generates other header files alongside generic-y
wrappers, generated-y specifies them.
@@ -1254,11 +1397,13 @@ See subsequent chapter for the syntax of the Kbuild file.
This prevents them being treated as stale asm-generic wrappers and
removed.
- Example:
+ Example::
+
#arch/x86/include/asm/Kbuild
generated-y += syscalls_32.h
---- 7.4 mandatory-y
+7.4 mandatory-y
+---------------
mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild
to define the minimum set of ASM headers that all architectures must have.
@@ -1270,12 +1415,12 @@ See subsequent chapter for the syntax of the Kbuild file.
The convention is to list one subdir per line and
preferably in alphabetic order.
-=== 8 Kbuild Variables
+8 Kbuild Variables
+==================
The top Makefile exports the following variables:
VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
-
These variables define the current kernel version. A few arch
Makefiles actually use these values directly; they should use
$(KERNELRELEASE) instead.
@@ -1289,32 +1434,28 @@ The top Makefile exports the following variables:
such as "-pre4", and is often blank.
KERNELRELEASE
-
$(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
for constructing installation directory names or showing in
version strings. Some arch Makefiles use it for this purpose.
ARCH
-
This variable defines the target architecture, such as "i386",
"arm", or "sparc". Some kbuild Makefiles test $(ARCH) to
determine which files to compile.
By default, the top Makefile sets $(ARCH) to be the same as the
host system architecture. For a cross build, a user may
- override the value of $(ARCH) on the command line:
+ override the value of $(ARCH) on the command line::
make ARCH=m68k ...
INSTALL_PATH
-
This variable defines a place for the arch Makefiles to install
the resident kernel image and System.map file.
Use this for architecture-specific install targets.
INSTALL_MOD_PATH, MODLIB
-
$(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
installation. This variable is not defined in the Makefile but
may be passed in by the user if desired.
@@ -1325,7 +1466,6 @@ The top Makefile exports the following variables:
override this value on the command line if desired.
INSTALL_MOD_STRIP
-
If this variable is specified, it will cause modules to be stripped
after they are installed. If INSTALL_MOD_STRIP is '1', then the
default option --strip-debug will be used. Otherwise, the
@@ -1333,7 +1473,8 @@ The top Makefile exports the following variables:
command.
-=== 9 Makefile language
+9 Makefile language
+===================
The kernel Makefiles are designed to be run with GNU Make. The Makefiles
use only the documented features of GNU Make, but they do use many
@@ -1352,18 +1493,17 @@ time the left-hand side is used.
There are some cases where "=" is appropriate. Usually, though, ":="
is the right choice.
-=== 10 Credits
+10 Credits
+==========
-Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
-Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
-Updates by Sam Ravnborg <sam@ravnborg.org>
-Language QA by Jan Engelhardt <jengelh@gmx.de>
+- Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
+- Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
+- Updates by Sam Ravnborg <sam@ravnborg.org>
+- Language QA by Jan Engelhardt <jengelh@gmx.de>
-=== 11 TODO
+11 TODO
+=======
- Describe how kbuild supports shipped files with _shipped.
- Generating offset header files.
- Add more variables to section 7?
-
-
-
diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.rst
similarity index 84%
rename from Documentation/kbuild/modules.txt
rename to Documentation/kbuild/modules.rst
index 80295c613e37..24e763482650 100644
--- a/Documentation/kbuild/modules.txt
+++ b/Documentation/kbuild/modules.rst
@@ -1,8 +1,10 @@
+=========================
Building External Modules
+=========================
This document describes how to build an out-of-tree kernel module.
-=== Table of Contents
+.. Table of Contents
=== 1 Introduction
=== 2 How to Build External Modules
@@ -31,7 +33,8 @@ This document describes how to build an out-of-tree kernel module.
-=== 1. Introduction
+1. Introduction
+===============
"kbuild" is the build system used by the Linux kernel. Modules must use
kbuild to stay compatible with changes in the build infrastructure and
@@ -48,7 +51,8 @@ easily accomplished, and a complete example will be presented in
section 3.
-=== 2. How to Build External Modules
+2. How to Build External Modules
+================================
To build external modules, you must have a prebuilt kernel available
that contains the configuration and header files used in the build.
@@ -65,25 +69,27 @@ NOTE: "modules_prepare" will not build Module.symvers even if
CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be
executed to make module versioning work.
---- 2.1 Command Syntax
+2.1 Command Syntax
+==================
- The command to build an external module is:
+ The command to build an external module is::
$ make -C <path_to_kernel_src> M=$PWD
The kbuild system knows that an external module is being built
due to the "M=<dir>" option given in the command.
- To build against the running kernel use:
+ To build against the running kernel use::
$ make -C /lib/modules/`uname -r`/build M=$PWD
Then to install the module(s) just built, add the target
- "modules_install" to the command:
+ "modules_install" to the command::
$ make -C /lib/modules/`uname -r`/build M=$PWD modules_install
---- 2.2 Options
+2.2 Options
+===========
($KDIR refers to the path of the kernel source directory.)
@@ -100,7 +106,8 @@ executed to make module versioning work.
directory where the external module (kbuild file) is
located.
---- 2.3 Targets
+2.3 Targets
+===========
When building an external module, only a subset of the "make"
targets are available.
@@ -130,26 +137,29 @@ executed to make module versioning work.
help
List the available targets for external modules.
---- 2.4 Building Separate Files
+2.4 Building Separate Files
+===========================
It is possible to build single files that are part of a module.
This works equally well for the kernel, a module, and even for
external modules.
- Example (The module foo.ko, consist of bar.o and baz.o):
+ Example (The module foo.ko, consist of bar.o and baz.o)::
+
make -C $KDIR M=$PWD bar.lst
make -C $KDIR M=$PWD baz.o
make -C $KDIR M=$PWD foo.ko
make -C $KDIR M=$PWD ./
-=== 3. Creating a Kbuild File for an External Module
+3. Creating a Kbuild File for an External Module
+================================================
In the last section we saw the command to build a module for the
running kernel. The module is not actually built, however, because a
build file is required. Contained in this file will be the name of
the module(s) being built, along with the list of requisite source
-files. The file may be as simple as a single line:
+files. The file may be as simple as a single line::
obj-m := <module_name>.o
@@ -157,15 +167,15 @@ The kbuild system will build <module_name>.o from <module_name>.c,
and, after linking, will result in the kernel module <module_name>.ko.
The above line can be put in either a "Kbuild" file or a "Makefile."
When the module is built from multiple sources, an additional line is
-needed listing the files:
+needed listing the files::
<module_name>-y := <src1>.o <src2>.o ...
NOTE: Further documentation describing the syntax used by kbuild is
-located in Documentation/kbuild/makefiles.txt.
+located in Documentation/kbuild/makefiles.rst.
The examples below demonstrate how to create a build file for the
-module 8123.ko, which is built from the following files:
+module 8123.ko, which is built from the following files::
8123_if.c
8123_if.h
@@ -181,7 +191,8 @@ module 8123.ko, which is built from the following files:
but should be filtered out from kbuild due to possible name
clashes.
- Example 1:
+ Example 1::
+
--> filename: Makefile
ifneq ($(KERNELRELEASE),)
# kbuild part of makefile
@@ -209,14 +220,16 @@ module 8123.ko, which is built from the following files:
line; the second pass is by the kbuild system, which is
initiated by the parameterized "make" in the default target.
---- 3.2 Separate Kbuild File and Makefile
+3.2 Separate Kbuild File and Makefile
+-------------------------------------
In newer versions of the kernel, kbuild will first look for a
file named "Kbuild," and only if that is not found, will it
then look for a makefile. Utilizing a "Kbuild" file allows us
to split up the makefile from example 1 into two files:
- Example 2:
+ Example 2::
+
--> filename: Kbuild
obj-m := 8123.o
8123-y := 8123_if.o 8123_pci.o 8123_bin.o
@@ -238,7 +251,8 @@ module 8123.ko, which is built from the following files:
The next example shows a backward compatible version.
- Example 3:
+ Example 3::
+
--> filename: Kbuild
obj-m := 8123.o
8123-y := 8123_if.o 8123_pci.o 8123_bin.o
@@ -266,7 +280,8 @@ module 8123.ko, which is built from the following files:
makefiles, to be used when the "make" and kbuild parts are
split into separate files.
---- 3.3 Binary Blobs
+3.3 Binary Blobs
+----------------
Some external modules need to include an object file as a blob.
kbuild has support for this, but requires the blob file to be
@@ -277,7 +292,7 @@ module 8123.ko, which is built from the following files:
Throughout this section, 8123_bin.o_shipped has been used to
build the kernel module 8123.ko; it has been included as
- 8123_bin.o.
+ 8123_bin.o::
8123-y := 8123_if.o 8123_pci.o 8123_bin.o
@@ -285,11 +300,12 @@ module 8123.ko, which is built from the following files:
files and the binary file, kbuild will pick up different rules
when creating the object file for the module.
---- 3.4 Building Multiple Modules
+3.4 Building Multiple Modules
+=============================
kbuild supports building multiple modules with a single build
file. For example, if you wanted to build two modules, foo.ko
- and bar.ko, the kbuild lines would be:
+ and bar.ko, the kbuild lines would be::
obj-m := foo.o bar.o
foo-y := <foo_srcs>
@@ -298,7 +314,8 @@ module 8123.ko, which is built from the following files:
It is that simple!
-=== 4. Include Files
+4. Include Files
+================
Within the kernel, header files are kept in standard locations
according to the following rule:
@@ -310,22 +327,25 @@ according to the following rule:
of the kernel that are located in different directories, then
the file is placed in include/linux/.
- NOTE: There are two notable exceptions to this rule: larger
- subsystems have their own directory under include/, such as
- include/scsi; and architecture specific headers are located
- under arch/$(ARCH)/include/.
+ NOTE:
+ There are two notable exceptions to this rule: larger
+ subsystems have their own directory under include/, such as
+ include/scsi; and architecture specific headers are located
+ under arch/$(ARCH)/include/.
---- 4.1 Kernel Includes
+4.1 Kernel Includes
+-------------------
To include a header file located under include/linux/, simply
- use:
+ use::
#include <linux/module.h>
kbuild will add options to "gcc" so the relevant directories
are searched.
---- 4.2 Single Subdirectory
+4.2 Single Subdirectory
+-----------------------
External modules tend to place header files in a separate
include/ directory where their source is located, although this
@@ -334,7 +354,7 @@ according to the following rule:
Using the example from section 3, if we moved 8123_if.h to a
subdirectory named include, the resulting kbuild file would
- look like:
+ look like::
--> filename: Kbuild
obj-m := 8123.o
@@ -346,23 +366,24 @@ according to the following rule:
the path. This is a limitation of kbuild: there must be no
space present.
---- 4.3 Several Subdirectories
+4.3 Several Subdirectories
+--------------------------
kbuild can handle files that are spread over several directories.
- Consider the following example:
+ Consider the following example::
- .
- |__ src
- | |__ complex_main.c
- | |__ hal
- | |__ hardwareif.c
- | |__ include
- | |__ hardwareif.h
- |__ include
- |__ complex.h
+ .
+ |__ src
+ | |__ complex_main.c
+ | |__ hal
+ | |__ hardwareif.c
+ | |__ include
+ | |__ hardwareif.h
+ |__ include
+ |__ complex.h
To build the module complex.ko, we then need the following
- kbuild file:
+ kbuild file::
--> filename: Kbuild
obj-m := complex.o
@@ -385,7 +406,8 @@ according to the following rule:
file is located.
-=== 5. Module Installation
+5. Module Installation
+======================
Modules which are included in the kernel are installed in the
directory:
@@ -396,11 +418,12 @@ And external modules are installed in:
/lib/modules/$(KERNELRELEASE)/extra/
---- 5.1 INSTALL_MOD_PATH
+5.1 INSTALL_MOD_PATH
+--------------------
Above are the default directories but as always some level of
customization is possible. A prefix can be added to the
- installation path using the variable INSTALL_MOD_PATH:
+ installation path using the variable INSTALL_MOD_PATH::
$ make INSTALL_MOD_PATH=/frodo modules_install
=> Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/
@@ -410,20 +433,22 @@ And external modules are installed in:
calling "make." This has effect when installing both in-tree
and out-of-tree modules.
---- 5.2 INSTALL_MOD_DIR
+5.2 INSTALL_MOD_DIR
+-------------------
External modules are by default installed to a directory under
/lib/modules/$(KERNELRELEASE)/extra/, but you may wish to
locate modules for a specific functionality in a separate
directory. For this purpose, use INSTALL_MOD_DIR to specify an
- alternative name to "extra."
+ alternative name to "extra."::
$ make INSTALL_MOD_DIR=gandalf -C $KDIR \
M=$PWD modules_install
=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/
-=== 6. Module Versioning
+6. Module Versioning
+====================
Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used
as a simple ABI consistency check. A CRC value of the full prototype
@@ -435,14 +460,16 @@ module.
Module.symvers contains a list of all exported symbols from a kernel
build.
---- 6.1 Symbols From the Kernel (vmlinux + modules)
+6.1 Symbols From the Kernel (vmlinux + modules)
+-----------------------------------------------
During a kernel build, a file named Module.symvers will be
generated. Module.symvers contains all exported symbols from
the kernel and compiled modules. For each symbol, the
corresponding CRC value is also stored.
- The syntax of the Module.symvers file is:
+ The syntax of the Module.symvers file is::
+
<CRC> <Symbol> <module>
0x2d036834 scsi_remove_host drivers/scsi/scsi_mod
@@ -451,10 +478,12 @@ build.
would read 0x00000000.
Module.symvers serves two purposes:
+
1) It lists all exported symbols from vmlinux and all modules.
2) It lists the CRC if CONFIG_MODVERSIONS is enabled.
---- 6.2 Symbols and External Modules
+6.2 Symbols and External Modules
+--------------------------------
When building an external module, the build system needs access
to the symbols from the kernel to check if all external symbols
@@ -481,17 +510,17 @@ build.
foo.ko needs symbols from bar.ko, you can use a
common top-level kbuild file so both modules are
compiled in the same build. Consider the following
- directory layout:
+ directory layout::
- ./foo/ <= contains foo.ko
- ./bar/ <= contains bar.ko
+ ./foo/ <= contains foo.ko
+ ./bar/ <= contains bar.ko
- The top-level kbuild file would then look like:
+ The top-level kbuild file would then look like::
- #./Kbuild (or ./Makefile):
- obj-y := foo/ bar/
+ #./Kbuild (or ./Makefile):
+ obj-y := foo/ bar/
- And executing
+ And executing::
$ make -C $KDIR M=$PWD
@@ -518,14 +547,16 @@ build.
initialization of its symbol tables.
-=== 7. Tips & Tricks
+7. Tips & Tricks
+================
---- 7.1 Testing for CONFIG_FOO_BAR
+7.1 Testing for CONFIG_FOO_BAR
+------------------------------
- Modules often need to check for certain CONFIG_ options to
+ Modules often need to check for certain `CONFIG_` options to
decide if a specific feature is included in the module. In
- kbuild this is done by referencing the CONFIG_ variable
- directly.
+ kbuild this is done by referencing the `CONFIG_` variable
+ directly::
#fs/ext2/Makefile
obj-$(CONFIG_EXT2_FS) += ext2.o
@@ -534,8 +565,7 @@ build.
ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
External modules have traditionally used "grep" to check for
- specific CONFIG_ settings directly in .config. This usage is
+ specific `CONFIG_` settings directly in .config. This usage is
broken. As introduced before, external modules should use
kbuild for building and can therefore use the same methods as
- in-tree modules when testing for CONFIG_ definitions.
-
+ in-tree modules when testing for `CONFIG_` definitions.
diff --git a/Documentation/kernel-hacking/hacking.rst b/Documentation/kernel-hacking/hacking.rst
index d824e4feaff3..5891a701a159 100644
--- a/Documentation/kernel-hacking/hacking.rst
+++ b/Documentation/kernel-hacking/hacking.rst
@@ -718,7 +718,7 @@ make a neat patch, there's administrative work to be done:
- Usually you want a configuration option for your kernel hack. Edit
``Kconfig`` in the appropriate directory. The Config language is
simple to use by cut and paste, and there's complete documentation in
- ``Documentation/kbuild/kconfig-language.txt``.
+ ``Documentation/kbuild/kconfig-language.rst``.
In your description of the option, make sure you address both the
expert user and the user who knows nothing about your feature.
@@ -728,7 +728,7 @@ make a neat patch, there's administrative work to be done:
- Edit the ``Makefile``: the CONFIG variables are exported here so you
can usually just add a "obj-$(CONFIG_xxx) += xxx.o" line. The syntax
- is documented in ``Documentation/kbuild/makefiles.txt``.
+ is documented in ``Documentation/kbuild/makefiles.rst``.
- Put yourself in ``CREDITS`` if you've done something noteworthy,
usually beyond a single file (your name should be at the top of the
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index fa864a51e6ea..f4a2198187f9 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -686,7 +686,7 @@ filesystems) should advertise this prominently in their prompt string::
...
For full documentation on the configuration files, see the file
-Documentation/kbuild/kconfig-language.txt.
+Documentation/kbuild/kconfig-language.rst.
11) Data structures
diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
index c88867b173d9..365efc9e4aa8 100644
--- a/Documentation/process/submit-checklist.rst
+++ b/Documentation/process/submit-checklist.rst
@@ -39,7 +39,7 @@ and elsewhere regarding submitting Linux kernel patches.
6) Any new or modified ``CONFIG`` options do not muck up the config menu and
default to off unless they meet the exception criteria documented in
- ``Documentation/kbuild/kconfig-language.txt`` Menu attributes: default value.
+ ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value.
7) All new ``Kconfig`` options have help text.
diff --git a/Documentation/translations/it_IT/kernel-hacking/hacking.rst b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
index 7178e517af0a..24c592852bf1 100644
--- a/Documentation/translations/it_IT/kernel-hacking/hacking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/hacking.rst
@@ -755,7 +755,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare:
- Solitamente vorrete un'opzione di configurazione per la vostra modifica
al kernel. Modificate ``Kconfig`` nella cartella giusta. Il linguaggio
Config è facile con copia ed incolla, e c'è una completa documentazione
- nel file ``Documentation/kbuild/kconfig-language.txt``.
+ nel file ``Documentation/kbuild/kconfig-language.rst``.
Nella descrizione della vostra opzione, assicuratevi di parlare sia agli
utenti esperti sia agli utente che non sanno nulla del vostro lavoro.
@@ -767,7 +767,7 @@ anche per avere patch pulite, c'è del lavoro amministrativo da fare:
- Modificate il file ``Makefile``: le variabili CONFIG sono esportate qui,
quindi potete solitamente aggiungere una riga come la seguete
"obj-$(CONFIG_xxx) += xxx.o". La sintassi è documentata nel file
- ``Documentation/kbuild/makefiles.txt``.
+ ``Documentation/kbuild/makefiles.rst``.
- Aggiungete voi stessi in ``CREDITS`` se avete fatto qualcosa di notevole,
solitamente qualcosa che supera il singolo file (comunque il vostro nome
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index a6559d25a23d..8995d2d19f20 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -696,7 +696,7 @@ nella stringa di titolo::
...
Per la documentazione completa sui file di configurazione, consultate
-il documento Documentation/kbuild/kconfig-language.txt
+il documento Documentation/kbuild/kconfig-language.rst
11) Strutture dati
diff --git a/Documentation/translations/it_IT/process/submit-checklist.rst b/Documentation/translations/it_IT/process/submit-checklist.rst
index 70e65a7b3620..ea74cae958d7 100644
--- a/Documentation/translations/it_IT/process/submit-checklist.rst
+++ b/Documentation/translations/it_IT/process/submit-checklist.rst
@@ -43,7 +43,7 @@ sottomissione delle patch, in particolare
6) Le opzioni ``CONFIG``, nuove o modificate, non scombussolano il menu
di configurazione e sono preimpostate come disabilitate a meno che non
- soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.txt``
+ soddisfino i criteri descritti in ``Documentation/kbuild/kconfig-language.rst``
alla punto "Voci di menu: valori predefiniti".
7) Tutte le nuove opzioni ``Kconfig`` hanno un messaggio di aiuto.
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 5479c591c2f7..4f6237392e65 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -599,7 +599,7 @@ Documentation/doc-guide/ 和 scripts/kernel-doc 以获得详细信息。
depends on ADFS_FS
...
-要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。
+要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.rst。
11) 数据结构
diff --git a/Documentation/translations/zh_CN/process/submit-checklist.rst b/Documentation/translations/zh_CN/process/submit-checklist.rst
index 89061aa8fdbe..f4785d2b0491 100644
--- a/Documentation/translations/zh_CN/process/submit-checklist.rst
+++ b/Documentation/translations/zh_CN/process/submit-checklist.rst
@@ -38,7 +38,7 @@ Linux内核补丁提交清单
违规行为。
6) 任何新的或修改过的 ``CONFIG`` 选项都不会弄脏配置菜单，并默认为关闭，除非
- 它们符合 ``Documentation/kbuild/kconfig-language.txt`` 中记录的异常条件,
+ 它们符合 ``Documentation/kbuild/kconfig-language.rst`` 中记录的异常条件,
菜单属性：默认值.
7) 所有新的 ``kconfig`` 选项都有帮助文本。
diff --git a/Kconfig b/Kconfig
index 990b0c390dfc..e10b3ee084d4 100644
--- a/Kconfig
+++ b/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
mainmenu "Linux/$(ARCH) $(KERNELVERSION) Kernel Configuration"
diff --git a/arch/arc/plat-eznps/Kconfig b/arch/arc/plat-eznps/Kconfig
index 2eaecfb063a7..a376a50d3fea 100644
--- a/arch/arc/plat-eznps/Kconfig
+++ b/arch/arc/plat-eznps/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
menuconfig ARC_PLAT_EZNPS
diff --git a/arch/c6x/Kconfig b/arch/c6x/Kconfig
index eeb0471268a0..c5e6b70e1510 100644
--- a/arch/c6x/Kconfig
+++ b/arch/c6x/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
config C6X
diff --git a/arch/microblaze/Kconfig.debug b/arch/microblaze/Kconfig.debug
index 3a343188d86c..865527ac332a 100644
--- a/arch/microblaze/Kconfig.debug
+++ b/arch/microblaze/Kconfig.debug
@@ -1,6 +1,6 @@
# SPDX-License-Identifier: GPL-2.0-only
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
config TRACE_IRQFLAGS_SUPPORT
def_bool y
diff --git a/arch/microblaze/Kconfig.platform b/arch/microblaze/Kconfig.platform
index 5bf54c1d4f60..7795f90dad86 100644
--- a/arch/microblaze/Kconfig.platform
+++ b/arch/microblaze/Kconfig.platform
@@ -1,6 +1,6 @@
# SPDX-License-Identifier: GPL-2.0-only
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
# Platform selection Kconfig menu for MicroBlaze targets
#
diff --git a/arch/nds32/Kconfig b/arch/nds32/Kconfig
index 3299e287a477..fd0d0639454f 100644
--- a/arch/nds32/Kconfig
+++ b/arch/nds32/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0-only
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
config NDS32
diff --git a/arch/openrisc/Kconfig b/arch/openrisc/Kconfig
index 7cfb20555b10..bf326f0edd2f 100644
--- a/arch/openrisc/Kconfig
+++ b/arch/openrisc/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
config OPENRISC
diff --git a/arch/powerpc/sysdev/Kconfig b/arch/powerpc/sysdev/Kconfig
index e0dbec780fe9..d23288c4abf6 100644
--- a/arch/powerpc/sysdev/Kconfig
+++ b/arch/powerpc/sysdev/Kconfig
@@ -1,6 +1,6 @@
# SPDX-License-Identifier: GPL-2.0
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
config PPC4xx_PCI_EXPRESS
diff --git a/arch/riscv/Kconfig b/arch/riscv/Kconfig
index 4961deaa3b1d..376bc759b9ab 100644
--- a/arch/riscv/Kconfig
+++ b/arch/riscv/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0-only
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
config 64BIT
diff --git a/drivers/auxdisplay/Kconfig b/drivers/auxdisplay/Kconfig
index c52c738e554a..dd61fdd400f0 100644
--- a/drivers/auxdisplay/Kconfig
+++ b/drivers/auxdisplay/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
# Auxiliary display drivers configuration.
#
diff --git a/drivers/firmware/Kconfig b/drivers/firmware/Kconfig
index 9026df923542..35078c6f334a 100644
--- a/drivers/firmware/Kconfig
+++ b/drivers/firmware/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0-only
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
menu "Firmware Drivers"
diff --git a/drivers/mtd/devices/Kconfig b/drivers/mtd/devices/Kconfig
index ef0e476b2525..49abbc52457d 100644
--- a/drivers/mtd/devices/Kconfig
+++ b/drivers/mtd/devices/Kconfig
@@ -48,7 +48,7 @@ config MTD_MS02NV
If you want to compile this driver as a module ( = code which can be
inserted in and removed from the running kernel whenever you want),
- say M here and read <file:Documentation/kbuild/modules.txt>.
+ say M here and read <file:Documentation/kbuild/modules.rst>.
The module will be called ms02-nv.
config MTD_DATAFLASH
diff --git a/drivers/net/ethernet/smsc/Kconfig b/drivers/net/ethernet/smsc/Kconfig
index d1b6a78557ec..9e1c3752b200 100644
--- a/drivers/net/ethernet/smsc/Kconfig
+++ b/drivers/net/ethernet/smsc/Kconfig
@@ -49,7 +49,7 @@ config SMC91X
This driver is also available as a module ( = code which can be
inserted in and removed from the running kernel whenever you want).
The module will be called smc91x. If you want to compile it as a
- module, say M here and read <file:Documentation/kbuild/modules.txt>.
+ module, say M here and read <file:Documentation/kbuild/modules.rst>.
config PCMCIA_SMC91C92
tristate "SMC 91Cxx PCMCIA support"
@@ -86,7 +86,7 @@ config SMC911X
This driver is also available as a module. The module will be
called smc911x. If you want to compile it as a module, say M
- here and read <file:Documentation/kbuild/modules.txt>
+ here and read <file:Documentation/kbuild/modules.rst>
config SMSC911X
tristate "SMSC LAN911x/LAN921x families embedded ethernet support"
@@ -121,6 +121,6 @@ config SMSC9420
This driver is also available as a module. The module will be
called smsc9420. If you want to compile it as a module, say M
- here and read <file:Documentation/kbuild/modules.txt>
+ here and read <file:Documentation/kbuild/modules.rst>
endif # NET_VENDOR_SMSC
diff --git a/drivers/net/wireless/intel/iwlegacy/Kconfig b/drivers/net/wireless/intel/iwlegacy/Kconfig
index aa01c83e0060..e329fd7b09c0 100644
--- a/drivers/net/wireless/intel/iwlegacy/Kconfig
+++ b/drivers/net/wireless/intel/iwlegacy/Kconfig
@@ -32,7 +32,7 @@ config IWL4965
If you want to compile the driver as a module ( = code which can be
inserted in and removed from the running kernel whenever you want),
- say M here and read <file:Documentation/kbuild/modules.txt>. The
+ say M here and read <file:Documentation/kbuild/modules.rst>. The
module will be called iwl4965.
config IWL3945
@@ -58,7 +58,7 @@ config IWL3945
If you want to compile the driver as a module ( = code which can be
inserted in and removed from the running kernel whenever you want),
- say M here and read <file:Documentation/kbuild/modules.txt>. The
+ say M here and read <file:Documentation/kbuild/modules.rst>. The
module will be called iwl3945.
menu "iwl3945 / iwl4965 Debugging Options"
diff --git a/drivers/net/wireless/intel/iwlwifi/Kconfig b/drivers/net/wireless/intel/iwlwifi/Kconfig
index e5528189163f..235349a33a3c 100644
--- a/drivers/net/wireless/intel/iwlwifi/Kconfig
+++ b/drivers/net/wireless/intel/iwlwifi/Kconfig
@@ -40,7 +40,7 @@ config IWLWIFI
If you want to compile the driver as a module ( = code which can be
inserted in and removed from the running kernel whenever you want),
- say M here and read <file:Documentation/kbuild/modules.txt>. The
+ say M here and read <file:Documentation/kbuild/modules.rst>. The
module will be called iwlwifi.
if IWLWIFI
diff --git a/drivers/parport/Kconfig b/drivers/parport/Kconfig
index 24189c3399e0..1791830e7a71 100644
--- a/drivers/parport/Kconfig
+++ b/drivers/parport/Kconfig
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: GPL-2.0-only
#
# For a description of the syntax of this configuration file,
-# see Documentation/kbuild/kconfig-language.txt.
+# see Documentation/kbuild/kconfig-language.rst.
#
# Parport configuration.
#
diff --git a/drivers/scsi/Kconfig b/drivers/scsi/Kconfig
index 73bce9b6d037..75f66f8ad3ea 100644
--- a/drivers/scsi/Kconfig
+++ b/drivers/scsi/Kconfig
@@ -161,7 +161,7 @@ config CHR_DEV_SCH
If you want to compile this as a module ( = code which can be
inserted in and removed from the running kernel whenever you want),
- say M here and read <file:Documentation/kbuild/modules.txt> and
+ say M here and read <file:Documentation/kbuild/modules.rst> and
<file:Documentation/scsi/scsi.txt>. The module will be called ch.o.
If unsure, say N.
@@ -1487,7 +1487,7 @@ config ZFCP
This driver is also available as a module. This module will be
called zfcp. If you want to compile it as a module, say M here
- and read <file:Documentation/kbuild/modules.txt>.
+ and read <file:Documentation/kbuild/modules.rst>.
config SCSI_PMCRAID
tristate "PMC SIERRA Linux MaxRAID adapter support"
diff --git a/drivers/staging/sm750fb/Kconfig b/drivers/staging/sm750fb/Kconfig
index fb5a086bf9b1..8c0d8a873d5b 100644
--- a/drivers/staging/sm750fb/Kconfig
+++ b/drivers/staging/sm750fb/Kconfig
@@ -12,4 +12,4 @@ config FB_SM750
This driver is also available as a module. The module will be
called sm750fb. If you want to compile it as a module, say M
- here and read <file:Documentation/kbuild/modules.txt>.
+ here and read <file:Documentation/kbuild/modules.rst>.
diff --git a/drivers/usb/misc/Kconfig b/drivers/usb/misc/Kconfig
index c97f270338bf..4a88e1ca25c0 100644
--- a/drivers/usb/misc/Kconfig
+++ b/drivers/usb/misc/Kconfig
@@ -16,7 +16,7 @@ config USB_EMI62
This code is also available as a module ( = code which can be
inserted in and removed from the running kernel whenever you want).
The module will be called audio. If you want to compile it as a
- module, say M here and read <file:Documentation/kbuild/modules.txt>.
+ module, say M here and read <file:Documentation/kbuild/modules.rst>.
config USB_EMI26
tristate "EMI 2|6 USB Audio interface support"
@@ -67,7 +67,7 @@ config USB_LEGOTOWER
inserted in and removed from the running kernel whenever you want).
The module will be called legousbtower. If you want to compile it as
a module, say M here and read
- <file:Documentation/kbuild/modules.txt>.
+ <file:Documentation/kbuild/modules.rst>.
config USB_LCD
tristate "USB LCD driver support"
diff --git a/drivers/video/fbdev/Kconfig b/drivers/video/fbdev/Kconfig
index 2315a5b72d71..702d6d53fb55 100644
--- a/drivers/video/fbdev/Kconfig
+++ b/drivers/video/fbdev/Kconfig
@@ -289,7 +289,7 @@ config FB_ARMCLCD
If you want to compile this as a module (=code which can be
inserted into and removed from the running kernel), say M
- here and read <file:Documentation/kbuild/modules.txt>. The module
+ here and read <file:Documentation/kbuild/modules.rst>. The module
will be called amba-clcd.
config FB_ACORN
@@ -1757,7 +1757,7 @@ config FB_PXA
This driver is also available as a module ( = code which can be
inserted and removed from the running kernel whenever you want). The
module will be called pxafb. If you want to compile it as a module,
- say M here and read <file:Documentation/kbuild/modules.txt>.
+ say M here and read <file:Documentation/kbuild/modules.rst>.
If unsure, say N.
@@ -1838,7 +1838,7 @@ config FB_W100
This driver is also available as a module ( = code which can be
inserted and removed from the running kernel whenever you want). The
module will be called w100fb. If you want to compile it as a module,
- say M here and read <file:Documentation/kbuild/modules.txt>.
+ say M here and read <file:Documentation/kbuild/modules.rst>.
If unsure, say N.
@@ -1867,7 +1867,7 @@ config FB_TMIO
This driver is also available as a module ( = code which can be
inserted and removed from the running kernel whenever you want). The
module will be called tmiofb. If you want to compile it as a module,
- say M here and read <file:Documentation/kbuild/modules.txt>.
+ say M here and read <file:Documentation/kbuild/modules.rst>.
If unsure, say N.
@@ -1913,7 +1913,7 @@ config FB_S3C2410
This driver is also available as a module ( = code which can be
inserted and removed from the running kernel whenever you want). The
module will be called s3c2410fb. If you want to compile it as a module,
- say M here and read <file:Documentation/kbuild/modules.txt>.
+ say M here and read <file:Documentation/kbuild/modules.rst>.
If unsure, say N.
config FB_S3C2410_DEBUG
@@ -1950,7 +1950,7 @@ config FB_SM501
This driver is also available as a module ( = code which can be
inserted and removed from the running kernel whenever you want). The
module will be called sm501fb. If you want to compile it as a module,
- say M here and read <file:Documentation/kbuild/modules.txt>.
+ say M here and read <file:Documentation/kbuild/modules.rst>.
If unsure, say N.
@@ -2283,7 +2283,7 @@ config FB_SM712
This driver is also available as a module. The module will be
called sm712fb. If you want to compile it as a module, say M
- here and read <file:Documentation/kbuild/modules.txt>.
+ here and read <file:Documentation/kbuild/modules.rst>.
source "drivers/video/fbdev/omap/Kconfig"
source "drivers/video/fbdev/omap2/Kconfig"
diff --git a/net/bridge/netfilter/Kconfig b/net/bridge/netfilter/Kconfig
index f4fb0b9b927d..d978f6d820f3 100644
--- a/net/bridge/netfilter/Kconfig
+++ b/net/bridge/netfilter/Kconfig
@@ -128,7 +128,7 @@ config BRIDGE_EBT_LIMIT
equivalent of the iptables limit match.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config BRIDGE_EBT_MARK
tristate "ebt: mark filter support"
diff --git a/net/ipv4/netfilter/Kconfig b/net/ipv4/netfilter/Kconfig
index 3e6494269501..69e76d677f9e 100644
--- a/net/ipv4/netfilter/Kconfig
+++ b/net/ipv4/netfilter/Kconfig
@@ -308,7 +308,7 @@ config IP_NF_RAW
and OUTPUT chains.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
# security table for MAC policy
config IP_NF_SECURITY
diff --git a/net/ipv6/netfilter/Kconfig b/net/ipv6/netfilter/Kconfig
index f7c6f5be9f76..6120a7800975 100644
--- a/net/ipv6/netfilter/Kconfig
+++ b/net/ipv6/netfilter/Kconfig
@@ -241,7 +241,7 @@ config IP6_NF_RAW
and OUTPUT chains.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
# security table for MAC policy
config IP6_NF_SECURITY
diff --git a/net/netfilter/Kconfig b/net/netfilter/Kconfig
index 21025c2c605b..dd2af7be3eea 100644
--- a/net/netfilter/Kconfig
+++ b/net/netfilter/Kconfig
@@ -1056,7 +1056,7 @@ config NETFILTER_XT_TARGET_TRACE
the tables, chains, rules.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_TARGET_SECMARK
tristate '"SECMARK" target support'
@@ -1115,7 +1115,7 @@ config NETFILTER_XT_MATCH_ADDRTYPE
eg. UNICAST, LOCAL, BROADCAST, ...
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_MATCH_BPF
tristate '"bpf" match support'
@@ -1160,7 +1160,7 @@ config NETFILTER_XT_MATCH_COMMENT
comments in your iptables ruleset.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_MATCH_CONNBYTES
tristate '"connbytes" per-connection counter match support'
@@ -1171,7 +1171,7 @@ config NETFILTER_XT_MATCH_CONNBYTES
number of bytes and/or packets for each direction within a connection.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_MATCH_CONNLABEL
tristate '"connlabel" match support'
@@ -1237,7 +1237,7 @@ config NETFILTER_XT_MATCH_DCCP
and DCCP flags.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_MATCH_DEVGROUP
tristate '"devgroup" match support'
@@ -1473,7 +1473,7 @@ config NETFILTER_XT_MATCH_QUOTA
byte counter.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_MATCH_RATEEST
tristate '"rateest" match support'
@@ -1497,7 +1497,7 @@ config NETFILTER_XT_MATCH_REALM
in tc world.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_MATCH_RECENT
tristate '"recent" match support'
@@ -1519,7 +1519,7 @@ config NETFILTER_XT_MATCH_SCTP
and SCTP chunk types.
If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>. If unsure, say `N'.
+ <file:Documentation/kbuild/modules.rst>. If unsure, say `N'.
config NETFILTER_XT_MATCH_SOCKET
tristate '"socket" match support'
diff --git a/net/tipc/Kconfig b/net/tipc/Kconfig
index b93bb7bdb04a..b83e16ade4d2 100644
--- a/net/tipc/Kconfig
+++ b/net/tipc/Kconfig
@@ -17,7 +17,7 @@ menuconfig TIPC
This protocol support is also available as a module ( = code which
can be inserted in and removed from the running kernel whenever you
want). The module will be called tipc. If you want to compile it
- as a module, say M here and read <file:Documentation/kbuild/modules.txt>.
+ as a module, say M here and read <file:Documentation/kbuild/modules.rst>.
If in doubt, say N.
diff --git a/scripts/Kbuild.include b/scripts/Kbuild.include
index f641bb0aa63f..ee58cde8ee3b 100644
--- a/scripts/Kbuild.include
+++ b/scripts/Kbuild.include
@@ -68,7 +68,7 @@ endef
######
# gcc support functions
-# See documentation in Documentation/kbuild/makefiles.txt
+# See documentation in Documentation/kbuild/makefiles.rst
# cc-cross-prefix
# Usage: CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu- m68k-linux-)
@@ -210,7 +210,7 @@ objectify = $(foreach o,$(1),$(if $(filter /%,$(o)),$(o),$(obj)/$(o)))
# if_changed_dep - as if_changed, but uses fixdep to reveal dependencies
# including used config symbols
# if_changed_rule - as if_changed but execute rule instead
-# See Documentation/kbuild/makefiles.txt for more info
+# See Documentation/kbuild/makefiles.rst for more info
ifneq ($(KBUILD_NOCMDDEP),1)
# Check if both arguments are the same including their order. Result is empty
diff --git a/scripts/Makefile.host b/scripts/Makefile.host
index b6a54bdf0965..a316d368b697 100644
--- a/scripts/Makefile.host
+++ b/scripts/Makefile.host
@@ -6,7 +6,7 @@
#
# Both C and C++ are supported, but preferred language is C for such utilities.
#
-# Sample syntax (see Documentation/kbuild/makefiles.txt for reference)
+# Sample syntax (see Documentation/kbuild/makefiles.rst for reference)
# hostprogs-y := bin2hex
# Will compile bin2hex.c and create an executable named bin2hex
#
diff --git a/scripts/kconfig/symbol.c b/scripts/kconfig/symbol.c
index 1f9266dadedf..09fd6fa18e1a 100644
--- a/scripts/kconfig/symbol.c
+++ b/scripts/kconfig/symbol.c
@@ -1114,7 +1114,7 @@ static void sym_check_print_recursive(struct symbol *last_sym)
}
fprintf(stderr,
- "For a resolution refer to Documentation/kbuild/kconfig-language.txt\n"
+ "For a resolution refer to Documentation/kbuild/kconfig-language.rst\n"
"subsection \"Kconfig recursive dependency limitations\"\n"
"\n");
diff --git a/scripts/kconfig/tests/err_recursive_dep/expected_stderr b/scripts/kconfig/tests/err_recursive_dep/expected_stderr
index 84679b104655..c9f4abf9a791 100644
--- a/scripts/kconfig/tests/err_recursive_dep/expected_stderr
+++ b/scripts/kconfig/tests/err_recursive_dep/expected_stderr
@@ -1,38 +1,38 @@
Kconfig:11:error: recursive dependency detected!
Kconfig:11: symbol B is selected by B
-For a resolution refer to Documentation/kbuild/kconfig-language.txt
+For a resolution refer to Documentation/kbuild/kconfig-language.rst
subsection "Kconfig recursive dependency limitations"
Kconfig:5:error: recursive dependency detected!
Kconfig:5: symbol A depends on A
-For a resolution refer to Documentation/kbuild/kconfig-language.txt
+For a resolution refer to Documentation/kbuild/kconfig-language.rst
subsection "Kconfig recursive dependency limitations"
Kconfig:17:error: recursive dependency detected!
Kconfig:17: symbol C1 depends on C2
Kconfig:21: symbol C2 depends on C1
-For a resolution refer to Documentation/kbuild/kconfig-language.txt
+For a resolution refer to Documentation/kbuild/kconfig-language.rst
subsection "Kconfig recursive dependency limitations"
Kconfig:32:error: recursive dependency detected!
Kconfig:32: symbol D2 is selected by D1
Kconfig:27: symbol D1 depends on D2
-For a resolution refer to Documentation/kbuild/kconfig-language.txt
+For a resolution refer to Documentation/kbuild/kconfig-language.rst
subsection "Kconfig recursive dependency limitations"
Kconfig:37:error: recursive dependency detected!
Kconfig:37: symbol E1 depends on E2
Kconfig:42: symbol E2 is implied by E1
-For a resolution refer to Documentation/kbuild/kconfig-language.txt
+For a resolution refer to Documentation/kbuild/kconfig-language.rst
subsection "Kconfig recursive dependency limitations"
Kconfig:60:error: recursive dependency detected!
Kconfig:60: symbol G depends on G
-For a resolution refer to Documentation/kbuild/kconfig-language.txt
+For a resolution refer to Documentation/kbuild/kconfig-language.rst
subsection "Kconfig recursive dependency limitations"
Kconfig:51:error: recursive dependency detected!
Kconfig:51: symbol F2 depends on F1
Kconfig:49: symbol F1 default value contains F2
-For a resolution refer to Documentation/kbuild/kconfig-language.txt
+For a resolution refer to Documentation/kbuild/kconfig-language.rst
subsection "Kconfig recursive dependency limitations"
diff --git a/sound/oss/dmasound/Kconfig b/sound/oss/dmasound/Kconfig
index 12e42165b4a5..1a3339859840 100644
--- a/sound/oss/dmasound/Kconfig
+++ b/sound/oss/dmasound/Kconfig
@@ -11,7 +11,7 @@ config DMASOUND_ATARI
This driver is also available as a module ( = code which can be
inserted in and removed from the running kernel whenever you
want). If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>.
+ <file:Documentation/kbuild/modules.rst>.
config DMASOUND_PAULA
tristate "Amiga DMA sound support"
@@ -25,7 +25,7 @@ config DMASOUND_PAULA
This driver is also available as a module ( = code which can be
inserted in and removed from the running kernel whenever you
want). If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>.
+ <file:Documentation/kbuild/modules.rst>.
config DMASOUND_Q40
tristate "Q40 sound support"
@@ -39,7 +39,7 @@ config DMASOUND_Q40
This driver is also available as a module ( = code which can be
inserted in and removed from the running kernel whenever you
want). If you want to compile it as a module, say M here and read
- <file:Documentation/kbuild/modules.txt>.
+ <file:Documentation/kbuild/modules.rst>.
config DMASOUND
tristate
--
2.21.0
_______________________________________________
linux-snps-arc mailing list
linux-snps-arc@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-snps-arc
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH v4 14/28] docs: locking: convert docs to ReST and rename to *.rst
[not found] <cover.1560361364.git.mchehab+samsung@kernel.org>
2019-06-12 17:52 ` [PATCH v4 09/28] docs: fb: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 17:52 ` [PATCH v4 12/28] docs: kbuild: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-14 20:36 ` Jonathan Corbet
2019-06-12 17:52 ` [PATCH v4 18/28] docs: " Mauro Carvalho Chehab
2019-06-12 17:53 ` [PATCH v4 28/28] docs: EDID/HOWTO.txt: convert it and rename to howto.rst Mauro Carvalho Chehab
4 siblings, 1 reply; 12+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Jonathan Corbet, Peter Zijlstra, David Airlie, Will Deacon,
linux-kernel, dri-devel, Mauro Carvalho Chehab, Maxime Ripard,
Ingo Molnar, Federico Vaga, Mauro Carvalho Chehab, Sean Paul
Convert the locking documents to ReST and add them to the
kernel development book where it belongs.
Most of the stuff here is just to make Sphinx to properly
parse the text file, as they're already in good shape,
not requiring massive changes in order to be parsed.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
Documentation/kernel-hacking/locking.rst | 2 +-
Documentation/locking/index.rst | 24 +++
...{lockdep-design.txt => lockdep-design.rst} | 51 +++--
Documentation/locking/lockstat.rst | 204 ++++++++++++++++++
Documentation/locking/lockstat.txt | 183 ----------------
.../{locktorture.txt => locktorture.rst} | 105 +++++----
.../{mutex-design.txt => mutex-design.rst} | 26 ++-
...t-mutex-design.txt => rt-mutex-design.rst} | 139 ++++++------
.../locking/{rt-mutex.txt => rt-mutex.rst} | 30 +--
.../locking/{spinlocks.txt => spinlocks.rst} | 32 ++-
...w-mutex-design.txt => ww-mutex-design.rst} | 82 +++----
Documentation/pi-futex.txt | 2 +-
.../it_IT/kernel-hacking/locking.rst | 2 +-
drivers/gpu/drm/drm_modeset_lock.c | 2 +-
include/linux/lockdep.h | 2 +-
include/linux/mutex.h | 2 +-
include/linux/rwsem.h | 2 +-
kernel/locking/mutex.c | 2 +-
kernel/locking/rtmutex.c | 2 +-
lib/Kconfig.debug | 4 +-
20 files changed, 511 insertions(+), 387 deletions(-)
create mode 100644 Documentation/locking/index.rst
rename Documentation/locking/{lockdep-design.txt => lockdep-design.rst} (93%)
create mode 100644 Documentation/locking/lockstat.rst
delete mode 100644 Documentation/locking/lockstat.txt
rename Documentation/locking/{locktorture.txt => locktorture.rst} (57%)
rename Documentation/locking/{mutex-design.txt => mutex-design.rst} (94%)
rename Documentation/locking/{rt-mutex-design.txt => rt-mutex-design.rst} (91%)
rename Documentation/locking/{rt-mutex.txt => rt-mutex.rst} (71%)
rename Documentation/locking/{spinlocks.txt => spinlocks.rst} (89%)
rename Documentation/locking/{ww-mutex-design.txt => ww-mutex-design.rst} (93%)
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index 519673df0e82..71a843464ec2 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -1364,7 +1364,7 @@ Futex API reference
Further reading
===============
-- ``Documentation/locking/spinlocks.txt``: Linus Torvalds' spinlocking
+- ``Documentation/locking/spinlocks.rst``: Linus Torvalds' spinlocking
tutorial in the kernel sources.
- Unix Systems for Modern Architectures: Symmetric Multiprocessing and
diff --git a/Documentation/locking/index.rst b/Documentation/locking/index.rst
new file mode 100644
index 000000000000..ef5da7fe9aac
--- /dev/null
+++ b/Documentation/locking/index.rst
@@ -0,0 +1,24 @@
+:orphan:
+
+=======
+locking
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ lockdep-design
+ lockstat
+ locktorture
+ mutex-design
+ rt-mutex-design
+ rt-mutex
+ spinlocks
+ ww-mutex-design
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/locking/lockdep-design.txt b/Documentation/locking/lockdep-design.rst
similarity index 93%
rename from Documentation/locking/lockdep-design.txt
rename to Documentation/locking/lockdep-design.rst
index f189d130e543..23fcbc4d3fc0 100644
--- a/Documentation/locking/lockdep-design.txt
+++ b/Documentation/locking/lockdep-design.rst
@@ -2,6 +2,7 @@ Runtime locking correctness validator
=====================================
started by Ingo Molnar <mingo@redhat.com>
+
additions by Arjan van de Ven <arjan@linux.intel.com>
Lock-class
@@ -56,7 +57,7 @@ where the last 1 category is:
When locking rules are violated, these usage bits are presented in the
locking error messages, inside curlies, with a total of 2 * n STATEs bits.
-A contrived example:
+A contrived example::
modprobe/2287 is trying to acquire lock:
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
@@ -70,12 +71,14 @@ of the lock and readlock (if exists), for each of the n STATEs listed
above respectively, and the character displayed at each bit position
indicates:
+ === ===================================================
'.' acquired while irqs disabled and not in irq context
'-' acquired in irq context
'+' acquired with irqs enabled
'?' acquired in irq context with irqs enabled.
+ === ===================================================
-The bits are illustrated with an example:
+The bits are illustrated with an example::
(&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
||||
@@ -90,13 +93,13 @@ context and whether that STATE is enabled yields four possible cases as
shown in the table below. The bit character is able to indicate which
exact case is for the lock as of the reporting time.
- -------------------------------------------
+ +--------------+-------------+--------------+
| | irq enabled | irq disabled |
- |-------------------------------------------|
+ +--------------+-------------+--------------+
| ever in irq | ? | - |
- |-------------------------------------------|
+ +--------------+-------------+--------------+
| never in irq | + | . |
- -------------------------------------------
+ +--------------+-------------+--------------+
The character '-' suggests irq is disabled because if otherwise the
charactor '?' would have been shown instead. Similar deduction can be
@@ -113,7 +116,7 @@ is irq-unsafe means it was ever acquired with irq enabled.
A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The
following states must be exclusive: only one of them is allowed to be set
-for any lock-class based on its usage:
+for any lock-class based on its usage::
<hardirq-safe> or <hardirq-unsafe>
<softirq-safe> or <softirq-unsafe>
@@ -134,7 +137,7 @@ Multi-lock dependency rules:
The same lock-class must not be acquired twice, because this could lead
to lock recursion deadlocks.
-Furthermore, two locks can not be taken in inverse order:
+Furthermore, two locks can not be taken in inverse order::
<L1> -> <L2>
<L2> -> <L1>
@@ -148,7 +151,7 @@ operations; the validator will still find whether these locks can be
acquired in a circular fashion.
Furthermore, the following usage based lock dependencies are not allowed
-between any two lock-classes:
+between any two lock-classes::
<hardirq-safe> -> <hardirq-unsafe>
<softirq-safe> -> <softirq-unsafe>
@@ -204,16 +207,16 @@ the ordering is not static.
In order to teach the validator about this correct usage model, new
versions of the various locking primitives were added that allow you to
specify a "nesting level". An example call, for the block device mutex,
-looks like this:
+looks like this::
-enum bdev_bd_mutex_lock_class
-{
+ enum bdev_bd_mutex_lock_class
+ {
BD_MUTEX_NORMAL,
BD_MUTEX_WHOLE,
BD_MUTEX_PARTITION
-};
+ };
- mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
In this case the locking is done on a bdev object that is known to be a
partition.
@@ -234,7 +237,7 @@ must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock).
As the name suggests, lockdep_assert_held* family of macros assert that a
particular lock is held at a certain time (and generate a WARN() otherwise).
This annotation is largely used all over the kernel, e.g. kernel/sched/
-core.c
+core.c::
void update_rq_clock(struct rq *rq)
{
@@ -253,7 +256,7 @@ out to be especially helpful to debug code with callbacks, where an upper
layer assumes a lock remains taken, but a lower layer thinks it can maybe drop
and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock()
returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check
-that nobody tampered with the lock, e.g. kernel/sched/sched.h
+that nobody tampered with the lock, e.g. kernel/sched/sched.h::
static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf)
{
@@ -280,7 +283,7 @@ correctness) in the sense that for every simple, standalone single-task
locking sequence that occurred at least once during the lifetime of the
kernel, the validator proves it with a 100% certainty that no
combination and timing of these locking sequences can cause any class of
-lock related deadlock. [*]
+lock related deadlock. [1]_
I.e. complex multi-CPU and multi-task locking scenarios do not have to
occur in practice to prove a deadlock: only the simple 'component'
@@ -299,7 +302,9 @@ possible combination of locking interaction between CPUs, combined with
every possible hardirq and softirq nesting scenario (which is impossible
to do in practice).
-[*] assuming that the validator itself is 100% correct, and no other
+.. [1]
+
+ assuming that the validator itself is 100% correct, and no other
part of the system corrupts the state of the validator in any way.
We also assume that all NMI/SMM paths [which could interrupt
even hardirq-disabled codepaths] are correct and do not interfere
@@ -310,7 +315,7 @@ to do in practice).
Performance:
------------
-The above rules require _massive_ amounts of runtime checking. If we did
+The above rules require **massive** amounts of runtime checking. If we did
that for every lock taken and for every irqs-enable event, it would
render the system practically unusably slow. The complexity of checking
is O(N^2), so even with just a few hundred lock-classes we'd have to do
@@ -369,17 +374,17 @@ be harder to do than to say.
Of course, if you do run out of lock classes, the next thing to do is
to find the offending lock classes. First, the following command gives
-you the number of lock classes currently in use along with the maximum:
+you the number of lock classes currently in use along with the maximum::
grep "lock-classes" /proc/lockdep_stats
-This command produces the following output on a modest system:
+This command produces the following output on a modest system::
- lock-classes: 748 [max: 8191]
+ lock-classes: 748 [max: 8191]
If the number allocated (748 above) increases continually over time,
then there is likely a leak. The following command can be used to
-identify the leaking lock classes:
+identify the leaking lock classes::
grep "BD" /proc/lockdep
diff --git a/Documentation/locking/lockstat.rst b/Documentation/locking/lockstat.rst
new file mode 100644
index 000000000000..536eab8dbd99
--- /dev/null
+++ b/Documentation/locking/lockstat.rst
@@ -0,0 +1,204 @@
+===============
+Lock Statistics
+===============
+
+What
+====
+
+As the name suggests, it provides statistics on locks.
+
+
+Why
+===
+
+Because things like lock contention can severely impact performance.
+
+How
+===
+
+Lockdep already has hooks in the lock functions and maps lock instances to
+lock classes. We build on that (see Documentation/locking/lockdep-design.rst).
+The graph below shows the relation between the lock functions and the various
+hooks therein::
+
+ __acquire
+ |
+ lock _____
+ | \
+ | __contended
+ | |
+ | <wait>
+ | _______/
+ |/
+ |
+ __acquired
+ |
+ .
+ <hold>
+ .
+ |
+ __release
+ |
+ unlock
+
+ lock, unlock - the regular lock functions
+ __* - the hooks
+ <> - states
+
+With these hooks we provide the following statistics:
+
+ con-bounces
+ - number of lock contention that involved x-cpu data
+ contentions
+ - number of lock acquisitions that had to wait
+ wait time
+ min
+ - shortest (non-0) time we ever had to wait for a lock
+ max
+ - longest time we ever had to wait for a lock
+ total
+ - total time we spend waiting on this lock
+ avg
+ - average time spent waiting on this lock
+ acq-bounces
+ - number of lock acquisitions that involved x-cpu data
+ acquisitions
+ - number of times we took the lock
+ hold time
+ min
+ - shortest (non-0) time we ever held the lock
+ max
+ - longest time we ever held the lock
+ total
+ - total time this lock was held
+ avg
+ - average time this lock was held
+
+These numbers are gathered per lock class, per read/write state (when
+applicable).
+
+It also tracks 4 contention points per class. A contention point is a call site
+that had to wait on lock acquisition.
+
+Configuration
+-------------
+
+Lock statistics are enabled via CONFIG_LOCK_STAT.
+
+Usage
+-----
+
+Enable collection of statistics::
+
+ # echo 1 >/proc/sys/kernel/lock_stat
+
+Disable collection of statistics::
+
+ # echo 0 >/proc/sys/kernel/lock_stat
+
+Look at the current lock statistics::
+
+ ( line numbers not part of actual output, done for clarity in the explanation
+ below )
+
+ # less /proc/lock_stat
+
+ 01 lock_stat version 0.4
+ 02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
+ 04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 05
+ 06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
+ 07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
+ 08 ---------------
+ 09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
+ 10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
+ 13 ---------------
+ 14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
+ 15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
+ 16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
+ 17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
+ 18
+ 19.............................................................................................................................................................................................................................
+ 20
+ 21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
+ 22 ---------------
+ 23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+ 27 ---------------
+ 28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
+ 29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
+ 30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
+ 31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
+
+
+This excerpt shows the first two lock class statistics. Line 01 shows the
+output version - each time the format changes this will be updated. Line 02-04
+show the header with column descriptions. Lines 05-18 and 20-31 show the actual
+statistics. These statistics come in two parts; the actual stats separated by a
+short separator (line 08, 13) from the contention points.
+
+Lines 09-12 show the first 4 recorded contention points (the code
+which tries to get the lock) and lines 14-17 show the first 4 recorded
+contended points (the lock holder). It is possible that the max
+con-bounces point is missing in the statistics.
+
+The first lock (05-18) is a read/write lock, and shows two lines above the
+short separator. The contention points don't match the column descriptors,
+they have two: contentions and [<IP>] symbol. The second set of contention
+points are the points we're contending with.
+
+The integer part of the time values is in us.
+
+Dealing with nested locks, subclasses may appear::
+
+ 32...........................................................................................................................................................................................................................
+ 33
+ 34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
+ 35 ---------
+ 36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
+ 39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
+ 40 ---------
+ 41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
+ 42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+ 43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 45
+ 46...........................................................................................................................................................................................................................
+ 47
+ 48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
+ 49 -----------
+ 50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 51 -----------
+ 52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
+ 53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
+ 54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
+ 55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
+
+Line 48 shows statistics for the second subclass (/1) of &rq->lock class
+(subclass starts from 0), since in this case, as line 50 suggests,
+double_rq_lock actually acquires a nested lock of two spinlocks.
+
+View the top contending locks::
+
+ # grep : /proc/lock_stat | head
+ clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
+ tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
+ &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
+ &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
+ &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
+ tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
+ tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
+ rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
+ &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
+ rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
+
+Clear the statistics::
+
+ # echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/lockstat.txt b/Documentation/locking/lockstat.txt
deleted file mode 100644
index fdbeb0c45ef3..000000000000
--- a/Documentation/locking/lockstat.txt
+++ /dev/null
@@ -1,183 +0,0 @@
-
-LOCK STATISTICS
-
-- WHAT
-
-As the name suggests, it provides statistics on locks.
-
-- WHY
-
-Because things like lock contention can severely impact performance.
-
-- HOW
-
-Lockdep already has hooks in the lock functions and maps lock instances to
-lock classes. We build on that (see Documentation/locking/lockdep-design.txt).
-The graph below shows the relation between the lock functions and the various
-hooks therein.
-
- __acquire
- |
- lock _____
- | \
- | __contended
- | |
- | <wait>
- | _______/
- |/
- |
- __acquired
- |
- .
- <hold>
- .
- |
- __release
- |
- unlock
-
-lock, unlock - the regular lock functions
-__* - the hooks
-<> - states
-
-With these hooks we provide the following statistics:
-
- con-bounces - number of lock contention that involved x-cpu data
- contentions - number of lock acquisitions that had to wait
- wait time min - shortest (non-0) time we ever had to wait for a lock
- max - longest time we ever had to wait for a lock
- total - total time we spend waiting on this lock
- avg - average time spent waiting on this lock
- acq-bounces - number of lock acquisitions that involved x-cpu data
- acquisitions - number of times we took the lock
- hold time min - shortest (non-0) time we ever held the lock
- max - longest time we ever held the lock
- total - total time this lock was held
- avg - average time this lock was held
-
-These numbers are gathered per lock class, per read/write state (when
-applicable).
-
-It also tracks 4 contention points per class. A contention point is a call site
-that had to wait on lock acquisition.
-
- - CONFIGURATION
-
-Lock statistics are enabled via CONFIG_LOCK_STAT.
-
- - USAGE
-
-Enable collection of statistics:
-
-# echo 1 >/proc/sys/kernel/lock_stat
-
-Disable collection of statistics:
-
-# echo 0 >/proc/sys/kernel/lock_stat
-
-Look at the current lock statistics:
-
-( line numbers not part of actual output, done for clarity in the explanation
- below )
-
-# less /proc/lock_stat
-
-01 lock_stat version 0.4
-02-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-03 class name con-bounces contentions waittime-min waittime-max waittime-total waittime-avg acq-bounces acquisitions holdtime-min holdtime-max holdtime-total holdtime-avg
-04-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-05
-06 &mm->mmap_sem-W: 46 84 0.26 939.10 16371.53 194.90 47291 2922365 0.16 2220301.69 17464026916.32 5975.99
-07 &mm->mmap_sem-R: 37 100 1.31 299502.61 325629.52 3256.30 212344 34316685 0.10 7744.91 95016910.20 2.77
-08 ---------------
-09 &mm->mmap_sem 1 [<ffffffff811502a7>] khugepaged_scan_mm_slot+0x57/0x280
-10 &mm->mmap_sem 96 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-11 &mm->mmap_sem 34 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-12 &mm->mmap_sem 17 [<ffffffff81127e71>] vm_munmap+0x41/0x80
-13 ---------------
-14 &mm->mmap_sem 1 [<ffffffff81046fda>] dup_mmap+0x2a/0x3f0
-15 &mm->mmap_sem 60 [<ffffffff81129e29>] SyS_mprotect+0xe9/0x250
-16 &mm->mmap_sem 41 [<ffffffff815351c4>] __do_page_fault+0x1d4/0x510
-17 &mm->mmap_sem 68 [<ffffffff81113d77>] vm_mmap_pgoff+0x87/0xd0
-18
-19.............................................................................................................................................................................................................................
-20
-21 unix_table_lock: 110 112 0.21 49.24 163.91 1.46 21094 66312 0.12 624.42 31589.81 0.48
-22 ---------------
-23 unix_table_lock 45 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-24 unix_table_lock 47 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-25 unix_table_lock 15 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-26 unix_table_lock 5 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-27 ---------------
-28 unix_table_lock 39 [<ffffffff8150b111>] unix_release_sock+0x31/0x250
-29 unix_table_lock 49 [<ffffffff8150ad8e>] unix_create1+0x16e/0x1b0
-30 unix_table_lock 20 [<ffffffff8150ca37>] unix_find_other+0x117/0x230
-31 unix_table_lock 4 [<ffffffff8150a09f>] unix_autobind+0x11f/0x1b0
-
-
-This excerpt shows the first two lock class statistics. Line 01 shows the
-output version - each time the format changes this will be updated. Line 02-04
-show the header with column descriptions. Lines 05-18 and 20-31 show the actual
-statistics. These statistics come in two parts; the actual stats separated by a
-short separator (line 08, 13) from the contention points.
-
-Lines 09-12 show the first 4 recorded contention points (the code
-which tries to get the lock) and lines 14-17 show the first 4 recorded
-contended points (the lock holder). It is possible that the max
-con-bounces point is missing in the statistics.
-
-The first lock (05-18) is a read/write lock, and shows two lines above the
-short separator. The contention points don't match the column descriptors,
-they have two: contentions and [<IP>] symbol. The second set of contention
-points are the points we're contending with.
-
-The integer part of the time values is in us.
-
-Dealing with nested locks, subclasses may appear:
-
-32...........................................................................................................................................................................................................................
-33
-34 &rq->lock: 13128 13128 0.43 190.53 103881.26 7.91 97454 3453404 0.00 401.11 13224683.11 3.82
-35 ---------
-36 &rq->lock 645 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-37 &rq->lock 297 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-38 &rq->lock 360 [<ffffffff8103c4c5>] select_task_rq_fair+0x1f0/0x74a
-39 &rq->lock 428 [<ffffffff81045f98>] scheduler_tick+0x46/0x1fb
-40 ---------
-41 &rq->lock 77 [<ffffffff8103bfc4>] task_rq_lock+0x43/0x75
-42 &rq->lock 174 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-43 &rq->lock 4715 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-44 &rq->lock 893 [<ffffffff81340524>] schedule+0x157/0x7b8
-45
-46...........................................................................................................................................................................................................................
-47
-48 &rq->lock/1: 1526 11488 0.33 388.73 136294.31 11.86 21461 38404 0.00 37.93 109388.53 2.84
-49 -----------
-50 &rq->lock/1 11526 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-51 -----------
-52 &rq->lock/1 5645 [<ffffffff8103ed4b>] double_rq_lock+0x42/0x54
-53 &rq->lock/1 1224 [<ffffffff81340524>] schedule+0x157/0x7b8
-54 &rq->lock/1 4336 [<ffffffff8103ed58>] double_rq_lock+0x4f/0x54
-55 &rq->lock/1 181 [<ffffffff8104ba65>] try_to_wake_up+0x127/0x25a
-
-Line 48 shows statistics for the second subclass (/1) of &rq->lock class
-(subclass starts from 0), since in this case, as line 50 suggests,
-double_rq_lock actually acquires a nested lock of two spinlocks.
-
-View the top contending locks:
-
-# grep : /proc/lock_stat | head
- clockevents_lock: 2926159 2947636 0.15 46882.81 1784540466.34 605.41 3381345 3879161 0.00 2260.97 53178395.68 13.71
- tick_broadcast_lock: 346460 346717 0.18 2257.43 39364622.71 113.54 3642919 4242696 0.00 2263.79 49173646.60 11.59
- &mapping->i_mmap_mutex: 203896 203899 3.36 645530.05 31767507988.39 155800.21 3361776 8893984 0.17 2254.15 14110121.02 1.59
- &rq->lock: 135014 136909 0.18 606.09 842160.68 6.15 1540728 10436146 0.00 728.72 17606683.41 1.69
- &(&zone->lru_lock)->rlock: 93000 94934 0.16 59.18 188253.78 1.98 1199912 3809894 0.15 391.40 3559518.81 0.93
- tasklist_lock-W: 40667 41130 0.23 1189.42 428980.51 10.43 270278 510106 0.16 653.51 3939674.91 7.72
- tasklist_lock-R: 21298 21305 0.20 1310.05 215511.12 10.12 186204 241258 0.14 1162.33 1179779.23 4.89
- rcu_node_1: 47656 49022 0.16 635.41 193616.41 3.95 844888 1865423 0.00 764.26 1656226.96 0.89
- &(&dentry->d_lockref.lock)->rlock: 39791 40179 0.15 1302.08 88851.96 2.21 2790851 12527025 0.10 1910.75 3379714.27 0.27
- rcu_node_0: 29203 30064 0.16 786.55 1555573.00 51.74 88963 244254 0.00 398.87 428872.51 1.76
-
-Clear the statistics:
-
-# echo 0 > /proc/lock_stat
diff --git a/Documentation/locking/locktorture.txt b/Documentation/locking/locktorture.rst
similarity index 57%
rename from Documentation/locking/locktorture.txt
rename to Documentation/locking/locktorture.rst
index 6a8df4cd19bf..e79eeeca3ac6 100644
--- a/Documentation/locking/locktorture.txt
+++ b/Documentation/locking/locktorture.rst
@@ -1,6 +1,9 @@
+==================================
Kernel Lock Torture Test Operation
+==================================
CONFIG_LOCK_TORTURE_TEST
+========================
The CONFIG LOCK_TORTURE_TEST config option provides a kernel module
that runs torture tests on core kernel locking primitives. The kernel
@@ -18,61 +21,77 @@ can be simulated by either enlarging this critical region hold time and/or
creating more kthreads.
-MODULE PARAMETERS
+Module Parameters
+=================
This module has the following parameters:
- ** Locktorture-specific **
+Locktorture-specific
+--------------------
-nwriters_stress Number of kernel threads that will stress exclusive lock
+nwriters_stress
+ Number of kernel threads that will stress exclusive lock
ownership (writers). The default value is twice the number
of online CPUs.
-nreaders_stress Number of kernel threads that will stress shared lock
+nreaders_stress
+ Number of kernel threads that will stress shared lock
ownership (readers). The default is the same amount of writer
locks. If the user did not specify nwriters_stress, then
both readers and writers be the amount of online CPUs.
-torture_type Type of lock to torture. By default, only spinlocks will
+torture_type
+ Type of lock to torture. By default, only spinlocks will
be tortured. This module can torture the following locks,
with string values as follows:
- o "lock_busted": Simulates a buggy lock implementation.
+ - "lock_busted":
+ Simulates a buggy lock implementation.
- o "spin_lock": spin_lock() and spin_unlock() pairs.
+ - "spin_lock":
+ spin_lock() and spin_unlock() pairs.
- o "spin_lock_irq": spin_lock_irq() and spin_unlock_irq()
- pairs.
+ - "spin_lock_irq":
+ spin_lock_irq() and spin_unlock_irq() pairs.
- o "rw_lock": read/write lock() and unlock() rwlock pairs.
+ - "rw_lock":
+ read/write lock() and unlock() rwlock pairs.
- o "rw_lock_irq": read/write lock_irq() and unlock_irq()
- rwlock pairs.
+ - "rw_lock_irq":
+ read/write lock_irq() and unlock_irq()
+ rwlock pairs.
- o "mutex_lock": mutex_lock() and mutex_unlock() pairs.
+ - "mutex_lock":
+ mutex_lock() and mutex_unlock() pairs.
- o "rtmutex_lock": rtmutex_lock() and rtmutex_unlock()
- pairs. Kernel must have CONFIG_RT_MUTEX=y.
+ - "rtmutex_lock":
+ rtmutex_lock() and rtmutex_unlock() pairs.
+ Kernel must have CONFIG_RT_MUTEX=y.
- o "rwsem_lock": read/write down() and up() semaphore pairs.
+ - "rwsem_lock":
+ read/write down() and up() semaphore pairs.
- ** Torture-framework (RCU + locking) **
+Torture-framework (RCU + locking)
+---------------------------------
-shutdown_secs The number of seconds to run the test before terminating
+shutdown_secs
+ The number of seconds to run the test before terminating
the test and powering off the system. The default is
zero, which disables test termination and system shutdown.
This capability is useful for automated testing.
-onoff_interval The number of seconds between each attempt to execute a
+onoff_interval
+ The number of seconds between each attempt to execute a
randomly selected CPU-hotplug operation. Defaults
to zero, which disables CPU hotplugging. In
CONFIG_HOTPLUG_CPU=n kernels, locktorture will silently
refuse to do any CPU-hotplug operations regardless of
what value is specified for onoff_interval.
-onoff_holdoff The number of seconds to wait until starting CPU-hotplug
+onoff_holdoff
+ The number of seconds to wait until starting CPU-hotplug
operations. This would normally only be used when
locktorture was built into the kernel and started
automatically at boot time, in which case it is useful
@@ -80,53 +99,59 @@ onoff_holdoff The number of seconds to wait until starting CPU-hotplug
coming and going. This parameter is only useful if
CONFIG_HOTPLUG_CPU is enabled.
-stat_interval Number of seconds between statistics-related printk()s.
+stat_interval
+ Number of seconds between statistics-related printk()s.
By default, locktorture will report stats every 60 seconds.
Setting the interval to zero causes the statistics to
be printed -only- when the module is unloaded, and this
is the default.
-stutter The length of time to run the test before pausing for this
+stutter
+ The length of time to run the test before pausing for this
same period of time. Defaults to "stutter=5", so as
to run and pause for (roughly) five-second intervals.
Specifying "stutter=0" causes the test to run continuously
without pausing, which is the old default behavior.
-shuffle_interval The number of seconds to keep the test threads affinitied
+shuffle_interval
+ The number of seconds to keep the test threads affinitied
to a particular subset of the CPUs, defaults to 3 seconds.
Used in conjunction with test_no_idle_hz.
-verbose Enable verbose debugging printing, via printk(). Enabled
+verbose
+ Enable verbose debugging printing, via printk(). Enabled
by default. This extra information is mostly related to
high-level errors and reports from the main 'torture'
framework.
-STATISTICS
+Statistics
+==========
-Statistics are printed in the following format:
+Statistics are printed in the following format::
-spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
- (A) (B) (C) (D) (E)
+ spin_lock-torture: Writes: Total: 93746064 Max/Min: 0/0 Fail: 0
+ (A) (B) (C) (D) (E)
-(A): Lock type that is being tortured -- torture_type parameter.
+ (A): Lock type that is being tortured -- torture_type parameter.
-(B): Number of writer lock acquisitions. If dealing with a read/write primitive
- a second "Reads" statistics line is printed.
+ (B): Number of writer lock acquisitions. If dealing with a read/write
+ primitive a second "Reads" statistics line is printed.
-(C): Number of times the lock was acquired.
+ (C): Number of times the lock was acquired.
-(D): Min and max number of times threads failed to acquire the lock.
+ (D): Min and max number of times threads failed to acquire the lock.
-(E): true/false values if there were errors acquiring the lock. This should
- -only- be positive if there is a bug in the locking primitive's
- implementation. Otherwise a lock should never fail (i.e., spin_lock()).
- Of course, the same applies for (C), above. A dummy example of this is
- the "lock_busted" type.
+ (E): true/false values if there were errors acquiring the lock. This should
+ -only- be positive if there is a bug in the locking primitive's
+ implementation. Otherwise a lock should never fail (i.e., spin_lock()).
+ Of course, the same applies for (C), above. A dummy example of this is
+ the "lock_busted" type.
-USAGE
+Usage
+=====
-The following script may be used to torture locks:
+The following script may be used to torture locks::
#!/bin/sh
diff --git a/Documentation/locking/mutex-design.txt b/Documentation/locking/mutex-design.rst
similarity index 94%
rename from Documentation/locking/mutex-design.txt
rename to Documentation/locking/mutex-design.rst
index 818aca19612f..4d8236b81fa5 100644
--- a/Documentation/locking/mutex-design.txt
+++ b/Documentation/locking/mutex-design.rst
@@ -1,6 +1,9 @@
+=======================
Generic Mutex Subsystem
+=======================
started by Ingo Molnar <mingo@redhat.com>
+
updated by Davidlohr Bueso <davidlohr@hp.com>
What are mutexes?
@@ -23,7 +26,7 @@ Implementation
Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h
and implemented in kernel/locking/mutex.c. These locks use an atomic variable
(->owner) to keep track of the lock state during its lifetime. Field owner
-actually contains 'struct task_struct *' to the current lock owner and it is
+actually contains `struct task_struct *` to the current lock owner and it is
therefore NULL if not currently owned. Since task_struct pointers are aligned
at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
if waiter list is non-empty). In its most basic form it also includes a
@@ -101,29 +104,36 @@ features that make lock debugging easier and faster:
Interfaces
----------
-Statically define the mutex:
+Statically define the mutex::
+
DEFINE_MUTEX(name);
-Dynamically initialize the mutex:
+Dynamically initialize the mutex::
+
mutex_init(mutex);
-Acquire the mutex, uninterruptible:
+Acquire the mutex, uninterruptible::
+
void mutex_lock(struct mutex *lock);
void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
int mutex_trylock(struct mutex *lock);
-Acquire the mutex, interruptible:
+Acquire the mutex, interruptible::
+
int mutex_lock_interruptible_nested(struct mutex *lock,
unsigned int subclass);
int mutex_lock_interruptible(struct mutex *lock);
-Acquire the mutex, interruptible, if dec to 0:
+Acquire the mutex, interruptible, if dec to 0::
+
int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
-Unlock the mutex:
+Unlock the mutex::
+
void mutex_unlock(struct mutex *lock);
-Test if the mutex is taken:
+Test if the mutex is taken::
+
int mutex_is_locked(struct mutex *lock);
Disadvantages
diff --git a/Documentation/locking/rt-mutex-design.txt b/Documentation/locking/rt-mutex-design.rst
similarity index 91%
rename from Documentation/locking/rt-mutex-design.txt
rename to Documentation/locking/rt-mutex-design.rst
index 3d7b865539cc..59c2a64efb21 100644
--- a/Documentation/locking/rt-mutex-design.txt
+++ b/Documentation/locking/rt-mutex-design.rst
@@ -1,14 +1,15 @@
-#
-# Copyright (c) 2006 Steven Rostedt
-# Licensed under the GNU Free Documentation License, Version 1.2
-#
-
+==============================
RT-mutex implementation design
-------------------------------
+==============================
+
+Copyright (c) 2006 Steven Rostedt
+
+Licensed under the GNU Free Documentation License, Version 1.2
+
This document tries to describe the design of the rtmutex.c implementation.
It doesn't describe the reasons why rtmutex.c exists. For that please see
-Documentation/locking/rt-mutex.txt. Although this document does explain problems
+Documentation/locking/rt-mutex.rst. Although this document does explain problems
that happen without this code, but that is in the concept to understand
what the code actually is doing.
@@ -41,17 +42,17 @@ to release the lock, because for all we know, B is a CPU hog and will
never give C a chance to release the lock. This is called unbounded priority
inversion.
-Here's a little ASCII art to show the problem.
+Here's a little ASCII art to show the problem::
- grab lock L1 (owned by C)
- |
-A ---+
- C preempted by B
- |
-C +----+
+ grab lock L1 (owned by C)
+ |
+ A ---+
+ C preempted by B
+ |
+ C +----+
-B +-------->
- B now keeps A from running.
+ B +-------->
+ B now keeps A from running.
Priority Inheritance (PI)
@@ -75,24 +76,29 @@ Terminology
Here I explain some terminology that is used in this document to help describe
the design that is used to implement PI.
-PI chain - The PI chain is an ordered series of locks and processes that cause
+PI chain
+ - The PI chain is an ordered series of locks and processes that cause
processes to inherit priorities from a previous process that is
blocked on one of its locks. This is described in more detail
later in this document.
-mutex - In this document, to differentiate from locks that implement
+mutex
+ - In this document, to differentiate from locks that implement
PI and spin locks that are used in the PI code, from now on
the PI locks will be called a mutex.
-lock - In this document from now on, I will use the term lock when
+lock
+ - In this document from now on, I will use the term lock when
referring to spin locks that are used to protect parts of the PI
algorithm. These locks disable preemption for UP (when
CONFIG_PREEMPT is enabled) and on SMP prevents multiple CPUs from
entering critical sections simultaneously.
-spin lock - Same as lock above.
+spin lock
+ - Same as lock above.
-waiter - A waiter is a struct that is stored on the stack of a blocked
+waiter
+ - A waiter is a struct that is stored on the stack of a blocked
process. Since the scope of the waiter is within the code for
a process being blocked on the mutex, it is fine to allocate
the waiter on the process's stack (local variable). This
@@ -104,14 +110,18 @@ waiter - A waiter is a struct that is stored on the stack of a blocked
waiter is sometimes used in reference to the task that is waiting
on a mutex. This is the same as waiter->task.
-waiters - A list of processes that are blocked on a mutex.
+waiters
+ - A list of processes that are blocked on a mutex.
-top waiter - The highest priority process waiting on a specific mutex.
+top waiter
+ - The highest priority process waiting on a specific mutex.
-top pi waiter - The highest priority process waiting on one of the mutexes
+top pi waiter
+ - The highest priority process waiting on one of the mutexes
that a specific process owns.
-Note: task and process are used interchangeably in this document, mostly to
+Note:
+ task and process are used interchangeably in this document, mostly to
differentiate between two processes that are being described together.
@@ -123,7 +133,7 @@ inheritance to take place. Multiple chains may converge, but a chain
would never diverge, since a process can't be blocked on more than one
mutex at a time.
-Example:
+Example::
Process: A, B, C, D, E
Mutexes: L1, L2, L3, L4
@@ -137,21 +147,21 @@ Example:
D owns L4
E blocked on L4
-The chain would be:
+The chain would be::
E->L4->D->L3->C->L2->B->L1->A
To show where two chains merge, we could add another process F and
another mutex L5 where B owns L5 and F is blocked on mutex L5.
-The chain for F would be:
+The chain for F would be::
F->L5->B->L1->A
Since a process may own more than one mutex, but never be blocked on more than
one, the chains merge.
-Here we show both chains:
+Here we show both chains::
E->L4->D->L3->C->L2-+
|
@@ -165,12 +175,12 @@ than the processes to the left or below in the chain.
Also since a mutex may have more than one process blocked on it, we can
have multiple chains merge at mutexes. If we add another process G that is
-blocked on mutex L2:
+blocked on mutex L2::
G->L2->B->L1->A
And once again, to show how this can grow I will show the merging chains
-again.
+again::
E->L4->D->L3->C-+
+->L2-+
@@ -184,7 +194,7 @@ the chain (A and B in this example), must have their priorities increased
to that of G.
Mutex Waiters Tree
------------------
+------------------
Every mutex keeps track of all the waiters that are blocked on itself. The
mutex has a rbtree to store these waiters by priority. This tree is protected
@@ -219,19 +229,19 @@ defined. But is very complex to figure it out, since it depends on all
the nesting of mutexes. Let's look at the example where we have 3 mutexes,
L1, L2, and L3, and four separate functions func1, func2, func3 and func4.
The following shows a locking order of L1->L2->L3, but may not actually
-be directly nested that way.
+be directly nested that way::
-void func1(void)
-{
+ void func1(void)
+ {
mutex_lock(L1);
/* do anything */
mutex_unlock(L1);
-}
+ }
-void func2(void)
-{
+ void func2(void)
+ {
mutex_lock(L1);
mutex_lock(L2);
@@ -239,10 +249,10 @@ void func2(void)
mutex_unlock(L2);
mutex_unlock(L1);
-}
+ }
-void func3(void)
-{
+ void func3(void)
+ {
mutex_lock(L2);
mutex_lock(L3);
@@ -250,30 +260,30 @@ void func3(void)
mutex_unlock(L3);
mutex_unlock(L2);
-}
+ }
-void func4(void)
-{
+ void func4(void)
+ {
mutex_lock(L3);
/* do something again */
mutex_unlock(L3);
-}
+ }
Now we add 4 processes that run each of these functions separately.
Processes A, B, C, and D which run functions func1, func2, func3 and func4
respectively, and such that D runs first and A last. With D being preempted
-in func4 in the "do something again" area, we have a locking that follows:
+in func4 in the "do something again" area, we have a locking that follows::
-D owns L3
- C blocked on L3
- C owns L2
- B blocked on L2
- B owns L1
- A blocked on L1
+ D owns L3
+ C blocked on L3
+ C owns L2
+ B blocked on L2
+ B owns L1
+ A blocked on L1
-And thus we have the chain A->L1->B->L2->C->L3->D.
+ And thus we have the chain A->L1->B->L2->C->L3->D.
This gives us a PI depth of 4 (four processes), but looking at any of the
functions individually, it seems as though they only have at most a locking
@@ -298,7 +308,7 @@ not true, the rtmutex.c code will be broken!), this allows for the least
significant bit to be used as a flag. Bit 0 is used as the "Has Waiters"
flag. It's set whenever there are waiters on a mutex.
-See Documentation/locking/rt-mutex.txt for further details.
+See Documentation/locking/rt-mutex.rst for further details.
cmpxchg Tricks
--------------
@@ -307,17 +317,17 @@ Some architectures implement an atomic cmpxchg (Compare and Exchange). This
is used (when applicable) to keep the fast path of grabbing and releasing
mutexes short.
-cmpxchg is basically the following function performed atomically:
+cmpxchg is basically the following function performed atomically::
-unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
-{
+ unsigned long _cmpxchg(unsigned long *A, unsigned long *B, unsigned long *C)
+ {
unsigned long T = *A;
if (*A == *B) {
*A = *C;
}
return T;
-}
-#define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
+ }
+ #define cmpxchg(a,b,c) _cmpxchg(&a,&b,&c)
This is really nice to have, since it allows you to only update a variable
if the variable is what you expect it to be. You know if it succeeded if
@@ -352,9 +362,10 @@ Then rt_mutex_setprio is called to adjust the priority of the task to the
new priority. Note that rt_mutex_setprio is defined in kernel/sched/core.c
to implement the actual change in priority.
-(Note: For the "prio" field in task_struct, the lower the number, the
+Note:
+ For the "prio" field in task_struct, the lower the number, the
higher the priority. A "prio" of 5 is of higher priority than a
- "prio" of 10.)
+ "prio" of 10.
It is interesting to note that rt_mutex_adjust_prio can either increase
or decrease the priority of the task. In the case that a higher priority
@@ -439,6 +450,7 @@ wait_lock, which this code currently holds. So setting the "Has Waiters" flag
forces the current owner to synchronize with this code.
The lock is taken if the following are true:
+
1) The lock has no owner
2) The current task is the highest priority against all other
waiters of the lock
@@ -546,10 +558,13 @@ Credits
-------
Author: Steven Rostedt <rostedt@goodmis.org>
+
Updated: Alex Shi <alex.shi@linaro.org> - 7/6/2017
-Original Reviewers: Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
+Original Reviewers:
+ Ingo Molnar, Thomas Gleixner, Thomas Duetsch, and
Randy Dunlap
+
Update (7/6/2017) Reviewers: Steven Rostedt and Sebastian Siewior
Updates
diff --git a/Documentation/locking/rt-mutex.txt b/Documentation/locking/rt-mutex.rst
similarity index 71%
rename from Documentation/locking/rt-mutex.txt
rename to Documentation/locking/rt-mutex.rst
index 35793e003041..c365dc302081 100644
--- a/Documentation/locking/rt-mutex.txt
+++ b/Documentation/locking/rt-mutex.rst
@@ -1,5 +1,6 @@
+==================================
RT-mutex subsystem with PI support
-----------------------------------
+==================================
RT-mutexes with priority inheritance are used to support PI-futexes,
which enable pthread_mutex_t priority inheritance attributes
@@ -46,27 +47,30 @@ The state of the rt-mutex is tracked via the owner field of the rt-mutex
structure:
lock->owner holds the task_struct pointer of the owner. Bit 0 is used to
-keep track of the "lock has waiters" state.
+keep track of the "lock has waiters" state:
- owner bit0
+ ============ ======= ================================================
+ owner bit0 Notes
+ ============ ======= ================================================
NULL 0 lock is free (fast acquire possible)
NULL 1 lock is free and has waiters and the top waiter
- is going to take the lock*
+ is going to take the lock [1]_
taskpointer 0 lock is held (fast release possible)
- taskpointer 1 lock is held and has waiters**
+ taskpointer 1 lock is held and has waiters [2]_
+ ============ ======= ================================================
The fast atomic compare exchange based acquire and release is only
possible when bit 0 of lock->owner is 0.
-(*) It also can be a transitional state when grabbing the lock
-with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
-we need to set the bit0 before looking at the lock, and the owner may be
-NULL in this small time, hence this can be a transitional state.
+.. [1] It also can be a transitional state when grabbing the lock
+ with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
+ we need to set the bit0 before looking at the lock, and the owner may
+ be NULL in this small time, hence this can be a transitional state.
-(**) There is a small time when bit 0 is set but there are no
-waiters. This can happen when grabbing the lock in the slow path.
-To prevent a cmpxchg of the owner releasing the lock, we need to
-set this bit before looking at the lock.
+.. [2] There is a small time when bit 0 is set but there are no
+ waiters. This can happen when grabbing the lock in the slow path.
+ To prevent a cmpxchg of the owner releasing the lock, we need to
+ set this bit before looking at the lock.
BTW, there is still technically a "Pending Owner", it's just not called
that anymore. The pending owner happens to be the top_waiter of a lock
diff --git a/Documentation/locking/spinlocks.txt b/Documentation/locking/spinlocks.rst
similarity index 89%
rename from Documentation/locking/spinlocks.txt
rename to Documentation/locking/spinlocks.rst
index ff35e40bdf5b..098107fb7d86 100644
--- a/Documentation/locking/spinlocks.txt
+++ b/Documentation/locking/spinlocks.rst
@@ -1,8 +1,13 @@
+===============
+Locking lessons
+===============
+
Lesson 1: Spin locks
+====================
-The most basic primitive for locking is spinlock.
+The most basic primitive for locking is spinlock::
-static DEFINE_SPINLOCK(xxx_lock);
+ static DEFINE_SPINLOCK(xxx_lock);
unsigned long flags;
@@ -19,23 +24,25 @@ worry about UP vs SMP issues: the spinlocks work correctly under both.
NOTE! Implications of spin_locks for memory are further described in:
Documentation/memory-barriers.txt
+
(5) LOCK operations.
+
(6) UNLOCK operations.
The above is usually pretty simple (you usually need and want only one
spinlock for most things - using more than one spinlock can make things a
lot more complex and even slower and is usually worth it only for
-sequences that you _know_ need to be split up: avoid it at all cost if you
+sequences that you **know** need to be split up: avoid it at all cost if you
aren't sure).
This is really the only really hard part about spinlocks: once you start
using spinlocks they tend to expand to areas you might not have noticed
before, because you have to make sure the spinlocks correctly protect the
-shared data structures _everywhere_ they are used. The spinlocks are most
+shared data structures **everywhere** they are used. The spinlocks are most
easily added to places that are completely independent of other code (for
example, internal driver data structures that nobody else ever touches).
- NOTE! The spin-lock is safe only when you _also_ use the lock itself
+ NOTE! The spin-lock is safe only when you **also** use the lock itself
to do locking across CPU's, which implies that EVERYTHING that
touches a shared variable has to agree about the spinlock they want
to use.
@@ -43,6 +50,7 @@ example, internal driver data structures that nobody else ever touches).
----
Lesson 2: reader-writer spinlocks.
+==================================
If your data accesses have a very natural pattern where you usually tend
to mostly read from the shared variables, the reader-writer locks
@@ -54,7 +62,7 @@ to change the variables it has to get an exclusive write lock.
simple spinlocks. Unless the reader critical section is long, you
are better off just using spinlocks.
-The routines look the same as above:
+The routines look the same as above::
rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock);
@@ -71,7 +79,7 @@ The routines look the same as above:
The above kind of lock may be useful for complex data structures like
linked lists, especially searching for entries without changing the list
itself. The read lock allows many concurrent readers. Anything that
-_changes_ the list will have to get the write lock.
+**changes** the list will have to get the write lock.
NOTE! RCU is better for list traversal, but requires careful
attention to design detail (see Documentation/RCU/listRCU.txt).
@@ -87,10 +95,11 @@ to get the write-lock at the very beginning.
----
Lesson 3: spinlocks revisited.
+==============================
The single spin-lock primitives above are by no means the only ones. They
are the most safe ones, and the ones that work under all circumstances,
-but partly _because_ they are safe they are also fairly slow. They are slower
+but partly **because** they are safe they are also fairly slow. They are slower
than they'd need to be, because they do have to disable interrupts
(which is just a single instruction on a x86, but it's an expensive one -
and on other architectures it can be worse).
@@ -98,7 +107,7 @@ and on other architectures it can be worse).
If you have a case where you have to protect a data structure across
several CPU's and you want to use spinlocks you can potentially use
cheaper versions of the spinlocks. IFF you know that the spinlocks are
-never used in interrupt handlers, you can use the non-irq versions:
+never used in interrupt handlers, you can use the non-irq versions::
spin_lock(&lock);
...
@@ -110,7 +119,7 @@ This is useful if you know that the data in question is only ever
manipulated from a "process context", ie no interrupts involved.
The reasons you mustn't use these versions if you have interrupts that
-play with the spinlock is that you can get deadlocks:
+play with the spinlock is that you can get deadlocks::
spin_lock(&lock);
...
@@ -147,9 +156,10 @@ indeed), while write-locks need to protect themselves against interrupts.
----
Reference information:
+======================
For dynamic initialization, use spin_lock_init() or rwlock_init() as
-appropriate:
+appropriate::
spinlock_t xxx_lock;
rwlock_t xxx_rw_lock;
diff --git a/Documentation/locking/ww-mutex-design.txt b/Documentation/locking/ww-mutex-design.rst
similarity index 93%
rename from Documentation/locking/ww-mutex-design.txt
rename to Documentation/locking/ww-mutex-design.rst
index f0ed7c30e695..1846c199da23 100644
--- a/Documentation/locking/ww-mutex-design.txt
+++ b/Documentation/locking/ww-mutex-design.rst
@@ -1,3 +1,4 @@
+======================================
Wound/Wait Deadlock-Proof Mutex Design
======================================
@@ -85,6 +86,7 @@ Furthermore there are three different class of w/w lock acquire functions:
no deadlock potential and hence the ww_mutex_lock call will block and not
prematurely return -EDEADLK. The advantage of the _slow functions is in
interface safety:
+
- ww_mutex_lock has a __must_check int return type, whereas ww_mutex_lock_slow
has a void return type. Note that since ww mutex code needs loops/retries
anyway the __must_check doesn't result in spurious warnings, even though the
@@ -115,36 +117,36 @@ expect the number of simultaneous competing transactions to be typically small,
and you want to reduce the number of rollbacks.
Three different ways to acquire locks within the same w/w class. Common
-definitions for methods #1 and #2:
+definitions for methods #1 and #2::
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-struct obj {
+ struct obj {
struct ww_mutex lock;
/* obj data */
-};
+ };
-struct obj_entry {
+ struct obj_entry {
struct list_head head;
struct obj *obj;
-};
+ };
Method 1, using a list in execbuf->buffers that's not allowed to be reordered.
This is useful if a list of required objects is already tracked somewhere.
Furthermore the lock helper can use propagate the -EALREADY return code back to
the caller as a signal that an object is twice on the list. This is useful if
the list is constructed from userspace input and the ABI requires userspace to
-not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl).
+not have duplicate entries (e.g. for a gpu commandbuffer submission ioctl)::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *res_obj = NULL;
struct obj_entry *contended_entry = NULL;
struct obj_entry *entry;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
list_for_each_entry (entry, list, head) {
if (entry->obj == res_obj) {
res_obj = NULL;
@@ -160,7 +162,7 @@ retry:
ww_acquire_done(ctx);
return 0;
-err:
+ err:
list_for_each_entry_continue_reverse (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
@@ -176,14 +178,14 @@ err:
ww_acquire_fini(ctx);
return ret;
-}
+ }
Method 2, using a list in execbuf->buffers that can be reordered. Same semantics
of duplicate entry detection using -EALREADY as method 1 above. But the
-list-reordering allows for a bit more idiomatic code.
+list-reordering allows for a bit more idiomatic code::
-int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry, *entry2;
ww_acquire_init(ctx, &ww_class);
@@ -216,24 +218,25 @@ int lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
ww_acquire_done(ctx);
return 0;
-}
+ }
-Unlocking works the same way for both methods #1 and #2:
+Unlocking works the same way for both methods #1 and #2::
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj_entry *entry;
list_for_each_entry (entry, list, head)
ww_mutex_unlock(&entry->obj->lock);
ww_acquire_fini(ctx);
-}
+ }
Method 3 is useful if the list of objects is constructed ad-hoc and not upfront,
e.g. when adjusting edges in a graph where each node has its own ww_mutex lock,
and edges can only be changed when holding the locks of all involved nodes. w/w
mutexes are a natural fit for such a case for two reasons:
+
- They can handle lock-acquisition in any order which allows us to start walking
a graph from a starting point and then iteratively discovering new edges and
locking down the nodes those edges connect to.
@@ -243,6 +246,7 @@ mutexes are a natural fit for such a case for two reasons:
as a starting point).
Note that this approach differs in two important ways from the above methods:
+
- Since the list of objects is dynamically constructed (and might very well be
different when retrying due to hitting the -EDEADLK die condition) there's
no need to keep any object on a persistent list when it's not locked. We can
@@ -260,17 +264,17 @@ any interface misuse for these cases.
Also, method 3 can't fail the lock acquisition step since it doesn't return
-EALREADY. Of course this would be different when using the _interruptible
-variants, but that's outside of the scope of these examples here.
+variants, but that's outside of the scope of these examples here::
-struct obj {
+ struct obj {
struct ww_mutex ww_mutex;
struct list_head locked_list;
-};
+ };
-static DEFINE_WW_CLASS(ww_class);
+ static DEFINE_WW_CLASS(ww_class);
-void __unlock_objs(struct list_head *list)
-{
+ void __unlock_objs(struct list_head *list)
+ {
struct obj *entry, *temp;
list_for_each_entry_safe (entry, temp, list, locked_list) {
@@ -279,15 +283,15 @@ void __unlock_objs(struct list_head *list)
list_del(&entry->locked_list);
ww_mutex_unlock(entry->ww_mutex)
}
-}
+ }
-void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void lock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
struct obj *obj;
ww_acquire_init(ctx, &ww_class);
-retry:
+ retry:
/* re-init loop start state */
loop {
/* magic code which walks over a graph and decides which objects
@@ -312,13 +316,13 @@ retry:
ww_acquire_done(ctx);
return 0;
-}
+ }
-void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
-{
+ void unlock_objs(struct list_head *list, struct ww_acquire_ctx *ctx)
+ {
__unlock_objs(list);
ww_acquire_fini(ctx);
-}
+ }
Method 4: Only lock one single objects. In that case deadlock detection and
prevention is obviously overkill, since with grabbing just one lock you can't
@@ -329,11 +333,14 @@ Implementation Details
----------------------
Design:
+^^^^^^^
+
ww_mutex currently encapsulates a struct mutex, this means no extra overhead for
normal mutex locks, which are far more common. As such there is only a small
increase in code size if wait/wound mutexes are not used.
We maintain the following invariants for the wait list:
+
(1) Waiters with an acquire context are sorted by stamp order; waiters
without an acquire context are interspersed in FIFO order.
(2) For Wait-Die, among waiters with contexts, only the first one can have
@@ -355,6 +362,8 @@ Design:
therefore be directed towards the uncontended cases.
Lockdep:
+^^^^^^^^
+
Special care has been taken to warn for as many cases of api abuse
as possible. Some common api abuses will be caught with
CONFIG_DEBUG_MUTEXES, but CONFIG_PROVE_LOCKING is recommended.
@@ -379,5 +388,6 @@ Lockdep:
having called ww_acquire_fini on the first.
- 'normal' deadlocks that can occur.
-FIXME: Update this section once we have the TASK_DEADLOCK task state flag magic
-implemented.
+FIXME:
+ Update this section once we have the TASK_DEADLOCK task state flag magic
+ implemented.
diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.txt
index b154f6c0c36e..c33ba2befbf8 100644
--- a/Documentation/pi-futex.txt
+++ b/Documentation/pi-futex.txt
@@ -119,4 +119,4 @@ properties of futexes, and all four combinations are possible: futex,
robust-futex, PI-futex, robust+PI-futex.
More details about priority inheritance can be found in
-Documentation/locking/rt-mutex.txt.
+Documentation/locking/rt-mutex.rst.
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 0ef31666663b..75d9b86fcc50 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -1404,7 +1404,7 @@ Riferimento per l'API dei Futex
Approfondimenti
===============
-- ``Documentation/locking/spinlocks.txt``: la guida di Linus Torvalds agli
+- ``Documentation/locking/spinlocks.rst``: la guida di Linus Torvalds agli
spinlock del kernel.
- Unix Systems for Modern Architectures: Symmetric Multiprocessing and
diff --git a/drivers/gpu/drm/drm_modeset_lock.c b/drivers/gpu/drm/drm_modeset_lock.c
index 53187821df01..fcfe1a03c4a1 100644
--- a/drivers/gpu/drm/drm_modeset_lock.c
+++ b/drivers/gpu/drm/drm_modeset_lock.c
@@ -36,7 +36,7 @@
* of extra utility/tracking out of our acquire-ctx. This is provided
* by &struct drm_modeset_lock and &struct drm_modeset_acquire_ctx.
*
- * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.txt
+ * For basic principles of &ww_mutex, see: Documentation/locking/ww-mutex-design.rst
*
* The basic usage pattern is to::
*
diff --git a/include/linux/lockdep.h b/include/linux/lockdep.h
index 30a0f81aa130..ebeedee924f6 100644
--- a/include/linux/lockdep.h
+++ b/include/linux/lockdep.h
@@ -5,7 +5,7 @@
* Copyright (C) 2006,2007 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
* Copyright (C) 2007 Red Hat, Inc., Peter Zijlstra
*
- * see Documentation/locking/lockdep-design.txt for more details.
+ * see Documentation/locking/lockdep-design.rst for more details.
*/
#ifndef __LINUX_LOCKDEP_H
#define __LINUX_LOCKDEP_H
diff --git a/include/linux/mutex.h b/include/linux/mutex.h
index 3093dd162424..dcd03fee6e01 100644
--- a/include/linux/mutex.h
+++ b/include/linux/mutex.h
@@ -151,7 +151,7 @@ static inline bool mutex_is_locked(struct mutex *lock)
/*
* See kernel/locking/mutex.c for detailed documentation of these APIs.
- * Also see Documentation/locking/mutex-design.txt.
+ * Also see Documentation/locking/mutex-design.rst.
*/
#ifdef CONFIG_DEBUG_LOCK_ALLOC
extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
diff --git a/include/linux/rwsem.h b/include/linux/rwsem.h
index 2ea18a3def04..61a084ae17ac 100644
--- a/include/linux/rwsem.h
+++ b/include/linux/rwsem.h
@@ -158,7 +158,7 @@ extern void downgrade_write(struct rw_semaphore *sem);
* static then another method for expressing nested locking is
* the explicit definition of lock class keys and the use of
* lockdep_set_class() at lock initialization time.
- * See Documentation/locking/lockdep-design.txt for more details.)
+ * See Documentation/locking/lockdep-design.rst for more details.)
*/
extern void down_read_nested(struct rw_semaphore *sem, int subclass);
extern void down_write_nested(struct rw_semaphore *sem, int subclass);
diff --git a/kernel/locking/mutex.c b/kernel/locking/mutex.c
index 0c601ae072b3..edd1c082dbf5 100644
--- a/kernel/locking/mutex.c
+++ b/kernel/locking/mutex.c
@@ -16,7 +16,7 @@
* by Steven Rostedt, based on work by Gregory Haskins, Peter Morreale
* and Sven Dietrich.
*
- * Also see Documentation/locking/mutex-design.txt.
+ * Also see Documentation/locking/mutex-design.rst.
*/
#include <linux/mutex.h>
#include <linux/ww_mutex.h>
diff --git a/kernel/locking/rtmutex.c b/kernel/locking/rtmutex.c
index 38fbf9fa7f1b..fa83d36e30c6 100644
--- a/kernel/locking/rtmutex.c
+++ b/kernel/locking/rtmutex.c
@@ -9,7 +9,7 @@
* Copyright (C) 2005 Kihon Technologies Inc., Steven Rostedt
* Copyright (C) 2006 Esben Nielsen
*
- * See Documentation/locking/rt-mutex-design.txt for details.
+ * See Documentation/locking/rt-mutex-design.rst for details.
*/
#include <linux/spinlock.h>
#include <linux/export.h>
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index 3a3554e8ca0f..0a3abf806ae8 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1132,7 +1132,7 @@ config PROVE_LOCKING
the proof of observed correctness is also maintained for an
arbitrary combination of these separate locking variants.
- For more details, see Documentation/locking/lockdep-design.txt.
+ For more details, see Documentation/locking/lockdep-design.rst.
config LOCK_STAT
bool "Lock usage statistics"
@@ -1146,7 +1146,7 @@ config LOCK_STAT
help
This feature enables tracking lock contention points
- For more details, see Documentation/locking/lockstat.txt
+ For more details, see Documentation/locking/lockstat.rst
This also enables lock events required by "perf lock",
subcommand of perf.
--
2.21.0
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH v4 14/28] docs: locking: convert docs to ReST and rename to *.rst
2019-06-12 17:52 ` [PATCH v4 14/28] docs: locking: " Mauro Carvalho Chehab
@ 2019-06-14 20:36 ` Jonathan Corbet
0 siblings, 0 replies; 12+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Peter Zijlstra, Ingo Molnar, Will Deacon, Federico Vaga,
Maarten Lankhorst, Maxime Ripard, Sean Paul, David Airlie,
Daniel Vetter, dri-devel
On Wed, 12 Jun 2019 14:52:50 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert the locking documents to ReST and add them to the
> kernel development book where it belongs.
>
> Most of the stuff here is just to make Sphinx to properly
> parse the text file, as they're already in good shape,
> not requiring massive changes in order to be parsed.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
This patch contains linux-next changes and doesn't apply to docs-next.
Perhaps the best thing to do is to apply it to the locking tree?
Thanks,
jon
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst
[not found] <cover.1560361364.git.mchehab+samsung@kernel.org>
` (2 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 14/28] docs: locking: " Mauro Carvalho Chehab
@ 2019-06-12 17:52 ` Mauro Carvalho Chehab
2019-06-13 0:25 ` Srivatsa S. Bhat
[not found] ` <fac44e1fbab5ea755a93601a4fdfa34fcc57ae9e.1560361364.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
2019-06-12 17:53 ` [PATCH v4 28/28] docs: EDID/HOWTO.txt: convert it and rename to howto.rst Mauro Carvalho Chehab
4 siblings, 2 replies; 12+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:52 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Sebastian Reichel, Rafael J. Wysocki,
Viresh Kumar, Len Brown, Pavel Machek, Nishanth Menon,
Stephen Boyd, Liam Girdwood, Mark Brown, Mathieu Poirier,
Suzuki K Poulose, Harry Wei, Alex Shi, Thomas Gleixner,
Ingo Molnar, Borislav Petkov, H. Peter Anvin
Convert the PM documents to ReST, in order to allow them to
build with Sphinx.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Bjorn Helgaas <bhelgaas@google.com>
Acked-by: Mark Brown <broonie@kernel.org>
---
.../ABI/testing/sysfs-class-powercap | 2 +-
.../admin-guide/kernel-parameters.txt | 6 +-
Documentation/cpu-freq/core.txt | 2 +-
Documentation/driver-api/pm/devices.rst | 6 +-
.../driver-api/usb/power-management.rst | 2 +-
.../power/{apm-acpi.txt => apm-acpi.rst} | 10 +-
...m-debugging.txt => basic-pm-debugging.rst} | 79 +--
...harger-manager.txt => charger-manager.rst} | 101 ++--
...rivers-testing.txt => drivers-testing.rst} | 15 +-
.../{energy-model.txt => energy-model.rst} | 101 ++--
...ing-of-tasks.txt => freezing-of-tasks.rst} | 91 ++--
Documentation/power/index.rst | 46 ++
.../power/{interface.txt => interface.rst} | 24 +-
Documentation/power/{opp.txt => opp.rst} | 175 +++---
Documentation/power/{pci.txt => pci.rst} | 87 ++-
...qos_interface.txt => pm_qos_interface.rst} | 127 +++--
Documentation/power/power_supply_class.rst | 282 ++++++++++
Documentation/power/power_supply_class.txt | 231 --------
Documentation/power/powercap/powercap.rst | 257 +++++++++
Documentation/power/powercap/powercap.txt | 236 ---------
.../regulator/{consumer.txt => consumer.rst} | 141 ++---
.../regulator/{design.txt => design.rst} | 9 +-
.../regulator/{machine.txt => machine.rst} | 47 +-
.../regulator/{overview.txt => overview.rst} | 57 +-
Documentation/power/regulator/regulator.rst | 32 ++
Documentation/power/regulator/regulator.txt | 30 --
.../power/{runtime_pm.txt => runtime_pm.rst} | 234 ++++----
Documentation/power/{s2ram.txt => s2ram.rst} | 20 +-
...hotplug.txt => suspend-and-cpuhotplug.rst} | 42 +-
...errupts.txt => suspend-and-interrupts.rst} | 2 +
...ap-files.txt => swsusp-and-swap-files.rst} | 17 +-
...{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} | 120 ++---
Documentation/power/swsusp.rst | 501 ++++++++++++++++++
Documentation/power/swsusp.txt | 446 ----------------
.../power/{tricks.txt => tricks.rst} | 6 +-
...serland-swsusp.txt => userland-swsusp.rst} | 55 +-
Documentation/power/{video.txt => video.rst} | 156 +++---
Documentation/process/submitting-drivers.rst | 2 +-
Documentation/scheduler/sched-energy.txt | 6 +-
Documentation/trace/coresight-cpu-debug.txt | 2 +-
.../zh_CN/process/submitting-drivers.rst | 2 +-
MAINTAINERS | 4 +-
arch/x86/Kconfig | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 2 +-
drivers/opp/Kconfig | 2 +-
drivers/power/supply/power_supply_core.c | 2 +-
include/linux/interrupt.h | 2 +-
include/linux/pci.h | 2 +-
include/linux/pm.h | 2 +-
kernel/power/Kconfig | 6 +-
net/wireless/Kconfig | 2 +-
51 files changed, 2126 insertions(+), 1707 deletions(-)
rename Documentation/power/{apm-acpi.txt => apm-acpi.rst} (87%)
rename Documentation/power/{basic-pm-debugging.txt => basic-pm-debugging.rst} (87%)
rename Documentation/power/{charger-manager.txt => charger-manager.rst} (78%)
rename Documentation/power/{drivers-testing.txt => drivers-testing.rst} (86%)
rename Documentation/power/{energy-model.txt => energy-model.rst} (74%)
rename Documentation/power/{freezing-of-tasks.txt => freezing-of-tasks.rst} (75%)
create mode 100644 Documentation/power/index.rst
rename Documentation/power/{interface.txt => interface.rst} (84%)
rename Documentation/power/{opp.txt => opp.rst} (78%)
rename Documentation/power/{pci.txt => pci.rst} (97%)
rename Documentation/power/{pm_qos_interface.txt => pm_qos_interface.rst} (62%)
create mode 100644 Documentation/power/power_supply_class.rst
delete mode 100644 Documentation/power/power_supply_class.txt
create mode 100644 Documentation/power/powercap/powercap.rst
delete mode 100644 Documentation/power/powercap/powercap.txt
rename Documentation/power/regulator/{consumer.txt => consumer.rst} (61%)
rename Documentation/power/regulator/{design.txt => design.rst} (86%)
rename Documentation/power/regulator/{machine.txt => machine.rst} (75%)
rename Documentation/power/regulator/{overview.txt => overview.rst} (79%)
create mode 100644 Documentation/power/regulator/regulator.rst
delete mode 100644 Documentation/power/regulator/regulator.txt
rename Documentation/power/{runtime_pm.txt => runtime_pm.rst} (89%)
rename Documentation/power/{s2ram.txt => s2ram.rst} (92%)
rename Documentation/power/{suspend-and-cpuhotplug.txt => suspend-and-cpuhotplug.rst} (90%)
rename Documentation/power/{suspend-and-interrupts.txt => suspend-and-interrupts.rst} (98%)
rename Documentation/power/{swsusp-and-swap-files.txt => swsusp-and-swap-files.rst} (83%)
rename Documentation/power/{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} (67%)
create mode 100644 Documentation/power/swsusp.rst
delete mode 100644 Documentation/power/swsusp.txt
rename Documentation/power/{tricks.txt => tricks.rst} (93%)
rename Documentation/power/{userland-swsusp.txt => userland-swsusp.rst} (85%)
rename Documentation/power/{video.txt => video.rst} (56%)
diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
index db3b3ff70d84..742dfd966592 100644
--- a/Documentation/ABI/testing/sysfs-class-powercap
+++ b/Documentation/ABI/testing/sysfs-class-powercap
@@ -5,7 +5,7 @@ Contact: linux-pm@vger.kernel.org
Description:
The powercap/ class sub directory belongs to the power cap
subsystem. Refer to
- Documentation/power/powercap/powercap.txt for details.
+ Documentation/power/powercap/powercap.rst for details.
What: /sys/class/powercap/<control type>
Date: September 2013
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index c31373f39240..0092a453f7dc 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -13,7 +13,7 @@
For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force"
are available
- See also Documentation/power/runtime_pm.txt, pci=noacpi
+ See also Documentation/power/runtime_pm.rst, pci=noacpi
acpi_apic_instance= [ACPI, IOAPIC]
Format: <int>
@@ -223,7 +223,7 @@
acpi_sleep= [HW,ACPI] Sleep options
Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig,
old_ordering, nonvs, sci_force_enable, nobl }
- See Documentation/power/video.txt for information on
+ See Documentation/power/video.rst for information on
s3_bios and s3_mode.
s3_beep is for debugging; it makes the PC's speaker beep
as soon as the kernel's real-mode entry point is called.
@@ -4128,7 +4128,7 @@
Specify the offset from the beginning of the partition
given by "resume=" at which the swap header is located,
in <PAGE_SIZE> units (needed only for swap files).
- See Documentation/power/swsusp-and-swap-files.txt
+ See Documentation/power/swsusp-and-swap-files.rst
resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to
read the resume files
diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt
index 073f128af5a7..55193e680250 100644
--- a/Documentation/cpu-freq/core.txt
+++ b/Documentation/cpu-freq/core.txt
@@ -95,7 +95,7 @@ flags - flags of the cpufreq driver
3. CPUFreq Table Generation with Operating Performance Point (OPP)
==================================================================
-For details about OPP, see Documentation/power/opp.txt
+For details about OPP, see Documentation/power/opp.rst
dev_pm_opp_init_cpufreq_table -
This function provides a ready to use conversion routine to translate
diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
index 30835683616a..f66c7b9126ea 100644
--- a/Documentation/driver-api/pm/devices.rst
+++ b/Documentation/driver-api/pm/devices.rst
@@ -225,7 +225,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto`
flag is clear.
For more information about the runtime power management framework, refer to
-:file:`Documentation/power/runtime_pm.txt`.
+:file:`Documentation/power/runtime_pm.rst`.
Calling Drivers to Enter and Leave System Sleep States
@@ -728,7 +728,7 @@ it into account in any way.
Devices may be defined as IRQ-safe which indicates to the PM core that their
runtime PM callbacks may be invoked with disabled interrupts (see
-:file:`Documentation/power/runtime_pm.txt` for more information). If an
+:file:`Documentation/power/runtime_pm.rst` for more information). If an
IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
disallowed, unless the domain itself is defined as IRQ-safe. However, it
makes sense to define a PM domain as IRQ-safe only if all the devices in it
@@ -795,7 +795,7 @@ so on) and the final state of the device must reflect the "active" runtime PM
status in that case.
During system-wide resume from a sleep state it's easiest to put devices into
-the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`.
+the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
[Refer to that document for more information regarding this particular issue as
well as for information on the device runtime power management framework in
general.]
diff --git a/Documentation/driver-api/usb/power-management.rst b/Documentation/driver-api/usb/power-management.rst
index 4a74cf6f2797..2525c3622cae 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -46,7 +46,7 @@ device is turned off while the system as a whole remains running, we
call it a "dynamic suspend" (also known as a "runtime suspend" or
"selective suspend"). This document concentrates mostly on how
dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see ``Documentation/power/*.txt`` for more
+covered to some extent (see ``Documentation/power/*.rst`` for more
information about system PM).
System PM support is present only if the kernel was built with
diff --git a/Documentation/power/apm-acpi.txt b/Documentation/power/apm-acpi.rst
similarity index 87%
rename from Documentation/power/apm-acpi.txt
rename to Documentation/power/apm-acpi.rst
index 6cc423d3662e..5b90d947126d 100644
--- a/Documentation/power/apm-acpi.txt
+++ b/Documentation/power/apm-acpi.rst
@@ -1,5 +1,7 @@
+============
APM or ACPI?
-------------
+============
+
If you have a relatively recent x86 mobile, desktop, or server system,
odds are it supports either Advanced Power Management (APM) or
Advanced Configuration and Power Interface (ACPI). ACPI is the newer
@@ -28,5 +30,7 @@ and be sure that they are started sometime in the system boot process.
Go ahead and start both. If ACPI or APM is not available on your
system the associated daemon will exit gracefully.
- apmd: http://ftp.debian.org/pool/main/a/apmd/
- acpid: http://acpid.sf.net/
+ ===== =======================================
+ apmd http://ftp.debian.org/pool/main/a/apmd/
+ acpid http://acpid.sf.net/
+ ===== =======================================
diff --git a/Documentation/power/basic-pm-debugging.txt b/Documentation/power/basic-pm-debugging.rst
similarity index 87%
rename from Documentation/power/basic-pm-debugging.txt
rename to Documentation/power/basic-pm-debugging.rst
index 708f87f78a75..69862e759c30 100644
--- a/Documentation/power/basic-pm-debugging.txt
+++ b/Documentation/power/basic-pm-debugging.rst
@@ -1,12 +1,16 @@
+=================================
Debugging hibernation and suspend
+=================================
+
(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
1. Testing hibernation (aka suspend to disk or STD)
+===================================================
-To check if hibernation works, you can try to hibernate in the "reboot" mode:
+To check if hibernation works, you can try to hibernate in the "reboot" mode::
-# echo reboot > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo reboot > /sys/power/disk
+ # echo disk > /sys/power/state
and the system should create a hibernation image, reboot, resume and get back to
the command prompt where you have started the transition. If that happens,
@@ -15,20 +19,21 @@ test at least a couple of times in a row for confidence. [This is necessary,
because some problems only show up on a second attempt at suspending and
resuming the system.] Moreover, hibernating in the "reboot" and "shutdown"
modes causes the PM core to skip some platform-related callbacks which on ACPI
-systems might be necessary to make hibernation work. Thus, if your machine fails
-to hibernate or resume in the "reboot" mode, you should try the "platform" mode:
+systems might be necessary to make hibernation work. Thus, if your machine
+fails to hibernate or resume in the "reboot" mode, you should try the
+"platform" mode::
-# echo platform > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo platform > /sys/power/disk
+ # echo disk > /sys/power/state
which is the default and recommended mode of hibernation.
Unfortunately, the "platform" mode of hibernation does not work on some systems
with broken BIOSes. In such cases the "shutdown" mode of hibernation might
-work:
+work::
-# echo shutdown > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo shutdown > /sys/power/disk
+ # echo disk > /sys/power/state
(it is similar to the "reboot" mode, but it requires you to press the power
button to make the system resume).
@@ -37,6 +42,7 @@ If neither "platform" nor "shutdown" hibernation mode works, you will need to
identify what goes wrong.
a) Test modes of hibernation
+----------------------------
To find out why hibernation fails on your system, you can use a special testing
facility available if the kernel is compiled with CONFIG_PM_DEBUG set. Then,
@@ -44,36 +50,38 @@ there is the file /sys/power/pm_test that can be used to make the hibernation
core run in a test mode. There are 5 test modes available:
freezer
-- test the freezing of processes
+ - test the freezing of processes
devices
-- test the freezing of processes and suspending of devices
+ - test the freezing of processes and suspending of devices
platform
-- test the freezing of processes, suspending of devices and platform
- global control methods(*)
+ - test the freezing of processes, suspending of devices and platform
+ global control methods [1]_
processors
-- test the freezing of processes, suspending of devices, platform
- global control methods(*) and the disabling of nonboot CPUs
+ - test the freezing of processes, suspending of devices, platform
+ global control methods [1]_ and the disabling of nonboot CPUs
core
-- test the freezing of processes, suspending of devices, platform global
- control methods(*), the disabling of nonboot CPUs and suspending of
- platform/system devices
+ - test the freezing of processes, suspending of devices, platform global
+ control methods\ [1]_, the disabling of nonboot CPUs and suspending
+ of platform/system devices
-(*) the platform global control methods are only available on ACPI systems
+.. [1]
+
+ the platform global control methods are only available on ACPI systems
and are only tested if the hibernation mode is set to "platform"
To use one of them it is necessary to write the corresponding string to
/sys/power/pm_test (eg. "devices" to test the freezing of processes and
suspending devices) and issue the standard hibernation commands. For example,
to use the "devices" test mode along with the "platform" mode of hibernation,
-you should do the following:
+you should do the following::
-# echo devices > /sys/power/pm_test
-# echo platform > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo devices > /sys/power/pm_test
+ # echo platform > /sys/power/disk
+ # echo disk > /sys/power/state
Then, the kernel will try to freeze processes, suspend devices, wait a few
seconds (5 by default, but configurable by the suspend.pm_test_delay module
@@ -108,11 +116,12 @@ If the "devices" test fails, most likely there is a driver that cannot suspend
or resume its device (in the latter case the system may hang or become unstable
after the test, so please take that into consideration). To find this driver,
you can carry out a binary search according to the rules:
+
- if the test fails, unload a half of the drivers currently loaded and repeat
-(that would probably involve rebooting the system, so always note what drivers
-have been loaded before the test),
+ (that would probably involve rebooting the system, so always note what drivers
+ have been loaded before the test),
- if the test succeeds, load a half of the drivers you have unloaded most
-recently and repeat.
+ recently and repeat.
Once you have found the failing driver (there can be more than just one of
them), you have to unload it every time before hibernation. In that case please
@@ -146,6 +155,7 @@ indicates a serious problem that very well may be related to the hardware, but
please report it anyway.
b) Testing minimal configuration
+--------------------------------
If all of the hibernation test modes work, you can boot the system with the
"init=/bin/bash" command line parameter and attempt to hibernate in the
@@ -165,14 +175,15 @@ Again, if you find the offending module(s), it(they) must be unloaded every time
before hibernation, and please report the problem with it(them).
c) Using the "test_resume" hibernation option
+---------------------------------------------
/sys/power/disk generally tells the kernel what to do after creating a
hibernation image. One of the available options is "test_resume" which
causes the just created image to be used for immediate restoration. Namely,
-after doing:
+after doing::
-# echo test_resume > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo test_resume > /sys/power/disk
+ # echo disk > /sys/power/state
a hibernation image will be created and a resume from it will be triggered
immediately without involving the platform firmware in any way.
@@ -190,6 +201,7 @@ to resume may be related to the differences between the restore and image
kernels.
d) Advanced debugging
+---------------------
In case that hibernation does not work on your system even in the minimal
configuration and compiling more drivers as modules is not practical or some
@@ -200,9 +212,10 @@ kernel messages using the serial console. This may provide you with some
information about the reasons of the suspend (resume) failure. Alternatively,
it may be possible to use a FireWire port for debugging with firescope
(http://v3.sk/~lkundrak/firescope/). On x86 it is also possible to
-use the PM_TRACE mechanism documented in Documentation/power/s2ram.txt .
+use the PM_TRACE mechanism documented in Documentation/power/s2ram.rst .
2. Testing suspend to RAM (STR)
+===============================
To verify that the STR works, it is generally more convenient to use the s2ram
tool available from http://suspend.sf.net and documented at
@@ -230,7 +243,8 @@ you will have to unload them every time before an STR transition (ie. before
you run s2ram), and please report the problems with them.
There is a debugfs entry which shows the suspend to RAM statistics. Here is an
-example of its output.
+example of its output::
+
# mount -t debugfs none /sys/kernel/debug
# cat /sys/kernel/debug/suspend_stats
success: 20
@@ -248,6 +262,7 @@ example of its output.
-16
last_failed_step: suspend
suspend
+
Field success means the success number of suspend to RAM, and field fail means
the failure number. Others are the failure number of different steps of suspend
to RAM. suspend_stats just lists the last 2 failed devices, error number and
diff --git a/Documentation/power/charger-manager.txt b/Documentation/power/charger-manager.rst
similarity index 78%
rename from Documentation/power/charger-manager.txt
rename to Documentation/power/charger-manager.rst
index 9ff1105e58d6..84fab9376792 100644
--- a/Documentation/power/charger-manager.txt
+++ b/Documentation/power/charger-manager.rst
@@ -1,4 +1,7 @@
+===============
Charger Manager
+===============
+
(C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL
Charger Manager provides in-kernel battery charger management that
@@ -55,41 +58,39 @@ Charger Manager supports the following:
notification to users with UEVENT.
2. Global Charger-Manager Data related with suspend_again
-========================================================
+=========================================================
In order to setup Charger Manager with suspend-again feature
(in-suspend monitoring), the user should provide charger_global_desc
-with setup_charger_manager(struct charger_global_desc *).
+with setup_charger_manager(`struct charger_global_desc *`).
This charger_global_desc data for in-suspend monitoring is global
as the name suggests. Thus, the user needs to provide only once even
if there are multiple batteries. If there are multiple batteries, the
multiple instances of Charger Manager share the same charger_global_desc
and it will manage in-suspend monitoring for all instances of Charger Manager.
-The user needs to provide all the three entries properly in order to activate
-in-suspend monitoring:
+The user needs to provide all the three entries to `struct charger_global_desc`
+properly in order to activate in-suspend monitoring:
-struct charger_global_desc {
-
-char *rtc_name;
- : The name of rtc (e.g., "rtc0") used to wakeup the system from
+`char *rtc_name;`
+ The name of rtc (e.g., "rtc0") used to wakeup the system from
suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
should be able to wake up the system from suspend. Charger Manager
saves and restores the alarm value and use the previously-defined
alarm if it is going to go off earlier than Charger Manager so that
Charger Manager does not interfere with previously-defined alarms.
-bool (*rtc_only_wakeup)(void);
- : This callback should let CM know whether
+`bool (*rtc_only_wakeup)(void);`
+ This callback should let CM know whether
the wakeup-from-suspend is caused only by the alarm of "rtc" in the
same struct. If there is any other wakeup source triggered the
wakeup, it should return false. If the "rtc" is the only wakeup
reason, it should return true.
-bool assume_timer_stops_in_suspend;
- : if true, Charger Manager assumes that
+`bool assume_timer_stops_in_suspend;`
+ if true, Charger Manager assumes that
the timer (CM uses jiffies as timer) stops during suspend. Then, CM
assumes that the suspend-duration is same as the alarm length.
-};
+
3. How to setup suspend_again
=============================
@@ -109,26 +110,28 @@ if the system was woken up by Charger Manager and the polling
=============================================
For each battery charged independently from other batteries (if a series of
batteries are charged by a single charger, they are counted as one independent
-battery), an instance of Charger Manager is attached to it.
+battery), an instance of Charger Manager is attached to it. The following
-struct charger_desc {
+struct charger_desc elements:
-char *psy_name;
- : The power-supply-class name of the battery. Default is
+`char *psy_name;`
+ The power-supply-class name of the battery. Default is
"battery" if psy_name is NULL. Users can access the psy entries
at "/sys/class/power_supply/[psy_name]/".
-enum polling_modes polling_mode;
- : CM_POLL_DISABLE: do not poll this battery.
- CM_POLL_ALWAYS: always poll this battery.
- CM_POLL_EXTERNAL_POWER_ONLY: poll this battery if and only if
- an external power source is attached.
- CM_POLL_CHARGING_ONLY: poll this battery if and only if the
- battery is being charged.
+`enum polling_modes polling_mode;`
+ CM_POLL_DISABLE:
+ do not poll this battery.
+ CM_POLL_ALWAYS:
+ always poll this battery.
+ CM_POLL_EXTERNAL_POWER_ONLY:
+ poll this battery if and only if an external power
+ source is attached.
+ CM_POLL_CHARGING_ONLY:
+ poll this battery if and only if the battery is being charged.
-unsigned int fullbatt_vchkdrop_ms;
-unsigned int fullbatt_vchkdrop_uV;
- : If both have non-zero values, Charger Manager will check the
+`unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;`
+ If both have non-zero values, Charger Manager will check the
battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
Manager will try to recharge the battery by disabling and enabling
@@ -136,50 +139,52 @@ unsigned int fullbatt_vchkdrop_uV;
condition) is needed to be implemented with hardware interrupts from
fuel gauges or charger devices/chips.
-unsigned int fullbatt_uV;
- : If specified with a non-zero value, Charger Manager assumes
+`unsigned int fullbatt_uV;`
+ If specified with a non-zero value, Charger Manager assumes
that the battery is full (capacity = 100) if the battery is not being
charged and the battery voltage is equal to or greater than
fullbatt_uV.
-unsigned int polling_interval_ms;
- : Required polling interval in ms. Charger Manager will poll
+`unsigned int polling_interval_ms;`
+ Required polling interval in ms. Charger Manager will poll
this battery every polling_interval_ms or more frequently.
-enum data_source battery_present;
- : CM_BATTERY_PRESENT: assume that the battery exists.
- CM_NO_BATTERY: assume that the battery does not exists.
- CM_FUEL_GAUGE: get battery presence information from fuel gauge.
- CM_CHARGER_STAT: get battery presence from chargers.
+`enum data_source battery_present;`
+ CM_BATTERY_PRESENT:
+ assume that the battery exists.
+ CM_NO_BATTERY:
+ assume that the battery does not exists.
+ CM_FUEL_GAUGE:
+ get battery presence information from fuel gauge.
+ CM_CHARGER_STAT:
+ get battery presence from chargers.
-char **psy_charger_stat;
- : An array ending with NULL that has power-supply-class names of
+`char **psy_charger_stat;`
+ An array ending with NULL that has power-supply-class names of
chargers. Each power-supply-class should provide "PRESENT" (if
battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an
external power source is attached or not), and "STATUS" (shows whether
the battery is {"FULL" or not FULL} or {"FULL", "Charging",
"Discharging", "NotCharging"}).
-int num_charger_regulators;
-struct regulator_bulk_data *charger_regulators;
- : Regulators representing the chargers in the form for
+`int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;`
+ Regulators representing the chargers in the form for
regulator framework's bulk functions.
-char *psy_fuel_gauge;
- : Power-supply-class name of the fuel gauge.
+`char *psy_fuel_gauge;`
+ Power-supply-class name of the fuel gauge.
-int (*temperature_out_of_range)(int *mC);
-bool measure_battery_temp;
- : This callback returns 0 if the temperature is safe for charging,
+`int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;`
+ This callback returns 0 if the temperature is safe for charging,
a positive number if it is too hot to charge, and a negative number
if it is too cold to charge. With the variable mC, the callback returns
the temperature in 1/1000 of centigrade.
The source of temperature can be battery or ambient one according to
the value of measure_battery_temp.
-};
+
5. Notify Charger-Manager of charger events: cm_notify_event()
-=========================================================
+==============================================================
If there is an charger event is required to notify
Charger Manager, a charger device driver that triggers the event can call
cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager.
diff --git a/Documentation/power/drivers-testing.txt b/Documentation/power/drivers-testing.rst
similarity index 86%
rename from Documentation/power/drivers-testing.txt
rename to Documentation/power/drivers-testing.rst
index 638afdf4d6b8..e53f1999fc39 100644
--- a/Documentation/power/drivers-testing.txt
+++ b/Documentation/power/drivers-testing.rst
@@ -1,7 +1,11 @@
+====================================================
Testing suspend and resume support in device drivers
+====================================================
+
(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
1. Preparing the test system
+============================
Unfortunately, to effectively test the support for the system-wide suspend and
resume transitions in a driver, it is necessary to suspend and resume a fully
@@ -14,19 +18,20 @@ the machine's BIOS.
Of course, for this purpose the test system has to be known to suspend and
resume without the driver being tested. Thus, if possible, you should first
resolve all suspend/resume-related problems in the test system before you start
-testing the new driver. Please see Documentation/power/basic-pm-debugging.txt
+testing the new driver. Please see Documentation/power/basic-pm-debugging.rst
for more information about the debugging of suspend/resume functionality.
2. Testing the driver
+=====================
Once you have resolved the suspend/resume-related problems with your test system
without the new driver, you are ready to test it:
a) Build the driver as a module, load it and try the test modes of hibernation
- (see: Documentation/power/basic-pm-debugging.txt, 1).
+ (see: Documentation/power/basic-pm-debugging.rst, 1).
b) Load the driver and attempt to hibernate in the "reboot", "shutdown" and
- "platform" modes (see: Documentation/power/basic-pm-debugging.txt, 1).
+ "platform" modes (see: Documentation/power/basic-pm-debugging.rst, 1).
c) Compile the driver directly into the kernel and try the test modes of
hibernation.
@@ -34,12 +39,12 @@ c) Compile the driver directly into the kernel and try the test modes of
d) Attempt to hibernate with the driver compiled directly into the kernel
in the "reboot", "shutdown" and "platform" modes.
-e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.txt,
+e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.rst,
2). [As far as the STR tests are concerned, it should not matter whether or
not the driver is built as a module.]
f) Attempt to suspend to RAM using the s2ram tool with the driver loaded
- (see: Documentation/power/basic-pm-debugging.txt, 2).
+ (see: Documentation/power/basic-pm-debugging.rst, 2).
Each of the above tests should be repeated several times and the STD tests
should be mixed with the STR tests. If any of them fails, the driver cannot be
diff --git a/Documentation/power/energy-model.txt b/Documentation/power/energy-model.rst
similarity index 74%
rename from Documentation/power/energy-model.txt
rename to Documentation/power/energy-model.rst
index a2b0ae4c76bd..90a345d57ae9 100644
--- a/Documentation/power/energy-model.txt
+++ b/Documentation/power/energy-model.rst
@@ -1,6 +1,6 @@
- ====================
- Energy Model of CPUs
- ====================
+====================
+Energy Model of CPUs
+====================
1. Overview
-----------
@@ -20,7 +20,7 @@ kernel, hence enabling to avoid redundant work.
The figure below depicts an example of drivers (Arm-specific here, but the
approach is applicable to any architecture) providing power costs to the EM
-framework, and interested clients reading the data from it.
+framework, and interested clients reading the data from it::
+---------------+ +-----------------+ +---------------+
| Thermal (IPA) | | Scheduler (EAS) | | Other |
@@ -58,15 +58,17 @@ micro-architectures.
2. Core APIs
------------
- 2.1 Config options
+2.1 Config options
+^^^^^^^^^^^^^^^^^^
CONFIG_ENERGY_MODEL must be enabled to use the EM framework.
- 2.2 Registration of performance domains
+2.2 Registration of performance domains
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Drivers are expected to register performance domains into the EM framework by
-calling the following API:
+calling the following API::
int em_register_perf_domain(cpumask_t *span, unsigned int nr_states,
struct em_data_callback *cb);
@@ -80,7 +82,8 @@ callback, and kernel/power/energy_model.c for further documentation on this
API.
- 2.3 Accessing performance domains
+2.3 Accessing performance domains
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Subsystems interested in the energy model of a CPU can retrieve it using the
em_cpu_get() API. The energy model tables are allocated once upon creation of
@@ -99,46 +102,46 @@ More details about the above APIs can be found in include/linux/energy_model.h.
This section provides a simple example of a CPUFreq driver registering a
performance domain in the Energy Model framework using the (fake) 'foo'
protocol. The driver implements an est_power() function to be provided to the
-EM framework.
+EM framework::
- -> drivers/cpufreq/foo_cpufreq.c
+ -> drivers/cpufreq/foo_cpufreq.c
-01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
-02 {
-03 long freq, power;
-04
-05 /* Use the 'foo' protocol to ceil the frequency */
-06 freq = foo_get_freq_ceil(cpu, *KHz);
-07 if (freq < 0);
-08 return freq;
-09
-10 /* Estimate the power cost for the CPU at the relevant freq. */
-11 power = foo_estimate_power(cpu, freq);
-12 if (power < 0);
-13 return power;
-14
-15 /* Return the values to the EM framework */
-16 *mW = power;
-17 *KHz = freq;
-18
-19 return 0;
-20 }
-21
-22 static int foo_cpufreq_init(struct cpufreq_policy *policy)
-23 {
-24 struct em_data_callback em_cb = EM_DATA_CB(est_power);
-25 int nr_opp, ret;
-26
-27 /* Do the actual CPUFreq init work ... */
-28 ret = do_foo_cpufreq_init(policy);
-29 if (ret)
-30 return ret;
-31
-32 /* Find the number of OPPs for this policy */
-33 nr_opp = foo_get_nr_opp(policy);
-34
-35 /* And register the new performance domain */
-36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
-37
-38 return 0;
-39 }
+ 01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
+ 02 {
+ 03 long freq, power;
+ 04
+ 05 /* Use the 'foo' protocol to ceil the frequency */
+ 06 freq = foo_get_freq_ceil(cpu, *KHz);
+ 07 if (freq < 0);
+ 08 return freq;
+ 09
+ 10 /* Estimate the power cost for the CPU at the relevant freq. */
+ 11 power = foo_estimate_power(cpu, freq);
+ 12 if (power < 0);
+ 13 return power;
+ 14
+ 15 /* Return the values to the EM framework */
+ 16 *mW = power;
+ 17 *KHz = freq;
+ 18
+ 19 return 0;
+ 20 }
+ 21
+ 22 static int foo_cpufreq_init(struct cpufreq_policy *policy)
+ 23 {
+ 24 struct em_data_callback em_cb = EM_DATA_CB(est_power);
+ 25 int nr_opp, ret;
+ 26
+ 27 /* Do the actual CPUFreq init work ... */
+ 28 ret = do_foo_cpufreq_init(policy);
+ 29 if (ret)
+ 30 return ret;
+ 31
+ 32 /* Find the number of OPPs for this policy */
+ 33 nr_opp = foo_get_nr_opp(policy);
+ 34
+ 35 /* And register the new performance domain */
+ 36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
+ 37
+ 38 return 0;
+ 39 }
diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.rst
similarity index 75%
rename from Documentation/power/freezing-of-tasks.txt
rename to Documentation/power/freezing-of-tasks.rst
index cd283190855a..ef110fe55e82 100644
--- a/Documentation/power/freezing-of-tasks.txt
+++ b/Documentation/power/freezing-of-tasks.rst
@@ -1,13 +1,18 @@
+=================
Freezing of tasks
- (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
+=================
+
+(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
I. What is the freezing of tasks?
+=================================
The freezing of tasks is a mechanism by which user space processes and some
kernel threads are controlled during hibernation or system-wide suspend (on some
architectures).
II. How does it work?
+=====================
There are three per-task flags used for that, PF_NOFREEZE, PF_FROZEN
and PF_FREEZER_SKIP (the last one is auxiliary). The tasks that have
@@ -41,7 +46,7 @@ explicitly in suitable places or use the wait_event_freezable() or
wait_event_freezable_timeout() macros (defined in include/linux/freezer.h)
that combine interruptible sleep with checking if the task is to be frozen and
calling try_to_freeze(). The main loop of a freezable kernel thread may look
-like the following one:
+like the following one::
set_freezable();
do {
@@ -65,7 +70,7 @@ order to clear the PF_FROZEN flag for each frozen task. Then, the tasks that
have been frozen leave __refrigerator() and continue running.
-Rationale behind the functions dealing with freezing and thawing of tasks:
+Rationale behind the functions dealing with freezing and thawing of tasks
-------------------------------------------------------------------------
freeze_processes():
@@ -86,6 +91,7 @@ thaw_processes():
III. Which kernel threads are freezable?
+========================================
Kernel threads are not freezable by default. However, a kernel thread may clear
PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE
@@ -93,37 +99,39 @@ directly is not allowed). From this point it is regarded as freezable
and must call try_to_freeze() in a suitable place.
IV. Why do we do that?
+======================
Generally speaking, there is a couple of reasons to use the freezing of tasks:
1. The principal reason is to prevent filesystems from being damaged after
-hibernation. At the moment we have no simple means of checkpointing
-filesystems, so if there are any modifications made to filesystem data and/or
-metadata on disks, we cannot bring them back to the state from before the
-modifications. At the same time each hibernation image contains some
-filesystem-related information that must be consistent with the state of the
-on-disk data and metadata after the system memory state has been restored from
-the image (otherwise the filesystems will be damaged in a nasty way, usually
-making them almost impossible to repair). We therefore freeze tasks that might
-cause the on-disk filesystems' data and metadata to be modified after the
-hibernation image has been created and before the system is finally powered off.
-The majority of these are user space processes, but if any of the kernel threads
-may cause something like this to happen, they have to be freezable.
+ hibernation. At the moment we have no simple means of checkpointing
+ filesystems, so if there are any modifications made to filesystem data and/or
+ metadata on disks, we cannot bring them back to the state from before the
+ modifications. At the same time each hibernation image contains some
+ filesystem-related information that must be consistent with the state of the
+ on-disk data and metadata after the system memory state has been restored
+ from the image (otherwise the filesystems will be damaged in a nasty way,
+ usually making them almost impossible to repair). We therefore freeze
+ tasks that might cause the on-disk filesystems' data and metadata to be
+ modified after the hibernation image has been created and before the
+ system is finally powered off. The majority of these are user space
+ processes, but if any of the kernel threads may cause something like this
+ to happen, they have to be freezable.
2. Next, to create the hibernation image we need to free a sufficient amount of
-memory (approximately 50% of available RAM) and we need to do that before
-devices are deactivated, because we generally need them for swapping out. Then,
-after the memory for the image has been freed, we don't want tasks to allocate
-additional memory and we prevent them from doing that by freezing them earlier.
-[Of course, this also means that device drivers should not allocate substantial
-amounts of memory from their .suspend() callbacks before hibernation, but this
-is a separate issue.]
+ memory (approximately 50% of available RAM) and we need to do that before
+ devices are deactivated, because we generally need them for swapping out.
+ Then, after the memory for the image has been freed, we don't want tasks
+ to allocate additional memory and we prevent them from doing that by
+ freezing them earlier. [Of course, this also means that device drivers
+ should not allocate substantial amounts of memory from their .suspend()
+ callbacks before hibernation, but this is a separate issue.]
3. The third reason is to prevent user space processes and some kernel threads
-from interfering with the suspending and resuming of devices. A user space
-process running on a second CPU while we are suspending devices may, for
-example, be troublesome and without the freezing of tasks we would need some
-safeguards against race conditions that might occur in such a case.
+ from interfering with the suspending and resuming of devices. A user space
+ process running on a second CPU while we are suspending devices may, for
+ example, be troublesome and without the freezing of tasks we would need some
+ safeguards against race conditions that might occur in such a case.
Although Linus Torvalds doesn't like the freezing of tasks, he said this in one
of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608):
@@ -132,7 +140,7 @@ of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608):
Linus: In many ways, 'at all'.
-I _do_ realize the IO request queue issues, and that we cannot actually do
+I **do** realize the IO request queue issues, and that we cannot actually do
s2ram with some devices in the middle of a DMA. So we want to be able to
avoid *that*, there's no question about that. And I suspect that stopping
user threads and then waiting for a sync is practically one of the easier
@@ -150,17 +158,18 @@ thawed after the driver's .resume() callback has run, so it won't be accessing
the device while it's suspended.
4. Another reason for freezing tasks is to prevent user space processes from
-realizing that hibernation (or suspend) operation takes place. Ideally, user
-space processes should not notice that such a system-wide operation has occurred
-and should continue running without any problems after the restore (or resume
-from suspend). Unfortunately, in the most general case this is quite difficult
-to achieve without the freezing of tasks. Consider, for example, a process
-that depends on all CPUs being online while it's running. Since we need to
-disable nonboot CPUs during the hibernation, if this process is not frozen, it
-may notice that the number of CPUs has changed and may start to work incorrectly
-because of that.
+ realizing that hibernation (or suspend) operation takes place. Ideally, user
+ space processes should not notice that such a system-wide operation has
+ occurred and should continue running without any problems after the restore
+ (or resume from suspend). Unfortunately, in the most general case this
+ is quite difficult to achieve without the freezing of tasks. Consider,
+ for example, a process that depends on all CPUs being online while it's
+ running. Since we need to disable nonboot CPUs during the hibernation,
+ if this process is not frozen, it may notice that the number of CPUs has
+ changed and may start to work incorrectly because of that.
V. Are there any problems related to the freezing of tasks?
+===========================================================
Yes, there are.
@@ -172,11 +181,12 @@ may be undesirable. That's why kernel threads are not freezable by default.
Second, there are the following two problems related to the freezing of user
space processes:
+
1. Putting processes into an uninterruptible sleep distorts the load average.
2. Now that we have FUSE, plus the framework for doing device drivers in
-userspace, it gets even more complicated because some userspace processes are
-now doing the sorts of things that kernel threads do
-(https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html).
+ userspace, it gets even more complicated because some userspace processes are
+ now doing the sorts of things that kernel threads do
+ (https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html).
The problem 1. seems to be fixable, although it hasn't been fixed so far. The
other one is more serious, but it seems that we can work around it by using
@@ -201,6 +211,7 @@ requested early enough using the suspend notifier API described in
Documentation/driver-api/pm/notifiers.rst.
VI. Are there any precautions to be taken to prevent freezing failures?
+=======================================================================
Yes, there are.
@@ -226,6 +237,8 @@ So, to summarize, use [un]lock_system_sleep() instead of directly using
mutex_[un]lock(&system_transition_mutex). That would prevent freezing failures.
V. Miscellaneous
+================
+
/sys/power/pm_freeze_timeout controls how long it will cost at most to freeze
all user space processes or all freezable kernel threads, in unit of millisecond.
The default value is 20000, with range of unsigned integer.
diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
new file mode 100644
index 000000000000..20415f21e48a
--- /dev/null
+++ b/Documentation/power/index.rst
@@ -0,0 +1,46 @@
+:orphan:
+
+================
+Power Management
+================
+
+.. toctree::
+ :maxdepth: 1
+
+ apm-acpi
+ basic-pm-debugging
+ charger-manager
+ drivers-testing
+ energy-model
+ freezing-of-tasks
+ interface
+ opp
+ pci
+ pm_qos_interface
+ power_supply_class
+ runtime_pm
+ s2ram
+ suspend-and-cpuhotplug
+ suspend-and-interrupts
+ swsusp-and-swap-files
+ swsusp-dmcrypt
+ swsusp
+ video
+ tricks
+
+ userland-swsusp
+
+ powercap/powercap
+
+ regulator/consumer
+ regulator/design
+ regulator/machine
+ regulator/overview
+ regulator/regulator
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/power/interface.txt b/Documentation/power/interface.rst
similarity index 84%
rename from Documentation/power/interface.txt
rename to Documentation/power/interface.rst
index 27df7f98668a..8d270ed27228 100644
--- a/Documentation/power/interface.txt
+++ b/Documentation/power/interface.rst
@@ -1,4 +1,6 @@
+===========================================
Power Management Interface for System Sleep
+===========================================
Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
@@ -11,10 +13,10 @@ mounted at /sys).
Reading from it returns a list of supported sleep states, encoded as:
-'freeze' (Suspend-to-Idle)
-'standby' (Power-On Suspend)
-'mem' (Suspend-to-RAM)
-'disk' (Suspend-to-Disk)
+- 'freeze' (Suspend-to-Idle)
+- 'standby' (Power-On Suspend)
+- 'mem' (Suspend-to-RAM)
+- 'disk' (Suspend-to-Disk)
Suspend-to-Idle is always supported. Suspend-to-Disk is always supported
too as long the kernel has been configured to support hibernation at all
@@ -32,18 +34,18 @@ Specifically, it tells the kernel what to do after creating a hibernation image.
Reading from it returns a list of supported options encoded as:
-'platform' (put the system into sleep using a platform-provided method)
-'shutdown' (shut the system down)
-'reboot' (reboot the system)
-'suspend' (trigger a Suspend-to-RAM transition)
-'test_resume' (resume-after-hibernation test mode)
+- 'platform' (put the system into sleep using a platform-provided method)
+- 'shutdown' (shut the system down)
+- 'reboot' (reboot the system)
+- 'suspend' (trigger a Suspend-to-RAM transition)
+- 'test_resume' (resume-after-hibernation test mode)
The currently selected option is printed in square brackets.
The 'platform' option is only available if the platform provides a special
mechanism to put the system to sleep after creating a hibernation image (ACPI
does that, for example). The 'suspend' option is available if Suspend-to-RAM
-is supported. Refer to Documentation/power/basic-pm-debugging.txt for the
+is supported. Refer to Documentation/power/basic-pm-debugging.rst for the
description of the 'test_resume' option.
To select an option, write the string representing it to /sys/power/disk.
@@ -71,7 +73,7 @@ If /sys/power/pm_trace contains '1', the fingerprint of each suspend/resume
event point in turn will be stored in the RTC memory (overwriting the actual
RTC information), so it will survive a system crash if one occurs right after
storing it and it can be used later to identify the driver that caused the crash
-to happen (see Documentation/power/s2ram.txt for more information).
+to happen (see Documentation/power/s2ram.rst for more information).
Initially it contains '0' which may be changed to '1' by writing a string
representing a nonzero integer into it.
diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.rst
similarity index 78%
rename from Documentation/power/opp.txt
rename to Documentation/power/opp.rst
index 0c007e250cd1..b3cf1def9dee 100644
--- a/Documentation/power/opp.txt
+++ b/Documentation/power/opp.rst
@@ -1,20 +1,23 @@
+==========================================
Operating Performance Points (OPP) Library
==========================================
(C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
-Contents
---------
-1. Introduction
-2. Initial OPP List Registration
-3. OPP Search Functions
-4. OPP Availability Control Functions
-5. OPP Data Retrieval Functions
-6. Data Structures
+.. Contents
+
+ 1. Introduction
+ 2. Initial OPP List Registration
+ 3. OPP Search Functions
+ 4. OPP Availability Control Functions
+ 5. OPP Data Retrieval Functions
+ 6. Data Structures
1. Introduction
===============
+
1.1 What is an Operating Performance Point (OPP)?
+-------------------------------------------------
Complex SoCs of today consists of a multiple sub-modules working in conjunction.
In an operational system executing varied use cases, not all modules in the SoC
@@ -28,16 +31,19 @@ the device will support per domain are called Operating Performance Points or
OPPs.
As an example:
+
Let us consider an MPU device which supports the following:
{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
{1GHz at minimum voltage of 1.3V}
We can represent these as three OPPs as the following {Hz, uV} tuples:
-{300000000, 1000000}
-{800000000, 1200000}
-{1000000000, 1300000}
+
+- {300000000, 1000000}
+- {800000000, 1200000}
+- {1000000000, 1300000}
1.2 Operating Performance Points Library
+----------------------------------------
OPP library provides a set of helper functions to organize and query the OPP
information. The library is located in drivers/base/power/opp.c and the header
@@ -46,9 +52,10 @@ CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on
CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to
optionally boot at a certain OPP without needing cpufreq.
-Typical usage of the OPP library is as follows:
-(users) -> registers a set of default OPPs -> (library)
-SoC framework -> modifies on required cases certain OPPs -> OPP layer
+Typical usage of the OPP library is as follows::
+
+ (users) -> registers a set of default OPPs -> (library)
+ SoC framework -> modifies on required cases certain OPPs -> OPP layer
-> queries to search/retrieve information ->
OPP layer expects each domain to be represented by a unique device pointer. SoC
@@ -57,8 +64,9 @@ list is expected to be an optimally small number typically around 5 per device.
This initial list contains a set of OPPs that the framework expects to be safely
enabled by default in the system.
-Note on OPP Availability:
-------------------------
+Note on OPP Availability
+^^^^^^^^^^^^^^^^^^^^^^^^
+
As the system proceeds to operate, SoC framework may choose to make certain
OPPs available or not available on each device based on various external
factors. Example usage: Thermal management or other exceptional situations where
@@ -88,7 +96,8 @@ registering the OPPs is maintained by OPP library throughout the device
operation. The SoC framework can subsequently control the availability of the
OPPs dynamically using the dev_pm_opp_enable / disable functions.
-dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer.
+dev_pm_opp_add
+ Add a new OPP for a specific domain represented by the device pointer.
The OPP is defined using the frequency and voltage. Once added, the OPP
is assumed to be available and control of it's availability can be done
with the dev_pm_opp_enable/disable functions. OPP library internally stores
@@ -96,9 +105,11 @@ dev_pm_opp_add - Add a new OPP for a specific domain represented by the device p
used by SoC framework to define a optimal list as per the demands of
SoC usage environment.
- WARNING: Do not use this function in interrupt context.
+ WARNING:
+ Do not use this function in interrupt context.
+
+ Example::
- Example:
soc_pm_init()
{
/* Do things */
@@ -125,12 +136,15 @@ Callers of these functions shall call dev_pm_opp_put() after they have used the
OPP. Otherwise the memory for the OPP will never get freed and result in
memleak.
-dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
+dev_pm_opp_find_freq_exact
+ Search for an OPP based on an *exact* frequency and
availability. This function is especially useful to enable an OPP which
is not available by default.
Example: In a case when SoC framework detects a situation where a
higher frequency could be made available, it can use this function to
- find the OPP prior to call the dev_pm_opp_enable to actually make it available.
+ find the OPP prior to call the dev_pm_opp_enable to actually make
+ it available::
+
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
dev_pm_opp_put(opp);
/* dont operate on the pointer.. just do a sanity check.. */
@@ -141,27 +155,34 @@ dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
dev_pm_opp_enable(dev,1000000000);
}
- NOTE: This is the only search function that operates on OPPs which are
- not available.
+ NOTE:
+ This is the only search function that operates on OPPs which are
+ not available.
-dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the
+dev_pm_opp_find_freq_floor
+ Search for an available OPP which is *at most* the
provided frequency. This function is useful while searching for a lesser
match OR operating on OPP information in the order of decreasing
frequency.
- Example: To find the highest opp for a device:
+ Example: To find the highest opp for a device::
+
freq = ULONG_MAX;
opp = dev_pm_opp_find_freq_floor(dev, &freq);
dev_pm_opp_put(opp);
-dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the
+dev_pm_opp_find_freq_ceil
+ Search for an available OPP which is *at least* the
provided frequency. This function is useful while searching for a
higher match OR operating on OPP information in the order of increasing
frequency.
- Example 1: To find the lowest opp for a device:
+ Example 1: To find the lowest opp for a device::
+
freq = 0;
opp = dev_pm_opp_find_freq_ceil(dev, &freq);
dev_pm_opp_put(opp);
- Example 2: A simplified implementation of a SoC cpufreq_driver->target:
+
+ Example 2: A simplified implementation of a SoC cpufreq_driver->target::
+
soc_cpufreq_target(..)
{
/* Do stuff like policy checks etc. */
@@ -184,12 +205,15 @@ fine grained dynamic control of which sets of OPPs are operationally available.
These functions are intended to *temporarily* remove an OPP in conditions such
as thermal considerations (e.g. don't use OPPx until the temperature drops).
-WARNING: Do not use these functions in interrupt context.
+WARNING:
+ Do not use these functions in interrupt context.
-dev_pm_opp_enable - Make a OPP available for operation.
+dev_pm_opp_enable
+ Make a OPP available for operation.
Example: Lets say that 1GHz OPP is to be made available only if the
SoC temperature is lower than a certain threshold. The SoC framework
- implementation might choose to do something as follows:
+ implementation might choose to do something as follows::
+
if (cur_temp < temp_low_thresh) {
/* Enable 1GHz if it was disabled */
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
@@ -201,10 +225,12 @@ dev_pm_opp_enable - Make a OPP available for operation.
goto try_something_else;
}
-dev_pm_opp_disable - Make an OPP to be not available for operation
+dev_pm_opp_disable
+ Make an OPP to be not available for operation
Example: Lets say that 1GHz OPP is to be disabled if the temperature
exceeds a threshold value. The SoC framework implementation might
- choose to do something as follows:
+ choose to do something as follows::
+
if (cur_temp > temp_high_thresh) {
/* Disable 1GHz if it was enabled */
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
@@ -223,11 +249,13 @@ information from the OPP structure is necessary. Once an OPP pointer is
retrieved using the search functions, the following functions can be used by SoC
framework to retrieve the information represented inside the OPP layer.
-dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
+dev_pm_opp_get_voltage
+ Retrieve the voltage represented by the opp pointer.
Example: At a cpufreq transition to a different frequency, SoC
framework requires to set the voltage represented by the OPP using
the regulator framework to the Power Management chip providing the
- voltage.
+ voltage::
+
soc_switch_to_freq_voltage(freq)
{
/* do things */
@@ -239,10 +267,12 @@ dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
/* do other things */
}
-dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
+dev_pm_opp_get_freq
+ Retrieve the freq represented by the opp pointer.
Example: Lets say the SoC framework uses a couple of helper functions
we could pass opp pointers instead of doing additional parameters to
- handle quiet a bit of data parameters.
+ handle quiet a bit of data parameters::
+
soc_cpufreq_target(..)
{
/* do things.. */
@@ -264,9 +294,11 @@ dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
/* do things.. */
}
-dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
+dev_pm_opp_get_opp_count
+ Retrieve the number of available opps for a device
Example: Lets say a co-processor in the SoC needs to know the available
- frequencies in a table, the main processor can notify as following:
+ frequencies in a table, the main processor can notify as following::
+
soc_notify_coproc_available_frequencies()
{
/* Do things */
@@ -289,54 +321,59 @@ dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
==================
Typically an SoC contains multiple voltage domains which are variable. Each
domain is represented by a device pointer. The relationship to OPP can be
-represented as follows:
-SoC
- |- device 1
- | |- opp 1 (availability, freq, voltage)
- | |- opp 2 ..
- ... ...
- | `- opp n ..
- |- device 2
- ...
- `- device m
+represented as follows::
+
+ SoC
+ |- device 1
+ | |- opp 1 (availability, freq, voltage)
+ | |- opp 2 ..
+ ... ...
+ | `- opp n ..
+ |- device 2
+ ...
+ `- device m
OPP library maintains a internal list that the SoC framework populates and
accessed by various functions as described above. However, the structures
representing the actual OPPs and domains are internal to the OPP library itself
to allow for suitable abstraction reusable across systems.
-struct dev_pm_opp - The internal data structure of OPP library which is used to
+struct dev_pm_opp
+ The internal data structure of OPP library which is used to
represent an OPP. In addition to the freq, voltage, availability
information, it also contains internal book keeping information required
for the OPP library to operate on. Pointer to this structure is
provided back to the users such as SoC framework to be used as a
identifier for OPP in the interactions with OPP layer.
- WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the
- users. The defaults of for an instance is populated by dev_pm_opp_add, but the
- availability of the OPP can be modified by dev_pm_opp_enable/disable functions.
+ WARNING:
+ The struct dev_pm_opp pointer should not be parsed or modified by the
+ users. The defaults of for an instance is populated by
+ dev_pm_opp_add, but the availability of the OPP can be modified
+ by dev_pm_opp_enable/disable functions.
-struct device - This is used to identify a domain to the OPP layer. The
+struct device
+ This is used to identify a domain to the OPP layer. The
nature of the device and it's implementation is left to the user of
OPP library such as the SoC framework.
Overall, in a simplistic view, the data structure operations is represented as
-following:
+following::
-Initialization / modification:
- +-----+ /- dev_pm_opp_enable
-dev_pm_opp_add --> | opp | <-------
- | +-----+ \- dev_pm_opp_disable
- \-------> domain_info(device)
+ Initialization / modification:
+ +-----+ /- dev_pm_opp_enable
+ dev_pm_opp_add --> | opp | <-------
+ | +-----+ \- dev_pm_opp_disable
+ \-------> domain_info(device)
-Search functions:
- /-- dev_pm_opp_find_freq_ceil ---\ +-----+
-domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
- \-- dev_pm_opp_find_freq_floor ---/ +-----+
+ Search functions:
+ /-- dev_pm_opp_find_freq_ceil ---\ +-----+
+ domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
+ \-- dev_pm_opp_find_freq_floor ---/ +-----+
-Retrieval functions:
-+-----+ /- dev_pm_opp_get_voltage
-| opp | <---
-+-----+ \- dev_pm_opp_get_freq
+ Retrieval functions:
+ +-----+ /- dev_pm_opp_get_voltage
+ | opp | <---
+ +-----+ \- dev_pm_opp_get_freq
-domain_info <- dev_pm_opp_get_opp_count
+ domain_info <- dev_pm_opp_get_opp_count
diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.rst
similarity index 97%
rename from Documentation/power/pci.txt
rename to Documentation/power/pci.rst
index 8eaf9ee24d43..0e2ef7429304 100644
--- a/Documentation/power/pci.txt
+++ b/Documentation/power/pci.rst
@@ -1,4 +1,6 @@
+====================
PCI Power Management
+====================
Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
@@ -9,14 +11,14 @@ management. Based on previous work by Patrick Mochel <mochel@transmeta.com>
This document only covers the aspects of power management specific to PCI
devices. For general description of the kernel's interfaces related to device
power management refer to Documentation/driver-api/pm/devices.rst and
-Documentation/power/runtime_pm.txt.
+Documentation/power/runtime_pm.rst.
----------------------------------------------------------------------------
+.. contents:
-1. Hardware and Platform Support for PCI Power Management
-2. PCI Subsystem and Device Power Management
-3. PCI Device Drivers and Power Management
-4. Resources
+ 1. Hardware and Platform Support for PCI Power Management
+ 2. PCI Subsystem and Device Power Management
+ 3. PCI Device Drivers and Power Management
+ 4. Resources
1. Hardware and Platform Support for PCI Power Management
@@ -24,6 +26,7 @@ Documentation/power/runtime_pm.txt.
1.1. Native and Platform-Based Power Management
-----------------------------------------------
+
In general, power management is a feature allowing one to save energy by putting
devices into states in which they draw less power (low-power states) at the
price of reduced functionality or performance.
@@ -67,6 +70,7 @@ mechanisms have to be used simultaneously to obtain the desired result.
1.2. Native PCI Power Management
--------------------------------
+
The PCI Bus Power Management Interface Specification (PCI PM Spec) was
introduced between the PCI 2.1 and PCI 2.2 Specifications. It defined a
standard interface for performing various operations related to power
@@ -134,6 +138,7 @@ sufficiently active to generate a wakeup signal.
1.3. ACPI Device Power Management
---------------------------------
+
The platform firmware support for the power management of PCI devices is
system-specific. However, if the system in question is compliant with the
Advanced Configuration and Power Interface (ACPI) Specification, like the
@@ -194,6 +199,7 @@ enabled for the device to be able to generate wakeup signals.
1.4. Wakeup Signaling
---------------------
+
Wakeup signals generated by PCI devices, either as native PCI PMEs, or as
a result of the execution of the _DSW (or _PSW) ACPI control method before
putting the device into a low-power state, have to be caught and handled as
@@ -265,14 +271,15 @@ the native PCI Express PME signaling cannot be used by the kernel in that case.
2.1. Device Power Management Callbacks
--------------------------------------
+
The PCI Subsystem participates in the power management of PCI devices in a
number of ways. First of all, it provides an intermediate code layer between
the device power management core (PM core) and PCI device drivers.
Specifically, the pm field of the PCI subsystem's struct bus_type object,
pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing
-pointers to several device power management callbacks:
+pointers to several device power management callbacks::
-const struct dev_pm_ops pci_dev_pm_ops = {
+ const struct dev_pm_ops pci_dev_pm_ops = {
.prepare = pci_pm_prepare,
.complete = pci_pm_complete,
.suspend = pci_pm_suspend,
@@ -290,7 +297,7 @@ const struct dev_pm_ops pci_dev_pm_ops = {
.runtime_suspend = pci_pm_runtime_suspend,
.runtime_resume = pci_pm_runtime_resume,
.runtime_idle = pci_pm_runtime_idle,
-};
+ };
These callbacks are executed by the PM core in various situations related to
device power management and they, in turn, execute power management callbacks
@@ -299,9 +306,9 @@ involving some standard configuration registers of PCI devices that device
drivers need not know or care about.
The structure representing a PCI device, struct pci_dev, contains several fields
-that these callbacks operate on:
+that these callbacks operate on::
-struct pci_dev {
+ struct pci_dev {
...
pci_power_t current_state; /* Current operating state. */
int pm_cap; /* PM capability offset in the
@@ -315,13 +322,14 @@ struct pci_dev {
unsigned int wakeup_prepared:1; /* Device prepared for wake up */
unsigned int d3_delay; /* D3->D0 transition time in ms */
...
-};
+ };
They also indirectly use some fields of the struct device that is embedded in
struct pci_dev.
2.2. Device Initialization
--------------------------
+
The PCI subsystem's first task related to device power management is to
prepare the device for power management and initialize the fields of struct
pci_dev used for this purpose. This happens in two functions defined in
@@ -348,10 +356,11 @@ during system-wide transitions to a sleep state and back to the working state.
2.3. Runtime Device Power Management
------------------------------------
+
The PCI subsystem plays a vital role in the runtime power management of PCI
devices. For this purpose it uses the general runtime power management
-(runtime PM) framework described in Documentation/power/runtime_pm.txt.
-Namely, it provides subsystem-level callbacks:
+(runtime PM) framework described in Documentation/power/runtime_pm.rst.
+Namely, it provides subsystem-level callbacks::
pci_pm_runtime_suspend()
pci_pm_runtime_resume()
@@ -425,13 +434,14 @@ to the given subsystem before the next phase begins. These phases always run
after tasks have been frozen.
2.4.1. System Suspend
+^^^^^^^^^^^^^^^^^^^^^
When the system is going into a sleep state in which the contents of memory will
be preserved, such as one of the ACPI sleep states S1-S3, the phases are:
prepare, suspend, suspend_noirq.
-The following PCI bus type's callbacks, respectively, are used in these phases:
+The following PCI bus type's callbacks, respectively, are used in these phases::
pci_pm_prepare()
pci_pm_suspend()
@@ -492,6 +502,7 @@ this purpose). PCI device drivers are not encouraged to do that, but in some
rare cases doing that in the driver may be the optimum approach.
2.4.2. System Resume
+^^^^^^^^^^^^^^^^^^^^
When the system is undergoing a transition from a sleep state in which the
contents of memory have been preserved, such as one of the ACPI sleep states
@@ -500,7 +511,7 @@ S1-S3, into the working state (ACPI S0), the phases are:
resume_noirq, resume, complete.
The following PCI bus type's callbacks, respectively, are executed in these
-phases:
+phases::
pci_pm_resume_noirq()
pci_pm_resume()
@@ -539,6 +550,7 @@ The pci_pm_complete() routine only executes the device driver's pm->complete()
callback, if defined.
2.4.3. System Hibernation
+^^^^^^^^^^^^^^^^^^^^^^^^^
System hibernation is more complicated than system suspend, because it requires
a system image to be created and written into a persistent storage medium. The
@@ -551,7 +563,7 @@ to be free) in the following three phases:
prepare, freeze, freeze_noirq
-that correspond to the PCI bus type's callbacks:
+that correspond to the PCI bus type's callbacks::
pci_pm_prepare()
pci_pm_freeze()
@@ -580,7 +592,7 @@ back to the fully functional state and this is done in the following phases:
thaw_noirq, thaw, complete
-using the following PCI bus type's callbacks:
+using the following PCI bus type's callbacks::
pci_pm_thaw_noirq()
pci_pm_thaw()
@@ -608,7 +620,7 @@ three phases:
where the prepare phase is exactly the same as for system suspend. The other
two phases are analogous to the suspend and suspend_noirq phases, respectively.
-The PCI subsystem-level callbacks they correspond to
+The PCI subsystem-level callbacks they correspond to::
pci_pm_poweroff()
pci_pm_poweroff_noirq()
@@ -618,6 +630,7 @@ although they don't attempt to save the device's standard configuration
registers.
2.4.4. System Restore
+^^^^^^^^^^^^^^^^^^^^^
System restore requires a hibernation image to be loaded into memory and the
pre-hibernation memory contents to be restored before the pre-hibernation system
@@ -653,7 +666,7 @@ phases:
The first two of these are analogous to the resume_noirq and resume phases
described above, respectively, and correspond to the following PCI subsystem
-callbacks:
+callbacks::
pci_pm_restore_noirq()
pci_pm_restore()
@@ -671,6 +684,7 @@ resume.
3.1. Power Management Callbacks
-------------------------------
+
PCI device drivers participate in power management by providing callbacks to be
executed by the PCI subsystem's power management routines described above and by
controlling the runtime power management of their devices.
@@ -698,6 +712,7 @@ defined, though, they are expected to behave as described in the following
subsections.
3.1.1. prepare()
+^^^^^^^^^^^^^^^^
The prepare() callback is executed during system suspend, during hibernation
(when a hibernation image is about to be created), during power-off after
@@ -716,6 +731,7 @@ preallocated earlier, for example in a suspend/hibernate notifier as described
in Documentation/driver-api/pm/notifiers.rst).
3.1.2. suspend()
+^^^^^^^^^^^^^^^^
The suspend() callback is only executed during system suspend, after prepare()
callbacks have been executed for all devices in the system.
@@ -742,6 +758,7 @@ operations relying on the driver's ability to handle interrupts should be
carried out in this callback.
3.1.3. suspend_noirq()
+^^^^^^^^^^^^^^^^^^^^^^
The suspend_noirq() callback is only executed during system suspend, after
suspend() callbacks have been executed for all devices in the system and
@@ -753,6 +770,7 @@ suspend_noirq() can carry out operations that would cause race conditions to
arise if they were performed in suspend().
3.1.4. freeze()
+^^^^^^^^^^^^^^^
The freeze() callback is hibernation-specific and is executed in two situations,
during hibernation, after prepare() callbacks have been executed for all devices
@@ -770,6 +788,7 @@ or put it into a low-power state. Still, either it or freeze_noirq() should
save the device's standard configuration registers using pci_save_state().
3.1.5. freeze_noirq()
+^^^^^^^^^^^^^^^^^^^^^
The freeze_noirq() callback is hibernation-specific. It is executed during
hibernation, after prepare() and freeze() callbacks have been executed for all
@@ -786,6 +805,7 @@ The difference between freeze_noirq() and freeze() is analogous to the
difference between suspend_noirq() and suspend().
3.1.6. poweroff()
+^^^^^^^^^^^^^^^^^
The poweroff() callback is hibernation-specific. It is executed when the system
is about to be powered off after saving a hibernation image to a persistent
@@ -802,6 +822,7 @@ into a low-power state, respectively, but it need not save the device's standard
configuration registers.
3.1.7. poweroff_noirq()
+^^^^^^^^^^^^^^^^^^^^^^^
The poweroff_noirq() callback is hibernation-specific. It is executed after
poweroff() callbacks have been executed for all devices in the system.
@@ -814,6 +835,7 @@ The difference between poweroff_noirq() and poweroff() is analogous to the
difference between suspend_noirq() and suspend().
3.1.8. resume_noirq()
+^^^^^^^^^^^^^^^^^^^^^
The resume_noirq() callback is only executed during system resume, after the
PM core has enabled the non-boot CPUs. The driver's interrupt handler will not
@@ -827,6 +849,7 @@ it should only be used for performing operations that would lead to race
conditions if carried out by resume().
3.1.9. resume()
+^^^^^^^^^^^^^^^
The resume() callback is only executed during system resume, after
resume_noirq() callbacks have been executed for all devices in the system and
@@ -837,6 +860,7 @@ device and bringing it back to the fully functional state. The device should be
able to process I/O in a usual way after resume() has returned.
3.1.10. thaw_noirq()
+^^^^^^^^^^^^^^^^^^^^
The thaw_noirq() callback is hibernation-specific. It is executed after a
system image has been created and the non-boot CPUs have been enabled by the PM
@@ -851,6 +875,7 @@ freeze() and freeze_noirq(), so in general it does not need to modify the
contents of the device's registers.
3.1.11. thaw()
+^^^^^^^^^^^^^^
The thaw() callback is hibernation-specific. It is executed after thaw_noirq()
callbacks have been executed for all devices in the system and after device
@@ -860,6 +885,7 @@ This callback is responsible for restoring the pre-freeze configuration of
the device, so that it will work in a usual way after thaw() has returned.
3.1.12. restore_noirq()
+^^^^^^^^^^^^^^^^^^^^^^^
The restore_noirq() callback is hibernation-specific. It is executed in the
restore_noirq phase of hibernation, when the boot kernel has passed control to
@@ -875,6 +901,7 @@ For the vast majority of PCI device drivers there is no difference between
resume_noirq() and restore_noirq().
3.1.13. restore()
+^^^^^^^^^^^^^^^^^
The restore() callback is hibernation-specific. It is executed after
restore_noirq() callbacks have been executed for all devices in the system and
@@ -888,14 +915,17 @@ For the vast majority of PCI device drivers there is no difference between
resume() and restore().
3.1.14. complete()
+^^^^^^^^^^^^^^^^^^
The complete() callback is executed in the following situations:
+
- during system resume, after resume() callbacks have been executed for all
devices,
- during hibernation, before saving the system image, after thaw() callbacks
have been executed for all devices,
- during system restore, when the system is going back to its pre-hibernation
state, after restore() callbacks have been executed for all devices.
+
It also may be executed if the loading of a hibernation image into memory fails
(in that case it is run after thaw() callbacks have been executed for all
devices that have drivers in the boot kernel).
@@ -904,6 +934,7 @@ This callback is entirely optional, although it may be necessary if the
prepare() callback performs operations that need to be reversed.
3.1.15. runtime_suspend()
+^^^^^^^^^^^^^^^^^^^^^^^^^
The runtime_suspend() callback is specific to device runtime power management
(runtime PM). It is executed by the PM core's runtime PM framework when the
@@ -915,6 +946,7 @@ put into a low-power state, but it must allow the PCI subsystem to perform all
of the PCI-specific actions necessary for suspending the device.
3.1.16. runtime_resume()
+^^^^^^^^^^^^^^^^^^^^^^^^
The runtime_resume() callback is specific to device runtime PM. It is executed
by the PM core's runtime PM framework when the device is about to be resumed
@@ -927,6 +959,7 @@ The device is expected to be able to process I/O in the usual way after
runtime_resume() has returned.
3.1.17. runtime_idle()
+^^^^^^^^^^^^^^^^^^^^^^
The runtime_idle() callback is specific to device runtime PM. It is executed
by the PM core's runtime PM framework whenever it may be desirable to suspend
@@ -939,6 +972,7 @@ PCI subsystem will call pm_runtime_suspend() for the device, which in turn will
cause the driver's runtime_suspend() callback to be executed.
3.1.18. Pointing Multiple Callback Pointers to One Routine
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Although in principle each of the callbacks described in the previous
subsections can be defined as a separate function, it often is convenient to
@@ -962,6 +996,7 @@ dev_pm_ops to indicate that one suspend routine is to be pointed to by the
be pointed to by the .resume(), .thaw(), and .restore() members.
3.1.19. Driver Flags for Power Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The PM core allows device drivers to set flags that influence the handling of
power management for the devices by the core itself and by middle layer code
@@ -1007,6 +1042,7 @@ it.
3.2. Device Runtime Power Management
------------------------------------
+
In addition to providing device power management callbacks PCI device drivers
are responsible for controlling the runtime power management (runtime PM) of
their devices.
@@ -1073,22 +1109,27 @@ device the PM core automatically queues a request to check if the device is
idle), device drivers are generally responsible for queuing power management
requests for their devices. For this purpose they should use the runtime PM
helper functions provided by the PM core, discussed in
-Documentation/power/runtime_pm.txt.
+Documentation/power/runtime_pm.rst.
Devices can also be suspended and resumed synchronously, without placing a
request into pm_wq. In the majority of cases this also is done by their
drivers that use helper functions provided by the PM core for this purpose.
For more information on the runtime PM of devices refer to
-Documentation/power/runtime_pm.txt.
+Documentation/power/runtime_pm.rst.
4. Resources
============
PCI Local Bus Specification, Rev. 3.0
+
PCI Bus Power Management Interface Specification, Rev. 1.2
+
Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
+
PCI Express Base Specification, Rev. 2.0
+
Documentation/driver-api/pm/devices.rst
-Documentation/power/runtime_pm.txt
+
+Documentation/power/runtime_pm.rst
diff --git a/Documentation/power/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.rst
similarity index 62%
rename from Documentation/power/pm_qos_interface.txt
rename to Documentation/power/pm_qos_interface.rst
index 19c5f7b1a7ba..945fc6d760c9 100644
--- a/Documentation/power/pm_qos_interface.txt
+++ b/Documentation/power/pm_qos_interface.rst
@@ -1,4 +1,6 @@
-PM Quality Of Service Interface.
+===============================
+PM Quality Of Service Interface
+===============================
This interface provides a kernel and user mode interface for registering
performance expectations by drivers, subsystems and user space applications on
@@ -11,6 +13,7 @@ memory_bandwidth.
constraints and PM QoS flags.
Each parameters have defined units:
+
* latency: usec
* timeout: usec
* throughput: kbs (kilo bit / sec)
@@ -18,6 +21,7 @@ Each parameters have defined units:
1. PM QoS framework
+===================
The infrastructure exposes multiple misc device nodes one per implemented
parameter. The set of parameters implement is defined by pm_qos_power_init()
@@ -37,38 +41,39 @@ reading the aggregated value does not require any locking mechanism.
From kernel mode the use of this interface is simple:
void pm_qos_add_request(handle, param_class, target_value):
-Will insert an element into the list for that identified PM QoS class with the
-target value. Upon change to this list the new target is recomputed and any
-registered notifiers are called only if the target value is now different.
-Clients of pm_qos need to save the returned handle for future use in other
-pm_qos API functions.
+ Will insert an element into the list for that identified PM QoS class with the
+ target value. Upon change to this list the new target is recomputed and any
+ registered notifiers are called only if the target value is now different.
+ Clients of pm_qos need to save the returned handle for future use in other
+ pm_qos API functions.
void pm_qos_update_request(handle, new_target_value):
-Will update the list element pointed to by the handle with the new target value
-and recompute the new aggregated target, calling the notification tree if the
-target is changed.
+ Will update the list element pointed to by the handle with the new target value
+ and recompute the new aggregated target, calling the notification tree if the
+ target is changed.
void pm_qos_remove_request(handle):
-Will remove the element. After removal it will update the aggregate target and
-call the notification tree if the target was changed as a result of removing
-the request.
+ Will remove the element. After removal it will update the aggregate target and
+ call the notification tree if the target was changed as a result of removing
+ the request.
int pm_qos_request(param_class):
-Returns the aggregated value for a given PM QoS class.
+ Returns the aggregated value for a given PM QoS class.
int pm_qos_request_active(handle):
-Returns if the request is still active, i.e. it has not been removed from a
-PM QoS class constraints list.
+ Returns if the request is still active, i.e. it has not been removed from a
+ PM QoS class constraints list.
int pm_qos_add_notifier(param_class, notifier):
-Adds a notification callback function to the PM QoS class. The callback is
-called when the aggregated value for the PM QoS class is changed.
+ Adds a notification callback function to the PM QoS class. The callback is
+ called when the aggregated value for the PM QoS class is changed.
int pm_qos_remove_notifier(int param_class, notifier):
-Removes the notification callback function for the PM QoS class.
+ Removes the notification callback function for the PM QoS class.
From user mode:
+
Only processes can register a pm_qos request. To provide for automatic
cleanup of a process, the interface requires the process to register its
parameter requests in the following way:
@@ -89,6 +94,7 @@ node.
2. PM QoS per-device latency and flags framework
+================================================
For each device, there are three lists of PM QoS requests. Two of them are
maintained along with the aggregated targets of resume latency and active
@@ -107,73 +113,80 @@ the aggregated value does not require any locking mechanism.
From kernel mode the use of this interface is the following:
int dev_pm_qos_add_request(device, handle, type, value):
-Will insert an element into the list for that identified device with the
-target value. Upon change to this list the new target is recomputed and any
-registered notifiers are called only if the target value is now different.
-Clients of dev_pm_qos need to save the handle for future use in other
-dev_pm_qos API functions.
+ Will insert an element into the list for that identified device with the
+ target value. Upon change to this list the new target is recomputed and any
+ registered notifiers are called only if the target value is now different.
+ Clients of dev_pm_qos need to save the handle for future use in other
+ dev_pm_qos API functions.
int dev_pm_qos_update_request(handle, new_value):
-Will update the list element pointed to by the handle with the new target value
-and recompute the new aggregated target, calling the notification trees if the
-target is changed.
+ Will update the list element pointed to by the handle with the new target
+ value and recompute the new aggregated target, calling the notification
+ trees if the target is changed.
int dev_pm_qos_remove_request(handle):
-Will remove the element. After removal it will update the aggregate target and
-call the notification trees if the target was changed as a result of removing
-the request.
+ Will remove the element. After removal it will update the aggregate target
+ and call the notification trees if the target was changed as a result of
+ removing the request.
s32 dev_pm_qos_read_value(device):
-Returns the aggregated value for a given device's constraints list.
+ Returns the aggregated value for a given device's constraints list.
enum pm_qos_flags_status dev_pm_qos_flags(device, mask)
-Check PM QoS flags of the given device against the given mask of flags.
-The meaning of the return values is as follows:
- PM_QOS_FLAGS_ALL: All flags from the mask are set
- PM_QOS_FLAGS_SOME: Some flags from the mask are set
- PM_QOS_FLAGS_NONE: No flags from the mask are set
- PM_QOS_FLAGS_UNDEFINED: The device's PM QoS structure has not been
- initialized or the list of requests is empty.
+ Check PM QoS flags of the given device against the given mask of flags.
+ The meaning of the return values is as follows:
+
+ PM_QOS_FLAGS_ALL:
+ All flags from the mask are set
+ PM_QOS_FLAGS_SOME:
+ Some flags from the mask are set
+ PM_QOS_FLAGS_NONE:
+ No flags from the mask are set
+ PM_QOS_FLAGS_UNDEFINED:
+ The device's PM QoS structure has not been initialized
+ or the list of requests is empty.
int dev_pm_qos_add_ancestor_request(dev, handle, type, value)
-Add a PM QoS request for the first direct ancestor of the given device whose
-power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests)
-or whose power.set_latency_tolerance callback pointer is not NULL (for
-DEV_PM_QOS_LATENCY_TOLERANCE requests).
+ Add a PM QoS request for the first direct ancestor of the given device whose
+ power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests)
+ or whose power.set_latency_tolerance callback pointer is not NULL (for
+ DEV_PM_QOS_LATENCY_TOLERANCE requests).
int dev_pm_qos_expose_latency_limit(device, value)
-Add a request to the device's PM QoS list of resume latency constraints and
-create a sysfs attribute pm_qos_resume_latency_us under the device's power
-directory allowing user space to manipulate that request.
+ Add a request to the device's PM QoS list of resume latency constraints and
+ create a sysfs attribute pm_qos_resume_latency_us under the device's power
+ directory allowing user space to manipulate that request.
void dev_pm_qos_hide_latency_limit(device)
-Drop the request added by dev_pm_qos_expose_latency_limit() from the device's
-PM QoS list of resume latency constraints and remove sysfs attribute
-pm_qos_resume_latency_us from the device's power directory.
+ Drop the request added by dev_pm_qos_expose_latency_limit() from the device's
+ PM QoS list of resume latency constraints and remove sysfs attribute
+ pm_qos_resume_latency_us from the device's power directory.
int dev_pm_qos_expose_flags(device, value)
-Add a request to the device's PM QoS list of flags and create sysfs attribute
-pm_qos_no_power_off under the device's power directory allowing user space to
-change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.
+ Add a request to the device's PM QoS list of flags and create sysfs attribute
+ pm_qos_no_power_off under the device's power directory allowing user space to
+ change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.
void dev_pm_qos_hide_flags(device)
-Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list
-of flags and remove sysfs attribute pm_qos_no_power_off from the device's power
-directory.
+ Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list
+ of flags and remove sysfs attribute pm_qos_no_power_off from the device's power
+ directory.
Notification mechanisms:
+
The per-device PM QoS framework has a per-device notification tree.
int dev_pm_qos_add_notifier(device, notifier):
-Adds a notification callback function for the device.
-The callback is called when the aggregated value of the device constraints list
-is changed (for resume latency device PM QoS only).
+ Adds a notification callback function for the device.
+ The callback is called when the aggregated value of the device constraints list
+ is changed (for resume latency device PM QoS only).
int dev_pm_qos_remove_notifier(device, notifier):
-Removes the notification callback function for the device.
+ Removes the notification callback function for the device.
Active state latency tolerance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This device PM QoS type is used to support systems in which hardware may switch
to energy-saving operation modes on the fly. In those systems, if the operation
diff --git a/Documentation/power/power_supply_class.rst b/Documentation/power/power_supply_class.rst
new file mode 100644
index 000000000000..3f2c3fe38a61
--- /dev/null
+++ b/Documentation/power/power_supply_class.rst
@@ -0,0 +1,282 @@
+========================
+Linux power supply class
+========================
+
+Synopsis
+~~~~~~~~
+Power supply class used to represent battery, UPS, AC or DC power supply
+properties to user-space.
+
+It defines core set of attributes, which should be applicable to (almost)
+every power supply out there. Attributes are available via sysfs and uevent
+interfaces.
+
+Each attribute has well defined meaning, up to unit of measure used. While
+the attributes provided are believed to be universally applicable to any
+power supply, specific monitoring hardware may not be able to provide them
+all, so any of them may be skipped.
+
+Power supply class is extensible, and allows to define drivers own attributes.
+The core attribute set is subject to the standard Linux evolution (i.e.
+if it will be found that some attribute is applicable to many power supply
+types or their drivers, it can be added to the core set).
+
+It also integrates with LED framework, for the purpose of providing
+typically expected feedback of battery charging/fully charged status and
+AC/USB power supply online status. (Note that specific details of the
+indication (including whether to use it at all) are fully controllable by
+user and/or specific machine defaults, per design principles of LED
+framework).
+
+
+Attributes/properties
+~~~~~~~~~~~~~~~~~~~~~
+Power supply class has predefined set of attributes, this eliminates code
+duplication across drivers. Power supply class insist on reusing its
+predefined attributes *and* their units.
+
+So, userspace gets predictable set of attributes and their units for any
+kind of power supply, and can process/present them to a user in consistent
+manner. Results for different power supplies and machines are also directly
+comparable.
+
+See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
+for the example how to declare and handle attributes.
+
+
+Units
+~~~~~
+Quoting include/linux/power_supply.h:
+
+ All voltages, currents, charges, energies, time and temperatures in µV,
+ µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
+ stated. It's driver's job to convert its raw values to units in which
+ this class operates.
+
+
+Attributes/properties detailed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++--------------------------------------------------------------------------+
+| **Charge/Energy/Capacity - how to not confuse** |
++--------------------------------------------------------------------------+
+| **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" |
+| of battery, this class distinguish these terms. Don't mix them!** |
+| |
+| - `CHARGE_*` |
+| attributes represents capacity in µAh only. |
+| - `ENERGY_*` |
+| attributes represents capacity in µWh only. |
+| - `CAPACITY` |
+| attribute represents capacity in *percents*, from 0 to 100. |
++--------------------------------------------------------------------------+
+
+Postfixes:
+
+_AVG
+ *hardware* averaged value, use it if your hardware is really able to
+ report averaged values.
+_NOW
+ momentary/instantaneous values.
+
+STATUS
+ this attribute represents operating status (charging, full,
+ discharging (i.e. powering a load), etc.). This corresponds to
+ `BATTERY_STATUS_*` values, as defined in battery.h.
+
+CHARGE_TYPE
+ batteries can typically charge at different rates.
+ This defines trickle and fast charges. For batteries that
+ are already charged or discharging, 'n/a' can be displayed (or
+ 'unknown', if the status is not known).
+
+AUTHENTIC
+ indicates the power supply (battery or charger) connected
+ to the platform is authentic(1) or non authentic(0).
+
+HEALTH
+ represents health of the battery, values corresponds to
+ POWER_SUPPLY_HEALTH_*, defined in battery.h.
+
+VOLTAGE_OCV
+ open circuit voltage of the battery.
+
+VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN
+ design values for maximal and minimal power supply voltages.
+ Maximal/minimal means values of voltages when battery considered
+ "full"/"empty" at normal conditions. Yes, there is no direct relation
+ between voltage and battery capacity, but some dumb
+ batteries use voltage for very approximated calculation of capacity.
+ Battery driver also can use this attribute just to inform userspace
+ about maximal and minimal voltage thresholds of a given battery.
+
+VOLTAGE_MAX, VOLTAGE_MIN
+ same as _DESIGN voltage values except that these ones should be used
+ if hardware could only guess (measure and retain) the thresholds of a
+ given power supply.
+
+VOLTAGE_BOOT
+ Reports the voltage measured during boot
+
+CURRENT_BOOT
+ Reports the current measured during boot
+
+CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
+ design charge values, when battery considered full/empty.
+
+ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
+ same as above but for energy.
+
+CHARGE_FULL, CHARGE_EMPTY
+ These attributes means "last remembered value of charge when battery
+ became full/empty". It also could mean "value of charge when battery
+ considered full/empty at given conditions (temperature, age)".
+ I.e. these attributes represents real thresholds, not design values.
+
+ENERGY_FULL, ENERGY_EMPTY
+ same as above but for energy.
+
+CHARGE_COUNTER
+ the current charge counter (in µAh). This could easily
+ be negative; there is no empty or full value. It is only useful for
+ relative, time-based measurements.
+
+PRECHARGE_CURRENT
+ the maximum charge current during precharge phase of charge cycle
+ (typically 20% of battery capacity).
+
+CHARGE_TERM_CURRENT
+ Charge termination current. The charge cycle terminates when battery
+ voltage is above recharge threshold, and charge current is below
+ this setting (typically 10% of battery capacity).
+
+CONSTANT_CHARGE_CURRENT
+ constant charge current programmed by charger.
+
+
+CONSTANT_CHARGE_CURRENT_MAX
+ maximum charge current supported by the power supply object.
+
+CONSTANT_CHARGE_VOLTAGE
+ constant charge voltage programmed by charger.
+CONSTANT_CHARGE_VOLTAGE_MAX
+ maximum charge voltage supported by the power supply object.
+
+INPUT_CURRENT_LIMIT
+ input current limit programmed by charger. Indicates
+ the current drawn from a charging source.
+
+CHARGE_CONTROL_LIMIT
+ current charge control limit setting
+CHARGE_CONTROL_LIMIT_MAX
+ maximum charge control limit setting
+
+CALIBRATE
+ battery or coulomb counter calibration status
+
+CAPACITY
+ capacity in percents.
+CAPACITY_ALERT_MIN
+ minimum capacity alert value in percents.
+CAPACITY_ALERT_MAX
+ maximum capacity alert value in percents.
+CAPACITY_LEVEL
+ capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*.
+
+TEMP
+ temperature of the power supply.
+TEMP_ALERT_MIN
+ minimum battery temperature alert.
+TEMP_ALERT_MAX
+ maximum battery temperature alert.
+TEMP_AMBIENT
+ ambient temperature.
+TEMP_AMBIENT_ALERT_MIN
+ minimum ambient temperature alert.
+TEMP_AMBIENT_ALERT_MAX
+ maximum ambient temperature alert.
+TEMP_MIN
+ minimum operatable temperature
+TEMP_MAX
+ maximum operatable temperature
+
+TIME_TO_EMPTY
+ seconds left for battery to be considered empty
+ (i.e. while battery powers a load)
+TIME_TO_FULL
+ seconds left for battery to be considered full
+ (i.e. while battery is charging)
+
+
+Battery <-> external power supply interaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Often power supplies are acting as supplies and supplicants at the same
+time. Batteries are good example. So, batteries usually care if they're
+externally powered or not.
+
+For that case, power supply class implements notification mechanism for
+batteries.
+
+External power supply (AC) lists supplicants (batteries) names in
+"supplied_to" struct member, and each power_supply_changed() call
+issued by external power supply will notify supplicants via
+external_power_changed callback.
+
+
+Devicetree battery characteristics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Drivers should call power_supply_get_battery_info() to obtain battery
+characteristics from a devicetree battery node, defined in
+Documentation/devicetree/bindings/power/supply/battery.txt. This is
+implemented in drivers/power/supply/bq27xxx_battery.c.
+
+Properties in struct power_supply_battery_info and their counterparts in the
+battery node have names corresponding to elements in enum power_supply_property,
+for naming consistency between sysfs attributes and battery node properties.
+
+
+QA
+~~
+
+Q:
+ Where is POWER_SUPPLY_PROP_XYZ attribute?
+A:
+ If you cannot find attribute suitable for your driver needs, feel free
+ to add it and send patch along with your driver.
+
+ The attributes available currently are the ones currently provided by the
+ drivers written.
+
+ Good candidates to add in future: model/part#, cycle_time, manufacturer,
+ etc.
+
+
+Q:
+ I have some very specific attribute (e.g. battery color), should I add
+ this attribute to standard ones?
+A:
+ Most likely, no. Such attribute can be placed in the driver itself, if
+ it is useful. Of course, if the attribute in question applicable to
+ large set of batteries, provided by many drivers, and/or comes from
+ some general battery specification/standard, it may be a candidate to
+ be added to the core attribute set.
+
+
+Q:
+ Suppose, my battery monitoring chip/firmware does not provides capacity
+ in percents, but provides charge_{now,full,empty}. Should I calculate
+ percentage capacity manually, inside the driver, and register CAPACITY
+ attribute? The same question about time_to_empty/time_to_full.
+A:
+ Most likely, no. This class is designed to export properties which are
+ directly measurable by the specific hardware available.
+
+ Inferring not available properties using some heuristics or mathematical
+ model is not subject of work for a battery driver. Such functionality
+ should be factored out, and in fact, apm_power, the driver to serve
+ legacy APM API on top of power supply class, uses a simple heuristic of
+ approximating remaining battery capacity based on its charge, current,
+ voltage and so on. But full-fledged battery model is likely not subject
+ for kernel at all, as it would require floating point calculation to deal
+ with things like differential equations and Kalman filters. This is
+ better be handled by batteryd/libbattery, yet to be written.
diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt
deleted file mode 100644
index 300d37896e51..000000000000
--- a/Documentation/power/power_supply_class.txt
+++ /dev/null
@@ -1,231 +0,0 @@
-Linux power supply class
-========================
-
-Synopsis
-~~~~~~~~
-Power supply class used to represent battery, UPS, AC or DC power supply
-properties to user-space.
-
-It defines core set of attributes, which should be applicable to (almost)
-every power supply out there. Attributes are available via sysfs and uevent
-interfaces.
-
-Each attribute has well defined meaning, up to unit of measure used. While
-the attributes provided are believed to be universally applicable to any
-power supply, specific monitoring hardware may not be able to provide them
-all, so any of them may be skipped.
-
-Power supply class is extensible, and allows to define drivers own attributes.
-The core attribute set is subject to the standard Linux evolution (i.e.
-if it will be found that some attribute is applicable to many power supply
-types or their drivers, it can be added to the core set).
-
-It also integrates with LED framework, for the purpose of providing
-typically expected feedback of battery charging/fully charged status and
-AC/USB power supply online status. (Note that specific details of the
-indication (including whether to use it at all) are fully controllable by
-user and/or specific machine defaults, per design principles of LED
-framework).
-
-
-Attributes/properties
-~~~~~~~~~~~~~~~~~~~~~
-Power supply class has predefined set of attributes, this eliminates code
-duplication across drivers. Power supply class insist on reusing its
-predefined attributes *and* their units.
-
-So, userspace gets predictable set of attributes and their units for any
-kind of power supply, and can process/present them to a user in consistent
-manner. Results for different power supplies and machines are also directly
-comparable.
-
-See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
-for the example how to declare and handle attributes.
-
-
-Units
-~~~~~
-Quoting include/linux/power_supply.h:
-
- All voltages, currents, charges, energies, time and temperatures in µV,
- µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
- stated. It's driver's job to convert its raw values to units in which
- this class operates.
-
-
-Attributes/properties detailed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-~ ~ ~ ~ ~ ~ ~ Charge/Energy/Capacity - how to not confuse ~ ~ ~ ~ ~ ~ ~
-~ ~
-~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity" ~
-~ of battery, this class distinguish these terms. Don't mix them! ~
-~ ~
-~ CHARGE_* attributes represents capacity in µAh only. ~
-~ ENERGY_* attributes represents capacity in µWh only. ~
-~ CAPACITY attribute represents capacity in *percents*, from 0 to 100. ~
-~ ~
-~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
-
-Postfixes:
-_AVG - *hardware* averaged value, use it if your hardware is really able to
-report averaged values.
-_NOW - momentary/instantaneous values.
-
-STATUS - this attribute represents operating status (charging, full,
-discharging (i.e. powering a load), etc.). This corresponds to
-BATTERY_STATUS_* values, as defined in battery.h.
-
-CHARGE_TYPE - batteries can typically charge at different rates.
-This defines trickle and fast charges. For batteries that
-are already charged or discharging, 'n/a' can be displayed (or
-'unknown', if the status is not known).
-
-AUTHENTIC - indicates the power supply (battery or charger) connected
-to the platform is authentic(1) or non authentic(0).
-
-HEALTH - represents health of the battery, values corresponds to
-POWER_SUPPLY_HEALTH_*, defined in battery.h.
-
-VOLTAGE_OCV - open circuit voltage of the battery.
-
-VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
-minimal power supply voltages. Maximal/minimal means values of voltages
-when battery considered "full"/"empty" at normal conditions. Yes, there is
-no direct relation between voltage and battery capacity, but some dumb
-batteries use voltage for very approximated calculation of capacity.
-Battery driver also can use this attribute just to inform userspace
-about maximal and minimal voltage thresholds of a given battery.
-
-VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
-these ones should be used if hardware could only guess (measure and
-retain) the thresholds of a given power supply.
-
-VOLTAGE_BOOT - Reports the voltage measured during boot
-
-CURRENT_BOOT - Reports the current measured during boot
-
-CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
-battery considered full/empty.
-
-ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
-
-CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
-of charge when battery became full/empty". It also could mean "value of
-charge when battery considered full/empty at given conditions (temperature,
-age)". I.e. these attributes represents real thresholds, not design values.
-
-ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
-
-CHARGE_COUNTER - the current charge counter (in µAh). This could easily
-be negative; there is no empty or full value. It is only useful for
-relative, time-based measurements.
-
-PRECHARGE_CURRENT - the maximum charge current during precharge phase
-of charge cycle (typically 20% of battery capacity).
-CHARGE_TERM_CURRENT - Charge termination current. The charge cycle
-terminates when battery voltage is above recharge threshold, and charge
-current is below this setting (typically 10% of battery capacity).
-
-CONSTANT_CHARGE_CURRENT - constant charge current programmed by charger.
-CONSTANT_CHARGE_CURRENT_MAX - maximum charge current supported by the
-power supply object.
-
-CONSTANT_CHARGE_VOLTAGE - constant charge voltage programmed by charger.
-CONSTANT_CHARGE_VOLTAGE_MAX - maximum charge voltage supported by the
-power supply object.
-
-INPUT_CURRENT_LIMIT - input current limit programmed by charger. Indicates
-the current drawn from a charging source.
-
-CHARGE_CONTROL_LIMIT - current charge control limit setting
-CHARGE_CONTROL_LIMIT_MAX - maximum charge control limit setting
-
-CALIBRATE - battery or coulomb counter calibration status
-
-CAPACITY - capacity in percents.
-CAPACITY_ALERT_MIN - minimum capacity alert value in percents.
-CAPACITY_ALERT_MAX - maximum capacity alert value in percents.
-CAPACITY_LEVEL - capacity level. This corresponds to
-POWER_SUPPLY_CAPACITY_LEVEL_*.
-
-TEMP - temperature of the power supply.
-TEMP_ALERT_MIN - minimum battery temperature alert.
-TEMP_ALERT_MAX - maximum battery temperature alert.
-TEMP_AMBIENT - ambient temperature.
-TEMP_AMBIENT_ALERT_MIN - minimum ambient temperature alert.
-TEMP_AMBIENT_ALERT_MAX - maximum ambient temperature alert.
-TEMP_MIN - minimum operatable temperature
-TEMP_MAX - maximum operatable temperature
-
-TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
-while battery powers a load)
-TIME_TO_FULL - seconds left for battery to be considered full (i.e.
-while battery is charging)
-
-
-Battery <-> external power supply interaction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Often power supplies are acting as supplies and supplicants at the same
-time. Batteries are good example. So, batteries usually care if they're
-externally powered or not.
-
-For that case, power supply class implements notification mechanism for
-batteries.
-
-External power supply (AC) lists supplicants (batteries) names in
-"supplied_to" struct member, and each power_supply_changed() call
-issued by external power supply will notify supplicants via
-external_power_changed callback.
-
-
-Devicetree battery characteristics
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Drivers should call power_supply_get_battery_info() to obtain battery
-characteristics from a devicetree battery node, defined in
-Documentation/devicetree/bindings/power/supply/battery.txt. This is
-implemented in drivers/power/supply/bq27xxx_battery.c.
-
-Properties in struct power_supply_battery_info and their counterparts in the
-battery node have names corresponding to elements in enum power_supply_property,
-for naming consistency between sysfs attributes and battery node properties.
-
-
-QA
-~~
-Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
-A: If you cannot find attribute suitable for your driver needs, feel free
- to add it and send patch along with your driver.
-
- The attributes available currently are the ones currently provided by the
- drivers written.
-
- Good candidates to add in future: model/part#, cycle_time, manufacturer,
- etc.
-
-
-Q: I have some very specific attribute (e.g. battery color), should I add
- this attribute to standard ones?
-A: Most likely, no. Such attribute can be placed in the driver itself, if
- it is useful. Of course, if the attribute in question applicable to
- large set of batteries, provided by many drivers, and/or comes from
- some general battery specification/standard, it may be a candidate to
- be added to the core attribute set.
-
-
-Q: Suppose, my battery monitoring chip/firmware does not provides capacity
- in percents, but provides charge_{now,full,empty}. Should I calculate
- percentage capacity manually, inside the driver, and register CAPACITY
- attribute? The same question about time_to_empty/time_to_full.
-A: Most likely, no. This class is designed to export properties which are
- directly measurable by the specific hardware available.
-
- Inferring not available properties using some heuristics or mathematical
- model is not subject of work for a battery driver. Such functionality
- should be factored out, and in fact, apm_power, the driver to serve
- legacy APM API on top of power supply class, uses a simple heuristic of
- approximating remaining battery capacity based on its charge, current,
- voltage and so on. But full-fledged battery model is likely not subject
- for kernel at all, as it would require floating point calculation to deal
- with things like differential equations and Kalman filters. This is
- better be handled by batteryd/libbattery, yet to be written.
diff --git a/Documentation/power/powercap/powercap.rst b/Documentation/power/powercap/powercap.rst
new file mode 100644
index 000000000000..7ae3b44c7624
--- /dev/null
+++ b/Documentation/power/powercap/powercap.rst
@@ -0,0 +1,257 @@
+=======================
+Power Capping Framework
+=======================
+
+The power capping framework provides a consistent interface between the kernel
+and the user space that allows power capping drivers to expose the settings to
+user space in a uniform way.
+
+Terminology
+===========
+
+The framework exposes power capping devices to user space via sysfs in the
+form of a tree of objects. The objects at the root level of the tree represent
+'control types', which correspond to different methods of power capping. For
+example, the intel-rapl control type represents the Intel "Running Average
+Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
+corresponds to the use of idle injection for controlling power.
+
+Power zones represent different parts of the system, which can be controlled and
+monitored using the power capping method determined by the control type the
+given zone belongs to. They each contain attributes for monitoring power, as
+well as controls represented in the form of power constraints. If the parts of
+the system represented by different power zones are hierarchical (that is, one
+bigger part consists of multiple smaller parts that each have their own power
+controls), those power zones may also be organized in a hierarchy with one
+parent power zone containing multiple subzones and so on to reflect the power
+control topology of the system. In that case, it is possible to apply power
+capping to a set of devices together using the parent power zone and if more
+fine grained control is required, it can be applied through the subzones.
+
+
+Example sysfs interface tree::
+
+ /sys/devices/virtual/powercap
+ └──intel-rapl
+ ├──intel-rapl:0
+ │ ├──constraint_0_name
+ │ ├──constraint_0_power_limit_uw
+ │ ├──constraint_0_time_window_us
+ │ ├──constraint_1_name
+ │ ├──constraint_1_power_limit_uw
+ │ ├──constraint_1_time_window_us
+ │ ├──device -> ../../intel-rapl
+ │ ├──energy_uj
+ │ ├──intel-rapl:0:0
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:0
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──intel-rapl:0:1
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:0
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──max_energy_range_uj
+ │ ├──max_power_range_uw
+ │ ├──name
+ │ ├──enabled
+ │ ├──power
+ │ │ ├──async
+ │ │ []
+ │ ├──subsystem -> ../../../../../class/power_cap
+ │ ├──enabled
+ │ ├──uevent
+ ├──intel-rapl:1
+ │ ├──constraint_0_name
+ │ ├──constraint_0_power_limit_uw
+ │ ├──constraint_0_time_window_us
+ │ ├──constraint_1_name
+ │ ├──constraint_1_power_limit_uw
+ │ ├──constraint_1_time_window_us
+ │ ├──device -> ../../intel-rapl
+ │ ├──energy_uj
+ │ ├──intel-rapl:1:0
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:1
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──intel-rapl:1:1
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:1
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──max_energy_range_uj
+ │ ├──max_power_range_uw
+ │ ├──name
+ │ ├──enabled
+ │ ├──power
+ │ │ ├──async
+ │ │ []
+ │ ├──subsystem -> ../../../../../class/power_cap
+ │ ├──uevent
+ ├──power
+ │ ├──async
+ │ []
+ ├──subsystem -> ../../../../class/power_cap
+ ├──enabled
+ └──uevent
+
+The above example illustrates a case in which the Intel RAPL technology,
+available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
+control type called intel-rapl which contains two power zones, intel-rapl:0 and
+intel-rapl:1, representing CPU packages. Each of these power zones contains
+two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
+"core" and the "uncore" parts of the given CPU package, respectively. All of
+the zones and subzones contain energy monitoring attributes (energy_uj,
+max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
+to be applied (the constraints in the 'package' power zones apply to the whole
+CPU packages and the subzone constraints only apply to the respective parts of
+the given package individually). Since Intel RAPL doesn't provide instantaneous
+power value, there is no power_uw attribute.
+
+In addition to that, each power zone contains a name attribute, allowing the
+part of the system represented by that zone to be identified.
+For example::
+
+ cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
+
+package-0
+---------
+
+The Intel RAPL technology allows two constraints, short term and long term,
+with two different time windows to be applied to each power zone. Thus for
+each zone there are 2 attributes representing the constraint names, 2 power
+limits and 2 attributes representing the sizes of the time windows. Such that,
+constraint_j_* attributes correspond to the jth constraint (j = 0,1).
+
+For example::
+
+ constraint_0_name
+ constraint_0_power_limit_uw
+ constraint_0_time_window_us
+ constraint_1_name
+ constraint_1_power_limit_uw
+ constraint_1_time_window_us
+
+Power Zone Attributes
+=====================
+
+Monitoring attributes
+---------------------
+
+energy_uj (rw)
+ Current energy counter in micro joules. Write "0" to reset.
+ If the counter can not be reset, then this attribute is read only.
+
+max_energy_range_uj (ro)
+ Range of the above energy counter in micro-joules.
+
+power_uw (ro)
+ Current power in micro watts.
+
+max_power_range_uw (ro)
+ Range of the above power value in micro-watts.
+
+name (ro)
+ Name of this power zone.
+
+It is possible that some domains have both power ranges and energy counter ranges;
+however, only one is mandatory.
+
+Constraints
+-----------
+
+constraint_X_power_limit_uw (rw)
+ Power limit in micro watts, which should be applicable for the
+ time window specified by "constraint_X_time_window_us".
+
+constraint_X_time_window_us (rw)
+ Time window in micro seconds.
+
+constraint_X_name (ro)
+ An optional name of the constraint
+
+constraint_X_max_power_uw(ro)
+ Maximum allowed power in micro watts.
+
+constraint_X_min_power_uw(ro)
+ Minimum allowed power in micro watts.
+
+constraint_X_max_time_window_us(ro)
+ Maximum allowed time window in micro seconds.
+
+constraint_X_min_time_window_us(ro)
+ Minimum allowed time window in micro seconds.
+
+Except power_limit_uw and time_window_us other fields are optional.
+
+Common zone and control type attributes
+---------------------------------------
+
+enabled (rw): Enable/Disable controls at zone level or for all zones using
+a control type.
+
+Power Cap Client Driver Interface
+=================================
+
+The API summary:
+
+Call powercap_register_control_type() to register control type object.
+Call powercap_register_zone() to register a power zone (under a given
+control type), either as a top-level power zone or as a subzone of another
+power zone registered earlier.
+The number of constraints in a power zone and the corresponding callbacks have
+to be defined prior to calling powercap_register_zone() to register that zone.
+
+To Free a power zone call powercap_unregister_zone().
+To free a control type object call powercap_unregister_control_type().
+Detailed API can be generated using kernel-doc on include/linux/powercap.h.
diff --git a/Documentation/power/powercap/powercap.txt b/Documentation/power/powercap/powercap.txt
deleted file mode 100644
index 1e6ef164e07a..000000000000
--- a/Documentation/power/powercap/powercap.txt
+++ /dev/null
@@ -1,236 +0,0 @@
-Power Capping Framework
-==================================
-
-The power capping framework provides a consistent interface between the kernel
-and the user space that allows power capping drivers to expose the settings to
-user space in a uniform way.
-
-Terminology
-=========================
-The framework exposes power capping devices to user space via sysfs in the
-form of a tree of objects. The objects at the root level of the tree represent
-'control types', which correspond to different methods of power capping. For
-example, the intel-rapl control type represents the Intel "Running Average
-Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
-corresponds to the use of idle injection for controlling power.
-
-Power zones represent different parts of the system, which can be controlled and
-monitored using the power capping method determined by the control type the
-given zone belongs to. They each contain attributes for monitoring power, as
-well as controls represented in the form of power constraints. If the parts of
-the system represented by different power zones are hierarchical (that is, one
-bigger part consists of multiple smaller parts that each have their own power
-controls), those power zones may also be organized in a hierarchy with one
-parent power zone containing multiple subzones and so on to reflect the power
-control topology of the system. In that case, it is possible to apply power
-capping to a set of devices together using the parent power zone and if more
-fine grained control is required, it can be applied through the subzones.
-
-
-Example sysfs interface tree:
-
-/sys/devices/virtual/powercap
-??? intel-rapl
- ??? intel-rapl:0
- ? ??? constraint_0_name
- ? ??? constraint_0_power_limit_uw
- ? ??? constraint_0_time_window_us
- ? ??? constraint_1_name
- ? ??? constraint_1_power_limit_uw
- ? ??? constraint_1_time_window_us
- ? ??? device -> ../../intel-rapl
- ? ??? energy_uj
- ? ??? intel-rapl:0:0
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:0
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? intel-rapl:0:1
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:0
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? max_energy_range_uj
- ? ??? max_power_range_uw
- ? ??? name
- ? ??? enabled
- ? ??? power
- ? ? ??? async
- ? ? []
- ? ??? subsystem -> ../../../../../class/power_cap
- ? ??? enabled
- ? ??? uevent
- ??? intel-rapl:1
- ? ??? constraint_0_name
- ? ??? constraint_0_power_limit_uw
- ? ??? constraint_0_time_window_us
- ? ??? constraint_1_name
- ? ??? constraint_1_power_limit_uw
- ? ??? constraint_1_time_window_us
- ? ??? device -> ../../intel-rapl
- ? ??? energy_uj
- ? ??? intel-rapl:1:0
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:1
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? intel-rapl:1:1
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:1
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? max_energy_range_uj
- ? ??? max_power_range_uw
- ? ??? name
- ? ??? enabled
- ? ??? power
- ? ? ??? async
- ? ? []
- ? ??? subsystem -> ../../../../../class/power_cap
- ? ??? uevent
- ??? power
- ? ??? async
- ? []
- ??? subsystem -> ../../../../class/power_cap
- ??? enabled
- ??? uevent
-
-The above example illustrates a case in which the Intel RAPL technology,
-available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
-control type called intel-rapl which contains two power zones, intel-rapl:0 and
-intel-rapl:1, representing CPU packages. Each of these power zones contains
-two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
-"core" and the "uncore" parts of the given CPU package, respectively. All of
-the zones and subzones contain energy monitoring attributes (energy_uj,
-max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
-to be applied (the constraints in the 'package' power zones apply to the whole
-CPU packages and the subzone constraints only apply to the respective parts of
-the given package individually). Since Intel RAPL doesn't provide instantaneous
-power value, there is no power_uw attribute.
-
-In addition to that, each power zone contains a name attribute, allowing the
-part of the system represented by that zone to be identified.
-For example:
-
-cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
-package-0
-
-The Intel RAPL technology allows two constraints, short term and long term,
-with two different time windows to be applied to each power zone. Thus for
-each zone there are 2 attributes representing the constraint names, 2 power
-limits and 2 attributes representing the sizes of the time windows. Such that,
-constraint_j_* attributes correspond to the jth constraint (j = 0,1).
-
-For example:
- constraint_0_name
- constraint_0_power_limit_uw
- constraint_0_time_window_us
- constraint_1_name
- constraint_1_power_limit_uw
- constraint_1_time_window_us
-
-Power Zone Attributes
-=================================
-Monitoring attributes
-----------------------
-
-energy_uj (rw): Current energy counter in micro joules. Write "0" to reset.
-If the counter can not be reset, then this attribute is read only.
-
-max_energy_range_uj (ro): Range of the above energy counter in micro-joules.
-
-power_uw (ro): Current power in micro watts.
-
-max_power_range_uw (ro): Range of the above power value in micro-watts.
-
-name (ro): Name of this power zone.
-
-It is possible that some domains have both power ranges and energy counter ranges;
-however, only one is mandatory.
-
-Constraints
-----------------
-constraint_X_power_limit_uw (rw): Power limit in micro watts, which should be
-applicable for the time window specified by "constraint_X_time_window_us".
-
-constraint_X_time_window_us (rw): Time window in micro seconds.
-
-constraint_X_name (ro): An optional name of the constraint
-
-constraint_X_max_power_uw(ro): Maximum allowed power in micro watts.
-
-constraint_X_min_power_uw(ro): Minimum allowed power in micro watts.
-
-constraint_X_max_time_window_us(ro): Maximum allowed time window in micro seconds.
-
-constraint_X_min_time_window_us(ro): Minimum allowed time window in micro seconds.
-
-Except power_limit_uw and time_window_us other fields are optional.
-
-Common zone and control type attributes
-----------------------------------------
-enabled (rw): Enable/Disable controls at zone level or for all zones using
-a control type.
-
-Power Cap Client Driver Interface
-==================================
-The API summary:
-
-Call powercap_register_control_type() to register control type object.
-Call powercap_register_zone() to register a power zone (under a given
-control type), either as a top-level power zone or as a subzone of another
-power zone registered earlier.
-The number of constraints in a power zone and the corresponding callbacks have
-to be defined prior to calling powercap_register_zone() to register that zone.
-
-To Free a power zone call powercap_unregister_zone().
-To free a control type object call powercap_unregister_control_type().
-Detailed API can be generated using kernel-doc on include/linux/powercap.h.
diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.rst
similarity index 61%
rename from Documentation/power/regulator/consumer.txt
rename to Documentation/power/regulator/consumer.rst
index e51564c1a140..0cd8cc1275a7 100644
--- a/Documentation/power/regulator/consumer.txt
+++ b/Documentation/power/regulator/consumer.rst
@@ -1,3 +1,4 @@
+===================================
Regulator Consumer Driver Interface
===================================
@@ -8,73 +9,77 @@ Please see overview.txt for a description of the terms used in this text.
1. Consumer Regulator Access (static & dynamic drivers)
=======================================================
-A consumer driver can get access to its supply regulator by calling :-
+A consumer driver can get access to its supply regulator by calling ::
-regulator = regulator_get(dev, "Vcc");
+ regulator = regulator_get(dev, "Vcc");
The consumer passes in its struct device pointer and power supply ID. The core
then finds the correct regulator by consulting a machine specific lookup table.
If the lookup is successful then this call will return a pointer to the struct
regulator that supplies this consumer.
-To release the regulator the consumer driver should call :-
+To release the regulator the consumer driver should call ::
-regulator_put(regulator);
+ regulator_put(regulator);
Consumers can be supplied by more than one regulator e.g. codec consumer with
-analog and digital supplies :-
+analog and digital supplies ::
-digital = regulator_get(dev, "Vcc"); /* digital core */
-analog = regulator_get(dev, "Avdd"); /* analog */
+ digital = regulator_get(dev, "Vcc"); /* digital core */
+ analog = regulator_get(dev, "Avdd"); /* analog */
The regulator access functions regulator_get() and regulator_put() will
usually be called in your device drivers probe() and remove() respectively.
2. Regulator Output Enable & Disable (static & dynamic drivers)
-====================================================================
+===============================================================
-A consumer can enable its power supply by calling:-
-int regulator_enable(regulator);
+A consumer can enable its power supply by calling::
-NOTE: The supply may already be enabled before regulator_enabled() is called.
-This may happen if the consumer shares the regulator or the regulator has been
-previously enabled by bootloader or kernel board initialization code.
+ int regulator_enable(regulator);
-A consumer can determine if a regulator is enabled by calling :-
+NOTE:
+ The supply may already be enabled before regulator_enabled() is called.
+ This may happen if the consumer shares the regulator or the regulator has been
+ previously enabled by bootloader or kernel board initialization code.
-int regulator_is_enabled(regulator);
+A consumer can determine if a regulator is enabled by calling::
+
+ int regulator_is_enabled(regulator);
This will return > zero when the regulator is enabled.
-A consumer can disable its supply when no longer needed by calling :-
+A consumer can disable its supply when no longer needed by calling::
-int regulator_disable(regulator);
+ int regulator_disable(regulator);
-NOTE: This may not disable the supply if it's shared with other consumers. The
-regulator will only be disabled when the enabled reference count is zero.
+NOTE:
+ This may not disable the supply if it's shared with other consumers. The
+ regulator will only be disabled when the enabled reference count is zero.
-Finally, a regulator can be forcefully disabled in the case of an emergency :-
+Finally, a regulator can be forcefully disabled in the case of an emergency::
-int regulator_force_disable(regulator);
+ int regulator_force_disable(regulator);
-NOTE: this will immediately and forcefully shutdown the regulator output. All
-consumers will be powered off.
+NOTE:
+ this will immediately and forcefully shutdown the regulator output. All
+ consumers will be powered off.
3. Regulator Voltage Control & Status (dynamic drivers)
-======================================================
+=======================================================
Some consumer drivers need to be able to dynamically change their supply
voltage to match system operating points. e.g. CPUfreq drivers can scale
voltage along with frequency to save power, SD drivers may need to select the
correct card voltage, etc.
-Consumers can control their supply voltage by calling :-
+Consumers can control their supply voltage by calling::
-int regulator_set_voltage(regulator, min_uV, max_uV);
+ int regulator_set_voltage(regulator, min_uV, max_uV);
Where min_uV and max_uV are the minimum and maximum acceptable voltages in
microvolts.
@@ -84,47 +89,50 @@ when enabled, then the voltage changes instantly, otherwise the voltage
configuration changes and the voltage is physically set when the regulator is
next enabled.
-The regulators configured voltage output can be found by calling :-
+The regulators configured voltage output can be found by calling::
-int regulator_get_voltage(regulator);
+ int regulator_get_voltage(regulator);
-NOTE: get_voltage() will return the configured output voltage whether the
-regulator is enabled or disabled and should NOT be used to determine regulator
-output state. However this can be used in conjunction with is_enabled() to
-determine the regulator physical output voltage.
+NOTE:
+ get_voltage() will return the configured output voltage whether the
+ regulator is enabled or disabled and should NOT be used to determine regulator
+ output state. However this can be used in conjunction with is_enabled() to
+ determine the regulator physical output voltage.
4. Regulator Current Limit Control & Status (dynamic drivers)
-===========================================================
+=============================================================
Some consumer drivers need to be able to dynamically change their supply
current limit to match system operating points. e.g. LCD backlight driver can
change the current limit to vary the backlight brightness, USB drivers may want
to set the limit to 500mA when supplying power.
-Consumers can control their supply current limit by calling :-
+Consumers can control their supply current limit by calling::
-int regulator_set_current_limit(regulator, min_uA, max_uA);
+ int regulator_set_current_limit(regulator, min_uA, max_uA);
Where min_uA and max_uA are the minimum and maximum acceptable current limit in
microamps.
-NOTE: this can be called when the regulator is enabled or disabled. If called
-when enabled, then the current limit changes instantly, otherwise the current
-limit configuration changes and the current limit is physically set when the
-regulator is next enabled.
+NOTE:
+ this can be called when the regulator is enabled or disabled. If called
+ when enabled, then the current limit changes instantly, otherwise the current
+ limit configuration changes and the current limit is physically set when the
+ regulator is next enabled.
-A regulators current limit can be found by calling :-
+A regulators current limit can be found by calling::
-int regulator_get_current_limit(regulator);
+ int regulator_get_current_limit(regulator);
-NOTE: get_current_limit() will return the current limit whether the regulator
-is enabled or disabled and should not be used to determine regulator current
-load.
+NOTE:
+ get_current_limit() will return the current limit whether the regulator
+ is enabled or disabled and should not be used to determine regulator current
+ load.
5. Regulator Operating Mode Control & Status (dynamic drivers)
-=============================================================
+==============================================================
Some consumers can further save system power by changing the operating mode of
their supply regulator to be more efficient when the consumers operating state
@@ -135,9 +143,9 @@ Regulator operating mode can be changed indirectly or directly.
Indirect operating mode control.
--------------------------------
Consumer drivers can request a change in their supply regulator operating mode
-by calling :-
+by calling::
-int regulator_set_load(struct regulator *regulator, int load_uA);
+ int regulator_set_load(struct regulator *regulator, int load_uA);
This will cause the core to recalculate the total load on the regulator (based
on all its consumers) and change operating mode (if necessary and permitted)
@@ -153,12 +161,13 @@ consumers.
Direct operating mode control.
------------------------------
+
Bespoke or tightly coupled drivers may want to directly control regulator
operating mode depending on their operating point. This can be achieved by
-calling :-
+calling::
-int regulator_set_mode(struct regulator *regulator, unsigned int mode);
-unsigned int regulator_get_mode(struct regulator *regulator);
+ int regulator_set_mode(struct regulator *regulator, unsigned int mode);
+ unsigned int regulator_get_mode(struct regulator *regulator);
Direct mode will only be used by consumers that *know* about the regulator and
are not sharing the regulator with other consumers.
@@ -166,24 +175,26 @@ are not sharing the regulator with other consumers.
6. Regulator Events
===================
+
Regulators can notify consumers of external events. Events could be received by
consumers under regulator stress or failure conditions.
-Consumers can register interest in regulator events by calling :-
+Consumers can register interest in regulator events by calling::
-int regulator_register_notifier(struct regulator *regulator,
- struct notifier_block *nb);
+ int regulator_register_notifier(struct regulator *regulator,
+ struct notifier_block *nb);
-Consumers can unregister interest by calling :-
+Consumers can unregister interest by calling::
-int regulator_unregister_notifier(struct regulator *regulator,
- struct notifier_block *nb);
+ int regulator_unregister_notifier(struct regulator *regulator,
+ struct notifier_block *nb);
Regulators use the kernel notifier framework to send event to their interested
consumers.
7. Regulator Direct Register Access
===================================
+
Some kinds of power management hardware or firmware are designed such that
they need to do low-level hardware access to regulators, with no involvement
from the kernel. Examples of such devices are:
@@ -199,20 +210,20 @@ to it. The regulator framework provides the following helpers for querying
these details.
Bus-specific details, like I2C addresses or transfer rates are handled by the
-regmap framework. To get the regulator's regmap (if supported), use :-
+regmap framework. To get the regulator's regmap (if supported), use::
-struct regmap *regulator_get_regmap(struct regulator *regulator);
+ struct regmap *regulator_get_regmap(struct regulator *regulator);
To obtain the hardware register offset and bitmask for the regulator's voltage
-selector register, use :-
+selector register, use::
-int regulator_get_hardware_vsel_register(struct regulator *regulator,
- unsigned *vsel_reg,
- unsigned *vsel_mask);
+ int regulator_get_hardware_vsel_register(struct regulator *regulator,
+ unsigned *vsel_reg,
+ unsigned *vsel_mask);
To convert a regulator framework voltage selector code (used by
regulator_list_voltage) to a hardware-specific voltage selector that can be
-directly written to the voltage selector register, use :-
+directly written to the voltage selector register, use::
-int regulator_list_hardware_vsel(struct regulator *regulator,
- unsigned selector);
+ int regulator_list_hardware_vsel(struct regulator *regulator,
+ unsigned selector);
diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.rst
similarity index 86%
rename from Documentation/power/regulator/design.txt
rename to Documentation/power/regulator/design.rst
index fdd919b96830..3b09c6841dc4 100644
--- a/Documentation/power/regulator/design.txt
+++ b/Documentation/power/regulator/design.rst
@@ -1,3 +1,4 @@
+==========================
Regulator API design notes
==========================
@@ -14,7 +15,9 @@ Safety
have different power requirements, and not all components with power
requirements are visible to software.
- => The API should make no changes to the hardware state unless it has
+.. note::
+
+ The API should make no changes to the hardware state unless it has
specific knowledge that these changes are safe to perform on this
particular system.
@@ -28,6 +31,8 @@ Consumer use cases
- Many of the power supplies in the system will be shared between many
different consumers.
- => The consumer API should be structured so that these use cases are
+.. note::
+
+ The consumer API should be structured so that these use cases are
very easy to handle and so that consumers will work with shared
supplies without any additional effort.
diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.rst
similarity index 75%
rename from Documentation/power/regulator/machine.txt
rename to Documentation/power/regulator/machine.rst
index eff4dcaaa252..22fffefaa3ad 100644
--- a/Documentation/power/regulator/machine.txt
+++ b/Documentation/power/regulator/machine.rst
@@ -1,10 +1,11 @@
+==================================
Regulator Machine Driver Interface
-===================================
+==================================
The regulator machine driver interface is intended for board/machine specific
initialisation code to configure the regulator subsystem.
-Consider the following machine :-
+Consider the following machine::
Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
|
@@ -13,31 +14,31 @@ Consider the following machine :-
The drivers for consumers A & B must be mapped to the correct regulator in
order to control their power supplies. This mapping can be achieved in machine
initialisation code by creating a struct regulator_consumer_supply for
-each regulator.
+each regulator::
-struct regulator_consumer_supply {
+ struct regulator_consumer_supply {
const char *dev_name; /* consumer dev_name() */
const char *supply; /* consumer supply - e.g. "vcc" */
-};
+ };
-e.g. for the machine above
+e.g. for the machine above::
-static struct regulator_consumer_supply regulator1_consumers[] = {
+ static struct regulator_consumer_supply regulator1_consumers[] = {
REGULATOR_SUPPLY("Vcc", "consumer B"),
-};
+ };
-static struct regulator_consumer_supply regulator2_consumers[] = {
+ static struct regulator_consumer_supply regulator2_consumers[] = {
REGULATOR_SUPPLY("Vcc", "consumer A"),
-};
+ };
This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
to the 'Vcc' supply for Consumer A.
Constraints can now be registered by defining a struct regulator_init_data
for each regulator power domain. This structure also maps the consumers
-to their supply regulators :-
+to their supply regulators::
-static struct regulator_init_data regulator1_data = {
+ static struct regulator_init_data regulator1_data = {
.constraints = {
.name = "Regulator-1",
.min_uV = 3300000,
@@ -46,7 +47,7 @@ static struct regulator_init_data regulator1_data = {
},
.num_consumer_supplies = ARRAY_SIZE(regulator1_consumers),
.consumer_supplies = regulator1_consumers,
-};
+ };
The name field should be set to something that is usefully descriptive
for the board for configuration of supplies for other regulators and
@@ -57,9 +58,9 @@ name is provided then the subsystem will choose one.
Regulator-1 supplies power to Regulator-2. This relationship must be registered
with the core so that Regulator-1 is also enabled when Consumer A enables its
supply (Regulator-2). The supply regulator is set by the supply_regulator
-field below and co:-
+field below and co::
-static struct regulator_init_data regulator2_data = {
+ static struct regulator_init_data regulator2_data = {
.supply_regulator = "Regulator-1",
.constraints = {
.min_uV = 1800000,
@@ -69,11 +70,11 @@ static struct regulator_init_data regulator2_data = {
},
.num_consumer_supplies = ARRAY_SIZE(regulator2_consumers),
.consumer_supplies = regulator2_consumers,
-};
+ };
-Finally the regulator devices must be registered in the usual manner.
+Finally the regulator devices must be registered in the usual manner::
-static struct platform_device regulator_devices[] = {
+ static struct platform_device regulator_devices[] = {
{
.name = "regulator",
.id = DCDC_1,
@@ -88,9 +89,9 @@ static struct platform_device regulator_devices[] = {
.platform_data = ®ulator2_data,
},
},
-};
-/* register regulator 1 device */
-platform_device_register(®ulator_devices[0]);
+ };
+ /* register regulator 1 device */
+ platform_device_register(®ulator_devices[0]);
-/* register regulator 2 device */
-platform_device_register(®ulator_devices[1]);
+ /* register regulator 2 device */
+ platform_device_register(®ulator_devices[1]);
diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.rst
similarity index 79%
rename from Documentation/power/regulator/overview.txt
rename to Documentation/power/regulator/overview.rst
index 721b4739ec32..ee494c70a7c4 100644
--- a/Documentation/power/regulator/overview.txt
+++ b/Documentation/power/regulator/overview.rst
@@ -1,3 +1,4 @@
+=============================================
Linux voltage and current regulator framework
=============================================
@@ -13,26 +14,30 @@ regulators (where voltage output is controllable) and current sinks (where
current limit is controllable).
(C) 2008 Wolfson Microelectronics PLC.
+
Author: Liam Girdwood <lrg@slimlogic.co.uk>
Nomenclature
============
-Some terms used in this document:-
+Some terms used in this document:
- o Regulator - Electronic device that supplies power to other devices.
+ - Regulator
+ - Electronic device that supplies power to other devices.
Most regulators can enable and disable their output while
some can control their output voltage and or current.
Input Voltage -> Regulator -> Output Voltage
- o PMIC - Power Management IC. An IC that contains numerous regulators
- and often contains other subsystems.
+ - PMIC
+ - Power Management IC. An IC that contains numerous
+ regulators and often contains other subsystems.
- o Consumer - Electronic device that is supplied power by a regulator.
+ - Consumer
+ - Electronic device that is supplied power by a regulator.
Consumers can be classified into two types:-
Static: consumer does not change its supply voltage or
@@ -44,46 +49,48 @@ Some terms used in this document:-
current limit to meet operation demands.
- o Power Domain - Electronic circuit that is supplied its input power by the
+ - Power Domain
+ - Electronic circuit that is supplied its input power by the
output power of a regulator, switch or by another power
domain.
- The supply regulator may be behind a switch(s). i.e.
+ The supply regulator may be behind a switch(s). i.e.::
- Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
- | |
- | +-> [Consumer B], [Consumer C]
- |
- +-> [Consumer D], [Consumer E]
+ Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
+ | |
+ | +-> [Consumer B], [Consumer C]
+ |
+ +-> [Consumer D], [Consumer E]
That is one regulator and three power domains:
- Domain 1: Switch-1, Consumers D & E.
- Domain 2: Switch-2, Consumers B & C.
- Domain 3: Consumer A.
+ - Domain 1: Switch-1, Consumers D & E.
+ - Domain 2: Switch-2, Consumers B & C.
+ - Domain 3: Consumer A.
and this represents a "supplies" relationship:
Domain-1 --> Domain-2 --> Domain-3.
A power domain may have regulators that are supplied power
- by other regulators. i.e.
+ by other regulators. i.e.::
- Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
- |
- +-> [Consumer B]
+ Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
+ |
+ +-> [Consumer B]
This gives us two regulators and two power domains:
- Domain 1: Regulator-2, Consumer B.
- Domain 2: Consumer A.
+ - Domain 1: Regulator-2, Consumer B.
+ - Domain 2: Consumer A.
and a "supplies" relationship:
Domain-1 --> Domain-2
- o Constraints - Constraints are used to define power levels for performance
+ - Constraints
+ - Constraints are used to define power levels for performance
and hardware protection. Constraints exist at three levels:
Regulator Level: This is defined by the regulator hardware
@@ -141,7 +148,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
limit. This also compiles out if not in use so drivers can be reused in
systems with no regulator based power control.
- See Documentation/power/regulator/consumer.txt
+ See Documentation/power/regulator/consumer.rst
2. Regulator driver interface.
@@ -149,7 +156,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
operations to the core. It also has a notifier call chain for propagating
regulator events to clients.
- See Documentation/power/regulator/regulator.txt
+ See Documentation/power/regulator/regulator.rst
3. Machine interface.
@@ -160,7 +167,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
allows the creation of a regulator tree whereby some regulators are
supplied by others (similar to a clock tree).
- See Documentation/power/regulator/machine.txt
+ See Documentation/power/regulator/machine.rst
4. Userspace ABI.
diff --git a/Documentation/power/regulator/regulator.rst b/Documentation/power/regulator/regulator.rst
new file mode 100644
index 000000000000..794b3256fbb9
--- /dev/null
+++ b/Documentation/power/regulator/regulator.rst
@@ -0,0 +1,32 @@
+==========================
+Regulator Driver Interface
+==========================
+
+The regulator driver interface is relatively simple and designed to allow
+regulator drivers to register their services with the core framework.
+
+
+Registration
+============
+
+Drivers can register a regulator by calling::
+
+ struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
+ const struct regulator_config *config);
+
+This will register the regulator's capabilities and operations to the regulator
+core.
+
+Regulators can be unregistered by calling::
+
+ void regulator_unregister(struct regulator_dev *rdev);
+
+
+Regulator Events
+================
+
+Regulators can send events (e.g. overtemperature, undervoltage, etc) to
+consumer drivers by calling::
+
+ int regulator_notifier_call_chain(struct regulator_dev *rdev,
+ unsigned long event, void *data);
diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt
deleted file mode 100644
index b17e5833ce21..000000000000
--- a/Documentation/power/regulator/regulator.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Regulator Driver Interface
-==========================
-
-The regulator driver interface is relatively simple and designed to allow
-regulator drivers to register their services with the core framework.
-
-
-Registration
-============
-
-Drivers can register a regulator by calling :-
-
-struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
- const struct regulator_config *config);
-
-This will register the regulator's capabilities and operations to the regulator
-core.
-
-Regulators can be unregistered by calling :-
-
-void regulator_unregister(struct regulator_dev *rdev);
-
-
-Regulator Events
-================
-Regulators can send events (e.g. overtemperature, undervoltage, etc) to
-consumer drivers by calling :-
-
-int regulator_notifier_call_chain(struct regulator_dev *rdev,
- unsigned long event, void *data);
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.rst
similarity index 89%
rename from Documentation/power/runtime_pm.txt
rename to Documentation/power/runtime_pm.rst
index 937e33c46211..2c2ec99b5088 100644
--- a/Documentation/power/runtime_pm.txt
+++ b/Documentation/power/runtime_pm.rst
@@ -1,10 +1,15 @@
+==================================================
Runtime Power Management Framework for I/O Devices
+==================================================
(C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
+
(C) 2010 Alan Stern <stern@rowland.harvard.edu>
+
(C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
1. Introduction
+===============
Support for runtime power management (runtime PM) of I/O devices is provided
at the power management core (PM core) level by means of:
@@ -33,16 +38,17 @@ fields of 'struct dev_pm_info' and the core helper functions provided for
runtime PM are described below.
2. Device Runtime PM Callbacks
+==============================
-There are three device runtime PM callbacks defined in 'struct dev_pm_ops':
+There are three device runtime PM callbacks defined in 'struct dev_pm_ops'::
-struct dev_pm_ops {
+ struct dev_pm_ops {
...
int (*runtime_suspend)(struct device *dev);
int (*runtime_resume)(struct device *dev);
int (*runtime_idle)(struct device *dev);
...
-};
+ };
The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks
are executed by the PM core for the device's subsystem that may be either of
@@ -112,7 +118,7 @@ low-power state during the execution of the suspend callback, it is expected
that remote wakeup will be enabled for the device. Generally, remote wakeup
should be enabled for all input devices put into low-power states at run time.
-The subsystem-level resume callback, if present, is _entirely_ _responsible_ for
+The subsystem-level resume callback, if present, is **entirely responsible** for
handling the resume of the device as appropriate, which may, but need not
include executing the device driver's own ->runtime_resume() callback (from the
PM core's point of view it is not necessary to implement a ->runtime_resume()
@@ -197,95 +203,96 @@ rules:
except for scheduled autosuspends.
3. Runtime PM Device Fields
+===========================
The following device runtime PM fields are present in 'struct dev_pm_info', as
defined in include/linux/pm.h:
- struct timer_list suspend_timer;
+ `struct timer_list suspend_timer;`
- timer used for scheduling (delayed) suspend and autosuspend requests
- unsigned long timer_expires;
+ `unsigned long timer_expires;`
- timer expiration time, in jiffies (if this is different from zero, the
timer is running and will expire at that time, otherwise the timer is not
running)
- struct work_struct work;
+ `struct work_struct work;`
- work structure used for queuing up requests (i.e. work items in pm_wq)
- wait_queue_head_t wait_queue;
+ `wait_queue_head_t wait_queue;`
- wait queue used if any of the helper functions needs to wait for another
one to complete
- spinlock_t lock;
+ `spinlock_t lock;`
- lock used for synchronization
- atomic_t usage_count;
+ `atomic_t usage_count;`
- the usage counter of the device
- atomic_t child_count;
+ `atomic_t child_count;`
- the count of 'active' children of the device
- unsigned int ignore_children;
+ `unsigned int ignore_children;`
- if set, the value of child_count is ignored (but still updated)
- unsigned int disable_depth;
+ `unsigned int disable_depth;`
- used for disabling the helper functions (they work normally if this is
equal to zero); the initial value of it is 1 (i.e. runtime PM is
initially disabled for all devices)
- int runtime_error;
+ `int runtime_error;`
- if set, there was a fatal error (one of the callbacks returned error code
as described in Section 2), so the helper functions will not work until
this flag is cleared; this is the error code returned by the failing
callback
- unsigned int idle_notification;
+ `unsigned int idle_notification;`
- if set, ->runtime_idle() is being executed
- unsigned int request_pending;
+ `unsigned int request_pending;`
- if set, there's a pending request (i.e. a work item queued up into pm_wq)
- enum rpm_request request;
+ `enum rpm_request request;`
- type of request that's pending (valid if request_pending is set)
- unsigned int deferred_resume;
+ `unsigned int deferred_resume;`
- set if ->runtime_resume() is about to be run while ->runtime_suspend() is
being executed for that device and it is not practical to wait for the
suspend to complete; means "start a resume as soon as you've suspended"
- enum rpm_status runtime_status;
+ `enum rpm_status runtime_status;`
- the runtime PM status of the device; this field's initial value is
RPM_SUSPENDED, which means that each device is initially regarded by the
PM core as 'suspended', regardless of its real hardware status
- unsigned int runtime_auto;
+ `unsigned int runtime_auto;`
- if set, indicates that the user space has allowed the device driver to
power manage the device at run time via the /sys/devices/.../power/control
- interface; it may only be modified with the help of the pm_runtime_allow()
+ `interface;` it may only be modified with the help of the pm_runtime_allow()
and pm_runtime_forbid() helper functions
- unsigned int no_callbacks;
+ `unsigned int no_callbacks;`
- indicates that the device does not use the runtime PM callbacks (see
Section 8); it may be modified only by the pm_runtime_no_callbacks()
helper function
- unsigned int irq_safe;
+ `unsigned int irq_safe;`
- indicates that the ->runtime_suspend() and ->runtime_resume() callbacks
will be invoked with the spinlock held and interrupts disabled
- unsigned int use_autosuspend;
+ `unsigned int use_autosuspend;`
- indicates that the device's driver supports delayed autosuspend (see
Section 9); it may be modified only by the
pm_runtime{_dont}_use_autosuspend() helper functions
- unsigned int timer_autosuspends;
+ `unsigned int timer_autosuspends;`
- indicates that the PM core should attempt to carry out an autosuspend
when the timer expires rather than a normal suspend
- int autosuspend_delay;
+ `int autosuspend_delay;`
- the delay time (in milliseconds) to be used for autosuspend
- unsigned long last_busy;
+ `unsigned long last_busy;`
- the time (in jiffies) when the pm_runtime_mark_last_busy() helper
function was last called for this device; used in calculating inactivity
periods for autosuspend
@@ -293,37 +300,38 @@ defined in include/linux/pm.h:
All of the above fields are members of the 'power' member of 'struct device'.
4. Runtime PM Device Helper Functions
+=====================================
The following runtime PM helper functions are defined in
drivers/base/power/runtime.c and include/linux/pm_runtime.h:
- void pm_runtime_init(struct device *dev);
+ `void pm_runtime_init(struct device *dev);`
- initialize the device runtime PM fields in 'struct dev_pm_info'
- void pm_runtime_remove(struct device *dev);
+ `void pm_runtime_remove(struct device *dev);`
- make sure that the runtime PM of the device will be disabled after
removing the device from device hierarchy
- int pm_runtime_idle(struct device *dev);
+ `int pm_runtime_idle(struct device *dev);`
- execute the subsystem-level idle callback for the device; returns an
error code on failure, where -EINPROGRESS means that ->runtime_idle() is
already being executed; if there is no callback or the callback returns 0
then run pm_runtime_autosuspend(dev) and return its result
- int pm_runtime_suspend(struct device *dev);
+ `int pm_runtime_suspend(struct device *dev);`
- execute the subsystem-level suspend callback for the device; returns 0 on
success, 1 if the device's runtime PM status was already 'suspended', or
error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt
to suspend the device again in future and -EACCES means that
'power.disable_depth' is different from 0
- int pm_runtime_autosuspend(struct device *dev);
+ `int pm_runtime_autosuspend(struct device *dev);`
- same as pm_runtime_suspend() except that the autosuspend delay is taken
- into account; if pm_runtime_autosuspend_expiration() says the delay has
+ `into account;` if pm_runtime_autosuspend_expiration() says the delay has
not yet expired then an autosuspend is scheduled for the appropriate time
and 0 is returned
- int pm_runtime_resume(struct device *dev);
+ `int pm_runtime_resume(struct device *dev);`
- execute the subsystem-level resume callback for the device; returns 0 on
success, 1 if the device's runtime PM status was already 'active' or
error code on failure, where -EAGAIN means it may be safe to attempt to
@@ -331,17 +339,17 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
checked additionally, and -EACCES means that 'power.disable_depth' is
different from 0
- int pm_request_idle(struct device *dev);
+ `int pm_request_idle(struct device *dev);`
- submit a request to execute the subsystem-level idle callback for the
device (the request is represented by a work item in pm_wq); returns 0 on
success or error code if the request has not been queued up
- int pm_request_autosuspend(struct device *dev);
+ `int pm_request_autosuspend(struct device *dev);`
- schedule the execution of the subsystem-level suspend callback for the
device when the autosuspend delay has expired; if the delay has already
expired then the work item is queued up immediately
- int pm_schedule_suspend(struct device *dev, unsigned int delay);
+ `int pm_schedule_suspend(struct device *dev, unsigned int delay);`
- schedule the execution of the subsystem-level suspend callback for the
device in future, where 'delay' is the time to wait before queuing up a
suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work
@@ -351,58 +359,58 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
->runtime_suspend() is already scheduled and not yet expired, the new
value of 'delay' will be used as the time to wait
- int pm_request_resume(struct device *dev);
+ `int pm_request_resume(struct device *dev);`
- submit a request to execute the subsystem-level resume callback for the
device (the request is represented by a work item in pm_wq); returns 0 on
success, 1 if the device's runtime PM status was already 'active', or
error code if the request hasn't been queued up
- void pm_runtime_get_noresume(struct device *dev);
+ `void pm_runtime_get_noresume(struct device *dev);`
- increment the device's usage counter
- int pm_runtime_get(struct device *dev);
+ `int pm_runtime_get(struct device *dev);`
- increment the device's usage counter, run pm_request_resume(dev) and
return its result
- int pm_runtime_get_sync(struct device *dev);
+ `int pm_runtime_get_sync(struct device *dev);`
- increment the device's usage counter, run pm_runtime_resume(dev) and
return its result
- int pm_runtime_get_if_in_use(struct device *dev);
+ `int pm_runtime_get_if_in_use(struct device *dev);`
- return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
runtime PM status is RPM_ACTIVE and the runtime PM usage counter is
nonzero, increment the counter and return 1; otherwise return 0 without
changing the counter
- void pm_runtime_put_noidle(struct device *dev);
+ `void pm_runtime_put_noidle(struct device *dev);`
- decrement the device's usage counter
- int pm_runtime_put(struct device *dev);
+ `int pm_runtime_put(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_request_idle(dev) and return its result
- int pm_runtime_put_autosuspend(struct device *dev);
+ `int pm_runtime_put_autosuspend(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_request_autosuspend(dev) and return its result
- int pm_runtime_put_sync(struct device *dev);
+ `int pm_runtime_put_sync(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_runtime_idle(dev) and return its result
- int pm_runtime_put_sync_suspend(struct device *dev);
+ `int pm_runtime_put_sync_suspend(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_runtime_suspend(dev) and return its result
- int pm_runtime_put_sync_autosuspend(struct device *dev);
+ `int pm_runtime_put_sync_autosuspend(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_runtime_autosuspend(dev) and return its result
- void pm_runtime_enable(struct device *dev);
+ `void pm_runtime_enable(struct device *dev);`
- decrement the device's 'power.disable_depth' field; if that field is equal
to zero, the runtime PM helper functions can execute subsystem-level
callbacks described in Section 2 for the device
- int pm_runtime_disable(struct device *dev);
+ `int pm_runtime_disable(struct device *dev);`
- increment the device's 'power.disable_depth' field (if the value of that
field was previously zero, this prevents subsystem-level runtime PM
callbacks from being run for the device), make sure that all of the
@@ -411,7 +419,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
necessary to execute the subsystem-level resume callback for the device
to satisfy that request, otherwise 0 is returned
- int pm_runtime_barrier(struct device *dev);
+ `int pm_runtime_barrier(struct device *dev);`
- check if there's a resume request pending for the device and resume it
(synchronously) in that case, cancel any other pending runtime PM requests
regarding it and wait for all runtime PM operations on it in progress to
@@ -419,10 +427,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
necessary to execute the subsystem-level resume callback for the device to
satisfy that request, otherwise 0 is returned
- void pm_suspend_ignore_children(struct device *dev, bool enable);
+ `void pm_suspend_ignore_children(struct device *dev, bool enable);`
- set/unset the power.ignore_children flag of the device
- int pm_runtime_set_active(struct device *dev);
+ `int pm_runtime_set_active(struct device *dev);`
- clear the device's 'power.runtime_error' flag, set the device's runtime
PM status to 'active' and update its parent's counter of 'active'
children as appropriate (it is only valid to use this function if
@@ -430,61 +438,61 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
zero); it will fail and return error code if the device has a parent
which is not active and the 'power.ignore_children' flag of which is unset
- void pm_runtime_set_suspended(struct device *dev);
+ `void pm_runtime_set_suspended(struct device *dev);`
- clear the device's 'power.runtime_error' flag, set the device's runtime
PM status to 'suspended' and update its parent's counter of 'active'
children as appropriate (it is only valid to use this function if
'power.runtime_error' is set or 'power.disable_depth' is greater than
zero)
- bool pm_runtime_active(struct device *dev);
+ `bool pm_runtime_active(struct device *dev);`
- return true if the device's runtime PM status is 'active' or its
'power.disable_depth' field is not equal to zero, or false otherwise
- bool pm_runtime_suspended(struct device *dev);
+ `bool pm_runtime_suspended(struct device *dev);`
- return true if the device's runtime PM status is 'suspended' and its
'power.disable_depth' field is equal to zero, or false otherwise
- bool pm_runtime_status_suspended(struct device *dev);
+ `bool pm_runtime_status_suspended(struct device *dev);`
- return true if the device's runtime PM status is 'suspended'
- void pm_runtime_allow(struct device *dev);
+ `void pm_runtime_allow(struct device *dev);`
- set the power.runtime_auto flag for the device and decrease its usage
counter (used by the /sys/devices/.../power/control interface to
effectively allow the device to be power managed at run time)
- void pm_runtime_forbid(struct device *dev);
+ `void pm_runtime_forbid(struct device *dev);`
- unset the power.runtime_auto flag for the device and increase its usage
counter (used by the /sys/devices/.../power/control interface to
effectively prevent the device from being power managed at run time)
- void pm_runtime_no_callbacks(struct device *dev);
+ `void pm_runtime_no_callbacks(struct device *dev);`
- set the power.no_callbacks flag for the device and remove the runtime
PM attributes from /sys/devices/.../power (or prevent them from being
added when the device is registered)
- void pm_runtime_irq_safe(struct device *dev);
+ `void pm_runtime_irq_safe(struct device *dev);`
- set the power.irq_safe flag for the device, causing the runtime-PM
callbacks to be invoked with interrupts off
- bool pm_runtime_is_irq_safe(struct device *dev);
+ `bool pm_runtime_is_irq_safe(struct device *dev);`
- return true if power.irq_safe flag was set for the device, causing
the runtime-PM callbacks to be invoked with interrupts off
- void pm_runtime_mark_last_busy(struct device *dev);
+ `void pm_runtime_mark_last_busy(struct device *dev);`
- set the power.last_busy field to the current time
- void pm_runtime_use_autosuspend(struct device *dev);
+ `void pm_runtime_use_autosuspend(struct device *dev);`
- set the power.use_autosuspend flag, enabling autosuspend delays; call
pm_runtime_get_sync if the flag was previously cleared and
power.autosuspend_delay is negative
- void pm_runtime_dont_use_autosuspend(struct device *dev);
+ `void pm_runtime_dont_use_autosuspend(struct device *dev);`
- clear the power.use_autosuspend flag, disabling autosuspend delays;
decrement the device's usage counter if the flag was previously set and
power.autosuspend_delay is negative; call pm_runtime_idle
- void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);
+ `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
- set the power.autosuspend_delay value to 'delay' (expressed in
milliseconds); if 'delay' is negative then runtime suspends are
prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be
@@ -493,7 +501,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
changed to or from a negative value; if power.use_autosuspend is clear,
pm_runtime_idle is called
- unsigned long pm_runtime_autosuspend_expiration(struct device *dev);
+ `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
- calculate the time when the current autosuspend delay period will expire,
based on power.last_busy and power.autosuspend_delay; if the delay time
is 1000 ms or larger then the expiration time is rounded up to the
@@ -503,36 +511,37 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
It is safe to execute the following helper functions from interrupt context:
-pm_request_idle()
-pm_request_autosuspend()
-pm_schedule_suspend()
-pm_request_resume()
-pm_runtime_get_noresume()
-pm_runtime_get()
-pm_runtime_put_noidle()
-pm_runtime_put()
-pm_runtime_put_autosuspend()
-pm_runtime_enable()
-pm_suspend_ignore_children()
-pm_runtime_set_active()
-pm_runtime_set_suspended()
-pm_runtime_suspended()
-pm_runtime_mark_last_busy()
-pm_runtime_autosuspend_expiration()
+- pm_request_idle()
+- pm_request_autosuspend()
+- pm_schedule_suspend()
+- pm_request_resume()
+- pm_runtime_get_noresume()
+- pm_runtime_get()
+- pm_runtime_put_noidle()
+- pm_runtime_put()
+- pm_runtime_put_autosuspend()
+- pm_runtime_enable()
+- pm_suspend_ignore_children()
+- pm_runtime_set_active()
+- pm_runtime_set_suspended()
+- pm_runtime_suspended()
+- pm_runtime_mark_last_busy()
+- pm_runtime_autosuspend_expiration()
If pm_runtime_irq_safe() has been called for a device then the following helper
functions may also be used in interrupt context:
-pm_runtime_idle()
-pm_runtime_suspend()
-pm_runtime_autosuspend()
-pm_runtime_resume()
-pm_runtime_get_sync()
-pm_runtime_put_sync()
-pm_runtime_put_sync_suspend()
-pm_runtime_put_sync_autosuspend()
+- pm_runtime_idle()
+- pm_runtime_suspend()
+- pm_runtime_autosuspend()
+- pm_runtime_resume()
+- pm_runtime_get_sync()
+- pm_runtime_put_sync()
+- pm_runtime_put_sync_suspend()
+- pm_runtime_put_sync_autosuspend()
5. Runtime PM Initialization, Device Probing and Removal
+========================================================
Initially, the runtime PM is disabled for all devices, which means that the
majority of the runtime PM helper functions described in Section 4 will return
@@ -608,6 +617,7 @@ manage the device at run time, the driver may confuse it by using
pm_runtime_forbid() this way.
6. Runtime PM and System Sleep
+==============================
Runtime PM and system sleep (i.e., system suspend and hibernation, also known
as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of
@@ -647,9 +657,9 @@ brought back to full power during resume, then its runtime PM status will have
to be updated to reflect the actual post-system sleep status. The way to do
this is:
- pm_runtime_disable(dev);
- pm_runtime_set_active(dev);
- pm_runtime_enable(dev);
+ - pm_runtime_disable(dev);
+ - pm_runtime_set_active(dev);
+ - pm_runtime_enable(dev);
The PM core always increments the runtime usage counter before calling the
->suspend() callback and decrements it after calling the ->resume() callback.
@@ -705,66 +715,66 @@ Subsystems may wish to conserve code space by using the set of generic power
management callbacks provided by the PM core, defined in
driver/base/power/generic_ops.c:
- int pm_generic_runtime_suspend(struct device *dev);
+ `int pm_generic_runtime_suspend(struct device *dev);`
- invoke the ->runtime_suspend() callback provided by the driver of this
device and return its result, or return 0 if not defined
- int pm_generic_runtime_resume(struct device *dev);
+ `int pm_generic_runtime_resume(struct device *dev);`
- invoke the ->runtime_resume() callback provided by the driver of this
device and return its result, or return 0 if not defined
- int pm_generic_suspend(struct device *dev);
+ `int pm_generic_suspend(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->suspend()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_suspend_noirq(struct device *dev);
+ `int pm_generic_suspend_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_resume(struct device *dev);
+ `int pm_generic_resume(struct device *dev);`
- invoke the ->resume() callback provided by the driver of this device and,
if successful, change the device's runtime PM status to 'active'
- int pm_generic_resume_noirq(struct device *dev);
+ `int pm_generic_resume_noirq(struct device *dev);`
- invoke the ->resume_noirq() callback provided by the driver of this device
- int pm_generic_freeze(struct device *dev);
+ `int pm_generic_freeze(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->freeze()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_freeze_noirq(struct device *dev);
+ `int pm_generic_freeze_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_thaw(struct device *dev);
+ `int pm_generic_thaw(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->thaw()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_thaw_noirq(struct device *dev);
+ `int pm_generic_thaw_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_poweroff(struct device *dev);
+ `int pm_generic_poweroff(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->poweroff()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_poweroff_noirq(struct device *dev);
+ `int pm_generic_poweroff_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_restore(struct device *dev);
+ `int pm_generic_restore(struct device *dev);`
- invoke the ->restore() callback provided by the driver of this device and,
if successful, change the device's runtime PM status to 'active'
- int pm_generic_restore_noirq(struct device *dev);
+ `int pm_generic_restore_noirq(struct device *dev);`
- invoke the ->restore_noirq() callback provided by the device's driver
These functions are the defaults used by the PM core, if a subsystem doesn't
@@ -781,6 +791,7 @@ UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its
last argument to NULL).
8. "No-Callback" Devices
+========================
Some "devices" are only logical sub-devices of their parent and cannot be
power-managed on their own. (The prototype example is a USB interface. Entire
@@ -807,6 +818,7 @@ parent must take responsibility for telling the device's driver when the
parent's power state changes.
9. Autosuspend, or automatically-delayed suspends
+=================================================
Changing a device's power state isn't free; it requires both time and energy.
A device should be put in a low-power state only when there's some reason to
@@ -832,8 +844,8 @@ registration the length should be controlled by user space, using the
In order to use autosuspend, subsystems or drivers must call
pm_runtime_use_autosuspend() (preferably before registering the device), and
-thereafter they should use the various *_autosuspend() helper functions instead
-of the non-autosuspend counterparts:
+thereafter they should use the various `*_autosuspend()` helper functions
+instead of the non-autosuspend counterparts::
Instead of: pm_runtime_suspend use: pm_runtime_autosuspend;
Instead of: pm_schedule_suspend use: pm_request_autosuspend;
@@ -858,7 +870,7 @@ The implementation is well suited for asynchronous use in interrupt contexts.
However such use inevitably involves races, because the PM core can't
synchronize ->runtime_suspend() callbacks with the arrival of I/O requests.
This synchronization must be handled by the driver, using its private lock.
-Here is a schematic pseudo-code example:
+Here is a schematic pseudo-code example::
foo_read_or_write(struct foo_priv *foo, void *data)
{
diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.rst
similarity index 92%
rename from Documentation/power/s2ram.txt
rename to Documentation/power/s2ram.rst
index 4685aee197fd..d739aa7c742c 100644
--- a/Documentation/power/s2ram.txt
+++ b/Documentation/power/s2ram.rst
@@ -1,7 +1,9 @@
- How to get s2ram working
- ~~~~~~~~~~~~~~~~~~~~~~~~
- 2006 Linus Torvalds
- 2006 Pavel Machek
+========================
+How to get s2ram working
+========================
+
+2006 Linus Torvalds
+2006 Pavel Machek
1) Check suspend.sf.net, program s2ram there has long whitelist of
"known ok" machines, along with tricks to use on each one.
@@ -12,8 +14,8 @@
3) You can use Linus' TRACE_RESUME infrastructure, described below.
- Using TRACE_RESUME
- ~~~~~~~~~~~~~~~~~~
+Using TRACE_RESUME
+~~~~~~~~~~~~~~~~~~
I've been working at making the machines I have able to STR, and almost
always it's a driver that is buggy. Thank God for the suspend/resume
@@ -27,7 +29,7 @@ machine that doesn't boot) is:
- enable PM_DEBUG, and PM_TRACE
- - use a script like this:
+ - use a script like this::
#!/bin/sh
sync
@@ -38,7 +40,7 @@ machine that doesn't boot) is:
- if it doesn't come back up (which is usually the problem), reboot by
holding the power button down, and look at the dmesg output for things
- like
+ like::
Magic number: 4:156:725
hash matches drivers/base/power/resume.c:28
@@ -52,7 +54,7 @@ machine that doesn't boot) is:
If no device matches the hash (or any matches appear to be false positives),
the culprit may be a device from a loadable kernel module that is not loaded
until after the hash is checked. You can check the hash against the current
- devices again after more modules are loaded using sysfs:
+ devices again after more modules are loaded using sysfs::
cat /sys/power/pm_trace_dev_match
diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst
similarity index 90%
rename from Documentation/power/suspend-and-cpuhotplug.txt
rename to Documentation/power/suspend-and-cpuhotplug.rst
index a8751b8df10e..9df664f5423a 100644
--- a/Documentation/power/suspend-and-cpuhotplug.txt
+++ b/Documentation/power/suspend-and-cpuhotplug.rst
@@ -1,10 +1,15 @@
+====================================================================
Interaction of Suspend code (S3) with the CPU hotplug infrastructure
+====================================================================
- (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
+(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
-I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM
- infrastructure uses it internally? And where do they share common code?
+I. Differences between CPU hotplug and Suspend-to-RAM
+======================================================
+
+How does the regular CPU hotplug code differ from how the Suspend-to-RAM
+infrastructure uses it internally? And where do they share common code?
Well, a picture is worth a thousand words... So ASCII art follows :-)
@@ -16,13 +21,13 @@ of describing where they take different paths and where they share code.
What happens when regular CPU hotplug and Suspend-to-RAM race with each other
is not depicted here.]
-On a high level, the suspend-resume cycle goes like this:
+On a high level, the suspend-resume cycle goes like this::
-|Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw |
-|tasks | | cpus | | | | cpus | |tasks|
+ |Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw |
+ |tasks | | cpus | | | | cpus | |tasks|
-More details follow:
+More details follow::
Suspend call path
-----------------
@@ -87,7 +92,9 @@ More details follow:
Resuming back is likewise, with the counterparts being (in the order of
execution during resume):
-* enable_nonboot_cpus() which involves:
+
+* enable_nonboot_cpus() which involves::
+
| Acquire cpu_add_remove_lock
| Decrease cpu_hotplug_disabled, thereby enabling regular cpu hotplug
| Call _cpu_up() [for all those cpus in the frozen_cpus mask, in a loop]
@@ -101,7 +108,7 @@ execution during resume):
It is to be noted here that the system_transition_mutex lock is acquired at the very
beginning, when we are just starting out to suspend, and then released only
-after the entire cycle is complete (i.e., suspend + resume).
+after the entire cycle is complete (i.e., suspend + resume)::
@@ -152,16 +159,16 @@ with the 'tasks_frozen' argument set to 1.
Important files and functions/entry points:
-------------------------------------------
+-------------------------------------------
-kernel/power/process.c : freeze_processes(), thaw_processes()
-kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish()
-kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus()
+- kernel/power/process.c : freeze_processes(), thaw_processes()
+- kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish()
+- kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus()
II. What are the issues involved in CPU hotplug?
- -------------------------------------------
+------------------------------------------------
There are some interesting situations involving CPU hotplug and microcode
update on the CPUs, as discussed below:
@@ -243,8 +250,11 @@ d. Handling microcode update during suspend/hibernate:
cycles).
-III. Are there any known problems when regular CPU hotplug and suspend race
- with each other?
+III. Known problems
+===================
+
+Are there any known problems when regular CPU hotplug and suspend race
+with each other?
Yes, they are listed below:
diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.rst
similarity index 98%
rename from Documentation/power/suspend-and-interrupts.txt
rename to Documentation/power/suspend-and-interrupts.rst
index 8afb29a8604a..4cda6617709a 100644
--- a/Documentation/power/suspend-and-interrupts.txt
+++ b/Documentation/power/suspend-and-interrupts.rst
@@ -1,4 +1,6 @@
+====================================
System Suspend and Device Interrupts
+====================================
Copyright (C) 2014 Intel Corp.
Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
diff --git a/Documentation/power/swsusp-and-swap-files.txt b/Documentation/power/swsusp-and-swap-files.rst
similarity index 83%
rename from Documentation/power/swsusp-and-swap-files.txt
rename to Documentation/power/swsusp-and-swap-files.rst
index f281886de490..a33a2919dbe4 100644
--- a/Documentation/power/swsusp-and-swap-files.txt
+++ b/Documentation/power/swsusp-and-swap-files.rst
@@ -1,4 +1,7 @@
+===============================================
Using swap files with software suspend (swsusp)
+===============================================
+
(C) 2006 Rafael J. Wysocki <rjw@sisk.pl>
The Linux kernel handles swap files almost in the same way as it handles swap
@@ -21,20 +24,20 @@ units.
In order to use a swap file with swsusp, you need to:
-1) Create the swap file and make it active, eg.
+1) Create the swap file and make it active, eg.::
-# dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k>
-# mkswap <swap_file_path>
-# swapon <swap_file_path>
+ # dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k>
+ # mkswap <swap_file_path>
+ # swapon <swap_file_path>
2) Use an application that will bmap the swap file with the help of the
FIBMAP ioctl and determine the location of the file's swap header, as the
offset, in <PAGE_SIZE> units, from the beginning of the partition which
holds the swap file.
-3) Add the following parameters to the kernel command line:
+3) Add the following parameters to the kernel command line::
-resume=<swap_file_partition> resume_offset=<swap_file_offset>
+ resume=<swap_file_partition> resume_offset=<swap_file_offset>
where <swap_file_partition> is the partition on which the swap file is located
and <swap_file_offset> is the offset of the swap header determined by the
@@ -46,7 +49,7 @@ OR
Use a userland suspend application that will set the partition and offset
with the help of the SNAPSHOT_SET_SWAP_AREA ioctl described in
-Documentation/power/userland-swsusp.txt (this is the only method to suspend
+Documentation/power/userland-swsusp.rst (this is the only method to suspend
to a swap file allowing the resume to be initiated from an initrd or initramfs
image).
diff --git a/Documentation/power/swsusp-dmcrypt.txt b/Documentation/power/swsusp-dmcrypt.rst
similarity index 67%
rename from Documentation/power/swsusp-dmcrypt.txt
rename to Documentation/power/swsusp-dmcrypt.rst
index b802fbfd95ef..426df59172cd 100644
--- a/Documentation/power/swsusp-dmcrypt.txt
+++ b/Documentation/power/swsusp-dmcrypt.rst
@@ -1,13 +1,15 @@
+=======================================
+How to use dm-crypt and swsusp together
+=======================================
+
Author: Andreas Steinmetz <ast@domdv.de>
-How to use dm-crypt and swsusp together:
-========================================
Some prerequisites:
You know how dm-crypt works. If not, visit the following web page:
http://www.saout.de/misc/dm-crypt/
-You have read Documentation/power/swsusp.txt and understand it.
+You have read Documentation/power/swsusp.rst and understand it.
You did read Documentation/admin-guide/initrd.rst and know how an initrd works.
You know how to create or how to modify an initrd.
@@ -29,23 +31,23 @@ a way that the swap device you suspend to/resume from has
always the same major/minor within the initrd as well as
within your running system. The easiest way to achieve this is
to always set up this swap device first with dmsetup, so that
-it will always look like the following:
+it will always look like the following::
-brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
+ brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
Now set up your kernel to use /dev/mapper/swap0 as the default
-resume partition, so your kernel .config contains:
+resume partition, so your kernel .config contains::
-CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
+ CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
Prepare your boot loader to use the initrd you will create or
modify. For lilo the simplest setup looks like the following
-lines:
+lines::
-image=/boot/vmlinuz
-initrd=/boot/initrd.gz
-label=linux
-append="root=/dev/ram0 init=/linuxrc rw"
+ image=/boot/vmlinuz
+ initrd=/boot/initrd.gz
+ label=linux
+ append="root=/dev/ram0 init=/linuxrc rw"
Finally you need to create or modify your initrd. Lets assume
you create an initrd that reads the required dm-crypt setup
@@ -53,66 +55,66 @@ from a pcmcia flash disk card. The card is formatted with an ext2
fs which resides on /dev/hde1 when the card is inserted. The
card contains at least the encrypted swap setup in a file
named "swapkey". /etc/fstab of your initrd contains something
-like the following:
+like the following::
-/dev/hda1 /mnt ext3 ro 0 0
-none /proc proc defaults,noatime,nodiratime 0 0
-none /sys sysfs defaults,noatime,nodiratime 0 0
+ /dev/hda1 /mnt ext3 ro 0 0
+ none /proc proc defaults,noatime,nodiratime 0 0
+ none /sys sysfs defaults,noatime,nodiratime 0 0
/dev/hda1 contains an unencrypted mini system that sets up all
of your crypto devices, again by reading the setup from the
pcmcia flash disk. What follows now is a /linuxrc for your
initrd that allows you to resume from encrypted swap and that
continues boot with your mini system on /dev/hda1 if resume
-does not happen:
+does not happen::
-#!/bin/sh
-PATH=/sbin:/bin:/usr/sbin:/usr/bin
-mount /proc
-mount /sys
-mapped=0
-noresume=`grep -c noresume /proc/cmdline`
-if [ "$*" != "" ]
-then
- noresume=1
-fi
-dmesg -n 1
-/sbin/cardmgr -q
-for i in 1 2 3 4 5 6 7 8 9 0
-do
- if [ -f /proc/ide/hde/media ]
+ #!/bin/sh
+ PATH=/sbin:/bin:/usr/sbin:/usr/bin
+ mount /proc
+ mount /sys
+ mapped=0
+ noresume=`grep -c noresume /proc/cmdline`
+ if [ "$*" != "" ]
then
+ noresume=1
+ fi
+ dmesg -n 1
+ /sbin/cardmgr -q
+ for i in 1 2 3 4 5 6 7 8 9 0
+ do
+ if [ -f /proc/ide/hde/media ]
+ then
+ usleep 500000
+ mount -t ext2 -o ro /dev/hde1 /mnt
+ if [ -f /mnt/swapkey ]
+ then
+ dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
+ fi
+ umount /mnt
+ break
+ fi
usleep 500000
- mount -t ext2 -o ro /dev/hde1 /mnt
- if [ -f /mnt/swapkey ]
+ done
+ killproc /sbin/cardmgr
+ dmesg -n 6
+ if [ $mapped = 1 ]
+ then
+ if [ $noresume != 0 ]
then
- dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
+ mkswap /dev/mapper/swap0 > /dev/null 2>&1
fi
- umount /mnt
- break
+ echo 254:0 > /sys/power/resume
+ dmsetup remove swap0
fi
- usleep 500000
-done
-killproc /sbin/cardmgr
-dmesg -n 6
-if [ $mapped = 1 ]
-then
- if [ $noresume != 0 ]
- then
- mkswap /dev/mapper/swap0 > /dev/null 2>&1
- fi
- echo 254:0 > /sys/power/resume
- dmsetup remove swap0
-fi
-umount /sys
-mount /mnt
-umount /proc
-cd /mnt
-pivot_root . mnt
-mount /proc
-umount -l /mnt
-umount /proc
-exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
+ umount /sys
+ mount /mnt
+ umount /proc
+ cd /mnt
+ pivot_root . mnt
+ mount /proc
+ umount -l /mnt
+ umount /proc
+ exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
Please don't mind the weird loop above, busybox's msh doesn't know
the let statement. Now, what is happening in the script?
diff --git a/Documentation/power/swsusp.rst b/Documentation/power/swsusp.rst
new file mode 100644
index 000000000000..d000312f6965
--- /dev/null
+++ b/Documentation/power/swsusp.rst
@@ -0,0 +1,501 @@
+============
+Swap suspend
+============
+
+Some warnings, first.
+
+.. warning::
+
+ **BIG FAT WARNING**
+
+ If you touch anything on disk between suspend and resume...
+ ...kiss your data goodbye.
+
+ If you do resume from initrd after your filesystems are mounted...
+ ...bye bye root partition.
+
+ [this is actually same case as above]
+
+ If you have unsupported ( ) devices using DMA, you may have some
+ problems. If your disk driver does not support suspend... (IDE does),
+ it may cause some problems, too. If you change kernel command line
+ between suspend and resume, it may do something wrong. If you change
+ your hardware while system is suspended... well, it was not good idea;
+ but it will probably only crash.
+
+ ( ) suspend/resume support is needed to make it safe.
+
+ If you have any filesystems on USB devices mounted before software suspend,
+ they won't be accessible after resume and you may lose data, as though
+ you have unplugged the USB devices with mounted filesystems on them;
+ see the FAQ below for details. (This is not true for more traditional
+ power states like "standby", which normally don't turn USB off.)
+
+Swap partition:
+ You need to append resume=/dev/your_swap_partition to kernel command
+ line or specify it using /sys/power/resume.
+
+Swap file:
+ If using a swapfile you can also specify a resume offset using
+ resume_offset=<number> on the kernel command line or specify it
+ in /sys/power/resume_offset.
+
+After preparing then you suspend by::
+
+ echo shutdown > /sys/power/disk; echo disk > /sys/power/state
+
+- If you feel ACPI works pretty well on your system, you might try::
+
+ echo platform > /sys/power/disk; echo disk > /sys/power/state
+
+- If you would like to write hibernation image to swap and then suspend
+ to RAM (provided your platform supports it), you can try::
+
+ echo suspend > /sys/power/disk; echo disk > /sys/power/state
+
+- If you have SATA disks, you'll need recent kernels with SATA suspend
+ support. For suspend and resume to work, make sure your disk drivers
+ are built into kernel -- not modules. [There's way to make
+ suspend/resume with modular disk drivers, see FAQ, but you probably
+ should not do that.]
+
+If you want to limit the suspend image size to N bytes, do::
+
+ echo N > /sys/power/image_size
+
+before suspend (it is limited to around 2/5 of available RAM by default).
+
+- The resume process checks for the presence of the resume device,
+ if found, it then checks the contents for the hibernation image signature.
+ If both are found, it resumes the hibernation image.
+
+- The resume process may be triggered in two ways:
+
+ 1) During lateinit: If resume=/dev/your_swap_partition is specified on
+ the kernel command line, lateinit runs the resume process. If the
+ resume device has not been probed yet, the resume process fails and
+ bootup continues.
+ 2) Manually from an initrd or initramfs: May be run from
+ the init script by using the /sys/power/resume file. It is vital
+ that this be done prior to remounting any filesystems (even as
+ read-only) otherwise data may be corrupted.
+
+Article about goals and implementation of Software Suspend for Linux
+====================================================================
+
+Author: Gábor Kuti
+Last revised: 2003-10-20 by Pavel Machek
+
+Idea and goals to achieve
+-------------------------
+
+Nowadays it is common in several laptops that they have a suspend button. It
+saves the state of the machine to a filesystem or to a partition and switches
+to standby mode. Later resuming the machine the saved state is loaded back to
+ram and the machine can continue its work. It has two real benefits. First we
+save ourselves the time machine goes down and later boots up, energy costs
+are real high when running from batteries. The other gain is that we don't have
+to interrupt our programs so processes that are calculating something for a long
+time shouldn't need to be written interruptible.
+
+swsusp saves the state of the machine into active swaps and then reboots or
+powerdowns. You must explicitly specify the swap partition to resume from with
+`resume=` kernel option. If signature is found it loads and restores saved
+state. If the option `noresume` is specified as a boot parameter, it skips
+the resuming. If the option `hibernate=nocompress` is specified as a boot
+parameter, it saves hibernation image without compression.
+
+In the meantime while the system is suspended you should not add/remove any
+of the hardware, write to the filesystems, etc.
+
+Sleep states summary
+====================
+
+There are three different interfaces you can use, /proc/acpi should
+work like this:
+
+In a really perfect world::
+
+ echo 1 > /proc/acpi/sleep # for standby
+ echo 2 > /proc/acpi/sleep # for suspend to ram
+ echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
+ echo 4 > /proc/acpi/sleep # for suspend to disk
+ echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
+
+and perhaps::
+
+ echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
+
+Frequently Asked Questions
+==========================
+
+Q:
+ well, suspending a server is IMHO a really stupid thing,
+ but... (Diego Zuccato):
+
+A:
+ You bought new UPS for your server. How do you install it without
+ bringing machine down? Suspend to disk, rearrange power cables,
+ resume.
+
+ You have your server on UPS. Power died, and UPS is indicating 30
+ seconds to failure. What do you do? Suspend to disk.
+
+
+Q:
+ Maybe I'm missing something, but why don't the regular I/O paths work?
+
+A:
+ We do use the regular I/O paths. However we cannot restore the data
+ to its original location as we load it. That would create an
+ inconsistent kernel state which would certainly result in an oops.
+ Instead, we load the image into unused memory and then atomically copy
+ it back to it original location. This implies, of course, a maximum
+ image size of half the amount of memory.
+
+ There are two solutions to this:
+
+ * require half of memory to be free during suspend. That way you can
+ read "new" data onto free spots, then cli and copy
+
+ * assume we had special "polling" ide driver that only uses memory
+ between 0-640KB. That way, I'd have to make sure that 0-640KB is free
+ during suspending, but otherwise it would work...
+
+ suspend2 shares this fundamental limitation, but does not include user
+ data and disk caches into "used memory" by saving them in
+ advance. That means that the limitation goes away in practice.
+
+Q:
+ Does linux support ACPI S4?
+
+A:
+ Yes. That's what echo platform > /sys/power/disk does.
+
+Q:
+ What is 'suspend2'?
+
+A:
+ suspend2 is 'Software Suspend 2', a forked implementation of
+ suspend-to-disk which is available as separate patches for 2.4 and 2.6
+ kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB
+ highmem and preemption. It also has a extensible architecture that
+ allows for arbitrary transformations on the image (compression,
+ encryption) and arbitrary backends for writing the image (eg to swap
+ or an NFS share[Work In Progress]). Questions regarding suspend2
+ should be sent to the mailing list available through the suspend2
+ website, and not to the Linux Kernel Mailing List. We are working
+ toward merging suspend2 into the mainline kernel.
+
+Q:
+ What is the freezing of tasks and why are we using it?
+
+A:
+ The freezing of tasks is a mechanism by which user space processes and some
+ kernel threads are controlled during hibernation or system-wide suspend (on some
+ architectures). See freezing-of-tasks.txt for details.
+
+Q:
+ What is the difference between "platform" and "shutdown"?
+
+A:
+ shutdown:
+ save state in linux, then tell bios to powerdown
+
+ platform:
+ save state in linux, then tell bios to powerdown and blink
+ "suspended led"
+
+ "platform" is actually right thing to do where supported, but
+ "shutdown" is most reliable (except on ACPI systems).
+
+Q:
+ I do not understand why you have such strong objections to idea of
+ selective suspend.
+
+A:
+ Do selective suspend during runtime power management, that's okay. But
+ it's useless for suspend-to-disk. (And I do not see how you could use
+ it for suspend-to-ram, I hope you do not want that).
+
+ Lets see, so you suggest to
+
+ * SUSPEND all but swap device and parents
+ * Snapshot
+ * Write image to disk
+ * SUSPEND swap device and parents
+ * Powerdown
+
+ Oh no, that does not work, if swap device or its parents uses DMA,
+ you've corrupted data. You'd have to do
+
+ * SUSPEND all but swap device and parents
+ * FREEZE swap device and parents
+ * Snapshot
+ * UNFREEZE swap device and parents
+ * Write
+ * SUSPEND swap device and parents
+
+ Which means that you still need that FREEZE state, and you get more
+ complicated code. (And I have not yet introduce details like system
+ devices).
+
+Q:
+ There don't seem to be any generally useful behavioral
+ distinctions between SUSPEND and FREEZE.
+
+A:
+ Doing SUSPEND when you are asked to do FREEZE is always correct,
+ but it may be unnecessarily slow. If you want your driver to stay simple,
+ slowness may not matter to you. It can always be fixed later.
+
+ For devices like disk it does matter, you do not want to spindown for
+ FREEZE.
+
+Q:
+ After resuming, system is paging heavily, leading to very bad interactivity.
+
+A:
+ Try running::
+
+ cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file
+ do
+ test -f "$file" && cat "$file" > /dev/null
+ done
+
+ after resume. swapoff -a; swapon -a may also be useful.
+
+Q:
+ What happens to devices during swsusp? They seem to be resumed
+ during system suspend?
+
+A:
+ That's correct. We need to resume them if we want to write image to
+ disk. Whole sequence goes like
+
+ **Suspend part**
+
+ running system, user asks for suspend-to-disk
+
+ user processes are stopped
+
+ suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
+ with state snapshot
+
+ state snapshot: copy of whole used memory is taken with interrupts disabled
+
+ resume(): devices are woken up so that we can write image to swap
+
+ write image to swap
+
+ suspend(PMSG_SUSPEND): suspend devices so that we can power off
+
+ turn the power off
+
+ **Resume part**
+
+ (is actually pretty similar)
+
+ running system, user asks for suspend-to-disk
+
+ user processes are stopped (in common case there are none,
+ but with resume-from-initrd, no one knows)
+
+ read image from disk
+
+ suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
+ with image restoration
+
+ image restoration: rewrite memory with image
+
+ resume(): devices are woken up so that system can continue
+
+ thaw all user processes
+
+Q:
+ What is this 'Encrypt suspend image' for?
+
+A:
+ First of all: it is not a replacement for dm-crypt encrypted swap.
+ It cannot protect your computer while it is suspended. Instead it does
+ protect from leaking sensitive data after resume from suspend.
+
+ Think of the following: you suspend while an application is running
+ that keeps sensitive data in memory. The application itself prevents
+ the data from being swapped out. Suspend, however, must write these
+ data to swap to be able to resume later on. Without suspend encryption
+ your sensitive data are then stored in plaintext on disk. This means
+ that after resume your sensitive data are accessible to all
+ applications having direct access to the swap device which was used
+ for suspend. If you don't need swap after resume these data can remain
+ on disk virtually forever. Thus it can happen that your system gets
+ broken in weeks later and sensitive data which you thought were
+ encrypted and protected are retrieved and stolen from the swap device.
+ To prevent this situation you should use 'Encrypt suspend image'.
+
+ During suspend a temporary key is created and this key is used to
+ encrypt the data written to disk. When, during resume, the data was
+ read back into memory the temporary key is destroyed which simply
+ means that all data written to disk during suspend are then
+ inaccessible so they can't be stolen later on. The only thing that
+ you must then take care of is that you call 'mkswap' for the swap
+ partition used for suspend as early as possible during regular
+ boot. This asserts that any temporary key from an oopsed suspend or
+ from a failed or aborted resume is erased from the swap device.
+
+ As a rule of thumb use encrypted swap to protect your data while your
+ system is shut down or suspended. Additionally use the encrypted
+ suspend image to prevent sensitive data from being stolen after
+ resume.
+
+Q:
+ Can I suspend to a swap file?
+
+A:
+ Generally, yes, you can. However, it requires you to use the "resume=" and
+ "resume_offset=" kernel command line parameters, so the resume from a swap file
+ cannot be initiated from an initrd or initramfs image. See
+ swsusp-and-swap-files.txt for details.
+
+Q:
+ Is there a maximum system RAM size that is supported by swsusp?
+
+A:
+ It should work okay with highmem.
+
+Q:
+ Does swsusp (to disk) use only one swap partition or can it use
+ multiple swap partitions (aggregate them into one logical space)?
+
+A:
+ Only one swap partition, sorry.
+
+Q:
+ If my application(s) causes lots of memory & swap space to be used
+ (over half of the total system RAM), is it correct that it is likely
+ to be useless to try to suspend to disk while that app is running?
+
+A:
+ No, it should work okay, as long as your app does not mlock()
+ it. Just prepare big enough swap partition.
+
+Q:
+ What information is useful for debugging suspend-to-disk problems?
+
+A:
+ Well, last messages on the screen are always useful. If something
+ is broken, it is usually some kernel driver, therefore trying with as
+ little as possible modules loaded helps a lot. I also prefer people to
+ suspend from console, preferably without X running. Booting with
+ init=/bin/bash, then swapon and starting suspend sequence manually
+ usually does the trick. Then it is good idea to try with latest
+ vanilla kernel.
+
+Q:
+ How can distributions ship a swsusp-supporting kernel with modular
+ disk drivers (especially SATA)?
+
+A:
+ Well, it can be done, load the drivers, then do echo into
+ /sys/power/resume file from initrd. Be sure not to mount
+ anything, not even read-only mount, or you are going to lose your
+ data.
+
+Q:
+ How do I make suspend more verbose?
+
+A:
+ If you want to see any non-error kernel messages on the virtual
+ terminal the kernel switches to during suspend, you have to set the
+ kernel console loglevel to at least 4 (KERN_WARNING), for example by
+ doing::
+
+ # save the old loglevel
+ read LOGLEVEL DUMMY < /proc/sys/kernel/printk
+ # set the loglevel so we see the progress bar.
+ # if the level is higher than needed, we leave it alone.
+ if [ $LOGLEVEL -lt 5 ]; then
+ echo 5 > /proc/sys/kernel/printk
+ fi
+
+ IMG_SZ=0
+ read IMG_SZ < /sys/power/image_size
+ echo -n disk > /sys/power/state
+ RET=$?
+ #
+ # the logic here is:
+ # if image_size > 0 (without kernel support, IMG_SZ will be zero),
+ # then try again with image_size set to zero.
+ if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size
+ echo 0 > /sys/power/image_size
+ echo -n disk > /sys/power/state
+ RET=$?
+ fi
+
+ # restore previous loglevel
+ echo $LOGLEVEL > /proc/sys/kernel/printk
+ exit $RET
+
+Q:
+ Is this true that if I have a mounted filesystem on a USB device and
+ I suspend to disk, I can lose data unless the filesystem has been mounted
+ with "sync"?
+
+A:
+ That's right ... if you disconnect that device, you may lose data.
+ In fact, even with "-o sync" you can lose data if your programs have
+ information in buffers they haven't written out to a disk you disconnect,
+ or if you disconnect before the device finished saving data you wrote.
+
+ Software suspend normally powers down USB controllers, which is equivalent
+ to disconnecting all USB devices attached to your system.
+
+ Your system might well support low-power modes for its USB controllers
+ while the system is asleep, maintaining the connection, using true sleep
+ modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the
+ /sys/power/state file; write "standby" or "mem".) We've not seen any
+ hardware that can use these modes through software suspend, although in
+ theory some systems might support "platform" modes that won't break the
+ USB connections.
+
+ Remember that it's always a bad idea to unplug a disk drive containing a
+ mounted filesystem. That's true even when your system is asleep! The
+ safest thing is to unmount all filesystems on removable media (such USB,
+ Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
+ before suspending; then remount them after resuming.
+
+ There is a work-around for this problem. For more information, see
+ Documentation/driver-api/usb/persist.rst.
+
+Q:
+ Can I suspend-to-disk using a swap partition under LVM?
+
+A:
+ Yes and No. You can suspend successfully, but the kernel will not be able
+ to resume on its own. You need an initramfs that can recognize the resume
+ situation, activate the logical volume containing the swap volume (but not
+ touch any filesystems!), and eventually call::
+
+ echo -n "$major:$minor" > /sys/power/resume
+
+ where $major and $minor are the respective major and minor device numbers of
+ the swap volume.
+
+ uswsusp works with LVM, too. See http://suspend.sourceforge.net/
+
+Q:
+ I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were
+ compiled with the similar configuration files. Anyway I found that
+ suspend to disk (and resume) is much slower on 2.6.16 compared to
+ 2.6.15. Any idea for why that might happen or how can I speed it up?
+
+A:
+ This is because the size of the suspend image is now greater than
+ for 2.6.15 (by saving more data we can get more responsive system
+ after resume).
+
+ There's the /sys/power/image_size knob that controls the size of the
+ image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as
+ root), the 2.6.15 behavior should be restored. If it is still too
+ slow, take a look at suspend.sf.net -- userland suspend is faster and
+ supports LZF compression to speed it up further.
diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt
deleted file mode 100644
index 236d1fb13640..000000000000
--- a/Documentation/power/swsusp.txt
+++ /dev/null
@@ -1,446 +0,0 @@
-Some warnings, first.
-
- * BIG FAT WARNING *********************************************************
- *
- * If you touch anything on disk between suspend and resume...
- * ...kiss your data goodbye.
- *
- * If you do resume from initrd after your filesystems are mounted...
- * ...bye bye root partition.
- * [this is actually same case as above]
- *
- * If you have unsupported (*) devices using DMA, you may have some
- * problems. If your disk driver does not support suspend... (IDE does),
- * it may cause some problems, too. If you change kernel command line
- * between suspend and resume, it may do something wrong. If you change
- * your hardware while system is suspended... well, it was not good idea;
- * but it will probably only crash.
- *
- * (*) suspend/resume support is needed to make it safe.
- *
- * If you have any filesystems on USB devices mounted before software suspend,
- * they won't be accessible after resume and you may lose data, as though
- * you have unplugged the USB devices with mounted filesystems on them;
- * see the FAQ below for details. (This is not true for more traditional
- * power states like "standby", which normally don't turn USB off.)
-
-Swap partition:
-You need to append resume=/dev/your_swap_partition to kernel command
-line or specify it using /sys/power/resume.
-
-Swap file:
-If using a swapfile you can also specify a resume offset using
-resume_offset=<number> on the kernel command line or specify it
-in /sys/power/resume_offset.
-
-After preparing then you suspend by
-
-echo shutdown > /sys/power/disk; echo disk > /sys/power/state
-
-. If you feel ACPI works pretty well on your system, you might try
-
-echo platform > /sys/power/disk; echo disk > /sys/power/state
-
-. If you would like to write hibernation image to swap and then suspend
-to RAM (provided your platform supports it), you can try
-
-echo suspend > /sys/power/disk; echo disk > /sys/power/state
-
-. If you have SATA disks, you'll need recent kernels with SATA suspend
-support. For suspend and resume to work, make sure your disk drivers
-are built into kernel -- not modules. [There's way to make
-suspend/resume with modular disk drivers, see FAQ, but you probably
-should not do that.]
-
-If you want to limit the suspend image size to N bytes, do
-
-echo N > /sys/power/image_size
-
-before suspend (it is limited to around 2/5 of available RAM by default).
-
-. The resume process checks for the presence of the resume device,
-if found, it then checks the contents for the hibernation image signature.
-If both are found, it resumes the hibernation image.
-
-. The resume process may be triggered in two ways:
- 1) During lateinit: If resume=/dev/your_swap_partition is specified on
- the kernel command line, lateinit runs the resume process. If the
- resume device has not been probed yet, the resume process fails and
- bootup continues.
- 2) Manually from an initrd or initramfs: May be run from
- the init script by using the /sys/power/resume file. It is vital
- that this be done prior to remounting any filesystems (even as
- read-only) otherwise data may be corrupted.
-
-Article about goals and implementation of Software Suspend for Linux
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Author: Gábor Kuti
-Last revised: 2003-10-20 by Pavel Machek
-
-Idea and goals to achieve
-
-Nowadays it is common in several laptops that they have a suspend button. It
-saves the state of the machine to a filesystem or to a partition and switches
-to standby mode. Later resuming the machine the saved state is loaded back to
-ram and the machine can continue its work. It has two real benefits. First we
-save ourselves the time machine goes down and later boots up, energy costs
-are real high when running from batteries. The other gain is that we don't have to
-interrupt our programs so processes that are calculating something for a long
-time shouldn't need to be written interruptible.
-
-swsusp saves the state of the machine into active swaps and then reboots or
-powerdowns. You must explicitly specify the swap partition to resume from with
-``resume='' kernel option. If signature is found it loads and restores saved
-state. If the option ``noresume'' is specified as a boot parameter, it skips
-the resuming. If the option ``hibernate=nocompress'' is specified as a boot
-parameter, it saves hibernation image without compression.
-
-In the meantime while the system is suspended you should not add/remove any
-of the hardware, write to the filesystems, etc.
-
-Sleep states summary
-====================
-
-There are three different interfaces you can use, /proc/acpi should
-work like this:
-
-In a really perfect world:
-echo 1 > /proc/acpi/sleep # for standby
-echo 2 > /proc/acpi/sleep # for suspend to ram
-echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
-echo 4 > /proc/acpi/sleep # for suspend to disk
-echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
-
-and perhaps
-echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
-
-Frequently Asked Questions
-==========================
-
-Q: well, suspending a server is IMHO a really stupid thing,
-but... (Diego Zuccato):
-
-A: You bought new UPS for your server. How do you install it without
-bringing machine down? Suspend to disk, rearrange power cables,
-resume.
-
-You have your server on UPS. Power died, and UPS is indicating 30
-seconds to failure. What do you do? Suspend to disk.
-
-
-Q: Maybe I'm missing something, but why don't the regular I/O paths work?
-
-A: We do use the regular I/O paths. However we cannot restore the data
-to its original location as we load it. That would create an
-inconsistent kernel state which would certainly result in an oops.
-Instead, we load the image into unused memory and then atomically copy
-it back to it original location. This implies, of course, a maximum
-image size of half the amount of memory.
-
-There are two solutions to this:
-
-* require half of memory to be free during suspend. That way you can
-read "new" data onto free spots, then cli and copy
-
-* assume we had special "polling" ide driver that only uses memory
-between 0-640KB. That way, I'd have to make sure that 0-640KB is free
-during suspending, but otherwise it would work...
-
-suspend2 shares this fundamental limitation, but does not include user
-data and disk caches into "used memory" by saving them in
-advance. That means that the limitation goes away in practice.
-
-Q: Does linux support ACPI S4?
-
-A: Yes. That's what echo platform > /sys/power/disk does.
-
-Q: What is 'suspend2'?
-
-A: suspend2 is 'Software Suspend 2', a forked implementation of
-suspend-to-disk which is available as separate patches for 2.4 and 2.6
-kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB
-highmem and preemption. It also has a extensible architecture that
-allows for arbitrary transformations on the image (compression,
-encryption) and arbitrary backends for writing the image (eg to swap
-or an NFS share[Work In Progress]). Questions regarding suspend2
-should be sent to the mailing list available through the suspend2
-website, and not to the Linux Kernel Mailing List. We are working
-toward merging suspend2 into the mainline kernel.
-
-Q: What is the freezing of tasks and why are we using it?
-
-A: The freezing of tasks is a mechanism by which user space processes and some
-kernel threads are controlled during hibernation or system-wide suspend (on some
-architectures). See freezing-of-tasks.txt for details.
-
-Q: What is the difference between "platform" and "shutdown"?
-
-A:
-
-shutdown: save state in linux, then tell bios to powerdown
-
-platform: save state in linux, then tell bios to powerdown and blink
- "suspended led"
-
-"platform" is actually right thing to do where supported, but
-"shutdown" is most reliable (except on ACPI systems).
-
-Q: I do not understand why you have such strong objections to idea of
-selective suspend.
-
-A: Do selective suspend during runtime power management, that's okay. But
-it's useless for suspend-to-disk. (And I do not see how you could use
-it for suspend-to-ram, I hope you do not want that).
-
-Lets see, so you suggest to
-
-* SUSPEND all but swap device and parents
-* Snapshot
-* Write image to disk
-* SUSPEND swap device and parents
-* Powerdown
-
-Oh no, that does not work, if swap device or its parents uses DMA,
-you've corrupted data. You'd have to do
-
-* SUSPEND all but swap device and parents
-* FREEZE swap device and parents
-* Snapshot
-* UNFREEZE swap device and parents
-* Write
-* SUSPEND swap device and parents
-
-Which means that you still need that FREEZE state, and you get more
-complicated code. (And I have not yet introduce details like system
-devices).
-
-Q: There don't seem to be any generally useful behavioral
-distinctions between SUSPEND and FREEZE.
-
-A: Doing SUSPEND when you are asked to do FREEZE is always correct,
-but it may be unnecessarily slow. If you want your driver to stay simple,
-slowness may not matter to you. It can always be fixed later.
-
-For devices like disk it does matter, you do not want to spindown for
-FREEZE.
-
-Q: After resuming, system is paging heavily, leading to very bad interactivity.
-
-A: Try running
-
-cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file
-do
- test -f "$file" && cat "$file" > /dev/null
-done
-
-after resume. swapoff -a; swapon -a may also be useful.
-
-Q: What happens to devices during swsusp? They seem to be resumed
-during system suspend?
-
-A: That's correct. We need to resume them if we want to write image to
-disk. Whole sequence goes like
-
- Suspend part
- ~~~~~~~~~~~~
- running system, user asks for suspend-to-disk
-
- user processes are stopped
-
- suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
- with state snapshot
-
- state snapshot: copy of whole used memory is taken with interrupts disabled
-
- resume(): devices are woken up so that we can write image to swap
-
- write image to swap
-
- suspend(PMSG_SUSPEND): suspend devices so that we can power off
-
- turn the power off
-
- Resume part
- ~~~~~~~~~~~
- (is actually pretty similar)
-
- running system, user asks for suspend-to-disk
-
- user processes are stopped (in common case there are none, but with resume-from-initrd, no one knows)
-
- read image from disk
-
- suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
- with image restoration
-
- image restoration: rewrite memory with image
-
- resume(): devices are woken up so that system can continue
-
- thaw all user processes
-
-Q: What is this 'Encrypt suspend image' for?
-
-A: First of all: it is not a replacement for dm-crypt encrypted swap.
-It cannot protect your computer while it is suspended. Instead it does
-protect from leaking sensitive data after resume from suspend.
-
-Think of the following: you suspend while an application is running
-that keeps sensitive data in memory. The application itself prevents
-the data from being swapped out. Suspend, however, must write these
-data to swap to be able to resume later on. Without suspend encryption
-your sensitive data are then stored in plaintext on disk. This means
-that after resume your sensitive data are accessible to all
-applications having direct access to the swap device which was used
-for suspend. If you don't need swap after resume these data can remain
-on disk virtually forever. Thus it can happen that your system gets
-broken in weeks later and sensitive data which you thought were
-encrypted and protected are retrieved and stolen from the swap device.
-To prevent this situation you should use 'Encrypt suspend image'.
-
-During suspend a temporary key is created and this key is used to
-encrypt the data written to disk. When, during resume, the data was
-read back into memory the temporary key is destroyed which simply
-means that all data written to disk during suspend are then
-inaccessible so they can't be stolen later on. The only thing that
-you must then take care of is that you call 'mkswap' for the swap
-partition used for suspend as early as possible during regular
-boot. This asserts that any temporary key from an oopsed suspend or
-from a failed or aborted resume is erased from the swap device.
-
-As a rule of thumb use encrypted swap to protect your data while your
-system is shut down or suspended. Additionally use the encrypted
-suspend image to prevent sensitive data from being stolen after
-resume.
-
-Q: Can I suspend to a swap file?
-
-A: Generally, yes, you can. However, it requires you to use the "resume=" and
-"resume_offset=" kernel command line parameters, so the resume from a swap file
-cannot be initiated from an initrd or initramfs image. See
-swsusp-and-swap-files.txt for details.
-
-Q: Is there a maximum system RAM size that is supported by swsusp?
-
-A: It should work okay with highmem.
-
-Q: Does swsusp (to disk) use only one swap partition or can it use
-multiple swap partitions (aggregate them into one logical space)?
-
-A: Only one swap partition, sorry.
-
-Q: If my application(s) causes lots of memory & swap space to be used
-(over half of the total system RAM), is it correct that it is likely
-to be useless to try to suspend to disk while that app is running?
-
-A: No, it should work okay, as long as your app does not mlock()
-it. Just prepare big enough swap partition.
-
-Q: What information is useful for debugging suspend-to-disk problems?
-
-A: Well, last messages on the screen are always useful. If something
-is broken, it is usually some kernel driver, therefore trying with as
-little as possible modules loaded helps a lot. I also prefer people to
-suspend from console, preferably without X running. Booting with
-init=/bin/bash, then swapon and starting suspend sequence manually
-usually does the trick. Then it is good idea to try with latest
-vanilla kernel.
-
-Q: How can distributions ship a swsusp-supporting kernel with modular
-disk drivers (especially SATA)?
-
-A: Well, it can be done, load the drivers, then do echo into
-/sys/power/resume file from initrd. Be sure not to mount
-anything, not even read-only mount, or you are going to lose your
-data.
-
-Q: How do I make suspend more verbose?
-
-A: If you want to see any non-error kernel messages on the virtual
-terminal the kernel switches to during suspend, you have to set the
-kernel console loglevel to at least 4 (KERN_WARNING), for example by
-doing
-
- # save the old loglevel
- read LOGLEVEL DUMMY < /proc/sys/kernel/printk
- # set the loglevel so we see the progress bar.
- # if the level is higher than needed, we leave it alone.
- if [ $LOGLEVEL -lt 5 ]; then
- echo 5 > /proc/sys/kernel/printk
- fi
-
- IMG_SZ=0
- read IMG_SZ < /sys/power/image_size
- echo -n disk > /sys/power/state
- RET=$?
- #
- # the logic here is:
- # if image_size > 0 (without kernel support, IMG_SZ will be zero),
- # then try again with image_size set to zero.
- if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size
- echo 0 > /sys/power/image_size
- echo -n disk > /sys/power/state
- RET=$?
- fi
-
- # restore previous loglevel
- echo $LOGLEVEL > /proc/sys/kernel/printk
- exit $RET
-
-Q: Is this true that if I have a mounted filesystem on a USB device and
-I suspend to disk, I can lose data unless the filesystem has been mounted
-with "sync"?
-
-A: That's right ... if you disconnect that device, you may lose data.
-In fact, even with "-o sync" you can lose data if your programs have
-information in buffers they haven't written out to a disk you disconnect,
-or if you disconnect before the device finished saving data you wrote.
-
-Software suspend normally powers down USB controllers, which is equivalent
-to disconnecting all USB devices attached to your system.
-
-Your system might well support low-power modes for its USB controllers
-while the system is asleep, maintaining the connection, using true sleep
-modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the
-/sys/power/state file; write "standby" or "mem".) We've not seen any
-hardware that can use these modes through software suspend, although in
-theory some systems might support "platform" modes that won't break the
-USB connections.
-
-Remember that it's always a bad idea to unplug a disk drive containing a
-mounted filesystem. That's true even when your system is asleep! The
-safest thing is to unmount all filesystems on removable media (such USB,
-Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
-before suspending; then remount them after resuming.
-
-There is a work-around for this problem. For more information, see
-Documentation/driver-api/usb/persist.rst.
-
-Q: Can I suspend-to-disk using a swap partition under LVM?
-
-A: Yes and No. You can suspend successfully, but the kernel will not be able
-to resume on its own. You need an initramfs that can recognize the resume
-situation, activate the logical volume containing the swap volume (but not
-touch any filesystems!), and eventually call
-
-echo -n "$major:$minor" > /sys/power/resume
-
-where $major and $minor are the respective major and minor device numbers of
-the swap volume.
-
-uswsusp works with LVM, too. See http://suspend.sourceforge.net/
-
-Q: I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were
-compiled with the similar configuration files. Anyway I found that
-suspend to disk (and resume) is much slower on 2.6.16 compared to
-2.6.15. Any idea for why that might happen or how can I speed it up?
-
-A: This is because the size of the suspend image is now greater than
-for 2.6.15 (by saving more data we can get more responsive system
-after resume).
-
-There's the /sys/power/image_size knob that controls the size of the
-image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as
-root), the 2.6.15 behavior should be restored. If it is still too
-slow, take a look at suspend.sf.net -- userland suspend is faster and
-supports LZF compression to speed it up further.
diff --git a/Documentation/power/tricks.txt b/Documentation/power/tricks.rst
similarity index 93%
rename from Documentation/power/tricks.txt
rename to Documentation/power/tricks.rst
index a1b8f7249f4c..ca787f142c3f 100644
--- a/Documentation/power/tricks.txt
+++ b/Documentation/power/tricks.rst
@@ -1,5 +1,7 @@
- swsusp/S3 tricks
- ~~~~~~~~~~~~~~~~
+================
+swsusp/S3 tricks
+================
+
Pavel Machek <pavel@ucw.cz>
If you want to trick swsusp/S3 into working, you might want to try:
diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.rst
similarity index 85%
rename from Documentation/power/userland-swsusp.txt
rename to Documentation/power/userland-swsusp.rst
index bbfcd1bbedc5..a0fa51bb1a4d 100644
--- a/Documentation/power/userland-swsusp.txt
+++ b/Documentation/power/userland-swsusp.rst
@@ -1,4 +1,7 @@
+=====================================================
Documentation for userland software suspend interface
+=====================================================
+
(C) 2006 Rafael J. Wysocki <rjw@sisk.pl>
First, the warnings at the beginning of swsusp.txt still apply.
@@ -30,13 +33,16 @@ called.
The ioctl() commands recognized by the device are:
-SNAPSHOT_FREEZE - freeze user space processes (the current process is
+SNAPSHOT_FREEZE
+ freeze user space processes (the current process is
not frozen); this is required for SNAPSHOT_CREATE_IMAGE
and SNAPSHOT_ATOMIC_RESTORE to succeed
-SNAPSHOT_UNFREEZE - thaw user space processes frozen by SNAPSHOT_FREEZE
+SNAPSHOT_UNFREEZE
+ thaw user space processes frozen by SNAPSHOT_FREEZE
-SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
+SNAPSHOT_CREATE_IMAGE
+ create a snapshot of the system memory; the
last argument of ioctl() should be a pointer to an int variable,
the value of which will indicate whether the call returned after
creating the snapshot (1) or after restoring the system memory state
@@ -45,48 +51,59 @@ SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
has been created the read() operation can be used to transfer
it out of the kernel
-SNAPSHOT_ATOMIC_RESTORE - restore the system memory state from the
+SNAPSHOT_ATOMIC_RESTORE
+ restore the system memory state from the
uploaded snapshot image; before calling it you should transfer
the system memory snapshot back to the kernel using the write()
operation; this call will not succeed if the snapshot
image is not available to the kernel
-SNAPSHOT_FREE - free memory allocated for the snapshot image
+SNAPSHOT_FREE
+ free memory allocated for the snapshot image
-SNAPSHOT_PREF_IMAGE_SIZE - set the preferred maximum size of the image
+SNAPSHOT_PREF_IMAGE_SIZE
+ set the preferred maximum size of the image
(the kernel will do its best to ensure the image size will not exceed
this number, but if it turns out to be impossible, the kernel will
create the smallest image possible)
-SNAPSHOT_GET_IMAGE_SIZE - return the actual size of the hibernation image
+SNAPSHOT_GET_IMAGE_SIZE
+ return the actual size of the hibernation image
-SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the
+SNAPSHOT_AVAIL_SWAP_SIZE
+ return the amount of available swap in bytes (the
last argument should be a pointer to an unsigned int variable that will
contain the result if the call is successful).
-SNAPSHOT_ALLOC_SWAP_PAGE - allocate a swap page from the resume partition
+SNAPSHOT_ALLOC_SWAP_PAGE
+ allocate a swap page from the resume partition
(the last argument should be a pointer to a loff_t variable that
will contain the swap page offset if the call is successful)
-SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated by
+SNAPSHOT_FREE_SWAP_PAGES
+ free all swap pages allocated by
SNAPSHOT_ALLOC_SWAP_PAGE
-SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
+SNAPSHOT_SET_SWAP_AREA
+ set the resume partition and the offset (in <PAGE_SIZE>
units) from the beginning of the partition at which the swap header is
located (the last ioctl() argument should point to a struct
resume_swap_area, as defined in kernel/power/suspend_ioctls.h,
containing the resume device specification and the offset); for swap
partitions the offset is always 0, but it is different from zero for
- swap files (see Documentation/power/swsusp-and-swap-files.txt for
+ swap files (see Documentation/power/swsusp-and-swap-files.rst for
details).
-SNAPSHOT_PLATFORM_SUPPORT - enable/disable the hibernation platform support,
+SNAPSHOT_PLATFORM_SUPPORT
+ enable/disable the hibernation platform support,
depending on the argument value (enable, if the argument is nonzero)
-SNAPSHOT_POWER_OFF - make the kernel transition the system to the hibernation
+SNAPSHOT_POWER_OFF
+ make the kernel transition the system to the hibernation
state (eg. ACPI S4) using the platform (eg. ACPI) driver
-SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
+SNAPSHOT_S2RAM
+ suspend to RAM; using this call causes the kernel to
immediately enter the suspend-to-RAM state, so this call must always
be preceded by the SNAPSHOT_FREEZE call and it is also necessary
to use the SNAPSHOT_UNFREEZE call after the system wakes up. This call
@@ -98,10 +115,11 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
The device's read() operation can be used to transfer the snapshot image from
the kernel. It has the following limitations:
+
- you cannot read() more than one virtual memory page at a time
- read()s across page boundaries are impossible (ie. if you read() 1/2 of
- a page in the previous call, you will only be able to read()
- _at_ _most_ 1/2 of the page in the next call)
+ a page in the previous call, you will only be able to read()
+ **at most** 1/2 of the page in the next call)
The device's write() operation is used for uploading the system memory snapshot
into the kernel. It has the same limitations as the read() operation.
@@ -143,8 +161,10 @@ preferably using mlockall(), before calling SNAPSHOT_FREEZE.
The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE
in the memory location pointed to by the last argument of ioctl() and proceed
in accordance with it:
+
1. If the value is 1 (ie. the system memory snapshot has just been
created and the system is ready for saving it):
+
(a) The suspending utility MUST NOT close the snapshot device
_unless_ the whole suspend procedure is to be cancelled, in
which case, if the snapshot image has already been saved, the
@@ -158,6 +178,7 @@ in accordance with it:
called. However, it MAY mount a file system that was not
mounted at that time and perform some operations on it (eg.
use it for saving the image).
+
2. If the value is 0 (ie. the system state has just been restored from
the snapshot image), the suspending utility MUST close the snapshot
device. Afterwards it will be treated as a regular userland process,
diff --git a/Documentation/power/video.txt b/Documentation/power/video.rst
similarity index 56%
rename from Documentation/power/video.txt
rename to Documentation/power/video.rst
index 3e6272bc4472..337a2ba9f32f 100644
--- a/Documentation/power/video.txt
+++ b/Documentation/power/video.rst
@@ -1,7 +1,8 @@
+===========================
+Video issues with S3 resume
+===========================
- Video issues with S3 resume
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 2003-2006, Pavel Machek
+2003-2006, Pavel Machek
During S3 resume, hardware needs to be reinitialized. For most
devices, this is easy, and kernel driver knows how to do
@@ -41,37 +42,37 @@ There are a few types of systems where video works after S3 resume:
(1) systems where video state is preserved over S3.
(2) systems where it is possible to call the video BIOS during S3
- resume. Unfortunately, it is not correct to call the video BIOS at
- that point, but it happens to work on some machines. Use
- acpi_sleep=s3_bios.
+ resume. Unfortunately, it is not correct to call the video BIOS at
+ that point, but it happens to work on some machines. Use
+ acpi_sleep=s3_bios.
(3) systems that initialize video card into vga text mode and where
- the BIOS works well enough to be able to set video mode. Use
- acpi_sleep=s3_mode on these.
+ the BIOS works well enough to be able to set video mode. Use
+ acpi_sleep=s3_mode on these.
(4) on some systems s3_bios kicks video into text mode, and
- acpi_sleep=s3_bios,s3_mode is needed.
+ acpi_sleep=s3_bios,s3_mode is needed.
(5) radeon systems, where X can soft-boot your video card. You'll need
- a new enough X, and a plain text console (no vesafb or radeonfb). See
- http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information.
- Alternatively, you should use vbetool (6) instead.
+ a new enough X, and a plain text console (no vesafb or radeonfb). See
+ http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information.
+ Alternatively, you should use vbetool (6) instead.
(6) other radeon systems, where vbetool is enough to bring system back
- to life. It needs text console to be working. Do vbetool vbestate
- save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool
- vbestate restore < /tmp/delme; setfont <whatever>, and your video
- should work.
+ to life. It needs text console to be working. Do vbetool vbestate
+ save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool
+ vbestate restore < /tmp/delme; setfont <whatever>, and your video
+ should work.
(7) on some systems, it is possible to boot most of kernel, and then
- POSTing bios works. Ole Rohne has patch to do just that at
- http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2.
+ POSTing bios works. Ole Rohne has patch to do just that at
+ http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2.
-(8) on some systems, you can use the video_post utility and or
- do echo 3 > /sys/power/state && /usr/sbin/video_post - which will
- initialize the display in console mode. If you are in X, you can switch
- to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get
- the display working in graphical mode again.
+(8) on some systems, you can use the video_post utility and or
+ do echo 3 > /sys/power/state && /usr/sbin/video_post - which will
+ initialize the display in console mode. If you are in X, you can switch
+ to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get
+ the display working in graphical mode again.
Now, if you pass acpi_sleep=something, and it does not work with your
bios, you'll get a hard crash during resume. Be careful. Also it is
@@ -87,99 +88,126 @@ chance of working.
Table of known working notebooks:
+
+=============================== ===============================================
Model hack (or "how to do it")
-------------------------------------------------------------------------------
+=============================== ===============================================
Acer Aspire 1406LC ole's late BIOS init (7), turn off DRI
Acer TM 230 s3_bios (2)
Acer TM 242FX vbetool (6)
Acer TM C110 video_post (8)
-Acer TM C300 vga=normal (only suspend on console, not in X), vbetool (6) or video_post (8)
+Acer TM C300 vga=normal (only suspend on console, not in X),
+ vbetool (6) or video_post (8)
Acer TM 4052LCi s3_bios (2)
Acer TM 636Lci s3_bios,s3_mode (4)
-Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text console back
-Acer TM 660 ??? (*)
-Acer TM 800 vga=normal, X patches, see webpage (5) or vbetool (6)
-Acer TM 803 vga=normal, X patches, see webpage (5) or vbetool (6)
+Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text
+ console back
+Acer TM 660 ??? [#f1]_
+Acer TM 800 vga=normal, X patches, see webpage (5)
+ or vbetool (6)
+Acer TM 803 vga=normal, X patches, see webpage (5)
+ or vbetool (6)
Acer TM 803LCi vga=normal, vbetool (6)
Arima W730a vbetool needed (6)
-Asus L2400D s3_mode (3)(***) (S1 also works OK)
+Asus L2400D s3_mode (3) [#f2]_ (S1 also works OK)
Asus L3350M (SiS 740) (6)
Asus L3800C (Radeon M7) s3_bios (2) (S1 also works OK)
-Asus M6887Ne vga=normal, s3_bios (2), use radeon driver instead of fglrx in x.org
+Asus M6887Ne vga=normal, s3_bios (2), use radeon driver
+ instead of fglrx in x.org
Athlon64 desktop prototype s3_bios (2)
-Compal CL-50 ??? (*)
+Compal CL-50 ??? [#f1]_
Compaq Armada E500 - P3-700 none (1) (S1 also works OK)
Compaq Evo N620c vga=normal, s3_bios (2)
Dell 600m, ATI R250 Lf none (1), but needs xorg-x11-6.8.1.902-1
Dell D600, ATI RV250 vga=normal and X, or try vbestate (6)
-Dell D610 vga=normal and X (possibly vbestate (6) too, but not tested)
-Dell Inspiron 4000 ??? (*)
-Dell Inspiron 500m ??? (*)
+Dell D610 vga=normal and X (possibly vbestate (6) too,
+ but not tested)
+Dell Inspiron 4000 ??? [#f1]_
+Dell Inspiron 500m ??? [#f1]_
Dell Inspiron 510m ???
Dell Inspiron 5150 vbetool needed (6)
-Dell Inspiron 600m ??? (*)
-Dell Inspiron 8200 ??? (*)
-Dell Inspiron 8500 ??? (*)
-Dell Inspiron 8600 ??? (*)
-eMachines athlon64 machines vbetool needed (6) (someone please get me model #s)
-HP NC6000 s3_bios, may not use radeonfb (2); or vbetool (6)
-HP NX7000 ??? (*)
-HP Pavilion ZD7000 vbetool post needed, need open-source nv driver for X
+Dell Inspiron 600m ??? [#f1]_
+Dell Inspiron 8200 ??? [#f1]_
+Dell Inspiron 8500 ??? [#f1]_
+Dell Inspiron 8600 ??? [#f1]_
+eMachines athlon64 machines vbetool needed (6) (someone please get
+ me model #s)
+HP NC6000 s3_bios, may not use radeonfb (2);
+ or vbetool (6)
+HP NX7000 ??? [#f1]_
+HP Pavilion ZD7000 vbetool post needed, need open-source nv
+ driver for X
HP Omnibook XE3 athlon version none (1)
HP Omnibook XE3GC none (1), video is S3 Savage/IX-MV
HP Omnibook XE3L-GF vbetool (6)
HP Omnibook 5150 none (1), (S1 also works OK)
-IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294 Savage/IX-MV, vesafb gets "interesting" but X work.
-IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with BIOS 1.04 2002-08-23, but not at all with BIOS 1.11 2004-11-05 :-(]
+IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294
+ Savage/IX-MV, vesafb gets "interesting"
+ but X work.
+IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with
+ BIOS 1.04 2002-08-23, but not at all with
+ BIOS 1.11 2004-11-05 :-(]
IBM TP R32 / Type 2658-MMG none (1)
-IBM TP R40 2722B3G ??? (*)
+IBM TP R40 2722B3G ??? [#f1]_
IBM TP R50p / Type 1832-22U s3_bios (2)
IBM TP R51 none (1)
-IBM TP T30 236681A ??? (*)
+IBM TP T30 236681A ??? [#f1]_
IBM TP T40 / Type 2373-MU4 none (1)
IBM TP T40p none (1)
IBM TP R40p s3_bios (2)
IBM TP T41p s3_bios (2), switch to X after resume
IBM TP T42 s3_bios (2)
IBM ThinkPad T42p (2373-GTG) s3_bios (2)
-IBM TP X20 ??? (*)
+IBM TP X20 ??? [#f1]_
IBM TP X30 s3_bios, s3_mode (4)
-IBM TP X31 / Type 2672-XXH none (1), use radeontool (http://fdd.com/software/radeon/) to turn off backlight.
-IBM TP X32 none (1), but backlight is on and video is trashed after long suspend. s3_bios,s3_mode (4) works too. Perhaps that gets better results?
+IBM TP X31 / Type 2672-XXH none (1), use radeontool
+ (http://fdd.com/software/radeon/) to
+ turn off backlight.
+IBM TP X32 none (1), but backlight is on and video is
+ trashed after long suspend. s3_bios,
+ s3_mode (4) works too. Perhaps that gets
+ better results?
IBM Thinkpad X40 Type 2371-7JG s3_bios,s3_mode (4)
-IBM TP 600e none(1), but a switch to console and back to X is needed
-Medion MD4220 ??? (*)
+IBM TP 600e none(1), but a switch to console and
+ back to X is needed
+Medion MD4220 ??? [#f1]_
Samsung P35 vbetool needed (6)
Sharp PC-AR10 (ATI rage) none (1), backlight does not switch off
Sony Vaio PCG-C1VRX/K s3_bios (2)
-Sony Vaio PCG-F403 ??? (*)
+Sony Vaio PCG-F403 ??? [#f1]_
Sony Vaio PCG-GRT995MP none (1), works with 'nv' X driver
-Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use radeontool (http://fdd.com/software/radeon/) to turn off backlight.
-Sony Vaio PCG-N505SN ??? (*)
+Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use
+ radeontool (http://fdd.com/software/radeon/)
+ to turn off backlight.
+Sony Vaio PCG-N505SN ??? [#f1]_
Sony Vaio vgn-s260 X or boot-radeon can init it (5)
-Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will be blank unless you return to X.
+Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will
+ be blank unless you return to X.
Sony Vaio vgn-FS115B s3_bios (2),s3_mode (4)
Toshiba Libretto L5 none (1)
Toshiba Libretto 100CT/110CT vbetool (6)
Toshiba Portege 3020CT s3_mode (3)
Toshiba Satellite 4030CDT s3_mode (3) (S1 also works OK)
Toshiba Satellite 4080XCDT s3_mode (3) (S1 also works OK)
-Toshiba Satellite 4090XCDT ??? (*)
-Toshiba Satellite P10-554 s3_bios,s3_mode (4)(****)
+Toshiba Satellite 4090XCDT ??? [#f1]_
+Toshiba Satellite P10-554 s3_bios,s3_mode (4)[#f3]_
Toshiba M30 (2) xor X with nvidia driver using internal AGP
-Uniwill 244IIO ??? (*)
+Uniwill 244IIO ??? [#f1]_
+=============================== ===============================================
Known working desktop systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================== ============================= ========================
Mainboard Graphics card hack (or "how to do it")
-------------------------------------------------------------------------------
+=================== ============================= ========================
Asus A7V8X nVidia RIVA TNT2 model 64 s3_bios,s3_mode (4)
+=================== ============================= ========================
-(*) from https://wiki.ubuntu.com/HoaryPMResults, not sure
- which options to use. If you know, please tell me.
+.. [#f1] from https://wiki.ubuntu.com/HoaryPMResults, not sure
+ which options to use. If you know, please tell me.
-(***) To be tested with a newer kernel.
+.. [#f2] To be tested with a newer kernel.
-(****) Not with SMP kernel, UP only.
+.. [#f3] Not with SMP kernel, UP only.
diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
index 58bc047e7b95..1acaa14903d6 100644
--- a/Documentation/process/submitting-drivers.rst
+++ b/Documentation/process/submitting-drivers.rst
@@ -117,7 +117,7 @@ PM support:
implemented") error. You should also try to make sure that your
driver uses as little power as possible when it's not doing
anything. For the driver testing instructions see
- Documentation/power/drivers-testing.txt and for a relatively
+ Documentation/power/drivers-testing.rst and for a relatively
complete overview of the power management issues related to
drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`.
diff --git a/Documentation/scheduler/sched-energy.txt b/Documentation/scheduler/sched-energy.txt
index 197d81f4b836..d97207b9accb 100644
--- a/Documentation/scheduler/sched-energy.txt
+++ b/Documentation/scheduler/sched-energy.txt
@@ -22,7 +22,7 @@ the highest.
The actual EM used by EAS is _not_ maintained by the scheduler, but by a
dedicated framework. For details about this framework and what it provides,
-please refer to its documentation (see Documentation/power/energy-model.txt).
+please refer to its documentation (see Documentation/power/energy-model.rst).
2. Background and Terminology
@@ -81,7 +81,7 @@ through the arch_scale_cpu_capacity() callback.
The rest of platform knowledge used by EAS is directly read from the Energy
Model (EM) framework. The EM of a platform is composed of a power cost table
-per 'performance domain' in the system (see Documentation/power/energy-model.txt
+per 'performance domain' in the system (see Documentation/power/energy-model.rst
for futher details about performance domains).
The scheduler manages references to the EM objects in the topology code when the
@@ -352,7 +352,7 @@ could be amended in the future if proven otherwise.
EAS uses the EM of a platform to estimate the impact of scheduling decisions on
energy. So, your platform must provide power cost tables to the EM framework in
order to make EAS start. To do so, please refer to documentation of the
-independent EM framework in Documentation/power/energy-model.txt.
+independent EM framework in Documentation/power/energy-model.rst.
Please also note that the scheduling domains need to be re-built after the
EM has been registered in order to start EAS.
diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt
index f07e38094b40..1a660a39e3c0 100644
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ b/Documentation/trace/coresight-cpu-debug.txt
@@ -151,7 +151,7 @@ At the runtime you can disable idle states with below methods:
It is possible to disable CPU idle states by way of the PM QoS
subsystem, more specifically by using the "/dev/cpu_dma_latency"
-interface (see Documentation/power/pm_qos_interface.txt for more
+interface (see Documentation/power/pm_qos_interface.rst for more
details). As specified in the PM QoS documentation the requested
parameter will stay in effect until the file descriptor is released.
For example:
diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst
index 72c6cd935821..f1c3906c69a8 100644
--- a/Documentation/translations/zh_CN/process/submitting-drivers.rst
+++ b/Documentation/translations/zh_CN/process/submitting-drivers.rst
@@ -97,7 +97,7 @@ Linux 2.6:
函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确
保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动
程序测试的指导，请参阅
- Documentation/power/drivers-testing.txt。有关驱动程序电
+ Documentation/power/drivers-testing.rst。有关驱动程序电
源管理问题相对全面的概述，请参阅
Documentation/driver-api/pm/devices.rst。
diff --git a/MAINTAINERS b/MAINTAINERS
index 5fdbf6e78d46..1c9ed0a5a9df 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6491,7 +6491,7 @@ M: "Rafael J. Wysocki" <rjw@rjwysocki.net>
M: Pavel Machek <pavel@ucw.cz>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/power/freezing-of-tasks.txt
+F: Documentation/power/freezing-of-tasks.rst
F: include/linux/freezer.h
F: kernel/freezer.c
@@ -11825,7 +11825,7 @@ S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/vireshk/pm.git
F: drivers/opp/
F: include/linux/pm_opp.h
-F: Documentation/power/opp.txt
+F: Documentation/power/opp.rst
F: Documentation/devicetree/bindings/opp/
OPL4 DRIVER
diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
index a109141a8d3b..bc5e1c218d4d 100644
--- a/arch/x86/Kconfig
+++ b/arch/x86/Kconfig
@@ -2448,7 +2448,7 @@ menuconfig APM
machines with more than one CPU.
In order to use APM, you will need supporting software. For location
- and more information, read <file:Documentation/power/apm-acpi.txt>
+ and more information, read <file:Documentation/power/apm-acpi.rst>
and the Battery Powered Linux mini-HOWTO, available from
<http://www.tldp.org/docs.html#howto>.
diff --git a/drivers/gpu/drm/i915/i915_drv.h b/drivers/gpu/drm/i915/i915_drv.h
index 0ea7f78ae227..eeb7edfa3597 100644
--- a/drivers/gpu/drm/i915/i915_drv.h
+++ b/drivers/gpu/drm/i915/i915_drv.h
@@ -1069,7 +1069,7 @@ struct skl_wm_params {
* to be disabled. This shouldn't happen and we'll print some error messages in
* case it happens.
*
- * For more, read the Documentation/power/runtime_pm.txt.
+ * For more, read the Documentation/power/runtime_pm.rst.
*/
struct i915_runtime_pm {
atomic_t wakeref_count;
diff --git a/drivers/opp/Kconfig b/drivers/opp/Kconfig
index fe54d349d2e1..35dfc7e80f92 100644
--- a/drivers/opp/Kconfig
+++ b/drivers/opp/Kconfig
@@ -11,4 +11,4 @@ config PM_OPP
OPP layer organizes the data internally using device pointers
representing individual voltage domains and provides SOC
implementations a ready to use framework to manage OPPs.
- For more information, read <file:Documentation/power/opp.txt>
+ For more information, read <file:Documentation/power/opp.rst>
diff --git a/drivers/power/supply/power_supply_core.c b/drivers/power/supply/power_supply_core.c
index 136e8f64848a..b55cdfe22a2e 100644
--- a/drivers/power/supply/power_supply_core.c
+++ b/drivers/power/supply/power_supply_core.c
@@ -606,7 +606,7 @@ int power_supply_get_battery_info(struct power_supply *psy,
/* The property and field names below must correspond to elements
* in enum power_supply_property. For reasoning, see
- * Documentation/power/power_supply_class.txt.
+ * Documentation/power/power_supply_class.rst.
*/
of_property_read_u32(battery_np, "energy-full-design-microwatt-hours",
diff --git a/include/linux/interrupt.h b/include/linux/interrupt.h
index c7eef32e7739..5b8328a99b2a 100644
--- a/include/linux/interrupt.h
+++ b/include/linux/interrupt.h
@@ -52,7 +52,7 @@
* irq line disabled until the threaded handler has been run.
* IRQF_NO_SUSPEND - Do not disable this IRQ during suspend. Does not guarantee
* that this interrupt will wake the system from a suspended
- * state. See Documentation/power/suspend-and-interrupts.txt
+ * state. See Documentation/power/suspend-and-interrupts.rst
* IRQF_FORCE_RESUME - Force enable it on resume even if IRQF_NO_SUSPEND is set
* IRQF_NO_THREAD - Interrupt cannot be threaded
* IRQF_EARLY_RESUME - Resume IRQ early during syscore instead of at device
diff --git a/include/linux/pci.h b/include/linux/pci.h
index 44d254548ca7..41c5673aba2f 100644
--- a/include/linux/pci.h
+++ b/include/linux/pci.h
@@ -808,7 +808,7 @@ struct module;
* @suspend_late: Put device into low power state.
* @resume_early: Wake device from low power state.
* @resume: Wake device from low power state.
- * (Please see Documentation/power/pci.txt for descriptions
+ * (Please see Documentation/power/pci.rst for descriptions
* of PCI Power Management and the related functions.)
* @shutdown: Hook into reboot_notifier_list (kernel/sys.c).
* Intended to stop any idling DMA operations.
diff --git a/include/linux/pm.h b/include/linux/pm.h
index 345d74a727e3..220e2008467d 100644
--- a/include/linux/pm.h
+++ b/include/linux/pm.h
@@ -271,7 +271,7 @@ typedef struct pm_message {
* actions to be performed by a device driver's callbacks generally depend on
* the platform and subsystem the device belongs to.
*
- * Refer to Documentation/power/runtime_pm.txt for more information about the
+ * Refer to Documentation/power/runtime_pm.rst for more information about the
* role of the @runtime_suspend(), @runtime_resume() and @runtime_idle()
* callbacks in device runtime power management.
*/
diff --git a/kernel/power/Kconfig b/kernel/power/Kconfig
index ff8592ddedee..d3667b4075c1 100644
--- a/kernel/power/Kconfig
+++ b/kernel/power/Kconfig
@@ -66,7 +66,7 @@ config HIBERNATION
need to run mkswap against the swap partition used for the suspend.
It also works with swap files to a limited extent (for details see
- <file:Documentation/power/swsusp-and-swap-files.txt>).
+ <file:Documentation/power/swsusp-and-swap-files.rst>).
Right now you may boot without resuming and resume later but in the
meantime you cannot use the swap partition(s)/file(s) involved in
@@ -75,7 +75,7 @@ config HIBERNATION
MOUNT any journaled filesystems mounted before the suspend or they
will get corrupted in a nasty way.
- For more information take a look at <file:Documentation/power/swsusp.txt>.
+ For more information take a look at <file:Documentation/power/swsusp.rst>.
config ARCH_SAVE_PAGE_KEYS
bool
@@ -256,7 +256,7 @@ config APM_EMULATION
notification of APM "events" (e.g. battery status change).
In order to use APM, you will need supporting software. For location
- and more information, read <file:Documentation/power/apm-acpi.txt>
+ and more information, read <file:Documentation/power/apm-acpi.rst>
and the Battery Powered Linux mini-HOWTO, available from
<http://www.tldp.org/docs.html#howto>.
diff --git a/net/wireless/Kconfig b/net/wireless/Kconfig
index 6310ddede220..cc70f5932773 100644
--- a/net/wireless/Kconfig
+++ b/net/wireless/Kconfig
@@ -166,7 +166,7 @@ config CFG80211_DEFAULT_PS
If this causes your applications to misbehave you should fix your
applications instead -- they need to register their network
- latency requirement, see Documentation/power/pm_qos_interface.txt.
+ latency requirement, see Documentation/power/pm_qos_interface.rst.
config CFG80211_DEBUGFS
bool "cfg80211 DebugFS entries"
--
2.21.0
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst
2019-06-12 17:52 ` [PATCH v4 18/28] docs: " Mauro Carvalho Chehab
@ 2019-06-13 0:25 ` Srivatsa S. Bhat
2019-06-13 9:58 ` Mauro Carvalho Chehab
2019-06-13 10:10 ` [PATCH v5] docs: power: " Mauro Carvalho Chehab
[not found] ` <fac44e1fbab5ea755a93601a4fdfa34fcc57ae9e.1560361364.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
1 sibling, 2 replies; 12+ messages in thread
From: Srivatsa S. Bhat @ 2019-06-13 0:25 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List
Cc: Nishanth Menon, linux-wireless, David Airlie, Viresh Kumar,
Joonas Lahtinen, dri-devel, Sebastian Reichel, Harry Wei,
Pavel Machek, H. Peter Anvin, Alex Shi, Jonathan Corbet, x86,
Ingo Molnar, linux-pci, Len Brown, Suzuki K Poulose, intel-gfx,
Jani Nikula, Mauro Carvalho Chehab, Mark Brown, Borislav Petkov,
Rodrigo Vivi, Bjorn Helgaas, Thomas Gleixner, linux-a
On 6/12/19 10:52 AM, Mauro Carvalho Chehab wrote:
> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> Acked-by: Mark Brown <broonie@kernel.org>
> ---
[...]
> diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst
> similarity index 90%
> rename from Documentation/power/suspend-and-cpuhotplug.txt
> rename to Documentation/power/suspend-and-cpuhotplug.rst
> index a8751b8df10e..9df664f5423a 100644
> --- a/Documentation/power/suspend-and-cpuhotplug.txt
> +++ b/Documentation/power/suspend-and-cpuhotplug.rst
> @@ -1,10 +1,15 @@
> +====================================================================
> Interaction of Suspend code (S3) with the CPU hotplug infrastructure
> +====================================================================
>
> - (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
> +(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
>
>
> -I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> - infrastructure uses it internally? And where do they share common code?
> +I. Differences between CPU hotplug and Suspend-to-RAM
> +======================================================
> +
> +How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> +infrastructure uses it internally? And where do they share common code?
>
> Well, a picture is worth a thousand words... So ASCII art follows :-)
>
[...]
> @@ -101,7 +108,7 @@ execution during resume):
>
> It is to be noted here that the system_transition_mutex lock is acquired at the very
> beginning, when we are just starting out to suspend, and then released only
> -after the entire cycle is complete (i.e., suspend + resume).
> +after the entire cycle is complete (i.e., suspend + resume)::
>
I think that should be a period, not a colon, because it is clarifying
the text above it (as opposed to referring to the example below it).
Other than that, for suspend-and-cpuhotplug.txt:
Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
Regards,
Srivatsa
VMware Photon OS
^ permalink raw reply [flat|nested] 12+ messages in thread* Re: [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst
2019-06-13 0:25 ` Srivatsa S. Bhat
@ 2019-06-13 9:58 ` Mauro Carvalho Chehab
2019-06-13 10:10 ` [PATCH v5] docs: power: " Mauro Carvalho Chehab
1 sibling, 0 replies; 12+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-13 9:58 UTC (permalink / raw)
To: Srivatsa S. Bhat
Cc: Nishanth Menon, linux-wireless, Linux Doc Mailing List,
David Airlie, Viresh Kumar, Joonas Lahtinen, dri-devel,
linux-kernel, Harry Wei, Pavel Machek, H. Peter Anvin, Alex Shi,
Jonathan Corbet, x86, Ingo Molnar, linux-pci, Len Brown,
Suzuki K Poulose, intel-gfx, Jani Nikula, Mauro Carvalho Chehab,
Mark Brown, Borislav Petkov, Rodrigo Vivi, Bjorn Helgaas
Em Wed, 12 Jun 2019 17:25:39 -0700
"Srivatsa S. Bhat" <srivatsa@csail.mit.edu> escreveu:
> On 6/12/19 10:52 AM, Mauro Carvalho Chehab wrote:
> > Convert the PM documents to ReST, in order to allow them to
> > build with Sphinx.
> >
> > The conversion is actually:
> > - add blank lines and identation in order to identify paragraphs;
> > - fix tables markups;
> > - add some lists markups;
> > - mark literal blocks;
> > - adjust title markups.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> > Acked-by: Mark Brown <broonie@kernel.org>
> > ---
>
> [...]
>
> > diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst
> > similarity index 90%
> > rename from Documentation/power/suspend-and-cpuhotplug.txt
> > rename to Documentation/power/suspend-and-cpuhotplug.rst
> > index a8751b8df10e..9df664f5423a 100644
> > --- a/Documentation/power/suspend-and-cpuhotplug.txt
> > +++ b/Documentation/power/suspend-and-cpuhotplug.rst
> > @@ -1,10 +1,15 @@
> > +====================================================================
> > Interaction of Suspend code (S3) with the CPU hotplug infrastructure
> > +====================================================================
> >
> > - (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
> > +(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
> >
> >
> > -I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> > - infrastructure uses it internally? And where do they share common code?
> > +I. Differences between CPU hotplug and Suspend-to-RAM
> > +======================================================
> > +
> > +How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> > +infrastructure uses it internally? And where do they share common code?
> >
> > Well, a picture is worth a thousand words... So ASCII art follows :-)
> >
>
> [...]
>
> > @@ -101,7 +108,7 @@ execution during resume):
> >
> > It is to be noted here that the system_transition_mutex lock is acquired at the very
> > beginning, when we are just starting out to suspend, and then released only
> > -after the entire cycle is complete (i.e., suspend + resume).
> > +after the entire cycle is complete (i.e., suspend + resume)::
> >
>
> I think that should be a period, not a colon, because it is clarifying
> the text above it (as opposed to referring to the example below it).
>
> Other than that, for suspend-and-cpuhotplug.txt:
>
> Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
Ah, ok. I'll change it to:
after the entire cycle is complete (i.e., suspend + resume).
::
and add your acked-by.
>
> Regards,
> Srivatsa
> VMware Photon OS
Thanks,
Mauro
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH v5] docs: power: convert docs to ReST and rename to *.rst
2019-06-13 0:25 ` Srivatsa S. Bhat
2019-06-13 9:58 ` Mauro Carvalho Chehab
@ 2019-06-13 10:10 ` Mauro Carvalho Chehab
2019-06-14 20:36 ` Jonathan Corbet
1 sibling, 1 reply; 12+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-13 10:10 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Nishanth Menon, linux-wireless, David Airlie, Viresh Kumar,
dri-devel, Sebastian Reichel, Harry Wei, Pavel Machek,
H. Peter Anvin, Mauro Carvalho Chehab, Alex Shi,
Srivatsa S . Bhat, Jonathan Corbet, x86, Ingo Molnar, linux-pci,
Len Brown, Suzuki K Poulose, intel-gfx, Mauro Carvalho Chehab,
Mark Brown, Borislav Petkov, Bjorn Helgaas, Thomas Gleixner,
linux-arm-kernel, Mat
Convert the PM documents to ReST, in order to allow them to
build with Sphinx.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- fix tables markups;
- add some lists markups;
- mark literal blocks;
- adjust title markups.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Bjorn Helgaas <bhelgaas@google.com>
Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
---
.../ABI/testing/sysfs-class-powercap | 2 +-
.../admin-guide/kernel-parameters.txt | 6 +-
Documentation/cpu-freq/core.txt | 2 +-
Documentation/driver-api/pm/devices.rst | 6 +-
.../driver-api/usb/power-management.rst | 2 +-
.../power/{apm-acpi.txt => apm-acpi.rst} | 10 +-
...m-debugging.txt => basic-pm-debugging.rst} | 79 +--
...harger-manager.txt => charger-manager.rst} | 101 ++--
...rivers-testing.txt => drivers-testing.rst} | 15 +-
.../{energy-model.txt => energy-model.rst} | 101 ++--
...ing-of-tasks.txt => freezing-of-tasks.rst} | 91 ++--
Documentation/power/index.rst | 46 ++
.../power/{interface.txt => interface.rst} | 24 +-
Documentation/power/{opp.txt => opp.rst} | 175 +++---
Documentation/power/{pci.txt => pci.rst} | 87 ++-
...qos_interface.txt => pm_qos_interface.rst} | 127 +++--
Documentation/power/power_supply_class.rst | 282 ++++++++++
Documentation/power/power_supply_class.txt | 231 --------
Documentation/power/powercap/powercap.rst | 257 +++++++++
Documentation/power/powercap/powercap.txt | 236 ---------
.../regulator/{consumer.txt => consumer.rst} | 141 ++---
.../regulator/{design.txt => design.rst} | 9 +-
.../regulator/{machine.txt => machine.rst} | 47 +-
.../regulator/{overview.txt => overview.rst} | 57 +-
Documentation/power/regulator/regulator.rst | 32 ++
Documentation/power/regulator/regulator.txt | 30 --
.../power/{runtime_pm.txt => runtime_pm.rst} | 234 ++++----
Documentation/power/{s2ram.txt => s2ram.rst} | 20 +-
...hotplug.txt => suspend-and-cpuhotplug.rst} | 42 +-
...errupts.txt => suspend-and-interrupts.rst} | 2 +
...ap-files.txt => swsusp-and-swap-files.rst} | 17 +-
...{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} | 120 ++---
Documentation/power/swsusp.rst | 501 ++++++++++++++++++
Documentation/power/swsusp.txt | 446 ----------------
.../power/{tricks.txt => tricks.rst} | 6 +-
...serland-swsusp.txt => userland-swsusp.rst} | 55 +-
Documentation/power/{video.txt => video.rst} | 156 +++---
Documentation/process/submitting-drivers.rst | 2 +-
Documentation/scheduler/sched-energy.txt | 6 +-
Documentation/trace/coresight-cpu-debug.txt | 2 +-
.../zh_CN/process/submitting-drivers.rst | 2 +-
MAINTAINERS | 4 +-
arch/x86/Kconfig | 2 +-
drivers/gpu/drm/i915/i915_drv.h | 2 +-
drivers/opp/Kconfig | 2 +-
drivers/power/supply/power_supply_core.c | 2 +-
include/linux/interrupt.h | 2 +-
include/linux/pci.h | 2 +-
include/linux/pm.h | 2 +-
kernel/power/Kconfig | 6 +-
net/wireless/Kconfig | 2 +-
51 files changed, 2127 insertions(+), 1706 deletions(-)
rename Documentation/power/{apm-acpi.txt => apm-acpi.rst} (87%)
rename Documentation/power/{basic-pm-debugging.txt => basic-pm-debugging.rst} (87%)
rename Documentation/power/{charger-manager.txt => charger-manager.rst} (78%)
rename Documentation/power/{drivers-testing.txt => drivers-testing.rst} (86%)
rename Documentation/power/{energy-model.txt => energy-model.rst} (74%)
rename Documentation/power/{freezing-of-tasks.txt => freezing-of-tasks.rst} (75%)
create mode 100644 Documentation/power/index.rst
rename Documentation/power/{interface.txt => interface.rst} (84%)
rename Documentation/power/{opp.txt => opp.rst} (78%)
rename Documentation/power/{pci.txt => pci.rst} (97%)
rename Documentation/power/{pm_qos_interface.txt => pm_qos_interface.rst} (62%)
create mode 100644 Documentation/power/power_supply_class.rst
delete mode 100644 Documentation/power/power_supply_class.txt
create mode 100644 Documentation/power/powercap/powercap.rst
delete mode 100644 Documentation/power/powercap/powercap.txt
rename Documentation/power/regulator/{consumer.txt => consumer.rst} (61%)
rename Documentation/power/regulator/{design.txt => design.rst} (86%)
rename Documentation/power/regulator/{machine.txt => machine.rst} (75%)
rename Documentation/power/regulator/{overview.txt => overview.rst} (79%)
create mode 100644 Documentation/power/regulator/regulator.rst
delete mode 100644 Documentation/power/regulator/regulator.txt
rename Documentation/power/{runtime_pm.txt => runtime_pm.rst} (89%)
rename Documentation/power/{s2ram.txt => s2ram.rst} (92%)
rename Documentation/power/{suspend-and-cpuhotplug.txt => suspend-and-cpuhotplug.rst} (90%)
rename Documentation/power/{suspend-and-interrupts.txt => suspend-and-interrupts.rst} (98%)
rename Documentation/power/{swsusp-and-swap-files.txt => swsusp-and-swap-files.rst} (83%)
rename Documentation/power/{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} (67%)
create mode 100644 Documentation/power/swsusp.rst
delete mode 100644 Documentation/power/swsusp.txt
rename Documentation/power/{tricks.txt => tricks.rst} (93%)
rename Documentation/power/{userland-swsusp.txt => userland-swsusp.rst} (85%)
rename Documentation/power/{video.txt => video.rst} (56%)
diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
index db3b3ff70d84..742dfd966592 100644
--- a/Documentation/ABI/testing/sysfs-class-powercap
+++ b/Documentation/ABI/testing/sysfs-class-powercap
@@ -5,7 +5,7 @@ Contact: linux-pm@vger.kernel.org
Description:
The powercap/ class sub directory belongs to the power cap
subsystem. Refer to
- Documentation/power/powercap/powercap.txt for details.
+ Documentation/power/powercap/powercap.rst for details.
What: /sys/class/powercap/<control type>
Date: September 2013
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index c31373f39240..0092a453f7dc 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -13,7 +13,7 @@
For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force"
are available
- See also Documentation/power/runtime_pm.txt, pci=noacpi
+ See also Documentation/power/runtime_pm.rst, pci=noacpi
acpi_apic_instance= [ACPI, IOAPIC]
Format: <int>
@@ -223,7 +223,7 @@
acpi_sleep= [HW,ACPI] Sleep options
Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig,
old_ordering, nonvs, sci_force_enable, nobl }
- See Documentation/power/video.txt for information on
+ See Documentation/power/video.rst for information on
s3_bios and s3_mode.
s3_beep is for debugging; it makes the PC's speaker beep
as soon as the kernel's real-mode entry point is called.
@@ -4128,7 +4128,7 @@
Specify the offset from the beginning of the partition
given by "resume=" at which the swap header is located,
in <PAGE_SIZE> units (needed only for swap files).
- See Documentation/power/swsusp-and-swap-files.txt
+ See Documentation/power/swsusp-and-swap-files.rst
resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to
read the resume files
diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt
index 073f128af5a7..55193e680250 100644
--- a/Documentation/cpu-freq/core.txt
+++ b/Documentation/cpu-freq/core.txt
@@ -95,7 +95,7 @@ flags - flags of the cpufreq driver
3. CPUFreq Table Generation with Operating Performance Point (OPP)
==================================================================
-For details about OPP, see Documentation/power/opp.txt
+For details about OPP, see Documentation/power/opp.rst
dev_pm_opp_init_cpufreq_table -
This function provides a ready to use conversion routine to translate
diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
index 30835683616a..f66c7b9126ea 100644
--- a/Documentation/driver-api/pm/devices.rst
+++ b/Documentation/driver-api/pm/devices.rst
@@ -225,7 +225,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto`
flag is clear.
For more information about the runtime power management framework, refer to
-:file:`Documentation/power/runtime_pm.txt`.
+:file:`Documentation/power/runtime_pm.rst`.
Calling Drivers to Enter and Leave System Sleep States
@@ -728,7 +728,7 @@ it into account in any way.
Devices may be defined as IRQ-safe which indicates to the PM core that their
runtime PM callbacks may be invoked with disabled interrupts (see
-:file:`Documentation/power/runtime_pm.txt` for more information). If an
+:file:`Documentation/power/runtime_pm.rst` for more information). If an
IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
disallowed, unless the domain itself is defined as IRQ-safe. However, it
makes sense to define a PM domain as IRQ-safe only if all the devices in it
@@ -795,7 +795,7 @@ so on) and the final state of the device must reflect the "active" runtime PM
status in that case.
During system-wide resume from a sleep state it's easiest to put devices into
-the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`.
+the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
[Refer to that document for more information regarding this particular issue as
well as for information on the device runtime power management framework in
general.]
diff --git a/Documentation/driver-api/usb/power-management.rst b/Documentation/driver-api/usb/power-management.rst
index 4a74cf6f2797..2525c3622cae 100644
--- a/Documentation/driver-api/usb/power-management.rst
+++ b/Documentation/driver-api/usb/power-management.rst
@@ -46,7 +46,7 @@ device is turned off while the system as a whole remains running, we
call it a "dynamic suspend" (also known as a "runtime suspend" or
"selective suspend"). This document concentrates mostly on how
dynamic PM is implemented in the USB subsystem, although system PM is
-covered to some extent (see ``Documentation/power/*.txt`` for more
+covered to some extent (see ``Documentation/power/*.rst`` for more
information about system PM).
System PM support is present only if the kernel was built with
diff --git a/Documentation/power/apm-acpi.txt b/Documentation/power/apm-acpi.rst
similarity index 87%
rename from Documentation/power/apm-acpi.txt
rename to Documentation/power/apm-acpi.rst
index 6cc423d3662e..5b90d947126d 100644
--- a/Documentation/power/apm-acpi.txt
+++ b/Documentation/power/apm-acpi.rst
@@ -1,5 +1,7 @@
+============
APM or ACPI?
-------------
+============
+
If you have a relatively recent x86 mobile, desktop, or server system,
odds are it supports either Advanced Power Management (APM) or
Advanced Configuration and Power Interface (ACPI). ACPI is the newer
@@ -28,5 +30,7 @@ and be sure that they are started sometime in the system boot process.
Go ahead and start both. If ACPI or APM is not available on your
system the associated daemon will exit gracefully.
- apmd: http://ftp.debian.org/pool/main/a/apmd/
- acpid: http://acpid.sf.net/
+ ===== =======================================
+ apmd http://ftp.debian.org/pool/main/a/apmd/
+ acpid http://acpid.sf.net/
+ ===== =======================================
diff --git a/Documentation/power/basic-pm-debugging.txt b/Documentation/power/basic-pm-debugging.rst
similarity index 87%
rename from Documentation/power/basic-pm-debugging.txt
rename to Documentation/power/basic-pm-debugging.rst
index 708f87f78a75..69862e759c30 100644
--- a/Documentation/power/basic-pm-debugging.txt
+++ b/Documentation/power/basic-pm-debugging.rst
@@ -1,12 +1,16 @@
+=================================
Debugging hibernation and suspend
+=================================
+
(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
1. Testing hibernation (aka suspend to disk or STD)
+===================================================
-To check if hibernation works, you can try to hibernate in the "reboot" mode:
+To check if hibernation works, you can try to hibernate in the "reboot" mode::
-# echo reboot > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo reboot > /sys/power/disk
+ # echo disk > /sys/power/state
and the system should create a hibernation image, reboot, resume and get back to
the command prompt where you have started the transition. If that happens,
@@ -15,20 +19,21 @@ test at least a couple of times in a row for confidence. [This is necessary,
because some problems only show up on a second attempt at suspending and
resuming the system.] Moreover, hibernating in the "reboot" and "shutdown"
modes causes the PM core to skip some platform-related callbacks which on ACPI
-systems might be necessary to make hibernation work. Thus, if your machine fails
-to hibernate or resume in the "reboot" mode, you should try the "platform" mode:
+systems might be necessary to make hibernation work. Thus, if your machine
+fails to hibernate or resume in the "reboot" mode, you should try the
+"platform" mode::
-# echo platform > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo platform > /sys/power/disk
+ # echo disk > /sys/power/state
which is the default and recommended mode of hibernation.
Unfortunately, the "platform" mode of hibernation does not work on some systems
with broken BIOSes. In such cases the "shutdown" mode of hibernation might
-work:
+work::
-# echo shutdown > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo shutdown > /sys/power/disk
+ # echo disk > /sys/power/state
(it is similar to the "reboot" mode, but it requires you to press the power
button to make the system resume).
@@ -37,6 +42,7 @@ If neither "platform" nor "shutdown" hibernation mode works, you will need to
identify what goes wrong.
a) Test modes of hibernation
+----------------------------
To find out why hibernation fails on your system, you can use a special testing
facility available if the kernel is compiled with CONFIG_PM_DEBUG set. Then,
@@ -44,36 +50,38 @@ there is the file /sys/power/pm_test that can be used to make the hibernation
core run in a test mode. There are 5 test modes available:
freezer
-- test the freezing of processes
+ - test the freezing of processes
devices
-- test the freezing of processes and suspending of devices
+ - test the freezing of processes and suspending of devices
platform
-- test the freezing of processes, suspending of devices and platform
- global control methods(*)
+ - test the freezing of processes, suspending of devices and platform
+ global control methods [1]_
processors
-- test the freezing of processes, suspending of devices, platform
- global control methods(*) and the disabling of nonboot CPUs
+ - test the freezing of processes, suspending of devices, platform
+ global control methods [1]_ and the disabling of nonboot CPUs
core
-- test the freezing of processes, suspending of devices, platform global
- control methods(*), the disabling of nonboot CPUs and suspending of
- platform/system devices
+ - test the freezing of processes, suspending of devices, platform global
+ control methods\ [1]_, the disabling of nonboot CPUs and suspending
+ of platform/system devices
-(*) the platform global control methods are only available on ACPI systems
+.. [1]
+
+ the platform global control methods are only available on ACPI systems
and are only tested if the hibernation mode is set to "platform"
To use one of them it is necessary to write the corresponding string to
/sys/power/pm_test (eg. "devices" to test the freezing of processes and
suspending devices) and issue the standard hibernation commands. For example,
to use the "devices" test mode along with the "platform" mode of hibernation,
-you should do the following:
+you should do the following::
-# echo devices > /sys/power/pm_test
-# echo platform > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo devices > /sys/power/pm_test
+ # echo platform > /sys/power/disk
+ # echo disk > /sys/power/state
Then, the kernel will try to freeze processes, suspend devices, wait a few
seconds (5 by default, but configurable by the suspend.pm_test_delay module
@@ -108,11 +116,12 @@ If the "devices" test fails, most likely there is a driver that cannot suspend
or resume its device (in the latter case the system may hang or become unstable
after the test, so please take that into consideration). To find this driver,
you can carry out a binary search according to the rules:
+
- if the test fails, unload a half of the drivers currently loaded and repeat
-(that would probably involve rebooting the system, so always note what drivers
-have been loaded before the test),
+ (that would probably involve rebooting the system, so always note what drivers
+ have been loaded before the test),
- if the test succeeds, load a half of the drivers you have unloaded most
-recently and repeat.
+ recently and repeat.
Once you have found the failing driver (there can be more than just one of
them), you have to unload it every time before hibernation. In that case please
@@ -146,6 +155,7 @@ indicates a serious problem that very well may be related to the hardware, but
please report it anyway.
b) Testing minimal configuration
+--------------------------------
If all of the hibernation test modes work, you can boot the system with the
"init=/bin/bash" command line parameter and attempt to hibernate in the
@@ -165,14 +175,15 @@ Again, if you find the offending module(s), it(they) must be unloaded every time
before hibernation, and please report the problem with it(them).
c) Using the "test_resume" hibernation option
+---------------------------------------------
/sys/power/disk generally tells the kernel what to do after creating a
hibernation image. One of the available options is "test_resume" which
causes the just created image to be used for immediate restoration. Namely,
-after doing:
+after doing::
-# echo test_resume > /sys/power/disk
-# echo disk > /sys/power/state
+ # echo test_resume > /sys/power/disk
+ # echo disk > /sys/power/state
a hibernation image will be created and a resume from it will be triggered
immediately without involving the platform firmware in any way.
@@ -190,6 +201,7 @@ to resume may be related to the differences between the restore and image
kernels.
d) Advanced debugging
+---------------------
In case that hibernation does not work on your system even in the minimal
configuration and compiling more drivers as modules is not practical or some
@@ -200,9 +212,10 @@ kernel messages using the serial console. This may provide you with some
information about the reasons of the suspend (resume) failure. Alternatively,
it may be possible to use a FireWire port for debugging with firescope
(http://v3.sk/~lkundrak/firescope/). On x86 it is also possible to
-use the PM_TRACE mechanism documented in Documentation/power/s2ram.txt .
+use the PM_TRACE mechanism documented in Documentation/power/s2ram.rst .
2. Testing suspend to RAM (STR)
+===============================
To verify that the STR works, it is generally more convenient to use the s2ram
tool available from http://suspend.sf.net and documented at
@@ -230,7 +243,8 @@ you will have to unload them every time before an STR transition (ie. before
you run s2ram), and please report the problems with them.
There is a debugfs entry which shows the suspend to RAM statistics. Here is an
-example of its output.
+example of its output::
+
# mount -t debugfs none /sys/kernel/debug
# cat /sys/kernel/debug/suspend_stats
success: 20
@@ -248,6 +262,7 @@ example of its output.
-16
last_failed_step: suspend
suspend
+
Field success means the success number of suspend to RAM, and field fail means
the failure number. Others are the failure number of different steps of suspend
to RAM. suspend_stats just lists the last 2 failed devices, error number and
diff --git a/Documentation/power/charger-manager.txt b/Documentation/power/charger-manager.rst
similarity index 78%
rename from Documentation/power/charger-manager.txt
rename to Documentation/power/charger-manager.rst
index 9ff1105e58d6..84fab9376792 100644
--- a/Documentation/power/charger-manager.txt
+++ b/Documentation/power/charger-manager.rst
@@ -1,4 +1,7 @@
+===============
Charger Manager
+===============
+
(C) 2011 MyungJoo Ham <myungjoo.ham@samsung.com>, GPL
Charger Manager provides in-kernel battery charger management that
@@ -55,41 +58,39 @@ Charger Manager supports the following:
notification to users with UEVENT.
2. Global Charger-Manager Data related with suspend_again
-========================================================
+=========================================================
In order to setup Charger Manager with suspend-again feature
(in-suspend monitoring), the user should provide charger_global_desc
-with setup_charger_manager(struct charger_global_desc *).
+with setup_charger_manager(`struct charger_global_desc *`).
This charger_global_desc data for in-suspend monitoring is global
as the name suggests. Thus, the user needs to provide only once even
if there are multiple batteries. If there are multiple batteries, the
multiple instances of Charger Manager share the same charger_global_desc
and it will manage in-suspend monitoring for all instances of Charger Manager.
-The user needs to provide all the three entries properly in order to activate
-in-suspend monitoring:
+The user needs to provide all the three entries to `struct charger_global_desc`
+properly in order to activate in-suspend monitoring:
-struct charger_global_desc {
-
-char *rtc_name;
- : The name of rtc (e.g., "rtc0") used to wakeup the system from
+`char *rtc_name;`
+ The name of rtc (e.g., "rtc0") used to wakeup the system from
suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
should be able to wake up the system from suspend. Charger Manager
saves and restores the alarm value and use the previously-defined
alarm if it is going to go off earlier than Charger Manager so that
Charger Manager does not interfere with previously-defined alarms.
-bool (*rtc_only_wakeup)(void);
- : This callback should let CM know whether
+`bool (*rtc_only_wakeup)(void);`
+ This callback should let CM know whether
the wakeup-from-suspend is caused only by the alarm of "rtc" in the
same struct. If there is any other wakeup source triggered the
wakeup, it should return false. If the "rtc" is the only wakeup
reason, it should return true.
-bool assume_timer_stops_in_suspend;
- : if true, Charger Manager assumes that
+`bool assume_timer_stops_in_suspend;`
+ if true, Charger Manager assumes that
the timer (CM uses jiffies as timer) stops during suspend. Then, CM
assumes that the suspend-duration is same as the alarm length.
-};
+
3. How to setup suspend_again
=============================
@@ -109,26 +110,28 @@ if the system was woken up by Charger Manager and the polling
=============================================
For each battery charged independently from other batteries (if a series of
batteries are charged by a single charger, they are counted as one independent
-battery), an instance of Charger Manager is attached to it.
+battery), an instance of Charger Manager is attached to it. The following
-struct charger_desc {
+struct charger_desc elements:
-char *psy_name;
- : The power-supply-class name of the battery. Default is
+`char *psy_name;`
+ The power-supply-class name of the battery. Default is
"battery" if psy_name is NULL. Users can access the psy entries
at "/sys/class/power_supply/[psy_name]/".
-enum polling_modes polling_mode;
- : CM_POLL_DISABLE: do not poll this battery.
- CM_POLL_ALWAYS: always poll this battery.
- CM_POLL_EXTERNAL_POWER_ONLY: poll this battery if and only if
- an external power source is attached.
- CM_POLL_CHARGING_ONLY: poll this battery if and only if the
- battery is being charged.
+`enum polling_modes polling_mode;`
+ CM_POLL_DISABLE:
+ do not poll this battery.
+ CM_POLL_ALWAYS:
+ always poll this battery.
+ CM_POLL_EXTERNAL_POWER_ONLY:
+ poll this battery if and only if an external power
+ source is attached.
+ CM_POLL_CHARGING_ONLY:
+ poll this battery if and only if the battery is being charged.
-unsigned int fullbatt_vchkdrop_ms;
-unsigned int fullbatt_vchkdrop_uV;
- : If both have non-zero values, Charger Manager will check the
+`unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;`
+ If both have non-zero values, Charger Manager will check the
battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
Manager will try to recharge the battery by disabling and enabling
@@ -136,50 +139,52 @@ unsigned int fullbatt_vchkdrop_uV;
condition) is needed to be implemented with hardware interrupts from
fuel gauges or charger devices/chips.
-unsigned int fullbatt_uV;
- : If specified with a non-zero value, Charger Manager assumes
+`unsigned int fullbatt_uV;`
+ If specified with a non-zero value, Charger Manager assumes
that the battery is full (capacity = 100) if the battery is not being
charged and the battery voltage is equal to or greater than
fullbatt_uV.
-unsigned int polling_interval_ms;
- : Required polling interval in ms. Charger Manager will poll
+`unsigned int polling_interval_ms;`
+ Required polling interval in ms. Charger Manager will poll
this battery every polling_interval_ms or more frequently.
-enum data_source battery_present;
- : CM_BATTERY_PRESENT: assume that the battery exists.
- CM_NO_BATTERY: assume that the battery does not exists.
- CM_FUEL_GAUGE: get battery presence information from fuel gauge.
- CM_CHARGER_STAT: get battery presence from chargers.
+`enum data_source battery_present;`
+ CM_BATTERY_PRESENT:
+ assume that the battery exists.
+ CM_NO_BATTERY:
+ assume that the battery does not exists.
+ CM_FUEL_GAUGE:
+ get battery presence information from fuel gauge.
+ CM_CHARGER_STAT:
+ get battery presence from chargers.
-char **psy_charger_stat;
- : An array ending with NULL that has power-supply-class names of
+`char **psy_charger_stat;`
+ An array ending with NULL that has power-supply-class names of
chargers. Each power-supply-class should provide "PRESENT" (if
battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an
external power source is attached or not), and "STATUS" (shows whether
the battery is {"FULL" or not FULL} or {"FULL", "Charging",
"Discharging", "NotCharging"}).
-int num_charger_regulators;
-struct regulator_bulk_data *charger_regulators;
- : Regulators representing the chargers in the form for
+`int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;`
+ Regulators representing the chargers in the form for
regulator framework's bulk functions.
-char *psy_fuel_gauge;
- : Power-supply-class name of the fuel gauge.
+`char *psy_fuel_gauge;`
+ Power-supply-class name of the fuel gauge.
-int (*temperature_out_of_range)(int *mC);
-bool measure_battery_temp;
- : This callback returns 0 if the temperature is safe for charging,
+`int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;`
+ This callback returns 0 if the temperature is safe for charging,
a positive number if it is too hot to charge, and a negative number
if it is too cold to charge. With the variable mC, the callback returns
the temperature in 1/1000 of centigrade.
The source of temperature can be battery or ambient one according to
the value of measure_battery_temp.
-};
+
5. Notify Charger-Manager of charger events: cm_notify_event()
-=========================================================
+==============================================================
If there is an charger event is required to notify
Charger Manager, a charger device driver that triggers the event can call
cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager.
diff --git a/Documentation/power/drivers-testing.txt b/Documentation/power/drivers-testing.rst
similarity index 86%
rename from Documentation/power/drivers-testing.txt
rename to Documentation/power/drivers-testing.rst
index 638afdf4d6b8..e53f1999fc39 100644
--- a/Documentation/power/drivers-testing.txt
+++ b/Documentation/power/drivers-testing.rst
@@ -1,7 +1,11 @@
+====================================================
Testing suspend and resume support in device drivers
+====================================================
+
(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
1. Preparing the test system
+============================
Unfortunately, to effectively test the support for the system-wide suspend and
resume transitions in a driver, it is necessary to suspend and resume a fully
@@ -14,19 +18,20 @@ the machine's BIOS.
Of course, for this purpose the test system has to be known to suspend and
resume without the driver being tested. Thus, if possible, you should first
resolve all suspend/resume-related problems in the test system before you start
-testing the new driver. Please see Documentation/power/basic-pm-debugging.txt
+testing the new driver. Please see Documentation/power/basic-pm-debugging.rst
for more information about the debugging of suspend/resume functionality.
2. Testing the driver
+=====================
Once you have resolved the suspend/resume-related problems with your test system
without the new driver, you are ready to test it:
a) Build the driver as a module, load it and try the test modes of hibernation
- (see: Documentation/power/basic-pm-debugging.txt, 1).
+ (see: Documentation/power/basic-pm-debugging.rst, 1).
b) Load the driver and attempt to hibernate in the "reboot", "shutdown" and
- "platform" modes (see: Documentation/power/basic-pm-debugging.txt, 1).
+ "platform" modes (see: Documentation/power/basic-pm-debugging.rst, 1).
c) Compile the driver directly into the kernel and try the test modes of
hibernation.
@@ -34,12 +39,12 @@ c) Compile the driver directly into the kernel and try the test modes of
d) Attempt to hibernate with the driver compiled directly into the kernel
in the "reboot", "shutdown" and "platform" modes.
-e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.txt,
+e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.rst,
2). [As far as the STR tests are concerned, it should not matter whether or
not the driver is built as a module.]
f) Attempt to suspend to RAM using the s2ram tool with the driver loaded
- (see: Documentation/power/basic-pm-debugging.txt, 2).
+ (see: Documentation/power/basic-pm-debugging.rst, 2).
Each of the above tests should be repeated several times and the STD tests
should be mixed with the STR tests. If any of them fails, the driver cannot be
diff --git a/Documentation/power/energy-model.txt b/Documentation/power/energy-model.rst
similarity index 74%
rename from Documentation/power/energy-model.txt
rename to Documentation/power/energy-model.rst
index a2b0ae4c76bd..90a345d57ae9 100644
--- a/Documentation/power/energy-model.txt
+++ b/Documentation/power/energy-model.rst
@@ -1,6 +1,6 @@
- ====================
- Energy Model of CPUs
- ====================
+====================
+Energy Model of CPUs
+====================
1. Overview
-----------
@@ -20,7 +20,7 @@ kernel, hence enabling to avoid redundant work.
The figure below depicts an example of drivers (Arm-specific here, but the
approach is applicable to any architecture) providing power costs to the EM
-framework, and interested clients reading the data from it.
+framework, and interested clients reading the data from it::
+---------------+ +-----------------+ +---------------+
| Thermal (IPA) | | Scheduler (EAS) | | Other |
@@ -58,15 +58,17 @@ micro-architectures.
2. Core APIs
------------
- 2.1 Config options
+2.1 Config options
+^^^^^^^^^^^^^^^^^^
CONFIG_ENERGY_MODEL must be enabled to use the EM framework.
- 2.2 Registration of performance domains
+2.2 Registration of performance domains
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Drivers are expected to register performance domains into the EM framework by
-calling the following API:
+calling the following API::
int em_register_perf_domain(cpumask_t *span, unsigned int nr_states,
struct em_data_callback *cb);
@@ -80,7 +82,8 @@ callback, and kernel/power/energy_model.c for further documentation on this
API.
- 2.3 Accessing performance domains
+2.3 Accessing performance domains
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Subsystems interested in the energy model of a CPU can retrieve it using the
em_cpu_get() API. The energy model tables are allocated once upon creation of
@@ -99,46 +102,46 @@ More details about the above APIs can be found in include/linux/energy_model.h.
This section provides a simple example of a CPUFreq driver registering a
performance domain in the Energy Model framework using the (fake) 'foo'
protocol. The driver implements an est_power() function to be provided to the
-EM framework.
+EM framework::
- -> drivers/cpufreq/foo_cpufreq.c
+ -> drivers/cpufreq/foo_cpufreq.c
-01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
-02 {
-03 long freq, power;
-04
-05 /* Use the 'foo' protocol to ceil the frequency */
-06 freq = foo_get_freq_ceil(cpu, *KHz);
-07 if (freq < 0);
-08 return freq;
-09
-10 /* Estimate the power cost for the CPU at the relevant freq. */
-11 power = foo_estimate_power(cpu, freq);
-12 if (power < 0);
-13 return power;
-14
-15 /* Return the values to the EM framework */
-16 *mW = power;
-17 *KHz = freq;
-18
-19 return 0;
-20 }
-21
-22 static int foo_cpufreq_init(struct cpufreq_policy *policy)
-23 {
-24 struct em_data_callback em_cb = EM_DATA_CB(est_power);
-25 int nr_opp, ret;
-26
-27 /* Do the actual CPUFreq init work ... */
-28 ret = do_foo_cpufreq_init(policy);
-29 if (ret)
-30 return ret;
-31
-32 /* Find the number of OPPs for this policy */
-33 nr_opp = foo_get_nr_opp(policy);
-34
-35 /* And register the new performance domain */
-36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
-37
-38 return 0;
-39 }
+ 01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
+ 02 {
+ 03 long freq, power;
+ 04
+ 05 /* Use the 'foo' protocol to ceil the frequency */
+ 06 freq = foo_get_freq_ceil(cpu, *KHz);
+ 07 if (freq < 0);
+ 08 return freq;
+ 09
+ 10 /* Estimate the power cost for the CPU at the relevant freq. */
+ 11 power = foo_estimate_power(cpu, freq);
+ 12 if (power < 0);
+ 13 return power;
+ 14
+ 15 /* Return the values to the EM framework */
+ 16 *mW = power;
+ 17 *KHz = freq;
+ 18
+ 19 return 0;
+ 20 }
+ 21
+ 22 static int foo_cpufreq_init(struct cpufreq_policy *policy)
+ 23 {
+ 24 struct em_data_callback em_cb = EM_DATA_CB(est_power);
+ 25 int nr_opp, ret;
+ 26
+ 27 /* Do the actual CPUFreq init work ... */
+ 28 ret = do_foo_cpufreq_init(policy);
+ 29 if (ret)
+ 30 return ret;
+ 31
+ 32 /* Find the number of OPPs for this policy */
+ 33 nr_opp = foo_get_nr_opp(policy);
+ 34
+ 35 /* And register the new performance domain */
+ 36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
+ 37
+ 38 return 0;
+ 39 }
diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.rst
similarity index 75%
rename from Documentation/power/freezing-of-tasks.txt
rename to Documentation/power/freezing-of-tasks.rst
index cd283190855a..ef110fe55e82 100644
--- a/Documentation/power/freezing-of-tasks.txt
+++ b/Documentation/power/freezing-of-tasks.rst
@@ -1,13 +1,18 @@
+=================
Freezing of tasks
- (C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
+=================
+
+(C) 2007 Rafael J. Wysocki <rjw@sisk.pl>, GPL
I. What is the freezing of tasks?
+=================================
The freezing of tasks is a mechanism by which user space processes and some
kernel threads are controlled during hibernation or system-wide suspend (on some
architectures).
II. How does it work?
+=====================
There are three per-task flags used for that, PF_NOFREEZE, PF_FROZEN
and PF_FREEZER_SKIP (the last one is auxiliary). The tasks that have
@@ -41,7 +46,7 @@ explicitly in suitable places or use the wait_event_freezable() or
wait_event_freezable_timeout() macros (defined in include/linux/freezer.h)
that combine interruptible sleep with checking if the task is to be frozen and
calling try_to_freeze(). The main loop of a freezable kernel thread may look
-like the following one:
+like the following one::
set_freezable();
do {
@@ -65,7 +70,7 @@ order to clear the PF_FROZEN flag for each frozen task. Then, the tasks that
have been frozen leave __refrigerator() and continue running.
-Rationale behind the functions dealing with freezing and thawing of tasks:
+Rationale behind the functions dealing with freezing and thawing of tasks
-------------------------------------------------------------------------
freeze_processes():
@@ -86,6 +91,7 @@ thaw_processes():
III. Which kernel threads are freezable?
+========================================
Kernel threads are not freezable by default. However, a kernel thread may clear
PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE
@@ -93,37 +99,39 @@ directly is not allowed). From this point it is regarded as freezable
and must call try_to_freeze() in a suitable place.
IV. Why do we do that?
+======================
Generally speaking, there is a couple of reasons to use the freezing of tasks:
1. The principal reason is to prevent filesystems from being damaged after
-hibernation. At the moment we have no simple means of checkpointing
-filesystems, so if there are any modifications made to filesystem data and/or
-metadata on disks, we cannot bring them back to the state from before the
-modifications. At the same time each hibernation image contains some
-filesystem-related information that must be consistent with the state of the
-on-disk data and metadata after the system memory state has been restored from
-the image (otherwise the filesystems will be damaged in a nasty way, usually
-making them almost impossible to repair). We therefore freeze tasks that might
-cause the on-disk filesystems' data and metadata to be modified after the
-hibernation image has been created and before the system is finally powered off.
-The majority of these are user space processes, but if any of the kernel threads
-may cause something like this to happen, they have to be freezable.
+ hibernation. At the moment we have no simple means of checkpointing
+ filesystems, so if there are any modifications made to filesystem data and/or
+ metadata on disks, we cannot bring them back to the state from before the
+ modifications. At the same time each hibernation image contains some
+ filesystem-related information that must be consistent with the state of the
+ on-disk data and metadata after the system memory state has been restored
+ from the image (otherwise the filesystems will be damaged in a nasty way,
+ usually making them almost impossible to repair). We therefore freeze
+ tasks that might cause the on-disk filesystems' data and metadata to be
+ modified after the hibernation image has been created and before the
+ system is finally powered off. The majority of these are user space
+ processes, but if any of the kernel threads may cause something like this
+ to happen, they have to be freezable.
2. Next, to create the hibernation image we need to free a sufficient amount of
-memory (approximately 50% of available RAM) and we need to do that before
-devices are deactivated, because we generally need them for swapping out. Then,
-after the memory for the image has been freed, we don't want tasks to allocate
-additional memory and we prevent them from doing that by freezing them earlier.
-[Of course, this also means that device drivers should not allocate substantial
-amounts of memory from their .suspend() callbacks before hibernation, but this
-is a separate issue.]
+ memory (approximately 50% of available RAM) and we need to do that before
+ devices are deactivated, because we generally need them for swapping out.
+ Then, after the memory for the image has been freed, we don't want tasks
+ to allocate additional memory and we prevent them from doing that by
+ freezing them earlier. [Of course, this also means that device drivers
+ should not allocate substantial amounts of memory from their .suspend()
+ callbacks before hibernation, but this is a separate issue.]
3. The third reason is to prevent user space processes and some kernel threads
-from interfering with the suspending and resuming of devices. A user space
-process running on a second CPU while we are suspending devices may, for
-example, be troublesome and without the freezing of tasks we would need some
-safeguards against race conditions that might occur in such a case.
+ from interfering with the suspending and resuming of devices. A user space
+ process running on a second CPU while we are suspending devices may, for
+ example, be troublesome and without the freezing of tasks we would need some
+ safeguards against race conditions that might occur in such a case.
Although Linus Torvalds doesn't like the freezing of tasks, he said this in one
of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608):
@@ -132,7 +140,7 @@ of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608):
Linus: In many ways, 'at all'.
-I _do_ realize the IO request queue issues, and that we cannot actually do
+I **do** realize the IO request queue issues, and that we cannot actually do
s2ram with some devices in the middle of a DMA. So we want to be able to
avoid *that*, there's no question about that. And I suspect that stopping
user threads and then waiting for a sync is practically one of the easier
@@ -150,17 +158,18 @@ thawed after the driver's .resume() callback has run, so it won't be accessing
the device while it's suspended.
4. Another reason for freezing tasks is to prevent user space processes from
-realizing that hibernation (or suspend) operation takes place. Ideally, user
-space processes should not notice that such a system-wide operation has occurred
-and should continue running without any problems after the restore (or resume
-from suspend). Unfortunately, in the most general case this is quite difficult
-to achieve without the freezing of tasks. Consider, for example, a process
-that depends on all CPUs being online while it's running. Since we need to
-disable nonboot CPUs during the hibernation, if this process is not frozen, it
-may notice that the number of CPUs has changed and may start to work incorrectly
-because of that.
+ realizing that hibernation (or suspend) operation takes place. Ideally, user
+ space processes should not notice that such a system-wide operation has
+ occurred and should continue running without any problems after the restore
+ (or resume from suspend). Unfortunately, in the most general case this
+ is quite difficult to achieve without the freezing of tasks. Consider,
+ for example, a process that depends on all CPUs being online while it's
+ running. Since we need to disable nonboot CPUs during the hibernation,
+ if this process is not frozen, it may notice that the number of CPUs has
+ changed and may start to work incorrectly because of that.
V. Are there any problems related to the freezing of tasks?
+===========================================================
Yes, there are.
@@ -172,11 +181,12 @@ may be undesirable. That's why kernel threads are not freezable by default.
Second, there are the following two problems related to the freezing of user
space processes:
+
1. Putting processes into an uninterruptible sleep distorts the load average.
2. Now that we have FUSE, plus the framework for doing device drivers in
-userspace, it gets even more complicated because some userspace processes are
-now doing the sorts of things that kernel threads do
-(https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html).
+ userspace, it gets even more complicated because some userspace processes are
+ now doing the sorts of things that kernel threads do
+ (https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html).
The problem 1. seems to be fixable, although it hasn't been fixed so far. The
other one is more serious, but it seems that we can work around it by using
@@ -201,6 +211,7 @@ requested early enough using the suspend notifier API described in
Documentation/driver-api/pm/notifiers.rst.
VI. Are there any precautions to be taken to prevent freezing failures?
+=======================================================================
Yes, there are.
@@ -226,6 +237,8 @@ So, to summarize, use [un]lock_system_sleep() instead of directly using
mutex_[un]lock(&system_transition_mutex). That would prevent freezing failures.
V. Miscellaneous
+================
+
/sys/power/pm_freeze_timeout controls how long it will cost at most to freeze
all user space processes or all freezable kernel threads, in unit of millisecond.
The default value is 20000, with range of unsigned integer.
diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
new file mode 100644
index 000000000000..20415f21e48a
--- /dev/null
+++ b/Documentation/power/index.rst
@@ -0,0 +1,46 @@
+:orphan:
+
+================
+Power Management
+================
+
+.. toctree::
+ :maxdepth: 1
+
+ apm-acpi
+ basic-pm-debugging
+ charger-manager
+ drivers-testing
+ energy-model
+ freezing-of-tasks
+ interface
+ opp
+ pci
+ pm_qos_interface
+ power_supply_class
+ runtime_pm
+ s2ram
+ suspend-and-cpuhotplug
+ suspend-and-interrupts
+ swsusp-and-swap-files
+ swsusp-dmcrypt
+ swsusp
+ video
+ tricks
+
+ userland-swsusp
+
+ powercap/powercap
+
+ regulator/consumer
+ regulator/design
+ regulator/machine
+ regulator/overview
+ regulator/regulator
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/power/interface.txt b/Documentation/power/interface.rst
similarity index 84%
rename from Documentation/power/interface.txt
rename to Documentation/power/interface.rst
index 27df7f98668a..8d270ed27228 100644
--- a/Documentation/power/interface.txt
+++ b/Documentation/power/interface.rst
@@ -1,4 +1,6 @@
+===========================================
Power Management Interface for System Sleep
+===========================================
Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
@@ -11,10 +13,10 @@ mounted at /sys).
Reading from it returns a list of supported sleep states, encoded as:
-'freeze' (Suspend-to-Idle)
-'standby' (Power-On Suspend)
-'mem' (Suspend-to-RAM)
-'disk' (Suspend-to-Disk)
+- 'freeze' (Suspend-to-Idle)
+- 'standby' (Power-On Suspend)
+- 'mem' (Suspend-to-RAM)
+- 'disk' (Suspend-to-Disk)
Suspend-to-Idle is always supported. Suspend-to-Disk is always supported
too as long the kernel has been configured to support hibernation at all
@@ -32,18 +34,18 @@ Specifically, it tells the kernel what to do after creating a hibernation image.
Reading from it returns a list of supported options encoded as:
-'platform' (put the system into sleep using a platform-provided method)
-'shutdown' (shut the system down)
-'reboot' (reboot the system)
-'suspend' (trigger a Suspend-to-RAM transition)
-'test_resume' (resume-after-hibernation test mode)
+- 'platform' (put the system into sleep using a platform-provided method)
+- 'shutdown' (shut the system down)
+- 'reboot' (reboot the system)
+- 'suspend' (trigger a Suspend-to-RAM transition)
+- 'test_resume' (resume-after-hibernation test mode)
The currently selected option is printed in square brackets.
The 'platform' option is only available if the platform provides a special
mechanism to put the system to sleep after creating a hibernation image (ACPI
does that, for example). The 'suspend' option is available if Suspend-to-RAM
-is supported. Refer to Documentation/power/basic-pm-debugging.txt for the
+is supported. Refer to Documentation/power/basic-pm-debugging.rst for the
description of the 'test_resume' option.
To select an option, write the string representing it to /sys/power/disk.
@@ -71,7 +73,7 @@ If /sys/power/pm_trace contains '1', the fingerprint of each suspend/resume
event point in turn will be stored in the RTC memory (overwriting the actual
RTC information), so it will survive a system crash if one occurs right after
storing it and it can be used later to identify the driver that caused the crash
-to happen (see Documentation/power/s2ram.txt for more information).
+to happen (see Documentation/power/s2ram.rst for more information).
Initially it contains '0' which may be changed to '1' by writing a string
representing a nonzero integer into it.
diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.rst
similarity index 78%
rename from Documentation/power/opp.txt
rename to Documentation/power/opp.rst
index 0c007e250cd1..b3cf1def9dee 100644
--- a/Documentation/power/opp.txt
+++ b/Documentation/power/opp.rst
@@ -1,20 +1,23 @@
+==========================================
Operating Performance Points (OPP) Library
==========================================
(C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
-Contents
---------
-1. Introduction
-2. Initial OPP List Registration
-3. OPP Search Functions
-4. OPP Availability Control Functions
-5. OPP Data Retrieval Functions
-6. Data Structures
+.. Contents
+
+ 1. Introduction
+ 2. Initial OPP List Registration
+ 3. OPP Search Functions
+ 4. OPP Availability Control Functions
+ 5. OPP Data Retrieval Functions
+ 6. Data Structures
1. Introduction
===============
+
1.1 What is an Operating Performance Point (OPP)?
+-------------------------------------------------
Complex SoCs of today consists of a multiple sub-modules working in conjunction.
In an operational system executing varied use cases, not all modules in the SoC
@@ -28,16 +31,19 @@ the device will support per domain are called Operating Performance Points or
OPPs.
As an example:
+
Let us consider an MPU device which supports the following:
{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
{1GHz at minimum voltage of 1.3V}
We can represent these as three OPPs as the following {Hz, uV} tuples:
-{300000000, 1000000}
-{800000000, 1200000}
-{1000000000, 1300000}
+
+- {300000000, 1000000}
+- {800000000, 1200000}
+- {1000000000, 1300000}
1.2 Operating Performance Points Library
+----------------------------------------
OPP library provides a set of helper functions to organize and query the OPP
information. The library is located in drivers/base/power/opp.c and the header
@@ -46,9 +52,10 @@ CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on
CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to
optionally boot at a certain OPP without needing cpufreq.
-Typical usage of the OPP library is as follows:
-(users) -> registers a set of default OPPs -> (library)
-SoC framework -> modifies on required cases certain OPPs -> OPP layer
+Typical usage of the OPP library is as follows::
+
+ (users) -> registers a set of default OPPs -> (library)
+ SoC framework -> modifies on required cases certain OPPs -> OPP layer
-> queries to search/retrieve information ->
OPP layer expects each domain to be represented by a unique device pointer. SoC
@@ -57,8 +64,9 @@ list is expected to be an optimally small number typically around 5 per device.
This initial list contains a set of OPPs that the framework expects to be safely
enabled by default in the system.
-Note on OPP Availability:
-------------------------
+Note on OPP Availability
+^^^^^^^^^^^^^^^^^^^^^^^^
+
As the system proceeds to operate, SoC framework may choose to make certain
OPPs available or not available on each device based on various external
factors. Example usage: Thermal management or other exceptional situations where
@@ -88,7 +96,8 @@ registering the OPPs is maintained by OPP library throughout the device
operation. The SoC framework can subsequently control the availability of the
OPPs dynamically using the dev_pm_opp_enable / disable functions.
-dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer.
+dev_pm_opp_add
+ Add a new OPP for a specific domain represented by the device pointer.
The OPP is defined using the frequency and voltage. Once added, the OPP
is assumed to be available and control of it's availability can be done
with the dev_pm_opp_enable/disable functions. OPP library internally stores
@@ -96,9 +105,11 @@ dev_pm_opp_add - Add a new OPP for a specific domain represented by the device p
used by SoC framework to define a optimal list as per the demands of
SoC usage environment.
- WARNING: Do not use this function in interrupt context.
+ WARNING:
+ Do not use this function in interrupt context.
+
+ Example::
- Example:
soc_pm_init()
{
/* Do things */
@@ -125,12 +136,15 @@ Callers of these functions shall call dev_pm_opp_put() after they have used the
OPP. Otherwise the memory for the OPP will never get freed and result in
memleak.
-dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
+dev_pm_opp_find_freq_exact
+ Search for an OPP based on an *exact* frequency and
availability. This function is especially useful to enable an OPP which
is not available by default.
Example: In a case when SoC framework detects a situation where a
higher frequency could be made available, it can use this function to
- find the OPP prior to call the dev_pm_opp_enable to actually make it available.
+ find the OPP prior to call the dev_pm_opp_enable to actually make
+ it available::
+
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
dev_pm_opp_put(opp);
/* dont operate on the pointer.. just do a sanity check.. */
@@ -141,27 +155,34 @@ dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
dev_pm_opp_enable(dev,1000000000);
}
- NOTE: This is the only search function that operates on OPPs which are
- not available.
+ NOTE:
+ This is the only search function that operates on OPPs which are
+ not available.
-dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the
+dev_pm_opp_find_freq_floor
+ Search for an available OPP which is *at most* the
provided frequency. This function is useful while searching for a lesser
match OR operating on OPP information in the order of decreasing
frequency.
- Example: To find the highest opp for a device:
+ Example: To find the highest opp for a device::
+
freq = ULONG_MAX;
opp = dev_pm_opp_find_freq_floor(dev, &freq);
dev_pm_opp_put(opp);
-dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the
+dev_pm_opp_find_freq_ceil
+ Search for an available OPP which is *at least* the
provided frequency. This function is useful while searching for a
higher match OR operating on OPP information in the order of increasing
frequency.
- Example 1: To find the lowest opp for a device:
+ Example 1: To find the lowest opp for a device::
+
freq = 0;
opp = dev_pm_opp_find_freq_ceil(dev, &freq);
dev_pm_opp_put(opp);
- Example 2: A simplified implementation of a SoC cpufreq_driver->target:
+
+ Example 2: A simplified implementation of a SoC cpufreq_driver->target::
+
soc_cpufreq_target(..)
{
/* Do stuff like policy checks etc. */
@@ -184,12 +205,15 @@ fine grained dynamic control of which sets of OPPs are operationally available.
These functions are intended to *temporarily* remove an OPP in conditions such
as thermal considerations (e.g. don't use OPPx until the temperature drops).
-WARNING: Do not use these functions in interrupt context.
+WARNING:
+ Do not use these functions in interrupt context.
-dev_pm_opp_enable - Make a OPP available for operation.
+dev_pm_opp_enable
+ Make a OPP available for operation.
Example: Lets say that 1GHz OPP is to be made available only if the
SoC temperature is lower than a certain threshold. The SoC framework
- implementation might choose to do something as follows:
+ implementation might choose to do something as follows::
+
if (cur_temp < temp_low_thresh) {
/* Enable 1GHz if it was disabled */
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
@@ -201,10 +225,12 @@ dev_pm_opp_enable - Make a OPP available for operation.
goto try_something_else;
}
-dev_pm_opp_disable - Make an OPP to be not available for operation
+dev_pm_opp_disable
+ Make an OPP to be not available for operation
Example: Lets say that 1GHz OPP is to be disabled if the temperature
exceeds a threshold value. The SoC framework implementation might
- choose to do something as follows:
+ choose to do something as follows::
+
if (cur_temp > temp_high_thresh) {
/* Disable 1GHz if it was enabled */
opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
@@ -223,11 +249,13 @@ information from the OPP structure is necessary. Once an OPP pointer is
retrieved using the search functions, the following functions can be used by SoC
framework to retrieve the information represented inside the OPP layer.
-dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
+dev_pm_opp_get_voltage
+ Retrieve the voltage represented by the opp pointer.
Example: At a cpufreq transition to a different frequency, SoC
framework requires to set the voltage represented by the OPP using
the regulator framework to the Power Management chip providing the
- voltage.
+ voltage::
+
soc_switch_to_freq_voltage(freq)
{
/* do things */
@@ -239,10 +267,12 @@ dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
/* do other things */
}
-dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
+dev_pm_opp_get_freq
+ Retrieve the freq represented by the opp pointer.
Example: Lets say the SoC framework uses a couple of helper functions
we could pass opp pointers instead of doing additional parameters to
- handle quiet a bit of data parameters.
+ handle quiet a bit of data parameters::
+
soc_cpufreq_target(..)
{
/* do things.. */
@@ -264,9 +294,11 @@ dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
/* do things.. */
}
-dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
+dev_pm_opp_get_opp_count
+ Retrieve the number of available opps for a device
Example: Lets say a co-processor in the SoC needs to know the available
- frequencies in a table, the main processor can notify as following:
+ frequencies in a table, the main processor can notify as following::
+
soc_notify_coproc_available_frequencies()
{
/* Do things */
@@ -289,54 +321,59 @@ dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
==================
Typically an SoC contains multiple voltage domains which are variable. Each
domain is represented by a device pointer. The relationship to OPP can be
-represented as follows:
-SoC
- |- device 1
- | |- opp 1 (availability, freq, voltage)
- | |- opp 2 ..
- ... ...
- | `- opp n ..
- |- device 2
- ...
- `- device m
+represented as follows::
+
+ SoC
+ |- device 1
+ | |- opp 1 (availability, freq, voltage)
+ | |- opp 2 ..
+ ... ...
+ | `- opp n ..
+ |- device 2
+ ...
+ `- device m
OPP library maintains a internal list that the SoC framework populates and
accessed by various functions as described above. However, the structures
representing the actual OPPs and domains are internal to the OPP library itself
to allow for suitable abstraction reusable across systems.
-struct dev_pm_opp - The internal data structure of OPP library which is used to
+struct dev_pm_opp
+ The internal data structure of OPP library which is used to
represent an OPP. In addition to the freq, voltage, availability
information, it also contains internal book keeping information required
for the OPP library to operate on. Pointer to this structure is
provided back to the users such as SoC framework to be used as a
identifier for OPP in the interactions with OPP layer.
- WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the
- users. The defaults of for an instance is populated by dev_pm_opp_add, but the
- availability of the OPP can be modified by dev_pm_opp_enable/disable functions.
+ WARNING:
+ The struct dev_pm_opp pointer should not be parsed or modified by the
+ users. The defaults of for an instance is populated by
+ dev_pm_opp_add, but the availability of the OPP can be modified
+ by dev_pm_opp_enable/disable functions.
-struct device - This is used to identify a domain to the OPP layer. The
+struct device
+ This is used to identify a domain to the OPP layer. The
nature of the device and it's implementation is left to the user of
OPP library such as the SoC framework.
Overall, in a simplistic view, the data structure operations is represented as
-following:
+following::
-Initialization / modification:
- +-----+ /- dev_pm_opp_enable
-dev_pm_opp_add --> | opp | <-------
- | +-----+ \- dev_pm_opp_disable
- \-------> domain_info(device)
+ Initialization / modification:
+ +-----+ /- dev_pm_opp_enable
+ dev_pm_opp_add --> | opp | <-------
+ | +-----+ \- dev_pm_opp_disable
+ \-------> domain_info(device)
-Search functions:
- /-- dev_pm_opp_find_freq_ceil ---\ +-----+
-domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
- \-- dev_pm_opp_find_freq_floor ---/ +-----+
+ Search functions:
+ /-- dev_pm_opp_find_freq_ceil ---\ +-----+
+ domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
+ \-- dev_pm_opp_find_freq_floor ---/ +-----+
-Retrieval functions:
-+-----+ /- dev_pm_opp_get_voltage
-| opp | <---
-+-----+ \- dev_pm_opp_get_freq
+ Retrieval functions:
+ +-----+ /- dev_pm_opp_get_voltage
+ | opp | <---
+ +-----+ \- dev_pm_opp_get_freq
-domain_info <- dev_pm_opp_get_opp_count
+ domain_info <- dev_pm_opp_get_opp_count
diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.rst
similarity index 97%
rename from Documentation/power/pci.txt
rename to Documentation/power/pci.rst
index 8eaf9ee24d43..0e2ef7429304 100644
--- a/Documentation/power/pci.txt
+++ b/Documentation/power/pci.rst
@@ -1,4 +1,6 @@
+====================
PCI Power Management
+====================
Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
@@ -9,14 +11,14 @@ management. Based on previous work by Patrick Mochel <mochel@transmeta.com>
This document only covers the aspects of power management specific to PCI
devices. For general description of the kernel's interfaces related to device
power management refer to Documentation/driver-api/pm/devices.rst and
-Documentation/power/runtime_pm.txt.
+Documentation/power/runtime_pm.rst.
----------------------------------------------------------------------------
+.. contents:
-1. Hardware and Platform Support for PCI Power Management
-2. PCI Subsystem and Device Power Management
-3. PCI Device Drivers and Power Management
-4. Resources
+ 1. Hardware and Platform Support for PCI Power Management
+ 2. PCI Subsystem and Device Power Management
+ 3. PCI Device Drivers and Power Management
+ 4. Resources
1. Hardware and Platform Support for PCI Power Management
@@ -24,6 +26,7 @@ Documentation/power/runtime_pm.txt.
1.1. Native and Platform-Based Power Management
-----------------------------------------------
+
In general, power management is a feature allowing one to save energy by putting
devices into states in which they draw less power (low-power states) at the
price of reduced functionality or performance.
@@ -67,6 +70,7 @@ mechanisms have to be used simultaneously to obtain the desired result.
1.2. Native PCI Power Management
--------------------------------
+
The PCI Bus Power Management Interface Specification (PCI PM Spec) was
introduced between the PCI 2.1 and PCI 2.2 Specifications. It defined a
standard interface for performing various operations related to power
@@ -134,6 +138,7 @@ sufficiently active to generate a wakeup signal.
1.3. ACPI Device Power Management
---------------------------------
+
The platform firmware support for the power management of PCI devices is
system-specific. However, if the system in question is compliant with the
Advanced Configuration and Power Interface (ACPI) Specification, like the
@@ -194,6 +199,7 @@ enabled for the device to be able to generate wakeup signals.
1.4. Wakeup Signaling
---------------------
+
Wakeup signals generated by PCI devices, either as native PCI PMEs, or as
a result of the execution of the _DSW (or _PSW) ACPI control method before
putting the device into a low-power state, have to be caught and handled as
@@ -265,14 +271,15 @@ the native PCI Express PME signaling cannot be used by the kernel in that case.
2.1. Device Power Management Callbacks
--------------------------------------
+
The PCI Subsystem participates in the power management of PCI devices in a
number of ways. First of all, it provides an intermediate code layer between
the device power management core (PM core) and PCI device drivers.
Specifically, the pm field of the PCI subsystem's struct bus_type object,
pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing
-pointers to several device power management callbacks:
+pointers to several device power management callbacks::
-const struct dev_pm_ops pci_dev_pm_ops = {
+ const struct dev_pm_ops pci_dev_pm_ops = {
.prepare = pci_pm_prepare,
.complete = pci_pm_complete,
.suspend = pci_pm_suspend,
@@ -290,7 +297,7 @@ const struct dev_pm_ops pci_dev_pm_ops = {
.runtime_suspend = pci_pm_runtime_suspend,
.runtime_resume = pci_pm_runtime_resume,
.runtime_idle = pci_pm_runtime_idle,
-};
+ };
These callbacks are executed by the PM core in various situations related to
device power management and they, in turn, execute power management callbacks
@@ -299,9 +306,9 @@ involving some standard configuration registers of PCI devices that device
drivers need not know or care about.
The structure representing a PCI device, struct pci_dev, contains several fields
-that these callbacks operate on:
+that these callbacks operate on::
-struct pci_dev {
+ struct pci_dev {
...
pci_power_t current_state; /* Current operating state. */
int pm_cap; /* PM capability offset in the
@@ -315,13 +322,14 @@ struct pci_dev {
unsigned int wakeup_prepared:1; /* Device prepared for wake up */
unsigned int d3_delay; /* D3->D0 transition time in ms */
...
-};
+ };
They also indirectly use some fields of the struct device that is embedded in
struct pci_dev.
2.2. Device Initialization
--------------------------
+
The PCI subsystem's first task related to device power management is to
prepare the device for power management and initialize the fields of struct
pci_dev used for this purpose. This happens in two functions defined in
@@ -348,10 +356,11 @@ during system-wide transitions to a sleep state and back to the working state.
2.3. Runtime Device Power Management
------------------------------------
+
The PCI subsystem plays a vital role in the runtime power management of PCI
devices. For this purpose it uses the general runtime power management
-(runtime PM) framework described in Documentation/power/runtime_pm.txt.
-Namely, it provides subsystem-level callbacks:
+(runtime PM) framework described in Documentation/power/runtime_pm.rst.
+Namely, it provides subsystem-level callbacks::
pci_pm_runtime_suspend()
pci_pm_runtime_resume()
@@ -425,13 +434,14 @@ to the given subsystem before the next phase begins. These phases always run
after tasks have been frozen.
2.4.1. System Suspend
+^^^^^^^^^^^^^^^^^^^^^
When the system is going into a sleep state in which the contents of memory will
be preserved, such as one of the ACPI sleep states S1-S3, the phases are:
prepare, suspend, suspend_noirq.
-The following PCI bus type's callbacks, respectively, are used in these phases:
+The following PCI bus type's callbacks, respectively, are used in these phases::
pci_pm_prepare()
pci_pm_suspend()
@@ -492,6 +502,7 @@ this purpose). PCI device drivers are not encouraged to do that, but in some
rare cases doing that in the driver may be the optimum approach.
2.4.2. System Resume
+^^^^^^^^^^^^^^^^^^^^
When the system is undergoing a transition from a sleep state in which the
contents of memory have been preserved, such as one of the ACPI sleep states
@@ -500,7 +511,7 @@ S1-S3, into the working state (ACPI S0), the phases are:
resume_noirq, resume, complete.
The following PCI bus type's callbacks, respectively, are executed in these
-phases:
+phases::
pci_pm_resume_noirq()
pci_pm_resume()
@@ -539,6 +550,7 @@ The pci_pm_complete() routine only executes the device driver's pm->complete()
callback, if defined.
2.4.3. System Hibernation
+^^^^^^^^^^^^^^^^^^^^^^^^^
System hibernation is more complicated than system suspend, because it requires
a system image to be created and written into a persistent storage medium. The
@@ -551,7 +563,7 @@ to be free) in the following three phases:
prepare, freeze, freeze_noirq
-that correspond to the PCI bus type's callbacks:
+that correspond to the PCI bus type's callbacks::
pci_pm_prepare()
pci_pm_freeze()
@@ -580,7 +592,7 @@ back to the fully functional state and this is done in the following phases:
thaw_noirq, thaw, complete
-using the following PCI bus type's callbacks:
+using the following PCI bus type's callbacks::
pci_pm_thaw_noirq()
pci_pm_thaw()
@@ -608,7 +620,7 @@ three phases:
where the prepare phase is exactly the same as for system suspend. The other
two phases are analogous to the suspend and suspend_noirq phases, respectively.
-The PCI subsystem-level callbacks they correspond to
+The PCI subsystem-level callbacks they correspond to::
pci_pm_poweroff()
pci_pm_poweroff_noirq()
@@ -618,6 +630,7 @@ although they don't attempt to save the device's standard configuration
registers.
2.4.4. System Restore
+^^^^^^^^^^^^^^^^^^^^^
System restore requires a hibernation image to be loaded into memory and the
pre-hibernation memory contents to be restored before the pre-hibernation system
@@ -653,7 +666,7 @@ phases:
The first two of these are analogous to the resume_noirq and resume phases
described above, respectively, and correspond to the following PCI subsystem
-callbacks:
+callbacks::
pci_pm_restore_noirq()
pci_pm_restore()
@@ -671,6 +684,7 @@ resume.
3.1. Power Management Callbacks
-------------------------------
+
PCI device drivers participate in power management by providing callbacks to be
executed by the PCI subsystem's power management routines described above and by
controlling the runtime power management of their devices.
@@ -698,6 +712,7 @@ defined, though, they are expected to behave as described in the following
subsections.
3.1.1. prepare()
+^^^^^^^^^^^^^^^^
The prepare() callback is executed during system suspend, during hibernation
(when a hibernation image is about to be created), during power-off after
@@ -716,6 +731,7 @@ preallocated earlier, for example in a suspend/hibernate notifier as described
in Documentation/driver-api/pm/notifiers.rst).
3.1.2. suspend()
+^^^^^^^^^^^^^^^^
The suspend() callback is only executed during system suspend, after prepare()
callbacks have been executed for all devices in the system.
@@ -742,6 +758,7 @@ operations relying on the driver's ability to handle interrupts should be
carried out in this callback.
3.1.3. suspend_noirq()
+^^^^^^^^^^^^^^^^^^^^^^
The suspend_noirq() callback is only executed during system suspend, after
suspend() callbacks have been executed for all devices in the system and
@@ -753,6 +770,7 @@ suspend_noirq() can carry out operations that would cause race conditions to
arise if they were performed in suspend().
3.1.4. freeze()
+^^^^^^^^^^^^^^^
The freeze() callback is hibernation-specific and is executed in two situations,
during hibernation, after prepare() callbacks have been executed for all devices
@@ -770,6 +788,7 @@ or put it into a low-power state. Still, either it or freeze_noirq() should
save the device's standard configuration registers using pci_save_state().
3.1.5. freeze_noirq()
+^^^^^^^^^^^^^^^^^^^^^
The freeze_noirq() callback is hibernation-specific. It is executed during
hibernation, after prepare() and freeze() callbacks have been executed for all
@@ -786,6 +805,7 @@ The difference between freeze_noirq() and freeze() is analogous to the
difference between suspend_noirq() and suspend().
3.1.6. poweroff()
+^^^^^^^^^^^^^^^^^
The poweroff() callback is hibernation-specific. It is executed when the system
is about to be powered off after saving a hibernation image to a persistent
@@ -802,6 +822,7 @@ into a low-power state, respectively, but it need not save the device's standard
configuration registers.
3.1.7. poweroff_noirq()
+^^^^^^^^^^^^^^^^^^^^^^^
The poweroff_noirq() callback is hibernation-specific. It is executed after
poweroff() callbacks have been executed for all devices in the system.
@@ -814,6 +835,7 @@ The difference between poweroff_noirq() and poweroff() is analogous to the
difference between suspend_noirq() and suspend().
3.1.8. resume_noirq()
+^^^^^^^^^^^^^^^^^^^^^
The resume_noirq() callback is only executed during system resume, after the
PM core has enabled the non-boot CPUs. The driver's interrupt handler will not
@@ -827,6 +849,7 @@ it should only be used for performing operations that would lead to race
conditions if carried out by resume().
3.1.9. resume()
+^^^^^^^^^^^^^^^
The resume() callback is only executed during system resume, after
resume_noirq() callbacks have been executed for all devices in the system and
@@ -837,6 +860,7 @@ device and bringing it back to the fully functional state. The device should be
able to process I/O in a usual way after resume() has returned.
3.1.10. thaw_noirq()
+^^^^^^^^^^^^^^^^^^^^
The thaw_noirq() callback is hibernation-specific. It is executed after a
system image has been created and the non-boot CPUs have been enabled by the PM
@@ -851,6 +875,7 @@ freeze() and freeze_noirq(), so in general it does not need to modify the
contents of the device's registers.
3.1.11. thaw()
+^^^^^^^^^^^^^^
The thaw() callback is hibernation-specific. It is executed after thaw_noirq()
callbacks have been executed for all devices in the system and after device
@@ -860,6 +885,7 @@ This callback is responsible for restoring the pre-freeze configuration of
the device, so that it will work in a usual way after thaw() has returned.
3.1.12. restore_noirq()
+^^^^^^^^^^^^^^^^^^^^^^^
The restore_noirq() callback is hibernation-specific. It is executed in the
restore_noirq phase of hibernation, when the boot kernel has passed control to
@@ -875,6 +901,7 @@ For the vast majority of PCI device drivers there is no difference between
resume_noirq() and restore_noirq().
3.1.13. restore()
+^^^^^^^^^^^^^^^^^
The restore() callback is hibernation-specific. It is executed after
restore_noirq() callbacks have been executed for all devices in the system and
@@ -888,14 +915,17 @@ For the vast majority of PCI device drivers there is no difference between
resume() and restore().
3.1.14. complete()
+^^^^^^^^^^^^^^^^^^
The complete() callback is executed in the following situations:
+
- during system resume, after resume() callbacks have been executed for all
devices,
- during hibernation, before saving the system image, after thaw() callbacks
have been executed for all devices,
- during system restore, when the system is going back to its pre-hibernation
state, after restore() callbacks have been executed for all devices.
+
It also may be executed if the loading of a hibernation image into memory fails
(in that case it is run after thaw() callbacks have been executed for all
devices that have drivers in the boot kernel).
@@ -904,6 +934,7 @@ This callback is entirely optional, although it may be necessary if the
prepare() callback performs operations that need to be reversed.
3.1.15. runtime_suspend()
+^^^^^^^^^^^^^^^^^^^^^^^^^
The runtime_suspend() callback is specific to device runtime power management
(runtime PM). It is executed by the PM core's runtime PM framework when the
@@ -915,6 +946,7 @@ put into a low-power state, but it must allow the PCI subsystem to perform all
of the PCI-specific actions necessary for suspending the device.
3.1.16. runtime_resume()
+^^^^^^^^^^^^^^^^^^^^^^^^
The runtime_resume() callback is specific to device runtime PM. It is executed
by the PM core's runtime PM framework when the device is about to be resumed
@@ -927,6 +959,7 @@ The device is expected to be able to process I/O in the usual way after
runtime_resume() has returned.
3.1.17. runtime_idle()
+^^^^^^^^^^^^^^^^^^^^^^
The runtime_idle() callback is specific to device runtime PM. It is executed
by the PM core's runtime PM framework whenever it may be desirable to suspend
@@ -939,6 +972,7 @@ PCI subsystem will call pm_runtime_suspend() for the device, which in turn will
cause the driver's runtime_suspend() callback to be executed.
3.1.18. Pointing Multiple Callback Pointers to One Routine
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Although in principle each of the callbacks described in the previous
subsections can be defined as a separate function, it often is convenient to
@@ -962,6 +996,7 @@ dev_pm_ops to indicate that one suspend routine is to be pointed to by the
be pointed to by the .resume(), .thaw(), and .restore() members.
3.1.19. Driver Flags for Power Management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The PM core allows device drivers to set flags that influence the handling of
power management for the devices by the core itself and by middle layer code
@@ -1007,6 +1042,7 @@ it.
3.2. Device Runtime Power Management
------------------------------------
+
In addition to providing device power management callbacks PCI device drivers
are responsible for controlling the runtime power management (runtime PM) of
their devices.
@@ -1073,22 +1109,27 @@ device the PM core automatically queues a request to check if the device is
idle), device drivers are generally responsible for queuing power management
requests for their devices. For this purpose they should use the runtime PM
helper functions provided by the PM core, discussed in
-Documentation/power/runtime_pm.txt.
+Documentation/power/runtime_pm.rst.
Devices can also be suspended and resumed synchronously, without placing a
request into pm_wq. In the majority of cases this also is done by their
drivers that use helper functions provided by the PM core for this purpose.
For more information on the runtime PM of devices refer to
-Documentation/power/runtime_pm.txt.
+Documentation/power/runtime_pm.rst.
4. Resources
============
PCI Local Bus Specification, Rev. 3.0
+
PCI Bus Power Management Interface Specification, Rev. 1.2
+
Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
+
PCI Express Base Specification, Rev. 2.0
+
Documentation/driver-api/pm/devices.rst
-Documentation/power/runtime_pm.txt
+
+Documentation/power/runtime_pm.rst
diff --git a/Documentation/power/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.rst
similarity index 62%
rename from Documentation/power/pm_qos_interface.txt
rename to Documentation/power/pm_qos_interface.rst
index 19c5f7b1a7ba..945fc6d760c9 100644
--- a/Documentation/power/pm_qos_interface.txt
+++ b/Documentation/power/pm_qos_interface.rst
@@ -1,4 +1,6 @@
-PM Quality Of Service Interface.
+===============================
+PM Quality Of Service Interface
+===============================
This interface provides a kernel and user mode interface for registering
performance expectations by drivers, subsystems and user space applications on
@@ -11,6 +13,7 @@ memory_bandwidth.
constraints and PM QoS flags.
Each parameters have defined units:
+
* latency: usec
* timeout: usec
* throughput: kbs (kilo bit / sec)
@@ -18,6 +21,7 @@ Each parameters have defined units:
1. PM QoS framework
+===================
The infrastructure exposes multiple misc device nodes one per implemented
parameter. The set of parameters implement is defined by pm_qos_power_init()
@@ -37,38 +41,39 @@ reading the aggregated value does not require any locking mechanism.
From kernel mode the use of this interface is simple:
void pm_qos_add_request(handle, param_class, target_value):
-Will insert an element into the list for that identified PM QoS class with the
-target value. Upon change to this list the new target is recomputed and any
-registered notifiers are called only if the target value is now different.
-Clients of pm_qos need to save the returned handle for future use in other
-pm_qos API functions.
+ Will insert an element into the list for that identified PM QoS class with the
+ target value. Upon change to this list the new target is recomputed and any
+ registered notifiers are called only if the target value is now different.
+ Clients of pm_qos need to save the returned handle for future use in other
+ pm_qos API functions.
void pm_qos_update_request(handle, new_target_value):
-Will update the list element pointed to by the handle with the new target value
-and recompute the new aggregated target, calling the notification tree if the
-target is changed.
+ Will update the list element pointed to by the handle with the new target value
+ and recompute the new aggregated target, calling the notification tree if the
+ target is changed.
void pm_qos_remove_request(handle):
-Will remove the element. After removal it will update the aggregate target and
-call the notification tree if the target was changed as a result of removing
-the request.
+ Will remove the element. After removal it will update the aggregate target and
+ call the notification tree if the target was changed as a result of removing
+ the request.
int pm_qos_request(param_class):
-Returns the aggregated value for a given PM QoS class.
+ Returns the aggregated value for a given PM QoS class.
int pm_qos_request_active(handle):
-Returns if the request is still active, i.e. it has not been removed from a
-PM QoS class constraints list.
+ Returns if the request is still active, i.e. it has not been removed from a
+ PM QoS class constraints list.
int pm_qos_add_notifier(param_class, notifier):
-Adds a notification callback function to the PM QoS class. The callback is
-called when the aggregated value for the PM QoS class is changed.
+ Adds a notification callback function to the PM QoS class. The callback is
+ called when the aggregated value for the PM QoS class is changed.
int pm_qos_remove_notifier(int param_class, notifier):
-Removes the notification callback function for the PM QoS class.
+ Removes the notification callback function for the PM QoS class.
From user mode:
+
Only processes can register a pm_qos request. To provide for automatic
cleanup of a process, the interface requires the process to register its
parameter requests in the following way:
@@ -89,6 +94,7 @@ node.
2. PM QoS per-device latency and flags framework
+================================================
For each device, there are three lists of PM QoS requests. Two of them are
maintained along with the aggregated targets of resume latency and active
@@ -107,73 +113,80 @@ the aggregated value does not require any locking mechanism.
From kernel mode the use of this interface is the following:
int dev_pm_qos_add_request(device, handle, type, value):
-Will insert an element into the list for that identified device with the
-target value. Upon change to this list the new target is recomputed and any
-registered notifiers are called only if the target value is now different.
-Clients of dev_pm_qos need to save the handle for future use in other
-dev_pm_qos API functions.
+ Will insert an element into the list for that identified device with the
+ target value. Upon change to this list the new target is recomputed and any
+ registered notifiers are called only if the target value is now different.
+ Clients of dev_pm_qos need to save the handle for future use in other
+ dev_pm_qos API functions.
int dev_pm_qos_update_request(handle, new_value):
-Will update the list element pointed to by the handle with the new target value
-and recompute the new aggregated target, calling the notification trees if the
-target is changed.
+ Will update the list element pointed to by the handle with the new target
+ value and recompute the new aggregated target, calling the notification
+ trees if the target is changed.
int dev_pm_qos_remove_request(handle):
-Will remove the element. After removal it will update the aggregate target and
-call the notification trees if the target was changed as a result of removing
-the request.
+ Will remove the element. After removal it will update the aggregate target
+ and call the notification trees if the target was changed as a result of
+ removing the request.
s32 dev_pm_qos_read_value(device):
-Returns the aggregated value for a given device's constraints list.
+ Returns the aggregated value for a given device's constraints list.
enum pm_qos_flags_status dev_pm_qos_flags(device, mask)
-Check PM QoS flags of the given device against the given mask of flags.
-The meaning of the return values is as follows:
- PM_QOS_FLAGS_ALL: All flags from the mask are set
- PM_QOS_FLAGS_SOME: Some flags from the mask are set
- PM_QOS_FLAGS_NONE: No flags from the mask are set
- PM_QOS_FLAGS_UNDEFINED: The device's PM QoS structure has not been
- initialized or the list of requests is empty.
+ Check PM QoS flags of the given device against the given mask of flags.
+ The meaning of the return values is as follows:
+
+ PM_QOS_FLAGS_ALL:
+ All flags from the mask are set
+ PM_QOS_FLAGS_SOME:
+ Some flags from the mask are set
+ PM_QOS_FLAGS_NONE:
+ No flags from the mask are set
+ PM_QOS_FLAGS_UNDEFINED:
+ The device's PM QoS structure has not been initialized
+ or the list of requests is empty.
int dev_pm_qos_add_ancestor_request(dev, handle, type, value)
-Add a PM QoS request for the first direct ancestor of the given device whose
-power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests)
-or whose power.set_latency_tolerance callback pointer is not NULL (for
-DEV_PM_QOS_LATENCY_TOLERANCE requests).
+ Add a PM QoS request for the first direct ancestor of the given device whose
+ power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests)
+ or whose power.set_latency_tolerance callback pointer is not NULL (for
+ DEV_PM_QOS_LATENCY_TOLERANCE requests).
int dev_pm_qos_expose_latency_limit(device, value)
-Add a request to the device's PM QoS list of resume latency constraints and
-create a sysfs attribute pm_qos_resume_latency_us under the device's power
-directory allowing user space to manipulate that request.
+ Add a request to the device's PM QoS list of resume latency constraints and
+ create a sysfs attribute pm_qos_resume_latency_us under the device's power
+ directory allowing user space to manipulate that request.
void dev_pm_qos_hide_latency_limit(device)
-Drop the request added by dev_pm_qos_expose_latency_limit() from the device's
-PM QoS list of resume latency constraints and remove sysfs attribute
-pm_qos_resume_latency_us from the device's power directory.
+ Drop the request added by dev_pm_qos_expose_latency_limit() from the device's
+ PM QoS list of resume latency constraints and remove sysfs attribute
+ pm_qos_resume_latency_us from the device's power directory.
int dev_pm_qos_expose_flags(device, value)
-Add a request to the device's PM QoS list of flags and create sysfs attribute
-pm_qos_no_power_off under the device's power directory allowing user space to
-change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.
+ Add a request to the device's PM QoS list of flags and create sysfs attribute
+ pm_qos_no_power_off under the device's power directory allowing user space to
+ change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.
void dev_pm_qos_hide_flags(device)
-Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list
-of flags and remove sysfs attribute pm_qos_no_power_off from the device's power
-directory.
+ Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list
+ of flags and remove sysfs attribute pm_qos_no_power_off from the device's power
+ directory.
Notification mechanisms:
+
The per-device PM QoS framework has a per-device notification tree.
int dev_pm_qos_add_notifier(device, notifier):
-Adds a notification callback function for the device.
-The callback is called when the aggregated value of the device constraints list
-is changed (for resume latency device PM QoS only).
+ Adds a notification callback function for the device.
+ The callback is called when the aggregated value of the device constraints list
+ is changed (for resume latency device PM QoS only).
int dev_pm_qos_remove_notifier(device, notifier):
-Removes the notification callback function for the device.
+ Removes the notification callback function for the device.
Active state latency tolerance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This device PM QoS type is used to support systems in which hardware may switch
to energy-saving operation modes on the fly. In those systems, if the operation
diff --git a/Documentation/power/power_supply_class.rst b/Documentation/power/power_supply_class.rst
new file mode 100644
index 000000000000..3f2c3fe38a61
--- /dev/null
+++ b/Documentation/power/power_supply_class.rst
@@ -0,0 +1,282 @@
+========================
+Linux power supply class
+========================
+
+Synopsis
+~~~~~~~~
+Power supply class used to represent battery, UPS, AC or DC power supply
+properties to user-space.
+
+It defines core set of attributes, which should be applicable to (almost)
+every power supply out there. Attributes are available via sysfs and uevent
+interfaces.
+
+Each attribute has well defined meaning, up to unit of measure used. While
+the attributes provided are believed to be universally applicable to any
+power supply, specific monitoring hardware may not be able to provide them
+all, so any of them may be skipped.
+
+Power supply class is extensible, and allows to define drivers own attributes.
+The core attribute set is subject to the standard Linux evolution (i.e.
+if it will be found that some attribute is applicable to many power supply
+types or their drivers, it can be added to the core set).
+
+It also integrates with LED framework, for the purpose of providing
+typically expected feedback of battery charging/fully charged status and
+AC/USB power supply online status. (Note that specific details of the
+indication (including whether to use it at all) are fully controllable by
+user and/or specific machine defaults, per design principles of LED
+framework).
+
+
+Attributes/properties
+~~~~~~~~~~~~~~~~~~~~~
+Power supply class has predefined set of attributes, this eliminates code
+duplication across drivers. Power supply class insist on reusing its
+predefined attributes *and* their units.
+
+So, userspace gets predictable set of attributes and their units for any
+kind of power supply, and can process/present them to a user in consistent
+manner. Results for different power supplies and machines are also directly
+comparable.
+
+See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
+for the example how to declare and handle attributes.
+
+
+Units
+~~~~~
+Quoting include/linux/power_supply.h:
+
+ All voltages, currents, charges, energies, time and temperatures in µV,
+ µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
+ stated. It's driver's job to convert its raw values to units in which
+ this class operates.
+
+
+Attributes/properties detailed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
++--------------------------------------------------------------------------+
+| **Charge/Energy/Capacity - how to not confuse** |
++--------------------------------------------------------------------------+
+| **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" |
+| of battery, this class distinguish these terms. Don't mix them!** |
+| |
+| - `CHARGE_*` |
+| attributes represents capacity in µAh only. |
+| - `ENERGY_*` |
+| attributes represents capacity in µWh only. |
+| - `CAPACITY` |
+| attribute represents capacity in *percents*, from 0 to 100. |
++--------------------------------------------------------------------------+
+
+Postfixes:
+
+_AVG
+ *hardware* averaged value, use it if your hardware is really able to
+ report averaged values.
+_NOW
+ momentary/instantaneous values.
+
+STATUS
+ this attribute represents operating status (charging, full,
+ discharging (i.e. powering a load), etc.). This corresponds to
+ `BATTERY_STATUS_*` values, as defined in battery.h.
+
+CHARGE_TYPE
+ batteries can typically charge at different rates.
+ This defines trickle and fast charges. For batteries that
+ are already charged or discharging, 'n/a' can be displayed (or
+ 'unknown', if the status is not known).
+
+AUTHENTIC
+ indicates the power supply (battery or charger) connected
+ to the platform is authentic(1) or non authentic(0).
+
+HEALTH
+ represents health of the battery, values corresponds to
+ POWER_SUPPLY_HEALTH_*, defined in battery.h.
+
+VOLTAGE_OCV
+ open circuit voltage of the battery.
+
+VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN
+ design values for maximal and minimal power supply voltages.
+ Maximal/minimal means values of voltages when battery considered
+ "full"/"empty" at normal conditions. Yes, there is no direct relation
+ between voltage and battery capacity, but some dumb
+ batteries use voltage for very approximated calculation of capacity.
+ Battery driver also can use this attribute just to inform userspace
+ about maximal and minimal voltage thresholds of a given battery.
+
+VOLTAGE_MAX, VOLTAGE_MIN
+ same as _DESIGN voltage values except that these ones should be used
+ if hardware could only guess (measure and retain) the thresholds of a
+ given power supply.
+
+VOLTAGE_BOOT
+ Reports the voltage measured during boot
+
+CURRENT_BOOT
+ Reports the current measured during boot
+
+CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
+ design charge values, when battery considered full/empty.
+
+ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
+ same as above but for energy.
+
+CHARGE_FULL, CHARGE_EMPTY
+ These attributes means "last remembered value of charge when battery
+ became full/empty". It also could mean "value of charge when battery
+ considered full/empty at given conditions (temperature, age)".
+ I.e. these attributes represents real thresholds, not design values.
+
+ENERGY_FULL, ENERGY_EMPTY
+ same as above but for energy.
+
+CHARGE_COUNTER
+ the current charge counter (in µAh). This could easily
+ be negative; there is no empty or full value. It is only useful for
+ relative, time-based measurements.
+
+PRECHARGE_CURRENT
+ the maximum charge current during precharge phase of charge cycle
+ (typically 20% of battery capacity).
+
+CHARGE_TERM_CURRENT
+ Charge termination current. The charge cycle terminates when battery
+ voltage is above recharge threshold, and charge current is below
+ this setting (typically 10% of battery capacity).
+
+CONSTANT_CHARGE_CURRENT
+ constant charge current programmed by charger.
+
+
+CONSTANT_CHARGE_CURRENT_MAX
+ maximum charge current supported by the power supply object.
+
+CONSTANT_CHARGE_VOLTAGE
+ constant charge voltage programmed by charger.
+CONSTANT_CHARGE_VOLTAGE_MAX
+ maximum charge voltage supported by the power supply object.
+
+INPUT_CURRENT_LIMIT
+ input current limit programmed by charger. Indicates
+ the current drawn from a charging source.
+
+CHARGE_CONTROL_LIMIT
+ current charge control limit setting
+CHARGE_CONTROL_LIMIT_MAX
+ maximum charge control limit setting
+
+CALIBRATE
+ battery or coulomb counter calibration status
+
+CAPACITY
+ capacity in percents.
+CAPACITY_ALERT_MIN
+ minimum capacity alert value in percents.
+CAPACITY_ALERT_MAX
+ maximum capacity alert value in percents.
+CAPACITY_LEVEL
+ capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*.
+
+TEMP
+ temperature of the power supply.
+TEMP_ALERT_MIN
+ minimum battery temperature alert.
+TEMP_ALERT_MAX
+ maximum battery temperature alert.
+TEMP_AMBIENT
+ ambient temperature.
+TEMP_AMBIENT_ALERT_MIN
+ minimum ambient temperature alert.
+TEMP_AMBIENT_ALERT_MAX
+ maximum ambient temperature alert.
+TEMP_MIN
+ minimum operatable temperature
+TEMP_MAX
+ maximum operatable temperature
+
+TIME_TO_EMPTY
+ seconds left for battery to be considered empty
+ (i.e. while battery powers a load)
+TIME_TO_FULL
+ seconds left for battery to be considered full
+ (i.e. while battery is charging)
+
+
+Battery <-> external power supply interaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Often power supplies are acting as supplies and supplicants at the same
+time. Batteries are good example. So, batteries usually care if they're
+externally powered or not.
+
+For that case, power supply class implements notification mechanism for
+batteries.
+
+External power supply (AC) lists supplicants (batteries) names in
+"supplied_to" struct member, and each power_supply_changed() call
+issued by external power supply will notify supplicants via
+external_power_changed callback.
+
+
+Devicetree battery characteristics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Drivers should call power_supply_get_battery_info() to obtain battery
+characteristics from a devicetree battery node, defined in
+Documentation/devicetree/bindings/power/supply/battery.txt. This is
+implemented in drivers/power/supply/bq27xxx_battery.c.
+
+Properties in struct power_supply_battery_info and their counterparts in the
+battery node have names corresponding to elements in enum power_supply_property,
+for naming consistency between sysfs attributes and battery node properties.
+
+
+QA
+~~
+
+Q:
+ Where is POWER_SUPPLY_PROP_XYZ attribute?
+A:
+ If you cannot find attribute suitable for your driver needs, feel free
+ to add it and send patch along with your driver.
+
+ The attributes available currently are the ones currently provided by the
+ drivers written.
+
+ Good candidates to add in future: model/part#, cycle_time, manufacturer,
+ etc.
+
+
+Q:
+ I have some very specific attribute (e.g. battery color), should I add
+ this attribute to standard ones?
+A:
+ Most likely, no. Such attribute can be placed in the driver itself, if
+ it is useful. Of course, if the attribute in question applicable to
+ large set of batteries, provided by many drivers, and/or comes from
+ some general battery specification/standard, it may be a candidate to
+ be added to the core attribute set.
+
+
+Q:
+ Suppose, my battery monitoring chip/firmware does not provides capacity
+ in percents, but provides charge_{now,full,empty}. Should I calculate
+ percentage capacity manually, inside the driver, and register CAPACITY
+ attribute? The same question about time_to_empty/time_to_full.
+A:
+ Most likely, no. This class is designed to export properties which are
+ directly measurable by the specific hardware available.
+
+ Inferring not available properties using some heuristics or mathematical
+ model is not subject of work for a battery driver. Such functionality
+ should be factored out, and in fact, apm_power, the driver to serve
+ legacy APM API on top of power supply class, uses a simple heuristic of
+ approximating remaining battery capacity based on its charge, current,
+ voltage and so on. But full-fledged battery model is likely not subject
+ for kernel at all, as it would require floating point calculation to deal
+ with things like differential equations and Kalman filters. This is
+ better be handled by batteryd/libbattery, yet to be written.
diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt
deleted file mode 100644
index 300d37896e51..000000000000
--- a/Documentation/power/power_supply_class.txt
+++ /dev/null
@@ -1,231 +0,0 @@
-Linux power supply class
-========================
-
-Synopsis
-~~~~~~~~
-Power supply class used to represent battery, UPS, AC or DC power supply
-properties to user-space.
-
-It defines core set of attributes, which should be applicable to (almost)
-every power supply out there. Attributes are available via sysfs and uevent
-interfaces.
-
-Each attribute has well defined meaning, up to unit of measure used. While
-the attributes provided are believed to be universally applicable to any
-power supply, specific monitoring hardware may not be able to provide them
-all, so any of them may be skipped.
-
-Power supply class is extensible, and allows to define drivers own attributes.
-The core attribute set is subject to the standard Linux evolution (i.e.
-if it will be found that some attribute is applicable to many power supply
-types or their drivers, it can be added to the core set).
-
-It also integrates with LED framework, for the purpose of providing
-typically expected feedback of battery charging/fully charged status and
-AC/USB power supply online status. (Note that specific details of the
-indication (including whether to use it at all) are fully controllable by
-user and/or specific machine defaults, per design principles of LED
-framework).
-
-
-Attributes/properties
-~~~~~~~~~~~~~~~~~~~~~
-Power supply class has predefined set of attributes, this eliminates code
-duplication across drivers. Power supply class insist on reusing its
-predefined attributes *and* their units.
-
-So, userspace gets predictable set of attributes and their units for any
-kind of power supply, and can process/present them to a user in consistent
-manner. Results for different power supplies and machines are also directly
-comparable.
-
-See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
-for the example how to declare and handle attributes.
-
-
-Units
-~~~~~
-Quoting include/linux/power_supply.h:
-
- All voltages, currents, charges, energies, time and temperatures in µV,
- µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
- stated. It's driver's job to convert its raw values to units in which
- this class operates.
-
-
-Attributes/properties detailed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-~ ~ ~ ~ ~ ~ ~ Charge/Energy/Capacity - how to not confuse ~ ~ ~ ~ ~ ~ ~
-~ ~
-~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity" ~
-~ of battery, this class distinguish these terms. Don't mix them! ~
-~ ~
-~ CHARGE_* attributes represents capacity in µAh only. ~
-~ ENERGY_* attributes represents capacity in µWh only. ~
-~ CAPACITY attribute represents capacity in *percents*, from 0 to 100. ~
-~ ~
-~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
-
-Postfixes:
-_AVG - *hardware* averaged value, use it if your hardware is really able to
-report averaged values.
-_NOW - momentary/instantaneous values.
-
-STATUS - this attribute represents operating status (charging, full,
-discharging (i.e. powering a load), etc.). This corresponds to
-BATTERY_STATUS_* values, as defined in battery.h.
-
-CHARGE_TYPE - batteries can typically charge at different rates.
-This defines trickle and fast charges. For batteries that
-are already charged or discharging, 'n/a' can be displayed (or
-'unknown', if the status is not known).
-
-AUTHENTIC - indicates the power supply (battery or charger) connected
-to the platform is authentic(1) or non authentic(0).
-
-HEALTH - represents health of the battery, values corresponds to
-POWER_SUPPLY_HEALTH_*, defined in battery.h.
-
-VOLTAGE_OCV - open circuit voltage of the battery.
-
-VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
-minimal power supply voltages. Maximal/minimal means values of voltages
-when battery considered "full"/"empty" at normal conditions. Yes, there is
-no direct relation between voltage and battery capacity, but some dumb
-batteries use voltage for very approximated calculation of capacity.
-Battery driver also can use this attribute just to inform userspace
-about maximal and minimal voltage thresholds of a given battery.
-
-VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
-these ones should be used if hardware could only guess (measure and
-retain) the thresholds of a given power supply.
-
-VOLTAGE_BOOT - Reports the voltage measured during boot
-
-CURRENT_BOOT - Reports the current measured during boot
-
-CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
-battery considered full/empty.
-
-ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
-
-CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
-of charge when battery became full/empty". It also could mean "value of
-charge when battery considered full/empty at given conditions (temperature,
-age)". I.e. these attributes represents real thresholds, not design values.
-
-ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
-
-CHARGE_COUNTER - the current charge counter (in µAh). This could easily
-be negative; there is no empty or full value. It is only useful for
-relative, time-based measurements.
-
-PRECHARGE_CURRENT - the maximum charge current during precharge phase
-of charge cycle (typically 20% of battery capacity).
-CHARGE_TERM_CURRENT - Charge termination current. The charge cycle
-terminates when battery voltage is above recharge threshold, and charge
-current is below this setting (typically 10% of battery capacity).
-
-CONSTANT_CHARGE_CURRENT - constant charge current programmed by charger.
-CONSTANT_CHARGE_CURRENT_MAX - maximum charge current supported by the
-power supply object.
-
-CONSTANT_CHARGE_VOLTAGE - constant charge voltage programmed by charger.
-CONSTANT_CHARGE_VOLTAGE_MAX - maximum charge voltage supported by the
-power supply object.
-
-INPUT_CURRENT_LIMIT - input current limit programmed by charger. Indicates
-the current drawn from a charging source.
-
-CHARGE_CONTROL_LIMIT - current charge control limit setting
-CHARGE_CONTROL_LIMIT_MAX - maximum charge control limit setting
-
-CALIBRATE - battery or coulomb counter calibration status
-
-CAPACITY - capacity in percents.
-CAPACITY_ALERT_MIN - minimum capacity alert value in percents.
-CAPACITY_ALERT_MAX - maximum capacity alert value in percents.
-CAPACITY_LEVEL - capacity level. This corresponds to
-POWER_SUPPLY_CAPACITY_LEVEL_*.
-
-TEMP - temperature of the power supply.
-TEMP_ALERT_MIN - minimum battery temperature alert.
-TEMP_ALERT_MAX - maximum battery temperature alert.
-TEMP_AMBIENT - ambient temperature.
-TEMP_AMBIENT_ALERT_MIN - minimum ambient temperature alert.
-TEMP_AMBIENT_ALERT_MAX - maximum ambient temperature alert.
-TEMP_MIN - minimum operatable temperature
-TEMP_MAX - maximum operatable temperature
-
-TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
-while battery powers a load)
-TIME_TO_FULL - seconds left for battery to be considered full (i.e.
-while battery is charging)
-
-
-Battery <-> external power supply interaction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Often power supplies are acting as supplies and supplicants at the same
-time. Batteries are good example. So, batteries usually care if they're
-externally powered or not.
-
-For that case, power supply class implements notification mechanism for
-batteries.
-
-External power supply (AC) lists supplicants (batteries) names in
-"supplied_to" struct member, and each power_supply_changed() call
-issued by external power supply will notify supplicants via
-external_power_changed callback.
-
-
-Devicetree battery characteristics
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Drivers should call power_supply_get_battery_info() to obtain battery
-characteristics from a devicetree battery node, defined in
-Documentation/devicetree/bindings/power/supply/battery.txt. This is
-implemented in drivers/power/supply/bq27xxx_battery.c.
-
-Properties in struct power_supply_battery_info and their counterparts in the
-battery node have names corresponding to elements in enum power_supply_property,
-for naming consistency between sysfs attributes and battery node properties.
-
-
-QA
-~~
-Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
-A: If you cannot find attribute suitable for your driver needs, feel free
- to add it and send patch along with your driver.
-
- The attributes available currently are the ones currently provided by the
- drivers written.
-
- Good candidates to add in future: model/part#, cycle_time, manufacturer,
- etc.
-
-
-Q: I have some very specific attribute (e.g. battery color), should I add
- this attribute to standard ones?
-A: Most likely, no. Such attribute can be placed in the driver itself, if
- it is useful. Of course, if the attribute in question applicable to
- large set of batteries, provided by many drivers, and/or comes from
- some general battery specification/standard, it may be a candidate to
- be added to the core attribute set.
-
-
-Q: Suppose, my battery monitoring chip/firmware does not provides capacity
- in percents, but provides charge_{now,full,empty}. Should I calculate
- percentage capacity manually, inside the driver, and register CAPACITY
- attribute? The same question about time_to_empty/time_to_full.
-A: Most likely, no. This class is designed to export properties which are
- directly measurable by the specific hardware available.
-
- Inferring not available properties using some heuristics or mathematical
- model is not subject of work for a battery driver. Such functionality
- should be factored out, and in fact, apm_power, the driver to serve
- legacy APM API on top of power supply class, uses a simple heuristic of
- approximating remaining battery capacity based on its charge, current,
- voltage and so on. But full-fledged battery model is likely not subject
- for kernel at all, as it would require floating point calculation to deal
- with things like differential equations and Kalman filters. This is
- better be handled by batteryd/libbattery, yet to be written.
diff --git a/Documentation/power/powercap/powercap.rst b/Documentation/power/powercap/powercap.rst
new file mode 100644
index 000000000000..7ae3b44c7624
--- /dev/null
+++ b/Documentation/power/powercap/powercap.rst
@@ -0,0 +1,257 @@
+=======================
+Power Capping Framework
+=======================
+
+The power capping framework provides a consistent interface between the kernel
+and the user space that allows power capping drivers to expose the settings to
+user space in a uniform way.
+
+Terminology
+===========
+
+The framework exposes power capping devices to user space via sysfs in the
+form of a tree of objects. The objects at the root level of the tree represent
+'control types', which correspond to different methods of power capping. For
+example, the intel-rapl control type represents the Intel "Running Average
+Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
+corresponds to the use of idle injection for controlling power.
+
+Power zones represent different parts of the system, which can be controlled and
+monitored using the power capping method determined by the control type the
+given zone belongs to. They each contain attributes for monitoring power, as
+well as controls represented in the form of power constraints. If the parts of
+the system represented by different power zones are hierarchical (that is, one
+bigger part consists of multiple smaller parts that each have their own power
+controls), those power zones may also be organized in a hierarchy with one
+parent power zone containing multiple subzones and so on to reflect the power
+control topology of the system. In that case, it is possible to apply power
+capping to a set of devices together using the parent power zone and if more
+fine grained control is required, it can be applied through the subzones.
+
+
+Example sysfs interface tree::
+
+ /sys/devices/virtual/powercap
+ └──intel-rapl
+ ├──intel-rapl:0
+ │ ├──constraint_0_name
+ │ ├──constraint_0_power_limit_uw
+ │ ├──constraint_0_time_window_us
+ │ ├──constraint_1_name
+ │ ├──constraint_1_power_limit_uw
+ │ ├──constraint_1_time_window_us
+ │ ├──device -> ../../intel-rapl
+ │ ├──energy_uj
+ │ ├──intel-rapl:0:0
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:0
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──intel-rapl:0:1
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:0
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──max_energy_range_uj
+ │ ├──max_power_range_uw
+ │ ├──name
+ │ ├──enabled
+ │ ├──power
+ │ │ ├──async
+ │ │ []
+ │ ├──subsystem -> ../../../../../class/power_cap
+ │ ├──enabled
+ │ ├──uevent
+ ├──intel-rapl:1
+ │ ├──constraint_0_name
+ │ ├──constraint_0_power_limit_uw
+ │ ├──constraint_0_time_window_us
+ │ ├──constraint_1_name
+ │ ├──constraint_1_power_limit_uw
+ │ ├──constraint_1_time_window_us
+ │ ├──device -> ../../intel-rapl
+ │ ├──energy_uj
+ │ ├──intel-rapl:1:0
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:1
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──intel-rapl:1:1
+ │ │ ├──constraint_0_name
+ │ │ ├──constraint_0_power_limit_uw
+ │ │ ├──constraint_0_time_window_us
+ │ │ ├──constraint_1_name
+ │ │ ├──constraint_1_power_limit_uw
+ │ │ ├──constraint_1_time_window_us
+ │ │ ├──device -> ../../intel-rapl:1
+ │ │ ├──energy_uj
+ │ │ ├──max_energy_range_uj
+ │ │ ├──name
+ │ │ ├──enabled
+ │ │ ├──power
+ │ │ │ ├──async
+ │ │ │ []
+ │ │ ├──subsystem -> ../../../../../../class/power_cap
+ │ │ └──uevent
+ │ ├──max_energy_range_uj
+ │ ├──max_power_range_uw
+ │ ├──name
+ │ ├──enabled
+ │ ├──power
+ │ │ ├──async
+ │ │ []
+ │ ├──subsystem -> ../../../../../class/power_cap
+ │ ├──uevent
+ ├──power
+ │ ├──async
+ │ []
+ ├──subsystem -> ../../../../class/power_cap
+ ├──enabled
+ └──uevent
+
+The above example illustrates a case in which the Intel RAPL technology,
+available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
+control type called intel-rapl which contains two power zones, intel-rapl:0 and
+intel-rapl:1, representing CPU packages. Each of these power zones contains
+two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
+"core" and the "uncore" parts of the given CPU package, respectively. All of
+the zones and subzones contain energy monitoring attributes (energy_uj,
+max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
+to be applied (the constraints in the 'package' power zones apply to the whole
+CPU packages and the subzone constraints only apply to the respective parts of
+the given package individually). Since Intel RAPL doesn't provide instantaneous
+power value, there is no power_uw attribute.
+
+In addition to that, each power zone contains a name attribute, allowing the
+part of the system represented by that zone to be identified.
+For example::
+
+ cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
+
+package-0
+---------
+
+The Intel RAPL technology allows two constraints, short term and long term,
+with two different time windows to be applied to each power zone. Thus for
+each zone there are 2 attributes representing the constraint names, 2 power
+limits and 2 attributes representing the sizes of the time windows. Such that,
+constraint_j_* attributes correspond to the jth constraint (j = 0,1).
+
+For example::
+
+ constraint_0_name
+ constraint_0_power_limit_uw
+ constraint_0_time_window_us
+ constraint_1_name
+ constraint_1_power_limit_uw
+ constraint_1_time_window_us
+
+Power Zone Attributes
+=====================
+
+Monitoring attributes
+---------------------
+
+energy_uj (rw)
+ Current energy counter in micro joules. Write "0" to reset.
+ If the counter can not be reset, then this attribute is read only.
+
+max_energy_range_uj (ro)
+ Range of the above energy counter in micro-joules.
+
+power_uw (ro)
+ Current power in micro watts.
+
+max_power_range_uw (ro)
+ Range of the above power value in micro-watts.
+
+name (ro)
+ Name of this power zone.
+
+It is possible that some domains have both power ranges and energy counter ranges;
+however, only one is mandatory.
+
+Constraints
+-----------
+
+constraint_X_power_limit_uw (rw)
+ Power limit in micro watts, which should be applicable for the
+ time window specified by "constraint_X_time_window_us".
+
+constraint_X_time_window_us (rw)
+ Time window in micro seconds.
+
+constraint_X_name (ro)
+ An optional name of the constraint
+
+constraint_X_max_power_uw(ro)
+ Maximum allowed power in micro watts.
+
+constraint_X_min_power_uw(ro)
+ Minimum allowed power in micro watts.
+
+constraint_X_max_time_window_us(ro)
+ Maximum allowed time window in micro seconds.
+
+constraint_X_min_time_window_us(ro)
+ Minimum allowed time window in micro seconds.
+
+Except power_limit_uw and time_window_us other fields are optional.
+
+Common zone and control type attributes
+---------------------------------------
+
+enabled (rw): Enable/Disable controls at zone level or for all zones using
+a control type.
+
+Power Cap Client Driver Interface
+=================================
+
+The API summary:
+
+Call powercap_register_control_type() to register control type object.
+Call powercap_register_zone() to register a power zone (under a given
+control type), either as a top-level power zone or as a subzone of another
+power zone registered earlier.
+The number of constraints in a power zone and the corresponding callbacks have
+to be defined prior to calling powercap_register_zone() to register that zone.
+
+To Free a power zone call powercap_unregister_zone().
+To free a control type object call powercap_unregister_control_type().
+Detailed API can be generated using kernel-doc on include/linux/powercap.h.
diff --git a/Documentation/power/powercap/powercap.txt b/Documentation/power/powercap/powercap.txt
deleted file mode 100644
index 1e6ef164e07a..000000000000
--- a/Documentation/power/powercap/powercap.txt
+++ /dev/null
@@ -1,236 +0,0 @@
-Power Capping Framework
-==================================
-
-The power capping framework provides a consistent interface between the kernel
-and the user space that allows power capping drivers to expose the settings to
-user space in a uniform way.
-
-Terminology
-=========================
-The framework exposes power capping devices to user space via sysfs in the
-form of a tree of objects. The objects at the root level of the tree represent
-'control types', which correspond to different methods of power capping. For
-example, the intel-rapl control type represents the Intel "Running Average
-Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
-corresponds to the use of idle injection for controlling power.
-
-Power zones represent different parts of the system, which can be controlled and
-monitored using the power capping method determined by the control type the
-given zone belongs to. They each contain attributes for monitoring power, as
-well as controls represented in the form of power constraints. If the parts of
-the system represented by different power zones are hierarchical (that is, one
-bigger part consists of multiple smaller parts that each have their own power
-controls), those power zones may also be organized in a hierarchy with one
-parent power zone containing multiple subzones and so on to reflect the power
-control topology of the system. In that case, it is possible to apply power
-capping to a set of devices together using the parent power zone and if more
-fine grained control is required, it can be applied through the subzones.
-
-
-Example sysfs interface tree:
-
-/sys/devices/virtual/powercap
-??? intel-rapl
- ??? intel-rapl:0
- ? ??? constraint_0_name
- ? ??? constraint_0_power_limit_uw
- ? ??? constraint_0_time_window_us
- ? ??? constraint_1_name
- ? ??? constraint_1_power_limit_uw
- ? ??? constraint_1_time_window_us
- ? ??? device -> ../../intel-rapl
- ? ??? energy_uj
- ? ??? intel-rapl:0:0
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:0
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? intel-rapl:0:1
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:0
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? max_energy_range_uj
- ? ??? max_power_range_uw
- ? ??? name
- ? ??? enabled
- ? ??? power
- ? ? ??? async
- ? ? []
- ? ??? subsystem -> ../../../../../class/power_cap
- ? ??? enabled
- ? ??? uevent
- ??? intel-rapl:1
- ? ??? constraint_0_name
- ? ??? constraint_0_power_limit_uw
- ? ??? constraint_0_time_window_us
- ? ??? constraint_1_name
- ? ??? constraint_1_power_limit_uw
- ? ??? constraint_1_time_window_us
- ? ??? device -> ../../intel-rapl
- ? ??? energy_uj
- ? ??? intel-rapl:1:0
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:1
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? intel-rapl:1:1
- ? ? ??? constraint_0_name
- ? ? ??? constraint_0_power_limit_uw
- ? ? ??? constraint_0_time_window_us
- ? ? ??? constraint_1_name
- ? ? ??? constraint_1_power_limit_uw
- ? ? ??? constraint_1_time_window_us
- ? ? ??? device -> ../../intel-rapl:1
- ? ? ??? energy_uj
- ? ? ??? max_energy_range_uj
- ? ? ??? name
- ? ? ??? enabled
- ? ? ??? power
- ? ? ? ??? async
- ? ? ? []
- ? ? ??? subsystem -> ../../../../../../class/power_cap
- ? ? ??? uevent
- ? ??? max_energy_range_uj
- ? ??? max_power_range_uw
- ? ??? name
- ? ??? enabled
- ? ??? power
- ? ? ??? async
- ? ? []
- ? ??? subsystem -> ../../../../../class/power_cap
- ? ??? uevent
- ??? power
- ? ??? async
- ? []
- ??? subsystem -> ../../../../class/power_cap
- ??? enabled
- ??? uevent
-
-The above example illustrates a case in which the Intel RAPL technology,
-available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
-control type called intel-rapl which contains two power zones, intel-rapl:0 and
-intel-rapl:1, representing CPU packages. Each of these power zones contains
-two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
-"core" and the "uncore" parts of the given CPU package, respectively. All of
-the zones and subzones contain energy monitoring attributes (energy_uj,
-max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
-to be applied (the constraints in the 'package' power zones apply to the whole
-CPU packages and the subzone constraints only apply to the respective parts of
-the given package individually). Since Intel RAPL doesn't provide instantaneous
-power value, there is no power_uw attribute.
-
-In addition to that, each power zone contains a name attribute, allowing the
-part of the system represented by that zone to be identified.
-For example:
-
-cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
-package-0
-
-The Intel RAPL technology allows two constraints, short term and long term,
-with two different time windows to be applied to each power zone. Thus for
-each zone there are 2 attributes representing the constraint names, 2 power
-limits and 2 attributes representing the sizes of the time windows. Such that,
-constraint_j_* attributes correspond to the jth constraint (j = 0,1).
-
-For example:
- constraint_0_name
- constraint_0_power_limit_uw
- constraint_0_time_window_us
- constraint_1_name
- constraint_1_power_limit_uw
- constraint_1_time_window_us
-
-Power Zone Attributes
-=================================
-Monitoring attributes
-----------------------
-
-energy_uj (rw): Current energy counter in micro joules. Write "0" to reset.
-If the counter can not be reset, then this attribute is read only.
-
-max_energy_range_uj (ro): Range of the above energy counter in micro-joules.
-
-power_uw (ro): Current power in micro watts.
-
-max_power_range_uw (ro): Range of the above power value in micro-watts.
-
-name (ro): Name of this power zone.
-
-It is possible that some domains have both power ranges and energy counter ranges;
-however, only one is mandatory.
-
-Constraints
-----------------
-constraint_X_power_limit_uw (rw): Power limit in micro watts, which should be
-applicable for the time window specified by "constraint_X_time_window_us".
-
-constraint_X_time_window_us (rw): Time window in micro seconds.
-
-constraint_X_name (ro): An optional name of the constraint
-
-constraint_X_max_power_uw(ro): Maximum allowed power in micro watts.
-
-constraint_X_min_power_uw(ro): Minimum allowed power in micro watts.
-
-constraint_X_max_time_window_us(ro): Maximum allowed time window in micro seconds.
-
-constraint_X_min_time_window_us(ro): Minimum allowed time window in micro seconds.
-
-Except power_limit_uw and time_window_us other fields are optional.
-
-Common zone and control type attributes
-----------------------------------------
-enabled (rw): Enable/Disable controls at zone level or for all zones using
-a control type.
-
-Power Cap Client Driver Interface
-==================================
-The API summary:
-
-Call powercap_register_control_type() to register control type object.
-Call powercap_register_zone() to register a power zone (under a given
-control type), either as a top-level power zone or as a subzone of another
-power zone registered earlier.
-The number of constraints in a power zone and the corresponding callbacks have
-to be defined prior to calling powercap_register_zone() to register that zone.
-
-To Free a power zone call powercap_unregister_zone().
-To free a control type object call powercap_unregister_control_type().
-Detailed API can be generated using kernel-doc on include/linux/powercap.h.
diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.rst
similarity index 61%
rename from Documentation/power/regulator/consumer.txt
rename to Documentation/power/regulator/consumer.rst
index e51564c1a140..0cd8cc1275a7 100644
--- a/Documentation/power/regulator/consumer.txt
+++ b/Documentation/power/regulator/consumer.rst
@@ -1,3 +1,4 @@
+===================================
Regulator Consumer Driver Interface
===================================
@@ -8,73 +9,77 @@ Please see overview.txt for a description of the terms used in this text.
1. Consumer Regulator Access (static & dynamic drivers)
=======================================================
-A consumer driver can get access to its supply regulator by calling :-
+A consumer driver can get access to its supply regulator by calling ::
-regulator = regulator_get(dev, "Vcc");
+ regulator = regulator_get(dev, "Vcc");
The consumer passes in its struct device pointer and power supply ID. The core
then finds the correct regulator by consulting a machine specific lookup table.
If the lookup is successful then this call will return a pointer to the struct
regulator that supplies this consumer.
-To release the regulator the consumer driver should call :-
+To release the regulator the consumer driver should call ::
-regulator_put(regulator);
+ regulator_put(regulator);
Consumers can be supplied by more than one regulator e.g. codec consumer with
-analog and digital supplies :-
+analog and digital supplies ::
-digital = regulator_get(dev, "Vcc"); /* digital core */
-analog = regulator_get(dev, "Avdd"); /* analog */
+ digital = regulator_get(dev, "Vcc"); /* digital core */
+ analog = regulator_get(dev, "Avdd"); /* analog */
The regulator access functions regulator_get() and regulator_put() will
usually be called in your device drivers probe() and remove() respectively.
2. Regulator Output Enable & Disable (static & dynamic drivers)
-====================================================================
+===============================================================
-A consumer can enable its power supply by calling:-
-int regulator_enable(regulator);
+A consumer can enable its power supply by calling::
-NOTE: The supply may already be enabled before regulator_enabled() is called.
-This may happen if the consumer shares the regulator or the regulator has been
-previously enabled by bootloader or kernel board initialization code.
+ int regulator_enable(regulator);
-A consumer can determine if a regulator is enabled by calling :-
+NOTE:
+ The supply may already be enabled before regulator_enabled() is called.
+ This may happen if the consumer shares the regulator or the regulator has been
+ previously enabled by bootloader or kernel board initialization code.
-int regulator_is_enabled(regulator);
+A consumer can determine if a regulator is enabled by calling::
+
+ int regulator_is_enabled(regulator);
This will return > zero when the regulator is enabled.
-A consumer can disable its supply when no longer needed by calling :-
+A consumer can disable its supply when no longer needed by calling::
-int regulator_disable(regulator);
+ int regulator_disable(regulator);
-NOTE: This may not disable the supply if it's shared with other consumers. The
-regulator will only be disabled when the enabled reference count is zero.
+NOTE:
+ This may not disable the supply if it's shared with other consumers. The
+ regulator will only be disabled when the enabled reference count is zero.
-Finally, a regulator can be forcefully disabled in the case of an emergency :-
+Finally, a regulator can be forcefully disabled in the case of an emergency::
-int regulator_force_disable(regulator);
+ int regulator_force_disable(regulator);
-NOTE: this will immediately and forcefully shutdown the regulator output. All
-consumers will be powered off.
+NOTE:
+ this will immediately and forcefully shutdown the regulator output. All
+ consumers will be powered off.
3. Regulator Voltage Control & Status (dynamic drivers)
-======================================================
+=======================================================
Some consumer drivers need to be able to dynamically change their supply
voltage to match system operating points. e.g. CPUfreq drivers can scale
voltage along with frequency to save power, SD drivers may need to select the
correct card voltage, etc.
-Consumers can control their supply voltage by calling :-
+Consumers can control their supply voltage by calling::
-int regulator_set_voltage(regulator, min_uV, max_uV);
+ int regulator_set_voltage(regulator, min_uV, max_uV);
Where min_uV and max_uV are the minimum and maximum acceptable voltages in
microvolts.
@@ -84,47 +89,50 @@ when enabled, then the voltage changes instantly, otherwise the voltage
configuration changes and the voltage is physically set when the regulator is
next enabled.
-The regulators configured voltage output can be found by calling :-
+The regulators configured voltage output can be found by calling::
-int regulator_get_voltage(regulator);
+ int regulator_get_voltage(regulator);
-NOTE: get_voltage() will return the configured output voltage whether the
-regulator is enabled or disabled and should NOT be used to determine regulator
-output state. However this can be used in conjunction with is_enabled() to
-determine the regulator physical output voltage.
+NOTE:
+ get_voltage() will return the configured output voltage whether the
+ regulator is enabled or disabled and should NOT be used to determine regulator
+ output state. However this can be used in conjunction with is_enabled() to
+ determine the regulator physical output voltage.
4. Regulator Current Limit Control & Status (dynamic drivers)
-===========================================================
+=============================================================
Some consumer drivers need to be able to dynamically change their supply
current limit to match system operating points. e.g. LCD backlight driver can
change the current limit to vary the backlight brightness, USB drivers may want
to set the limit to 500mA when supplying power.
-Consumers can control their supply current limit by calling :-
+Consumers can control their supply current limit by calling::
-int regulator_set_current_limit(regulator, min_uA, max_uA);
+ int regulator_set_current_limit(regulator, min_uA, max_uA);
Where min_uA and max_uA are the minimum and maximum acceptable current limit in
microamps.
-NOTE: this can be called when the regulator is enabled or disabled. If called
-when enabled, then the current limit changes instantly, otherwise the current
-limit configuration changes and the current limit is physically set when the
-regulator is next enabled.
+NOTE:
+ this can be called when the regulator is enabled or disabled. If called
+ when enabled, then the current limit changes instantly, otherwise the current
+ limit configuration changes and the current limit is physically set when the
+ regulator is next enabled.
-A regulators current limit can be found by calling :-
+A regulators current limit can be found by calling::
-int regulator_get_current_limit(regulator);
+ int regulator_get_current_limit(regulator);
-NOTE: get_current_limit() will return the current limit whether the regulator
-is enabled or disabled and should not be used to determine regulator current
-load.
+NOTE:
+ get_current_limit() will return the current limit whether the regulator
+ is enabled or disabled and should not be used to determine regulator current
+ load.
5. Regulator Operating Mode Control & Status (dynamic drivers)
-=============================================================
+==============================================================
Some consumers can further save system power by changing the operating mode of
their supply regulator to be more efficient when the consumers operating state
@@ -135,9 +143,9 @@ Regulator operating mode can be changed indirectly or directly.
Indirect operating mode control.
--------------------------------
Consumer drivers can request a change in their supply regulator operating mode
-by calling :-
+by calling::
-int regulator_set_load(struct regulator *regulator, int load_uA);
+ int regulator_set_load(struct regulator *regulator, int load_uA);
This will cause the core to recalculate the total load on the regulator (based
on all its consumers) and change operating mode (if necessary and permitted)
@@ -153,12 +161,13 @@ consumers.
Direct operating mode control.
------------------------------
+
Bespoke or tightly coupled drivers may want to directly control regulator
operating mode depending on their operating point. This can be achieved by
-calling :-
+calling::
-int regulator_set_mode(struct regulator *regulator, unsigned int mode);
-unsigned int regulator_get_mode(struct regulator *regulator);
+ int regulator_set_mode(struct regulator *regulator, unsigned int mode);
+ unsigned int regulator_get_mode(struct regulator *regulator);
Direct mode will only be used by consumers that *know* about the regulator and
are not sharing the regulator with other consumers.
@@ -166,24 +175,26 @@ are not sharing the regulator with other consumers.
6. Regulator Events
===================
+
Regulators can notify consumers of external events. Events could be received by
consumers under regulator stress or failure conditions.
-Consumers can register interest in regulator events by calling :-
+Consumers can register interest in regulator events by calling::
-int regulator_register_notifier(struct regulator *regulator,
- struct notifier_block *nb);
+ int regulator_register_notifier(struct regulator *regulator,
+ struct notifier_block *nb);
-Consumers can unregister interest by calling :-
+Consumers can unregister interest by calling::
-int regulator_unregister_notifier(struct regulator *regulator,
- struct notifier_block *nb);
+ int regulator_unregister_notifier(struct regulator *regulator,
+ struct notifier_block *nb);
Regulators use the kernel notifier framework to send event to their interested
consumers.
7. Regulator Direct Register Access
===================================
+
Some kinds of power management hardware or firmware are designed such that
they need to do low-level hardware access to regulators, with no involvement
from the kernel. Examples of such devices are:
@@ -199,20 +210,20 @@ to it. The regulator framework provides the following helpers for querying
these details.
Bus-specific details, like I2C addresses or transfer rates are handled by the
-regmap framework. To get the regulator's regmap (if supported), use :-
+regmap framework. To get the regulator's regmap (if supported), use::
-struct regmap *regulator_get_regmap(struct regulator *regulator);
+ struct regmap *regulator_get_regmap(struct regulator *regulator);
To obtain the hardware register offset and bitmask for the regulator's voltage
-selector register, use :-
+selector register, use::
-int regulator_get_hardware_vsel_register(struct regulator *regulator,
- unsigned *vsel_reg,
- unsigned *vsel_mask);
+ int regulator_get_hardware_vsel_register(struct regulator *regulator,
+ unsigned *vsel_reg,
+ unsigned *vsel_mask);
To convert a regulator framework voltage selector code (used by
regulator_list_voltage) to a hardware-specific voltage selector that can be
-directly written to the voltage selector register, use :-
+directly written to the voltage selector register, use::
-int regulator_list_hardware_vsel(struct regulator *regulator,
- unsigned selector);
+ int regulator_list_hardware_vsel(struct regulator *regulator,
+ unsigned selector);
diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.rst
similarity index 86%
rename from Documentation/power/regulator/design.txt
rename to Documentation/power/regulator/design.rst
index fdd919b96830..3b09c6841dc4 100644
--- a/Documentation/power/regulator/design.txt
+++ b/Documentation/power/regulator/design.rst
@@ -1,3 +1,4 @@
+==========================
Regulator API design notes
==========================
@@ -14,7 +15,9 @@ Safety
have different power requirements, and not all components with power
requirements are visible to software.
- => The API should make no changes to the hardware state unless it has
+.. note::
+
+ The API should make no changes to the hardware state unless it has
specific knowledge that these changes are safe to perform on this
particular system.
@@ -28,6 +31,8 @@ Consumer use cases
- Many of the power supplies in the system will be shared between many
different consumers.
- => The consumer API should be structured so that these use cases are
+.. note::
+
+ The consumer API should be structured so that these use cases are
very easy to handle and so that consumers will work with shared
supplies without any additional effort.
diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.rst
similarity index 75%
rename from Documentation/power/regulator/machine.txt
rename to Documentation/power/regulator/machine.rst
index eff4dcaaa252..22fffefaa3ad 100644
--- a/Documentation/power/regulator/machine.txt
+++ b/Documentation/power/regulator/machine.rst
@@ -1,10 +1,11 @@
+==================================
Regulator Machine Driver Interface
-===================================
+==================================
The regulator machine driver interface is intended for board/machine specific
initialisation code to configure the regulator subsystem.
-Consider the following machine :-
+Consider the following machine::
Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
|
@@ -13,31 +14,31 @@ Consider the following machine :-
The drivers for consumers A & B must be mapped to the correct regulator in
order to control their power supplies. This mapping can be achieved in machine
initialisation code by creating a struct regulator_consumer_supply for
-each regulator.
+each regulator::
-struct regulator_consumer_supply {
+ struct regulator_consumer_supply {
const char *dev_name; /* consumer dev_name() */
const char *supply; /* consumer supply - e.g. "vcc" */
-};
+ };
-e.g. for the machine above
+e.g. for the machine above::
-static struct regulator_consumer_supply regulator1_consumers[] = {
+ static struct regulator_consumer_supply regulator1_consumers[] = {
REGULATOR_SUPPLY("Vcc", "consumer B"),
-};
+ };
-static struct regulator_consumer_supply regulator2_consumers[] = {
+ static struct regulator_consumer_supply regulator2_consumers[] = {
REGULATOR_SUPPLY("Vcc", "consumer A"),
-};
+ };
This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
to the 'Vcc' supply for Consumer A.
Constraints can now be registered by defining a struct regulator_init_data
for each regulator power domain. This structure also maps the consumers
-to their supply regulators :-
+to their supply regulators::
-static struct regulator_init_data regulator1_data = {
+ static struct regulator_init_data regulator1_data = {
.constraints = {
.name = "Regulator-1",
.min_uV = 3300000,
@@ -46,7 +47,7 @@ static struct regulator_init_data regulator1_data = {
},
.num_consumer_supplies = ARRAY_SIZE(regulator1_consumers),
.consumer_supplies = regulator1_consumers,
-};
+ };
The name field should be set to something that is usefully descriptive
for the board for configuration of supplies for other regulators and
@@ -57,9 +58,9 @@ name is provided then the subsystem will choose one.
Regulator-1 supplies power to Regulator-2. This relationship must be registered
with the core so that Regulator-1 is also enabled when Consumer A enables its
supply (Regulator-2). The supply regulator is set by the supply_regulator
-field below and co:-
+field below and co::
-static struct regulator_init_data regulator2_data = {
+ static struct regulator_init_data regulator2_data = {
.supply_regulator = "Regulator-1",
.constraints = {
.min_uV = 1800000,
@@ -69,11 +70,11 @@ static struct regulator_init_data regulator2_data = {
},
.num_consumer_supplies = ARRAY_SIZE(regulator2_consumers),
.consumer_supplies = regulator2_consumers,
-};
+ };
-Finally the regulator devices must be registered in the usual manner.
+Finally the regulator devices must be registered in the usual manner::
-static struct platform_device regulator_devices[] = {
+ static struct platform_device regulator_devices[] = {
{
.name = "regulator",
.id = DCDC_1,
@@ -88,9 +89,9 @@ static struct platform_device regulator_devices[] = {
.platform_data = ®ulator2_data,
},
},
-};
-/* register regulator 1 device */
-platform_device_register(®ulator_devices[0]);
+ };
+ /* register regulator 1 device */
+ platform_device_register(®ulator_devices[0]);
-/* register regulator 2 device */
-platform_device_register(®ulator_devices[1]);
+ /* register regulator 2 device */
+ platform_device_register(®ulator_devices[1]);
diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.rst
similarity index 79%
rename from Documentation/power/regulator/overview.txt
rename to Documentation/power/regulator/overview.rst
index 721b4739ec32..ee494c70a7c4 100644
--- a/Documentation/power/regulator/overview.txt
+++ b/Documentation/power/regulator/overview.rst
@@ -1,3 +1,4 @@
+=============================================
Linux voltage and current regulator framework
=============================================
@@ -13,26 +14,30 @@ regulators (where voltage output is controllable) and current sinks (where
current limit is controllable).
(C) 2008 Wolfson Microelectronics PLC.
+
Author: Liam Girdwood <lrg@slimlogic.co.uk>
Nomenclature
============
-Some terms used in this document:-
+Some terms used in this document:
- o Regulator - Electronic device that supplies power to other devices.
+ - Regulator
+ - Electronic device that supplies power to other devices.
Most regulators can enable and disable their output while
some can control their output voltage and or current.
Input Voltage -> Regulator -> Output Voltage
- o PMIC - Power Management IC. An IC that contains numerous regulators
- and often contains other subsystems.
+ - PMIC
+ - Power Management IC. An IC that contains numerous
+ regulators and often contains other subsystems.
- o Consumer - Electronic device that is supplied power by a regulator.
+ - Consumer
+ - Electronic device that is supplied power by a regulator.
Consumers can be classified into two types:-
Static: consumer does not change its supply voltage or
@@ -44,46 +49,48 @@ Some terms used in this document:-
current limit to meet operation demands.
- o Power Domain - Electronic circuit that is supplied its input power by the
+ - Power Domain
+ - Electronic circuit that is supplied its input power by the
output power of a regulator, switch or by another power
domain.
- The supply regulator may be behind a switch(s). i.e.
+ The supply regulator may be behind a switch(s). i.e.::
- Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
- | |
- | +-> [Consumer B], [Consumer C]
- |
- +-> [Consumer D], [Consumer E]
+ Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
+ | |
+ | +-> [Consumer B], [Consumer C]
+ |
+ +-> [Consumer D], [Consumer E]
That is one regulator and three power domains:
- Domain 1: Switch-1, Consumers D & E.
- Domain 2: Switch-2, Consumers B & C.
- Domain 3: Consumer A.
+ - Domain 1: Switch-1, Consumers D & E.
+ - Domain 2: Switch-2, Consumers B & C.
+ - Domain 3: Consumer A.
and this represents a "supplies" relationship:
Domain-1 --> Domain-2 --> Domain-3.
A power domain may have regulators that are supplied power
- by other regulators. i.e.
+ by other regulators. i.e.::
- Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
- |
- +-> [Consumer B]
+ Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
+ |
+ +-> [Consumer B]
This gives us two regulators and two power domains:
- Domain 1: Regulator-2, Consumer B.
- Domain 2: Consumer A.
+ - Domain 1: Regulator-2, Consumer B.
+ - Domain 2: Consumer A.
and a "supplies" relationship:
Domain-1 --> Domain-2
- o Constraints - Constraints are used to define power levels for performance
+ - Constraints
+ - Constraints are used to define power levels for performance
and hardware protection. Constraints exist at three levels:
Regulator Level: This is defined by the regulator hardware
@@ -141,7 +148,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
limit. This also compiles out if not in use so drivers can be reused in
systems with no regulator based power control.
- See Documentation/power/regulator/consumer.txt
+ See Documentation/power/regulator/consumer.rst
2. Regulator driver interface.
@@ -149,7 +156,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
operations to the core. It also has a notifier call chain for propagating
regulator events to clients.
- See Documentation/power/regulator/regulator.txt
+ See Documentation/power/regulator/regulator.rst
3. Machine interface.
@@ -160,7 +167,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
allows the creation of a regulator tree whereby some regulators are
supplied by others (similar to a clock tree).
- See Documentation/power/regulator/machine.txt
+ See Documentation/power/regulator/machine.rst
4. Userspace ABI.
diff --git a/Documentation/power/regulator/regulator.rst b/Documentation/power/regulator/regulator.rst
new file mode 100644
index 000000000000..794b3256fbb9
--- /dev/null
+++ b/Documentation/power/regulator/regulator.rst
@@ -0,0 +1,32 @@
+==========================
+Regulator Driver Interface
+==========================
+
+The regulator driver interface is relatively simple and designed to allow
+regulator drivers to register their services with the core framework.
+
+
+Registration
+============
+
+Drivers can register a regulator by calling::
+
+ struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
+ const struct regulator_config *config);
+
+This will register the regulator's capabilities and operations to the regulator
+core.
+
+Regulators can be unregistered by calling::
+
+ void regulator_unregister(struct regulator_dev *rdev);
+
+
+Regulator Events
+================
+
+Regulators can send events (e.g. overtemperature, undervoltage, etc) to
+consumer drivers by calling::
+
+ int regulator_notifier_call_chain(struct regulator_dev *rdev,
+ unsigned long event, void *data);
diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt
deleted file mode 100644
index b17e5833ce21..000000000000
--- a/Documentation/power/regulator/regulator.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Regulator Driver Interface
-==========================
-
-The regulator driver interface is relatively simple and designed to allow
-regulator drivers to register their services with the core framework.
-
-
-Registration
-============
-
-Drivers can register a regulator by calling :-
-
-struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
- const struct regulator_config *config);
-
-This will register the regulator's capabilities and operations to the regulator
-core.
-
-Regulators can be unregistered by calling :-
-
-void regulator_unregister(struct regulator_dev *rdev);
-
-
-Regulator Events
-================
-Regulators can send events (e.g. overtemperature, undervoltage, etc) to
-consumer drivers by calling :-
-
-int regulator_notifier_call_chain(struct regulator_dev *rdev,
- unsigned long event, void *data);
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.rst
similarity index 89%
rename from Documentation/power/runtime_pm.txt
rename to Documentation/power/runtime_pm.rst
index 937e33c46211..2c2ec99b5088 100644
--- a/Documentation/power/runtime_pm.txt
+++ b/Documentation/power/runtime_pm.rst
@@ -1,10 +1,15 @@
+==================================================
Runtime Power Management Framework for I/O Devices
+==================================================
(C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
+
(C) 2010 Alan Stern <stern@rowland.harvard.edu>
+
(C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
1. Introduction
+===============
Support for runtime power management (runtime PM) of I/O devices is provided
at the power management core (PM core) level by means of:
@@ -33,16 +38,17 @@ fields of 'struct dev_pm_info' and the core helper functions provided for
runtime PM are described below.
2. Device Runtime PM Callbacks
+==============================
-There are three device runtime PM callbacks defined in 'struct dev_pm_ops':
+There are three device runtime PM callbacks defined in 'struct dev_pm_ops'::
-struct dev_pm_ops {
+ struct dev_pm_ops {
...
int (*runtime_suspend)(struct device *dev);
int (*runtime_resume)(struct device *dev);
int (*runtime_idle)(struct device *dev);
...
-};
+ };
The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks
are executed by the PM core for the device's subsystem that may be either of
@@ -112,7 +118,7 @@ low-power state during the execution of the suspend callback, it is expected
that remote wakeup will be enabled for the device. Generally, remote wakeup
should be enabled for all input devices put into low-power states at run time.
-The subsystem-level resume callback, if present, is _entirely_ _responsible_ for
+The subsystem-level resume callback, if present, is **entirely responsible** for
handling the resume of the device as appropriate, which may, but need not
include executing the device driver's own ->runtime_resume() callback (from the
PM core's point of view it is not necessary to implement a ->runtime_resume()
@@ -197,95 +203,96 @@ rules:
except for scheduled autosuspends.
3. Runtime PM Device Fields
+===========================
The following device runtime PM fields are present in 'struct dev_pm_info', as
defined in include/linux/pm.h:
- struct timer_list suspend_timer;
+ `struct timer_list suspend_timer;`
- timer used for scheduling (delayed) suspend and autosuspend requests
- unsigned long timer_expires;
+ `unsigned long timer_expires;`
- timer expiration time, in jiffies (if this is different from zero, the
timer is running and will expire at that time, otherwise the timer is not
running)
- struct work_struct work;
+ `struct work_struct work;`
- work structure used for queuing up requests (i.e. work items in pm_wq)
- wait_queue_head_t wait_queue;
+ `wait_queue_head_t wait_queue;`
- wait queue used if any of the helper functions needs to wait for another
one to complete
- spinlock_t lock;
+ `spinlock_t lock;`
- lock used for synchronization
- atomic_t usage_count;
+ `atomic_t usage_count;`
- the usage counter of the device
- atomic_t child_count;
+ `atomic_t child_count;`
- the count of 'active' children of the device
- unsigned int ignore_children;
+ `unsigned int ignore_children;`
- if set, the value of child_count is ignored (but still updated)
- unsigned int disable_depth;
+ `unsigned int disable_depth;`
- used for disabling the helper functions (they work normally if this is
equal to zero); the initial value of it is 1 (i.e. runtime PM is
initially disabled for all devices)
- int runtime_error;
+ `int runtime_error;`
- if set, there was a fatal error (one of the callbacks returned error code
as described in Section 2), so the helper functions will not work until
this flag is cleared; this is the error code returned by the failing
callback
- unsigned int idle_notification;
+ `unsigned int idle_notification;`
- if set, ->runtime_idle() is being executed
- unsigned int request_pending;
+ `unsigned int request_pending;`
- if set, there's a pending request (i.e. a work item queued up into pm_wq)
- enum rpm_request request;
+ `enum rpm_request request;`
- type of request that's pending (valid if request_pending is set)
- unsigned int deferred_resume;
+ `unsigned int deferred_resume;`
- set if ->runtime_resume() is about to be run while ->runtime_suspend() is
being executed for that device and it is not practical to wait for the
suspend to complete; means "start a resume as soon as you've suspended"
- enum rpm_status runtime_status;
+ `enum rpm_status runtime_status;`
- the runtime PM status of the device; this field's initial value is
RPM_SUSPENDED, which means that each device is initially regarded by the
PM core as 'suspended', regardless of its real hardware status
- unsigned int runtime_auto;
+ `unsigned int runtime_auto;`
- if set, indicates that the user space has allowed the device driver to
power manage the device at run time via the /sys/devices/.../power/control
- interface; it may only be modified with the help of the pm_runtime_allow()
+ `interface;` it may only be modified with the help of the pm_runtime_allow()
and pm_runtime_forbid() helper functions
- unsigned int no_callbacks;
+ `unsigned int no_callbacks;`
- indicates that the device does not use the runtime PM callbacks (see
Section 8); it may be modified only by the pm_runtime_no_callbacks()
helper function
- unsigned int irq_safe;
+ `unsigned int irq_safe;`
- indicates that the ->runtime_suspend() and ->runtime_resume() callbacks
will be invoked with the spinlock held and interrupts disabled
- unsigned int use_autosuspend;
+ `unsigned int use_autosuspend;`
- indicates that the device's driver supports delayed autosuspend (see
Section 9); it may be modified only by the
pm_runtime{_dont}_use_autosuspend() helper functions
- unsigned int timer_autosuspends;
+ `unsigned int timer_autosuspends;`
- indicates that the PM core should attempt to carry out an autosuspend
when the timer expires rather than a normal suspend
- int autosuspend_delay;
+ `int autosuspend_delay;`
- the delay time (in milliseconds) to be used for autosuspend
- unsigned long last_busy;
+ `unsigned long last_busy;`
- the time (in jiffies) when the pm_runtime_mark_last_busy() helper
function was last called for this device; used in calculating inactivity
periods for autosuspend
@@ -293,37 +300,38 @@ defined in include/linux/pm.h:
All of the above fields are members of the 'power' member of 'struct device'.
4. Runtime PM Device Helper Functions
+=====================================
The following runtime PM helper functions are defined in
drivers/base/power/runtime.c and include/linux/pm_runtime.h:
- void pm_runtime_init(struct device *dev);
+ `void pm_runtime_init(struct device *dev);`
- initialize the device runtime PM fields in 'struct dev_pm_info'
- void pm_runtime_remove(struct device *dev);
+ `void pm_runtime_remove(struct device *dev);`
- make sure that the runtime PM of the device will be disabled after
removing the device from device hierarchy
- int pm_runtime_idle(struct device *dev);
+ `int pm_runtime_idle(struct device *dev);`
- execute the subsystem-level idle callback for the device; returns an
error code on failure, where -EINPROGRESS means that ->runtime_idle() is
already being executed; if there is no callback or the callback returns 0
then run pm_runtime_autosuspend(dev) and return its result
- int pm_runtime_suspend(struct device *dev);
+ `int pm_runtime_suspend(struct device *dev);`
- execute the subsystem-level suspend callback for the device; returns 0 on
success, 1 if the device's runtime PM status was already 'suspended', or
error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt
to suspend the device again in future and -EACCES means that
'power.disable_depth' is different from 0
- int pm_runtime_autosuspend(struct device *dev);
+ `int pm_runtime_autosuspend(struct device *dev);`
- same as pm_runtime_suspend() except that the autosuspend delay is taken
- into account; if pm_runtime_autosuspend_expiration() says the delay has
+ `into account;` if pm_runtime_autosuspend_expiration() says the delay has
not yet expired then an autosuspend is scheduled for the appropriate time
and 0 is returned
- int pm_runtime_resume(struct device *dev);
+ `int pm_runtime_resume(struct device *dev);`
- execute the subsystem-level resume callback for the device; returns 0 on
success, 1 if the device's runtime PM status was already 'active' or
error code on failure, where -EAGAIN means it may be safe to attempt to
@@ -331,17 +339,17 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
checked additionally, and -EACCES means that 'power.disable_depth' is
different from 0
- int pm_request_idle(struct device *dev);
+ `int pm_request_idle(struct device *dev);`
- submit a request to execute the subsystem-level idle callback for the
device (the request is represented by a work item in pm_wq); returns 0 on
success or error code if the request has not been queued up
- int pm_request_autosuspend(struct device *dev);
+ `int pm_request_autosuspend(struct device *dev);`
- schedule the execution of the subsystem-level suspend callback for the
device when the autosuspend delay has expired; if the delay has already
expired then the work item is queued up immediately
- int pm_schedule_suspend(struct device *dev, unsigned int delay);
+ `int pm_schedule_suspend(struct device *dev, unsigned int delay);`
- schedule the execution of the subsystem-level suspend callback for the
device in future, where 'delay' is the time to wait before queuing up a
suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work
@@ -351,58 +359,58 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
->runtime_suspend() is already scheduled and not yet expired, the new
value of 'delay' will be used as the time to wait
- int pm_request_resume(struct device *dev);
+ `int pm_request_resume(struct device *dev);`
- submit a request to execute the subsystem-level resume callback for the
device (the request is represented by a work item in pm_wq); returns 0 on
success, 1 if the device's runtime PM status was already 'active', or
error code if the request hasn't been queued up
- void pm_runtime_get_noresume(struct device *dev);
+ `void pm_runtime_get_noresume(struct device *dev);`
- increment the device's usage counter
- int pm_runtime_get(struct device *dev);
+ `int pm_runtime_get(struct device *dev);`
- increment the device's usage counter, run pm_request_resume(dev) and
return its result
- int pm_runtime_get_sync(struct device *dev);
+ `int pm_runtime_get_sync(struct device *dev);`
- increment the device's usage counter, run pm_runtime_resume(dev) and
return its result
- int pm_runtime_get_if_in_use(struct device *dev);
+ `int pm_runtime_get_if_in_use(struct device *dev);`
- return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
runtime PM status is RPM_ACTIVE and the runtime PM usage counter is
nonzero, increment the counter and return 1; otherwise return 0 without
changing the counter
- void pm_runtime_put_noidle(struct device *dev);
+ `void pm_runtime_put_noidle(struct device *dev);`
- decrement the device's usage counter
- int pm_runtime_put(struct device *dev);
+ `int pm_runtime_put(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_request_idle(dev) and return its result
- int pm_runtime_put_autosuspend(struct device *dev);
+ `int pm_runtime_put_autosuspend(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_request_autosuspend(dev) and return its result
- int pm_runtime_put_sync(struct device *dev);
+ `int pm_runtime_put_sync(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_runtime_idle(dev) and return its result
- int pm_runtime_put_sync_suspend(struct device *dev);
+ `int pm_runtime_put_sync_suspend(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_runtime_suspend(dev) and return its result
- int pm_runtime_put_sync_autosuspend(struct device *dev);
+ `int pm_runtime_put_sync_autosuspend(struct device *dev);`
- decrement the device's usage counter; if the result is 0 then run
pm_runtime_autosuspend(dev) and return its result
- void pm_runtime_enable(struct device *dev);
+ `void pm_runtime_enable(struct device *dev);`
- decrement the device's 'power.disable_depth' field; if that field is equal
to zero, the runtime PM helper functions can execute subsystem-level
callbacks described in Section 2 for the device
- int pm_runtime_disable(struct device *dev);
+ `int pm_runtime_disable(struct device *dev);`
- increment the device's 'power.disable_depth' field (if the value of that
field was previously zero, this prevents subsystem-level runtime PM
callbacks from being run for the device), make sure that all of the
@@ -411,7 +419,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
necessary to execute the subsystem-level resume callback for the device
to satisfy that request, otherwise 0 is returned
- int pm_runtime_barrier(struct device *dev);
+ `int pm_runtime_barrier(struct device *dev);`
- check if there's a resume request pending for the device and resume it
(synchronously) in that case, cancel any other pending runtime PM requests
regarding it and wait for all runtime PM operations on it in progress to
@@ -419,10 +427,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
necessary to execute the subsystem-level resume callback for the device to
satisfy that request, otherwise 0 is returned
- void pm_suspend_ignore_children(struct device *dev, bool enable);
+ `void pm_suspend_ignore_children(struct device *dev, bool enable);`
- set/unset the power.ignore_children flag of the device
- int pm_runtime_set_active(struct device *dev);
+ `int pm_runtime_set_active(struct device *dev);`
- clear the device's 'power.runtime_error' flag, set the device's runtime
PM status to 'active' and update its parent's counter of 'active'
children as appropriate (it is only valid to use this function if
@@ -430,61 +438,61 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
zero); it will fail and return error code if the device has a parent
which is not active and the 'power.ignore_children' flag of which is unset
- void pm_runtime_set_suspended(struct device *dev);
+ `void pm_runtime_set_suspended(struct device *dev);`
- clear the device's 'power.runtime_error' flag, set the device's runtime
PM status to 'suspended' and update its parent's counter of 'active'
children as appropriate (it is only valid to use this function if
'power.runtime_error' is set or 'power.disable_depth' is greater than
zero)
- bool pm_runtime_active(struct device *dev);
+ `bool pm_runtime_active(struct device *dev);`
- return true if the device's runtime PM status is 'active' or its
'power.disable_depth' field is not equal to zero, or false otherwise
- bool pm_runtime_suspended(struct device *dev);
+ `bool pm_runtime_suspended(struct device *dev);`
- return true if the device's runtime PM status is 'suspended' and its
'power.disable_depth' field is equal to zero, or false otherwise
- bool pm_runtime_status_suspended(struct device *dev);
+ `bool pm_runtime_status_suspended(struct device *dev);`
- return true if the device's runtime PM status is 'suspended'
- void pm_runtime_allow(struct device *dev);
+ `void pm_runtime_allow(struct device *dev);`
- set the power.runtime_auto flag for the device and decrease its usage
counter (used by the /sys/devices/.../power/control interface to
effectively allow the device to be power managed at run time)
- void pm_runtime_forbid(struct device *dev);
+ `void pm_runtime_forbid(struct device *dev);`
- unset the power.runtime_auto flag for the device and increase its usage
counter (used by the /sys/devices/.../power/control interface to
effectively prevent the device from being power managed at run time)
- void pm_runtime_no_callbacks(struct device *dev);
+ `void pm_runtime_no_callbacks(struct device *dev);`
- set the power.no_callbacks flag for the device and remove the runtime
PM attributes from /sys/devices/.../power (or prevent them from being
added when the device is registered)
- void pm_runtime_irq_safe(struct device *dev);
+ `void pm_runtime_irq_safe(struct device *dev);`
- set the power.irq_safe flag for the device, causing the runtime-PM
callbacks to be invoked with interrupts off
- bool pm_runtime_is_irq_safe(struct device *dev);
+ `bool pm_runtime_is_irq_safe(struct device *dev);`
- return true if power.irq_safe flag was set for the device, causing
the runtime-PM callbacks to be invoked with interrupts off
- void pm_runtime_mark_last_busy(struct device *dev);
+ `void pm_runtime_mark_last_busy(struct device *dev);`
- set the power.last_busy field to the current time
- void pm_runtime_use_autosuspend(struct device *dev);
+ `void pm_runtime_use_autosuspend(struct device *dev);`
- set the power.use_autosuspend flag, enabling autosuspend delays; call
pm_runtime_get_sync if the flag was previously cleared and
power.autosuspend_delay is negative
- void pm_runtime_dont_use_autosuspend(struct device *dev);
+ `void pm_runtime_dont_use_autosuspend(struct device *dev);`
- clear the power.use_autosuspend flag, disabling autosuspend delays;
decrement the device's usage counter if the flag was previously set and
power.autosuspend_delay is negative; call pm_runtime_idle
- void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);
+ `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
- set the power.autosuspend_delay value to 'delay' (expressed in
milliseconds); if 'delay' is negative then runtime suspends are
prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be
@@ -493,7 +501,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
changed to or from a negative value; if power.use_autosuspend is clear,
pm_runtime_idle is called
- unsigned long pm_runtime_autosuspend_expiration(struct device *dev);
+ `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
- calculate the time when the current autosuspend delay period will expire,
based on power.last_busy and power.autosuspend_delay; if the delay time
is 1000 ms or larger then the expiration time is rounded up to the
@@ -503,36 +511,37 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
It is safe to execute the following helper functions from interrupt context:
-pm_request_idle()
-pm_request_autosuspend()
-pm_schedule_suspend()
-pm_request_resume()
-pm_runtime_get_noresume()
-pm_runtime_get()
-pm_runtime_put_noidle()
-pm_runtime_put()
-pm_runtime_put_autosuspend()
-pm_runtime_enable()
-pm_suspend_ignore_children()
-pm_runtime_set_active()
-pm_runtime_set_suspended()
-pm_runtime_suspended()
-pm_runtime_mark_last_busy()
-pm_runtime_autosuspend_expiration()
+- pm_request_idle()
+- pm_request_autosuspend()
+- pm_schedule_suspend()
+- pm_request_resume()
+- pm_runtime_get_noresume()
+- pm_runtime_get()
+- pm_runtime_put_noidle()
+- pm_runtime_put()
+- pm_runtime_put_autosuspend()
+- pm_runtime_enable()
+- pm_suspend_ignore_children()
+- pm_runtime_set_active()
+- pm_runtime_set_suspended()
+- pm_runtime_suspended()
+- pm_runtime_mark_last_busy()
+- pm_runtime_autosuspend_expiration()
If pm_runtime_irq_safe() has been called for a device then the following helper
functions may also be used in interrupt context:
-pm_runtime_idle()
-pm_runtime_suspend()
-pm_runtime_autosuspend()
-pm_runtime_resume()
-pm_runtime_get_sync()
-pm_runtime_put_sync()
-pm_runtime_put_sync_suspend()
-pm_runtime_put_sync_autosuspend()
+- pm_runtime_idle()
+- pm_runtime_suspend()
+- pm_runtime_autosuspend()
+- pm_runtime_resume()
+- pm_runtime_get_sync()
+- pm_runtime_put_sync()
+- pm_runtime_put_sync_suspend()
+- pm_runtime_put_sync_autosuspend()
5. Runtime PM Initialization, Device Probing and Removal
+========================================================
Initially, the runtime PM is disabled for all devices, which means that the
majority of the runtime PM helper functions described in Section 4 will return
@@ -608,6 +617,7 @@ manage the device at run time, the driver may confuse it by using
pm_runtime_forbid() this way.
6. Runtime PM and System Sleep
+==============================
Runtime PM and system sleep (i.e., system suspend and hibernation, also known
as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of
@@ -647,9 +657,9 @@ brought back to full power during resume, then its runtime PM status will have
to be updated to reflect the actual post-system sleep status. The way to do
this is:
- pm_runtime_disable(dev);
- pm_runtime_set_active(dev);
- pm_runtime_enable(dev);
+ - pm_runtime_disable(dev);
+ - pm_runtime_set_active(dev);
+ - pm_runtime_enable(dev);
The PM core always increments the runtime usage counter before calling the
->suspend() callback and decrements it after calling the ->resume() callback.
@@ -705,66 +715,66 @@ Subsystems may wish to conserve code space by using the set of generic power
management callbacks provided by the PM core, defined in
driver/base/power/generic_ops.c:
- int pm_generic_runtime_suspend(struct device *dev);
+ `int pm_generic_runtime_suspend(struct device *dev);`
- invoke the ->runtime_suspend() callback provided by the driver of this
device and return its result, or return 0 if not defined
- int pm_generic_runtime_resume(struct device *dev);
+ `int pm_generic_runtime_resume(struct device *dev);`
- invoke the ->runtime_resume() callback provided by the driver of this
device and return its result, or return 0 if not defined
- int pm_generic_suspend(struct device *dev);
+ `int pm_generic_suspend(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->suspend()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_suspend_noirq(struct device *dev);
+ `int pm_generic_suspend_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_resume(struct device *dev);
+ `int pm_generic_resume(struct device *dev);`
- invoke the ->resume() callback provided by the driver of this device and,
if successful, change the device's runtime PM status to 'active'
- int pm_generic_resume_noirq(struct device *dev);
+ `int pm_generic_resume_noirq(struct device *dev);`
- invoke the ->resume_noirq() callback provided by the driver of this device
- int pm_generic_freeze(struct device *dev);
+ `int pm_generic_freeze(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->freeze()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_freeze_noirq(struct device *dev);
+ `int pm_generic_freeze_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_thaw(struct device *dev);
+ `int pm_generic_thaw(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->thaw()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_thaw_noirq(struct device *dev);
+ `int pm_generic_thaw_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_poweroff(struct device *dev);
+ `int pm_generic_poweroff(struct device *dev);`
- if the device has not been suspended at run time, invoke the ->poweroff()
callback provided by its driver and return its result, or return 0 if not
defined
- int pm_generic_poweroff_noirq(struct device *dev);
+ `int pm_generic_poweroff_noirq(struct device *dev);`
- if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq()
callback provided by the device's driver and return its result, or return
0 if not defined
- int pm_generic_restore(struct device *dev);
+ `int pm_generic_restore(struct device *dev);`
- invoke the ->restore() callback provided by the driver of this device and,
if successful, change the device's runtime PM status to 'active'
- int pm_generic_restore_noirq(struct device *dev);
+ `int pm_generic_restore_noirq(struct device *dev);`
- invoke the ->restore_noirq() callback provided by the device's driver
These functions are the defaults used by the PM core, if a subsystem doesn't
@@ -781,6 +791,7 @@ UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its
last argument to NULL).
8. "No-Callback" Devices
+========================
Some "devices" are only logical sub-devices of their parent and cannot be
power-managed on their own. (The prototype example is a USB interface. Entire
@@ -807,6 +818,7 @@ parent must take responsibility for telling the device's driver when the
parent's power state changes.
9. Autosuspend, or automatically-delayed suspends
+=================================================
Changing a device's power state isn't free; it requires both time and energy.
A device should be put in a low-power state only when there's some reason to
@@ -832,8 +844,8 @@ registration the length should be controlled by user space, using the
In order to use autosuspend, subsystems or drivers must call
pm_runtime_use_autosuspend() (preferably before registering the device), and
-thereafter they should use the various *_autosuspend() helper functions instead
-of the non-autosuspend counterparts:
+thereafter they should use the various `*_autosuspend()` helper functions
+instead of the non-autosuspend counterparts::
Instead of: pm_runtime_suspend use: pm_runtime_autosuspend;
Instead of: pm_schedule_suspend use: pm_request_autosuspend;
@@ -858,7 +870,7 @@ The implementation is well suited for asynchronous use in interrupt contexts.
However such use inevitably involves races, because the PM core can't
synchronize ->runtime_suspend() callbacks with the arrival of I/O requests.
This synchronization must be handled by the driver, using its private lock.
-Here is a schematic pseudo-code example:
+Here is a schematic pseudo-code example::
foo_read_or_write(struct foo_priv *foo, void *data)
{
diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.rst
similarity index 92%
rename from Documentation/power/s2ram.txt
rename to Documentation/power/s2ram.rst
index 4685aee197fd..d739aa7c742c 100644
--- a/Documentation/power/s2ram.txt
+++ b/Documentation/power/s2ram.rst
@@ -1,7 +1,9 @@
- How to get s2ram working
- ~~~~~~~~~~~~~~~~~~~~~~~~
- 2006 Linus Torvalds
- 2006 Pavel Machek
+========================
+How to get s2ram working
+========================
+
+2006 Linus Torvalds
+2006 Pavel Machek
1) Check suspend.sf.net, program s2ram there has long whitelist of
"known ok" machines, along with tricks to use on each one.
@@ -12,8 +14,8 @@
3) You can use Linus' TRACE_RESUME infrastructure, described below.
- Using TRACE_RESUME
- ~~~~~~~~~~~~~~~~~~
+Using TRACE_RESUME
+~~~~~~~~~~~~~~~~~~
I've been working at making the machines I have able to STR, and almost
always it's a driver that is buggy. Thank God for the suspend/resume
@@ -27,7 +29,7 @@ machine that doesn't boot) is:
- enable PM_DEBUG, and PM_TRACE
- - use a script like this:
+ - use a script like this::
#!/bin/sh
sync
@@ -38,7 +40,7 @@ machine that doesn't boot) is:
- if it doesn't come back up (which is usually the problem), reboot by
holding the power button down, and look at the dmesg output for things
- like
+ like::
Magic number: 4:156:725
hash matches drivers/base/power/resume.c:28
@@ -52,7 +54,7 @@ machine that doesn't boot) is:
If no device matches the hash (or any matches appear to be false positives),
the culprit may be a device from a loadable kernel module that is not loaded
until after the hash is checked. You can check the hash against the current
- devices again after more modules are loaded using sysfs:
+ devices again after more modules are loaded using sysfs::
cat /sys/power/pm_trace_dev_match
diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst
similarity index 90%
rename from Documentation/power/suspend-and-cpuhotplug.txt
rename to Documentation/power/suspend-and-cpuhotplug.rst
index a8751b8df10e..7ac8e1f549f4 100644
--- a/Documentation/power/suspend-and-cpuhotplug.txt
+++ b/Documentation/power/suspend-and-cpuhotplug.rst
@@ -1,10 +1,15 @@
+====================================================================
Interaction of Suspend code (S3) with the CPU hotplug infrastructure
+====================================================================
- (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
+(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat@linux.vnet.ibm.com>
-I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM
- infrastructure uses it internally? And where do they share common code?
+I. Differences between CPU hotplug and Suspend-to-RAM
+======================================================
+
+How does the regular CPU hotplug code differ from how the Suspend-to-RAM
+infrastructure uses it internally? And where do they share common code?
Well, a picture is worth a thousand words... So ASCII art follows :-)
@@ -16,13 +21,13 @@ of describing where they take different paths and where they share code.
What happens when regular CPU hotplug and Suspend-to-RAM race with each other
is not depicted here.]
-On a high level, the suspend-resume cycle goes like this:
+On a high level, the suspend-resume cycle goes like this::
-|Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw |
-|tasks | | cpus | | | | cpus | |tasks|
+ |Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw |
+ |tasks | | cpus | | | | cpus | |tasks|
-More details follow:
+More details follow::
Suspend call path
-----------------
@@ -87,7 +92,9 @@ More details follow:
Resuming back is likewise, with the counterparts being (in the order of
execution during resume):
-* enable_nonboot_cpus() which involves:
+
+* enable_nonboot_cpus() which involves::
+
| Acquire cpu_add_remove_lock
| Decrease cpu_hotplug_disabled, thereby enabling regular cpu hotplug
| Call _cpu_up() [for all those cpus in the frozen_cpus mask, in a loop]
@@ -103,6 +110,8 @@ It is to be noted here that the system_transition_mutex lock is acquired at the
beginning, when we are just starting out to suspend, and then released only
after the entire cycle is complete (i.e., suspend + resume).
+::
+
Regular CPU hotplug call path
@@ -152,16 +161,16 @@ with the 'tasks_frozen' argument set to 1.
Important files and functions/entry points:
-------------------------------------------
+-------------------------------------------
-kernel/power/process.c : freeze_processes(), thaw_processes()
-kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish()
-kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus()
+- kernel/power/process.c : freeze_processes(), thaw_processes()
+- kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish()
+- kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus()
II. What are the issues involved in CPU hotplug?
- -------------------------------------------
+------------------------------------------------
There are some interesting situations involving CPU hotplug and microcode
update on the CPUs, as discussed below:
@@ -243,8 +252,11 @@ d. Handling microcode update during suspend/hibernate:
cycles).
-III. Are there any known problems when regular CPU hotplug and suspend race
- with each other?
+III. Known problems
+===================
+
+Are there any known problems when regular CPU hotplug and suspend race
+with each other?
Yes, they are listed below:
diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.rst
similarity index 98%
rename from Documentation/power/suspend-and-interrupts.txt
rename to Documentation/power/suspend-and-interrupts.rst
index 8afb29a8604a..4cda6617709a 100644
--- a/Documentation/power/suspend-and-interrupts.txt
+++ b/Documentation/power/suspend-and-interrupts.rst
@@ -1,4 +1,6 @@
+====================================
System Suspend and Device Interrupts
+====================================
Copyright (C) 2014 Intel Corp.
Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
diff --git a/Documentation/power/swsusp-and-swap-files.txt b/Documentation/power/swsusp-and-swap-files.rst
similarity index 83%
rename from Documentation/power/swsusp-and-swap-files.txt
rename to Documentation/power/swsusp-and-swap-files.rst
index f281886de490..a33a2919dbe4 100644
--- a/Documentation/power/swsusp-and-swap-files.txt
+++ b/Documentation/power/swsusp-and-swap-files.rst
@@ -1,4 +1,7 @@
+===============================================
Using swap files with software suspend (swsusp)
+===============================================
+
(C) 2006 Rafael J. Wysocki <rjw@sisk.pl>
The Linux kernel handles swap files almost in the same way as it handles swap
@@ -21,20 +24,20 @@ units.
In order to use a swap file with swsusp, you need to:
-1) Create the swap file and make it active, eg.
+1) Create the swap file and make it active, eg.::
-# dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k>
-# mkswap <swap_file_path>
-# swapon <swap_file_path>
+ # dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k>
+ # mkswap <swap_file_path>
+ # swapon <swap_file_path>
2) Use an application that will bmap the swap file with the help of the
FIBMAP ioctl and determine the location of the file's swap header, as the
offset, in <PAGE_SIZE> units, from the beginning of the partition which
holds the swap file.
-3) Add the following parameters to the kernel command line:
+3) Add the following parameters to the kernel command line::
-resume=<swap_file_partition> resume_offset=<swap_file_offset>
+ resume=<swap_file_partition> resume_offset=<swap_file_offset>
where <swap_file_partition> is the partition on which the swap file is located
and <swap_file_offset> is the offset of the swap header determined by the
@@ -46,7 +49,7 @@ OR
Use a userland suspend application that will set the partition and offset
with the help of the SNAPSHOT_SET_SWAP_AREA ioctl described in
-Documentation/power/userland-swsusp.txt (this is the only method to suspend
+Documentation/power/userland-swsusp.rst (this is the only method to suspend
to a swap file allowing the resume to be initiated from an initrd or initramfs
image).
diff --git a/Documentation/power/swsusp-dmcrypt.txt b/Documentation/power/swsusp-dmcrypt.rst
similarity index 67%
rename from Documentation/power/swsusp-dmcrypt.txt
rename to Documentation/power/swsusp-dmcrypt.rst
index b802fbfd95ef..426df59172cd 100644
--- a/Documentation/power/swsusp-dmcrypt.txt
+++ b/Documentation/power/swsusp-dmcrypt.rst
@@ -1,13 +1,15 @@
+=======================================
+How to use dm-crypt and swsusp together
+=======================================
+
Author: Andreas Steinmetz <ast@domdv.de>
-How to use dm-crypt and swsusp together:
-========================================
Some prerequisites:
You know how dm-crypt works. If not, visit the following web page:
http://www.saout.de/misc/dm-crypt/
-You have read Documentation/power/swsusp.txt and understand it.
+You have read Documentation/power/swsusp.rst and understand it.
You did read Documentation/admin-guide/initrd.rst and know how an initrd works.
You know how to create or how to modify an initrd.
@@ -29,23 +31,23 @@ a way that the swap device you suspend to/resume from has
always the same major/minor within the initrd as well as
within your running system. The easiest way to achieve this is
to always set up this swap device first with dmsetup, so that
-it will always look like the following:
+it will always look like the following::
-brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
+ brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
Now set up your kernel to use /dev/mapper/swap0 as the default
-resume partition, so your kernel .config contains:
+resume partition, so your kernel .config contains::
-CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
+ CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
Prepare your boot loader to use the initrd you will create or
modify. For lilo the simplest setup looks like the following
-lines:
+lines::
-image=/boot/vmlinuz
-initrd=/boot/initrd.gz
-label=linux
-append="root=/dev/ram0 init=/linuxrc rw"
+ image=/boot/vmlinuz
+ initrd=/boot/initrd.gz
+ label=linux
+ append="root=/dev/ram0 init=/linuxrc rw"
Finally you need to create or modify your initrd. Lets assume
you create an initrd that reads the required dm-crypt setup
@@ -53,66 +55,66 @@ from a pcmcia flash disk card. The card is formatted with an ext2
fs which resides on /dev/hde1 when the card is inserted. The
card contains at least the encrypted swap setup in a file
named "swapkey". /etc/fstab of your initrd contains something
-like the following:
+like the following::
-/dev/hda1 /mnt ext3 ro 0 0
-none /proc proc defaults,noatime,nodiratime 0 0
-none /sys sysfs defaults,noatime,nodiratime 0 0
+ /dev/hda1 /mnt ext3 ro 0 0
+ none /proc proc defaults,noatime,nodiratime 0 0
+ none /sys sysfs defaults,noatime,nodiratime 0 0
/dev/hda1 contains an unencrypted mini system that sets up all
of your crypto devices, again by reading the setup from the
pcmcia flash disk. What follows now is a /linuxrc for your
initrd that allows you to resume from encrypted swap and that
continues boot with your mini system on /dev/hda1 if resume
-does not happen:
+does not happen::
-#!/bin/sh
-PATH=/sbin:/bin:/usr/sbin:/usr/bin
-mount /proc
-mount /sys
-mapped=0
-noresume=`grep -c noresume /proc/cmdline`
-if [ "$*" != "" ]
-then
- noresume=1
-fi
-dmesg -n 1
-/sbin/cardmgr -q
-for i in 1 2 3 4 5 6 7 8 9 0
-do
- if [ -f /proc/ide/hde/media ]
+ #!/bin/sh
+ PATH=/sbin:/bin:/usr/sbin:/usr/bin
+ mount /proc
+ mount /sys
+ mapped=0
+ noresume=`grep -c noresume /proc/cmdline`
+ if [ "$*" != "" ]
then
+ noresume=1
+ fi
+ dmesg -n 1
+ /sbin/cardmgr -q
+ for i in 1 2 3 4 5 6 7 8 9 0
+ do
+ if [ -f /proc/ide/hde/media ]
+ then
+ usleep 500000
+ mount -t ext2 -o ro /dev/hde1 /mnt
+ if [ -f /mnt/swapkey ]
+ then
+ dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
+ fi
+ umount /mnt
+ break
+ fi
usleep 500000
- mount -t ext2 -o ro /dev/hde1 /mnt
- if [ -f /mnt/swapkey ]
+ done
+ killproc /sbin/cardmgr
+ dmesg -n 6
+ if [ $mapped = 1 ]
+ then
+ if [ $noresume != 0 ]
then
- dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
+ mkswap /dev/mapper/swap0 > /dev/null 2>&1
fi
- umount /mnt
- break
+ echo 254:0 > /sys/power/resume
+ dmsetup remove swap0
fi
- usleep 500000
-done
-killproc /sbin/cardmgr
-dmesg -n 6
-if [ $mapped = 1 ]
-then
- if [ $noresume != 0 ]
- then
- mkswap /dev/mapper/swap0 > /dev/null 2>&1
- fi
- echo 254:0 > /sys/power/resume
- dmsetup remove swap0
-fi
-umount /sys
-mount /mnt
-umount /proc
-cd /mnt
-pivot_root . mnt
-mount /proc
-umount -l /mnt
-umount /proc
-exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
+ umount /sys
+ mount /mnt
+ umount /proc
+ cd /mnt
+ pivot_root . mnt
+ mount /proc
+ umount -l /mnt
+ umount /proc
+ exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
Please don't mind the weird loop above, busybox's msh doesn't know
the let statement. Now, what is happening in the script?
diff --git a/Documentation/power/swsusp.rst b/Documentation/power/swsusp.rst
new file mode 100644
index 000000000000..d000312f6965
--- /dev/null
+++ b/Documentation/power/swsusp.rst
@@ -0,0 +1,501 @@
+============
+Swap suspend
+============
+
+Some warnings, first.
+
+.. warning::
+
+ **BIG FAT WARNING**
+
+ If you touch anything on disk between suspend and resume...
+ ...kiss your data goodbye.
+
+ If you do resume from initrd after your filesystems are mounted...
+ ...bye bye root partition.
+
+ [this is actually same case as above]
+
+ If you have unsupported ( ) devices using DMA, you may have some
+ problems. If your disk driver does not support suspend... (IDE does),
+ it may cause some problems, too. If you change kernel command line
+ between suspend and resume, it may do something wrong. If you change
+ your hardware while system is suspended... well, it was not good idea;
+ but it will probably only crash.
+
+ ( ) suspend/resume support is needed to make it safe.
+
+ If you have any filesystems on USB devices mounted before software suspend,
+ they won't be accessible after resume and you may lose data, as though
+ you have unplugged the USB devices with mounted filesystems on them;
+ see the FAQ below for details. (This is not true for more traditional
+ power states like "standby", which normally don't turn USB off.)
+
+Swap partition:
+ You need to append resume=/dev/your_swap_partition to kernel command
+ line or specify it using /sys/power/resume.
+
+Swap file:
+ If using a swapfile you can also specify a resume offset using
+ resume_offset=<number> on the kernel command line or specify it
+ in /sys/power/resume_offset.
+
+After preparing then you suspend by::
+
+ echo shutdown > /sys/power/disk; echo disk > /sys/power/state
+
+- If you feel ACPI works pretty well on your system, you might try::
+
+ echo platform > /sys/power/disk; echo disk > /sys/power/state
+
+- If you would like to write hibernation image to swap and then suspend
+ to RAM (provided your platform supports it), you can try::
+
+ echo suspend > /sys/power/disk; echo disk > /sys/power/state
+
+- If you have SATA disks, you'll need recent kernels with SATA suspend
+ support. For suspend and resume to work, make sure your disk drivers
+ are built into kernel -- not modules. [There's way to make
+ suspend/resume with modular disk drivers, see FAQ, but you probably
+ should not do that.]
+
+If you want to limit the suspend image size to N bytes, do::
+
+ echo N > /sys/power/image_size
+
+before suspend (it is limited to around 2/5 of available RAM by default).
+
+- The resume process checks for the presence of the resume device,
+ if found, it then checks the contents for the hibernation image signature.
+ If both are found, it resumes the hibernation image.
+
+- The resume process may be triggered in two ways:
+
+ 1) During lateinit: If resume=/dev/your_swap_partition is specified on
+ the kernel command line, lateinit runs the resume process. If the
+ resume device has not been probed yet, the resume process fails and
+ bootup continues.
+ 2) Manually from an initrd or initramfs: May be run from
+ the init script by using the /sys/power/resume file. It is vital
+ that this be done prior to remounting any filesystems (even as
+ read-only) otherwise data may be corrupted.
+
+Article about goals and implementation of Software Suspend for Linux
+====================================================================
+
+Author: Gábor Kuti
+Last revised: 2003-10-20 by Pavel Machek
+
+Idea and goals to achieve
+-------------------------
+
+Nowadays it is common in several laptops that they have a suspend button. It
+saves the state of the machine to a filesystem or to a partition and switches
+to standby mode. Later resuming the machine the saved state is loaded back to
+ram and the machine can continue its work. It has two real benefits. First we
+save ourselves the time machine goes down and later boots up, energy costs
+are real high when running from batteries. The other gain is that we don't have
+to interrupt our programs so processes that are calculating something for a long
+time shouldn't need to be written interruptible.
+
+swsusp saves the state of the machine into active swaps and then reboots or
+powerdowns. You must explicitly specify the swap partition to resume from with
+`resume=` kernel option. If signature is found it loads and restores saved
+state. If the option `noresume` is specified as a boot parameter, it skips
+the resuming. If the option `hibernate=nocompress` is specified as a boot
+parameter, it saves hibernation image without compression.
+
+In the meantime while the system is suspended you should not add/remove any
+of the hardware, write to the filesystems, etc.
+
+Sleep states summary
+====================
+
+There are three different interfaces you can use, /proc/acpi should
+work like this:
+
+In a really perfect world::
+
+ echo 1 > /proc/acpi/sleep # for standby
+ echo 2 > /proc/acpi/sleep # for suspend to ram
+ echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
+ echo 4 > /proc/acpi/sleep # for suspend to disk
+ echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
+
+and perhaps::
+
+ echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
+
+Frequently Asked Questions
+==========================
+
+Q:
+ well, suspending a server is IMHO a really stupid thing,
+ but... (Diego Zuccato):
+
+A:
+ You bought new UPS for your server. How do you install it without
+ bringing machine down? Suspend to disk, rearrange power cables,
+ resume.
+
+ You have your server on UPS. Power died, and UPS is indicating 30
+ seconds to failure. What do you do? Suspend to disk.
+
+
+Q:
+ Maybe I'm missing something, but why don't the regular I/O paths work?
+
+A:
+ We do use the regular I/O paths. However we cannot restore the data
+ to its original location as we load it. That would create an
+ inconsistent kernel state which would certainly result in an oops.
+ Instead, we load the image into unused memory and then atomically copy
+ it back to it original location. This implies, of course, a maximum
+ image size of half the amount of memory.
+
+ There are two solutions to this:
+
+ * require half of memory to be free during suspend. That way you can
+ read "new" data onto free spots, then cli and copy
+
+ * assume we had special "polling" ide driver that only uses memory
+ between 0-640KB. That way, I'd have to make sure that 0-640KB is free
+ during suspending, but otherwise it would work...
+
+ suspend2 shares this fundamental limitation, but does not include user
+ data and disk caches into "used memory" by saving them in
+ advance. That means that the limitation goes away in practice.
+
+Q:
+ Does linux support ACPI S4?
+
+A:
+ Yes. That's what echo platform > /sys/power/disk does.
+
+Q:
+ What is 'suspend2'?
+
+A:
+ suspend2 is 'Software Suspend 2', a forked implementation of
+ suspend-to-disk which is available as separate patches for 2.4 and 2.6
+ kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB
+ highmem and preemption. It also has a extensible architecture that
+ allows for arbitrary transformations on the image (compression,
+ encryption) and arbitrary backends for writing the image (eg to swap
+ or an NFS share[Work In Progress]). Questions regarding suspend2
+ should be sent to the mailing list available through the suspend2
+ website, and not to the Linux Kernel Mailing List. We are working
+ toward merging suspend2 into the mainline kernel.
+
+Q:
+ What is the freezing of tasks and why are we using it?
+
+A:
+ The freezing of tasks is a mechanism by which user space processes and some
+ kernel threads are controlled during hibernation or system-wide suspend (on some
+ architectures). See freezing-of-tasks.txt for details.
+
+Q:
+ What is the difference between "platform" and "shutdown"?
+
+A:
+ shutdown:
+ save state in linux, then tell bios to powerdown
+
+ platform:
+ save state in linux, then tell bios to powerdown and blink
+ "suspended led"
+
+ "platform" is actually right thing to do where supported, but
+ "shutdown" is most reliable (except on ACPI systems).
+
+Q:
+ I do not understand why you have such strong objections to idea of
+ selective suspend.
+
+A:
+ Do selective suspend during runtime power management, that's okay. But
+ it's useless for suspend-to-disk. (And I do not see how you could use
+ it for suspend-to-ram, I hope you do not want that).
+
+ Lets see, so you suggest to
+
+ * SUSPEND all but swap device and parents
+ * Snapshot
+ * Write image to disk
+ * SUSPEND swap device and parents
+ * Powerdown
+
+ Oh no, that does not work, if swap device or its parents uses DMA,
+ you've corrupted data. You'd have to do
+
+ * SUSPEND all but swap device and parents
+ * FREEZE swap device and parents
+ * Snapshot
+ * UNFREEZE swap device and parents
+ * Write
+ * SUSPEND swap device and parents
+
+ Which means that you still need that FREEZE state, and you get more
+ complicated code. (And I have not yet introduce details like system
+ devices).
+
+Q:
+ There don't seem to be any generally useful behavioral
+ distinctions between SUSPEND and FREEZE.
+
+A:
+ Doing SUSPEND when you are asked to do FREEZE is always correct,
+ but it may be unnecessarily slow. If you want your driver to stay simple,
+ slowness may not matter to you. It can always be fixed later.
+
+ For devices like disk it does matter, you do not want to spindown for
+ FREEZE.
+
+Q:
+ After resuming, system is paging heavily, leading to very bad interactivity.
+
+A:
+ Try running::
+
+ cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file
+ do
+ test -f "$file" && cat "$file" > /dev/null
+ done
+
+ after resume. swapoff -a; swapon -a may also be useful.
+
+Q:
+ What happens to devices during swsusp? They seem to be resumed
+ during system suspend?
+
+A:
+ That's correct. We need to resume them if we want to write image to
+ disk. Whole sequence goes like
+
+ **Suspend part**
+
+ running system, user asks for suspend-to-disk
+
+ user processes are stopped
+
+ suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
+ with state snapshot
+
+ state snapshot: copy of whole used memory is taken with interrupts disabled
+
+ resume(): devices are woken up so that we can write image to swap
+
+ write image to swap
+
+ suspend(PMSG_SUSPEND): suspend devices so that we can power off
+
+ turn the power off
+
+ **Resume part**
+
+ (is actually pretty similar)
+
+ running system, user asks for suspend-to-disk
+
+ user processes are stopped (in common case there are none,
+ but with resume-from-initrd, no one knows)
+
+ read image from disk
+
+ suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
+ with image restoration
+
+ image restoration: rewrite memory with image
+
+ resume(): devices are woken up so that system can continue
+
+ thaw all user processes
+
+Q:
+ What is this 'Encrypt suspend image' for?
+
+A:
+ First of all: it is not a replacement for dm-crypt encrypted swap.
+ It cannot protect your computer while it is suspended. Instead it does
+ protect from leaking sensitive data after resume from suspend.
+
+ Think of the following: you suspend while an application is running
+ that keeps sensitive data in memory. The application itself prevents
+ the data from being swapped out. Suspend, however, must write these
+ data to swap to be able to resume later on. Without suspend encryption
+ your sensitive data are then stored in plaintext on disk. This means
+ that after resume your sensitive data are accessible to all
+ applications having direct access to the swap device which was used
+ for suspend. If you don't need swap after resume these data can remain
+ on disk virtually forever. Thus it can happen that your system gets
+ broken in weeks later and sensitive data which you thought were
+ encrypted and protected are retrieved and stolen from the swap device.
+ To prevent this situation you should use 'Encrypt suspend image'.
+
+ During suspend a temporary key is created and this key is used to
+ encrypt the data written to disk. When, during resume, the data was
+ read back into memory the temporary key is destroyed which simply
+ means that all data written to disk during suspend are then
+ inaccessible so they can't be stolen later on. The only thing that
+ you must then take care of is that you call 'mkswap' for the swap
+ partition used for suspend as early as possible during regular
+ boot. This asserts that any temporary key from an oopsed suspend or
+ from a failed or aborted resume is erased from the swap device.
+
+ As a rule of thumb use encrypted swap to protect your data while your
+ system is shut down or suspended. Additionally use the encrypted
+ suspend image to prevent sensitive data from being stolen after
+ resume.
+
+Q:
+ Can I suspend to a swap file?
+
+A:
+ Generally, yes, you can. However, it requires you to use the "resume=" and
+ "resume_offset=" kernel command line parameters, so the resume from a swap file
+ cannot be initiated from an initrd or initramfs image. See
+ swsusp-and-swap-files.txt for details.
+
+Q:
+ Is there a maximum system RAM size that is supported by swsusp?
+
+A:
+ It should work okay with highmem.
+
+Q:
+ Does swsusp (to disk) use only one swap partition or can it use
+ multiple swap partitions (aggregate them into one logical space)?
+
+A:
+ Only one swap partition, sorry.
+
+Q:
+ If my application(s) causes lots of memory & swap space to be used
+ (over half of the total system RAM), is it correct that it is likely
+ to be useless to try to suspend to disk while that app is running?
+
+A:
+ No, it should work okay, as long as your app does not mlock()
+ it. Just prepare big enough swap partition.
+
+Q:
+ What information is useful for debugging suspend-to-disk problems?
+
+A:
+ Well, last messages on the screen are always useful. If something
+ is broken, it is usually some kernel driver, therefore trying with as
+ little as possible modules loaded helps a lot. I also prefer people to
+ suspend from console, preferably without X running. Booting with
+ init=/bin/bash, then swapon and starting suspend sequence manually
+ usually does the trick. Then it is good idea to try with latest
+ vanilla kernel.
+
+Q:
+ How can distributions ship a swsusp-supporting kernel with modular
+ disk drivers (especially SATA)?
+
+A:
+ Well, it can be done, load the drivers, then do echo into
+ /sys/power/resume file from initrd. Be sure not to mount
+ anything, not even read-only mount, or you are going to lose your
+ data.
+
+Q:
+ How do I make suspend more verbose?
+
+A:
+ If you want to see any non-error kernel messages on the virtual
+ terminal the kernel switches to during suspend, you have to set the
+ kernel console loglevel to at least 4 (KERN_WARNING), for example by
+ doing::
+
+ # save the old loglevel
+ read LOGLEVEL DUMMY < /proc/sys/kernel/printk
+ # set the loglevel so we see the progress bar.
+ # if the level is higher than needed, we leave it alone.
+ if [ $LOGLEVEL -lt 5 ]; then
+ echo 5 > /proc/sys/kernel/printk
+ fi
+
+ IMG_SZ=0
+ read IMG_SZ < /sys/power/image_size
+ echo -n disk > /sys/power/state
+ RET=$?
+ #
+ # the logic here is:
+ # if image_size > 0 (without kernel support, IMG_SZ will be zero),
+ # then try again with image_size set to zero.
+ if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size
+ echo 0 > /sys/power/image_size
+ echo -n disk > /sys/power/state
+ RET=$?
+ fi
+
+ # restore previous loglevel
+ echo $LOGLEVEL > /proc/sys/kernel/printk
+ exit $RET
+
+Q:
+ Is this true that if I have a mounted filesystem on a USB device and
+ I suspend to disk, I can lose data unless the filesystem has been mounted
+ with "sync"?
+
+A:
+ That's right ... if you disconnect that device, you may lose data.
+ In fact, even with "-o sync" you can lose data if your programs have
+ information in buffers they haven't written out to a disk you disconnect,
+ or if you disconnect before the device finished saving data you wrote.
+
+ Software suspend normally powers down USB controllers, which is equivalent
+ to disconnecting all USB devices attached to your system.
+
+ Your system might well support low-power modes for its USB controllers
+ while the system is asleep, maintaining the connection, using true sleep
+ modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the
+ /sys/power/state file; write "standby" or "mem".) We've not seen any
+ hardware that can use these modes through software suspend, although in
+ theory some systems might support "platform" modes that won't break the
+ USB connections.
+
+ Remember that it's always a bad idea to unplug a disk drive containing a
+ mounted filesystem. That's true even when your system is asleep! The
+ safest thing is to unmount all filesystems on removable media (such USB,
+ Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
+ before suspending; then remount them after resuming.
+
+ There is a work-around for this problem. For more information, see
+ Documentation/driver-api/usb/persist.rst.
+
+Q:
+ Can I suspend-to-disk using a swap partition under LVM?
+
+A:
+ Yes and No. You can suspend successfully, but the kernel will not be able
+ to resume on its own. You need an initramfs that can recognize the resume
+ situation, activate the logical volume containing the swap volume (but not
+ touch any filesystems!), and eventually call::
+
+ echo -n "$major:$minor" > /sys/power/resume
+
+ where $major and $minor are the respective major and minor device numbers of
+ the swap volume.
+
+ uswsusp works with LVM, too. See http://suspend.sourceforge.net/
+
+Q:
+ I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were
+ compiled with the similar configuration files. Anyway I found that
+ suspend to disk (and resume) is much slower on 2.6.16 compared to
+ 2.6.15. Any idea for why that might happen or how can I speed it up?
+
+A:
+ This is because the size of the suspend image is now greater than
+ for 2.6.15 (by saving more data we can get more responsive system
+ after resume).
+
+ There's the /sys/power/image_size knob that controls the size of the
+ image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as
+ root), the 2.6.15 behavior should be restored. If it is still too
+ slow, take a look at suspend.sf.net -- userland suspend is faster and
+ supports LZF compression to speed it up further.
diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt
deleted file mode 100644
index 236d1fb13640..000000000000
--- a/Documentation/power/swsusp.txt
+++ /dev/null
@@ -1,446 +0,0 @@
-Some warnings, first.
-
- * BIG FAT WARNING *********************************************************
- *
- * If you touch anything on disk between suspend and resume...
- * ...kiss your data goodbye.
- *
- * If you do resume from initrd after your filesystems are mounted...
- * ...bye bye root partition.
- * [this is actually same case as above]
- *
- * If you have unsupported (*) devices using DMA, you may have some
- * problems. If your disk driver does not support suspend... (IDE does),
- * it may cause some problems, too. If you change kernel command line
- * between suspend and resume, it may do something wrong. If you change
- * your hardware while system is suspended... well, it was not good idea;
- * but it will probably only crash.
- *
- * (*) suspend/resume support is needed to make it safe.
- *
- * If you have any filesystems on USB devices mounted before software suspend,
- * they won't be accessible after resume and you may lose data, as though
- * you have unplugged the USB devices with mounted filesystems on them;
- * see the FAQ below for details. (This is not true for more traditional
- * power states like "standby", which normally don't turn USB off.)
-
-Swap partition:
-You need to append resume=/dev/your_swap_partition to kernel command
-line or specify it using /sys/power/resume.
-
-Swap file:
-If using a swapfile you can also specify a resume offset using
-resume_offset=<number> on the kernel command line or specify it
-in /sys/power/resume_offset.
-
-After preparing then you suspend by
-
-echo shutdown > /sys/power/disk; echo disk > /sys/power/state
-
-. If you feel ACPI works pretty well on your system, you might try
-
-echo platform > /sys/power/disk; echo disk > /sys/power/state
-
-. If you would like to write hibernation image to swap and then suspend
-to RAM (provided your platform supports it), you can try
-
-echo suspend > /sys/power/disk; echo disk > /sys/power/state
-
-. If you have SATA disks, you'll need recent kernels with SATA suspend
-support. For suspend and resume to work, make sure your disk drivers
-are built into kernel -- not modules. [There's way to make
-suspend/resume with modular disk drivers, see FAQ, but you probably
-should not do that.]
-
-If you want to limit the suspend image size to N bytes, do
-
-echo N > /sys/power/image_size
-
-before suspend (it is limited to around 2/5 of available RAM by default).
-
-. The resume process checks for the presence of the resume device,
-if found, it then checks the contents for the hibernation image signature.
-If both are found, it resumes the hibernation image.
-
-. The resume process may be triggered in two ways:
- 1) During lateinit: If resume=/dev/your_swap_partition is specified on
- the kernel command line, lateinit runs the resume process. If the
- resume device has not been probed yet, the resume process fails and
- bootup continues.
- 2) Manually from an initrd or initramfs: May be run from
- the init script by using the /sys/power/resume file. It is vital
- that this be done prior to remounting any filesystems (even as
- read-only) otherwise data may be corrupted.
-
-Article about goals and implementation of Software Suspend for Linux
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Author: Gábor Kuti
-Last revised: 2003-10-20 by Pavel Machek
-
-Idea and goals to achieve
-
-Nowadays it is common in several laptops that they have a suspend button. It
-saves the state of the machine to a filesystem or to a partition and switches
-to standby mode. Later resuming the machine the saved state is loaded back to
-ram and the machine can continue its work. It has two real benefits. First we
-save ourselves the time machine goes down and later boots up, energy costs
-are real high when running from batteries. The other gain is that we don't have to
-interrupt our programs so processes that are calculating something for a long
-time shouldn't need to be written interruptible.
-
-swsusp saves the state of the machine into active swaps and then reboots or
-powerdowns. You must explicitly specify the swap partition to resume from with
-``resume='' kernel option. If signature is found it loads and restores saved
-state. If the option ``noresume'' is specified as a boot parameter, it skips
-the resuming. If the option ``hibernate=nocompress'' is specified as a boot
-parameter, it saves hibernation image without compression.
-
-In the meantime while the system is suspended you should not add/remove any
-of the hardware, write to the filesystems, etc.
-
-Sleep states summary
-====================
-
-There are three different interfaces you can use, /proc/acpi should
-work like this:
-
-In a really perfect world:
-echo 1 > /proc/acpi/sleep # for standby
-echo 2 > /proc/acpi/sleep # for suspend to ram
-echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
-echo 4 > /proc/acpi/sleep # for suspend to disk
-echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
-
-and perhaps
-echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
-
-Frequently Asked Questions
-==========================
-
-Q: well, suspending a server is IMHO a really stupid thing,
-but... (Diego Zuccato):
-
-A: You bought new UPS for your server. How do you install it without
-bringing machine down? Suspend to disk, rearrange power cables,
-resume.
-
-You have your server on UPS. Power died, and UPS is indicating 30
-seconds to failure. What do you do? Suspend to disk.
-
-
-Q: Maybe I'm missing something, but why don't the regular I/O paths work?
-
-A: We do use the regular I/O paths. However we cannot restore the data
-to its original location as we load it. That would create an
-inconsistent kernel state which would certainly result in an oops.
-Instead, we load the image into unused memory and then atomically copy
-it back to it original location. This implies, of course, a maximum
-image size of half the amount of memory.
-
-There are two solutions to this:
-
-* require half of memory to be free during suspend. That way you can
-read "new" data onto free spots, then cli and copy
-
-* assume we had special "polling" ide driver that only uses memory
-between 0-640KB. That way, I'd have to make sure that 0-640KB is free
-during suspending, but otherwise it would work...
-
-suspend2 shares this fundamental limitation, but does not include user
-data and disk caches into "used memory" by saving them in
-advance. That means that the limitation goes away in practice.
-
-Q: Does linux support ACPI S4?
-
-A: Yes. That's what echo platform > /sys/power/disk does.
-
-Q: What is 'suspend2'?
-
-A: suspend2 is 'Software Suspend 2', a forked implementation of
-suspend-to-disk which is available as separate patches for 2.4 and 2.6
-kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB
-highmem and preemption. It also has a extensible architecture that
-allows for arbitrary transformations on the image (compression,
-encryption) and arbitrary backends for writing the image (eg to swap
-or an NFS share[Work In Progress]). Questions regarding suspend2
-should be sent to the mailing list available through the suspend2
-website, and not to the Linux Kernel Mailing List. We are working
-toward merging suspend2 into the mainline kernel.
-
-Q: What is the freezing of tasks and why are we using it?
-
-A: The freezing of tasks is a mechanism by which user space processes and some
-kernel threads are controlled during hibernation or system-wide suspend (on some
-architectures). See freezing-of-tasks.txt for details.
-
-Q: What is the difference between "platform" and "shutdown"?
-
-A:
-
-shutdown: save state in linux, then tell bios to powerdown
-
-platform: save state in linux, then tell bios to powerdown and blink
- "suspended led"
-
-"platform" is actually right thing to do where supported, but
-"shutdown" is most reliable (except on ACPI systems).
-
-Q: I do not understand why you have such strong objections to idea of
-selective suspend.
-
-A: Do selective suspend during runtime power management, that's okay. But
-it's useless for suspend-to-disk. (And I do not see how you could use
-it for suspend-to-ram, I hope you do not want that).
-
-Lets see, so you suggest to
-
-* SUSPEND all but swap device and parents
-* Snapshot
-* Write image to disk
-* SUSPEND swap device and parents
-* Powerdown
-
-Oh no, that does not work, if swap device or its parents uses DMA,
-you've corrupted data. You'd have to do
-
-* SUSPEND all but swap device and parents
-* FREEZE swap device and parents
-* Snapshot
-* UNFREEZE swap device and parents
-* Write
-* SUSPEND swap device and parents
-
-Which means that you still need that FREEZE state, and you get more
-complicated code. (And I have not yet introduce details like system
-devices).
-
-Q: There don't seem to be any generally useful behavioral
-distinctions between SUSPEND and FREEZE.
-
-A: Doing SUSPEND when you are asked to do FREEZE is always correct,
-but it may be unnecessarily slow. If you want your driver to stay simple,
-slowness may not matter to you. It can always be fixed later.
-
-For devices like disk it does matter, you do not want to spindown for
-FREEZE.
-
-Q: After resuming, system is paging heavily, leading to very bad interactivity.
-
-A: Try running
-
-cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file
-do
- test -f "$file" && cat "$file" > /dev/null
-done
-
-after resume. swapoff -a; swapon -a may also be useful.
-
-Q: What happens to devices during swsusp? They seem to be resumed
-during system suspend?
-
-A: That's correct. We need to resume them if we want to write image to
-disk. Whole sequence goes like
-
- Suspend part
- ~~~~~~~~~~~~
- running system, user asks for suspend-to-disk
-
- user processes are stopped
-
- suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
- with state snapshot
-
- state snapshot: copy of whole used memory is taken with interrupts disabled
-
- resume(): devices are woken up so that we can write image to swap
-
- write image to swap
-
- suspend(PMSG_SUSPEND): suspend devices so that we can power off
-
- turn the power off
-
- Resume part
- ~~~~~~~~~~~
- (is actually pretty similar)
-
- running system, user asks for suspend-to-disk
-
- user processes are stopped (in common case there are none, but with resume-from-initrd, no one knows)
-
- read image from disk
-
- suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
- with image restoration
-
- image restoration: rewrite memory with image
-
- resume(): devices are woken up so that system can continue
-
- thaw all user processes
-
-Q: What is this 'Encrypt suspend image' for?
-
-A: First of all: it is not a replacement for dm-crypt encrypted swap.
-It cannot protect your computer while it is suspended. Instead it does
-protect from leaking sensitive data after resume from suspend.
-
-Think of the following: you suspend while an application is running
-that keeps sensitive data in memory. The application itself prevents
-the data from being swapped out. Suspend, however, must write these
-data to swap to be able to resume later on. Without suspend encryption
-your sensitive data are then stored in plaintext on disk. This means
-that after resume your sensitive data are accessible to all
-applications having direct access to the swap device which was used
-for suspend. If you don't need swap after resume these data can remain
-on disk virtually forever. Thus it can happen that your system gets
-broken in weeks later and sensitive data which you thought were
-encrypted and protected are retrieved and stolen from the swap device.
-To prevent this situation you should use 'Encrypt suspend image'.
-
-During suspend a temporary key is created and this key is used to
-encrypt the data written to disk. When, during resume, the data was
-read back into memory the temporary key is destroyed which simply
-means that all data written to disk during suspend are then
-inaccessible so they can't be stolen later on. The only thing that
-you must then take care of is that you call 'mkswap' for the swap
-partition used for suspend as early as possible during regular
-boot. This asserts that any temporary key from an oopsed suspend or
-from a failed or aborted resume is erased from the swap device.
-
-As a rule of thumb use encrypted swap to protect your data while your
-system is shut down or suspended. Additionally use the encrypted
-suspend image to prevent sensitive data from being stolen after
-resume.
-
-Q: Can I suspend to a swap file?
-
-A: Generally, yes, you can. However, it requires you to use the "resume=" and
-"resume_offset=" kernel command line parameters, so the resume from a swap file
-cannot be initiated from an initrd or initramfs image. See
-swsusp-and-swap-files.txt for details.
-
-Q: Is there a maximum system RAM size that is supported by swsusp?
-
-A: It should work okay with highmem.
-
-Q: Does swsusp (to disk) use only one swap partition or can it use
-multiple swap partitions (aggregate them into one logical space)?
-
-A: Only one swap partition, sorry.
-
-Q: If my application(s) causes lots of memory & swap space to be used
-(over half of the total system RAM), is it correct that it is likely
-to be useless to try to suspend to disk while that app is running?
-
-A: No, it should work okay, as long as your app does not mlock()
-it. Just prepare big enough swap partition.
-
-Q: What information is useful for debugging suspend-to-disk problems?
-
-A: Well, last messages on the screen are always useful. If something
-is broken, it is usually some kernel driver, therefore trying with as
-little as possible modules loaded helps a lot. I also prefer people to
-suspend from console, preferably without X running. Booting with
-init=/bin/bash, then swapon and starting suspend sequence manually
-usually does the trick. Then it is good idea to try with latest
-vanilla kernel.
-
-Q: How can distributions ship a swsusp-supporting kernel with modular
-disk drivers (especially SATA)?
-
-A: Well, it can be done, load the drivers, then do echo into
-/sys/power/resume file from initrd. Be sure not to mount
-anything, not even read-only mount, or you are going to lose your
-data.
-
-Q: How do I make suspend more verbose?
-
-A: If you want to see any non-error kernel messages on the virtual
-terminal the kernel switches to during suspend, you have to set the
-kernel console loglevel to at least 4 (KERN_WARNING), for example by
-doing
-
- # save the old loglevel
- read LOGLEVEL DUMMY < /proc/sys/kernel/printk
- # set the loglevel so we see the progress bar.
- # if the level is higher than needed, we leave it alone.
- if [ $LOGLEVEL -lt 5 ]; then
- echo 5 > /proc/sys/kernel/printk
- fi
-
- IMG_SZ=0
- read IMG_SZ < /sys/power/image_size
- echo -n disk > /sys/power/state
- RET=$?
- #
- # the logic here is:
- # if image_size > 0 (without kernel support, IMG_SZ will be zero),
- # then try again with image_size set to zero.
- if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size
- echo 0 > /sys/power/image_size
- echo -n disk > /sys/power/state
- RET=$?
- fi
-
- # restore previous loglevel
- echo $LOGLEVEL > /proc/sys/kernel/printk
- exit $RET
-
-Q: Is this true that if I have a mounted filesystem on a USB device and
-I suspend to disk, I can lose data unless the filesystem has been mounted
-with "sync"?
-
-A: That's right ... if you disconnect that device, you may lose data.
-In fact, even with "-o sync" you can lose data if your programs have
-information in buffers they haven't written out to a disk you disconnect,
-or if you disconnect before the device finished saving data you wrote.
-
-Software suspend normally powers down USB controllers, which is equivalent
-to disconnecting all USB devices attached to your system.
-
-Your system might well support low-power modes for its USB controllers
-while the system is asleep, maintaining the connection, using true sleep
-modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the
-/sys/power/state file; write "standby" or "mem".) We've not seen any
-hardware that can use these modes through software suspend, although in
-theory some systems might support "platform" modes that won't break the
-USB connections.
-
-Remember that it's always a bad idea to unplug a disk drive containing a
-mounted filesystem. That's true even when your system is asleep! The
-safest thing is to unmount all filesystems on removable media (such USB,
-Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
-before suspending; then remount them after resuming.
-
-There is a work-around for this problem. For more information, see
-Documentation/driver-api/usb/persist.rst.
-
-Q: Can I suspend-to-disk using a swap partition under LVM?
-
-A: Yes and No. You can suspend successfully, but the kernel will not be able
-to resume on its own. You need an initramfs that can recognize the resume
-situation, activate the logical volume containing the swap volume (but not
-touch any filesystems!), and eventually call
-
-echo -n "$major:$minor" > /sys/power/resume
-
-where $major and $minor are the respective major and minor device numbers of
-the swap volume.
-
-uswsusp works with LVM, too. See http://suspend.sourceforge.net/
-
-Q: I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were
-compiled with the similar configuration files. Anyway I found that
-suspend to disk (and resume) is much slower on 2.6.16 compared to
-2.6.15. Any idea for why that might happen or how can I speed it up?
-
-A: This is because the size of the suspend image is now greater than
-for 2.6.15 (by saving more data we can get more responsive system
-after resume).
-
-There's the /sys/power/image_size knob that controls the size of the
-image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as
-root), the 2.6.15 behavior should be restored. If it is still too
-slow, take a look at suspend.sf.net -- userland suspend is faster and
-supports LZF compression to speed it up further.
diff --git a/Documentation/power/tricks.txt b/Documentation/power/tricks.rst
similarity index 93%
rename from Documentation/power/tricks.txt
rename to Documentation/power/tricks.rst
index a1b8f7249f4c..ca787f142c3f 100644
--- a/Documentation/power/tricks.txt
+++ b/Documentation/power/tricks.rst
@@ -1,5 +1,7 @@
- swsusp/S3 tricks
- ~~~~~~~~~~~~~~~~
+================
+swsusp/S3 tricks
+================
+
Pavel Machek <pavel@ucw.cz>
If you want to trick swsusp/S3 into working, you might want to try:
diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.rst
similarity index 85%
rename from Documentation/power/userland-swsusp.txt
rename to Documentation/power/userland-swsusp.rst
index bbfcd1bbedc5..a0fa51bb1a4d 100644
--- a/Documentation/power/userland-swsusp.txt
+++ b/Documentation/power/userland-swsusp.rst
@@ -1,4 +1,7 @@
+=====================================================
Documentation for userland software suspend interface
+=====================================================
+
(C) 2006 Rafael J. Wysocki <rjw@sisk.pl>
First, the warnings at the beginning of swsusp.txt still apply.
@@ -30,13 +33,16 @@ called.
The ioctl() commands recognized by the device are:
-SNAPSHOT_FREEZE - freeze user space processes (the current process is
+SNAPSHOT_FREEZE
+ freeze user space processes (the current process is
not frozen); this is required for SNAPSHOT_CREATE_IMAGE
and SNAPSHOT_ATOMIC_RESTORE to succeed
-SNAPSHOT_UNFREEZE - thaw user space processes frozen by SNAPSHOT_FREEZE
+SNAPSHOT_UNFREEZE
+ thaw user space processes frozen by SNAPSHOT_FREEZE
-SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
+SNAPSHOT_CREATE_IMAGE
+ create a snapshot of the system memory; the
last argument of ioctl() should be a pointer to an int variable,
the value of which will indicate whether the call returned after
creating the snapshot (1) or after restoring the system memory state
@@ -45,48 +51,59 @@ SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
has been created the read() operation can be used to transfer
it out of the kernel
-SNAPSHOT_ATOMIC_RESTORE - restore the system memory state from the
+SNAPSHOT_ATOMIC_RESTORE
+ restore the system memory state from the
uploaded snapshot image; before calling it you should transfer
the system memory snapshot back to the kernel using the write()
operation; this call will not succeed if the snapshot
image is not available to the kernel
-SNAPSHOT_FREE - free memory allocated for the snapshot image
+SNAPSHOT_FREE
+ free memory allocated for the snapshot image
-SNAPSHOT_PREF_IMAGE_SIZE - set the preferred maximum size of the image
+SNAPSHOT_PREF_IMAGE_SIZE
+ set the preferred maximum size of the image
(the kernel will do its best to ensure the image size will not exceed
this number, but if it turns out to be impossible, the kernel will
create the smallest image possible)
-SNAPSHOT_GET_IMAGE_SIZE - return the actual size of the hibernation image
+SNAPSHOT_GET_IMAGE_SIZE
+ return the actual size of the hibernation image
-SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the
+SNAPSHOT_AVAIL_SWAP_SIZE
+ return the amount of available swap in bytes (the
last argument should be a pointer to an unsigned int variable that will
contain the result if the call is successful).
-SNAPSHOT_ALLOC_SWAP_PAGE - allocate a swap page from the resume partition
+SNAPSHOT_ALLOC_SWAP_PAGE
+ allocate a swap page from the resume partition
(the last argument should be a pointer to a loff_t variable that
will contain the swap page offset if the call is successful)
-SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated by
+SNAPSHOT_FREE_SWAP_PAGES
+ free all swap pages allocated by
SNAPSHOT_ALLOC_SWAP_PAGE
-SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
+SNAPSHOT_SET_SWAP_AREA
+ set the resume partition and the offset (in <PAGE_SIZE>
units) from the beginning of the partition at which the swap header is
located (the last ioctl() argument should point to a struct
resume_swap_area, as defined in kernel/power/suspend_ioctls.h,
containing the resume device specification and the offset); for swap
partitions the offset is always 0, but it is different from zero for
- swap files (see Documentation/power/swsusp-and-swap-files.txt for
+ swap files (see Documentation/power/swsusp-and-swap-files.rst for
details).
-SNAPSHOT_PLATFORM_SUPPORT - enable/disable the hibernation platform support,
+SNAPSHOT_PLATFORM_SUPPORT
+ enable/disable the hibernation platform support,
depending on the argument value (enable, if the argument is nonzero)
-SNAPSHOT_POWER_OFF - make the kernel transition the system to the hibernation
+SNAPSHOT_POWER_OFF
+ make the kernel transition the system to the hibernation
state (eg. ACPI S4) using the platform (eg. ACPI) driver
-SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
+SNAPSHOT_S2RAM
+ suspend to RAM; using this call causes the kernel to
immediately enter the suspend-to-RAM state, so this call must always
be preceded by the SNAPSHOT_FREEZE call and it is also necessary
to use the SNAPSHOT_UNFREEZE call after the system wakes up. This call
@@ -98,10 +115,11 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
The device's read() operation can be used to transfer the snapshot image from
the kernel. It has the following limitations:
+
- you cannot read() more than one virtual memory page at a time
- read()s across page boundaries are impossible (ie. if you read() 1/2 of
- a page in the previous call, you will only be able to read()
- _at_ _most_ 1/2 of the page in the next call)
+ a page in the previous call, you will only be able to read()
+ **at most** 1/2 of the page in the next call)
The device's write() operation is used for uploading the system memory snapshot
into the kernel. It has the same limitations as the read() operation.
@@ -143,8 +161,10 @@ preferably using mlockall(), before calling SNAPSHOT_FREEZE.
The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE
in the memory location pointed to by the last argument of ioctl() and proceed
in accordance with it:
+
1. If the value is 1 (ie. the system memory snapshot has just been
created and the system is ready for saving it):
+
(a) The suspending utility MUST NOT close the snapshot device
_unless_ the whole suspend procedure is to be cancelled, in
which case, if the snapshot image has already been saved, the
@@ -158,6 +178,7 @@ in accordance with it:
called. However, it MAY mount a file system that was not
mounted at that time and perform some operations on it (eg.
use it for saving the image).
+
2. If the value is 0 (ie. the system state has just been restored from
the snapshot image), the suspending utility MUST close the snapshot
device. Afterwards it will be treated as a regular userland process,
diff --git a/Documentation/power/video.txt b/Documentation/power/video.rst
similarity index 56%
rename from Documentation/power/video.txt
rename to Documentation/power/video.rst
index 3e6272bc4472..337a2ba9f32f 100644
--- a/Documentation/power/video.txt
+++ b/Documentation/power/video.rst
@@ -1,7 +1,8 @@
+===========================
+Video issues with S3 resume
+===========================
- Video issues with S3 resume
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
- 2003-2006, Pavel Machek
+2003-2006, Pavel Machek
During S3 resume, hardware needs to be reinitialized. For most
devices, this is easy, and kernel driver knows how to do
@@ -41,37 +42,37 @@ There are a few types of systems where video works after S3 resume:
(1) systems where video state is preserved over S3.
(2) systems where it is possible to call the video BIOS during S3
- resume. Unfortunately, it is not correct to call the video BIOS at
- that point, but it happens to work on some machines. Use
- acpi_sleep=s3_bios.
+ resume. Unfortunately, it is not correct to call the video BIOS at
+ that point, but it happens to work on some machines. Use
+ acpi_sleep=s3_bios.
(3) systems that initialize video card into vga text mode and where
- the BIOS works well enough to be able to set video mode. Use
- acpi_sleep=s3_mode on these.
+ the BIOS works well enough to be able to set video mode. Use
+ acpi_sleep=s3_mode on these.
(4) on some systems s3_bios kicks video into text mode, and
- acpi_sleep=s3_bios,s3_mode is needed.
+ acpi_sleep=s3_bios,s3_mode is needed.
(5) radeon systems, where X can soft-boot your video card. You'll need
- a new enough X, and a plain text console (no vesafb or radeonfb). See
- http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information.
- Alternatively, you should use vbetool (6) instead.
+ a new enough X, and a plain text console (no vesafb or radeonfb). See
+ http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information.
+ Alternatively, you should use vbetool (6) instead.
(6) other radeon systems, where vbetool is enough to bring system back
- to life. It needs text console to be working. Do vbetool vbestate
- save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool
- vbestate restore < /tmp/delme; setfont <whatever>, and your video
- should work.
+ to life. It needs text console to be working. Do vbetool vbestate
+ save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool
+ vbestate restore < /tmp/delme; setfont <whatever>, and your video
+ should work.
(7) on some systems, it is possible to boot most of kernel, and then
- POSTing bios works. Ole Rohne has patch to do just that at
- http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2.
+ POSTing bios works. Ole Rohne has patch to do just that at
+ http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2.
-(8) on some systems, you can use the video_post utility and or
- do echo 3 > /sys/power/state && /usr/sbin/video_post - which will
- initialize the display in console mode. If you are in X, you can switch
- to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get
- the display working in graphical mode again.
+(8) on some systems, you can use the video_post utility and or
+ do echo 3 > /sys/power/state && /usr/sbin/video_post - which will
+ initialize the display in console mode. If you are in X, you can switch
+ to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get
+ the display working in graphical mode again.
Now, if you pass acpi_sleep=something, and it does not work with your
bios, you'll get a hard crash during resume. Be careful. Also it is
@@ -87,99 +88,126 @@ chance of working.
Table of known working notebooks:
+
+=============================== ===============================================
Model hack (or "how to do it")
-------------------------------------------------------------------------------
+=============================== ===============================================
Acer Aspire 1406LC ole's late BIOS init (7), turn off DRI
Acer TM 230 s3_bios (2)
Acer TM 242FX vbetool (6)
Acer TM C110 video_post (8)
-Acer TM C300 vga=normal (only suspend on console, not in X), vbetool (6) or video_post (8)
+Acer TM C300 vga=normal (only suspend on console, not in X),
+ vbetool (6) or video_post (8)
Acer TM 4052LCi s3_bios (2)
Acer TM 636Lci s3_bios,s3_mode (4)
-Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text console back
-Acer TM 660 ??? (*)
-Acer TM 800 vga=normal, X patches, see webpage (5) or vbetool (6)
-Acer TM 803 vga=normal, X patches, see webpage (5) or vbetool (6)
+Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text
+ console back
+Acer TM 660 ??? [#f1]_
+Acer TM 800 vga=normal, X patches, see webpage (5)
+ or vbetool (6)
+Acer TM 803 vga=normal, X patches, see webpage (5)
+ or vbetool (6)
Acer TM 803LCi vga=normal, vbetool (6)
Arima W730a vbetool needed (6)
-Asus L2400D s3_mode (3)(***) (S1 also works OK)
+Asus L2400D s3_mode (3) [#f2]_ (S1 also works OK)
Asus L3350M (SiS 740) (6)
Asus L3800C (Radeon M7) s3_bios (2) (S1 also works OK)
-Asus M6887Ne vga=normal, s3_bios (2), use radeon driver instead of fglrx in x.org
+Asus M6887Ne vga=normal, s3_bios (2), use radeon driver
+ instead of fglrx in x.org
Athlon64 desktop prototype s3_bios (2)
-Compal CL-50 ??? (*)
+Compal CL-50 ??? [#f1]_
Compaq Armada E500 - P3-700 none (1) (S1 also works OK)
Compaq Evo N620c vga=normal, s3_bios (2)
Dell 600m, ATI R250 Lf none (1), but needs xorg-x11-6.8.1.902-1
Dell D600, ATI RV250 vga=normal and X, or try vbestate (6)
-Dell D610 vga=normal and X (possibly vbestate (6) too, but not tested)
-Dell Inspiron 4000 ??? (*)
-Dell Inspiron 500m ??? (*)
+Dell D610 vga=normal and X (possibly vbestate (6) too,
+ but not tested)
+Dell Inspiron 4000 ??? [#f1]_
+Dell Inspiron 500m ??? [#f1]_
Dell Inspiron 510m ???
Dell Inspiron 5150 vbetool needed (6)
-Dell Inspiron 600m ??? (*)
-Dell Inspiron 8200 ??? (*)
-Dell Inspiron 8500 ??? (*)
-Dell Inspiron 8600 ??? (*)
-eMachines athlon64 machines vbetool needed (6) (someone please get me model #s)
-HP NC6000 s3_bios, may not use radeonfb (2); or vbetool (6)
-HP NX7000 ??? (*)
-HP Pavilion ZD7000 vbetool post needed, need open-source nv driver for X
+Dell Inspiron 600m ??? [#f1]_
+Dell Inspiron 8200 ??? [#f1]_
+Dell Inspiron 8500 ??? [#f1]_
+Dell Inspiron 8600 ??? [#f1]_
+eMachines athlon64 machines vbetool needed (6) (someone please get
+ me model #s)
+HP NC6000 s3_bios, may not use radeonfb (2);
+ or vbetool (6)
+HP NX7000 ??? [#f1]_
+HP Pavilion ZD7000 vbetool post needed, need open-source nv
+ driver for X
HP Omnibook XE3 athlon version none (1)
HP Omnibook XE3GC none (1), video is S3 Savage/IX-MV
HP Omnibook XE3L-GF vbetool (6)
HP Omnibook 5150 none (1), (S1 also works OK)
-IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294 Savage/IX-MV, vesafb gets "interesting" but X work.
-IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with BIOS 1.04 2002-08-23, but not at all with BIOS 1.11 2004-11-05 :-(]
+IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294
+ Savage/IX-MV, vesafb gets "interesting"
+ but X work.
+IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with
+ BIOS 1.04 2002-08-23, but not at all with
+ BIOS 1.11 2004-11-05 :-(]
IBM TP R32 / Type 2658-MMG none (1)
-IBM TP R40 2722B3G ??? (*)
+IBM TP R40 2722B3G ??? [#f1]_
IBM TP R50p / Type 1832-22U s3_bios (2)
IBM TP R51 none (1)
-IBM TP T30 236681A ??? (*)
+IBM TP T30 236681A ??? [#f1]_
IBM TP T40 / Type 2373-MU4 none (1)
IBM TP T40p none (1)
IBM TP R40p s3_bios (2)
IBM TP T41p s3_bios (2), switch to X after resume
IBM TP T42 s3_bios (2)
IBM ThinkPad T42p (2373-GTG) s3_bios (2)
-IBM TP X20 ??? (*)
+IBM TP X20 ??? [#f1]_
IBM TP X30 s3_bios, s3_mode (4)
-IBM TP X31 / Type 2672-XXH none (1), use radeontool (http://fdd.com/software/radeon/) to turn off backlight.
-IBM TP X32 none (1), but backlight is on and video is trashed after long suspend. s3_bios,s3_mode (4) works too. Perhaps that gets better results?
+IBM TP X31 / Type 2672-XXH none (1), use radeontool
+ (http://fdd.com/software/radeon/) to
+ turn off backlight.
+IBM TP X32 none (1), but backlight is on and video is
+ trashed after long suspend. s3_bios,
+ s3_mode (4) works too. Perhaps that gets
+ better results?
IBM Thinkpad X40 Type 2371-7JG s3_bios,s3_mode (4)
-IBM TP 600e none(1), but a switch to console and back to X is needed
-Medion MD4220 ??? (*)
+IBM TP 600e none(1), but a switch to console and
+ back to X is needed
+Medion MD4220 ??? [#f1]_
Samsung P35 vbetool needed (6)
Sharp PC-AR10 (ATI rage) none (1), backlight does not switch off
Sony Vaio PCG-C1VRX/K s3_bios (2)
-Sony Vaio PCG-F403 ??? (*)
+Sony Vaio PCG-F403 ??? [#f1]_
Sony Vaio PCG-GRT995MP none (1), works with 'nv' X driver
-Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use radeontool (http://fdd.com/software/radeon/) to turn off backlight.
-Sony Vaio PCG-N505SN ??? (*)
+Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use
+ radeontool (http://fdd.com/software/radeon/)
+ to turn off backlight.
+Sony Vaio PCG-N505SN ??? [#f1]_
Sony Vaio vgn-s260 X or boot-radeon can init it (5)
-Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will be blank unless you return to X.
+Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will
+ be blank unless you return to X.
Sony Vaio vgn-FS115B s3_bios (2),s3_mode (4)
Toshiba Libretto L5 none (1)
Toshiba Libretto 100CT/110CT vbetool (6)
Toshiba Portege 3020CT s3_mode (3)
Toshiba Satellite 4030CDT s3_mode (3) (S1 also works OK)
Toshiba Satellite 4080XCDT s3_mode (3) (S1 also works OK)
-Toshiba Satellite 4090XCDT ??? (*)
-Toshiba Satellite P10-554 s3_bios,s3_mode (4)(****)
+Toshiba Satellite 4090XCDT ??? [#f1]_
+Toshiba Satellite P10-554 s3_bios,s3_mode (4)[#f3]_
Toshiba M30 (2) xor X with nvidia driver using internal AGP
-Uniwill 244IIO ??? (*)
+Uniwill 244IIO ??? [#f1]_
+=============================== ===============================================
Known working desktop systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=================== ============================= ========================
Mainboard Graphics card hack (or "how to do it")
-------------------------------------------------------------------------------
+=================== ============================= ========================
Asus A7V8X nVidia RIVA TNT2 model 64 s3_bios,s3_mode (4)
+=================== ============================= ========================
-(*) from https://wiki.ubuntu.com/HoaryPMResults, not sure
- which options to use. If you know, please tell me.
+.. [#f1] from https://wiki.ubuntu.com/HoaryPMResults, not sure
+ which options to use. If you know, please tell me.
-(***) To be tested with a newer kernel.
+.. [#f2] To be tested with a newer kernel.
-(****) Not with SMP kernel, UP only.
+.. [#f3] Not with SMP kernel, UP only.
diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
index 58bc047e7b95..1acaa14903d6 100644
--- a/Documentation/process/submitting-drivers.rst
+++ b/Documentation/process/submitting-drivers.rst
@@ -117,7 +117,7 @@ PM support:
implemented") error. You should also try to make sure that your
driver uses as little power as possible when it's not doing
anything. For the driver testing instructions see
- Documentation/power/drivers-testing.txt and for a relatively
+ Documentation/power/drivers-testing.rst and for a relatively
complete overview of the power management issues related to
drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`.
diff --git a/Documentation/scheduler/sched-energy.txt b/Documentation/scheduler/sched-energy.txt
index 197d81f4b836..d97207b9accb 100644
--- a/Documentation/scheduler/sched-energy.txt
+++ b/Documentation/scheduler/sched-energy.txt
@@ -22,7 +22,7 @@ the highest.
The actual EM used by EAS is _not_ maintained by the scheduler, but by a
dedicated framework. For details about this framework and what it provides,
-please refer to its documentation (see Documentation/power/energy-model.txt).
+please refer to its documentation (see Documentation/power/energy-model.rst).
2. Background and Terminology
@@ -81,7 +81,7 @@ through the arch_scale_cpu_capacity() callback.
The rest of platform knowledge used by EAS is directly read from the Energy
Model (EM) framework. The EM of a platform is composed of a power cost table
-per 'performance domain' in the system (see Documentation/power/energy-model.txt
+per 'performance domain' in the system (see Documentation/power/energy-model.rst
for futher details about performance domains).
The scheduler manages references to the EM objects in the topology code when the
@@ -352,7 +352,7 @@ could be amended in the future if proven otherwise.
EAS uses the EM of a platform to estimate the impact of scheduling decisions on
energy. So, your platform must provide power cost tables to the EM framework in
order to make EAS start. To do so, please refer to documentation of the
-independent EM framework in Documentation/power/energy-model.txt.
+independent EM framework in Documentation/power/energy-model.rst.
Please also note that the scheduling domains need to be re-built after the
EM has been registered in order to start EAS.
diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt
index f07e38094b40..1a660a39e3c0 100644
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ b/Documentation/trace/coresight-cpu-debug.txt
@@ -151,7 +151,7 @@ At the runtime you can disable idle states with below methods:
It is possible to disable CPU idle states by way of the PM QoS
subsystem, more specifically by using the "/dev/cpu_dma_latency"
-interface (see Documentation/power/pm_qos_interface.txt for more
+interface (see Documentation/power/pm_qos_interface.rst for more
details). As specified in the PM QoS documentation the requested
parameter will stay in effect until the file descriptor is released.
For example:
diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst
index 72c6cd935821..f1c3906c69a8 100644
--- a/Documentation/translations/zh_CN/process/submitting-drivers.rst
+++ b/Documentation/translations/zh_CN/process/submitting-drivers.rst
@@ -97,7 +97,7 @@ Linux 2.6:
函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确
保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动
程序测试的指导，请参阅
- Documentation/power/drivers-testing.txt。有关驱动程序电
+ Documentation/power/drivers-testing.rst。有关驱动程序电
源管理问题相对全面的概述，请参阅
Documentation/driver-api/pm/devices.rst。
diff --git a/MAINTAINERS b/MAINTAINERS
index 5fdbf6e78d46..1c9ed0a5a9df 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -6491,7 +6491,7 @@ M: "Rafael J. Wysocki" <rjw@rjwysocki.net>
M: Pavel Machek <pavel@ucw.cz>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/power/freezing-of-tasks.txt
+F: Documentation/power/freezing-of-tasks.rst
F: include/linux/freezer.h
F: kernel/freezer.c
@@ -11825,7 +11825,7 @@ S: Maintained
T: git git://git.kernel.org/pub/scm/linux/kernel/git/vireshk/pm.git
F: drivers/opp/
F: include/linux/pm_opp.h
-F: Documentation/power/opp.txt
+F: Documentation/power/opp.rst
F: Documentation/devicetree/bindings/opp/
OPL4 DRIVER
diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
index a109141a8d3b..bc5e1c218d4d 100644
--- a/arch/x86/Kconfig
+++ b/arch/x86/Kconfig
@@ -2448,7 +2448,7 @@ menuconfig APM
machines with more than one CPU.
In order to use APM, you will need supporting software. For location
- and more information, read <file:Documentation/power/apm-acpi.txt>
+ and more information, read <file:Documentation/power/apm-acpi.rst>
and the Battery Powered Linux mini-HOWTO, available from
<http://www.tldp.org/docs.html#howto>.
diff --git a/drivers/gpu/drm/i915/i915_drv.h b/drivers/gpu/drm/i915/i915_drv.h
index 0ea7f78ae227..eeb7edfa3597 100644
--- a/drivers/gpu/drm/i915/i915_drv.h
+++ b/drivers/gpu/drm/i915/i915_drv.h
@@ -1069,7 +1069,7 @@ struct skl_wm_params {
* to be disabled. This shouldn't happen and we'll print some error messages in
* case it happens.
*
- * For more, read the Documentation/power/runtime_pm.txt.
+ * For more, read the Documentation/power/runtime_pm.rst.
*/
struct i915_runtime_pm {
atomic_t wakeref_count;
diff --git a/drivers/opp/Kconfig b/drivers/opp/Kconfig
index fe54d349d2e1..35dfc7e80f92 100644
--- a/drivers/opp/Kconfig
+++ b/drivers/opp/Kconfig
@@ -11,4 +11,4 @@ config PM_OPP
OPP layer organizes the data internally using device pointers
representing individual voltage domains and provides SOC
implementations a ready to use framework to manage OPPs.
- For more information, read <file:Documentation/power/opp.txt>
+ For more information, read <file:Documentation/power/opp.rst>
diff --git a/drivers/power/supply/power_supply_core.c b/drivers/power/supply/power_supply_core.c
index 136e8f64848a..b55cdfe22a2e 100644
--- a/drivers/power/supply/power_supply_core.c
+++ b/drivers/power/supply/power_supply_core.c
@@ -606,7 +606,7 @@ int power_supply_get_battery_info(struct power_supply *psy,
/* The property and field names below must correspond to elements
* in enum power_supply_property. For reasoning, see
- * Documentation/power/power_supply_class.txt.
+ * Documentation/power/power_supply_class.rst.
*/
of_property_read_u32(battery_np, "energy-full-design-microwatt-hours",
diff --git a/include/linux/interrupt.h b/include/linux/interrupt.h
index c7eef32e7739..5b8328a99b2a 100644
--- a/include/linux/interrupt.h
+++ b/include/linux/interrupt.h
@@ -52,7 +52,7 @@
* irq line disabled until the threaded handler has been run.
* IRQF_NO_SUSPEND - Do not disable this IRQ during suspend. Does not guarantee
* that this interrupt will wake the system from a suspended
- * state. See Documentation/power/suspend-and-interrupts.txt
+ * state. See Documentation/power/suspend-and-interrupts.rst
* IRQF_FORCE_RESUME - Force enable it on resume even if IRQF_NO_SUSPEND is set
* IRQF_NO_THREAD - Interrupt cannot be threaded
* IRQF_EARLY_RESUME - Resume IRQ early during syscore instead of at device
diff --git a/include/linux/pci.h b/include/linux/pci.h
index 44d254548ca7..41c5673aba2f 100644
--- a/include/linux/pci.h
+++ b/include/linux/pci.h
@@ -808,7 +808,7 @@ struct module;
* @suspend_late: Put device into low power state.
* @resume_early: Wake device from low power state.
* @resume: Wake device from low power state.
- * (Please see Documentation/power/pci.txt for descriptions
+ * (Please see Documentation/power/pci.rst for descriptions
* of PCI Power Management and the related functions.)
* @shutdown: Hook into reboot_notifier_list (kernel/sys.c).
* Intended to stop any idling DMA operations.
diff --git a/include/linux/pm.h b/include/linux/pm.h
index 345d74a727e3..220e2008467d 100644
--- a/include/linux/pm.h
+++ b/include/linux/pm.h
@@ -271,7 +271,7 @@ typedef struct pm_message {
* actions to be performed by a device driver's callbacks generally depend on
* the platform and subsystem the device belongs to.
*
- * Refer to Documentation/power/runtime_pm.txt for more information about the
+ * Refer to Documentation/power/runtime_pm.rst for more information about the
* role of the @runtime_suspend(), @runtime_resume() and @runtime_idle()
* callbacks in device runtime power management.
*/
diff --git a/kernel/power/Kconfig b/kernel/power/Kconfig
index ff8592ddedee..d3667b4075c1 100644
--- a/kernel/power/Kconfig
+++ b/kernel/power/Kconfig
@@ -66,7 +66,7 @@ config HIBERNATION
need to run mkswap against the swap partition used for the suspend.
It also works with swap files to a limited extent (for details see
- <file:Documentation/power/swsusp-and-swap-files.txt>).
+ <file:Documentation/power/swsusp-and-swap-files.rst>).
Right now you may boot without resuming and resume later but in the
meantime you cannot use the swap partition(s)/file(s) involved in
@@ -75,7 +75,7 @@ config HIBERNATION
MOUNT any journaled filesystems mounted before the suspend or they
will get corrupted in a nasty way.
- For more information take a look at <file:Documentation/power/swsusp.txt>.
+ For more information take a look at <file:Documentation/power/swsusp.rst>.
config ARCH_SAVE_PAGE_KEYS
bool
@@ -256,7 +256,7 @@ config APM_EMULATION
notification of APM "events" (e.g. battery status change).
In order to use APM, you will need supporting software. For location
- and more information, read <file:Documentation/power/apm-acpi.txt>
+ and more information, read <file:Documentation/power/apm-acpi.rst>
and the Battery Powered Linux mini-HOWTO, available from
<http://www.tldp.org/docs.html#howto>.
diff --git a/net/wireless/Kconfig b/net/wireless/Kconfig
index 6310ddede220..cc70f5932773 100644
--- a/net/wireless/Kconfig
+++ b/net/wireless/Kconfig
@@ -166,7 +166,7 @@ config CFG80211_DEFAULT_PS
If this causes your applications to misbehave you should fix your
applications instead -- they need to register their network
- latency requirement, see Documentation/power/pm_qos_interface.txt.
+ latency requirement, see Documentation/power/pm_qos_interface.rst.
config CFG80211_DEBUGFS
bool "cfg80211 DebugFS entries"
--
2.21.0
_______________________________________________
Intel-gfx mailing list
Intel-gfx@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH v5] docs: power: convert docs to ReST and rename to *.rst
2019-06-13 10:10 ` [PATCH v5] docs: power: " Mauro Carvalho Chehab
@ 2019-06-14 20:36 ` Jonathan Corbet
2019-06-14 21:14 ` Bjorn Helgaas
0 siblings, 1 reply; 12+ messages in thread
From: Jonathan Corbet @ 2019-06-14 20:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Sebastian Reichel, Rafael J. Wysocki, Viresh Kumar, Len Brown,
Pavel Machek, Nishanth Menon, Stephen Boyd, Liam Girdwood,
Mark Brown, Mathieu Poirier, Suzuki K Poulose, Harry Wei,
Alex Shi, Thomas Gleixner, Ingo Molnar, Borislav Petkov,
H. Peter Anvin, x86, Jani Nikula <ja>
On Thu, 13 Jun 2019 07:10:36 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> Acked-by: Mark Brown <broonie@kernel.org>
> Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
So I can't apply this one due to conflicts in include/linux/pci.h. Bjorn,
perhaps the easiest thing is for you to take this one through your tree?
Thanks,
jon
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH v5] docs: power: convert docs to ReST and rename to *.rst
2019-06-14 20:36 ` Jonathan Corbet
@ 2019-06-14 21:14 ` Bjorn Helgaas
0 siblings, 0 replies; 12+ messages in thread
From: Bjorn Helgaas @ 2019-06-14 21:14 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Linux Doc Mailing List,
Mauro Carvalho Chehab, linux-kernel, Sebastian Reichel,
Rafael J. Wysocki, Viresh Kumar, Len Brown, Pavel Machek,
Nishanth Menon, Stephen Boyd, Liam Girdwood, Mark Brown,
Mathieu Poirier, Suzuki K Poulose, Harry Wei, Alex Shi,
Thomas Gleixner, Ingo Molnar, Borislav Petkov, H. Peter
On Fri, Jun 14, 2019 at 02:36:31PM -0600, Jonathan Corbet wrote:
> On Thu, 13 Jun 2019 07:10:36 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > Convert the PM documents to ReST, in order to allow them to
> > build with Sphinx.
> >
> > The conversion is actually:
> > - add blank lines and identation in order to identify paragraphs;
> > - fix tables markups;
> > - add some lists markups;
> > - mark literal blocks;
> > - adjust title markups.
> >
> > At its new index.rst, let's add a :orphan: while this is not linked to
> > the main index.rst file, in order to avoid build warnings.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > Acked-by: Mark Brown <broonie@kernel.org>
> > Acked-by: Bjorn Helgaas <bhelgaas@google.com>
> > Acked-by: Srivatsa S. Bhat (VMware) <srivatsa@csail.mit.edu>
>
> So I can't apply this one due to conflicts in include/linux/pci.h. Bjorn,
> perhaps the easiest thing is for you to take this one through your tree?
OK, I applied this to pci/docs for v5.3. I applied this entire patch,
but if you would prefer that I only apply the PCI-related parts, let
me know and I'll split those out.
Bjorn
^ permalink raw reply [flat|nested] 12+ messages in thread
[parent not found: <fac44e1fbab5ea755a93601a4fdfa34fcc57ae9e.1560361364.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>]
* Re: [PATCH v4 18/28] docs: convert docs to ReST and rename to *.rst
[not found] ` <fac44e1fbab5ea755a93601a4fdfa34fcc57ae9e.1560361364.git.mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
@ 2019-06-13 15:58 ` Mathieu Poirier
0 siblings, 0 replies; 12+ messages in thread
From: Mathieu Poirier @ 2019-06-13 15:58 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel-u79uwXL29TY76Z2rM5mHXA, Jonathan Corbet,
Sebastian Reichel, Rafael J. Wysocki, Viresh Kumar, Len Brown,
Pavel Machek, Nishanth Menon, Stephen Boyd, Liam Girdwood,
Mark Brown, Suzuki K Poulose, Harry Wei, Alex Shi,
Thomas Gleixner, Ingo Molnar, Borislav Petkov, H. Peter Anvin,
x86-DgEjT+Ai2ygdnm+yROfE0A, Jani Nikula
On Wed, Jun 12, 2019 at 02:52:54PM -0300, Mauro Carvalho Chehab wrote:
> Convert the PM documents to ReST, in order to allow them to
> build with Sphinx.
>
> The conversion is actually:
> - add blank lines and identation in order to identify paragraphs;
> - fix tables markups;
> - add some lists markups;
> - mark literal blocks;
> - adjust title markups.
>
> At its new index.rst, let's add a :orphan: while this is not linked to
> the main index.rst file, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> Acked-by: Bjorn Helgaas <bhelgaas-hpIqsD4AKlfQT0dZR+AlfA@public.gmane.org>
> Acked-by: Mark Brown <broonie-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> ---
> .../ABI/testing/sysfs-class-powercap | 2 +-
> .../admin-guide/kernel-parameters.txt | 6 +-
> Documentation/cpu-freq/core.txt | 2 +-
> Documentation/driver-api/pm/devices.rst | 6 +-
> .../driver-api/usb/power-management.rst | 2 +-
> .../power/{apm-acpi.txt => apm-acpi.rst} | 10 +-
> ...m-debugging.txt => basic-pm-debugging.rst} | 79 +--
> ...harger-manager.txt => charger-manager.rst} | 101 ++--
> ...rivers-testing.txt => drivers-testing.rst} | 15 +-
> .../{energy-model.txt => energy-model.rst} | 101 ++--
> ...ing-of-tasks.txt => freezing-of-tasks.rst} | 91 ++--
> Documentation/power/index.rst | 46 ++
> .../power/{interface.txt => interface.rst} | 24 +-
> Documentation/power/{opp.txt => opp.rst} | 175 +++---
> Documentation/power/{pci.txt => pci.rst} | 87 ++-
> ...qos_interface.txt => pm_qos_interface.rst} | 127 +++--
> Documentation/power/power_supply_class.rst | 282 ++++++++++
> Documentation/power/power_supply_class.txt | 231 --------
> Documentation/power/powercap/powercap.rst | 257 +++++++++
> Documentation/power/powercap/powercap.txt | 236 ---------
> .../regulator/{consumer.txt => consumer.rst} | 141 ++---
> .../regulator/{design.txt => design.rst} | 9 +-
> .../regulator/{machine.txt => machine.rst} | 47 +-
> .../regulator/{overview.txt => overview.rst} | 57 +-
> Documentation/power/regulator/regulator.rst | 32 ++
> Documentation/power/regulator/regulator.txt | 30 --
> .../power/{runtime_pm.txt => runtime_pm.rst} | 234 ++++----
> Documentation/power/{s2ram.txt => s2ram.rst} | 20 +-
> ...hotplug.txt => suspend-and-cpuhotplug.rst} | 42 +-
> ...errupts.txt => suspend-and-interrupts.rst} | 2 +
> ...ap-files.txt => swsusp-and-swap-files.rst} | 17 +-
> ...{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} | 120 ++---
> Documentation/power/swsusp.rst | 501 ++++++++++++++++++
> Documentation/power/swsusp.txt | 446 ----------------
> .../power/{tricks.txt => tricks.rst} | 6 +-
> ...serland-swsusp.txt => userland-swsusp.rst} | 55 +-
> Documentation/power/{video.txt => video.rst} | 156 +++---
> Documentation/process/submitting-drivers.rst | 2 +-
> Documentation/scheduler/sched-energy.txt | 6 +-
> Documentation/trace/coresight-cpu-debug.txt | 2 +-
For the coresight-debug part:
Reviewed-by: Mathieu Poirier <mathieu.poirier-QSEj5FYQhm4dnm+yROfE0A@public.gmane.org>
> .../zh_CN/process/submitting-drivers.rst | 2 +-
> MAINTAINERS | 4 +-
> arch/x86/Kconfig | 2 +-
> drivers/gpu/drm/i915/i915_drv.h | 2 +-
> drivers/opp/Kconfig | 2 +-
> drivers/power/supply/power_supply_core.c | 2 +-
> include/linux/interrupt.h | 2 +-
> include/linux/pci.h | 2 +-
> include/linux/pm.h | 2 +-
> kernel/power/Kconfig | 6 +-
> net/wireless/Kconfig | 2 +-
> 51 files changed, 2126 insertions(+), 1707 deletions(-)
> rename Documentation/power/{apm-acpi.txt => apm-acpi.rst} (87%)
> rename Documentation/power/{basic-pm-debugging.txt => basic-pm-debugging.rst} (87%)
> rename Documentation/power/{charger-manager.txt => charger-manager.rst} (78%)
> rename Documentation/power/{drivers-testing.txt => drivers-testing.rst} (86%)
> rename Documentation/power/{energy-model.txt => energy-model.rst} (74%)
> rename Documentation/power/{freezing-of-tasks.txt => freezing-of-tasks.rst} (75%)
> create mode 100644 Documentation/power/index.rst
> rename Documentation/power/{interface.txt => interface.rst} (84%)
> rename Documentation/power/{opp.txt => opp.rst} (78%)
> rename Documentation/power/{pci.txt => pci.rst} (97%)
> rename Documentation/power/{pm_qos_interface.txt => pm_qos_interface.rst} (62%)
> create mode 100644 Documentation/power/power_supply_class.rst
> delete mode 100644 Documentation/power/power_supply_class.txt
> create mode 100644 Documentation/power/powercap/powercap.rst
> delete mode 100644 Documentation/power/powercap/powercap.txt
> rename Documentation/power/regulator/{consumer.txt => consumer.rst} (61%)
> rename Documentation/power/regulator/{design.txt => design.rst} (86%)
> rename Documentation/power/regulator/{machine.txt => machine.rst} (75%)
> rename Documentation/power/regulator/{overview.txt => overview.rst} (79%)
> create mode 100644 Documentation/power/regulator/regulator.rst
> delete mode 100644 Documentation/power/regulator/regulator.txt
> rename Documentation/power/{runtime_pm.txt => runtime_pm.rst} (89%)
> rename Documentation/power/{s2ram.txt => s2ram.rst} (92%)
> rename Documentation/power/{suspend-and-cpuhotplug.txt => suspend-and-cpuhotplug.rst} (90%)
> rename Documentation/power/{suspend-and-interrupts.txt => suspend-and-interrupts.rst} (98%)
> rename Documentation/power/{swsusp-and-swap-files.txt => swsusp-and-swap-files.rst} (83%)
> rename Documentation/power/{swsusp-dmcrypt.txt => swsusp-dmcrypt.rst} (67%)
> create mode 100644 Documentation/power/swsusp.rst
> delete mode 100644 Documentation/power/swsusp.txt
> rename Documentation/power/{tricks.txt => tricks.rst} (93%)
> rename Documentation/power/{userland-swsusp.txt => userland-swsusp.rst} (85%)
> rename Documentation/power/{video.txt => video.rst} (56%)
>
> diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
> index db3b3ff70d84..742dfd966592 100644
> --- a/Documentation/ABI/testing/sysfs-class-powercap
> +++ b/Documentation/ABI/testing/sysfs-class-powercap
> @@ -5,7 +5,7 @@ Contact: linux-pm-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> Description:
> The powercap/ class sub directory belongs to the power cap
> subsystem. Refer to
> - Documentation/power/powercap/powercap.txt for details.
> + Documentation/power/powercap/powercap.rst for details.
>
> What: /sys/class/powercap/<control type>
> Date: September 2013
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index c31373f39240..0092a453f7dc 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -13,7 +13,7 @@
> For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force"
> are available
>
> - See also Documentation/power/runtime_pm.txt, pci=noacpi
> + See also Documentation/power/runtime_pm.rst, pci=noacpi
>
> acpi_apic_instance= [ACPI, IOAPIC]
> Format: <int>
> @@ -223,7 +223,7 @@
> acpi_sleep= [HW,ACPI] Sleep options
> Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig,
> old_ordering, nonvs, sci_force_enable, nobl }
> - See Documentation/power/video.txt for information on
> + See Documentation/power/video.rst for information on
> s3_bios and s3_mode.
> s3_beep is for debugging; it makes the PC's speaker beep
> as soon as the kernel's real-mode entry point is called.
> @@ -4128,7 +4128,7 @@
> Specify the offset from the beginning of the partition
> given by "resume=" at which the swap header is located,
> in <PAGE_SIZE> units (needed only for swap files).
> - See Documentation/power/swsusp-and-swap-files.txt
> + See Documentation/power/swsusp-and-swap-files.rst
>
> resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to
> read the resume files
> diff --git a/Documentation/cpu-freq/core.txt b/Documentation/cpu-freq/core.txt
> index 073f128af5a7..55193e680250 100644
> --- a/Documentation/cpu-freq/core.txt
> +++ b/Documentation/cpu-freq/core.txt
> @@ -95,7 +95,7 @@ flags - flags of the cpufreq driver
>
> 3. CPUFreq Table Generation with Operating Performance Point (OPP)
> ==================================================================
> -For details about OPP, see Documentation/power/opp.txt
> +For details about OPP, see Documentation/power/opp.rst
>
> dev_pm_opp_init_cpufreq_table -
> This function provides a ready to use conversion routine to translate
> diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst
> index 30835683616a..f66c7b9126ea 100644
> --- a/Documentation/driver-api/pm/devices.rst
> +++ b/Documentation/driver-api/pm/devices.rst
> @@ -225,7 +225,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto`
> flag is clear.
>
> For more information about the runtime power management framework, refer to
> -:file:`Documentation/power/runtime_pm.txt`.
> +:file:`Documentation/power/runtime_pm.rst`.
>
>
> Calling Drivers to Enter and Leave System Sleep States
> @@ -728,7 +728,7 @@ it into account in any way.
>
> Devices may be defined as IRQ-safe which indicates to the PM core that their
> runtime PM callbacks may be invoked with disabled interrupts (see
> -:file:`Documentation/power/runtime_pm.txt` for more information). If an
> +:file:`Documentation/power/runtime_pm.rst` for more information). If an
> IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
> disallowed, unless the domain itself is defined as IRQ-safe. However, it
> makes sense to define a PM domain as IRQ-safe only if all the devices in it
> @@ -795,7 +795,7 @@ so on) and the final state of the device must reflect the "active" runtime PM
> status in that case.
>
> During system-wide resume from a sleep state it's easiest to put devices into
> -the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`.
> +the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
> [Refer to that document for more information regarding this particular issue as
> well as for information on the device runtime power management framework in
> general.]
> diff --git a/Documentation/driver-api/usb/power-management.rst b/Documentation/driver-api/usb/power-management.rst
> index 4a74cf6f2797..2525c3622cae 100644
> --- a/Documentation/driver-api/usb/power-management.rst
> +++ b/Documentation/driver-api/usb/power-management.rst
> @@ -46,7 +46,7 @@ device is turned off while the system as a whole remains running, we
> call it a "dynamic suspend" (also known as a "runtime suspend" or
> "selective suspend"). This document concentrates mostly on how
> dynamic PM is implemented in the USB subsystem, although system PM is
> -covered to some extent (see ``Documentation/power/*.txt`` for more
> +covered to some extent (see ``Documentation/power/*.rst`` for more
> information about system PM).
>
> System PM support is present only if the kernel was built with
> diff --git a/Documentation/power/apm-acpi.txt b/Documentation/power/apm-acpi.rst
> similarity index 87%
> rename from Documentation/power/apm-acpi.txt
> rename to Documentation/power/apm-acpi.rst
> index 6cc423d3662e..5b90d947126d 100644
> --- a/Documentation/power/apm-acpi.txt
> +++ b/Documentation/power/apm-acpi.rst
> @@ -1,5 +1,7 @@
> +============
> APM or ACPI?
> -------------
> +============
> +
> If you have a relatively recent x86 mobile, desktop, or server system,
> odds are it supports either Advanced Power Management (APM) or
> Advanced Configuration and Power Interface (ACPI). ACPI is the newer
> @@ -28,5 +30,7 @@ and be sure that they are started sometime in the system boot process.
> Go ahead and start both. If ACPI or APM is not available on your
> system the associated daemon will exit gracefully.
>
> - apmd: http://ftp.debian.org/pool/main/a/apmd/
> - acpid: http://acpid.sf.net/
> + ===== =======================================
> + apmd http://ftp.debian.org/pool/main/a/apmd/
> + acpid http://acpid.sf.net/
> + ===== =======================================
> diff --git a/Documentation/power/basic-pm-debugging.txt b/Documentation/power/basic-pm-debugging.rst
> similarity index 87%
> rename from Documentation/power/basic-pm-debugging.txt
> rename to Documentation/power/basic-pm-debugging.rst
> index 708f87f78a75..69862e759c30 100644
> --- a/Documentation/power/basic-pm-debugging.txt
> +++ b/Documentation/power/basic-pm-debugging.rst
> @@ -1,12 +1,16 @@
> +=================================
> Debugging hibernation and suspend
> +=================================
> +
> (C) 2007 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>, GPL
>
> 1. Testing hibernation (aka suspend to disk or STD)
> +===================================================
>
> -To check if hibernation works, you can try to hibernate in the "reboot" mode:
> +To check if hibernation works, you can try to hibernate in the "reboot" mode::
>
> -# echo reboot > /sys/power/disk
> -# echo disk > /sys/power/state
> + # echo reboot > /sys/power/disk
> + # echo disk > /sys/power/state
>
> and the system should create a hibernation image, reboot, resume and get back to
> the command prompt where you have started the transition. If that happens,
> @@ -15,20 +19,21 @@ test at least a couple of times in a row for confidence. [This is necessary,
> because some problems only show up on a second attempt at suspending and
> resuming the system.] Moreover, hibernating in the "reboot" and "shutdown"
> modes causes the PM core to skip some platform-related callbacks which on ACPI
> -systems might be necessary to make hibernation work. Thus, if your machine fails
> -to hibernate or resume in the "reboot" mode, you should try the "platform" mode:
> +systems might be necessary to make hibernation work. Thus, if your machine
> +fails to hibernate or resume in the "reboot" mode, you should try the
> +"platform" mode::
>
> -# echo platform > /sys/power/disk
> -# echo disk > /sys/power/state
> + # echo platform > /sys/power/disk
> + # echo disk > /sys/power/state
>
> which is the default and recommended mode of hibernation.
>
> Unfortunately, the "platform" mode of hibernation does not work on some systems
> with broken BIOSes. In such cases the "shutdown" mode of hibernation might
> -work:
> +work::
>
> -# echo shutdown > /sys/power/disk
> -# echo disk > /sys/power/state
> + # echo shutdown > /sys/power/disk
> + # echo disk > /sys/power/state
>
> (it is similar to the "reboot" mode, but it requires you to press the power
> button to make the system resume).
> @@ -37,6 +42,7 @@ If neither "platform" nor "shutdown" hibernation mode works, you will need to
> identify what goes wrong.
>
> a) Test modes of hibernation
> +----------------------------
>
> To find out why hibernation fails on your system, you can use a special testing
> facility available if the kernel is compiled with CONFIG_PM_DEBUG set. Then,
> @@ -44,36 +50,38 @@ there is the file /sys/power/pm_test that can be used to make the hibernation
> core run in a test mode. There are 5 test modes available:
>
> freezer
> -- test the freezing of processes
> + - test the freezing of processes
>
> devices
> -- test the freezing of processes and suspending of devices
> + - test the freezing of processes and suspending of devices
>
> platform
> -- test the freezing of processes, suspending of devices and platform
> - global control methods(*)
> + - test the freezing of processes, suspending of devices and platform
> + global control methods [1]_
>
> processors
> -- test the freezing of processes, suspending of devices, platform
> - global control methods(*) and the disabling of nonboot CPUs
> + - test the freezing of processes, suspending of devices, platform
> + global control methods [1]_ and the disabling of nonboot CPUs
>
> core
> -- test the freezing of processes, suspending of devices, platform global
> - control methods(*), the disabling of nonboot CPUs and suspending of
> - platform/system devices
> + - test the freezing of processes, suspending of devices, platform global
> + control methods\ [1]_, the disabling of nonboot CPUs and suspending
> + of platform/system devices
>
> -(*) the platform global control methods are only available on ACPI systems
> +.. [1]
> +
> + the platform global control methods are only available on ACPI systems
> and are only tested if the hibernation mode is set to "platform"
>
> To use one of them it is necessary to write the corresponding string to
> /sys/power/pm_test (eg. "devices" to test the freezing of processes and
> suspending devices) and issue the standard hibernation commands. For example,
> to use the "devices" test mode along with the "platform" mode of hibernation,
> -you should do the following:
> +you should do the following::
>
> -# echo devices > /sys/power/pm_test
> -# echo platform > /sys/power/disk
> -# echo disk > /sys/power/state
> + # echo devices > /sys/power/pm_test
> + # echo platform > /sys/power/disk
> + # echo disk > /sys/power/state
>
> Then, the kernel will try to freeze processes, suspend devices, wait a few
> seconds (5 by default, but configurable by the suspend.pm_test_delay module
> @@ -108,11 +116,12 @@ If the "devices" test fails, most likely there is a driver that cannot suspend
> or resume its device (in the latter case the system may hang or become unstable
> after the test, so please take that into consideration). To find this driver,
> you can carry out a binary search according to the rules:
> +
> - if the test fails, unload a half of the drivers currently loaded and repeat
> -(that would probably involve rebooting the system, so always note what drivers
> -have been loaded before the test),
> + (that would probably involve rebooting the system, so always note what drivers
> + have been loaded before the test),
> - if the test succeeds, load a half of the drivers you have unloaded most
> -recently and repeat.
> + recently and repeat.
>
> Once you have found the failing driver (there can be more than just one of
> them), you have to unload it every time before hibernation. In that case please
> @@ -146,6 +155,7 @@ indicates a serious problem that very well may be related to the hardware, but
> please report it anyway.
>
> b) Testing minimal configuration
> +--------------------------------
>
> If all of the hibernation test modes work, you can boot the system with the
> "init=/bin/bash" command line parameter and attempt to hibernate in the
> @@ -165,14 +175,15 @@ Again, if you find the offending module(s), it(they) must be unloaded every time
> before hibernation, and please report the problem with it(them).
>
> c) Using the "test_resume" hibernation option
> +---------------------------------------------
>
> /sys/power/disk generally tells the kernel what to do after creating a
> hibernation image. One of the available options is "test_resume" which
> causes the just created image to be used for immediate restoration. Namely,
> -after doing:
> +after doing::
>
> -# echo test_resume > /sys/power/disk
> -# echo disk > /sys/power/state
> + # echo test_resume > /sys/power/disk
> + # echo disk > /sys/power/state
>
> a hibernation image will be created and a resume from it will be triggered
> immediately without involving the platform firmware in any way.
> @@ -190,6 +201,7 @@ to resume may be related to the differences between the restore and image
> kernels.
>
> d) Advanced debugging
> +---------------------
>
> In case that hibernation does not work on your system even in the minimal
> configuration and compiling more drivers as modules is not practical or some
> @@ -200,9 +212,10 @@ kernel messages using the serial console. This may provide you with some
> information about the reasons of the suspend (resume) failure. Alternatively,
> it may be possible to use a FireWire port for debugging with firescope
> (http://v3.sk/~lkundrak/firescope/). On x86 it is also possible to
> -use the PM_TRACE mechanism documented in Documentation/power/s2ram.txt .
> +use the PM_TRACE mechanism documented in Documentation/power/s2ram.rst .
>
> 2. Testing suspend to RAM (STR)
> +===============================
>
> To verify that the STR works, it is generally more convenient to use the s2ram
> tool available from http://suspend.sf.net and documented at
> @@ -230,7 +243,8 @@ you will have to unload them every time before an STR transition (ie. before
> you run s2ram), and please report the problems with them.
>
> There is a debugfs entry which shows the suspend to RAM statistics. Here is an
> -example of its output.
> +example of its output::
> +
> # mount -t debugfs none /sys/kernel/debug
> # cat /sys/kernel/debug/suspend_stats
> success: 20
> @@ -248,6 +262,7 @@ example of its output.
> -16
> last_failed_step: suspend
> suspend
> +
> Field success means the success number of suspend to RAM, and field fail means
> the failure number. Others are the failure number of different steps of suspend
> to RAM. suspend_stats just lists the last 2 failed devices, error number and
> diff --git a/Documentation/power/charger-manager.txt b/Documentation/power/charger-manager.rst
> similarity index 78%
> rename from Documentation/power/charger-manager.txt
> rename to Documentation/power/charger-manager.rst
> index 9ff1105e58d6..84fab9376792 100644
> --- a/Documentation/power/charger-manager.txt
> +++ b/Documentation/power/charger-manager.rst
> @@ -1,4 +1,7 @@
> +===============
> Charger Manager
> +===============
> +
> (C) 2011 MyungJoo Ham <myungjoo.ham-Sze3O3UU22JBDgjK7y7TUQ@public.gmane.org>, GPL
>
> Charger Manager provides in-kernel battery charger management that
> @@ -55,41 +58,39 @@ Charger Manager supports the following:
> notification to users with UEVENT.
>
> 2. Global Charger-Manager Data related with suspend_again
> -========================================================
> +=========================================================
> In order to setup Charger Manager with suspend-again feature
> (in-suspend monitoring), the user should provide charger_global_desc
> -with setup_charger_manager(struct charger_global_desc *).
> +with setup_charger_manager(`struct charger_global_desc *`).
> This charger_global_desc data for in-suspend monitoring is global
> as the name suggests. Thus, the user needs to provide only once even
> if there are multiple batteries. If there are multiple batteries, the
> multiple instances of Charger Manager share the same charger_global_desc
> and it will manage in-suspend monitoring for all instances of Charger Manager.
>
> -The user needs to provide all the three entries properly in order to activate
> -in-suspend monitoring:
> +The user needs to provide all the three entries to `struct charger_global_desc`
> +properly in order to activate in-suspend monitoring:
>
> -struct charger_global_desc {
> -
> -char *rtc_name;
> - : The name of rtc (e.g., "rtc0") used to wakeup the system from
> +`char *rtc_name;`
> + The name of rtc (e.g., "rtc0") used to wakeup the system from
> suspend for Charger Manager. The alarm interrupt (AIE) of the rtc
> should be able to wake up the system from suspend. Charger Manager
> saves and restores the alarm value and use the previously-defined
> alarm if it is going to go off earlier than Charger Manager so that
> Charger Manager does not interfere with previously-defined alarms.
>
> -bool (*rtc_only_wakeup)(void);
> - : This callback should let CM know whether
> +`bool (*rtc_only_wakeup)(void);`
> + This callback should let CM know whether
> the wakeup-from-suspend is caused only by the alarm of "rtc" in the
> same struct. If there is any other wakeup source triggered the
> wakeup, it should return false. If the "rtc" is the only wakeup
> reason, it should return true.
>
> -bool assume_timer_stops_in_suspend;
> - : if true, Charger Manager assumes that
> +`bool assume_timer_stops_in_suspend;`
> + if true, Charger Manager assumes that
> the timer (CM uses jiffies as timer) stops during suspend. Then, CM
> assumes that the suspend-duration is same as the alarm length.
> -};
> +
>
> 3. How to setup suspend_again
> =============================
> @@ -109,26 +110,28 @@ if the system was woken up by Charger Manager and the polling
> =============================================
> For each battery charged independently from other batteries (if a series of
> batteries are charged by a single charger, they are counted as one independent
> -battery), an instance of Charger Manager is attached to it.
> +battery), an instance of Charger Manager is attached to it. The following
>
> -struct charger_desc {
> +struct charger_desc elements:
>
> -char *psy_name;
> - : The power-supply-class name of the battery. Default is
> +`char *psy_name;`
> + The power-supply-class name of the battery. Default is
> "battery" if psy_name is NULL. Users can access the psy entries
> at "/sys/class/power_supply/[psy_name]/".
>
> -enum polling_modes polling_mode;
> - : CM_POLL_DISABLE: do not poll this battery.
> - CM_POLL_ALWAYS: always poll this battery.
> - CM_POLL_EXTERNAL_POWER_ONLY: poll this battery if and only if
> - an external power source is attached.
> - CM_POLL_CHARGING_ONLY: poll this battery if and only if the
> - battery is being charged.
> +`enum polling_modes polling_mode;`
> + CM_POLL_DISABLE:
> + do not poll this battery.
> + CM_POLL_ALWAYS:
> + always poll this battery.
> + CM_POLL_EXTERNAL_POWER_ONLY:
> + poll this battery if and only if an external power
> + source is attached.
> + CM_POLL_CHARGING_ONLY:
> + poll this battery if and only if the battery is being charged.
>
> -unsigned int fullbatt_vchkdrop_ms;
> -unsigned int fullbatt_vchkdrop_uV;
> - : If both have non-zero values, Charger Manager will check the
> +`unsigned int fullbatt_vchkdrop_ms; / unsigned int fullbatt_vchkdrop_uV;`
> + If both have non-zero values, Charger Manager will check the
> battery voltage drop fullbatt_vchkdrop_ms after the battery is fully
> charged. If the voltage drop is over fullbatt_vchkdrop_uV, Charger
> Manager will try to recharge the battery by disabling and enabling
> @@ -136,50 +139,52 @@ unsigned int fullbatt_vchkdrop_uV;
> condition) is needed to be implemented with hardware interrupts from
> fuel gauges or charger devices/chips.
>
> -unsigned int fullbatt_uV;
> - : If specified with a non-zero value, Charger Manager assumes
> +`unsigned int fullbatt_uV;`
> + If specified with a non-zero value, Charger Manager assumes
> that the battery is full (capacity = 100) if the battery is not being
> charged and the battery voltage is equal to or greater than
> fullbatt_uV.
>
> -unsigned int polling_interval_ms;
> - : Required polling interval in ms. Charger Manager will poll
> +`unsigned int polling_interval_ms;`
> + Required polling interval in ms. Charger Manager will poll
> this battery every polling_interval_ms or more frequently.
>
> -enum data_source battery_present;
> - : CM_BATTERY_PRESENT: assume that the battery exists.
> - CM_NO_BATTERY: assume that the battery does not exists.
> - CM_FUEL_GAUGE: get battery presence information from fuel gauge.
> - CM_CHARGER_STAT: get battery presence from chargers.
> +`enum data_source battery_present;`
> + CM_BATTERY_PRESENT:
> + assume that the battery exists.
> + CM_NO_BATTERY:
> + assume that the battery does not exists.
> + CM_FUEL_GAUGE:
> + get battery presence information from fuel gauge.
> + CM_CHARGER_STAT:
> + get battery presence from chargers.
>
> -char **psy_charger_stat;
> - : An array ending with NULL that has power-supply-class names of
> +`char **psy_charger_stat;`
> + An array ending with NULL that has power-supply-class names of
> chargers. Each power-supply-class should provide "PRESENT" (if
> battery_present is "CM_CHARGER_STAT"), "ONLINE" (shows whether an
> external power source is attached or not), and "STATUS" (shows whether
> the battery is {"FULL" or not FULL} or {"FULL", "Charging",
> "Discharging", "NotCharging"}).
>
> -int num_charger_regulators;
> -struct regulator_bulk_data *charger_regulators;
> - : Regulators representing the chargers in the form for
> +`int num_charger_regulators; / struct regulator_bulk_data *charger_regulators;`
> + Regulators representing the chargers in the form for
> regulator framework's bulk functions.
>
> -char *psy_fuel_gauge;
> - : Power-supply-class name of the fuel gauge.
> +`char *psy_fuel_gauge;`
> + Power-supply-class name of the fuel gauge.
>
> -int (*temperature_out_of_range)(int *mC);
> -bool measure_battery_temp;
> - : This callback returns 0 if the temperature is safe for charging,
> +`int (*temperature_out_of_range)(int *mC); / bool measure_battery_temp;`
> + This callback returns 0 if the temperature is safe for charging,
> a positive number if it is too hot to charge, and a negative number
> if it is too cold to charge. With the variable mC, the callback returns
> the temperature in 1/1000 of centigrade.
> The source of temperature can be battery or ambient one according to
> the value of measure_battery_temp.
> -};
> +
>
> 5. Notify Charger-Manager of charger events: cm_notify_event()
> -=========================================================
> +==============================================================
> If there is an charger event is required to notify
> Charger Manager, a charger device driver that triggers the event can call
> cm_notify_event(psy, type, msg) to notify the corresponding Charger Manager.
> diff --git a/Documentation/power/drivers-testing.txt b/Documentation/power/drivers-testing.rst
> similarity index 86%
> rename from Documentation/power/drivers-testing.txt
> rename to Documentation/power/drivers-testing.rst
> index 638afdf4d6b8..e53f1999fc39 100644
> --- a/Documentation/power/drivers-testing.txt
> +++ b/Documentation/power/drivers-testing.rst
> @@ -1,7 +1,11 @@
> +====================================================
> Testing suspend and resume support in device drivers
> +====================================================
> +
> (C) 2007 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>, GPL
>
> 1. Preparing the test system
> +============================
>
> Unfortunately, to effectively test the support for the system-wide suspend and
> resume transitions in a driver, it is necessary to suspend and resume a fully
> @@ -14,19 +18,20 @@ the machine's BIOS.
> Of course, for this purpose the test system has to be known to suspend and
> resume without the driver being tested. Thus, if possible, you should first
> resolve all suspend/resume-related problems in the test system before you start
> -testing the new driver. Please see Documentation/power/basic-pm-debugging.txt
> +testing the new driver. Please see Documentation/power/basic-pm-debugging.rst
> for more information about the debugging of suspend/resume functionality.
>
> 2. Testing the driver
> +=====================
>
> Once you have resolved the suspend/resume-related problems with your test system
> without the new driver, you are ready to test it:
>
> a) Build the driver as a module, load it and try the test modes of hibernation
> - (see: Documentation/power/basic-pm-debugging.txt, 1).
> + (see: Documentation/power/basic-pm-debugging.rst, 1).
>
> b) Load the driver and attempt to hibernate in the "reboot", "shutdown" and
> - "platform" modes (see: Documentation/power/basic-pm-debugging.txt, 1).
> + "platform" modes (see: Documentation/power/basic-pm-debugging.rst, 1).
>
> c) Compile the driver directly into the kernel and try the test modes of
> hibernation.
> @@ -34,12 +39,12 @@ c) Compile the driver directly into the kernel and try the test modes of
> d) Attempt to hibernate with the driver compiled directly into the kernel
> in the "reboot", "shutdown" and "platform" modes.
>
> -e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.txt,
> +e) Try the test modes of suspend (see: Documentation/power/basic-pm-debugging.rst,
> 2). [As far as the STR tests are concerned, it should not matter whether or
> not the driver is built as a module.]
>
> f) Attempt to suspend to RAM using the s2ram tool with the driver loaded
> - (see: Documentation/power/basic-pm-debugging.txt, 2).
> + (see: Documentation/power/basic-pm-debugging.rst, 2).
>
> Each of the above tests should be repeated several times and the STD tests
> should be mixed with the STR tests. If any of them fails, the driver cannot be
> diff --git a/Documentation/power/energy-model.txt b/Documentation/power/energy-model.rst
> similarity index 74%
> rename from Documentation/power/energy-model.txt
> rename to Documentation/power/energy-model.rst
> index a2b0ae4c76bd..90a345d57ae9 100644
> --- a/Documentation/power/energy-model.txt
> +++ b/Documentation/power/energy-model.rst
> @@ -1,6 +1,6 @@
> - ====================
> - Energy Model of CPUs
> - ====================
> +====================
> +Energy Model of CPUs
> +====================
>
> 1. Overview
> -----------
> @@ -20,7 +20,7 @@ kernel, hence enabling to avoid redundant work.
>
> The figure below depicts an example of drivers (Arm-specific here, but the
> approach is applicable to any architecture) providing power costs to the EM
> -framework, and interested clients reading the data from it.
> +framework, and interested clients reading the data from it::
>
> +---------------+ +-----------------+ +---------------+
> | Thermal (IPA) | | Scheduler (EAS) | | Other |
> @@ -58,15 +58,17 @@ micro-architectures.
> 2. Core APIs
> ------------
>
> - 2.1 Config options
> +2.1 Config options
> +^^^^^^^^^^^^^^^^^^
>
> CONFIG_ENERGY_MODEL must be enabled to use the EM framework.
>
>
> - 2.2 Registration of performance domains
> +2.2 Registration of performance domains
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Drivers are expected to register performance domains into the EM framework by
> -calling the following API:
> +calling the following API::
>
> int em_register_perf_domain(cpumask_t *span, unsigned int nr_states,
> struct em_data_callback *cb);
> @@ -80,7 +82,8 @@ callback, and kernel/power/energy_model.c for further documentation on this
> API.
>
>
> - 2.3 Accessing performance domains
> +2.3 Accessing performance domains
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Subsystems interested in the energy model of a CPU can retrieve it using the
> em_cpu_get() API. The energy model tables are allocated once upon creation of
> @@ -99,46 +102,46 @@ More details about the above APIs can be found in include/linux/energy_model.h.
> This section provides a simple example of a CPUFreq driver registering a
> performance domain in the Energy Model framework using the (fake) 'foo'
> protocol. The driver implements an est_power() function to be provided to the
> -EM framework.
> +EM framework::
>
> - -> drivers/cpufreq/foo_cpufreq.c
> + -> drivers/cpufreq/foo_cpufreq.c
>
> -01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
> -02 {
> -03 long freq, power;
> -04
> -05 /* Use the 'foo' protocol to ceil the frequency */
> -06 freq = foo_get_freq_ceil(cpu, *KHz);
> -07 if (freq < 0);
> -08 return freq;
> -09
> -10 /* Estimate the power cost for the CPU at the relevant freq. */
> -11 power = foo_estimate_power(cpu, freq);
> -12 if (power < 0);
> -13 return power;
> -14
> -15 /* Return the values to the EM framework */
> -16 *mW = power;
> -17 *KHz = freq;
> -18
> -19 return 0;
> -20 }
> -21
> -22 static int foo_cpufreq_init(struct cpufreq_policy *policy)
> -23 {
> -24 struct em_data_callback em_cb = EM_DATA_CB(est_power);
> -25 int nr_opp, ret;
> -26
> -27 /* Do the actual CPUFreq init work ... */
> -28 ret = do_foo_cpufreq_init(policy);
> -29 if (ret)
> -30 return ret;
> -31
> -32 /* Find the number of OPPs for this policy */
> -33 nr_opp = foo_get_nr_opp(policy);
> -34
> -35 /* And register the new performance domain */
> -36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
> -37
> -38 return 0;
> -39 }
> + 01 static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
> + 02 {
> + 03 long freq, power;
> + 04
> + 05 /* Use the 'foo' protocol to ceil the frequency */
> + 06 freq = foo_get_freq_ceil(cpu, *KHz);
> + 07 if (freq < 0);
> + 08 return freq;
> + 09
> + 10 /* Estimate the power cost for the CPU at the relevant freq. */
> + 11 power = foo_estimate_power(cpu, freq);
> + 12 if (power < 0);
> + 13 return power;
> + 14
> + 15 /* Return the values to the EM framework */
> + 16 *mW = power;
> + 17 *KHz = freq;
> + 18
> + 19 return 0;
> + 20 }
> + 21
> + 22 static int foo_cpufreq_init(struct cpufreq_policy *policy)
> + 23 {
> + 24 struct em_data_callback em_cb = EM_DATA_CB(est_power);
> + 25 int nr_opp, ret;
> + 26
> + 27 /* Do the actual CPUFreq init work ... */
> + 28 ret = do_foo_cpufreq_init(policy);
> + 29 if (ret)
> + 30 return ret;
> + 31
> + 32 /* Find the number of OPPs for this policy */
> + 33 nr_opp = foo_get_nr_opp(policy);
> + 34
> + 35 /* And register the new performance domain */
> + 36 em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
> + 37
> + 38 return 0;
> + 39 }
> diff --git a/Documentation/power/freezing-of-tasks.txt b/Documentation/power/freezing-of-tasks.rst
> similarity index 75%
> rename from Documentation/power/freezing-of-tasks.txt
> rename to Documentation/power/freezing-of-tasks.rst
> index cd283190855a..ef110fe55e82 100644
> --- a/Documentation/power/freezing-of-tasks.txt
> +++ b/Documentation/power/freezing-of-tasks.rst
> @@ -1,13 +1,18 @@
> +=================
> Freezing of tasks
> - (C) 2007 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>, GPL
> +=================
> +
> +(C) 2007 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>, GPL
>
> I. What is the freezing of tasks?
> +=================================
>
> The freezing of tasks is a mechanism by which user space processes and some
> kernel threads are controlled during hibernation or system-wide suspend (on some
> architectures).
>
> II. How does it work?
> +=====================
>
> There are three per-task flags used for that, PF_NOFREEZE, PF_FROZEN
> and PF_FREEZER_SKIP (the last one is auxiliary). The tasks that have
> @@ -41,7 +46,7 @@ explicitly in suitable places or use the wait_event_freezable() or
> wait_event_freezable_timeout() macros (defined in include/linux/freezer.h)
> that combine interruptible sleep with checking if the task is to be frozen and
> calling try_to_freeze(). The main loop of a freezable kernel thread may look
> -like the following one:
> +like the following one::
>
> set_freezable();
> do {
> @@ -65,7 +70,7 @@ order to clear the PF_FROZEN flag for each frozen task. Then, the tasks that
> have been frozen leave __refrigerator() and continue running.
>
>
> -Rationale behind the functions dealing with freezing and thawing of tasks:
> +Rationale behind the functions dealing with freezing and thawing of tasks
> -------------------------------------------------------------------------
>
> freeze_processes():
> @@ -86,6 +91,7 @@ thaw_processes():
>
>
> III. Which kernel threads are freezable?
> +========================================
>
> Kernel threads are not freezable by default. However, a kernel thread may clear
> PF_NOFREEZE for itself by calling set_freezable() (the resetting of PF_NOFREEZE
> @@ -93,37 +99,39 @@ directly is not allowed). From this point it is regarded as freezable
> and must call try_to_freeze() in a suitable place.
>
> IV. Why do we do that?
> +======================
>
> Generally speaking, there is a couple of reasons to use the freezing of tasks:
>
> 1. The principal reason is to prevent filesystems from being damaged after
> -hibernation. At the moment we have no simple means of checkpointing
> -filesystems, so if there are any modifications made to filesystem data and/or
> -metadata on disks, we cannot bring them back to the state from before the
> -modifications. At the same time each hibernation image contains some
> -filesystem-related information that must be consistent with the state of the
> -on-disk data and metadata after the system memory state has been restored from
> -the image (otherwise the filesystems will be damaged in a nasty way, usually
> -making them almost impossible to repair). We therefore freeze tasks that might
> -cause the on-disk filesystems' data and metadata to be modified after the
> -hibernation image has been created and before the system is finally powered off.
> -The majority of these are user space processes, but if any of the kernel threads
> -may cause something like this to happen, they have to be freezable.
> + hibernation. At the moment we have no simple means of checkpointing
> + filesystems, so if there are any modifications made to filesystem data and/or
> + metadata on disks, we cannot bring them back to the state from before the
> + modifications. At the same time each hibernation image contains some
> + filesystem-related information that must be consistent with the state of the
> + on-disk data and metadata after the system memory state has been restored
> + from the image (otherwise the filesystems will be damaged in a nasty way,
> + usually making them almost impossible to repair). We therefore freeze
> + tasks that might cause the on-disk filesystems' data and metadata to be
> + modified after the hibernation image has been created and before the
> + system is finally powered off. The majority of these are user space
> + processes, but if any of the kernel threads may cause something like this
> + to happen, they have to be freezable.
>
> 2. Next, to create the hibernation image we need to free a sufficient amount of
> -memory (approximately 50% of available RAM) and we need to do that before
> -devices are deactivated, because we generally need them for swapping out. Then,
> -after the memory for the image has been freed, we don't want tasks to allocate
> -additional memory and we prevent them from doing that by freezing them earlier.
> -[Of course, this also means that device drivers should not allocate substantial
> -amounts of memory from their .suspend() callbacks before hibernation, but this
> -is a separate issue.]
> + memory (approximately 50% of available RAM) and we need to do that before
> + devices are deactivated, because we generally need them for swapping out.
> + Then, after the memory for the image has been freed, we don't want tasks
> + to allocate additional memory and we prevent them from doing that by
> + freezing them earlier. [Of course, this also means that device drivers
> + should not allocate substantial amounts of memory from their .suspend()
> + callbacks before hibernation, but this is a separate issue.]
>
> 3. The third reason is to prevent user space processes and some kernel threads
> -from interfering with the suspending and resuming of devices. A user space
> -process running on a second CPU while we are suspending devices may, for
> -example, be troublesome and without the freezing of tasks we would need some
> -safeguards against race conditions that might occur in such a case.
> + from interfering with the suspending and resuming of devices. A user space
> + process running on a second CPU while we are suspending devices may, for
> + example, be troublesome and without the freezing of tasks we would need some
> + safeguards against race conditions that might occur in such a case.
>
> Although Linus Torvalds doesn't like the freezing of tasks, he said this in one
> of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608):
> @@ -132,7 +140,7 @@ of the discussions on LKML (http://lkml.org/lkml/2007/4/27/608):
>
> Linus: In many ways, 'at all'.
>
> -I _do_ realize the IO request queue issues, and that we cannot actually do
> +I **do** realize the IO request queue issues, and that we cannot actually do
> s2ram with some devices in the middle of a DMA. So we want to be able to
> avoid *that*, there's no question about that. And I suspect that stopping
> user threads and then waiting for a sync is practically one of the easier
> @@ -150,17 +158,18 @@ thawed after the driver's .resume() callback has run, so it won't be accessing
> the device while it's suspended.
>
> 4. Another reason for freezing tasks is to prevent user space processes from
> -realizing that hibernation (or suspend) operation takes place. Ideally, user
> -space processes should not notice that such a system-wide operation has occurred
> -and should continue running without any problems after the restore (or resume
> -from suspend). Unfortunately, in the most general case this is quite difficult
> -to achieve without the freezing of tasks. Consider, for example, a process
> -that depends on all CPUs being online while it's running. Since we need to
> -disable nonboot CPUs during the hibernation, if this process is not frozen, it
> -may notice that the number of CPUs has changed and may start to work incorrectly
> -because of that.
> + realizing that hibernation (or suspend) operation takes place. Ideally, user
> + space processes should not notice that such a system-wide operation has
> + occurred and should continue running without any problems after the restore
> + (or resume from suspend). Unfortunately, in the most general case this
> + is quite difficult to achieve without the freezing of tasks. Consider,
> + for example, a process that depends on all CPUs being online while it's
> + running. Since we need to disable nonboot CPUs during the hibernation,
> + if this process is not frozen, it may notice that the number of CPUs has
> + changed and may start to work incorrectly because of that.
>
> V. Are there any problems related to the freezing of tasks?
> +===========================================================
>
> Yes, there are.
>
> @@ -172,11 +181,12 @@ may be undesirable. That's why kernel threads are not freezable by default.
>
> Second, there are the following two problems related to the freezing of user
> space processes:
> +
> 1. Putting processes into an uninterruptible sleep distorts the load average.
> 2. Now that we have FUSE, plus the framework for doing device drivers in
> -userspace, it gets even more complicated because some userspace processes are
> -now doing the sorts of things that kernel threads do
> -(https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html).
> + userspace, it gets even more complicated because some userspace processes are
> + now doing the sorts of things that kernel threads do
> + (https://lists.linux-foundation.org/pipermail/linux-pm/2007-May/012309.html).
>
> The problem 1. seems to be fixable, although it hasn't been fixed so far. The
> other one is more serious, but it seems that we can work around it by using
> @@ -201,6 +211,7 @@ requested early enough using the suspend notifier API described in
> Documentation/driver-api/pm/notifiers.rst.
>
> VI. Are there any precautions to be taken to prevent freezing failures?
> +=======================================================================
>
> Yes, there are.
>
> @@ -226,6 +237,8 @@ So, to summarize, use [un]lock_system_sleep() instead of directly using
> mutex_[un]lock(&system_transition_mutex). That would prevent freezing failures.
>
> V. Miscellaneous
> +================
> +
> /sys/power/pm_freeze_timeout controls how long it will cost at most to freeze
> all user space processes or all freezable kernel threads, in unit of millisecond.
> The default value is 20000, with range of unsigned integer.
> diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
> new file mode 100644
> index 000000000000..20415f21e48a
> --- /dev/null
> +++ b/Documentation/power/index.rst
> @@ -0,0 +1,46 @@
> +:orphan:
> +
> +================
> +Power Management
> +================
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + apm-acpi
> + basic-pm-debugging
> + charger-manager
> + drivers-testing
> + energy-model
> + freezing-of-tasks
> + interface
> + opp
> + pci
> + pm_qos_interface
> + power_supply_class
> + runtime_pm
> + s2ram
> + suspend-and-cpuhotplug
> + suspend-and-interrupts
> + swsusp-and-swap-files
> + swsusp-dmcrypt
> + swsusp
> + video
> + tricks
> +
> + userland-swsusp
> +
> + powercap/powercap
> +
> + regulator/consumer
> + regulator/design
> + regulator/machine
> + regulator/overview
> + regulator/regulator
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> diff --git a/Documentation/power/interface.txt b/Documentation/power/interface.rst
> similarity index 84%
> rename from Documentation/power/interface.txt
> rename to Documentation/power/interface.rst
> index 27df7f98668a..8d270ed27228 100644
> --- a/Documentation/power/interface.txt
> +++ b/Documentation/power/interface.rst
> @@ -1,4 +1,6 @@
> +===========================================
> Power Management Interface for System Sleep
> +===========================================
>
> Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>
> @@ -11,10 +13,10 @@ mounted at /sys).
>
> Reading from it returns a list of supported sleep states, encoded as:
>
> -'freeze' (Suspend-to-Idle)
> -'standby' (Power-On Suspend)
> -'mem' (Suspend-to-RAM)
> -'disk' (Suspend-to-Disk)
> +- 'freeze' (Suspend-to-Idle)
> +- 'standby' (Power-On Suspend)
> +- 'mem' (Suspend-to-RAM)
> +- 'disk' (Suspend-to-Disk)
>
> Suspend-to-Idle is always supported. Suspend-to-Disk is always supported
> too as long the kernel has been configured to support hibernation at all
> @@ -32,18 +34,18 @@ Specifically, it tells the kernel what to do after creating a hibernation image.
>
> Reading from it returns a list of supported options encoded as:
>
> -'platform' (put the system into sleep using a platform-provided method)
> -'shutdown' (shut the system down)
> -'reboot' (reboot the system)
> -'suspend' (trigger a Suspend-to-RAM transition)
> -'test_resume' (resume-after-hibernation test mode)
> +- 'platform' (put the system into sleep using a platform-provided method)
> +- 'shutdown' (shut the system down)
> +- 'reboot' (reboot the system)
> +- 'suspend' (trigger a Suspend-to-RAM transition)
> +- 'test_resume' (resume-after-hibernation test mode)
>
> The currently selected option is printed in square brackets.
>
> The 'platform' option is only available if the platform provides a special
> mechanism to put the system to sleep after creating a hibernation image (ACPI
> does that, for example). The 'suspend' option is available if Suspend-to-RAM
> -is supported. Refer to Documentation/power/basic-pm-debugging.txt for the
> +is supported. Refer to Documentation/power/basic-pm-debugging.rst for the
> description of the 'test_resume' option.
>
> To select an option, write the string representing it to /sys/power/disk.
> @@ -71,7 +73,7 @@ If /sys/power/pm_trace contains '1', the fingerprint of each suspend/resume
> event point in turn will be stored in the RTC memory (overwriting the actual
> RTC information), so it will survive a system crash if one occurs right after
> storing it and it can be used later to identify the driver that caused the crash
> -to happen (see Documentation/power/s2ram.txt for more information).
> +to happen (see Documentation/power/s2ram.rst for more information).
>
> Initially it contains '0' which may be changed to '1' by writing a string
> representing a nonzero integer into it.
> diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.rst
> similarity index 78%
> rename from Documentation/power/opp.txt
> rename to Documentation/power/opp.rst
> index 0c007e250cd1..b3cf1def9dee 100644
> --- a/Documentation/power/opp.txt
> +++ b/Documentation/power/opp.rst
> @@ -1,20 +1,23 @@
> +==========================================
> Operating Performance Points (OPP) Library
> ==========================================
>
> (C) 2009-2010 Nishanth Menon <nm-l0cyMroinI0@public.gmane.org>, Texas Instruments Incorporated
>
> -Contents
> ---------
> -1. Introduction
> -2. Initial OPP List Registration
> -3. OPP Search Functions
> -4. OPP Availability Control Functions
> -5. OPP Data Retrieval Functions
> -6. Data Structures
> +.. Contents
> +
> + 1. Introduction
> + 2. Initial OPP List Registration
> + 3. OPP Search Functions
> + 4. OPP Availability Control Functions
> + 5. OPP Data Retrieval Functions
> + 6. Data Structures
>
> 1. Introduction
> ===============
> +
> 1.1 What is an Operating Performance Point (OPP)?
> +-------------------------------------------------
>
> Complex SoCs of today consists of a multiple sub-modules working in conjunction.
> In an operational system executing varied use cases, not all modules in the SoC
> @@ -28,16 +31,19 @@ the device will support per domain are called Operating Performance Points or
> OPPs.
>
> As an example:
> +
> Let us consider an MPU device which supports the following:
> {300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
> {1GHz at minimum voltage of 1.3V}
>
> We can represent these as three OPPs as the following {Hz, uV} tuples:
> -{300000000, 1000000}
> -{800000000, 1200000}
> -{1000000000, 1300000}
> +
> +- {300000000, 1000000}
> +- {800000000, 1200000}
> +- {1000000000, 1300000}
>
> 1.2 Operating Performance Points Library
> +----------------------------------------
>
> OPP library provides a set of helper functions to organize and query the OPP
> information. The library is located in drivers/base/power/opp.c and the header
> @@ -46,9 +52,10 @@ CONFIG_PM_OPP from power management menuconfig menu. OPP library depends on
> CONFIG_PM as certain SoCs such as Texas Instrument's OMAP framework allows to
> optionally boot at a certain OPP without needing cpufreq.
>
> -Typical usage of the OPP library is as follows:
> -(users) -> registers a set of default OPPs -> (library)
> -SoC framework -> modifies on required cases certain OPPs -> OPP layer
> +Typical usage of the OPP library is as follows::
> +
> + (users) -> registers a set of default OPPs -> (library)
> + SoC framework -> modifies on required cases certain OPPs -> OPP layer
> -> queries to search/retrieve information ->
>
> OPP layer expects each domain to be represented by a unique device pointer. SoC
> @@ -57,8 +64,9 @@ list is expected to be an optimally small number typically around 5 per device.
> This initial list contains a set of OPPs that the framework expects to be safely
> enabled by default in the system.
>
> -Note on OPP Availability:
> -------------------------
> +Note on OPP Availability
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> As the system proceeds to operate, SoC framework may choose to make certain
> OPPs available or not available on each device based on various external
> factors. Example usage: Thermal management or other exceptional situations where
> @@ -88,7 +96,8 @@ registering the OPPs is maintained by OPP library throughout the device
> operation. The SoC framework can subsequently control the availability of the
> OPPs dynamically using the dev_pm_opp_enable / disable functions.
>
> -dev_pm_opp_add - Add a new OPP for a specific domain represented by the device pointer.
> +dev_pm_opp_add
> + Add a new OPP for a specific domain represented by the device pointer.
> The OPP is defined using the frequency and voltage. Once added, the OPP
> is assumed to be available and control of it's availability can be done
> with the dev_pm_opp_enable/disable functions. OPP library internally stores
> @@ -96,9 +105,11 @@ dev_pm_opp_add - Add a new OPP for a specific domain represented by the device p
> used by SoC framework to define a optimal list as per the demands of
> SoC usage environment.
>
> - WARNING: Do not use this function in interrupt context.
> + WARNING:
> + Do not use this function in interrupt context.
> +
> + Example::
>
> - Example:
> soc_pm_init()
> {
> /* Do things */
> @@ -125,12 +136,15 @@ Callers of these functions shall call dev_pm_opp_put() after they have used the
> OPP. Otherwise the memory for the OPP will never get freed and result in
> memleak.
>
> -dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
> +dev_pm_opp_find_freq_exact
> + Search for an OPP based on an *exact* frequency and
> availability. This function is especially useful to enable an OPP which
> is not available by default.
> Example: In a case when SoC framework detects a situation where a
> higher frequency could be made available, it can use this function to
> - find the OPP prior to call the dev_pm_opp_enable to actually make it available.
> + find the OPP prior to call the dev_pm_opp_enable to actually make
> + it available::
> +
> opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
> dev_pm_opp_put(opp);
> /* dont operate on the pointer.. just do a sanity check.. */
> @@ -141,27 +155,34 @@ dev_pm_opp_find_freq_exact - Search for an OPP based on an *exact* frequency and
> dev_pm_opp_enable(dev,1000000000);
> }
>
> - NOTE: This is the only search function that operates on OPPs which are
> - not available.
> + NOTE:
> + This is the only search function that operates on OPPs which are
> + not available.
>
> -dev_pm_opp_find_freq_floor - Search for an available OPP which is *at most* the
> +dev_pm_opp_find_freq_floor
> + Search for an available OPP which is *at most* the
> provided frequency. This function is useful while searching for a lesser
> match OR operating on OPP information in the order of decreasing
> frequency.
> - Example: To find the highest opp for a device:
> + Example: To find the highest opp for a device::
> +
> freq = ULONG_MAX;
> opp = dev_pm_opp_find_freq_floor(dev, &freq);
> dev_pm_opp_put(opp);
>
> -dev_pm_opp_find_freq_ceil - Search for an available OPP which is *at least* the
> +dev_pm_opp_find_freq_ceil
> + Search for an available OPP which is *at least* the
> provided frequency. This function is useful while searching for a
> higher match OR operating on OPP information in the order of increasing
> frequency.
> - Example 1: To find the lowest opp for a device:
> + Example 1: To find the lowest opp for a device::
> +
> freq = 0;
> opp = dev_pm_opp_find_freq_ceil(dev, &freq);
> dev_pm_opp_put(opp);
> - Example 2: A simplified implementation of a SoC cpufreq_driver->target:
> +
> + Example 2: A simplified implementation of a SoC cpufreq_driver->target::
> +
> soc_cpufreq_target(..)
> {
> /* Do stuff like policy checks etc. */
> @@ -184,12 +205,15 @@ fine grained dynamic control of which sets of OPPs are operationally available.
> These functions are intended to *temporarily* remove an OPP in conditions such
> as thermal considerations (e.g. don't use OPPx until the temperature drops).
>
> -WARNING: Do not use these functions in interrupt context.
> +WARNING:
> + Do not use these functions in interrupt context.
>
> -dev_pm_opp_enable - Make a OPP available for operation.
> +dev_pm_opp_enable
> + Make a OPP available for operation.
> Example: Lets say that 1GHz OPP is to be made available only if the
> SoC temperature is lower than a certain threshold. The SoC framework
> - implementation might choose to do something as follows:
> + implementation might choose to do something as follows::
> +
> if (cur_temp < temp_low_thresh) {
> /* Enable 1GHz if it was disabled */
> opp = dev_pm_opp_find_freq_exact(dev, 1000000000, false);
> @@ -201,10 +225,12 @@ dev_pm_opp_enable - Make a OPP available for operation.
> goto try_something_else;
> }
>
> -dev_pm_opp_disable - Make an OPP to be not available for operation
> +dev_pm_opp_disable
> + Make an OPP to be not available for operation
> Example: Lets say that 1GHz OPP is to be disabled if the temperature
> exceeds a threshold value. The SoC framework implementation might
> - choose to do something as follows:
> + choose to do something as follows::
> +
> if (cur_temp > temp_high_thresh) {
> /* Disable 1GHz if it was enabled */
> opp = dev_pm_opp_find_freq_exact(dev, 1000000000, true);
> @@ -223,11 +249,13 @@ information from the OPP structure is necessary. Once an OPP pointer is
> retrieved using the search functions, the following functions can be used by SoC
> framework to retrieve the information represented inside the OPP layer.
>
> -dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
> +dev_pm_opp_get_voltage
> + Retrieve the voltage represented by the opp pointer.
> Example: At a cpufreq transition to a different frequency, SoC
> framework requires to set the voltage represented by the OPP using
> the regulator framework to the Power Management chip providing the
> - voltage.
> + voltage::
> +
> soc_switch_to_freq_voltage(freq)
> {
> /* do things */
> @@ -239,10 +267,12 @@ dev_pm_opp_get_voltage - Retrieve the voltage represented by the opp pointer.
> /* do other things */
> }
>
> -dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
> +dev_pm_opp_get_freq
> + Retrieve the freq represented by the opp pointer.
> Example: Lets say the SoC framework uses a couple of helper functions
> we could pass opp pointers instead of doing additional parameters to
> - handle quiet a bit of data parameters.
> + handle quiet a bit of data parameters::
> +
> soc_cpufreq_target(..)
> {
> /* do things.. */
> @@ -264,9 +294,11 @@ dev_pm_opp_get_freq - Retrieve the freq represented by the opp pointer.
> /* do things.. */
> }
>
> -dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
> +dev_pm_opp_get_opp_count
> + Retrieve the number of available opps for a device
> Example: Lets say a co-processor in the SoC needs to know the available
> - frequencies in a table, the main processor can notify as following:
> + frequencies in a table, the main processor can notify as following::
> +
> soc_notify_coproc_available_frequencies()
> {
> /* Do things */
> @@ -289,54 +321,59 @@ dev_pm_opp_get_opp_count - Retrieve the number of available opps for a device
> ==================
> Typically an SoC contains multiple voltage domains which are variable. Each
> domain is represented by a device pointer. The relationship to OPP can be
> -represented as follows:
> -SoC
> - |- device 1
> - | |- opp 1 (availability, freq, voltage)
> - | |- opp 2 ..
> - ... ...
> - | `- opp n ..
> - |- device 2
> - ...
> - `- device m
> +represented as follows::
> +
> + SoC
> + |- device 1
> + | |- opp 1 (availability, freq, voltage)
> + | |- opp 2 ..
> + ... ...
> + | `- opp n ..
> + |- device 2
> + ...
> + `- device m
>
> OPP library maintains a internal list that the SoC framework populates and
> accessed by various functions as described above. However, the structures
> representing the actual OPPs and domains are internal to the OPP library itself
> to allow for suitable abstraction reusable across systems.
>
> -struct dev_pm_opp - The internal data structure of OPP library which is used to
> +struct dev_pm_opp
> + The internal data structure of OPP library which is used to
> represent an OPP. In addition to the freq, voltage, availability
> information, it also contains internal book keeping information required
> for the OPP library to operate on. Pointer to this structure is
> provided back to the users such as SoC framework to be used as a
> identifier for OPP in the interactions with OPP layer.
>
> - WARNING: The struct dev_pm_opp pointer should not be parsed or modified by the
> - users. The defaults of for an instance is populated by dev_pm_opp_add, but the
> - availability of the OPP can be modified by dev_pm_opp_enable/disable functions.
> + WARNING:
> + The struct dev_pm_opp pointer should not be parsed or modified by the
> + users. The defaults of for an instance is populated by
> + dev_pm_opp_add, but the availability of the OPP can be modified
> + by dev_pm_opp_enable/disable functions.
>
> -struct device - This is used to identify a domain to the OPP layer. The
> +struct device
> + This is used to identify a domain to the OPP layer. The
> nature of the device and it's implementation is left to the user of
> OPP library such as the SoC framework.
>
> Overall, in a simplistic view, the data structure operations is represented as
> -following:
> +following::
>
> -Initialization / modification:
> - +-----+ /- dev_pm_opp_enable
> -dev_pm_opp_add --> | opp | <-------
> - | +-----+ \- dev_pm_opp_disable
> - \-------> domain_info(device)
> + Initialization / modification:
> + +-----+ /- dev_pm_opp_enable
> + dev_pm_opp_add --> | opp | <-------
> + | +-----+ \- dev_pm_opp_disable
> + \-------> domain_info(device)
>
> -Search functions:
> - /-- dev_pm_opp_find_freq_ceil ---\ +-----+
> -domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
> - \-- dev_pm_opp_find_freq_floor ---/ +-----+
> + Search functions:
> + /-- dev_pm_opp_find_freq_ceil ---\ +-----+
> + domain_info<---- dev_pm_opp_find_freq_exact -----> | opp |
> + \-- dev_pm_opp_find_freq_floor ---/ +-----+
>
> -Retrieval functions:
> -+-----+ /- dev_pm_opp_get_voltage
> -| opp | <---
> -+-----+ \- dev_pm_opp_get_freq
> + Retrieval functions:
> + +-----+ /- dev_pm_opp_get_voltage
> + | opp | <---
> + +-----+ \- dev_pm_opp_get_freq
>
> -domain_info <- dev_pm_opp_get_opp_count
> + domain_info <- dev_pm_opp_get_opp_count
> diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.rst
> similarity index 97%
> rename from Documentation/power/pci.txt
> rename to Documentation/power/pci.rst
> index 8eaf9ee24d43..0e2ef7429304 100644
> --- a/Documentation/power/pci.txt
> +++ b/Documentation/power/pci.rst
> @@ -1,4 +1,6 @@
> +====================
> PCI Power Management
> +====================
>
> Copyright (c) 2010 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>, Novell Inc.
>
> @@ -9,14 +11,14 @@ management. Based on previous work by Patrick Mochel <mochel-Lhe3bsMrZseB+jHODAdFcQ@public.gmane.org>
> This document only covers the aspects of power management specific to PCI
> devices. For general description of the kernel's interfaces related to device
> power management refer to Documentation/driver-api/pm/devices.rst and
> -Documentation/power/runtime_pm.txt.
> +Documentation/power/runtime_pm.rst.
>
> ----------------------------------------------------------------------------
> +.. contents:
>
> -1. Hardware and Platform Support for PCI Power Management
> -2. PCI Subsystem and Device Power Management
> -3. PCI Device Drivers and Power Management
> -4. Resources
> + 1. Hardware and Platform Support for PCI Power Management
> + 2. PCI Subsystem and Device Power Management
> + 3. PCI Device Drivers and Power Management
> + 4. Resources
>
>
> 1. Hardware and Platform Support for PCI Power Management
> @@ -24,6 +26,7 @@ Documentation/power/runtime_pm.txt.
>
> 1.1. Native and Platform-Based Power Management
> -----------------------------------------------
> +
> In general, power management is a feature allowing one to save energy by putting
> devices into states in which they draw less power (low-power states) at the
> price of reduced functionality or performance.
> @@ -67,6 +70,7 @@ mechanisms have to be used simultaneously to obtain the desired result.
>
> 1.2. Native PCI Power Management
> --------------------------------
> +
> The PCI Bus Power Management Interface Specification (PCI PM Spec) was
> introduced between the PCI 2.1 and PCI 2.2 Specifications. It defined a
> standard interface for performing various operations related to power
> @@ -134,6 +138,7 @@ sufficiently active to generate a wakeup signal.
>
> 1.3. ACPI Device Power Management
> ---------------------------------
> +
> The platform firmware support for the power management of PCI devices is
> system-specific. However, if the system in question is compliant with the
> Advanced Configuration and Power Interface (ACPI) Specification, like the
> @@ -194,6 +199,7 @@ enabled for the device to be able to generate wakeup signals.
>
> 1.4. Wakeup Signaling
> ---------------------
> +
> Wakeup signals generated by PCI devices, either as native PCI PMEs, or as
> a result of the execution of the _DSW (or _PSW) ACPI control method before
> putting the device into a low-power state, have to be caught and handled as
> @@ -265,14 +271,15 @@ the native PCI Express PME signaling cannot be used by the kernel in that case.
>
> 2.1. Device Power Management Callbacks
> --------------------------------------
> +
> The PCI Subsystem participates in the power management of PCI devices in a
> number of ways. First of all, it provides an intermediate code layer between
> the device power management core (PM core) and PCI device drivers.
> Specifically, the pm field of the PCI subsystem's struct bus_type object,
> pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing
> -pointers to several device power management callbacks:
> +pointers to several device power management callbacks::
>
> -const struct dev_pm_ops pci_dev_pm_ops = {
> + const struct dev_pm_ops pci_dev_pm_ops = {
> .prepare = pci_pm_prepare,
> .complete = pci_pm_complete,
> .suspend = pci_pm_suspend,
> @@ -290,7 +297,7 @@ const struct dev_pm_ops pci_dev_pm_ops = {
> .runtime_suspend = pci_pm_runtime_suspend,
> .runtime_resume = pci_pm_runtime_resume,
> .runtime_idle = pci_pm_runtime_idle,
> -};
> + };
>
> These callbacks are executed by the PM core in various situations related to
> device power management and they, in turn, execute power management callbacks
> @@ -299,9 +306,9 @@ involving some standard configuration registers of PCI devices that device
> drivers need not know or care about.
>
> The structure representing a PCI device, struct pci_dev, contains several fields
> -that these callbacks operate on:
> +that these callbacks operate on::
>
> -struct pci_dev {
> + struct pci_dev {
> ...
> pci_power_t current_state; /* Current operating state. */
> int pm_cap; /* PM capability offset in the
> @@ -315,13 +322,14 @@ struct pci_dev {
> unsigned int wakeup_prepared:1; /* Device prepared for wake up */
> unsigned int d3_delay; /* D3->D0 transition time in ms */
> ...
> -};
> + };
>
> They also indirectly use some fields of the struct device that is embedded in
> struct pci_dev.
>
> 2.2. Device Initialization
> --------------------------
> +
> The PCI subsystem's first task related to device power management is to
> prepare the device for power management and initialize the fields of struct
> pci_dev used for this purpose. This happens in two functions defined in
> @@ -348,10 +356,11 @@ during system-wide transitions to a sleep state and back to the working state.
>
> 2.3. Runtime Device Power Management
> ------------------------------------
> +
> The PCI subsystem plays a vital role in the runtime power management of PCI
> devices. For this purpose it uses the general runtime power management
> -(runtime PM) framework described in Documentation/power/runtime_pm.txt.
> -Namely, it provides subsystem-level callbacks:
> +(runtime PM) framework described in Documentation/power/runtime_pm.rst.
> +Namely, it provides subsystem-level callbacks::
>
> pci_pm_runtime_suspend()
> pci_pm_runtime_resume()
> @@ -425,13 +434,14 @@ to the given subsystem before the next phase begins. These phases always run
> after tasks have been frozen.
>
> 2.4.1. System Suspend
> +^^^^^^^^^^^^^^^^^^^^^
>
> When the system is going into a sleep state in which the contents of memory will
> be preserved, such as one of the ACPI sleep states S1-S3, the phases are:
>
> prepare, suspend, suspend_noirq.
>
> -The following PCI bus type's callbacks, respectively, are used in these phases:
> +The following PCI bus type's callbacks, respectively, are used in these phases::
>
> pci_pm_prepare()
> pci_pm_suspend()
> @@ -492,6 +502,7 @@ this purpose). PCI device drivers are not encouraged to do that, but in some
> rare cases doing that in the driver may be the optimum approach.
>
> 2.4.2. System Resume
> +^^^^^^^^^^^^^^^^^^^^
>
> When the system is undergoing a transition from a sleep state in which the
> contents of memory have been preserved, such as one of the ACPI sleep states
> @@ -500,7 +511,7 @@ S1-S3, into the working state (ACPI S0), the phases are:
> resume_noirq, resume, complete.
>
> The following PCI bus type's callbacks, respectively, are executed in these
> -phases:
> +phases::
>
> pci_pm_resume_noirq()
> pci_pm_resume()
> @@ -539,6 +550,7 @@ The pci_pm_complete() routine only executes the device driver's pm->complete()
> callback, if defined.
>
> 2.4.3. System Hibernation
> +^^^^^^^^^^^^^^^^^^^^^^^^^
>
> System hibernation is more complicated than system suspend, because it requires
> a system image to be created and written into a persistent storage medium. The
> @@ -551,7 +563,7 @@ to be free) in the following three phases:
>
> prepare, freeze, freeze_noirq
>
> -that correspond to the PCI bus type's callbacks:
> +that correspond to the PCI bus type's callbacks::
>
> pci_pm_prepare()
> pci_pm_freeze()
> @@ -580,7 +592,7 @@ back to the fully functional state and this is done in the following phases:
>
> thaw_noirq, thaw, complete
>
> -using the following PCI bus type's callbacks:
> +using the following PCI bus type's callbacks::
>
> pci_pm_thaw_noirq()
> pci_pm_thaw()
> @@ -608,7 +620,7 @@ three phases:
>
> where the prepare phase is exactly the same as for system suspend. The other
> two phases are analogous to the suspend and suspend_noirq phases, respectively.
> -The PCI subsystem-level callbacks they correspond to
> +The PCI subsystem-level callbacks they correspond to::
>
> pci_pm_poweroff()
> pci_pm_poweroff_noirq()
> @@ -618,6 +630,7 @@ although they don't attempt to save the device's standard configuration
> registers.
>
> 2.4.4. System Restore
> +^^^^^^^^^^^^^^^^^^^^^
>
> System restore requires a hibernation image to be loaded into memory and the
> pre-hibernation memory contents to be restored before the pre-hibernation system
> @@ -653,7 +666,7 @@ phases:
>
> The first two of these are analogous to the resume_noirq and resume phases
> described above, respectively, and correspond to the following PCI subsystem
> -callbacks:
> +callbacks::
>
> pci_pm_restore_noirq()
> pci_pm_restore()
> @@ -671,6 +684,7 @@ resume.
>
> 3.1. Power Management Callbacks
> -------------------------------
> +
> PCI device drivers participate in power management by providing callbacks to be
> executed by the PCI subsystem's power management routines described above and by
> controlling the runtime power management of their devices.
> @@ -698,6 +712,7 @@ defined, though, they are expected to behave as described in the following
> subsections.
>
> 3.1.1. prepare()
> +^^^^^^^^^^^^^^^^
>
> The prepare() callback is executed during system suspend, during hibernation
> (when a hibernation image is about to be created), during power-off after
> @@ -716,6 +731,7 @@ preallocated earlier, for example in a suspend/hibernate notifier as described
> in Documentation/driver-api/pm/notifiers.rst).
>
> 3.1.2. suspend()
> +^^^^^^^^^^^^^^^^
>
> The suspend() callback is only executed during system suspend, after prepare()
> callbacks have been executed for all devices in the system.
> @@ -742,6 +758,7 @@ operations relying on the driver's ability to handle interrupts should be
> carried out in this callback.
>
> 3.1.3. suspend_noirq()
> +^^^^^^^^^^^^^^^^^^^^^^
>
> The suspend_noirq() callback is only executed during system suspend, after
> suspend() callbacks have been executed for all devices in the system and
> @@ -753,6 +770,7 @@ suspend_noirq() can carry out operations that would cause race conditions to
> arise if they were performed in suspend().
>
> 3.1.4. freeze()
> +^^^^^^^^^^^^^^^
>
> The freeze() callback is hibernation-specific and is executed in two situations,
> during hibernation, after prepare() callbacks have been executed for all devices
> @@ -770,6 +788,7 @@ or put it into a low-power state. Still, either it or freeze_noirq() should
> save the device's standard configuration registers using pci_save_state().
>
> 3.1.5. freeze_noirq()
> +^^^^^^^^^^^^^^^^^^^^^
>
> The freeze_noirq() callback is hibernation-specific. It is executed during
> hibernation, after prepare() and freeze() callbacks have been executed for all
> @@ -786,6 +805,7 @@ The difference between freeze_noirq() and freeze() is analogous to the
> difference between suspend_noirq() and suspend().
>
> 3.1.6. poweroff()
> +^^^^^^^^^^^^^^^^^
>
> The poweroff() callback is hibernation-specific. It is executed when the system
> is about to be powered off after saving a hibernation image to a persistent
> @@ -802,6 +822,7 @@ into a low-power state, respectively, but it need not save the device's standard
> configuration registers.
>
> 3.1.7. poweroff_noirq()
> +^^^^^^^^^^^^^^^^^^^^^^^
>
> The poweroff_noirq() callback is hibernation-specific. It is executed after
> poweroff() callbacks have been executed for all devices in the system.
> @@ -814,6 +835,7 @@ The difference between poweroff_noirq() and poweroff() is analogous to the
> difference between suspend_noirq() and suspend().
>
> 3.1.8. resume_noirq()
> +^^^^^^^^^^^^^^^^^^^^^
>
> The resume_noirq() callback is only executed during system resume, after the
> PM core has enabled the non-boot CPUs. The driver's interrupt handler will not
> @@ -827,6 +849,7 @@ it should only be used for performing operations that would lead to race
> conditions if carried out by resume().
>
> 3.1.9. resume()
> +^^^^^^^^^^^^^^^
>
> The resume() callback is only executed during system resume, after
> resume_noirq() callbacks have been executed for all devices in the system and
> @@ -837,6 +860,7 @@ device and bringing it back to the fully functional state. The device should be
> able to process I/O in a usual way after resume() has returned.
>
> 3.1.10. thaw_noirq()
> +^^^^^^^^^^^^^^^^^^^^
>
> The thaw_noirq() callback is hibernation-specific. It is executed after a
> system image has been created and the non-boot CPUs have been enabled by the PM
> @@ -851,6 +875,7 @@ freeze() and freeze_noirq(), so in general it does not need to modify the
> contents of the device's registers.
>
> 3.1.11. thaw()
> +^^^^^^^^^^^^^^
>
> The thaw() callback is hibernation-specific. It is executed after thaw_noirq()
> callbacks have been executed for all devices in the system and after device
> @@ -860,6 +885,7 @@ This callback is responsible for restoring the pre-freeze configuration of
> the device, so that it will work in a usual way after thaw() has returned.
>
> 3.1.12. restore_noirq()
> +^^^^^^^^^^^^^^^^^^^^^^^
>
> The restore_noirq() callback is hibernation-specific. It is executed in the
> restore_noirq phase of hibernation, when the boot kernel has passed control to
> @@ -875,6 +901,7 @@ For the vast majority of PCI device drivers there is no difference between
> resume_noirq() and restore_noirq().
>
> 3.1.13. restore()
> +^^^^^^^^^^^^^^^^^
>
> The restore() callback is hibernation-specific. It is executed after
> restore_noirq() callbacks have been executed for all devices in the system and
> @@ -888,14 +915,17 @@ For the vast majority of PCI device drivers there is no difference between
> resume() and restore().
>
> 3.1.14. complete()
> +^^^^^^^^^^^^^^^^^^
>
> The complete() callback is executed in the following situations:
> +
> - during system resume, after resume() callbacks have been executed for all
> devices,
> - during hibernation, before saving the system image, after thaw() callbacks
> have been executed for all devices,
> - during system restore, when the system is going back to its pre-hibernation
> state, after restore() callbacks have been executed for all devices.
> +
> It also may be executed if the loading of a hibernation image into memory fails
> (in that case it is run after thaw() callbacks have been executed for all
> devices that have drivers in the boot kernel).
> @@ -904,6 +934,7 @@ This callback is entirely optional, although it may be necessary if the
> prepare() callback performs operations that need to be reversed.
>
> 3.1.15. runtime_suspend()
> +^^^^^^^^^^^^^^^^^^^^^^^^^
>
> The runtime_suspend() callback is specific to device runtime power management
> (runtime PM). It is executed by the PM core's runtime PM framework when the
> @@ -915,6 +946,7 @@ put into a low-power state, but it must allow the PCI subsystem to perform all
> of the PCI-specific actions necessary for suspending the device.
>
> 3.1.16. runtime_resume()
> +^^^^^^^^^^^^^^^^^^^^^^^^
>
> The runtime_resume() callback is specific to device runtime PM. It is executed
> by the PM core's runtime PM framework when the device is about to be resumed
> @@ -927,6 +959,7 @@ The device is expected to be able to process I/O in the usual way after
> runtime_resume() has returned.
>
> 3.1.17. runtime_idle()
> +^^^^^^^^^^^^^^^^^^^^^^
>
> The runtime_idle() callback is specific to device runtime PM. It is executed
> by the PM core's runtime PM framework whenever it may be desirable to suspend
> @@ -939,6 +972,7 @@ PCI subsystem will call pm_runtime_suspend() for the device, which in turn will
> cause the driver's runtime_suspend() callback to be executed.
>
> 3.1.18. Pointing Multiple Callback Pointers to One Routine
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Although in principle each of the callbacks described in the previous
> subsections can be defined as a separate function, it often is convenient to
> @@ -962,6 +996,7 @@ dev_pm_ops to indicate that one suspend routine is to be pointed to by the
> be pointed to by the .resume(), .thaw(), and .restore() members.
>
> 3.1.19. Driver Flags for Power Management
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> The PM core allows device drivers to set flags that influence the handling of
> power management for the devices by the core itself and by middle layer code
> @@ -1007,6 +1042,7 @@ it.
>
> 3.2. Device Runtime Power Management
> ------------------------------------
> +
> In addition to providing device power management callbacks PCI device drivers
> are responsible for controlling the runtime power management (runtime PM) of
> their devices.
> @@ -1073,22 +1109,27 @@ device the PM core automatically queues a request to check if the device is
> idle), device drivers are generally responsible for queuing power management
> requests for their devices. For this purpose they should use the runtime PM
> helper functions provided by the PM core, discussed in
> -Documentation/power/runtime_pm.txt.
> +Documentation/power/runtime_pm.rst.
>
> Devices can also be suspended and resumed synchronously, without placing a
> request into pm_wq. In the majority of cases this also is done by their
> drivers that use helper functions provided by the PM core for this purpose.
>
> For more information on the runtime PM of devices refer to
> -Documentation/power/runtime_pm.txt.
> +Documentation/power/runtime_pm.rst.
>
>
> 4. Resources
> ============
>
> PCI Local Bus Specification, Rev. 3.0
> +
> PCI Bus Power Management Interface Specification, Rev. 1.2
> +
> Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
> +
> PCI Express Base Specification, Rev. 2.0
> +
> Documentation/driver-api/pm/devices.rst
> -Documentation/power/runtime_pm.txt
> +
> +Documentation/power/runtime_pm.rst
> diff --git a/Documentation/power/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.rst
> similarity index 62%
> rename from Documentation/power/pm_qos_interface.txt
> rename to Documentation/power/pm_qos_interface.rst
> index 19c5f7b1a7ba..945fc6d760c9 100644
> --- a/Documentation/power/pm_qos_interface.txt
> +++ b/Documentation/power/pm_qos_interface.rst
> @@ -1,4 +1,6 @@
> -PM Quality Of Service Interface.
> +===============================
> +PM Quality Of Service Interface
> +===============================
>
> This interface provides a kernel and user mode interface for registering
> performance expectations by drivers, subsystems and user space applications on
> @@ -11,6 +13,7 @@ memory_bandwidth.
> constraints and PM QoS flags.
>
> Each parameters have defined units:
> +
> * latency: usec
> * timeout: usec
> * throughput: kbs (kilo bit / sec)
> @@ -18,6 +21,7 @@ Each parameters have defined units:
>
>
> 1. PM QoS framework
> +===================
>
> The infrastructure exposes multiple misc device nodes one per implemented
> parameter. The set of parameters implement is defined by pm_qos_power_init()
> @@ -37,38 +41,39 @@ reading the aggregated value does not require any locking mechanism.
> From kernel mode the use of this interface is simple:
>
> void pm_qos_add_request(handle, param_class, target_value):
> -Will insert an element into the list for that identified PM QoS class with the
> -target value. Upon change to this list the new target is recomputed and any
> -registered notifiers are called only if the target value is now different.
> -Clients of pm_qos need to save the returned handle for future use in other
> -pm_qos API functions.
> + Will insert an element into the list for that identified PM QoS class with the
> + target value. Upon change to this list the new target is recomputed and any
> + registered notifiers are called only if the target value is now different.
> + Clients of pm_qos need to save the returned handle for future use in other
> + pm_qos API functions.
>
> void pm_qos_update_request(handle, new_target_value):
> -Will update the list element pointed to by the handle with the new target value
> -and recompute the new aggregated target, calling the notification tree if the
> -target is changed.
> + Will update the list element pointed to by the handle with the new target value
> + and recompute the new aggregated target, calling the notification tree if the
> + target is changed.
>
> void pm_qos_remove_request(handle):
> -Will remove the element. After removal it will update the aggregate target and
> -call the notification tree if the target was changed as a result of removing
> -the request.
> + Will remove the element. After removal it will update the aggregate target and
> + call the notification tree if the target was changed as a result of removing
> + the request.
>
> int pm_qos_request(param_class):
> -Returns the aggregated value for a given PM QoS class.
> + Returns the aggregated value for a given PM QoS class.
>
> int pm_qos_request_active(handle):
> -Returns if the request is still active, i.e. it has not been removed from a
> -PM QoS class constraints list.
> + Returns if the request is still active, i.e. it has not been removed from a
> + PM QoS class constraints list.
>
> int pm_qos_add_notifier(param_class, notifier):
> -Adds a notification callback function to the PM QoS class. The callback is
> -called when the aggregated value for the PM QoS class is changed.
> + Adds a notification callback function to the PM QoS class. The callback is
> + called when the aggregated value for the PM QoS class is changed.
>
> int pm_qos_remove_notifier(int param_class, notifier):
> -Removes the notification callback function for the PM QoS class.
> + Removes the notification callback function for the PM QoS class.
>
>
> From user mode:
> +
> Only processes can register a pm_qos request. To provide for automatic
> cleanup of a process, the interface requires the process to register its
> parameter requests in the following way:
> @@ -89,6 +94,7 @@ node.
>
>
> 2. PM QoS per-device latency and flags framework
> +================================================
>
> For each device, there are three lists of PM QoS requests. Two of them are
> maintained along with the aggregated targets of resume latency and active
> @@ -107,73 +113,80 @@ the aggregated value does not require any locking mechanism.
> From kernel mode the use of this interface is the following:
>
> int dev_pm_qos_add_request(device, handle, type, value):
> -Will insert an element into the list for that identified device with the
> -target value. Upon change to this list the new target is recomputed and any
> -registered notifiers are called only if the target value is now different.
> -Clients of dev_pm_qos need to save the handle for future use in other
> -dev_pm_qos API functions.
> + Will insert an element into the list for that identified device with the
> + target value. Upon change to this list the new target is recomputed and any
> + registered notifiers are called only if the target value is now different.
> + Clients of dev_pm_qos need to save the handle for future use in other
> + dev_pm_qos API functions.
>
> int dev_pm_qos_update_request(handle, new_value):
> -Will update the list element pointed to by the handle with the new target value
> -and recompute the new aggregated target, calling the notification trees if the
> -target is changed.
> + Will update the list element pointed to by the handle with the new target
> + value and recompute the new aggregated target, calling the notification
> + trees if the target is changed.
>
> int dev_pm_qos_remove_request(handle):
> -Will remove the element. After removal it will update the aggregate target and
> -call the notification trees if the target was changed as a result of removing
> -the request.
> + Will remove the element. After removal it will update the aggregate target
> + and call the notification trees if the target was changed as a result of
> + removing the request.
>
> s32 dev_pm_qos_read_value(device):
> -Returns the aggregated value for a given device's constraints list.
> + Returns the aggregated value for a given device's constraints list.
>
> enum pm_qos_flags_status dev_pm_qos_flags(device, mask)
> -Check PM QoS flags of the given device against the given mask of flags.
> -The meaning of the return values is as follows:
> - PM_QOS_FLAGS_ALL: All flags from the mask are set
> - PM_QOS_FLAGS_SOME: Some flags from the mask are set
> - PM_QOS_FLAGS_NONE: No flags from the mask are set
> - PM_QOS_FLAGS_UNDEFINED: The device's PM QoS structure has not been
> - initialized or the list of requests is empty.
> + Check PM QoS flags of the given device against the given mask of flags.
> + The meaning of the return values is as follows:
> +
> + PM_QOS_FLAGS_ALL:
> + All flags from the mask are set
> + PM_QOS_FLAGS_SOME:
> + Some flags from the mask are set
> + PM_QOS_FLAGS_NONE:
> + No flags from the mask are set
> + PM_QOS_FLAGS_UNDEFINED:
> + The device's PM QoS structure has not been initialized
> + or the list of requests is empty.
>
> int dev_pm_qos_add_ancestor_request(dev, handle, type, value)
> -Add a PM QoS request for the first direct ancestor of the given device whose
> -power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests)
> -or whose power.set_latency_tolerance callback pointer is not NULL (for
> -DEV_PM_QOS_LATENCY_TOLERANCE requests).
> + Add a PM QoS request for the first direct ancestor of the given device whose
> + power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests)
> + or whose power.set_latency_tolerance callback pointer is not NULL (for
> + DEV_PM_QOS_LATENCY_TOLERANCE requests).
>
> int dev_pm_qos_expose_latency_limit(device, value)
> -Add a request to the device's PM QoS list of resume latency constraints and
> -create a sysfs attribute pm_qos_resume_latency_us under the device's power
> -directory allowing user space to manipulate that request.
> + Add a request to the device's PM QoS list of resume latency constraints and
> + create a sysfs attribute pm_qos_resume_latency_us under the device's power
> + directory allowing user space to manipulate that request.
>
> void dev_pm_qos_hide_latency_limit(device)
> -Drop the request added by dev_pm_qos_expose_latency_limit() from the device's
> -PM QoS list of resume latency constraints and remove sysfs attribute
> -pm_qos_resume_latency_us from the device's power directory.
> + Drop the request added by dev_pm_qos_expose_latency_limit() from the device's
> + PM QoS list of resume latency constraints and remove sysfs attribute
> + pm_qos_resume_latency_us from the device's power directory.
>
> int dev_pm_qos_expose_flags(device, value)
> -Add a request to the device's PM QoS list of flags and create sysfs attribute
> -pm_qos_no_power_off under the device's power directory allowing user space to
> -change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.
> + Add a request to the device's PM QoS list of flags and create sysfs attribute
> + pm_qos_no_power_off under the device's power directory allowing user space to
> + change the value of the PM_QOS_FLAG_NO_POWER_OFF flag.
>
> void dev_pm_qos_hide_flags(device)
> -Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list
> -of flags and remove sysfs attribute pm_qos_no_power_off from the device's power
> -directory.
> + Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list
> + of flags and remove sysfs attribute pm_qos_no_power_off from the device's power
> + directory.
>
> Notification mechanisms:
> +
> The per-device PM QoS framework has a per-device notification tree.
>
> int dev_pm_qos_add_notifier(device, notifier):
> -Adds a notification callback function for the device.
> -The callback is called when the aggregated value of the device constraints list
> -is changed (for resume latency device PM QoS only).
> + Adds a notification callback function for the device.
> + The callback is called when the aggregated value of the device constraints list
> + is changed (for resume latency device PM QoS only).
>
> int dev_pm_qos_remove_notifier(device, notifier):
> -Removes the notification callback function for the device.
> + Removes the notification callback function for the device.
>
>
> Active state latency tolerance
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> This device PM QoS type is used to support systems in which hardware may switch
> to energy-saving operation modes on the fly. In those systems, if the operation
> diff --git a/Documentation/power/power_supply_class.rst b/Documentation/power/power_supply_class.rst
> new file mode 100644
> index 000000000000..3f2c3fe38a61
> --- /dev/null
> +++ b/Documentation/power/power_supply_class.rst
> @@ -0,0 +1,282 @@
> +========================
> +Linux power supply class
> +========================
> +
> +Synopsis
> +~~~~~~~~
> +Power supply class used to represent battery, UPS, AC or DC power supply
> +properties to user-space.
> +
> +It defines core set of attributes, which should be applicable to (almost)
> +every power supply out there. Attributes are available via sysfs and uevent
> +interfaces.
> +
> +Each attribute has well defined meaning, up to unit of measure used. While
> +the attributes provided are believed to be universally applicable to any
> +power supply, specific monitoring hardware may not be able to provide them
> +all, so any of them may be skipped.
> +
> +Power supply class is extensible, and allows to define drivers own attributes.
> +The core attribute set is subject to the standard Linux evolution (i.e.
> +if it will be found that some attribute is applicable to many power supply
> +types or their drivers, it can be added to the core set).
> +
> +It also integrates with LED framework, for the purpose of providing
> +typically expected feedback of battery charging/fully charged status and
> +AC/USB power supply online status. (Note that specific details of the
> +indication (including whether to use it at all) are fully controllable by
> +user and/or specific machine defaults, per design principles of LED
> +framework).
> +
> +
> +Attributes/properties
> +~~~~~~~~~~~~~~~~~~~~~
> +Power supply class has predefined set of attributes, this eliminates code
> +duplication across drivers. Power supply class insist on reusing its
> +predefined attributes *and* their units.
> +
> +So, userspace gets predictable set of attributes and their units for any
> +kind of power supply, and can process/present them to a user in consistent
> +manner. Results for different power supplies and machines are also directly
> +comparable.
> +
> +See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
> +for the example how to declare and handle attributes.
> +
> +
> +Units
> +~~~~~
> +Quoting include/linux/power_supply.h:
> +
> + All voltages, currents, charges, energies, time and temperatures in µV,
> + µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
> + stated. It's driver's job to convert its raw values to units in which
> + this class operates.
> +
> +
> +Attributes/properties detailed
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> ++--------------------------------------------------------------------------+
> +| **Charge/Energy/Capacity - how to not confuse** |
> ++--------------------------------------------------------------------------+
> +| **Because both "charge" (µAh) and "energy" (µWh) represents "capacity" |
> +| of battery, this class distinguish these terms. Don't mix them!** |
> +| |
> +| - `CHARGE_*` |
> +| attributes represents capacity in µAh only. |
> +| - `ENERGY_*` |
> +| attributes represents capacity in µWh only. |
> +| - `CAPACITY` |
> +| attribute represents capacity in *percents*, from 0 to 100. |
> ++--------------------------------------------------------------------------+
> +
> +Postfixes:
> +
> +_AVG
> + *hardware* averaged value, use it if your hardware is really able to
> + report averaged values.
> +_NOW
> + momentary/instantaneous values.
> +
> +STATUS
> + this attribute represents operating status (charging, full,
> + discharging (i.e. powering a load), etc.). This corresponds to
> + `BATTERY_STATUS_*` values, as defined in battery.h.
> +
> +CHARGE_TYPE
> + batteries can typically charge at different rates.
> + This defines trickle and fast charges. For batteries that
> + are already charged or discharging, 'n/a' can be displayed (or
> + 'unknown', if the status is not known).
> +
> +AUTHENTIC
> + indicates the power supply (battery or charger) connected
> + to the platform is authentic(1) or non authentic(0).
> +
> +HEALTH
> + represents health of the battery, values corresponds to
> + POWER_SUPPLY_HEALTH_*, defined in battery.h.
> +
> +VOLTAGE_OCV
> + open circuit voltage of the battery.
> +
> +VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN
> + design values for maximal and minimal power supply voltages.
> + Maximal/minimal means values of voltages when battery considered
> + "full"/"empty" at normal conditions. Yes, there is no direct relation
> + between voltage and battery capacity, but some dumb
> + batteries use voltage for very approximated calculation of capacity.
> + Battery driver also can use this attribute just to inform userspace
> + about maximal and minimal voltage thresholds of a given battery.
> +
> +VOLTAGE_MAX, VOLTAGE_MIN
> + same as _DESIGN voltage values except that these ones should be used
> + if hardware could only guess (measure and retain) the thresholds of a
> + given power supply.
> +
> +VOLTAGE_BOOT
> + Reports the voltage measured during boot
> +
> +CURRENT_BOOT
> + Reports the current measured during boot
> +
> +CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN
> + design charge values, when battery considered full/empty.
> +
> +ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN
> + same as above but for energy.
> +
> +CHARGE_FULL, CHARGE_EMPTY
> + These attributes means "last remembered value of charge when battery
> + became full/empty". It also could mean "value of charge when battery
> + considered full/empty at given conditions (temperature, age)".
> + I.e. these attributes represents real thresholds, not design values.
> +
> +ENERGY_FULL, ENERGY_EMPTY
> + same as above but for energy.
> +
> +CHARGE_COUNTER
> + the current charge counter (in µAh). This could easily
> + be negative; there is no empty or full value. It is only useful for
> + relative, time-based measurements.
> +
> +PRECHARGE_CURRENT
> + the maximum charge current during precharge phase of charge cycle
> + (typically 20% of battery capacity).
> +
> +CHARGE_TERM_CURRENT
> + Charge termination current. The charge cycle terminates when battery
> + voltage is above recharge threshold, and charge current is below
> + this setting (typically 10% of battery capacity).
> +
> +CONSTANT_CHARGE_CURRENT
> + constant charge current programmed by charger.
> +
> +
> +CONSTANT_CHARGE_CURRENT_MAX
> + maximum charge current supported by the power supply object.
> +
> +CONSTANT_CHARGE_VOLTAGE
> + constant charge voltage programmed by charger.
> +CONSTANT_CHARGE_VOLTAGE_MAX
> + maximum charge voltage supported by the power supply object.
> +
> +INPUT_CURRENT_LIMIT
> + input current limit programmed by charger. Indicates
> + the current drawn from a charging source.
> +
> +CHARGE_CONTROL_LIMIT
> + current charge control limit setting
> +CHARGE_CONTROL_LIMIT_MAX
> + maximum charge control limit setting
> +
> +CALIBRATE
> + battery or coulomb counter calibration status
> +
> +CAPACITY
> + capacity in percents.
> +CAPACITY_ALERT_MIN
> + minimum capacity alert value in percents.
> +CAPACITY_ALERT_MAX
> + maximum capacity alert value in percents.
> +CAPACITY_LEVEL
> + capacity level. This corresponds to POWER_SUPPLY_CAPACITY_LEVEL_*.
> +
> +TEMP
> + temperature of the power supply.
> +TEMP_ALERT_MIN
> + minimum battery temperature alert.
> +TEMP_ALERT_MAX
> + maximum battery temperature alert.
> +TEMP_AMBIENT
> + ambient temperature.
> +TEMP_AMBIENT_ALERT_MIN
> + minimum ambient temperature alert.
> +TEMP_AMBIENT_ALERT_MAX
> + maximum ambient temperature alert.
> +TEMP_MIN
> + minimum operatable temperature
> +TEMP_MAX
> + maximum operatable temperature
> +
> +TIME_TO_EMPTY
> + seconds left for battery to be considered empty
> + (i.e. while battery powers a load)
> +TIME_TO_FULL
> + seconds left for battery to be considered full
> + (i.e. while battery is charging)
> +
> +
> +Battery <-> external power supply interaction
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Often power supplies are acting as supplies and supplicants at the same
> +time. Batteries are good example. So, batteries usually care if they're
> +externally powered or not.
> +
> +For that case, power supply class implements notification mechanism for
> +batteries.
> +
> +External power supply (AC) lists supplicants (batteries) names in
> +"supplied_to" struct member, and each power_supply_changed() call
> +issued by external power supply will notify supplicants via
> +external_power_changed callback.
> +
> +
> +Devicetree battery characteristics
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Drivers should call power_supply_get_battery_info() to obtain battery
> +characteristics from a devicetree battery node, defined in
> +Documentation/devicetree/bindings/power/supply/battery.txt. This is
> +implemented in drivers/power/supply/bq27xxx_battery.c.
> +
> +Properties in struct power_supply_battery_info and their counterparts in the
> +battery node have names corresponding to elements in enum power_supply_property,
> +for naming consistency between sysfs attributes and battery node properties.
> +
> +
> +QA
> +~~
> +
> +Q:
> + Where is POWER_SUPPLY_PROP_XYZ attribute?
> +A:
> + If you cannot find attribute suitable for your driver needs, feel free
> + to add it and send patch along with your driver.
> +
> + The attributes available currently are the ones currently provided by the
> + drivers written.
> +
> + Good candidates to add in future: model/part#, cycle_time, manufacturer,
> + etc.
> +
> +
> +Q:
> + I have some very specific attribute (e.g. battery color), should I add
> + this attribute to standard ones?
> +A:
> + Most likely, no. Such attribute can be placed in the driver itself, if
> + it is useful. Of course, if the attribute in question applicable to
> + large set of batteries, provided by many drivers, and/or comes from
> + some general battery specification/standard, it may be a candidate to
> + be added to the core attribute set.
> +
> +
> +Q:
> + Suppose, my battery monitoring chip/firmware does not provides capacity
> + in percents, but provides charge_{now,full,empty}. Should I calculate
> + percentage capacity manually, inside the driver, and register CAPACITY
> + attribute? The same question about time_to_empty/time_to_full.
> +A:
> + Most likely, no. This class is designed to export properties which are
> + directly measurable by the specific hardware available.
> +
> + Inferring not available properties using some heuristics or mathematical
> + model is not subject of work for a battery driver. Such functionality
> + should be factored out, and in fact, apm_power, the driver to serve
> + legacy APM API on top of power supply class, uses a simple heuristic of
> + approximating remaining battery capacity based on its charge, current,
> + voltage and so on. But full-fledged battery model is likely not subject
> + for kernel at all, as it would require floating point calculation to deal
> + with things like differential equations and Kalman filters. This is
> + better be handled by batteryd/libbattery, yet to be written.
> diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt
> deleted file mode 100644
> index 300d37896e51..000000000000
> --- a/Documentation/power/power_supply_class.txt
> +++ /dev/null
> @@ -1,231 +0,0 @@
> -Linux power supply class
> -========================
> -
> -Synopsis
> -~~~~~~~~
> -Power supply class used to represent battery, UPS, AC or DC power supply
> -properties to user-space.
> -
> -It defines core set of attributes, which should be applicable to (almost)
> -every power supply out there. Attributes are available via sysfs and uevent
> -interfaces.
> -
> -Each attribute has well defined meaning, up to unit of measure used. While
> -the attributes provided are believed to be universally applicable to any
> -power supply, specific monitoring hardware may not be able to provide them
> -all, so any of them may be skipped.
> -
> -Power supply class is extensible, and allows to define drivers own attributes.
> -The core attribute set is subject to the standard Linux evolution (i.e.
> -if it will be found that some attribute is applicable to many power supply
> -types or their drivers, it can be added to the core set).
> -
> -It also integrates with LED framework, for the purpose of providing
> -typically expected feedback of battery charging/fully charged status and
> -AC/USB power supply online status. (Note that specific details of the
> -indication (including whether to use it at all) are fully controllable by
> -user and/or specific machine defaults, per design principles of LED
> -framework).
> -
> -
> -Attributes/properties
> -~~~~~~~~~~~~~~~~~~~~~
> -Power supply class has predefined set of attributes, this eliminates code
> -duplication across drivers. Power supply class insist on reusing its
> -predefined attributes *and* their units.
> -
> -So, userspace gets predictable set of attributes and their units for any
> -kind of power supply, and can process/present them to a user in consistent
> -manner. Results for different power supplies and machines are also directly
> -comparable.
> -
> -See drivers/power/supply/ds2760_battery.c and drivers/power/supply/pda_power.c
> -for the example how to declare and handle attributes.
> -
> -
> -Units
> -~~~~~
> -Quoting include/linux/power_supply.h:
> -
> - All voltages, currents, charges, energies, time and temperatures in µV,
> - µA, µAh, µWh, seconds and tenths of degree Celsius unless otherwise
> - stated. It's driver's job to convert its raw values to units in which
> - this class operates.
> -
> -
> -Attributes/properties detailed
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -~ ~ ~ ~ ~ ~ ~ Charge/Energy/Capacity - how to not confuse ~ ~ ~ ~ ~ ~ ~
> -~ ~
> -~ Because both "charge" (µAh) and "energy" (µWh) represents "capacity" ~
> -~ of battery, this class distinguish these terms. Don't mix them! ~
> -~ ~
> -~ CHARGE_* attributes represents capacity in µAh only. ~
> -~ ENERGY_* attributes represents capacity in µWh only. ~
> -~ CAPACITY attribute represents capacity in *percents*, from 0 to 100. ~
> -~ ~
> -~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
> -
> -Postfixes:
> -_AVG - *hardware* averaged value, use it if your hardware is really able to
> -report averaged values.
> -_NOW - momentary/instantaneous values.
> -
> -STATUS - this attribute represents operating status (charging, full,
> -discharging (i.e. powering a load), etc.). This corresponds to
> -BATTERY_STATUS_* values, as defined in battery.h.
> -
> -CHARGE_TYPE - batteries can typically charge at different rates.
> -This defines trickle and fast charges. For batteries that
> -are already charged or discharging, 'n/a' can be displayed (or
> -'unknown', if the status is not known).
> -
> -AUTHENTIC - indicates the power supply (battery or charger) connected
> -to the platform is authentic(1) or non authentic(0).
> -
> -HEALTH - represents health of the battery, values corresponds to
> -POWER_SUPPLY_HEALTH_*, defined in battery.h.
> -
> -VOLTAGE_OCV - open circuit voltage of the battery.
> -
> -VOLTAGE_MAX_DESIGN, VOLTAGE_MIN_DESIGN - design values for maximal and
> -minimal power supply voltages. Maximal/minimal means values of voltages
> -when battery considered "full"/"empty" at normal conditions. Yes, there is
> -no direct relation between voltage and battery capacity, but some dumb
> -batteries use voltage for very approximated calculation of capacity.
> -Battery driver also can use this attribute just to inform userspace
> -about maximal and minimal voltage thresholds of a given battery.
> -
> -VOLTAGE_MAX, VOLTAGE_MIN - same as _DESIGN voltage values except that
> -these ones should be used if hardware could only guess (measure and
> -retain) the thresholds of a given power supply.
> -
> -VOLTAGE_BOOT - Reports the voltage measured during boot
> -
> -CURRENT_BOOT - Reports the current measured during boot
> -
> -CHARGE_FULL_DESIGN, CHARGE_EMPTY_DESIGN - design charge values, when
> -battery considered full/empty.
> -
> -ENERGY_FULL_DESIGN, ENERGY_EMPTY_DESIGN - same as above but for energy.
> -
> -CHARGE_FULL, CHARGE_EMPTY - These attributes means "last remembered value
> -of charge when battery became full/empty". It also could mean "value of
> -charge when battery considered full/empty at given conditions (temperature,
> -age)". I.e. these attributes represents real thresholds, not design values.
> -
> -ENERGY_FULL, ENERGY_EMPTY - same as above but for energy.
> -
> -CHARGE_COUNTER - the current charge counter (in µAh). This could easily
> -be negative; there is no empty or full value. It is only useful for
> -relative, time-based measurements.
> -
> -PRECHARGE_CURRENT - the maximum charge current during precharge phase
> -of charge cycle (typically 20% of battery capacity).
> -CHARGE_TERM_CURRENT - Charge termination current. The charge cycle
> -terminates when battery voltage is above recharge threshold, and charge
> -current is below this setting (typically 10% of battery capacity).
> -
> -CONSTANT_CHARGE_CURRENT - constant charge current programmed by charger.
> -CONSTANT_CHARGE_CURRENT_MAX - maximum charge current supported by the
> -power supply object.
> -
> -CONSTANT_CHARGE_VOLTAGE - constant charge voltage programmed by charger.
> -CONSTANT_CHARGE_VOLTAGE_MAX - maximum charge voltage supported by the
> -power supply object.
> -
> -INPUT_CURRENT_LIMIT - input current limit programmed by charger. Indicates
> -the current drawn from a charging source.
> -
> -CHARGE_CONTROL_LIMIT - current charge control limit setting
> -CHARGE_CONTROL_LIMIT_MAX - maximum charge control limit setting
> -
> -CALIBRATE - battery or coulomb counter calibration status
> -
> -CAPACITY - capacity in percents.
> -CAPACITY_ALERT_MIN - minimum capacity alert value in percents.
> -CAPACITY_ALERT_MAX - maximum capacity alert value in percents.
> -CAPACITY_LEVEL - capacity level. This corresponds to
> -POWER_SUPPLY_CAPACITY_LEVEL_*.
> -
> -TEMP - temperature of the power supply.
> -TEMP_ALERT_MIN - minimum battery temperature alert.
> -TEMP_ALERT_MAX - maximum battery temperature alert.
> -TEMP_AMBIENT - ambient temperature.
> -TEMP_AMBIENT_ALERT_MIN - minimum ambient temperature alert.
> -TEMP_AMBIENT_ALERT_MAX - maximum ambient temperature alert.
> -TEMP_MIN - minimum operatable temperature
> -TEMP_MAX - maximum operatable temperature
> -
> -TIME_TO_EMPTY - seconds left for battery to be considered empty (i.e.
> -while battery powers a load)
> -TIME_TO_FULL - seconds left for battery to be considered full (i.e.
> -while battery is charging)
> -
> -
> -Battery <-> external power supply interaction
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -Often power supplies are acting as supplies and supplicants at the same
> -time. Batteries are good example. So, batteries usually care if they're
> -externally powered or not.
> -
> -For that case, power supply class implements notification mechanism for
> -batteries.
> -
> -External power supply (AC) lists supplicants (batteries) names in
> -"supplied_to" struct member, and each power_supply_changed() call
> -issued by external power supply will notify supplicants via
> -external_power_changed callback.
> -
> -
> -Devicetree battery characteristics
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -Drivers should call power_supply_get_battery_info() to obtain battery
> -characteristics from a devicetree battery node, defined in
> -Documentation/devicetree/bindings/power/supply/battery.txt. This is
> -implemented in drivers/power/supply/bq27xxx_battery.c.
> -
> -Properties in struct power_supply_battery_info and their counterparts in the
> -battery node have names corresponding to elements in enum power_supply_property,
> -for naming consistency between sysfs attributes and battery node properties.
> -
> -
> -QA
> -~~
> -Q: Where is POWER_SUPPLY_PROP_XYZ attribute?
> -A: If you cannot find attribute suitable for your driver needs, feel free
> - to add it and send patch along with your driver.
> -
> - The attributes available currently are the ones currently provided by the
> - drivers written.
> -
> - Good candidates to add in future: model/part#, cycle_time, manufacturer,
> - etc.
> -
> -
> -Q: I have some very specific attribute (e.g. battery color), should I add
> - this attribute to standard ones?
> -A: Most likely, no. Such attribute can be placed in the driver itself, if
> - it is useful. Of course, if the attribute in question applicable to
> - large set of batteries, provided by many drivers, and/or comes from
> - some general battery specification/standard, it may be a candidate to
> - be added to the core attribute set.
> -
> -
> -Q: Suppose, my battery monitoring chip/firmware does not provides capacity
> - in percents, but provides charge_{now,full,empty}. Should I calculate
> - percentage capacity manually, inside the driver, and register CAPACITY
> - attribute? The same question about time_to_empty/time_to_full.
> -A: Most likely, no. This class is designed to export properties which are
> - directly measurable by the specific hardware available.
> -
> - Inferring not available properties using some heuristics or mathematical
> - model is not subject of work for a battery driver. Such functionality
> - should be factored out, and in fact, apm_power, the driver to serve
> - legacy APM API on top of power supply class, uses a simple heuristic of
> - approximating remaining battery capacity based on its charge, current,
> - voltage and so on. But full-fledged battery model is likely not subject
> - for kernel at all, as it would require floating point calculation to deal
> - with things like differential equations and Kalman filters. This is
> - better be handled by batteryd/libbattery, yet to be written.
> diff --git a/Documentation/power/powercap/powercap.rst b/Documentation/power/powercap/powercap.rst
> new file mode 100644
> index 000000000000..7ae3b44c7624
> --- /dev/null
> +++ b/Documentation/power/powercap/powercap.rst
> @@ -0,0 +1,257 @@
> +=======================
> +Power Capping Framework
> +=======================
> +
> +The power capping framework provides a consistent interface between the kernel
> +and the user space that allows power capping drivers to expose the settings to
> +user space in a uniform way.
> +
> +Terminology
> +===========
> +
> +The framework exposes power capping devices to user space via sysfs in the
> +form of a tree of objects. The objects at the root level of the tree represent
> +'control types', which correspond to different methods of power capping. For
> +example, the intel-rapl control type represents the Intel "Running Average
> +Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
> +corresponds to the use of idle injection for controlling power.
> +
> +Power zones represent different parts of the system, which can be controlled and
> +monitored using the power capping method determined by the control type the
> +given zone belongs to. They each contain attributes for monitoring power, as
> +well as controls represented in the form of power constraints. If the parts of
> +the system represented by different power zones are hierarchical (that is, one
> +bigger part consists of multiple smaller parts that each have their own power
> +controls), those power zones may also be organized in a hierarchy with one
> +parent power zone containing multiple subzones and so on to reflect the power
> +control topology of the system. In that case, it is possible to apply power
> +capping to a set of devices together using the parent power zone and if more
> +fine grained control is required, it can be applied through the subzones.
> +
> +
> +Example sysfs interface tree::
> +
> + /sys/devices/virtual/powercap
> + └──intel-rapl
> + ├──intel-rapl:0
> + │ ├──constraint_0_name
> + │ ├──constraint_0_power_limit_uw
> + │ ├──constraint_0_time_window_us
> + │ ├──constraint_1_name
> + │ ├──constraint_1_power_limit_uw
> + │ ├──constraint_1_time_window_us
> + │ ├──device -> ../../intel-rapl
> + │ ├──energy_uj
> + │ ├──intel-rapl:0:0
> + │ │ ├──constraint_0_name
> + │ │ ├──constraint_0_power_limit_uw
> + │ │ ├──constraint_0_time_window_us
> + │ │ ├──constraint_1_name
> + │ │ ├──constraint_1_power_limit_uw
> + │ │ ├──constraint_1_time_window_us
> + │ │ ├──device -> ../../intel-rapl:0
> + │ │ ├──energy_uj
> + │ │ ├──max_energy_range_uj
> + │ │ ├──name
> + │ │ ├──enabled
> + │ │ ├──power
> + │ │ │ ├──async
> + │ │ │ []
> + │ │ ├──subsystem -> ../../../../../../class/power_cap
> + │ │ └──uevent
> + │ ├──intel-rapl:0:1
> + │ │ ├──constraint_0_name
> + │ │ ├──constraint_0_power_limit_uw
> + │ │ ├──constraint_0_time_window_us
> + │ │ ├──constraint_1_name
> + │ │ ├──constraint_1_power_limit_uw
> + │ │ ├──constraint_1_time_window_us
> + │ │ ├──device -> ../../intel-rapl:0
> + │ │ ├──energy_uj
> + │ │ ├──max_energy_range_uj
> + │ │ ├──name
> + │ │ ├──enabled
> + │ │ ├──power
> + │ │ │ ├──async
> + │ │ │ []
> + │ │ ├──subsystem -> ../../../../../../class/power_cap
> + │ │ └──uevent
> + │ ├──max_energy_range_uj
> + │ ├──max_power_range_uw
> + │ ├──name
> + │ ├──enabled
> + │ ├──power
> + │ │ ├──async
> + │ │ []
> + │ ├──subsystem -> ../../../../../class/power_cap
> + │ ├──enabled
> + │ ├──uevent
> + ├──intel-rapl:1
> + │ ├──constraint_0_name
> + │ ├──constraint_0_power_limit_uw
> + │ ├──constraint_0_time_window_us
> + │ ├──constraint_1_name
> + │ ├──constraint_1_power_limit_uw
> + │ ├──constraint_1_time_window_us
> + │ ├──device -> ../../intel-rapl
> + │ ├──energy_uj
> + │ ├──intel-rapl:1:0
> + │ │ ├──constraint_0_name
> + │ │ ├──constraint_0_power_limit_uw
> + │ │ ├──constraint_0_time_window_us
> + │ │ ├──constraint_1_name
> + │ │ ├──constraint_1_power_limit_uw
> + │ │ ├──constraint_1_time_window_us
> + │ │ ├──device -> ../../intel-rapl:1
> + │ │ ├──energy_uj
> + │ │ ├──max_energy_range_uj
> + │ │ ├──name
> + │ │ ├──enabled
> + │ │ ├──power
> + │ │ │ ├──async
> + │ │ │ []
> + │ │ ├──subsystem -> ../../../../../../class/power_cap
> + │ │ └──uevent
> + │ ├──intel-rapl:1:1
> + │ │ ├──constraint_0_name
> + │ │ ├──constraint_0_power_limit_uw
> + │ │ ├──constraint_0_time_window_us
> + │ │ ├──constraint_1_name
> + │ │ ├──constraint_1_power_limit_uw
> + │ │ ├──constraint_1_time_window_us
> + │ │ ├──device -> ../../intel-rapl:1
> + │ │ ├──energy_uj
> + │ │ ├──max_energy_range_uj
> + │ │ ├──name
> + │ │ ├──enabled
> + │ │ ├──power
> + │ │ │ ├──async
> + │ │ │ []
> + │ │ ├──subsystem -> ../../../../../../class/power_cap
> + │ │ └──uevent
> + │ ├──max_energy_range_uj
> + │ ├──max_power_range_uw
> + │ ├──name
> + │ ├──enabled
> + │ ├──power
> + │ │ ├──async
> + │ │ []
> + │ ├──subsystem -> ../../../../../class/power_cap
> + │ ├──uevent
> + ├──power
> + │ ├──async
> + │ []
> + ├──subsystem -> ../../../../class/power_cap
> + ├──enabled
> + └──uevent
> +
> +The above example illustrates a case in which the Intel RAPL technology,
> +available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
> +control type called intel-rapl which contains two power zones, intel-rapl:0 and
> +intel-rapl:1, representing CPU packages. Each of these power zones contains
> +two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
> +"core" and the "uncore" parts of the given CPU package, respectively. All of
> +the zones and subzones contain energy monitoring attributes (energy_uj,
> +max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
> +to be applied (the constraints in the 'package' power zones apply to the whole
> +CPU packages and the subzone constraints only apply to the respective parts of
> +the given package individually). Since Intel RAPL doesn't provide instantaneous
> +power value, there is no power_uw attribute.
> +
> +In addition to that, each power zone contains a name attribute, allowing the
> +part of the system represented by that zone to be identified.
> +For example::
> +
> + cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
> +
> +package-0
> +---------
> +
> +The Intel RAPL technology allows two constraints, short term and long term,
> +with two different time windows to be applied to each power zone. Thus for
> +each zone there are 2 attributes representing the constraint names, 2 power
> +limits and 2 attributes representing the sizes of the time windows. Such that,
> +constraint_j_* attributes correspond to the jth constraint (j = 0,1).
> +
> +For example::
> +
> + constraint_0_name
> + constraint_0_power_limit_uw
> + constraint_0_time_window_us
> + constraint_1_name
> + constraint_1_power_limit_uw
> + constraint_1_time_window_us
> +
> +Power Zone Attributes
> +=====================
> +
> +Monitoring attributes
> +---------------------
> +
> +energy_uj (rw)
> + Current energy counter in micro joules. Write "0" to reset.
> + If the counter can not be reset, then this attribute is read only.
> +
> +max_energy_range_uj (ro)
> + Range of the above energy counter in micro-joules.
> +
> +power_uw (ro)
> + Current power in micro watts.
> +
> +max_power_range_uw (ro)
> + Range of the above power value in micro-watts.
> +
> +name (ro)
> + Name of this power zone.
> +
> +It is possible that some domains have both power ranges and energy counter ranges;
> +however, only one is mandatory.
> +
> +Constraints
> +-----------
> +
> +constraint_X_power_limit_uw (rw)
> + Power limit in micro watts, which should be applicable for the
> + time window specified by "constraint_X_time_window_us".
> +
> +constraint_X_time_window_us (rw)
> + Time window in micro seconds.
> +
> +constraint_X_name (ro)
> + An optional name of the constraint
> +
> +constraint_X_max_power_uw(ro)
> + Maximum allowed power in micro watts.
> +
> +constraint_X_min_power_uw(ro)
> + Minimum allowed power in micro watts.
> +
> +constraint_X_max_time_window_us(ro)
> + Maximum allowed time window in micro seconds.
> +
> +constraint_X_min_time_window_us(ro)
> + Minimum allowed time window in micro seconds.
> +
> +Except power_limit_uw and time_window_us other fields are optional.
> +
> +Common zone and control type attributes
> +---------------------------------------
> +
> +enabled (rw): Enable/Disable controls at zone level or for all zones using
> +a control type.
> +
> +Power Cap Client Driver Interface
> +=================================
> +
> +The API summary:
> +
> +Call powercap_register_control_type() to register control type object.
> +Call powercap_register_zone() to register a power zone (under a given
> +control type), either as a top-level power zone or as a subzone of another
> +power zone registered earlier.
> +The number of constraints in a power zone and the corresponding callbacks have
> +to be defined prior to calling powercap_register_zone() to register that zone.
> +
> +To Free a power zone call powercap_unregister_zone().
> +To free a control type object call powercap_unregister_control_type().
> +Detailed API can be generated using kernel-doc on include/linux/powercap.h.
> diff --git a/Documentation/power/powercap/powercap.txt b/Documentation/power/powercap/powercap.txt
> deleted file mode 100644
> index 1e6ef164e07a..000000000000
> --- a/Documentation/power/powercap/powercap.txt
> +++ /dev/null
> @@ -1,236 +0,0 @@
> -Power Capping Framework
> -==================================
> -
> -The power capping framework provides a consistent interface between the kernel
> -and the user space that allows power capping drivers to expose the settings to
> -user space in a uniform way.
> -
> -Terminology
> -=========================
> -The framework exposes power capping devices to user space via sysfs in the
> -form of a tree of objects. The objects at the root level of the tree represent
> -'control types', which correspond to different methods of power capping. For
> -example, the intel-rapl control type represents the Intel "Running Average
> -Power Limit" (RAPL) technology, whereas the 'idle-injection' control type
> -corresponds to the use of idle injection for controlling power.
> -
> -Power zones represent different parts of the system, which can be controlled and
> -monitored using the power capping method determined by the control type the
> -given zone belongs to. They each contain attributes for monitoring power, as
> -well as controls represented in the form of power constraints. If the parts of
> -the system represented by different power zones are hierarchical (that is, one
> -bigger part consists of multiple smaller parts that each have their own power
> -controls), those power zones may also be organized in a hierarchy with one
> -parent power zone containing multiple subzones and so on to reflect the power
> -control topology of the system. In that case, it is possible to apply power
> -capping to a set of devices together using the parent power zone and if more
> -fine grained control is required, it can be applied through the subzones.
> -
> -
> -Example sysfs interface tree:
> -
> -/sys/devices/virtual/powercap
> -??? intel-rapl
> - ??? intel-rapl:0
> - ? ??? constraint_0_name
> - ? ??? constraint_0_power_limit_uw
> - ? ??? constraint_0_time_window_us
> - ? ??? constraint_1_name
> - ? ??? constraint_1_power_limit_uw
> - ? ??? constraint_1_time_window_us
> - ? ??? device -> ../../intel-rapl
> - ? ??? energy_uj
> - ? ??? intel-rapl:0:0
> - ? ? ??? constraint_0_name
> - ? ? ??? constraint_0_power_limit_uw
> - ? ? ??? constraint_0_time_window_us
> - ? ? ??? constraint_1_name
> - ? ? ??? constraint_1_power_limit_uw
> - ? ? ??? constraint_1_time_window_us
> - ? ? ??? device -> ../../intel-rapl:0
> - ? ? ??? energy_uj
> - ? ? ??? max_energy_range_uj
> - ? ? ??? name
> - ? ? ??? enabled
> - ? ? ??? power
> - ? ? ? ??? async
> - ? ? ? []
> - ? ? ??? subsystem -> ../../../../../../class/power_cap
> - ? ? ??? uevent
> - ? ??? intel-rapl:0:1
> - ? ? ??? constraint_0_name
> - ? ? ??? constraint_0_power_limit_uw
> - ? ? ??? constraint_0_time_window_us
> - ? ? ??? constraint_1_name
> - ? ? ??? constraint_1_power_limit_uw
> - ? ? ??? constraint_1_time_window_us
> - ? ? ??? device -> ../../intel-rapl:0
> - ? ? ??? energy_uj
> - ? ? ??? max_energy_range_uj
> - ? ? ??? name
> - ? ? ??? enabled
> - ? ? ??? power
> - ? ? ? ??? async
> - ? ? ? []
> - ? ? ??? subsystem -> ../../../../../../class/power_cap
> - ? ? ??? uevent
> - ? ??? max_energy_range_uj
> - ? ??? max_power_range_uw
> - ? ??? name
> - ? ??? enabled
> - ? ??? power
> - ? ? ??? async
> - ? ? []
> - ? ??? subsystem -> ../../../../../class/power_cap
> - ? ??? enabled
> - ? ??? uevent
> - ??? intel-rapl:1
> - ? ??? constraint_0_name
> - ? ??? constraint_0_power_limit_uw
> - ? ??? constraint_0_time_window_us
> - ? ??? constraint_1_name
> - ? ??? constraint_1_power_limit_uw
> - ? ??? constraint_1_time_window_us
> - ? ??? device -> ../../intel-rapl
> - ? ??? energy_uj
> - ? ??? intel-rapl:1:0
> - ? ? ??? constraint_0_name
> - ? ? ??? constraint_0_power_limit_uw
> - ? ? ??? constraint_0_time_window_us
> - ? ? ??? constraint_1_name
> - ? ? ??? constraint_1_power_limit_uw
> - ? ? ??? constraint_1_time_window_us
> - ? ? ??? device -> ../../intel-rapl:1
> - ? ? ??? energy_uj
> - ? ? ??? max_energy_range_uj
> - ? ? ??? name
> - ? ? ??? enabled
> - ? ? ??? power
> - ? ? ? ??? async
> - ? ? ? []
> - ? ? ??? subsystem -> ../../../../../../class/power_cap
> - ? ? ??? uevent
> - ? ??? intel-rapl:1:1
> - ? ? ??? constraint_0_name
> - ? ? ??? constraint_0_power_limit_uw
> - ? ? ??? constraint_0_time_window_us
> - ? ? ??? constraint_1_name
> - ? ? ??? constraint_1_power_limit_uw
> - ? ? ??? constraint_1_time_window_us
> - ? ? ??? device -> ../../intel-rapl:1
> - ? ? ??? energy_uj
> - ? ? ??? max_energy_range_uj
> - ? ? ??? name
> - ? ? ??? enabled
> - ? ? ??? power
> - ? ? ? ??? async
> - ? ? ? []
> - ? ? ??? subsystem -> ../../../../../../class/power_cap
> - ? ? ??? uevent
> - ? ??? max_energy_range_uj
> - ? ??? max_power_range_uw
> - ? ??? name
> - ? ??? enabled
> - ? ??? power
> - ? ? ??? async
> - ? ? []
> - ? ??? subsystem -> ../../../../../class/power_cap
> - ? ??? uevent
> - ??? power
> - ? ??? async
> - ? []
> - ??? subsystem -> ../../../../class/power_cap
> - ??? enabled
> - ??? uevent
> -
> -The above example illustrates a case in which the Intel RAPL technology,
> -available in Intel® IA-64 and IA-32 Processor Architectures, is used. There is one
> -control type called intel-rapl which contains two power zones, intel-rapl:0 and
> -intel-rapl:1, representing CPU packages. Each of these power zones contains
> -two subzones, intel-rapl:j:0 and intel-rapl:j:1 (j = 0, 1), representing the
> -"core" and the "uncore" parts of the given CPU package, respectively. All of
> -the zones and subzones contain energy monitoring attributes (energy_uj,
> -max_energy_range_uj) and constraint attributes (constraint_*) allowing controls
> -to be applied (the constraints in the 'package' power zones apply to the whole
> -CPU packages and the subzone constraints only apply to the respective parts of
> -the given package individually). Since Intel RAPL doesn't provide instantaneous
> -power value, there is no power_uw attribute.
> -
> -In addition to that, each power zone contains a name attribute, allowing the
> -part of the system represented by that zone to be identified.
> -For example:
> -
> -cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
> -package-0
> -
> -The Intel RAPL technology allows two constraints, short term and long term,
> -with two different time windows to be applied to each power zone. Thus for
> -each zone there are 2 attributes representing the constraint names, 2 power
> -limits and 2 attributes representing the sizes of the time windows. Such that,
> -constraint_j_* attributes correspond to the jth constraint (j = 0,1).
> -
> -For example:
> - constraint_0_name
> - constraint_0_power_limit_uw
> - constraint_0_time_window_us
> - constraint_1_name
> - constraint_1_power_limit_uw
> - constraint_1_time_window_us
> -
> -Power Zone Attributes
> -=================================
> -Monitoring attributes
> -----------------------
> -
> -energy_uj (rw): Current energy counter in micro joules. Write "0" to reset.
> -If the counter can not be reset, then this attribute is read only.
> -
> -max_energy_range_uj (ro): Range of the above energy counter in micro-joules.
> -
> -power_uw (ro): Current power in micro watts.
> -
> -max_power_range_uw (ro): Range of the above power value in micro-watts.
> -
> -name (ro): Name of this power zone.
> -
> -It is possible that some domains have both power ranges and energy counter ranges;
> -however, only one is mandatory.
> -
> -Constraints
> -----------------
> -constraint_X_power_limit_uw (rw): Power limit in micro watts, which should be
> -applicable for the time window specified by "constraint_X_time_window_us".
> -
> -constraint_X_time_window_us (rw): Time window in micro seconds.
> -
> -constraint_X_name (ro): An optional name of the constraint
> -
> -constraint_X_max_power_uw(ro): Maximum allowed power in micro watts.
> -
> -constraint_X_min_power_uw(ro): Minimum allowed power in micro watts.
> -
> -constraint_X_max_time_window_us(ro): Maximum allowed time window in micro seconds.
> -
> -constraint_X_min_time_window_us(ro): Minimum allowed time window in micro seconds.
> -
> -Except power_limit_uw and time_window_us other fields are optional.
> -
> -Common zone and control type attributes
> -----------------------------------------
> -enabled (rw): Enable/Disable controls at zone level or for all zones using
> -a control type.
> -
> -Power Cap Client Driver Interface
> -==================================
> -The API summary:
> -
> -Call powercap_register_control_type() to register control type object.
> -Call powercap_register_zone() to register a power zone (under a given
> -control type), either as a top-level power zone or as a subzone of another
> -power zone registered earlier.
> -The number of constraints in a power zone and the corresponding callbacks have
> -to be defined prior to calling powercap_register_zone() to register that zone.
> -
> -To Free a power zone call powercap_unregister_zone().
> -To free a control type object call powercap_unregister_control_type().
> -Detailed API can be generated using kernel-doc on include/linux/powercap.h.
> diff --git a/Documentation/power/regulator/consumer.txt b/Documentation/power/regulator/consumer.rst
> similarity index 61%
> rename from Documentation/power/regulator/consumer.txt
> rename to Documentation/power/regulator/consumer.rst
> index e51564c1a140..0cd8cc1275a7 100644
> --- a/Documentation/power/regulator/consumer.txt
> +++ b/Documentation/power/regulator/consumer.rst
> @@ -1,3 +1,4 @@
> +===================================
> Regulator Consumer Driver Interface
> ===================================
>
> @@ -8,73 +9,77 @@ Please see overview.txt for a description of the terms used in this text.
> 1. Consumer Regulator Access (static & dynamic drivers)
> =======================================================
>
> -A consumer driver can get access to its supply regulator by calling :-
> +A consumer driver can get access to its supply regulator by calling ::
>
> -regulator = regulator_get(dev, "Vcc");
> + regulator = regulator_get(dev, "Vcc");
>
> The consumer passes in its struct device pointer and power supply ID. The core
> then finds the correct regulator by consulting a machine specific lookup table.
> If the lookup is successful then this call will return a pointer to the struct
> regulator that supplies this consumer.
>
> -To release the regulator the consumer driver should call :-
> +To release the regulator the consumer driver should call ::
>
> -regulator_put(regulator);
> + regulator_put(regulator);
>
> Consumers can be supplied by more than one regulator e.g. codec consumer with
> -analog and digital supplies :-
> +analog and digital supplies ::
>
> -digital = regulator_get(dev, "Vcc"); /* digital core */
> -analog = regulator_get(dev, "Avdd"); /* analog */
> + digital = regulator_get(dev, "Vcc"); /* digital core */
> + analog = regulator_get(dev, "Avdd"); /* analog */
>
> The regulator access functions regulator_get() and regulator_put() will
> usually be called in your device drivers probe() and remove() respectively.
>
>
> 2. Regulator Output Enable & Disable (static & dynamic drivers)
> -====================================================================
> +===============================================================
>
> -A consumer can enable its power supply by calling:-
>
> -int regulator_enable(regulator);
> +A consumer can enable its power supply by calling::
>
> -NOTE: The supply may already be enabled before regulator_enabled() is called.
> -This may happen if the consumer shares the regulator or the regulator has been
> -previously enabled by bootloader or kernel board initialization code.
> + int regulator_enable(regulator);
>
> -A consumer can determine if a regulator is enabled by calling :-
> +NOTE:
> + The supply may already be enabled before regulator_enabled() is called.
> + This may happen if the consumer shares the regulator or the regulator has been
> + previously enabled by bootloader or kernel board initialization code.
>
> -int regulator_is_enabled(regulator);
> +A consumer can determine if a regulator is enabled by calling::
> +
> + int regulator_is_enabled(regulator);
>
> This will return > zero when the regulator is enabled.
>
>
> -A consumer can disable its supply when no longer needed by calling :-
> +A consumer can disable its supply when no longer needed by calling::
>
> -int regulator_disable(regulator);
> + int regulator_disable(regulator);
>
> -NOTE: This may not disable the supply if it's shared with other consumers. The
> -regulator will only be disabled when the enabled reference count is zero.
> +NOTE:
> + This may not disable the supply if it's shared with other consumers. The
> + regulator will only be disabled when the enabled reference count is zero.
>
> -Finally, a regulator can be forcefully disabled in the case of an emergency :-
> +Finally, a regulator can be forcefully disabled in the case of an emergency::
>
> -int regulator_force_disable(regulator);
> + int regulator_force_disable(regulator);
>
> -NOTE: this will immediately and forcefully shutdown the regulator output. All
> -consumers will be powered off.
> +NOTE:
> + this will immediately and forcefully shutdown the regulator output. All
> + consumers will be powered off.
>
>
> 3. Regulator Voltage Control & Status (dynamic drivers)
> -======================================================
> +=======================================================
>
> Some consumer drivers need to be able to dynamically change their supply
> voltage to match system operating points. e.g. CPUfreq drivers can scale
> voltage along with frequency to save power, SD drivers may need to select the
> correct card voltage, etc.
>
> -Consumers can control their supply voltage by calling :-
> +Consumers can control their supply voltage by calling::
>
> -int regulator_set_voltage(regulator, min_uV, max_uV);
> + int regulator_set_voltage(regulator, min_uV, max_uV);
>
> Where min_uV and max_uV are the minimum and maximum acceptable voltages in
> microvolts.
> @@ -84,47 +89,50 @@ when enabled, then the voltage changes instantly, otherwise the voltage
> configuration changes and the voltage is physically set when the regulator is
> next enabled.
>
> -The regulators configured voltage output can be found by calling :-
> +The regulators configured voltage output can be found by calling::
>
> -int regulator_get_voltage(regulator);
> + int regulator_get_voltage(regulator);
>
> -NOTE: get_voltage() will return the configured output voltage whether the
> -regulator is enabled or disabled and should NOT be used to determine regulator
> -output state. However this can be used in conjunction with is_enabled() to
> -determine the regulator physical output voltage.
> +NOTE:
> + get_voltage() will return the configured output voltage whether the
> + regulator is enabled or disabled and should NOT be used to determine regulator
> + output state. However this can be used in conjunction with is_enabled() to
> + determine the regulator physical output voltage.
>
>
> 4. Regulator Current Limit Control & Status (dynamic drivers)
> -===========================================================
> +=============================================================
>
> Some consumer drivers need to be able to dynamically change their supply
> current limit to match system operating points. e.g. LCD backlight driver can
> change the current limit to vary the backlight brightness, USB drivers may want
> to set the limit to 500mA when supplying power.
>
> -Consumers can control their supply current limit by calling :-
> +Consumers can control their supply current limit by calling::
>
> -int regulator_set_current_limit(regulator, min_uA, max_uA);
> + int regulator_set_current_limit(regulator, min_uA, max_uA);
>
> Where min_uA and max_uA are the minimum and maximum acceptable current limit in
> microamps.
>
> -NOTE: this can be called when the regulator is enabled or disabled. If called
> -when enabled, then the current limit changes instantly, otherwise the current
> -limit configuration changes and the current limit is physically set when the
> -regulator is next enabled.
> +NOTE:
> + this can be called when the regulator is enabled or disabled. If called
> + when enabled, then the current limit changes instantly, otherwise the current
> + limit configuration changes and the current limit is physically set when the
> + regulator is next enabled.
>
> -A regulators current limit can be found by calling :-
> +A regulators current limit can be found by calling::
>
> -int regulator_get_current_limit(regulator);
> + int regulator_get_current_limit(regulator);
>
> -NOTE: get_current_limit() will return the current limit whether the regulator
> -is enabled or disabled and should not be used to determine regulator current
> -load.
> +NOTE:
> + get_current_limit() will return the current limit whether the regulator
> + is enabled or disabled and should not be used to determine regulator current
> + load.
>
>
> 5. Regulator Operating Mode Control & Status (dynamic drivers)
> -=============================================================
> +==============================================================
>
> Some consumers can further save system power by changing the operating mode of
> their supply regulator to be more efficient when the consumers operating state
> @@ -135,9 +143,9 @@ Regulator operating mode can be changed indirectly or directly.
> Indirect operating mode control.
> --------------------------------
> Consumer drivers can request a change in their supply regulator operating mode
> -by calling :-
> +by calling::
>
> -int regulator_set_load(struct regulator *regulator, int load_uA);
> + int regulator_set_load(struct regulator *regulator, int load_uA);
>
> This will cause the core to recalculate the total load on the regulator (based
> on all its consumers) and change operating mode (if necessary and permitted)
> @@ -153,12 +161,13 @@ consumers.
>
> Direct operating mode control.
> ------------------------------
> +
> Bespoke or tightly coupled drivers may want to directly control regulator
> operating mode depending on their operating point. This can be achieved by
> -calling :-
> +calling::
>
> -int regulator_set_mode(struct regulator *regulator, unsigned int mode);
> -unsigned int regulator_get_mode(struct regulator *regulator);
> + int regulator_set_mode(struct regulator *regulator, unsigned int mode);
> + unsigned int regulator_get_mode(struct regulator *regulator);
>
> Direct mode will only be used by consumers that *know* about the regulator and
> are not sharing the regulator with other consumers.
> @@ -166,24 +175,26 @@ are not sharing the regulator with other consumers.
>
> 6. Regulator Events
> ===================
> +
> Regulators can notify consumers of external events. Events could be received by
> consumers under regulator stress or failure conditions.
>
> -Consumers can register interest in regulator events by calling :-
> +Consumers can register interest in regulator events by calling::
>
> -int regulator_register_notifier(struct regulator *regulator,
> - struct notifier_block *nb);
> + int regulator_register_notifier(struct regulator *regulator,
> + struct notifier_block *nb);
>
> -Consumers can unregister interest by calling :-
> +Consumers can unregister interest by calling::
>
> -int regulator_unregister_notifier(struct regulator *regulator,
> - struct notifier_block *nb);
> + int regulator_unregister_notifier(struct regulator *regulator,
> + struct notifier_block *nb);
>
> Regulators use the kernel notifier framework to send event to their interested
> consumers.
>
> 7. Regulator Direct Register Access
> ===================================
> +
> Some kinds of power management hardware or firmware are designed such that
> they need to do low-level hardware access to regulators, with no involvement
> from the kernel. Examples of such devices are:
> @@ -199,20 +210,20 @@ to it. The regulator framework provides the following helpers for querying
> these details.
>
> Bus-specific details, like I2C addresses or transfer rates are handled by the
> -regmap framework. To get the regulator's regmap (if supported), use :-
> +regmap framework. To get the regulator's regmap (if supported), use::
>
> -struct regmap *regulator_get_regmap(struct regulator *regulator);
> + struct regmap *regulator_get_regmap(struct regulator *regulator);
>
> To obtain the hardware register offset and bitmask for the regulator's voltage
> -selector register, use :-
> +selector register, use::
>
> -int regulator_get_hardware_vsel_register(struct regulator *regulator,
> - unsigned *vsel_reg,
> - unsigned *vsel_mask);
> + int regulator_get_hardware_vsel_register(struct regulator *regulator,
> + unsigned *vsel_reg,
> + unsigned *vsel_mask);
>
> To convert a regulator framework voltage selector code (used by
> regulator_list_voltage) to a hardware-specific voltage selector that can be
> -directly written to the voltage selector register, use :-
> +directly written to the voltage selector register, use::
>
> -int regulator_list_hardware_vsel(struct regulator *regulator,
> - unsigned selector);
> + int regulator_list_hardware_vsel(struct regulator *regulator,
> + unsigned selector);
> diff --git a/Documentation/power/regulator/design.txt b/Documentation/power/regulator/design.rst
> similarity index 86%
> rename from Documentation/power/regulator/design.txt
> rename to Documentation/power/regulator/design.rst
> index fdd919b96830..3b09c6841dc4 100644
> --- a/Documentation/power/regulator/design.txt
> +++ b/Documentation/power/regulator/design.rst
> @@ -1,3 +1,4 @@
> +==========================
> Regulator API design notes
> ==========================
>
> @@ -14,7 +15,9 @@ Safety
> have different power requirements, and not all components with power
> requirements are visible to software.
>
> - => The API should make no changes to the hardware state unless it has
> +.. note::
> +
> + The API should make no changes to the hardware state unless it has
> specific knowledge that these changes are safe to perform on this
> particular system.
>
> @@ -28,6 +31,8 @@ Consumer use cases
> - Many of the power supplies in the system will be shared between many
> different consumers.
>
> - => The consumer API should be structured so that these use cases are
> +.. note::
> +
> + The consumer API should be structured so that these use cases are
> very easy to handle and so that consumers will work with shared
> supplies without any additional effort.
> diff --git a/Documentation/power/regulator/machine.txt b/Documentation/power/regulator/machine.rst
> similarity index 75%
> rename from Documentation/power/regulator/machine.txt
> rename to Documentation/power/regulator/machine.rst
> index eff4dcaaa252..22fffefaa3ad 100644
> --- a/Documentation/power/regulator/machine.txt
> +++ b/Documentation/power/regulator/machine.rst
> @@ -1,10 +1,11 @@
> +==================================
> Regulator Machine Driver Interface
> -===================================
> +==================================
>
> The regulator machine driver interface is intended for board/machine specific
> initialisation code to configure the regulator subsystem.
>
> -Consider the following machine :-
> +Consider the following machine::
>
> Regulator-1 -+-> Regulator-2 --> [Consumer A @ 1.8 - 2.0V]
> |
> @@ -13,31 +14,31 @@ Consider the following machine :-
> The drivers for consumers A & B must be mapped to the correct regulator in
> order to control their power supplies. This mapping can be achieved in machine
> initialisation code by creating a struct regulator_consumer_supply for
> -each regulator.
> +each regulator::
>
> -struct regulator_consumer_supply {
> + struct regulator_consumer_supply {
> const char *dev_name; /* consumer dev_name() */
> const char *supply; /* consumer supply - e.g. "vcc" */
> -};
> + };
>
> -e.g. for the machine above
> +e.g. for the machine above::
>
> -static struct regulator_consumer_supply regulator1_consumers[] = {
> + static struct regulator_consumer_supply regulator1_consumers[] = {
> REGULATOR_SUPPLY("Vcc", "consumer B"),
> -};
> + };
>
> -static struct regulator_consumer_supply regulator2_consumers[] = {
> + static struct regulator_consumer_supply regulator2_consumers[] = {
> REGULATOR_SUPPLY("Vcc", "consumer A"),
> -};
> + };
>
> This maps Regulator-1 to the 'Vcc' supply for Consumer B and maps Regulator-2
> to the 'Vcc' supply for Consumer A.
>
> Constraints can now be registered by defining a struct regulator_init_data
> for each regulator power domain. This structure also maps the consumers
> -to their supply regulators :-
> +to their supply regulators::
>
> -static struct regulator_init_data regulator1_data = {
> + static struct regulator_init_data regulator1_data = {
> .constraints = {
> .name = "Regulator-1",
> .min_uV = 3300000,
> @@ -46,7 +47,7 @@ static struct regulator_init_data regulator1_data = {
> },
> .num_consumer_supplies = ARRAY_SIZE(regulator1_consumers),
> .consumer_supplies = regulator1_consumers,
> -};
> + };
>
> The name field should be set to something that is usefully descriptive
> for the board for configuration of supplies for other regulators and
> @@ -57,9 +58,9 @@ name is provided then the subsystem will choose one.
> Regulator-1 supplies power to Regulator-2. This relationship must be registered
> with the core so that Regulator-1 is also enabled when Consumer A enables its
> supply (Regulator-2). The supply regulator is set by the supply_regulator
> -field below and co:-
> +field below and co::
>
> -static struct regulator_init_data regulator2_data = {
> + static struct regulator_init_data regulator2_data = {
> .supply_regulator = "Regulator-1",
> .constraints = {
> .min_uV = 1800000,
> @@ -69,11 +70,11 @@ static struct regulator_init_data regulator2_data = {
> },
> .num_consumer_supplies = ARRAY_SIZE(regulator2_consumers),
> .consumer_supplies = regulator2_consumers,
> -};
> + };
>
> -Finally the regulator devices must be registered in the usual manner.
> +Finally the regulator devices must be registered in the usual manner::
>
> -static struct platform_device regulator_devices[] = {
> + static struct platform_device regulator_devices[] = {
> {
> .name = "regulator",
> .id = DCDC_1,
> @@ -88,9 +89,9 @@ static struct platform_device regulator_devices[] = {
> .platform_data = ®ulator2_data,
> },
> },
> -};
> -/* register regulator 1 device */
> -platform_device_register(®ulator_devices[0]);
> + };
> + /* register regulator 1 device */
> + platform_device_register(®ulator_devices[0]);
>
> -/* register regulator 2 device */
> -platform_device_register(®ulator_devices[1]);
> + /* register regulator 2 device */
> + platform_device_register(®ulator_devices[1]);
> diff --git a/Documentation/power/regulator/overview.txt b/Documentation/power/regulator/overview.rst
> similarity index 79%
> rename from Documentation/power/regulator/overview.txt
> rename to Documentation/power/regulator/overview.rst
> index 721b4739ec32..ee494c70a7c4 100644
> --- a/Documentation/power/regulator/overview.txt
> +++ b/Documentation/power/regulator/overview.rst
> @@ -1,3 +1,4 @@
> +=============================================
> Linux voltage and current regulator framework
> =============================================
>
> @@ -13,26 +14,30 @@ regulators (where voltage output is controllable) and current sinks (where
> current limit is controllable).
>
> (C) 2008 Wolfson Microelectronics PLC.
> +
> Author: Liam Girdwood <lrg-kDsPt+C1G03kYMGBc/C6ZA@public.gmane.org>
>
>
> Nomenclature
> ============
>
> -Some terms used in this document:-
> +Some terms used in this document:
>
> - o Regulator - Electronic device that supplies power to other devices.
> + - Regulator
> + - Electronic device that supplies power to other devices.
> Most regulators can enable and disable their output while
> some can control their output voltage and or current.
>
> Input Voltage -> Regulator -> Output Voltage
>
>
> - o PMIC - Power Management IC. An IC that contains numerous regulators
> - and often contains other subsystems.
> + - PMIC
> + - Power Management IC. An IC that contains numerous
> + regulators and often contains other subsystems.
>
>
> - o Consumer - Electronic device that is supplied power by a regulator.
> + - Consumer
> + - Electronic device that is supplied power by a regulator.
> Consumers can be classified into two types:-
>
> Static: consumer does not change its supply voltage or
> @@ -44,46 +49,48 @@ Some terms used in this document:-
> current limit to meet operation demands.
>
>
> - o Power Domain - Electronic circuit that is supplied its input power by the
> + - Power Domain
> + - Electronic circuit that is supplied its input power by the
> output power of a regulator, switch or by another power
> domain.
>
> - The supply regulator may be behind a switch(s). i.e.
> + The supply regulator may be behind a switch(s). i.e.::
>
> - Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
> - | |
> - | +-> [Consumer B], [Consumer C]
> - |
> - +-> [Consumer D], [Consumer E]
> + Regulator -+-> Switch-1 -+-> Switch-2 --> [Consumer A]
> + | |
> + | +-> [Consumer B], [Consumer C]
> + |
> + +-> [Consumer D], [Consumer E]
>
> That is one regulator and three power domains:
>
> - Domain 1: Switch-1, Consumers D & E.
> - Domain 2: Switch-2, Consumers B & C.
> - Domain 3: Consumer A.
> + - Domain 1: Switch-1, Consumers D & E.
> + - Domain 2: Switch-2, Consumers B & C.
> + - Domain 3: Consumer A.
>
> and this represents a "supplies" relationship:
>
> Domain-1 --> Domain-2 --> Domain-3.
>
> A power domain may have regulators that are supplied power
> - by other regulators. i.e.
> + by other regulators. i.e.::
>
> - Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
> - |
> - +-> [Consumer B]
> + Regulator-1 -+-> Regulator-2 -+-> [Consumer A]
> + |
> + +-> [Consumer B]
>
> This gives us two regulators and two power domains:
>
> - Domain 1: Regulator-2, Consumer B.
> - Domain 2: Consumer A.
> + - Domain 1: Regulator-2, Consumer B.
> + - Domain 2: Consumer A.
>
> and a "supplies" relationship:
>
> Domain-1 --> Domain-2
>
>
> - o Constraints - Constraints are used to define power levels for performance
> + - Constraints
> + - Constraints are used to define power levels for performance
> and hardware protection. Constraints exist at three levels:
>
> Regulator Level: This is defined by the regulator hardware
> @@ -141,7 +148,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
> limit. This also compiles out if not in use so drivers can be reused in
> systems with no regulator based power control.
>
> - See Documentation/power/regulator/consumer.txt
> + See Documentation/power/regulator/consumer.rst
>
> 2. Regulator driver interface.
>
> @@ -149,7 +156,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
> operations to the core. It also has a notifier call chain for propagating
> regulator events to clients.
>
> - See Documentation/power/regulator/regulator.txt
> + See Documentation/power/regulator/regulator.rst
>
> 3. Machine interface.
>
> @@ -160,7 +167,7 @@ relevant to non SoC devices and is split into the following four interfaces:-
> allows the creation of a regulator tree whereby some regulators are
> supplied by others (similar to a clock tree).
>
> - See Documentation/power/regulator/machine.txt
> + See Documentation/power/regulator/machine.rst
>
> 4. Userspace ABI.
>
> diff --git a/Documentation/power/regulator/regulator.rst b/Documentation/power/regulator/regulator.rst
> new file mode 100644
> index 000000000000..794b3256fbb9
> --- /dev/null
> +++ b/Documentation/power/regulator/regulator.rst
> @@ -0,0 +1,32 @@
> +==========================
> +Regulator Driver Interface
> +==========================
> +
> +The regulator driver interface is relatively simple and designed to allow
> +regulator drivers to register their services with the core framework.
> +
> +
> +Registration
> +============
> +
> +Drivers can register a regulator by calling::
> +
> + struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
> + const struct regulator_config *config);
> +
> +This will register the regulator's capabilities and operations to the regulator
> +core.
> +
> +Regulators can be unregistered by calling::
> +
> + void regulator_unregister(struct regulator_dev *rdev);
> +
> +
> +Regulator Events
> +================
> +
> +Regulators can send events (e.g. overtemperature, undervoltage, etc) to
> +consumer drivers by calling::
> +
> + int regulator_notifier_call_chain(struct regulator_dev *rdev,
> + unsigned long event, void *data);
> diff --git a/Documentation/power/regulator/regulator.txt b/Documentation/power/regulator/regulator.txt
> deleted file mode 100644
> index b17e5833ce21..000000000000
> --- a/Documentation/power/regulator/regulator.txt
> +++ /dev/null
> @@ -1,30 +0,0 @@
> -Regulator Driver Interface
> -==========================
> -
> -The regulator driver interface is relatively simple and designed to allow
> -regulator drivers to register their services with the core framework.
> -
> -
> -Registration
> -============
> -
> -Drivers can register a regulator by calling :-
> -
> -struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
> - const struct regulator_config *config);
> -
> -This will register the regulator's capabilities and operations to the regulator
> -core.
> -
> -Regulators can be unregistered by calling :-
> -
> -void regulator_unregister(struct regulator_dev *rdev);
> -
> -
> -Regulator Events
> -================
> -Regulators can send events (e.g. overtemperature, undervoltage, etc) to
> -consumer drivers by calling :-
> -
> -int regulator_notifier_call_chain(struct regulator_dev *rdev,
> - unsigned long event, void *data);
> diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.rst
> similarity index 89%
> rename from Documentation/power/runtime_pm.txt
> rename to Documentation/power/runtime_pm.rst
> index 937e33c46211..2c2ec99b5088 100644
> --- a/Documentation/power/runtime_pm.txt
> +++ b/Documentation/power/runtime_pm.rst
> @@ -1,10 +1,15 @@
> +==================================================
> Runtime Power Management Framework for I/O Devices
> +==================================================
>
> (C) 2009-2011 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>, Novell Inc.
> +
> (C) 2010 Alan Stern <stern-nwvwT67g6+6dFdvTe/nMLpVzexx5G7lz@public.gmane.org>
> +
> (C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
>
> 1. Introduction
> +===============
>
> Support for runtime power management (runtime PM) of I/O devices is provided
> at the power management core (PM core) level by means of:
> @@ -33,16 +38,17 @@ fields of 'struct dev_pm_info' and the core helper functions provided for
> runtime PM are described below.
>
> 2. Device Runtime PM Callbacks
> +==============================
>
> -There are three device runtime PM callbacks defined in 'struct dev_pm_ops':
> +There are three device runtime PM callbacks defined in 'struct dev_pm_ops'::
>
> -struct dev_pm_ops {
> + struct dev_pm_ops {
> ...
> int (*runtime_suspend)(struct device *dev);
> int (*runtime_resume)(struct device *dev);
> int (*runtime_idle)(struct device *dev);
> ...
> -};
> + };
>
> The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks
> are executed by the PM core for the device's subsystem that may be either of
> @@ -112,7 +118,7 @@ low-power state during the execution of the suspend callback, it is expected
> that remote wakeup will be enabled for the device. Generally, remote wakeup
> should be enabled for all input devices put into low-power states at run time.
>
> -The subsystem-level resume callback, if present, is _entirely_ _responsible_ for
> +The subsystem-level resume callback, if present, is **entirely responsible** for
> handling the resume of the device as appropriate, which may, but need not
> include executing the device driver's own ->runtime_resume() callback (from the
> PM core's point of view it is not necessary to implement a ->runtime_resume()
> @@ -197,95 +203,96 @@ rules:
> except for scheduled autosuspends.
>
> 3. Runtime PM Device Fields
> +===========================
>
> The following device runtime PM fields are present in 'struct dev_pm_info', as
> defined in include/linux/pm.h:
>
> - struct timer_list suspend_timer;
> + `struct timer_list suspend_timer;`
> - timer used for scheduling (delayed) suspend and autosuspend requests
>
> - unsigned long timer_expires;
> + `unsigned long timer_expires;`
> - timer expiration time, in jiffies (if this is different from zero, the
> timer is running and will expire at that time, otherwise the timer is not
> running)
>
> - struct work_struct work;
> + `struct work_struct work;`
> - work structure used for queuing up requests (i.e. work items in pm_wq)
>
> - wait_queue_head_t wait_queue;
> + `wait_queue_head_t wait_queue;`
> - wait queue used if any of the helper functions needs to wait for another
> one to complete
>
> - spinlock_t lock;
> + `spinlock_t lock;`
> - lock used for synchronization
>
> - atomic_t usage_count;
> + `atomic_t usage_count;`
> - the usage counter of the device
>
> - atomic_t child_count;
> + `atomic_t child_count;`
> - the count of 'active' children of the device
>
> - unsigned int ignore_children;
> + `unsigned int ignore_children;`
> - if set, the value of child_count is ignored (but still updated)
>
> - unsigned int disable_depth;
> + `unsigned int disable_depth;`
> - used for disabling the helper functions (they work normally if this is
> equal to zero); the initial value of it is 1 (i.e. runtime PM is
> initially disabled for all devices)
>
> - int runtime_error;
> + `int runtime_error;`
> - if set, there was a fatal error (one of the callbacks returned error code
> as described in Section 2), so the helper functions will not work until
> this flag is cleared; this is the error code returned by the failing
> callback
>
> - unsigned int idle_notification;
> + `unsigned int idle_notification;`
> - if set, ->runtime_idle() is being executed
>
> - unsigned int request_pending;
> + `unsigned int request_pending;`
> - if set, there's a pending request (i.e. a work item queued up into pm_wq)
>
> - enum rpm_request request;
> + `enum rpm_request request;`
> - type of request that's pending (valid if request_pending is set)
>
> - unsigned int deferred_resume;
> + `unsigned int deferred_resume;`
> - set if ->runtime_resume() is about to be run while ->runtime_suspend() is
> being executed for that device and it is not practical to wait for the
> suspend to complete; means "start a resume as soon as you've suspended"
>
> - enum rpm_status runtime_status;
> + `enum rpm_status runtime_status;`
> - the runtime PM status of the device; this field's initial value is
> RPM_SUSPENDED, which means that each device is initially regarded by the
> PM core as 'suspended', regardless of its real hardware status
>
> - unsigned int runtime_auto;
> + `unsigned int runtime_auto;`
> - if set, indicates that the user space has allowed the device driver to
> power manage the device at run time via the /sys/devices/.../power/control
> - interface; it may only be modified with the help of the pm_runtime_allow()
> + `interface;` it may only be modified with the help of the pm_runtime_allow()
> and pm_runtime_forbid() helper functions
>
> - unsigned int no_callbacks;
> + `unsigned int no_callbacks;`
> - indicates that the device does not use the runtime PM callbacks (see
> Section 8); it may be modified only by the pm_runtime_no_callbacks()
> helper function
>
> - unsigned int irq_safe;
> + `unsigned int irq_safe;`
> - indicates that the ->runtime_suspend() and ->runtime_resume() callbacks
> will be invoked with the spinlock held and interrupts disabled
>
> - unsigned int use_autosuspend;
> + `unsigned int use_autosuspend;`
> - indicates that the device's driver supports delayed autosuspend (see
> Section 9); it may be modified only by the
> pm_runtime{_dont}_use_autosuspend() helper functions
>
> - unsigned int timer_autosuspends;
> + `unsigned int timer_autosuspends;`
> - indicates that the PM core should attempt to carry out an autosuspend
> when the timer expires rather than a normal suspend
>
> - int autosuspend_delay;
> + `int autosuspend_delay;`
> - the delay time (in milliseconds) to be used for autosuspend
>
> - unsigned long last_busy;
> + `unsigned long last_busy;`
> - the time (in jiffies) when the pm_runtime_mark_last_busy() helper
> function was last called for this device; used in calculating inactivity
> periods for autosuspend
> @@ -293,37 +300,38 @@ defined in include/linux/pm.h:
> All of the above fields are members of the 'power' member of 'struct device'.
>
> 4. Runtime PM Device Helper Functions
> +=====================================
>
> The following runtime PM helper functions are defined in
> drivers/base/power/runtime.c and include/linux/pm_runtime.h:
>
> - void pm_runtime_init(struct device *dev);
> + `void pm_runtime_init(struct device *dev);`
> - initialize the device runtime PM fields in 'struct dev_pm_info'
>
> - void pm_runtime_remove(struct device *dev);
> + `void pm_runtime_remove(struct device *dev);`
> - make sure that the runtime PM of the device will be disabled after
> removing the device from device hierarchy
>
> - int pm_runtime_idle(struct device *dev);
> + `int pm_runtime_idle(struct device *dev);`
> - execute the subsystem-level idle callback for the device; returns an
> error code on failure, where -EINPROGRESS means that ->runtime_idle() is
> already being executed; if there is no callback or the callback returns 0
> then run pm_runtime_autosuspend(dev) and return its result
>
> - int pm_runtime_suspend(struct device *dev);
> + `int pm_runtime_suspend(struct device *dev);`
> - execute the subsystem-level suspend callback for the device; returns 0 on
> success, 1 if the device's runtime PM status was already 'suspended', or
> error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt
> to suspend the device again in future and -EACCES means that
> 'power.disable_depth' is different from 0
>
> - int pm_runtime_autosuspend(struct device *dev);
> + `int pm_runtime_autosuspend(struct device *dev);`
> - same as pm_runtime_suspend() except that the autosuspend delay is taken
> - into account; if pm_runtime_autosuspend_expiration() says the delay has
> + `into account;` if pm_runtime_autosuspend_expiration() says the delay has
> not yet expired then an autosuspend is scheduled for the appropriate time
> and 0 is returned
>
> - int pm_runtime_resume(struct device *dev);
> + `int pm_runtime_resume(struct device *dev);`
> - execute the subsystem-level resume callback for the device; returns 0 on
> success, 1 if the device's runtime PM status was already 'active' or
> error code on failure, where -EAGAIN means it may be safe to attempt to
> @@ -331,17 +339,17 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
> checked additionally, and -EACCES means that 'power.disable_depth' is
> different from 0
>
> - int pm_request_idle(struct device *dev);
> + `int pm_request_idle(struct device *dev);`
> - submit a request to execute the subsystem-level idle callback for the
> device (the request is represented by a work item in pm_wq); returns 0 on
> success or error code if the request has not been queued up
>
> - int pm_request_autosuspend(struct device *dev);
> + `int pm_request_autosuspend(struct device *dev);`
> - schedule the execution of the subsystem-level suspend callback for the
> device when the autosuspend delay has expired; if the delay has already
> expired then the work item is queued up immediately
>
> - int pm_schedule_suspend(struct device *dev, unsigned int delay);
> + `int pm_schedule_suspend(struct device *dev, unsigned int delay);`
> - schedule the execution of the subsystem-level suspend callback for the
> device in future, where 'delay' is the time to wait before queuing up a
> suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work
> @@ -351,58 +359,58 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
> ->runtime_suspend() is already scheduled and not yet expired, the new
> value of 'delay' will be used as the time to wait
>
> - int pm_request_resume(struct device *dev);
> + `int pm_request_resume(struct device *dev);`
> - submit a request to execute the subsystem-level resume callback for the
> device (the request is represented by a work item in pm_wq); returns 0 on
> success, 1 if the device's runtime PM status was already 'active', or
> error code if the request hasn't been queued up
>
> - void pm_runtime_get_noresume(struct device *dev);
> + `void pm_runtime_get_noresume(struct device *dev);`
> - increment the device's usage counter
>
> - int pm_runtime_get(struct device *dev);
> + `int pm_runtime_get(struct device *dev);`
> - increment the device's usage counter, run pm_request_resume(dev) and
> return its result
>
> - int pm_runtime_get_sync(struct device *dev);
> + `int pm_runtime_get_sync(struct device *dev);`
> - increment the device's usage counter, run pm_runtime_resume(dev) and
> return its result
>
> - int pm_runtime_get_if_in_use(struct device *dev);
> + `int pm_runtime_get_if_in_use(struct device *dev);`
> - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
> runtime PM status is RPM_ACTIVE and the runtime PM usage counter is
> nonzero, increment the counter and return 1; otherwise return 0 without
> changing the counter
>
> - void pm_runtime_put_noidle(struct device *dev);
> + `void pm_runtime_put_noidle(struct device *dev);`
> - decrement the device's usage counter
>
> - int pm_runtime_put(struct device *dev);
> + `int pm_runtime_put(struct device *dev);`
> - decrement the device's usage counter; if the result is 0 then run
> pm_request_idle(dev) and return its result
>
> - int pm_runtime_put_autosuspend(struct device *dev);
> + `int pm_runtime_put_autosuspend(struct device *dev);`
> - decrement the device's usage counter; if the result is 0 then run
> pm_request_autosuspend(dev) and return its result
>
> - int pm_runtime_put_sync(struct device *dev);
> + `int pm_runtime_put_sync(struct device *dev);`
> - decrement the device's usage counter; if the result is 0 then run
> pm_runtime_idle(dev) and return its result
>
> - int pm_runtime_put_sync_suspend(struct device *dev);
> + `int pm_runtime_put_sync_suspend(struct device *dev);`
> - decrement the device's usage counter; if the result is 0 then run
> pm_runtime_suspend(dev) and return its result
>
> - int pm_runtime_put_sync_autosuspend(struct device *dev);
> + `int pm_runtime_put_sync_autosuspend(struct device *dev);`
> - decrement the device's usage counter; if the result is 0 then run
> pm_runtime_autosuspend(dev) and return its result
>
> - void pm_runtime_enable(struct device *dev);
> + `void pm_runtime_enable(struct device *dev);`
> - decrement the device's 'power.disable_depth' field; if that field is equal
> to zero, the runtime PM helper functions can execute subsystem-level
> callbacks described in Section 2 for the device
>
> - int pm_runtime_disable(struct device *dev);
> + `int pm_runtime_disable(struct device *dev);`
> - increment the device's 'power.disable_depth' field (if the value of that
> field was previously zero, this prevents subsystem-level runtime PM
> callbacks from being run for the device), make sure that all of the
> @@ -411,7 +419,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
> necessary to execute the subsystem-level resume callback for the device
> to satisfy that request, otherwise 0 is returned
>
> - int pm_runtime_barrier(struct device *dev);
> + `int pm_runtime_barrier(struct device *dev);`
> - check if there's a resume request pending for the device and resume it
> (synchronously) in that case, cancel any other pending runtime PM requests
> regarding it and wait for all runtime PM operations on it in progress to
> @@ -419,10 +427,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
> necessary to execute the subsystem-level resume callback for the device to
> satisfy that request, otherwise 0 is returned
>
> - void pm_suspend_ignore_children(struct device *dev, bool enable);
> + `void pm_suspend_ignore_children(struct device *dev, bool enable);`
> - set/unset the power.ignore_children flag of the device
>
> - int pm_runtime_set_active(struct device *dev);
> + `int pm_runtime_set_active(struct device *dev);`
> - clear the device's 'power.runtime_error' flag, set the device's runtime
> PM status to 'active' and update its parent's counter of 'active'
> children as appropriate (it is only valid to use this function if
> @@ -430,61 +438,61 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
> zero); it will fail and return error code if the device has a parent
> which is not active and the 'power.ignore_children' flag of which is unset
>
> - void pm_runtime_set_suspended(struct device *dev);
> + `void pm_runtime_set_suspended(struct device *dev);`
> - clear the device's 'power.runtime_error' flag, set the device's runtime
> PM status to 'suspended' and update its parent's counter of 'active'
> children as appropriate (it is only valid to use this function if
> 'power.runtime_error' is set or 'power.disable_depth' is greater than
> zero)
>
> - bool pm_runtime_active(struct device *dev);
> + `bool pm_runtime_active(struct device *dev);`
> - return true if the device's runtime PM status is 'active' or its
> 'power.disable_depth' field is not equal to zero, or false otherwise
>
> - bool pm_runtime_suspended(struct device *dev);
> + `bool pm_runtime_suspended(struct device *dev);`
> - return true if the device's runtime PM status is 'suspended' and its
> 'power.disable_depth' field is equal to zero, or false otherwise
>
> - bool pm_runtime_status_suspended(struct device *dev);
> + `bool pm_runtime_status_suspended(struct device *dev);`
> - return true if the device's runtime PM status is 'suspended'
>
> - void pm_runtime_allow(struct device *dev);
> + `void pm_runtime_allow(struct device *dev);`
> - set the power.runtime_auto flag for the device and decrease its usage
> counter (used by the /sys/devices/.../power/control interface to
> effectively allow the device to be power managed at run time)
>
> - void pm_runtime_forbid(struct device *dev);
> + `void pm_runtime_forbid(struct device *dev);`
> - unset the power.runtime_auto flag for the device and increase its usage
> counter (used by the /sys/devices/.../power/control interface to
> effectively prevent the device from being power managed at run time)
>
> - void pm_runtime_no_callbacks(struct device *dev);
> + `void pm_runtime_no_callbacks(struct device *dev);`
> - set the power.no_callbacks flag for the device and remove the runtime
> PM attributes from /sys/devices/.../power (or prevent them from being
> added when the device is registered)
>
> - void pm_runtime_irq_safe(struct device *dev);
> + `void pm_runtime_irq_safe(struct device *dev);`
> - set the power.irq_safe flag for the device, causing the runtime-PM
> callbacks to be invoked with interrupts off
>
> - bool pm_runtime_is_irq_safe(struct device *dev);
> + `bool pm_runtime_is_irq_safe(struct device *dev);`
> - return true if power.irq_safe flag was set for the device, causing
> the runtime-PM callbacks to be invoked with interrupts off
>
> - void pm_runtime_mark_last_busy(struct device *dev);
> + `void pm_runtime_mark_last_busy(struct device *dev);`
> - set the power.last_busy field to the current time
>
> - void pm_runtime_use_autosuspend(struct device *dev);
> + `void pm_runtime_use_autosuspend(struct device *dev);`
> - set the power.use_autosuspend flag, enabling autosuspend delays; call
> pm_runtime_get_sync if the flag was previously cleared and
> power.autosuspend_delay is negative
>
> - void pm_runtime_dont_use_autosuspend(struct device *dev);
> + `void pm_runtime_dont_use_autosuspend(struct device *dev);`
> - clear the power.use_autosuspend flag, disabling autosuspend delays;
> decrement the device's usage counter if the flag was previously set and
> power.autosuspend_delay is negative; call pm_runtime_idle
>
> - void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);
> + `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
> - set the power.autosuspend_delay value to 'delay' (expressed in
> milliseconds); if 'delay' is negative then runtime suspends are
> prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be
> @@ -493,7 +501,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
> changed to or from a negative value; if power.use_autosuspend is clear,
> pm_runtime_idle is called
>
> - unsigned long pm_runtime_autosuspend_expiration(struct device *dev);
> + `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
> - calculate the time when the current autosuspend delay period will expire,
> based on power.last_busy and power.autosuspend_delay; if the delay time
> is 1000 ms or larger then the expiration time is rounded up to the
> @@ -503,36 +511,37 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
>
> It is safe to execute the following helper functions from interrupt context:
>
> -pm_request_idle()
> -pm_request_autosuspend()
> -pm_schedule_suspend()
> -pm_request_resume()
> -pm_runtime_get_noresume()
> -pm_runtime_get()
> -pm_runtime_put_noidle()
> -pm_runtime_put()
> -pm_runtime_put_autosuspend()
> -pm_runtime_enable()
> -pm_suspend_ignore_children()
> -pm_runtime_set_active()
> -pm_runtime_set_suspended()
> -pm_runtime_suspended()
> -pm_runtime_mark_last_busy()
> -pm_runtime_autosuspend_expiration()
> +- pm_request_idle()
> +- pm_request_autosuspend()
> +- pm_schedule_suspend()
> +- pm_request_resume()
> +- pm_runtime_get_noresume()
> +- pm_runtime_get()
> +- pm_runtime_put_noidle()
> +- pm_runtime_put()
> +- pm_runtime_put_autosuspend()
> +- pm_runtime_enable()
> +- pm_suspend_ignore_children()
> +- pm_runtime_set_active()
> +- pm_runtime_set_suspended()
> +- pm_runtime_suspended()
> +- pm_runtime_mark_last_busy()
> +- pm_runtime_autosuspend_expiration()
>
> If pm_runtime_irq_safe() has been called for a device then the following helper
> functions may also be used in interrupt context:
>
> -pm_runtime_idle()
> -pm_runtime_suspend()
> -pm_runtime_autosuspend()
> -pm_runtime_resume()
> -pm_runtime_get_sync()
> -pm_runtime_put_sync()
> -pm_runtime_put_sync_suspend()
> -pm_runtime_put_sync_autosuspend()
> +- pm_runtime_idle()
> +- pm_runtime_suspend()
> +- pm_runtime_autosuspend()
> +- pm_runtime_resume()
> +- pm_runtime_get_sync()
> +- pm_runtime_put_sync()
> +- pm_runtime_put_sync_suspend()
> +- pm_runtime_put_sync_autosuspend()
>
> 5. Runtime PM Initialization, Device Probing and Removal
> +========================================================
>
> Initially, the runtime PM is disabled for all devices, which means that the
> majority of the runtime PM helper functions described in Section 4 will return
> @@ -608,6 +617,7 @@ manage the device at run time, the driver may confuse it by using
> pm_runtime_forbid() this way.
>
> 6. Runtime PM and System Sleep
> +==============================
>
> Runtime PM and system sleep (i.e., system suspend and hibernation, also known
> as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of
> @@ -647,9 +657,9 @@ brought back to full power during resume, then its runtime PM status will have
> to be updated to reflect the actual post-system sleep status. The way to do
> this is:
>
> - pm_runtime_disable(dev);
> - pm_runtime_set_active(dev);
> - pm_runtime_enable(dev);
> + - pm_runtime_disable(dev);
> + - pm_runtime_set_active(dev);
> + - pm_runtime_enable(dev);
>
> The PM core always increments the runtime usage counter before calling the
> ->suspend() callback and decrements it after calling the ->resume() callback.
> @@ -705,66 +715,66 @@ Subsystems may wish to conserve code space by using the set of generic power
> management callbacks provided by the PM core, defined in
> driver/base/power/generic_ops.c:
>
> - int pm_generic_runtime_suspend(struct device *dev);
> + `int pm_generic_runtime_suspend(struct device *dev);`
> - invoke the ->runtime_suspend() callback provided by the driver of this
> device and return its result, or return 0 if not defined
>
> - int pm_generic_runtime_resume(struct device *dev);
> + `int pm_generic_runtime_resume(struct device *dev);`
> - invoke the ->runtime_resume() callback provided by the driver of this
> device and return its result, or return 0 if not defined
>
> - int pm_generic_suspend(struct device *dev);
> + `int pm_generic_suspend(struct device *dev);`
> - if the device has not been suspended at run time, invoke the ->suspend()
> callback provided by its driver and return its result, or return 0 if not
> defined
>
> - int pm_generic_suspend_noirq(struct device *dev);
> + `int pm_generic_suspend_noirq(struct device *dev);`
> - if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq()
> callback provided by the device's driver and return its result, or return
> 0 if not defined
>
> - int pm_generic_resume(struct device *dev);
> + `int pm_generic_resume(struct device *dev);`
> - invoke the ->resume() callback provided by the driver of this device and,
> if successful, change the device's runtime PM status to 'active'
>
> - int pm_generic_resume_noirq(struct device *dev);
> + `int pm_generic_resume_noirq(struct device *dev);`
> - invoke the ->resume_noirq() callback provided by the driver of this device
>
> - int pm_generic_freeze(struct device *dev);
> + `int pm_generic_freeze(struct device *dev);`
> - if the device has not been suspended at run time, invoke the ->freeze()
> callback provided by its driver and return its result, or return 0 if not
> defined
>
> - int pm_generic_freeze_noirq(struct device *dev);
> + `int pm_generic_freeze_noirq(struct device *dev);`
> - if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq()
> callback provided by the device's driver and return its result, or return
> 0 if not defined
>
> - int pm_generic_thaw(struct device *dev);
> + `int pm_generic_thaw(struct device *dev);`
> - if the device has not been suspended at run time, invoke the ->thaw()
> callback provided by its driver and return its result, or return 0 if not
> defined
>
> - int pm_generic_thaw_noirq(struct device *dev);
> + `int pm_generic_thaw_noirq(struct device *dev);`
> - if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq()
> callback provided by the device's driver and return its result, or return
> 0 if not defined
>
> - int pm_generic_poweroff(struct device *dev);
> + `int pm_generic_poweroff(struct device *dev);`
> - if the device has not been suspended at run time, invoke the ->poweroff()
> callback provided by its driver and return its result, or return 0 if not
> defined
>
> - int pm_generic_poweroff_noirq(struct device *dev);
> + `int pm_generic_poweroff_noirq(struct device *dev);`
> - if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq()
> callback provided by the device's driver and return its result, or return
> 0 if not defined
>
> - int pm_generic_restore(struct device *dev);
> + `int pm_generic_restore(struct device *dev);`
> - invoke the ->restore() callback provided by the driver of this device and,
> if successful, change the device's runtime PM status to 'active'
>
> - int pm_generic_restore_noirq(struct device *dev);
> + `int pm_generic_restore_noirq(struct device *dev);`
> - invoke the ->restore_noirq() callback provided by the device's driver
>
> These functions are the defaults used by the PM core, if a subsystem doesn't
> @@ -781,6 +791,7 @@ UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its
> last argument to NULL).
>
> 8. "No-Callback" Devices
> +========================
>
> Some "devices" are only logical sub-devices of their parent and cannot be
> power-managed on their own. (The prototype example is a USB interface. Entire
> @@ -807,6 +818,7 @@ parent must take responsibility for telling the device's driver when the
> parent's power state changes.
>
> 9. Autosuspend, or automatically-delayed suspends
> +=================================================
>
> Changing a device's power state isn't free; it requires both time and energy.
> A device should be put in a low-power state only when there's some reason to
> @@ -832,8 +844,8 @@ registration the length should be controlled by user space, using the
>
> In order to use autosuspend, subsystems or drivers must call
> pm_runtime_use_autosuspend() (preferably before registering the device), and
> -thereafter they should use the various *_autosuspend() helper functions instead
> -of the non-autosuspend counterparts:
> +thereafter they should use the various `*_autosuspend()` helper functions
> +instead of the non-autosuspend counterparts::
>
> Instead of: pm_runtime_suspend use: pm_runtime_autosuspend;
> Instead of: pm_schedule_suspend use: pm_request_autosuspend;
> @@ -858,7 +870,7 @@ The implementation is well suited for asynchronous use in interrupt contexts.
> However such use inevitably involves races, because the PM core can't
> synchronize ->runtime_suspend() callbacks with the arrival of I/O requests.
> This synchronization must be handled by the driver, using its private lock.
> -Here is a schematic pseudo-code example:
> +Here is a schematic pseudo-code example::
>
> foo_read_or_write(struct foo_priv *foo, void *data)
> {
> diff --git a/Documentation/power/s2ram.txt b/Documentation/power/s2ram.rst
> similarity index 92%
> rename from Documentation/power/s2ram.txt
> rename to Documentation/power/s2ram.rst
> index 4685aee197fd..d739aa7c742c 100644
> --- a/Documentation/power/s2ram.txt
> +++ b/Documentation/power/s2ram.rst
> @@ -1,7 +1,9 @@
> - How to get s2ram working
> - ~~~~~~~~~~~~~~~~~~~~~~~~
> - 2006 Linus Torvalds
> - 2006 Pavel Machek
> +========================
> +How to get s2ram working
> +========================
> +
> +2006 Linus Torvalds
> +2006 Pavel Machek
>
> 1) Check suspend.sf.net, program s2ram there has long whitelist of
> "known ok" machines, along with tricks to use on each one.
> @@ -12,8 +14,8 @@
>
> 3) You can use Linus' TRACE_RESUME infrastructure, described below.
>
> - Using TRACE_RESUME
> - ~~~~~~~~~~~~~~~~~~
> +Using TRACE_RESUME
> +~~~~~~~~~~~~~~~~~~
>
> I've been working at making the machines I have able to STR, and almost
> always it's a driver that is buggy. Thank God for the suspend/resume
> @@ -27,7 +29,7 @@ machine that doesn't boot) is:
>
> - enable PM_DEBUG, and PM_TRACE
>
> - - use a script like this:
> + - use a script like this::
>
> #!/bin/sh
> sync
> @@ -38,7 +40,7 @@ machine that doesn't boot) is:
>
> - if it doesn't come back up (which is usually the problem), reboot by
> holding the power button down, and look at the dmesg output for things
> - like
> + like::
>
> Magic number: 4:156:725
> hash matches drivers/base/power/resume.c:28
> @@ -52,7 +54,7 @@ machine that doesn't boot) is:
> If no device matches the hash (or any matches appear to be false positives),
> the culprit may be a device from a loadable kernel module that is not loaded
> until after the hash is checked. You can check the hash against the current
> - devices again after more modules are loaded using sysfs:
> + devices again after more modules are loaded using sysfs::
>
> cat /sys/power/pm_trace_dev_match
>
> diff --git a/Documentation/power/suspend-and-cpuhotplug.txt b/Documentation/power/suspend-and-cpuhotplug.rst
> similarity index 90%
> rename from Documentation/power/suspend-and-cpuhotplug.txt
> rename to Documentation/power/suspend-and-cpuhotplug.rst
> index a8751b8df10e..9df664f5423a 100644
> --- a/Documentation/power/suspend-and-cpuhotplug.txt
> +++ b/Documentation/power/suspend-and-cpuhotplug.rst
> @@ -1,10 +1,15 @@
> +====================================================================
> Interaction of Suspend code (S3) with the CPU hotplug infrastructure
> +====================================================================
>
> - (C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat-23VcF4HTsmIX0ybBhKVfKdBPR1lH4CV8@public.gmane.org>
> +(C) 2011 - 2014 Srivatsa S. Bhat <srivatsa.bhat-23VcF4HTsmIX0ybBhKVfKdBPR1lH4CV8@public.gmane.org>
>
>
> -I. How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> - infrastructure uses it internally? And where do they share common code?
> +I. Differences between CPU hotplug and Suspend-to-RAM
> +======================================================
> +
> +How does the regular CPU hotplug code differ from how the Suspend-to-RAM
> +infrastructure uses it internally? And where do they share common code?
>
> Well, a picture is worth a thousand words... So ASCII art follows :-)
>
> @@ -16,13 +21,13 @@ of describing where they take different paths and where they share code.
> What happens when regular CPU hotplug and Suspend-to-RAM race with each other
> is not depicted here.]
>
> -On a high level, the suspend-resume cycle goes like this:
> +On a high level, the suspend-resume cycle goes like this::
>
> -|Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw |
> -|tasks | | cpus | | | | cpus | |tasks|
> + |Freeze| -> |Disable nonboot| -> |Do suspend| -> |Enable nonboot| -> |Thaw |
> + |tasks | | cpus | | | | cpus | |tasks|
>
>
> -More details follow:
> +More details follow::
>
> Suspend call path
> -----------------
> @@ -87,7 +92,9 @@ More details follow:
>
> Resuming back is likewise, with the counterparts being (in the order of
> execution during resume):
> -* enable_nonboot_cpus() which involves:
> +
> +* enable_nonboot_cpus() which involves::
> +
> | Acquire cpu_add_remove_lock
> | Decrease cpu_hotplug_disabled, thereby enabling regular cpu hotplug
> | Call _cpu_up() [for all those cpus in the frozen_cpus mask, in a loop]
> @@ -101,7 +108,7 @@ execution during resume):
>
> It is to be noted here that the system_transition_mutex lock is acquired at the very
> beginning, when we are just starting out to suspend, and then released only
> -after the entire cycle is complete (i.e., suspend + resume).
> +after the entire cycle is complete (i.e., suspend + resume)::
>
>
>
> @@ -152,16 +159,16 @@ with the 'tasks_frozen' argument set to 1.
>
>
> Important files and functions/entry points:
> -------------------------------------------
> +-------------------------------------------
>
> -kernel/power/process.c : freeze_processes(), thaw_processes()
> -kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish()
> -kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus()
> +- kernel/power/process.c : freeze_processes(), thaw_processes()
> +- kernel/power/suspend.c : suspend_prepare(), suspend_enter(), suspend_finish()
> +- kernel/cpu.c: cpu_[up|down](), _cpu_[up|down](), [disable|enable]_nonboot_cpus()
>
>
>
> II. What are the issues involved in CPU hotplug?
> - -------------------------------------------
> +------------------------------------------------
>
> There are some interesting situations involving CPU hotplug and microcode
> update on the CPUs, as discussed below:
> @@ -243,8 +250,11 @@ d. Handling microcode update during suspend/hibernate:
> cycles).
>
>
> -III. Are there any known problems when regular CPU hotplug and suspend race
> - with each other?
> +III. Known problems
> +===================
> +
> +Are there any known problems when regular CPU hotplug and suspend race
> +with each other?
>
> Yes, they are listed below:
>
> diff --git a/Documentation/power/suspend-and-interrupts.txt b/Documentation/power/suspend-and-interrupts.rst
> similarity index 98%
> rename from Documentation/power/suspend-and-interrupts.txt
> rename to Documentation/power/suspend-and-interrupts.rst
> index 8afb29a8604a..4cda6617709a 100644
> --- a/Documentation/power/suspend-and-interrupts.txt
> +++ b/Documentation/power/suspend-and-interrupts.rst
> @@ -1,4 +1,6 @@
> +====================================
> System Suspend and Device Interrupts
> +====================================
>
> Copyright (C) 2014 Intel Corp.
> Author: Rafael J. Wysocki <rafael.j.wysocki-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> diff --git a/Documentation/power/swsusp-and-swap-files.txt b/Documentation/power/swsusp-and-swap-files.rst
> similarity index 83%
> rename from Documentation/power/swsusp-and-swap-files.txt
> rename to Documentation/power/swsusp-and-swap-files.rst
> index f281886de490..a33a2919dbe4 100644
> --- a/Documentation/power/swsusp-and-swap-files.txt
> +++ b/Documentation/power/swsusp-and-swap-files.rst
> @@ -1,4 +1,7 @@
> +===============================================
> Using swap files with software suspend (swsusp)
> +===============================================
> +
> (C) 2006 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>
>
> The Linux kernel handles swap files almost in the same way as it handles swap
> @@ -21,20 +24,20 @@ units.
>
> In order to use a swap file with swsusp, you need to:
>
> -1) Create the swap file and make it active, eg.
> +1) Create the swap file and make it active, eg.::
>
> -# dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k>
> -# mkswap <swap_file_path>
> -# swapon <swap_file_path>
> + # dd if=/dev/zero of=<swap_file_path> bs=1024 count=<swap_file_size_in_k>
> + # mkswap <swap_file_path>
> + # swapon <swap_file_path>
>
> 2) Use an application that will bmap the swap file with the help of the
> FIBMAP ioctl and determine the location of the file's swap header, as the
> offset, in <PAGE_SIZE> units, from the beginning of the partition which
> holds the swap file.
>
> -3) Add the following parameters to the kernel command line:
> +3) Add the following parameters to the kernel command line::
>
> -resume=<swap_file_partition> resume_offset=<swap_file_offset>
> + resume=<swap_file_partition> resume_offset=<swap_file_offset>
>
> where <swap_file_partition> is the partition on which the swap file is located
> and <swap_file_offset> is the offset of the swap header determined by the
> @@ -46,7 +49,7 @@ OR
>
> Use a userland suspend application that will set the partition and offset
> with the help of the SNAPSHOT_SET_SWAP_AREA ioctl described in
> -Documentation/power/userland-swsusp.txt (this is the only method to suspend
> +Documentation/power/userland-swsusp.rst (this is the only method to suspend
> to a swap file allowing the resume to be initiated from an initrd or initramfs
> image).
>
> diff --git a/Documentation/power/swsusp-dmcrypt.txt b/Documentation/power/swsusp-dmcrypt.rst
> similarity index 67%
> rename from Documentation/power/swsusp-dmcrypt.txt
> rename to Documentation/power/swsusp-dmcrypt.rst
> index b802fbfd95ef..426df59172cd 100644
> --- a/Documentation/power/swsusp-dmcrypt.txt
> +++ b/Documentation/power/swsusp-dmcrypt.rst
> @@ -1,13 +1,15 @@
> +=======================================
> +How to use dm-crypt and swsusp together
> +=======================================
> +
> Author: Andreas Steinmetz <ast-sy9/ueDX/ME@public.gmane.org>
>
>
> -How to use dm-crypt and swsusp together:
> -========================================
>
> Some prerequisites:
> You know how dm-crypt works. If not, visit the following web page:
> http://www.saout.de/misc/dm-crypt/
> -You have read Documentation/power/swsusp.txt and understand it.
> +You have read Documentation/power/swsusp.rst and understand it.
> You did read Documentation/admin-guide/initrd.rst and know how an initrd works.
> You know how to create or how to modify an initrd.
>
> @@ -29,23 +31,23 @@ a way that the swap device you suspend to/resume from has
> always the same major/minor within the initrd as well as
> within your running system. The easiest way to achieve this is
> to always set up this swap device first with dmsetup, so that
> -it will always look like the following:
> +it will always look like the following::
>
> -brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
> + brw------- 1 root root 254, 0 Jul 28 13:37 /dev/mapper/swap0
>
> Now set up your kernel to use /dev/mapper/swap0 as the default
> -resume partition, so your kernel .config contains:
> +resume partition, so your kernel .config contains::
>
> -CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
> + CONFIG_PM_STD_PARTITION="/dev/mapper/swap0"
>
> Prepare your boot loader to use the initrd you will create or
> modify. For lilo the simplest setup looks like the following
> -lines:
> +lines::
>
> -image=/boot/vmlinuz
> -initrd=/boot/initrd.gz
> -label=linux
> -append="root=/dev/ram0 init=/linuxrc rw"
> + image=/boot/vmlinuz
> + initrd=/boot/initrd.gz
> + label=linux
> + append="root=/dev/ram0 init=/linuxrc rw"
>
> Finally you need to create or modify your initrd. Lets assume
> you create an initrd that reads the required dm-crypt setup
> @@ -53,66 +55,66 @@ from a pcmcia flash disk card. The card is formatted with an ext2
> fs which resides on /dev/hde1 when the card is inserted. The
> card contains at least the encrypted swap setup in a file
> named "swapkey". /etc/fstab of your initrd contains something
> -like the following:
> +like the following::
>
> -/dev/hda1 /mnt ext3 ro 0 0
> -none /proc proc defaults,noatime,nodiratime 0 0
> -none /sys sysfs defaults,noatime,nodiratime 0 0
> + /dev/hda1 /mnt ext3 ro 0 0
> + none /proc proc defaults,noatime,nodiratime 0 0
> + none /sys sysfs defaults,noatime,nodiratime 0 0
>
> /dev/hda1 contains an unencrypted mini system that sets up all
> of your crypto devices, again by reading the setup from the
> pcmcia flash disk. What follows now is a /linuxrc for your
> initrd that allows you to resume from encrypted swap and that
> continues boot with your mini system on /dev/hda1 if resume
> -does not happen:
> +does not happen::
>
> -#!/bin/sh
> -PATH=/sbin:/bin:/usr/sbin:/usr/bin
> -mount /proc
> -mount /sys
> -mapped=0
> -noresume=`grep -c noresume /proc/cmdline`
> -if [ "$*" != "" ]
> -then
> - noresume=1
> -fi
> -dmesg -n 1
> -/sbin/cardmgr -q
> -for i in 1 2 3 4 5 6 7 8 9 0
> -do
> - if [ -f /proc/ide/hde/media ]
> + #!/bin/sh
> + PATH=/sbin:/bin:/usr/sbin:/usr/bin
> + mount /proc
> + mount /sys
> + mapped=0
> + noresume=`grep -c noresume /proc/cmdline`
> + if [ "$*" != "" ]
> then
> + noresume=1
> + fi
> + dmesg -n 1
> + /sbin/cardmgr -q
> + for i in 1 2 3 4 5 6 7 8 9 0
> + do
> + if [ -f /proc/ide/hde/media ]
> + then
> + usleep 500000
> + mount -t ext2 -o ro /dev/hde1 /mnt
> + if [ -f /mnt/swapkey ]
> + then
> + dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
> + fi
> + umount /mnt
> + break
> + fi
> usleep 500000
> - mount -t ext2 -o ro /dev/hde1 /mnt
> - if [ -f /mnt/swapkey ]
> + done
> + killproc /sbin/cardmgr
> + dmesg -n 6
> + if [ $mapped = 1 ]
> + then
> + if [ $noresume != 0 ]
> then
> - dmsetup create swap0 /mnt/swapkey > /dev/null 2>&1 && mapped=1
> + mkswap /dev/mapper/swap0 > /dev/null 2>&1
> fi
> - umount /mnt
> - break
> + echo 254:0 > /sys/power/resume
> + dmsetup remove swap0
> fi
> - usleep 500000
> -done
> -killproc /sbin/cardmgr
> -dmesg -n 6
> -if [ $mapped = 1 ]
> -then
> - if [ $noresume != 0 ]
> - then
> - mkswap /dev/mapper/swap0 > /dev/null 2>&1
> - fi
> - echo 254:0 > /sys/power/resume
> - dmsetup remove swap0
> -fi
> -umount /sys
> -mount /mnt
> -umount /proc
> -cd /mnt
> -pivot_root . mnt
> -mount /proc
> -umount -l /mnt
> -umount /proc
> -exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
> + umount /sys
> + mount /mnt
> + umount /proc
> + cd /mnt
> + pivot_root . mnt
> + mount /proc
> + umount -l /mnt
> + umount /proc
> + exec chroot . /sbin/init $* < dev/console > dev/console 2>&1
>
> Please don't mind the weird loop above, busybox's msh doesn't know
> the let statement. Now, what is happening in the script?
> diff --git a/Documentation/power/swsusp.rst b/Documentation/power/swsusp.rst
> new file mode 100644
> index 000000000000..d000312f6965
> --- /dev/null
> +++ b/Documentation/power/swsusp.rst
> @@ -0,0 +1,501 @@
> +============
> +Swap suspend
> +============
> +
> +Some warnings, first.
> +
> +.. warning::
> +
> + **BIG FAT WARNING**
> +
> + If you touch anything on disk between suspend and resume...
> + ...kiss your data goodbye.
> +
> + If you do resume from initrd after your filesystems are mounted...
> + ...bye bye root partition.
> +
> + [this is actually same case as above]
> +
> + If you have unsupported ( ) devices using DMA, you may have some
> + problems. If your disk driver does not support suspend... (IDE does),
> + it may cause some problems, too. If you change kernel command line
> + between suspend and resume, it may do something wrong. If you change
> + your hardware while system is suspended... well, it was not good idea;
> + but it will probably only crash.
> +
> + ( ) suspend/resume support is needed to make it safe.
> +
> + If you have any filesystems on USB devices mounted before software suspend,
> + they won't be accessible after resume and you may lose data, as though
> + you have unplugged the USB devices with mounted filesystems on them;
> + see the FAQ below for details. (This is not true for more traditional
> + power states like "standby", which normally don't turn USB off.)
> +
> +Swap partition:
> + You need to append resume=/dev/your_swap_partition to kernel command
> + line or specify it using /sys/power/resume.
> +
> +Swap file:
> + If using a swapfile you can also specify a resume offset using
> + resume_offset=<number> on the kernel command line or specify it
> + in /sys/power/resume_offset.
> +
> +After preparing then you suspend by::
> +
> + echo shutdown > /sys/power/disk; echo disk > /sys/power/state
> +
> +- If you feel ACPI works pretty well on your system, you might try::
> +
> + echo platform > /sys/power/disk; echo disk > /sys/power/state
> +
> +- If you would like to write hibernation image to swap and then suspend
> + to RAM (provided your platform supports it), you can try::
> +
> + echo suspend > /sys/power/disk; echo disk > /sys/power/state
> +
> +- If you have SATA disks, you'll need recent kernels with SATA suspend
> + support. For suspend and resume to work, make sure your disk drivers
> + are built into kernel -- not modules. [There's way to make
> + suspend/resume with modular disk drivers, see FAQ, but you probably
> + should not do that.]
> +
> +If you want to limit the suspend image size to N bytes, do::
> +
> + echo N > /sys/power/image_size
> +
> +before suspend (it is limited to around 2/5 of available RAM by default).
> +
> +- The resume process checks for the presence of the resume device,
> + if found, it then checks the contents for the hibernation image signature.
> + If both are found, it resumes the hibernation image.
> +
> +- The resume process may be triggered in two ways:
> +
> + 1) During lateinit: If resume=/dev/your_swap_partition is specified on
> + the kernel command line, lateinit runs the resume process. If the
> + resume device has not been probed yet, the resume process fails and
> + bootup continues.
> + 2) Manually from an initrd or initramfs: May be run from
> + the init script by using the /sys/power/resume file. It is vital
> + that this be done prior to remounting any filesystems (even as
> + read-only) otherwise data may be corrupted.
> +
> +Article about goals and implementation of Software Suspend for Linux
> +====================================================================
> +
> +Author: Gábor Kuti
> +Last revised: 2003-10-20 by Pavel Machek
> +
> +Idea and goals to achieve
> +-------------------------
> +
> +Nowadays it is common in several laptops that they have a suspend button. It
> +saves the state of the machine to a filesystem or to a partition and switches
> +to standby mode. Later resuming the machine the saved state is loaded back to
> +ram and the machine can continue its work. It has two real benefits. First we
> +save ourselves the time machine goes down and later boots up, energy costs
> +are real high when running from batteries. The other gain is that we don't have
> +to interrupt our programs so processes that are calculating something for a long
> +time shouldn't need to be written interruptible.
> +
> +swsusp saves the state of the machine into active swaps and then reboots or
> +powerdowns. You must explicitly specify the swap partition to resume from with
> +`resume=` kernel option. If signature is found it loads and restores saved
> +state. If the option `noresume` is specified as a boot parameter, it skips
> +the resuming. If the option `hibernate=nocompress` is specified as a boot
> +parameter, it saves hibernation image without compression.
> +
> +In the meantime while the system is suspended you should not add/remove any
> +of the hardware, write to the filesystems, etc.
> +
> +Sleep states summary
> +====================
> +
> +There are three different interfaces you can use, /proc/acpi should
> +work like this:
> +
> +In a really perfect world::
> +
> + echo 1 > /proc/acpi/sleep # for standby
> + echo 2 > /proc/acpi/sleep # for suspend to ram
> + echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
> + echo 4 > /proc/acpi/sleep # for suspend to disk
> + echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
> +
> +and perhaps::
> +
> + echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
> +
> +Frequently Asked Questions
> +==========================
> +
> +Q:
> + well, suspending a server is IMHO a really stupid thing,
> + but... (Diego Zuccato):
> +
> +A:
> + You bought new UPS for your server. How do you install it without
> + bringing machine down? Suspend to disk, rearrange power cables,
> + resume.
> +
> + You have your server on UPS. Power died, and UPS is indicating 30
> + seconds to failure. What do you do? Suspend to disk.
> +
> +
> +Q:
> + Maybe I'm missing something, but why don't the regular I/O paths work?
> +
> +A:
> + We do use the regular I/O paths. However we cannot restore the data
> + to its original location as we load it. That would create an
> + inconsistent kernel state which would certainly result in an oops.
> + Instead, we load the image into unused memory and then atomically copy
> + it back to it original location. This implies, of course, a maximum
> + image size of half the amount of memory.
> +
> + There are two solutions to this:
> +
> + * require half of memory to be free during suspend. That way you can
> + read "new" data onto free spots, then cli and copy
> +
> + * assume we had special "polling" ide driver that only uses memory
> + between 0-640KB. That way, I'd have to make sure that 0-640KB is free
> + during suspending, but otherwise it would work...
> +
> + suspend2 shares this fundamental limitation, but does not include user
> + data and disk caches into "used memory" by saving them in
> + advance. That means that the limitation goes away in practice.
> +
> +Q:
> + Does linux support ACPI S4?
> +
> +A:
> + Yes. That's what echo platform > /sys/power/disk does.
> +
> +Q:
> + What is 'suspend2'?
> +
> +A:
> + suspend2 is 'Software Suspend 2', a forked implementation of
> + suspend-to-disk which is available as separate patches for 2.4 and 2.6
> + kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB
> + highmem and preemption. It also has a extensible architecture that
> + allows for arbitrary transformations on the image (compression,
> + encryption) and arbitrary backends for writing the image (eg to swap
> + or an NFS share[Work In Progress]). Questions regarding suspend2
> + should be sent to the mailing list available through the suspend2
> + website, and not to the Linux Kernel Mailing List. We are working
> + toward merging suspend2 into the mainline kernel.
> +
> +Q:
> + What is the freezing of tasks and why are we using it?
> +
> +A:
> + The freezing of tasks is a mechanism by which user space processes and some
> + kernel threads are controlled during hibernation or system-wide suspend (on some
> + architectures). See freezing-of-tasks.txt for details.
> +
> +Q:
> + What is the difference between "platform" and "shutdown"?
> +
> +A:
> + shutdown:
> + save state in linux, then tell bios to powerdown
> +
> + platform:
> + save state in linux, then tell bios to powerdown and blink
> + "suspended led"
> +
> + "platform" is actually right thing to do where supported, but
> + "shutdown" is most reliable (except on ACPI systems).
> +
> +Q:
> + I do not understand why you have such strong objections to idea of
> + selective suspend.
> +
> +A:
> + Do selective suspend during runtime power management, that's okay. But
> + it's useless for suspend-to-disk. (And I do not see how you could use
> + it for suspend-to-ram, I hope you do not want that).
> +
> + Lets see, so you suggest to
> +
> + * SUSPEND all but swap device and parents
> + * Snapshot
> + * Write image to disk
> + * SUSPEND swap device and parents
> + * Powerdown
> +
> + Oh no, that does not work, if swap device or its parents uses DMA,
> + you've corrupted data. You'd have to do
> +
> + * SUSPEND all but swap device and parents
> + * FREEZE swap device and parents
> + * Snapshot
> + * UNFREEZE swap device and parents
> + * Write
> + * SUSPEND swap device and parents
> +
> + Which means that you still need that FREEZE state, and you get more
> + complicated code. (And I have not yet introduce details like system
> + devices).
> +
> +Q:
> + There don't seem to be any generally useful behavioral
> + distinctions between SUSPEND and FREEZE.
> +
> +A:
> + Doing SUSPEND when you are asked to do FREEZE is always correct,
> + but it may be unnecessarily slow. If you want your driver to stay simple,
> + slowness may not matter to you. It can always be fixed later.
> +
> + For devices like disk it does matter, you do not want to spindown for
> + FREEZE.
> +
> +Q:
> + After resuming, system is paging heavily, leading to very bad interactivity.
> +
> +A:
> + Try running::
> +
> + cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file
> + do
> + test -f "$file" && cat "$file" > /dev/null
> + done
> +
> + after resume. swapoff -a; swapon -a may also be useful.
> +
> +Q:
> + What happens to devices during swsusp? They seem to be resumed
> + during system suspend?
> +
> +A:
> + That's correct. We need to resume them if we want to write image to
> + disk. Whole sequence goes like
> +
> + **Suspend part**
> +
> + running system, user asks for suspend-to-disk
> +
> + user processes are stopped
> +
> + suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
> + with state snapshot
> +
> + state snapshot: copy of whole used memory is taken with interrupts disabled
> +
> + resume(): devices are woken up so that we can write image to swap
> +
> + write image to swap
> +
> + suspend(PMSG_SUSPEND): suspend devices so that we can power off
> +
> + turn the power off
> +
> + **Resume part**
> +
> + (is actually pretty similar)
> +
> + running system, user asks for suspend-to-disk
> +
> + user processes are stopped (in common case there are none,
> + but with resume-from-initrd, no one knows)
> +
> + read image from disk
> +
> + suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
> + with image restoration
> +
> + image restoration: rewrite memory with image
> +
> + resume(): devices are woken up so that system can continue
> +
> + thaw all user processes
> +
> +Q:
> + What is this 'Encrypt suspend image' for?
> +
> +A:
> + First of all: it is not a replacement for dm-crypt encrypted swap.
> + It cannot protect your computer while it is suspended. Instead it does
> + protect from leaking sensitive data after resume from suspend.
> +
> + Think of the following: you suspend while an application is running
> + that keeps sensitive data in memory. The application itself prevents
> + the data from being swapped out. Suspend, however, must write these
> + data to swap to be able to resume later on. Without suspend encryption
> + your sensitive data are then stored in plaintext on disk. This means
> + that after resume your sensitive data are accessible to all
> + applications having direct access to the swap device which was used
> + for suspend. If you don't need swap after resume these data can remain
> + on disk virtually forever. Thus it can happen that your system gets
> + broken in weeks later and sensitive data which you thought were
> + encrypted and protected are retrieved and stolen from the swap device.
> + To prevent this situation you should use 'Encrypt suspend image'.
> +
> + During suspend a temporary key is created and this key is used to
> + encrypt the data written to disk. When, during resume, the data was
> + read back into memory the temporary key is destroyed which simply
> + means that all data written to disk during suspend are then
> + inaccessible so they can't be stolen later on. The only thing that
> + you must then take care of is that you call 'mkswap' for the swap
> + partition used for suspend as early as possible during regular
> + boot. This asserts that any temporary key from an oopsed suspend or
> + from a failed or aborted resume is erased from the swap device.
> +
> + As a rule of thumb use encrypted swap to protect your data while your
> + system is shut down or suspended. Additionally use the encrypted
> + suspend image to prevent sensitive data from being stolen after
> + resume.
> +
> +Q:
> + Can I suspend to a swap file?
> +
> +A:
> + Generally, yes, you can. However, it requires you to use the "resume=" and
> + "resume_offset=" kernel command line parameters, so the resume from a swap file
> + cannot be initiated from an initrd or initramfs image. See
> + swsusp-and-swap-files.txt for details.
> +
> +Q:
> + Is there a maximum system RAM size that is supported by swsusp?
> +
> +A:
> + It should work okay with highmem.
> +
> +Q:
> + Does swsusp (to disk) use only one swap partition or can it use
> + multiple swap partitions (aggregate them into one logical space)?
> +
> +A:
> + Only one swap partition, sorry.
> +
> +Q:
> + If my application(s) causes lots of memory & swap space to be used
> + (over half of the total system RAM), is it correct that it is likely
> + to be useless to try to suspend to disk while that app is running?
> +
> +A:
> + No, it should work okay, as long as your app does not mlock()
> + it. Just prepare big enough swap partition.
> +
> +Q:
> + What information is useful for debugging suspend-to-disk problems?
> +
> +A:
> + Well, last messages on the screen are always useful. If something
> + is broken, it is usually some kernel driver, therefore trying with as
> + little as possible modules loaded helps a lot. I also prefer people to
> + suspend from console, preferably without X running. Booting with
> + init=/bin/bash, then swapon and starting suspend sequence manually
> + usually does the trick. Then it is good idea to try with latest
> + vanilla kernel.
> +
> +Q:
> + How can distributions ship a swsusp-supporting kernel with modular
> + disk drivers (especially SATA)?
> +
> +A:
> + Well, it can be done, load the drivers, then do echo into
> + /sys/power/resume file from initrd. Be sure not to mount
> + anything, not even read-only mount, or you are going to lose your
> + data.
> +
> +Q:
> + How do I make suspend more verbose?
> +
> +A:
> + If you want to see any non-error kernel messages on the virtual
> + terminal the kernel switches to during suspend, you have to set the
> + kernel console loglevel to at least 4 (KERN_WARNING), for example by
> + doing::
> +
> + # save the old loglevel
> + read LOGLEVEL DUMMY < /proc/sys/kernel/printk
> + # set the loglevel so we see the progress bar.
> + # if the level is higher than needed, we leave it alone.
> + if [ $LOGLEVEL -lt 5 ]; then
> + echo 5 > /proc/sys/kernel/printk
> + fi
> +
> + IMG_SZ=0
> + read IMG_SZ < /sys/power/image_size
> + echo -n disk > /sys/power/state
> + RET=$?
> + #
> + # the logic here is:
> + # if image_size > 0 (without kernel support, IMG_SZ will be zero),
> + # then try again with image_size set to zero.
> + if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size
> + echo 0 > /sys/power/image_size
> + echo -n disk > /sys/power/state
> + RET=$?
> + fi
> +
> + # restore previous loglevel
> + echo $LOGLEVEL > /proc/sys/kernel/printk
> + exit $RET
> +
> +Q:
> + Is this true that if I have a mounted filesystem on a USB device and
> + I suspend to disk, I can lose data unless the filesystem has been mounted
> + with "sync"?
> +
> +A:
> + That's right ... if you disconnect that device, you may lose data.
> + In fact, even with "-o sync" you can lose data if your programs have
> + information in buffers they haven't written out to a disk you disconnect,
> + or if you disconnect before the device finished saving data you wrote.
> +
> + Software suspend normally powers down USB controllers, which is equivalent
> + to disconnecting all USB devices attached to your system.
> +
> + Your system might well support low-power modes for its USB controllers
> + while the system is asleep, maintaining the connection, using true sleep
> + modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the
> + /sys/power/state file; write "standby" or "mem".) We've not seen any
> + hardware that can use these modes through software suspend, although in
> + theory some systems might support "platform" modes that won't break the
> + USB connections.
> +
> + Remember that it's always a bad idea to unplug a disk drive containing a
> + mounted filesystem. That's true even when your system is asleep! The
> + safest thing is to unmount all filesystems on removable media (such USB,
> + Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
> + before suspending; then remount them after resuming.
> +
> + There is a work-around for this problem. For more information, see
> + Documentation/driver-api/usb/persist.rst.
> +
> +Q:
> + Can I suspend-to-disk using a swap partition under LVM?
> +
> +A:
> + Yes and No. You can suspend successfully, but the kernel will not be able
> + to resume on its own. You need an initramfs that can recognize the resume
> + situation, activate the logical volume containing the swap volume (but not
> + touch any filesystems!), and eventually call::
> +
> + echo -n "$major:$minor" > /sys/power/resume
> +
> + where $major and $minor are the respective major and minor device numbers of
> + the swap volume.
> +
> + uswsusp works with LVM, too. See http://suspend.sourceforge.net/
> +
> +Q:
> + I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were
> + compiled with the similar configuration files. Anyway I found that
> + suspend to disk (and resume) is much slower on 2.6.16 compared to
> + 2.6.15. Any idea for why that might happen or how can I speed it up?
> +
> +A:
> + This is because the size of the suspend image is now greater than
> + for 2.6.15 (by saving more data we can get more responsive system
> + after resume).
> +
> + There's the /sys/power/image_size knob that controls the size of the
> + image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as
> + root), the 2.6.15 behavior should be restored. If it is still too
> + slow, take a look at suspend.sf.net -- userland suspend is faster and
> + supports LZF compression to speed it up further.
> diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt
> deleted file mode 100644
> index 236d1fb13640..000000000000
> --- a/Documentation/power/swsusp.txt
> +++ /dev/null
> @@ -1,446 +0,0 @@
> -Some warnings, first.
> -
> - * BIG FAT WARNING *********************************************************
> - *
> - * If you touch anything on disk between suspend and resume...
> - * ...kiss your data goodbye.
> - *
> - * If you do resume from initrd after your filesystems are mounted...
> - * ...bye bye root partition.
> - * [this is actually same case as above]
> - *
> - * If you have unsupported (*) devices using DMA, you may have some
> - * problems. If your disk driver does not support suspend... (IDE does),
> - * it may cause some problems, too. If you change kernel command line
> - * between suspend and resume, it may do something wrong. If you change
> - * your hardware while system is suspended... well, it was not good idea;
> - * but it will probably only crash.
> - *
> - * (*) suspend/resume support is needed to make it safe.
> - *
> - * If you have any filesystems on USB devices mounted before software suspend,
> - * they won't be accessible after resume and you may lose data, as though
> - * you have unplugged the USB devices with mounted filesystems on them;
> - * see the FAQ below for details. (This is not true for more traditional
> - * power states like "standby", which normally don't turn USB off.)
> -
> -Swap partition:
> -You need to append resume=/dev/your_swap_partition to kernel command
> -line or specify it using /sys/power/resume.
> -
> -Swap file:
> -If using a swapfile you can also specify a resume offset using
> -resume_offset=<number> on the kernel command line or specify it
> -in /sys/power/resume_offset.
> -
> -After preparing then you suspend by
> -
> -echo shutdown > /sys/power/disk; echo disk > /sys/power/state
> -
> -. If you feel ACPI works pretty well on your system, you might try
> -
> -echo platform > /sys/power/disk; echo disk > /sys/power/state
> -
> -. If you would like to write hibernation image to swap and then suspend
> -to RAM (provided your platform supports it), you can try
> -
> -echo suspend > /sys/power/disk; echo disk > /sys/power/state
> -
> -. If you have SATA disks, you'll need recent kernels with SATA suspend
> -support. For suspend and resume to work, make sure your disk drivers
> -are built into kernel -- not modules. [There's way to make
> -suspend/resume with modular disk drivers, see FAQ, but you probably
> -should not do that.]
> -
> -If you want to limit the suspend image size to N bytes, do
> -
> -echo N > /sys/power/image_size
> -
> -before suspend (it is limited to around 2/5 of available RAM by default).
> -
> -. The resume process checks for the presence of the resume device,
> -if found, it then checks the contents for the hibernation image signature.
> -If both are found, it resumes the hibernation image.
> -
> -. The resume process may be triggered in two ways:
> - 1) During lateinit: If resume=/dev/your_swap_partition is specified on
> - the kernel command line, lateinit runs the resume process. If the
> - resume device has not been probed yet, the resume process fails and
> - bootup continues.
> - 2) Manually from an initrd or initramfs: May be run from
> - the init script by using the /sys/power/resume file. It is vital
> - that this be done prior to remounting any filesystems (even as
> - read-only) otherwise data may be corrupted.
> -
> -Article about goals and implementation of Software Suspend for Linux
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -Author: Gábor Kuti
> -Last revised: 2003-10-20 by Pavel Machek
> -
> -Idea and goals to achieve
> -
> -Nowadays it is common in several laptops that they have a suspend button. It
> -saves the state of the machine to a filesystem or to a partition and switches
> -to standby mode. Later resuming the machine the saved state is loaded back to
> -ram and the machine can continue its work. It has two real benefits. First we
> -save ourselves the time machine goes down and later boots up, energy costs
> -are real high when running from batteries. The other gain is that we don't have to
> -interrupt our programs so processes that are calculating something for a long
> -time shouldn't need to be written interruptible.
> -
> -swsusp saves the state of the machine into active swaps and then reboots or
> -powerdowns. You must explicitly specify the swap partition to resume from with
> -``resume='' kernel option. If signature is found it loads and restores saved
> -state. If the option ``noresume'' is specified as a boot parameter, it skips
> -the resuming. If the option ``hibernate=nocompress'' is specified as a boot
> -parameter, it saves hibernation image without compression.
> -
> -In the meantime while the system is suspended you should not add/remove any
> -of the hardware, write to the filesystems, etc.
> -
> -Sleep states summary
> -====================
> -
> -There are three different interfaces you can use, /proc/acpi should
> -work like this:
> -
> -In a really perfect world:
> -echo 1 > /proc/acpi/sleep # for standby
> -echo 2 > /proc/acpi/sleep # for suspend to ram
> -echo 3 > /proc/acpi/sleep # for suspend to ram, but with more power conservative
> -echo 4 > /proc/acpi/sleep # for suspend to disk
> -echo 5 > /proc/acpi/sleep # for shutdown unfriendly the system
> -
> -and perhaps
> -echo 4b > /proc/acpi/sleep # for suspend to disk via s4bios
> -
> -Frequently Asked Questions
> -==========================
> -
> -Q: well, suspending a server is IMHO a really stupid thing,
> -but... (Diego Zuccato):
> -
> -A: You bought new UPS for your server. How do you install it without
> -bringing machine down? Suspend to disk, rearrange power cables,
> -resume.
> -
> -You have your server on UPS. Power died, and UPS is indicating 30
> -seconds to failure. What do you do? Suspend to disk.
> -
> -
> -Q: Maybe I'm missing something, but why don't the regular I/O paths work?
> -
> -A: We do use the regular I/O paths. However we cannot restore the data
> -to its original location as we load it. That would create an
> -inconsistent kernel state which would certainly result in an oops.
> -Instead, we load the image into unused memory and then atomically copy
> -it back to it original location. This implies, of course, a maximum
> -image size of half the amount of memory.
> -
> -There are two solutions to this:
> -
> -* require half of memory to be free during suspend. That way you can
> -read "new" data onto free spots, then cli and copy
> -
> -* assume we had special "polling" ide driver that only uses memory
> -between 0-640KB. That way, I'd have to make sure that 0-640KB is free
> -during suspending, but otherwise it would work...
> -
> -suspend2 shares this fundamental limitation, but does not include user
> -data and disk caches into "used memory" by saving them in
> -advance. That means that the limitation goes away in practice.
> -
> -Q: Does linux support ACPI S4?
> -
> -A: Yes. That's what echo platform > /sys/power/disk does.
> -
> -Q: What is 'suspend2'?
> -
> -A: suspend2 is 'Software Suspend 2', a forked implementation of
> -suspend-to-disk which is available as separate patches for 2.4 and 2.6
> -kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB
> -highmem and preemption. It also has a extensible architecture that
> -allows for arbitrary transformations on the image (compression,
> -encryption) and arbitrary backends for writing the image (eg to swap
> -or an NFS share[Work In Progress]). Questions regarding suspend2
> -should be sent to the mailing list available through the suspend2
> -website, and not to the Linux Kernel Mailing List. We are working
> -toward merging suspend2 into the mainline kernel.
> -
> -Q: What is the freezing of tasks and why are we using it?
> -
> -A: The freezing of tasks is a mechanism by which user space processes and some
> -kernel threads are controlled during hibernation or system-wide suspend (on some
> -architectures). See freezing-of-tasks.txt for details.
> -
> -Q: What is the difference between "platform" and "shutdown"?
> -
> -A:
> -
> -shutdown: save state in linux, then tell bios to powerdown
> -
> -platform: save state in linux, then tell bios to powerdown and blink
> - "suspended led"
> -
> -"platform" is actually right thing to do where supported, but
> -"shutdown" is most reliable (except on ACPI systems).
> -
> -Q: I do not understand why you have such strong objections to idea of
> -selective suspend.
> -
> -A: Do selective suspend during runtime power management, that's okay. But
> -it's useless for suspend-to-disk. (And I do not see how you could use
> -it for suspend-to-ram, I hope you do not want that).
> -
> -Lets see, so you suggest to
> -
> -* SUSPEND all but swap device and parents
> -* Snapshot
> -* Write image to disk
> -* SUSPEND swap device and parents
> -* Powerdown
> -
> -Oh no, that does not work, if swap device or its parents uses DMA,
> -you've corrupted data. You'd have to do
> -
> -* SUSPEND all but swap device and parents
> -* FREEZE swap device and parents
> -* Snapshot
> -* UNFREEZE swap device and parents
> -* Write
> -* SUSPEND swap device and parents
> -
> -Which means that you still need that FREEZE state, and you get more
> -complicated code. (And I have not yet introduce details like system
> -devices).
> -
> -Q: There don't seem to be any generally useful behavioral
> -distinctions between SUSPEND and FREEZE.
> -
> -A: Doing SUSPEND when you are asked to do FREEZE is always correct,
> -but it may be unnecessarily slow. If you want your driver to stay simple,
> -slowness may not matter to you. It can always be fixed later.
> -
> -For devices like disk it does matter, you do not want to spindown for
> -FREEZE.
> -
> -Q: After resuming, system is paging heavily, leading to very bad interactivity.
> -
> -A: Try running
> -
> -cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u | while read file
> -do
> - test -f "$file" && cat "$file" > /dev/null
> -done
> -
> -after resume. swapoff -a; swapon -a may also be useful.
> -
> -Q: What happens to devices during swsusp? They seem to be resumed
> -during system suspend?
> -
> -A: That's correct. We need to resume them if we want to write image to
> -disk. Whole sequence goes like
> -
> - Suspend part
> - ~~~~~~~~~~~~
> - running system, user asks for suspend-to-disk
> -
> - user processes are stopped
> -
> - suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
> - with state snapshot
> -
> - state snapshot: copy of whole used memory is taken with interrupts disabled
> -
> - resume(): devices are woken up so that we can write image to swap
> -
> - write image to swap
> -
> - suspend(PMSG_SUSPEND): suspend devices so that we can power off
> -
> - turn the power off
> -
> - Resume part
> - ~~~~~~~~~~~
> - (is actually pretty similar)
> -
> - running system, user asks for suspend-to-disk
> -
> - user processes are stopped (in common case there are none, but with resume-from-initrd, no one knows)
> -
> - read image from disk
> -
> - suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
> - with image restoration
> -
> - image restoration: rewrite memory with image
> -
> - resume(): devices are woken up so that system can continue
> -
> - thaw all user processes
> -
> -Q: What is this 'Encrypt suspend image' for?
> -
> -A: First of all: it is not a replacement for dm-crypt encrypted swap.
> -It cannot protect your computer while it is suspended. Instead it does
> -protect from leaking sensitive data after resume from suspend.
> -
> -Think of the following: you suspend while an application is running
> -that keeps sensitive data in memory. The application itself prevents
> -the data from being swapped out. Suspend, however, must write these
> -data to swap to be able to resume later on. Without suspend encryption
> -your sensitive data are then stored in plaintext on disk. This means
> -that after resume your sensitive data are accessible to all
> -applications having direct access to the swap device which was used
> -for suspend. If you don't need swap after resume these data can remain
> -on disk virtually forever. Thus it can happen that your system gets
> -broken in weeks later and sensitive data which you thought were
> -encrypted and protected are retrieved and stolen from the swap device.
> -To prevent this situation you should use 'Encrypt suspend image'.
> -
> -During suspend a temporary key is created and this key is used to
> -encrypt the data written to disk. When, during resume, the data was
> -read back into memory the temporary key is destroyed which simply
> -means that all data written to disk during suspend are then
> -inaccessible so they can't be stolen later on. The only thing that
> -you must then take care of is that you call 'mkswap' for the swap
> -partition used for suspend as early as possible during regular
> -boot. This asserts that any temporary key from an oopsed suspend or
> -from a failed or aborted resume is erased from the swap device.
> -
> -As a rule of thumb use encrypted swap to protect your data while your
> -system is shut down or suspended. Additionally use the encrypted
> -suspend image to prevent sensitive data from being stolen after
> -resume.
> -
> -Q: Can I suspend to a swap file?
> -
> -A: Generally, yes, you can. However, it requires you to use the "resume=" and
> -"resume_offset=" kernel command line parameters, so the resume from a swap file
> -cannot be initiated from an initrd or initramfs image. See
> -swsusp-and-swap-files.txt for details.
> -
> -Q: Is there a maximum system RAM size that is supported by swsusp?
> -
> -A: It should work okay with highmem.
> -
> -Q: Does swsusp (to disk) use only one swap partition or can it use
> -multiple swap partitions (aggregate them into one logical space)?
> -
> -A: Only one swap partition, sorry.
> -
> -Q: If my application(s) causes lots of memory & swap space to be used
> -(over half of the total system RAM), is it correct that it is likely
> -to be useless to try to suspend to disk while that app is running?
> -
> -A: No, it should work okay, as long as your app does not mlock()
> -it. Just prepare big enough swap partition.
> -
> -Q: What information is useful for debugging suspend-to-disk problems?
> -
> -A: Well, last messages on the screen are always useful. If something
> -is broken, it is usually some kernel driver, therefore trying with as
> -little as possible modules loaded helps a lot. I also prefer people to
> -suspend from console, preferably without X running. Booting with
> -init=/bin/bash, then swapon and starting suspend sequence manually
> -usually does the trick. Then it is good idea to try with latest
> -vanilla kernel.
> -
> -Q: How can distributions ship a swsusp-supporting kernel with modular
> -disk drivers (especially SATA)?
> -
> -A: Well, it can be done, load the drivers, then do echo into
> -/sys/power/resume file from initrd. Be sure not to mount
> -anything, not even read-only mount, or you are going to lose your
> -data.
> -
> -Q: How do I make suspend more verbose?
> -
> -A: If you want to see any non-error kernel messages on the virtual
> -terminal the kernel switches to during suspend, you have to set the
> -kernel console loglevel to at least 4 (KERN_WARNING), for example by
> -doing
> -
> - # save the old loglevel
> - read LOGLEVEL DUMMY < /proc/sys/kernel/printk
> - # set the loglevel so we see the progress bar.
> - # if the level is higher than needed, we leave it alone.
> - if [ $LOGLEVEL -lt 5 ]; then
> - echo 5 > /proc/sys/kernel/printk
> - fi
> -
> - IMG_SZ=0
> - read IMG_SZ < /sys/power/image_size
> - echo -n disk > /sys/power/state
> - RET=$?
> - #
> - # the logic here is:
> - # if image_size > 0 (without kernel support, IMG_SZ will be zero),
> - # then try again with image_size set to zero.
> - if [ $RET -ne 0 -a $IMG_SZ -ne 0 ]; then # try again with minimal image size
> - echo 0 > /sys/power/image_size
> - echo -n disk > /sys/power/state
> - RET=$?
> - fi
> -
> - # restore previous loglevel
> - echo $LOGLEVEL > /proc/sys/kernel/printk
> - exit $RET
> -
> -Q: Is this true that if I have a mounted filesystem on a USB device and
> -I suspend to disk, I can lose data unless the filesystem has been mounted
> -with "sync"?
> -
> -A: That's right ... if you disconnect that device, you may lose data.
> -In fact, even with "-o sync" you can lose data if your programs have
> -information in buffers they haven't written out to a disk you disconnect,
> -or if you disconnect before the device finished saving data you wrote.
> -
> -Software suspend normally powers down USB controllers, which is equivalent
> -to disconnecting all USB devices attached to your system.
> -
> -Your system might well support low-power modes for its USB controllers
> -while the system is asleep, maintaining the connection, using true sleep
> -modes like "suspend-to-RAM" or "standby". (Don't write "disk" to the
> -/sys/power/state file; write "standby" or "mem".) We've not seen any
> -hardware that can use these modes through software suspend, although in
> -theory some systems might support "platform" modes that won't break the
> -USB connections.
> -
> -Remember that it's always a bad idea to unplug a disk drive containing a
> -mounted filesystem. That's true even when your system is asleep! The
> -safest thing is to unmount all filesystems on removable media (such USB,
> -Firewire, CompactFlash, MMC, external SATA, or even IDE hotplug bays)
> -before suspending; then remount them after resuming.
> -
> -There is a work-around for this problem. For more information, see
> -Documentation/driver-api/usb/persist.rst.
> -
> -Q: Can I suspend-to-disk using a swap partition under LVM?
> -
> -A: Yes and No. You can suspend successfully, but the kernel will not be able
> -to resume on its own. You need an initramfs that can recognize the resume
> -situation, activate the logical volume containing the swap volume (but not
> -touch any filesystems!), and eventually call
> -
> -echo -n "$major:$minor" > /sys/power/resume
> -
> -where $major and $minor are the respective major and minor device numbers of
> -the swap volume.
> -
> -uswsusp works with LVM, too. See http://suspend.sourceforge.net/
> -
> -Q: I upgraded the kernel from 2.6.15 to 2.6.16. Both kernels were
> -compiled with the similar configuration files. Anyway I found that
> -suspend to disk (and resume) is much slower on 2.6.16 compared to
> -2.6.15. Any idea for why that might happen or how can I speed it up?
> -
> -A: This is because the size of the suspend image is now greater than
> -for 2.6.15 (by saving more data we can get more responsive system
> -after resume).
> -
> -There's the /sys/power/image_size knob that controls the size of the
> -image. If you set it to 0 (eg. by echo 0 > /sys/power/image_size as
> -root), the 2.6.15 behavior should be restored. If it is still too
> -slow, take a look at suspend.sf.net -- userland suspend is faster and
> -supports LZF compression to speed it up further.
> diff --git a/Documentation/power/tricks.txt b/Documentation/power/tricks.rst
> similarity index 93%
> rename from Documentation/power/tricks.txt
> rename to Documentation/power/tricks.rst
> index a1b8f7249f4c..ca787f142c3f 100644
> --- a/Documentation/power/tricks.txt
> +++ b/Documentation/power/tricks.rst
> @@ -1,5 +1,7 @@
> - swsusp/S3 tricks
> - ~~~~~~~~~~~~~~~~
> +================
> +swsusp/S3 tricks
> +================
> +
> Pavel Machek <pavel-+ZI9xUNit7I@public.gmane.org>
>
> If you want to trick swsusp/S3 into working, you might want to try:
> diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.rst
> similarity index 85%
> rename from Documentation/power/userland-swsusp.txt
> rename to Documentation/power/userland-swsusp.rst
> index bbfcd1bbedc5..a0fa51bb1a4d 100644
> --- a/Documentation/power/userland-swsusp.txt
> +++ b/Documentation/power/userland-swsusp.rst
> @@ -1,4 +1,7 @@
> +=====================================================
> Documentation for userland software suspend interface
> +=====================================================
> +
> (C) 2006 Rafael J. Wysocki <rjw-KKrjLPT3xs0@public.gmane.org>
>
> First, the warnings at the beginning of swsusp.txt still apply.
> @@ -30,13 +33,16 @@ called.
>
> The ioctl() commands recognized by the device are:
>
> -SNAPSHOT_FREEZE - freeze user space processes (the current process is
> +SNAPSHOT_FREEZE
> + freeze user space processes (the current process is
> not frozen); this is required for SNAPSHOT_CREATE_IMAGE
> and SNAPSHOT_ATOMIC_RESTORE to succeed
>
> -SNAPSHOT_UNFREEZE - thaw user space processes frozen by SNAPSHOT_FREEZE
> +SNAPSHOT_UNFREEZE
> + thaw user space processes frozen by SNAPSHOT_FREEZE
>
> -SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
> +SNAPSHOT_CREATE_IMAGE
> + create a snapshot of the system memory; the
> last argument of ioctl() should be a pointer to an int variable,
> the value of which will indicate whether the call returned after
> creating the snapshot (1) or after restoring the system memory state
> @@ -45,48 +51,59 @@ SNAPSHOT_CREATE_IMAGE - create a snapshot of the system memory; the
> has been created the read() operation can be used to transfer
> it out of the kernel
>
> -SNAPSHOT_ATOMIC_RESTORE - restore the system memory state from the
> +SNAPSHOT_ATOMIC_RESTORE
> + restore the system memory state from the
> uploaded snapshot image; before calling it you should transfer
> the system memory snapshot back to the kernel using the write()
> operation; this call will not succeed if the snapshot
> image is not available to the kernel
>
> -SNAPSHOT_FREE - free memory allocated for the snapshot image
> +SNAPSHOT_FREE
> + free memory allocated for the snapshot image
>
> -SNAPSHOT_PREF_IMAGE_SIZE - set the preferred maximum size of the image
> +SNAPSHOT_PREF_IMAGE_SIZE
> + set the preferred maximum size of the image
> (the kernel will do its best to ensure the image size will not exceed
> this number, but if it turns out to be impossible, the kernel will
> create the smallest image possible)
>
> -SNAPSHOT_GET_IMAGE_SIZE - return the actual size of the hibernation image
> +SNAPSHOT_GET_IMAGE_SIZE
> + return the actual size of the hibernation image
>
> -SNAPSHOT_AVAIL_SWAP_SIZE - return the amount of available swap in bytes (the
> +SNAPSHOT_AVAIL_SWAP_SIZE
> + return the amount of available swap in bytes (the
> last argument should be a pointer to an unsigned int variable that will
> contain the result if the call is successful).
>
> -SNAPSHOT_ALLOC_SWAP_PAGE - allocate a swap page from the resume partition
> +SNAPSHOT_ALLOC_SWAP_PAGE
> + allocate a swap page from the resume partition
> (the last argument should be a pointer to a loff_t variable that
> will contain the swap page offset if the call is successful)
>
> -SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated by
> +SNAPSHOT_FREE_SWAP_PAGES
> + free all swap pages allocated by
> SNAPSHOT_ALLOC_SWAP_PAGE
>
> -SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
> +SNAPSHOT_SET_SWAP_AREA
> + set the resume partition and the offset (in <PAGE_SIZE>
> units) from the beginning of the partition at which the swap header is
> located (the last ioctl() argument should point to a struct
> resume_swap_area, as defined in kernel/power/suspend_ioctls.h,
> containing the resume device specification and the offset); for swap
> partitions the offset is always 0, but it is different from zero for
> - swap files (see Documentation/power/swsusp-and-swap-files.txt for
> + swap files (see Documentation/power/swsusp-and-swap-files.rst for
> details).
>
> -SNAPSHOT_PLATFORM_SUPPORT - enable/disable the hibernation platform support,
> +SNAPSHOT_PLATFORM_SUPPORT
> + enable/disable the hibernation platform support,
> depending on the argument value (enable, if the argument is nonzero)
>
> -SNAPSHOT_POWER_OFF - make the kernel transition the system to the hibernation
> +SNAPSHOT_POWER_OFF
> + make the kernel transition the system to the hibernation
> state (eg. ACPI S4) using the platform (eg. ACPI) driver
>
> -SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
> +SNAPSHOT_S2RAM
> + suspend to RAM; using this call causes the kernel to
> immediately enter the suspend-to-RAM state, so this call must always
> be preceded by the SNAPSHOT_FREEZE call and it is also necessary
> to use the SNAPSHOT_UNFREEZE call after the system wakes up. This call
> @@ -98,10 +115,11 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
>
> The device's read() operation can be used to transfer the snapshot image from
> the kernel. It has the following limitations:
> +
> - you cannot read() more than one virtual memory page at a time
> - read()s across page boundaries are impossible (ie. if you read() 1/2 of
> - a page in the previous call, you will only be able to read()
> - _at_ _most_ 1/2 of the page in the next call)
> + a page in the previous call, you will only be able to read()
> + **at most** 1/2 of the page in the next call)
>
> The device's write() operation is used for uploading the system memory snapshot
> into the kernel. It has the same limitations as the read() operation.
> @@ -143,8 +161,10 @@ preferably using mlockall(), before calling SNAPSHOT_FREEZE.
> The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE
> in the memory location pointed to by the last argument of ioctl() and proceed
> in accordance with it:
> +
> 1. If the value is 1 (ie. the system memory snapshot has just been
> created and the system is ready for saving it):
> +
> (a) The suspending utility MUST NOT close the snapshot device
> _unless_ the whole suspend procedure is to be cancelled, in
> which case, if the snapshot image has already been saved, the
> @@ -158,6 +178,7 @@ in accordance with it:
> called. However, it MAY mount a file system that was not
> mounted at that time and perform some operations on it (eg.
> use it for saving the image).
> +
> 2. If the value is 0 (ie. the system state has just been restored from
> the snapshot image), the suspending utility MUST close the snapshot
> device. Afterwards it will be treated as a regular userland process,
> diff --git a/Documentation/power/video.txt b/Documentation/power/video.rst
> similarity index 56%
> rename from Documentation/power/video.txt
> rename to Documentation/power/video.rst
> index 3e6272bc4472..337a2ba9f32f 100644
> --- a/Documentation/power/video.txt
> +++ b/Documentation/power/video.rst
> @@ -1,7 +1,8 @@
> +===========================
> +Video issues with S3 resume
> +===========================
>
> - Video issues with S3 resume
> - ~~~~~~~~~~~~~~~~~~~~~~~~~~~
> - 2003-2006, Pavel Machek
> +2003-2006, Pavel Machek
>
> During S3 resume, hardware needs to be reinitialized. For most
> devices, this is easy, and kernel driver knows how to do
> @@ -41,37 +42,37 @@ There are a few types of systems where video works after S3 resume:
> (1) systems where video state is preserved over S3.
>
> (2) systems where it is possible to call the video BIOS during S3
> - resume. Unfortunately, it is not correct to call the video BIOS at
> - that point, but it happens to work on some machines. Use
> - acpi_sleep=s3_bios.
> + resume. Unfortunately, it is not correct to call the video BIOS at
> + that point, but it happens to work on some machines. Use
> + acpi_sleep=s3_bios.
>
> (3) systems that initialize video card into vga text mode and where
> - the BIOS works well enough to be able to set video mode. Use
> - acpi_sleep=s3_mode on these.
> + the BIOS works well enough to be able to set video mode. Use
> + acpi_sleep=s3_mode on these.
>
> (4) on some systems s3_bios kicks video into text mode, and
> - acpi_sleep=s3_bios,s3_mode is needed.
> + acpi_sleep=s3_bios,s3_mode is needed.
>
> (5) radeon systems, where X can soft-boot your video card. You'll need
> - a new enough X, and a plain text console (no vesafb or radeonfb). See
> - http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information.
> - Alternatively, you should use vbetool (6) instead.
> + a new enough X, and a plain text console (no vesafb or radeonfb). See
> + http://www.doesi.gmxhome.de/linux/tm800s3/s3.html for more information.
> + Alternatively, you should use vbetool (6) instead.
>
> (6) other radeon systems, where vbetool is enough to bring system back
> - to life. It needs text console to be working. Do vbetool vbestate
> - save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool
> - vbestate restore < /tmp/delme; setfont <whatever>, and your video
> - should work.
> + to life. It needs text console to be working. Do vbetool vbestate
> + save > /tmp/delme; echo 3 > /proc/acpi/sleep; vbetool post; vbetool
> + vbestate restore < /tmp/delme; setfont <whatever>, and your video
> + should work.
>
> (7) on some systems, it is possible to boot most of kernel, and then
> - POSTing bios works. Ole Rohne has patch to do just that at
> - http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2.
> + POSTing bios works. Ole Rohne has patch to do just that at
> + http://dev.gentoo.org/~marineam/patch-radeonfb-2.6.11-rc2-mm2.
>
> -(8) on some systems, you can use the video_post utility and or
> - do echo 3 > /sys/power/state && /usr/sbin/video_post - which will
> - initialize the display in console mode. If you are in X, you can switch
> - to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get
> - the display working in graphical mode again.
> +(8) on some systems, you can use the video_post utility and or
> + do echo 3 > /sys/power/state && /usr/sbin/video_post - which will
> + initialize the display in console mode. If you are in X, you can switch
> + to a virtual terminal and back to X using CTRL+ALT+F1 - CTRL+ALT+F7 to get
> + the display working in graphical mode again.
>
> Now, if you pass acpi_sleep=something, and it does not work with your
> bios, you'll get a hard crash during resume. Be careful. Also it is
> @@ -87,99 +88,126 @@ chance of working.
>
> Table of known working notebooks:
>
> +
> +=============================== ===============================================
> Model hack (or "how to do it")
> -------------------------------------------------------------------------------
> +=============================== ===============================================
> Acer Aspire 1406LC ole's late BIOS init (7), turn off DRI
> Acer TM 230 s3_bios (2)
> Acer TM 242FX vbetool (6)
> Acer TM C110 video_post (8)
> -Acer TM C300 vga=normal (only suspend on console, not in X), vbetool (6) or video_post (8)
> +Acer TM C300 vga=normal (only suspend on console, not in X),
> + vbetool (6) or video_post (8)
> Acer TM 4052LCi s3_bios (2)
> Acer TM 636Lci s3_bios,s3_mode (4)
> -Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text console back
> -Acer TM 660 ??? (*)
> -Acer TM 800 vga=normal, X patches, see webpage (5) or vbetool (6)
> -Acer TM 803 vga=normal, X patches, see webpage (5) or vbetool (6)
> +Acer TM 650 (Radeon M7) vga=normal plus boot-radeon (5) gets text
> + console back
> +Acer TM 660 ??? [#f1]_
> +Acer TM 800 vga=normal, X patches, see webpage (5)
> + or vbetool (6)
> +Acer TM 803 vga=normal, X patches, see webpage (5)
> + or vbetool (6)
> Acer TM 803LCi vga=normal, vbetool (6)
> Arima W730a vbetool needed (6)
> -Asus L2400D s3_mode (3)(***) (S1 also works OK)
> +Asus L2400D s3_mode (3) [#f2]_ (S1 also works OK)
> Asus L3350M (SiS 740) (6)
> Asus L3800C (Radeon M7) s3_bios (2) (S1 also works OK)
> -Asus M6887Ne vga=normal, s3_bios (2), use radeon driver instead of fglrx in x.org
> +Asus M6887Ne vga=normal, s3_bios (2), use radeon driver
> + instead of fglrx in x.org
> Athlon64 desktop prototype s3_bios (2)
> -Compal CL-50 ??? (*)
> +Compal CL-50 ??? [#f1]_
> Compaq Armada E500 - P3-700 none (1) (S1 also works OK)
> Compaq Evo N620c vga=normal, s3_bios (2)
> Dell 600m, ATI R250 Lf none (1), but needs xorg-x11-6.8.1.902-1
> Dell D600, ATI RV250 vga=normal and X, or try vbestate (6)
> -Dell D610 vga=normal and X (possibly vbestate (6) too, but not tested)
> -Dell Inspiron 4000 ??? (*)
> -Dell Inspiron 500m ??? (*)
> +Dell D610 vga=normal and X (possibly vbestate (6) too,
> + but not tested)
> +Dell Inspiron 4000 ??? [#f1]_
> +Dell Inspiron 500m ??? [#f1]_
> Dell Inspiron 510m ???
> Dell Inspiron 5150 vbetool needed (6)
> -Dell Inspiron 600m ??? (*)
> -Dell Inspiron 8200 ??? (*)
> -Dell Inspiron 8500 ??? (*)
> -Dell Inspiron 8600 ??? (*)
> -eMachines athlon64 machines vbetool needed (6) (someone please get me model #s)
> -HP NC6000 s3_bios, may not use radeonfb (2); or vbetool (6)
> -HP NX7000 ??? (*)
> -HP Pavilion ZD7000 vbetool post needed, need open-source nv driver for X
> +Dell Inspiron 600m ??? [#f1]_
> +Dell Inspiron 8200 ??? [#f1]_
> +Dell Inspiron 8500 ??? [#f1]_
> +Dell Inspiron 8600 ??? [#f1]_
> +eMachines athlon64 machines vbetool needed (6) (someone please get
> + me model #s)
> +HP NC6000 s3_bios, may not use radeonfb (2);
> + or vbetool (6)
> +HP NX7000 ??? [#f1]_
> +HP Pavilion ZD7000 vbetool post needed, need open-source nv
> + driver for X
> HP Omnibook XE3 athlon version none (1)
> HP Omnibook XE3GC none (1), video is S3 Savage/IX-MV
> HP Omnibook XE3L-GF vbetool (6)
> HP Omnibook 5150 none (1), (S1 also works OK)
> -IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294 Savage/IX-MV, vesafb gets "interesting" but X work.
> -IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with BIOS 1.04 2002-08-23, but not at all with BIOS 1.11 2004-11-05 :-(]
> +IBM TP T20, model 2647-44G none (1), video is S3 Inc. 86C270-294
> + Savage/IX-MV, vesafb gets "interesting"
> + but X work.
> +IBM TP A31 / Type 2652-M5G s3_mode (3) [works ok with
> + BIOS 1.04 2002-08-23, but not at all with
> + BIOS 1.11 2004-11-05 :-(]
> IBM TP R32 / Type 2658-MMG none (1)
> -IBM TP R40 2722B3G ??? (*)
> +IBM TP R40 2722B3G ??? [#f1]_
> IBM TP R50p / Type 1832-22U s3_bios (2)
> IBM TP R51 none (1)
> -IBM TP T30 236681A ??? (*)
> +IBM TP T30 236681A ??? [#f1]_
> IBM TP T40 / Type 2373-MU4 none (1)
> IBM TP T40p none (1)
> IBM TP R40p s3_bios (2)
> IBM TP T41p s3_bios (2), switch to X after resume
> IBM TP T42 s3_bios (2)
> IBM ThinkPad T42p (2373-GTG) s3_bios (2)
> -IBM TP X20 ??? (*)
> +IBM TP X20 ??? [#f1]_
> IBM TP X30 s3_bios, s3_mode (4)
> -IBM TP X31 / Type 2672-XXH none (1), use radeontool (http://fdd.com/software/radeon/) to turn off backlight.
> -IBM TP X32 none (1), but backlight is on and video is trashed after long suspend. s3_bios,s3_mode (4) works too. Perhaps that gets better results?
> +IBM TP X31 / Type 2672-XXH none (1), use radeontool
> + (http://fdd.com/software/radeon/) to
> + turn off backlight.
> +IBM TP X32 none (1), but backlight is on and video is
> + trashed after long suspend. s3_bios,
> + s3_mode (4) works too. Perhaps that gets
> + better results?
> IBM Thinkpad X40 Type 2371-7JG s3_bios,s3_mode (4)
> -IBM TP 600e none(1), but a switch to console and back to X is needed
> -Medion MD4220 ??? (*)
> +IBM TP 600e none(1), but a switch to console and
> + back to X is needed
> +Medion MD4220 ??? [#f1]_
> Samsung P35 vbetool needed (6)
> Sharp PC-AR10 (ATI rage) none (1), backlight does not switch off
> Sony Vaio PCG-C1VRX/K s3_bios (2)
> -Sony Vaio PCG-F403 ??? (*)
> +Sony Vaio PCG-F403 ??? [#f1]_
> Sony Vaio PCG-GRT995MP none (1), works with 'nv' X driver
> -Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use radeontool (http://fdd.com/software/radeon/) to turn off backlight.
> -Sony Vaio PCG-N505SN ??? (*)
> +Sony Vaio PCG-GR7/K none (1), but needs radeonfb, use
> + radeontool (http://fdd.com/software/radeon/)
> + to turn off backlight.
> +Sony Vaio PCG-N505SN ??? [#f1]_
> Sony Vaio vgn-s260 X or boot-radeon can init it (5)
> -Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will be blank unless you return to X.
> +Sony Vaio vgn-S580BH vga=normal, but suspend from X. Console will
> + be blank unless you return to X.
> Sony Vaio vgn-FS115B s3_bios (2),s3_mode (4)
> Toshiba Libretto L5 none (1)
> Toshiba Libretto 100CT/110CT vbetool (6)
> Toshiba Portege 3020CT s3_mode (3)
> Toshiba Satellite 4030CDT s3_mode (3) (S1 also works OK)
> Toshiba Satellite 4080XCDT s3_mode (3) (S1 also works OK)
> -Toshiba Satellite 4090XCDT ??? (*)
> -Toshiba Satellite P10-554 s3_bios,s3_mode (4)(****)
> +Toshiba Satellite 4090XCDT ??? [#f1]_
> +Toshiba Satellite P10-554 s3_bios,s3_mode (4)[#f3]_
> Toshiba M30 (2) xor X with nvidia driver using internal AGP
> -Uniwill 244IIO ??? (*)
> +Uniwill 244IIO ??? [#f1]_
> +=============================== ===============================================
>
> Known working desktop systems
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> +=================== ============================= ========================
> Mainboard Graphics card hack (or "how to do it")
> -------------------------------------------------------------------------------
> +=================== ============================= ========================
> Asus A7V8X nVidia RIVA TNT2 model 64 s3_bios,s3_mode (4)
> +=================== ============================= ========================
>
>
> -(*) from https://wiki.ubuntu.com/HoaryPMResults, not sure
> - which options to use. If you know, please tell me.
> +.. [#f1] from https://wiki.ubuntu.com/HoaryPMResults, not sure
> + which options to use. If you know, please tell me.
>
> -(***) To be tested with a newer kernel.
> +.. [#f2] To be tested with a newer kernel.
>
> -(****) Not with SMP kernel, UP only.
> +.. [#f3] Not with SMP kernel, UP only.
> diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
> index 58bc047e7b95..1acaa14903d6 100644
> --- a/Documentation/process/submitting-drivers.rst
> +++ b/Documentation/process/submitting-drivers.rst
> @@ -117,7 +117,7 @@ PM support:
> implemented") error. You should also try to make sure that your
> driver uses as little power as possible when it's not doing
> anything. For the driver testing instructions see
> - Documentation/power/drivers-testing.txt and for a relatively
> + Documentation/power/drivers-testing.rst and for a relatively
> complete overview of the power management issues related to
> drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`.
>
> diff --git a/Documentation/scheduler/sched-energy.txt b/Documentation/scheduler/sched-energy.txt
> index 197d81f4b836..d97207b9accb 100644
> --- a/Documentation/scheduler/sched-energy.txt
> +++ b/Documentation/scheduler/sched-energy.txt
> @@ -22,7 +22,7 @@ the highest.
>
> The actual EM used by EAS is _not_ maintained by the scheduler, but by a
> dedicated framework. For details about this framework and what it provides,
> -please refer to its documentation (see Documentation/power/energy-model.txt).
> +please refer to its documentation (see Documentation/power/energy-model.rst).
>
>
> 2. Background and Terminology
> @@ -81,7 +81,7 @@ through the arch_scale_cpu_capacity() callback.
>
> The rest of platform knowledge used by EAS is directly read from the Energy
> Model (EM) framework. The EM of a platform is composed of a power cost table
> -per 'performance domain' in the system (see Documentation/power/energy-model.txt
> +per 'performance domain' in the system (see Documentation/power/energy-model.rst
> for futher details about performance domains).
>
> The scheduler manages references to the EM objects in the topology code when the
> @@ -352,7 +352,7 @@ could be amended in the future if proven otherwise.
> EAS uses the EM of a platform to estimate the impact of scheduling decisions on
> energy. So, your platform must provide power cost tables to the EM framework in
> order to make EAS start. To do so, please refer to documentation of the
> -independent EM framework in Documentation/power/energy-model.txt.
> +independent EM framework in Documentation/power/energy-model.rst.
>
> Please also note that the scheduling domains need to be re-built after the
> EM has been registered in order to start EAS.
> diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.txt
> index f07e38094b40..1a660a39e3c0 100644
> --- a/Documentation/trace/coresight-cpu-debug.txt
> +++ b/Documentation/trace/coresight-cpu-debug.txt
> @@ -151,7 +151,7 @@ At the runtime you can disable idle states with below methods:
>
> It is possible to disable CPU idle states by way of the PM QoS
> subsystem, more specifically by using the "/dev/cpu_dma_latency"
> -interface (see Documentation/power/pm_qos_interface.txt for more
> +interface (see Documentation/power/pm_qos_interface.rst for more
> details). As specified in the PM QoS documentation the requested
> parameter will stay in effect until the file descriptor is released.
> For example:
> diff --git a/Documentation/translations/zh_CN/process/submitting-drivers.rst b/Documentation/translations/zh_CN/process/submitting-drivers.rst
> index 72c6cd935821..f1c3906c69a8 100644
> --- a/Documentation/translations/zh_CN/process/submitting-drivers.rst
> +++ b/Documentation/translations/zh_CN/process/submitting-drivers.rst
> @@ -97,7 +97,7 @@ Linux 2.6:
> 函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确
> 保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动
> 程序测试的指导，请参阅
> - Documentation/power/drivers-testing.txt。有关驱动程序电
> + Documentation/power/drivers-testing.rst。有关驱动程序电
> 源管理问题相对全面的概述，请参阅
> Documentation/driver-api/pm/devices.rst。
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 5fdbf6e78d46..1c9ed0a5a9df 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -6491,7 +6491,7 @@ M: "Rafael J. Wysocki" <rjw-LthD3rsA81gm4RdzfppkhA@public.gmane.org>
> M: Pavel Machek <pavel-+ZI9xUNit7I@public.gmane.org>
> L: linux-pm-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> S: Supported
> -F: Documentation/power/freezing-of-tasks.txt
> +F: Documentation/power/freezing-of-tasks.rst
> F: include/linux/freezer.h
> F: kernel/freezer.c
>
> @@ -11825,7 +11825,7 @@ S: Maintained
> T: git git://git.kernel.org/pub/scm/linux/kernel/git/vireshk/pm.git
> F: drivers/opp/
> F: include/linux/pm_opp.h
> -F: Documentation/power/opp.txt
> +F: Documentation/power/opp.rst
> F: Documentation/devicetree/bindings/opp/
>
> OPL4 DRIVER
> diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
> index a109141a8d3b..bc5e1c218d4d 100644
> --- a/arch/x86/Kconfig
> +++ b/arch/x86/Kconfig
> @@ -2448,7 +2448,7 @@ menuconfig APM
> machines with more than one CPU.
>
> In order to use APM, you will need supporting software. For location
> - and more information, read <file:Documentation/power/apm-acpi.txt>
> + and more information, read <file:Documentation/power/apm-acpi.rst>
> and the Battery Powered Linux mini-HOWTO, available from
> <http://www.tldp.org/docs.html#howto>.
>
> diff --git a/drivers/gpu/drm/i915/i915_drv.h b/drivers/gpu/drm/i915/i915_drv.h
> index 0ea7f78ae227..eeb7edfa3597 100644
> --- a/drivers/gpu/drm/i915/i915_drv.h
> +++ b/drivers/gpu/drm/i915/i915_drv.h
> @@ -1069,7 +1069,7 @@ struct skl_wm_params {
> * to be disabled. This shouldn't happen and we'll print some error messages in
> * case it happens.
> *
> - * For more, read the Documentation/power/runtime_pm.txt.
> + * For more, read the Documentation/power/runtime_pm.rst.
> */
> struct i915_runtime_pm {
> atomic_t wakeref_count;
> diff --git a/drivers/opp/Kconfig b/drivers/opp/Kconfig
> index fe54d349d2e1..35dfc7e80f92 100644
> --- a/drivers/opp/Kconfig
> +++ b/drivers/opp/Kconfig
> @@ -11,4 +11,4 @@ config PM_OPP
> OPP layer organizes the data internally using device pointers
> representing individual voltage domains and provides SOC
> implementations a ready to use framework to manage OPPs.
> - For more information, read <file:Documentation/power/opp.txt>
> + For more information, read <file:Documentation/power/opp.rst>
> diff --git a/drivers/power/supply/power_supply_core.c b/drivers/power/supply/power_supply_core.c
> index 136e8f64848a..b55cdfe22a2e 100644
> --- a/drivers/power/supply/power_supply_core.c
> +++ b/drivers/power/supply/power_supply_core.c
> @@ -606,7 +606,7 @@ int power_supply_get_battery_info(struct power_supply *psy,
>
> /* The property and field names below must correspond to elements
> * in enum power_supply_property. For reasoning, see
> - * Documentation/power/power_supply_class.txt.
> + * Documentation/power/power_supply_class.rst.
> */
>
> of_property_read_u32(battery_np, "energy-full-design-microwatt-hours",
> diff --git a/include/linux/interrupt.h b/include/linux/interrupt.h
> index c7eef32e7739..5b8328a99b2a 100644
> --- a/include/linux/interrupt.h
> +++ b/include/linux/interrupt.h
> @@ -52,7 +52,7 @@
> * irq line disabled until the threaded handler has been run.
> * IRQF_NO_SUSPEND - Do not disable this IRQ during suspend. Does not guarantee
> * that this interrupt will wake the system from a suspended
> - * state. See Documentation/power/suspend-and-interrupts.txt
> + * state. See Documentation/power/suspend-and-interrupts.rst
> * IRQF_FORCE_RESUME - Force enable it on resume even if IRQF_NO_SUSPEND is set
> * IRQF_NO_THREAD - Interrupt cannot be threaded
> * IRQF_EARLY_RESUME - Resume IRQ early during syscore instead of at device
> diff --git a/include/linux/pci.h b/include/linux/pci.h
> index 44d254548ca7..41c5673aba2f 100644
> --- a/include/linux/pci.h
> +++ b/include/linux/pci.h
> @@ -808,7 +808,7 @@ struct module;
> * @suspend_late: Put device into low power state.
> * @resume_early: Wake device from low power state.
> * @resume: Wake device from low power state.
> - * (Please see Documentation/power/pci.txt for descriptions
> + * (Please see Documentation/power/pci.rst for descriptions
> * of PCI Power Management and the related functions.)
> * @shutdown: Hook into reboot_notifier_list (kernel/sys.c).
> * Intended to stop any idling DMA operations.
> diff --git a/include/linux/pm.h b/include/linux/pm.h
> index 345d74a727e3..220e2008467d 100644
> --- a/include/linux/pm.h
> +++ b/include/linux/pm.h
> @@ -271,7 +271,7 @@ typedef struct pm_message {
> * actions to be performed by a device driver's callbacks generally depend on
> * the platform and subsystem the device belongs to.
> *
> - * Refer to Documentation/power/runtime_pm.txt for more information about the
> + * Refer to Documentation/power/runtime_pm.rst for more information about the
> * role of the @runtime_suspend(), @runtime_resume() and @runtime_idle()
> * callbacks in device runtime power management.
> */
> diff --git a/kernel/power/Kconfig b/kernel/power/Kconfig
> index ff8592ddedee..d3667b4075c1 100644
> --- a/kernel/power/Kconfig
> +++ b/kernel/power/Kconfig
> @@ -66,7 +66,7 @@ config HIBERNATION
> need to run mkswap against the swap partition used for the suspend.
>
> It also works with swap files to a limited extent (for details see
> - <file:Documentation/power/swsusp-and-swap-files.txt>).
> + <file:Documentation/power/swsusp-and-swap-files.rst>).
>
> Right now you may boot without resuming and resume later but in the
> meantime you cannot use the swap partition(s)/file(s) involved in
> @@ -75,7 +75,7 @@ config HIBERNATION
> MOUNT any journaled filesystems mounted before the suspend or they
> will get corrupted in a nasty way.
>
> - For more information take a look at <file:Documentation/power/swsusp.txt>.
> + For more information take a look at <file:Documentation/power/swsusp.rst>.
>
> config ARCH_SAVE_PAGE_KEYS
> bool
> @@ -256,7 +256,7 @@ config APM_EMULATION
> notification of APM "events" (e.g. battery status change).
>
> In order to use APM, you will need supporting software. For location
> - and more information, read <file:Documentation/power/apm-acpi.txt>
> + and more information, read <file:Documentation/power/apm-acpi.rst>
> and the Battery Powered Linux mini-HOWTO, available from
> <http://www.tldp.org/docs.html#howto>.
>
> diff --git a/net/wireless/Kconfig b/net/wireless/Kconfig
> index 6310ddede220..cc70f5932773 100644
> --- a/net/wireless/Kconfig
> +++ b/net/wireless/Kconfig
> @@ -166,7 +166,7 @@ config CFG80211_DEFAULT_PS
>
> If this causes your applications to misbehave you should fix your
> applications instead -- they need to register their network
> - latency requirement, see Documentation/power/pm_qos_interface.txt.
> + latency requirement, see Documentation/power/pm_qos_interface.rst.
>
> config CFG80211_DEBUGFS
> bool "cfg80211 DebugFS entries"
> --
> 2.21.0
>
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH v4 28/28] docs: EDID/HOWTO.txt: convert it and rename to howto.rst
[not found] <cover.1560361364.git.mchehab+samsung@kernel.org>
` (3 preceding siblings ...)
2019-06-12 17:52 ` [PATCH v4 18/28] docs: " Mauro Carvalho Chehab
@ 2019-06-12 17:53 ` Mauro Carvalho Chehab
4 siblings, 0 replies; 12+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 17:53 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Jonathan Corbet, Maxime Ripard, linux-kernel, dri-devel,
Mauro Carvalho Chehab, David Airlie, Mauro Carvalho Chehab,
Sean Paul
Sphinx need to know when a paragraph ends. So, do some adjustments
at the file for it to be properly parsed.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
that's said, I believe that this file should be moved to the
GPU/DRM documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/EDID/{HOWTO.txt => howto.rst} | 31 ++++++++++++-------
.../admin-guide/kernel-parameters.txt | 2 +-
drivers/gpu/drm/Kconfig | 2 +-
3 files changed, 22 insertions(+), 13 deletions(-)
rename Documentation/EDID/{HOWTO.txt => howto.rst} (83%)
diff --git a/Documentation/EDID/HOWTO.txt b/Documentation/EDID/howto.rst
similarity index 83%
rename from Documentation/EDID/HOWTO.txt
rename to Documentation/EDID/howto.rst
index 539871c3b785..725fd49a88ca 100644
--- a/Documentation/EDID/HOWTO.txt
+++ b/Documentation/EDID/howto.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+====
+EDID
+====
+
In the good old days when graphics parameters were configured explicitly
in a file called xorg.conf, even broken hardware could be managed.
@@ -34,16 +40,19 @@ Makefile. Please note that the EDID data structure expects the timing
values in a different way as compared to the standard X11 format.
X11:
-HTimings: hdisp hsyncstart hsyncend htotal
-VTimings: vdisp vsyncstart vsyncend vtotal
+ HTimings:
+ hdisp hsyncstart hsyncend htotal
+ VTimings:
+ vdisp vsyncstart vsyncend vtotal
-EDID:
-#define XPIX hdisp
-#define XBLANK htotal-hdisp
-#define XOFFSET hsyncstart-hdisp
-#define XPULSE hsyncend-hsyncstart
+EDID::
-#define YPIX vdisp
-#define YBLANK vtotal-vdisp
-#define YOFFSET vsyncstart-vdisp
-#define YPULSE vsyncend-vsyncstart
+ #define XPIX hdisp
+ #define XBLANK htotal-hdisp
+ #define XOFFSET hsyncstart-hdisp
+ #define XPULSE hsyncend-hsyncstart
+
+ #define YPIX vdisp
+ #define YBLANK vtotal-vdisp
+ #define YOFFSET vsyncstart-vdisp
+ #define YPULSE vsyncend-vsyncstart
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 3d072ca532bb..3faf37b8b001 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -930,7 +930,7 @@
edid/1680x1050.bin, or edid/1920x1080.bin is given
and no file with the same name exists. Details and
instructions how to build your own EDID data are
- available in Documentation/EDID/HOWTO.txt. An EDID
+ available in Documentation/EDID/howto.rst. An EDID
data set will only be used for a particular connector,
if its name and a colon are prepended to the EDID
name. Each connector may use a unique EDID data
diff --git a/drivers/gpu/drm/Kconfig b/drivers/gpu/drm/Kconfig
index 6b34949416b1..c3a6dd284c91 100644
--- a/drivers/gpu/drm/Kconfig
+++ b/drivers/gpu/drm/Kconfig
@@ -141,7 +141,7 @@ config DRM_LOAD_EDID_FIRMWARE
monitor are unable to provide appropriate EDID data. Since this
feature is provided as a workaround for broken hardware, the
default case is N. Details and instructions how to build your own
- EDID data are given in Documentation/EDID/HOWTO.txt.
+ EDID data are given in Documentation/EDID/howto.rst.
config DRM_DP_CEC
bool "Enable DisplayPort CEC-Tunneling-over-AUX HDMI support"
--
2.21.0
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 12+ messages in thread