This is the second part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.
As it touches on lot of stuff, this series is based on today's linux-next,
at tag next-20190617.
The first version of this series had 57 patches. The first part with 28 patches
were already merged. Right now, there are still ~76 patches pending applying
(including this series), and that's because I opted to do ~1 patch per converted
directory.
That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts for the conversion, plus a final patch adding orphaned books
to existing ones.
Those patches should probably be good to be merged either by subsystem
maintainers or via the docs tree.
I opted to mark new files not included yet to the main index.rst (directly or
indirectly) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement, after I
submit the third part.
Both this series and the other parts of this work are on my devel git tree,
at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v5.1
The final output in html (after all patches I currently have, including
the upcoming series) can be seen at:
https://www.infradead.org/~mchehab/rst_conversion/
It contains all pending work from my side related to the conversion, plus
the patches I finished a first version today with contains the renaming
patches and de-orphan changes.
---
Version 2:
- Removed patches merged via other trees;
- rebased on the top of today's linux-next (next-20190617);
- Fix a typo on one patch's description;
- Added received acks.
Mauro Carvalho Chehab (29):
docs: connector: convert to ReST and rename to connector.rst
docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
docs: lp855x-driver.txt: convert to ReST and move to kernel-api
docs: m68k: convert docs to ReST and rename to *.rst
docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst
docs: console.txt: convert docs to ReST and rename to *.rst
docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst
docs: early-userspace: convert docs to ReST and rename to *.rst
docs: driver-model: convert docs to ReST and rename to *.rst
docs: arm: convert docs to ReST and rename to *.rst
docs: memory-devices: convert ti-emif.txt to ReST
docs: xen-tpmfront.txt: convert it to .rst
docs: bus-devices: ti-gpmc.rst: convert it to ReST
docs: nvmem: convert docs to ReST and rename to *.rst
docs: phy: convert samsung-usb2.txt to ReST format
docs: rbtree.txt: fix Sphinx build warnings
docs: DMA-API-HOWTO.txt: fix an unmarked code block
docs: accounting: convert to ReST
docs: ia64: convert to ReST
docs: leds: convert to ReST
docs: laptops: convert to ReST
docs: iio: convert to ReST
docs: namespaces: convert to ReST
docs: nfc: convert to ReST
docs: md: convert to ReST
docs: mtd: convert to ReST
docs: nvdimm: convert to ReST
docs: xtensa: convert to ReST
docs: mmc: convert to ReST
Documentation/ABI/testing/sysfs-block-device | 2 +-
.../ABI/testing/sysfs-platform-asus-laptop | 2 +-
Documentation/DMA-API-HOWTO.txt | 2 +-
.../{cgroupstats.txt => cgroupstats.rst} | 14 +-
...ay-accounting.txt => delay-accounting.rst} | 61 ++-
Documentation/accounting/index.rst | 14 +
Documentation/accounting/{psi.txt => psi.rst} | 40 +-
...kstats-struct.txt => taskstats-struct.rst} | 79 ++-
.../{taskstats.txt => taskstats.rst} | 15 +-
Documentation/admin-guide/cgroup-v2.rst | 6 +-
.../admin-guide/kernel-parameters.rst | 2 +-
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/arm/Marvell/README | 395 -------------
Documentation/arm/Netwinder | 78 ---
Documentation/arm/SA1100/FreeBird | 21 -
Documentation/arm/SA1100/empeg | 2 -
Documentation/arm/SA1100/serial_UART | 47 --
Documentation/arm/{README => arm.rst} | 50 +-
Documentation/arm/{Booting => booting.rst} | 71 ++-
...ance.txt => cluster-pm-race-avoidance.rst} | 177 +++---
.../arm/{firmware.txt => firmware.rst} | 14 +-
Documentation/arm/index.rst | 80 +++
.../arm/{Interrupts => interrupts.rst} | 86 +--
Documentation/arm/{IXP4xx => ixp4xx.rst} | 61 ++-
...nel_mode_neon.txt => kernel_mode_neon.rst} | 3 +
...er_helpers.txt => kernel_user_helpers.rst} | 79 +--
.../keystone/{knav-qmss.txt => knav-qmss.rst} | 6 +-
.../keystone/{Overview.txt => overview.rst} | 47 +-
Documentation/arm/marvel.rst | 488 +++++++++++++++++
.../arm/{mem_alignment => mem_alignment.rst} | 11 +-
Documentation/arm/{memory.txt => memory.rst} | 9 +-
.../arm/{Microchip/README => microchip.rst} | 63 ++-
Documentation/arm/netwinder.rst | 85 +++
Documentation/arm/nwfpe/index.rst | 11 +
.../nwfpe/{README.FPE => netwinder-fpe.rst} | 24 +-
Documentation/arm/nwfpe/{NOTES => notes.rst} | 3 +
Documentation/arm/nwfpe/{README => nwfpe.rst} | 10 +-
Documentation/arm/nwfpe/{TODO => todo.rst} | 47 +-
Documentation/arm/{OMAP/DSS => omap/dss.rst} | 112 ++--
Documentation/arm/omap/index.rst | 10 +
.../arm/{OMAP/README => omap/omap.rst} | 7 +
.../arm/{OMAP/omap_pm => omap/omap_pm.rst} | 55 +-
Documentation/arm/{Porting => porting.rst} | 14 +-
Documentation/arm/pxa/{mfp.txt => mfp.rst} | 106 ++--
.../{SA1100/ADSBitsy => sa1100/adsbitsy.rst} | 14 +-
.../{SA1100/Assabet => sa1100/assabet.rst} | 185 +++----
.../arm/{SA1100/Brutus => sa1100/brutus.rst} | 45 +-
.../arm/{SA1100/CERF => sa1100/cerf.rst} | 10 +-
Documentation/arm/sa1100/freebird.rst | 25 +
.../graphicsclient.rst} | 46 +-
.../graphicsmaster.rst} | 13 +-
.../HUW_WEBPANEL => sa1100/huw_webpanel.rst} | 8 +-
Documentation/arm/sa1100/index.rst | 23 +
.../arm/{SA1100/Itsy => sa1100/itsy.rst} | 14 +-
.../arm/{SA1100/LART => sa1100/lart.rst} | 3 +-
.../nanoEngine => sa1100/nanoengine.rst} | 6 +-
.../{SA1100/Pangolin => sa1100/pangolin.rst} | 10 +-
.../arm/{SA1100/PLEB => sa1100/pleb.rst} | 6 +-
Documentation/arm/sa1100/serial_uart.rst | 51 ++
.../arm/{SA1100/Tifon => sa1100/tifon.rst} | 4 +-
.../arm/{SA1100/Yopy => sa1100/yopy.rst} | 5 +-
.../cpufreq.rst} | 5 +-
.../eb2410itx.rst} | 5 +-
.../GPIO.txt => samsung-s3c24xx/gpio.rst} | 23 +-
.../H1940.txt => samsung-s3c24xx/h1940.rst} | 5 +-
Documentation/arm/samsung-s3c24xx/index.rst | 18 +
.../NAND.txt => samsung-s3c24xx/nand.rst} | 6 +-
.../overview.rst} | 21 +-
.../s3c2412.rst} | 5 +-
.../s3c2413.rst} | 7 +-
.../smdk2440.rst} | 5 +-
.../suspend.rst} | 20 +-
.../usb-host.rst} | 16 +-
.../bootloader-interface.rst} | 27 +-
.../clksrc-change-registers.awk | 0
.../{Samsung/GPIO.txt => samsung/gpio.rst} | 7 +-
Documentation/arm/samsung/index.rst | 10 +
.../Overview.txt => samsung/overview.rst} | 15 +-
Documentation/arm/{Setup => setup.rst} | 49 +-
.../arm/{SH-Mobile => sh-mobile}/.gitignore | 0
.../overview.txt => spear/overview.rst} | 20 +-
.../arm/sti/{overview.txt => overview.rst} | 21 +-
...h407-overview.txt => stih407-overview.rst} | 9 +-
...h415-overview.txt => stih415-overview.rst} | 8 +-
...h416-overview.txt => stih416-overview.rst} | 5 +-
...h418-overview.txt => stih418-overview.rst} | 9 +-
Documentation/arm/stm32/overview.rst | 2 -
.../arm/stm32/stm32f429-overview.rst | 7 +-
.../arm/stm32/stm32f746-overview.rst | 7 +-
.../arm/stm32/stm32f769-overview.rst | 7 +-
.../arm/stm32/stm32h743-overview.rst | 7 +-
.../arm/stm32/stm32mp157-overview.rst | 3 +-
Documentation/arm/{sunxi/README => sunxi.rst} | 98 +++-
.../arm/sunxi/{clocks.txt => clocks.rst} | 7 +-
.../arm/{swp_emulation => swp_emulation.rst} | 24 +-
Documentation/arm/{tcm.txt => tcm.rst} | 54 +-
Documentation/arm/{uefi.txt => uefi.rst} | 39 +-
.../release-notes.rst} | 4 +-
Documentation/arm/{vlocks.txt => vlocks.rst} | 9 +-
...cd-panel-cgram.txt => lcd-panel-cgram.rst} | 9 +-
Documentation/backlight/lp855x-driver.rst | 83 +++
Documentation/backlight/lp855x-driver.txt | 66 ---
.../bus-devices/{ti-gpmc.txt => ti-gpmc.rst} | 159 ++++--
.../cma/{debugfs.txt => debugfs.rst} | 8 +-
.../{connector.txt => connector.rst} | 130 ++---
.../console/{console.txt => console.rst} | 63 ++-
Documentation/devicetree/bindings/arm/xen.txt | 2 +-
.../devicetree/booting-without-of.txt | 4 +-
Documentation/driver-api/gpio/driver.rst | 2 +-
.../driver-model/{binding.txt => binding.rst} | 20 +-
.../driver-model/{bus.txt => bus.rst} | 69 +--
.../driver-model/{class.txt => class.rst} | 74 +--
...esign-patterns.txt => design-patterns.rst} | 106 ++--
.../driver-model/{device.txt => device.rst} | 57 +-
.../driver-model/{devres.txt => devres.rst} | 50 +-
.../driver-model/{driver.txt => driver.rst} | 112 ++--
Documentation/driver-model/index.rst | 26 +
.../{overview.txt => overview.rst} | 37 +-
.../{platform.txt => platform.rst} | 30 +-
.../driver-model/{porting.txt => porting.rst} | 333 +++++------
.../{buffer-format.txt => buffer-format.rst} | 19 +-
.../{README => early_userspace_support.rst} | 3 +
Documentation/early-userspace/index.rst | 18 +
Documentation/eisa.txt | 4 +-
Documentation/fb/fbcon.rst | 4 +-
Documentation/filesystems/nfs/nfsroot.txt | 2 +-
.../filesystems/ramfs-rootfs-initramfs.txt | 4 +-
Documentation/hwmon/submitting-patches.rst | 2 +-
.../ia64/{aliasing.txt => aliasing.rst} | 73 ++-
Documentation/ia64/{efirtc.txt => efirtc.rst} | 118 ++--
.../ia64/{err_inject.txt => err_inject.rst} | 349 ++++++------
Documentation/ia64/{fsys.txt => fsys.rst} | 127 +++--
Documentation/ia64/{README => ia64.rst} | 26 +-
Documentation/ia64/index.rst | 18 +
.../ia64/{IRQ-redir.txt => irq-redir.rst} | 31 +-
Documentation/ia64/{mca.txt => mca.rst} | 10 +-
Documentation/ia64/{serial.txt => serial.rst} | 36 +-
Documentation/ia64/xen.rst | 206 +++++++
Documentation/ia64/xen.txt | 183 -------
.../iio/{ep93xx_adc.txt => ep93xx_adc.rst} | 15 +-
.../{iio_configfs.txt => iio_configfs.rst} | 52 +-
Documentation/iio/index.rst | 12 +
Documentation/index.rst | 1 +
.../{asus-laptop.txt => asus-laptop.rst} | 92 ++--
...otection.txt => disk-shock-protection.rst} | 32 +-
Documentation/laptops/index.rst | 17 +
.../{laptop-mode.txt => laptop-mode.rst} | 509 +++++++++--------
.../{sony-laptop.txt => sony-laptop.rst} | 58 +-
.../laptops/{sonypi.txt => sonypi.rst} | 28 +-
.../{thinkpad-acpi.txt => thinkpad-acpi.rst} | 367 ++++++++-----
.../{toshiba_haps.txt => toshiba_haps.rst} | 47 +-
Documentation/leds/index.rst | 25 +
.../leds/{leds-blinkm.txt => leds-blinkm.rst} | 64 ++-
...s-class-flash.txt => leds-class-flash.rst} | 49 +-
.../leds/{leds-class.txt => leds-class.rst} | 15 +-
.../leds/{leds-lm3556.txt => leds-lm3556.rst} | 100 +++-
.../leds/{leds-lp3944.txt => leds-lp3944.rst} | 23 +-
Documentation/leds/leds-lp5521.rst | 115 ++++
Documentation/leds/leds-lp5521.txt | 101 ----
Documentation/leds/leds-lp5523.rst | 147 +++++
Documentation/leds/leds-lp5523.txt | 130 -----
Documentation/leds/leds-lp5562.rst | 137 +++++
Documentation/leds/leds-lp5562.txt | 120 ----
Documentation/leds/leds-lp55xx.rst | 224 ++++++++
Documentation/leds/leds-lp55xx.txt | 194 -------
Documentation/leds/leds-mlxcpld.rst | 118 ++++
Documentation/leds/leds-mlxcpld.txt | 110 ----
...edtrig-oneshot.txt => ledtrig-oneshot.rst} | 11 +-
...ig-transient.txt => ledtrig-transient.rst} | 63 ++-
...edtrig-usbport.txt => ledtrig-usbport.rst} | 11 +-
Documentation/leds/{uleds.txt => uleds.rst} | 5 +-
Documentation/m68k/index.rst | 17 +
...{kernel-options.txt => kernel-options.rst} | 319 ++++++-----
Documentation/md/index.rst | 12 +
.../md/{md-cluster.txt => md-cluster.rst} | 188 ++++---
.../md/{raid5-cache.txt => raid5-cache.rst} | 28 +-
.../md/{raid5-ppl.txt => raid5-ppl.rst} | 2 +
.../{ti-emif.txt => ti-emif.rst} | 27 +-
Documentation/mmc/index.rst | 13 +
.../{mmc-async-req.txt => mmc-async-req.rst} | 53 +-
.../{mmc-dev-attrs.txt => mmc-dev-attrs.rst} | 32 +-
.../{mmc-dev-parts.txt => mmc-dev-parts.rst} | 13 +-
.../mmc/{mmc-tools.txt => mmc-tools.rst} | 5 +-
Documentation/mtd/index.rst | 12 +
.../mtd/{intel-spi.txt => intel-spi.rst} | 46 +-
.../mtd/{nand_ecc.txt => nand_ecc.rst} | 481 ++++++++--------
.../mtd/{spi-nor.txt => spi-nor.rst} | 7 +-
...bility-list.txt => compatibility-list.rst} | 10 +-
Documentation/namespaces/index.rst | 11 +
...ource-control.txt => resource-control.rst} | 4 +
Documentation/nfc/index.rst | 11 +
.../nfc/{nfc-hci.txt => nfc-hci.rst} | 163 +++---
.../nfc/{nfc-pn544.txt => nfc-pn544.rst} | 6 +-
Documentation/nvdimm/{btt.txt => btt.rst} | 140 ++---
Documentation/nvdimm/index.rst | 12 +
.../nvdimm/{nvdimm.txt => nvdimm.rst} | 518 ++++++++++--------
.../nvdimm/{security.txt => security.rst} | 4 +-
Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 ++--
.../{samsung-usb2.txt => samsung-usb2.rst} | 62 ++-
Documentation/pti/pti_intel_mid.rst | 106 ++++
Documentation/pti/pti_intel_mid.txt | 99 ----
Documentation/rbtree.txt | 6 +-
.../{xen-tpmfront.txt => xen-tpmfront.rst} | 103 ++--
Documentation/sysctl/vm.txt | 4 +-
Documentation/translations/zh_CN/arm/Booting | 4 +-
.../zh_CN/arm/kernel_user_helpers.txt | 4 +-
.../xtensa/{atomctl.txt => atomctl.rst} | 13 +-
.../xtensa/{booting.txt => booting.rst} | 5 +-
Documentation/xtensa/index.rst | 12 +
Documentation/xtensa/mmu.rst | 195 +++++++
Documentation/xtensa/mmu.txt | 189 -------
MAINTAINERS | 16 +-
arch/arm/Kconfig | 2 +-
arch/arm/common/mcpm_entry.c | 2 +-
arch/arm/common/mcpm_head.S | 2 +-
arch/arm/common/vlock.S | 2 +-
arch/arm/include/asm/setup.h | 2 +-
arch/arm/include/uapi/asm/setup.h | 2 +-
arch/arm/kernel/entry-armv.S | 2 +-
arch/arm/mach-exynos/common.h | 2 +-
arch/arm/mach-ixp4xx/Kconfig | 14 +-
arch/arm/mach-s3c24xx/pm.c | 2 +-
arch/arm/mm/Kconfig | 4 +-
arch/arm/plat-samsung/Kconfig | 6 +-
arch/arm/tools/mach-types | 2 +-
arch/arm64/Kconfig | 2 +-
arch/arm64/kernel/kuser32.S | 2 +-
arch/ia64/kernel/efi.c | 2 +-
arch/ia64/kernel/fsys.S | 2 +-
arch/ia64/mm/ioremap.c | 2 +-
arch/ia64/pci/pci.c | 2 +-
arch/mips/bmips/setup.c | 2 +-
arch/xtensa/include/asm/initialize_mmu.h | 2 +-
drivers/base/platform.c | 2 +-
drivers/char/Kconfig | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-cipher.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-core.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss-hash.c | 2 +-
drivers/crypto/sunxi-ss/sun4i-ss.h | 2 +-
drivers/gpio/gpio-cs5535.c | 2 +-
drivers/iio/Kconfig | 2 +-
drivers/input/touchscreen/sun4i-ts.c | 2 +-
drivers/leds/trigger/Kconfig | 2 +-
drivers/leds/trigger/ledtrig-transient.c | 2 +-
drivers/mtd/nand/raw/nand_ecc.c | 2 +-
drivers/net/ethernet/intel/ice/ice_main.c | 2 +-
drivers/nvdimm/Kconfig | 2 +-
drivers/platform/x86/Kconfig | 4 +-
drivers/tty/Kconfig | 2 +-
drivers/tty/serial/Kconfig | 2 +-
drivers/w1/Kconfig | 2 +-
include/linux/connector.h | 63 ++-
init/Kconfig | 2 +-
net/netfilter/Kconfig | 2 +-
samples/Kconfig | 2 +-
scripts/coccinelle/free/devm_free.cocci | 2 +-
usr/Kconfig | 2 +-
257 files changed, 7122 insertions(+), 5341 deletions(-)
rename Documentation/accounting/{cgroupstats.txt => cgroupstats.rst} (77%)
rename Documentation/accounting/{delay-accounting.txt => delay-accounting.rst} (77%)
create mode 100644 Documentation/accounting/index.rst
rename Documentation/accounting/{psi.txt => psi.rst} (91%)
rename Documentation/accounting/{taskstats-struct.txt => taskstats-struct.rst} (78%)
rename Documentation/accounting/{taskstats.txt => taskstats.rst} (95%)
delete mode 100644 Documentation/arm/Marvell/README
delete mode 100644 Documentation/arm/Netwinder
delete mode 100644 Documentation/arm/SA1100/FreeBird
delete mode 100644 Documentation/arm/SA1100/empeg
delete mode 100644 Documentation/arm/SA1100/serial_UART
rename Documentation/arm/{README => arm.rst} (88%)
rename Documentation/arm/{Booting => booting.rst} (89%)
rename Documentation/arm/{cluster-pm-race-avoidance.txt => cluster-pm-race-avoidance.rst} (84%)
rename Documentation/arm/{firmware.txt => firmware.rst} (86%)
create mode 100644 Documentation/arm/index.rst
rename Documentation/arm/{Interrupts => interrupts.rst} (81%)
rename Documentation/arm/{IXP4xx => ixp4xx.rst} (84%)
rename Documentation/arm/{kernel_mode_neon.txt => kernel_mode_neon.rst} (99%)
rename Documentation/arm/{kernel_user_helpers.txt => kernel_user_helpers.rst} (78%)
rename Documentation/arm/keystone/{knav-qmss.txt => knav-qmss.rst} (92%)
rename Documentation/arm/keystone/{Overview.txt => overview.rst} (59%)
create mode 100644 Documentation/arm/marvel.rst
rename Documentation/arm/{mem_alignment => mem_alignment.rst} (89%)
rename Documentation/arm/{memory.txt => memory.rst} (90%)
rename Documentation/arm/{Microchip/README => microchip.rst} (92%)
create mode 100644 Documentation/arm/netwinder.rst
create mode 100644 Documentation/arm/nwfpe/index.rst
rename Documentation/arm/nwfpe/{README.FPE => netwinder-fpe.rst} (94%)
rename Documentation/arm/nwfpe/{NOTES => notes.rst} (99%)
rename Documentation/arm/nwfpe/{README => nwfpe.rst} (98%)
rename Documentation/arm/nwfpe/{TODO => todo.rst} (75%)
rename Documentation/arm/{OMAP/DSS => omap/dss.rst} (86%)
create mode 100644 Documentation/arm/omap/index.rst
rename Documentation/arm/{OMAP/README => omap/omap.rst} (62%)
rename Documentation/arm/{OMAP/omap_pm => omap/omap_pm.rst} (83%)
rename Documentation/arm/{Porting => porting.rst} (94%)
rename Documentation/arm/pxa/{mfp.txt => mfp.rst} (83%)
rename Documentation/arm/{SA1100/ADSBitsy => sa1100/adsbitsy.rst} (90%)
rename Documentation/arm/{SA1100/Assabet => sa1100/assabet.rst} (62%)
rename Documentation/arm/{SA1100/Brutus => sa1100/brutus.rst} (75%)
rename Documentation/arm/{SA1100/CERF => sa1100/cerf.rst} (91%)
create mode 100644 Documentation/arm/sa1100/freebird.rst
rename Documentation/arm/{SA1100/GraphicsClient => sa1100/graphicsclient.rst} (87%)
rename Documentation/arm/{SA1100/GraphicsMaster => sa1100/graphicsmaster.rst} (92%)
rename Documentation/arm/{SA1100/HUW_WEBPANEL => sa1100/huw_webpanel.rst} (78%)
create mode 100644 Documentation/arm/sa1100/index.rst
rename Documentation/arm/{SA1100/Itsy => sa1100/itsy.rst} (88%)
rename Documentation/arm/{SA1100/LART => sa1100/lart.rst} (90%)
rename Documentation/arm/{SA1100/nanoEngine => sa1100/nanoengine.rst} (74%)
rename Documentation/arm/{SA1100/Pangolin => sa1100/pangolin.rst} (81%)
rename Documentation/arm/{SA1100/PLEB => sa1100/pleb.rst} (95%)
create mode 100644 Documentation/arm/sa1100/serial_uart.rst
rename Documentation/arm/{SA1100/Tifon => sa1100/tifon.rst} (88%)
rename Documentation/arm/{SA1100/Yopy => sa1100/yopy.rst} (74%)
rename Documentation/arm/{Samsung-S3C24XX/CPUfreq.txt => samsung-s3c24xx/cpufreq.rst} (96%)
rename Documentation/arm/{Samsung-S3C24XX/EB2410ITX.txt => samsung-s3c24xx/eb2410itx.rst} (92%)
rename Documentation/arm/{Samsung-S3C24XX/GPIO.txt => samsung-s3c24xx/gpio.rst} (89%)
rename Documentation/arm/{Samsung-S3C24XX/H1940.txt => samsung-s3c24xx/h1940.rst} (94%)
create mode 100644 Documentation/arm/samsung-s3c24xx/index.rst
rename Documentation/arm/{Samsung-S3C24XX/NAND.txt => samsung-s3c24xx/nand.rst} (92%)
rename Documentation/arm/{Samsung-S3C24XX/Overview.txt => samsung-s3c24xx/overview.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/S3C2412.txt => samsung-s3c24xx/s3c2412.rst} (96%)
rename Documentation/arm/{Samsung-S3C24XX/S3C2413.txt => samsung-s3c24xx/s3c2413.rst} (77%)
rename Documentation/arm/{Samsung-S3C24XX/SMDK2440.txt => samsung-s3c24xx/smdk2440.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/Suspend.txt => samsung-s3c24xx/suspend.rst} (94%)
rename Documentation/arm/{Samsung-S3C24XX/USB-Host.txt => samsung-s3c24xx/usb-host.rst} (94%)
rename Documentation/arm/{Samsung/Bootloader-interface.txt => samsung/bootloader-interface.rst} (72%)
rename Documentation/arm/{Samsung => samsung}/clksrc-change-registers.awk (100%)
rename Documentation/arm/{Samsung/GPIO.txt => samsung/gpio.rst} (87%)
create mode 100644 Documentation/arm/samsung/index.rst
rename Documentation/arm/{Samsung/Overview.txt => samsung/overview.rst} (86%)
rename Documentation/arm/{Setup => setup.rst} (87%)
rename Documentation/arm/{SH-Mobile => sh-mobile}/.gitignore (100%)
rename Documentation/arm/{SPEAr/overview.txt => spear/overview.rst} (91%)
rename Documentation/arm/sti/{overview.txt => overview.rst} (82%)
rename Documentation/arm/sti/{stih407-overview.txt => stih407-overview.rst} (82%)
rename Documentation/arm/sti/{stih415-overview.txt => stih415-overview.rst} (79%)
rename Documentation/arm/sti/{stih416-overview.txt => stih416-overview.rst} (83%)
rename Documentation/arm/sti/{stih418-overview.txt => stih418-overview.rst} (83%)
rename Documentation/arm/{sunxi/README => sunxi.rst} (83%)
rename Documentation/arm/sunxi/{clocks.txt => clocks.rst} (92%)
rename Documentation/arm/{swp_emulation => swp_emulation.rst} (63%)
rename Documentation/arm/{tcm.txt => tcm.rst} (86%)
rename Documentation/arm/{uefi.txt => uefi.rst} (63%)
rename Documentation/arm/{VFP/release-notes.txt => vfp/release-notes.rst} (92%)
rename Documentation/arm/{vlocks.txt => vlocks.rst} (98%)
rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%)
create mode 100644 Documentation/backlight/lp855x-driver.rst
delete mode 100644 Documentation/backlight/lp855x-driver.txt
rename Documentation/bus-devices/{ti-gpmc.txt => ti-gpmc.rst} (58%)
rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%)
rename Documentation/connector/{connector.txt => connector.rst} (57%)
rename Documentation/console/{console.txt => console.rst} (80%)
rename Documentation/driver-model/{binding.txt => binding.rst} (92%)
rename Documentation/driver-model/{bus.txt => bus.rst} (76%)
rename Documentation/driver-model/{class.txt => class.rst} (75%)
rename Documentation/driver-model/{design-patterns.txt => design-patterns.rst} (59%)
rename Documentation/driver-model/{device.txt => device.rst} (71%)
rename Documentation/driver-model/{devres.txt => devres.rst} (93%)
rename Documentation/driver-model/{driver.txt => driver.rst} (75%)
create mode 100644 Documentation/driver-model/index.rst
rename Documentation/driver-model/{overview.txt => overview.rst} (90%)
rename Documentation/driver-model/{platform.txt => platform.rst} (95%)
rename Documentation/driver-model/{porting.txt => porting.rst} (62%)
rename Documentation/early-userspace/{buffer-format.txt => buffer-format.rst} (91%)
rename Documentation/early-userspace/{README => early_userspace_support.rst} (99%)
create mode 100644 Documentation/early-userspace/index.rst
rename Documentation/ia64/{aliasing.txt => aliasing.rst} (83%)
rename Documentation/ia64/{efirtc.txt => efirtc.rst} (70%)
rename Documentation/ia64/{err_inject.txt => err_inject.rst} (82%)
rename Documentation/ia64/{fsys.txt => fsys.rst} (76%)
rename Documentation/ia64/{README => ia64.rst} (61%)
create mode 100644 Documentation/ia64/index.rst
rename Documentation/ia64/{IRQ-redir.txt => irq-redir.rst} (86%)
rename Documentation/ia64/{mca.txt => mca.rst} (96%)
rename Documentation/ia64/{serial.txt => serial.rst} (87%)
create mode 100644 Documentation/ia64/xen.rst
delete mode 100644 Documentation/ia64/xen.txt
rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
create mode 100644 Documentation/iio/index.rst
rename Documentation/laptops/{asus-laptop.txt => asus-laptop.rst} (84%)
rename Documentation/laptops/{disk-shock-protection.txt => disk-shock-protection.rst} (91%)
create mode 100644 Documentation/laptops/index.rst
rename Documentation/laptops/{laptop-mode.txt => laptop-mode.rst} (62%)
rename Documentation/laptops/{sony-laptop.txt => sony-laptop.rst} (85%)
rename Documentation/laptops/{sonypi.txt => sonypi.rst} (87%)
rename Documentation/laptops/{thinkpad-acpi.txt => thinkpad-acpi.rst} (89%)
rename Documentation/laptops/{toshiba_haps.txt => toshiba_haps.rst} (60%)
create mode 100644 Documentation/leds/index.rst
rename Documentation/leds/{leds-blinkm.txt => leds-blinkm.rst} (57%)
rename Documentation/leds/{leds-class-flash.txt => leds-class-flash.rst} (74%)
rename Documentation/leds/{leds-class.txt => leds-class.rst} (92%)
rename Documentation/leds/{leds-lm3556.txt => leds-lm3556.rst} (70%)
rename Documentation/leds/{leds-lp3944.txt => leds-lp3944.rst} (78%)
create mode 100644 Documentation/leds/leds-lp5521.rst
delete mode 100644 Documentation/leds/leds-lp5521.txt
create mode 100644 Documentation/leds/leds-lp5523.rst
delete mode 100644 Documentation/leds/leds-lp5523.txt
create mode 100644 Documentation/leds/leds-lp5562.rst
delete mode 100644 Documentation/leds/leds-lp5562.txt
create mode 100644 Documentation/leds/leds-lp55xx.rst
delete mode 100644 Documentation/leds/leds-lp55xx.txt
create mode 100644 Documentation/leds/leds-mlxcpld.rst
delete mode 100644 Documentation/leds/leds-mlxcpld.txt
rename Documentation/leds/{ledtrig-oneshot.txt => ledtrig-oneshot.rst} (90%)
rename Documentation/leds/{ledtrig-transient.txt => ledtrig-transient.rst} (81%)
rename Documentation/leds/{ledtrig-usbport.txt => ledtrig-usbport.rst} (86%)
rename Documentation/leds/{uleds.txt => uleds.rst} (95%)
create mode 100644 Documentation/m68k/index.rst
rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%)
create mode 100644 Documentation/md/index.rst
rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)
rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%)
create mode 100644 Documentation/mmc/index.rst
rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%)
rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%)
rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%)
rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%)
create mode 100644 Documentation/mtd/index.rst
rename Documentation/mtd/{intel-spi.txt => intel-spi.rst} (71%)
rename Documentation/mtd/{nand_ecc.txt => nand_ecc.rst} (67%)
rename Documentation/mtd/{spi-nor.txt => spi-nor.rst} (94%)
rename Documentation/namespaces/{compatibility-list.txt => compatibility-list.rst} (86%)
create mode 100644 Documentation/namespaces/index.rst
rename Documentation/namespaces/{resource-control.txt => resource-control.rst} (89%)
create mode 100644 Documentation/nfc/index.rst
rename Documentation/nfc/{nfc-hci.txt => nfc-hci.rst} (71%)
rename Documentation/nfc/{nfc-pn544.txt => nfc-pn544.rst} (82%)
rename Documentation/nvdimm/{btt.txt => btt.rst} (71%)
create mode 100644 Documentation/nvdimm/index.rst
rename Documentation/nvdimm/{nvdimm.txt => nvdimm.rst} (60%)
rename Documentation/nvdimm/{security.txt => security.rst} (99%)
rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)
rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%)
create mode 100644 Documentation/pti/pti_intel_mid.rst
delete mode 100644 Documentation/pti/pti_intel_mid.txt
rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)
rename Documentation/xtensa/{atomctl.txt => atomctl.rst} (81%)
rename Documentation/xtensa/{booting.txt => booting.rst} (91%)
create mode 100644 Documentation/xtensa/index.rst
create mode 100644 Documentation/xtensa/mmu.rst
delete mode 100644 Documentation/xtensa/mmu.txt
--
2.21.0
Rename the ia64 documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
There are two upper case file names. Rename them to
lower case, as we're working to avoid upper case file
names at Documentation.
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 <[email protected]>
---
.../ia64/{aliasing.txt => aliasing.rst} | 73 ++--
Documentation/ia64/{efirtc.txt => efirtc.rst} | 118 +++---
.../ia64/{err_inject.txt => err_inject.rst} | 349 +++++++++---------
Documentation/ia64/{fsys.txt => fsys.rst} | 127 ++++---
Documentation/ia64/{README => ia64.rst} | 26 +-
Documentation/ia64/index.rst | 18 +
.../ia64/{IRQ-redir.txt => irq-redir.rst} | 31 +-
Documentation/ia64/{mca.txt => mca.rst} | 10 +-
Documentation/ia64/{serial.txt => serial.rst} | 36 +-
Documentation/ia64/xen.rst | 206 +++++++++++
Documentation/ia64/xen.txt | 183 ---------
MAINTAINERS | 2 +-
arch/ia64/kernel/efi.c | 2 +-
arch/ia64/kernel/fsys.S | 2 +-
arch/ia64/mm/ioremap.c | 2 +-
arch/ia64/pci/pci.c | 2 +-
16 files changed, 660 insertions(+), 527 deletions(-)
rename Documentation/ia64/{aliasing.txt => aliasing.rst} (83%)
rename Documentation/ia64/{efirtc.txt => efirtc.rst} (70%)
rename Documentation/ia64/{err_inject.txt => err_inject.rst} (82%)
rename Documentation/ia64/{fsys.txt => fsys.rst} (76%)
rename Documentation/ia64/{README => ia64.rst} (61%)
create mode 100644 Documentation/ia64/index.rst
rename Documentation/ia64/{IRQ-redir.txt => irq-redir.rst} (86%)
rename Documentation/ia64/{mca.txt => mca.rst} (96%)
rename Documentation/ia64/{serial.txt => serial.rst} (87%)
create mode 100644 Documentation/ia64/xen.rst
delete mode 100644 Documentation/ia64/xen.txt
diff --git a/Documentation/ia64/aliasing.txt b/Documentation/ia64/aliasing.rst
similarity index 83%
rename from Documentation/ia64/aliasing.txt
rename to Documentation/ia64/aliasing.rst
index 5a4dea6abebd..a08b36aba015 100644
--- a/Documentation/ia64/aliasing.txt
+++ b/Documentation/ia64/aliasing.rst
@@ -1,20 +1,25 @@
- MEMORY ATTRIBUTE ALIASING ON IA-64
+==================================
+Memory Attribute Aliasing on IA-64
+==================================
- Bjorn Helgaas
- <[email protected]>
- May 4, 2006
+Bjorn Helgaas <[email protected]>
+May 4, 2006
-MEMORY ATTRIBUTES
+
+Memory Attributes
+=================
Itanium supports several attributes for virtual memory references.
The attribute is part of the virtual translation, i.e., it is
contained in the TLB entry. The ones of most interest to the Linux
kernel are:
- WB Write-back (cacheable)
+ == ======================
+ WB Write-back (cacheable)
UC Uncacheable
WC Write-coalescing
+ == ======================
System memory typically uses the WB attribute. The UC attribute is
used for memory-mapped I/O devices. The WC attribute is uncacheable
@@ -29,7 +34,8 @@ MEMORY ATTRIBUTES
support either WB or UC access to main memory, while others support
only WB access.
-MEMORY MAP
+Memory Map
+==========
Platform firmware describes the physical memory map and the
supported attributes for each region. At boot-time, the kernel uses
@@ -55,7 +61,8 @@ MEMORY MAP
The efi_memmap table is preserved unmodified because the original
boot-time information is required for kexec.
-KERNEL IDENTITY MAPPINGS
+Kernel Identify Mappings
+========================
Linux/ia64 identity mappings are done with large pages, currently
either 16MB or 64MB, referred to as "granules." Cacheable mappings
@@ -74,17 +81,20 @@ KERNEL IDENTITY MAPPINGS
are only partially populated, or populated with a combination of UC
and WB regions.
-USER MAPPINGS
+User Mappings
+=============
User mappings are typically done with 16K or 64K pages. The smaller
page size allows more flexibility because only 16K or 64K has to be
homogeneous with respect to memory attributes.
-POTENTIAL ATTRIBUTE ALIASING CASES
+Potential Attribute Aliasing Cases
+==================================
There are several ways the kernel creates new mappings:
- mmap of /dev/mem
+mmap of /dev/mem
+----------------
This uses remap_pfn_range(), which creates user mappings. These
mappings may be either WB or UC. If the region being mapped
@@ -98,7 +108,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
Since the EFI memory map does not describe MMIO on some
machines, this should use an uncacheable mapping as a fallback.
- mmap of /sys/class/pci_bus/.../legacy_mem
+mmap of /sys/class/pci_bus/.../legacy_mem
+-----------------------------------------
This is very similar to mmap of /dev/mem, except that legacy_mem
only allows mmap of the one megabyte "legacy MMIO" area for a
@@ -112,9 +123,10 @@ POTENTIAL ATTRIBUTE ALIASING CASES
The /dev/mem mmap constraints apply.
- mmap of /proc/bus/pci/.../??.?
+mmap of /proc/bus/pci/.../??.?
+------------------------------
- This is an MMIO mmap of PCI functions, which additionally may or
+ This is an MMIO mmap of PCI functions, which additionally may or
may not be requested as using the WC attribute.
If WC is requested, and the region in kern_memmap is either WC
@@ -124,7 +136,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
Otherwise, the user mapping must use the same attribute as the
kernel mapping.
- read/write of /dev/mem
+read/write of /dev/mem
+----------------------
This uses copy_from_user(), which implicitly uses a kernel
identity mapping. This is obviously safe for things in
@@ -138,7 +151,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
eight-byte accesses, and the copy_from_user() path doesn't allow
any control over the access size, so this would be dangerous.
- ioremap()
+ioremap()
+---------
This returns a mapping for use inside the kernel.
@@ -155,9 +169,11 @@ POTENTIAL ATTRIBUTE ALIASING CASES
Failing all of the above, we have to fall back to a UC mapping.
-PAST PROBLEM CASES
+Past Problem Cases
+==================
- mmap of various MMIO regions from /dev/mem by "X" on Intel platforms
+mmap of various MMIO regions from /dev/mem by "X" on Intel platforms
+--------------------------------------------------------------------
The EFI memory map may not report these MMIO regions.
@@ -166,12 +182,16 @@ PAST PROBLEM CASES
succeed. It may create either WB or UC user mappings, depending
on whether the region is in kern_memmap or the EFI memory map.
- mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled
+mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled
+----------------------------------------------------------------------
The EFI memory map reports the following attributes:
+
+ =============== ======= ==================
0x00000-0x9FFFF WB only
0xA0000-0xBFFFF UC only (VGA frame buffer)
0xC0000-0xFFFFF WB only
+ =============== ======= ==================
This mmap is done with user pages, not kernel identity mappings,
so it is safe to use WB mappings.
@@ -182,7 +202,8 @@ PAST PROBLEM CASES
never generate an uncacheable reference to the WB-only areas unless
the driver explicitly touches them.
- mmap of 0x0-0xFFFFF legacy_mem by "X"
+mmap of 0x0-0xFFFFF legacy_mem by "X"
+-------------------------------------
If the EFI memory map reports that the entire range supports the
same attributes, we can allow the mmap (and we will prefer WB if
@@ -197,15 +218,18 @@ PAST PROBLEM CASES
that doesn't report the VGA frame buffer at all), we should fail the
mmap and force the user to map just the specific region of interest.
- mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled
+mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled
+------------------------------------------------------------------------
+
+ The EFI memory map reports the following attributes::
- The EFI memory map reports the following attributes:
0x00000-0xFFFFF WB only (no VGA MMIO hole)
This is a special case of the previous case, and the mmap should
fail for the same reason as above.
- read of /sys/devices/.../rom
+read of /sys/devices/.../rom
+----------------------------
For VGA devices, this may cause an ioremap() of 0xC0000. This
used to be done with a UC mapping, because the VGA frame buffer
@@ -215,7 +239,8 @@ PAST PROBLEM CASES
We should use WB page table mappings to avoid covering the VGA
frame buffer.
-NOTES
+Notes
+=====
[1] SDM rev 2.2, vol 2, sec 4.4.1.
[2] SDM rev 2.2, vol 2, sec 4.4.6.
diff --git a/Documentation/ia64/efirtc.txt b/Documentation/ia64/efirtc.rst
similarity index 70%
rename from Documentation/ia64/efirtc.txt
rename to Documentation/ia64/efirtc.rst
index 057e6bebda8f..2f7ff5026308 100644
--- a/Documentation/ia64/efirtc.txt
+++ b/Documentation/ia64/efirtc.rst
@@ -1,12 +1,16 @@
+==========================
EFI Real Time Clock driver
--------------------------------
+==========================
+
S. Eranian <[email protected]>
+
March 2000
-I/ Introduction
+1. Introduction
+===============
This document describes the efirtc.c driver has provided for
-the IA-64 platform.
+the IA-64 platform.
The purpose of this driver is to supply an API for kernel and user applications
to get access to the Time Service offered by EFI version 0.92.
@@ -16,112 +20,124 @@ SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this
driver. We describe those calls as well the design of the driver in the
following sections.
-II/ Design Decisions
+2. Design Decisions
+===================
-The original ideas was to provide a very simple driver to get access to,
-at first, the time of day service. This is required in order to access, in a
-portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock
+The original ideas was to provide a very simple driver to get access to,
+at first, the time of day service. This is required in order to access, in a
+portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock
to initialize the system view of the time during boot.
Because we wanted to minimize the impact on existing user-level apps using
the CMOS clock, we decided to expose an API that was very similar to the one
-used today with the legacy RTC driver (driver/char/rtc.c). However, because
+used today with the legacy RTC driver (driver/char/rtc.c). However, because
EFI provides a simpler services, not all ioctl() are available. Also
-new ioctl()s have been introduced for things that EFI provides but not the
+new ioctl()s have been introduced for things that EFI provides but not the
legacy.
EFI uses a slightly different way of representing the time, noticeably
the reference date is different. Year is the using the full 4-digit format.
The Epoch is January 1st 1998. For backward compatibility reasons we don't
-expose this new way of representing time. Instead we use something very
+expose this new way of representing time. Instead we use something very
similar to the struct tm, i.e. struct rtc_time, as used by hwclock.
One of the reasons for doing it this way is to allow for EFI to still evolve
without necessarily impacting any of the user applications. The decoupling
enables flexibility and permits writing wrapper code is ncase things change.
The driver exposes two interfaces, one via the device file and a set of
-ioctl()s. The other is read-only via the /proc filesystem.
+ioctl()s. The other is read-only via the /proc filesystem.
As of today we don't offer a /proc/sys interface.
To allow for a uniform interface between the legacy RTC and EFI time service,
-we have created the include/linux/rtc.h header file to contain only the
-"public" API of the two drivers. The specifics of the legacy RTC are still
+we have created the include/linux/rtc.h header file to contain only the
+"public" API of the two drivers. The specifics of the legacy RTC are still
in include/linux/mc146818rtc.h.
-
-III/ Time of day service
+
+3. Time of day service
+======================
The part of the driver gives access to the time of day service of EFI.
Two ioctl()s, compatible with the legacy RTC calls:
- Read the CMOS clock: ioctl(d, RTC_RD_TIME, &rtc);
+ Read the CMOS clock::
- Write the CMOS clock: ioctl(d, RTC_SET_TIME, &rtc);
+ ioctl(d, RTC_RD_TIME, &rtc);
+
+ Write the CMOS clock::
+
+ ioctl(d, RTC_SET_TIME, &rtc);
The rtc is a pointer to a data structure defined in rtc.h which is close
-to a struct tm:
+to a struct tm::
-struct rtc_time {
- int tm_sec;
- int tm_min;
- int tm_hour;
- int tm_mday;
- int tm_mon;
- int tm_year;
- int tm_wday;
- int tm_yday;
- int tm_isdst;
-};
+ struct rtc_time {
+ int tm_sec;
+ int tm_min;
+ int tm_hour;
+ int tm_mday;
+ int tm_mon;
+ int tm_year;
+ int tm_wday;
+ int tm_yday;
+ int tm_isdst;
+ };
The driver takes care of converting back an forth between the EFI time and
this format.
Those two ioctl()s can be exercised with the hwclock command:
-For reading:
-# /sbin/hwclock --show
-Mon Mar 6 15:32:32 2000 -0.910248 seconds
+For reading::
-For setting:
-# /sbin/hwclock --systohc
+ # /sbin/hwclock --show
+ Mon Mar 6 15:32:32 2000 -0.910248 seconds
+
+For setting::
+
+ # /sbin/hwclock --systohc
Root privileges are required to be able to set the time of day.
-IV/ Wakeup Alarm service
+4. Wakeup Alarm service
+=======================
EFI provides an API by which one can program when a machine should wakeup,
i.e. reboot. This is very different from the alarm provided by the legacy
RTC which is some kind of interval timer alarm. For this reason we don't use
the same ioctl()s to get access to the service. Instead we have
-introduced 2 news ioctl()s to the interface of an RTC.
+introduced 2 news ioctl()s to the interface of an RTC.
We have added 2 new ioctl()s that are specific to the EFI driver:
- Read the current state of the alarm
- ioctl(d, RTC_WKLAM_RD, &wkt)
+ Read the current state of the alarm::
- Set the alarm or change its status
- ioctl(d, RTC_WKALM_SET, &wkt)
+ ioctl(d, RTC_WKLAM_RD, &wkt)
-The wkt structure encapsulates a struct rtc_time + 2 extra fields to get
-status information:
-
-struct rtc_wkalrm {
+ Set the alarm or change its status::
- unsigned char enabled; /* =1 if alarm is enabled */
- unsigned char pending; /* =1 if alarm is pending */
+ ioctl(d, RTC_WKALM_SET, &wkt)
- struct rtc_time time;
-}
+The wkt structure encapsulates a struct rtc_time + 2 extra fields to get
+status information::
+
+ struct rtc_wkalrm {
+
+ unsigned char enabled; /* =1 if alarm is enabled */
+ unsigned char pending; /* =1 if alarm is pending */
+
+ struct rtc_time time;
+ }
As of today, none of the existing user-level apps supports this feature.
-However writing such a program should be hard by simply using those two
-ioctl().
+However writing such a program should be hard by simply using those two
+ioctl().
Root privileges are required to be able to set the alarm.
-V/ References.
+5. References
+=============
Checkout the following Web site for more information on EFI:
diff --git a/Documentation/ia64/err_inject.txt b/Documentation/ia64/err_inject.rst
similarity index 82%
rename from Documentation/ia64/err_inject.txt
rename to Documentation/ia64/err_inject.rst
index 9f651c181429..900f71e93a29 100644
--- a/Documentation/ia64/err_inject.txt
+++ b/Documentation/ia64/err_inject.rst
@@ -1,4 +1,4 @@
-
+========================================
IPF Machine Check (MC) error inject tool
========================================
@@ -32,94 +32,94 @@ Errata: Itanium 2 Processors Specification Update lists some errata against
the pal_mc_error_inject PAL procedure. The following err.conf has been tested
on latest Montecito PAL.
-err.conf:
+err.conf::
-#This is configuration file for err_inject_tool.
-#The format of the each line is:
-#cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer
-#where
-# cpu: logical cpu number the error will be inject in.
-# loop: times the error will be injected.
-# interval: In second. every so often one error is injected.
-# err_type_info, err_struct_info: PAL parameters.
-#
-#Note: All values are hex w/o or w/ 0x prefix.
+ #This is configuration file for err_inject_tool.
+ #The format of the each line is:
+ #cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer
+ #where
+ # cpu: logical cpu number the error will be inject in.
+ # loop: times the error will be injected.
+ # interval: In second. every so often one error is injected.
+ # err_type_info, err_struct_info: PAL parameters.
+ #
+ #Note: All values are hex w/o or w/ 0x prefix.
-#On cpu2, inject only total 0x10 errors, interval 5 seconds
-#corrected, data cache, hier-2, physical addr(assigned by tool code).
-#working on Montecito latest PAL.
-2, 10, 5, 4101, 95
+ #On cpu2, inject only total 0x10 errors, interval 5 seconds
+ #corrected, data cache, hier-2, physical addr(assigned by tool code).
+ #working on Montecito latest PAL.
+ 2, 10, 5, 4101, 95
-#On cpu4, inject and consume total 0x10 errors, interval 5 seconds
-#corrected, data cache, hier-2, physical addr(assigned by tool code).
-#working on Montecito latest PAL.
-4, 10, 5, 4109, 95
+ #On cpu4, inject and consume total 0x10 errors, interval 5 seconds
+ #corrected, data cache, hier-2, physical addr(assigned by tool code).
+ #working on Montecito latest PAL.
+ 4, 10, 5, 4109, 95
-#On cpu15, inject and consume total 0x10 errors, interval 5 seconds
-#recoverable, DTR0, hier-2.
-#working on Montecito latest PAL.
-0xf, 0x10, 5, 4249, 15
+ #On cpu15, inject and consume total 0x10 errors, interval 5 seconds
+ #recoverable, DTR0, hier-2.
+ #working on Montecito latest PAL.
+ 0xf, 0x10, 5, 4249, 15
The sample application source code:
-err_injection_tool.c:
+err_injection_tool.c::
-/*
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
- * NON INFRINGEMENT. See the GNU General Public License for more
- * details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * Copyright (C) 2006 Intel Co
- * Fenghua Yu <[email protected]>
- *
- */
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#include <stdio.h>
-#include <sched.h>
-#include <unistd.h>
-#include <stdlib.h>
-#include <stdarg.h>
-#include <string.h>
-#include <errno.h>
-#include <time.h>
-#include <sys/ipc.h>
-#include <sys/sem.h>
-#include <sys/wait.h>
-#include <sys/mman.h>
-#include <sys/shm.h>
+ /*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
+ * NON INFRINGEMENT. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ *
+ * Copyright (C) 2006 Intel Co
+ * Fenghua Yu <[email protected]>
+ *
+ */
+ #include <sys/types.h>
+ #include <sys/stat.h>
+ #include <fcntl.h>
+ #include <stdio.h>
+ #include <sched.h>
+ #include <unistd.h>
+ #include <stdlib.h>
+ #include <stdarg.h>
+ #include <string.h>
+ #include <errno.h>
+ #include <time.h>
+ #include <sys/ipc.h>
+ #include <sys/sem.h>
+ #include <sys/wait.h>
+ #include <sys/mman.h>
+ #include <sys/shm.h>
-#define MAX_FN_SIZE 256
-#define MAX_BUF_SIZE 256
-#define DATA_BUF_SIZE 256
-#define NR_CPUS 512
-#define MAX_TASK_NUM 2048
-#define MIN_INTERVAL 5 // seconds
-#define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte.
-#define PARA_FIELD_NUM 5
-#define MASK_SIZE (NR_CPUS/64)
-#define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/"
+ #define MAX_FN_SIZE 256
+ #define MAX_BUF_SIZE 256
+ #define DATA_BUF_SIZE 256
+ #define NR_CPUS 512
+ #define MAX_TASK_NUM 2048
+ #define MIN_INTERVAL 5 // seconds
+ #define ERR_DATA_BUFFER_SIZE 3 // Three 8-byte.
+ #define PARA_FIELD_NUM 5
+ #define MASK_SIZE (NR_CPUS/64)
+ #define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/"
-int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask);
+ int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask);
-int verbose;
-#define vbprintf if (verbose) printf
+ int verbose;
+ #define vbprintf if (verbose) printf
-int log_info(int cpu, const char *fmt, ...)
-{
+ int log_info(int cpu, const char *fmt, ...)
+ {
FILE *log;
char fn[MAX_FN_SIZE];
char buf[MAX_BUF_SIZE];
@@ -142,12 +142,12 @@ int log_info(int cpu, const char *fmt, ...)
fclose(log);
return 0;
-}
+ }
-typedef unsigned long u64;
-typedef unsigned int u32;
+ typedef unsigned long u64;
+ typedef unsigned int u32;
-typedef union err_type_info_u {
+ typedef union err_type_info_u {
struct {
u64 mode : 3, /* 0-2 */
err_inj : 3, /* 3-5 */
@@ -157,9 +157,9 @@ typedef union err_type_info_u {
reserved : 48; /* 16-63 */
} err_type_info_u;
u64 err_type_info;
-} err_type_info_t;
+ } err_type_info_t;
-typedef union err_struct_info_u {
+ typedef union err_struct_info_u {
struct {
u64 siv : 1, /* 0 */
c_t : 2, /* 1-2 */
@@ -197,9 +197,9 @@ typedef union err_struct_info_u {
u64 reserved;
} err_struct_info_bus_processor_interconnect;
u64 err_struct_info;
-} err_struct_info_t;
+ } err_struct_info_t;
-typedef union err_data_buffer_u {
+ typedef union err_data_buffer_u {
struct {
u64 trigger_addr; /* 0-63 */
u64 inj_addr; /* 64-127 */
@@ -221,9 +221,9 @@ typedef union err_data_buffer_u {
u64 reserved; /* 0-63 */
} err_data_buffer_bus_processor_interconnect;
u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
-} err_data_buffer_t;
+ } err_data_buffer_t;
-typedef union capabilities_u {
+ typedef union capabilities_u {
struct {
u64 i : 1,
d : 1,
@@ -276,9 +276,9 @@ typedef union capabilities_u {
struct {
u64 reserved;
} capabilities_bus_processor_interconnect;
-} capabilities_t;
+ } capabilities_t;
-typedef struct resources_s {
+ typedef struct resources_s {
u64 ibr0 : 1,
ibr2 : 1,
ibr4 : 1,
@@ -288,24 +288,24 @@ typedef struct resources_s {
dbr4 : 1,
dbr6 : 1,
reserved : 48;
-} resources_t;
+ } resources_t;
-long get_page_size(void)
-{
+ long get_page_size(void)
+ {
long page_size=sysconf(_SC_PAGESIZE);
return page_size;
-}
+ }
-#define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size())
-#define SHM_SIZE (2*PAGE_SIZE*NR_CPUS)
-#define SHM_VA 0x2000000100000000
+ #define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size())
+ #define SHM_SIZE (2*PAGE_SIZE*NR_CPUS)
+ #define SHM_VA 0x2000000100000000
-int shmid;
-void *shmaddr;
+ int shmid;
+ void *shmaddr;
-int create_shm(void)
-{
+ int create_shm(void)
+ {
key_t key;
char fn[MAX_FN_SIZE];
@@ -343,34 +343,34 @@ int create_shm(void)
mlock(shmaddr, SHM_SIZE);
return 0;
-}
+ }
-int free_shm()
-{
+ int free_shm()
+ {
munlock(shmaddr, SHM_SIZE);
- shmdt(shmaddr);
+ shmdt(shmaddr);
semctl(shmid, 0, IPC_RMID);
return 0;
-}
+ }
-#ifdef _SEM_SEMUN_UNDEFINED
-union semun
-{
+ #ifdef _SEM_SEMUN_UNDEFINED
+ union semun
+ {
int val;
struct semid_ds *buf;
unsigned short int *array;
struct seminfo *__buf;
-};
-#endif
+ };
+ #endif
-u32 mode=1; /* 1: physical mode; 2: virtual mode. */
-int one_lock=1;
-key_t key[NR_CPUS];
-int semid[NR_CPUS];
+ u32 mode=1; /* 1: physical mode; 2: virtual mode. */
+ int one_lock=1;
+ key_t key[NR_CPUS];
+ int semid[NR_CPUS];
-int create_sem(int cpu)
-{
+ int create_sem(int cpu)
+ {
union semun arg;
char fn[MAX_FN_SIZE];
int sid;
@@ -407,37 +407,37 @@ int create_sem(int cpu)
}
return 0;
-}
+ }
-static int lock(int cpu)
-{
+ static int lock(int cpu)
+ {
struct sembuf lock;
lock.sem_num = cpu;
lock.sem_op = 1;
semop(semid[cpu], &lock, 1);
- return 0;
-}
+ return 0;
+ }
-static int unlock(int cpu)
-{
+ static int unlock(int cpu)
+ {
struct sembuf unlock;
unlock.sem_num = cpu;
unlock.sem_op = -1;
semop(semid[cpu], &unlock, 1);
- return 0;
-}
+ return 0;
+ }
-void free_sem(int cpu)
-{
+ void free_sem(int cpu)
+ {
semctl(semid[cpu], 0, IPC_RMID);
-}
+ }
-int wr_multi(char *fn, unsigned long *data, int size)
-{
+ int wr_multi(char *fn, unsigned long *data, int size)
+ {
int fd;
char buf[MAX_BUF_SIZE];
int ret;
@@ -459,15 +459,15 @@ int wr_multi(char *fn, unsigned long *data, int size)
ret=write(fd, buf, sizeof(buf));
close(fd);
return ret;
-}
+ }
-int wr(char *fn, unsigned long data)
-{
+ int wr(char *fn, unsigned long data)
+ {
return wr_multi(fn, &data, 1);
-}
+ }
-int rd(char *fn, unsigned long *data)
-{
+ int rd(char *fn, unsigned long *data)
+ {
int fd;
char buf[MAX_BUF_SIZE];
@@ -480,10 +480,10 @@ int rd(char *fn, unsigned long *data)
*data=strtoul(buf, NULL, 16);
close(fd);
return 0;
-}
+ }
-int rd_status(char *path, int *status)
-{
+ int rd_status(char *path, int *status)
+ {
char fn[MAX_FN_SIZE];
sprintf(fn, "%s/status", path);
if (rd(fn, (u64*)status)<0) {
@@ -492,10 +492,10 @@ int rd_status(char *path, int *status)
}
return 0;
-}
+ }
-int rd_capabilities(char *path, u64 *capabilities)
-{
+ int rd_capabilities(char *path, u64 *capabilities)
+ {
char fn[MAX_FN_SIZE];
sprintf(fn, "%s/capabilities", path);
if (rd(fn, capabilities)<0) {
@@ -504,10 +504,10 @@ int rd_capabilities(char *path, u64 *capabilities)
}
return 0;
-}
+ }
-int rd_all(char *path)
-{
+ int rd_all(char *path)
+ {
unsigned long err_type_info, err_struct_info, err_data_buffer;
int status;
unsigned long capabilities, resources;
@@ -556,11 +556,11 @@ int rd_all(char *path)
printf("resources=%lx\n", resources);
return 0;
-}
+ }
-int query_capabilities(char *path, err_type_info_t err_type_info,
+ int query_capabilities(char *path, err_type_info_t err_type_info,
u64 *capabilities)
-{
+ {
char fn[MAX_FN_SIZE];
err_struct_info_t err_struct_info;
err_data_buffer_t err_data_buffer;
@@ -583,10 +583,10 @@ int query_capabilities(char *path, err_type_info_t err_type_info,
return -1;
return 0;
-}
+ }
-int query_all_capabilities()
-{
+ int query_all_capabilities()
+ {
int status;
err_type_info_t err_type_info;
int err_sev, err_struct, struct_hier;
@@ -629,12 +629,12 @@ int query_all_capabilities()
}
return 0;
-}
+ }
-int err_inject(int cpu, char *path, err_type_info_t err_type_info,
+ int err_inject(int cpu, char *path, err_type_info_t err_type_info,
err_struct_info_t err_struct_info,
err_data_buffer_t err_data_buffer)
-{
+ {
int status;
char fn[MAX_FN_SIZE];
@@ -667,13 +667,13 @@ int err_inject(int cpu, char *path, err_type_info_t err_type_info,
}
return status;
-}
+ }
-static int construct_data_buf(char *path, err_type_info_t err_type_info,
+ static int construct_data_buf(char *path, err_type_info_t err_type_info,
err_struct_info_t err_struct_info,
err_data_buffer_t *err_data_buffer,
void *va1)
-{
+ {
char fn[MAX_FN_SIZE];
u64 virt_addr=0, phys_addr=0;
@@ -710,22 +710,22 @@ static int construct_data_buf(char *path, err_type_info_t err_type_info,
}
return 0;
-}
+ }
-typedef struct {
+ typedef struct {
u64 cpu;
u64 loop;
u64 interval;
u64 err_type_info;
u64 err_struct_info;
u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
-} parameters_t;
+ } parameters_t;
-parameters_t line_para;
-int para;
+ parameters_t line_para;
+ int para;
-static int empty_data_buffer(u64 *err_data_buffer)
-{
+ static int empty_data_buffer(u64 *err_data_buffer)
+ {
int empty=1;
int i;
@@ -734,10 +734,10 @@ static int empty_data_buffer(u64 *err_data_buffer)
empty=0;
return empty;
-}
+ }
-int err_inj()
-{
+ int err_inj()
+ {
err_type_info_t err_type_info;
err_struct_info_t err_struct_info;
err_data_buffer_t err_data_buffer;
@@ -951,10 +951,10 @@ int err_inj()
printf("All done.\n");
return 0;
-}
+ }
-void help()
-{
+ void help()
+ {
printf("err_inject_tool:\n");
printf("\t-q: query all capabilities. default: off\n");
printf("\t-m: procedure mode. 1: physical 2: virtual. default: 1\n");
@@ -977,10 +977,10 @@ void help()
printf("The tool will take err.conf file as ");
printf("input to inject single or multiple errors ");
printf("on one or multiple cpus in parallel.\n");
-}
+ }
-int main(int argc, char **argv)
-{
+ int main(int argc, char **argv)
+ {
char c;
int do_err_inj=0;
int do_query_all=0;
@@ -1031,7 +1031,7 @@ int main(int argc, char **argv)
if (count!=PARA_FIELD_NUM+3) {
line_para.err_data_buffer[0]=-1,
line_para.err_data_buffer[1]=-1,
- line_para.err_data_buffer[2]=-1;
+ line_para.err_data_buffer[2]=-1;
count=sscanf(optarg, "%lx, %lx, %lx, %lx, %lx\n",
&line_para.cpu,
&line_para.loop,
@@ -1064,5 +1064,4 @@ int main(int argc, char **argv)
help();
return 0;
-}
-
+ }
diff --git a/Documentation/ia64/fsys.txt b/Documentation/ia64/fsys.rst
similarity index 76%
rename from Documentation/ia64/fsys.txt
rename to Documentation/ia64/fsys.rst
index 59dd689d9b86..a702d2cc94b6 100644
--- a/Documentation/ia64/fsys.txt
+++ b/Documentation/ia64/fsys.rst
@@ -1,9 +1,9 @@
--*-Mode: outline-*-
-
- Light-weight System Calls for IA-64
- -----------------------------------
+===================================
+Light-weight System Calls for IA-64
+===================================
Started: 13-Jan-2003
+
Last update: 27-Sep-2003
David Mosberger-Tang
@@ -52,12 +52,13 @@ privilege level is at level 0, this means that fsys-mode requires some
care (see below).
-* How to tell fsys-mode
+How to tell fsys-mode
+=====================
Linux operates in fsys-mode when (a) the privilege level is 0 (most
privileged) and (b) the stacks have NOT been switched to kernel memory
yet. For convenience, the header file <asm-ia64/ptrace.h> provides
-three macros:
+three macros::
user_mode(regs)
user_stack(task,regs)
@@ -70,11 +71,12 @@ to by "regs" was executing in user mode (privilege level 3).
user_stack() returns TRUE if the state pointed to by "regs" was
executing on the user-level stack(s). Finally, fsys_mode() returns
TRUE if the CPU state pointed to by "regs" was executing in fsys-mode.
-The fsys_mode() macro is equivalent to the expression:
+The fsys_mode() macro is equivalent to the expression::
!user_mode(regs) && user_stack(task,regs)
-* How to write an fsyscall handler
+How to write an fsyscall handler
+================================
The file arch/ia64/kernel/fsys.S contains a table of fsyscall-handlers
(fsyscall_table). This table contains one entry for each system call.
@@ -87,66 +89,72 @@ of the getpid() system call.
The entry and exit-state of an fsyscall handler is as follows:
-** Machine state on entry to fsyscall handler:
+Machine state on entry to fsyscall handler
+------------------------------------------
- - r10 = 0
- - r11 = saved ar.pfs (a user-level value)
- - r15 = system call number
- - r16 = "current" task pointer (in normal kernel-mode, this is in r13)
- - r32-r39 = system call arguments
- - b6 = return address (a user-level value)
- - ar.pfs = previous frame-state (a user-level value)
- - PSR.be = cleared to zero (i.e., little-endian byte order is in effect)
- - all other registers may contain values passed in from user-mode
+ ========= ===============================================================
+ r10 0
+ r11 saved ar.pfs (a user-level value)
+ r15 system call number
+ r16 "current" task pointer (in normal kernel-mode, this is in r13)
+ r32-r39 system call arguments
+ b6 return address (a user-level value)
+ ar.pfs previous frame-state (a user-level value)
+ PSR.be cleared to zero (i.e., little-endian byte order is in effect)
+ - all other registers may contain values passed in from user-mode
+ ========= ===============================================================
-** Required machine state on exit to fsyscall handler:
+Required machine state on exit to fsyscall handler
+--------------------------------------------------
- - r11 = saved ar.pfs (as passed into the fsyscall handler)
- - r15 = system call number (as passed into the fsyscall handler)
- - r32-r39 = system call arguments (as passed into the fsyscall handler)
- - b6 = return address (as passed into the fsyscall handler)
- - ar.pfs = previous frame-state (as passed into the fsyscall handler)
+ ========= ===========================================================
+ r11 saved ar.pfs (as passed into the fsyscall handler)
+ r15 system call number (as passed into the fsyscall handler)
+ r32-r39 system call arguments (as passed into the fsyscall handler)
+ b6 return address (as passed into the fsyscall handler)
+ ar.pfs previous frame-state (as passed into the fsyscall handler)
+ ========= ===========================================================
Fsyscall handlers can execute with very little overhead, but with that
speed comes a set of restrictions:
- o Fsyscall-handlers MUST check for any pending work in the flags
+ * Fsyscall-handlers MUST check for any pending work in the flags
member of the thread-info structure and if any of the
TIF_ALLWORK_MASK flags are set, the handler needs to fall back on
doing a full system call (by calling fsys_fallback_syscall).
- o Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,
+ * Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,
r15, b6, and ar.pfs) because they will be needed in case of a
system call restart. Of course, all "preserved" registers also
must be preserved, in accordance to the normal calling conventions.
- o Fsyscall-handlers MUST check argument registers for containing a
+ * Fsyscall-handlers MUST check argument registers for containing a
NaT value before using them in any way that could trigger a
NaT-consumption fault. If a system call argument is found to
contain a NaT value, an fsyscall-handler may return immediately
with r8=EINVAL, r10=-1.
- o Fsyscall-handlers MUST NOT use the "alloc" instruction or perform
+ * Fsyscall-handlers MUST NOT use the "alloc" instruction or perform
any other operation that would trigger mandatory RSE
(register-stack engine) traffic.
- o Fsyscall-handlers MUST NOT write to any stacked registers because
+ * Fsyscall-handlers MUST NOT write to any stacked registers because
it is not safe to assume that user-level called a handler with the
proper number of arguments.
- o Fsyscall-handlers need to be careful when accessing per-CPU variables:
+ * Fsyscall-handlers need to be careful when accessing per-CPU variables:
unless proper safe-guards are taken (e.g., interruptions are avoided),
execution may be pre-empted and resumed on another CPU at any given
time.
- o Fsyscall-handlers must be careful not to leak sensitive kernel'
+ * Fsyscall-handlers must be careful not to leak sensitive kernel'
information back to user-level. In particular, before returning to
user-level, care needs to be taken to clear any scratch registers
that could contain sensitive information (note that the current
task pointer is not considered sensitive: it's already exposed
through ar.k6).
- o Fsyscall-handlers MUST NOT access user-memory without first
+ * Fsyscall-handlers MUST NOT access user-memory without first
validating access-permission (this can be done typically via
probe.r.fault and/or probe.w.fault) and without guarding against
memory access exceptions (this can be done with the EX() macros
@@ -162,7 +170,8 @@ fast system call execution (while fully preserving system call
semantics), but there is also a lot of flexibility in handling more
complicated cases.
-* Signal handling
+Signal handling
+===============
The delivery of (asynchronous) signals must be delayed until fsys-mode
is exited. This is accomplished with the help of the lower-privilege
@@ -173,7 +182,8 @@ PSR.lp and returns immediately. When fsys-mode is exited via the
occur. The trap handler clears PSR.lp again and returns immediately.
The kernel exit path then checks for and delivers any pending signals.
-* PSR Handling
+PSR Handling
+============
The "epc" instruction doesn't change the contents of PSR at all. This
is in contrast to a regular interruption, which clears almost all
@@ -181,6 +191,7 @@ bits. Because of that, some care needs to be taken to ensure things
work as expected. The following discussion describes how each PSR bit
is handled.
+======= =======================================================================
PSR.be Cleared when entering fsys-mode. A srlz.d instruction is used
to ensure the CPU is in little-endian mode before the first
load/store instruction is executed. PSR.be is normally NOT
@@ -202,7 +213,8 @@ PSR.pp Unchanged.
PSR.di Unchanged.
PSR.si Unchanged.
PSR.db Unchanged. The kernel prevents user-level from setting a hardware
- breakpoint that triggers at any privilege level other than 3 (user-mode).
+ breakpoint that triggers at any privilege level other than
+ 3 (user-mode).
PSR.lp Unchanged.
PSR.tb Lazy redirect. If a taken-branch trap occurs while in
fsys-mode, the trap-handler modifies the saved machine state
@@ -235,47 +247,52 @@ PSR.ed Unchanged. Note: This bit could only have an effect if an fsys-mode
PSR.bn Unchanged. Note: fsys-mode handlers may clear the bit, if needed.
Doing so requires clearing PSR.i and PSR.ic as well.
PSR.ia Unchanged. Note: the ia64 linux kernel never sets this bit.
+======= =======================================================================
-* Using fast system calls
+Using fast system calls
+=======================
To use fast system calls, userspace applications need simply call
__kernel_syscall_via_epc(). For example
-- example fgettimeofday() call --
+
-- fgettimeofday.S --
-#include <asm/asmmacro.h>
+::
-GLOBAL_ENTRY(fgettimeofday)
-.prologue
-.save ar.pfs, r11
-mov r11 = ar.pfs
-.body
+ #include <asm/asmmacro.h>
-mov r2 = 0xa000000000020660;; // gate address
- // found by inspection of System.map for the
+ GLOBAL_ENTRY(fgettimeofday)
+ .prologue
+ .save ar.pfs, r11
+ mov r11 = ar.pfs
+ .body
+
+ mov r2 = 0xa000000000020660;; // gate address
+ // found by inspection of System.map for the
// __kernel_syscall_via_epc() function. See
// below for how to do this for real.
-mov b7 = r2
-mov r15 = 1087 // gettimeofday syscall
-;;
-br.call.sptk.many b6 = b7
-;;
+ mov b7 = r2
+ mov r15 = 1087 // gettimeofday syscall
+ ;;
+ br.call.sptk.many b6 = b7
+ ;;
-.restore sp
+ .restore sp
-mov ar.pfs = r11
-br.ret.sptk.many rp;; // return to caller
-END(fgettimeofday)
+ mov ar.pfs = r11
+ br.ret.sptk.many rp;; // return to caller
+ END(fgettimeofday)
-- end fgettimeofday.S --
In reality, getting the gate address is accomplished by two extra
values passed via the ELF auxiliary vector (include/asm-ia64/elf.h)
- o AT_SYSINFO : is the address of __kernel_syscall_via_epc()
- o AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO
+ * AT_SYSINFO : is the address of __kernel_syscall_via_epc()
+ * AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO
The ELF DSO is a pre-linked library that is mapped in by the kernel at
the gate page. It is a proper ELF shared object so, with a dynamic
diff --git a/Documentation/ia64/README b/Documentation/ia64/ia64.rst
similarity index 61%
rename from Documentation/ia64/README
rename to Documentation/ia64/ia64.rst
index aa17f2154cba..b725019a9492 100644
--- a/Documentation/ia64/README
+++ b/Documentation/ia64/ia64.rst
@@ -1,43 +1,49 @@
- Linux kernel release 2.4.xx for the IA-64 Platform
+===========================================
+Linux kernel release for the IA-64 Platform
+===========================================
- These are the release notes for Linux version 2.4 for IA-64
+ These are the release notes for Linux since version 2.4 for IA-64
platform. This document provides information specific to IA-64
ONLY, to get additional information about the Linux kernel also
read the original Linux README provided with the kernel.
-INSTALLING the kernel:
+Installing the Kernel
+=====================
- IA-64 kernel installation is the same as the other platforms, see
original README for details.
-SOFTWARE REQUIREMENTS
+Software Requirements
+=====================
Compiling and running this kernel requires an IA-64 compliant GCC
compiler. And various software packages also compiled with an
IA-64 compliant GCC compiler.
-CONFIGURING the kernel:
+Configuring the Kernel
+======================
Configuration is the same, see original README for details.
-COMPILING the kernel:
+Compiling the Kernel:
- Compiling this kernel doesn't differ from other platform so read
the original README for details BUT make sure you have an IA-64
compliant GCC compiler.
-IA-64 SPECIFICS
+IA-64 Specifics
+===============
- General issues:
- o Hardly any performance tuning has been done. Obvious targets
+ * Hardly any performance tuning has been done. Obvious targets
include the library routines (IP checksum, etc.). Less
obvious targets include making sure we don't flush the TLB
needlessly, etc.
- o SMP locks cleanup/optimization
+ * SMP locks cleanup/optimization
- o IA32 support. Currently experimental. It mostly works.
+ * IA32 support. Currently experimental. It mostly works.
diff --git a/Documentation/ia64/index.rst b/Documentation/ia64/index.rst
new file mode 100644
index 000000000000..a3e3052ad6e2
--- /dev/null
+++ b/Documentation/ia64/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+==================
+IA-64 Architecture
+==================
+
+.. toctree::
+ :maxdepth: 1
+
+ ia64
+ aliasing
+ efirtc
+ err_inject
+ fsys
+ irq-redir
+ mca
+ serial
+ xen
diff --git a/Documentation/ia64/IRQ-redir.txt b/Documentation/ia64/irq-redir.rst
similarity index 86%
rename from Documentation/ia64/IRQ-redir.txt
rename to Documentation/ia64/irq-redir.rst
index f7bd72261283..39bf94484a15 100644
--- a/Documentation/ia64/IRQ-redir.txt
+++ b/Documentation/ia64/irq-redir.rst
@@ -1,6 +1,8 @@
+==============================
IRQ affinity on IA64 platforms
-------------------------------
- 07.01.2002, Erich Focht <[email protected]>
+==============================
+
+07.01.2002, Erich Focht <[email protected]>
By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
@@ -12,22 +14,27 @@ IRQ target is one particular CPU and cannot be a mask of several
CPUs. Only the first non-zero bit is taken into account.
-Usage examples:
+Usage examples
+==============
The target CPU has to be specified as a hexadecimal CPU mask. The
first non-zero bit is the selected CPU. This format has been kept for
compatibility reasons with i386.
Set the delivery mode of interrupt 41 to fixed and route the
-interrupts to CPU #3 (logical CPU number) (2^3=0x08):
+interrupts to CPU #3 (logical CPU number) (2^3=0x08)::
+
echo "8" >/proc/irq/41/smp_affinity
Set the default route for IRQ number 41 to CPU 6 in lowest priority
-delivery mode (redirectable):
+delivery mode (redirectable)::
+
echo "r 40" >/proc/irq/41/smp_affinity
-The output of the command
+The output of the command::
+
cat /proc/irq/IRQ#/smp_affinity
+
gives the target CPU mask for the specified interrupt vector. If the CPU
mask is preceded by the character "r", the interrupt is redirectable
(i.e. lowest priority mode routing is used), otherwise its route is
@@ -35,7 +42,8 @@ fixed.
-Initialization and default behavior:
+Initialization and default behavior
+===================================
If the platform features IRQ redirection (info provided by SAL) all
IO-SAPIC interrupts are initialized with CPU#0 as their default target
@@ -43,9 +51,11 @@ and the routing is the so called "lowest priority mode" (actually
fixed SAPIC mode with hint). The XTP chipset registers are used as hints
for the IRQ routing. Currently in Linux XTP registers can have three
values:
+
- minimal for an idle task,
- normal if any other task runs,
- maximal if the CPU is going to be switched off.
+
The IRQ is routed to the CPU with lowest XTP register value, the
search begins at the default CPU. Therefore most of the interrupts
will be handled by CPU #0.
@@ -53,12 +63,14 @@ will be handled by CPU #0.
If the platform doesn't feature interrupt redirection IOSAPIC fixed
routing is used. The target CPUs are distributed in a round robin
manner. IRQs will be routed only to the selected target CPUs. Check
-with
+with::
+
cat /proc/interrupts
-Comments:
+Comments
+========
On large (multi-node) systems it is recommended to route the IRQs to
the node to which the corresponding device is connected.
@@ -66,4 +78,3 @@ For systems like the NEC AzusA we get IRQ node-affinity for free. This
is because usually the chipsets on each node redirect the interrupts
only to their own CPUs (as they cannot see the XTP registers on the
other nodes).
-
diff --git a/Documentation/ia64/mca.txt b/Documentation/ia64/mca.rst
similarity index 96%
rename from Documentation/ia64/mca.txt
rename to Documentation/ia64/mca.rst
index f097c60cba1b..08270bba44a4 100644
--- a/Documentation/ia64/mca.txt
+++ b/Documentation/ia64/mca.rst
@@ -1,5 +1,8 @@
-An ad-hoc collection of notes on IA64 MCA and INIT processing. Feel
-free to update it with notes about any area that is not clear.
+=============================================================
+An ad-hoc collection of notes on IA64 MCA and INIT processing
+=============================================================
+
+Feel free to update it with notes about any area that is not clear.
---
@@ -82,7 +85,8 @@ if we have a choice here.
own stack as running on that cpu. Then a recursive error gets a
trace of the failing handler's "task".
-[1] My (Keith Owens) original design called for ia64 to separate its
+[1]
+ My (Keith Owens) original design called for ia64 to separate its
struct task and the kernel stacks. Then the MCA/INIT data would be
chained stacks like i386 interrupt stacks. But that required
radical surgery on the rest of ia64, plus extra hard wired TLB
diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.rst
similarity index 87%
rename from Documentation/ia64/serial.txt
rename to Documentation/ia64/serial.rst
index a63d2c54329b..1de70c305a79 100644
--- a/Documentation/ia64/serial.txt
+++ b/Documentation/ia64/serial.rst
@@ -1,4 +1,9 @@
-SERIAL DEVICE NAMING
+==============
+Serial Devices
+==============
+
+Serial Device Naming
+====================
As of 2.6.10, serial devices on ia64 are named based on the
order of ACPI and PCI enumeration. The first device in the
@@ -30,17 +35,21 @@ SERIAL DEVICE NAMING
(described in the ACPI namespace) plus an MP[2] (a PCI device) has
these ports:
- pre-2.6.10 pre-2.6.10
- MMIO (EFI console (EFI console
- address on builtin) on MP port) 2.6.10
- ========== ========== ========== ======
+ ========== ========== ============ ============ =======
+ Type MMIO pre-2.6.10 pre-2.6.10 2.6.10+
+ address
+ (EFI console (EFI console
+ on builtin) on MP port)
+ ========== ========== ============ ============ =======
builtin 0xff5e0000 ttyS0 ttyS1 ttyS0
MP UPS 0xf8031000 ttyS1 ttyS2 ttyS1
MP Console 0xf8030000 ttyS2 ttyS0 ttyS2
MP 2 0xf8030010 ttyS3 ttyS3 ttyS3
MP 3 0xf8030038 ttyS4 ttyS4 ttyS4
+ ========== ========== ============ ============ =======
-CONSOLE SELECTION
+Console Selection
+=================
EFI knows what your console devices are, but it doesn't tell the
kernel quite enough to actually locate them. The DIG64 HCDP
@@ -67,7 +76,8 @@ CONSOLE SELECTION
entries in /etc/inittab (for getty) and /etc/securetty (to allow
root login).
-EARLY SERIAL CONSOLE
+Early Serial Console
+====================
The kernel can't start using a serial console until it knows where
the device lives. Normally this happens when the driver enumerates
@@ -80,7 +90,8 @@ EARLY SERIAL CONSOLE
or if the EFI console path contains only a UART device and the
firmware supplies an HCDP.
-TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
+Troubleshooting Serial Console Problems
+=======================================
No kernel output after elilo prints "Uncompressing Linux... done":
@@ -133,19 +144,22 @@ TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
-[1] http://www.dig64.org/specifications/agreement
+[1]
+ http://www.dig64.org/specifications/agreement
The table was originally defined as the "HCDP" for "Headless
Console/Debug Port." The current version is the "PCDP" for
"Primary Console and Debug Port Devices."
-[2] The HP MP (management processor) is a PCI device that provides
+[2]
+ The HP MP (management processor) is a PCI device that provides
several UARTs. One of the UARTs is often used as a console; the
EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart".
The external connection is usually a 25-pin connector, and a
special dongle converts that to three 9-pin connectors, one of
which is labelled "Console."
-[3] EFI console devices are configured using the EFI Boot Manager
+[3]
+ EFI console devices are configured using the EFI Boot Manager
"Boot option maintenance" menu. You may have to interrupt the
boot sequence to use this menu, and you will have to reset the
box after changing console configuration.
diff --git a/Documentation/ia64/xen.rst b/Documentation/ia64/xen.rst
new file mode 100644
index 000000000000..831339c74441
--- /dev/null
+++ b/Documentation/ia64/xen.rst
@@ -0,0 +1,206 @@
+********************************************************
+Recipe for getting/building/running Xen/ia64 with pv_ops
+********************************************************
+This recipe describes how to get xen-ia64 source and build it,
+and run domU with pv_ops.
+
+Requirements
+============
+
+ - python
+ - mercurial
+ it (aka "hg") is an open-source source code
+ management software. See the below.
+ http://www.selenic.com/mercurial/wiki/
+ - git
+ - bridge-utils
+
+Getting and Building Xen and Dom0
+=================================
+
+ My environment is:
+
+ - Machine : Tiger4
+ - Domain0 OS : RHEL5
+ - DomainU OS : RHEL5
+
+ 1. Download source::
+
+ # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg
+ # cd xen-unstable.hg
+ # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg
+
+ 2. # make world
+
+ 3. # make install-tools
+
+ 4. copy kernels and xen::
+
+ # cp xen/xen.gz /boot/efi/efi/redhat/
+ # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \
+ /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen
+
+ 5. make initrd for Dom0/DomU::
+
+ # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \
+ O=$(pwd)/build-linux-2.6.18-xen_ia64
+ # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \
+ 2.6.18.8-xen --builtin mptspi --builtin mptbase \
+ --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \
+ --builtin ehci-hcd
+
+Making a disk image for guest OS
+================================
+
+ 1. make file::
+
+ # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0
+ # mke2fs -F -j /root/rhel5.img
+ # mount -o loop /root/rhel5.img /mnt
+ # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt
+ # mkdir /mnt/{root,proc,sys,home,tmp}
+
+ Note: You may miss some device files. If so, please create them
+ with mknod. Or you can use tar instead of cp.
+
+ 2. modify DomU's fstab::
+
+ # vi /mnt/etc/fstab
+ /dev/xvda1 / ext3 defaults 1 1
+ none /dev/pts devpts gid=5,mode=620 0 0
+ none /dev/shm tmpfs defaults 0 0
+ none /proc proc defaults 0 0
+ none /sys sysfs defaults 0 0
+
+ 3. modify inittab
+
+ set runlevel to 3 to avoid X trying to start::
+
+ # vi /mnt/etc/inittab
+ id:3:initdefault:
+
+ Start a getty on the hvc0 console::
+
+ X0:2345:respawn:/sbin/mingetty hvc0
+
+ tty1-6 mingetty can be commented out
+
+ 4. add hvc0 into /etc/securetty::
+
+ # vi /mnt/etc/securetty (add hvc0)
+
+ 5. umount::
+
+ # umount /mnt
+
+FYI, virt-manager can also make a disk image for guest OS.
+It's GUI tools and easy to make it.
+
+Boot Xen & Domain0
+==================
+
+ 1. replace elilo
+ elilo of RHEL5 can boot Xen and Dom0.
+ If you use old elilo (e.g RHEL4), please download from the below
+ http://elilo.sourceforge.net/cgi-bin/blosxom
+ and copy into /boot/efi/efi/redhat/::
+
+ # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi
+
+ 2. modify elilo.conf (like the below)::
+
+ # vi /boot/efi/efi/redhat/elilo.conf
+ prompt
+ timeout=20
+ default=xen
+ relocatable
+
+ image=vmlinuz-2.6.18.8-xen
+ label=xen
+ vmm=xen.gz
+ initrd=initrd-2.6.18.8-xen.img
+ read-only
+ append=" -- rhgb root=/dev/sda2"
+
+The append options before "--" are for xen hypervisor,
+the options after "--" are for dom0.
+
+FYI, your machine may need console options like
+"com1=19200,8n1 console=vga,com1". For example,
+append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \
+console=ttyS0 root=/dev/sda2"
+
+Getting and Building domU with pv_ops
+=====================================
+
+ 1. get pv_ops tree::
+
+ # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/
+
+ 2. git branch (if necessary)::
+
+ # cd linux-2.6-xen-ia64/
+ # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19
+
+ Note:
+ The current branch is xen-ia64-domu-minimal-2008may19.
+ But you would find the new branch. You can see with
+ "git branch -r" to get the branch lists.
+
+ http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/
+
+ is also available.
+
+ The tree is based on
+
+ git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test)
+
+ 3. copy .config for pv_ops of domU::
+
+ # cp arch/ia64/configs/xen_domu_wip_defconfig .config
+
+ 4. make kernel with pv_ops::
+
+ # make oldconfig
+ # make
+
+ 5. install the kernel and initrd::
+
+ # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU
+ # make modules_install
+ # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \
+ 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \
+ --builtin mptbase --builtin mptscsih --builtin uhci-hcd \
+ --builtin ohci-hcd --builtin ehci-hcd
+
+Boot DomainU with pv_ops
+========================
+
+ 1. make config of DomU::
+
+ # vi /etc/xen/rhel5
+ kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU"
+ ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img"
+ vcpus = 1
+ memory = 512
+ name = "rhel5"
+ disk = [ 'file:/root/rhel5.img,xvda1,w' ]
+ root = "/dev/xvda1 ro"
+ extra= "rhgb console=hvc0"
+
+ 2. After boot xen and dom0, start xend::
+
+ # /etc/init.d/xend start
+
+ ( In the debugging case, `# XEND_DEBUG=1 xend trace_start` )
+
+ 3. start domU::
+
+ # xm create -c rhel5
+
+Reference
+=========
+- Wiki of Xen/IA64 upstream merge
+ http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge
+
+Written by Akio Takebe <[email protected]> on 28 May 2008
diff --git a/Documentation/ia64/xen.txt b/Documentation/ia64/xen.txt
deleted file mode 100644
index a12c74ce2773..000000000000
--- a/Documentation/ia64/xen.txt
+++ /dev/null
@@ -1,183 +0,0 @@
- Recipe for getting/building/running Xen/ia64 with pv_ops
- --------------------------------------------------------
-
-This recipe describes how to get xen-ia64 source and build it,
-and run domU with pv_ops.
-
-============
-Requirements
-============
-
- - python
- - mercurial
- it (aka "hg") is an open-source source code
- management software. See the below.
- http://www.selenic.com/mercurial/wiki/
- - git
- - bridge-utils
-
-=================================
-Getting and Building Xen and Dom0
-=================================
-
- My environment is;
- Machine : Tiger4
- Domain0 OS : RHEL5
- DomainU OS : RHEL5
-
- 1. Download source
- # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg
- # cd xen-unstable.hg
- # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg
-
- 2. # make world
-
- 3. # make install-tools
-
- 4. copy kernels and xen
- # cp xen/xen.gz /boot/efi/efi/redhat/
- # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \
- /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen
-
- 5. make initrd for Dom0/DomU
- # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \
- O=$(pwd)/build-linux-2.6.18-xen_ia64
- # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \
- 2.6.18.8-xen --builtin mptspi --builtin mptbase \
- --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \
- --builtin ehci-hcd
-
-================================
-Making a disk image for guest OS
-================================
-
- 1. make file
- # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0
- # mke2fs -F -j /root/rhel5.img
- # mount -o loop /root/rhel5.img /mnt
- # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt
- # mkdir /mnt/{root,proc,sys,home,tmp}
-
- Note: You may miss some device files. If so, please create them
- with mknod. Or you can use tar instead of cp.
-
- 2. modify DomU's fstab
- # vi /mnt/etc/fstab
- /dev/xvda1 / ext3 defaults 1 1
- none /dev/pts devpts gid=5,mode=620 0 0
- none /dev/shm tmpfs defaults 0 0
- none /proc proc defaults 0 0
- none /sys sysfs defaults 0 0
-
- 3. modify inittab
- set runlevel to 3 to avoid X trying to start
- # vi /mnt/etc/inittab
- id:3:initdefault:
- Start a getty on the hvc0 console
- X0:2345:respawn:/sbin/mingetty hvc0
- tty1-6 mingetty can be commented out
-
- 4. add hvc0 into /etc/securetty
- # vi /mnt/etc/securetty (add hvc0)
-
- 5. umount
- # umount /mnt
-
-FYI, virt-manager can also make a disk image for guest OS.
-It's GUI tools and easy to make it.
-
-==================
-Boot Xen & Domain0
-==================
-
- 1. replace elilo
- elilo of RHEL5 can boot Xen and Dom0.
- If you use old elilo (e.g RHEL4), please download from the below
- http://elilo.sourceforge.net/cgi-bin/blosxom
- and copy into /boot/efi/efi/redhat/
- # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi
-
- 2. modify elilo.conf (like the below)
- # vi /boot/efi/efi/redhat/elilo.conf
- prompt
- timeout=20
- default=xen
- relocatable
-
- image=vmlinuz-2.6.18.8-xen
- label=xen
- vmm=xen.gz
- initrd=initrd-2.6.18.8-xen.img
- read-only
- append=" -- rhgb root=/dev/sda2"
-
-The append options before "--" are for xen hypervisor,
-the options after "--" are for dom0.
-
-FYI, your machine may need console options like
-"com1=19200,8n1 console=vga,com1". For example,
-append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \
-console=ttyS0 root=/dev/sda2"
-
-=====================================
-Getting and Building domU with pv_ops
-=====================================
-
- 1. get pv_ops tree
- # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/
-
- 2. git branch (if necessary)
- # cd linux-2.6-xen-ia64/
- # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19
- (Note: The current branch is xen-ia64-domu-minimal-2008may19.
- But you would find the new branch. You can see with
- "git branch -r" to get the branch lists.
- http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/
- is also available. The tree is based on
- git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test)
-
-
- 3. copy .config for pv_ops of domU
- # cp arch/ia64/configs/xen_domu_wip_defconfig .config
-
- 4. make kernel with pv_ops
- # make oldconfig
- # make
-
- 5. install the kernel and initrd
- # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU
- # make modules_install
- # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \
- 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \
- --builtin mptbase --builtin mptscsih --builtin uhci-hcd \
- --builtin ohci-hcd --builtin ehci-hcd
-
-========================
-Boot DomainU with pv_ops
-========================
-
- 1. make config of DomU
- # vi /etc/xen/rhel5
- kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU"
- ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img"
- vcpus = 1
- memory = 512
- name = "rhel5"
- disk = [ 'file:/root/rhel5.img,xvda1,w' ]
- root = "/dev/xvda1 ro"
- extra= "rhgb console=hvc0"
-
- 2. After boot xen and dom0, start xend
- # /etc/init.d/xend start
- ( In the debugging case, # XEND_DEBUG=1 xend trace_start )
-
- 3. start domU
- # xm create -c rhel5
-
-=========
-Reference
-=========
-- Wiki of Xen/IA64 upstream merge
- http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge
-
-Written by Akio Takebe <[email protected]> on 28 May 2008
diff --git a/MAINTAINERS b/MAINTAINERS
index 8941a73880e6..f27f50f88638 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14266,7 +14266,7 @@ SGI SN-IA64 (Altix) SERIAL CONSOLE DRIVER
M: Pat Gefre <[email protected]>
L: [email protected]
S: Supported
-F: Documentation/ia64/serial.txt
+F: Documentation/ia64/serial.rst
F: drivers/tty/serial/ioc?_serial.c
F: include/linux/ioc?.h
diff --git a/arch/ia64/kernel/efi.c b/arch/ia64/kernel/efi.c
index 8f106638913c..3795d18276c4 100644
--- a/arch/ia64/kernel/efi.c
+++ b/arch/ia64/kernel/efi.c
@@ -852,7 +852,7 @@ valid_phys_addr_range (phys_addr_t phys_addr, unsigned long size)
* /dev/mem reads and writes use copy_to_user(), which implicitly
* uses a granule-sized kernel identity mapping. It's really
* only safe to do this for regions in kern_memmap. For more
- * details, see Documentation/ia64/aliasing.txt.
+ * details, see Documentation/ia64/aliasing.rst.
*/
attr = kern_mem_attribute(phys_addr, size);
if (attr & EFI_MEMORY_WB || attr & EFI_MEMORY_UC)
diff --git a/arch/ia64/kernel/fsys.S b/arch/ia64/kernel/fsys.S
index d80c99a5f55d..0750a716adc7 100644
--- a/arch/ia64/kernel/fsys.S
+++ b/arch/ia64/kernel/fsys.S
@@ -28,7 +28,7 @@
#include <asm/native/inst.h>
/*
- * See Documentation/ia64/fsys.txt for details on fsyscalls.
+ * See Documentation/ia64/fsys.rst for details on fsyscalls.
*
* On entry to an fsyscall handler:
* r10 = 0 (i.e., defaults to "successful syscall return")
diff --git a/arch/ia64/mm/ioremap.c b/arch/ia64/mm/ioremap.c
index 43964cde6214..c7da3376b6f8 100644
--- a/arch/ia64/mm/ioremap.c
+++ b/arch/ia64/mm/ioremap.c
@@ -45,7 +45,7 @@ ioremap (unsigned long phys_addr, unsigned long size)
/*
* For things in kern_memmap, we must use the same attribute
* as the rest of the kernel. For more details, see
- * Documentation/ia64/aliasing.txt.
+ * Documentation/ia64/aliasing.rst.
*/
attr = kern_mem_attribute(phys_addr, size);
if (attr & EFI_MEMORY_WB)
diff --git a/arch/ia64/pci/pci.c b/arch/ia64/pci/pci.c
index e308196c2229..165e561dc81a 100644
--- a/arch/ia64/pci/pci.c
+++ b/arch/ia64/pci/pci.c
@@ -450,7 +450,7 @@ pci_mmap_legacy_page_range(struct pci_bus *bus, struct vm_area_struct *vma,
return -ENOSYS;
/*
- * Avoid attribute aliasing. See Documentation/ia64/aliasing.txt
+ * Avoid attribute aliasing. See Documentation/ia64/aliasing.rst
* for more details.
*/
if (!valid_mmap_phys_addr_range(vma->vm_pgoff, size))
--
2.21.0
Convert the m68k kernel-options.txt file to ReST.
The conversion is trivial, as the document is already on a format
close enough to ReST. Just some small adjustments were needed in
order to make it both good for being parsed while keeping it on
a good txt shape.
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 <[email protected]>
---
.../admin-guide/kernel-parameters.rst | 2 +-
Documentation/m68k/index.rst | 17 +
...{kernel-options.txt => kernel-options.rst} | 319 ++++++++++--------
3 files changed, 191 insertions(+), 147 deletions(-)
create mode 100644 Documentation/m68k/index.rst
rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%)
diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index 8d3273e32eb1..006196bd763a 100644
--- a/Documentation/admin-guide/kernel-parameters.rst
+++ b/Documentation/admin-guide/kernel-parameters.rst
@@ -118,7 +118,7 @@ parameter is applicable::
LOOP Loopback device support is enabled.
M68k M68k architecture is enabled.
These options have more detailed description inside of
- Documentation/m68k/kernel-options.txt.
+ Documentation/m68k/kernel-options.rst.
MDA MDA console support is enabled.
MIPS MIPS architecture is enabled.
MOUSE Appropriate mouse support is enabled.
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
new file mode 100644
index 000000000000..f3273ec075c3
--- /dev/null
+++ b/Documentation/m68k/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+=================
+m68k Architecture
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ kernel-options
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.rst
similarity index 78%
rename from Documentation/m68k/kernel-options.txt
rename to Documentation/m68k/kernel-options.rst
index 79d21246c75a..cabd9419740d 100644
--- a/Documentation/m68k/kernel-options.txt
+++ b/Documentation/m68k/kernel-options.rst
@@ -1,22 +1,24 @@
-
-
- Command Line Options for Linux/m68k
- ===================================
+===================================
+Command Line Options for Linux/m68k
+===================================
Last Update: 2 May 1999
+
Linux/m68k version: 2.2.6
+
Author: [email protected] (Roman Hodek)
+
Update: [email protected] (Jes Sorensen) and [email protected] (Chris Lawrence)
0) Introduction
===============
- Often I've been asked which command line options the Linux/m68k
+Often I've been asked which command line options the Linux/m68k
kernel understands, or how the exact syntax for the ... option is, or
... about the option ... . I hope, this document supplies all the
answers...
- Note that some options might be outdated, their descriptions being
+Note that some options might be outdated, their descriptions being
incomplete or missing. Please update the information and send in the
patches.
@@ -38,11 +40,11 @@ argument contains an '=', it is of class 2, and the definition is put
into init's environment. All other arguments are passed to init as
command line options.
- This document describes the valid kernel options for Linux/m68k in
+This document describes the valid kernel options for Linux/m68k in
the version mentioned at the start of this file. Later revisions may
add new such options, and some may be missing in older versions.
- In general, the value (the part after the '=') of an option is a
+In general, the value (the part after the '=') of an option is a
list of values separated by commas. The interpretation of these values
is up to the driver that "owns" the option. This association of
options with drivers is also the reason that some are further
@@ -55,21 +57,21 @@ subdivided.
2.1) root=
----------
-Syntax: root=/dev/<device>
- or: root=<hex_number>
+:Syntax: root=/dev/<device>
+:or: root=<hex_number>
This tells the kernel which device it should mount as the root
filesystem. The device must be a block device with a valid filesystem
on it.
- The first syntax gives the device by name. These names are converted
+The first syntax gives the device by name. These names are converted
into a major/minor number internally in the kernel in an unusual way.
Normally, this "conversion" is done by the device files in /dev, but
this isn't possible here, because the root filesystem (with /dev)
isn't mounted yet... So the kernel parses the name itself, with some
hardcoded name to number mappings. The name must always be a
combination of two or three letters, followed by a decimal number.
-Valid names are:
+Valid names are::
/dev/ram: -> 0x0100 (initial ramdisk)
/dev/hda: -> 0x0300 (first IDE disk)
@@ -81,7 +83,7 @@ Valid names are:
/dev/sde: -> 0x0840 (fifth SCSI disk)
/dev/fd : -> 0x0200 (floppy disk)
- The name must be followed by a decimal number, that stands for the
+The name must be followed by a decimal number, that stands for the
partition number. Internally, the value of the number is just
added to the device number mentioned in the table above. The
exceptions are /dev/ram and /dev/fd, where /dev/ram refers to an
@@ -100,12 +102,12 @@ the kernel command line.
[Strange and maybe uninteresting stuff ON]
- This unusual translation of device names has some strange
+This unusual translation of device names has some strange
consequences: If, for example, you have a symbolic link from /dev/fd
to /dev/fd0D720 as an abbreviation for floppy driver #0 in DD format,
you cannot use this name for specifying the root device, because the
kernel cannot see this symlink before mounting the root FS and it
-isn't in the table above. If you use it, the root device will not be
+isn't in the table above. If you use it, the root device will not be
set at all, without an error message. Another example: You cannot use a
partition on e.g. the sixth SCSI disk as the root filesystem, if you
want to specify it by name. This is, because only the devices up to
@@ -118,7 +120,7 @@ knowledge that each disk uses 16 minors, and write "root=/dev/sde17"
[Strange and maybe uninteresting stuff OFF]
- If the device containing your root partition isn't in the table
+If the device containing your root partition isn't in the table
above, you can also specify it by major and minor numbers. These are
written in hex, with no prefix and no separator between. E.g., if you
have a CD with contents appropriate as a root filesystem in the first
@@ -136,6 +138,7 @@ known partition UUID as the starting point. For example,
if partition 5 of the device has the UUID of
00112233-4455-6677-8899-AABBCCDDEEFF then partition 3 may be found as
follows:
+
PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2
Authoritative information can be found in
@@ -145,8 +148,8 @@ Authoritative information can be found in
2.2) ro, rw
-----------
-Syntax: ro
- or: rw
+:Syntax: ro
+:or: rw
These two options tell the kernel whether it should mount the root
filesystem read-only or read-write. The default is read-only, except
@@ -156,7 +159,7 @@ for ramdisks, which default to read-write.
2.3) debug
----------
-Syntax: debug
+:Syntax: debug
This raises the kernel log level to 10 (the default is 7). This is the
same level as set by the "dmesg" command, just that the maximum level
@@ -166,7 +169,7 @@ selectable by dmesg is 8.
2.4) debug=
-----------
-Syntax: debug=<device>
+:Syntax: debug=<device>
This option causes certain kernel messages be printed to the selected
debugging device. This can aid debugging the kernel, since the
@@ -175,7 +178,7 @@ devices are possible depends on the machine type. There are no checks
for the validity of the device name. If the device isn't implemented,
nothing happens.
- Messages logged this way are in general stack dumps after kernel
+Messages logged this way are in general stack dumps after kernel
memory faults or bad kernel traps, and kernel panics. To be exact: all
messages of level 0 (panic messages) and all messages printed while
the log level is 8 or more (their level doesn't matter). Before stack
@@ -185,19 +188,27 @@ at least 8 can also be set by the "debug" command line option (see
Devices possible for Amiga:
- - "ser": built-in serial port; parameters: 9600bps, 8N1
- - "mem": Save the messages to a reserved area in chip mem. After
+ - "ser":
+ built-in serial port; parameters: 9600bps, 8N1
+ - "mem":
+ Save the messages to a reserved area in chip mem. After
rebooting, they can be read under AmigaOS with the tool
'dmesg'.
Devices possible for Atari:
- - "ser1": ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
- - "ser2": SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
- - "ser" : default serial port
+ - "ser1":
+ ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
+ - "ser2":
+ SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
+ - "ser" :
+ default serial port
This is "ser2" for a Falcon, and "ser1" for any other machine
- - "midi": The MIDI port; parameters: 31250bps, 8N1
- - "par" : parallel port
+ - "midi":
+ The MIDI port; parameters: 31250bps, 8N1
+ - "par" :
+ parallel port
+
The printing routine for this implements a timeout for the
case there's no printer connected (else the kernel would
lock up). The timeout is not exact, but usually a few
@@ -205,26 +216,29 @@ Devices possible for Atari:
2.6) ramdisk_size=
--------------
+------------------
-Syntax: ramdisk_size=<size>
+:Syntax: ramdisk_size=<size>
- This option instructs the kernel to set up a ramdisk of the given
+This option instructs the kernel to set up a ramdisk of the given
size in KBytes. Do not use this option if the ramdisk contents are
passed by bootstrap! In this case, the size is selected automatically
and should not be overwritten.
- The only application is for root filesystems on floppy disks, that
+The only application is for root filesystems on floppy disks, that
should be loaded into memory. To do that, select the corresponding
size of the disk as ramdisk size, and set the root device to the disk
drive (with "root=").
2.7) swap=
+
+ I can't find any sign of this option in 2.2.6.
+
2.8) buff=
-----------
- I can't find any sign of these options in 2.2.6.
+ I can't find any sign of this option in 2.2.6.
3) General Device Options (Amiga and Atari)
@@ -233,13 +247,13 @@ drive (with "root=").
3.1) ether=
-----------
-Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
+:Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
- <dev-name> is the name of a net driver, as specified in
+<dev-name> is the name of a net driver, as specified in
drivers/net/Space.c in the Linux source. Most prominent are eth0, ...
eth3, sl0, ... sl3, ppp0, ..., ppp3, dummy, and lo.
- The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
+The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
settings by this options. Also, the existing ethernet drivers for
Linux/m68k (ariadne, a2065, hydra) don't use them because Zorro boards
are really Plug-'n-Play, so the "ether=" option is useless altogether
@@ -249,9 +263,9 @@ for Linux/m68k.
3.2) hd=
--------
-Syntax: hd=<cylinders>,<heads>,<sectors>
+:Syntax: hd=<cylinders>,<heads>,<sectors>
- This option sets the disk geometry of an IDE disk. The first hd=
+This option sets the disk geometry of an IDE disk. The first hd=
option is for the first IDE disk, the second for the second one.
(I.e., you can give this option twice.) In most cases, you won't have
to use this option, since the kernel can obtain the geometry data
@@ -262,9 +276,9 @@ disks.
3.3) max_scsi_luns=
-------------------
-Syntax: max_scsi_luns=<n>
+:Syntax: max_scsi_luns=<n>
- Sets the maximum number of LUNs (logical units) of SCSI devices to
+Sets the maximum number of LUNs (logical units) of SCSI devices to
be scanned. Valid values for <n> are between 1 and 8. Default is 8 if
"Probe all LUNs on each SCSI device" was selected during the kernel
configuration, else 1.
@@ -273,9 +287,9 @@ configuration, else 1.
3.4) st=
--------
-Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
+:Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
- Sets several parameters of the SCSI tape driver. <buffer_size> is
+Sets several parameters of the SCSI tape driver. <buffer_size> is
the number of 512-byte buffers reserved for tape operations for each
device. <write_thres> sets the number of blocks which must be filled
to start an actual write operation to the tape. Maximum value is the
@@ -286,9 +300,9 @@ buffers allocated for all tape devices.
3.5) dmasound=
--------------
-Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
+:Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
- This option controls some configurations of the Linux/m68k DMA sound
+This option controls some configurations of the Linux/m68k DMA sound
driver (Amiga and Atari): <buffers> is the number of buffers you want
to use (minimum 4, default 4), <buffer-size> is the size of each
buffer in kilobytes (minimum 4, default 32) and <catch-radius> says
@@ -305,20 +319,22 @@ don't need to expand the sound.
4.1) video=
-----------
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
The <fbname> parameter specifies the name of the frame buffer,
-eg. most atari users will want to specify `atafb' here. The
+eg. most atari users will want to specify `atafb` here. The
<sub-options> is a comma-separated list of the sub-options listed
below.
-NB: Please notice that this option was renamed from `atavideo' to
- `video' during the development of the 1.3.x kernels, thus you
+NB:
+ Please notice that this option was renamed from `atavideo` to
+ `video` during the development of the 1.3.x kernels, thus you
might need to update your boot-scripts if upgrading to 2.x from
an 1.2.x kernel.
-NBB: The behavior of video= was changed in 2.1.57 so the recommended
-option is to specify the name of the frame buffer.
+NBB:
+ The behavior of video= was changed in 2.1.57 so the recommended
+ option is to specify the name of the frame buffer.
4.1.1) Video Mode
-----------------
@@ -341,11 +357,11 @@ mode, if the hardware allows. Currently defined names are:
- falh2 : 896x608x1, Falcon only
- falh16 : 896x608x4, Falcon only
- If no video mode is given on the command line, the kernel tries the
+If no video mode is given on the command line, the kernel tries the
modes names "default<n>" in turn, until one is possible with the
hardware in use.
- A video mode setting doesn't make sense, if the external driver is
+A video mode setting doesn't make sense, if the external driver is
activated by a "external:" sub-option.
4.1.2) inverse
@@ -358,17 +374,17 @@ option, you can make the background white.
4.1.3) font
-----------
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
Specify the font to use in text modes. Currently you can choose only
-between `VGA8x8', `VGA8x16' and `PEARL8x8'. `VGA8x8' is default, if the
+between `VGA8x8`, `VGA8x16` and `PEARL8x8`. `VGA8x8` is default, if the
vertical size of the display is less than 400 pixel rows. Otherwise, the
-`VGA8x16' font is the default.
+`VGA8x16` font is the default.
-4.1.4) hwscroll_
-----------------
+4.1.4) `hwscroll_`
+------------------
-Syntax: hwscroll_<n>
+:Syntax: `hwscroll_<n>`
The number of additional lines of video memory to reserve for
speeding up the scrolling ("hardware scrolling"). Hardware scrolling
@@ -378,7 +394,7 @@ possible with plain STs and graphics cards (The former because the
base address must be on a 256 byte boundary there, the latter because
the kernel doesn't know how to set the base address at all.)
- By default, <n> is set to the number of visible text lines on the
+By default, <n> is set to the number of visible text lines on the
display. Thus, the amount of video memory is doubled, compared to no
hardware scrolling. You can turn off the hardware scrolling altogether
by setting <n> to 0.
@@ -386,31 +402,31 @@ by setting <n> to 0.
4.1.5) internal:
----------------
-Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
+:Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
This option specifies the capabilities of some extended internal video
hardware, like e.g. OverScan. <xres> and <yres> give the (extended)
dimensions of the screen.
- If your OverScan needs a black border, you have to write the last
+If your OverScan needs a black border, you have to write the last
three arguments of the "internal:". <xres_max> is the maximum line
length the hardware allows, <yres_max> the maximum number of lines.
<offset> is the offset of the visible part of the screen memory to its
physical start, in bytes.
- Often, extended interval video hardware has to be activated somehow.
+Often, extended interval video hardware has to be activated somehow.
For this, see the "sw_*" options below.
4.1.6) external:
----------------
-Syntax:
- external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>\
- [;<colw>[;<coltype>[;<xres_virtual>]]]]]
+:Syntax:
+ external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>
+ [;<colw>[;<coltype>[;<xres_virtual>]]]]]
-[I had to break this line...]
+.. I had to break this line...
- This is probably the most complicated parameter... It specifies that
+This is probably the most complicated parameter... It specifies that
you have some external video hardware (a graphics board), and how to
use it under Linux/m68k. The kernel cannot know more about the hardware
than you tell it here! The kernel also is unable to set or change any
@@ -418,38 +434,44 @@ video modes, since it doesn't know about any board internal. So, you
have to switch to that video mode before you start Linux, and cannot
switch to another mode once Linux has started.
- The first 3 parameters of this sub-option should be obvious: <xres>,
+The first 3 parameters of this sub-option should be obvious: <xres>,
<yres> and <depth> give the dimensions of the screen and the number of
planes (depth). The depth is the logarithm to base 2 of the number
of colors possible. (Or, the other way round: The number of colors is
2^depth).
- You have to tell the kernel furthermore how the video memory is
+You have to tell the kernel furthermore how the video memory is
organized. This is done by a letter as <org> parameter:
- 'n': "normal planes", i.e. one whole plane after another
- 'i': "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
+ 'n':
+ "normal planes", i.e. one whole plane after another
+ 'i':
+ "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
of the next, and so on... This mode is used only with the
- built-in Atari video modes, I think there is no card that
- supports this mode.
- 'p': "packed pixels", i.e. <depth> consecutive bits stand for all
- planes of one pixel; this is the most common mode for 8 planes
- (256 colors) on graphic cards
- 't': "true color" (more or less packed pixels, but without a color
- lookup table); usually depth is 24
+ built-in Atari video modes, I think there is no card that
+ supports this mode.
+ 'p':
+ "packed pixels", i.e. <depth> consecutive bits stand for all
+ planes of one pixel; this is the most common mode for 8 planes
+ (256 colors) on graphic cards
+ 't':
+ "true color" (more or less packed pixels, but without a color
+ lookup table); usually depth is 24
For monochrome modes (i.e., <depth> is 1), the <org> letter has a
different meaning:
- 'n': normal colors, i.e. 0=white, 1=black
- 'i': inverted colors, i.e. 0=black, 1=white
+ 'n':
+ normal colors, i.e. 0=white, 1=black
+ 'i':
+ inverted colors, i.e. 0=black, 1=white
- The next important information about the video hardware is the base
+The next important information about the video hardware is the base
address of the video memory. That is given in the <scrmem> parameter,
as a hexadecimal number with a "0x" prefix. You have to find out this
address in the documentation of your hardware.
- The next parameter, <scrlen>, tells the kernel about the size of the
+The next parameter, <scrlen>, tells the kernel about the size of the
video memory. If it's missing, the size is calculated from <xres>,
<yres>, and <depth>. For now, it is not useful to write a value here.
It would be used only for hardware scrolling (which isn't possible
@@ -460,7 +482,7 @@ empty, either by ending the "external:" after the video address or by
writing two consecutive semicolons, if you want to give a <vgabase>
(it is allowed to leave this parameter empty).
- The <vgabase> parameter is optional. If it is not given, the kernel
+The <vgabase> parameter is optional. If it is not given, the kernel
cannot read or write any color registers of the video hardware, and
thus you have to set appropriate colors before you start Linux. But if
your card is somehow VGA compatible, you can tell the kernel the base
@@ -472,18 +494,18 @@ uses the addresses vgabase+0x3c7...vgabase+0x3c9. The <vgabase>
parameter is written in hexadecimal with a "0x" prefix, just as
<scrmem>.
- <colw> is meaningful only if <vgabase> is specified. It tells the
+<colw> is meaningful only if <vgabase> is specified. It tells the
kernel how wide each of the color register is, i.e. the number of bits
per single color (red/green/blue). Default is 6, another quite usual
value is 8.
- Also <coltype> is used together with <vgabase>. It tells the kernel
+Also <coltype> is used together with <vgabase>. It tells the kernel
about the color register model of your gfx board. Currently, the types
"vga" (which is also the default) and "mv300" (SANG MV300) are
implemented.
- Parameter <xres_virtual> is required for ProMST or ET4000 cards where
-the physical linelength differs from the visible length. With ProMST,
+Parameter <xres_virtual> is required for ProMST or ET4000 cards where
+the physical linelength differs from the visible length. With ProMST,
xres_virtual must be set to 2048. For ET4000, xres_virtual depends on the
initialisation of the video-card.
If you're missing a corresponding yres_virtual: the external part is legacy,
@@ -499,13 +521,13 @@ currently works only with the ScreenWonder!
4.1.8) monitorcap:
-------------------
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
This describes the capabilities of a multisync monitor. Don't use it
with a fixed-frequency monitor! For now, only the Falcon frame buffer
uses the settings of "monitorcap:".
- <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
your monitor can work with, in Hz. <hmin> and <hmax> are the same for
the horizontal frequency, in kHz.
@@ -520,28 +542,28 @@ If this option is given, the framebuffer device doesn't do any video
mode calculations and settings on its own. The only Atari fb device
that does this currently is the Falcon.
- What you reach with this: Settings for unknown video extensions
+What you reach with this: Settings for unknown video extensions
aren't overridden by the driver, so you can still use the mode found
when booting, when the driver doesn't know to set this mode itself.
But this also means, that you can't switch video modes anymore...
- An example where you may want to use "keep" is the ScreenBlaster for
+An example where you may want to use "keep" is the ScreenBlaster for
the Falcon.
4.2) atamouse=
--------------
-Syntax: atamouse=<x-threshold>,[<y-threshold>]
+:Syntax: atamouse=<x-threshold>,[<y-threshold>]
- With this option, you can set the mouse movement reporting threshold.
+With this option, you can set the mouse movement reporting threshold.
This is the number of pixels of mouse movement that have to accumulate
before the IKBD sends a new mouse packet to the kernel. Higher values
reduce the mouse interrupt load and thus reduce the chance of keyboard
overruns. Lower values give a slightly faster mouse responses and
slightly better mouse tracking.
- You can set the threshold in x and y separately, but usually this is
+You can set the threshold in x and y separately, but usually this is
of little practical use. If there's just one number in the option, it
is used for both dimensions. The default value is 2 for both
thresholds.
@@ -550,7 +572,7 @@ thresholds.
4.3) ataflop=
-------------
-Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
+:Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
The drive type may be 0, 1, or 2, for DD, HD, and ED, resp. This
setting affects how many buffers are reserved and which formats are
@@ -563,15 +585,15 @@ Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
no for the Medusa and yes for all others.
With the two following parameters, you can change the default
- steprate used for drive A and B, resp.
+ steprate used for drive A and B, resp.
4.4) atascsi=
-------------
-Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
+:Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
- This option sets some parameters for the Atari native SCSI driver.
+This option sets some parameters for the Atari native SCSI driver.
Generally, any number of arguments can be omitted from the end. And
for each of the numbers, a negative value means "use default". The
defaults depend on whether TT-style or Falcon-style SCSI is used.
@@ -597,11 +619,14 @@ ignored (others aren't affected).
32). Default: 8/1. (Note: Values > 1 seem to cause problems on a
Falcon, cause not yet known.)
- The <cmd_per_lun> value at a great part determines the amount of
+ The <cmd_per_lun> value at a great part determines the amount of
memory SCSI reserves for itself. The formula is rather
complicated, but I can give you some hints:
- no scatter-gather : cmd_per_lun * 232 bytes
- full scatter-gather: cmd_per_lun * approx. 17 Kbytes
+
+ no scatter-gather:
+ cmd_per_lun * 232 bytes
+ full scatter-gather:
+ cmd_per_lun * approx. 17 Kbytes
<scat-gat>:
Size of the scatter-gather table, i.e. the number of requests
@@ -634,19 +659,23 @@ ignored (others aren't affected).
4.5 switches=
-------------
-Syntax: switches=<list of switches>
+:Syntax: switches=<list of switches>
- With this option you can switch some hardware lines that are often
+With this option you can switch some hardware lines that are often
used to enable/disable certain hardware extensions. Examples are
OverScan, overclocking, ...
- The <list of switches> is a comma-separated list of the following
+The <list of switches> is a comma-separated list of the following
items:
- ikbd: set RTS of the keyboard ACIA high
- midi: set RTS of the MIDI ACIA high
- snd6: set bit 6 of the PSG port A
- snd7: set bit 6 of the PSG port A
+ ikbd:
+ set RTS of the keyboard ACIA high
+ midi:
+ set RTS of the MIDI ACIA high
+ snd6:
+ set bit 6 of the PSG port A
+ snd7:
+ set bit 6 of the PSG port A
It doesn't make sense to mention a switch more than once (no
difference to only once), but you can give as many switches as you
@@ -654,16 +683,16 @@ want to enable different features. The switch lines are set as early
as possible during kernel initialization (even before determining the
present hardware.)
- All of the items can also be prefixed with "ov_", i.e. "ov_ikbd",
-"ov_midi", ... These options are meant for switching on an OverScan
+All of the items can also be prefixed with `ov_`, i.e. `ov_ikbd`,
+`ov_midi`, ... These options are meant for switching on an OverScan
video extension. The difference to the bare option is that the
switch-on is done after video initialization, and somehow synchronized
to the HBLANK. A speciality is that ov_ikbd and ov_midi are switched
off before rebooting, so that OverScan is disabled and TOS boots
correctly.
- If you give an option both, with and without the "ov_" prefix, the
-earlier initialization ("ov_"-less) takes precedence. But the
+If you give an option both, with and without the `ov_` prefix, the
+earlier initialization (`ov_`-less) takes precedence. But the
switching-off on reset still happens in this case.
5) Options for Amiga Only:
@@ -672,10 +701,10 @@ switching-off on reset still happens in this case.
5.1) video=
-----------
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
The <fbname> parameter specifies the name of the frame buffer, valid
-options are `amifb', `cyber', 'virge', `retz3' and `clgen', provided
+options are `amifb`, `cyber`, 'virge', `retz3` and `clgen`, provided
that the respective frame buffer devices have been compiled into the
kernel (or compiled as loadable modules). The behavior of the <fbname>
option was changed in 2.1.57 so it is now recommended to specify this
@@ -697,9 +726,11 @@ predefined video modes are available:
NTSC modes:
- ntsc : 640x200, 15 kHz, 60 Hz
- ntsc-lace : 640x400, 15 kHz, 60 Hz interlaced
+
PAL modes:
- pal : 640x256, 15 kHz, 50 Hz
- pal-lace : 640x512, 15 kHz, 50 Hz interlaced
+
ECS modes:
- multiscan : 640x480, 29 kHz, 57 Hz
- multiscan-lace : 640x960, 29 kHz, 57 Hz interlaced
@@ -715,6 +746,7 @@ ECS modes:
- dblpal-lace : 640x1024, 27 kHz, 47 Hz interlaced
- dblntsc : 640x200, 27 kHz, 57 Hz doublescan
- dblpal : 640x256, 27 kHz, 47 Hz doublescan
+
VGA modes:
- vga : 640x480, 31 kHz, 60 Hz
- vga70 : 640x400, 31 kHz, 70 Hz
@@ -726,7 +758,7 @@ chipset and 8-bit color for the AGA chipset.
5.1.2) depth
------------
-Syntax: depth:<nr. of bit-planes>
+:Syntax: depth:<nr. of bit-planes>
Specify the number of bit-planes for the selected video-mode.
@@ -739,32 +771,32 @@ Use inverted display (black on white). Functionally the same as the
5.1.4) font
-----------
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
Specify the font to use in text modes. Functionally the same as the
-"font" sub-option for the Atari, except that `PEARL8x8' is used instead
-of `VGA8x8' if the vertical size of the display is less than 400 pixel
+"font" sub-option for the Atari, except that `PEARL8x8` is used instead
+of `VGA8x8` if the vertical size of the display is less than 400 pixel
rows.
5.1.5) monitorcap:
-------------------
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
This describes the capabilities of a multisync monitor. For now, only
the color frame buffer uses the settings of "monitorcap:".
- <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
your monitor can work with, in Hz. <hmin> and <hmax> are the same for
the horizontal frequency, in kHz.
- The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
+The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
5.2) fd_def_df0=
----------------
-Syntax: fd_def_df0=<value>
+:Syntax: fd_def_df0=<value>
Sets the df0 value for "silent" floppy drives. The value should be in
hexadecimal with "0x" prefix.
@@ -773,7 +805,7 @@ hexadecimal with "0x" prefix.
5.3) wd33c93=
-------------
-Syntax: wd33c93=<sub-options...>
+:Syntax: wd33c93=<sub-options...>
These options affect the A590/A2091, A3000 and GVP Series II SCSI
controllers.
@@ -784,9 +816,9 @@ below.
5.3.1) nosync
-------------
-Syntax: nosync:bitmask
+:Syntax: nosync:bitmask
- bitmask is a byte where the 1st 7 bits correspond with the 7
+bitmask is a byte where the 1st 7 bits correspond with the 7
possible SCSI devices. Set a bit to prevent sync negotiation on that
device. To maintain backwards compatibility, a command-line such as
"wd33c93=255" will be automatically translated to
@@ -796,35 +828,35 @@ all devices, eg. nosync:0xff.
5.3.2) period
-------------
-Syntax: period:ns
+:Syntax: period:ns
- `ns' is the minimum # of nanoseconds in a SCSI data transfer
+`ns` is the minimum # of nanoseconds in a SCSI data transfer
period. Default is 500; acceptable values are 250 - 1000.
5.3.3) disconnect
-----------------
-Syntax: disconnect:x
+:Syntax: disconnect:x
- Specify x = 0 to never allow disconnects, 2 to always allow them.
+Specify x = 0 to never allow disconnects, 2 to always allow them.
x = 1 does 'adaptive' disconnects, which is the default and generally
the best choice.
5.3.4) debug
------------
-Syntax: debug:x
+:Syntax: debug:x
- If `DEBUGGING_ON' is defined, x is a bit mask that causes various
+If `DEBUGGING_ON` is defined, x is a bit mask that causes various
types of debug output to printed - see the DB_xxx defines in
wd33c93.h.
5.3.5) clock
------------
-Syntax: clock:x
+:Syntax: clock:x
- x = clock input in MHz for WD33c93 chip. Normal values would be from
+x = clock input in MHz for WD33c93 chip. Normal values would be from
8 through 20. The default value depends on your hostadapter(s),
default for the A3000 internal controller is 14, for the A2091 it's 8
and for the GVP hostadapters it's either 8 or 14, depending on the
@@ -834,15 +866,15 @@ hostadapters.
5.3.6) next
-----------
- No argument. Used to separate blocks of keywords when there's more
+No argument. Used to separate blocks of keywords when there's more
than one wd33c93-based host adapter in the system.
5.3.7) nodma
------------
-Syntax: nodma:x
+:Syntax: nodma:x
- If x is 1 (or if the option is just written as "nodma"), the WD33c93
+If x is 1 (or if the option is just written as "nodma"), the WD33c93
controller will not use DMA (= direct memory access) to access the
Amiga's memory. This is useful for some systems (like A3000's and
A4000's with the A3640 accelerator, revision 3.0) that have problems
@@ -853,32 +885,27 @@ possible.
5.4) gvp11=
-----------
-Syntax: gvp11=<addr-mask>
+:Syntax: gvp11=<addr-mask>
- The earlier versions of the GVP driver did not handle DMA
+The earlier versions of the GVP driver did not handle DMA
address-mask settings correctly which made it necessary for some
people to use this option, in order to get their GVP controller
running under Linux. These problems have hopefully been solved and the
use of this option is now highly unrecommended!
- Incorrect use can lead to unpredictable behavior, so please only use
+Incorrect use can lead to unpredictable behavior, so please only use
this option if you *know* what you are doing and have a reason to do
so. In any case if you experience problems and need to use this
option, please inform us about it by mailing to the Linux/68k kernel
mailing list.
- The address mask set by this option specifies which addresses are
+The address mask set by this option specifies which addresses are
valid for DMA with the GVP Series II SCSI controller. An address is
valid, if no bits are set except the bits that are set in the mask,
too.
- Some versions of the GVP can only DMA into a 24 bit address range,
+Some versions of the GVP can only DMA into a 24 bit address range,
some can address a 25 bit address range while others can use the whole
32 bit address range for DMA. The correct setting depends on your
controller and should be autodetected by the driver. An example is the
24 bit region which is specified by a mask of 0x00fffffe.
-
-
-/* Local Variables: */
-/* mode: text */
-/* End: */
--
2.21.0
Rename the nvdimm documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
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 <[email protected]>
---
Documentation/nvdimm/{btt.txt => btt.rst} | 140 ++---
Documentation/nvdimm/index.rst | 12 +
.../nvdimm/{nvdimm.txt => nvdimm.rst} | 518 ++++++++++--------
.../nvdimm/{security.txt => security.rst} | 4 +-
drivers/nvdimm/Kconfig | 2 +-
5 files changed, 387 insertions(+), 289 deletions(-)
rename Documentation/nvdimm/{btt.txt => btt.rst} (71%)
create mode 100644 Documentation/nvdimm/index.rst
rename Documentation/nvdimm/{nvdimm.txt => nvdimm.rst} (60%)
rename Documentation/nvdimm/{security.txt => security.rst} (99%)
diff --git a/Documentation/nvdimm/btt.txt b/Documentation/nvdimm/btt.rst
similarity index 71%
rename from Documentation/nvdimm/btt.txt
rename to Documentation/nvdimm/btt.rst
index e293fb664924..2d8269f834bd 100644
--- a/Documentation/nvdimm/btt.txt
+++ b/Documentation/nvdimm/btt.rst
@@ -1,9 +1,10 @@
+=============================
BTT - Block Translation Table
=============================
1. Introduction
----------------
+===============
Persistent memory based storage is able to perform IO at byte (or more
accurately, cache line) granularity. However, we often want to expose such
@@ -25,7 +26,7 @@ provides atomic sector updates.
2. Static Layout
-----------------
+================
The underlying storage on which a BTT can be laid out is not limited in any way.
The BTT, however, splits the available space into chunks of up to 512 GiB,
@@ -33,43 +34,43 @@ called "Arenas".
Each arena follows the same layout for its metadata, and all references in an
arena are internal to it (with the exception of one field that points to the
-next arena). The following depicts the "On-disk" metadata layout:
+next arena). The following depicts the "On-disk" metadata layout::
- Backing Store +-------> Arena
-+---------------+ | +------------------+
-| | | | Arena info block |
-| Arena 0 +---+ | 4K |
-| 512G | +------------------+
-| | | |
-+---------------+ | |
-| | | |
-| Arena 1 | | Data Blocks |
-| 512G | | |
-| | | |
-+---------------+ | |
-| . | | |
-| . | | |
-| . | | |
-| | | |
-| | | |
-+---------------+ +------------------+
- | |
- | BTT Map |
- | |
- | |
- +------------------+
- | |
- | BTT Flog |
- | |
- +------------------+
- | Info block copy |
- | 4K |
- +------------------+
+ Backing Store +-------> Arena
+ +---------------+ | +------------------+
+ | | | | Arena info block |
+ | Arena 0 +---+ | 4K |
+ | 512G | +------------------+
+ | | | |
+ +---------------+ | |
+ | | | |
+ | Arena 1 | | Data Blocks |
+ | 512G | | |
+ | | | |
+ +---------------+ | |
+ | . | | |
+ | . | | |
+ | . | | |
+ | | | |
+ | | | |
+ +---------------+ +------------------+
+ | |
+ | BTT Map |
+ | |
+ | |
+ +------------------+
+ | |
+ | BTT Flog |
+ | |
+ +------------------+
+ | Info block copy |
+ | 4K |
+ +------------------+
3. Theory of Operation
-----------------------
+======================
a. The BTT Map
@@ -79,31 +80,37 @@ The map is a simple lookup/indirection table that maps an LBA to an internal
block. Each map entry is 32 bits. The two most significant bits are special
flags, and the remaining form the internal block number.
+======== =============================================================
Bit Description
-31 - 30 : Error and Zero flags - Used in the following way:
- Bit Description
- 31 30
- -----------------------------------------------------------------------
- 00 Initial state. Reads return zeroes; Premap = Postmap
- 01 Zero state: Reads return zeroes
- 10 Error state: Reads fail; Writes clear 'E' bit
- 11 Normal Block – has valid postmap
+======== =============================================================
+31 - 30 Error and Zero flags - Used in the following way:
+ == == ====================================================
+ 31 30 Description
+ == == ====================================================
+ 0 0 Initial state. Reads return zeroes; Premap = Postmap
+ 0 1 Zero state: Reads return zeroes
+ 1 0 Error state: Reads fail; Writes clear 'E' bit
+ 1 1 Normal Block – has valid postmap
+ == == ====================================================
-29 - 0 : Mappings to internal 'postmap' blocks
+29 - 0 Mappings to internal 'postmap' blocks
+======== =============================================================
Some of the terminology that will be subsequently used:
-External LBA : LBA as made visible to upper layers.
-ABA : Arena Block Address - Block offset/number within an arena
-Premap ABA : The block offset into an arena, which was decided upon by range
+============ ================================================================
+External LBA LBA as made visible to upper layers.
+ABA Arena Block Address - Block offset/number within an arena
+Premap ABA The block offset into an arena, which was decided upon by range
checking the External LBA
-Postmap ABA : The block number in the "Data Blocks" area obtained after
+Postmap ABA The block number in the "Data Blocks" area obtained after
indirection from the map
-nfree : The number of free blocks that are maintained at any given time.
+nfree The number of free blocks that are maintained at any given time.
This is the number of concurrent writes that can happen to the
arena.
+============ ================================================================
For example, after adding a BTT, we surface a disk of 1024G. We get a read for
@@ -121,19 +128,21 @@ i.e. Every write goes to a "free" block. A running list of free blocks is
maintained in the form of the BTT flog. 'Flog' is a combination of the words
"free list" and "log". The flog contains 'nfree' entries, and an entry contains:
-lba : The premap ABA that is being written to
-old_map : The old postmap ABA - after 'this' write completes, this will be a
+======== =====================================================================
+lba The premap ABA that is being written to
+old_map The old postmap ABA - after 'this' write completes, this will be a
free block.
-new_map : The new postmap ABA. The map will up updated to reflect this
+new_map The new postmap ABA. The map will up updated to reflect this
lba->postmap_aba mapping, but we log it here in case we have to
recover.
-seq : Sequence number to mark which of the 2 sections of this flog entry is
+seq Sequence number to mark which of the 2 sections of this flog entry is
valid/newest. It cycles between 01->10->11->01 (binary) under normal
operation, with 00 indicating an uninitialized state.
-lba' : alternate lba entry
-old_map': alternate old postmap entry
-new_map': alternate new postmap entry
-seq' : alternate sequence number.
+lba' alternate lba entry
+old_map' alternate old postmap entry
+new_map' alternate new postmap entry
+seq' alternate sequence number.
+======== =====================================================================
Each of the above fields is 32-bit, making one entry 32 bytes. Entries are also
padded to 64 bytes to avoid cache line sharing or aliasing. Flog updates are
@@ -147,8 +156,10 @@ c. The concept of lanes
While 'nfree' describes the number of concurrent IOs an arena can process
concurrently, 'nlanes' is the number of IOs the BTT device as a whole can
-process.
- nlanes = min(nfree, num_cpus)
+process::
+
+ nlanes = min(nfree, num_cpus)
+
A lane number is obtained at the start of any IO, and is used for indexing into
all the on-disk and in-memory data structures for the duration of the IO. If
there are more CPUs than the max number of available lanes, than lanes are
@@ -180,10 +191,10 @@ e. In-memory data structure: map locks
--------------------------------------
Consider a case where two writer threads are writing to the same LBA. There can
-be a race in the following sequence of steps:
+be a race in the following sequence of steps::
-free[lane] = map[premap_aba]
-map[premap_aba] = postmap_aba
+ free[lane] = map[premap_aba]
+ map[premap_aba] = postmap_aba
Both threads can update their respective free[lane] with the same old, freed
postmap_aba. This has made the layout inconsistent by losing a free entry, and
@@ -202,6 +213,7 @@ On startup, we analyze the BTT flog to create our list of free blocks. We walk
through all the entries, and for each lane, of the set of two possible
'sections', we always look at the most recent one only (based on the sequence
number). The reconstruction rules/steps are simple:
+
- Read map[log_entry.lba].
- If log_entry.new matches the map entry, then log_entry.old is free.
- If log_entry.new does not match the map entry, then log_entry.new is free.
@@ -228,7 +240,7 @@ Write:
1. Convert external LBA to Arena number + pre-map ABA
2. Get a lane (and take lane_lock)
3. Use lane to index into in-memory free list and obtain a new block, next flog
- index, next sequence number
+ index, next sequence number
4. Scan the RTT to check if free block is present, and spin/wait if it is.
5. Write data to this free block
6. Read map to get the existing post-map ABA entry for this pre-map ABA
@@ -245,6 +257,7 @@ Write:
An arena would be in an error state if any of the metadata is corrupted
irrecoverably, either due to a bug or a media error. The following conditions
indicate an error:
+
- Info block checksum does not match (and recovering from the copy also fails)
- All internal available blocks are not uniquely and entirely addressed by the
sum of mapped blocks and free blocks (from the BTT flog).
@@ -263,11 +276,10 @@ The BTT can be set up on any disk (namespace) exposed by the libnvdimm subsystem
(pmem, or blk mode). The easiest way to set up such a namespace is using the
'ndctl' utility [1]:
-For example, the ndctl command line to setup a btt with a 4k sector size is:
+For example, the ndctl command line to setup a btt with a 4k sector size is::
ndctl create-namespace -f -e namespace0.0 -m sector -l 4k
See ndctl create-namespace --help for more options.
[1]: https://github.com/pmem/ndctl
-
diff --git a/Documentation/nvdimm/index.rst b/Documentation/nvdimm/index.rst
new file mode 100644
index 000000000000..1a3402d3775e
--- /dev/null
+++ b/Documentation/nvdimm/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+===================================
+Non-Volatile Memory Device (NVDIMM)
+===================================
+
+.. toctree::
+ :maxdepth: 1
+
+ nvdimm
+ btt
+ security
diff --git a/Documentation/nvdimm/nvdimm.txt b/Documentation/nvdimm/nvdimm.rst
similarity index 60%
rename from Documentation/nvdimm/nvdimm.txt
rename to Documentation/nvdimm/nvdimm.rst
index 1669f626b037..08f855cbb4e6 100644
--- a/Documentation/nvdimm/nvdimm.txt
+++ b/Documentation/nvdimm/nvdimm.rst
@@ -1,8 +1,14 @@
- LIBNVDIMM: Non-Volatile Devices
- libnvdimm - kernel / libndctl - userspace helper library
- [email protected]
- v13
+===============================
+LIBNVDIMM: Non-Volatile Devices
+===============================
+libnvdimm - kernel / libndctl - userspace helper library
+
[email protected]
+
+Version 13
+
+.. contents:
Glossary
Overview
@@ -40,49 +46,57 @@
Glossary
---------
-
-PMEM: A system-physical-address range where writes are persistent. A
-block device composed of PMEM is capable of DAX. A PMEM address range
-may span an interleave of several DIMMs.
-
-BLK: A set of one or more programmable memory mapped apertures provided
-by a DIMM to access its media. This indirection precludes the
-performance benefit of interleaving, but enables DIMM-bounded failure
-modes.
-
-DPA: DIMM Physical Address, is a DIMM-relative offset. With one DIMM in
-the system there would be a 1:1 system-physical-address:DPA association.
-Once more DIMMs are added a memory controller interleave must be
-decoded to determine the DPA associated with a given
-system-physical-address. BLK capacity always has a 1:1 relationship
-with a single-DIMM's DPA range.
-
-DAX: File system extensions to bypass the page cache and block layer to
-mmap persistent memory, from a PMEM block device, directly into a
-process address space.
-
-DSM: Device Specific Method: ACPI method to to control specific
-device - in this case the firmware.
-
-DCR: NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
-It defines a vendor-id, device-id, and interface format for a given DIMM.
-
-BTT: Block Translation Table: Persistent memory is byte addressable.
-Existing software may have an expectation that the power-fail-atomicity
-of writes is at least one sector, 512 bytes. The BTT is an indirection
-table with atomic update semantics to front a PMEM/BLK block device
-driver and present arbitrary atomic sector sizes.
-
-LABEL: Metadata stored on a DIMM device that partitions and identifies
-(persistently names) storage between PMEM and BLK. It also partitions
-BLK storage to host BTTs with different parameters per BLK-partition.
-Note that traditional partition tables, GPT/MBR, are layered on top of a
-BLK or PMEM device.
+========
+
+PMEM:
+ A system-physical-address range where writes are persistent. A
+ block device composed of PMEM is capable of DAX. A PMEM address range
+ may span an interleave of several DIMMs.
+
+BLK:
+ A set of one or more programmable memory mapped apertures provided
+ by a DIMM to access its media. This indirection precludes the
+ performance benefit of interleaving, but enables DIMM-bounded failure
+ modes.
+
+DPA:
+ DIMM Physical Address, is a DIMM-relative offset. With one DIMM in
+ the system there would be a 1:1 system-physical-address:DPA association.
+ Once more DIMMs are added a memory controller interleave must be
+ decoded to determine the DPA associated with a given
+ system-physical-address. BLK capacity always has a 1:1 relationship
+ with a single-DIMM's DPA range.
+
+DAX:
+ File system extensions to bypass the page cache and block layer to
+ mmap persistent memory, from a PMEM block device, directly into a
+ process address space.
+
+DSM:
+ Device Specific Method: ACPI method to to control specific
+ device - in this case the firmware.
+
+DCR:
+ NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
+ It defines a vendor-id, device-id, and interface format for a given DIMM.
+
+BTT:
+ Block Translation Table: Persistent memory is byte addressable.
+ Existing software may have an expectation that the power-fail-atomicity
+ of writes is at least one sector, 512 bytes. The BTT is an indirection
+ table with atomic update semantics to front a PMEM/BLK block device
+ driver and present arbitrary atomic sector sizes.
+
+LABEL:
+ Metadata stored on a DIMM device that partitions and identifies
+ (persistently names) storage between PMEM and BLK. It also partitions
+ BLK storage to host BTTs with different parameters per BLK-partition.
+ Note that traditional partition tables, GPT/MBR, are layered on top of a
+ BLK or PMEM device.
Overview
---------
+========
The LIBNVDIMM subsystem provides support for three types of NVDIMMs, namely,
PMEM, BLK, and NVDIMM devices that can simultaneously support both PMEM
@@ -96,19 +110,30 @@ accessible via BLK. When that occurs a LABEL is needed to reserve DPA
for exclusive access via one mode a time.
Supporting Documents
-ACPI 6: http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
-NVDIMM Namespace: http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
-DSM Interface Example: http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
-Driver Writer's Guide: http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
+--------------------
+
+ACPI 6:
+ http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
+NVDIMM Namespace:
+ http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
+DSM Interface Example:
+ http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
+Driver Writer's Guide:
+ http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
Git Trees
-LIBNVDIMM: https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
-LIBNDCTL: https://github.com/pmem/ndctl.git
-PMEM: https://github.com/01org/prd
+---------
+
+LIBNVDIMM:
+ https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
+LIBNDCTL:
+ https://github.com/pmem/ndctl.git
+PMEM:
+ https://github.com/01org/prd
LIBNVDIMM PMEM and BLK
-------------------
+======================
Prior to the arrival of the NFIT, non-volatile memory was described to a
system in various ad-hoc ways. Usually only the bare minimum was
@@ -122,38 +147,39 @@ For each NVDIMM access method (PMEM, BLK), LIBNVDIMM provides a block
device driver:
1. PMEM (nd_pmem.ko): Drives a system-physical-address range. This
- range is contiguous in system memory and may be interleaved (hardware
- memory controller striped) across multiple DIMMs. When interleaved the
- platform may optionally provide details of which DIMMs are participating
- in the interleave.
+ range is contiguous in system memory and may be interleaved (hardware
+ memory controller striped) across multiple DIMMs. When interleaved the
+ platform may optionally provide details of which DIMMs are participating
+ in the interleave.
- Note that while LIBNVDIMM describes system-physical-address ranges that may
- alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
- alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
- distinction. The different device-types are an implementation detail
- that userspace can exploit to implement policies like "only interface
- with address ranges from certain DIMMs". It is worth noting that when
- aliasing is present and a DIMM lacks a label, then no block device can
- be created by default as userspace needs to do at least one allocation
- of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once
- registered, can be immediately attached to nd_pmem.
+ Note that while LIBNVDIMM describes system-physical-address ranges that may
+ alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
+ alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
+ distinction. The different device-types are an implementation detail
+ that userspace can exploit to implement policies like "only interface
+ with address ranges from certain DIMMs". It is worth noting that when
+ aliasing is present and a DIMM lacks a label, then no block device can
+ be created by default as userspace needs to do at least one allocation
+ of DPA to the PMEM range. In contrast ND_NAMESPACE_IO ranges, once
+ registered, can be immediately attached to nd_pmem.
2. BLK (nd_blk.ko): This driver performs I/O using a set of platform
- defined apertures. A set of apertures will access just one DIMM.
- Multiple windows (apertures) allow multiple concurrent accesses, much like
- tagged-command-queuing, and would likely be used by different threads or
- different CPUs.
+ defined apertures. A set of apertures will access just one DIMM.
+ Multiple windows (apertures) allow multiple concurrent accesses, much like
+ tagged-command-queuing, and would likely be used by different threads or
+ different CPUs.
- The NFIT specification defines a standard format for a BLK-aperture, but
- the spec also allows for vendor specific layouts, and non-NFIT BLK
- implementations may have other designs for BLK I/O. For this reason
- "nd_blk" calls back into platform-specific code to perform the I/O.
- One such implementation is defined in the "Driver Writer's Guide" and "DSM
- Interface Example".
+ The NFIT specification defines a standard format for a BLK-aperture, but
+ the spec also allows for vendor specific layouts, and non-NFIT BLK
+ implementations may have other designs for BLK I/O. For this reason
+ "nd_blk" calls back into platform-specific code to perform the I/O.
+
+ One such implementation is defined in the "Driver Writer's Guide" and "DSM
+ Interface Example".
Why BLK?
---------
+========
While PMEM provides direct byte-addressable CPU-load/store access to
NVDIMM storage, it does not provide the best system RAS (recovery,
@@ -162,12 +188,15 @@ system-physical-address address causes a CPU exception while an access
to a corrupted address through an BLK-aperture causes that block window
to raise an error status in a register. The latter is more aligned with
the standard error model that host-bus-adapter attached disks present.
+
Also, if an administrator ever wants to replace a memory it is easier to
service a system at DIMM module boundaries. Compare this to PMEM where
data could be interleaved in an opaque hardware specific manner across
several DIMMs.
PMEM vs BLK
+-----------
+
BLK-apertures solve these RAS problems, but their presence is also the
major contributing factor to the complexity of the ND subsystem. They
complicate the implementation because PMEM and BLK alias in DPA space.
@@ -185,13 +214,14 @@ carved into an arbitrary number of BLK devices with discontiguous
extents.
BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX
---------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One of the few
reasons to allow multiple BLK namespaces per REGION is so that each
BLK-namespace can be configured with a BTT with unique atomic sector
sizes. While a PMEM device can host a BTT the LABEL specification does
not provide for a sector size to be specified for a PMEM namespace.
+
This is due to the expectation that the primary usage model for PMEM is
via DAX, and the BTT is incompatible with DAX. However, for the cases
where an application or filesystem still needs atomic sector update
@@ -200,52 +230,52 @@ LIBNVDIMM/NDCTL: Block Translation Table "btt"
Example NVDIMM Platform
------------------------
+=======================
For the remainder of this document the following diagram will be
-referenced for any example sysfs layouts.
+referenced for any example sysfs layouts::
- (a) (b) DIMM BLK-REGION
- +-------------------+--------+--------+--------+
-+------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2
-| imc0 +--+- - - region0- - - +--------+ +--------+
-+--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3
- | +-------------------+--------v v--------+
-+--+---+ | |
-| cpu0 | region1
-+--+---+ | |
- | +----------------------------^ ^--------+
-+--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4
-| imc1 +--+----------------------------| +--------+
-+------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5
- +----------------------------+--------+--------+
+ (a) (b) DIMM BLK-REGION
+ +-------------------+--------+--------+--------+
+ +------+ | pm0.0 | blk2.0 | pm1.0 | blk2.1 | 0 region2
+ | imc0 +--+- - - region0- - - +--------+ +--------+
+ +--+---+ | pm0.0 | blk3.0 | pm1.0 | blk3.1 | 1 region3
+ | +-------------------+--------v v--------+
+ +--+---+ | |
+ | cpu0 | region1
+ +--+---+ | |
+ | +----------------------------^ ^--------+
+ +--+---+ | blk4.0 | pm1.0 | blk4.0 | 2 region4
+ | imc1 +--+----------------------------| +--------+
+ +------+ | blk5.0 | pm1.0 | blk5.0 | 3 region5
+ +----------------------------+--------+--------+
In this platform we have four DIMMs and two memory controllers in one
socket. Each unique interface (BLK or PMEM) to DPA space is identified
by a region device with a dynamically assigned id (REGION0 - REGION5).
1. The first portion of DIMM0 and DIMM1 are interleaved as REGION0. A
- single PMEM namespace is created in the REGION0-SPA-range that spans most
- of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
- interleaved system-physical-address range is reclaimed as BLK-aperture
- accessed space starting at DPA-offset (a) into each DIMM. In that
- reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
- REGION3 where "blk2.0" and "blk3.0" are just human readable names that
- could be set to any user-desired name in the LABEL.
+ single PMEM namespace is created in the REGION0-SPA-range that spans most
+ of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
+ interleaved system-physical-address range is reclaimed as BLK-aperture
+ accessed space starting at DPA-offset (a) into each DIMM. In that
+ reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
+ REGION3 where "blk2.0" and "blk3.0" are just human readable names that
+ could be set to any user-desired name in the LABEL.
2. In the last portion of DIMM0 and DIMM1 we have an interleaved
- system-physical-address range, REGION1, that spans those two DIMMs as
- well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace
- named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
- each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
- "blk5.0".
+ system-physical-address range, REGION1, that spans those two DIMMs as
+ well as DIMM2 and DIMM3. Some of REGION1 is allocated to a PMEM namespace
+ named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
+ each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
+ "blk5.0".
3. The portion of DIMM2 and DIMM3 that do not participate in the REGION1
- interleaved system-physical-address range (i.e. the DPA address past
- offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
- Note, that this example shows that BLK-aperture namespaces don't need to
- be contiguous in DPA-space.
+ interleaved system-physical-address range (i.e. the DPA address past
+ offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
+ Note, that this example shows that BLK-aperture namespaces don't need to
+ be contiguous in DPA-space.
This bus is provided by the kernel under the device
/sys/devices/platform/nfit_test.0 when CONFIG_NFIT_TEST is enabled and
@@ -254,7 +284,7 @@ by a region device with a dynamically assigned id (REGION0 - REGION5).
LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API
-----------------------------------------------------
+========================================================
What follows is a description of the LIBNVDIMM sysfs layout and a
corresponding object hierarchy diagram as viewed through the LIBNDCTL
@@ -263,12 +293,18 @@ NVDIMM Platform which is also the LIBNVDIMM bus used in the LIBNDCTL unit
test.
LIBNDCTL: Context
+-----------------
+
Every API call in the LIBNDCTL library requires a context that holds the
logging parameters and other library instance state. The library is
based on the libabc template:
-https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
+
+ https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
LIBNDCTL: instantiate a new library context example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
struct ndctl_ctx *ctx;
@@ -278,7 +314,7 @@ LIBNDCTL: instantiate a new library context example
return NULL;
LIBNVDIMM/LIBNDCTL: Bus
--------------------
+-----------------------
A bus has a 1:1 relationship with an NFIT. The current expectation for
ACPI based systems is that there is only ever one platform-global NFIT.
@@ -288,9 +324,10 @@ we use this capability to test multiple NFIT configurations in the unit
test.
LIBNVDIMM: control class device in /sys/class
+---------------------------------------------
This character device accepts DSM messages to be passed to DIMM
-identified by its NFIT handle.
+identified by its NFIT handle::
/sys/class/nd/ndctl0
|-- dev
@@ -300,10 +337,15 @@ identified by its NFIT handle.
LIBNVDIMM: bus
+--------------
+
+::
struct nvdimm_bus *nvdimm_bus_register(struct device *parent,
struct nvdimm_bus_descriptor *nfit_desc);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- commands
|-- nd
@@ -324,7 +366,9 @@ LIBNVDIMM: bus
`-- wait_probe
LIBNDCTL: bus enumeration example
-Find the bus handle that describes the bus from Example NVDIMM Platform
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Find the bus handle that describes the bus from Example NVDIMM Platform::
static struct ndctl_bus *get_bus_by_provider(struct ndctl_ctx *ctx,
const char *provider)
@@ -342,7 +386,7 @@ Find the bus handle that describes the bus from Example NVDIMM Platform
LIBNVDIMM/LIBNDCTL: DIMM (NMEM)
----------------------------
+-------------------------------
The DIMM device provides a character device for sending commands to
hardware, and it is a container for LABELs. If the DIMM is defined by
@@ -355,11 +399,16 @@ Range Mapping Structure", and there is no requirement that they actually
be physical DIMMs, so we use a more generic name.
LIBNVDIMM: DIMM (NMEM)
+^^^^^^^^^^^^^^^^^^^^^^
+
+::
struct nvdimm *nvdimm_create(struct nvdimm_bus *nvdimm_bus, void *provider_data,
const struct attribute_group **groups, unsigned long flags,
unsigned long *dsm_mask);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- nmem0
| |-- available_slots
@@ -384,15 +433,20 @@ LIBNVDIMM: DIMM (NMEM)
LIBNDCTL: DIMM enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note, in this example we are assuming NFIT-defined DIMMs which are
identified by an "nfit_handle" a 32-bit value where:
-Bit 3:0 DIMM number within the memory channel
-Bit 7:4 memory channel number
-Bit 11:8 memory controller ID
-Bit 15:12 socket ID (within scope of a Node controller if node controller is present)
-Bit 27:16 Node Controller ID
-Bit 31:28 Reserved
+
+ - Bit 3:0 DIMM number within the memory channel
+ - Bit 7:4 memory channel number
+ - Bit 11:8 memory controller ID
+ - Bit 15:12 socket ID (within scope of a Node controller if node
+ controller is present)
+ - Bit 27:16 Node Controller ID
+ - Bit 31:28 Reserved
+
+::
static struct ndctl_dimm *get_dimm_by_handle(struct ndctl_bus *bus,
unsigned int handle)
@@ -413,7 +467,7 @@ Bit 31:28 Reserved
dimm = get_dimm_by_handle(bus, DIMM_HANDLE(0, 0, 0, 0, 0));
LIBNVDIMM/LIBNDCTL: Region
-----------------------
+--------------------------
A generic REGION device is registered for each PMEM range or BLK-aperture
set. Per the example there are 6 regions: 2 PMEM and 4 BLK-aperture
@@ -435,13 +489,15 @@ emits, "devtype" duplicates the DEVTYPE variable stored by udev at the
at the 'add' event, and finally, the optional "spa_index" is provided in
the case where the region is defined by a SPA.
-LIBNVDIMM: region
+LIBNVDIMM: region::
struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus,
struct nd_region_desc *ndr_desc);
struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus,
struct nd_region_desc *ndr_desc);
+::
+
/sys/devices/platform/nfit_test.0/ndbus0
|-- region0
| |-- available_size
@@ -468,10 +524,11 @@ LIBNVDIMM: region
[..]
LIBNDCTL: region enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sample region retrieval routines based on NFIT-unique data like
"spa_index" (interleave set id) for PMEM and "nfit_handle" (dimm id) for
-BLK.
+BLK::
static struct ndctl_region *get_pmem_region_by_spa_index(struct ndctl_bus *bus,
unsigned int spa_index)
@@ -518,33 +575,33 @@ REGION name generic and expects userspace to always consider the
region-attributes for four reasons:
1. There are already more than two REGION and "namespace" types. For
- PMEM there are two subtypes. As mentioned previously we have PMEM where
- the constituent DIMM devices are known and anonymous PMEM. For BLK
- regions the NFIT specification already anticipates vendor specific
- implementations. The exact distinction of what a region contains is in
- the region-attributes not the region-name or the region-devtype.
+ PMEM there are two subtypes. As mentioned previously we have PMEM where
+ the constituent DIMM devices are known and anonymous PMEM. For BLK
+ regions the NFIT specification already anticipates vendor specific
+ implementations. The exact distinction of what a region contains is in
+ the region-attributes not the region-name or the region-devtype.
2. A region with zero child-namespaces is a possible configuration. For
- example, the NFIT allows for a DCR to be published without a
- corresponding BLK-aperture. This equates to a DIMM that can only accept
- control/configuration messages, but no i/o through a descendant block
- device. Again, this "type" is advertised in the attributes ('mappings'
- == 0) and the name does not tell you much.
+ example, the NFIT allows for a DCR to be published without a
+ corresponding BLK-aperture. This equates to a DIMM that can only accept
+ control/configuration messages, but no i/o through a descendant block
+ device. Again, this "type" is advertised in the attributes ('mappings'
+ == 0) and the name does not tell you much.
3. What if a third major interface type arises in the future? Outside
- of vendor specific implementations, it's not difficult to envision a
- third class of interface type beyond BLK and PMEM. With a generic name
- for the REGION level of the device-hierarchy old userspace
- implementations can still make sense of new kernel advertised
- region-types. Userspace can always rely on the generic region
- attributes like "mappings", "size", etc and the expected child devices
- named "namespace". This generic format of the device-model hierarchy
- allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
- future-proof.
+ of vendor specific implementations, it's not difficult to envision a
+ third class of interface type beyond BLK and PMEM. With a generic name
+ for the REGION level of the device-hierarchy old userspace
+ implementations can still make sense of new kernel advertised
+ region-types. Userspace can always rely on the generic region
+ attributes like "mappings", "size", etc and the expected child devices
+ named "namespace". This generic format of the device-model hierarchy
+ allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
+ future-proof.
4. There are more robust mechanisms for determining the major type of a
- region than a device name. See the next section, How Do I Determine the
- Major Type of a Region?
+ region than a device name. See the next section, How Do I Determine the
+ Major Type of a Region?
How Do I Determine the Major Type of a Region?
----------------------------------------------
@@ -553,7 +610,8 @@ Outside of the blanket recommendation of "use libndctl", or simply
looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
"nstype" integer attribute, here are some other options.
- 1. module alias lookup:
+1. module alias lookup
+^^^^^^^^^^^^^^^^^^^^^^
The whole point of region/namespace device type differentiation is to
decide which block-device driver will attach to a given LIBNVDIMM namespace.
@@ -569,28 +627,31 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
the resulting namespaces. The output from module resolution is more
accurate than a region-name or region-devtype.
- 2. udev:
+2. udev
+^^^^^^^
- The kernel "devtype" is registered in the udev database
- # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
- P: /devices/platform/nfit_test.0/ndbus0/region0
- E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
- E: DEVTYPE=nd_pmem
- E: MODALIAS=nd:t2
- E: SUBSYSTEM=nd
+ The kernel "devtype" is registered in the udev database::
- # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
- P: /devices/platform/nfit_test.0/ndbus0/region4
- E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
- E: DEVTYPE=nd_blk
- E: MODALIAS=nd:t3
- E: SUBSYSTEM=nd
+ # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
+ P: /devices/platform/nfit_test.0/ndbus0/region0
+ E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
+ E: DEVTYPE=nd_pmem
+ E: MODALIAS=nd:t2
+ E: SUBSYSTEM=nd
+
+ # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
+ P: /devices/platform/nfit_test.0/ndbus0/region4
+ E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
+ E: DEVTYPE=nd_blk
+ E: MODALIAS=nd:t3
+ E: SUBSYSTEM=nd
...and is available as a region attribute, but keep in mind that the
"devtype" does not indicate sub-type variations and scripts should
really be understanding the other attributes.
- 3. type specific attributes:
+3. type specific attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
As it currently stands a BLK-aperture region will never have a
"nfit/spa_index" attribute, but neither will a non-NFIT PMEM region. A
@@ -600,7 +661,7 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
LIBNVDIMM/LIBNDCTL: Namespace
--------------------------
+-----------------------------
A REGION, after resolving DPA aliasing and LABEL specified boundaries,
surfaces one or more "namespace" devices. The arrival of a "namespace"
@@ -608,12 +669,14 @@ device currently triggers either the nd_blk or nd_pmem driver to load
and register a disk/block device.
LIBNVDIMM: namespace
+^^^^^^^^^^^^^^^^^^^^
+
Here is a sample layout from the three major types of NAMESPACE where
namespace0.0 represents DIMM-info-backed PMEM (note that it has a 'uuid'
attribute), namespace2.0 represents a BLK namespace (note it has a
'sector_size' attribute) that, and namespace6.0 represents an anonymous
PMEM namespace (note that has no 'uuid' attribute due to not support a
-LABEL).
+LABEL)::
/sys/devices/platform/nfit_test.0/ndbus0/region0/namespace0.0
|-- alt_name
@@ -656,76 +719,84 @@ LABEL).
`-- uevent
LIBNDCTL: namespace enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Namespaces are indexed relative to their parent region, example below.
These indexes are mostly static from boot to boot, but subsystem makes
no guarantees in this regard. For a static namespace identifier use its
'uuid' attribute.
-static struct ndctl_namespace *get_namespace_by_id(struct ndctl_region *region,
- unsigned int id)
-{
- struct ndctl_namespace *ndns;
+::
- ndctl_namespace_foreach(region, ndns)
- if (ndctl_namespace_get_id(ndns) == id)
- return ndns;
+ static struct ndctl_namespace
+ *get_namespace_by_id(struct ndctl_region *region, unsigned int id)
+ {
+ struct ndctl_namespace *ndns;
- return NULL;
-}
+ ndctl_namespace_foreach(region, ndns)
+ if (ndctl_namespace_get_id(ndns) == id)
+ return ndns;
+
+ return NULL;
+ }
LIBNDCTL: namespace creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Idle namespaces are automatically created by the kernel if a given
region has enough available capacity to create a new namespace.
Namespace instantiation involves finding an idle namespace and
configuring it. For the most part the setting of namespace attributes
can occur in any order, the only constraint is that 'uuid' must be set
before 'size'. This enables the kernel to track DPA allocations
-internally with a static identifier.
+internally with a static identifier::
-static int configure_namespace(struct ndctl_region *region,
- struct ndctl_namespace *ndns,
- struct namespace_parameters *parameters)
-{
- char devname[50];
+ static int configure_namespace(struct ndctl_region *region,
+ struct ndctl_namespace *ndns,
+ struct namespace_parameters *parameters)
+ {
+ char devname[50];
- snprintf(devname, sizeof(devname), "namespace%d.%d",
- ndctl_region_get_id(region), paramaters->id);
+ snprintf(devname, sizeof(devname), "namespace%d.%d",
+ ndctl_region_get_id(region), paramaters->id);
- ndctl_namespace_set_alt_name(ndns, devname);
- /* 'uuid' must be set prior to setting size! */
- ndctl_namespace_set_uuid(ndns, paramaters->uuid);
- ndctl_namespace_set_size(ndns, paramaters->size);
- /* unlike pmem namespaces, blk namespaces have a sector size */
- if (parameters->lbasize)
- ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
- ndctl_namespace_enable(ndns);
-}
+ ndctl_namespace_set_alt_name(ndns, devname);
+ /* 'uuid' must be set prior to setting size! */
+ ndctl_namespace_set_uuid(ndns, paramaters->uuid);
+ ndctl_namespace_set_size(ndns, paramaters->size);
+ /* unlike pmem namespaces, blk namespaces have a sector size */
+ if (parameters->lbasize)
+ ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
+ ndctl_namespace_enable(ndns);
+ }
Why the Term "namespace"?
+^^^^^^^^^^^^^^^^^^^^^^^^^
1. Why not "volume" for instance? "volume" ran the risk of confusing
- ND (libnvdimm subsystem) to a volume manager like device-mapper.
+ ND (libnvdimm subsystem) to a volume manager like device-mapper.
2. The term originated to describe the sub-devices that can be created
- within a NVME controller (see the nvme specification:
- http://www.nvmexpress.org/specifications/), and NFIT namespaces are
- meant to parallel the capabilities and configurability of
- NVME-namespaces.
+ within a NVME controller (see the nvme specification:
+ http://www.nvmexpress.org/specifications/), and NFIT namespaces are
+ meant to parallel the capabilities and configurability of
+ NVME-namespaces.
LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
----------------------------------------------
+-------------------------------------------------
A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked
block device driver that fronts either the whole block device or a
partition of a block device emitted by either a PMEM or BLK NAMESPACE.
LIBNVDIMM: btt layout
+^^^^^^^^^^^^^^^^^^^^^
+
Every region will start out with at least one BTT device which is the
seed device. To activate it set the "namespace", "uuid", and
"sector_size" attributes and then bind the device to the nd_pmem or
-nd_blk driver depending on the region type.
+nd_blk driver depending on the region type::
/sys/devices/platform/nfit_test.1/ndbus0/region0/btt0/
|-- namespace
@@ -739,10 +810,12 @@ nd_blk driver depending on the region type.
`-- uuid
LIBNDCTL: btt creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Similar to namespaces an idle BTT device is automatically created per
region. Each time this "seed" btt device is configured and enabled a new
seed is created. Creating a BTT configuration involves two steps of
-finding and idle BTT and assigning it to consume a PMEM or BLK namespace.
+finding and idle BTT and assigning it to consume a PMEM or BLK namespace::
static struct ndctl_btt *get_idle_btt(struct ndctl_region *region)
{
@@ -787,29 +860,28 @@ Summary LIBNDCTL Diagram
------------------------
For the given example above, here is the view of the objects as seen by the
-LIBNDCTL API:
- +---+
- |CTX| +---------+ +--------------+ +---------------+
- +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
- | | +---------+ +--------------+ +---------------+
-+-------+ | | +---------+ +--------------+ +---------------+
-| DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
-+-------+ | | | +---------+ +--------------+ +---------------+
-| DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+
-+-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" |
-| DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+
-+-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 |
-| DIMM3 <-+ | +--------------+ +----------------------+
-+-------+ | +---------+ +--------------+ +---------------+
- +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" |
- | +---------+ | +--------------+ +----------------------+
- | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 |
- | +--------------+ +----------------------+
- | +---------+ +--------------+ +---------------+
- +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" |
- | +---------+ +--------------+ +---------------+
- | +---------+ +--------------+ +----------------------+
- +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 |
- +---------+ +--------------+ +---------------+------+
-
+LIBNDCTL API::
+ +---+
+ |CTX| +---------+ +--------------+ +---------------+
+ +-+-+ +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
+ | | +---------+ +--------------+ +---------------+
+ +-------+ | | +---------+ +--------------+ +---------------+
+ | DIMM0 <-+ | +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
+ +-------+ | | | +---------+ +--------------+ +---------------+
+ | DIMM1 <-+ +-v--+ | +---------+ +--------------+ +---------------+
+ +-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6 "blk2.0" |
+ | DIMM2 <-+ +----+ | +---------+ | +--------------+ +----------------------+
+ +-------+ | | +-> NAMESPACE2.1 +--> ND5 "blk2.1" | BTT2 |
+ | DIMM3 <-+ | +--------------+ +----------------------+
+ +-------+ | +---------+ +--------------+ +---------------+
+ +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4 "blk3.0" |
+ | +---------+ | +--------------+ +----------------------+
+ | +-> NAMESPACE3.1 +--> ND3 "blk3.1" | BTT1 |
+ | +--------------+ +----------------------+
+ | +---------+ +--------------+ +---------------+
+ +-> REGION4 +---> NAMESPACE4.0 +--> ND2 "blk4.0" |
+ | +---------+ +--------------+ +---------------+
+ | +---------+ +--------------+ +----------------------+
+ +-> REGION5 +---> NAMESPACE5.0 +--> ND1 "blk5.0" | BTT0 |
+ +---------+ +--------------+ +---------------+------+
diff --git a/Documentation/nvdimm/security.txt b/Documentation/nvdimm/security.rst
similarity index 99%
rename from Documentation/nvdimm/security.txt
rename to Documentation/nvdimm/security.rst
index 4c36c05ca98e..ad9dea099b34 100644
--- a/Documentation/nvdimm/security.txt
+++ b/Documentation/nvdimm/security.rst
@@ -1,4 +1,5 @@
-NVDIMM SECURITY
+===============
+NVDIMM Security
===============
1. Introduction
@@ -138,4 +139,5 @@ This command is only available when the master security is enabled, indicated
by the extended security status.
[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
+
[2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
diff --git a/drivers/nvdimm/Kconfig b/drivers/nvdimm/Kconfig
index 54500798f23a..e89c1c332407 100644
--- a/drivers/nvdimm/Kconfig
+++ b/drivers/nvdimm/Kconfig
@@ -33,7 +33,7 @@ config BLK_DEV_PMEM
Documentation/admin-guide/kernel-parameters.rst). This driver converts
these persistent memory ranges into block devices that are
capable of DAX (direct-access) file system mappings. See
- Documentation/nvdimm/nvdimm.txt for more details.
+ Documentation/nvdimm/nvdimm.rst for more details.
Say Y if you want to use an NVDIMM
--
2.21.0
In order to be able to add it into a doc book, we need first
convert it to ReST.
The conversion is actually:
- add blank lines and identation in order to identify paragraphs;
- mark literal blocks;
- adjust title markups.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 ++++++++++---------
1 file changed, 59 insertions(+), 53 deletions(-)
rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)
diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.rst
similarity index 62%
rename from Documentation/nvmem/nvmem.txt
rename to Documentation/nvmem/nvmem.rst
index fc2fe4b18655..3866b6e066d5 100644
--- a/Documentation/nvmem/nvmem.txt
+++ b/Documentation/nvmem/nvmem.rst
@@ -1,5 +1,10 @@
- NVMEM SUBSYSTEM
- Srinivas Kandagatla <[email protected]>
+:orphan:
+
+===============
+NVMEM Subsystem
+===============
+
+ Srinivas Kandagatla <[email protected]>
This document explains the NVMEM Framework along with the APIs provided,
and how to use it.
@@ -40,54 +45,54 @@ nvmem_device pointer.
nvmem_unregister(nvmem) is used to unregister a previously registered provider.
-For example, a simple qfprom case:
+For example, a simple qfprom case::
-static struct nvmem_config econfig = {
+ static struct nvmem_config econfig = {
.name = "qfprom",
.owner = THIS_MODULE,
-};
+ };
-static int qfprom_probe(struct platform_device *pdev)
-{
+ static int qfprom_probe(struct platform_device *pdev)
+ {
...
econfig.dev = &pdev->dev;
nvmem = nvmem_register(&econfig);
...
-}
+ }
It is mandatory that the NVMEM provider has a regmap associated with its
struct device. Failure to do would return error code from nvmem_register().
Users of board files can define and register nvmem cells using the
-nvmem_cell_table struct:
+nvmem_cell_table struct::
-static struct nvmem_cell_info foo_nvmem_cells[] = {
+ static struct nvmem_cell_info foo_nvmem_cells[] = {
{
.name = "macaddr",
.offset = 0x7f00,
.bytes = ETH_ALEN,
}
-};
+ };
-static struct nvmem_cell_table foo_nvmem_cell_table = {
+ static struct nvmem_cell_table foo_nvmem_cell_table = {
.nvmem_name = "i2c-eeprom",
.cells = foo_nvmem_cells,
.ncells = ARRAY_SIZE(foo_nvmem_cells),
-};
+ };
-nvmem_add_cell_table(&foo_nvmem_cell_table);
+ nvmem_add_cell_table(&foo_nvmem_cell_table);
Additionally it is possible to create nvmem cell lookup entries and register
-them with the nvmem framework from machine code as shown in the example below:
+them with the nvmem framework from machine code as shown in the example below::
-static struct nvmem_cell_lookup foo_nvmem_lookup = {
+ static struct nvmem_cell_lookup foo_nvmem_lookup = {
.nvmem_name = "i2c-eeprom",
.cell_name = "macaddr",
.dev_id = "foo_mac.0",
.con_id = "mac-address",
-};
+ };
-nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
+ nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
NVMEM Consumers
+++++++++++++++
@@ -99,43 +104,43 @@ read from and to NVMEM.
=================================
NVMEM cells are the data entries/fields in the NVMEM.
-The NVMEM framework provides 3 APIs to read/write NVMEM cells.
+The NVMEM framework provides 3 APIs to read/write NVMEM cells::
-struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
-struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
+ struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
+ struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+ void nvmem_cell_put(struct nvmem_cell *cell);
+ void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
-int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
+ void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
+ int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
-*nvmem_cell_get() apis will get a reference to nvmem cell for a given id,
+`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
and nvmem_cell_read/write() can then read or write to the cell.
-Once the usage of the cell is finished the consumer should call *nvmem_cell_put()
-to free all the allocation memory for the cell.
+Once the usage of the cell is finished the consumer should call
+`*nvmem_cell_put()` to free all the allocation memory for the cell.
4. Direct NVMEM device based consumer APIs
==========================================
In some instances it is necessary to directly read/write the NVMEM.
-To facilitate such consumers NVMEM framework provides below apis.
+To facilitate such consumers NVMEM framework provides below apis::
-struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
-struct nvmem_device *devm_nvmem_device_get(struct device *dev,
+ struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
+ struct nvmem_device *devm_nvmem_device_get(struct device *dev,
const char *name);
-void nvmem_device_put(struct nvmem_device *nvmem);
-int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
+ void nvmem_device_put(struct nvmem_device *nvmem);
+ int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf);
-int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
+ int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
size_t bytes, void *buf);
-int nvmem_device_cell_read(struct nvmem_device *nvmem,
+ int nvmem_device_cell_read(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf);
-int nvmem_device_cell_write(struct nvmem_device *nvmem,
+ int nvmem_device_cell_write(struct nvmem_device *nvmem,
struct nvmem_cell_info *info, void *buf);
Before the consumers can read/write NVMEM directly, it should get hold
-of nvmem_controller from one of the *nvmem_device_get() api.
+of nvmem_controller from one of the `*nvmem_device_get()` api.
The difference between these apis and cell based apis is that these apis always
take nvmem_device as parameter.
@@ -145,12 +150,12 @@ take nvmem_device as parameter.
When a consumer no longer needs the NVMEM, it has to release the reference
to the NVMEM it has obtained using the APIs mentioned in the above section.
-The NVMEM framework provides 2 APIs to release a reference to the NVMEM.
+The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void nvmem_device_put(struct nvmem_device *nvmem);
-void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
+ void nvmem_cell_put(struct nvmem_cell *cell);
+ void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+ void nvmem_device_put(struct nvmem_device *nvmem);
+ void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
Both these APIs are used to release a reference to the NVMEM and
devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
@@ -162,20 +167,21 @@ Userspace
6. Userspace binary interface
==============================
-Userspace can read/write the raw NVMEM file located at
-/sys/bus/nvmem/devices/*/nvmem
+Userspace can read/write the raw NVMEM file located at::
-ex:
+ /sys/bus/nvmem/devices/*/nvmem
-hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ex::
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-*
-00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-...
-*
-0001000
+ hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ *
+ 00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+ 0000000 0000 0000 0000 0000 0000 0000 0000 0000
+ ...
+ *
+ 0001000
7. DeviceTree Binding
=====================
--
2.21.0
Convert this small file to ReST in preparation for adding it to
the driver-api book.
While this is not part of the driver-api book, mark it as
:orphan:, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../console/{console.txt => console.rst} | 63 ++++++++++---------
Documentation/fb/fbcon.rst | 4 +-
drivers/tty/Kconfig | 2 +-
3 files changed, 38 insertions(+), 31 deletions(-)
rename Documentation/console/{console.txt => console.rst} (80%)
diff --git a/Documentation/console/console.txt b/Documentation/console/console.rst
similarity index 80%
rename from Documentation/console/console.txt
rename to Documentation/console/console.rst
index d73c2ab4beda..b374141b027e 100644
--- a/Documentation/console/console.txt
+++ b/Documentation/console/console.rst
@@ -1,3 +1,6 @@
+:orphan:
+
+===============
Console Drivers
===============
@@ -17,25 +20,26 @@ of driver occupying the consoles.) They can only take over the console that is
occupied by the system driver. In the same token, if the modular driver is
released by the console, the system driver will take over.
-Modular drivers, from the programmer's point of view, have to call:
+Modular drivers, from the programmer's point of view, have to call::
do_take_over_console() - load and bind driver to console layer
give_up_console() - unload driver; it will only work if driver
is fully unbound
-In newer kernels, the following are also available:
+In newer kernels, the following are also available::
do_register_con_driver()
do_unregister_con_driver()
If sysfs is enabled, the contents of /sys/class/vtconsole can be
examined. This shows the console backends currently registered by the
-system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus:
+system which are named vtcon<n> where <n> is an integer from 0 to 15.
+Thus::
ls /sys/class/vtconsole
. .. vtcon0 vtcon1
-Each directory in /sys/class/vtconsole has 3 files:
+Each directory in /sys/class/vtconsole has 3 files::
ls /sys/class/vtconsole/vtcon0
. .. bind name uevent
@@ -46,27 +50,29 @@ What do these files signify?
read, or acts to bind or unbind the driver to the virtual consoles
when written to. The possible values are:
- 0 - means the driver is not bound and if echo'ed, commands the driver
+ 0
+ - means the driver is not bound and if echo'ed, commands the driver
to unbind
- 1 - means the driver is bound and if echo'ed, commands the driver to
+ 1
+ - means the driver is bound and if echo'ed, commands the driver to
bind
- 2. name - read-only file. Shows the name of the driver in this format:
+ 2. name - read-only file. Shows the name of the driver in this format::
- cat /sys/class/vtconsole/vtcon0/name
- (S) VGA+
+ cat /sys/class/vtconsole/vtcon0/name
+ (S) VGA+
- '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
- commanded to bind or unbind
+ '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
+ commanded to bind or unbind
- 'VGA+' is the name of the driver
+ 'VGA+' is the name of the driver
- cat /sys/class/vtconsole/vtcon1/name
- (M) frame buffer device
+ cat /sys/class/vtconsole/vtcon1/name
+ (M) frame buffer device
- In this case, '(M)' stands for a (M)odular driver, one that can be
- directly commanded to bind or unbind.
+ In this case, '(M)' stands for a (M)odular driver, one that can be
+ directly commanded to bind or unbind.
3. uevent - ignore this file
@@ -75,14 +81,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other
hand, will bind the driver to the consoles that are currently occupied by a
system driver.
-NOTE1: Binding and unbinding must be selected in Kconfig. It's under:
+NOTE1:
+ Binding and unbinding must be selected in Kconfig. It's under::
-Device Drivers -> Character devices -> Support for binding and unbinding
-console drivers
+ Device Drivers ->
+ Character devices ->
+ Support for binding and unbinding console drivers
-NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
-unbinding will not succeed. An example of an application that sets the console
-to KD_GRAPHICS is X.
+NOTE2:
+ If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
+ unbinding will not succeed. An example of an application that sets the
+ console to KD_GRAPHICS is X.
How useful is this feature? This is very useful for console driver
developers. By unbinding the driver from the console layer, one can unload the
@@ -92,10 +101,10 @@ framebuffer console to VGA console and vice versa, this feature also makes
this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
for more details.)
-Notes for developers:
-=====================
+Notes for developers
+====================
-do_take_over_console() is now broken up into:
+do_take_over_console() is now broken up into::
do_register_con_driver()
do_bind_con_driver() - private function
@@ -104,7 +113,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must
be fully unbound for this call to succeed. con_is_bound() will check if the
driver is bound or not.
-Guidelines for console driver writers:
+Guidelines for console driver writers
=====================================
In order for binding to and unbinding from the console to properly work,
@@ -140,6 +149,4 @@ The current crop of console drivers should still work correctly, but binding
and unbinding them may cause problems. With minimal fixes, these drivers can
be made to work correctly.
-==========================
Antonino Daplas <[email protected]>
-
diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst
index cfb9f7c38f18..22112718dd5d 100644
--- a/Documentation/fb/fbcon.rst
+++ b/Documentation/fb/fbcon.rst
@@ -187,7 +187,7 @@ the hardware. Thus, in a VGA console::
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
unloaded if it is still bound to the console layer. (See
-Documentation/console/console.txt for more information).
+Documentation/console/console.rst 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::
@@ -204,7 +204,7 @@ fbcon. Thus, there is no need to explicitly unbind the fbdev drivers from
fbcon.
So, how do we unbind fbcon from the console? Part of the answer is in
-Documentation/console/console.txt. To summarize:
+Documentation/console/console.rst. To summarize:
Echo a value to the bind file that represents the framebuffer console
driver. So assuming vtcon1 represents fbcon, then::
diff --git a/drivers/tty/Kconfig b/drivers/tty/Kconfig
index 0e3e4dacbc12..1cb50f19d58c 100644
--- a/drivers/tty/Kconfig
+++ b/drivers/tty/Kconfig
@@ -93,7 +93,7 @@ config VT_HW_CONSOLE_BINDING
select the console driver that will serve as the backend for the
virtual terminals.
- See <file:Documentation/console/console.txt> for more
+ See <file:Documentation/console/console.rst> for more
information. For framebuffer console users, please refer to
<file:Documentation/fb/fbcon.rst>.
--
2.21.0
Rename the namespaces documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
There are two upper case file names. Rename them to
lower case, as we're working to avoid upper case file
names at Documentation.
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 <[email protected]>
---
...{compatibility-list.txt => compatibility-list.rst} | 10 +++++++---
Documentation/namespaces/index.rst | 11 +++++++++++
.../{resource-control.txt => resource-control.rst} | 4 ++++
3 files changed, 22 insertions(+), 3 deletions(-)
rename Documentation/namespaces/{compatibility-list.txt => compatibility-list.rst} (86%)
create mode 100644 Documentation/namespaces/index.rst
rename Documentation/namespaces/{resource-control.txt => resource-control.rst} (89%)
diff --git a/Documentation/namespaces/compatibility-list.txt b/Documentation/namespaces/compatibility-list.rst
similarity index 86%
rename from Documentation/namespaces/compatibility-list.txt
rename to Documentation/namespaces/compatibility-list.rst
index defc5589bfcd..318800b2a943 100644
--- a/Documentation/namespaces/compatibility-list.txt
+++ b/Documentation/namespaces/compatibility-list.rst
@@ -1,4 +1,6 @@
- Namespaces compatibility list
+=============================
+Namespaces compatibility list
+=============================
This document contains the information about the problems user
may have when creating tasks living in different namespaces.
@@ -7,13 +9,16 @@ Here's the summary. This matrix shows the known problems, that
occur when tasks share some namespace (the columns) while living
in different other namespaces (the rows):
- UTS IPC VFS PID User Net
+==== === === === === ==== ===
+- UTS IPC VFS PID User Net
+==== === === === === ==== ===
UTS X
IPC X 1
VFS X
PID 1 1 X
User 2 2 X
Net X
+==== === === === === ==== ===
1. Both the IPC and the PID namespaces provide IDs to address
object inside the kernel. E.g. semaphore with IPCID or
@@ -36,4 +41,3 @@ Net X
even having equal UIDs.
But currently this is not so.
-
diff --git a/Documentation/namespaces/index.rst b/Documentation/namespaces/index.rst
new file mode 100644
index 000000000000..bf40625dd11a
--- /dev/null
+++ b/Documentation/namespaces/index.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+==========
+Namespaces
+==========
+
+.. toctree::
+ :maxdepth: 1
+
+ compatibility-list
+ resource-control
diff --git a/Documentation/namespaces/resource-control.txt b/Documentation/namespaces/resource-control.rst
similarity index 89%
rename from Documentation/namespaces/resource-control.txt
rename to Documentation/namespaces/resource-control.rst
index abc13c394738..369556e00f0c 100644
--- a/Documentation/namespaces/resource-control.txt
+++ b/Documentation/namespaces/resource-control.rst
@@ -1,3 +1,7 @@
+===========================
+Namespaces research control
+===========================
+
There are a lot of kinds of objects in the kernel that don't have
individual limits or that have limits that are ineffective when a set
of processes is allowed to switch user ids. With user namespaces
--
2.21.0
Rename the md documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.
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 <[email protected]>
---
Documentation/md/index.rst | 12 ++
.../md/{md-cluster.txt => md-cluster.rst} | 188 ++++++++++++------
.../md/{raid5-cache.txt => raid5-cache.rst} | 28 +--
.../md/{raid5-ppl.txt => raid5-ppl.rst} | 2 +
4 files changed, 153 insertions(+), 77 deletions(-)
create mode 100644 Documentation/md/index.rst
rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)
diff --git a/Documentation/md/index.rst b/Documentation/md/index.rst
new file mode 100644
index 000000000000..c4db34ed327d
--- /dev/null
+++ b/Documentation/md/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+====
+RAID
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ md-cluster
+ raid5-cache
+ raid5-ppl
diff --git a/Documentation/md/md-cluster.txt b/Documentation/md/md-cluster.rst
similarity index 68%
rename from Documentation/md/md-cluster.txt
rename to Documentation/md/md-cluster.rst
index e1055f105cf5..96eb52cec7eb 100644
--- a/Documentation/md/md-cluster.txt
+++ b/Documentation/md/md-cluster.rst
@@ -1,19 +1,24 @@
+==========
+MD Cluster
+==========
+
The cluster MD is a shared-device RAID for a cluster, it supports
two levels: raid1 and raid10 (limited support).
1. On-disk format
+=================
Separate write-intent-bitmaps are used for each cluster node.
The bitmaps record all writes that may have been started on that node,
-and may not yet have finished. The on-disk layout is:
+and may not yet have finished. The on-disk layout is::
-0 4k 8k 12k
--------------------------------------------------------------------
-| idle | md super | bm super [0] + bits |
-| bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] |
-| bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits |
-| bm bits [3, contd] | | |
+ 0 4k 8k 12k
+ -------------------------------------------------------------------
+ | idle | md super | bm super [0] + bits |
+ | bm bits[0, contd] | bm super[1] + bits | bm bits[1, contd] |
+ | bm super[2] + bits | bm bits [2, contd] | bm super[3] + bits |
+ | bm bits [3, contd] | | |
During "normal" functioning we assume the filesystem ensures that only
one node writes to any given block at a time, so a write request will
@@ -28,10 +33,12 @@ node) is writing.
2. DLM Locks for management
+===========================
There are three groups of locks for managing the device:
2.1 Bitmap lock resource (bm_lockres)
+-------------------------------------
The bm_lockres protects individual node bitmaps. They are named in
the form bitmap000 for node 1, bitmap001 for node 2 and so on. When a
@@ -48,6 +55,7 @@ There are three groups of locks for managing the device:
joins the cluster.
2.2 Message passing locks
+-------------------------
Each node has to communicate with other nodes when starting or ending
resync, and for metadata superblock updates. This communication is
@@ -55,116 +63,155 @@ There are three groups of locks for managing the device:
with the Lock Value Block (LVB) of one of the "message" lock.
2.3 new-device management
+-------------------------
A single lock: "no-new-dev" is used to co-ordinate the addition of
new devices - this must be synchronized across the array.
Normally all nodes hold a concurrent-read lock on this device.
3. Communication
+================
Messages can be broadcast to all nodes, and the sender waits for all
other nodes to acknowledge the message before proceeding. Only one
message can be processed at a time.
3.1 Message Types
+-----------------
There are six types of messages which are passed:
- 3.1.1 METADATA_UPDATED: informs other nodes that the metadata has
+3.1.1 METADATA_UPDATED
+^^^^^^^^^^^^^^^^^^^^^^
+
+ informs other nodes that the metadata has
been updated, and the node must re-read the md superblock. This is
performed synchronously. It is primarily used to signal device
failure.
- 3.1.2 RESYNCING: informs other nodes that a resync is initiated or
+3.1.2 RESYNCING
+^^^^^^^^^^^^^^^
+ informs other nodes that a resync is initiated or
ended so that each node may suspend or resume the region. Each
RESYNCING message identifies a range of the devices that the
sending node is about to resync. This overrides any previous
notification from that node: only one ranged can be resynced at a
time per-node.
- 3.1.3 NEWDISK: informs other nodes that a device is being added to
+3.1.3 NEWDISK
+^^^^^^^^^^^^^
+
+ informs other nodes that a device is being added to
the array. Message contains an identifier for that device. See
below for further details.
- 3.1.4 REMOVE: A failed or spare device is being removed from the
+3.1.4 REMOVE
+^^^^^^^^^^^^
+
+ A failed or spare device is being removed from the
array. The slot-number of the device is included in the message.
- 3.1.5 RE_ADD: A failed device is being re-activated - the assumption
+ 3.1.5 RE_ADD:
+
+ A failed device is being re-activated - the assumption
is that it has been determined to be working again.
- 3.1.6 BITMAP_NEEDS_SYNC: if a node is stopped locally but the bitmap
+ 3.1.6 BITMAP_NEEDS_SYNC:
+
+ If a node is stopped locally but the bitmap
isn't clean, then another node is informed to take the ownership of
resync.
3.2 Communication mechanism
+---------------------------
The DLM LVB is used to communicate within nodes of the cluster. There
are three resources used for the purpose:
- 3.2.1 token: The resource which protects the entire communication
+3.2.1 token
+^^^^^^^^^^^
+ The resource which protects the entire communication
system. The node having the token resource is allowed to
communicate.
- 3.2.2 message: The lock resource which carries the data to
- communicate.
+3.2.2 message
+^^^^^^^^^^^^^
+ The lock resource which carries the data to communicate.
- 3.2.3 ack: The resource, acquiring which means the message has been
+3.2.3 ack
+^^^^^^^^^
+
+ The resource, acquiring which means the message has been
acknowledged by all nodes in the cluster. The BAST of the resource
is used to inform the receiving node that a node wants to
communicate.
The algorithm is:
- 1. receive status - all nodes have concurrent-reader lock on "ack".
+ 1. receive status - all nodes have concurrent-reader lock on "ack"::
- sender receiver receiver
- "ack":CR "ack":CR "ack":CR
+ sender receiver receiver
+ "ack":CR "ack":CR "ack":CR
- 2. sender get EX on "token"
- sender get EX on "message"
- sender receiver receiver
- "token":EX "ack":CR "ack":CR
- "message":EX
- "ack":CR
+ 2. sender get EX on "token",
+ sender get EX on "message"::
+
+ sender receiver receiver
+ "token":EX "ack":CR "ack":CR
+ "message":EX
+ "ack":CR
Sender checks that it still needs to send a message. Messages
received or other events that happened while waiting for the
"token" may have made this message inappropriate or redundant.
- 3. sender writes LVB.
+ 3. sender writes LVB
+
sender down-convert "message" from EX to CW
+
sender try to get EX of "ack"
- [ wait until all receivers have *processed* the "message" ]
-
- [ triggered by bast of "ack" ]
- receiver get CR on "message"
- receiver read LVB
- receiver processes the message
- [ wait finish ]
- receiver releases "ack"
- receiver tries to get PR on "message"
-
- sender receiver receiver
- "token":EX "message":CR "message":CR
- "message":CW
- "ack":EX
+
+ ::
+
+ [ wait until all receivers have *processed* the "message" ]
+
+ [ triggered by bast of "ack" ]
+ receiver get CR on "message"
+ receiver read LVB
+ receiver processes the message
+ [ wait finish ]
+ receiver releases "ack"
+ receiver tries to get PR on "message"
+
+ sender receiver receiver
+ "token":EX "message":CR "message":CR
+ "message":CW
+ "ack":EX
4. triggered by grant of EX on "ack" (indicating all receivers
have processed message)
+
sender down-converts "ack" from EX to CR
+
sender releases "message"
+
sender releases "token"
- receiver upconvert to PR on "message"
- receiver get CR of "ack"
- receiver release "message"
- sender receiver receiver
- "ack":CR "ack":CR "ack":CR
+ ::
+
+ receiver upconvert to PR on "message"
+ receiver get CR of "ack"
+ receiver release "message"
+
+ sender receiver receiver
+ "ack":CR "ack":CR "ack":CR
4. Handling Failures
+====================
4.1 Node Failure
+----------------
When a node fails, the DLM informs the cluster with the slot
number. The node starts a cluster recovery thread. The cluster
@@ -177,11 +224,11 @@ The algorithm is:
- cleans the bitmap of the failed node
- releases bitmap<number> lock of the failed node
- initiates resync of the bitmap on the current node
- md_check_recovery is invoked within recover_bitmaps,
- then md_check_recovery -> metadata_update_start/finish,
- it will lock the communication by lock_comm.
- Which means when one node is resyncing it blocks all
- other nodes from writing anywhere on the array.
+ md_check_recovery is invoked within recover_bitmaps,
+ then md_check_recovery -> metadata_update_start/finish,
+ it will lock the communication by lock_comm.
+ Which means when one node is resyncing it blocks all
+ other nodes from writing anywhere on the array.
The resync process is the regular md resync. However, in a clustered
environment when a resync is performed, it needs to tell other nodes
@@ -198,6 +245,7 @@ The algorithm is:
particular I/O range should be suspended or not.
4.2 Device Failure
+==================
Device failures are handled and communicated with the metadata update
routine. When a node detects a device failure it does not allow
@@ -205,38 +253,41 @@ The algorithm is:
acknowledged by all other nodes.
5. Adding a new Device
+----------------------
For adding a new device, it is necessary that all nodes "see" the new
device to be added. For this, the following algorithm is used:
- 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
+ 1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CLUSTER_ADD)
- 2. Node 1 sends a NEWDISK message with uuid and slot number
- 3. Other nodes issue kobject_uevent_env with uuid and slot number
+ 2. Node 1 sends a NEWDISK message with uuid and slot number
+ 3. Other nodes issue kobject_uevent_env with uuid and slot number
(Steps 4,5 could be a udev rule)
- 4. In userspace, the node searches for the disk, perhaps
+ 4. In userspace, the node searches for the disk, perhaps
using blkid -t SUB_UUID=""
- 5. Other nodes issue either of the following depending on whether
+ 5. Other nodes issue either of the following depending on whether
the disk was found:
ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CANDIDATE and
- disc.number set to slot number)
+ disc.number set to slot number)
ioctl(CLUSTERED_DISK_NACK)
- 6. Other nodes drop lock on "no-new-devs" (CR) if device is found
- 7. Node 1 attempts EX lock on "no-new-dev"
- 8. If node 1 gets the lock, it sends METADATA_UPDATED after
+ 6. Other nodes drop lock on "no-new-devs" (CR) if device is found
+ 7. Node 1 attempts EX lock on "no-new-dev"
+ 8. If node 1 gets the lock, it sends METADATA_UPDATED after
unmarking the disk as SpareLocal
- 9. If not (get "no-new-dev" lock), it fails the operation and sends
+ 9. If not (get "no-new-dev" lock), it fails the operation and sends
METADATA_UPDATED.
10. Other nodes get the information whether a disk is added or not
by the following METADATA_UPDATED.
-6. Module interface.
+6. Module interface
+===================
There are 17 call-backs which the md core can make to the cluster
module. Understanding these can give a good overview of the whole
process.
6.1 join(nodes) and leave()
+---------------------------
These are called when an array is started with a clustered bitmap,
and when the array is stopped. join() ensures the cluster is
@@ -244,11 +295,13 @@ The algorithm is:
Only the first 'nodes' nodes in the cluster can use the array.
6.2 slot_number()
+-----------------
Reports the slot number advised by the cluster infrastructure.
Range is from 0 to nodes-1.
6.3 resync_info_update()
+------------------------
This updates the resync range that is stored in the bitmap lock.
The starting point is updated as the resync progresses. The
@@ -256,6 +309,7 @@ The algorithm is:
It does *not* send a RESYNCING message.
6.4 resync_start(), resync_finish()
+-----------------------------------
These are called when resync/recovery/reshape starts or stops.
They update the resyncing range in the bitmap lock and also
@@ -265,8 +319,8 @@ The algorithm is:
resync_finish() also sends a BITMAP_NEEDS_SYNC message which
allows some other node to take over.
-6.5 metadata_update_start(), metadata_update_finish(),
- metadata_update_cancel().
+6.5 metadata_update_start(), metadata_update_finish(), metadata_update_cancel()
+-------------------------------------------------------------------------------
metadata_update_start is used to get exclusive access to
the metadata. If a change is still needed once that access is
@@ -275,6 +329,7 @@ The algorithm is:
can be used to release the lock.
6.6 area_resyncing()
+--------------------
This combines two elements of functionality.
@@ -289,6 +344,7 @@ The algorithm is:
a node failure.
6.7 add_new_disk_start(), add_new_disk_finish(), new_disk_ack()
+---------------------------------------------------------------
These are used to manage the new-disk protocol described above.
When a new device is added, add_new_disk_start() is called before
@@ -300,17 +356,20 @@ The algorithm is:
new_disk_ack() is called.
6.8 remove_disk()
+-----------------
This is called when a spare or failed device is removed from
the array. It causes a REMOVE message to be send to other nodes.
6.9 gather_bitmaps()
+--------------------
This sends a RE_ADD message to all other nodes and then
gathers bitmap information from all bitmaps. This combined
bitmap is then used to recovery the re-added device.
6.10 lock_all_bitmaps() and unlock_all_bitmaps()
+------------------------------------------------
These are called when change bitmap to none. If a node plans
to clear the cluster raid's bitmap, it need to make sure no other
@@ -319,6 +378,7 @@ The algorithm is:
accordingly.
7. Unsupported features
+=======================
There are somethings which are not supported by cluster MD yet.
diff --git a/Documentation/md/raid5-cache.txt b/Documentation/md/raid5-cache.rst
similarity index 92%
rename from Documentation/md/raid5-cache.txt
rename to Documentation/md/raid5-cache.rst
index 2b210f295786..d7a15f44a7c3 100644
--- a/Documentation/md/raid5-cache.txt
+++ b/Documentation/md/raid5-cache.rst
@@ -1,4 +1,6 @@
-RAID5 cache
+================
+RAID 4/5/6 cache
+================
Raid 4/5/6 could include an extra disk for data cache besides normal RAID
disks. The role of RAID disks isn't changed with the cache disk. The cache disk
@@ -6,19 +8,19 @@ caches data to the RAID disks. The cache can be in write-through (supported
since 4.4) or write-back mode (supported since 4.10). mdadm (supported since
3.4) has a new option '--write-journal' to create array with cache. Please
refer to mdadm manual for details. By default (RAID array starts), the cache is
-in write-through mode. A user can switch it to write-back mode by:
+in write-through mode. A user can switch it to write-back mode by::
-echo "write-back" > /sys/block/md0/md/journal_mode
+ echo "write-back" > /sys/block/md0/md/journal_mode
-And switch it back to write-through mode by:
+And switch it back to write-through mode by::
-echo "write-through" > /sys/block/md0/md/journal_mode
+ echo "write-through" > /sys/block/md0/md/journal_mode
In both modes, all writes to the array will hit cache disk first. This means
the cache disk must be fast and sustainable.
--------------------------------------
-write-through mode:
+write-through mode
+==================
This mode mainly fixes the 'write hole' issue. For RAID 4/5/6 array, an unclean
shutdown can cause data in some stripes to not be in consistent state, eg, data
@@ -42,8 +44,8 @@ exposed to 'write hole' again.
In write-through mode, the cache disk isn't required to be big. Several
hundreds megabytes are enough.
---------------------------------------
-write-back mode:
+write-back mode
+===============
write-back mode fixes the 'write hole' issue too, since all write data is
cached on cache disk. But the main goal of 'write-back' cache is to speed up
@@ -64,16 +66,16 @@ data loss.
In write-back mode, MD also caches data in memory. The memory cache includes
the same data stored on cache disk, so a power loss doesn't cause data loss.
The memory cache size has performance impact for the array. It's recommended
-the size is big. A user can configure the size by:
+the size is big. A user can configure the size by::
-echo "2048" > /sys/block/md0/md/stripe_cache_size
+ echo "2048" > /sys/block/md0/md/stripe_cache_size
Too small cache disk will make the write aggregation less efficient in this
mode depending on the workloads. It's recommended to use a cache disk with at
least several gigabytes size in write-back mode.
---------------------------------------
-The implementation:
+The implementation
+==================
The write-through and write-back cache use the same disk format. The cache disk
is organized as a simple write log. The log consists of 'meta data' and 'data'
diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/md/raid5-ppl.rst
similarity index 98%
rename from Documentation/md/raid5-ppl.txt
rename to Documentation/md/raid5-ppl.rst
index bfa092589e00..357e5515bc55 100644
--- a/Documentation/md/raid5-ppl.txt
+++ b/Documentation/md/raid5-ppl.rst
@@ -1,4 +1,6 @@
+==================
Partial Parity Log
+==================
Partial Parity Log (PPL) is a feature available for RAID5 arrays. The issue
addressed by PPL is that after a dirty shutdown, parity of a particular stripe
--
2.21.0
In order to be able to add this file to the security book,
we need first to convert it to reST.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../{xen-tpmfront.txt => xen-tpmfront.rst} | 103 ++++++++++--------
1 file changed, 58 insertions(+), 45 deletions(-)
rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)
diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.rst
similarity index 66%
rename from Documentation/security/tpm/xen-tpmfront.txt
rename to Documentation/security/tpm/xen-tpmfront.rst
index 69346de87ff3..98a16ab87360 100644
--- a/Documentation/security/tpm/xen-tpmfront.txt
+++ b/Documentation/security/tpm/xen-tpmfront.rst
@@ -1,4 +1,8 @@
+:orphan:
+
+=============================
Virtual TPM interface for Xen
+=============================
Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
@@ -6,7 +10,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for
Xen. The reader is assumed to have familiarity with building and installing Xen,
Linux, and a basic understanding of the TPM and vTPM concepts.
-INTRODUCTION
+Introduction
+------------
The goal of this work is to provide a TPM functionality to a virtual guest
operating system (in Xen terms, a DomU). This allows programs to interact with
@@ -24,81 +29,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by
IBM and Intel corporation.
-DESIGN OVERVIEW
+Design Overview
---------------
-The architecture of vTPM is described below:
+The architecture of vTPM is described below::
-+------------------+
-| Linux DomU | ...
-| | ^ |
-| v | |
-| xen-tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpm-stubdom | ...
-| | ^ |
-| v | |
-| mini-os/tpmfront |
-+------------------+
- | ^
- v |
-+------------------+
-| mini-os/tpmback |
-| | ^ |
-| v | |
-| vtpmmgr-stubdom |
-| | ^ |
-| v | |
-| mini-os/tpm_tis |
-+------------------+
- | ^
- v |
-+------------------+
-| Hardware TPM |
-+------------------+
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM |
+ +------------------+
- * Linux DomU: The Linux based guest that wants to use a vTPM. There may be
+* Linux DomU:
+ The Linux based guest that wants to use a vTPM. There may be
more than one of these.
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
+* xen-tpmfront.ko:
+ Linux kernel virtual TPM frontend driver. This driver
provides vTPM access to a Linux-based DomU.
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
+* mini-os/tpmback:
+ Mini-os TPM backend driver. The Linux frontend driver
connects to this backend driver to facilitate communications
between the Linux DomU and its vTPM. This driver is also
used by vtpmmgr-stubdom to communicate with vtpm-stubdom.
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
+* vtpm-stubdom:
+ A mini-os stub domain that implements a vTPM. There is a
one to one mapping between running vtpm-stubdom instances and
logical vtpms on the system. The vTPM Platform Configuration
Registers (PCRs) are normally all initialized to zero.
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
+* mini-os/tpmfront:
+ Mini-os TPM frontend driver. The vTPM mini-os domain
vtpm-stubdom uses this driver to communicate with
vtpmmgr-stubdom. This driver is also used in mini-os
domains such as pv-grub that talk to the vTPM domain.
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is
+* vtpmmgr-stubdom:
+ A mini-os domain that implements the vTPM manager. There is
only one vTPM manager and it should be running during the
entire lifetime of the machine. This domain regulates
access to the physical TPM on the system and secures the
persistent state of each vTPM.
- * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+* mini-os/tpm_tis:
+ Mini-os TPM version 1.2 TPM Interface Specification (TIS)
driver. This driver used by vtpmmgr-stubdom to talk directly to
the hardware TPM. Communication is facilitated by mapping
hardware memory pages into vtpmmgr-stubdom.
- * Hardware TPM: The physical TPM that is soldered onto the motherboard.
+* Hardware TPM:
+ The physical TPM that is soldered onto the motherboard.
-INTEGRATION WITH XEN
+Integration With Xen
--------------------
Support for the vTPM driver was added in Xen using the libxl toolstack in Xen
--
2.21.0
Prepare this file to be moved to a kernel book by converting
it to ReST format and renaming it to ti-emif.rst.
While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
.../{ti-emif.txt => ti-emif.rst} | 27 ++++++++++++-------
1 file changed, 17 insertions(+), 10 deletions(-)
rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%)
diff --git a/Documentation/memory-devices/ti-emif.txt b/Documentation/memory-devices/ti-emif.rst
similarity index 81%
rename from Documentation/memory-devices/ti-emif.txt
rename to Documentation/memory-devices/ti-emif.rst
index f4ad9a7d0f4b..c9242294e63c 100644
--- a/Documentation/memory-devices/ti-emif.txt
+++ b/Documentation/memory-devices/ti-emif.rst
@@ -1,20 +1,24 @@
-TI EMIF SDRAM Controller Driver:
+:orphan:
+
+===============================
+TI EMIF SDRAM Controller Driver
+===============================
Author
-========
+======
Aneesh V <[email protected]>
Location
-============
+========
driver/memory/emif.c
Supported SoCs:
-===================
+===============
TI OMAP44xx
TI OMAP54xx
Menuconfig option:
-==========================
+==================
Device Drivers
Memory devices
Texas Instruments EMIF driver
@@ -29,10 +33,11 @@ functions of the driver includes re-configuring AC timing
parameters and other settings during frequency, voltage and
temperature changes
-Platform Data (see include/linux/platform_data/emif_plat.h):
-=====================================================================
+Platform Data (see include/linux/platform_data/emif_plat.h)
+===========================================================
DDR device details and other board dependent and SoC dependent
information can be passed through platform data (struct emif_platform_data)
+
- DDR device details: 'struct ddr_device_info'
- Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck'
- Custom configurations: customizable policy options through
@@ -40,17 +45,19 @@ information can be passed through platform data (struct emif_platform_data)
- IP revision
- PHY type
-Interface to the external world:
-================================
+Interface to the external world
+===============================
EMIF driver registers notifiers for voltage and frequency changes
affecting EMIF and takes appropriate actions when these are invoked.
+
- freq_pre_notify_handling()
- freq_post_notify_handling()
- volt_notify_handling()
Debugfs
-========
+=======
The driver creates two debugfs entries per device.
+
- regcache_dump : dump of register values calculated and saved for all
frequencies used so far.
- mr4 : last polled value of MR4 register in the LPDDR2 device. MR4
--
2.21.0
On Tue, Jun 18, 2019 at 05:53:24PM -0300, Mauro Carvalho Chehab wrote:
> Convert this small file to ReST in preparation for adding it to
> the driver-api book.
>
> While this is not part of the driver-api book, mark it as
> :orphan:, in order to avoid build warnings.
>
> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Acked-by: Greg Kroah-Hartman <[email protected]>