* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-pm,
linux-arm-kernel, linux-samsung-soc, linux-pci, linuxppc-dev,
linux-scsi, devicetree, linux-i2c, linux-hwmon, linux-spi,
linux-iio, linux-rtc, netdev, linux-parisc, openrisc, devel,
linux-cifs, samba-technical, devel, dmaengine, alsa-devel,
linux-mips, linux-wireless, rcu
This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.
This series is at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
And it is based on yesterday's upstream tree.
After this series, we have ~320 files left to be converted to ReST.
v2:
- Added 3 files submitted for v5.3 that weren't merged yet;
- markdown patch broken into two, per Rob's request;
- rebased on the top of upstream master branch
Mauro Carvalho Chehab (26):
docs: power: add it to to the main documentation index
docs: thermal: add it to the driver API
docs: powerpc: convert docs to ReST and rename to *.rst
docs: ubifs-authentication.md: convert to ReST
docs: writing-schema.md: convert from markdown to ReST
docs: i2c: convert to ReST and add to driver-api bookset
docs: w1: convert to ReST and add to the kAPI group of docs
spi: docs: convert to ReST and add it to the kABI bookset
docs: ipmb: place it at driver-api and convert to ReST
docs: packing: move it to core-api book and adjust markups
docs: admin-guide: add auxdisplay files to it after conversion to ReST
docs: README.buddha: convert to ReST and add to m68k book
docs: parisc: convert to ReST and add to documentation body
docs: openrisc: convert to ReST and add to documentation body
docs: isdn: convert to ReST and add to kAPI bookset
docs: fs: cifs: convert to ReST and add to admin-guide book
docs: fs: convert docs without extension to ReST
docs: fs: convert porting to ReST
docs: index.rst: don't use genindex for pdf output
docs: wimax: convert to ReST and add to admin-guide
docs: mips: add to the documentation body as ReST
docs: hwmon: pxe1610: convert to ReST format and add to the index
docs: nios2: add it to the main Documentation body
docs: net: convert two README files to ReST format
docs: rcu: convert some articles from html to ReST
docs: ABI: remove extension from sysfs-class-mic.txt
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
.../{sysfs-class-mic.txt => sysfs-class-mic} | 0
Documentation/PCI/pci-error-recovery.rst | 2 +-
.../Data-Structures/Data-Structures.html | 1391 -------
.../Data-Structures/Data-Structures.rst | 1163 ++++++
...riods.html => Expedited-Grace-Periods.rst} | 949 ++---
.../Memory-Ordering/Tree-RCU-Diagram.html | 9 -
...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
.../RCU/Design/Requirements/Requirements.html | 3330 -----------------
.../RCU/Design/Requirements/Requirements.rst | 2662 +++++++++++++
Documentation/RCU/index.rst | 5 +
Documentation/RCU/whatisRCU.txt | 4 +-
.../auxdisplay/cfag12864b.rst} | 115 +-
.../admin-guide/auxdisplay/index.rst | 16 +
.../auxdisplay/ks0108.rst} | 53 +-
.../AUTHORS => admin-guide/cifs/authors.rst} | 64 +-
.../CHANGES => admin-guide/cifs/changes.rst} | 4 +
Documentation/admin-guide/cifs/index.rst | 21 +
.../cifs/introduction.rst} | 8 +
.../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +-
.../README => admin-guide/cifs/usage.rst} | 560 +--
.../cifs/winucase_convert.pl | 0
Documentation/admin-guide/index.rst | 3 +
.../wimax/i2400m.rst} | 145 +-
Documentation/admin-guide/wimax/index.rst | 19 +
.../wimax/wimax.rst} | 36 +-
Documentation/core-api/index.rst | 3 +-
.../{packing.txt => core-api/packing.rst} | 81 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
.../{writing-schema.md => writing-schema.rst} | 137 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/index.rst | 2 +
Documentation/driver-api/ipmb.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
.../thermal/cpu-cooling-api.rst | 0
.../thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
.../{ => driver-api}/thermal/index.rst | 2 +-
.../thermal/intel_powerclamp.rst | 0
.../thermal/nouveau_thermal.rst | 0
.../thermal/power_allocator.rst | 0
.../{ => driver-api}/thermal/sysfs-api.rst | 12 +-
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
...irectory-locking => directory-locking.rst} | 40 +-
Documentation/filesystems/index.rst | 4 +
.../filesystems/{Locking => locking.rst} | 257 +-
.../nfs/{Exporting => exporting.rst} | 31 +-
.../filesystems/{porting => porting.rst} | 824 ++--
...entication.md => ubifs-authentication.rst} | 70 +-
Documentation/filesystems/vfs.rst | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +-
.../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} | 14 +-
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
...2c-parport-light => i2c-parport-light.rst} | 8 +-
.../busses/{i2c-parport => i2c-parport.rst} | 164 +-
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +-
.../i2c/busses/{i2c-sis630 => i2c-sis630.rst} | 39 +-
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 +-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 28 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +-
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 5 +-
.../i2c/{functionality => functionality.rst} | 22 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 +-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +-
Documentation/i2c/index.rst | 37 +
...ting-devices => instantiating-devices.rst} | 45 +-
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +-
...e-parameters => old-module-parameters.rst} | 27 +-
...eprom-backend => slave-eeprom-backend.rst} | 4 +-
.../{slave-interface => slave-interface.rst} | 33 +-
.../{smbus-protocol => smbus-protocol.rst} | 86 +-
Documentation/i2c/{summary => summary.rst} | 6 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 204 +-
.../{writing-clients => writing-clients.rst} | 94 +-
Documentation/index.rst | 10 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 +-
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +-
.../isdn/{README.hysdn => hysdn.rst} | 125 +-
Documentation/isdn/index.rst | 24 +
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +-
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
.../m68k/{README.buddha => buddha-driver.rst} | 95 +-
Documentation/m68k/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +-
Documentation/mips/index.rst | 17 +
.../networking/caif/{README => caif.rst} | 88 +-
.../networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
.../{README => mac80211_hwsim.rst} | 28 +-
Documentation/nios2/{README => nios2.rst} | 1 +
Documentation/openrisc/index.rst | 18 +
.../openrisc/{README => openrisc_port.rst} | 25 +-
Documentation/openrisc/{TODO => todo.rst} | 9 +-
.../parisc/{debugging => debugging.rst} | 7 +
Documentation/parisc/index.rst | 18 +
.../parisc/{registers => registers.rst} | 59 +-
Documentation/power/index.rst | 2 +-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +-
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/sound/index.rst | 2 +-
.../spi/{butterfly => butterfly.rst} | 44 +-
Documentation/spi/index.rst | 22 +
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 +-
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 +-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 5 +-
.../spi/{spi-summary => spi-summary.rst} | 105 +-
Documentation/spi/{spidev => spidev.rst} | 30 +-
Documentation/w1/index.rst | 21 +
.../w1/masters/{ds2482 => ds2482.rst} | 16 +-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +
.../w1/masters/{mxc-w1 => mxc-w1.rst} | 13 +-
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +-
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +-
Documentation/w1/slaves/index.rst | 16 +
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +-
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 +
.../w1/slaves/{w1_ds2423 => w1_ds2423.rst} | 27 +-
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 +-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 +
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 +-
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 +-
.../w1/{w1.generic => w1-generic.rst} | 88 +-
.../w1/{w1.netlink => w1-netlink.rst} | 89 +-
MAINTAINERS | 68 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 4 +-
drivers/rtc/rtc-ds1374.c | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
fs/orangefs/orangefs-kernel.h | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
include/linux/i2c.h | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
include/linux/thermal.h | 4 +-
include/soc/fsl/qe/qe.h | 2 +-
216 files changed, 9148 insertions(+), 8672 deletions(-)
rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
create mode 100644 Documentation/admin-guide/cifs/index.rst
rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
rename Documentation/filesystems/{porting => porting.rst} (49%)
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
rename Documentation/nios2/{README => nios2.rst} (96%)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
--
2.21.0
^ permalink raw reply [flat|nested] 75+ messages in thread
* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-pm,
linux-arm-kernel, linux-samsung-soc, linux-pci, linuxppc-dev,
linux-scsi, devicetree, linux-i2c, linux-hwmon, linux-spi,
linux-iio, linux-rtc, netdev, linux-parisc, openrisc, devel,
linux-cifs, samba-technical, devel, dmaengine, alsa-devel,
linux-mips, linux-wireless, rcu
This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.
This series is at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
And it is based on yesterday's upstream tree.
After this series, we have ~320 files left to be converted to ReST.
v2:
- Added 3 files submitted for v5.3 that weren't merged yet;
- markdown patch broken into two, per Rob's request;
- rebased on the top of upstream master branch
Mauro Carvalho Chehab (26):
docs: power: add it to to the main documentation index
docs: thermal: add it to the driver API
docs: powerpc: convert docs to ReST and rename to *.rst
docs: ubifs-authentication.md: convert to ReST
docs: writing-schema.md: convert from markdown to ReST
docs: i2c: convert to ReST and add to driver-api bookset
docs: w1: convert to ReST and add to the kAPI group of docs
spi: docs: convert to ReST and add it to the kABI bookset
docs: ipmb: place it at driver-api and convert to ReST
docs: packing: move it to core-api book and adjust markups
docs: admin-guide: add auxdisplay files to it after conversion to ReST
docs: README.buddha: convert to ReST and add to m68k book
docs: parisc: convert to ReST and add to documentation body
docs: openrisc: convert to ReST and add to documentation body
docs: isdn: convert to ReST and add to kAPI bookset
docs: fs: cifs: convert to ReST and add to admin-guide book
docs: fs: convert docs without extension to ReST
docs: fs: convert porting to ReST
docs: index.rst: don't use genindex for pdf output
docs: wimax: convert to ReST and add to admin-guide
docs: mips: add to the documentation body as ReST
docs: hwmon: pxe1610: convert to ReST format and add to the index
docs: nios2: add it to the main Documentation body
docs: net: convert two README files to ReST format
docs: rcu: convert some articles from html to ReST
docs: ABI: remove extension from sysfs-class-mic.txt
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
.../{sysfs-class-mic.txt => sysfs-class-mic} | 0
Documentation/PCI/pci-error-recovery.rst | 2 +-
.../Data-Structures/Data-Structures.html | 1391 -------
.../Data-Structures/Data-Structures.rst | 1163 ++++++
...riods.html => Expedited-Grace-Periods.rst} | 949 ++---
.../Memory-Ordering/Tree-RCU-Diagram.html | 9 -
...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
.../RCU/Design/Requirements/Requirements.html | 3330 -----------------
.../RCU/Design/Requirements/Requirements.rst | 2662 +++++++++++++
Documentation/RCU/index.rst | 5 +
Documentation/RCU/whatisRCU.txt | 4 +-
.../auxdisplay/cfag12864b.rst} | 115 +-
.../admin-guide/auxdisplay/index.rst | 16 +
.../auxdisplay/ks0108.rst} | 53 +-
.../AUTHORS => admin-guide/cifs/authors.rst} | 64 +-
.../CHANGES => admin-guide/cifs/changes.rst} | 4 +
Documentation/admin-guide/cifs/index.rst | 21 +
.../cifs/introduction.rst} | 8 +
.../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +-
.../README => admin-guide/cifs/usage.rst} | 560 +--
.../cifs/winucase_convert.pl | 0
Documentation/admin-guide/index.rst | 3 +
.../wimax/i2400m.rst} | 145 +-
Documentation/admin-guide/wimax/index.rst | 19 +
.../wimax/wimax.rst} | 36 +-
Documentation/core-api/index.rst | 3 +-
.../{packing.txt => core-api/packing.rst} | 81 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
.../{writing-schema.md => writing-schema.rst} | 137 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/index.rst | 2 +
Documentation/driver-api/ipmb.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
.../thermal/cpu-cooling-api.rst | 0
.../thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
.../{ => driver-api}/thermal/index.rst | 2 +-
.../thermal/intel_powerclamp.rst | 0
.../thermal/nouveau_thermal.rst | 0
.../thermal/power_allocator.rst | 0
.../{ => driver-api}/thermal/sysfs-api.rst | 12 +-
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
...irectory-locking => directory-locking.rst} | 40 +-
Documentation/filesystems/index.rst | 4 +
.../filesystems/{Locking => locking.rst} | 257 +-
.../nfs/{Exporting => exporting.rst} | 31 +-
.../filesystems/{porting => porting.rst} | 824 ++--
...entication.md => ubifs-authentication.rst} | 70 +-
Documentation/filesystems/vfs.rst | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +-
.../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} | 14 +-
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
...2c-parport-light => i2c-parport-light.rst} | 8 +-
.../busses/{i2c-parport => i2c-parport.rst} | 164 +-
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +-
.../i2c/busses/{i2c-sis630 => i2c-sis630.rst} | 39 +-
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 +-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 28 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +-
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 5 +-
.../i2c/{functionality => functionality.rst} | 22 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 +-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +-
Documentation/i2c/index.rst | 37 +
...ting-devices => instantiating-devices.rst} | 45 +-
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +-
...e-parameters => old-module-parameters.rst} | 27 +-
...eprom-backend => slave-eeprom-backend.rst} | 4 +-
.../{slave-interface => slave-interface.rst} | 33 +-
.../{smbus-protocol => smbus-protocol.rst} | 86 +-
Documentation/i2c/{summary => summary.rst} | 6 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 204 +-
.../{writing-clients => writing-clients.rst} | 94 +-
Documentation/index.rst | 10 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 +-
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +-
.../isdn/{README.hysdn => hysdn.rst} | 125 +-
Documentation/isdn/index.rst | 24 +
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +-
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
.../m68k/{README.buddha => buddha-driver.rst} | 95 +-
Documentation/m68k/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +-
Documentation/mips/index.rst | 17 +
.../networking/caif/{README => caif.rst} | 88 +-
.../networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
.../{README => mac80211_hwsim.rst} | 28 +-
Documentation/nios2/{README => nios2.rst} | 1 +
Documentation/openrisc/index.rst | 18 +
.../openrisc/{README => openrisc_port.rst} | 25 +-
Documentation/openrisc/{TODO => todo.rst} | 9 +-
.../parisc/{debugging => debugging.rst} | 7 +
Documentation/parisc/index.rst | 18 +
.../parisc/{registers => registers.rst} | 59 +-
Documentation/power/index.rst | 2 +-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +-
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/sound/index.rst | 2 +-
.../spi/{butterfly => butterfly.rst} | 44 +-
Documentation/spi/index.rst | 22 +
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 +-
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 +-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 5 +-
.../spi/{spi-summary => spi-summary.rst} | 105 +-
Documentation/spi/{spidev => spidev.rst} | 30 +-
Documentation/w1/index.rst | 21 +
.../w1/masters/{ds2482 => ds2482.rst} | 16 +-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +
.../w1/masters/{mxc-w1 => mxc-w1.rst} | 13 +-
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +-
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +-
Documentation/w1/slaves/index.rst | 16 +
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +-
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 +
.../w1/slaves/{w1_ds2423 => w1_ds2423.rst} | 27 +-
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 +-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 +
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 +-
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 +-
.../w1/{w1.generic => w1-generic.rst} | 88 +-
.../w1/{w1.netlink => w1-netlink.rst} | 89 +-
MAINTAINERS | 68 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 4 +-
drivers/rtc/rtc-ds1374.c | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
fs/orangefs/orangefs-kernel.h | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
include/linux/i2c.h | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
include/linux/thermal.h | 4 +-
include/soc/fsl/qe/qe.h | 2 +-
216 files changed, 9148 insertions(+), 8672 deletions(-)
rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
create mode 100644 Documentation/admin-guide/cifs/index.rst
rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
rename Documentation/filesystems/{porting => porting.rst} (49%)
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
rename Documentation/nios2/{README => nios2.rst} (96%)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
--
2.21.0
^ permalink raw reply [flat|nested] 75+ messages in thread
* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
linux-mips, linux-i2c, Mauro Carvalho Chehab, devel, linux-cifs,
linux-samsung-soc, linux-scsi, devel, devicetree, linux-pm, rcu,
openrisc, linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
samba-technical, linux-kernel, linux-spi, dmaengine,
linuxppc-dev, linux-rtc
This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.
This series is at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
And it is based on yesterday's upstream tree.
After this series, we have ~320 files left to be converted to ReST.
v2:
- Added 3 files submitted for v5.3 that weren't merged yet;
- markdown patch broken into two, per Rob's request;
- rebased on the top of upstream master branch
Mauro Carvalho Chehab (26):
docs: power: add it to to the main documentation index
docs: thermal: add it to the driver API
docs: powerpc: convert docs to ReST and rename to *.rst
docs: ubifs-authentication.md: convert to ReST
docs: writing-schema.md: convert from markdown to ReST
docs: i2c: convert to ReST and add to driver-api bookset
docs: w1: convert to ReST and add to the kAPI group of docs
spi: docs: convert to ReST and add it to the kABI bookset
docs: ipmb: place it at driver-api and convert to ReST
docs: packing: move it to core-api book and adjust markups
docs: admin-guide: add auxdisplay files to it after conversion to ReST
docs: README.buddha: convert to ReST and add to m68k book
docs: parisc: convert to ReST and add to documentation body
docs: openrisc: convert to ReST and add to documentation body
docs: isdn: convert to ReST and add to kAPI bookset
docs: fs: cifs: convert to ReST and add to admin-guide book
docs: fs: convert docs without extension to ReST
docs: fs: convert porting to ReST
docs: index.rst: don't use genindex for pdf output
docs: wimax: convert to ReST and add to admin-guide
docs: mips: add to the documentation body as ReST
docs: hwmon: pxe1610: convert to ReST format and add to the index
docs: nios2: add it to the main Documentation body
docs: net: convert two README files to ReST format
docs: rcu: convert some articles from html to ReST
docs: ABI: remove extension from sysfs-class-mic.txt
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
.../{sysfs-class-mic.txt => sysfs-class-mic} | 0
Documentation/PCI/pci-error-recovery.rst | 2 +-
.../Data-Structures/Data-Structures.html | 1391 -------
.../Data-Structures/Data-Structures.rst | 1163 ++++++
...riods.html => Expedited-Grace-Periods.rst} | 949 ++---
.../Memory-Ordering/Tree-RCU-Diagram.html | 9 -
...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
.../RCU/Design/Requirements/Requirements.html | 3330 -----------------
.../RCU/Design/Requirements/Requirements.rst | 2662 +++++++++++++
Documentation/RCU/index.rst | 5 +
Documentation/RCU/whatisRCU.txt | 4 +-
.../auxdisplay/cfag12864b.rst} | 115 +-
.../admin-guide/auxdisplay/index.rst | 16 +
.../auxdisplay/ks0108.rst} | 53 +-
.../AUTHORS => admin-guide/cifs/authors.rst} | 64 +-
.../CHANGES => admin-guide/cifs/changes.rst} | 4 +
Documentation/admin-guide/cifs/index.rst | 21 +
.../cifs/introduction.rst} | 8 +
.../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +-
.../README => admin-guide/cifs/usage.rst} | 560 +--
.../cifs/winucase_convert.pl | 0
Documentation/admin-guide/index.rst | 3 +
.../wimax/i2400m.rst} | 145 +-
Documentation/admin-guide/wimax/index.rst | 19 +
.../wimax/wimax.rst} | 36 +-
Documentation/core-api/index.rst | 3 +-
.../{packing.txt => core-api/packing.rst} | 81 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
.../{writing-schema.md => writing-schema.rst} | 137 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/index.rst | 2 +
Documentation/driver-api/ipmb.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
.../thermal/cpu-cooling-api.rst | 0
.../thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
.../{ => driver-api}/thermal/index.rst | 2 +-
.../thermal/intel_powerclamp.rst | 0
.../thermal/nouveau_thermal.rst | 0
.../thermal/power_allocator.rst | 0
.../{ => driver-api}/thermal/sysfs-api.rst | 12 +-
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
...irectory-locking => directory-locking.rst} | 40 +-
Documentation/filesystems/index.rst | 4 +
.../filesystems/{Locking => locking.rst} | 257 +-
.../nfs/{Exporting => exporting.rst} | 31 +-
.../filesystems/{porting => porting.rst} | 824 ++--
...entication.md => ubifs-authentication.rst} | 70 +-
Documentation/filesystems/vfs.rst | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +-
.../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} | 14 +-
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
...2c-parport-light => i2c-parport-light.rst} | 8 +-
.../busses/{i2c-parport => i2c-parport.rst} | 164 +-
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +-
.../i2c/busses/{i2c-sis630 => i2c-sis630.rst} | 39 +-
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 +-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 28 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +-
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 5 +-
.../i2c/{functionality => functionality.rst} | 22 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 +-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +-
Documentation/i2c/index.rst | 37 +
...ting-devices => instantiating-devices.rst} | 45 +-
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +-
...e-parameters => old-module-parameters.rst} | 27 +-
...eprom-backend => slave-eeprom-backend.rst} | 4 +-
.../{slave-interface => slave-interface.rst} | 33 +-
.../{smbus-protocol => smbus-protocol.rst} | 86 +-
Documentation/i2c/{summary => summary.rst} | 6 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 204 +-
.../{writing-clients => writing-clients.rst} | 94 +-
Documentation/index.rst | 10 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 +-
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +-
.../isdn/{README.hysdn => hysdn.rst} | 125 +-
Documentation/isdn/index.rst | 24 +
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +-
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
.../m68k/{README.buddha => buddha-driver.rst} | 95 +-
Documentation/m68k/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +-
Documentation/mips/index.rst | 17 +
.../networking/caif/{README => caif.rst} | 88 +-
.../networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
.../{README => mac80211_hwsim.rst} | 28 +-
Documentation/nios2/{README => nios2.rst} | 1 +
Documentation/openrisc/index.rst | 18 +
.../openrisc/{README => openrisc_port.rst} | 25 +-
Documentation/openrisc/{TODO => todo.rst} | 9 +-
.../parisc/{debugging => debugging.rst} | 7 +
Documentation/parisc/index.rst | 18 +
.../parisc/{registers => registers.rst} | 59 +-
Documentation/power/index.rst | 2 +-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +-
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/sound/index.rst | 2 +-
.../spi/{butterfly => butterfly.rst} | 44 +-
Documentation/spi/index.rst | 22 +
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 +-
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 +-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 5 +-
.../spi/{spi-summary => spi-summary.rst} | 105 +-
Documentation/spi/{spidev => spidev.rst} | 30 +-
Documentation/w1/index.rst | 21 +
.../w1/masters/{ds2482 => ds2482.rst} | 16 +-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +
.../w1/masters/{mxc-w1 => mxc-w1.rst} | 13 +-
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +-
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +-
Documentation/w1/slaves/index.rst | 16 +
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +-
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 +
.../w1/slaves/{w1_ds2423 => w1_ds2423.rst} | 27 +-
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 +-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 +
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 +-
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 +-
.../w1/{w1.generic => w1-generic.rst} | 88 +-
.../w1/{w1.netlink => w1-netlink.rst} | 89 +-
MAINTAINERS | 68 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 4 +-
drivers/rtc/rtc-ds1374.c | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
fs/orangefs/orangefs-kernel.h | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
include/linux/i2c.h | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
include/linux/thermal.h | 4 +-
include/soc/fsl/qe/qe.h | 2 +-
216 files changed, 9148 insertions(+), 8672 deletions(-)
rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
create mode 100644 Documentation/admin-guide/cifs/index.rst
rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
rename Documentation/filesystems/{porting => porting.rst} (49%)
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
rename Documentation/nios2/{README => nios2.rst} (96%)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
--
2.21.0
^ permalink raw reply [flat|nested] 75+ messages in thread
* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
linux-mips, linux-i2c, Mauro Carvalho Chehab, devel, linux-cifs,
linux-samsung-soc, linux-scsi, devel, devicetree, linux-pm, rcu,
openrisc, linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
samba-technical, linux-kernel, linux-spi, dmaengine,
linuxppc-dev, linux-rtc
This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.
This series is at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
And it is based on yesterday's upstream tree.
After this series, we have ~320 files left to be converted to ReST.
v2:
- Added 3 files submitted for v5.3 that weren't merged yet;
- markdown patch broken into two, per Rob's request;
- rebased on the top of upstream master branch
Mauro Carvalho Chehab (26):
docs: power: add it to to the main documentation index
docs: thermal: add it to the driver API
docs: powerpc: convert docs to ReST and rename to *.rst
docs: ubifs-authentication.md: convert to ReST
docs: writing-schema.md: convert from markdown to ReST
docs: i2c: convert to ReST and add to driver-api bookset
docs: w1: convert to ReST and add to the kAPI group of docs
spi: docs: convert to ReST and add it to the kABI bookset
docs: ipmb: place it at driver-api and convert to ReST
docs: packing: move it to core-api book and adjust markups
docs: admin-guide: add auxdisplay files to it after conversion to ReST
docs: README.buddha: convert to ReST and add to m68k book
docs: parisc: convert to ReST and add to documentation body
docs: openrisc: convert to ReST and add to documentation body
docs: isdn: convert to ReST and add to kAPI bookset
docs: fs: cifs: convert to ReST and add to admin-guide book
docs: fs: convert docs without extension to ReST
docs: fs: convert porting to ReST
docs: index.rst: don't use genindex for pdf output
docs: wimax: convert to ReST and add to admin-guide
docs: mips: add to the documentation body as ReST
docs: hwmon: pxe1610: convert to ReST format and add to the index
docs: nios2: add it to the main Documentation body
docs: net: convert two README files to ReST format
docs: rcu: convert some articles from html to ReST
docs: ABI: remove extension from sysfs-class-mic.txt
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
.../{sysfs-class-mic.txt => sysfs-class-mic} | 0
Documentation/PCI/pci-error-recovery.rst | 2 +-
.../Data-Structures/Data-Structures.html | 1391 -------
.../Data-Structures/Data-Structures.rst | 1163 ++++++
...riods.html => Expedited-Grace-Periods.rst} | 949 ++---
.../Memory-Ordering/Tree-RCU-Diagram.html | 9 -
...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
.../RCU/Design/Requirements/Requirements.html | 3330 -----------------
.../RCU/Design/Requirements/Requirements.rst | 2662 +++++++++++++
Documentation/RCU/index.rst | 5 +
Documentation/RCU/whatisRCU.txt | 4 +-
.../auxdisplay/cfag12864b.rst} | 115 +-
.../admin-guide/auxdisplay/index.rst | 16 +
.../auxdisplay/ks0108.rst} | 53 +-
.../AUTHORS => admin-guide/cifs/authors.rst} | 64 +-
.../CHANGES => admin-guide/cifs/changes.rst} | 4 +
Documentation/admin-guide/cifs/index.rst | 21 +
.../cifs/introduction.rst} | 8 +
.../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +-
.../README => admin-guide/cifs/usage.rst} | 560 +--
.../cifs/winucase_convert.pl | 0
Documentation/admin-guide/index.rst | 3 +
.../wimax/i2400m.rst} | 145 +-
Documentation/admin-guide/wimax/index.rst | 19 +
.../wimax/wimax.rst} | 36 +-
Documentation/core-api/index.rst | 3 +-
.../{packing.txt => core-api/packing.rst} | 81 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
.../{writing-schema.md => writing-schema.rst} | 137 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/index.rst | 2 +
Documentation/driver-api/ipmb.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
.../thermal/cpu-cooling-api.rst | 0
.../thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
.../{ => driver-api}/thermal/index.rst | 2 +-
.../thermal/intel_powerclamp.rst | 0
.../thermal/nouveau_thermal.rst | 0
.../thermal/power_allocator.rst | 0
.../{ => driver-api}/thermal/sysfs-api.rst | 12 +-
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
...irectory-locking => directory-locking.rst} | 40 +-
Documentation/filesystems/index.rst | 4 +
.../filesystems/{Locking => locking.rst} | 257 +-
.../nfs/{Exporting => exporting.rst} | 31 +-
.../filesystems/{porting => porting.rst} | 824 ++--
...entication.md => ubifs-authentication.rst} | 70 +-
Documentation/filesystems/vfs.rst | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +-
.../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} | 14 +-
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
...2c-parport-light => i2c-parport-light.rst} | 8 +-
.../busses/{i2c-parport => i2c-parport.rst} | 164 +-
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +-
.../i2c/busses/{i2c-sis630 => i2c-sis630.rst} | 39 +-
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 +-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 28 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +-
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 5 +-
.../i2c/{functionality => functionality.rst} | 22 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 +-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +-
Documentation/i2c/index.rst | 37 +
...ting-devices => instantiating-devices.rst} | 45 +-
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +-
...e-parameters => old-module-parameters.rst} | 27 +-
...eprom-backend => slave-eeprom-backend.rst} | 4 +-
.../{slave-interface => slave-interface.rst} | 33 +-
.../{smbus-protocol => smbus-protocol.rst} | 86 +-
Documentation/i2c/{summary => summary.rst} | 6 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 204 +-
.../{writing-clients => writing-clients.rst} | 94 +-
Documentation/index.rst | 10 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 +-
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +-
.../isdn/{README.hysdn => hysdn.rst} | 125 +-
Documentation/isdn/index.rst | 24 +
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +-
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
.../m68k/{README.buddha => buddha-driver.rst} | 95 +-
Documentation/m68k/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +-
Documentation/mips/index.rst | 17 +
.../networking/caif/{README => caif.rst} | 88 +-
.../networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
.../{README => mac80211_hwsim.rst} | 28 +-
Documentation/nios2/{README => nios2.rst} | 1 +
Documentation/openrisc/index.rst | 18 +
.../openrisc/{README => openrisc_port.rst} | 25 +-
Documentation/openrisc/{TODO => todo.rst} | 9 +-
.../parisc/{debugging => debugging.rst} | 7 +
Documentation/parisc/index.rst | 18 +
.../parisc/{registers => registers.rst} | 59 +-
Documentation/power/index.rst | 2 +-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +-
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/sound/index.rst | 2 +-
.../spi/{butterfly => butterfly.rst} | 44 +-
Documentation/spi/index.rst | 22 +
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 +-
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 +-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 5 +-
.../spi/{spi-summary => spi-summary.rst} | 105 +-
Documentation/spi/{spidev => spidev.rst} | 30 +-
Documentation/w1/index.rst | 21 +
.../w1/masters/{ds2482 => ds2482.rst} | 16 +-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +
.../w1/masters/{mxc-w1 => mxc-w1.rst} | 13 +-
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +-
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +-
Documentation/w1/slaves/index.rst | 16 +
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +-
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 +
.../w1/slaves/{w1_ds2423 => w1_ds2423.rst} | 27 +-
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 +-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 +
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 +-
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 +-
.../w1/{w1.generic => w1-generic.rst} | 88 +-
.../w1/{w1.netlink => w1-netlink.rst} | 89 +-
MAINTAINERS | 68 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 4 +-
drivers/rtc/rtc-ds1374.c | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
fs/orangefs/orangefs-kernel.h | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
include/linux/i2c.h | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
include/linux/thermal.h | 4 +-
include/soc/fsl/qe/qe.h | 2 +-
216 files changed, 9148 insertions(+), 8672 deletions(-)
rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
create mode 100644 Documentation/admin-guide/cifs/index.rst
rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
rename Documentation/filesystems/{porting => porting.rst} (49%)
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
rename Documentation/nios2/{README => nios2.rst} (96%)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
--
2.21.0
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply [flat|nested] 75+ messages in thread
* [OpenRISC] [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
To: openrisc
This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.
This series is at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
And it is based on yesterday's upstream tree.
After this series, we have ~320 files left to be converted to ReST.
v2:
- Added 3 files submitted for v5.3 that weren't merged yet;
- markdown patch broken into two, per Rob's request;
- rebased on the top of upstream master branch
Mauro Carvalho Chehab (26):
docs: power: add it to to the main documentation index
docs: thermal: add it to the driver API
docs: powerpc: convert docs to ReST and rename to *.rst
docs: ubifs-authentication.md: convert to ReST
docs: writing-schema.md: convert from markdown to ReST
docs: i2c: convert to ReST and add to driver-api bookset
docs: w1: convert to ReST and add to the kAPI group of docs
spi: docs: convert to ReST and add it to the kABI bookset
docs: ipmb: place it at driver-api and convert to ReST
docs: packing: move it to core-api book and adjust markups
docs: admin-guide: add auxdisplay files to it after conversion to ReST
docs: README.buddha: convert to ReST and add to m68k book
docs: parisc: convert to ReST and add to documentation body
docs: openrisc: convert to ReST and add to documentation body
docs: isdn: convert to ReST and add to kAPI bookset
docs: fs: cifs: convert to ReST and add to admin-guide book
docs: fs: convert docs without extension to ReST
docs: fs: convert porting to ReST
docs: index.rst: don't use genindex for pdf output
docs: wimax: convert to ReST and add to admin-guide
docs: mips: add to the documentation body as ReST
docs: hwmon: pxe1610: convert to ReST format and add to the index
docs: nios2: add it to the main Documentation body
docs: net: convert two README files to ReST format
docs: rcu: convert some articles from html to ReST
docs: ABI: remove extension from sysfs-class-mic.txt
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
.../{sysfs-class-mic.txt => sysfs-class-mic} | 0
Documentation/PCI/pci-error-recovery.rst | 2 +-
.../Data-Structures/Data-Structures.html | 1391 -------
.../Data-Structures/Data-Structures.rst | 1163 ++++++
...riods.html => Expedited-Grace-Periods.rst} | 949 ++---
.../Memory-Ordering/Tree-RCU-Diagram.html | 9 -
...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
.../RCU/Design/Requirements/Requirements.html | 3330 -----------------
.../RCU/Design/Requirements/Requirements.rst | 2662 +++++++++++++
Documentation/RCU/index.rst | 5 +
Documentation/RCU/whatisRCU.txt | 4 +-
.../auxdisplay/cfag12864b.rst} | 115 +-
.../admin-guide/auxdisplay/index.rst | 16 +
.../auxdisplay/ks0108.rst} | 53 +-
.../AUTHORS => admin-guide/cifs/authors.rst} | 64 +-
.../CHANGES => admin-guide/cifs/changes.rst} | 4 +
Documentation/admin-guide/cifs/index.rst | 21 +
.../cifs/introduction.rst} | 8 +
.../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +-
.../README => admin-guide/cifs/usage.rst} | 560 +--
.../cifs/winucase_convert.pl | 0
Documentation/admin-guide/index.rst | 3 +
.../wimax/i2400m.rst} | 145 +-
Documentation/admin-guide/wimax/index.rst | 19 +
.../wimax/wimax.rst} | 36 +-
Documentation/core-api/index.rst | 3 +-
.../{packing.txt => core-api/packing.rst} | 81 +-
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
.../{writing-schema.md => writing-schema.rst} | 137 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/index.rst | 2 +
Documentation/driver-api/ipmb.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
.../thermal/cpu-cooling-api.rst | 0
.../thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
.../{ => driver-api}/thermal/index.rst | 2 +-
.../thermal/intel_powerclamp.rst | 0
.../thermal/nouveau_thermal.rst | 0
.../thermal/power_allocator.rst | 0
.../{ => driver-api}/thermal/sysfs-api.rst | 12 +-
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
...irectory-locking => directory-locking.rst} | 40 +-
Documentation/filesystems/index.rst | 4 +
.../filesystems/{Locking => locking.rst} | 257 +-
.../nfs/{Exporting => exporting.rst} | 31 +-
.../filesystems/{porting => porting.rst} | 824 ++--
...entication.md => ubifs-authentication.rst} | 70 +-
Documentation/filesystems/vfs.rst | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +-
.../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} | 14 +-
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +-
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +-
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
...2c-parport-light => i2c-parport-light.rst} | 8 +-
.../busses/{i2c-parport => i2c-parport.rst} | 164 +-
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +-
.../i2c/busses/{i2c-sis630 => i2c-sis630.rst} | 39 +-
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 +-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 28 +-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 +-
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 5 +-
.../i2c/{functionality => functionality.rst} | 22 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 +-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +-
Documentation/i2c/index.rst | 37 +
...ting-devices => instantiating-devices.rst} | 45 +-
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +-
...e-parameters => old-module-parameters.rst} | 27 +-
...eprom-backend => slave-eeprom-backend.rst} | 4 +-
.../{slave-interface => slave-interface.rst} | 33 +-
.../{smbus-protocol => smbus-protocol.rst} | 86 +-
Documentation/i2c/{summary => summary.rst} | 6 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 204 +-
.../{writing-clients => writing-clients.rst} | 94 +-
Documentation/index.rst | 10 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 +-
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +-
.../isdn/{README.hysdn => hysdn.rst} | 125 +-
Documentation/isdn/index.rst | 24 +
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +-
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
.../m68k/{README.buddha => buddha-driver.rst} | 95 +-
Documentation/m68k/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +-
Documentation/mips/index.rst | 17 +
.../networking/caif/{README => caif.rst} | 88 +-
.../networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
.../{README => mac80211_hwsim.rst} | 28 +-
Documentation/nios2/{README => nios2.rst} | 1 +
Documentation/openrisc/index.rst | 18 +
.../openrisc/{README => openrisc_port.rst} | 25 +-
Documentation/openrisc/{TODO => todo.rst} | 9 +-
.../parisc/{debugging => debugging.rst} | 7 +
Documentation/parisc/index.rst | 18 +
.../parisc/{registers => registers.rst} | 59 +-
Documentation/power/index.rst | 2 +-
.../{bootwrapper.txt => bootwrapper.rst} | 28 +-
.../{cpu_families.txt => cpu_families.rst} | 23 +-
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +-
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +-
...ed-dump.txt => firmware-assisted-dump.rst} | 117 +-
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 +-
Documentation/powerpc/index.rst | 34 +
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +-
.../{qe_firmware.txt => qe_firmware.rst} | 37 +-
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +-
...al_memory.txt => transactional_memory.rst} | 45 +-
Documentation/sound/index.rst | 2 +-
.../spi/{butterfly => butterfly.rst} | 44 +-
Documentation/spi/index.rst | 22 +
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 +-
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 +-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 5 +-
.../spi/{spi-summary => spi-summary.rst} | 105 +-
Documentation/spi/{spidev => spidev.rst} | 30 +-
Documentation/w1/index.rst | 21 +
.../w1/masters/{ds2482 => ds2482.rst} | 16 +-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +
.../w1/masters/{mxc-w1 => mxc-w1.rst} | 13 +-
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +-
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +-
Documentation/w1/slaves/index.rst | 16 +
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +-
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 +
.../w1/slaves/{w1_ds2423 => w1_ds2423.rst} | 27 +-
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 +-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 +
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 +-
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 +-
.../w1/{w1.generic => w1-generic.rst} | 88 +-
.../w1/{w1.netlink => w1-netlink.rst} | 89 +-
MAINTAINERS | 68 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 4 +-
drivers/rtc/rtc-ds1374.c | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
fs/orangefs/orangefs-kernel.h | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
include/linux/i2c.h | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
include/linux/thermal.h | 4 +-
include/soc/fsl/qe/qe.h | 2 +-
216 files changed, 9148 insertions(+), 8672 deletions(-)
rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
create mode 100644 Documentation/admin-guide/cifs/index.rst
rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
rename Documentation/filesystems/{porting => porting.rst} (49%)
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
rename Documentation/nios2/{README => nios2.rst} (96%)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
--
2.21.0
^ permalink raw reply [flat|nested] 75+ messages in thread
* [PATCH v2 01/26] docs: power: add it to to the main documentation index
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (3 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-31 19:03 ` Jonathan Corbet
-1 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Rafael J. Wysocki,
Len Brown, Pavel Machek, linux-doc, linux-pm
The power docs are orphaned at the documentation body.
While it could likely be moved to be inside some guide, I'm opting to just
adding it to the main index.rst, removing the :orphan: and adding the SPDX
header.
The reason is similar to what it was done for other driver-specific
subsystems: the docs there contain a mix of Kernelspace, uAPI and
admin-guide. So, better to keep them on its own directory,
while the docs there are not properly classified.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
Documentation/power/index.rst | 2 +-
2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 70ae148ec980..230e550e9741 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -111,6 +111,7 @@ needed).
netlabel/index
networking/index
pcmcia/index
+ power/index
target/index
timers/index
watchdog/index
diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
index 20415f21e48a..002e42745263 100644
--- a/Documentation/power/index.rst
+++ b/Documentation/power/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
================
Power Management
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 02/26] docs: thermal: add it to the driver API
2019-07-26 12:51 ` Mauro Carvalho Chehab
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Amit Daniel Kachhap,
Viresh Kumar, Javi Merino, Kukjin Kim, Krzysztof Kozlowski,
Zhang Rui, Eduardo Valentin, Daniel Lezcano, linux-doc, linux-pm,
linux-arm-kernel, linux-samsung-soc
The file contents mostly describes driver internals.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
.../{ => driver-api}/thermal/cpu-cooling-api.rst | 0
.../{ => driver-api}/thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
Documentation/{ => driver-api}/thermal/index.rst | 2 +-
.../{ => driver-api}/thermal/intel_powerclamp.rst | 0
.../{ => driver-api}/thermal/nouveau_thermal.rst | 0
.../{ => driver-api}/thermal/power_allocator.rst | 0
Documentation/{ => driver-api}/thermal/sysfs-api.rst | 12 ++++++------
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
MAINTAINERS | 2 +-
include/linux/thermal.h | 4 ++--
12 files changed, 12 insertions(+), 11 deletions(-)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f386a6..37ac052ded85 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@ available subsections can be seen below.
dmaengine/index
slimbus
soundwire/index
+ thermal/index
fpga/index
acpi/index
backlight/lp855x-driver.rst
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
similarity index 100%
rename from Documentation/thermal/cpu-cooling-api.rst
rename to Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal.rst
rename to Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal_emulation.rst
rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
similarity index 86%
rename from Documentation/thermal/index.rst
rename to Documentation/driver-api/thermal/index.rst
index 8c1c00146cad..5ba61d19c6ae 100644
--- a/Documentation/thermal/index.rst
+++ b/Documentation/driver-api/thermal/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
=======
Thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
similarity index 100%
rename from Documentation/thermal/intel_powerclamp.rst
rename to Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
similarity index 100%
rename from Documentation/thermal/nouveau_thermal.rst
rename to Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
similarity index 100%
rename from Documentation/thermal/power_allocator.rst
rename to Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
similarity index 98%
rename from Documentation/thermal/sysfs-api.rst
rename to Documentation/driver-api/thermal/sysfs-api.rst
index e4930761d3e5..fab2c9b36d08 100644
--- a/Documentation/thermal/sysfs-api.rst
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -552,7 +552,7 @@ emul_temp
sustainable_power
An estimate of the sustained power that can be dissipated by
the thermal zone. Used by the power allocator governor. For
- more information see Documentation/thermal/power_allocator.rst
+ more information see Documentation/driver-api/thermal/power_allocator.rst
Unit: milliwatts
@@ -563,7 +563,7 @@ k_po
controller during temperature overshoot. Temperature overshoot
is when the current temperature is above the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -572,7 +572,7 @@ k_pu
controller during temperature undershoot. Temperature undershoot
is when the current temperature is below the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -580,14 +580,14 @@ k_i
The integral term of the power allocator governor's PID
controller. This term allows the PID controller to compensate
for long term drift. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
k_d
The derivative term of the power allocator governor's PID
controller. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -598,7 +598,7 @@ integral_cutoff
example, if integral_cutoff is 0, then the integral term only
accumulates error when temperature is above the desired
temperature trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
Unit: millidegree Celsius
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
similarity index 94%
rename from Documentation/thermal/x86_pkg_temperature_thermal.rst
rename to Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
index f134dbd3f5a9..2ac42ccd236f 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -40,7 +40,7 @@ This contains two trip points:
- trip_point_1_temp
User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
thermal sys-fs details.
Any value other than 0 in these trip points, can trigger thermal notifications.
diff --git a/MAINTAINERS b/MAINTAINERS
index 4e2a525e22c0..3d6cd6efb264 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15907,7 +15907,7 @@ M: Viresh Kumar <viresh.kumar@linaro.org>
M: Javi Merino <javi.merino@kernel.org>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/thermal/cpu-cooling-api.rst
+F: Documentation/driver-api/thermal/cpu-cooling-api.rst
F: drivers/thermal/cpu_cooling.c
F: include/linux/cpu_cooling.h
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 681047f8cc05..e45659c75920 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
* platform characterization. This value is relative to the
* rest of the weights so a cooling device whose weight is
* double that of another cooling device is twice as
- * effective. See Documentation/thermal/sysfs-api.rst for more
+ * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
* information.
*/
int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
/*
* This is a bit mask that gives the binding relation between this
* thermal zone and cdev, for a particular trip point.
- * See Documentation/thermal/sysfs-api.rst for more information.
+ * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
*/
int trip_mask;
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 02/26] docs: thermal: add it to the driver API
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: linux-samsung-soc, Jonathan Corbet, Viresh Kumar,
Amit Daniel Kachhap, Daniel Lezcano, linux-doc,
Krzysztof Kozlowski, Eduardo Valentin, Kukjin Kim, linux-pm,
Mauro Carvalho Chehab, Zhang Rui, Javi Merino, linux-arm-kernel
The file contents mostly describes driver internals.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
.../{ => driver-api}/thermal/cpu-cooling-api.rst | 0
.../{ => driver-api}/thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
Documentation/{ => driver-api}/thermal/index.rst | 2 +-
.../{ => driver-api}/thermal/intel_powerclamp.rst | 0
.../{ => driver-api}/thermal/nouveau_thermal.rst | 0
.../{ => driver-api}/thermal/power_allocator.rst | 0
Documentation/{ => driver-api}/thermal/sysfs-api.rst | 12 ++++++------
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
MAINTAINERS | 2 +-
include/linux/thermal.h | 4 ++--
12 files changed, 12 insertions(+), 11 deletions(-)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f386a6..37ac052ded85 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@ available subsections can be seen below.
dmaengine/index
slimbus
soundwire/index
+ thermal/index
fpga/index
acpi/index
backlight/lp855x-driver.rst
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
similarity index 100%
rename from Documentation/thermal/cpu-cooling-api.rst
rename to Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal.rst
rename to Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal_emulation.rst
rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
similarity index 86%
rename from Documentation/thermal/index.rst
rename to Documentation/driver-api/thermal/index.rst
index 8c1c00146cad..5ba61d19c6ae 100644
--- a/Documentation/thermal/index.rst
+++ b/Documentation/driver-api/thermal/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
=======
Thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
similarity index 100%
rename from Documentation/thermal/intel_powerclamp.rst
rename to Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
similarity index 100%
rename from Documentation/thermal/nouveau_thermal.rst
rename to Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
similarity index 100%
rename from Documentation/thermal/power_allocator.rst
rename to Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
similarity index 98%
rename from Documentation/thermal/sysfs-api.rst
rename to Documentation/driver-api/thermal/sysfs-api.rst
index e4930761d3e5..fab2c9b36d08 100644
--- a/Documentation/thermal/sysfs-api.rst
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -552,7 +552,7 @@ emul_temp
sustainable_power
An estimate of the sustained power that can be dissipated by
the thermal zone. Used by the power allocator governor. For
- more information see Documentation/thermal/power_allocator.rst
+ more information see Documentation/driver-api/thermal/power_allocator.rst
Unit: milliwatts
@@ -563,7 +563,7 @@ k_po
controller during temperature overshoot. Temperature overshoot
is when the current temperature is above the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -572,7 +572,7 @@ k_pu
controller during temperature undershoot. Temperature undershoot
is when the current temperature is below the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -580,14 +580,14 @@ k_i
The integral term of the power allocator governor's PID
controller. This term allows the PID controller to compensate
for long term drift. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
k_d
The derivative term of the power allocator governor's PID
controller. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -598,7 +598,7 @@ integral_cutoff
example, if integral_cutoff is 0, then the integral term only
accumulates error when temperature is above the desired
temperature trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
Unit: millidegree Celsius
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
similarity index 94%
rename from Documentation/thermal/x86_pkg_temperature_thermal.rst
rename to Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
index f134dbd3f5a9..2ac42ccd236f 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -40,7 +40,7 @@ This contains two trip points:
- trip_point_1_temp
User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
thermal sys-fs details.
Any value other than 0 in these trip points, can trigger thermal notifications.
diff --git a/MAINTAINERS b/MAINTAINERS
index 4e2a525e22c0..3d6cd6efb264 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15907,7 +15907,7 @@ M: Viresh Kumar <viresh.kumar@linaro.org>
M: Javi Merino <javi.merino@kernel.org>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/thermal/cpu-cooling-api.rst
+F: Documentation/driver-api/thermal/cpu-cooling-api.rst
F: drivers/thermal/cpu_cooling.c
F: include/linux/cpu_cooling.h
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 681047f8cc05..e45659c75920 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
* platform characterization. This value is relative to the
* rest of the weights so a cooling device whose weight is
* double that of another cooling device is twice as
- * effective. See Documentation/thermal/sysfs-api.rst for more
+ * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
* information.
*/
int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
/*
* This is a bit mask that gives the binding relation between this
* thermal zone and cdev, for a particular trip point.
- * See Documentation/thermal/sysfs-api.rst for more information.
+ * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
*/
int trip_mask;
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 02/26] docs: thermal: add it to the driver API
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: linux-samsung-soc, Jonathan Corbet, Viresh Kumar,
Amit Daniel Kachhap, Daniel Lezcano, linux-doc,
Krzysztof Kozlowski, Eduardo Valentin, Kukjin Kim, linux-pm,
Mauro Carvalho Chehab, Zhang Rui, Javi Merino, linux-arm-kernel
The file contents mostly describes driver internals.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
.../{ => driver-api}/thermal/cpu-cooling-api.rst | 0
.../{ => driver-api}/thermal/exynos_thermal.rst | 0
.../thermal/exynos_thermal_emulation.rst | 0
Documentation/{ => driver-api}/thermal/index.rst | 2 +-
.../{ => driver-api}/thermal/intel_powerclamp.rst | 0
.../{ => driver-api}/thermal/nouveau_thermal.rst | 0
.../{ => driver-api}/thermal/power_allocator.rst | 0
Documentation/{ => driver-api}/thermal/sysfs-api.rst | 12 ++++++------
.../thermal/x86_pkg_temperature_thermal.rst | 2 +-
MAINTAINERS | 2 +-
include/linux/thermal.h | 4 ++--
12 files changed, 12 insertions(+), 11 deletions(-)
rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
rename Documentation/{ => driver-api}/thermal/index.rst (86%)
rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f386a6..37ac052ded85 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@ available subsections can be seen below.
dmaengine/index
slimbus
soundwire/index
+ thermal/index
fpga/index
acpi/index
backlight/lp855x-driver.rst
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
similarity index 100%
rename from Documentation/thermal/cpu-cooling-api.rst
rename to Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal.rst
rename to Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal_emulation.rst
rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
similarity index 86%
rename from Documentation/thermal/index.rst
rename to Documentation/driver-api/thermal/index.rst
index 8c1c00146cad..5ba61d19c6ae 100644
--- a/Documentation/thermal/index.rst
+++ b/Documentation/driver-api/thermal/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
=======
Thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
similarity index 100%
rename from Documentation/thermal/intel_powerclamp.rst
rename to Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
similarity index 100%
rename from Documentation/thermal/nouveau_thermal.rst
rename to Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
similarity index 100%
rename from Documentation/thermal/power_allocator.rst
rename to Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
similarity index 98%
rename from Documentation/thermal/sysfs-api.rst
rename to Documentation/driver-api/thermal/sysfs-api.rst
index e4930761d3e5..fab2c9b36d08 100644
--- a/Documentation/thermal/sysfs-api.rst
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -552,7 +552,7 @@ emul_temp
sustainable_power
An estimate of the sustained power that can be dissipated by
the thermal zone. Used by the power allocator governor. For
- more information see Documentation/thermal/power_allocator.rst
+ more information see Documentation/driver-api/thermal/power_allocator.rst
Unit: milliwatts
@@ -563,7 +563,7 @@ k_po
controller during temperature overshoot. Temperature overshoot
is when the current temperature is above the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -572,7 +572,7 @@ k_pu
controller during temperature undershoot. Temperature undershoot
is when the current temperature is below the "desired
temperature" trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -580,14 +580,14 @@ k_i
The integral term of the power allocator governor's PID
controller. This term allows the PID controller to compensate
for long term drift. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
k_d
The derivative term of the power allocator governor's PID
controller. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
RW, Optional
@@ -598,7 +598,7 @@ integral_cutoff
example, if integral_cutoff is 0, then the integral term only
accumulates error when temperature is above the desired
temperature trip point. For more information see
- Documentation/thermal/power_allocator.rst
+ Documentation/driver-api/thermal/power_allocator.rst
Unit: millidegree Celsius
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
similarity index 94%
rename from Documentation/thermal/x86_pkg_temperature_thermal.rst
rename to Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
index f134dbd3f5a9..2ac42ccd236f 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -40,7 +40,7 @@ This contains two trip points:
- trip_point_1_temp
User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
thermal sys-fs details.
Any value other than 0 in these trip points, can trigger thermal notifications.
diff --git a/MAINTAINERS b/MAINTAINERS
index 4e2a525e22c0..3d6cd6efb264 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15907,7 +15907,7 @@ M: Viresh Kumar <viresh.kumar@linaro.org>
M: Javi Merino <javi.merino@kernel.org>
L: linux-pm@vger.kernel.org
S: Supported
-F: Documentation/thermal/cpu-cooling-api.rst
+F: Documentation/driver-api/thermal/cpu-cooling-api.rst
F: drivers/thermal/cpu_cooling.c
F: include/linux/cpu_cooling.h
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 681047f8cc05..e45659c75920 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
* platform characterization. This value is relative to the
* rest of the weights so a cooling device whose weight is
* double that of another cooling device is twice as
- * effective. See Documentation/thermal/sysfs-api.rst for more
+ * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
* information.
*/
int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
/*
* This is a bit mask that gives the binding relation between this
* thermal zone and cdev, for a particular trip point.
- * See Documentation/thermal/sysfs-api.rst for more information.
+ * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
*/
int trip_mask;
--
2.21.0
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
2019-07-26 12:51 ` Mauro Carvalho Chehab
(?)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Linas Vepstas, Russell Currey,
Sam Bobroff, Oliver O'Halloran, Bjorn Helgaas,
Jonathan Corbet, Benjamin Herrenschmidt, Paul Mackerras,
Michael Ellerman, Frederic Barrat, Andrew Donnellan,
Manoj N. Kumar, Matthew R. Ochs, Uma Krishnan, Qiang Zhao,
Li Yang, Greg Kroah-Hartman, Jiri Slaby, linux-pci, linuxppc-dev,
linux-doc, linux-scsi, linux-arm-kernel, Andrew Donnellan
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
Documentation/PCI/pci-error-recovery.rst | 2 +-
Documentation/index.rst | 1 +
.../{bootwrapper.txt => bootwrapper.rst} | 28 ++-
.../{cpu_families.txt => cpu_families.rst} | 23 +--
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +++--
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 ++++++-----
Documentation/powerpc/index.rst | 34 ++++
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +++++++++---------
.../{qe_firmware.txt => qe_firmware.rst} | 37 ++--
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +--
...al_memory.txt => transactional_memory.rst} | 45 ++---
MAINTAINERS | 6 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
26 files changed, 495 insertions(+), 358 deletions(-)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
.. note::
Implementation details for the powerpc platform are discussed in
- the file Documentation/powerpc/eeh-pci-error-recovery.txt
+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
arm64/index
ia64/index
m68k/index
+ powerpc/index
riscv/index
s390/index
sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+ - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -28,7 +32,7 @@ Introduction
responsible for the initialization of the adapter, setting up the
special path for user space access, and performing error recovery. It
communicates directly the Flash Accelerator Functional Unit (AFU)
- as described in Documentation/powerpc/cxl.txt.
+ as described in Documentation/powerpc/cxl.rst.
The cxlflash driver supports two, mutually exclusive, modes of
operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
if it points to cache inhibited (CI) memory. Currently Linux has no way to
disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
writing the DAWR.
To double check the DAWR is working, run this kernel selftest:
+
tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ bootwrapper
+ cpu_families
+ cpu_features
+ cxl
+ cxlflash
+ dawr-power9
+ dscr
+ eeh-pci-error-recovery
+ firmware-assisted-dump
+ hvcs
+ isa-versions
+ mpc52xx
+ pci_iov_resource_on_powernv
+ pmu-ebb
+ ptrace
+ qe_firmware
+ syscall64-abi
+ transactional_memory
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -60,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -73,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
GDB intends to support the following hardware debug features of BookE
processors:
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
following 3 new ptrace requests.
1. PTRACE_PPC_GETHWDEBUGINFO
+============================
Query for GDB to discover the hardware debug features. The main info to
be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
Since we're at it, we added other useful info that the kernel can return to
GDB: this query will return the number of hardware breakpoints, hardware
watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
-struct ppc_debug_info {
+ struct ppc_debug_info {
unit32_t version;
unit32_t num_instruction_bps;
unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
unit32_t data_bp_alignment;
unit32_t sizeof_condition; /* size of the DVC register */
uint64_t features; /* bitmask of the individual flags */
-};
+ };
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
2. PTRACE_SETHWDEBUG
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
-struct ppc_hw_breakpoint {
+ struct ppc_hw_breakpoint {
uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
uint32_t addr_mode; /* address match mode */
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
uint32_t condition_mode; /* break/watchpoint condition flags */
uint64_t addr;
uint64_t addr2;
uint64_t condition_value;
-};
+ };
A request specifies one event, not necessarily just one register to be set.
For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
Some examples of using the structure to:
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
3. PTRACE_DELHWDEBUG
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F: arch/powerpc/platforms/powernv/pci-cxl.c
F: drivers/misc/cxl/
F: include/misc/cxl*
F: include/uapi/misc/cxl.h
-F: Documentation/powerpc/cxl.txt
+F: Documentation/powerpc/cxl.rst
F: Documentation/ABI/testing/sysfs-class-cxl
CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L: linux-scsi@vger.kernel.org
S: Supported
F: drivers/scsi/cxlflash/
F: include/uapi/scsi/cxlflash_ioctl.h
-F: Documentation/powerpc/cxlflash.txt
+F: Documentation/powerpc/cxlflash.rst
CYBERPRO FB DRIVER
M: Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
-F: Documentation/powerpc/eeh-pci-error-recovery.txt
+F: Documentation/powerpc/eeh-pci-error-recovery.rst
F: arch/powerpc/kernel/eeh*.c
F: arch/powerpc/platforms/*/eeh*.c
F: arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
*
* Call convention:
*
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
*
* For hypercalls, the register convention is as follows:
* r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
/*
* Upload a microcode to the I-RAM at a specific address.
*
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
* uploading.
*
* Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
* using the 2.6 Linux kernel kref construct.
*
* For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
*/
#include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
/* Structure that defines QE firmware binary files.
*
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
* fields.
*/
struct qe_firmware {
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: linux-doc, Benjamin Herrenschmidt, linux-pci,
Oliver O'Halloran, Russell Currey, Mauro Carvalho Chehab,
Qiang Zhao, linux-scsi, Jonathan Corbet, Michael Ellerman,
Jiri Slaby, Linas Vepstas, Andrew Donnellan, Manoj N. Kumar,
Bjorn Helgaas, linux-arm-kernel, Matthew R. Ochs, Uma Krishnan,
Sam Bobroff, Greg Kroah-Hartman, Li Yang, Andrew Donnellan,
Frederic Barrat, Paul
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
Documentation/PCI/pci-error-recovery.rst | 2 +-
Documentation/index.rst | 1 +
.../{bootwrapper.txt => bootwrapper.rst} | 28 ++-
.../{cpu_families.txt => cpu_families.rst} | 23 +--
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +++--
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 ++++++-----
Documentation/powerpc/index.rst | 34 ++++
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +++++++++---------
.../{qe_firmware.txt => qe_firmware.rst} | 37 ++--
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +--
...al_memory.txt => transactional_memory.rst} | 45 ++---
MAINTAINERS | 6 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
26 files changed, 495 insertions(+), 358 deletions(-)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
.. note::
Implementation details for the powerpc platform are discussed in
- the file Documentation/powerpc/eeh-pci-error-recovery.txt
+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
arm64/index
ia64/index
m68k/index
+ powerpc/index
riscv/index
s390/index
sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+ - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -28,7 +32,7 @@ Introduction
responsible for the initialization of the adapter, setting up the
special path for user space access, and performing error recovery. It
communicates directly the Flash Accelerator Functional Unit (AFU)
- as described in Documentation/powerpc/cxl.txt.
+ as described in Documentation/powerpc/cxl.rst.
The cxlflash driver supports two, mutually exclusive, modes of
operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
if it points to cache inhibited (CI) memory. Currently Linux has no way to
disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
writing the DAWR.
To double check the DAWR is working, run this kernel selftest:
+
tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ bootwrapper
+ cpu_families
+ cpu_features
+ cxl
+ cxlflash
+ dawr-power9
+ dscr
+ eeh-pci-error-recovery
+ firmware-assisted-dump
+ hvcs
+ isa-versions
+ mpc52xx
+ pci_iov_resource_on_powernv
+ pmu-ebb
+ ptrace
+ qe_firmware
+ syscall64-abi
+ transactional_memory
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -60,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -73,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
GDB intends to support the following hardware debug features of BookE
processors:
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
following 3 new ptrace requests.
1. PTRACE_PPC_GETHWDEBUGINFO
+============================
Query for GDB to discover the hardware debug features. The main info to
be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
Since we're at it, we added other useful info that the kernel can return to
GDB: this query will return the number of hardware breakpoints, hardware
watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
-struct ppc_debug_info {
+ struct ppc_debug_info {
unit32_t version;
unit32_t num_instruction_bps;
unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
unit32_t data_bp_alignment;
unit32_t sizeof_condition; /* size of the DVC register */
uint64_t features; /* bitmask of the individual flags */
-};
+ };
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
2. PTRACE_SETHWDEBUG
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
-struct ppc_hw_breakpoint {
+ struct ppc_hw_breakpoint {
uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
uint32_t addr_mode; /* address match mode */
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
uint32_t condition_mode; /* break/watchpoint condition flags */
uint64_t addr;
uint64_t addr2;
uint64_t condition_value;
-};
+ };
A request specifies one event, not necessarily just one register to be set.
For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
Some examples of using the structure to:
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
3. PTRACE_DELHWDEBUG
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F: arch/powerpc/platforms/powernv/pci-cxl.c
F: drivers/misc/cxl/
F: include/misc/cxl*
F: include/uapi/misc/cxl.h
-F: Documentation/powerpc/cxl.txt
+F: Documentation/powerpc/cxl.rst
F: Documentation/ABI/testing/sysfs-class-cxl
CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L: linux-scsi@vger.kernel.org
S: Supported
F: drivers/scsi/cxlflash/
F: include/uapi/scsi/cxlflash_ioctl.h
-F: Documentation/powerpc/cxlflash.txt
+F: Documentation/powerpc/cxlflash.rst
CYBERPRO FB DRIVER
M: Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
-F: Documentation/powerpc/eeh-pci-error-recovery.txt
+F: Documentation/powerpc/eeh-pci-error-recovery.rst
F: arch/powerpc/kernel/eeh*.c
F: arch/powerpc/platforms/*/eeh*.c
F: arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
*
* Call convention:
*
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
*
* For hypercalls, the register convention is as follows:
* r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
/*
* Upload a microcode to the I-RAM at a specific address.
*
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
* uploading.
*
* Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
* using the 2.6 Linux kernel kref construct.
*
* For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
*/
#include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
/* Structure that defines QE firmware binary files.
*
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
* fields.
*/
struct qe_firmware {
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: linux-doc, linux-pci, Oliver O'Halloran,
Mauro Carvalho Chehab, Qiang Zhao, linux-scsi, Jonathan Corbet,
Jiri Slaby, Linas Vepstas, Andrew Donnellan, Manoj N. Kumar,
Bjorn Helgaas, linux-arm-kernel, Matthew R. Ochs, Uma Krishnan,
Sam Bobroff, Greg Kroah-Hartman, Li Yang, Andrew Donnellan,
Frederic Barrat, Paul Mackerras, linuxppc-dev
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
Documentation/PCI/pci-error-recovery.rst | 2 +-
Documentation/index.rst | 1 +
.../{bootwrapper.txt => bootwrapper.rst} | 28 ++-
.../{cpu_families.txt => cpu_families.rst} | 23 +--
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +++--
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 ++++++-----
Documentation/powerpc/index.rst | 34 ++++
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +++++++++---------
.../{qe_firmware.txt => qe_firmware.rst} | 37 ++--
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +--
...al_memory.txt => transactional_memory.rst} | 45 ++---
MAINTAINERS | 6 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
26 files changed, 495 insertions(+), 358 deletions(-)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
.. note::
Implementation details for the powerpc platform are discussed in
- the file Documentation/powerpc/eeh-pci-error-recovery.txt
+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
arm64/index
ia64/index
m68k/index
+ powerpc/index
riscv/index
s390/index
sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+ - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -28,7 +32,7 @@ Introduction
responsible for the initialization of the adapter, setting up the
special path for user space access, and performing error recovery. It
communicates directly the Flash Accelerator Functional Unit (AFU)
- as described in Documentation/powerpc/cxl.txt.
+ as described in Documentation/powerpc/cxl.rst.
The cxlflash driver supports two, mutually exclusive, modes of
operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
if it points to cache inhibited (CI) memory. Currently Linux has no way to
disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
writing the DAWR.
To double check the DAWR is working, run this kernel selftest:
+
tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ bootwrapper
+ cpu_families
+ cpu_features
+ cxl
+ cxlflash
+ dawr-power9
+ dscr
+ eeh-pci-error-recovery
+ firmware-assisted-dump
+ hvcs
+ isa-versions
+ mpc52xx
+ pci_iov_resource_on_powernv
+ pmu-ebb
+ ptrace
+ qe_firmware
+ syscall64-abi
+ transactional_memory
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -60,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -73,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
GDB intends to support the following hardware debug features of BookE
processors:
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
following 3 new ptrace requests.
1. PTRACE_PPC_GETHWDEBUGINFO
+============================
Query for GDB to discover the hardware debug features. The main info to
be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
Since we're at it, we added other useful info that the kernel can return to
GDB: this query will return the number of hardware breakpoints, hardware
watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
-struct ppc_debug_info {
+ struct ppc_debug_info {
unit32_t version;
unit32_t num_instruction_bps;
unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
unit32_t data_bp_alignment;
unit32_t sizeof_condition; /* size of the DVC register */
uint64_t features; /* bitmask of the individual flags */
-};
+ };
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
2. PTRACE_SETHWDEBUG
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
-struct ppc_hw_breakpoint {
+ struct ppc_hw_breakpoint {
uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
uint32_t addr_mode; /* address match mode */
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
uint32_t condition_mode; /* break/watchpoint condition flags */
uint64_t addr;
uint64_t addr2;
uint64_t condition_value;
-};
+ };
A request specifies one event, not necessarily just one register to be set.
For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
Some examples of using the structure to:
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
3. PTRACE_DELHWDEBUG
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F: arch/powerpc/platforms/powernv/pci-cxl.c
F: drivers/misc/cxl/
F: include/misc/cxl*
F: include/uapi/misc/cxl.h
-F: Documentation/powerpc/cxl.txt
+F: Documentation/powerpc/cxl.rst
F: Documentation/ABI/testing/sysfs-class-cxl
CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L: linux-scsi@vger.kernel.org
S: Supported
F: drivers/scsi/cxlflash/
F: include/uapi/scsi/cxlflash_ioctl.h
-F: Documentation/powerpc/cxlflash.txt
+F: Documentation/powerpc/cxlflash.rst
CYBERPRO FB DRIVER
M: Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
-F: Documentation/powerpc/eeh-pci-error-recovery.txt
+F: Documentation/powerpc/eeh-pci-error-recovery.rst
F: arch/powerpc/kernel/eeh*.c
F: arch/powerpc/platforms/*/eeh*.c
F: arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
*
* Call convention:
*
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
*
* For hypercalls, the register convention is as follows:
* r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
/*
* Upload a microcode to the I-RAM at a specific address.
*
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
* uploading.
*
* Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
* using the 2.6 Linux kernel kref construct.
*
* For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
*/
#include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
/* Structure that defines QE firmware binary files.
*
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
* fields.
*/
struct qe_firmware {
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: linux-doc, Benjamin Herrenschmidt, linux-pci,
Oliver O'Halloran, Russell Currey, Mauro Carvalho Chehab,
Qiang Zhao, linux-scsi, Jonathan Corbet, Michael Ellerman,
Jiri Slaby, Linas Vepstas, Andrew Donnellan, Manoj N. Kumar,
Bjorn Helgaas, linux-arm-kernel, Matthew R. Ochs, Uma Krishnan,
Sam Bobroff, Greg Kroah-Hartman, Li Yang, Andrew Donnellan,
Frederic Barrat, Paul Mackerras, linuxppc-dev
Convert docs to ReST and add them to the arch-specific
book.
The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.
The changes were mostly to mark literal blocks and add a few
missing section title identifiers.
One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.
At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
Documentation/PCI/pci-error-recovery.rst | 2 +-
Documentation/index.rst | 1 +
.../{bootwrapper.txt => bootwrapper.rst} | 28 ++-
.../{cpu_families.txt => cpu_families.rst} | 23 +--
.../{cpu_features.txt => cpu_features.rst} | 6 +-
Documentation/powerpc/{cxl.txt => cxl.rst} | 46 +++--
.../powerpc/{cxlflash.txt => cxlflash.rst} | 10 +-
.../{DAWR-POWER9.txt => dawr-power9.rst} | 15 +-
Documentation/powerpc/{dscr.txt => dscr.rst} | 18 +-
...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
Documentation/powerpc/{hvcs.txt => hvcs.rst} | 108 ++++++-----
Documentation/powerpc/index.rst | 34 ++++
Documentation/powerpc/isa-versions.rst | 15 +-
.../powerpc/{mpc52xx.txt => mpc52xx.rst} | 12 +-
...nv.txt => pci_iov_resource_on_powernv.rst} | 15 +-
.../powerpc/{pmu-ebb.txt => pmu-ebb.rst} | 1 +
.../powerpc/{ptrace.txt => ptrace.rst} | 169 +++++++++---------
.../{qe_firmware.txt => qe_firmware.rst} | 37 ++--
.../{syscall64-abi.txt => syscall64-abi.rst} | 29 +--
...al_memory.txt => transactional_memory.rst} | 45 ++---
MAINTAINERS | 6 +-
arch/powerpc/kernel/exceptions-64s.S | 2 +-
drivers/soc/fsl/qe/qe.c | 2 +-
drivers/tty/hvc/hvcs.c | 2 +-
include/soc/fsl/qe/qe.h | 2 +-
26 files changed, 495 insertions(+), 358 deletions(-)
rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
create mode 100644 Documentation/powerpc/index.rst
rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
.. note::
Implementation details for the powerpc platform are discussed in
- the file Documentation/powerpc/eeh-pci-error-recovery.txt
+ the file Documentation/powerpc/eeh-pci-error-recovery.rst
As of this writing, there is a growing list of device drivers with
patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
arm64/index
ia64/index
m68k/index
+ powerpc/index
riscv/index
s390/index
sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
The PowerPC boot wrapper
-------------------------
+========================
+
Copyright (C) Secret Lab Technologies Ltd.
PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
image. The details of the build system is discussed in the next section.
Currently, the following image format targets exist:
+ ==================== ========================================================
cuImage.%: Backwards compatible uImage for older version of
U-Boot (for versions that don't understand the device
tree). This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
with boot wrapper code that extracts data from the old
bd_info structure and loads the data into the device
tree before jumping into the kernel.
- Because of the series of #ifdefs found in the
+
+ Because of the series of #ifdefs found in the
bd_info structure used in the old U-Boot interfaces,
cuImages are platform specific. Each specific
U-Boot platform has a different platform init file
which populates the embedded device tree with data
from the platform specific bd_info file. The platform
specific cuImage platform init code can be found in
- arch/powerpc/boot/cuboot.*.c. Selection of the correct
+ `arch/powerpc/boot/cuboot.*.c`. Selection of the correct
cuImage init code for a specific board can be found in
the wrapper structure.
+
dtbImage.%: Similar to zImage, except device tree blob is embedded
inside the image instead of provided by firmware. The
output image file can be either an elf file or a flat
binary depending on the platform.
- dtbImages are used on systems which do not have an
+
+ dtbImages are used on systems which do not have an
interface for passing a device tree directly.
dtbImages are similar to simpleImages except that
dtbImages have platform specific code for extracting
data from the board firmware, but simpleImages do not
talk to the firmware at all.
- PlayStation 3 support uses dtbImage. So do Embedded
+
+ PlayStation 3 support uses dtbImage. So do Embedded
Planet boards using the PlanetCore firmware. Board
specific initialization code is typically found in a
file named arch/powerpc/boot/<platform>.c; but this
can be overridden by the wrapper script.
+
simpleImage.%: Firmware independent compressed image that does not
depend on any particular firmware interface and embeds
a device tree blob. This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
Firmware cannot pass any configuration data to the
kernel with this image type and it depends entirely on
the embedded device tree for all information.
- The simpleImage is useful for booting systems with
+
+ The simpleImage is useful for booting systems with
an unknown firmware interface or for booting from
a debugger when no firmware is present (such as on
the Xilinx Virtex platform). The only assumption that
simpleImage makes is that RAM is correctly initialized
and that the MMU is either off or has RAM mapped to
base address 0.
- simpleImage also supports inserting special platform
+
+ simpleImage also supports inserting special platform
specific initialization code to the start of the bootup
sequence. The virtex405 platform uses this feature to
ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
named (virtex405-<board>.dts). Search the wrapper
script for 'virtex405' and see the file
arch/powerpc/boot/virtex405-head.S for details.
+
treeImage.%; Image format for used with OpenBIOS firmware found
on some ppc4xx hardware. This image embeds a device
tree blob inside the image.
+
uImage: Native image format used by U-Boot. The uImage target
does not add any boot code. It just wraps a compressed
vmlinux in the uImage data structure. This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
a device tree to the kernel at boot. If using an older
version of U-Boot, then you need to use a cuImage
instead.
+
zImage.%: Image format which does not embed a device tree.
Used by OpenFirmware and other firmware interfaces
which are able to supply a device tree. This image
expects firmware to provide the device tree at boot.
Typically, if you have general purpose PowerPC
hardware then you want this image format.
+ ==================== ========================================================
Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
CPU Families
============
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
Book3S (aka sPAPR)
------------------
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
+--------------+ +----------------+
| Old POWER | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
IBM BookE
---------
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
+--------------+
| 401 |
@@ -155,8 +156,8 @@ IBM BookE
Motorola/Freescale 8xx
----------------------
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
+-------------+
| MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
Freescale BookE
---------------
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
+--------------+
| e200 |
@@ -207,8 +208,8 @@ Freescale BookE
IBM A2 core
-----------
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
+--------------+ +----------------+
| A2 core | --> | WSP |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
Hollis Blanchard <hollis@austin.ibm.com>
5 Jun 2002
@@ -32,7 +36,7 @@ anyways).
After detecting the processor type, the kernel patches out sections of code
that shouldn't be used by writing nop's over it. Using cpufeatures requires
just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
#ifdef CONFIG_ALTIVEC
BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
Coherent Accelerator Interface (CXL)
====================================
@@ -21,6 +22,8 @@ Introduction
Hardware overview
=================
+ ::
+
POWER8/9 FPGA
+----------+ +---------+
| | | |
@@ -59,14 +62,16 @@ Hardware overview
the fault. The context to which this fault is serviced is based on
who owns that acceleration function.
- POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
- POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+ - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+ - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
This PSL Version 9 provides new features such as:
+
* Interaction with the nest MMU on the P9 chip.
* Native DMA support.
* Supports sending ASB_Notify messages for host thread wakeup.
* Supports Atomic operations.
- * ....
+ * etc.
Cards with a PSL9 won't work on a POWER8 system and cards with a
PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
master devices.
A userspace library libcxl is available here:
+
https://github.com/ibm-capi/libcxl
+
This provides a C interface to this kernel API.
open
@@ -165,7 +172,8 @@ open
When all available contexts are allocated the open call will fail
and return -ENOSPC.
- Note: IRQs need to be allocated for each context, which may limit
+ Note:
+ IRQs need to be allocated for each context, which may limit
the number of contexts that can be created, and therefore
how many times the device can be opened. The POWER8 CAPP
supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
updated as userspace allocates and frees memory. This ioctl
returns once the AFU context is started.
- Takes a pointer to a struct cxl_ioctl_start_work:
+ Takes a pointer to a struct cxl_ioctl_start_work
+
+ ::
struct cxl_ioctl_start_work {
__u64 flags;
@@ -269,7 +279,7 @@ read
The buffer passed to read() must be at least 4K bytes.
The result of the read will be a buffer of one or more events,
- each event is of type struct cxl_event, of varying size.
+ each event is of type struct cxl_event, of varying size::
struct cxl_event {
struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
};
};
- The struct cxl_event_header is defined as:
+ The struct cxl_event_header is defined as
+
+ ::
struct cxl_event_header {
__u16 type;
@@ -307,7 +319,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_AFU_INTERRUPT then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_afu_interrupt {
__u16 flags;
@@ -326,7 +340,9 @@ read
For future extensions and padding.
If the event type is CXL_EVENT_DATA_STORAGE then the event
- structure is defined as:
+ structure is defined as
+
+ ::
struct cxl_event_data_storage {
__u16 flags;
@@ -356,7 +372,9 @@ read
For future extensions
If the event type is CXL_EVENT_AFU_ERROR then the event structure
- is defined as:
+ is defined as
+
+ ::
struct cxl_event_afu_error {
__u16 flags;
@@ -393,15 +411,15 @@ open
ioctl
-----
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
Starts and controls flashing a new FPGA image. Partial
reconfiguration is not supported (yet), so the image must contain
a copy of the PSL and AFU(s). Since an image can be quite large,
the caller may have to iterate, splitting the image in smaller
chunks.
- Takes a pointer to a struct cxl_adapter_image:
+ Takes a pointer to a struct cxl_adapter_image::
+
struct cxl_adapter_image {
__u64 flags;
__u64 data;
@@ -442,7 +460,7 @@ Udev rules
The following udev rules could be used to create a symlink to the
most logical chardev to use in any programming mode (afuX.Yd for
dedicated, afuX.Ys for afu directed), since the API is virtually
- identical for each:
+ identical for each::
SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
Introduction
============
@@ -28,7 +32,7 @@ Introduction
responsible for the initialization of the adapter, setting up the
special path for user space access, and performing error recovery. It
communicates directly the Flash Accelerator Functional Unit (AFU)
- as described in Documentation/powerpc/cxl.txt.
+ as described in Documentation/powerpc/cxl.rst.
The cxlflash driver supports two, mutually exclusive, modes of
operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
The CXL Flash Adapter Driver establishes a master context with the
AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
- Adapter Problem Space Memory Map looks like this:
+ Adapter Problem Space Memory Map looks like this::
+-------------------------------+
| 512 * 64 KB User MMIO |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
Each host adapter instance that is supported by the cxlflash driver
has a special character device associated with it to enable a set of
host management function. These character devices are hosted in a
- class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+ class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
Applications can be written to perform various functions using the
host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
DAWR issues on POWER9
-============================
+=====================
On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
if it points to cache inhibited (CI) memory. Currently Linux has no way to
disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
powerpc: Disable DAWR in the base POWER9 CPU features
Technical Details:
-============================
+==================
DAWR has 6 different ways of being set.
1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
For xmon, the 'bd' command will return an error on P9.
Consequences for users
-============================
+======================
For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
migrated back to the POWER8 host, it will start working again.
Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
writing the DAWR.
To double check the DAWR is working, run this kernel selftest:
+
tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
- DSCR (Data Stream Control Register)
- ================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
DSCR register in powerpc allows user to have some control of prefetch of data
stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
(A) Data Structures:
- (1) thread_struct:
+ (1) thread_struct::
+
dscr /* Thread DSCR value */
dscr_inherit /* Thread has changed default DSCR */
- (2) PACA:
+ (2) PACA::
+
dscr_default /* per-CPU DSCR default value */
- (3) sysfs.c:
+ (3) sysfs.c::
+
dscr_default /* System DSCR default value */
(B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
(C) SYSFS Interface:
- Global DSCR default: /sys/devices/system/cpu/dscr_default
- CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
+ - Global DSCR default: /sys/devices/system/cpu/dscr_default
+ - CPU specific DSCR default: /sys/devices/system/cpu/cpuN/dscr
Changing the global DSCR default in the sysfs will change all the CPU
specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
+Linas Vepstas <linas@austin.ibm.com>
- PCI Bus EEH Error Recovery
- --------------------------
- Linas Vepstas
- <linas@austin.ibm.com>
- 12 January 2005
+12 January 2005
Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change). Normally, almost
all of these occur during boot, when the PCI bus is scanned, where
a large number of 0xff reads are part of the bus scan procedure.
-If a frozen slot is detected, code in
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
-syslog (/var/log/messages). This stack trace has proven to be very
-useful to device-driver authors for finding out at what point the EEH
-error was detected, as the error itself usually occurs slightly
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages). This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
beforehand.
Next, it uses the Linux kernel notifier chain/work queue mechanism to
allow any interested parties to find out about the failure. Device
drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
events. The event will include a pointer to the pci device, the
device node and some state info. Receivers of the event can "do as
they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
To assist in the recovery of the device, eeh.c exports the
following functions:
-rtas_set_slot_reset() -- assert the PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+ assert the PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+ ask firmware to configure any PCI bridges
located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+ save and restore the PCI
config-space info for a device and any devices under it.
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
Following is an example sequence of events that cause a device driver
close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
rpa_php_unconfig_pci_adapter (struct slot *) // in rpaphp_pci.c
{
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
}}}}}}
- in drivers/pci/pci_driver.c,
- struct device_driver->remove() is just pci_device_remove()
- which calls struct pci_driver->remove() which is pcnet32_remove_one()
- which calls unregister_netdev() (in net/core/dev.c)
- which calls dev_close() (in net/core/dev.c)
- which calls dev->stop() which is pcnet32_close()
- which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev() (in net/core/dev.c)
+which calls dev_close() (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
---
+
Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
-rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
- calls
- pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+ rpa_php_unconfig_pci_adapter() { // in rpaphp_pci.c
calls
- pci_destroy_dev (struct pci_dev *) {
+ pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
calls
- device_unregister (&dev->dev) { // in /drivers/base/core.c
+ pci_destroy_dev (struct pci_dev *) {
calls
- device_del(struct device * dev) { // in /drivers/base/core.c
+ device_unregister (&dev->dev) { // in /drivers/base/core.c
calls
- kobject_del() { //in /libs/kobject.c
+ device_del(struct device * dev) { // in /drivers/base/core.c
calls
- kobject_uevent() { // in /libs/kobject.c
+ kobject_del() { //in /libs/kobject.c
calls
- kset_uevent() { // in /lib/kobject.c
+ kobject_uevent() { // in /libs/kobject.c
calls
- kset->uevent_ops->uevent() // which is really just
- a call to
- dev_uevent() { // in /drivers/base/core.c
+ kset_uevent() { // in /lib/kobject.c
calls
- dev->bus->uevent() which is really just a call to
- pci_uevent () { // in drivers/pci/hotplug.c
- which prints device name, etc....
+ kset->uevent_ops->uevent() // which is really just
+ a call to
+ dev_uevent() { // in /drivers/base/core.c
+ calls
+ dev->bus->uevent() which is really just a call to
+ pci_uevent () { // in drivers/pci/hotplug.c
+ which prints device name, etc....
+ }
}
- }
- then kobject_uevent() sends a netlink uevent to userspace
- --> userspace uevent
- (during early boot, nobody listens to netlink events and
- kobject_uevent() executes uevent_helper[], which runs the
- event process /sbin/hotplug)
+ then kobject_uevent() sends a netlink uevent to userspace
+ --> userspace uevent
+ (during early boot, nobody listens to netlink events and
+ kobject_uevent() executes uevent_helper[], which runs the
+ event process /sbin/hotplug)
+ }
}
- }
- kobject_del() then calls sysfs_remove_dir(), which would
- trigger any user-space daemon that was watching /sysfs,
- and notice the delete event.
+ kobject_del() then calls sysfs_remove_dir(), which would
+ trigger any user-space daemon that was watching /sysfs,
+ and notice the delete event.
Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
The biggest negative of the design is that it potentially disturbs
network daemons and file systems that didn't need to be disturbed.
--- A minor complaint is that resetting the network card causes
+- A minor complaint is that resetting the network card causes
user-space back-to-back ifdown/ifup burps that potentially disturb
network daemons, that didn't need to even know that the pci
card was being rebooted.
--- A more serious concern is that the same reset, for SCSI devices,
+- A more serious concern is that the same reset, for SCSI devices,
causes havoc to mounted file systems. Scripts cannot post-facto
unmount a file system without flushing pending buffers, but this
is impossible, because I/O has already been stopped. Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
from the block layer. It would be very natural to add an EEH
reset into this chain of events.
--- If a SCSI error occurs for the root device, all is lost unless
+- If a SCSI error occurs for the root device, all is lost unless
the sysadmin had the foresight to run /bin, /sbin, /etc, /var
and so on, out of ramdisk/tmpfs.
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
Conclusions
-----------
There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
- Firmware-Assisted Dump
- ------------------------
- July 2011
+July 2011
The goal of firmware-assisted dump is to enable the dump of
a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
Comparing with kdump or other strategies, firmware-assisted
dump offers several strong, practical advantages:
--- Unlike kdump, the system has been reset, and loaded
+- Unlike kdump, the system has been reset, and loaded
with a fresh copy of the kernel. In particular,
PCI and I/O devices have been reinitialized and are
in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+- Once the dump is copied out, the memory that held the dump
is immediately available to the running kernel. And therefore,
unlike kdump, fadump doesn't need a 2nd reboot to get back
the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
and assistance from the Power firmware. The procedure is
as follows:
--- The first kernel registers the sections of memory with the
+- The first kernel registers the sections of memory with the
Power firmware for dump preservation during OS initialization.
These registered sections of memory are reserved by the first
kernel during early boot.
--- When a system crashes, the Power firmware will save
+- When a system crashes, the Power firmware will save
the low memory (boot memory of size larger of 5% of system RAM
or 256MB) of RAM to the previous registered region. It will
also save system registers, and hardware PTE's.
- NOTE: The term 'boot memory' means size of the low memory chunk
+ NOTE:
+ The term 'boot memory' means size of the low memory chunk
that is required for a kernel to boot successfully when
booted with restricted memory. By default, the boot memory
size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
as fadump uses a predefined offset to reserve memory
for boot memory dump preservation in case of a crash.
--- After the low memory (boot memory) area has been saved, the
+- After the low memory (boot memory) area has been saved, the
firmware will reset PCI and other hardware state. It will
*not* clear the RAM. It will then launch the bootloader, as
normal.
--- The freshly booted kernel will notice that there is a new
+- The freshly booted kernel will notice that there is a new
node (ibm,dump-kernel) in the device tree, indicating that
there is crash data available from a previous boot. During
the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
size. This will make sure that the second kernel will not
touch any of the dump memory area.
--- User-space tools will read /proc/vmcore to obtain the contents
+- User-space tools will read /proc/vmcore to obtain the contents
of memory, which holds the previous crashed kernel dump in ELF
format. The userspace tools may copy this info to disk, or
network, nas, san, iscsi, etc. as desired.
--- Once the userspace tool is done saving dump, it will echo
+- Once the userspace tool is done saving dump, it will echo
'1' to /sys/kernel/fadump_release_mem to release the reserved
memory back to general use, except the memory required for
next firmware-assisted dump registration.
- e.g.
+ e.g.::
+
# echo 1 > /sys/kernel/fadump_release_mem
Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
firmware versions.
Implementation details:
-----------------------
+-----------------------
During boot, a check is made to see if firmware supports
this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
With CMA reservation this memory will be available for applications to
use it, while kernel is prevented from using it. With this fadump will
still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
o Memory Reservation during first kernel
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
used for kdump.
How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
1. Set config option CONFIG_FA_DUMP=y and build kernel.
2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
to specify size of the memory to reserve for boot memory dump
preservation.
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
- use 'crashkernel=' to specify size of the memory to reserve
- for boot memory dump preservation.
- 2. If firmware-assisted dump fails to reserve memory then it
- will fallback to existing kdump mechanism if 'crashkernel='
- option is set at kernel cmdline.
- 3. if user wants to capture all of user space memory and ok with
- reserved memory not available to production system, then
- 'fadump=nocma' kernel parameter can be used to fallback to
- old behaviour.
+NOTE:
+ 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+ use 'crashkernel=' to specify size of the memory to reserve
+ for boot memory dump preservation.
+ 2. If firmware-assisted dump fails to reserve memory then it
+ will fallback to existing kdump mechanism if 'crashkernel='
+ option is set at kernel cmdline.
+ 3. if user wants to capture all of user space memory and ok with
+ reserved memory not available to production system, then
+ 'fadump=nocma' kernel parameter can be used to fallback to
+ old behaviour.
Sysfs/debugfs files:
-------------
+--------------------
Firmware-assisted dump feature uses sysfs file system to hold
the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
Here is the list of files under kernel sysfs:
/sys/kernel/fadump_enabled
-
This is used to display the fadump status.
- 0 = fadump is disabled
- 1 = fadump is enabled
+
+ - 0 = fadump is disabled
+ - 1 = fadump is enabled
This interface can be used by kdump init scripts to identify if
fadump is enabled in the kernel and act accordingly.
/sys/kernel/fadump_registered
-
This is used to display the fadump registration status as well
as to control (start/stop) the fadump registration.
- 0 = fadump is not registered.
- 1 = fadump is registered and ready to handle system crash.
+
+ - 0 = fadump is not registered.
+ - 1 = fadump is registered and ready to handle system crash.
To register fadump echo 1 > /sys/kernel/fadump_registered and
echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
easily integrated with kdump service start/stop.
/sys/kernel/fadump_release_mem
-
This file is available only when fadump is active during
second kernel. This is used to release the reserved memory
region that are held for saving crash dump. To release the
- reserved memory echo 1 to it:
+ reserved memory echo 1 to it::
- echo 1 > /sys/kernel/fadump_release_mem
+ echo 1 > /sys/kernel/fadump_release_mem
After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
(Assuming debugfs is mounted on /sys/kernel/debug directory.)
/sys/kernel/debug/powerpc/fadump_region
-
This file shows the reserved memory regions if fadump is
enabled otherwise this file is empty. The output format
- is:
- <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+ is::
+
+ <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
e.g.
- Contents when fadump is registered during first kernel
+ Contents when fadump is registered during first kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
- Contents when fadump is active during second kernel
+ Contents when fadump is active during second kernel::
- # cat /sys/kernel/debug/powerpc/fadump_region
- CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
- HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
- DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
- : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+ # cat /sys/kernel/debug/powerpc/fadump_region
+ CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+ HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+ DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+ : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+ Please refer to Documentation/filesystems/debugfs.txt on
how to mount the debugfs filesystem.
TODO:
-----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
accurate boot memory size that is required for a kernel to
boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
in the scratch area before the ELF core header. The idea of introducing
this structure is to pass some important crash info data to the second
kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
design implementation does not address a possibility of introducing
additional fields (in future) to this structure without affecting
compatibility. Need to come up with the better approach to address this.
+
The possible approaches are:
+
1. Introduce version field for version tracking, bump up the version
whenever a new field is added to the structure in future. The version
field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
2. Reserve the area of predefined size (say PAGE_SIZE) for this
structure and have unused area as reserved (initialized to zero)
for future field additions.
+
The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
This document is based on the original documentation written for phyp
+
assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
- HVCS
- IBM "Hypervisor Virtual Console Server" Installation Guide
- for Linux Kernel 2.6.4+
- Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
- Author(s) : Ryan S. Arnold <rsa@us.ibm.com>
- Date Created: March, 02, 2004
- Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
1. Driver Introduction:
2. System Requirements
@@ -27,8 +30,8 @@ Table of contents:
8. Questions & Answers:
9. Reporting Bugs:
----------------------------------------------------------------------------
1. Driver Introduction:
+=======================
This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system. Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.
----------------------------------------------------------------------------
2. System Requirements:
+=======================
This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server. Directions
for sysfs mounting are outside the scope of this document.
----------------------------------------------------------------------------
3. Build Options:
+=================
The hvcs driver registers itself as a tty driver. The tty layer
dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
built into the kernel. If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.
----------------------------------------------------------------------------
3.1 Built-in:
+-------------
The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
Device Drivers --->
Character devices --->
@@ -77,11 +80,11 @@ driver into the kernel.
Begin the kernel make process.
----------------------------------------------------------------------------
3.2 Module:
+-----------
The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
Device Drivers --->
Character devices --->
@@ -89,11 +92,11 @@ driver as a kernel module.
The make process will build the following kernel modules:
- hvcs.ko
- hvcserver.ko
+ - hvcs.ko
+ - hvcserver.ko
To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
insmod hvcserver.ko
insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.
To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
insmod hvcs.ko hvcs_parm_num_devs=4
@@ -115,31 +118,31 @@ source file before building.
NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
rmmod hvcs.ko
The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
-modprobe hvcs hvcs_parm_num_devs=4
+ modprobe hvcs hvcs_parm_num_devs=4
The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.
The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
-modprobe -r hvcs
+ modprobe -r hvcs
----------------------------------------------------------------------------
4. Installation:
+================
The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver. The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
sys/
|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
|-- *other sysfs base dirs*
For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
Pow5:/sys/class/tty/hvcs0/ # cat dev
254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
will do it automatically.
Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
mknod /dev/hvcs0 c 254 0
mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
persistent. Once created they will exist prior to the driver insmod.
Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
"/dev/hvcs*: No such device".
NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.
----------------------------------------------------------------------------
5. Connection
+=============
Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry. This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device. For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots. Look
in the Q & A section for more on this issue.
----------------------------------------------------------------------------
6. Disconnection
+================
As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
previously read '1'. The write directive is ignored if the vterm_state
read '0' or if any value other than '0' was written to the vterm_state
attribute. The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
All vty-server connections are automatically terminated when the device is
hotplug removed and when the module is removed.
----------------------------------------------------------------------------
7. Configuration
+================
Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
Pow5:/sys/bus/vio/drivers/hvcs # ls
. .. 30000003 30000004 rescan
@@ -344,7 +347,7 @@ completed or was never executed.
Vty-server entries in this directory are a 32 bit partition unique unit
address that is created by firmware. An example vty-server sysfs entry
-looks like the following:
+looks like the following::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
. current_vty devspec name partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
Each entry is provided, by default with a "name" attribute. Reading the
"name" attribute will reveal the device type as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
vty-server
Each entry is also provided, by default, with a "devspec" attribute which
reveals the full device specification when read, as shown in the following
-example:
+example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
/vdevice/vty-server@30000004
Each vty-server sysfs dir is provided with two read-only attributes that
provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time. The entry,
read.
The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
Information on the "vterm_state" attribute was covered earlier on the
chapter entitled "disconnection".
----------------------------------------------------------------------------
8. Questions & Answers:
-===========================================================================
+=======================
+
Q: What are the security concerns involving hvcs?
A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
partition) will experience the previously logged in session.
---------------------------------------------------------------------------
+
Q: How do I multiplex a console that I grab through hvcs so that other
people can see it:
@@ -440,6 +444,7 @@ term type "screen" to others. This means that curses based programs may
not display properly in screen sessions.
---------------------------------------------------------------------------
+
Q: Why are the colors all messed up?
Q: Why are the control characters acting strange or not working?
Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console. This will ensure that the next user gets
their own TERM type set when they login.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, can't open connection: /dev/hvcs*"What is happening?
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
/dev/hvcs* entry.
---------------------------------------------------------------------------
+
Q: When I try to CONNECT kermit to an hvcs device I get:
"Sorry, write access to UUCP lockfile directory denied."
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
does? Maybe you haven't inserted the module (on systems with udev).
---------------------------------------------------------------------------
+
Q: If I already have one Linux partition installed can I use hvcs on said
partition to provide the console for the install of a second Linux
partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
kermit or cu or some other program that doesn't provide terminal emulation.
---------------------------------------------------------------------------
+
Q: Can I connect to more than one partition's console at a time using this
driver?
@@ -512,6 +521,7 @@ A: Yes. Of course this means that there must be more than one vty-server
configured for this partition and each must point to a disconnected vty.
---------------------------------------------------------------------------
+
Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
handle additions of new devices and removals of unused devices.
---------------------------------------------------------------------------
+
Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
after a reboot. What happened?
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
Hint; look at the sysfs "index" attribute for the vty-server.
---------------------------------------------------------------------------
+
Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
device on that partition as the other end of the pipe?
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*. Now you have a tty conduit between two
partitions.
---------------------------------------------------------------------------
+
9. Reporting Bugs:
+==================
The proper channel for reporting bugs is either through the Linux OS
distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+ :maxdepth: 1
+
+ bootwrapper
+ cpu_families
+ cpu_features
+ cxl
+ cxlflash
+ dawr-power9
+ dscr
+ eeh-pci-error-recovery
+ firmware-assisted-dump
+ hvcs
+ isa-versions
+ mpc52xx
+ pci_iov_resource_on_powernv
+ pmu-ebb
+ ptrace
+ qe_firmware
+ syscall64-abi
+ transactional_memory
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
CPU to ISA Version Mapping
==========================
Mapping of some CPU versions to relevant ISA versions.
-========= ====================
+========= ====================================================================
CPU Architecture version
-========= ====================
+========= ====================================================================
Power9 Power ISA v3.0B
Power8 Power ISA v2.07
Power7 Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970 - PowerPC User Instruction Set Architecture Book I v2.01
- PowerPC Virtual Environment Architecture Book II v2.01
- PowerPC Operating Environment Architecture Book III v2.01
- Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
Key Features
@@ -60,9 +59,9 @@ Power5 No
PPC970 No
========== ====
-========== ====================
+========== ====================================
CPU Transactional Memory
-========== ====================
+========== ====================================
Power9 Yes (* see transactional_memory.txt)
Power8 Yes
Power7 No
@@ -73,4 +72,4 @@ Power5++ No
Power5+ No
Power5 No
PPC970 No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
Linux 2.6.x on MPC52xx family
------------------------------
+=============================
For the latest info, go to http://www.246tNt.com/mpc52xx/
To compile/use :
- - U-Boot:
+ - U-Boot::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
=> tftpboot 400000 pRamdisk
=> bootm 200000 400000
- - DBug:
+ - DBug::
+
# <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
if you wish to ).
# make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
DBug> dn -i zImage.initrd.lite5200
-Some remarks :
+Some remarks:
+
- The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
is not supported, and I'm not sure anyone is interesting in working on it
so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
Wei Yang <weiyang@linux.vnet.ibm.com>
+
Benjamin Herrenschmidt <benh@au1.ibm.com>
+
Bjorn Helgaas <bhelgaas@google.com>
+
26 Aug 2014
This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
about considerations on enabling SRIOV on IODA2.
1. Introduction to Partitionable Endpoints
+==========================================
A Partitionable Endpoint (PE) is a way to group the various resources
associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
its own set of PEs, etc.
2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
P8 supports up to 256 Partitionable Endpoints per PHB.
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
sense, but we haven't done it yet.
3. Considerations for SR-IOV on PowerKVM
+========================================
* SR-IOV Background
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
IODA supports 256 PEs, so segmented windows contain 256 segments, so if
total_VFs is less than 256, we have the situation in Figure 1.0, where
segments [total_VFs, 255] of the M64 window may map to some MMIO range on
- other devices:
+ other devices::
0 1 total_VFs - 1
+------+------+- -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
Figure 1.0 Direct map VF(n) BAR space
Our current solution is to allocate 256 segments even if the VF(n) BAR
- space doesn't need that much, as shown in Figure 1.1:
+ space doesn't need that much, as shown in Figure 1.1::
0 1 total_VFs - 1 255
+------+------+- -+------+------+- -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
responds to segments [total_VFs, 255].
4. Implications for the Generic PCI Code
+========================================
The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
PMU Event Based Branches
========================
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
GDB intends to support the following hardware debug features of BookE
processors:
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
following 3 new ptrace requests.
1. PTRACE_PPC_GETHWDEBUGINFO
+============================
Query for GDB to discover the hardware debug features. The main info to
be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
Since we're at it, we added other useful info that the kernel can return to
GDB: this query will return the number of hardware breakpoints, hardware
watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
-struct ppc_debug_info {
+ struct ppc_debug_info {
unit32_t version;
unit32_t num_instruction_bps;
unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
unit32_t data_bp_alignment;
unit32_t sizeof_condition; /* size of the DVC register */
uint64_t features; /* bitmask of the individual flags */
-};
+ };
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
+ #define PPC_DEBUG_FEATURE_INSN_BP_RANGE 0x1
+ #define PPC_DEBUG_FEATURE_INSN_BP_MASK 0x2
+ #define PPC_DEBUG_FEATURE_DATA_BP_RANGE 0x4
+ #define PPC_DEBUG_FEATURE_DATA_BP_MASK 0x8
+ #define PPC_DEBUG_FEATURE_DATA_BP_DAWR 0x10
2. PTRACE_SETHWDEBUG
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
-struct ppc_hw_breakpoint {
+ struct ppc_hw_breakpoint {
uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
-#define PPC_BREAKPOINT_TRIGGER_READ 0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
+ #define PPC_BREAKPOINT_TRIGGER_EXECUTE 0x1
+ #define PPC_BREAKPOINT_TRIGGER_READ 0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE 0x4
uint32_t trigger_type; /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT 0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
-#define PPC_BREAKPOINT_MODE_MASK 0x3
+ #define PPC_BREAKPOINT_MODE_EXACT 0x0
+ #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE 0x1
+ #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE 0x2
+ #define PPC_BREAKPOINT_MODE_MASK 0x3
uint32_t addr_mode; /* address match mode */
-#define PPC_BREAKPOINT_CONDITION_MODE 0x3
-#define PPC_BREAKPOINT_CONDITION_NONE 0x0
-#define PPC_BREAKPOINT_CONDITION_AND 0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR 0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
+ #define PPC_BREAKPOINT_CONDITION_MODE 0x3
+ #define PPC_BREAKPOINT_CONDITION_NONE 0x0
+ #define PPC_BREAKPOINT_CONDITION_AND 0x1
+ #define PPC_BREAKPOINT_CONDITION_EXACT 0x1 /* different name for the same thing as above */
+ #define PPC_BREAKPOINT_CONDITION_OR 0x2
+ #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+ #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000 /* byte enable bits */
+ #define PPC_BREAKPOINT_CONDITION_BE(n) (1<<((n)+16))
uint32_t condition_mode; /* break/watchpoint condition flags */
uint64_t addr;
uint64_t addr2;
uint64_t condition_value;
-};
+ };
A request specifies one event, not necessarily just one register to be set.
For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
Some examples of using the structure to:
-- set a breakpoint in the first breakpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
- p.addr = (uint64_t) address;
- p.addr2 = 0;
- p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
- p.version = PPC_DEBUG_CURRENT_VERSION;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
- p.version = 1;
- p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
- p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
- or
- p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
-
- p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
- p.addr = (uint64_t) begin_range;
- /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
- * addr2 - addr <= 8 Bytes.
- */
- p.addr2 = (uint64_t) end_range;
- p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_READ;
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+ p.addr = (uint64_t) address;
+ p.addr2 = 0;
+ p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+ p.version = PPC_DEBUG_CURRENT_VERSION;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+ p.version = 1;
+ p.trigger_type = PPC_BREAKPOINT_TRIGGER_RW;
+ p.addr_mode = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+ or
+ p.addr_mode = PPC_BREAKPOINT_MODE_EXACT;
+
+ p.condition_mode = PPC_BREAKPOINT_CONDITION_NONE;
+ p.addr = (uint64_t) begin_range;
+ /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+ * addr2 - addr <= 8 Bytes.
+ */
+ p.addr2 = (uint64_t) end_range;
+ p.condition_value = 0;
3. PTRACE_DELHWDEBUG
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
- Freescale QUICC Engine Firmware Uploading
- -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
(c) 2007 Timur Tabi <timur at freescale.com>,
Freescale Semiconductor
-Table of Contents
-=================
+.. Table of Contents
- I - Software License for Firmware
+ I - Software License for Firmware
- II - Microcode Availability
+ II - Microcode Availability
- III - Description and Terminology
+ III - Description and Terminology
- IV - Microcode Programming Details
+ IV - Microcode Programming Details
- V - Firmware Structure Layout
+ V - Firmware Structure Layout
- VI - Sample Code for Creating Firmware Files
+ VI - Sample Code for Creating Firmware Files
Revision Information
====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com. For other firmware files, please contact
your Freescale representative or your operating system vendor.
III - Description and Terminology
-================================
+=================================
In this document, the term 'microcode' refers to the sequence of 32-bit
integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated. This data
structure signals the microcode which of these virtual traps is active.
This structure contains 6 words that the application should copy to some
-specific been defined. This table describes the structure.
+specific been defined. This table describes the structure::
---------------------------------------------------------------
| Offset in | | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
This is a double word bit array (64 bits) that defines special functionality
which has an impact on the software drivers. Each bit has its own impact
and has special instructions for the s/w associated with it. This structure is
-described in this table:
+described in this table::
-----------------------------------------------------------------------
| Bit # | Name | Description |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
'major' and 'minor' fields are the major and minor revision numbers,
respectively, of the SOC.
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
soc.model = 8323
soc.major = 1
soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
'reserved'.
After the last microcode is a 32-bit CRC. It can be calculated using
-this algorithm:
+this algorithm::
-u32 crc32(const u8 *p, unsigned int len)
-{
+ u32 crc32(const u8 *p, unsigned int len)
+ {
unsigned int i;
u32 crc = 0;
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
}
return crc;
-}
+ }
VI - Sample Code for Creating Firmware Files
============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
syscall
=======
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
specification C function calling sequence, including register preservation
rules, with the following differences.
-[*] Some syscalls (typically low-level management functions) may have
- different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+ different calling sequences (e.g., rt_sigreturn).
Parameters and return value
---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
Register preservation rules match the ELF ABI calling sequence with the
following differences:
-r0: Volatile. (System call number.)
-r3: Volatile. (Parameter 1, and return value.)
-r4-r8: Volatile. (Parameters 2-6.)
-cr0: Volatile (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr: Nonvolatile.
+=========== ============= ========================================
+r0 Volatile (System call number.)
+r3 Volatile (Parameter 1, and return value.)
+r4-r8 Volatile (Parameters 2-6.)
+cr0 Volatile (cr0.SO is the return error condition)
+cr1, cr5-7 Nonvolatile
+lr Nonvolatile
+=========== ============= ========================================
All floating point and vector data registers as well as control and status
registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
Register preservation rules
---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0 Volatile
+cr1, cr5-7 Volatile
+lr Volatile
+=========== ========
Invocation
----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
Transactional Memory support
============================
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
guaranteed to either complete atomically or roll back and undo any partial
changes.
-A simple transaction looks like this:
+A simple transaction looks like this::
-begin_move_money:
- tbegin
- beq abort_handler
+ begin_move_money:
+ tbegin
+ beq abort_handler
- ld r4, SAVINGS_ACCT(r3)
- ld r5, CURRENT_ACCT(r3)
- subi r5, r5, 1
- addi r4, r4, 1
- std r4, SAVINGS_ACCT(r3)
- std r5, CURRENT_ACCT(r3)
+ ld r4, SAVINGS_ACCT(r3)
+ ld r5, CURRENT_ACCT(r3)
+ subi r5, r5, 1
+ addi r4, r4, 1
+ std r4, SAVINGS_ACCT(r3)
+ std r5, CURRENT_ACCT(r3)
- tend
+ tend
- b continue
+ b continue
-abort_handler:
- ... test for odd failures ...
+ abort_handler:
+ ... test for odd failures ...
- /* Retry the transaction if it failed because it conflicted with
- * someone else: */
- b begin_move_money
+ /* Retry the transaction if it failed because it conflicted with
+ * someone else: */
+ b begin_move_money
The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
from the second ucontext. This will be necessary for crash handlers to
determine, for example, the address of the instruction causing the SIGSEGV.
-Example signal handler:
+Example signal handler::
void crash_handler(int sig, siginfo_t *si, void *uc)
{
@@ -133,9 +134,9 @@ Example signal handler:
if (ucp_link) {
u64 msr = ucp->uc_mcontext.regs->msr;
/* May have transactional ucontext! */
-#ifndef __powerpc64__
+ #ifndef __powerpc64__
msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+ #endif
if (MSR_TM_ACTIVE(msr)) {
/* Yes, we crashed during a transaction. Oops. */
fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
These are defined in <asm/reg.h>, and distinguish different reasons why the
kernel aborted a transaction:
+ ====================== ================================
TM_CAUSE_RESCHED Thread was rescheduled.
TM_CAUSE_TLBI Software TLB invalid.
TM_CAUSE_FAC_UNAV FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
TM_CAUSE_MISC Currently unused.
TM_CAUSE_ALIGNMENT Alignment fault.
TM_CAUSE_EMULATE Emulation that touched memory.
+ ====================== ================================
These can be checked by the user program's abort handler as TEXASR[0:7]. If
bit 7 is set, it indicates that the error is consider persistent. For example
@@ -203,7 +206,7 @@ POWER9
======
TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F: arch/powerpc/platforms/powernv/pci-cxl.c
F: drivers/misc/cxl/
F: include/misc/cxl*
F: include/uapi/misc/cxl.h
-F: Documentation/powerpc/cxl.txt
+F: Documentation/powerpc/cxl.rst
F: Documentation/ABI/testing/sysfs-class-cxl
CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L: linux-scsi@vger.kernel.org
S: Supported
F: drivers/scsi/cxlflash/
F: include/uapi/scsi/cxlflash_ioctl.h
-F: Documentation/powerpc/cxlflash.txt
+F: Documentation/powerpc/cxlflash.rst
CYBERPRO FB DRIVER
M: Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F: Documentation/PCI/pci-error-recovery.rst
F: drivers/pci/pcie/aer.c
F: drivers/pci/pcie/dpc.c
F: drivers/pci/pcie/err.c
-F: Documentation/powerpc/eeh-pci-error-recovery.txt
+F: Documentation/powerpc/eeh-pci-error-recovery.rst
F: arch/powerpc/kernel/eeh*.c
F: arch/powerpc/platforms/*/eeh*.c
F: arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
*
* Call convention:
*
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
*
* For hypercalls, the register convention is as follows:
* r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
/*
* Upload a microcode to the I-RAM at a specific address.
*
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
* uploading.
*
* Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
* using the 2.6 Linux kernel kref construct.
*
* For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
*/
#include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
/* Structure that defines QE firmware binary files.
*
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
* fields.
*/
struct qe_firmware {
--
2.21.0
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 04/26] docs: ubifs-authentication.md: convert to ReST
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (6 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc, Rob Herring
The documentation standard is ReST and not markdown.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
---
...entication.md => ubifs-authentication.rst} | 70 ++++++++++++-------
1 file changed, 44 insertions(+), 26 deletions(-)
rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.rst
similarity index 95%
rename from Documentation/filesystems/ubifs-authentication.md
rename to Documentation/filesystems/ubifs-authentication.rst
index 23e698167141..6a9584f6ff46 100644
--- a/Documentation/filesystems/ubifs-authentication.md
+++ b/Documentation/filesystems/ubifs-authentication.rst
@@ -1,8 +1,11 @@
-% UBIFS Authentication
-% sigma star gmbh
-% 2018
+:orphan:
-# Introduction
+.. UBIFS Authentication
+.. sigma star gmbh
+.. 2018
+
+Introduction
+============
UBIFS utilizes the fscrypt framework to provide confidentiality for file
contents and file names. This prevents attacks where an attacker is able to
@@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also
be possible to use UBIFS authentication without using encryption.
-## MTD, UBI & UBIFS
+MTD, UBI & UBIFS
+----------------
On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
interface to access raw flash devices. One of the more prominent subsystems that
@@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
leveling and some flash specifics are left to UBI, while UBIFS focuses on
scalability, performance and recoverability.
-
+::
+------------+ +*******+ +-----------+ +-----+
| | * UBIFS * | UBI-BLOCK | | ... |
@@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in
[UBIFS-WP].
-### UBIFS Index & Tree Node Cache
+UBIFS Index & Tree Node Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
@@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes
marked as dirty are written to the flash to update the persisted index.
-### Journal
+Journal
+~~~~~~~
To avoid wearing out the flash, the index is only persisted (*commited*) when
-certain conditions are met (eg. `fsync(2)`). The journal is used to record
+certain conditions are met (eg. ``fsync(2)``). The journal is used to record
any changes (in form of inode nodes, data nodes etc.) between commits
of the index. During mount, the journal is read from the flash and replayed
onto the TNC (which will be created on-demand from the on-flash index).
UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
amount of log area LEBs is configured on filesystem creation (using
-`mkfs.ubifs`) and stored in the superblock node. The log area contains only
+``mkfs.ubifs``) and stored in the superblock node. The log area contains only
two types of nodes: *reference nodes* and *commit start nodes*. A commit start
node is written whenever an index commit is performed. Reference nodes are
written on every journal update. Each reference node points to the position of
@@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt
because of a power cut. If the recovery fails, UBIFS will not mount. An error
for every other LEB will directly cause UBIFS to fail the mount operation.
+::
| ---- LOG AREA ---- | ---------- MAIN AREA ------------ |
@@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation.
containing their buds
-### LEB Property Tree/Table
+LEB Property Tree/Table
+~~~~~~~~~~~~~~~~~~~~~~~
The LEB property tree is used to store per-LEB information. This includes the
-LEB type and amount of free and *dirty* (old, obsolete content) space [1] on
+LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on
the LEB. The type is important, because UBIFS never mixes index nodes with data
nodes on a single LEB and thus each LEB has a specific purpose. This again is
useful for free space calculations. See [UBIFS-WP] for more details.
@@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every
commit. Thus, saving the LPT is an atomic operation.
-[1] Since LEBs can only be appended and never overwritten, there is a
-difference between free space ie. the remaining space left on the LEB to be
-written to without erasing it and previously written content that is obsolete
-but can't be overwritten without erasing the full LEB.
+.. [1] Since LEBs can only be appended and never overwritten, there is a
+ difference between free space ie. the remaining space left on the LEB to be
+ written to without erasing it and previously written content that is obsolete
+ but can't be overwritten without erasing the full LEB.
-# UBIFS Authentication
+UBIFS Authentication
+====================
This chapter introduces UBIFS authentication which enables UBIFS to verify
the authenticity and integrity of metadata and file contents stored on flash.
-## Threat Model
+Threat Model
+------------
UBIFS authentication enables detection of offline data modification. While it
does not prevent it, it enables (trusted) code to check the integrity and
@@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to
ensure that only trusted code is executed on a device.
-## Authentication
+Authentication
+--------------
To be able to fully trust data read from flash, all UBIFS data structures
stored on flash are authenticated. That is:
@@ -236,7 +247,8 @@ stored on flash are authenticated. That is:
- The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
-### Index Authentication
+Index Authentication
+~~~~~~~~~~~~~~~~~~~~
Through UBIFS' concept of a wandering tree, it already takes care of only
updating and persisting changed parts from leaf node up to the root node
@@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces
the storage overhead which is precious for users of UBIFS (ie. embedded
devices).
+::
+---------------+
| Master Node |
@@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted
atomically together with its respective node.
-### Journal Authentication
+Journal Authentication
+~~~~~~~~~~~~~~~~~~~~~~
The journal is authenticated too. Since the journal is continuously written
it is necessary to also add authentication information frequently to the
@@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last
authentication node. The tail of the journal which may not have a authentication
node cannot be authenticated and is skipped during journal replay.
-We get this picture for journal authentication:
+We get this picture for journal authentication::
,,,,,,,,
,......,...........................................
@@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only
modified on feature flag or similar changes, but never on file changes.
-### LPT Authentication
+LPT Authentication
+~~~~~~~~~~~~~~~~~~
The location of the LPT root node on the flash is stored in the UBIFS master
node. Since the LPT is written and read atomically on every commit, there is
@@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the
LTP hash stored there with the hash computed from the read on-flash LPT.
-## Key Management
+Key Management
+--------------
For simplicity, UBIFS authentication uses a single key to compute the HMACs
of superblock, master, commit start and reference nodes. This key has to be
@@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2
[FSCRYPT-POLICY2].
-# Future Extensions
+Future Extensions
+=================
In certain cases where a vendor wants to provide an authenticated filesystem
image to customers, it should be possible to do so without sharing the secret
@@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key
will then have to be provided beforehand in the normal way.
-# References
+References
+==========
[CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 05/26] docs: writing-schema.md: convert from markdown to ReST
2019-07-26 12:51 ` Mauro Carvalho Chehab
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Rob Herring, Mark Rutland, devicetree,
Rob Herring
The documentation standard is ReST and not markdown.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
---
.../{writing-schema.md => writing-schema.rst} | 137 ++++++++++--------
1 file changed, 80 insertions(+), 57 deletions(-)
rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.rst
similarity index 48%
rename from Documentation/devicetree/writing-schema.md
rename to Documentation/devicetree/writing-schema.rst
index dc032db36262..8f71d1e2ac52 100644
--- a/Documentation/devicetree/writing-schema.md
+++ b/Documentation/devicetree/writing-schema.rst
@@ -1,65 +1,81 @@
-# Writing DeviceTree Bindings in json-schema
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
Devicetree bindings are written using json-schema vocabulary. Schema files are
written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
considered more human readable and has some advantages such as allowing
comments (Prefixed with '#').
-## Schema Contents
+Schema Contents
+---------------
Each schema doc is a structured json-schema which is defined by a set of
top-level properties. Generally, there is one binding defined per file. The
top-level json-schema properties used are:
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
- A property can also define a child DT node with child properties defined
+$id
+ A json-schema unique identifier string. The string must be a valid
+ URI typically containing the binding's filename and path. For DT schema, it must
+ begin with "http://devicetree.org/schemas/". The URL is used in constructing
+ references to other files specified in schema "$ref" properties. A $ref values
+ with a leading '/' will have the hostname prepended. A $ref value a relative
+ path or filename only will be prepended with the hostname and path components
+ of the current schema file's '$id' value. A URL is used even for local files,
+ but there may not actually be files present at those locations.
+
+$schema
+ Indicates the meta-schema the schema file adheres to.
+
+title
+ A one line description on the contents of the binding schema.
+
+maintainers
+ A DT specific property. Contains a list of email address(es)
+ for maintainers of this binding.
+
+description
+ Optional. A multi-line text block containing any detailed
+ information about this binding. It should contain things such as what the block
+ or device does, standards the device conforms to, and links to datasheets for
+ more information.
+
+select
+ Optional. A json-schema used to match nodes for applying the
+ schema. By default without 'select', nodes are matched against their possible
+ compatible string values or node name. Most bindings should not need select.
+
+ allOf
+ Optional. A list of other schemas to include. This is used to
+ include other schemas the binding conforms to. This may be schemas for a
+ particular class of devices such as I2C or SPI controllers.
+
+ properties
+ A set of sub-schema defining all the DT properties for the
+ binding. The exact schema syntax depends on whether properties are known,
+ common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
under it.
- For more details on properties sections, see 'Property Schema' section.
+For more details on properties sections, see 'Property Schema' section.
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
+patternProperties
+ Optional. Similar to 'properties', but names are regex.
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
+required
+ A list of DT properties from the 'properties' section that
+ must always be present.
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+examples
+ Optional. A list of one or more DTS hunks implementing the
+ binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
Unless noted otherwise, all properties are required.
-## Property Schema
+Property Schema
+---------------
The 'properties' section of the schema contains all the DT properties for a
binding. Each property contains a set of constraints using json-schema
@@ -89,42 +105,49 @@ The YAML Devicetree format also makes all string values an array and scalar
values a matrix (in order to define groupings) even when only a single value
is present. Single entries in schemas are fixed up to match this encoding.
-## Testing
+Testing
+-------
-### Dependencies
+Dependencies
+~~~~~~~~~~~~
The DT schema project must be installed in order to validate the DT schema
binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
+project can be installed with pip::
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
+ pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
dtc must also be built with YAML output support enabled. This requires that
libyaml and its headers be installed on the host system.
-### Running checks
+Running checks
+~~~~~~~~~~~~~~
The DT schema binding documents must be validated using the meta-schema (the
schema for the schema) to ensure they are both valid json-schema and valid
binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
+``dt_binding_check`` target::
-`make dt_binding_check`
+ make dt_binding_check
-In order to perform validation of DT source files, use the `dtbs_check` target:
+In order to perform validation of DT source files, use the `dtbs_check` target::
-`make dtbs_check`
+ make dtbs_check
This will first run the `dt_binding_check` which generates the processed schema.
It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
+``DT_SCHEMA_FILES`` variable to a specific schema file.
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
+::
+ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
-## json-schema Resources
-[JSON-Schema Specifications](http://json-schema.org/)
+json-schema Resources
+---------------------
-[Using JSON Schema Book](http://usingjsonschema.com/)
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 05/26] docs: writing-schema.md: convert from markdown to ReST
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Rob Herring, Mark Rutland, devicetree,
Rob Herring
The documentation standard is ReST and not markdown.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
---
.../{writing-schema.md => writing-schema.rst} | 137 ++++++++++--------
1 file changed, 80 insertions(+), 57 deletions(-)
rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.rst
similarity index 48%
rename from Documentation/devicetree/writing-schema.md
rename to Documentation/devicetree/writing-schema.rst
index dc032db36262..8f71d1e2ac52 100644
--- a/Documentation/devicetree/writing-schema.md
+++ b/Documentation/devicetree/writing-schema.rst
@@ -1,65 +1,81 @@
-# Writing DeviceTree Bindings in json-schema
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
Devicetree bindings are written using json-schema vocabulary. Schema files are
written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
considered more human readable and has some advantages such as allowing
comments (Prefixed with '#').
-## Schema Contents
+Schema Contents
+---------------
Each schema doc is a structured json-schema which is defined by a set of
top-level properties. Generally, there is one binding defined per file. The
top-level json-schema properties used are:
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
- A property can also define a child DT node with child properties defined
+$id
+ A json-schema unique identifier string. The string must be a valid
+ URI typically containing the binding's filename and path. For DT schema, it must
+ begin with "http://devicetree.org/schemas/". The URL is used in constructing
+ references to other files specified in schema "$ref" properties. A $ref values
+ with a leading '/' will have the hostname prepended. A $ref value a relative
+ path or filename only will be prepended with the hostname and path components
+ of the current schema file's '$id' value. A URL is used even for local files,
+ but there may not actually be files present at those locations.
+
+$schema
+ Indicates the meta-schema the schema file adheres to.
+
+title
+ A one line description on the contents of the binding schema.
+
+maintainers
+ A DT specific property. Contains a list of email address(es)
+ for maintainers of this binding.
+
+description
+ Optional. A multi-line text block containing any detailed
+ information about this binding. It should contain things such as what the block
+ or device does, standards the device conforms to, and links to datasheets for
+ more information.
+
+select
+ Optional. A json-schema used to match nodes for applying the
+ schema. By default without 'select', nodes are matched against their possible
+ compatible string values or node name. Most bindings should not need select.
+
+ allOf
+ Optional. A list of other schemas to include. This is used to
+ include other schemas the binding conforms to. This may be schemas for a
+ particular class of devices such as I2C or SPI controllers.
+
+ properties
+ A set of sub-schema defining all the DT properties for the
+ binding. The exact schema syntax depends on whether properties are known,
+ common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
under it.
- For more details on properties sections, see 'Property Schema' section.
+For more details on properties sections, see 'Property Schema' section.
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
+patternProperties
+ Optional. Similar to 'properties', but names are regex.
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
+required
+ A list of DT properties from the 'properties' section that
+ must always be present.
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+examples
+ Optional. A list of one or more DTS hunks implementing the
+ binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
Unless noted otherwise, all properties are required.
-## Property Schema
+Property Schema
+---------------
The 'properties' section of the schema contains all the DT properties for a
binding. Each property contains a set of constraints using json-schema
@@ -89,42 +105,49 @@ The YAML Devicetree format also makes all string values an array and scalar
values a matrix (in order to define groupings) even when only a single value
is present. Single entries in schemas are fixed up to match this encoding.
-## Testing
+Testing
+-------
-### Dependencies
+Dependencies
+~~~~~~~~~~~~
The DT schema project must be installed in order to validate the DT schema
binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
+project can be installed with pip::
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
+ pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
dtc must also be built with YAML output support enabled. This requires that
libyaml and its headers be installed on the host system.
-### Running checks
+Running checks
+~~~~~~~~~~~~~~
The DT schema binding documents must be validated using the meta-schema (the
schema for the schema) to ensure they are both valid json-schema and valid
binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
+``dt_binding_check`` target::
-`make dt_binding_check`
+ make dt_binding_check
-In order to perform validation of DT source files, use the `dtbs_check` target:
+In order to perform validation of DT source files, use the `dtbs_check` target::
-`make dtbs_check`
+ make dtbs_check
This will first run the `dt_binding_check` which generates the processed schema.
It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
+``DT_SCHEMA_FILES`` variable to a specific schema file.
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
+::
+ make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
-## json-schema Resources
-[JSON-Schema Specifications](http://json-schema.org/)
+json-schema Resources
+---------------------
-[Using JSON Schema Book](http://usingjsonschema.com/)
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 06/26] docs: i2c: convert to ReST and add to driver-api bookset
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (8 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Peter Rosin, Rob Herring, Mark Rutland,
Jonathan Corbet, Jean Delvare, Guenter Roeck, Andreas Werner,
Wolfram Sang, Rudolf Marek, Seth Heasley, Neil Horman,
Vadim Pasternak, Michael Shych, Ajay Gupta, Peter Korsgaard,
Andrew Lunn, Jim Cromie, Mark Brown, Jonathan Cameron,
Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler,
Alessandro Zummo, Alexandre Belloni, linux-i2c, devicetree,
linux-doc, linux-hwmon, linux-spi, linux-iio, linux-rtc,
Jonathan Cameron
Convert each file at I2C subsystem, renaming them to .rst and
adding to the driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Wolfram Sang <wsa@the-dreams.de>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
.../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +-
Documentation/driver-api/ipmb.rst | 2 +-
Documentation/hwmon/adm1021.rst | 2 +-
Documentation/hwmon/adm1275.rst | 2 +-
Documentation/hwmon/hih6130.rst | 2 +-
Documentation/hwmon/ibm-cffps.rst | 2 +-
Documentation/hwmon/lm25066.rst | 2 +-
Documentation/hwmon/max16064.rst | 2 +-
Documentation/hwmon/max16065.rst | 2 +-
Documentation/hwmon/max20751.rst | 2 +-
Documentation/hwmon/max34440.rst | 2 +-
Documentation/hwmon/max6650.rst | 2 +-
Documentation/hwmon/max8688.rst | 2 +-
Documentation/hwmon/menf21bmc.rst | 2 +-
Documentation/hwmon/pcf8591.rst | 2 +-
Documentation/hwmon/sht3x.rst | 2 +-
Documentation/hwmon/shtc1.rst | 2 +-
Documentation/hwmon/tmp103.rst | 2 +-
Documentation/hwmon/tps40422.rst | 2 +-
Documentation/hwmon/ucd9000.rst | 2 +-
Documentation/hwmon/ucd9200.rst | 2 +-
Documentation/hwmon/via686a.rst | 2 +-
Documentation/hwmon/zl6100.rst | 2 +-
.../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +-
.../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 +
.../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +++---
.../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} | 14 +-
.../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +-
.../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +-
.../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 +
.../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +--
.../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +-
.../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 +
.../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +--
.../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +-
.../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +-
...2c-parport-light => i2c-parport-light.rst} | 8 +-
.../busses/{i2c-parport => i2c-parport.rst} | 164 +++++++-------
.../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +-
.../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +-
.../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +-
.../i2c/busses/{i2c-sis630 => i2c-sis630.rst} | 39 ++--
.../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 ++-
.../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +-
.../i2c/busses/{i2c-via => i2c-via.rst} | 28 ++-
.../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +-
Documentation/i2c/busses/index.rst | 33 +++
.../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +-
.../i2c/{dev-interface => dev-interface.rst} | 94 ++++----
...-considerations => dma-considerations.rst} | 0
.../i2c/{fault-codes => fault-codes.rst} | 5 +-
.../i2c/{functionality => functionality.rst} | 22 +-
...ult-injection => gpio-fault-injection.rst} | 12 +-
.../i2c/{i2c-protocol => i2c-protocol.rst} | 28 ++-
Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +-
.../i2c/{i2c-topology => i2c-topology.rst} | 68 +++---
Documentation/i2c/index.rst | 37 ++++
...ting-devices => instantiating-devices.rst} | 45 ++--
.../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +--
...e-parameters => old-module-parameters.rst} | 27 ++-
...eprom-backend => slave-eeprom-backend.rst} | 4 +-
.../{slave-interface => slave-interface.rst} | 33 +--
.../{smbus-protocol => smbus-protocol.rst} | 86 +++++---
Documentation/i2c/{summary => summary.rst} | 6 +-
...en-bit-addresses => ten-bit-addresses.rst} | 5 +
...pgrading-clients => upgrading-clients.rst} | 204 +++++++++---------
.../{writing-clients => writing-clients.rst} | 94 ++++----
Documentation/index.rst | 1 +
Documentation/spi/spi-sc18is602 | 2 +-
MAINTAINERS | 48 ++---
drivers/hwmon/atxp1.c | 2 +-
drivers/hwmon/smm665.c | 2 +-
drivers/i2c/Kconfig | 4 +-
drivers/i2c/busses/Kconfig | 2 +-
drivers/i2c/busses/i2c-i801.c | 2 +-
drivers/i2c/busses/i2c-taos-evm.c | 2 +-
drivers/i2c/i2c-core-base.c | 4 +-
drivers/iio/dummy/iio_simple_dummy.c | 2 +-
drivers/rtc/rtc-ds1374.c | 2 +-
include/linux/i2c.h | 2 +-
80 files changed, 930 insertions(+), 624 deletions(-)
rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
create mode 100644 Documentation/i2c/busses/index.rst
rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
rename Documentation/i2c/{functionality => functionality.rst} (91%)
rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
create mode 100644 Documentation/i2c/index.rst
rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
rename Documentation/i2c/{summary => summary.rst} (96%)
rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
index 2907dab56298..8b444b94e92f 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
@@ -42,7 +42,7 @@ Optional properties:
This means that no unrelated I2C transactions are allowed on the parent I2C
adapter for the complete multiplexed I2C transaction.
The properties of mux-locked and parent-locked multiplexers are discussed
- in more detail in Documentation/i2c/i2c-topology.
+ in more detail in Documentation/i2c/i2c-topology.rst.
For each i2c child node, an I2C child bus will be created. They will
be numbered based on their order in the device tree.
diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst
index 7e2265144157..3ec3baed84c4 100644
--- a/Documentation/driver-api/ipmb.rst
+++ b/Documentation/driver-api/ipmb.rst
@@ -83,7 +83,7 @@ Instantiate the device
----------------------
After loading the driver, you can instantiate the device as
-described in 'Documentation/i2c/instantiating-devices'.
+described in 'Documentation/i2c/instantiating-devices.rst'.
If you have multiple BMCs, each connected to your Satellite MC via
a different I2C bus, you can instantiate a device for each of
those BMCs.
diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst
index 6cbb0f75fe00..116fb2019956 100644
--- a/Documentation/hwmon/adm1021.rst
+++ b/Documentation/hwmon/adm1021.rst
@@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
If nothing happens when loading the adm1021 module, and you are certain
that your specific Xeon processor model includes compatible sensors, you
will have to explicitly instantiate the sensor chips from user-space. See
-method 4 in Documentation/i2c/instantiating-devices. Possible slave
+method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
only temp2 will be correct and temp1 will have to be ignored.
diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
index 9a1913e5b4d9..49966ed70ec6 100644
--- a/Documentation/hwmon/adm1275.rst
+++ b/Documentation/hwmon/adm1275.rst
@@ -75,7 +75,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
The ADM1075, unlike many other PMBus devices, does not support internal voltage
diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst
index 649bd4be4fc2..e95d373eb693 100644
--- a/Documentation/hwmon/hih6130.rst
+++ b/Documentation/hwmon/hih6130.rst
@@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
can be used in the board setup code.
-Please see Documentation/i2c/instantiating-devices for details on how to
+Please see Documentation/i2c/instantiating-devices.rst for details on how to
instantiate I2C devices.
sysfs-Interface
diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst
index 52e74e39463a..ef8f3f806968 100644
--- a/Documentation/hwmon/ibm-cffps.rst
+++ b/Documentation/hwmon/ibm-cffps.rst
@@ -17,7 +17,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries
diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
index da15e3094c8c..30e6e77fb3c8 100644
--- a/Documentation/hwmon/lm25066.rst
+++ b/Documentation/hwmon/lm25066.rst
@@ -76,7 +76,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst
index 6d5e9538991f..c06249292557 100644
--- a/Documentation/hwmon/max16064.rst
+++ b/Documentation/hwmon/max16064.rst
@@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst
index fa5c852a178c..45f69f334f25 100644
--- a/Documentation/hwmon/max16065.rst
+++ b/Documentation/hwmon/max16065.rst
@@ -79,7 +79,7 @@ Usage Notes
This driver does not probe for devices, since there is no register which
can be safely used to identify the chip. You will have to instantiate
-the devices explicitly. Please see Documentation/i2c/instantiating-devices for
+the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
WARNING: Do not access chip registers using the i2cdump command, and do not use
diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
index aa4469be6674..fe701e07eaf5 100644
--- a/Documentation/hwmon/max20751.rst
+++ b/Documentation/hwmon/max20751.rst
@@ -30,7 +30,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
index 939138e12b02..5744df100a5d 100644
--- a/Documentation/hwmon/max34440.rst
+++ b/Documentation/hwmon/max34440.rst
@@ -83,7 +83,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
For MAX34446, the value of the currX_crit attribute determines if current or
diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst
index 253482add082..7952b6ecaa2d 100644
--- a/Documentation/hwmon/max6650.rst
+++ b/Documentation/hwmon/max6650.rst
@@ -55,7 +55,7 @@ Usage notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
Module parameters
diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst
index 009487759c61..71e7f2cbe2e2 100644
--- a/Documentation/hwmon/max8688.rst
+++ b/Documentation/hwmon/max8688.rst
@@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst
index 1f0c6b2235ab..978691d5956d 100644
--- a/Documentation/hwmon/menf21bmc.rst
+++ b/Documentation/hwmon/menf21bmc.rst
@@ -28,7 +28,7 @@ Usage Notes
This driver is part of the MFD driver named "menf21bmc" and does
not auto-detect devices.
You will have to instantiate the MFD driver explicitly.
-Please see Documentation/i2c/instantiating-devices for
+Please see Documentation/i2c/instantiating-devices.rst for
details.
Sysfs entries
diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst
index e98bd542a441..5c4e85f53177 100644
--- a/Documentation/hwmon/pcf8591.rst
+++ b/Documentation/hwmon/pcf8591.rst
@@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
The PCF8591 is plainly impossible to detect! Thus the driver won't even
try. You have to explicitly instantiate the device at the relevant
address (in the interval [0x48..0x4f]) either through platform data, or
-using the sysfs interface. See Documentation/i2c/instantiating-devices
+using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
for details.
Directories are being created for each instantiated PCF8591:
diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst
index 978a7117e4b2..95a850d5b2c1 100644
--- a/Documentation/hwmon/sht3x.rst
+++ b/Documentation/hwmon/sht3x.rst
@@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
The device communicates with the I2C protocol. Sensors can have the I2C
addresses 0x44 or 0x45, depending on the wiring. See
-Documentation/i2c/instantiating-devices for methods to instantiate the device.
+Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
There are two options configurable by means of sht3x_platform_data:
diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
index aa116332ba26..70c1192bbd8c 100644
--- a/Documentation/hwmon/shtc1.rst
+++ b/Documentation/hwmon/shtc1.rst
@@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1
chip, which has the same electrical interface.
The device communicates with the I2C protocol. All sensors are set to I2C
-address 0x70. See Documentation/i2c/instantiating-devices for methods to
+address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
instantiate the device.
There are two options configurable by means of shtc1_platform_data:
diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
index 15d25806d585..205de6148fcb 100644
--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
Documentation/hwmon/sysfs-interface.rst under Temperatures).
Please refer how to instantiate this driver:
-Documentation/i2c/instantiating-devices
+Documentation/i2c/instantiating-devices.rst
diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
index b691e30479dd..8fe3e1c3572e 100644
--- a/Documentation/hwmon/tps40422.rst
+++ b/Documentation/hwmon/tps40422.rst
@@ -28,7 +28,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst
index ebc4f2b3bfea..746f21fcb48c 100644
--- a/Documentation/hwmon/ucd9000.rst
+++ b/Documentation/hwmon/ucd9000.rst
@@ -64,7 +64,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst
index b819dfd75f71..4f0e7c3ca6f4 100644
--- a/Documentation/hwmon/ucd9200.rst
+++ b/Documentation/hwmon/ucd9200.rst
@@ -40,7 +40,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst
index a343c35df740..7ab9ddebcf79 100644
--- a/Documentation/hwmon/via686a.rst
+++ b/Documentation/hwmon/via686a.rst
@@ -40,7 +40,7 @@ all as a 686A.
The Via 686a southbridge has integrated hardware monitor functionality.
It also has an I2C bus, but this driver only supports the hardware monitor.
-For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
+For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
The Via 686a implements three temperature sensors, two fan rotation speed
sensors, five voltage sensors and alarms.
diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst
index 41513bb7fe51..968aff10ce0a 100644
--- a/Documentation/hwmon/zl6100.rst
+++ b/Documentation/hwmon/zl6100.rst
@@ -121,7 +121,7 @@ Usage Notes
-----------
This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.
.. warning::
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst
similarity index 82%
rename from Documentation/i2c/busses/i2c-ali1535
rename to Documentation/i2c/busses/i2c-ali1535.rst
index 5d46342e486a..6941064730dc 100644
--- a/Documentation/i2c/busses/i2c-ali1535
+++ b/Documentation/i2c/busses/i2c-ali1535.rst
@@ -1,16 +1,19 @@
+=========================
Kernel driver i2c-ali1535
+=========================
Supported adapters:
* Acer Labs, Inc. ALI 1535 (south bridge)
+
Datasheet: Now under NDA
http://www.ali.com.tw/
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Dan Eaton <dan.eaton@rocketlogix.com>,
- Stephen Rousset<stephen.rousset@rocketlogix.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Dan Eaton <dan.eaton@rocketlogix.com>,
+ - Stephen Rousset<stephen.rousset@rocketlogix.com>
Description
-----------
diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst
similarity index 93%
rename from Documentation/i2c/busses/i2c-ali1563
rename to Documentation/i2c/busses/i2c-ali1563.rst
index 41b1a077e4c7..eec32c3ba92a 100644
--- a/Documentation/i2c/busses/i2c-ali1563
+++ b/Documentation/i2c/busses/i2c-ali1563.rst
@@ -1,7 +1,10 @@
+=========================
Kernel driver i2c-ali1563
+=========================
Supported adapters:
* Acer Labs, Inc. ALI 1563 (south bridge)
+
Datasheet: Now under NDA
http://www.ali.com.tw/
diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst
similarity index 72%
rename from Documentation/i2c/busses/i2c-ali15x3
rename to Documentation/i2c/busses/i2c-ali15x3.rst
index 42888d8ac124..d4c1a2a419cb 100644
--- a/Documentation/i2c/busses/i2c-ali15x3
+++ b/Documentation/i2c/busses/i2c-ali15x3.rst
@@ -1,20 +1,23 @@
+=========================
Kernel driver i2c-ali15x3
+=========================
Supported adapters:
* Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
+
Datasheet: Now under NDA
http://www.ali.com.tw/
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>
Module Parameters
-----------------
* force_addr: int
- Initialize the base address of the i2c controller
+ Initialize the base address of the i2c controller
Notes
@@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
lspci. Don't use this unless the driver complains that the base address is
not set.
-Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
+Example::
+
+ modprobe i2c-ali15x3 force_addr=0xe800
SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
by a power cycle. Cause unknown (see Issues below).
@@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
M1541 and M1543C South Bridges.
The M1543C is a South bridge for desktop systems.
+
The M1541 is a South bridge for portable systems.
+
They are part of the following ALI chipsets:
* "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
- 100MHz CPU Front Side bus
+ 100MHz CPU Front Side bus
* "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
- CPU Front Side bus
+ CPU Front Side bus
+
Some Aladdin V motherboards:
- Asus P5A
- Atrend ATC-5220
- BCM/GVC VP1541
- Biostar M5ALA
- Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
- enable the 7101 device! **)
- Iwill XA100 Plus
- Micronics C200
- Microstar (MSI) MS-5169
+ - Asus P5A
+ - Atrend ATC-5220
+ - BCM/GVC VP1541
+ - Biostar M5ALA
+ - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
+ enable the 7101 device!)
+ - Iwill XA100 Plus
+ - Micronics C200
+ - Microstar (MSI) MS-5169
* "Aladdin IV" includes the M1541 Socket 7 North bridge
- with host bus up to 83.3 MHz.
+ with host bus up to 83.3 MHz.
For an overview of these chips see http://www.acerlabs.com. At this time the
full data sheets on the web site are password protected, however if you
contact the ALI office in San Jose they may give you the password.
The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
-output of lspci will show something similar to the following:
+output of lspci will show something similar to the following::
00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED
00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
-** IMPORTANT **
-** If you have a M1533 or M1543C on the board and you get
-** "ali15x3: Error: Can't detect ali15x3!"
-** then run lspci.
-** If you see the 1533 and 5229 devices but NOT the 7101 device,
-** then you must enable ACPI, the PMU, SMB, or something similar
-** in the BIOS.
-** The driver won't work if it can't find the M7101 device.
+.. important::
+
+ If you have a M1533 or M1543C on the board and you get
+ "ali15x3: Error: Can't detect ali15x3!"
+ then run lspci.
+
+ If you see the 1533 and 5229 devices but NOT the 7101 device,
+ then you must enable ACPI, the PMU, SMB, or something similar
+ in the BIOS.
+
+ The driver won't work if it can't find the M7101 device.
The SMB controller is part of the M7101 device, which is an ACPI-compliant
Power Management Unit (PMU).
@@ -109,4 +120,3 @@ There may be electrical problems on this board.
On the P5A, the W83781D sensor chip is on both the ISA and
SMBus. Therefore the SMBus hangs can generally be avoided
by accessing the W83781D on the ISA bus only.
-
diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2.rst
similarity index 42%
rename from Documentation/i2c/busses/i2c-amd-mp2
rename to Documentation/i2c/busses/i2c-amd-mp2.rst
index 6571487171f4..ebc2fa899325 100644
--- a/Documentation/i2c/busses/i2c-amd-mp2
+++ b/Documentation/i2c/busses/i2c-amd-mp2.rst
@@ -1,4 +1,6 @@
+=========================
Kernel driver i2c-amd-mp2
+=========================
Supported adapters:
* AMD MP2 PCIe interface
@@ -6,9 +8,9 @@ Supported adapters:
Datasheet: not publicly available.
Authors:
- Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
- Nehal Shah <nehal-bakulchandra.shah@amd.com>
- Elie Morisse <syniurge@gmail.com>
+ - Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
+ - Nehal Shah <nehal-bakulchandra.shah@amd.com>
+ - Elie Morisse <syniurge@gmail.com>
Description
-----------
@@ -16,8 +18,8 @@ Description
The MP2 is an ARM processor programmed as an I2C controller and communicating
with the x86 host through PCI.
-If you see something like this:
+If you see something like this::
-03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
+ 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
-in your 'lspci -v', then this driver is for your device.
+in your ``lspci -v``, then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst
similarity index 79%
rename from Documentation/i2c/busses/i2c-amd756
rename to Documentation/i2c/busses/i2c-amd756.rst
index 67f30874d0bf..bc93f392a4fc 100644
--- a/Documentation/i2c/busses/i2c-amd756
+++ b/Documentation/i2c/busses/i2c-amd756.rst
@@ -1,18 +1,22 @@
+========================
Kernel driver i2c-amd756
+========================
Supported adapters:
* AMD 756
* AMD 766
* AMD 768
* AMD 8111
+
Datasheets: Publicly available on AMD website
* nVidia nForce
+
Datasheet: Unavailable
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Philip Edelbrock <phil@netroedge.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Philip Edelbrock <phil@netroedge.com>
Description
-----------
diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst
similarity index 66%
rename from Documentation/i2c/busses/i2c-amd8111
rename to Documentation/i2c/busses/i2c-amd8111.rst
index 460dd6635fd2..d08bf0a7f0ac 100644
--- a/Documentation/i2c/busses/i2c-amd8111
+++ b/Documentation/i2c/busses/i2c-amd8111.rst
@@ -1,4 +1,6 @@
+=========================
Kernel driver i2c-adm8111
+=========================
Supported adapters:
* AMD-8111 SMBus 2.0 PCI interface
@@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz>
Description
-----------
-If you see something like this:
+If you see something like this::
-00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
- Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
- Flags: medium devsel, IRQ 19
- I/O ports at d400 [size=32]
+ 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
+ Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
+ Flags: medium devsel, IRQ 19
+ I/O ports at d400 [size=32]
-in your 'lspci -v', then this driver is for your chipset.
+in your ``lspci -v``, then this driver is for your chipset.
Process Call Support
--------------------
diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-diolan-u2c
rename to Documentation/i2c/busses/i2c-diolan-u2c.rst
index 0d6018c316c7..c18cbdcdf73c 100644
--- a/Documentation/i2c/busses/i2c-diolan-u2c
+++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst
@@ -1,7 +1,10 @@
+============================
Kernel driver i2c-diolan-u2c
+============================
Supported adapters:
* Diolan U2C-12 I2C-USB adapter
+
Documentation:
http://www.diolan.com/i2c/u2c12.html
diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst
similarity index 89%
rename from Documentation/i2c/busses/i2c-i801
rename to Documentation/i2c/busses/i2c-i801.rst
index f426c13c63a9..2a570c214880 100644
--- a/Documentation/i2c/busses/i2c-i801
+++ b/Documentation/i2c/busses/i2c-i801.rst
@@ -1,4 +1,7 @@
+======================
Kernel driver i2c-i801
+======================
+
Supported adapters:
* Intel 82801AA and 82801AB (ICH and ICH0 - part of the
@@ -39,28 +42,33 @@ Supported adapters:
* Intel Comet Lake (PCH)
* Intel Elkhart Lake (PCH)
* Intel Tiger Lake (PCH)
+
Datasheets: Publicly available at the Intel website
On Intel Patsburg and later chipsets, both the normal host SMBus controller
and the additional 'Integrated Device Function' controllers are supported.
-Authors:
- Mark Studebaker <mdsxyz123@yahoo.com>
- Jean Delvare <jdelvare@suse.de>
+Authors:
+ - Mark Studebaker <mdsxyz123@yahoo.com>
+ - Jean Delvare <jdelvare@suse.de>
Module Parameters
-----------------
* disable_features (bit vector)
+
Disable selected features normally supported by the device. This makes it
possible to work around possible driver or hardware bugs if the feature in
question doesn't work as intended for whatever reason. Bit values:
+
+ ==== =========================================
0x01 disable SMBus PEC
0x02 disable the block buffer
0x08 disable the I2C block read functionality
0x10 don't use interrupts
0x20 disable SMBus Host Notify
+ ==== =========================================
Description
@@ -73,7 +81,7 @@ Pentium-based PCs, '815E' chipset, and others.
The ICH chips contain at least SEVEN separate PCI functions in TWO logical
PCI devices. An output of lspci will show something similar to the
-following:
+following::
00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
@@ -139,14 +147,14 @@ and you think there's something interesting on the SMBus (e.g. a
hardware monitoring chip), you need to add your board to the list.
The motherboard is identified using the subvendor and subdevice IDs of the
-host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
+host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
-00:00.0 Class 0600: 8086:2570 (rev 02)
- Subsystem: 1043:80f2
- Flags: bus master, fast devsel, latency 0
- Memory at fc000000 (32-bit, prefetchable) [size=32M]
- Capabilities: [e4] #09 [2106]
- Capabilities: [a0] AGP version 3.0
+ 00:00.0 Class 0600: 8086:2570 (rev 02)
+ Subsystem: 1043:80f2
+ Flags: bus master, fast devsel, latency 0
+ Memory at fc000000 (32-bit, prefetchable) [size=32M]
+ Capabilities: [e4] #09 [2106]
+ Capabilities: [a0] AGP version 3.0
Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
(Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
@@ -165,7 +173,8 @@ kernel. It's very convenient if you just want to check if there's
anything interesting on your hidden ICH SMBus.
-**********************
+----------------------------------------------------------------------------
+
The lm_sensors project gratefully acknowledges the support of Texas
Instruments in the initial development of this driver.
diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst
similarity index 81%
rename from Documentation/i2c/busses/i2c-ismt
rename to Documentation/i2c/busses/i2c-ismt.rst
index 737355822c0b..8e74919a3fdf 100644
--- a/Documentation/i2c/busses/i2c-ismt
+++ b/Documentation/i2c/busses/i2c-ismt.rst
@@ -1,4 +1,7 @@
+======================
Kernel driver i2c-ismt
+======================
+
Supported adapters:
* Intel S12xx series SOCs
@@ -11,16 +14,21 @@ Module Parameters
-----------------
* bus_speed (unsigned int)
+
Allows changing of the bus speed. Normally, the bus speed is set by the BIOS
and never needs to be changed. However, some SMBus analyzers are too slow for
monitoring the bus during debug, thus the need for this module parameter.
Specify the bus speed in kHz.
+
Available bus frequency settings:
- 0 no change
- 80 kHz
- 100 kHz
- 400 kHz
- 1000 kHz
+
+ ==== =========
+ 0 no change
+ 80 kHz
+ 100 kHz
+ 400 kHz
+ 1000 kHz
+ ==== =========
Description
@@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
targeted primarily at the microserver and storage markets.
The S12xx series contain a pair of PCI functions. An output of lspci will show
-something similar to the following:
+something similar to the following::
00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst
similarity index 88%
rename from Documentation/i2c/busses/i2c-mlxcpld
rename to Documentation/i2c/busses/i2c-mlxcpld.rst
index 925904aa9b57..9a0b2916aa71 100644
--- a/Documentation/i2c/busses/i2c-mlxcpld
+++ b/Documentation/i2c/busses/i2c-mlxcpld.rst
@@ -1,9 +1,12 @@
+==================
Driver i2c-mlxcpld
+==================
Author: Michael Shych <michaelsh@mellanox.com>
This is the Mellanox I2C controller logic, implemented in Lattice CPLD
device.
+
Device supports:
- Master mode.
- One physical bus.
@@ -20,6 +23,8 @@ The next transaction types are supported:
- Write Byte/Block.
Registers:
+
+=============== === =======================================================================
CPBLTY 0x0 - capability reg.
Bits [6:5] - transaction length. b01 - 72B is supported,
36B in other case.
@@ -49,3 +54,4 @@ DATAx 0xa - 0x54 - 68 bytes data buffer regs.
For read transactions address is sent in a separate transaction and
specified in the four first bytes (DATA0 - DATA3). Data is read
starting from DATA0.
+=============== === =======================================================================
diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst
similarity index 58%
rename from Documentation/i2c/busses/i2c-nforce2
rename to Documentation/i2c/busses/i2c-nforce2.rst
index 9698c396b830..83181445268f 100644
--- a/Documentation/i2c/busses/i2c-nforce2
+++ b/Documentation/i2c/busses/i2c-nforce2.rst
@@ -1,10 +1,12 @@
+=========================
Kernel driver i2c-nforce2
+=========================
Supported adapters:
- * nForce2 MCP 10de:0064
- * nForce2 Ultra 400 MCP 10de:0084
- * nForce3 Pro150 MCP 10de:00D4
- * nForce3 250Gb MCP 10de:00E4
+ * nForce2 MCP 10de:0064
+ * nForce2 Ultra 400 MCP 10de:0084
+ * nForce3 Pro150 MCP 10de:00D4
+ * nForce3 250Gb MCP 10de:00E4
* nForce4 MCP 10de:0052
* nForce4 MCP-04 10de:0034
* nForce MCP51 10de:0264
@@ -16,26 +18,27 @@ Supported adapters:
* nForce MCP78S 10de:0752
* nForce MCP79 10de:0AA2
-Datasheet: not publicly available, but seems to be similar to the
+Datasheet:
+ not publicly available, but seems to be similar to the
AMD-8111 SMBus 2.0 adapter.
Authors:
- Hans-Frieder Vogt <hfvogt@gmx.net>,
- Thomas Leibold <thomas@plx.com>,
- Patrick Dreker <patrick@dreker.de>
-
+ - Hans-Frieder Vogt <hfvogt@gmx.net>,
+ - Thomas Leibold <thomas@plx.com>,
+ - Patrick Dreker <patrick@dreker.de>
+
Description
-----------
i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
-00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
- Subsystem: Asustek Computer, Inc.: Unknown device 0c11
- Flags: 66Mhz, fast devsel, IRQ 5
- I/O ports at c000 [size=32]
- Capabilities: <available only to root>
+ 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
+ Subsystem: Asustek Computer, Inc.: Unknown device 0c11
+ Flags: 66Mhz, fast devsel, IRQ 5
+ I/O ports at c000 [size=32]
+ Capabilities: <available only to root>
then this driver should support the SMBuses of your motherboard.
diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
similarity index 63%
rename from Documentation/i2c/busses/i2c-nvidia-gpu
rename to Documentation/i2c/busses/i2c-nvidia-gpu.rst
index 31884d2b2eb5..38fb8a4c8756 100644
--- a/Documentation/i2c/busses/i2c-nvidia-gpu
+++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
@@ -1,4 +1,6 @@
+============================
Kernel driver i2c-nvidia-gpu
+============================
Datasheet: not publicly available.
@@ -11,8 +13,8 @@ Description
i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
and later GPUs and it is used to communicate with Type-C controller on GPUs.
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
-01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
+ 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
then this driver should support the I2C controller of your GPU.
diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst
similarity index 82%
rename from Documentation/i2c/busses/i2c-ocores
rename to Documentation/i2c/busses/i2c-ocores.rst
index 9caaf7df1b2f..f5e175f2a2a6 100644
--- a/Documentation/i2c/busses/i2c-ocores
+++ b/Documentation/i2c/busses/i2c-ocores.rst
@@ -1,4 +1,6 @@
+========================
Kernel driver i2c-ocores
+========================
Supported adapters:
* OpenCores.org I2C controller by Richard Herveille (see datasheet link)
@@ -23,9 +25,9 @@ distance between registers and the input clock speed.
There is also a possibility to attach a list of i2c_board_info which
the i2c-ocores driver will add to the bus upon creation.
-E.G. something like:
+E.G. something like::
-static struct resource ocores_resources[] = {
+ static struct resource ocores_resources[] = {
[0] = {
.start = MYI2C_BASEADDR,
.end = MYI2C_BASEADDR + 8,
@@ -36,10 +38,10 @@ static struct resource ocores_resources[] = {
.end = MYI2C_IRQ,
.flags = IORESOURCE_IRQ,
},
-};
+ };
-/* optional board info */
-struct i2c_board_info ocores_i2c_board_info[] = {
+ /* optional board info */
+ struct i2c_board_info ocores_i2c_board_info[] = {
{
I2C_BOARD_INFO("tsc2003", 0x48),
.platform_data = &tsc2003_platform_data,
@@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = {
I2C_BOARD_INFO("adv7180", 0x42 >> 1),
.irq = ADV_IRQ
}
-};
+ };
-static struct ocores_i2c_platform_data myi2c_data = {
+ static struct ocores_i2c_platform_data myi2c_data = {
.regstep = 2, /* two bytes between registers */
.clock_khz = 50000, /* input clock of 50MHz */
.devices = ocores_i2c_board_info, /* optional table of devices */
.num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */
-};
+ };
-static struct platform_device myi2c = {
+ static struct platform_device myi2c = {
.name = "ocores-i2c",
.dev = {
.platform_data = &myi2c_data,
},
.num_resources = ARRAY_SIZE(ocores_resources),
.resource = ocores_resources,
-};
+ };
diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-parport-light
rename to Documentation/i2c/busses/i2c-parport-light.rst
index 7071b8ba0af4..e73af975d2c8 100644
--- a/Documentation/i2c/busses/i2c-parport-light
+++ b/Documentation/i2c/busses/i2c-parport-light.rst
@@ -1,13 +1,15 @@
+===============================
Kernel driver i2c-parport-light
+===============================
Author: Jean Delvare <jdelvare@suse.de>
-This driver is a light version of i2c-parport. It doesn't depend
+This driver is a light version of i2c-parport. It doesn't depend
on the parport driver, and uses direct I/O access instead. This might be
preferred on embedded systems where wasting memory for the clean but heavy
parport handling is not an option. The drawback is a reduced portability
-and the impossibility to daisy-chain other parallel port devices.
-
+and the impossibility to daisy-chain other parallel port devices.
+
Please see i2c-parport for documentation.
Module parameters:
diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport.rst
similarity index 49%
rename from Documentation/i2c/busses/i2c-parport
rename to Documentation/i2c/busses/i2c-parport.rst
index c3dbb3bfd814..a9b4e8133700 100644
--- a/Documentation/i2c/busses/i2c-parport
+++ b/Documentation/i2c/busses/i2c-parport.rst
@@ -1,17 +1,21 @@
+=========================
Kernel driver i2c-parport
+=========================
Author: Jean Delvare <jdelvare@suse.de>
This is a unified driver for several i2c-over-parallel-port adapters,
such as the ones made by Philips, Velleman or ELV. This driver is
meant as a replacement for the older, individual drivers:
+
* i2c-philips-par
* i2c-elv
* i2c-velleman
- * video/i2c-parport (NOT the same as this one, dedicated to home brew
- teletext adapters)
+ * video/i2c-parport
+ (NOT the same as this one, dedicated to home brew teletext adapters)
It currently supports the following devices:
+
* (type=0) Philips adapter
* (type=1) home brew teletext adapter
* (type=2) Velleman K8000 adapter
@@ -38,44 +42,48 @@ Building your own adapter
-------------------------
If you want to build you own i2c-over-parallel-port adapter, here is
-a sample electronics schema (credits go to Sylvain Munaut):
+a sample electronics schema (credits go to Sylvain Munaut)::
+
+ Device PC
+ Side ___________________Vdd (+) Side
+ | | |
+ --- --- ---
+ | | | | | |
+ |R| |R| |R|
+ | | | | | |
+ --- --- ---
+ | | |
+ | | /| |
+ SCL ----------x--------o |-----------x------------------- pin 2
+ | \| | |
+ | | |
+ | |\ | |
+ SDA ----------x----x---| o---x--------------------------- pin 13
+ | |/ |
+ | |
+ | /| |
+ ---------o |----------------x-------------- pin 3
+ \| | |
+ | |
+ --- ---
+ | | | |
+ |R| |R|
+ | | | |
+ --- ---
+ | |
+ ### ###
+ GND GND
-Device PC
-Side ___________________Vdd (+) Side
- | | |
- --- --- ---
- | | | | | |
- |R| |R| |R|
- | | | | | |
- --- --- ---
- | | |
- | | /| |
-SCL ----------x--------o |-----------x------------------- pin 2
- | \| | |
- | | |
- | |\ | |
-SDA ----------x----x---| o---x--------------------------- pin 13
- | |/ |
- | |
- | /| |
- ---------o |----------------x-------------- pin 3
- \| | |
- | |
- --- ---
- | | | |
- |R| |R|
- | | | |
- --- ---
- | |
- ### ###
- GND GND
-
Remarks:
- This is the exact pinout and electronics used on the Analog Devices
evaluation boards.
+ - All inverters::
+
/|
- - All inverters -o |- must be 74HC05, they must be open collector output.
+ -o |-
\|
+
+ must be 74HC05, they must be open collector output.
- All resitors are 10k.
- Pins 18-25 of the parallel port connected to GND.
- Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
@@ -84,47 +92,47 @@ Remarks:
all connected lines MUST BE driven at the same state, else you'll short
circuit the output buffers! So plugging the I2C adapter after loading
the i2c-parport module might be a good safety since data line state
- prior to init may be unknown.
+ prior to init may be unknown.
- This is 5V!
- Obviously you cannot read SCL (so it's not really standard-compliant).
Pretty easy to add, just copy the SDA part and use another input pin.
- That would give (ELV compatible pinout):
+ That would give (ELV compatible pinout)::
-Device PC
-Side ______________________________Vdd (+) Side
- | | | |
- --- --- --- ---
- | | | | | | | |
- |R| |R| |R| |R|
- | | | | | | | |
- --- --- --- ---
- | | | |
- | | |\ | |
-SCL ----------x--------x--| o---x------------------------ pin 15
- | | |/ |
- | | |
- | | /| |
- | ---o |-------------x-------------- pin 2
- | \| | |
- | | |
- | | |
- | |\ | |
-SDA ---------------x---x--| o--------x------------------- pin 10
- | |/ |
- | |
- | /| |
- ---o |------------------x--------- pin 3
- \| | |
- | |
- --- ---
- | | | |
- |R| |R|
- | | | |
- --- ---
- | |
- ### ###
- GND GND
+ Device PC
+ Side ______________________________Vdd (+) Side
+ | | | |
+ --- --- --- ---
+ | | | | | | | |
+ |R| |R| |R| |R|
+ | | | | | | | |
+ --- --- --- ---
+ | | | |
+ | | |\ | |
+ SCL ----------x--------x--| o---x------------------------ pin 15
+ | | |/ |
+ | | |
+ | | /| |
+ | ---o |-------------x-------------- pin 2
+ | \| | |
+ | | |
+ | | |
+ | |\ | |
+ SDA ---------------x---x--| o--------x------------------- pin 10
+ | |/ |
+ | |
+ | /| |
+ ---o |------------------x--------- pin 3
+ \| | |
+ | |
+ --- ---
+ | | | |
+ |R| |R|
+ | | | |
+ --- ---
+ | |
+ ### ###
+ GND GND
If possible, you should use the same pinout configuration as existing
@@ -149,19 +157,23 @@ Legacy documentation for Velleman adapter
-----------------------------------------
Useful links:
-Velleman http://www.velleman.be/
-Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
+
+- Velleman http://www.velleman.be/
+- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html
The project has lead to new libs for the Velleman K8000 and K8005:
+
LIBK8000 v1.99.1 and LIBK8005 v0.21
+
With these libs, you can control the K8000 interface card and the K8005
stepper motor card with the simple commands which are in the original
Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
many more, using /dev/velleman.
- http://home.wanadoo.nl/hihihi/libk8000.htm
- http://home.wanadoo.nl/hihihi/libk8005.htm
- http://struyve.mine.nu:8080/index.php?block=k8000
- http://sourceforge.net/projects/libk8005/
+
+ - http://home.wanadoo.nl/hihihi/libk8000.htm
+ - http://home.wanadoo.nl/hihihi/libk8005.htm
+ - http://struyve.mine.nu:8080/index.php?block=k8000
+ - http://sourceforge.net/projects/libk8005/
One For All JP1 parallel port adapter
diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst
similarity index 72%
rename from Documentation/i2c/busses/i2c-pca-isa
rename to Documentation/i2c/busses/i2c-pca-isa.rst
index b044e5265488..a254010c8055 100644
--- a/Documentation/i2c/busses/i2c-pca-isa
+++ b/Documentation/i2c/busses/i2c-pca-isa.rst
@@ -1,6 +1,9 @@
+=========================
Kernel driver i2c-pca-isa
+=========================
Supported adapters:
+
This driver supports ISA boards using the Philips PCA 9564
Parallel bus to I2C bus controller
@@ -10,11 +13,11 @@ Module Parameters
-----------------
* base int
- I/O base address
+ I/O base address
* irq int
- IRQ interrupt
+ IRQ interrupt
* clock int
- Clock rate as described in table 1 of PCA9564 datasheet
+ Clock rate as described in table 1 of PCA9564 datasheet
Description
-----------
diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst
similarity index 92%
rename from Documentation/i2c/busses/i2c-piix4
rename to Documentation/i2c/busses/i2c-piix4.rst
index 2703bc3acad0..cc9000259223 100644
--- a/Documentation/i2c/busses/i2c-piix4
+++ b/Documentation/i2c/busses/i2c-piix4.rst
@@ -1,4 +1,6 @@
+=======================
Kernel driver i2c-piix4
+=======================
Supported adapters:
* Intel 82371AB PIIX4 and PIIX4E
@@ -20,9 +22,9 @@ Supported adapters:
* Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
Datasheet: Publicly available at the SMSC website http://www.smsc.com
-Authors:
- Frodo Looijaard <frodol@dds.nl>
- Philip Edelbrock <phil@netroedge.com>
+Authors:
+ - Frodo Looijaard <frodol@dds.nl>
+ - Philip Edelbrock <phil@netroedge.com>
Module Parameters
@@ -39,16 +41,16 @@ Description
The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
functionality. Among other things, it implements the PCI bus. One of its
-minor functions is implementing a System Management Bus. This is a true
+minor functions is implementing a System Management Bus. This is a true
SMBus - you can not access it on I2C levels. The good news is that it
natively understands SMBus commands and you do not have to worry about
timing problems. The bad news is that non-SMBus devices connected to it can
confuse it mightily. Yes, this is known to happen...
-Do 'lspci -v' and see whether it contains an entry like this:
+Do ``lspci -v`` and see whether it contains an entry like this::
-0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
- Flags: medium devsel, IRQ 9
+ 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
+ Flags: medium devsel, IRQ 9
Bus and device numbers may differ, but the function number must be
identical (like many PCI devices, the PIIX4 incorporates a number of
@@ -91,7 +93,7 @@ the SMI mode.
device is located at 00:0f.0.
2) Now you just need to change the value in 0xD2 register. Get it first with
command: lspci -xxx -s 00:0f.0
- If the value is 0x3 then you need to change it to 0x1
+ If the value is 0x3 then you need to change it to 0x1:
setpci -s 00:0f.0 d2.b=1
Please note that you don't need to do that in all cases, just when the SMBus is
diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst
similarity index 74%
rename from Documentation/i2c/busses/i2c-sis5595
rename to Documentation/i2c/busses/i2c-sis5595.rst
index ecd21fb49a8f..b85630c84a96 100644
--- a/Documentation/i2c/busses/i2c-sis5595
+++ b/Documentation/i2c/busses/i2c-sis5595.rst
@@ -1,9 +1,11 @@
+=========================
Kernel driver i2c-sis5595
+=========================
Authors:
- Frodo Looijaard <frodol@dds.nl>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Philip Edelbrock <phil@netroedge.com>
+ - Frodo Looijaard <frodol@dds.nl>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Philip Edelbrock <phil@netroedge.com>
Supported adapters:
* Silicon Integrated Systems Corp. SiS5595 Southbridge
@@ -11,14 +13,19 @@ Supported adapters:
Note: all have mfr. ID 0x1039.
+ ========= ======
SUPPORTED PCI ID
+ ========= ======
5595 0008
+ ========= ======
Note: these chips contain a 0008 device which is incompatible with the
5595. We recognize these by the presence of the listed
"blacklist" PCI ID and refuse to load.
+ ============= ====== ================
NOT SUPPORTED PCI ID BLACKLIST PCI ID
+ ============= ====== ================
540 0008 0540
550 0008 0550
5513 0008 5511
@@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039.
735 0008 0735
745 0008 0745
746 0008 0746
+ ============= ====== ================
Module Parameters
-----------------
-* force_addr=0xaddr Set the I/O base address. Useful for boards
+================== =====================================================
+force_addr=0xaddr Set the I/O base address. Useful for boards
that don't set the address in the BIOS. Does not do a
PCI force; the device must still be present in lspci.
Don't use this unless the driver complains that the
base address is not set.
+================== =====================================================
Description
-----------
@@ -56,4 +66,3 @@ WARNING: If you are trying to access the integrated sensors on the SiS5595
chip, you want the sis5595 driver for those, not this driver. This driver
is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP
drivers to access chips on the bus.
-
diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630.rst
similarity index 37%
rename from Documentation/i2c/busses/i2c-sis630
rename to Documentation/i2c/busses/i2c-sis630.rst
index ee7943631074..9fcd74b18781 100644
--- a/Documentation/i2c/busses/i2c-sis630
+++ b/Documentation/i2c/busses/i2c-sis630.rst
@@ -1,4 +1,6 @@
+========================
Kernel driver i2c-sis630
+========================
Supported adapters:
* Silicon Integrated Systems Corp (SiS)
@@ -7,20 +9,24 @@ Supported adapters:
964 chipset
* Possible other SiS chipsets ?
-Author: Alexander Malysh <amalysh@web.de>
- Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
+Author:
+ - Alexander Malysh <amalysh@web.de>
+ - Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
Module Parameters
-----------------
-* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
- This can be interesting for chipsets not named
- above to check if it works for you chipset, but DANGEROUS!
+================== =====================================================
+force = [1|0] Forcibly enable the SIS630. DANGEROUS!
+ This can be interesting for chipsets not named
+ above to check if it works for you chipset,
+ but DANGEROUS!
-* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
+high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
what your BIOS use). DANGEROUS! This should be a bit
faster, but freeze some systems (i.e. my Laptop).
SIS630/730 chip only.
+================== =====================================================
Description
@@ -29,23 +35,23 @@ Description
This SMBus only driver is known to work on motherboards with the above
named chipsets.
-If you see something like this:
+If you see something like this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
+ 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-or like this:
+or like this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
+ 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-or like this:
+or like this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
LPC Controller (rev 36)
-in your 'lspci' output , then this driver is for your chipset.
+in your ``lspci`` output , then this driver is for your chipset.
Thank You
---------
@@ -55,4 +61,3 @@ Mark M. Hoffman <mhoffman@lightlink.com>
- bug fixes
To anyone else which I forgot here ;), thanks!
-
diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst
similarity index 74%
rename from Documentation/i2c/busses/i2c-sis96x
rename to Documentation/i2c/busses/i2c-sis96x.rst
index 0b979f3252a4..437cc1d89588 100644
--- a/Documentation/i2c/busses/i2c-sis96x
+++ b/Documentation/i2c/busses/i2c-sis96x.rst
@@ -1,13 +1,18 @@
+========================
Kernel driver i2c-sis96x
+========================
Replaces 2.4.x i2c-sis645
Supported adapters:
+
* Silicon Integrated Systems Corp (SiS)
+
Any combination of these host bridges:
645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
+
and these south bridges:
- 961, 962, 963(L)
+ 961, 962, 963(L)
Author: Mark M. Hoffman <mhoffman@lightlink.com>
@@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different
place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
SiS630 datasheet (and driver).
-The command "lspci" as root should produce something like these lines:
+The command ``lspci`` as root should produce something like these lines::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+ 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
-or perhaps this...
+or perhaps this::
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+ 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+ 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
+ 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
(kernel versions later than 2.4.18 may fill in the "Unknown"s)
@@ -50,7 +55,7 @@ TO DOs
------
* The driver does not support SMBus block reads/writes; I may add them if a
-scenario is found where they're needed.
+ scenario is found where they're needed.
Thank You
@@ -58,16 +63,20 @@ Thank You
Mark D. Studebaker <mdsxyz123@yahoo.com>
- design hints and bug fixes
+
Alexander Maylsh <amalysh@web.de>
- ditto, plus an important datasheet... almost the one I really wanted
+
Hans-Günter Lütke Uphues <hg_lu@t-online.de>
- patch for SiS735
+
Robert Zwerus <arzie@dds.nl>
- testing for SiS645DX
+
Kianusch Sayah Karadji <kianusch@sk-tech.net>
- patch for SiS645DX/962
+
Ken Healy
- patch for SiS655
To anyone else who has written w/ feedback, thanks!
-
diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-taos-evm
rename to Documentation/i2c/busses/i2c-taos-evm.rst
index 60299555dcf0..f342e313ee3d 100644
--- a/Documentation/i2c/busses/i2c-taos-evm
+++ b/Documentation/i2c/busses/i2c-taos-evm.rst
@@ -1,4 +1,6 @@
+==========================
Kernel driver i2c-taos-evm
+==========================
Author: Jean Delvare <jdelvare@suse.de>
@@ -23,10 +25,10 @@ Using this driver
In order to use this driver, you'll need the serport driver, and the
inputattach tool, which is part of the input-utils package. The following
commands will tell the kernel that you have a TAOS EVM on the first
-serial port:
+serial port::
-# modprobe serport
-# inputattach --taos-evm /dev/ttyS0
+ # modprobe serport
+ # inputattach --taos-evm /dev/ttyS0
Technical details
diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst
similarity index 54%
rename from Documentation/i2c/busses/i2c-via
rename to Documentation/i2c/busses/i2c-via.rst
index 343870661ac3..846aa17d80a2 100644
--- a/Documentation/i2c/busses/i2c-via
+++ b/Documentation/i2c/busses/i2c-via.rst
@@ -1,4 +1,6 @@
+=====================
Kernel driver i2c-via
+=====================
Supported adapters:
* VIA Technologies, InC. VT82C586B
@@ -12,23 +14,27 @@ Description
i2c-via is an i2c bus driver for motherboards with VIA chipset.
The following VIA pci chipsets are supported:
- - MVP3, VP3, VP2/97, VPX/97
+ - MVP3, VP3, VP2/97, VPX/97
- others with South bridge VT82C586B
-Your lspci listing must show this :
+Your ``lspci`` listing must show this ::
Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
- Problems?
-
- Q: You have VT82C586B on the motherboard, but not in the listing.
-
- A: Go to your BIOS setup, section PCI devices or similar.
- Turn USB support on, and try again.
+Problems?
+---------
- Q: No error messages, but still i2c doesn't seem to work.
+ Q:
+ You have VT82C586B on the motherboard, but not in the listing.
- A: This can happen. This driver uses the pins VIA recommends in their
+ A:
+ Go to your BIOS setup, section PCI devices or similar.
+ Turn USB support on, and try again.
+
+ Q:
+ No error messages, but still i2c doesn't seem to work.
+
+ A:
+ This can happen. This driver uses the pins VIA recommends in their
datasheets, but there are several ways the motherboard manufacturer
can actually wire the lines.
-
diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst
similarity index 87%
rename from Documentation/i2c/busses/i2c-viapro
rename to Documentation/i2c/busses/i2c-viapro.rst
index ab64ce21c254..1762f0cf93d0 100644
--- a/Documentation/i2c/busses/i2c-viapro
+++ b/Documentation/i2c/busses/i2c-viapro.rst
@@ -1,4 +1,6 @@
+========================
Kernel driver i2c-viapro
+========================
Supported adapters:
* VIA Technologies, Inc. VT82C596A/B
@@ -26,9 +28,9 @@ Supported adapters:
Datasheet: available on http://linux.via.com.tw
Authors:
- Kyösti Mälkki <kmalkki@cc.hut.fi>,
- Mark D. Studebaker <mdsxyz123@yahoo.com>,
- Jean Delvare <jdelvare@suse.de>
+ - Kyösti Mälkki <kmalkki@cc.hut.fi>,
+ - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+ - Jean Delvare <jdelvare@suse.de>
Module Parameters
-----------------
@@ -44,8 +46,9 @@ Description
i2c-viapro is a true SMBus host driver for motherboards with one of the
supported VIA south bridges.
-Your lspci -n listing must show one of these :
+Your ``lspci -n`` listing must show one of these :
+ ================ ======================
device 1106:3050 (VT82C596A function 3)
device 1106:3051 (VT82C596B function 3)
device 1106:3057 (VT82C686 function 4)
@@ -61,6 +64,7 @@ Your lspci -n listing must show one of these :
device 1106:8353 (VX800/VX820)
device 1106:8409 (VX855/VX875)
device 1106:8410 (VX900)
+ ================ ======================
If none of these show up, you should look in the BIOS for settings like
enable ACPI / SMBus or even USB.
diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst
new file mode 100644
index 000000000000..97ca4d510816
--- /dev/null
+++ b/Documentation/i2c/busses/index.rst
@@ -0,0 +1,33 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===============
+I2C Bus Drivers
+===============
+
+.. toctree::
+ :maxdepth: 1
+
+ i2c-ali1535
+ i2c-ali1563
+ i2c-ali15x3
+ i2c-amd756
+ i2c-amd8111
+ i2c-amd-mp2
+ i2c-diolan-u2c
+ i2c-i801
+ i2c-ismt
+ i2c-mlxcpld
+ i2c-nforce2
+ i2c-nvidia-gpu
+ i2c-ocores
+ i2c-parport-light
+ i2c-parport
+ i2c-pca-isa
+ i2c-piix4
+ i2c-sis5595
+ i2c-sis630
+ i2c-sis96x
+ i2c-taos-evm
+ i2c-viapro
+ i2c-via
+ scx200_acb
diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst
similarity index 86%
rename from Documentation/i2c/busses/scx200_acb
rename to Documentation/i2c/busses/scx200_acb.rst
index ce83c871fe95..8dc7c352508c 100644
--- a/Documentation/i2c/busses/scx200_acb
+++ b/Documentation/i2c/busses/scx200_acb.rst
@@ -1,4 +1,6 @@
+========================
Kernel driver scx200_acb
+========================
Author: Christer Weinigel <wingel@nano-system.com>
@@ -25,8 +27,11 @@ Device-specific notes
The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
If the scx200_acb driver is built into the kernel, add the following
-parameter to your boot command line:
+parameter to your boot command line::
+
scx200_acb.base=0x810,0x820
+
If the scx200_acb driver is built as a module, add the following line to
-a configuration file in /etc/modprobe.d/ instead:
+a configuration file in /etc/modprobe.d/ instead::
+
options scx200_acb base=0x810,0x820
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst
similarity index 71%
rename from Documentation/i2c/dev-interface
rename to Documentation/i2c/dev-interface.rst
index fbed645ccd75..69c23a3c2b1b 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface.rst
@@ -1,3 +1,7 @@
+====================
+I2C Device Interface
+====================
+
Usually, i2c devices are controlled by a kernel driver. But it is also
possible to access all devices on an adapter from userspace, through
the /dev interface. You need to load module i2c-dev for this.
@@ -18,7 +22,7 @@ C example
=========
So let's say you want to access an i2c adapter from a C program.
-First, you need to include these two headers:
+First, you need to include these two headers::
#include <linux/i2c-dev.h>
#include <i2c/smbus.h>
@@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
Adapter numbers are assigned somewhat dynamically, so you can not
assume much about them. They can even change from one boot to the next.
-Next thing, open the device file, as follows:
+Next thing, open the device file, as follows::
int file;
int adapter_nr = 2; /* probably dynamically determined */
@@ -42,7 +46,7 @@ Next thing, open the device file, as follows:
}
When you have opened the device, you must specify with what device
-address you want to communicate:
+address you want to communicate::
int addr = 0x40; /* The I2C address */
@@ -53,7 +57,7 @@ address you want to communicate:
Well, you are all set up now. You can now use SMBus commands or plain
I2C to communicate with your device. SMBus commands are preferred if
-the device supports them. Both are illustrated below.
+the device supports them. Both are illustrated below::
__u8 reg = 0x10; /* Device register to access */
__s32 res;
@@ -100,35 +104,35 @@ Full interface description
The following IOCTLs are defined:
-ioctl(file, I2C_SLAVE, long addr)
+``ioctl(file, I2C_SLAVE, long addr)``
Change slave address. The address is passed in the 7 lower bits of the
argument (except for 10 bit addresses, passed in the 10 lower bits in this
case).
-ioctl(file, I2C_TENBIT, long select)
+``ioctl(file, I2C_TENBIT, long select)``
Selects ten bit addresses if select not equals 0, selects normal 7 bit
addresses if select equals 0. Default 0. This request is only valid
if the adapter has I2C_FUNC_10BIT_ADDR.
-ioctl(file, I2C_PEC, long select)
+``ioctl(file, I2C_PEC, long select)``
Selects SMBus PEC (packet error checking) generation and verification
if select not equals 0, disables if select equals 0. Default 0.
Used only for SMBus transactions. This request only has an effect if the
the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
doesn't have any effect.
-ioctl(file, I2C_FUNCS, unsigned long *funcs)
- Gets the adapter functionality and puts it in *funcs.
+``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
+ Gets the adapter functionality and puts it in ``*funcs``.
-ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
+``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
Do combined read/write transaction without stop in between.
Only valid if the adapter has I2C_FUNC_I2C. The argument is
- a pointer to a
+ a pointer to a::
- struct i2c_rdwr_ioctl_data {
+ struct i2c_rdwr_ioctl_data {
struct i2c_msg *msgs; /* ptr to array of simple messages */
int nmsgs; /* number of messages to exchange */
- }
+ }
The msgs[] themselves contain further pointers into data buffers.
The function will write or read data to or from that buffers depending
@@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
The slave address and whether to use ten bit address mode has to be
set in each message, overriding the values set with the above ioctl's.
-ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
- If possible, use the provided i2c_smbus_* methods described below instead
+``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
+ If possible, use the provided ``i2c_smbus_*`` methods described below instead
of issuing direct ioctls.
You can do plain i2c transactions by using read(2) and write(2) calls.
@@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through
ioctl I2C_SLAVE before you try to access the device.
You can do SMBus level transactions (see documentation file smbus-protocol
-for details) through the following functions:
+for details) through the following functions::
+
__s32 i2c_smbus_write_quick(int file, __u8 value);
__s32 i2c_smbus_read_byte(int file);
__s32 i2c_smbus_write_byte(int file, __u8 value);
@@ -157,6 +162,7 @@ for details) through the following functions:
__s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
__s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
__u8 *values);
+
All these transactions return -1 on failure; you can read errno to see
what happened. The 'write' transactions return 0 on success; the
'read' transactions return the read value, except for read_block, which
@@ -174,39 +180,39 @@ Implementation details
For the interested, here's the code flow which happens inside the kernel
when you use the /dev interface to I2C:
-1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
-section "C example" above.
+1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
+ section "C example" above.
-2* These open() and ioctl() calls are handled by the i2c-dev kernel
-driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
-respectively. You can think of i2c-dev as a generic I2C chip driver
-that can be programmed from user-space.
+2) These open() and ioctl() calls are handled by the i2c-dev kernel
+ driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
+ respectively. You can think of i2c-dev as a generic I2C chip driver
+ that can be programmed from user-space.
-3* Some ioctl() calls are for administrative tasks and are handled by
-i2c-dev directly. Examples include I2C_SLAVE (set the address of the
-device you want to access) and I2C_PEC (enable or disable SMBus error
-checking on future transactions.)
+3) Some ioctl() calls are for administrative tasks and are handled by
+ i2c-dev directly. Examples include I2C_SLAVE (set the address of the
+ device you want to access) and I2C_PEC (enable or disable SMBus error
+ checking on future transactions.)
-4* Other ioctl() calls are converted to in-kernel function calls by
-i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
-functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
-performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
+4) Other ioctl() calls are converted to in-kernel function calls by
+ i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
+ functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
+ performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
-The i2c-dev driver is responsible for checking all the parameters that
-come from user-space for validity. After this point, there is no
-difference between these calls that came from user-space through i2c-dev
-and calls that would have been performed by kernel I2C chip drivers
-directly. This means that I2C bus drivers don't need to implement
-anything special to support access from user-space.
+ The i2c-dev driver is responsible for checking all the parameters that
+ come from user-space for validity. After this point, there is no
+ difference between these calls that came from user-space through i2c-dev
+ and calls that would have been performed by kernel I2C chip drivers
+ directly. This means that I2C bus drivers don't need to implement
+ anything special to support access from user-space.
-5* These i2c.h functions are wrappers to the actual implementation of
-your I2C bus driver. Each adapter must declare callback functions
-implementing these standard calls. i2c.h:i2c_get_functionality() calls
-i2c_adapter.algo->functionality(), while
-i2c-core-smbus.c:i2c_smbus_xfer() calls either
-adapter.algo->smbus_xfer() if it is implemented, or if not,
-i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
-i2c_adapter.algo->master_xfer().
+5) These i2c.h functions are wrappers to the actual implementation of
+ your I2C bus driver. Each adapter must declare callback functions
+ implementing these standard calls. i2c.h:i2c_get_functionality() calls
+ i2c_adapter.algo->functionality(), while
+ i2c-core-smbus.c:i2c_smbus_xfer() calls either
+ adapter.algo->smbus_xfer() if it is implemented, or if not,
+ i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
+ i2c_adapter.algo->master_xfer().
After your I2C bus driver has processed these requests, execution runs
up the call chain, with almost no processing done, except by i2c-dev to
diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst
similarity index 100%
rename from Documentation/i2c/DMA-considerations
rename to Documentation/i2c/dma-considerations.rst
diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst
similarity index 98%
rename from Documentation/i2c/fault-codes
rename to Documentation/i2c/fault-codes.rst
index 0cee0fc545b4..80b14e718b52 100644
--- a/Documentation/i2c/fault-codes
+++ b/Documentation/i2c/fault-codes.rst
@@ -1,3 +1,7 @@
+=====================
+I2C/SMBUS Fault Codes
+=====================
+
This is a summary of the most important conventions for use of fault
codes in the I2C/SMBus stack.
@@ -125,4 +129,3 @@ ETIMEDOUT
when a slave stretches clocks too far. I2C has no such
timeouts, but it's normal for I2C adapters to impose some
arbitrary limits (much longer than SMBus!) too.
-
diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst
similarity index 91%
rename from Documentation/i2c/functionality
rename to Documentation/i2c/functionality.rst
index 4aae8ed15873..377507c56162 100644
--- a/Documentation/i2c/functionality
+++ b/Documentation/i2c/functionality.rst
@@ -1,11 +1,15 @@
+=======================
+I2C/SMBus Functionality
+=======================
+
INTRODUCTION
------------
-Because not every I2C or SMBus adapter implements everything in the
+Because not every I2C or SMBus adapter implements everything in the
I2C specifications, a client can not trust that everything it needs
is implemented when it is given the option to attach to an adapter:
the client needs some way to check whether an adapter has the needed
-functionality.
+functionality.
FUNCTIONALITY CONSTANTS
@@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS
For the most up-to-date list of functionality constants, please check
<uapi/linux/i2c.h>!
+ =============================== ==============================================
I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus
adapters typically can not do these)
I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions
@@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check
I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command
I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command
+ =============================== ==============================================
A few combinations of the above flags are also defined for your convenience:
+ ========================= ======================================
I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte
and write_byte commands
I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data
@@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience:
I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be
emulated by a real I2C adapter (using
the transparent emulation layer)
+ ========================= ======================================
In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
part of I2C_FUNC_PROTOCOL_MANGLING.
@@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION
----------------------
When you write a new adapter driver, you will have to implement a
-function callback `functionality'. Typical implementations are given
+function callback ``functionality``. Typical implementations are given
below.
A typical SMBus-only adapter would list all the SMBus transactions it
-supports. This example comes from the i2c-piix4 driver:
+supports. This example comes from the i2c-piix4 driver::
static u32 piix4_func(struct i2c_adapter *adapter)
{
@@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver:
}
A typical full-I2C adapter would use the following (from the i2c-pxa
-driver):
+driver)::
static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
{
@@ -94,7 +102,7 @@ CLIENT CHECKING
Before a client tries to attach to an adapter, or even do tests to check
whether one of the devices it supports is present on an adapter, it should
check whether the needed functionality is present. The typical way to do
-this is (from the lm75 driver):
+this is (from the lm75 driver)::
static int lm75_detect(...)
{
@@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have
to use the /dev interface. You will still have to check whether the
functionality you need is supported, of course. This is done using
the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
-below:
+below::
int file;
if (file = open("/dev/i2c-0", O_RDWR) < 0) {
diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst
similarity index 97%
rename from Documentation/i2c/gpio-fault-injection
rename to Documentation/i2c/gpio-fault-injection.rst
index c87f416d53dd..9dca6ec7d266 100644
--- a/Documentation/i2c/gpio-fault-injection
+++ b/Documentation/i2c/gpio-fault-injection.rst
@@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost
should be detected beforehand. Also note, that SCL going down is monitored
using interrupts, so the interrupt latency might cause the first bits to be not
corrupted. A good starting point for using this fault injector on an otherwise
-idle bus is:
+idle bus is::
-# echo 200 > lose_arbitration &
-# i2cget -y <bus_to_test> 0x3f
+ # echo 200 > lose_arbitration &
+ # i2cget -y <bus_to_test> 0x3f
Panic during transfer
=====================
@@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The
process is interruptible, though.
Start of a transfer is detected by waiting for SCL going down by the master
-under test. A good starting point for using this fault injector is:
+under test. A good starting point for using this fault injector is::
-# echo 0 > inject_panic &
-# i2cget -y <bus_to_test> <some_address>
+ # echo 0 > inject_panic &
+ # i2cget -y <bus_to_test> <some_address>
Note that there doesn't need to be a device listening to the address you are
using. Results may vary depending on that, though.
diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst
similarity index 83%
rename from Documentation/i2c/i2c-protocol
rename to Documentation/i2c/i2c-protocol.rst
index ff6d6cee6c7e..2f8fcf671b2e 100644
--- a/Documentation/i2c/i2c-protocol
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -1,8 +1,13 @@
+============
+I2C Protocol
+============
+
This document describes the i2c protocol. Or will, when it is finished :-)
Key to symbols
==============
+=============== =============================================================
S (1 bit) : Start bit
P (1 bit) : Stop bit
Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
@@ -15,33 +20,35 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
for 16 bit data.
Count (8 bits): A data byte containing the length of a block operation.
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]: Data sent by I2C device, as opposed to data sent by the
+ host adapter.
+=============== =============================================================
Simple send transaction
-======================
+=======================
-This corresponds to i2c_master_send.
+This corresponds to i2c_master_send::
S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
Simple receive transaction
-===========================
+==========================
-This corresponds to i2c_master_recv
+This corresponds to i2c_master_recv::
S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
Combined transactions
-====================
+=====================
This corresponds to i2c_transfer
They are just like the above transactions, but instead of a stop bit P
a start bit S is sent and the transaction continues. An example of
-a byte read, followed by a byte write:
+a byte read, followed by a byte write::
S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
@@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK:
I2C_M_NOSTART:
In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
point. For example, setting I2C_M_NOSTART on the second partial message
- generates something like:
+ generates something like::
+
S Addr Rd [A] [Data] NA Data [A] P
+
If you set the I2C_M_NOSTART variable for the first partial message,
we do not generate Addr, but we do generate the startbit S. This will
probably confuse all other clients on your bus, so don't try this.
@@ -79,7 +88,8 @@ I2C_M_NOSTART:
I2C_M_REV_DIR_ADDR:
This toggles the Rd/Wr flag. That is, if you want to do a write, but
need to emit an Rd instead of a Wr, or vice versa, you set this
- flag. For example:
+ flag. For example::
+
S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
I2C_M_STOP:
diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst
similarity index 93%
rename from Documentation/i2c/i2c-stub
rename to Documentation/i2c/i2c-stub.rst
index a16924fbd289..a6fc6916d6bc 100644
--- a/Documentation/i2c/i2c-stub
+++ b/Documentation/i2c/i2c-stub.rst
@@ -1,6 +1,9 @@
-MODULE: i2c-stub
+========
+i2c-stub
+========
-DESCRIPTION:
+Description
+===========
This module is a very simple fake I2C/SMBus driver. It implements six
types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
@@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always
return the number of bytes selected with the largest write so far.
The typical use-case is like this:
+
1. load this module
2. use i2cset (from the i2c-tools project) to pre-load some data
3. load the target chip driver module
@@ -36,7 +40,8 @@ The typical use-case is like this:
There's a script named i2c-stub-from-dump in the i2c-tools package which
can load register values automatically from a chip dump.
-PARAMETERS:
+Parameters
+==========
int chip_addr[10]:
The SMBus addresses to emulate chips at.
@@ -47,18 +52,15 @@ unsigned long functionality:
value 0x1f0000 would only enable the quick, byte and byte data
commands.
-u8 bank_reg[10]
-u8 bank_mask[10]
-u8 bank_start[10]
-u8 bank_end[10]:
+u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
Optional bank settings. They tell which bits in which register
select the active bank, as well as the range of banked registers.
-CAVEATS:
+Caveats
+=======
If your target driver polls some byte or word waiting for it to change, the
stub could lock it up. Use i2cset to unlock it.
If you spam it hard enough, printk can be lossy. This module really wants
something like relayfs.
-
diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst
similarity index 89%
rename from Documentation/i2c/i2c-topology
rename to Documentation/i2c/i2c-topology.rst
index f74d78b53d4d..0c1ae95f6a97 100644
--- a/Documentation/i2c/i2c-topology
+++ b/Documentation/i2c/i2c-topology.rst
@@ -1,3 +1,4 @@
+============
I2C topology
============
@@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices.
that has to be operated before the device can be accessed.
Etc
+===
These constructs are represented as i2c adapter trees by Linux, where
each adapter has a parent adapter (except the root adapter) and zero or
@@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be
useful to know if a mux is mux-locked or if it is parent-locked. The
following list was correct at the time of writing:
-In drivers/i2c/muxes/
+In drivers/i2c/muxes/:
+
+====================== =============================================
i2c-arb-gpio-challenge Parent-locked
i2c-mux-gpio Normally parent-locked, mux-locked iff
all involved gpio pins are controlled by the
@@ -52,18 +56,25 @@ i2c-mux-pinctrl Normally parent-locked, mux-locked iff
all involved pinctrl devices are controlled
by the same i2c root adapter that they mux.
i2c-mux-reg Parent-locked
+====================== =============================================
-In drivers/iio/
+In drivers/iio/:
+
+====================== =============================================
gyro/mpu3050 Mux-locked
imu/inv_mpu6050/ Mux-locked
+====================== =============================================
-In drivers/media/
+In drivers/media/:
+
+======================= =============================================
dvb-frontends/lgdt3306a Mux-locked
dvb-frontends/m88ds3103 Parent-locked
dvb-frontends/rtl2830 Parent-locked
dvb-frontends/rtl2832 Mux-locked
dvb-frontends/si2168 Mux-locked
usb/cx231xx/ Parent-locked
+======================= =============================================
Mux-locked muxes
@@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different
stages of the transaction. This has the benefit that the mux driver
may be easier and cleaner to implement, but it has some caveats.
+==== =====================================================================
ML1. If you build a topology with a mux-locked mux being the parent
of a parent-locked mux, this might break the expectation from the
parent-locked mux that the root adapter is locked during the
@@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
Otherwise garbage may appear on the bus as seen from devices
behind the mux, when an unrelated i2c transfer is in flight during
the non-i2c mux-changing operation.
+==== =====================================================================
Mux-locked Example
------------------
+
+::
+
.----------. .--------.
.--------. | mux- |-----| dev D1 |
| root |--+--| locked | '--------'
@@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g.
__i2c_transfer), or a deadlock will follow. There are a couple of
caveats.
+==== ====================================================================
PL1. If you build a topology with a parent-locked mux being the child
of another mux, this might break a possible assumption from the
child mux that the root adapter is unused between its select op
@@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio,
caused by these subsystems are unlocked. This can be convoluted to
accomplish, maybe even impossible if an acceptably clean solution
is sought.
+==== ====================================================================
Parent-locked Example
---------------------
+::
+
.----------. .--------.
.--------. | parent- |-----| dev D1 |
| root |--+--| locked | '--------'
@@ -177,20 +197,20 @@ Parent-locked Example
When there is an access to D1, this happens:
- 1. Someone issues an i2c-transfer to D1.
- 2. M1 locks muxes on its parent (the root adapter in this case).
- 3. M1 locks its parent adapter.
- 4. M1 calls ->select to ready the mux.
- 5. If M1 does any i2c-transfers (on this root adapter) as part of
- its select, those transfers must be unlocked i2c-transfers so
- that they do not deadlock the root adapter.
- 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an
- unlocked i2c-transfer, so that it does not deadlock the parent
- adapter.
- 7. M1 calls ->deselect, if it has one.
- 8. Same rules as in step 5, but for ->deselect.
- 9. M1 unlocks its parent adapter.
-10. M1 unlocks muxes on its parent.
+ 1. Someone issues an i2c-transfer to D1.
+ 2. M1 locks muxes on its parent (the root adapter in this case).
+ 3. M1 locks its parent adapter.
+ 4. M1 calls ->select to ready the mux.
+ 5. If M1 does any i2c-transfers (on this root adapter) as part of
+ its select, those transfers must be unlocked i2c-transfers so
+ that they do not deadlock the root adapter.
+ 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an
+ unlocked i2c-transfer, so that it does not deadlock the parent
+ adapter.
+ 7. M1 calls ->deselect, if it has one.
+ 8. Same rules as in step 5, but for ->deselect.
+ 9. M1 unlocks its parent adapter.
+ 10. M1 unlocks muxes on its parent.
This means that accesses to both D2 and D3 are locked out for the full
@@ -203,7 +223,7 @@ Complex Examples
Parent-locked mux as parent of parent-locked mux
------------------------------------------------
-This is a useful topology, but it can be bad.
+This is a useful topology, but it can be bad::
.----------. .----------. .--------.
.--------. | parent- |-----| parent- |-----| dev D1 |
@@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely.
Mux-locked mux as parent of mux-locked mux
------------------------------------------
-This is a good topology.
+This is a good topology::
.----------. .----------. .--------.
.--------. | mux- |-----| mux- |-----| dev D1 |
@@ -248,7 +268,7 @@ are still possibly interleaved.
Mux-locked mux as parent of parent-locked mux
---------------------------------------------
-This is probably a bad topology.
+This is probably a bad topology::
.----------. .----------. .--------.
.--------. | mux- |-----| parent- |-----| dev D1 |
@@ -282,7 +302,7 @@ auto-closing, the topology is fine.
Parent-locked mux as parent of mux-locked mux
---------------------------------------------
-This is a good topology.
+This is a good topology::
.----------. .----------. .--------.
.--------. | parent- |-----| mux- |-----| dev D1 |
@@ -306,7 +326,7 @@ adapter is locked directly.
Two mux-locked sibling muxes
----------------------------
-This is a good topology.
+This is a good topology::
.--------.
.----------. .--| dev D1 |
@@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time.
Two parent-locked sibling muxes
-------------------------------
-This is a good topology.
+This is a good topology::
.--------.
.----------. .--| dev D1 |
@@ -354,7 +374,7 @@ out.
Mux-locked and parent-locked sibling muxes
------------------------------------------
-This is a good topology.
+This is a good topology::
.--------.
.----------. .--| dev D1 |
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
new file mode 100644
index 000000000000..cd8d020f7ac5
--- /dev/null
+++ b/Documentation/i2c/index.rst
@@ -0,0 +1,37 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===================
+I2C/SMBus Subsystem
+===================
+
+.. toctree::
+ :maxdepth: 1
+
+ dev-interface
+ dma-considerations
+ fault-codes
+ functionality
+ gpio-fault-injection
+ i2c-protocol
+ i2c-stub
+ i2c-topology
+ instantiating-devices
+ old-module-parameters
+ slave-eeprom-backend
+ slave-interface
+ smbus-protocol
+ summary
+ ten-bit-addresses
+ upgrading-clients
+ writing-clients
+
+ muxes/i2c-mux-gpio
+
+ busses/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst
similarity index 93%
rename from Documentation/i2c/instantiating-devices
rename to Documentation/i2c/instantiating-devices.rst
index 345e9ea8281a..1238f1fa3382 100644
--- a/Documentation/i2c/instantiating-devices
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -1,3 +1,4 @@
+==============================
How to instantiate I2C devices
==============================
@@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C
devices which live on this bus. This is done with an array of struct
i2c_board_info which is registered by calling i2c_register_board_info().
-Example (from omap2 h4):
+Example (from omap2 h4)::
-static struct i2c_board_info h4_i2c_board_info[] __initdata = {
+ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
{
I2C_BOARD_INFO("isp1301_omap", 0x2d),
.irq = OMAP_GPIO_IRQ(125),
@@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
I2C_BOARD_INFO("24c01", 0x57),
.platform_data = &m24c01,
},
-};
+ };
-static void __init omap_h4_init(void)
-{
+ static void __init omap_h4_init(void)
+ {
(...)
i2c_register_board_info(1, h4_i2c_board_info,
ARRAY_SIZE(h4_i2c_board_info));
(...)
-}
+ }
The above code declares 3 devices on I2C bus 1, including their respective
addresses and custom data needed by their drivers. When the I2C bus in
@@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree
This method has the same implications as method 1a. The declaration of I2C
devices is here done via devicetree as subnodes of the master controller.
-Example:
+Example::
i2c1: i2c@400a0000 {
/* ... master properties skipped ... */
@@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead,
you can instantiate your I2C devices explicitly. This is done by filling
a struct i2c_board_info and calling i2c_new_device().
-Example (from the sfe4001 network driver):
+Example (from the sfe4001 network driver)::
-static struct i2c_board_info sfe4001_hwmon_info = {
+ static struct i2c_board_info sfe4001_hwmon_info = {
I2C_BOARD_INFO("max6647", 0x4e),
-};
+ };
-int sfe4001_init(struct efx_nic *efx)
-{
+ int sfe4001_init(struct efx_nic *efx)
+ {
(...)
efx->board_info.hwmon_client =
i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
(...)
-}
+ }
The above code instantiates 1 I2C device on the I2C bus which is on the
network adapter in question.
@@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer
changing its design without notice). In this case, you can call
i2c_new_probed_device() instead of i2c_new_device().
-Example (from the nxp OHCI driver):
+Example (from the nxp OHCI driver)::
-static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
+ static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
-static int usb_hcd_nxp_probe(struct platform_device *pdev)
-{
+ static int usb_hcd_nxp_probe(struct platform_device *pdev)
+ {
(...)
struct i2c_adapter *i2c_adap;
struct i2c_board_info i2c_info;
@@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
normal_i2c, NULL);
i2c_put_adapter(i2c_adap);
(...)
-}
+ }
The above code instantiates up to 1 I2C device on the I2C bus which is on
the OHCI adapter in question. It first tries at address 0x2c, if nothing
@@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their
drivers are loaded, and if any is found, an I2C device will be
instantiated automatically. In order to prevent any misbehavior of this
mechanism, the following restrictions apply:
+
* The I2C device driver must implement the detect() method, which
identifies a supported device by reading from arbitrary registers.
* Only buses which are likely to have a supported device and agree to be
@@ -189,6 +191,7 @@ first.
Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
kernels will find out that this method 3 is essentially similar to what
was done there. Two significant differences are:
+
* Probing is only one way to instantiate I2C devices now, while it was the
only way back then. Where possible, methods 1 and 2 should be preferred.
Method 3 should only be used when there is no other way, as it can have
@@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C
segment, the address is sufficient to uniquely identify the device to be
deleted.
-Example:
-# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
+Example::
+
+ # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
While this interface should only be used when in-kernel device declaration
can't be done, there is a variety of cases where it can be helpful:
+
* The I2C driver usually detects devices (method 3 above) but the bus
segment your device lives on doesn't have the proper class bit set and
thus detection doesn't trigger.
diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst
similarity index 85%
rename from Documentation/i2c/muxes/i2c-mux-gpio
rename to Documentation/i2c/muxes/i2c-mux-gpio.rst
index 893ecdfe6e43..7d27444035c3 100644
--- a/Documentation/i2c/muxes/i2c-mux-gpio
+++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst
@@ -1,4 +1,6 @@
+==========================
Kernel driver i2c-mux-gpio
+==========================
Author: Peter Korsgaard <peter.korsgaard@barco.com>
@@ -8,7 +10,7 @@ Description
i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
from a master I2C bus and a hardware MUX controlled through GPIO pins.
-E.G.:
+E.G.::
---------- ---------- Bus segment 1 - - - - -
| | SCL/SDA | |-------------- | |
@@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used
to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
E.G. something like this for a MUX providing 4 bus segments
-controlled through 3 GPIO pins:
+controlled through 3 GPIO pins::
-#include <linux/platform_data/i2c-mux-gpio.h>
-#include <linux/platform_device.h>
+ #include <linux/platform_data/i2c-mux-gpio.h>
+ #include <linux/platform_device.h>
-static const unsigned myboard_gpiomux_gpios[] = {
+ static const unsigned myboard_gpiomux_gpios[] = {
AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
-};
+ };
-static const unsigned myboard_gpiomux_values[] = {
+ static const unsigned myboard_gpiomux_values[] = {
0, 1, 2, 3
-};
+ };
-static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
+ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
.parent = 1,
.base_nr = 2, /* optional */
.values = myboard_gpiomux_values,
@@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
.gpios = myboard_gpiomux_gpios,
.n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios),
.idle = 4, /* optional */
-};
+ };
-static struct platform_device myboard_i2cmux = {
+ static struct platform_device myboard_i2cmux = {
.name = "i2c-mux-gpio",
.id = 0,
.dev = {
.platform_data = &myboard_i2cmux_data,
},
-};
+ };
If you don't know the absolute GPIO pin numbers at registration time,
you can instead provide a chip name (.chip_name) and relative GPIO pin
diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst
similarity index 75%
rename from Documentation/i2c/old-module-parameters
rename to Documentation/i2c/old-module-parameters.rst
index 8e2b629d533c..a1939512ad66 100644
--- a/Documentation/i2c/old-module-parameters
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -1,3 +1,4 @@
+=================================================
I2C device driver binding control from user-space
=================================================
@@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface.
Attaching a driver to an I2C device
-----------------------------------
-Old method (module parameters):
-# modprobe <driver> probe=1,0x2d
-# modprobe <driver> force=1,0x2d
-# modprobe <driver> force_<device>=1,0x2d
+Old method (module parameters)::
-New method (sysfs interface):
-# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
+ # modprobe <driver> probe=1,0x2d
+ # modprobe <driver> force=1,0x2d
+ # modprobe <driver> force_<device>=1,0x2d
+
+New method (sysfs interface)::
+
+ # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
Preventing a driver from attaching to an I2C device
---------------------------------------------------
-Old method (module parameters):
-# modprobe <driver> ignore=1,0x2f
+Old method (module parameters)::
-New method (sysfs interface):
-# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
-# modprobe <driver>
+ # modprobe <driver> ignore=1,0x2f
+
+New method (sysfs interface)::
+
+ # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
+ # modprobe <driver>
Of course, it is important to instantiate the "dummy" device before loading
the driver. The dummy device will be handled by i2c-core itself, preventing
diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst
similarity index 90%
rename from Documentation/i2c/slave-eeprom-backend
rename to Documentation/i2c/slave-eeprom-backend.rst
index 04f8d8a9b817..0b8cd83698e0 100644
--- a/Documentation/i2c/slave-eeprom-backend
+++ b/Documentation/i2c/slave-eeprom-backend.rst
@@ -1,3 +1,4 @@
+==============================
Linux I2C slave eeprom backend
==============================
@@ -5,10 +6,9 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
This is a proof-of-concept backend which acts like an EEPROM on the connected
I2C bus. The memory contents can be modified from userspace via this file
-located in sysfs:
+located in sysfs::
/sys/bus/i2c/devices/<device-directory>/slave-eeprom
As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
notification when another master changed the content.
-
diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst
similarity index 94%
rename from Documentation/i2c/slave-interface
rename to Documentation/i2c/slave-interface.rst
index 7e2a228f21bc..c769bd6a15bf 100644
--- a/Documentation/i2c/slave-interface
+++ b/Documentation/i2c/slave-interface.rst
@@ -1,3 +1,4 @@
+=====================================
Linux I2C slave interface description
=====================================
@@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
needed. The backend driver and the I2C bus driver communicate via events. Here
is a small graph visualizing the data flow and the means by which data is
transported. The dotted line marks only one example. The backend could also
-use a character device, be in-kernel only, or something completely different:
+use a character device, be in-kernel only, or something completely different::
e.g. sysfs I2C slave events I/O registers
@@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference
is that i2c slave backends have their own address space. So, you have to add
0x1000 to the address you would originally request. An example for
instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
-on bus 1:
+on bus 1::
# echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
@@ -54,7 +55,7 @@ drivers and writing backends will be given.
I2C slave events
----------------
-The bus driver sends an event to the backend using the following function:
+The bus driver sends an event to the backend using the following function::
ret = i2c_slave_event(client, event, &val)
@@ -69,8 +70,9 @@ Event types:
* I2C_SLAVE_WRITE_REQUESTED (mandatory)
-'val': unused
-'ret': always 0
+ 'val': unused
+
+ 'ret': always 0
Another I2C master wants to write data to us. This event should be sent once
our own address and the write bit was detected. The data did not arrive yet, so
@@ -79,8 +81,9 @@ to be done, though.
* I2C_SLAVE_READ_REQUESTED (mandatory)
-'val': backend returns first byte to be sent
-'ret': always 0
+ 'val': backend returns first byte to be sent
+
+ 'ret': always 0
Another I2C master wants to read data from us. This event should be sent once
our own address and the read bit was detected. After returning, the bus driver
@@ -88,8 +91,9 @@ should transmit the first byte.
* I2C_SLAVE_WRITE_RECEIVED (mandatory)
-'val': bus driver delivers received byte
-'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+ 'val': bus driver delivers received byte
+
+ 'ret': 0 if the byte should be acked, some errno if the byte should be nacked
Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
@@ -97,8 +101,9 @@ should be nacked.
* I2C_SLAVE_READ_PROCESSED (mandatory)
-'val': backend returns next byte to be sent
-'ret': always 0
+ 'val': backend returns next byte to be sent
+
+ 'ret': always 0
The bus driver requests the next byte to be sent to another I2C master in
'val'. Important: This does not mean that the previous byte has been acked, it
@@ -111,8 +116,9 @@ your backend, though.
* I2C_SLAVE_STOP (mandatory)
-'val': unused
-'ret': always 0
+ 'val': unused
+
+ 'ret': always 0
A stop condition was received. This can happen anytime and the backend should
reset its state machine for I2C transfers to be able to receive new requests.
@@ -190,4 +196,3 @@ this time of writing. Some points to keep in mind when using buffers:
* A master can send STOP at any time. For partially transferred buffers, this
means additional code to handle this exception. Such code tends to be
error-prone.
-
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst
similarity index 82%
rename from Documentation/i2c/smbus-protocol
rename to Documentation/i2c/smbus-protocol.rst
index 092d474f5843..e30eb1d274c6 100644
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -1,3 +1,4 @@
+======================
SMBus Protocol Summary
======================
@@ -27,17 +28,18 @@ Each transaction type corresponds to a functionality flag. Before calling a
transaction function, a device driver should always check (just once) for
the corresponding functionality flag to ensure that the underlying I2C
adapter supports the transaction in question. See
-<file:Documentation/i2c/functionality> for the details.
+<file:Documentation/i2c/functionality.rst> for the details.
Key to symbols
==============
+=============== =============================================================
S (1 bit) : Start bit
P (1 bit) : Stop bit
Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit) : Accept and reverse accept bit.
-Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
+A, NA (1 bit) : Accept and reverse accept bit.
+Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
get a 10 bit I2C address.
Comm (8 bits): Command byte, a data byte which often selects a register on
the device.
@@ -45,15 +47,17 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
for 16 bit data.
Count (8 bits): A data byte containing the length of a block operation.
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]: Data sent by I2C device, as opposed to data sent by the host
+ adapter.
+=============== =============================================================
SMBus Quick Command
===================
-This sends a single bit to the device, at the place of the Rd/Wr bit.
+This sends a single bit to the device, at the place of the Rd/Wr bit::
-A Addr Rd/Wr [A] P
+ A Addr Rd/Wr [A] P
Functionality flag: I2C_FUNC_SMBUS_QUICK
@@ -64,9 +68,9 @@ SMBus Receive Byte: i2c_smbus_read_byte()
This reads a single byte from a device, without specifying a device
register. Some devices are so simple that this interface is enough; for
others, it is a shorthand if you want to read the same register as in
-the previous SMBus command.
+the previous SMBus command::
-S Addr Rd [A] [Data] NA P
+ S Addr Rd [A] [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
@@ -77,7 +81,9 @@ SMBus Send Byte: i2c_smbus_write_byte()
This operation is the reverse of Receive Byte: it sends a single byte
to a device. See Receive Byte for more information.
-S Addr Wr [A] Data [A] P
+::
+
+ S Addr Wr [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
@@ -86,9 +92,9 @@ SMBus Read Byte: i2c_smbus_read_byte_data()
============================================
This reads a single byte from a device, from a designated register.
-The register is specified through the Comm byte.
+The register is specified through the Comm byte::
-S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
+ S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
@@ -98,9 +104,9 @@ SMBus Read Word: i2c_smbus_read_word_data()
This operation is very like Read Byte; again, data is read from a
device, from a designated register that is specified through the Comm
-byte. But this time, the data is a complete word (16 bits).
+byte. But this time, the data is a complete word (16 bits)::
-S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
+ S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
@@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The
register is specified through the Comm byte. This is the opposite of
the Read Byte operation.
-S Addr Wr [A] Comm [A] Data [A] P
+::
+
+ S Addr Wr [A] Comm [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
@@ -126,9 +134,9 @@ SMBus Write Word: i2c_smbus_write_word_data()
This is the opposite of the Read Word operation. 16 bits
of data is written to a device, to the designated register that is
-specified through the Comm byte.
+specified through the Comm byte.::
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
+ S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
@@ -141,10 +149,10 @@ SMBus Process Call:
===================
This command selects a device register (through the Comm byte), sends
-16 bits of data to it, and reads 16 bits of data in return.
+16 bits of data to it, and reads 16 bits of data in return::
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
- S Addr Rd [A] [DataLow] A [DataHigh] NA P
+ S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
+ S Addr Rd [A] [DataLow] A [DataHigh] NA P
Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
@@ -152,12 +160,14 @@ Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
SMBus Block Read: i2c_smbus_read_block_data()
==============================================
-This command reads a block of up to 32 bytes from a device, from a
+This command reads a block of up to 32 bytes from a device, from a
designated register that is specified through the Comm byte. The amount
of data is specified by the device in the Count byte.
-S Addr Wr [A] Comm [A]
- S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
+::
+
+ S Addr Wr [A] Comm [A]
+ S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
@@ -165,11 +175,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
SMBus Block Write: i2c_smbus_write_block_data()
================================================
-The opposite of the Block Read command, this writes up to 32 bytes to
+The opposite of the Block Read command, this writes up to 32 bytes to
a device, to a designated register that is specified through the
Comm byte. The amount of data is specified in the Count byte.
-S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+ S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
@@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in
Revision 2.0 of the specification.
This command selects a device register (through the Comm byte), sends
-1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
+1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
-S Addr Wr [A] Comm [A] Count [A] Data [A] ...
- S Addr Rd [A] [Count] A [Data] ... A P
+ S Addr Wr [A] Comm [A] Count [A] Data [A] ...
+ S Addr Rd [A] [Count] A [Data] ... A P
Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
@@ -197,9 +209,12 @@ SMBus host acting as a slave.
It is the same form as Write Word, with the command code replaced by the
alerting device's address.
-[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
+::
+
+ [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
This is implemented in the following way in the Linux kernel:
+
* I2C bus drivers which support SMBus Host Notify should report
I2C_FUNC_SMBUS_HOST_NOTIFY.
* I2C bus drivers trigger SMBus Host Notify by a call to
@@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master
to know which slave triggered the interrupt.
This is implemented the following way in the Linux kernel:
+
* I2C bus drivers which support SMBus alert should call
i2c_setup_smbus_alert() to setup SMBus alert support.
* I2C drivers for devices which can trigger SMBus alerts should implement
@@ -261,11 +277,11 @@ but the SMBus layer places a limit of 32 bytes.
I2C Block Read: i2c_smbus_read_i2c_block_data()
================================================
-This command reads a block of bytes from a device, from a
-designated register that is specified through the Comm byte.
+This command reads a block of bytes from a device, from a
+designated register that is specified through the Comm byte::
-S Addr Wr [A] Comm [A]
- S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
+ S Addr Wr [A] Comm [A]
+ S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
@@ -273,11 +289,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
I2C Block Write: i2c_smbus_write_i2c_block_data()
==================================================
-The opposite of the Block Read command, this writes bytes to
+The opposite of the Block Read command, this writes bytes to
a device, to a designated register that is specified through the
Comm byte. Note that command lengths of 0, 2, or more bytes are
supported as they are indistinguishable from data.
-S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+ S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst
similarity index 96%
rename from Documentation/i2c/summary
rename to Documentation/i2c/summary.rst
index 809541ab352f..3a24eac17375 100644
--- a/Documentation/i2c/summary
+++ b/Documentation/i2c/summary.rst
@@ -1,7 +1,8 @@
+=============
I2C and SMBus
=============
-I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
+I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
extension (3.4 MHz). It provides an inexpensive bus for connecting many
types of devices with infrequent or low bandwidth communications needs.
@@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages.
Terminology
===========
-When we talk about I2C, we use the following terms:
+When we talk about I2C, we use the following terms::
+
Bus -> Algorithm
Adapter
Device -> Driver
diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst
similarity index 95%
rename from Documentation/i2c/ten-bit-addresses
rename to Documentation/i2c/ten-bit-addresses.rst
index 7b2d11e53a49..5c765aff16d5 100644
--- a/Documentation/i2c/ten-bit-addresses
+++ b/Documentation/i2c/ten-bit-addresses.rst
@@ -1,3 +1,7 @@
+=====================
+I2C Ten-bit Addresses
+=====================
+
The I2C protocol knows about two kinds of device addresses: normal 7 bit
addresses, and an extended set of 10 bit addresses. The sets of addresses
do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
@@ -12,6 +16,7 @@ See the I2C specification for the details.
The current 10 bit address support is minimal. It should work, however
you can expect some problems along the way:
+
* Not all bus drivers support 10-bit addresses. Some don't because the
hardware doesn't support them (SMBus doesn't require 10-bit address
support for example), some don't because nobody bothered adding the
diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst
similarity index 54%
rename from Documentation/i2c/upgrading-clients
rename to Documentation/i2c/upgrading-clients.rst
index 96392cc5b5c7..27d29032c138 100644
--- a/Documentation/i2c/upgrading-clients
+++ b/Documentation/i2c/upgrading-clients.rst
@@ -1,3 +1,4 @@
+=================================================
Upgrading I2C Drivers to the new 2.6 Driver Model
=================================================
@@ -13,21 +14,22 @@ the old to the new new binding methods.
Example old-style driver
------------------------
+::
-struct example_state {
+ struct example_state {
struct i2c_client client;
....
-};
+ };
-static struct i2c_driver example_driver;
+ static struct i2c_driver example_driver;
-static unsigned short ignore[] = { I2C_CLIENT_END };
-static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+ static unsigned short ignore[] = { I2C_CLIENT_END };
+ static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
-I2C_CLIENT_INSMOD;
+ I2C_CLIENT_INSMOD;
-static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-{
+ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+ {
struct example_state *state;
struct device *dev = &adap->dev; /* to use for dev_ reports */
int ret;
@@ -59,31 +61,31 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
dev_info(dev, "example client created\n");
return 0;
-}
+ }
-static int example_detach(struct i2c_client *client)
-{
+ static int example_detach(struct i2c_client *client)
+ {
struct example_state *state = i2c_get_clientdata(client);
i2c_detach_client(client);
kfree(state);
return 0;
-}
+ }
-static int example_attach_adapter(struct i2c_adapter *adap)
-{
+ static int example_attach_adapter(struct i2c_adapter *adap)
+ {
return i2c_probe(adap, &addr_data, example_attach);
-}
+ }
-static struct i2c_driver example_driver = {
- .driver = {
+ static struct i2c_driver example_driver = {
+ .driver = {
.owner = THIS_MODULE,
.name = "example",
.pm = &example_pm_ops,
},
.attach_adapter = example_attach_adapter,
.detach_client = example_detach,
-};
+ };
Updating the client
@@ -93,38 +95,38 @@ The new style binding model will check against a list of supported
devices and their associated address supplied by the code registering
the busses. This means that the driver .attach_adapter and
.detach_client methods can be removed, along with the addr_data,
-as follows:
+as follows::
-- static struct i2c_driver example_driver;
+ - static struct i2c_driver example_driver;
-- static unsigned short ignore[] = { I2C_CLIENT_END };
-- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+ - static unsigned short ignore[] = { I2C_CLIENT_END };
+ - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
-- I2C_CLIENT_INSMOD;
+ - I2C_CLIENT_INSMOD;
-- static int example_attach_adapter(struct i2c_adapter *adap)
-- {
-- return i2c_probe(adap, &addr_data, example_attach);
-- }
+ - static int example_attach_adapter(struct i2c_adapter *adap)
+ - {
+ - return i2c_probe(adap, &addr_data, example_attach);
+ - }
- static struct i2c_driver example_driver = {
-- .attach_adapter = example_attach_adapter,
-- .detach_client = example_detach,
- }
+ static struct i2c_driver example_driver = {
+ - .attach_adapter = example_attach_adapter,
+ - .detach_client = example_detach,
+ }
-Add the probe and remove methods to the i2c_driver, as so:
+Add the probe and remove methods to the i2c_driver, as so::
- static struct i2c_driver example_driver = {
-+ .probe = example_probe,
-+ .remove = example_remove,
- }
+ static struct i2c_driver example_driver = {
+ + .probe = example_probe,
+ + .remove = example_remove,
+ }
Change the example_attach method to accept the new parameters
-which include the i2c_client that it will be working with:
+which include the i2c_client that it will be working with::
-- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-+ static int example_probe(struct i2c_client *client,
-+ const struct i2c_device_id *id)
+ - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+ + static int example_probe(struct i2c_client *client,
+ + const struct i2c_device_id *id)
Change the name of example_attach to example_probe to align it with the
i2c_driver entry names. The rest of the probe routine will now need to be
@@ -132,57 +134,59 @@ changed as the i2c_client has already been setup for use.
The necessary client fields have already been setup before
the probe function is called, so the following client setup
-can be removed:
+can be removed::
-- example->client.addr = addr;
-- example->client.flags = 0;
-- example->client.adapter = adap;
--
-- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
+ - example->client.addr = addr;
+ - example->client.flags = 0;
+ - example->client.adapter = adap;
+ -
+ - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
-The i2c_set_clientdata is now:
+The i2c_set_clientdata is now::
-- i2c_set_clientdata(&state->client, state);
-+ i2c_set_clientdata(client, state);
+ - i2c_set_clientdata(&state->client, state);
+ + i2c_set_clientdata(client, state);
The call to i2c_attach_client is no longer needed, if the probe
routine exits successfully, then the driver will be automatically
-attached by the core. Change the probe routine as so:
+attached by the core. Change the probe routine as so::
-- ret = i2c_attach_client(&state->i2c_client);
-- if (ret < 0) {
-- dev_err(dev, "failed to attach client\n");
-- kfree(state);
-- return ret;
-- }
+ - ret = i2c_attach_client(&state->i2c_client);
+ - if (ret < 0) {
+ - dev_err(dev, "failed to attach client\n");
+ - kfree(state);
+ - return ret;
+ - }
Remove the storage of 'struct i2c_client' from the 'struct example_state'
as we are provided with the i2c_client in our example_probe. Instead we
store a pointer to it for when it is needed.
-struct example_state {
-- struct i2c_client client;
-+ struct i2c_client *client;
+::
-the new i2c client as so:
+ struct example_state {
+ - struct i2c_client client;
+ + struct i2c_client *client;
-- struct device *dev = &adap->dev; /* to use for dev_ reports */
-+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
+the new i2c client as so::
+
+ - struct device *dev = &adap->dev; /* to use for dev_ reports */
+ + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */
And remove the change after our client is attached, as the driver no
-longer needs to register a new client structure with the core:
+longer needs to register a new client structure with the core::
-- dev = &state->i2c_client.dev;
+ - dev = &state->i2c_client.dev;
In the probe routine, ensure that the new state has the client stored
-in it:
+in it::
-static int example_probe(struct i2c_client *i2c_client,
+ static int example_probe(struct i2c_client *i2c_client,
const struct i2c_device_id *id)
-{
+ {
struct example_state *state;
- struct device *dev = &i2c_client->dev;
+ struct device *dev = &i2c_client->dev;
int ret;
state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
@@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client,
return -ENOMEM;
}
-+ state->client = i2c_client;
+ + state->client = i2c_client;
Update the detach method, by changing the name to _remove and
to delete the i2c_detach_client call. It is possible that you
can also remove the ret variable as it is not needed for any
of the core functions.
-- static int example_detach(struct i2c_client *client)
-+ static int example_remove(struct i2c_client *client)
-{
+::
+
+ - static int example_detach(struct i2c_client *client)
+ + static int example_remove(struct i2c_client *client)
+ {
struct example_state *state = i2c_get_clientdata(client);
-- i2c_detach_client(client);
+ - i2c_detach_client(client);
And finally ensure that we have the correct ID table for the i2c-core
-and other utilities:
+and other utilities::
-+ struct i2c_device_id example_idtable[] = {
-+ { "example", 0 },
-+ { }
-+};
-+
-+MODULE_DEVICE_TABLE(i2c, example_idtable);
+ + struct i2c_device_id example_idtable[] = {
+ + { "example", 0 },
+ + { }
+ +};
+ +
+ +MODULE_DEVICE_TABLE(i2c, example_idtable);
-static struct i2c_driver example_driver = {
- .driver = {
+ static struct i2c_driver example_driver = {
+ .driver = {
.owner = THIS_MODULE,
.name = "example",
},
-+ .id_table = example_ids,
+ + .id_table = example_ids,
-Our driver should now look like this:
+Our driver should now look like this::
-struct example_state {
+ struct example_state {
struct i2c_client *client;
....
-};
+ };
-static int example_probe(struct i2c_client *client,
- const struct i2c_device_id *id)
-{
+ static int example_probe(struct i2c_client *client,
+ const struct i2c_device_id *id)
+ {
struct example_state *state;
struct device *dev = &client->dev;
@@ -250,25 +256,25 @@ static int example_probe(struct i2c_client *client,
dev_info(dev, "example client created\n");
return 0;
-}
+ }
-static int example_remove(struct i2c_client *client)
-{
+ static int example_remove(struct i2c_client *client)
+ {
struct example_state *state = i2c_get_clientdata(client);
kfree(state);
return 0;
-}
+ }
-static struct i2c_device_id example_idtable[] = {
+ static struct i2c_device_id example_idtable[] = {
{ "example", 0 },
{ }
-};
+ };
-MODULE_DEVICE_TABLE(i2c, example_idtable);
+ MODULE_DEVICE_TABLE(i2c, example_idtable);
-static struct i2c_driver example_driver = {
- .driver = {
+ static struct i2c_driver example_driver = {
+ .driver = {
.owner = THIS_MODULE,
.name = "example",
.pm = &example_pm_ops,
@@ -276,4 +282,4 @@ static struct i2c_driver example_driver = {
.id_table = example_idtable,
.probe = example_probe,
.remove = example_remove,
-};
+ };
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst
similarity index 91%
rename from Documentation/i2c/writing-clients
rename to Documentation/i2c/writing-clients.rst
index a755b141fa4a..dddf0a14ab7c 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients.rst
@@ -1,3 +1,7 @@
+===================
+Writing I2C Clients
+===================
+
This is a small guide for those who want to write kernel drivers for I2C
or SMBus devices, using Linux as the protocol host/master (not slave).
@@ -12,7 +16,7 @@ General remarks
Try to keep the kernel namespace as clean as possible. The best way to
do this is to use a unique prefix for all global symbols. This is
especially important for exported symbols, but it is a good idea to do
-it for non-exported symbols too. We will use the prefix `foo_' in this
+it for non-exported symbols too. We will use the prefix ``foo_`` in this
tutorial.
@@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you
provide. A client structure holds device-specific information like the
driver model device node, and its I2C address.
-static struct i2c_device_id foo_idtable[] = {
+::
+
+ static struct i2c_device_id foo_idtable[] = {
{ "foo", my_id_for_foo },
{ "bar", my_id_for_bar },
{ }
-};
+ };
-MODULE_DEVICE_TABLE(i2c, foo_idtable);
+ MODULE_DEVICE_TABLE(i2c, foo_idtable);
-static struct i2c_driver foo_driver = {
+ static struct i2c_driver foo_driver = {
.driver = {
.name = "foo",
.pm = &foo_pm_ops, /* optional */
@@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = {
.shutdown = foo_shutdown, /* optional */
.command = foo_command, /* optional, deprecated */
-}
+ }
The name field is the driver name, and must not contain spaces. It
should match the module name (if the driver can be compiled as a module),
@@ -64,16 +70,18 @@ below.
Extra client data
=================
-Each client structure has a special `data' field that can point to any
+Each client structure has a special ``data`` field that can point to any
structure at all. You should use this to keep device-specific data.
+::
+
/* store the value */
void i2c_set_clientdata(struct i2c_client *client, void *data);
/* retrieve the value */
void *i2c_get_clientdata(const struct i2c_client *client);
-Note that starting with kernel 2.6.34, you don't have to set the `data' field
+Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
to NULL in remove() or if probe() failed anymore. The i2c-core does this
automatically on these occasions. Those are also the only times the core will
touch this field.
@@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily
be encapsulated.
The below functions are simple examples, and should not be copied
-literally.
+literally::
-int foo_read_value(struct i2c_client *client, u8 reg)
-{
+ int foo_read_value(struct i2c_client *client, u8 reg)
+ {
if (reg < 0x10) /* byte-sized register */
return i2c_smbus_read_byte_data(client, reg);
else /* word-sized register */
return i2c_smbus_read_word_data(client, reg);
-}
+ }
-int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
-{
+ int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+ {
if (reg == 0x10) /* Impossible to write - driver error! */
return -EINVAL;
else if (reg < 0x10) /* byte-sized register */
return i2c_smbus_write_byte_data(client, reg, value);
else /* word-sized register */
return i2c_smbus_write_word_data(client, reg, value);
-}
+ }
Probing and attaching
@@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other
kind of driver in Linux: they provide a probe() method to bind to
those devices, and a remove() method to unbind.
+::
+
static int foo_probe(struct i2c_client *client,
const struct i2c_device_id *id);
static int foo_remove(struct i2c_client *client);
@@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted,
you have to do some initializing. Fortunately, just registering the
driver module is usually enough.
-static int __init foo_init(void)
-{
+::
+
+ static int __init foo_init(void)
+ {
return i2c_add_driver(&foo_driver);
-}
-module_init(foo_init);
+ }
+ module_init(foo_init);
-static void __exit foo_cleanup(void)
-{
+ static void __exit foo_cleanup(void)
+ {
i2c_del_driver(&foo_driver);
-}
-module_exit(foo_cleanup);
+ }
+ module_exit(foo_cleanup);
-The module_i2c_driver() macro can be used to reduce above code.
+ The module_i2c_driver() macro can be used to reduce above code.
-module_i2c_driver(foo_driver);
+ module_i2c_driver(foo_driver);
-Note that some functions are marked by `__init'. These functions can
+Note that some functions are marked by ``__init``. These functions can
be removed after kernel booting (or module loading) is completed.
-Likewise, functions marked by `__exit' are dropped by the compiler when
+Likewise, functions marked by ``__exit`` are dropped by the compiler when
the code is built into the kernel, as they would never be called.
Driver Information
==================
-/* Substitute your own name and email address */
-MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
-MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+::
-/* a few non-GPL license types are also allowed */
-MODULE_LICENSE("GPL");
+ /* Substitute your own name and email address */
+ MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+ MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+
+ /* a few non-GPL license types are also allowed */
+ MODULE_LICENSE("GPL");
Power Management
@@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C!
Plain I2C communication
-----------------------
+::
+
int i2c_master_send(struct i2c_client *client, const char *buf,
int count);
int i2c_master_recv(struct i2c_client *client, char *buf, int count);
@@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be
less than 64k since msg.len is u16.) Returned is the actual number of bytes
read/written.
+::
+
int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
int num);
@@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains
for each message the client address, the number of bytes of the message
and the message data itself.
-You can read the file `i2c-protocol' for more information about the
+You can read the file ``i2c-protocol`` for more information about the
actual I2C protocol.
SMBus communication
-------------------
+::
+
s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
unsigned short flags, char read_write, u8 command,
int size, union i2c_smbus_data *data);
@@ -357,6 +377,8 @@ SMBus communication
This is the generic SMBus function. All functions below are implemented
in terms of it. Never use this function directly!
+::
+
s32 i2c_smbus_read_byte(struct i2c_client *client);
s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
@@ -376,7 +398,7 @@ in terms of it. Never use this function directly!
const u8 *values);
These ones were removed from i2c-core because they had no users, but could
-be added back later if needed:
+be added back later if needed::
s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
s32 i2c_smbus_process_call(struct i2c_client *client,
@@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read
value, except for block transactions, which return the number of values
read. The block buffers need not be longer than 32 bytes.
-You can read the file `smbus-protocol' for more information about the
+You can read the file ``smbus-protocol`` for more information about the
actual SMBus protocol.
@@ -397,7 +419,7 @@ General purpose routines
========================
Below all general purpose routines are listed, that were not mentioned
-before.
+before::
/* Return the adapter number for a specific adapter */
int i2c_adapter_id(struct i2c_adapter *adap);
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 68ae2a4d689d..f6ee5333587d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -104,6 +104,7 @@ needed).
fb/index
fpga/index
hid/index
+ i2c/index
iio/index
infiniband/index
leds/index
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602
index a45702865a38..0feffd5af411 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602
@@ -17,7 +17,7 @@ kernel's SPI core subsystem.
The driver does not probe for supported chips, since the SI18IS602/603 does not
support Chip ID registers. You will have to instantiate the devices explicitly.
-Please see Documentation/i2c/instantiating-devices for details.
+Please see Documentation/i2c/instantiating-devices.rst for details.
Usage Notes
diff --git a/MAINTAINERS b/MAINTAINERS
index 15b58d5947a3..8fcb0c65ab91 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -666,7 +666,7 @@ ALI1563 I2C DRIVER
M: Rudolf Marek <r.marek@assembler.cz>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-ali1563
+F: Documentation/i2c/busses/i2c-ali1563.rst
F: drivers/i2c/busses/i2c-ali1563.c
ALLEGRO DVT VIDEO IP CORE DRIVER
@@ -6731,7 +6731,7 @@ L: linux-i2c@vger.kernel.org
S: Supported
F: drivers/i2c/muxes/i2c-mux-gpio.c
F: include/linux/platform_data/i2c-mux-gpio.h
-F: Documentation/i2c/muxes/i2c-mux-gpio
+F: Documentation/i2c/muxes/i2c-mux-gpio.rst
GENERIC HDLC (WAN) DRIVERS
M: Krzysztof Halasa <khc@pm.waw.pl>
@@ -7487,14 +7487,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU
M: Ajay Gupta <ajayg@nvidia.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-nvidia-gpu
+F: Documentation/i2c/busses/i2c-nvidia-gpu.rst
F: drivers/i2c/busses/i2c-nvidia-gpu.c
I2C MUXES
M: Peter Rosin <peda@axentia.se>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/i2c-topology
+F: Documentation/i2c/i2c-topology.rst
F: Documentation/i2c/muxes/
F: Documentation/devicetree/bindings/i2c/i2c-mux*
F: Documentation/devicetree/bindings/i2c/i2c-arb*
@@ -7514,8 +7514,8 @@ I2C OVER PARALLEL PORT
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-parport
-F: Documentation/i2c/busses/i2c-parport-light
+F: Documentation/i2c/busses/i2c-parport.rst
+F: Documentation/i2c/busses/i2c-parport-light.rst
F: drivers/i2c/busses/i2c-parport.c
F: drivers/i2c/busses/i2c-parport-light.c
@@ -7549,7 +7549,7 @@ I2C-TAOS-EVM DRIVER
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-taos-evm
+F: Documentation/i2c/busses/i2c-taos-evm.rst
F: drivers/i2c/busses/i2c-taos-evm.c
I2C-TINY-USB DRIVER
@@ -7563,19 +7563,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC
M: Jean Delvare <jdelvare@suse.com>
L: linux-i2c@vger.kernel.org
S: Maintained
-F: Documentation/i2c/busses/i2c-ali1535
-F: Documentation/i2c/busses/i2c-ali1563
-F: Documentation/i2c/busses/i2c-ali15x3
-F: Documentation/i2c/busses/i2c-amd756
-F: Documentation/i2c/busses/i2c-amd8111
-F: Documentation/i2c/busses/i2c-i801
-F: Documentation/i2c/busses/i2c-nforce2
-F: Documentation/i2c/busses/i2c-piix4
-F: Documentation/i2c/busses/i2c-sis5595
-F: Documentation/i2c/busses/i2c-sis630
-F: Documentation/i2c/busses/i2c-sis96x
-F: Documentation/i2c/busses/i2c-via
-F: Documentation/i2c/busses/i2c-viapro
+F: Documentation/i2c/busses/i2c-ali1535.rst
+F: Documentation/i2c/busses/i2c-ali1563.rst
+F: Documentation/i2c/busses/i2c-ali15x3.rst
+F: Documentation/i2c/busses/i2c-amd756.rst
+F: Documentation/i2c/busses/i2c-amd8111.rst
+F: Documentation/i2c/busses/i2c-i801.rst
+F: Documentation/i2c/busses/i2c-nforce2.rst
+F: Documentation/i2c/busses/i2c-piix4.rst
+F: Documentation/i2c/busses/i2c-sis5595.rst
+F: Documentation/i2c/busses/i2c-sis630.rst
+F: Documentation/i2c/busses/i2c-sis96x.rst
+F: Documentation/i2c/busses/i2c-via.rst
+F: Documentation/i2c/busses/i2c-viapro.rst
F: drivers/i2c/busses/i2c-ali1535.c
F: drivers/i2c/busses/i2c-ali1563.c
F: drivers/i2c/busses/i2c-ali15x3.c
@@ -7604,7 +7604,7 @@ M: Seth Heasley <seth.heasley@intel.com>
M: Neil Horman <nhorman@tuxdriver.com>
L: linux-i2c@vger.kernel.org
F: drivers/i2c/busses/i2c-ismt.c
-F: Documentation/i2c/busses/i2c-ismt
+F: Documentation/i2c/busses/i2c-ismt.rst
I2C/SMBUS STUB DRIVER
M: Jean Delvare <jdelvare@suse.com>
@@ -10345,7 +10345,7 @@ L: linux-i2c@vger.kernel.org
S: Supported
F: drivers/i2c/busses/i2c-mlxcpld.c
F: drivers/i2c/muxes/i2c-mux-mlxcpld.c
-F: Documentation/i2c/busses/i2c-mlxcpld
+F: Documentation/i2c/busses/i2c-mlxcpld.rst
MELLANOX MLXCPLD LED DRIVER
M: Vadim Pasternak <vadimp@mellanox.com>
@@ -11966,7 +11966,7 @@ M: Andrew Lunn <andrew@lunn.ch>
L: linux-i2c@vger.kernel.org
S: Maintained
F: Documentation/devicetree/bindings/i2c/i2c-ocores.txt
-F: Documentation/i2c/busses/i2c-ocores
+F: Documentation/i2c/busses/i2c-ocores.rst
F: drivers/i2c/busses/i2c-ocores.c
F: include/linux/platform_data/i2c-ocores.h
@@ -14271,7 +14271,7 @@ F: net/sctp/
SCx200 CPU SUPPORT
M: Jim Cromie <jim.cromie@gmail.com>
S: Odd Fixes
-F: Documentation/i2c/busses/scx200_acb
+F: Documentation/i2c/busses/scx200_acb.rst
F: arch/x86/platform/scx200/
F: drivers/watchdog/scx200_wdt.c
F: drivers/i2c/busses/scx200*
diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c
index e232fa948833..79b8df258371 100644
--- a/drivers/hwmon/atxp1.c
+++ b/drivers/hwmon/atxp1.c
@@ -5,7 +5,7 @@
*
* The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is
* not auto-detected by the driver and must be instantiated explicitly.
- * See Documentation/i2c/instantiating-devices for more information.
+ * See Documentation/i2c/instantiating-devices.rst for more information.
*/
#include <linux/kernel.h>
diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c
index d8c91c2cb8cf..9ae0dc28b9cf 100644
--- a/drivers/hwmon/smm665.c
+++ b/drivers/hwmon/smm665.c
@@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc)
if (rv != -ENXIO) {
/*
* We expect ENXIO to reflect NACK
- * (per Documentation/i2c/fault-codes).
+ * (per Documentation/i2c/fault-codes.rst).
* Everything else is an error.
*/
dev_dbg(&client->dev,
diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig
index abedd55a1264..1474e57ecafc 100644
--- a/drivers/i2c/Kconfig
+++ b/drivers/i2c/Kconfig
@@ -54,7 +54,7 @@ config I2C_CHARDEV
Say Y here to use i2c-* device files, usually found in the /dev
directory on your system. They make it possible to have user-space
programs use the I2C bus. Information on how to do this is
- contained in the file <file:Documentation/i2c/dev-interface>.
+ contained in the file <file:Documentation/i2c/dev-interface.rst>.
This support is also available as a module. If so, the module
will be called i2c-dev.
@@ -107,7 +107,7 @@ config I2C_STUB
especially for certain kinds of sensor chips.
If you do build this module, be sure to read the notes and warnings
- in <file:Documentation/i2c/i2c-stub>.
+ in <file:Documentation/i2c/i2c-stub.rst>.
If you don't know what to do here, definitely say N.
diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig
index 09367fc014c3..22fcf554257b 100644
--- a/drivers/i2c/busses/Kconfig
+++ b/drivers/i2c/busses/Kconfig
@@ -1206,7 +1206,7 @@ config I2C_PARPORT
and makes it easier to add support for new devices.
An adapter type parameter is now mandatory. Please read the file
- Documentation/i2c/busses/i2c-parport for details.
+ Documentation/i2c/busses/i2c-parport.rst for details.
Another driver exists, named i2c-parport-light, which doesn't depend
on the parport driver. This is meant for embedded systems. Don't say
diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c
index f2956936c3f2..c2f087d20420 100644
--- a/drivers/i2c/busses/i2c-i801.c
+++ b/drivers/i2c/busses/i2c-i801.c
@@ -77,7 +77,7 @@
* SMBus Host Notify yes
* Interrupt processing yes
*
- * See the file Documentation/i2c/busses/i2c-i801 for details.
+ * See the file Documentation/i2c/busses/i2c-i801.rst for details.
*/
#include <linux/interrupt.h>
diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c
index c82e78f57386..37347c93e8e0 100644
--- a/drivers/i2c/busses/i2c-taos-evm.c
+++ b/drivers/i2c/busses/i2c-taos-evm.c
@@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
/*
* Voluntarily dropping error code of kstrtou8 since all
* error code that it could return are invalid according
- * to Documentation/i2c/fault-codes.
+ * to Documentation/i2c/fault-codes.rst.
*/
if (kstrtou8(p + 1, 16, &data->byte))
return -EPROTO;
diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c
index f26ed495d384..2e6dcf8ecbc9 100644
--- a/drivers/i2c/i2c-core-base.c
+++ b/drivers/i2c/i2c-core-base.c
@@ -2206,7 +2206,7 @@ static int i2c_detect_address(struct i2c_client *temp_client,
dev_warn(&adapter->dev,
"This adapter will soon drop class based instantiation of devices. "
"Please make sure client 0x%02x gets instantiated by other means. "
- "Check 'Documentation/i2c/instantiating-devices' for details.\n",
+ "Check 'Documentation/i2c/instantiating-devices.rst' for details.\n",
info.addr);
dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n",
@@ -2236,7 +2236,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver)
if (adapter->class == I2C_CLASS_DEPRECATED) {
dev_dbg(&adapter->dev,
"This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. "
- "If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n",
+ "If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n",
driver->driver.name);
return 0;
}
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index 8f99c005458a..d28974ad9e0e 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
* Varies depending on bus type of the device. As there is no device
* here, call probe directly. For information on device registration
* i2c:
- * Documentation/i2c/writing-clients
+ * Documentation/i2c/writing-clients.rst
* spi:
* Documentation/spi/spi-summary
*/
diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
index 225a8df1d4e9..367497914c10 100644
--- a/drivers/rtc/rtc-ds1374.c
+++ b/drivers/rtc/rtc-ds1374.c
@@ -14,7 +14,7 @@
*/
/*
* It would be more efficient to use i2c msgs/i2c_transfer directly but, as
- * recommened in .../Documentation/i2c/writing-clients section
+ * recommended in .../Documentation/i2c/writing-clients.rst section
* "Sending and receiving", using SMBus level communication is preferred.
*/
diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index fa5552c2307b..c0a78c069117 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
*
* The return codes from the @master_xfer{_atomic} fields should indicate the
* type of error code that occurred during the transfer, as documented in the
- * Kernel Documentation file Documentation/i2c/fault-codes.
+ * Kernel Documentation file Documentation/i2c/fault-codes.rst.
*/
struct i2c_algorithm {
/*
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of docs
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (9 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Evgeniy Polyakov, linux-doc
The 1wire documentation was written with w1 developers in
mind, so, it makes sense to add it together with the driver-api
set.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/ABI/stable/sysfs-bus-w1 | 2 +-
.../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +-
.../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +-
Documentation/index.rst | 1 +
Documentation/w1/index.rst | 21 +++++
.../w1/masters/{ds2482 => ds2482.rst} | 16 +++-
.../w1/masters/{ds2490 => ds2490.rst} | 6 +-
Documentation/w1/masters/index.rst | 14 +++
.../w1/masters/{mxc-w1 => mxc-w1.rst} | 13 ++-
.../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +--
.../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +++--
Documentation/w1/slaves/index.rst | 16 ++++
.../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +-
.../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 ++
.../w1/slaves/{w1_ds2423 => w1_ds2423.rst} | 27 +++---
.../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 ++-
.../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 ++
.../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 ++--
.../w1/slaves/{w1_therm => w1_therm.rst} | 11 ++-
.../w1/{w1.generic => w1-generic.rst} | 88 ++++++++++--------
.../w1/{w1.netlink => w1-netlink.rst} | 89 +++++++++++--------
21 files changed, 263 insertions(+), 124 deletions(-)
create mode 100644 Documentation/w1/index.rst
rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
create mode 100644 Documentation/w1/masters/index.rst
rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
create mode 100644 Documentation/w1/slaves/index.rst
rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 140d85b4ae92..992dfb183ed0 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,6 @@ Description: Bus scanning interval, microseconds component.
control systems are attached/generate presence for as short as
100 ms - hence the tens-to-hundreds milliseconds scan intervals
are required.
- see Documentation/w1/w1.generic for detailed information.
+ see Documentation/w1/w1-generic.rst for detailed information.
Users: any user space application which wants to know bus scanning
interval
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee868c9..3e1c1fa8d54d 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the two PIO's of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
@@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom
Date: May 2012
Contact: Markus Franke <franm@hrz.tu-chemnitz.de>
Description: read/write the contents of the EEPROM memory of the DS28E04-100
- see Documentation/w1/slaves/w1_ds28e04 for detailed information
+ see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
Users: any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
index e928def14f28..534e63731a49 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -2,5 +2,5 @@ What: /sys/bus/w1/devices/.../w1_seq
Date: Apr 2015
Contact: Matt Campbell <mattrcampbell@gmail.com>
Description: Support for the DS28EA00 chain sequence function
- see Documentation/w1/slaves/w1_therm for detailed information
+ see Documentation/w1/slaves/w1_therm.rst for detailed information
Users: any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/index.rst b/Documentation/index.rst
index f6ee5333587d..e53c379dcb78 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ w1/index
watchdog/index
input/index
hwmon/index
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
new file mode 100644
index 000000000000..57cba81865e2
--- /dev/null
+++ b/Documentation/w1/index.rst
@@ -0,0 +1,21 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+ :maxdepth: 1
+
+
+ w1-generic.rst
+ w1-netlink.rst
+ masters/index
+ slaves/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst
similarity index 71%
rename from Documentation/w1/masters/ds2482
rename to Documentation/w1/masters/ds2482.rst
index 56f8edace6ac..17ebe8f660cd 100644
--- a/Documentation/w1/masters/ds2482
+++ b/Documentation/w1/masters/ds2482.rst
@@ -1,13 +1,19 @@
+====================
Kernel driver ds2482
====================
Supported chips:
+
* Maxim DS2482-100, Maxim DS2482-800
+
Prefix: 'ds2482'
+
Addresses scanned: None
+
Datasheets:
- http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
- http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+ - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
Author: Ben Gardner <bgardner@wabtec.com>
@@ -23,9 +29,11 @@ General Remarks
---------------
Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
However, the device cannot be detected without writing to the i2c bus, so no
detection is done. You should instantiate the device explicitly.
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
+ $ modprobe ds2482
+ $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst
similarity index 98%
rename from Documentation/w1/masters/ds2490
rename to Documentation/w1/masters/ds2490.rst
index 3e091151dd80..7e5b50f9c0f5 100644
--- a/Documentation/w1/masters/ds2490
+++ b/Documentation/w1/masters/ds2490.rst
@@ -1,7 +1,9 @@
+====================
Kernel driver ds2490
====================
Supported chips:
+
* Maxim DS2490 based
Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
low-level operational chip.
Notes and limitations.
+
- The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
- The 5V strong pullup is supported with a minimum of 5.9mA and a
maximum of 30.4 mA. (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
reattaching would clear the problem. usbmon output in the guest and
host did not explain the problem. My guess is a bug in either qemu
or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
+
+03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst
new file mode 100644
index 000000000000..4442a98850ad
--- /dev/null
+++ b/Documentation/w1/masters/index.rst
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+ :maxdepth: 1
+
+ ds2482
+ ds2490
+ mxc-w1
+ omap-hdq
+ w1-gpio
diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1.rst
similarity index 33%
rename from Documentation/w1/masters/mxc-w1
rename to Documentation/w1/masters/mxc-w1.rst
index 38be1ad65532..334f9893103f 100644
--- a/Documentation/w1/masters/mxc-w1
+++ b/Documentation/w1/masters/mxc-w1.rst
@@ -1,12 +1,17 @@
+====================
Kernel driver mxc_w1
====================
Supported chips:
+
* Freescale MX27, MX31 and probably other i.MX SoCs
+
Datasheets:
- http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
- Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-Author: Originally based on Freescale code, prepared for mainline by
+ - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+ - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+ Originally based on Freescale code, prepared for mainline by
Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst
similarity index 90%
rename from Documentation/w1/masters/omap-hdq
rename to Documentation/w1/masters/omap-hdq.rst
index 234522709a5f..345298a59e50 100644
--- a/Documentation/w1/masters/omap-hdq
+++ b/Documentation/w1/masters/omap-hdq.rst
@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
========================================
Supported chips:
================
- HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
A useful link about HDQ basics:
===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
Please note to load both the modules with a different ID if required, but note
that the ID used should be same for both master and slave driver loading.
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+ insmod omap_hdq.ko W1_ID=2
+ inamod w1_bq27000.ko F_ID=2
The driver also supports 1-wire mode. In this mode, there is no need to
pass slave ID as parameter. The driver will auto-detect slaves connected
diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst
similarity index 75%
rename from Documentation/w1/masters/w1-gpio
rename to Documentation/w1/masters/w1-gpio.rst
index 623961d9e83f..18fdb7366372 100644
--- a/Documentation/w1/masters/w1-gpio
+++ b/Documentation/w1/masters/w1-gpio.rst
@@ -1,3 +1,4 @@
+=====================
Kernel driver w1-gpio
=====================
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
Example (mach-at91)
-------------------
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+ #include <linux/gpio/machine.h>
+ #include <linux/w1-gpio.h>
+
+ static struct gpiod_lookup_table foo_w1_gpiod_table = {
.dev_id = "w1-gpio",
.table = {
GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
},
-};
+ };
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+ static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
.ext_pullup_enable_pin = -EINVAL,
-};
+ };
-static struct platform_device foo_w1_device = {
+ static struct platform_device foo_w1_device = {
.name = "w1-gpio",
.id = -1,
.dev.platform_data = &foo_w1_gpio_pdata,
-};
+ };
-...
+ ...
at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
gpiod_add_lookup_table(&foo_w1_gpiod_table);
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 000000000000..d0697b202f09
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ w1_ds2406
+ w1_ds2413
+ w1_ds2423
+ w1_ds2438
+ w1_ds28e04
+ w1_ds28e17
+ w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst
similarity index 96%
rename from Documentation/w1/slaves/w1_ds2406
rename to Documentation/w1/slaves/w1_ds2406.rst
index 8137fe6f6c3d..d3e68266084f 100644
--- a/Documentation/w1/slaves/w1_ds2406
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -1,7 +1,9 @@
+=======================
w1_ds2406 kernel driver
=======================
Supported chips:
+
* Maxim DS2406 (and other family 0x12) addressable switches
Author: Scott Alfter <scott@alfter.us>
@@ -9,7 +11,7 @@ Author: Scott Alfter <scott@alfter.us>
Description
-----------
-The w1_ds2406 driver allows connected devices to be switched on and off.
+The w1_ds2406 driver allows connected devices to be switched on and off.
These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
not supported. In TSOC-6 form, the DS2406 provides two switch outputs and
can be provided with power on a dedicated input. In TO-92 form, it provides
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst
similarity index 81%
rename from Documentation/w1/slaves/w1_ds2413
rename to Documentation/w1/slaves/w1_ds2413.rst
index 936263a8ccb4..c15bb5b919b7 100644
--- a/Documentation/w1/slaves/w1_ds2413
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -1,11 +1,16 @@
+=======================
Kernel driver w1_ds2413
=======================
Supported chips:
+
* Maxim DS2413 1-Wire Dual Channel Addressable Switch
supported family codes:
+
+ ================ ====
W1_FAMILY_DS2413 0x3A
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -20,11 +25,13 @@ Reading state
The "state" file provides one-byte value which is in the same format as for
the chip PIO_ACCESS_READ command (refer the datasheet for details):
+======== =============================================================
Bit 0: PIOA Pin State
Bit 1: PIOA Output Latch State
Bit 2: PIOB Pin State
Bit 3: PIOB Output Latch State
Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
This file is readonly.
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
It is writable, you can write one-byte value to this sysfs file.
Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
+======== ======================================
Bit 0: PIOA
Bit 1: PIOB
Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
The chip has some kind of basic protection against transmission errors.
diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423.rst
similarity index 48%
rename from Documentation/w1/slaves/w1_ds2423
rename to Documentation/w1/slaves/w1_ds2423.rst
index 3f98b505a0ee..755d659ad997 100644
--- a/Documentation/w1/slaves/w1_ds2423
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -2,10 +2,14 @@ Kernel driver w1_ds2423
=======================
Supported chips:
+
* Maxim DS2423 based counter devices.
supported family codes:
+
+ =============== ====
W1_THERM_DS2423 0x1D
+ =============== ====
Author: Mika Laitio <lamikr@pilppa.org>
@@ -26,6 +30,7 @@ If the operation was successful, there is also in the end of each line
a counter value expressed as an integer after c=
Meaning of 42 bytes represented is following:
+
- 1 byte from ram page
- 4 bytes for the counter value
- 4 zero bytes
@@ -34,14 +39,16 @@ Meaning of 42 bytes represented is following:
- crc=YES/NO indicating whether read was ok and crc matched
- c=<int> current counter value
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+example from the successful read::
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+ 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+ 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+ 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+ 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds2438
rename to Documentation/w1/slaves/w1_ds2438.rst
index e64f65a09387..a29309a3f8e5 100644
--- a/Documentation/w1/slaves/w1_ds2438
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
=======================
Supported chips:
+
* Maxim DS2438 Smart Battery Monitor
supported family codes:
+ ================ ====
W1_FAMILY_DS2438 0x26
+ ================ ====
Author: Mariusz Bialonczyk <manio@skyboo.net>
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
command of the chip.
Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+ general purpose A/D input (VAD)
+vdd:
+ battery input (VDD)
After the voltage conversion the value is returned as decimal ASCII.
Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds28e04
rename to Documentation/w1/slaves/w1_ds28e04.rst
index 7819b65cfa48..b12b118890d3 100644
--- a/Documentation/w1/slaves/w1_ds28e04
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e04
========================
Supported chips:
+
* Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E04 0x1C
+ ================= ====
Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst
similarity index 88%
rename from Documentation/w1/slaves/w1_ds28e17
rename to Documentation/w1/slaves/w1_ds28e17.rst
index 7fcfad5b4a37..e2d9f96d8f2c 100644
--- a/Documentation/w1/slaves/w1_ds28e17
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -1,11 +1,16 @@
+========================
Kernel driver w1_ds28e17
========================
Supported chips:
+
* Maxim DS28E17 1-Wire-to-I2C Master Bridge
supported family codes:
+
+ ================= ====
W1_FAMILY_DS28E17 0x19
+ ================= ====
Author: Jan Kandziora <jjj@gmx.de>
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
connected to a "native" I2C bus master.
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
- SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+ SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+ SYMLINK+="i2c-$attr{name}"
+
may be used to create stable /dev/i2c- entries based on the unique id of the
DS28E17 chip.
@@ -65,4 +70,3 @@ structure is created.
See https://github.com/ianka/w1_ds28e17 for even more information.
-
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst
similarity index 95%
rename from Documentation/w1/slaves/w1_therm
rename to Documentation/w1/slaves/w1_therm.rst
index d1f93af36f38..90531c340a07 100644
--- a/Documentation/w1/slaves/w1_therm
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -1,7 +1,9 @@
+======================
Kernel driver w1_therm
-====================
+======================
Supported chips:
+
* Maxim ds18*20 based temperature sensors.
* Maxim ds1825 based temperature sensors.
@@ -13,12 +15,16 @@ Description
w1_therm provides basic temperature conversion for ds18*20 devices, and the
ds28ea00 device.
-supported family codes:
+
+Supported family codes:
+
+==================== ====
W1_THERM_DS18S20 0x10
W1_THERM_DS1822 0x22
W1_THERM_DS18B20 0x28
W1_THERM_DS1825 0x3B
W1_THERM_DS28EA00 0x42
+==================== ====
Support is provided through the sysfs w1_slave file. Each open and
read sequence will initiate a temperature conversion then provide two
@@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup.
In case the detection of parasite devices using this command fails
(seems to be the case with some DS18S20) the strong pullup can
be force-enabled.
+
If the strong pullup is enabled, the master's strong pullup will be
driven when the conversion is taking place, provided the master driver
does support the strong pullup (or it falls back to a pullup
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst
similarity index 59%
rename from Documentation/w1/w1.generic
rename to Documentation/w1/w1-generic.rst
index c51b1ab012d0..da4e8b4e9b01 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1-generic.rst
@@ -1,5 +1,7 @@
-The 1-wire (w1) subsystem
-------------------------------------------------------------------
+=========================================
+Introduction to the 1-wire (w1) subsystem
+=========================================
+
The 1-wire bus is a simple master-slave bus that communicates via a single
signal wire (plus ground, so two wires).
@@ -12,14 +14,16 @@ communication with slaves.
All w1 slave devices must be connected to a w1 bus master device.
Example w1 master devices:
- DS9490 usb device
- W1-over-GPIO
- DS2482 (i2c to w1 bridge)
- Emulated devices, such as a RS232 converter, parallel port adapter, etc
+
+ - DS9490 usb device
+ - W1-over-GPIO
+ - DS2482 (i2c to w1 bridge)
+ - Emulated devices, such as a RS232 converter, parallel port adapter, etc
What does the w1 subsystem do?
-------------------------------------------------------------------
+------------------------------
+
When a w1 master driver registers with the w1 subsystem, the following occurs:
- sysfs entries for that w1 master are created
@@ -43,24 +47,28 @@ be read, since no device was selected.
W1 device families
-------------------------------------------------------------------
+------------------
+
Slave devices are handled by a driver written for a family of w1 devices.
A family driver populates a struct w1_family_ops (see w1_family.h) and
registers with the w1 subsystem.
Current family drivers:
-w1_therm - (ds18?20 thermal sensor family driver)
+
+w1_therm
+ - (ds18?20 thermal sensor family driver)
provides temperature reading function which is bound to ->rbin() method
of the above w1_family_ops structure.
-w1_smem - driver for simple 64bit memory cell provides ID reading method.
+w1_smem
+ - driver for simple 64bit memory cell provides ID reading method.
You can call above methods by reading appropriate sysfs files.
What does a w1 master driver need to implement?
-------------------------------------------------------------------
+-----------------------------------------------
The driver for w1 bus master must provide at minimum two functions.
@@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details.
w1 master sysfs interface
-------------------------------------------------------------------
-<xx-xxxxxxxxxxxx> - A directory for a found device. The format is family-serial
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-w1_master_add - (rw) manually register a slave device
-w1_master_attempts - (ro) the number of times a search was attempted
-w1_master_max_slave_count
- - (rw) maximum number of slaves to search for at a time
-w1_master_name - (ro) the name of the device (w1_bus_masterX)
-w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled
-w1_master_remove - (rw) manually remove a slave device
-w1_master_search - (rw) the number of searches left to do,
- -1=continual (default)
-w1_master_slave_count
- - (ro) the number of slaves found
-w1_master_slaves - (ro) the names of the slaves, one per line
-w1_master_timeout - (ro) the delay in seconds between searches
-w1_master_timeout_us
- - (ro) the delay in microseconds beetwen searches
+-------------------------
+
+========================= =====================================================
+<xx-xxxxxxxxxxxx> A directory for a found device. The format is
+ family-serial
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+w1_master_add (rw) manually register a slave device
+w1_master_attempts (ro) the number of times a search was attempted
+w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
+w1_master_name (ro) the name of the device (w1_bus_masterX)
+w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled
+w1_master_remove (rw) manually remove a slave device
+w1_master_search (rw) the number of searches left to do,
+ -1=continual (default)
+w1_master_slave_count (ro) the number of slaves found
+w1_master_slaves (ro) the names of the slaves, one per line
+w1_master_timeout (ro) the delay in seconds between searches
+w1_master_timeout_us (ro) the delay in microseconds beetwen searches
+========================= =====================================================
If you have a w1 bus that never changes (you don't add or remove devices),
you can set the module parameter search_count to a small positive number
@@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments
w1_master_attempts by 1.
w1 slave sysfs interface
-------------------------------------------------------------------
-bus - (standard) symlink to the w1 bus
-driver - (standard) symlink to the w1 driver
-name - the device name, usually the same as the directory name
-w1_slave - (optional) a binary file whose meaning depends on the
- family driver
-rw - (optional) created for slave devices which do not have
- appropriate family driver. Allows to read/write binary data.
+------------------------
+
+=================== ============================================================
+bus (standard) symlink to the w1 bus
+driver (standard) symlink to the w1 driver
+name the device name, usually the same as the directory name
+w1_slave (optional) a binary file whose meaning depends on the
+ family driver
+rw (optional) created for slave devices which do not have
+ appropriate family driver. Allows to read/write binary data.
+=================== ============================================================
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst
similarity index 77%
rename from Documentation/w1/w1.netlink
rename to Documentation/w1/w1-netlink.rst
index 94ad4c420828..aaa13243a5e4 100644
--- a/Documentation/w1/w1.netlink
+++ b/Documentation/w1/w1-netlink.rst
@@ -1,22 +1,26 @@
-Userspace communication protocol over connector [1].
+===============================================
+Userspace communication protocol over connector
+===============================================
-
-Message types.
+Message types
=============
There are three types of messages between w1 core and userspace:
+
1. Events. They are generated each time a new master or slave device
- is found either due to automatic or requested search.
+ is found either due to automatic or requested search.
2. Userspace commands.
3. Replies to userspace commands.
-Protocol.
+Protocol
========
-[struct cn_msg] - connector header.
+::
+
+ [struct cn_msg] - connector header.
Its length field is equal to size of the attached data
-[struct w1_netlink_msg] - w1 netlink header.
+ [struct w1_netlink_msg] - w1 netlink header.
__u8 type - message type.
W1_LIST_MASTERS
list current bus masters
@@ -40,7 +44,7 @@ Protocol.
} mst;
} id;
-[struct w1_netlink_cmd] - command for given master or slave device.
+ [struct w1_netlink_cmd] - command for given master or slave device.
__u8 cmd - command opcode.
W1_CMD_READ - read command
W1_CMD_WRITE - write command
@@ -71,18 +75,18 @@ when it is added to w1 core.
Currently replies to userspace commands are only generated for read
command request. One reply is generated exactly for one w1_netlink_cmd
read request. Replies are not combined when sent - i.e. typical reply
-messages looks like the following:
+messages looks like the following::
-[cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) +
+ [cn_msg][w1_netlink_msg][w1_netlink_cmd]
+ cn_msg.len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
cmd->len;
-w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
-w1_netlink_cmd.len = cmd->len;
+ w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
+ w1_netlink_cmd.len = cmd->len;
Replies to W1_LIST_MASTERS should send a message back to the userspace
which will contain list of all registered master ids in the following
-format:
+format::
cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
w1_netlink_msg) plus number of masters multiplied by 4)
@@ -90,39 +94,47 @@ format:
number of masters multiplied by 4 (u32 size))
id0 ... idN
- Each message is at most 4k in size, so if number of master devices
- exceeds this, it will be split into several messages.
+Each message is at most 4k in size, so if number of master devices
+exceeds this, it will be split into several messages.
W1 search and alarm search commands.
-request:
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
- id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
-reply:
+request::
+
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
+ id is equal to the bus master id to use for searching]
+ [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+
+reply::
+
[cn_msg, ack = 1 and increasing, 0 means the last message,
- seq is equal to the request seq]
+ seq is equal to the request seq]
[w1_netlink_msg type = W1_MASTER_CMD]
[w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
len is equal to number of IDs multiplied by 8]
[64bit-id0 ... 64bit-idN]
+
Length in each header corresponds to the size of the data behind it, so
w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
- Can be zero.
-w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
-cn_msg->len = sizeof(struct w1_netlink_msg) +
+Can be zero.
+
+::
+
+ w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+ cn_msg->len = sizeof(struct w1_netlink_msg) +
sizeof(struct w1_netlink_cmd) +
N*8;
-W1 reset command.
-[cn_msg]
- [w1_netlink_msg type = W1_MASTER_CMD
- id is equal to the bus master id to use for searching]
- [w1_netlink_cmd cmd = W1_CMD_RESET]
+W1 reset command::
+ [cn_msg]
+ [w1_netlink_msg type = W1_MASTER_CMD
+ id is equal to the bus master id to use for searching]
+ [w1_netlink_cmd cmd = W1_CMD_RESET]
-Command status replies.
+
+Command status replies
======================
Each command (either root, master or slave with or without w1_netlink_cmd
@@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
even if there were errors, only length mismatch interrupts message processing.
-Operation steps in w1 core when new command is received.
+Operation steps in w1 core when new command is received
=======================================================
When new message (w1_netlink_msg) is received w1 core detects if it is
@@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked
and next w1_netlink_msg header processing started.
-Connector [1] specific documentation.
+Connector [1] specific documentation
====================================
Each connector message includes two u32 fields as "address".
@@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and
acknowledge number is set to seq+1.
-Additional documantion, source code examples.
-============================================
+Additional documentation, source code examples
+==============================================
1. Documentation/driver-api/connector.rst
2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which uses
-read/write/search commands for all master/slave devices found on the bus.
+
+ This archive includes userspace application w1d.c which uses
+ read/write/search commands for all master/slave devices found on the bus.
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI bookset
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (10 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Mark Brown,
Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen,
Peter Meerwald-Stadler, linux-doc, linux-spi, linux-iio,
Jonathan Cameron
While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio
---
Documentation/index.rst | 1 +
.../spi/{butterfly => butterfly.rst} | 44 ++++----
Documentation/spi/index.rst | 22 ++++
Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 ++++++++--------
.../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 ++-
.../spi/{spi-sc18is602 => spi-sc18is602.rst} | 3 +
.../spi/{spi-summary => spi-summary.rst} | 105 ++++++++++--------
Documentation/spi/{spidev => spidev.rst} | 30 +++--
drivers/iio/dummy/iio_simple_dummy.c | 2 +-
drivers/spi/Kconfig | 2 +-
drivers/spi/spi-butterfly.c | 2 +-
drivers/spi/spi-lm70llp.c | 2 +-
include/linux/platform_data/sc18is602.h | 2 +-
13 files changed, 198 insertions(+), 129 deletions(-)
rename Documentation/spi/{butterfly => butterfly.rst} (71%)
create mode 100644 Documentation/spi/index.rst
rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
rename Documentation/spi/{spidev => spidev.rst} (90%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e53c379dcb78..d9e607d8a9b9 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
power/index
target/index
timers/index
+ spi/index
w1/index
watchdog/index
input/index
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
similarity index 71%
rename from Documentation/spi/butterfly
rename to Documentation/spi/butterfly.rst
index 9927af7a629c..e614a589547c 100644
--- a/Documentation/spi/butterfly
+++ b/Documentation/spi/butterfly.rst
@@ -1,3 +1,4 @@
+===================================================
spi_butterfly - parport-to-butterfly adapter driver
===================================================
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
connector pins (used also on non-Butterfly AVR boards). On the parport
side this is like "sp12" programming cables.
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PB1/SCK = pin 2/D0
- RESET = J403.nRST = pin 3/D1
- VCC = J403.VCC_EXT = pin 8/D6
- MOSI = J403.PB2/MOSI = pin 9/D7
- MISO = J403.PB3/MISO = pin 11/S7,nBUSY
- GND = J403.GND = pin 23/GND
+ ====== ============= ===================
+ SCK J403.PB1/SCK pin 2/D0
+ RESET J403.nRST pin 3/D1
+ VCC J403.VCC_EXT pin 8/D6
+ MOSI J403.PB2/MOSI pin 9/D7
+ MISO J403.PB3/MISO pin 11/S7,nBUSY
+ GND J403.GND pin 23/GND
+ ====== ============= ===================
Then to let Linux master that bus to talk to the DataFlash chip, you must
(a) flash new firmware that disables SPI (set PRR.2, and disable pullups
by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
(c) cable in the chipselect.
+ ====== ============ ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- VCC = J400.VCC_EXT = pin 7/D5
- SELECT = J400.PB0/nSS = pin 17/C3,nSELECT
- GND = J400.GND = pin 24/GND
+ ====== ============ ===================
+ VCC J400.VCC_EXT pin 7/D5
+ SELECT J400.PB0/nSS pin 17/C3,nSELECT
+ GND J400.GND pin 24/GND
+ ====== ============ ===================
Or you could flash firmware making the AVR into an SPI slave (keeping the
DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
while letting either Linux or the AVR use the DataFlash. There are plenty
of spare parport pins to wire this one up, such as:
+ ====== ============= ===================
Signal Butterfly Parport (DB-25)
- ------ --------- ---------------
- SCK = J403.PE4/USCK = pin 5/D3
- MOSI = J403.PE5/DI = pin 6/D4
- MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT
- GND = J403.GND = pin 22/GND
-
- IRQ = J402.PF4 = pin 10/S6,ACK
- GND = J402.GND(P2) = pin 25/GND
+ ====== ============= ===================
+ SCK J403.PE4/USCK pin 5/D3
+ MOSI J403.PE5/DI pin 6/D4
+ MISO J403.PE6/DO pin 12/S5,nPAPEROUT
+ GND J403.GND pin 22/GND
+ IRQ J402.PF4 pin 10/S6,ACK
+ GND J402.GND(P2) pin 25/GND
+ ====== ============= ===================
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
new file mode 100644
index 000000000000..06c34ea11bcf
--- /dev/null
+++ b/Documentation/spi/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+ :maxdepth: 1
+
+ spi-summary
+ spidev
+ butterfly
+ pxa2xx
+ spi-lm70llp
+ spi-sc18is602
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
similarity index 83%
rename from Documentation/spi/pxa2xx
rename to Documentation/spi/pxa2xx.rst
index 551325b66b23..882d3cc72cc2 100644
--- a/Documentation/spi/pxa2xx
+++ b/Documentation/spi/pxa2xx.rst
@@ -1,8 +1,10 @@
+==============================
PXA2xx SPI on SSP driver HOWTO
-===================================================
+==============================
+
This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx
synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
+(see Documentation/spi/spi-summary.rst). The driver has the following features
- Support for any PXA2xx SSP
- SSP PIO and SSP DMA data transfers.
@@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
-----------------------------------
Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
"platform device". The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
+found in include/linux/spi/pxa2xx_spi.h::
-struct pxa2xx_spi_controller {
+ struct pxa2xx_spi_controller {
u16 num_chipselect;
u8 enable_dma;
-};
+ };
The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
slave device (chips) attached to this SPI master.
@@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
NSSP MASTER SAMPLE
------------------
-Below is a sample configuration using the PXA255 NSSP.
+Below is a sample configuration using the PXA255 NSSP::
-static struct resource pxa_spi_nssp_resources[] = {
+ static struct resource pxa_spi_nssp_resources[] = {
[0] = {
.start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
.end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
@@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
.end = IRQ_NSSP,
.flags = IORESOURCE_IRQ,
},
-};
+ };
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+ static struct pxa2xx_spi_controller pxa_nssp_master_info = {
.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
.enable_dma = 1, /* Enables NSSP DMA */
-};
+ };
-static struct platform_device pxa_spi_nssp = {
+ static struct platform_device pxa_spi_nssp = {
.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
.resource = pxa_spi_nssp_resources,
@@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
.dev = {
.platform_data = &pxa_nssp_master_info, /* Passed to driver */
},
-};
+ };
-static struct platform_device *devices[] __initdata = {
+ static struct platform_device *devices[] __initdata = {
&pxa_spi_nssp,
-};
+ };
-static void __init board_init(void)
-{
+ static void __init board_init(void)
+ {
(void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
+ }
Declaring Slave Devices
-----------------------
Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
+"Documentation/spi/spi-summary.rst" for additional information.
Each slave device attached to the PXA must provide slave specific configuration
information via the structure "pxa2xx_spi_chip" found in
@@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
will uses the configuration whenever the driver communicates with the slave
device. All fields are optional.
-struct pxa2xx_spi_chip {
+::
+
+ struct pxa2xx_spi_chip {
u8 tx_threshold;
u8 rx_threshold;
u8 dma_burst_size;
u32 timeout;
u8 enable_loopback;
void (*cs_control)(u32 command);
-};
+ };
The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
used to configure the SSP hardware fifo. These fields are critical to the
performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
+fifo overruns (especially in PIO mode transfers). Good default values are::
.tx_threshold = 8,
.rx_threshold = 8,
@@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
"spi_board_info.controller_data" field. Below is a sample configuration using
the PXA255 NSSP.
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
+::
+
+ /* Chip Select control for the CS8415A SPI slave device */
+ static void cs8415a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(2) = GPIO_bit(2);
else
GPSR(2) = GPIO_bit(2);
-}
+ }
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
+ /* Chip Select control for the CS8405A SPI slave device */
+ static void cs8405a_cs_control(u32 command)
+ {
if (command & PXA2XX_CS_ASSERT)
GPCR(3) = GPIO_bit(3);
else
GPSR(3) = GPIO_bit(3);
-}
+ }
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
+ static struct pxa2xx_spi_chip cs8415a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8415a_cs_control, /* Use external chip select */
-};
+ };
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
+ static struct pxa2xx_spi_chip cs8405a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8405a_cs_control, /* Use external chip select */
-};
+ };
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
{
.modalias = "cs8415a", /* Name of spi_driver for this device */
.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
@@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
.controller_data = &cs8405a_chip_info, /* Master chip config */
.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
},
-};
+ };
-static void __init streetracer_init(void)
-{
+ static void __init streetracer_init(void)
+ {
spi_register_board_info(streetracer_spi_board_info,
ARRAY_SIZE(streetracer_spi_board_info));
-}
+ }
DMA and PIO I/O Support
@@ -210,26 +216,25 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The
mode supports both coherent and stream based DMA mappings.
The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
+a per "spi_transfer" basis::
-if !enable_dma then
+ if !enable_dma then
always use PIO transfers
-if spi_message.len > 8191 then
+ if spi_message.len > 8191 then
print "rate limited" warning
use PIO transfers
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+ if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
use coherent DMA mode
-if rx_buf and tx_buf are aligned on 8 byte boundary then
+ if rx_buf and tx_buf are aligned on 8 byte boundary then
use streaming DMA mode
-otherwise
+ otherwise
use PIO transfer
THANKS TO
---------
David Brownell and others for mentoring the development of this driver.
-
diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
similarity index 88%
rename from Documentation/spi/spi-lm70llp
rename to Documentation/spi/spi-lm70llp.rst
index 463f6d01fa15..07631aef4343 100644
--- a/Documentation/spi/spi-lm70llp
+++ b/Documentation/spi/spi-lm70llp.rst
@@ -1,8 +1,11 @@
+==============================================
spi_lm70llp : LM70-LLP parport-to-SPI adapter
==============================================
Supported board/chip:
+
* National Semiconductor LM70 LLP evaluation board
+
Datasheet: http://www.national.com/pf/LM/LM70.html
Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
The hardware interfacing on the LM70 LLP eval board is as follows:
+ ======== == ========= ==========
Parallel LM70 LLP
- Port Direction JP2 Header
- ----------- --------- ----------------
+ Port . Direction JP2 Header
+ ======== == ========= ==========
D0 2 - -
D1 3 --> V+ 5
D2 4 --> V+ 5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
D7 9 --> SI/O 5
GND 25 - GND 7
Select 13 <-- SI/O 1
- ----------- --------- ----------------
+ ======== == ========= ==========
Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
Thanks to
---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
similarity index 97%
rename from Documentation/spi/spi-sc18is602
rename to Documentation/spi/spi-sc18is602.rst
index 0feffd5af411..2a31dc722321 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -1,8 +1,11 @@
+===========================
Kernel driver spi-sc18is602
===========================
Supported chips:
+
* NXP SI18IS602/602B/603
+
Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
Author:
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
similarity index 93%
rename from Documentation/spi/spi-summary
rename to Documentation/spi/spi-summary.rst
index 1a63194b74d7..f1daffe10d78 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary.rst
@@ -1,3 +1,4 @@
+====================================
Overview of Linux kernel SPI support
====================================
@@ -139,12 +140,14 @@ a command and then reading its response.
There are two types of SPI driver, here called:
- Controller drivers ... controllers may be built into System-On-Chip
+ Controller drivers ...
+ controllers may be built into System-On-Chip
processors, and often support both Master and Slave roles.
These drivers touch hardware registers and may use DMA.
Or they can be PIO bitbangers, needing just GPIO pins.
- Protocol drivers ... these pass messages through the controller
+ Protocol drivers ...
+ these pass messages through the controller
driver to communicate with a Slave or Master device on the
other side of an SPI link.
@@ -160,7 +163,7 @@ those two types of drivers.
There is a minimal core of SPI programming interfaces, focussing on
using the driver model to connect controller and protocol drivers using
device tables provided by board specific initialization code. SPI
-shows up in sysfs in several locations:
+shows up in sysfs in several locations::
/sys/devices/.../CTLR ... physical node for a given SPI controller
@@ -168,7 +171,7 @@ shows up in sysfs in several locations:
chipselect C, accessed through CTLR.
/sys/bus/spi/devices/spiB.C ... symlink to that physical
- .../CTLR/spiB.C device
+ .../CTLR/spiB.C device
/sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
that should be used with this device (for hotplug/coldplug)
@@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
That information is normally provided by board-specific code, even for
chips that do support some of automated discovery/enumeration.
-DECLARE CONTROLLERS
+Declare Controllers
+^^^^^^^^^^^^^^^^^^^
The first kind of information is a list of what SPI controllers exist.
For System-on-Chip (SOC) based boards, these will usually be platform
@@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several
SPI-capable controllers, and only the ones actually usable on a given
board should normally be set up and registered.
-So for example arch/.../mach-*/board-*.c files might have code like:
+So for example arch/.../mach-*/board-*.c files might have code like::
#include <mach/spi.h> /* for mysoc_spi_data */
@@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
...
}
-And SOC-specific utility code might look something like:
+And SOC-specific utility code might look something like::
#include <mach/spi.h>
@@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use
an external clock, where another derives the SPI clock from current
settings of some master clock.
-
-DECLARE SLAVE DEVICES
+Declare Slave Devices
+^^^^^^^^^^^^^^^^^^^^^
The second kind of information is a list of what SPI slave devices exist
on the target board, often with some board-specific data needed for the
@@ -278,7 +282,7 @@ driver to work correctly.
Normally your arch/.../mach-*/board-*.c files would provide a small table
listing the SPI devices on each board. (This would typically be only a
-small handful.) That might look like:
+small handful.) That might look like::
static struct ads7846_platform_data ads_info = {
.vref_delay_usecs = 100,
@@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
Then your board initialization code would register that table with the SPI
infrastructure, so that it's available later when the SPI master controller
-driver is registered:
+driver is registered::
spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
@@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
The widely used "card" style computers bundle memory, cpu, and little else
onto a card that's maybe just thirty square centimeters. On such systems,
-your arch/.../mach-.../board-*.c file would primarily provide information
+your ``arch/.../mach-.../board-*.c`` file would primarily provide information
about the devices on the mainboard into which such a card is plugged. That
certainly includes SPI devices hooked up through the card connectors!
-NON-STATIC CONFIGURATIONS
+Non-static Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^
Developer boards often play by different rules than product boards, and one
example is the potential need to hotplug SPI devices and/or controllers.
@@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
Most SPI drivers are currently kernel drivers, but there's also support
for userspace drivers. Here we talk only about kernel drivers.
-SPI protocol drivers somewhat resemble platform device drivers:
+SPI protocol drivers somewhat resemble platform device drivers::
static struct spi_driver CHIP_driver = {
.driver = {
@@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code
might look like this unless you're creating a device which is managing
a bus (appearing under /sys/class/spi_master).
+::
+
static int CHIP_probe(struct spi_device *spi)
{
struct CHIP *chip;
@@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
to get the driver-private data allocated for that device.
+::
+
struct spi_master *master;
struct CONTROLLER *c;
@@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
will reverse the effect of spi_register_master().
-BUS NUMBERING
+Bus Numbering
+^^^^^^^^^^^^^
Bus numbering is important, since that's how Linux identifies a given
SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
@@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
this as a non-static configuration (see above).
-SPI MASTER METHODS
+SPI Master Methods
+^^^^^^^^^^^^^^^^^^
- master->setup(struct spi_device *spi)
+``master->setup(struct spi_device *spi)``
This sets up the device clock rate, SPI mode, and word sizes.
Drivers may change the defaults provided by board_info, and then
call spi_setup(spi) to invoke this routine. It may sleep.
@@ -528,37 +539,37 @@ SPI MASTER METHODS
change them right away ... otherwise drivers could corrupt I/O
that's in progress for other SPI devices.
- ** BUG ALERT: for some reason the first version of
- ** many spi_master drivers seems to get this wrong.
- ** When you code setup(), ASSUME that the controller
- ** is actively processing transfers for another device.
+ .. note::
- master->cleanup(struct spi_device *spi)
+ BUG ALERT: for some reason the first version of
+ many spi_master drivers seems to get this wrong.
+ When you code setup(), ASSUME that the controller
+ is actively processing transfers for another device.
+
+``master->cleanup(struct spi_device *spi)``
Your controller driver may use spi_device.controller_state to hold
state it dynamically associates with that device. If you do that,
be sure to provide the cleanup() method to free that state.
- master->prepare_transfer_hardware(struct spi_master *master)
+``master->prepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that a message is coming in soon, so the subsystem requests the
driver to prepare the transfer hardware by issuing this call.
This may sleep.
- master->unprepare_transfer_hardware(struct spi_master *master)
+``master->unprepare_transfer_hardware(struct spi_master *master)``
This will be called by the queue mechanism to signal to the driver
that there are no more messages pending in the queue and it may
relax the hardware (e.g. by power management calls). This may sleep.
- master->transfer_one_message(struct spi_master *master,
- struct spi_message *mesg)
+``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
The subsystem calls the driver to transfer a single message while
queuing transfers that arrive in the meantime. When the driver is
finished with this message, it must call
spi_finalize_current_message() so the subsystem can issue the next
message. This may sleep.
- master->transfer_one(struct spi_master *master, struct spi_device *spi,
- struct spi_transfer *transfer)
+``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
The subsystem calls the driver to transfer a single transfer while
queuing transfers that arrive in the meantime. When the driver is
finished with this transfer, it must call
@@ -568,19 +579,20 @@ SPI MASTER METHODS
not call your transfer_one callback.
Return values:
- negative errno: error
- 0: transfer is finished
- 1: transfer is still in progress
- master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
- u8 hold_clk_cycles, u8 inactive_clk_cycles)
+ * negative errno: error
+ * 0: transfer is finished
+ * 1: transfer is still in progress
+
+``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
This method allows SPI client drivers to request SPI master controller
for configuring device specific CS setup, hold and inactive timing
requirements.
- DEPRECATED METHODS
+Deprecated Methods
+^^^^^^^^^^^^^^^^^^
- master->transfer(struct spi_device *spi, struct spi_message *message)
+``master->transfer(struct spi_device *spi, struct spi_message *message)``
This must not sleep. Its responsibility is to arrange that the
transfer happens and its complete() callback is issued. The two
will normally happen later, after other transfers complete, and
@@ -590,7 +602,8 @@ SPI MASTER METHODS
implemented.
-SPI MESSAGE QUEUE
+SPI Message Queue
+^^^^^^^^^^^^^^^^^
If you are happy with the standard queueing mechanism provided by the
SPI subsystem, just implement the queued methods specified above. Using
@@ -619,13 +632,13 @@ THANKS TO
Contributors to Linux-SPI discussions include (in alphabetical order,
by last name):
-Mark Brown
-David Brownell
-Russell King
-Grant Likely
-Dmitry Pervushin
-Stephen Street
-Mark Underwood
-Andrew Victor
-Linus Walleij
-Vitaly Wool
+- Mark Brown
+- David Brownell
+- Russell King
+- Grant Likely
+- Dmitry Pervushin
+- Stephen Street
+- Mark Underwood
+- Andrew Victor
+- Linus Walleij
+- Vitaly Wool
diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
similarity index 90%
rename from Documentation/spi/spidev
rename to Documentation/spi/spidev.rst
index 3d14035b1766..f05dbc5ccdbc 100644
--- a/Documentation/spi/spidev
+++ b/Documentation/spi/spidev.rst
@@ -1,7 +1,13 @@
+=================
+SPI userspace API
+=================
+
SPI devices have a limited userspace API, supporting basic half-duplex
read() and write() access to SPI slave devices. Using ioctl() requests,
full duplex transfers and device I/O configuration are also available.
+::
+
#include <fcntl.h>
#include <unistd.h>
#include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
busybox; it's less featureful, but often enough.) For a SPI device with
chipselect C on bus B, you should see:
- /dev/spidevB.C ... character special device, major number 153 with
+ /dev/spidevB.C ...
+ character special device, major number 153 with
a dynamically chosen minor device number. This is the node
that userspace programs will open, created by "udev" or "mdev".
- /sys/devices/.../spiB.C ... as usual, the SPI device node will
+ /sys/devices/.../spiB.C ...
+ as usual, the SPI device node will
be a child of its SPI master controller.
- /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+ /sys/class/spidev/spidevB.C ...
+ created when the "spidev" driver
binds to that device. (Directory or symlink, based on whether
or not you enabled the "deprecated sysfs files" Kconfig option.)
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
Several ioctl() requests let your driver read or override the device's current
settings for data transfer parameters:
- SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+ SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+ pass a pointer to a byte which will
return (RD) or assign (WR) the SPI transfer mode. Use the constants
SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
Note that this request is limited to SPI mode flags that fit in a
single byte.
- SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+ SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+ pass a pointer to a uin32_t
which will return (RD) or assign (WR) the full SPI transfer mode,
not limited to the bits that fit in one byte.
- SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+ SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+ pass a pointer to a byte
which will return (RD) or assign (WR) the bit justification used to
transfer SPI words. Zero indicates MSB-first; other values indicate
the less common LSB-first encoding. In both cases the specified value
is right-justified in each word, so that unused (TX) or undefined (RX)
bits are in the MSBs.
- SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+ SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+ pass a pointer to
a byte which will return (RD) or assign (WR) the number of bits in
each SPI transfer word. The value zero signifies eight bits.
- SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+ SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+ pass a pointer to a
u32 which will return (RD) or assign (WR) the maximum SPI transfer
speed, in Hz. The controller can't necessarily assign that specific
clock speed.
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index d28974ad9e0e..6cb02299a215 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
* i2c:
* Documentation/i2c/writing-clients.rst
* spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
*/
static const struct iio_sw_device_ops iio_dummy_device_ops = {
.probe = iio_dummy_probe,
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index 3a1d8f1170de..d5a24fe983e7 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -543,7 +543,7 @@ config SPI_PXA2XX
help
This enables using a PXA2xx or Sodaville SSP port as a SPI master
controller. The driver can be configured to use any SSP port and
- additional documentation can be found a Documentation/spi/pxa2xx.
+ additional documentation can be found a Documentation/spi/pxa2xx.rst.
config SPI_PXA2XX_PCI
def_tristate SPI_PXA2XX && PCI && COMMON_CLK
diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
index 8c77d1114ad3..7e71a351f3b7 100644
--- a/drivers/spi/spi-butterfly.c
+++ b/drivers/spi/spi-butterfly.c
@@ -23,7 +23,7 @@
* with a battery powered AVR microcontroller and lots of goodies. You
* can use GCC to develop firmware for this.
*
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
* and use this custom parallel port cable.
*/
diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
index f18f912c9dea..174dba29b1dd 100644
--- a/drivers/spi/spi-lm70llp.c
+++ b/drivers/spi/spi-lm70llp.c
@@ -34,7 +34,7 @@
* available (on page 4) here:
* http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
*
- * Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is
* (heavily) based on spi-butterfly by David Brownell.
*
* The LM70 LLP connects to the PC parallel port in the following manner:
diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
index e066d3b0d6d8..0e91489edfe6 100644
--- a/include/linux/platform_data/sc18is602.h
+++ b/include/linux/platform_data/sc18is602.h
@@ -4,7 +4,7 @@
*
* Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
*
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
*/
/**
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 09/26] docs: ipmb: place it at driver-api and convert to ReST
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (11 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
No new doc should be added at the main Documentation/ directory.
Instead, new docs should be added as ReST files, within the
Kernel documentation body.
Fixes: 51bd6f291583 ("Add support for IPMB driver")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/driver-api/index.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 37ac052ded85..38e638abe3eb 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -76,6 +76,7 @@ available subsections can be seen below.
dell_rbu
edid
eisa
+ ipmb
isa
isapnp
generic-counter
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 10/26] docs: packing: move it to core-api book and adjust markups
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (12 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vladimir Oltean,
linux-doc, netdev, Mike Rapoport
The packing.txt file was misplaced, as docs should be part of
a documentation book, and not at the root dir.
So, move it to the core-api directory and add to its index.
Also, ensure that the file will be properly parsed and the bitmap
ascii artwork will use a monotonic font.
Fixes: 554aae35007e ("lib: Add support for generic packing operations")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Vladimir Oltean <olteanv@gmail.com>
Tested-by: Vladimir Oltean <olteanv@gmail.com>
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
---
Documentation/core-api/index.rst | 1 +
.../{packing.txt => core-api/packing.rst} | 81 +++++++++++--------
MAINTAINERS | 2 +-
3 files changed, 51 insertions(+), 33 deletions(-)
rename Documentation/{packing.txt => core-api/packing.rst} (61%)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index da0ed972d224..dfd8fad1e1ec 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -25,6 +25,7 @@ Core utilities
librs
genalloc
errseq
+ packing
printk-formats
circular-buffers
generic-radix-tree
diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
similarity index 61%
rename from Documentation/packing.txt
rename to Documentation/core-api/packing.rst
index f830c98645f1..d8c341fe383e 100644
--- a/Documentation/packing.txt
+++ b/Documentation/core-api/packing.rst
@@ -30,6 +30,7 @@ The solution
------------
This API deals with 2 basic operations:
+
- Packing a CPU-usable number into a memory buffer (with hardware
constraints/quirks)
- Unpacking a memory buffer (which has hardware constraints/quirks)
@@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
1. Normally (no quirks), we would do it like this:
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
+::
+
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
LSByte (0) of the u64 sits at memory offset 7.
@@ -63,10 +66,12 @@ comments as "logical" notation.
2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
+::
+
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
inverts bit offsets inside a byte.
@@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
+::
+
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
byte from each 4-byte word is placed at its mirrored position compared to
@@ -86,18 +93,22 @@ the boundary of that word.
4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
like this:
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
+::
+
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
-3 2 1 0
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7 6 5 4
+::
+
+ 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
+ 3 2 1 0
+ 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+ 7 6 5 4
In this case the 8 byte memory region is interpreted as follows: first
4 bytes correspond to the least significant 4-byte word, next 4 bytes to
@@ -107,28 +118,34 @@ the more significant 4-byte word.
6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
this:
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
-3 2 1 0
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7 6 5 4
+::
+
+ 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7
+ 3 2 1 0
+ 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+ 7 6 5 4
7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
this:
-7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0 1 2 3
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4 5 6 7
+::
+
+ 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+ 0 1 2 3
+ 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+ 4 5 6 7
8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
are set, it looks like this:
-0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0 1 2 3
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4 5 6 7
+::
+
+ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+ 0 1 2 3
+ 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+ 4 5 6 7
We always think of our offsets as if there were no quirk, and we translate
diff --git a/MAINTAINERS b/MAINTAINERS
index 8fcb0c65ab91..e5593c66f904 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12089,7 +12089,7 @@ L: netdev@vger.kernel.org
S: Supported
F: lib/packing.c
F: include/linux/packing.h
-F: Documentation/packing.txt
+F: Documentation/core-api/packing.rst
PADATA PARALLEL EXECUTION MECHANISM
M: Steffen Klassert <steffen.klassert@secunet.com>
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 11/26] docs: admin-guide: add auxdisplay files to it after conversion to ReST
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (13 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Miguel Ojeda Sandonis, linux-doc
Those two files describe userspace-faced information. While part of
it might fit on uAPI, it sounds to me that the admin guide is the
best place for them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
---
.../auxdisplay/cfag12864b.rst} | 115 ++++++++----------
.../admin-guide/auxdisplay/index.rst | 16 +++
.../auxdisplay/ks0108.rst} | 53 ++++----
Documentation/admin-guide/index.rst | 1 +
MAINTAINERS | 2 +-
drivers/auxdisplay/Kconfig | 2 +-
6 files changed, 97 insertions(+), 92 deletions(-)
rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
similarity index 26%
rename from Documentation/auxdisplay/cfag12864b
rename to Documentation/admin-guide/auxdisplay/cfag12864b.rst
index 12fd51b8de75..18c2865bd322 100644
--- a/Documentation/auxdisplay/cfag12864b
+++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
@@ -1,92 +1,85 @@
- ===================================
- cfag12864b LCD Driver Documentation
- ===================================
+===================================
+cfag12864b LCD Driver Documentation
+===================================
-License: GPLv2
-Author & Maintainer: Miguel Ojeda Sandonis
-Date: 2006-10-27
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda Sandonis
+:Date: 2006-10-27
---------
-0. INDEX
---------
+.. INDEX
1. DRIVER INFORMATION
2. DEVICE INFORMATION
3. WIRING
4. USERSPACE PROGRAMMING
-
----------------------
-1. DRIVER INFORMATION
+1. Driver Information
---------------------
This driver supports a cfag12864b LCD.
----------------------
-2. DEVICE INFORMATION
+2. Device Information
---------------------
-Manufacturer: Crystalfontz
-Device Name: Crystalfontz 12864b LCD Series
-Device Code: cfag12864b
-Webpage: http://www.crystalfontz.com
-Device Webpage: http://www.crystalfontz.com/products/12864b/
-Type: LCD (Liquid Crystal Display)
-Width: 128
-Height: 64
-Colors: 2 (B/N)
-Controller: ks0108
-Controllers: 2
-Pages: 8 each controller
-Addresses: 64 each page
-Data size: 1 byte each address
-Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
+:Manufacturer: Crystalfontz
+:Device Name: Crystalfontz 12864b LCD Series
+:Device Code: cfag12864b
+:Webpage: http://www.crystalfontz.com
+:Device Webpage: http://www.crystalfontz.com/products/12864b/
+:Type: LCD (Liquid Crystal Display)
+:Width: 128
+:Height: 64
+:Colors: 2 (B/N)
+:Controller: ks0108
+:Controllers: 2
+:Pages: 8 each controller
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
----------
-3. WIRING
+3. Wiring
---------
The cfag12864b LCD Series don't have official wiring.
-The common wiring is done to the parallel port as shown:
+The common wiring is done to the parallel port as shown::
-Parallel Port cfag12864b
+ Parallel Port cfag12864b
- Name Pin# Pin# Name
+ Name Pin# Pin# Name
-Strobe ( 1)------------------------------(17) Enable
-Data 0 ( 2)------------------------------( 4) Data 0
-Data 1 ( 3)------------------------------( 5) Data 1
-Data 2 ( 4)------------------------------( 6) Data 2
-Data 3 ( 5)------------------------------( 7) Data 3
-Data 4 ( 6)------------------------------( 8) Data 4
-Data 5 ( 7)------------------------------( 9) Data 5
-Data 6 ( 8)------------------------------(10) Data 6
-Data 7 ( 9)------------------------------(11) Data 7
- (10) [+5v]---( 1) Vdd
- (11) [GND]---( 2) Ground
- (12) [+5v]---(14) Reset
- (13) [GND]---(15) Read / Write
- Line (14)------------------------------(13) Controller Select 1
- (15)
- Init (16)------------------------------(12) Controller Select 2
-Select (17)------------------------------(16) Data / Instruction
-Ground (18)---[GND] [+5v]---(19) LED +
-Ground (19)---[GND]
-Ground (20)---[GND] E A Values:
-Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
-Ground (22)---[GND] | - P1 = Preset = 10 Kohm
-Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
-Ground (24)---[GND] | |
-Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
+ Strobe ( 1)------------------------------(17) Enable
+ Data 0 ( 2)------------------------------( 4) Data 0
+ Data 1 ( 3)------------------------------( 5) Data 1
+ Data 2 ( 4)------------------------------( 6) Data 2
+ Data 3 ( 5)------------------------------( 7) Data 3
+ Data 4 ( 6)------------------------------( 8) Data 4
+ Data 5 ( 7)------------------------------( 9) Data 5
+ Data 6 ( 8)------------------------------(10) Data 6
+ Data 7 ( 9)------------------------------(11) Data 7
+ (10) [+5v]---( 1) Vdd
+ (11) [GND]---( 2) Ground
+ (12) [+5v]---(14) Reset
+ (13) [GND]---(15) Read / Write
+ Line (14)------------------------------(13) Controller Select 1
+ (15)
+ Init (16)------------------------------(12) Controller Select 2
+ Select (17)------------------------------(16) Data / Instruction
+ Ground (18)---[GND] [+5v]---(19) LED +
+ Ground (19)---[GND]
+ Ground (20)---[GND] E A Values:
+ Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm
+ Ground (22)---[GND] | - P1 = Preset = 10 Kohm
+ Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm
+ Ground (24)---[GND] | |
+ Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
-------------------------
-4. USERSPACE PROGRAMMING
+4. Userspace Programming
------------------------
The cfag12864bfb describes a framebuffer device (/dev/fbX).
diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst
new file mode 100644
index 000000000000..e466f0595248
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -0,0 +1,16 @@
+=========================
+Auxiliary Display Support
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
+ ks0108.rst
+ cfag12864b.rst
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/admin-guide/auxdisplay/ks0108.rst
similarity index 32%
rename from Documentation/auxdisplay/ks0108
rename to Documentation/admin-guide/auxdisplay/ks0108.rst
index 8ddda0c8ceef..c0b7faf73136 100644
--- a/Documentation/auxdisplay/ks0108
+++ b/Documentation/admin-guide/auxdisplay/ks0108.rst
@@ -1,50 +1,45 @@
- ==========================================
- ks0108 LCD Controller Driver Documentation
- ==========================================
+==========================================
+ks0108 LCD Controller Driver Documentation
+==========================================
-License: GPLv2
-Author & Maintainer: Miguel Ojeda Sandonis
-Date: 2006-10-27
+:License: GPLv2
+:Author & Maintainer: Miguel Ojeda Sandonis
+:Date: 2006-10-27
---------
-0. INDEX
---------
+.. INDEX
1. DRIVER INFORMATION
2. DEVICE INFORMATION
3. WIRING
----------------------
-1. DRIVER INFORMATION
+1. Driver Information
---------------------
This driver supports the ks0108 LCD controller.
----------------------
-2. DEVICE INFORMATION
+2. Device Information
---------------------
-Manufacturer: Samsung
-Device Name: KS0108 LCD Controller
-Device Code: ks0108
-Webpage: -
-Device Webpage: -
-Type: LCD Controller (Liquid Crystal Display Controller)
-Width: 64
-Height: 64
-Colors: 2 (B/N)
-Pages: 8
-Addresses: 64 each page
-Data size: 1 byte each address
-Memory size: 8 * 64 * 1 = 512 bytes
+:Manufacturer: Samsung
+:Device Name: KS0108 LCD Controller
+:Device Code: ks0108
+:Webpage: -
+:Device Webpage: -
+:Type: LCD Controller (Liquid Crystal Display Controller)
+:Width: 64
+:Height: 64
+:Colors: 2 (B/N)
+:Pages: 8
+:Addresses: 64 each page
+:Data size: 1 byte each address
+:Memory size: 8 * 64 * 1 = 512 bytes
----------
-3. WIRING
+3. Wiring
---------
The driver supports data parallel port wiring.
@@ -52,4 +47,4 @@ The driver supports data parallel port wiring.
If you aren't building LCD related hardware, you should check
your LCD specific wiring information in the same folder.
-For example, check Documentation/auxdisplay/cfag12864b.
+For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 33feab2f4084..99d84f5f80db 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -98,6 +98,7 @@ configure specific aspects of kernel behavior to your liking.
iostats
kernel-per-CPU-kthreads
laptops/index
+ auxdisplay/index
lcd-panel-cgram
ldm
lockup-watchdogs
diff --git a/MAINTAINERS b/MAINTAINERS
index e5593c66f904..2055887f07ef 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8991,7 +8991,7 @@ F: kernel/kprobes.c
KS0108 LCD CONTROLLER DRIVER
M: Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com>
S: Maintained
-F: Documentation/auxdisplay/ks0108
+F: Documentation/admin-guide/auxdisplay/ks0108.rst
F: drivers/auxdisplay/ks0108.c
F: include/linux/ks0108.h
diff --git a/drivers/auxdisplay/Kconfig b/drivers/auxdisplay/Kconfig
index dd61fdd400f0..6b476e663e80 100644
--- a/drivers/auxdisplay/Kconfig
+++ b/drivers/auxdisplay/Kconfig
@@ -97,7 +97,7 @@ config CFAG12864B
say Y. You also need the ks0108 LCD Controller driver.
For help about how to wire your LCD to the parallel port,
- check Documentation/auxdisplay/cfag12864b
+ check Documentation/admin-guide/auxdisplay/cfag12864b.rst
Depends on the x86 arch and the framebuffer support.
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 12/26] docs: README.buddha: convert to ReST and add to m68k book
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (14 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
Adjust the file for it to be properly parsed by Sphinx, adding
it to the index of the book it belongs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../m68k/{README.buddha => buddha-driver.rst} | 95 +++++++++----------
Documentation/m68k/index.rst | 1 +
2 files changed, 48 insertions(+), 48 deletions(-)
rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/buddha-driver.rst
similarity index 73%
rename from Documentation/m68k/README.buddha
rename to Documentation/m68k/buddha-driver.rst
index 3ea9827ba3c7..20e401413991 100644
--- a/Documentation/m68k/README.buddha
+++ b/Documentation/m68k/buddha-driver.rst
@@ -1,3 +1,6 @@
+=====================================
+Amiga Buddha and Catweasel IDE Driver
+=====================================
The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by
Geert Uytterhoeven based on the following specifications:
@@ -12,12 +15,12 @@ described in their manuals, no tricks have been used (for
example leaving some address lines out of the equations...).
If you want to configure the board yourself (for example let
a Linux kernel configure the card), look at the Commodore
-Docs. Reading the nibbles should give this information:
+Docs. Reading the nibbles should give this information::
-Vendor number: 4626 ($1212)
-product number: 0 (42 for Catweasel Z-II)
-Serial number: 0
-Rom-vector: $1000
+ Vendor number: 4626 ($1212)
+ product number: 0 (42 for Catweasel Z-II)
+ Serial number: 0
+ Rom-vector: $1000
The card should be a Z-II board, size 64K, not for freemem
list, Rom-Vektor is valid, no second Autoconfig-board on the
@@ -34,6 +37,7 @@ otherwise your chance is only 1:16 to find the board :-).
The local memory-map is even active when mapped to $e8:
+============== ===========================================
$0-$7e Autokonfig-space, see Z-II docs.
$80-$7fd reserved
@@ -50,50 +54,51 @@ $a00-$aff IDE-Select 2 (Port 1, Register set 0)
$b00-$bff IDE-Select 3 (Port 1, Register set 1)
$c00-$cff IDE-Select 4 (Port 2, Register set 0,
- Catweasel only!)
+ Catweasel only!)
$d00-$dff IDE-Select 5 (Port 3, Register set 1,
- Catweasel only!)
+ Catweasel only!)
-$e00-$eff local expansion port, on Catweasel Z-II the
+$e00-$eff local expansion port, on Catweasel Z-II the
Catweasel registers are also mapped here.
Never touch, use multidisk.device!
-
-$f00 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 0.
+
+$f00 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 0.
$f01-$f3f mirror of $f00
-$f40 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 1.
+$f40 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 1.
$f41-$f7f mirror of $f40
-$f80 read only, Byte-access: Bit 7 shows the
- level of the IRQ-line of IDE port 2.
+$f80 read only, Byte-access: Bit 7 shows the
+ level of the IRQ-line of IDE port 2.
(Catweasel only!)
$f81-$fbf mirror of $f80
$fc0 write-only: Writing any value to this
- register enables IRQs to be passed from the
- IDE ports to the Zorro bus. This mechanism
- has been implemented to be compatible with
+ register enables IRQs to be passed from the
+ IDE ports to the Zorro bus. This mechanism
+ has been implemented to be compatible with
harddisks that are either defective or have
- a buggy firmware and pull the IRQ line up
- while starting up. If interrupts would
- always be passed to the bus, the computer
- might not start up. Once enabled, this flag
- can not be disabled again. The level of the
- flag can not be determined by software
+ a buggy firmware and pull the IRQ line up
+ while starting up. If interrupts would
+ always be passed to the bus, the computer
+ might not start up. Once enabled, this flag
+ can not be disabled again. The level of the
+ flag can not be determined by software
(what for? Write to me if it's necessary!).
$fc1-$fff mirror of $fc0
$1000-$ffff Buddha-Rom with offset $1000 in the rom
- chip. The addresses $0 to $fff of the rom
+ chip. The addresses $0 to $fff of the rom
chip cannot be read. Rom is Byte-wide and
mapped to even addresses.
+============== ===========================================
The IDE ports issue an INT2. You can read the level of the
IRQ-lines of the IDE-ports by reading from the three (two
@@ -128,7 +133,8 @@ must always be set to 1 to be compatible with later Buddha
versions (if I'll ever update this one). I presume that
I'll never use the lower four bits, but they have to be set
to 1 by definition.
- The values in this table have to be shifted 5 bits to the
+
+The values in this table have to be shifted 5 bits to the
left and or'd with $1f (this sets the lower 5 bits).
All the timings have in common: Select and IOR/IOW rise at
@@ -138,44 +144,36 @@ values are no multiple of 71. One clock-cycle is 71ns long
(exactly 70,5 at 14,18 Mhz on PAL systems).
value 0 (Default after reset)
-
-497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
-(same timing as the Amiga 1200 does on it's IDE port without
-accelerator card)
+ 497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
+ (same timing as the Amiga 1200 does on it's IDE port without
+ accelerator card)
value 1
-
-639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+ 639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
value 2
-
-781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+ 781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
value 3
-
-355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+ 355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
value 4
-
-355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
+ 355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
value 5
-
-355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+ 355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
value 6
-
-1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+ 1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
value 7
-
-355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+ 355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
When accessing IDE registers with A6=1 (for example $84x),
the timing will always be mode 0 8-bit compatible, no matter
what you have selected in the speed register:
-781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
+781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
All the timings with a very short select-signal (the 355ns
fast accesses) depend on the accelerator card used in the
@@ -204,7 +202,8 @@ always shows a "no IRQ here" on the Buddha, and accesses to
the third IDE port are going into data's Nirwana on the
Buddha.
- Jens Schönfeld february 19th, 1997
- updated may 27th, 1997
- eMail: sysop@nostlgic.tng.oche.de
+Jens Schönfeld february 19th, 1997
+updated may 27th, 1997
+
+eMail: sysop@nostlgic.tng.oche.de
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
index 3a5ba7fe1703..b89cb6a86d9b 100644
--- a/Documentation/m68k/index.rst
+++ b/Documentation/m68k/index.rst
@@ -8,6 +8,7 @@ m68k Architecture
:maxdepth: 2
kernel-options
+ buddha-driver
.. only:: subproject and html
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 13/26] docs: parisc: convert to ReST and add to documentation body
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (15 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, James E.J. Bottomley,
Helge Deller, linux-doc, linux-parisc
Manually convert the two PA-RISC documents to ReST, adding them
to the Linux documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../parisc/{debugging => debugging.rst} | 7 +++
Documentation/parisc/index.rst | 18 ++++++
.../parisc/{registers => registers.rst} | 59 +++++++++++++------
4 files changed, 68 insertions(+), 17 deletions(-)
rename Documentation/parisc/{debugging => debugging.rst} (94%)
create mode 100644 Documentation/parisc/index.rst
rename Documentation/parisc/{registers => registers.rst} (70%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index d9e607d8a9b9..25e080664050 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -148,6 +148,7 @@ implementation.
ia64/index
m68k/index
powerpc/index
+ parisc/index
riscv/index
s390/index
sh/index
diff --git a/Documentation/parisc/debugging b/Documentation/parisc/debugging.rst
similarity index 94%
rename from Documentation/parisc/debugging
rename to Documentation/parisc/debugging.rst
index 7d75223fa18d..de1b60402c5b 100644
--- a/Documentation/parisc/debugging
+++ b/Documentation/parisc/debugging.rst
@@ -1,8 +1,13 @@
+=================
+PA-RISC Debugging
+=================
+
okay, here are some hints for debugging the lower-level parts of
linux/parisc.
1. Absolute addresses
+=====================
A lot of the assembly code currently runs in real mode, which means
absolute addresses are used instead of virtual addresses as in the
@@ -12,6 +17,7 @@ currently).
2. HPMCs
+========
When real-mode code tries to access non-existent memory, you'll get
an HPMC instead of a kernel oops. To debug an HPMC, try to find
@@ -27,6 +33,7 @@ access it.
3. Q bit fun
+============
Certain, very critical code has to clear the Q bit in the PSW. What
happens when the Q bit is cleared is the CPU does not update the
diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst
new file mode 100644
index 000000000000..aa3ee0470425
--- /dev/null
+++ b/Documentation/parisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+PA-RISC Architecture
+====================
+
+.. toctree::
+ :maxdepth: 2
+
+ debugging
+ registers
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers.rst
similarity index 70%
rename from Documentation/parisc/registers
rename to Documentation/parisc/registers.rst
index 10c7d1730f5d..59c8ecf3e856 100644
--- a/Documentation/parisc/registers
+++ b/Documentation/parisc/registers.rst
@@ -1,11 +1,16 @@
+================================
Register Usage for Linux/PA-RISC
+================================
[ an asterisk is used for planned usage which is currently unimplemented ]
- General Registers as specified by ABI
+General Registers as specified by ABI
+=====================================
- Control Registers
+Control Registers
+-----------------
+=============================== ===============================================
CR 0 (Recovery Counter) used for ptrace
CR 1-CR 7(undefined) unused
CR 8 (Protection ID) per-process value*
@@ -29,26 +34,35 @@ CR28 (TR 4) not used
CR29 (TR 5) not used
CR30 (TR 6) current / 0
CR31 (TR 7) Temporary register, used in various places
+=============================== ===============================================
- Space Registers (kernel mode)
+Space Registers (kernel mode)
+-----------------------------
+=============================== ===============================================
SR0 temporary space register
SR4-SR7 set to 0
SR1 temporary space register
SR2 kernel should not clobber this
SR3 used for userspace accesses (current process)
+=============================== ===============================================
- Space Registers (user mode)
+Space Registers (user mode)
+---------------------------
+=============================== ===============================================
SR0 temporary space register
SR1 temporary space register
SR2 holds space of linux gateway page
SR3 holds user address space value while in kernel
SR4-SR7 Defines short address space for user/kernel
+=============================== ===============================================
- Processor Status Word
+Processor Status Word
+---------------------
+=============================== ===============================================
W (64-bit addresses) 0
E (Little-endian) 0
S (Secure Interval Timer) 0
@@ -69,15 +83,19 @@ Q (collect interruption state) 1 (0 in code directly preceding an rfi)
P (Protection Identifiers) 1*
D (Data address translation) 1, 0 while executing real-mode code
I (external interrupt mask) used by cli()/sti() macros
+=============================== ===============================================
- "Invisible" Registers
+"Invisible" Registers
+---------------------
+=============================== ===============================================
PSW default W value 0
PSW default E value 0
Shadow Registers used by interruption handler code
TOC enable bit 1
+=============================== ===============================================
-=========================================================================
+-------------------------------------------------------------------------
The PA-RISC architecture defines 7 registers as "shadow registers".
Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce
@@ -85,7 +103,8 @@ the state save and restore time by eliminating the need for general register
(GR) saves and restores in interruption handlers.
Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25.
-=========================================================================
+-------------------------------------------------------------------------
+
Register usage notes, originally from John Marvin, with some additional
notes from Randolph Chung.
@@ -96,10 +115,12 @@ course, you need to save them if you care about them, before calling
another procedure. Some of the above registers do have special meanings
that you should be aware of:
- r1: The addil instruction is hardwired to place its result in r1,
+ r1:
+ The addil instruction is hardwired to place its result in r1,
so if you use that instruction be aware of that.
- r2: This is the return pointer. In general you don't want to
+ r2:
+ This is the return pointer. In general you don't want to
use this, since you need the pointer to get back to your
caller. However, it is grouped with this set of registers
since the caller can't rely on the value being the same
@@ -107,23 +128,27 @@ that you should be aware of:
and return through that register after trashing r2, and
that should not cause a problem for the calling routine.
- r19-r22: these are generally regarded as temporary registers.
+ r19-r22:
+ these are generally regarded as temporary registers.
Note that in 64 bit they are arg7-arg4.
- r23-r26: these are arg3-arg0, i.e. you can use them if you
+ r23-r26:
+ these are arg3-arg0, i.e. you can use them if you
don't care about the values that were passed in anymore.
- r28,r29: are ret0 and ret1. They are what you pass return values
+ r28,r29:
+ are ret0 and ret1. They are what you pass return values
in. r28 is the primary return. When returning small structures
r29 may also be used to pass data back to the caller.
- r30: stack pointer
+ r30:
+ stack pointer
- r31: the ble instruction puts the return pointer in here.
+ r31:
+ the ble instruction puts the return pointer in here.
-r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
+ r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
general purpose registers. r27 is the data pointer, and is
used to make references to global variables easier. r30 is
the stack pointer.
-
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 14/26] docs: openrisc: convert to ReST and add to documentation body
2019-07-26 12:51 ` Mauro Carvalho Chehab
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Jonas Bonn,
Stefan Kristiansson, Stafford Horne, linux-doc, openrisc
Manually convert the two openRisc documents to ReST, adding them
to the Linux documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Stafford Horne <shorne@gmail.com>
---
Documentation/index.rst | 1 +
Documentation/openrisc/index.rst | 18 +++++++++++++
.../openrisc/{README => openrisc_port.rst} | 25 +++++++++++++------
Documentation/openrisc/{TODO => todo.rst} | 9 ++++---
4 files changed, 43 insertions(+), 10 deletions(-)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 25e080664050..6402f62ac90f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -148,6 +148,7 @@ implementation.
ia64/index
m68k/index
powerpc/index
+ openrisc/index
parisc/index
riscv/index
s390/index
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
new file mode 100644
index 000000000000..748b3eea1707
--- /dev/null
+++ b/Documentation/openrisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+OpenRISC Architecture
+=====================
+
+.. toctree::
+ :maxdepth: 2
+
+ openrisc_port
+ todo
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst
similarity index 80%
rename from Documentation/openrisc/README
rename to Documentation/openrisc/openrisc_port.rst
index 777a893d533d..a18747a8d191 100644
--- a/Documentation/openrisc/README
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -1,3 +1,4 @@
+==============
OpenRISC Linux
==============
@@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
For information about OpenRISC processors and ongoing development:
+ ======= =============================
website http://openrisc.io
email openrisc@lists.librecores.org
+ ======= =============================
---------------------------------------------------------------------
@@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page.
Instructions for building the different toolchains can be found on openrisc.io
or Stafford's toolchain build and release scripts.
+ ========== =================================================
binaries https://github.com/openrisc/or1k-gcc/releases
toolchains https://openrisc.io/software
building https://github.com/stffrdhrn/or1k-toolchain-build
+ ========== =================================================
2) Building
-Build the Linux kernel as usual
+Build the Linux kernel as usual::
make ARCH=openrisc defconfig
make ARCH=openrisc
@@ -43,6 +48,8 @@ development board with the OpenRISC SoC. During the build FPGA RTL is code
downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
tools. Binaries are loaded onto the board with openocd.
+::
+
git clone https://github.com/olofk/fusesoc
cd fusesoc
sudo pip install -e .
@@ -65,7 +72,9 @@ platform. Please follow the OpenRISC instructions on the QEMU website to get
Linux running on QEMU. You can build QEMU yourself, but your Linux distribution
likely provides binary packages to support OpenRISC.
+ ============= ======================================================
qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC
+ ============= ======================================================
---------------------------------------------------------------------
@@ -75,36 +84,38 @@ Terminology
In the code, the following particles are used on symbols to limit the scope
to more or less specific processor implementations:
+========= =======================================
openrisc: the OpenRISC class of processors
or1k: the OpenRISC 1000 family of processors
or1200: the OpenRISC 1200 processor
+========= =======================================
---------------------------------------------------------------------
History
========
-18. 11. 2003 Matjaz Breskvar (phoenix@bsemi.com)
+18-11-2003 Matjaz Breskvar (phoenix@bsemi.com)
initial port of linux to OpenRISC/or32 architecture.
all the core stuff is implemented and seams usable.
-08. 12. 2003 Matjaz Breskvar (phoenix@bsemi.com)
+08-12-2003 Matjaz Breskvar (phoenix@bsemi.com)
complete change of TLB miss handling.
rewrite of exceptions handling.
fully functional sash-3.6 in default initrd.
a much improved version with changes all around.
-10. 04. 2004 Matjaz Breskvar (phoenix@bsemi.com)
+10-04-2004 Matjaz Breskvar (phoenix@bsemi.com)
alot of bugfixes all over.
ethernet support, functional http and telnet servers.
running many standard linux apps.
-26. 06. 2004 Matjaz Breskvar (phoenix@bsemi.com)
+26-06-2004 Matjaz Breskvar (phoenix@bsemi.com)
port to 2.6.x
-30. 11. 2004 Matjaz Breskvar (phoenix@bsemi.com)
+30-11-2004 Matjaz Breskvar (phoenix@bsemi.com)
lots of bugfixes and enhancments.
added opencores framebuffer driver.
-09. 10. 2010 Jonas Bonn (jonas@southpole.se)
+09-10-2010 Jonas Bonn (jonas@southpole.se)
major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst
similarity index 78%
rename from Documentation/openrisc/TODO
rename to Documentation/openrisc/todo.rst
index c43d4e1d14eb..420b18b87eda 100644
--- a/Documentation/openrisc/TODO
+++ b/Documentation/openrisc/todo.rst
@@ -1,12 +1,15 @@
+====
+TODO
+====
+
The OpenRISC Linux port is fully functional and has been tracking upstream
since 2.6.35. There are, however, remaining items to be completed within
the coming months. Here's a list of known-to-be-less-than-stellar items
that are due for investigation shortly, i.e. our TODO list:
--- Implement the rest of the DMA API... dma_map_sg, etc.
+- Implement the rest of the DMA API... dma_map_sg, etc.
--- Finish the renaming cleanup... there are references to or32 in the code
+- Finish the renaming cleanup... there are references to or32 in the code
which was an older name for the architecture. The name we've settled on is
or1k and this change is slowly trickling through the stack. For the time
being, or32 is equivalent to or1k.
-
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [OpenRISC] [PATCH v2 14/26] docs: openrisc: convert to ReST and add to documentation body
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
To: openrisc
Manually convert the two openRisc documents to ReST, adding them
to the Linux documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Stafford Horne <shorne@gmail.com>
---
Documentation/index.rst | 1 +
Documentation/openrisc/index.rst | 18 +++++++++++++
.../openrisc/{README => openrisc_port.rst} | 25 +++++++++++++------
Documentation/openrisc/{TODO => todo.rst} | 9 ++++---
4 files changed, 43 insertions(+), 10 deletions(-)
create mode 100644 Documentation/openrisc/index.rst
rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
rename Documentation/openrisc/{TODO => todo.rst} (78%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 25e080664050..6402f62ac90f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -148,6 +148,7 @@ implementation.
ia64/index
m68k/index
powerpc/index
+ openrisc/index
parisc/index
riscv/index
s390/index
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
new file mode 100644
index 000000000000..748b3eea1707
--- /dev/null
+++ b/Documentation/openrisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+OpenRISC Architecture
+=====================
+
+.. toctree::
+ :maxdepth: 2
+
+ openrisc_port
+ todo
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst
similarity index 80%
rename from Documentation/openrisc/README
rename to Documentation/openrisc/openrisc_port.rst
index 777a893d533d..a18747a8d191 100644
--- a/Documentation/openrisc/README
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -1,3 +1,4 @@
+==============
OpenRISC Linux
==============
@@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
For information about OpenRISC processors and ongoing development:
+ ======= =============================
website http://openrisc.io
email openrisc at lists.librecores.org
+ ======= =============================
---------------------------------------------------------------------
@@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page.
Instructions for building the different toolchains can be found on openrisc.io
or Stafford's toolchain build and release scripts.
+ ========== =================================================
binaries https://github.com/openrisc/or1k-gcc/releases
toolchains https://openrisc.io/software
building https://github.com/stffrdhrn/or1k-toolchain-build
+ ========== =================================================
2) Building
-Build the Linux kernel as usual
+Build the Linux kernel as usual::
make ARCH=openrisc defconfig
make ARCH=openrisc
@@ -43,6 +48,8 @@ development board with the OpenRISC SoC. During the build FPGA RTL is code
downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
tools. Binaries are loaded onto the board with openocd.
+::
+
git clone https://github.com/olofk/fusesoc
cd fusesoc
sudo pip install -e .
@@ -65,7 +72,9 @@ platform. Please follow the OpenRISC instructions on the QEMU website to get
Linux running on QEMU. You can build QEMU yourself, but your Linux distribution
likely provides binary packages to support OpenRISC.
+ ============= ======================================================
qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC
+ ============= ======================================================
---------------------------------------------------------------------
@@ -75,36 +84,38 @@ Terminology
In the code, the following particles are used on symbols to limit the scope
to more or less specific processor implementations:
+========= =======================================
openrisc: the OpenRISC class of processors
or1k: the OpenRISC 1000 family of processors
or1200: the OpenRISC 1200 processor
+========= =======================================
---------------------------------------------------------------------
History
========
-18. 11. 2003 Matjaz Breskvar (phoenix at bsemi.com)
+18-11-2003 Matjaz Breskvar (phoenix at bsemi.com)
initial port of linux to OpenRISC/or32 architecture.
all the core stuff is implemented and seams usable.
-08. 12. 2003 Matjaz Breskvar (phoenix at bsemi.com)
+08-12-2003 Matjaz Breskvar (phoenix at bsemi.com)
complete change of TLB miss handling.
rewrite of exceptions handling.
fully functional sash-3.6 in default initrd.
a much improved version with changes all around.
-10. 04. 2004 Matjaz Breskvar (phoenix at bsemi.com)
+10-04-2004 Matjaz Breskvar (phoenix at bsemi.com)
alot of bugfixes all over.
ethernet support, functional http and telnet servers.
running many standard linux apps.
-26. 06. 2004 Matjaz Breskvar (phoenix at bsemi.com)
+26-06-2004 Matjaz Breskvar (phoenix at bsemi.com)
port to 2.6.x
-30. 11. 2004 Matjaz Breskvar (phoenix at bsemi.com)
+30-11-2004 Matjaz Breskvar (phoenix at bsemi.com)
lots of bugfixes and enhancments.
added opencores framebuffer driver.
-09. 10. 2010 Jonas Bonn (jonas at southpole.se)
+09-10-2010 Jonas Bonn (jonas at southpole.se)
major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst
similarity index 78%
rename from Documentation/openrisc/TODO
rename to Documentation/openrisc/todo.rst
index c43d4e1d14eb..420b18b87eda 100644
--- a/Documentation/openrisc/TODO
+++ b/Documentation/openrisc/todo.rst
@@ -1,12 +1,15 @@
+====
+TODO
+====
+
The OpenRISC Linux port is fully functional and has been tracking upstream
since 2.6.35. There are, however, remaining items to be completed within
the coming months. Here's a list of known-to-be-less-than-stellar items
that are due for investigation shortly, i.e. our TODO list:
--- Implement the rest of the DMA API... dma_map_sg, etc.
+- Implement the rest of the DMA API... dma_map_sg, etc.
--- Finish the renaming cleanup... there are references to or32 in the code
+- Finish the renaming cleanup... there are references to or32 in the code
which was an older name for the architecture. The name we've settled on is
or1k and this change is slowly trickling through the stack. For the time
being, or32 is equivalent to or1k.
-
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 15/26] docs: isdn: convert to ReST and add to kAPI bookset
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (17 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Karsten Keil,
Greg Kroah-Hartman, linux-doc, netdev, devel
The ISDN documentation is a mix of admin guide, uAPI and kAPI.
Ideally, it should be split. Yet, not sure if it would worth
the troble. Anyway, we have the same kind of mix on several
drivers specific documentation. So, just like the others, keep
the directory at the root Documentation/ tree, just adding a
pointer to it at the kAPI section, as the documentation was
written with the Kernel developers in mind.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 ++++++++------
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +++++++++++-------
.../isdn/{README.hysdn => hysdn.rst} | 125 ++++----
Documentation/isdn/index.rst | 24 ++
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +++++++----
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
9 files changed, 536 insertions(+), 331 deletions(-)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 6402f62ac90f..de7be1c31450 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -106,6 +106,7 @@ needed).
hid/index
i2c/index
iio/index
+ isdn/index
infiniband/index
leds/index
media/index
diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst
similarity index 50%
rename from Documentation/isdn/README.avmb1
rename to Documentation/isdn/avmb1.rst
index 9e075484ef1e..de3961e67553 100644
--- a/Documentation/isdn/README.avmb1
+++ b/Documentation/isdn/avmb1.rst
@@ -1,4 +1,6 @@
-Driver for active AVM Controller.
+================================
+Driver for active AVM Controller
+================================
The driver provides a kernel capi2.0 Interface (kernelcapi) and
on top of this a User-Level-CAPI2.0-interface (capi)
@@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils.
t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
Currently supported cards:
- B1 ISA (all versions)
- B1 PCI
- T1/T1B (HEMA card)
- M1
- M2
- B1 PCMCIA
+
+ - B1 ISA (all versions)
+ - B1 PCI
+ - T1/T1B (HEMA card)
+ - M1
+ - M2
+ - B1 PCMCIA
Installing
----------
You need at least /dev/capi20 to load the firmware.
-mknod /dev/capi20 c 68 0
-mknod /dev/capi20.00 c 68 1
-mknod /dev/capi20.01 c 68 2
-.
-.
-.
-mknod /dev/capi20.19 c 68 20
+::
+
+ mknod /dev/capi20 c 68 0
+ mknod /dev/capi20.00 c 68 1
+ mknod /dev/capi20.01 c 68 2
+ .
+ .
+ .
+ mknod /dev/capi20.19 c 68 20
Running
-------
@@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware.
AVM GmbH provides several t4-files for the different D-channel
protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
-if you configure as modules load the modules this way:
-
-insmod /lib/modules/current/misc/capiutil.o
-insmod /lib/modules/current/misc/b1.o
-insmod /lib/modules/current/misc/kernelcapi.o
-insmod /lib/modules/current/misc/capidrv.o
-insmod /lib/modules/current/misc/capi.o
-
-if you have an B1-PCI card load the module b1pci.o
-insmod /lib/modules/current/misc/b1pci.o
-and load the firmware with
-avmcapictrl load /lib/isdn/b1.t4 1
+if you configure as modules load the modules this way::
+
+ insmod /lib/modules/current/misc/capiutil.o
+ insmod /lib/modules/current/misc/b1.o
+ insmod /lib/modules/current/misc/kernelcapi.o
+ insmod /lib/modules/current/misc/capidrv.o
+ insmod /lib/modules/current/misc/capi.o
+
+if you have an B1-PCI card load the module b1pci.o::
+
+ insmod /lib/modules/current/misc/b1pci.o
+
+and load the firmware with::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
if you have an B1-ISA card load the module b1isa.o
-and add the card by calling
-avmcapictrl add 0x150 15
-and load the firmware by calling
-avmcapictrl load /lib/isdn/b1.t4 1
+and add the card by calling::
+
+ avmcapictrl add 0x150 15
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
if you have an T1-ISA card load the module t1isa.o
-and add the card by calling
-avmcapictrl add 0x450 15 T1 0
-and load the firmware by calling
-avmcapictrl load /lib/isdn/t1.t4 1
+and add the card by calling::
+
+ avmcapictrl add 0x450 15 T1 0
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/t1.t4 1
if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
before you insert the card.
Leased Lines with B1
--------------------
+
Init card and load firmware.
+
For an D64S use "FV: 1" as phone number
+
For an D64S2 use "FV: 1" and "FV: 2" for multilink
or "FV: 1,2" to use CAPI channel bundling.
/proc-Interface
-----------------
-/proc/capi:
+/proc/capi::
+
dr-xr-xr-x 2 root root 0 Jul 1 14:03 .
dr-xr-xr-x 82 root root 0 Jun 30 19:08 ..
-r--r--r-- 1 root root 0 Jul 1 14:03 applications
@@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling.
/proc/capi/applications:
applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
- level3cnt: capi_register parameter
- datablkcnt: capi_register parameter
- ncci-cnt: current number of nccis (connections)
- recvqueuelen: number of messages on receive queue
- for example:
-1 -2 16 2048 1 0
-2 2 7 2048 1 0
+ level3cnt:
+ capi_register parameter
+ datablkcnt:
+ capi_register parameter
+ ncci-cnt:
+ current number of nccis (connections)
+ recvqueuelen:
+ number of messages on receive queue
+
+ for example::
+
+ 1 -2 16 2048 1 0
+ 2 2 7 2048 1 0
/proc/capi/applstats:
applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
- recvctlmsg: capi messages received without DATA_B3_IND
- recvdatamsg: capi DATA_B3_IND received
- sentctlmsg: capi messages sent without DATA_B3_REQ
- sentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2057 1699 1721 1699
+ recvctlmsg:
+ capi messages received without DATA_B3_IND
+ recvdatamsg:
+ capi DATA_B3_IND received
+ sentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ sentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2057 1699 1721 1699
/proc/capi/capi20: statistics of capi.o (/dev/capi20)
minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- minor: minor device number of capi device
- nopen: number of calls to devices open
- nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
+ minor:
+ minor device number of capi device
+ nopen:
+ number of calls to devices open
+ nrecvdropmsg:
+ capi messages dropped (messages in recvqueue in close)
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
- for example:
-1 2 18 0 16 2
+ for example::
+
+ 1 2 18 0 16 2
/proc/capi/capidrv: statistics of capidrv.o (capi messages)
nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
for example:
-2780 2226 2256 2226
+ 2780 2226 2256 2226
/proc/capi/controller:
controller drivername state cardname controllerinfo
- for example:
-1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
-2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
-3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
+
+ for example::
+
+ 1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
+ 2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
+ 3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
/proc/capi/contrstats:
controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2845 2272 2310 2274
-2 2 0 2 0
-3 2 0 2 0
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2845 2272 2310 2274
+ 2 2 0 2 0
+ 3 2 0 2 0
/proc/capi/driver:
drivername ncontroller
- for example:
-b1pci 1
-t1isa 1
-b1pcmcia 1
-b1isa 0
+
+ for example::
+
+ b1pci 1
+ t1isa 1
+ b1pcmcia 1
+ b1isa 0
/proc/capi/ncci:
apllid ncci winsize sendwindow
- for example:
-1 0x10101 8 0
+
+ for example::
+
+ 1 0x10101 8 0
/proc/capi/users: kernelmodules that use the kernelcapi.
name
- for example:
-capidrv
-capi20
+
+ for example::
+
+ capidrv
+ capi20
Questions
---------
+
Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
linux-avmb1@calle.in-berlin.de mailing list by sending
a mail to majordomo@calle.in-berlin.de with
@@ -178,9 +236,10 @@ in the body.
German documentation and several scripts can be found at
ftp://ftp.avm.de/cardware/b1/linux/
-Bugs
+Bugs
----
-If you find any please let me know.
+
+If you find any please let me know.
Enjoy,
diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst
similarity index 96%
rename from Documentation/isdn/CREDITS
rename to Documentation/isdn/credits.rst
index c1679e913fca..319323f2091f 100644
--- a/Documentation/isdn/CREDITS
+++ b/Documentation/isdn/credits.rst
@@ -1,3 +1,7 @@
+=======
+Credits
+=======
+
I want to thank all who contributed to this project and especially to:
(in alphabetical order)
@@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de)
For creating and maintaining the FAQ.
Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
- For creating the FAQ, and the leafsite HOWTO.
+ For creating the FAQ, and the leafsite HOWTO.
Michael 'Ghandi' Herold (michael@abadonna.franken.de)
For contribution of the vbox answering machine.
@@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
Thomas Uhl (uhl@think.de)
For distributing the cards.
For pushing me to work ;-)
-
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst
similarity index 74%
rename from Documentation/isdn/README.gigaset
rename to Documentation/isdn/gigaset.rst
index f6184b637182..98b4ec521c51 100644
--- a/Documentation/isdn/README.gigaset
+++ b/Documentation/isdn/gigaset.rst
@@ -1,33 +1,36 @@
+==========================
GigaSet 307x Device Driver
==========================
1. Requirements
- ------------
+=================
+
1.1. Hardware
- --------
+-------------
+
This driver supports the connection of the Gigaset 307x/417x family of
ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
connection. The following devices are reported to be compatible:
Bases:
- Siemens Gigaset 3070/3075 isdn
- Siemens Gigaset 4170/4175 isdn
- Siemens Gigaset SX205/255
- Siemens Gigaset SX353
- T-Com Sinus 45 [AB] isdn
- T-Com Sinus 721X[A] [SE]
- Vox Chicago 390 ISDN (KPN Telecom)
+ - Siemens Gigaset 3070/3075 isdn
+ - Siemens Gigaset 4170/4175 isdn
+ - Siemens Gigaset SX205/255
+ - Siemens Gigaset SX353
+ - T-Com Sinus 45 [AB] isdn
+ - T-Com Sinus 721X[A] [SE]
+ - Vox Chicago 390 ISDN (KPN Telecom)
RS232 data boxes:
- Siemens Gigaset M101 Data
- T-Com Sinus 45 Data 1
+ - Siemens Gigaset M101 Data
+ - T-Com Sinus 45 Data 1
USB data boxes:
- Siemens Gigaset M105 Data
- Siemens Gigaset USB Adapter DECT
- T-Com Sinus 45 Data 2
- T-Com Sinus 721 data
- Chicago 390 USB (KPN)
+ - Siemens Gigaset M105 Data
+ - Siemens Gigaset USB Adapter DECT
+ - T-Com Sinus 45 Data 2
+ - T-Com Sinus 721 data
+ - Chicago 390 USB (KPN)
See also http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
@@ -37,17 +40,21 @@ GigaSet 307x Device Driver
with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
If you have another device that works with our driver, please let us know.
- Chances of getting an USB device to work are good if the output of
- lsusb
- at the command line contains one of the following:
- ID 0681:0001
- ID 0681:0002
- ID 0681:0009
- ID 0681:0021
- ID 0681:0022
+ Chances of getting an USB device to work are good if the output of::
+
+ lsusb
+
+ at the command line contains one of the following::
+
+ ID 0681:0001
+ ID 0681:0002
+ ID 0681:0009
+ ID 0681:0021
+ ID 0681:0022
1.2. Software
- --------
+-------------
+
The driver works with the Kernel CAPI subsystem and can be used with any
software which is able to use CAPI 2.0 for ISDN connections (voice or data).
@@ -58,9 +65,11 @@ GigaSet 307x Device Driver
2. How to use the driver
- ---------------------
+==========================
+
2.1. Modules
- -------
+------------
+
For the devices to work, the proper kernel modules have to be loaded.
This normally happens automatically when the system detects the USB
device (base, M105) or when the line discipline is attached (M101). It
@@ -71,13 +80,17 @@ GigaSet 307x Device Driver
which uses the regular serial port driver to access the device, and must
therefore be attached to the serial device to which the M101 is connected.
The ldattach(8) command (included in util-linux-ng release 2.14 or later)
- can be used for that purpose, for example:
+ can be used for that purpose, for example::
+
ldattach GIGASET_M101 /dev/ttyS1
+
This will open the device file, attach the line discipline to it, and
then sleep in the background, keeping the device open so that the line
discipline remains active. To deactivate it, kill the daemon, for example
- with
+ with::
+
killall ldattach
+
before disconnecting the device. To have this happen automatically at
system startup/shutdown on an LSB compatible system, create and activate
an appropriate LSB startup script /etc/init.d/gigaset. (The init name
@@ -86,9 +99,10 @@ GigaSet 307x Device Driver
The modules accept the following parameters:
- Module Parameter Meaning
+ =============== ========== ==========================================
+ Module Parameter Meaning
- gigaset debug debug level (see section 3.2.)
+ gigaset debug debug level (see section 3.2.)
startmode initial operation mode (see section 2.5.):
bas_gigaset ) 1=CAPI (default), 0=Unimodem
@@ -96,11 +110,14 @@ GigaSet 307x Device Driver
usb_gigaset ) cidmode initial Call-ID mode setting (see section
2.5.): 1=on (default), 0=off
+ =============== ========== ==========================================
+
Depending on your distribution you may want to create a separate module
configuration file like /etc/modprobe.d/gigaset.conf for these.
2.2. Device nodes for user space programs
- ------------------------------------
+-----------------------------------------
+
The device can be accessed from user space (eg. by the user space tools
mentioned in 1.2.) through the device nodes:
@@ -113,46 +130,56 @@ GigaSet 307x Device Driver
You can also set a "default device" for the user space tools to use when
no device node is given as parameter, by creating a symlink /dev/ttyG to
- one of them, eg.:
+ one of them, eg.::
ln -s /dev/ttyGB0 /dev/ttyG
The devices accept the following device specific ioctl calls
(defined in gigaset_dev.h):
- ioctl(int fd, GIGASET_REDIR, int *cmd);
+ ``ioctl(int fd, GIGASET_REDIR, int *cmd);``
+
If cmd==1, the device is set to be controlled exclusively through the
character device node; access from the ISDN subsystem is blocked.
+
If cmd==0, the device is set to be used from the ISDN subsystem and does
not communicate through the character device node.
- ioctl(int fd, GIGASET_CONFIG, int *cmd);
+ ``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
+
(ser_gigaset and usb_gigaset only)
+
If cmd==1, the device is set to adapter configuration mode where commands
are interpreted by the M10x DECT adapter itself instead of being
forwarded to the base station. In this mode, the device accepts the
commands described in Siemens document "AT-Kommando Alignment M10x Data"
for setting the operation mode, associating with a base station and
querying parameters like field strengh and signal quality.
+
Note that there is no ioctl command for leaving adapter configuration
mode and returning to regular operation. In order to leave adapter
configuration mode, write the command ATO to the device.
- ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
+ ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
+
(usb_gigaset only)
+
Set the break characters on an M105's internal serial adapter to the six
bytes stored in brkchars[]. Unused bytes should be set to zero.
ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
Retrieve version information from the driver. version[0] must be set to
one of:
+
- GIGVER_DRIVER: retrieve driver version
- GIGVER_COMPAT: retrieve interface compatibility version
- GIGVER_FWBASE: retrieve the firmware version of the base
+
Upon return, version[] is filled with the requested version information.
2.3. CAPI
- ----
+---------
+
The devices will show up as CAPI controllers as soon as the
corresponding driver module is loaded, and can then be used with
CAPI 2.0 kernel and user space applications. For user space access,
@@ -165,21 +192,22 @@ GigaSet 307x Device Driver
driver.
2.5. Unimodem mode
- -------------
+------------------
+
In this mode the device works like a modem connected to a serial port
- (the /dev/ttyGU0, ... mentioned above) which understands the commands
+ (the /dev/ttyGU0, ... mentioned above) which understands the commands::
- ATZ init, reset
- => OK or ERROR
- ATD
- ATDT dial
- => OK, CONNECT,
- BUSY,
- NO DIAL TONE,
- NO CARRIER,
- NO ANSWER
- <pause>+++<pause> change to command mode when connected
- ATH hangup
+ ATZ init, reset
+ => OK or ERROR
+ ATD
+ ATDT dial
+ => OK, CONNECT,
+ BUSY,
+ NO DIAL TONE,
+ NO CARRIER,
+ NO ANSWER
+ <pause>+++<pause> change to command mode when connected
+ ATH hangup
You can use some configuration tool of your distribution to configure this
"modem" or configure pppd/wvdial manually. There are some example ppp
@@ -189,40 +217,52 @@ GigaSet 307x Device Driver
control lines. This means you must use "Stupid Mode" if you are using
wvdial or you should use the nocrtscts option of pppd.
You must also assure that the ppp_async module is loaded with the parameter
- flag_time=0. You can do this e.g. by adding a line like
+ flag_time=0. You can do this e.g. by adding a line like::
- options ppp_async flag_time=0
+ options ppp_async flag_time=0
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf.
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf.
Unimodem mode is needed for making some devices [e.g. SX100] work which
do not support the regular Gigaset command set. If debug output (see
- section 3.2.) shows something like this when dialing:
- CMD Received: ERROR
- Available Params: 0
- Connection State: 0, Response: -1
- gigaset_process_response: resp_code -1 in ConState 0 !
- Timeout occurred
+ section 3.2.) shows something like this when dialing::
+
+ CMD Received: ERROR
+ Available Params: 0
+ Connection State: 0, Response: -1
+ gigaset_process_response: resp_code -1 in ConState 0 !
+ Timeout occurred
+
then switching to unimodem mode may help.
If you have installed the command line tool gigacontr, you can enter
- unimodem mode using
- gigacontr --mode unimodem
- You can switch back using
- gigacontr --mode isdn
+ unimodem mode using::
+
+ gigacontr --mode unimodem
+
+ You can switch back using::
+
+ gigacontr --mode isdn
You can also put the driver directly into Unimodem mode when it's loaded,
by passing the module parameter startmode=0 to the hardware specific
- module, e.g.
+ module, e.g.::
+
modprobe usb_gigaset startmode=0
- or by adding a line like
+
+ or by adding a line like::
+
options usb_gigaset startmode=0
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf
+
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf
2.6. Call-ID (CID) mode
- ------------------
+-----------------------
+
Call-IDs are numbers used to tag commands to, and responses from, the
Gigaset base in order to support the simultaneous handling of multiple
ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
@@ -238,6 +278,7 @@ GigaSet 307x Device Driver
During active operation, the driver switches to the necessary mode
automatically. However, for the reasons above, the mode chosen when
the device is not in use (idle) can be selected by the user.
+
- If you want to receive incoming calls, you can use the default
settings (CID mode).
- If you have several DECT data devices (M10x) which you want to use
@@ -247,25 +288,27 @@ GigaSet 307x Device Driver
If you want both of these at once, you are out of luck.
You can also use the tty class parameter "cidmode" of the device to
- change its CID mode while the driver is loaded, eg.
- echo 0 > /sys/class/tty/ttyGU0/cidmode
+ change its CID mode while the driver is loaded, eg.::
+
+ echo 0 > /sys/class/tty/ttyGU0/cidmode
2.7. Dialing Numbers
- ---------------
- The called party number provided by an application for dialing out must
+--------------------
+provided by an application for dialing out must
be a public network number according to the local dialing plan, without
any dial prefix for getting an outside line.
Internal calls can be made by providing an internal extension number
- prefixed with "**" (two asterisks) as the called party number. So to dial
- eg. the first registered DECT handset, give "**11" as the called party
- number. Dialing "***" (three asterisks) calls all extensions
+ prefixed with ``**`` (two asterisks) as the called party number. So to dial
+ eg. the first registered DECT handset, give ``**11`` as the called party
+ number. Dialing ``***`` (three asterisks) calls all extensions
simultaneously (global call).
Unimodem mode does not support internal calls.
2.8. Unregistered Wireless Devices (M101/M105)
- -----------------------------------------
+----------------------------------------------
+
The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
the M101 and M105 wireless devices to be used as ISDN devices for ISDN
connections through a Gigaset base. Therefore they assume that the device
@@ -279,73 +322,91 @@ GigaSet 307x Device Driver
modes. See the gigacontr(8) manpage for details.
3. Troubleshooting
- ---------------
+====================
+
3.1. Solutions to frequently reported problems
- -----------------------------------------
+----------------------------------------------
+
Problem:
- You have a slow provider and isdn4linux gives up dialing too early.
+ You have a slow provider and isdn4linux gives up dialing too early.
Solution:
- Load the isdn module using the dialtimeout option. You can do this e.g.
- by adding a line like
+ Load the isdn module using the dialtimeout option. You can do this e.g.
+ by adding a line like::
- options isdn dialtimeout=15
+ options isdn dialtimeout=15
- to /etc/modprobe.d/gigaset.conf or a similar file.
+ to /etc/modprobe.d/gigaset.conf or a similar file.
Problem:
- The isdnlog program emits error messages or just doesn't work.
+ The isdnlog program emits error messages or just doesn't work.
Solution:
- Isdnlog supports only the HiSax driver. Do not attempt to use it with
+ Isdnlog supports only the HiSax driver. Do not attempt to use it with
other drivers such as Gigaset.
Problem:
- You have two or more DECT data adapters (M101/M105) and only the
- first one you turn on works.
+ You have two or more DECT data adapters (M101/M105) and only the
+ first one you turn on works.
Solution:
- Select Unimodem mode for all DECT data adapters. (see section 2.5.)
+ Select Unimodem mode for all DECT data adapters. (see section 2.5.)
Problem:
- Messages like this:
+ Messages like this::
+
usb_gigaset 3-2:1.0: Could not initialize the device.
+
appear in your syslog.
Solution:
Check whether your M10x wireless device is correctly registered to the
Gigaset base. (see section 2.7.)
3.2. Telling the driver to provide more information
- ----------------------------------------------
+---------------------------------------------------
Building the driver with the "Gigaset debugging" kernel configuration
option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
information useful for debugging.
You can control the amount of debugging information the driver produces by
- writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
- echo 0 > /sys/module/gigaset/parameters/debug
+ writing an appropriate value to /sys/module/gigaset/parameters/debug,
+ e.g.::
+
+ echo 0 > /sys/module/gigaset/parameters/debug
+
switches off debugging output completely,
- echo 0x302020 > /sys/module/gigaset/parameters/debug
+
+ ::
+
+ echo 0x302020 > /sys/module/gigaset/parameters/debug
+
enables a reasonable set of debugging output messages. These values are
bit patterns where every bit controls a certain type of debugging output.
See the constants DEBUG_* in the source file gigaset.h for details.
The initial value can be set using the debug parameter when loading the
- module "gigaset", e.g. by adding a line
- options gigaset debug=0
+ module "gigaset", e.g. by adding a line::
+
+ options gigaset debug=0
+
to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
Generated debugging information can be found
- - as output of the command
- dmesg
+ - as output of the command::
+
+ dmesg
+
- in system log files written by your syslog daemon, usually
in /var/log/, e.g. /var/log/messages.
3.3. Reporting problems and bugs
- ---------------------------
+--------------------------------
If you can't solve problems with the driver on your own, feel free to
use one of the forums, bug trackers, or mailing lists on
- https://sourceforge.net/projects/gigaset307x
+
+ https://sourceforge.net/projects/gigaset307x
+
or write an electronic mail to the maintainers.
Try to provide as much information as possible, such as
+
- distribution
- kernel version (uname -r)
- gcc version (gcc --version)
@@ -362,7 +423,7 @@ GigaSet 307x Device Driver
appropriate forums and newsgroups.
3.4. Reporting problem solutions
- ---------------------------
+--------------------------------
If you solved a problem with our drivers, wrote startup scripts for your
distribution, ... feel free to contact us (using one of the places
mentioned in 3.3.). We'd like to add scripts, hints, documentation
@@ -370,34 +431,35 @@ GigaSet 307x Device Driver
4. Links, other software
- ---------------------
+==========================
+
- Sourceforge project developing this driver and associated tools
- https://sourceforge.net/projects/gigaset307x
+ https://sourceforge.net/projects/gigaset307x
- Yahoo! Group on the Siemens Gigaset family of devices
- https://de.groups.yahoo.com/group/Siemens-Gigaset
+ https://de.groups.yahoo.com/group/Siemens-Gigaset
- Siemens Gigaset/T-Sinus compatibility table
- http://www.erbze.info/sinus_gigaset.htm
+ http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
5. Credits
- -------
+============
+
Thanks to
Karsten Keil
- for his help with isdn4linux
+ for his help with isdn4linux
Deti Fliegl
- for his base driver code
+ for his base driver code
Dennis Dietrich
- for his kernel 2.6 patches
+ for his kernel 2.6 patches
Andreas Rummel
- for his work and logs to get unimodem mode working
+ for his work and logs to get unimodem mode working
Andreas Degert
- for his logs and patches to get cx 100 working
+ for his logs and patches to get cx 100 working
Dietrich Feist
- for his generous donation of one M105 and two M101 cordless adapters
+ for his generous donation of one M105 and two M101 cordless adapters
Christoph Schweers
- for his generous donation of a M34 device
+ for his generous donation of a M34 device
and all the other people who sent logs and other information.
-
diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst
similarity index 80%
rename from Documentation/isdn/README.hysdn
rename to Documentation/isdn/hysdn.rst
index eeca11f00ccd..0a168d1cbffc 100644
--- a/Documentation/isdn/README.hysdn
+++ b/Documentation/isdn/hysdn.rst
@@ -1,4 +1,7 @@
-$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
+============
+Hysdn Driver
+============
+
The hysdn driver has been written by
Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
@@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany.
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-Table of contents
-=================
+.. Table of contents
-1. About the driver
+ 1. About the driver
-2. Loading/Unloading the driver
+ 2. Loading/Unloading the driver
-3. Entries in the /proc filesystem
+ 3. Entries in the /proc filesystem
-4. The /proc/net/hysdn/cardconfX file
+ 4. The /proc/net/hysdn/cardconfX file
-5. The /proc/net/hysdn/cardlogX file
+ 5. The /proc/net/hysdn/cardlogX file
-6. Where to get additional info and help
+ 6. Where to get additional info and help
1. About the driver
+===================
- The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
+ The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
enable ISDN support in the kernel config and support for HYSDN cards in
- the active cards submenu. The driver may only be compiled and used if
+ the active cards submenu. The driver may only be compiled and used if
support for loadable modules and the process filesystem have been enabled.
These cards provide two different interfaces to the kernel. Without the
@@ -52,22 +55,23 @@ Table of contents
handlers for various protocols like ppp and others as well as config info
and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
- With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
- compliant devices with either CAPI 2.0 applications
+ With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+ compliant devices with either CAPI 2.0 applications
(check isdn4k-utils) or -using the capidrv module- as a regular
- isdn4linux device. This is done via the same mechanism as with the
+ isdn4linux device. This is done via the same mechanism as with the
active AVM cards and in fact uses the same module.
-
+
2. Loading/Unloading the driver
+===============================
The module has no command line parameters and auto detects up to 10 cards
in the id-range 0-9.
If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
- subdir need to be closed and all ethernet interfaces allocated by this
+ subdir need to be closed and all ethernet interfaces allocated by this
driver must be shut down. Otherwise the module counter will avoid a module
unload.
-
+
If you are using the CAPI 2.0-interface, make sure to load/modprobe the
kernelcapi-module first.
@@ -76,52 +80,57 @@ Table of contents
any avm-specific modules).
3. Entries in the /proc filesystem
+==================================
- When the module has been loaded it adds the directory hysdn in the
- /proc/net tree. This directory contains exactly 2 file entries for each
+ When the module has been loaded it adds the directory hysdn in the
+ /proc/net tree. This directory contains exactly 2 file entries for each
card. One is called cardconfX and the other cardlogX, where X is the
- card id number from 0 to 9.
+ card id number from 0 to 9.
The cards are numbered in the order found in the PCI config data.
4. The /proc/net/hysdn/cardconfX file
+=====================================
- This file may be read to get by everyone to get info about the cards type,
+ This file may be read to get by everyone to get info about the cards type,
actual state, available features and used resources.
The first 3 entries (id, bus and slot) are PCI info fields, the following
type field gives the information about the cards type:
- 4 -> Ergo card (server card with 2 b-chans)
- 5 -> Metro card (server card with 4 or 8 b-chans)
- 6 -> Champ card (client card with 2 b-chans)
+ - 4 -> Ergo card (server card with 2 b-chans)
+ - 5 -> Metro card (server card with 4 or 8 b-chans)
+ - 6 -> Champ card (client card with 2 b-chans)
The following 3 fields show the hardware assignments for irq, iobase and the
dual ported memory (dp-mem).
+
The fields b-chans and fax-chans announce the available card resources of
this types for the user.
+
The state variable indicates the actual drivers state for this card with the
following assignments.
- 0 -> card has not been booted since driver load
- 1 -> card booting is actually in progess
- 2 -> card is in an error state due to a previous boot failure
- 3 -> card is booted and active
+ - 0 -> card has not been booted since driver load
+ - 1 -> card booting is actually in progess
+ - 2 -> card is in an error state due to a previous boot failure
+ - 3 -> card is booted and active
And the last field (device) shows the name of the ethernet device assigned
to this card. Up to the first successful boot this field only shows a -
to tell that no net device has been allocated up to now. Once a net device
has been allocated it remains assigned to this card, even if a card is
- rebooted and an boot error occurs.
+ rebooted and an boot error occurs.
- Writing to the cardconfX file boots the card or transfers config lines to
- the cards firmware. The type of data is automatically detected when the
+ Writing to the cardconfX file boots the card or transfers config lines to
+ the cards firmware. The type of data is automatically detected when the
first data is written. Only root has write access to this file.
The firmware boot files are normally called hyclient.pof for client cards
and hyserver.pof for server cards.
After successfully writing the boot file, complete config files or single
config lines may be copied to this file.
- If an error occurs the return value given to the writing process has the
+ If an error occurs the return value given to the writing process has the
following additional codes (decimal):
+ ==== ============================================
1000 Another process is currently bootng the card
1001 Invalid firmware header
1002 Boards dual-port RAM test failed
@@ -131,34 +140,39 @@ Table of contents
1006 Second boot stage failure
1007 Timeout waiting for card ready during boot
1008 Operation only allowed in booted state
- 1009 Config line too long
- 1010 Invalid channel number
+ 1009 Config line too long
+ 1010 Invalid channel number
1011 Timeout sending config data
+ ==== ============================================
- Additional info about error reasons may be fetched from the log output.
+ Additional info about error reasons may be fetched from the log output.
5. The /proc/net/hysdn/cardlogX file
-
- The cardlogX file entry may be opened multiple for reading by everyone to
+====================================
+
+ The cardlogX file entry may be opened multiple for reading by everyone to
get the cards and drivers log data. Card messages always start with the
- keyword LOG. All other lines are output from the driver.
- The driver log data may be redirected to the syslog by selecting the
+ keyword LOG. All other lines are output from the driver.
+ The driver log data may be redirected to the syslog by selecting the
appropriate bitmask. The cards log messages will always be send to this
interface but never to the syslog.
A root user may write a decimal or hex (with 0x) value t this file to select
- desired output options. As mentioned above the cards log dat is always
+ desired output options. As mentioned above the cards log dat is always
written to the cardlog file independent of the following options only used
to check and debug the driver itself:
- For example:
- echo "0x34560078" > /proc/net/hysdn/cardlog0
+ For example::
+
+ echo "0x34560078" > /proc/net/hysdn/cardlog0
+
to output the hex log mask 34560078 for card 0.
-
- The written value is regarded as an unsigned 32-Bit value, bit ored for
+
+ The written value is regarded as an unsigned 32-Bit value, bit ored for
desired output. The following bits are already assigned:
- 0x80000000 All driver log data is alternatively via syslog
+ ========== ============================================================
+ 0x80000000 All driver log data is alternatively via syslog
0x00000001 Log memory allocation errors
0x00000010 Firmware load start and close are logged
0x00000020 Log firmware record parser
@@ -171,25 +185,12 @@ Table of contents
0x00100000 Log all open and close actions to /proc/net/hysdn/card files
0x00200000 Log all actions from /proc file entries
0x00010000 Log network interface init and deinit
-
+ ========== ============================================================
+
6. Where to get additional info and help
+========================================
- If you have any problems concerning the driver or configuration contact
+ If you have any problems concerning the driver or configuration contact
the Hypercope support team (support@hypercope.de) and or the authors
Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
Ulrich Albrecht (ualbrecht@hypercope.de).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
new file mode 100644
index 000000000000..407e74b78372
--- /dev/null
+++ b/Documentation/isdn/index.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ISDN
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ interface_capi
+
+ avmb1
+ gigaset
+ hysdn
+ m_isdn
+
+ credits
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst
similarity index 75%
rename from Documentation/isdn/INTERFACE.CAPI
rename to Documentation/isdn/interface_capi.rst
index 021aa9cf139d..01a4b5ade9a4 100644
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/interface_capi.rst
@@ -1,7 +1,9 @@
+=========================================
Kernel CAPI Interface to Hardware Drivers
------------------------------------------
+=========================================
1. Overview
+===========
From the CAPI 2.0 specification:
COMMON-ISDN-API (CAPI) is an application programming interface standard used
@@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org.
2. Driver and Device Registration
+=================================
CAPI drivers optionally register themselves with Kernel CAPI by calling the
Kernel CAPI function register_capi_driver() with a pointer to a struct
@@ -50,6 +53,7 @@ callback functions by Kernel CAPI.
3. Application Registration and Communication
+=============================================
Kernel CAPI forwards registration requests from applications (calls to CAPI
operation CAPI_REGISTER) to an appropriate hardware driver by calling its
@@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore.
4. Data Structures
+==================
4.1 struct capi_driver
+----------------------
This structure describes a Kernel CAPI driver itself. It is used in the
register_capi_driver() and unregister_capi_driver() functions, and contains
the following non-private fields, all to be set by the driver before calling
register_capi_driver():
-char name[32]
+``char name[32]``
the name of the driver, as a zero-terminated ASCII string
-char revision[32]
+``char revision[32]``
the revision number of the driver, as a zero-terminated ASCII string
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
+``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
a callback function pointer (may be NULL)
4.2 struct capi_ctr
+-------------------
This structure describes an ISDN device (controller) handled by a Kernel CAPI
driver. After registration via the attach_capi_ctr() function it is passed to
@@ -96,88 +103,109 @@ identify the controller to operate on.
It contains the following non-private fields:
-- to be set by the driver before calling attach_capi_ctr():
+to be set by the driver before calling attach_capi_ctr():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-struct module *owner
+``struct module *owner``
pointer to the driver module owning the device
-void *driverdata
+``void *driverdata``
an opaque pointer to driver specific data, not touched by Kernel CAPI
-char name[32]
+``char name[32]``
the name of the controller, as a zero-terminated ASCII string
-char *driver_name
+``char *driver_name``
the name of the driver, as a zero-terminated ASCII string
-int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
+``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
(optional) pointer to a callback function for sending firmware and
configuration data to the device
+
The function may return before the operation has completed.
+
Completion must be signalled by a call to capi_ctr_ready().
+
Return value: 0 on success, error code on error
Called in process context.
-void (*reset_ctr)(struct capi_ctr *ctrlr)
+``void (*reset_ctr)(struct capi_ctr *ctrlr)``
(optional) pointer to a callback function for stopping the device,
releasing all registered applications
+
The function may return before the operation has completed.
+
Completion must be signalled by a call to capi_ctr_down().
+
Called in process context.
-void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
- capi_register_params *rparam)
-void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
- pointers to callback functions for registration and deregistration of
+``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
+ pointers to callback function for registration of
applications with the device
+
+ Calls to these functions are serialized by Kernel CAPI so that only
+ one call to any of them is active at any time.
+
+``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
+ pointers to callback functions deregistration of
+ applications with the device
+
Calls to these functions are serialized by Kernel CAPI so that only
one call to any of them is active at any time.
-u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
+``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
pointer to a callback function for sending a CAPI message to the
device
+
Return value: CAPI error code
+
If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
of the skb and the caller may no longer access it. If it returns a
non-zero (error) value then ownership of the skb returns to the caller
who may reuse or free it.
+
The return value should only be used to signal problems with respect
to accepting or queueing the message. Errors occurring during the
actual processing of the message should be signaled with an
appropriate reply message.
+
May be called in process or interrupt context.
+
Calls to this function are not serialized by Kernel CAPI, ie. it must
be prepared to be re-entered.
-char *(*procinfo)(struct capi_ctr *ctrlr)
+``char *(*procinfo)(struct capi_ctr *ctrlr)``
pointer to a callback function returning the entry for the device in
the CAPI controller info table, /proc/capi/controller
-const struct file_operations *proc_fops
+``const struct file_operations *proc_fops``
pointers to callback functions for the device's proc file
system entry, /proc/capi/controllers/<n>; pointer to the device's
capi_ctr structure is available from struct proc_dir_entry::data
which is available from struct inode.
-Note: Callback functions except send_message() are never called in interrupt
-context.
+Note:
+ Callback functions except send_message() are never called in interrupt
+ context.
-- to be filled in before calling capi_ctr_ready():
+to be filled in before calling capi_ctr_ready():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-u8 manu[CAPI_MANUFACTURER_LEN]
+``u8 manu[CAPI_MANUFACTURER_LEN]``
value to return for CAPI_GET_MANUFACTURER
-capi_version version
+``capi_version version``
value to return for CAPI_GET_VERSION
-capi_profile profile
+``capi_profile profile``
value to return for CAPI_GET_PROFILE
-u8 serial[CAPI_SERIAL_LEN]
+``u8 serial[CAPI_SERIAL_LEN]``
value to return for CAPI_GET_SERIAL
4.3 SKBs
+--------
CAPI messages are passed between Kernel CAPI and the driver via send_message()
and capi_ctr_handle_message(), stored in the data portion of a socket buffer
@@ -192,6 +220,7 @@ instead of 30.
4.4 The _cmsg Structure
+-----------------------
(declared in <linux/isdn/capiutil.h>)
@@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they
represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
types are:
+=========== =================================================================
u8 for CAPI parameters of type 'byte'
u16 for CAPI parameters of type 'word'
@@ -235,6 +265,7 @@ _cmstruct alternative representation for CAPI parameters of type 'struct'
CAPI_COMPOSE: The parameter is present.
Subparameter values are stored individually in the corresponding
_cmsg structure members.
+=========== =================================================================
Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
messages between their transport encoding described in the CAPI 2.0 standard
@@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message.
5. Lower Layer Interface Functions
+==================================
(declared in <linux/isdn/capilli.h>)
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
- register/unregister a driver with Kernel CAPI
-
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
- register/unregister a device (controller) with Kernel CAPI
-
-void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_down(struct capi_ctr *ctrlr)
- signal controller ready/not ready
-
-void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
- signal suspend/resume
-
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
- struct sk_buff *skb)
- pass a received CAPI message to Kernel CAPI
- for forwarding to the specified application
+::
+
+ void register_capi_driver(struct capi_driver *drvr)
+ void unregister_capi_driver(struct capi_driver *drvr)
+
+register/unregister a driver with Kernel CAPI
+
+::
+
+ int attach_capi_ctr(struct capi_ctr *ctrlr)
+ int detach_capi_ctr(struct capi_ctr *ctrlr)
+
+register/unregister a device (controller) with Kernel CAPI
+
+::
+
+ void capi_ctr_ready(struct capi_ctr *ctrlr)
+ void capi_ctr_down(struct capi_ctr *ctrlr)
+
+signal controller ready/not ready
+
+::
+
+ void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
+ void capi_ctr_resume_output(struct capi_ctr *ctrlr)
+
+signal suspend/resume
+
+::
+
+ void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
+ struct sk_buff *skb)
+
+pass a received CAPI message to Kernel CAPI
+for forwarding to the specified application
6. Helper Functions and Macros
+==============================
Library functions (from <linux/isdn/capilli.h>):
-void capilib_new_ncci(struct list_head *head, u16 applid,
+::
+
+ void capilib_new_ncci(struct list_head *head, u16 applid,
u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
+ void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
+ void capilib_release_appl(struct list_head *head, u16 applid)
+ void capilib_release(struct list_head *head)
+ void capilib_data_b3_conf(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
-u16 capilib_data_b3_req(struct list_head *head, u16 applid,
+ u16 capilib_data_b3_req(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
Macros to extract/set element values from/in a CAPI message header
(from <linux/isdn/capiutil.h>):
+====================== ============================= ====================
Get Macro Set Macro Element (Type)
-
+====================== ============================= ====================
CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
@@ -300,31 +351,31 @@ CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
(u32)
CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
+====================== ============================= ====================
Library functions for working with _cmsg structures
(from <linux/isdn/capiutil.h>):
-unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
- Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
- result in *msg.
+``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
+ Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
+ storing the result in ``*msg``.
-unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
- Disassembles the CAPI 2.0 message in *msg, storing the parameters in
- *cmsg.
+``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
+ Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
+ in ``*cmsg``.
-unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
- u16 Messagenumber, u32 Controller)
- Fills the header part and address field of the _cmsg structure *cmsg
+``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
+ Fills the header part and address field of the _cmsg structure ``*cmsg``
with the given values, zeroing the remainder of the structure so only
parameters with non-default values need to be changed before sending
the message.
-void capi_cmsg_answer(_cmsg *cmsg)
- Sets the low bit of the Subcommand field in *cmsg, thereby converting
- _REQ to _CONF and _IND to _RESP.
+``void capi_cmsg_answer(_cmsg *cmsg)``
+ Sets the low bit of the Subcommand field in ``*cmsg``, thereby
+ converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
-char *capi_cmd2str(u8 Command, u8 Subcommand)
+``char *capi_cmd2str(u8 Command, u8 Subcommand)``
Returns the CAPI 2.0 message name corresponding to the given command
and subcommand values, as a static ASCII string. The return value may
be NULL if the command/subcommand is not one of those defined in the
@@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand)
7. Debugging
+============
The module kernelcapi has a module parameter showcapimsgs controlling some
debugging output produced by the module. It can only be set when the module is
diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst
similarity index 89%
rename from Documentation/isdn/README.mISDN
rename to Documentation/isdn/m_isdn.rst
index cd8bf920e77b..9957de349e69 100644
--- a/Documentation/isdn/README.mISDN
+++ b/Documentation/isdn/m_isdn.rst
@@ -1,6 +1,9 @@
+============
+mISDN Driver
+============
+
mISDN is a new modular ISDN driver, in the long term it should replace
the old I4L driver architecture for passiv ISDN cards.
It was designed to allow a broad range of applications and interfaces
but only have the basic function in kernel, the interface to the user
space is based on sockets with a own address family AF_ISDN.
-
diff --git a/drivers/staging/isdn/hysdn/Kconfig b/drivers/staging/isdn/hysdn/Kconfig
index 1971ef850c9a..4c8a9283b9dd 100644
--- a/drivers/staging/isdn/hysdn/Kconfig
+++ b/drivers/staging/isdn/hysdn/Kconfig
@@ -5,7 +5,7 @@ config HYSDN
help
Say Y here if you have one of Hypercope's active PCI ISDN cards
Champ, Ergo and Metro. You will then get a module called hysdn.
- Please read the file <file:Documentation/isdn/README.hysdn> for more
+ Please read the file <file:Documentation/isdn/hysdn.rst> for more
information.
config HYSDN_CAPI
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 15/26] docs: isdn: convert to ReST and add to kAPI bookset
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (18 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: devel, Karsten Keil, linux-doc, Greg Kroah-Hartman,
Jonathan Corbet, netdev, Mauro Carvalho Chehab
The ISDN documentation is a mix of admin guide, uAPI and kAPI.
Ideally, it should be split. Yet, not sure if it would worth
the troble. Anyway, we have the same kind of mix on several
drivers specific documentation. So, just like the others, keep
the directory at the root Documentation/ tree, just adding a
pointer to it at the kAPI section, as the documentation was
written with the Kernel developers in mind.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
.../isdn/{README.avmb1 => avmb1.rst} | 231 ++++++++------
Documentation/isdn/{CREDITS => credits.rst} | 7 +-
.../isdn/{README.gigaset => gigaset.rst} | 290 +++++++++++-------
.../isdn/{README.hysdn => hysdn.rst} | 125 ++++----
Documentation/isdn/index.rst | 24 ++
.../{INTERFACE.CAPI => interface_capi.rst} | 182 +++++++----
.../isdn/{README.mISDN => m_isdn.rst} | 5 +-
drivers/staging/isdn/hysdn/Kconfig | 2 +-
9 files changed, 536 insertions(+), 331 deletions(-)
rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
rename Documentation/isdn/{CREDITS => credits.rst} (96%)
rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
create mode 100644 Documentation/isdn/index.rst
rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 6402f62ac90f..de7be1c31450 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -106,6 +106,7 @@ needed).
hid/index
i2c/index
iio/index
+ isdn/index
infiniband/index
leds/index
media/index
diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst
similarity index 50%
rename from Documentation/isdn/README.avmb1
rename to Documentation/isdn/avmb1.rst
index 9e075484ef1e..de3961e67553 100644
--- a/Documentation/isdn/README.avmb1
+++ b/Documentation/isdn/avmb1.rst
@@ -1,4 +1,6 @@
-Driver for active AVM Controller.
+================================
+Driver for active AVM Controller
+================================
The driver provides a kernel capi2.0 Interface (kernelcapi) and
on top of this a User-Level-CAPI2.0-interface (capi)
@@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils.
t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
Currently supported cards:
- B1 ISA (all versions)
- B1 PCI
- T1/T1B (HEMA card)
- M1
- M2
- B1 PCMCIA
+
+ - B1 ISA (all versions)
+ - B1 PCI
+ - T1/T1B (HEMA card)
+ - M1
+ - M2
+ - B1 PCMCIA
Installing
----------
You need at least /dev/capi20 to load the firmware.
-mknod /dev/capi20 c 68 0
-mknod /dev/capi20.00 c 68 1
-mknod /dev/capi20.01 c 68 2
-.
-.
-.
-mknod /dev/capi20.19 c 68 20
+::
+
+ mknod /dev/capi20 c 68 0
+ mknod /dev/capi20.00 c 68 1
+ mknod /dev/capi20.01 c 68 2
+ .
+ .
+ .
+ mknod /dev/capi20.19 c 68 20
Running
-------
@@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware.
AVM GmbH provides several t4-files for the different D-channel
protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
-if you configure as modules load the modules this way:
-
-insmod /lib/modules/current/misc/capiutil.o
-insmod /lib/modules/current/misc/b1.o
-insmod /lib/modules/current/misc/kernelcapi.o
-insmod /lib/modules/current/misc/capidrv.o
-insmod /lib/modules/current/misc/capi.o
-
-if you have an B1-PCI card load the module b1pci.o
-insmod /lib/modules/current/misc/b1pci.o
-and load the firmware with
-avmcapictrl load /lib/isdn/b1.t4 1
+if you configure as modules load the modules this way::
+
+ insmod /lib/modules/current/misc/capiutil.o
+ insmod /lib/modules/current/misc/b1.o
+ insmod /lib/modules/current/misc/kernelcapi.o
+ insmod /lib/modules/current/misc/capidrv.o
+ insmod /lib/modules/current/misc/capi.o
+
+if you have an B1-PCI card load the module b1pci.o::
+
+ insmod /lib/modules/current/misc/b1pci.o
+
+and load the firmware with::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
if you have an B1-ISA card load the module b1isa.o
-and add the card by calling
-avmcapictrl add 0x150 15
-and load the firmware by calling
-avmcapictrl load /lib/isdn/b1.t4 1
+and add the card by calling::
+
+ avmcapictrl add 0x150 15
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/b1.t4 1
if you have an T1-ISA card load the module t1isa.o
-and add the card by calling
-avmcapictrl add 0x450 15 T1 0
-and load the firmware by calling
-avmcapictrl load /lib/isdn/t1.t4 1
+and add the card by calling::
+
+ avmcapictrl add 0x450 15 T1 0
+
+and load the firmware by calling::
+
+ avmcapictrl load /lib/isdn/t1.t4 1
if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
before you insert the card.
Leased Lines with B1
--------------------
+
Init card and load firmware.
+
For an D64S use "FV: 1" as phone number
+
For an D64S2 use "FV: 1" and "FV: 2" for multilink
or "FV: 1,2" to use CAPI channel bundling.
/proc-Interface
-----------------
-/proc/capi:
+/proc/capi::
+
dr-xr-xr-x 2 root root 0 Jul 1 14:03 .
dr-xr-xr-x 82 root root 0 Jun 30 19:08 ..
-r--r--r-- 1 root root 0 Jul 1 14:03 applications
@@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling.
/proc/capi/applications:
applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
- level3cnt: capi_register parameter
- datablkcnt: capi_register parameter
- ncci-cnt: current number of nccis (connections)
- recvqueuelen: number of messages on receive queue
- for example:
-1 -2 16 2048 1 0
-2 2 7 2048 1 0
+ level3cnt:
+ capi_register parameter
+ datablkcnt:
+ capi_register parameter
+ ncci-cnt:
+ current number of nccis (connections)
+ recvqueuelen:
+ number of messages on receive queue
+
+ for example::
+
+ 1 -2 16 2048 1 0
+ 2 2 7 2048 1 0
/proc/capi/applstats:
applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
- recvctlmsg: capi messages received without DATA_B3_IND
- recvdatamsg: capi DATA_B3_IND received
- sentctlmsg: capi messages sent without DATA_B3_REQ
- sentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2057 1699 1721 1699
+ recvctlmsg:
+ capi messages received without DATA_B3_IND
+ recvdatamsg:
+ capi DATA_B3_IND received
+ sentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ sentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2057 1699 1721 1699
/proc/capi/capi20: statistics of capi.o (/dev/capi20)
minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- minor: minor device number of capi device
- nopen: number of calls to devices open
- nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
+ minor:
+ minor device number of capi device
+ nopen:
+ number of calls to devices open
+ nrecvdropmsg:
+ capi messages dropped (messages in recvqueue in close)
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
- for example:
-1 2 18 0 16 2
+ for example::
+
+ 1 2 18 0 16 2
/proc/capi/capidrv: statistics of capidrv.o (capi messages)
nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
for example:
-2780 2226 2256 2226
+ 2780 2226 2256 2226
/proc/capi/controller:
controller drivername state cardname controllerinfo
- for example:
-1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
-2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
-3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
+
+ for example::
+
+ 1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19
+ 2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0
+ 3 b1pcmcia running m2-150 B1 3.07-01 0x150 5
/proc/capi/contrstats:
controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
- nrecvctlmsg: capi messages received without DATA_B3_IND
- nrecvdatamsg: capi DATA_B3_IND received
- nsentctlmsg: capi messages sent without DATA_B3_REQ
- nsentdatamsg: capi DATA_B3_REQ sent
- for example:
-1 2845 2272 2310 2274
-2 2 0 2 0
-3 2 0 2 0
+ nrecvctlmsg:
+ capi messages received without DATA_B3_IND
+ nrecvdatamsg:
+ capi DATA_B3_IND received
+ nsentctlmsg:
+ capi messages sent without DATA_B3_REQ
+ nsentdatamsg:
+ capi DATA_B3_REQ sent
+
+ for example::
+
+ 1 2845 2272 2310 2274
+ 2 2 0 2 0
+ 3 2 0 2 0
/proc/capi/driver:
drivername ncontroller
- for example:
-b1pci 1
-t1isa 1
-b1pcmcia 1
-b1isa 0
+
+ for example::
+
+ b1pci 1
+ t1isa 1
+ b1pcmcia 1
+ b1isa 0
/proc/capi/ncci:
apllid ncci winsize sendwindow
- for example:
-1 0x10101 8 0
+
+ for example::
+
+ 1 0x10101 8 0
/proc/capi/users: kernelmodules that use the kernelcapi.
name
- for example:
-capidrv
-capi20
+
+ for example::
+
+ capidrv
+ capi20
Questions
---------
+
Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
linux-avmb1@calle.in-berlin.de mailing list by sending
a mail to majordomo@calle.in-berlin.de with
@@ -178,9 +236,10 @@ in the body.
German documentation and several scripts can be found at
ftp://ftp.avm.de/cardware/b1/linux/
-Bugs
+Bugs
----
-If you find any please let me know.
+
+If you find any please let me know.
Enjoy,
diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst
similarity index 96%
rename from Documentation/isdn/CREDITS
rename to Documentation/isdn/credits.rst
index c1679e913fca..319323f2091f 100644
--- a/Documentation/isdn/CREDITS
+++ b/Documentation/isdn/credits.rst
@@ -1,3 +1,7 @@
+=======
+Credits
+=======
+
I want to thank all who contributed to this project and especially to:
(in alphabetical order)
@@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de)
For creating and maintaining the FAQ.
Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
- For creating the FAQ, and the leafsite HOWTO.
+ For creating the FAQ, and the leafsite HOWTO.
Michael 'Ghandi' Herold (michael@abadonna.franken.de)
For contribution of the vbox answering machine.
@@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
Thomas Uhl (uhl@think.de)
For distributing the cards.
For pushing me to work ;-)
-
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst
similarity index 74%
rename from Documentation/isdn/README.gigaset
rename to Documentation/isdn/gigaset.rst
index f6184b637182..98b4ec521c51 100644
--- a/Documentation/isdn/README.gigaset
+++ b/Documentation/isdn/gigaset.rst
@@ -1,33 +1,36 @@
+==========================
GigaSet 307x Device Driver
==========================
1. Requirements
- ------------
+=================
+
1.1. Hardware
- --------
+-------------
+
This driver supports the connection of the Gigaset 307x/417x family of
ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
connection. The following devices are reported to be compatible:
Bases:
- Siemens Gigaset 3070/3075 isdn
- Siemens Gigaset 4170/4175 isdn
- Siemens Gigaset SX205/255
- Siemens Gigaset SX353
- T-Com Sinus 45 [AB] isdn
- T-Com Sinus 721X[A] [SE]
- Vox Chicago 390 ISDN (KPN Telecom)
+ - Siemens Gigaset 3070/3075 isdn
+ - Siemens Gigaset 4170/4175 isdn
+ - Siemens Gigaset SX205/255
+ - Siemens Gigaset SX353
+ - T-Com Sinus 45 [AB] isdn
+ - T-Com Sinus 721X[A] [SE]
+ - Vox Chicago 390 ISDN (KPN Telecom)
RS232 data boxes:
- Siemens Gigaset M101 Data
- T-Com Sinus 45 Data 1
+ - Siemens Gigaset M101 Data
+ - T-Com Sinus 45 Data 1
USB data boxes:
- Siemens Gigaset M105 Data
- Siemens Gigaset USB Adapter DECT
- T-Com Sinus 45 Data 2
- T-Com Sinus 721 data
- Chicago 390 USB (KPN)
+ - Siemens Gigaset M105 Data
+ - Siemens Gigaset USB Adapter DECT
+ - T-Com Sinus 45 Data 2
+ - T-Com Sinus 721 data
+ - Chicago 390 USB (KPN)
See also http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
@@ -37,17 +40,21 @@ GigaSet 307x Device Driver
with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
If you have another device that works with our driver, please let us know.
- Chances of getting an USB device to work are good if the output of
- lsusb
- at the command line contains one of the following:
- ID 0681:0001
- ID 0681:0002
- ID 0681:0009
- ID 0681:0021
- ID 0681:0022
+ Chances of getting an USB device to work are good if the output of::
+
+ lsusb
+
+ at the command line contains one of the following::
+
+ ID 0681:0001
+ ID 0681:0002
+ ID 0681:0009
+ ID 0681:0021
+ ID 0681:0022
1.2. Software
- --------
+-------------
+
The driver works with the Kernel CAPI subsystem and can be used with any
software which is able to use CAPI 2.0 for ISDN connections (voice or data).
@@ -58,9 +65,11 @@ GigaSet 307x Device Driver
2. How to use the driver
- ---------------------
+==========================
+
2.1. Modules
- -------
+------------
+
For the devices to work, the proper kernel modules have to be loaded.
This normally happens automatically when the system detects the USB
device (base, M105) or when the line discipline is attached (M101). It
@@ -71,13 +80,17 @@ GigaSet 307x Device Driver
which uses the regular serial port driver to access the device, and must
therefore be attached to the serial device to which the M101 is connected.
The ldattach(8) command (included in util-linux-ng release 2.14 or later)
- can be used for that purpose, for example:
+ can be used for that purpose, for example::
+
ldattach GIGASET_M101 /dev/ttyS1
+
This will open the device file, attach the line discipline to it, and
then sleep in the background, keeping the device open so that the line
discipline remains active. To deactivate it, kill the daemon, for example
- with
+ with::
+
killall ldattach
+
before disconnecting the device. To have this happen automatically at
system startup/shutdown on an LSB compatible system, create and activate
an appropriate LSB startup script /etc/init.d/gigaset. (The init name
@@ -86,9 +99,10 @@ GigaSet 307x Device Driver
The modules accept the following parameters:
- Module Parameter Meaning
+ =============== ========== ==========================================
+ Module Parameter Meaning
- gigaset debug debug level (see section 3.2.)
+ gigaset debug debug level (see section 3.2.)
startmode initial operation mode (see section 2.5.):
bas_gigaset ) 1=CAPI (default), 0=Unimodem
@@ -96,11 +110,14 @@ GigaSet 307x Device Driver
usb_gigaset ) cidmode initial Call-ID mode setting (see section
2.5.): 1=on (default), 0=off
+ =============== ========== ==========================================
+
Depending on your distribution you may want to create a separate module
configuration file like /etc/modprobe.d/gigaset.conf for these.
2.2. Device nodes for user space programs
- ------------------------------------
+-----------------------------------------
+
The device can be accessed from user space (eg. by the user space tools
mentioned in 1.2.) through the device nodes:
@@ -113,46 +130,56 @@ GigaSet 307x Device Driver
You can also set a "default device" for the user space tools to use when
no device node is given as parameter, by creating a symlink /dev/ttyG to
- one of them, eg.:
+ one of them, eg.::
ln -s /dev/ttyGB0 /dev/ttyG
The devices accept the following device specific ioctl calls
(defined in gigaset_dev.h):
- ioctl(int fd, GIGASET_REDIR, int *cmd);
+ ``ioctl(int fd, GIGASET_REDIR, int *cmd);``
+
If cmd==1, the device is set to be controlled exclusively through the
character device node; access from the ISDN subsystem is blocked.
+
If cmd==0, the device is set to be used from the ISDN subsystem and does
not communicate through the character device node.
- ioctl(int fd, GIGASET_CONFIG, int *cmd);
+ ``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
+
(ser_gigaset and usb_gigaset only)
+
If cmd==1, the device is set to adapter configuration mode where commands
are interpreted by the M10x DECT adapter itself instead of being
forwarded to the base station. In this mode, the device accepts the
commands described in Siemens document "AT-Kommando Alignment M10x Data"
for setting the operation mode, associating with a base station and
querying parameters like field strengh and signal quality.
+
Note that there is no ioctl command for leaving adapter configuration
mode and returning to regular operation. In order to leave adapter
configuration mode, write the command ATO to the device.
- ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
+ ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
+
(usb_gigaset only)
+
Set the break characters on an M105's internal serial adapter to the six
bytes stored in brkchars[]. Unused bytes should be set to zero.
ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
Retrieve version information from the driver. version[0] must be set to
one of:
+
- GIGVER_DRIVER: retrieve driver version
- GIGVER_COMPAT: retrieve interface compatibility version
- GIGVER_FWBASE: retrieve the firmware version of the base
+
Upon return, version[] is filled with the requested version information.
2.3. CAPI
- ----
+---------
+
The devices will show up as CAPI controllers as soon as the
corresponding driver module is loaded, and can then be used with
CAPI 2.0 kernel and user space applications. For user space access,
@@ -165,21 +192,22 @@ GigaSet 307x Device Driver
driver.
2.5. Unimodem mode
- -------------
+------------------
+
In this mode the device works like a modem connected to a serial port
- (the /dev/ttyGU0, ... mentioned above) which understands the commands
+ (the /dev/ttyGU0, ... mentioned above) which understands the commands::
- ATZ init, reset
- => OK or ERROR
- ATD
- ATDT dial
- => OK, CONNECT,
- BUSY,
- NO DIAL TONE,
- NO CARRIER,
- NO ANSWER
- <pause>+++<pause> change to command mode when connected
- ATH hangup
+ ATZ init, reset
+ => OK or ERROR
+ ATD
+ ATDT dial
+ => OK, CONNECT,
+ BUSY,
+ NO DIAL TONE,
+ NO CARRIER,
+ NO ANSWER
+ <pause>+++<pause> change to command mode when connected
+ ATH hangup
You can use some configuration tool of your distribution to configure this
"modem" or configure pppd/wvdial manually. There are some example ppp
@@ -189,40 +217,52 @@ GigaSet 307x Device Driver
control lines. This means you must use "Stupid Mode" if you are using
wvdial or you should use the nocrtscts option of pppd.
You must also assure that the ppp_async module is loaded with the parameter
- flag_time=0. You can do this e.g. by adding a line like
+ flag_time=0. You can do this e.g. by adding a line like::
- options ppp_async flag_time=0
+ options ppp_async flag_time=0
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf.
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf.
Unimodem mode is needed for making some devices [e.g. SX100] work which
do not support the regular Gigaset command set. If debug output (see
- section 3.2.) shows something like this when dialing:
- CMD Received: ERROR
- Available Params: 0
- Connection State: 0, Response: -1
- gigaset_process_response: resp_code -1 in ConState 0 !
- Timeout occurred
+ section 3.2.) shows something like this when dialing::
+
+ CMD Received: ERROR
+ Available Params: 0
+ Connection State: 0, Response: -1
+ gigaset_process_response: resp_code -1 in ConState 0 !
+ Timeout occurred
+
then switching to unimodem mode may help.
If you have installed the command line tool gigacontr, you can enter
- unimodem mode using
- gigacontr --mode unimodem
- You can switch back using
- gigacontr --mode isdn
+ unimodem mode using::
+
+ gigacontr --mode unimodem
+
+ You can switch back using::
+
+ gigacontr --mode isdn
You can also put the driver directly into Unimodem mode when it's loaded,
by passing the module parameter startmode=0 to the hardware specific
- module, e.g.
+ module, e.g.::
+
modprobe usb_gigaset startmode=0
- or by adding a line like
+
+ or by adding a line like::
+
options usb_gigaset startmode=0
- to an appropriate module configuration file, like
- /etc/modprobe.d/gigaset.conf
+
+ to an appropriate module configuration file, like::
+
+ /etc/modprobe.d/gigaset.conf
2.6. Call-ID (CID) mode
- ------------------
+-----------------------
+
Call-IDs are numbers used to tag commands to, and responses from, the
Gigaset base in order to support the simultaneous handling of multiple
ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
@@ -238,6 +278,7 @@ GigaSet 307x Device Driver
During active operation, the driver switches to the necessary mode
automatically. However, for the reasons above, the mode chosen when
the device is not in use (idle) can be selected by the user.
+
- If you want to receive incoming calls, you can use the default
settings (CID mode).
- If you have several DECT data devices (M10x) which you want to use
@@ -247,25 +288,27 @@ GigaSet 307x Device Driver
If you want both of these at once, you are out of luck.
You can also use the tty class parameter "cidmode" of the device to
- change its CID mode while the driver is loaded, eg.
- echo 0 > /sys/class/tty/ttyGU0/cidmode
+ change its CID mode while the driver is loaded, eg.::
+
+ echo 0 > /sys/class/tty/ttyGU0/cidmode
2.7. Dialing Numbers
- ---------------
- The called party number provided by an application for dialing out must
+--------------------
+provided by an application for dialing out must
be a public network number according to the local dialing plan, without
any dial prefix for getting an outside line.
Internal calls can be made by providing an internal extension number
- prefixed with "**" (two asterisks) as the called party number. So to dial
- eg. the first registered DECT handset, give "**11" as the called party
- number. Dialing "***" (three asterisks) calls all extensions
+ prefixed with ``**`` (two asterisks) as the called party number. So to dial
+ eg. the first registered DECT handset, give ``**11`` as the called party
+ number. Dialing ``***`` (three asterisks) calls all extensions
simultaneously (global call).
Unimodem mode does not support internal calls.
2.8. Unregistered Wireless Devices (M101/M105)
- -----------------------------------------
+----------------------------------------------
+
The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
the M101 and M105 wireless devices to be used as ISDN devices for ISDN
connections through a Gigaset base. Therefore they assume that the device
@@ -279,73 +322,91 @@ GigaSet 307x Device Driver
modes. See the gigacontr(8) manpage for details.
3. Troubleshooting
- ---------------
+====================
+
3.1. Solutions to frequently reported problems
- -----------------------------------------
+----------------------------------------------
+
Problem:
- You have a slow provider and isdn4linux gives up dialing too early.
+ You have a slow provider and isdn4linux gives up dialing too early.
Solution:
- Load the isdn module using the dialtimeout option. You can do this e.g.
- by adding a line like
+ Load the isdn module using the dialtimeout option. You can do this e.g.
+ by adding a line like::
- options isdn dialtimeout=15
+ options isdn dialtimeout=15
- to /etc/modprobe.d/gigaset.conf or a similar file.
+ to /etc/modprobe.d/gigaset.conf or a similar file.
Problem:
- The isdnlog program emits error messages or just doesn't work.
+ The isdnlog program emits error messages or just doesn't work.
Solution:
- Isdnlog supports only the HiSax driver. Do not attempt to use it with
+ Isdnlog supports only the HiSax driver. Do not attempt to use it with
other drivers such as Gigaset.
Problem:
- You have two or more DECT data adapters (M101/M105) and only the
- first one you turn on works.
+ You have two or more DECT data adapters (M101/M105) and only the
+ first one you turn on works.
Solution:
- Select Unimodem mode for all DECT data adapters. (see section 2.5.)
+ Select Unimodem mode for all DECT data adapters. (see section 2.5.)
Problem:
- Messages like this:
+ Messages like this::
+
usb_gigaset 3-2:1.0: Could not initialize the device.
+
appear in your syslog.
Solution:
Check whether your M10x wireless device is correctly registered to the
Gigaset base. (see section 2.7.)
3.2. Telling the driver to provide more information
- ----------------------------------------------
+---------------------------------------------------
Building the driver with the "Gigaset debugging" kernel configuration
option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
information useful for debugging.
You can control the amount of debugging information the driver produces by
- writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
- echo 0 > /sys/module/gigaset/parameters/debug
+ writing an appropriate value to /sys/module/gigaset/parameters/debug,
+ e.g.::
+
+ echo 0 > /sys/module/gigaset/parameters/debug
+
switches off debugging output completely,
- echo 0x302020 > /sys/module/gigaset/parameters/debug
+
+ ::
+
+ echo 0x302020 > /sys/module/gigaset/parameters/debug
+
enables a reasonable set of debugging output messages. These values are
bit patterns where every bit controls a certain type of debugging output.
See the constants DEBUG_* in the source file gigaset.h for details.
The initial value can be set using the debug parameter when loading the
- module "gigaset", e.g. by adding a line
- options gigaset debug=0
+ module "gigaset", e.g. by adding a line::
+
+ options gigaset debug=0
+
to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
Generated debugging information can be found
- - as output of the command
- dmesg
+ - as output of the command::
+
+ dmesg
+
- in system log files written by your syslog daemon, usually
in /var/log/, e.g. /var/log/messages.
3.3. Reporting problems and bugs
- ---------------------------
+--------------------------------
If you can't solve problems with the driver on your own, feel free to
use one of the forums, bug trackers, or mailing lists on
- https://sourceforge.net/projects/gigaset307x
+
+ https://sourceforge.net/projects/gigaset307x
+
or write an electronic mail to the maintainers.
Try to provide as much information as possible, such as
+
- distribution
- kernel version (uname -r)
- gcc version (gcc --version)
@@ -362,7 +423,7 @@ GigaSet 307x Device Driver
appropriate forums and newsgroups.
3.4. Reporting problem solutions
- ---------------------------
+--------------------------------
If you solved a problem with our drivers, wrote startup scripts for your
distribution, ... feel free to contact us (using one of the places
mentioned in 3.3.). We'd like to add scripts, hints, documentation
@@ -370,34 +431,35 @@ GigaSet 307x Device Driver
4. Links, other software
- ---------------------
+==========================
+
- Sourceforge project developing this driver and associated tools
- https://sourceforge.net/projects/gigaset307x
+ https://sourceforge.net/projects/gigaset307x
- Yahoo! Group on the Siemens Gigaset family of devices
- https://de.groups.yahoo.com/group/Siemens-Gigaset
+ https://de.groups.yahoo.com/group/Siemens-Gigaset
- Siemens Gigaset/T-Sinus compatibility table
- http://www.erbze.info/sinus_gigaset.htm
+ http://www.erbze.info/sinus_gigaset.htm
(archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
5. Credits
- -------
+============
+
Thanks to
Karsten Keil
- for his help with isdn4linux
+ for his help with isdn4linux
Deti Fliegl
- for his base driver code
+ for his base driver code
Dennis Dietrich
- for his kernel 2.6 patches
+ for his kernel 2.6 patches
Andreas Rummel
- for his work and logs to get unimodem mode working
+ for his work and logs to get unimodem mode working
Andreas Degert
- for his logs and patches to get cx 100 working
+ for his logs and patches to get cx 100 working
Dietrich Feist
- for his generous donation of one M105 and two M101 cordless adapters
+ for his generous donation of one M105 and two M101 cordless adapters
Christoph Schweers
- for his generous donation of a M34 device
+ for his generous donation of a M34 device
and all the other people who sent logs and other information.
-
diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst
similarity index 80%
rename from Documentation/isdn/README.hysdn
rename to Documentation/isdn/hysdn.rst
index eeca11f00ccd..0a168d1cbffc 100644
--- a/Documentation/isdn/README.hysdn
+++ b/Documentation/isdn/hysdn.rst
@@ -1,4 +1,7 @@
-$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
+============
+Hysdn Driver
+============
+
The hysdn driver has been written by
Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
@@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany.
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
-Table of contents
-=================
+.. Table of contents
-1. About the driver
+ 1. About the driver
-2. Loading/Unloading the driver
+ 2. Loading/Unloading the driver
-3. Entries in the /proc filesystem
+ 3. Entries in the /proc filesystem
-4. The /proc/net/hysdn/cardconfX file
+ 4. The /proc/net/hysdn/cardconfX file
-5. The /proc/net/hysdn/cardlogX file
+ 5. The /proc/net/hysdn/cardlogX file
-6. Where to get additional info and help
+ 6. Where to get additional info and help
1. About the driver
+===================
- The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
+ The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
enable ISDN support in the kernel config and support for HYSDN cards in
- the active cards submenu. The driver may only be compiled and used if
+ the active cards submenu. The driver may only be compiled and used if
support for loadable modules and the process filesystem have been enabled.
These cards provide two different interfaces to the kernel. Without the
@@ -52,22 +55,23 @@ Table of contents
handlers for various protocols like ppp and others as well as config info
and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
- With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
- compliant devices with either CAPI 2.0 applications
+ With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+ compliant devices with either CAPI 2.0 applications
(check isdn4k-utils) or -using the capidrv module- as a regular
- isdn4linux device. This is done via the same mechanism as with the
+ isdn4linux device. This is done via the same mechanism as with the
active AVM cards and in fact uses the same module.
-
+
2. Loading/Unloading the driver
+===============================
The module has no command line parameters and auto detects up to 10 cards
in the id-range 0-9.
If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
- subdir need to be closed and all ethernet interfaces allocated by this
+ subdir need to be closed and all ethernet interfaces allocated by this
driver must be shut down. Otherwise the module counter will avoid a module
unload.
-
+
If you are using the CAPI 2.0-interface, make sure to load/modprobe the
kernelcapi-module first.
@@ -76,52 +80,57 @@ Table of contents
any avm-specific modules).
3. Entries in the /proc filesystem
+==================================
- When the module has been loaded it adds the directory hysdn in the
- /proc/net tree. This directory contains exactly 2 file entries for each
+ When the module has been loaded it adds the directory hysdn in the
+ /proc/net tree. This directory contains exactly 2 file entries for each
card. One is called cardconfX and the other cardlogX, where X is the
- card id number from 0 to 9.
+ card id number from 0 to 9.
The cards are numbered in the order found in the PCI config data.
4. The /proc/net/hysdn/cardconfX file
+=====================================
- This file may be read to get by everyone to get info about the cards type,
+ This file may be read to get by everyone to get info about the cards type,
actual state, available features and used resources.
The first 3 entries (id, bus and slot) are PCI info fields, the following
type field gives the information about the cards type:
- 4 -> Ergo card (server card with 2 b-chans)
- 5 -> Metro card (server card with 4 or 8 b-chans)
- 6 -> Champ card (client card with 2 b-chans)
+ - 4 -> Ergo card (server card with 2 b-chans)
+ - 5 -> Metro card (server card with 4 or 8 b-chans)
+ - 6 -> Champ card (client card with 2 b-chans)
The following 3 fields show the hardware assignments for irq, iobase and the
dual ported memory (dp-mem).
+
The fields b-chans and fax-chans announce the available card resources of
this types for the user.
+
The state variable indicates the actual drivers state for this card with the
following assignments.
- 0 -> card has not been booted since driver load
- 1 -> card booting is actually in progess
- 2 -> card is in an error state due to a previous boot failure
- 3 -> card is booted and active
+ - 0 -> card has not been booted since driver load
+ - 1 -> card booting is actually in progess
+ - 2 -> card is in an error state due to a previous boot failure
+ - 3 -> card is booted and active
And the last field (device) shows the name of the ethernet device assigned
to this card. Up to the first successful boot this field only shows a -
to tell that no net device has been allocated up to now. Once a net device
has been allocated it remains assigned to this card, even if a card is
- rebooted and an boot error occurs.
+ rebooted and an boot error occurs.
- Writing to the cardconfX file boots the card or transfers config lines to
- the cards firmware. The type of data is automatically detected when the
+ Writing to the cardconfX file boots the card or transfers config lines to
+ the cards firmware. The type of data is automatically detected when the
first data is written. Only root has write access to this file.
The firmware boot files are normally called hyclient.pof for client cards
and hyserver.pof for server cards.
After successfully writing the boot file, complete config files or single
config lines may be copied to this file.
- If an error occurs the return value given to the writing process has the
+ If an error occurs the return value given to the writing process has the
following additional codes (decimal):
+ ==== ============================================
1000 Another process is currently bootng the card
1001 Invalid firmware header
1002 Boards dual-port RAM test failed
@@ -131,34 +140,39 @@ Table of contents
1006 Second boot stage failure
1007 Timeout waiting for card ready during boot
1008 Operation only allowed in booted state
- 1009 Config line too long
- 1010 Invalid channel number
+ 1009 Config line too long
+ 1010 Invalid channel number
1011 Timeout sending config data
+ ==== ============================================
- Additional info about error reasons may be fetched from the log output.
+ Additional info about error reasons may be fetched from the log output.
5. The /proc/net/hysdn/cardlogX file
-
- The cardlogX file entry may be opened multiple for reading by everyone to
+====================================
+
+ The cardlogX file entry may be opened multiple for reading by everyone to
get the cards and drivers log data. Card messages always start with the
- keyword LOG. All other lines are output from the driver.
- The driver log data may be redirected to the syslog by selecting the
+ keyword LOG. All other lines are output from the driver.
+ The driver log data may be redirected to the syslog by selecting the
appropriate bitmask. The cards log messages will always be send to this
interface but never to the syslog.
A root user may write a decimal or hex (with 0x) value t this file to select
- desired output options. As mentioned above the cards log dat is always
+ desired output options. As mentioned above the cards log dat is always
written to the cardlog file independent of the following options only used
to check and debug the driver itself:
- For example:
- echo "0x34560078" > /proc/net/hysdn/cardlog0
+ For example::
+
+ echo "0x34560078" > /proc/net/hysdn/cardlog0
+
to output the hex log mask 34560078 for card 0.
-
- The written value is regarded as an unsigned 32-Bit value, bit ored for
+
+ The written value is regarded as an unsigned 32-Bit value, bit ored for
desired output. The following bits are already assigned:
- 0x80000000 All driver log data is alternatively via syslog
+ ========== ============================================================
+ 0x80000000 All driver log data is alternatively via syslog
0x00000001 Log memory allocation errors
0x00000010 Firmware load start and close are logged
0x00000020 Log firmware record parser
@@ -171,25 +185,12 @@ Table of contents
0x00100000 Log all open and close actions to /proc/net/hysdn/card files
0x00200000 Log all actions from /proc file entries
0x00010000 Log network interface init and deinit
-
+ ========== ============================================================
+
6. Where to get additional info and help
+========================================
- If you have any problems concerning the driver or configuration contact
+ If you have any problems concerning the driver or configuration contact
the Hypercope support team (support@hypercope.de) and or the authors
Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
Ulrich Albrecht (ualbrecht@hypercope.de).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
new file mode 100644
index 000000000000..407e74b78372
--- /dev/null
+++ b/Documentation/isdn/index.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ISDN
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ interface_capi
+
+ avmb1
+ gigaset
+ hysdn
+ m_isdn
+
+ credits
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst
similarity index 75%
rename from Documentation/isdn/INTERFACE.CAPI
rename to Documentation/isdn/interface_capi.rst
index 021aa9cf139d..01a4b5ade9a4 100644
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/interface_capi.rst
@@ -1,7 +1,9 @@
+=========================================
Kernel CAPI Interface to Hardware Drivers
------------------------------------------
+=========================================
1. Overview
+===========
From the CAPI 2.0 specification:
COMMON-ISDN-API (CAPI) is an application programming interface standard used
@@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org.
2. Driver and Device Registration
+=================================
CAPI drivers optionally register themselves with Kernel CAPI by calling the
Kernel CAPI function register_capi_driver() with a pointer to a struct
@@ -50,6 +53,7 @@ callback functions by Kernel CAPI.
3. Application Registration and Communication
+=============================================
Kernel CAPI forwards registration requests from applications (calls to CAPI
operation CAPI_REGISTER) to an appropriate hardware driver by calling its
@@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore.
4. Data Structures
+==================
4.1 struct capi_driver
+----------------------
This structure describes a Kernel CAPI driver itself. It is used in the
register_capi_driver() and unregister_capi_driver() functions, and contains
the following non-private fields, all to be set by the driver before calling
register_capi_driver():
-char name[32]
+``char name[32]``
the name of the driver, as a zero-terminated ASCII string
-char revision[32]
+``char revision[32]``
the revision number of the driver, as a zero-terminated ASCII string
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
+``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
a callback function pointer (may be NULL)
4.2 struct capi_ctr
+-------------------
This structure describes an ISDN device (controller) handled by a Kernel CAPI
driver. After registration via the attach_capi_ctr() function it is passed to
@@ -96,88 +103,109 @@ identify the controller to operate on.
It contains the following non-private fields:
-- to be set by the driver before calling attach_capi_ctr():
+to be set by the driver before calling attach_capi_ctr():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-struct module *owner
+``struct module *owner``
pointer to the driver module owning the device
-void *driverdata
+``void *driverdata``
an opaque pointer to driver specific data, not touched by Kernel CAPI
-char name[32]
+``char name[32]``
the name of the controller, as a zero-terminated ASCII string
-char *driver_name
+``char *driver_name``
the name of the driver, as a zero-terminated ASCII string
-int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
+``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
(optional) pointer to a callback function for sending firmware and
configuration data to the device
+
The function may return before the operation has completed.
+
Completion must be signalled by a call to capi_ctr_ready().
+
Return value: 0 on success, error code on error
Called in process context.
-void (*reset_ctr)(struct capi_ctr *ctrlr)
+``void (*reset_ctr)(struct capi_ctr *ctrlr)``
(optional) pointer to a callback function for stopping the device,
releasing all registered applications
+
The function may return before the operation has completed.
+
Completion must be signalled by a call to capi_ctr_down().
+
Called in process context.
-void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
- capi_register_params *rparam)
-void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
- pointers to callback functions for registration and deregistration of
+``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
+ pointers to callback function for registration of
applications with the device
+
+ Calls to these functions are serialized by Kernel CAPI so that only
+ one call to any of them is active at any time.
+
+``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
+ pointers to callback functions deregistration of
+ applications with the device
+
Calls to these functions are serialized by Kernel CAPI so that only
one call to any of them is active at any time.
-u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
+``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
pointer to a callback function for sending a CAPI message to the
device
+
Return value: CAPI error code
+
If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
of the skb and the caller may no longer access it. If it returns a
non-zero (error) value then ownership of the skb returns to the caller
who may reuse or free it.
+
The return value should only be used to signal problems with respect
to accepting or queueing the message. Errors occurring during the
actual processing of the message should be signaled with an
appropriate reply message.
+
May be called in process or interrupt context.
+
Calls to this function are not serialized by Kernel CAPI, ie. it must
be prepared to be re-entered.
-char *(*procinfo)(struct capi_ctr *ctrlr)
+``char *(*procinfo)(struct capi_ctr *ctrlr)``
pointer to a callback function returning the entry for the device in
the CAPI controller info table, /proc/capi/controller
-const struct file_operations *proc_fops
+``const struct file_operations *proc_fops``
pointers to callback functions for the device's proc file
system entry, /proc/capi/controllers/<n>; pointer to the device's
capi_ctr structure is available from struct proc_dir_entry::data
which is available from struct inode.
-Note: Callback functions except send_message() are never called in interrupt
-context.
+Note:
+ Callback functions except send_message() are never called in interrupt
+ context.
-- to be filled in before calling capi_ctr_ready():
+to be filled in before calling capi_ctr_ready():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-u8 manu[CAPI_MANUFACTURER_LEN]
+``u8 manu[CAPI_MANUFACTURER_LEN]``
value to return for CAPI_GET_MANUFACTURER
-capi_version version
+``capi_version version``
value to return for CAPI_GET_VERSION
-capi_profile profile
+``capi_profile profile``
value to return for CAPI_GET_PROFILE
-u8 serial[CAPI_SERIAL_LEN]
+``u8 serial[CAPI_SERIAL_LEN]``
value to return for CAPI_GET_SERIAL
4.3 SKBs
+--------
CAPI messages are passed between Kernel CAPI and the driver via send_message()
and capi_ctr_handle_message(), stored in the data portion of a socket buffer
@@ -192,6 +220,7 @@ instead of 30.
4.4 The _cmsg Structure
+-----------------------
(declared in <linux/isdn/capiutil.h>)
@@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they
represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
types are:
+=========== =================================================================
u8 for CAPI parameters of type 'byte'
u16 for CAPI parameters of type 'word'
@@ -235,6 +265,7 @@ _cmstruct alternative representation for CAPI parameters of type 'struct'
CAPI_COMPOSE: The parameter is present.
Subparameter values are stored individually in the corresponding
_cmsg structure members.
+=========== =================================================================
Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
messages between their transport encoding described in the CAPI 2.0 standard
@@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message.
5. Lower Layer Interface Functions
+==================================
(declared in <linux/isdn/capilli.h>)
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
- register/unregister a driver with Kernel CAPI
-
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
- register/unregister a device (controller) with Kernel CAPI
-
-void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_down(struct capi_ctr *ctrlr)
- signal controller ready/not ready
-
-void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
- signal suspend/resume
-
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
- struct sk_buff *skb)
- pass a received CAPI message to Kernel CAPI
- for forwarding to the specified application
+::
+
+ void register_capi_driver(struct capi_driver *drvr)
+ void unregister_capi_driver(struct capi_driver *drvr)
+
+register/unregister a driver with Kernel CAPI
+
+::
+
+ int attach_capi_ctr(struct capi_ctr *ctrlr)
+ int detach_capi_ctr(struct capi_ctr *ctrlr)
+
+register/unregister a device (controller) with Kernel CAPI
+
+::
+
+ void capi_ctr_ready(struct capi_ctr *ctrlr)
+ void capi_ctr_down(struct capi_ctr *ctrlr)
+
+signal controller ready/not ready
+
+::
+
+ void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
+ void capi_ctr_resume_output(struct capi_ctr *ctrlr)
+
+signal suspend/resume
+
+::
+
+ void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
+ struct sk_buff *skb)
+
+pass a received CAPI message to Kernel CAPI
+for forwarding to the specified application
6. Helper Functions and Macros
+==============================
Library functions (from <linux/isdn/capilli.h>):
-void capilib_new_ncci(struct list_head *head, u16 applid,
+::
+
+ void capilib_new_ncci(struct list_head *head, u16 applid,
u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
+ void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
+ void capilib_release_appl(struct list_head *head, u16 applid)
+ void capilib_release(struct list_head *head)
+ void capilib_data_b3_conf(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
-u16 capilib_data_b3_req(struct list_head *head, u16 applid,
+ u16 capilib_data_b3_req(struct list_head *head, u16 applid,
u32 ncci, u16 msgid)
Macros to extract/set element values from/in a CAPI message header
(from <linux/isdn/capiutil.h>):
+====================== ============================= ====================
Get Macro Set Macro Element (Type)
-
+====================== ============================= ====================
CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16)
CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16)
CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8)
@@ -300,31 +351,31 @@ CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16)
CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI
(u32)
CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16)
+====================== ============================= ====================
Library functions for working with _cmsg structures
(from <linux/isdn/capiutil.h>):
-unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
- Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
- result in *msg.
+``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
+ Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
+ storing the result in ``*msg``.
-unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
- Disassembles the CAPI 2.0 message in *msg, storing the parameters in
- *cmsg.
+``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
+ Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
+ in ``*cmsg``.
-unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
- u16 Messagenumber, u32 Controller)
- Fills the header part and address field of the _cmsg structure *cmsg
+``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
+ Fills the header part and address field of the _cmsg structure ``*cmsg``
with the given values, zeroing the remainder of the structure so only
parameters with non-default values need to be changed before sending
the message.
-void capi_cmsg_answer(_cmsg *cmsg)
- Sets the low bit of the Subcommand field in *cmsg, thereby converting
- _REQ to _CONF and _IND to _RESP.
+``void capi_cmsg_answer(_cmsg *cmsg)``
+ Sets the low bit of the Subcommand field in ``*cmsg``, thereby
+ converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
-char *capi_cmd2str(u8 Command, u8 Subcommand)
+``char *capi_cmd2str(u8 Command, u8 Subcommand)``
Returns the CAPI 2.0 message name corresponding to the given command
and subcommand values, as a static ASCII string. The return value may
be NULL if the command/subcommand is not one of those defined in the
@@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand)
7. Debugging
+============
The module kernelcapi has a module parameter showcapimsgs controlling some
debugging output produced by the module. It can only be set when the module is
diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst
similarity index 89%
rename from Documentation/isdn/README.mISDN
rename to Documentation/isdn/m_isdn.rst
index cd8bf920e77b..9957de349e69 100644
--- a/Documentation/isdn/README.mISDN
+++ b/Documentation/isdn/m_isdn.rst
@@ -1,6 +1,9 @@
+============
+mISDN Driver
+============
+
mISDN is a new modular ISDN driver, in the long term it should replace
the old I4L driver architecture for passiv ISDN cards.
It was designed to allow a broad range of applications and interfaces
but only have the basic function in kernel, the interface to the user
space is based on sockets with a own address family AF_ISDN.
-
diff --git a/drivers/staging/isdn/hysdn/Kconfig b/drivers/staging/isdn/hysdn/Kconfig
index 1971ef850c9a..4c8a9283b9dd 100644
--- a/drivers/staging/isdn/hysdn/Kconfig
+++ b/drivers/staging/isdn/hysdn/Kconfig
@@ -5,7 +5,7 @@ config HYSDN
help
Say Y here if you have one of Hypercope's active PCI ISDN cards
Champ, Ergo and Metro. You will then get a module called hysdn.
- Please read the file <file:Documentation/isdn/README.hysdn> for more
+ Please read the file <file:Documentation/isdn/hysdn.rst> for more
information.
config HYSDN_CAPI
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide book
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (19 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Steve French, Jonathan Corbet, linux-cifs,
samba-technical, linux-doc
The filenames for cifs documentation is not using the same
convention as almost all Kernel documents is using. So,
rename them to a more appropriate name. Then, manually convert
the documentation files for CIFS to ReST.
By doing a manual conversion, we can preserve the original
author's style, while making it to look more like the other
Kernel documents.
Most of the conversion here is trivial. The most complex one was
the README file (which was renamed to usage.rst).
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../AUTHORS => admin-guide/cifs/authors.rst} | 64 +-
.../CHANGES => admin-guide/cifs/changes.rst} | 4 +
Documentation/admin-guide/cifs/index.rst | 21 +
.../cifs/introduction.rst} | 8 +
.../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +--
.../README => admin-guide/cifs/usage.rst} | 560 +++++++++++-------
.../cifs/winucase_convert.pl | 0
Documentation/admin-guide/index.rst | 1 +
MAINTAINERS | 2 +-
9 files changed, 460 insertions(+), 287 deletions(-)
rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
create mode 100644 Documentation/admin-guide/cifs/index.rst
rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
diff --git a/Documentation/filesystems/cifs/AUTHORS b/Documentation/admin-guide/cifs/authors.rst
similarity index 60%
rename from Documentation/filesystems/cifs/AUTHORS
rename to Documentation/admin-guide/cifs/authors.rst
index 75865da2ce14..b02d6dd6c070 100644
--- a/Documentation/filesystems/cifs/AUTHORS
+++ b/Documentation/admin-guide/cifs/authors.rst
@@ -1,5 +1,10 @@
+=======
+Authors
+=======
+
Original Author
-===============
+---------------
+
Steve French (sfrench@samba.org)
The author wishes to express his appreciation and thanks to:
@@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing
portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
for proving years ago that very good smb/cifs clients could be done on Unix-like
-operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
+operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John
Newbigin and others for their work on the Linux smbfs module. Thanks to
the other members of the Storage Network Industry Association CIFS Technical
Workgroup for their work specifying this highly complex protocol and finally
@@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement.
Patch Contributors
------------------
-Zwane Mwaikambo
-Andi Kleen
-Amrut Joshi
-Shobhit Dayal
-Sergey Vlasov
-Richard Hughes
-Yury Umanets
-Mark Hamzy (for some of the early cifs IPv6 work)
-Domen Puncer
-Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
-Vince Negri and Dave Stahl (for finding an important caching bug)
-Adrian Bunk (kcalloc cleanups)
-Miklos Szeredi
-Kazeon team for various fixes especially for 2.4 version.
-Asser Ferno (Change Notify support)
-Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
-Gunter Kukkukk (testing and suggestions for support of old servers)
-Igor Mammedov (DFS support)
-Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
-Scott Lovenberg
-Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
-Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
-Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
-Shirish Pargaonkar (for many ACL patches over the years)
-Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
-Paulo Alcantara
-Long Li (some great work on RDMA, SMB Direct)
+
+- Zwane Mwaikambo
+- Andi Kleen
+- Amrut Joshi
+- Shobhit Dayal
+- Sergey Vlasov
+- Richard Hughes
+- Yury Umanets
+- Mark Hamzy (for some of the early cifs IPv6 work)
+- Domen Puncer
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
+- Adrian Bunk (kcalloc cleanups)
+- Miklos Szeredi
+- Kazeon team for various fixes especially for 2.4 version.
+- Asser Ferno (Change Notify support)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Gunter Kukkukk (testing and suggestions for support of old servers)
+- Igor Mammedov (DFS support)
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Scott Lovenberg
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Shirish Pargaonkar (for many ACL patches over the years)
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Paulo Alcantara
+- Long Li (some great work on RDMA, SMB Direct)
Test case and Bug Report contributors
diff --git a/Documentation/filesystems/cifs/CHANGES b/Documentation/admin-guide/cifs/changes.rst
similarity index 91%
rename from Documentation/filesystems/cifs/CHANGES
rename to Documentation/admin-guide/cifs/changes.rst
index 1df7f4910eb2..71f2ecb62299 100644
--- a/Documentation/filesystems/cifs/CHANGES
+++ b/Documentation/admin-guide/cifs/changes.rst
@@ -1,3 +1,7 @@
+=======
+Changes
+=======
+
See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
information (that may be easier to read than parsing the output of
"git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes
diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst
new file mode 100644
index 000000000000..fad5268635f5
--- /dev/null
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction
+ usage
+ todo
+ changes
+ authors
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/filesystems/cifs/cifs.txt b/Documentation/admin-guide/cifs/introduction.rst
similarity index 98%
rename from Documentation/filesystems/cifs/cifs.txt
rename to Documentation/admin-guide/cifs/introduction.rst
index 1be3d21c286e..0b98f672d36f 100644
--- a/Documentation/filesystems/cifs/cifs.txt
+++ b/Documentation/admin-guide/cifs/introduction.rst
@@ -1,3 +1,7 @@
+============
+Introduction
+============
+
This is the client VFS module for the SMB3 NAS protocol as well
as for older dialects such as the Common Internet File System (CIFS)
protocol which was the successor to the Server Message Block
@@ -33,7 +37,9 @@
tools (including smbinfo and setcifsacl) that can be obtained from
https://git.samba.org/?p=cifs-utils.git
+
or
+
git://git.samba.org/cifs-utils.git
mount.cifs should be installed in the directory with the other mount helpers.
@@ -41,5 +47,7 @@
For more information on the module see the project wiki page at
https://wiki.samba.org/index.php/LinuxCIFS
+
and
+
https://wiki.samba.org/index.php/LinuxCIFS_utils
diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/admin-guide/cifs/todo.rst
similarity index 58%
rename from Documentation/filesystems/cifs/TODO
rename to Documentation/admin-guide/cifs/todo.rst
index 9267f3fb131f..95f18e8c9b8a 100644
--- a/Documentation/filesystems/cifs/TODO
+++ b/Documentation/admin-guide/cifs/todo.rst
@@ -1,3 +1,7 @@
+====
+TODO
+====
+
Version 2.14 December 21, 2018
A Partial List of Missing Features
@@ -8,6 +12,7 @@ for visible, important contributions to this module. Here
is a partial list of the known problems and missing features:
a) SMB3 (and SMB3.1.1) missing optional features:
+
- multichannel (started), integration with RDMA
- directory leases (improved metadata caching), started (root dir only)
- T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
@@ -16,45 +21,46 @@ a) SMB3 (and SMB3.1.1) missing optional features:
b) improved sparse file support
c) Directory entry caching relies on a 1 second timer, rather than
-using Directory Leases, currently only the root file handle is cached longer
+ using Directory Leases, currently only the root file handle is cached longer
d) quota support (needs minor kernel change since quota calls
-to make it to network filesystems or deviceless filesystems)
+ to make it to network filesystems or deviceless filesystems)
e) Additional use cases where we use "compoounding" (e.g. open/query/close
-and open/setinfo/close) to reduce the number of roundtrips, and also
-open to reduce redundant opens (using deferred close and reference counts more).
+ and open/setinfo/close) to reduce the number of roundtrips, and also
+ open to reduce redundant opens (using deferred close and reference counts
+ more).
f) Finish inotify support so kde and gnome file list windows
-will autorefresh (partially complete by Asser). Needs minor kernel
-vfs change to support removing D_NOTIFY on a file.
+ will autorefresh (partially complete by Asser). Needs minor kernel
+ vfs change to support removing D_NOTIFY on a file.
g) Add GUI tool to configure /proc/fs/cifs settings and for display of
-the CIFS statistics (started)
+ the CIFS statistics (started)
h) implement support for security and trusted categories of xattrs
-(requires minor protocol extension) to enable better support for SELINUX
+ (requires minor protocol extension) to enable better support for SELINUX
i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
feature (may be especially useful for virtualization).
j) Create UID mapping facility so server UIDs can be mapped on a per
-mount or a per server basis to client UIDs or nobody if no mapping
-exists. Also better integration with winbind for resolving SID owners
+ mount or a per server basis to client UIDs or nobody if no mapping
+ exists. Also better integration with winbind for resolving SID owners
k) Add tools to take advantage of more smb3 specific ioctls and features
-(passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
-is in progress, and a passthrough query_info call is already implemented
-in cifs.ko to allow smb3 info levels queries to be sent from userspace)
+ (passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
+ is in progress, and a passthrough query_info call is already implemented
+ in cifs.ko to allow smb3 info levels queries to be sent from userspace)
l) encrypted file support
m) improved stats gathering tools (perhaps integration with nfsometer?)
-to extend and make easier to use what is currently in /proc/fs/cifs/Stats
+ to extend and make easier to use what is currently in /proc/fs/cifs/Stats
-n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed
-file attribute via chflags) and improve user space tools for managing and
-viewing them.
+n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to
+ compressed file attribute via chflags) and improve user space tools for
+ managing and viewing them.
o) mount helper GUI (to simplify the various configuration options on mount)
@@ -65,55 +71,56 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
different servers, and the server we are connected to has gone down.
q) Allow mount.cifs to be more verbose in reporting errors with dialect
-or unsupported feature errors.
+ or unsupported feature errors.
r) updating cifs documentation, and user guide.
s) Addressing bugs found by running a broader set of xfstests in standard
-file system xfstest suite.
+ file system xfstest suite.
t) split cifs and smb3 support into separate modules so legacy (and less
-secure) CIFS dialect can be disabled in environments that don't need it
-and simplify the code.
+ secure) CIFS dialect can be disabled in environments that don't need it
+ and simplify the code.
v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
-so far).
+ so far).
w) Add support for additional strong encryption types, and additional spnego
-authentication mechanisms (see MS-SMB2)
+ authentication mechanisms (see MS-SMB2)
+
+Known Bugs
+==========
-KNOWN BUGS
-====================================
See http://bugzilla.samba.org - search on product "CifsVFS" for
current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
1) existing symbolic links (Windows reparse points) are recognized but
-can not be created remotely. They are implemented for Samba and those that
-support the CIFS Unix extensions, although earlier versions of Samba
-overly restrict the pathnames.
+ can not be created remotely. They are implemented for Samba and those that
+ support the CIFS Unix extensions, although earlier versions of Samba
+ overly restrict the pathnames.
2) follow_link and readdir code does not follow dfs junctions
-but recognizes them
+ but recognizes them
Misc testing to do
==================
1) check out max path names and max path name components against various server
-types. Try nested symlinks (8 deep). Return max path name in stat -f information
+ types. Try nested symlinks (8 deep). Return max path name in stat -f information
2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
-cifs/smb3 better
+ cifs/smb3 better
-3) Additional performance testing and optimization using iozone and similar -
-there are some easy changes that can be done to parallelize sequential writes,
-and when signing is disabled to request larger read sizes (larger than
-negotiated size) and send larger write sizes to modern servers.
+3) Additional performance testing and optimization using iozone and similar -
+ there are some easy changes that can be done to parallelize sequential writes,
+ and when signing is disabled to request larger read sizes (larger than
+ negotiated size) and send larger write sizes to modern servers.
4) More exhaustively test against less common servers
5) Continue to extend the smb3 "buildbot" which does automated xfstesting
-against Windows, Samba and Azure currently - to add additional tests and
-to allow the buildbot to execute the tests faster. The URL for the
-buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
+ against Windows, Samba and Azure currently - to add additional tests and
+ to allow the buildbot to execute the tests faster. The URL for the
+ buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
6) Address various coverity warnings (most are not bugs per-se, but
-the more warnings are addressed, the easier it is to spot real
-problems that static analyzers will point out in the future).
+ the more warnings are addressed, the easier it is to spot real
+ problems that static analyzers will point out in the future).
diff --git a/Documentation/filesystems/cifs/README b/Documentation/admin-guide/cifs/usage.rst
similarity index 72%
rename from Documentation/filesystems/cifs/README
rename to Documentation/admin-guide/cifs/usage.rst
index 4a804619cff2..d3fb67b8a976 100644
--- a/Documentation/filesystems/cifs/README
+++ b/Documentation/admin-guide/cifs/usage.rst
@@ -1,53 +1,61 @@
+=====
+Usage
+=====
+
This module supports the SMB3 family of advanced network protocols (as well
as older dialects, originally called "CIFS" or SMB1).
The CIFS VFS module for Linux supports many advanced network filesystem
features such as hierarchical DFS like namespace, hardlinks, locking and more.
-It was designed to comply with the SNIA CIFS Technical Reference (which
-supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
-practical interoperability with Windows 2000, Windows XP, Samba and equivalent
+It was designed to comply with the SNIA CIFS Technical Reference (which
+supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
+practical interoperability with Windows 2000, Windows XP, Samba and equivalent
servers. This code was developed in participation with the Protocol Freedom
Information Foundation. CIFS and now SMB3 has now become a defacto
standard for interoperating between Macs and Windows and major NAS appliances.
Please see
- MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
- http://protocolfreedom.org/ and
- http://samba.org/samba/PFIF/
+MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
+http://protocolfreedom.org/ and
+http://samba.org/samba/PFIF/
for more details.
For questions or bug reports please contact:
+
smfrench@gmail.com
See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils
-Build instructions:
+Build instructions
==================
+
For Linux:
+
1) Download the kernel (e.g. from http://www.kernel.org)
-and change directory into the top of the kernel directory tree
-(e.g. /usr/src/linux-2.5.73)
+ and change directory into the top of the kernel directory tree
+ (e.g. /usr/src/linux-2.5.73)
2) make menuconfig (or make xconfig)
3) select cifs from within the network filesystem choices
4) save and exit
5) make
-Installation instructions:
+Installation instructions
=========================
+
If you have built the CIFS vfs as module (successfully) simply
-type "make modules_install" (or if you prefer, manually copy the file to
+type ``make modules_install`` (or if you prefer, manually copy the file to
the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko).
If you have built the CIFS vfs into the kernel itself, follow the instructions
for your distribution on how to install a new kernel (usually you
-would simply type "make install").
+would simply type ``make install``).
If you do not have the utility mount.cifs (in the Samba 4.x source tree and on
the CIFS VFS web site) copy it to the same directory in which mount helpers
reside (usually /sbin). Although the helper software is not
-required, mount.cifs is recommended. Most distros include a "cifs-utils"
+required, mount.cifs is recommended. Most distros include a ``cifs-utils``
package that includes this utility so it is recommended to install this.
Note that running the Winbind pam/nss module (logon service) on all of your
@@ -57,13 +65,16 @@ found at cifs-utils.git on git.samba.org
If cifs is built as a module, then the size and number of network buffers
and maximum number of simultaneous requests to one server can be configured.
-Changing these from their defaults is not recommended. By executing modinfo
+Changing these from their defaults is not recommended. By executing modinfo::
+
modinfo kernel/fs/cifs/cifs.ko
+
on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made
at module initialization time (by running insmod cifs.ko) can be seen.
Recommendations
===============
+
To improve security the SMB2.1 dialect or later (usually will get SMB3) is now
the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"
on mount (or vers=2.0 for Windows Vista). Note that the CIFS (vers=1.0) is
@@ -72,156 +83,168 @@ many advanced security features such as downgrade attack detection
and encrypted shares and stronger signing and authentication algorithms.
There are additional mount options that may be helpful for SMB3 to get
improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1):
- "mfsymlinks" and "cifsacl" and "idsfromsid"
+
+ ``mfsymlinks`` and ``cifsacl`` and ``idsfromsid``
Allowing User Mounts
====================
+
To permit users to mount and unmount over directories they own is possible
with the cifs vfs. A way to enable such mounting is to mark the mount.cifs
-utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to
+utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to
umount shares they mount requires
+
1) mount.cifs version 1.4 or later
2) an entry for the share in /etc/fstab indicating that a user may
-unmount it e.g.
-//server/usersharename /mnt/username cifs user 0 0
+ unmount it e.g.::
-Note that when the mount.cifs utility is run suid (allowing user mounts),
-in order to reduce risks, the "nosuid" mount flag is passed in on mount to
+ //server/usersharename /mnt/username cifs user 0 0
+
+Note that when the mount.cifs utility is run suid (allowing user mounts),
+in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to
disallow execution of an suid program mounted on the remote target.
When mount is executed as root, nosuid is not passed in by default,
and execution of suid programs on the remote target would be enabled
-by default. This can be changed, as with nfs and other filesystems,
-by simply specifying "nosuid" among the mount options. For user mounts
-though to be able to pass the suid flag to mount requires rebuilding
+by default. This can be changed, as with nfs and other filesystems,
+by simply specifying ``nosuid`` among the mount options. For user mounts
+though to be able to pass the suid flag to mount requires rebuilding
mount.cifs with the following flag: CIFS_ALLOW_USR_SUID
There is a corresponding manual page for cifs mounting in the Samba 3.0 and
-later source tree in docs/manpages/mount.cifs.8
+later source tree in docs/manpages/mount.cifs.8
Allowing User Unmounts
======================
+
To permit users to ummount directories that they have user mounted (see above),
-the utility umount.cifs may be used. It may be invoked directly, or if
+the utility umount.cifs may be used. It may be invoked directly, or if
umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
(at least for most versions of the umount utility) for umount of cifs
mounts, unless umount is invoked with -i (which will avoid invoking a umount
helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
-as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions
+as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions
allow adding entries to a file to the /etc/permissions file to achieve the
equivalent suid effect). For this utility to succeed the target path
must be a cifs mount, and the uid of the current user must match the uid
of the user who mounted the resource.
-Also note that the customary way of allowing user mounts and unmounts is
+Also note that the customary way of allowing user mounts and unmounts is
(instead of using mount.cifs and unmount.cifs as suid) to add a line
to the file /etc/fstab for each //server/share you wish to mount, but
this can become unwieldy when potential mount targets include many
or unpredictable UNC names.
-Samba Considerations
+Samba Considerations
====================
+
Most current servers support SMB2.1 and SMB3 which are more secure,
but there are useful protocol extensions for the older less secure CIFS
dialect, so to get the maximum benefit if mounting using the older dialect
(CIFS/SMB1), we recommend using a server that supports the SNIA CIFS
Unix Extensions standard (e.g. almost any version of Samba ie version
2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers.
-Note that uid, gid and file permissions will display default values if you do
-not have a server that supports the Unix extensions for CIFS (such as Samba
-2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add
-the line:
+Note that uid, gid and file permissions will display default values if you do
+not have a server that supports the Unix extensions for CIFS (such as Samba
+2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add
+the line::
unix extensions = yes
-
-to your smb.conf file on the server. Note that the following smb.conf settings
-are also useful (on the Samba server) when the majority of clients are Unix or
-Linux:
+
+to your smb.conf file on the server. Note that the following smb.conf settings
+are also useful (on the Samba server) when the majority of clients are Unix or
+Linux::
case sensitive = yes
- delete readonly = yes
+ delete readonly = yes
ea support = yes
Note that server ea support is required for supporting xattrs from the Linux
-cifs client, and that EA support is present in later versions of Samba (e.g.
+cifs client, and that EA support is present in later versions of Samba (e.g.
3.0.6 and later (also EA support works in all versions of Windows, at least to
shares on NTFS filesystems). Extended Attribute (xattr) support is an optional
feature of most Linux filesystems which may require enabling via
make menuconfig. Client support for extended attributes (user xattr) can be
-disabled on a per-mount basis by specifying "nouser_xattr" on mount.
+disabled on a per-mount basis by specifying ``nouser_xattr`` on mount.
The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
-version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and
+version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and
then POSIX support in the CIFS configuration options when building the cifs
module. POSIX ACL support can be disabled on a per mount basic by specifying
-"noacl" on mount.
-
-Some administrators may want to change Samba's smb.conf "map archive" and
-"create mask" parameters from the default. Unless the create mask is changed
+``noacl`` on mount.
+
+Some administrators may want to change Samba's smb.conf ``map archive`` and
+``create mask`` parameters from the default. Unless the create mask is changed
newly created files can end up with an unnecessarily restrictive default mode,
which may not be what you want, although if the CIFS Unix extensions are
enabled on the server and client, subsequent setattr calls (e.g. chmod) can
-fix the mode. Note that creating special devices (mknod) remotely
-may require specifying a mkdev function to Samba if you are not using
+fix the mode. Note that creating special devices (mknod) remotely
+may require specifying a mkdev function to Samba if you are not using
Samba 3.0.6 or later. For more information on these see the manual pages
-("man smb.conf") on the Samba server system. Note that the cifs vfs,
-unlike the smbfs vfs, does not read the smb.conf on the client system
-(the few optional settings are passed in on mount via -o parameters instead).
+(``man smb.conf``) on the Samba server system. Note that the cifs vfs,
+unlike the smbfs vfs, does not read the smb.conf on the client system
+(the few optional settings are passed in on mount via -o parameters instead).
Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
-open files (required for strict POSIX compliance). Windows Servers already
+open files (required for strict POSIX compliance). Windows Servers already
supported this feature. Samba server does not allow symlinks that refer to files
outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
-files with absolute paths (ie beginning with slash) such as:
+files with absolute paths (ie beginning with slash) such as::
+
ln -s /mnt/foo bar
-would be forbidden. Samba 3.0.6 server or later includes the ability to create
-such symlinks safely by converting unsafe symlinks (ie symlinks to server
+
+would be forbidden. Samba 3.0.6 server or later includes the ability to create
+such symlinks safely by converting unsafe symlinks (ie symlinks to server
files that are outside of the share) to a samba specific format on the server
that is ignored by local server applications and non-cifs clients and that will
not be traversed by the Samba server). This is opaque to the Linux client
application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
later, but only for remote clients using the CIFS Unix extensions, and will
be invisbile to Windows clients and typically will not affect local
-applications running on the same server as Samba.
+applications running on the same server as Samba.
-Use instructions:
+Use instructions
================
-Once the CIFS VFS support is built into the kernel or installed as a module
+
+Once the CIFS VFS support is built into the kernel or installed as a module
(cifs.ko), you can use mount syntax like the following to access Samba or
-Mac or Windows servers:
+Mac or Windows servers::
mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword
Before -o the option -v may be specified to make the mount.cifs
-mount helper display the mount steps more verbosely.
+mount helper display the mount steps more verbosely.
After -o the following commonly used cifs vfs specific options
-are supported:
+are supported::
username=<username>
password=<password>
domain=<domain name>
-
+
Other cifs mount options are described below. Use of TCP names (in addition to
ip addresses) is available if the mount helper (mount.cifs) is installed. If
you do not trust the server to which are mounted, or if you do not have
cifs signing enabled (and the physical network is insecure), consider use
-of the standard mount options "noexec" and "nosuid" to reduce the risk of
+of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of
running an altered binary on your local system (downloaded from a hostile server
or altered by a hostile router).
Although mounting using format corresponding to the CIFS URL specification is
not possible in mount.cifs yet, it is possible to use an alternate format
for the server and sharename (which is somewhat similar to NFS style mount
-syntax) instead of the more widely used UNC format (i.e. \\server\share):
+syntax) instead of the more widely used UNC format (i.e. \\server\share)::
+
mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
When using the mount helper mount.cifs, passwords may be specified via alternate
-mechanisms, instead of specifying it after -o using the normal "pass=" syntax
+mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax
on the command line:
1) By including it in a credential file. Specify credentials=filename as one
-of the mount options. Credential files contain two lines
- username=someuser
- password=your_password
+of the mount options. Credential files contain two lines::
+
+ username=someuser
+ password=your_password
+
2) By specifying the password in the PASSWD environment variable (similarly
-the user name can be taken from the USER environment variable).
+ the user name can be taken from the USER environment variable).
3) By specifying the password in a file by name via PASSWD_FILE
4) By specifying the password in a file by file descriptor via PASSWD_FD
@@ -229,39 +252,47 @@ If no password is provided, mount.cifs will prompt for password entry
Restrictions
============
-Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
-1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
+
+Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
+1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
problem as most servers support this.
Valid filenames differ between Windows and Linux. Windows typically restricts
-filenames which contain certain reserved characters (e.g.the character :
+filenames which contain certain reserved characters (e.g.the character :
which is used to delimit the beginning of a stream name by Windows), while
Linux allows a slightly wider set of valid characters in filenames. Windows
servers can remap such characters when an explicit mapping is specified in
-the Server's registry. Samba starting with version 3.10 will allow such
+the Server's registry. Samba starting with version 3.10 will allow such
filenames (ie those which contain valid Linux characters, which normally
would be forbidden for Windows/CIFS semantics) as long as the server is
configured for Unix Extensions (and the client has not disabled
/proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
-"mapposix" can be used on CIFS (vers=1.0) to force the mapping of
+``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of
illegal Windows/NTFS/SMB characters to a remap range (this mount parm
-is the default for SMB3). This remap ("mapposix") range is also
+is the default for SMB3). This remap (``mapposix``) range is also
compatible with Mac (and "Services for Mac" on some older Windows).
CIFS VFS Mount Options
======================
A partial list of the supported mount options follows:
- username The user name to use when trying to establish
+
+ username
+ The user name to use when trying to establish
the CIFS session.
- password The user password. If the mount helper is
+ password
+ The user password. If the mount helper is
installed, the user will be prompted for password
if not supplied.
- ip The ip address of the target server
- unc The target server Universal Network Name (export) to
- mount.
- domain Set the SMB/CIFS workgroup name prepended to the
+ ip
+ The ip address of the target server
+ unc
+ The target server Universal Network Name (export) to
+ mount.
+ domain
+ Set the SMB/CIFS workgroup name prepended to the
username during CIFS session establishment
- forceuid Set the default uid for inodes to the uid
+ forceuid
+ Set the default uid for inodes to the uid
passed in on mount. For mounts to servers
which do support the CIFS Unix extensions, such as a
properly configured Samba server, the server provides
@@ -276,32 +307,39 @@ A partial list of the supported mount options follows:
extensions, the default uid (and gid) returned on lookup
of existing files will be the uid (gid) of the person
who executed the mount (root, except when mount.cifs
- is configured setuid for user mounts) unless the "uid="
+ is configured setuid for user mounts) unless the ``uid=``
(gid) mount option is specified. Also note that permission
checks (authorization checks) on accesses to a file occur
at the server, but there are cases in which an administrator
may want to restrict at the client as well. For those
servers which do not report a uid/gid owner
(such as Windows), permissions can also be checked at the
- client, and a crude form of client side permission checking
- can be enabled by specifying file_mode and dir_mode on
+ client, and a crude form of client side permission checking
+ can be enabled by specifying file_mode and dir_mode on
the client. (default)
- forcegid (similar to above but for the groupid instead of uid) (default)
- noforceuid Fill in file owner information (uid) by requesting it from
+ forcegid
+ (similar to above but for the groupid instead of uid) (default)
+ noforceuid
+ Fill in file owner information (uid) by requesting it from
the server if possible. With this option, the value given in
the uid= option (on mount) will only be used if the server
can not support returning uids on inodes.
- noforcegid (similar to above but for the group owner, gid, instead of uid)
- uid Set the default uid for inodes, and indicate to the
+ noforcegid
+ (similar to above but for the group owner, gid, instead of uid)
+ uid
+ Set the default uid for inodes, and indicate to the
cifs kernel driver which local user mounted. If the server
supports the unix extensions the default uid is
not used to fill in the owner fields of inodes (files)
- unless the "forceuid" parameter is specified.
- gid Set the default gid for inodes (similar to above).
- file_mode If CIFS Unix extensions are not supported by the server
+ unless the ``forceuid`` parameter is specified.
+ gid
+ Set the default gid for inodes (similar to above).
+ file_mode
+ If CIFS Unix extensions are not supported by the server
this overrides the default mode for file inodes.
- fsc Enable local disk caching using FS-Cache (off by default). This
- option could be useful to improve performance on a slow link,
+ fsc
+ Enable local disk caching using FS-Cache (off by default). This
+ option could be useful to improve performance on a slow link,
heavily loaded server and/or network where reading from the
disk is faster than reading from the server (over the network).
This could also impact scalability positively as the
@@ -310,18 +348,22 @@ A partial list of the supported mount options follows:
type workloads. So, you need to consider carefully your
workload/scenario before using this option. Currently, local
disk caching is functional for CIFS files opened as read-only.
- dir_mode If CIFS Unix extensions are not supported by the server
+ dir_mode
+ If CIFS Unix extensions are not supported by the server
this overrides the default mode for directory inodes.
- port attempt to contact the server on this tcp port, before
+ port
+ attempt to contact the server on this tcp port, before
trying the usual ports (port 445, then 139).
- iocharset Codepage used to convert local path names to and from
+ iocharset
+ Codepage used to convert local path names to and from
Unicode. Unicode is used by default for network path
names if the server supports it. If iocharset is
not specified then the nls_default specified
during the local client kernel build will be used.
If server does not support Unicode, this parameter is
unused.
- rsize default read size (usually 16K). The client currently
+ rsize
+ default read size (usually 16K). The client currently
can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize
defaults to 16K and may be changed (from 8K to the maximum
kmalloc size allowed by your kernel) at module install time
@@ -333,10 +375,12 @@ A partial list of the supported mount options follows:
newer servers (e.g. Samba 3.0.26 or later) do. rsize can be
set from a minimum of 2048 to a maximum of 130048 (127K or
CIFSMaxBufSize, whichever is smaller)
- wsize default write size (default 57344)
+ wsize
+ default write size (default 57344)
maximum wsize currently allowed by CIFS is 57344 (fourteen
4096 byte pages)
- actimeo=n attribute cache timeout in seconds (default 1 second).
+ actimeo=n
+ attribute cache timeout in seconds (default 1 second).
After this timeout, the cifs client requests fresh attribute
information from the server. This option allows to tune the
attribute cache timeout to suit the workload needs. Shorter
@@ -345,49 +389,67 @@ A partial list of the supported mount options follows:
of calls to the server at the expense of less stricter cache
coherency checks (i.e. incorrect attribute cache for a short
period of time).
- rw mount the network share read-write (note that the
+ rw
+ mount the network share read-write (note that the
server may still consider the share read-only)
- ro mount network share read-only
- version used to distinguish different versions of the
+ ro
+ mount network share read-only
+ version
+ used to distinguish different versions of the
mount helper utility (not typically needed)
- sep if first mount option (after the -o), overrides
+ sep
+ if first mount option (after the -o), overrides
the comma as the separator between the mount
- parms. e.g.
+ parms. e.g.::
+
-o user=myname,password=mypassword,domain=mydom
- could be passed instead with period as the separator by
+
+ could be passed instead with period as the separator by::
+
-o sep=.user=myname.password=mypassword.domain=mydom
+
this might be useful when comma is contained within username
or password or domain. This option is less important
when the cifs mount helper cifs.mount (version 1.1 or later)
is used.
- nosuid Do not allow remote executables with the suid bit
+ nosuid
+ Do not allow remote executables with the suid bit
program to be executed. This is only meaningful for mounts
to servers such as Samba which support the CIFS Unix Extensions.
If you do not trust the servers in your network (your mount
targets) it is recommended that you specify this option for
greater security.
- exec Permit execution of binaries on the mount.
- noexec Do not permit execution of binaries on the mount.
- dev Recognize block devices on the remote mount.
- nodev Do not recognize devices on the remote mount.
- suid Allow remote files on this mountpoint with suid enabled to
+ exec
+ Permit execution of binaries on the mount.
+ noexec
+ Do not permit execution of binaries on the mount.
+ dev
+ Recognize block devices on the remote mount.
+ nodev
+ Do not recognize devices on the remote mount.
+ suid
+ Allow remote files on this mountpoint with suid enabled to
be executed (default for mounts when executed as root,
nosuid is default for user mounts).
- credentials Although ignored by the cifs kernel component, it is used by
+ credentials
+ Although ignored by the cifs kernel component, it is used by
the mount helper, mount.cifs. When mount.cifs is installed it
- opens and reads the credential file specified in order
+ opens and reads the credential file specified in order
to obtain the userid and password arguments which are passed to
the cifs vfs.
- guest Although ignored by the kernel component, the mount.cifs
+ guest
+ Although ignored by the kernel component, the mount.cifs
mount helper will not prompt the user for a password
if guest is specified on the mount options. If no
password is specified a null password will be used.
- perm Client does permission checks (vfs_permission check of uid
+ perm
+ Client does permission checks (vfs_permission check of uid
and gid of the file against the mode and desired operation),
Note that this is in addition to the normal ACL check on the
- target machine done by the server software.
+ target machine done by the server software.
Client permission checking is enabled by default.
- noperm Client does not do permission checks. This can expose
+ noperm
+ Client does not do permission checks. This can expose
files on this mount to access by other users on the local
client system. It is typically only needed when the server
supports the CIFS Unix Extensions but the UIDs/GIDs on the
@@ -399,7 +461,8 @@ A partial list of the supported mount options follows:
Note that this does not affect the normal ACL check on the
target machine done by the server software (of the server
ACL against the user name provided at mount time).
- serverino Use server's inode numbers instead of generating automatically
+ serverino
+ Use server's inode numbers instead of generating automatically
incrementing inode numbers on the client. Although this will
make it easier to spot hardlinked files (as they will have
the same inode numbers) and inode numbers may be persistent,
@@ -412,14 +475,16 @@ A partial list of the supported mount options follows:
or the CIFS Unix Extensions equivalent and for those
this mount option will have no effect. Exporting cifs mounts
under nfsd requires this mount option on the cifs mount.
- This is now the default if server supports the
+ This is now the default if server supports the
required network operation.
- noserverino Client generates inode numbers (rather than using the actual one
+ noserverino
+ Client generates inode numbers (rather than using the actual one
from the server). These inode numbers will vary after
unmount or reboot which can confuse some applications,
but not all server filesystems support unique inode
numbers.
- setuids If the CIFS Unix extensions are negotiated with the server
+ setuids
+ If the CIFS Unix extensions are negotiated with the server
the client will attempt to set the effective uid and gid of
the local process on newly created files, directories, and
devices (create, mkdir, mknod). If the CIFS Unix Extensions
@@ -427,9 +492,10 @@ A partial list of the supported mount options follows:
instead of using the default uid and gid specified on
the mount, cache the new file's uid and gid locally which means
that the uid for the file can change when the inode is
- reloaded (or the user remounts the share).
- nosetuids The client will not attempt to set the uid and gid on
- on newly created files, directories, and devices (create,
+ reloaded (or the user remounts the share).
+ nosetuids
+ The client will not attempt to set the uid and gid on
+ on newly created files, directories, and devices (create,
mkdir, mknod) which will result in the server setting the
uid and gid to the default (usually the server uid of the
user who mounted the share). Letting the server (rather than
@@ -437,38 +503,49 @@ A partial list of the supported mount options follows:
Unix Extensions are not negotiated then the uid and gid for
new files will appear to be the uid (gid) of the mounter or the
uid (gid) parameter specified on the mount.
- netbiosname When mounting to servers via port 139, specifies the RFC1001
- source name to use to represent the client netbios machine
+ netbiosname
+ When mounting to servers via port 139, specifies the RFC1001
+ source name to use to represent the client netbios machine
name when doing the RFC1001 netbios session initialize.
- direct Do not do inode data caching on files opened on this mount.
+ direct
+ Do not do inode data caching on files opened on this mount.
This precludes mmapping files on this mount. In some cases
with fast networks and little or no caching benefits on the
client (e.g. when the application is doing large sequential
- reads bigger than page size without rereading the same data)
+ reads bigger than page size without rereading the same data)
this can provide better performance than the default
- behavior which caches reads (readahead) and writes
- (writebehind) through the local Linux client pagecache
+ behavior which caches reads (readahead) and writes
+ (writebehind) through the local Linux client pagecache
if oplock (caching token) is granted and held. Note that
direct allows write operations larger than page size
to be sent to the server.
- strictcache Use for switching on strict cache mode. In this mode the
+ strictcache
+ Use for switching on strict cache mode. In this mode the
client read from the cache all the time it has Oplock Level II,
otherwise - read from the server. All written data are stored
in the cache, but if the client doesn't have Exclusive Oplock,
it writes the data to the server.
- rwpidforward Forward pid of a process who opened a file to any read or write
+ rwpidforward
+ Forward pid of a process who opened a file to any read or write
operation on that file. This prevent applications like WINE
from failing on read and write if we use mandatory brlock style.
- acl Allow setfacl and getfacl to manage posix ACLs if server
+ acl
+ Allow setfacl and getfacl to manage posix ACLs if server
supports them. (default)
- noacl Do not allow setfacl and getfacl calls on this mount
- user_xattr Allow getting and setting user xattrs (those attributes whose
- name begins with "user." or "os2.") as OS/2 EAs (extended
+ noacl
+ Do not allow setfacl and getfacl calls on this mount
+ user_xattr
+ Allow getting and setting user xattrs (those attributes whose
+ name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended
attributes) to the server. This allows support of the
setfattr and getfattr utilities. (default)
- nouser_xattr Do not allow getfattr/setfattr to get/set/list xattrs
- mapchars Translate six of the seven reserved characters (not backslash)
+ nouser_xattr
+ Do not allow getfattr/setfattr to get/set/list xattrs
+ mapchars
+ Translate six of the seven reserved characters (not backslash)::
+
*?<>|:
+
to the remap range (above 0xF000), which also
allows the CIFS client to recognize files created with
such characters by Windows's POSIX emulation. This can
@@ -477,39 +554,47 @@ A partial list of the supported mount options follows:
whose names contain any of these seven characters).
This has no effect if the server does not support
Unicode on the wire.
- nomapchars Do not translate any of these seven characters (default).
- nocase Request case insensitive path name matching (case
+ nomapchars
+ Do not translate any of these seven characters (default).
+ nocase
+ Request case insensitive path name matching (case
sensitive is the default if the server supports it).
- (mount option "ignorecase" is identical to "nocase")
- posixpaths If CIFS Unix extensions are supported, attempt to
+ (mount option ``ignorecase`` is identical to ``nocase``)
+ posixpaths
+ If CIFS Unix extensions are supported, attempt to
negotiate posix path name support which allows certain
characters forbidden in typical CIFS filenames, without
requiring remapping. (default)
- noposixpaths If CIFS Unix extensions are supported, do not request
+ noposixpaths
+ If CIFS Unix extensions are supported, do not request
posix path name support (this may cause servers to
reject creatingfile with certain reserved characters).
- nounix Disable the CIFS Unix Extensions for this mount (tree
+ nounix
+ Disable the CIFS Unix Extensions for this mount (tree
connection). This is rarely needed, but it may be useful
in order to turn off multiple settings all at once (ie
posix acls, posix locks, posix paths, symlink support
and retrieving uids/gids/mode from the server) or to
work around a bug in server which implement the Unix
Extensions.
- nobrl Do not send byte range lock requests to the server.
+ nobrl
+ Do not send byte range lock requests to the server.
This is necessary for certain applications that break
with cifs style mandatory byte range locks (and most
cifs servers do not yet support requesting advisory
byte range locks).
- forcemandatorylock Even if the server supports posix (advisory) byte range
+ forcemandatorylock
+ Even if the server supports posix (advisory) byte range
locking, send only mandatory lock requests. For some
(presumably rare) applications, originally coded for
DOS/Windows, which require Windows style mandatory byte range
locking, they may be able to take advantage of this option,
forcing the cifs client to only send mandatory locks
even if the cifs server would support posix advisory locks.
- "forcemand" is accepted as a shorter form of this mount
+ ``forcemand`` is accepted as a shorter form of this mount
option.
- nostrictsync If this mount option is set, when an application does an
+ nostrictsync
+ If this mount option is set, when an application does an
fsync call then the cifs client does not send an SMB Flush
to the server (to force the server to write all dirty data
for this file immediately to disk), although cifs still sends
@@ -522,41 +607,50 @@ A partial list of the supported mount options follows:
crash. If this mount option is not set, by default cifs will
send an SMB flush request (and wait for a response) on every
fsync call.
- nodfs Disable DFS (global name space support) even if the
+ nodfs
+ Disable DFS (global name space support) even if the
server claims to support it. This can help work around
a problem with parsing of DFS paths with Samba server
versions 3.0.24 and 3.0.25.
- remount remount the share (often used to change from ro to rw mounts
- or vice versa)
- cifsacl Report mode bits (e.g. on stat) based on the Windows ACL for
- the file. (EXPERIMENTAL)
- servern Specify the server 's netbios name (RFC1001 name) to use
- when attempting to setup a session to the server.
+ remount
+ remount the share (often used to change from ro to rw mounts
+ or vice versa)
+ cifsacl
+ Report mode bits (e.g. on stat) based on the Windows ACL for
+ the file. (EXPERIMENTAL)
+ servern
+ Specify the server 's netbios name (RFC1001 name) to use
+ when attempting to setup a session to the server.
This is needed for mounting to some older servers (such
as OS/2 or Windows 98 and Windows ME) since they do not
support a default server name. A server name can be up
to 15 characters long and is usually uppercased.
- sfu When the CIFS Unix Extensions are not negotiated, attempt to
+ sfu
+ When the CIFS Unix Extensions are not negotiated, attempt to
create device files and fifos in a format compatible with
Services for Unix (SFU). In addition retrieve bits 10-12
of the mode via the SETFILEBITS extended attribute (as
SFU does). In the future the bottom 9 bits of the
mode also will be emulated using queries of the security
descriptor (ACL).
- mfsymlinks Enable support for Minshall+French symlinks
+ mfsymlinks
+ Enable support for Minshall+French symlinks
(see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks)
This option is ignored when specified together with the
'sfu' option. Minshall+French symlinks are used even if
the server supports the CIFS Unix Extensions.
- sign Must use packet signing (helps avoid unwanted data modification
+ sign
+ Must use packet signing (helps avoid unwanted data modification
by intermediate systems in the route). Note that signing
does not work with lanman or plaintext authentication.
- seal Must seal (encrypt) all data on this mounted share before
+ seal
+ Must seal (encrypt) all data on this mounted share before
sending on the network. Requires support for Unix Extensions.
Note that this differs from the sign mount option in that it
causes encryption of data sent over this mounted share but other
shares mounted to the same server are unaffected.
- locallease This option is rarely needed. Fcntl F_SETLEASE is
+ locallease
+ This option is rarely needed. Fcntl F_SETLEASE is
used by some applications such as Samba and NFSv4 server to
check to see whether a file is cacheable. CIFS has no way
to explicitly request a lease, but can check whether a file
@@ -569,51 +663,73 @@ A partial list of the supported mount options follows:
will allow the cifs client to check for leases (only) locally
for files which are not oplocked instead of denying leases
in that case. (EXPERIMENTAL)
- sec Security mode. Allowed values are:
- none attempt to connection as a null user (no name)
- krb5 Use Kerberos version 5 authentication
- krb5i Use Kerberos authentication and packet signing
- ntlm Use NTLM password hashing (default)
- ntlmi Use NTLM password hashing with signing (if
+ sec
+ Security mode. Allowed values are:
+
+ none
+ attempt to connection as a null user (no name)
+ krb5
+ Use Kerberos version 5 authentication
+ krb5i
+ Use Kerberos authentication and packet signing
+ ntlm
+ Use NTLM password hashing (default)
+ ntlmi
+ Use NTLM password hashing with signing (if
/proc/fs/cifs/PacketSigningEnabled on or if
- server requires signing also can be the default)
- ntlmv2 Use NTLMv2 password hashing
- ntlmv2i Use NTLMv2 password hashing with packet signing
- lanman (if configured in kernel config) use older
+ server requires signing also can be the default)
+ ntlmv2
+ Use NTLMv2 password hashing
+ ntlmv2i
+ Use NTLMv2 password hashing with packet signing
+ lanman
+ (if configured in kernel config) use older
lanman hash
-hard Retry file operations if server is not responding
-soft Limit retries to unresponsive servers (usually only
+ hard
+ Retry file operations if server is not responding
+ soft
+ Limit retries to unresponsive servers (usually only
one retry) before returning an error. (default)
The mount.cifs mount helper also accepts a few mount options before -o
including:
+=============== ===============================================================
-S take password from stdin (equivalent to setting the environment
- variable "PASSWD_FD=0"
+ variable ``PASSWD_FD=0``
-V print mount.cifs version
-? display simple usage information
+=============== ===============================================================
With most 2.6 kernel versions of modutils, the version of the cifs kernel
module can be displayed via modinfo.
Misc /proc/fs/cifs Flags and Debug Info
=======================================
+
Informational pseudo-files:
+
+======================= =======================================================
DebugData Displays information about active CIFS sessions and
shares, features enabled as well as the cifs.ko
version.
Stats Lists summary resource usage information as well as per
share statistics.
+======================= =======================================================
Configuration pseudo-files:
+
+======================= =======================================================
SecurityFlags Flags which control security negotiation and
also packet signing. Authentication (may/must)
flags (e.g. for NTLM and/or NTLMv2) may be combined with
the signing flags. Specifying two different password
- hashing mechanisms (as "must use") on the other hand
- does not make much sense. Default flags are
- 0x07007
- (NTLM, NTLMv2 and packet signing allowed). The maximum
+ hashing mechanisms (as "must use") on the other hand
+ does not make much sense. Default flags are::
+
+ 0x07007
+
+ (NTLM, NTLMv2 and packet signing allowed). The maximum
allowable flags if you want to allow mounts to servers
using weaker password hashes is 0x37037 (lanman,
plaintext, ntlm, ntlmv2, signing allowed). Some
@@ -626,21 +742,21 @@ SecurityFlags Flags which control security negotiation and
laintext passwords using the older lanman dialect
form of the session setup SMB. (e.g. for authentication
using plain text passwords, set the SecurityFlags
- to 0x30030):
-
- may use packet signing 0x00001
- must use packet signing 0x01001
- may use NTLM (most common password hash) 0x00002
- must use NTLM 0x02002
- may use NTLMv2 0x00004
- must use NTLMv2 0x04004
- may use Kerberos security 0x00008
- must use Kerberos 0x08008
- may use lanman (weak) password hash 0x00010
- must use lanman password hash 0x10010
- may use plaintext passwords 0x00020
- must use plaintext passwords 0x20020
- (reserved for future packet encryption) 0x00040
+ to 0x30030)::
+
+ may use packet signing 0x00001
+ must use packet signing 0x01001
+ may use NTLM (most common password hash) 0x00002
+ must use NTLM 0x02002
+ may use NTLMv2 0x00004
+ must use NTLMv2 0x04004
+ may use Kerberos security 0x00008
+ must use Kerberos 0x08008
+ may use lanman (weak) password hash 0x00010
+ must use lanman password hash 0x10010
+ may use plaintext passwords 0x00020
+ must use plaintext passwords 0x20020
+ (reserved for future packet encryption) 0x00040
cifsFYI If set to non-zero value, additional debug information
will be logged to the system error log. This field
@@ -650,14 +766,19 @@ cifsFYI If set to non-zero value, additional debug information
Some debugging statements are not compiled into the
cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the
kernel configuration. cifsFYI may be set to one or
- nore of the following flags (7 sets them all):
+ nore of the following flags (7 sets them all)::
+
+ +-----------------------------------------------+------+
+ | log cifs informational messages | 0x01 |
+ +-----------------------------------------------+------+
+ | log return codes from cifs entry points | 0x02 |
+ +-----------------------------------------------+------+
+ | log slow responses | 0x04 |
+ | (ie which take longer than 1 second) | |
+ | | |
+ | CONFIG_CIFS_STATS2 must be enabled in .config | |
+ +-----------------------------------------------+------+
- log cifs informational messages 0x01
- log return codes from cifs entry points 0x02
- log slow responses (ie which take longer than 1 second)
- CONFIG_CIFS_STATS2 must be enabled in .config 0x04
-
-
traceSMB If set to one, debug information is logged to the
system error log with the start of smb requests
and responses (default 0)
@@ -671,24 +792,25 @@ LinuxExtensionsEnabled If set to one then the client will attempt to
as support symbolic links. If you use servers
such as Samba that support the CIFS Unix
extensions but do not want to use symbolic link
- support and want to map the uid and gid fields
- to values supplied at mount (rather than the
+ support and want to map the uid and gid fields
+ to values supplied at mount (rather than the
actual values, then set this to zero. (default 1)
+======================= =======================================================
-These experimental features and tracing can be enabled by changing flags in
-/proc/fs/cifs (after the cifs module has been installed or built into the
-kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable
-tracing to the kernel message log type:
+These experimental features and tracing can be enabled by changing flags in
+/proc/fs/cifs (after the cifs module has been installed or built into the
+kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable
+tracing to the kernel message log type::
echo 7 > /proc/fs/cifs/cifsFYI
-
+
cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
logging of various informational messages. 2 enables logging of non-zero
SMB return codes while 4 enables logging of requests that take longer
-than one second to complete (except for byte range lock requests).
+than one second to complete (except for byte range lock requests).
Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration
(.config). Setting it to seven enables all three. Finally, tracing
-the start of smb requests and responses can be enabled via:
+the start of smb requests and responses can be enabled via::
echo 1 > /proc/fs/cifs/traceSMB
@@ -700,10 +822,10 @@ server) SMB3 (or cifs) requests grouped by request type (read, write, close etc.
Also recorded is the total bytes read and bytes written to the server for
that share. Note that due to client caching effects this can be less than the
number of bytes read and written by the application running on the client.
-Statistics can be reset to zero by "echo 0 > /proc/fs/cifs/Stats" which may be
+Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be
useful if comparing performance of two different scenarios.
-
-Also note that "cat /proc/fs/cifs/DebugData" will display information about
+
+Also note that ``cat /proc/fs/cifs/DebugData`` will display information about
the active sessions and the shares that are mounted.
Enabling Kerberos (extended security) works but requires version 1.2 or later
@@ -725,19 +847,23 @@ space to ease network configuration and improve reliability.
To use cifs Kerberos and DFS support, the Linux keyutils package should be
installed and something like the following lines should be added to the
-/etc/request-key.conf file:
+/etc/request-key.conf file::
-create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
-create dns_resolver * * /usr/local/sbin/cifs.upcall %k
+ create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
+ create dns_resolver * * /usr/local/sbin/cifs.upcall %k
CIFS kernel module parameters
=============================
These module parameters can be specified or modified either during the time of
-module loading or during the runtime by using the interface
+module loading or during the runtime by using the interface::
+
/proc/module/cifs/parameters/<param>
-i.e. echo "value" > /sys/module/cifs/parameters/<param>
+i.e.::
-1. enable_oplocks - Enable or disable oplocks. Oplocks are enabled by default.
- [Y/y/1]. To disable use any of [N/n/0].
+ echo "value" > /sys/module/cifs/parameters/<param>
+================= ==========================================================
+1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default.
+ [Y/y/1]. To disable use any of [N/n/0].
+================= ==========================================================
diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl
similarity index 100%
rename from Documentation/filesystems/cifs/winucase_convert.pl
rename to Documentation/admin-guide/cifs/winucase_convert.pl
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 99d84f5f80db..6e6c23b6193a 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking.
blockdev/index
ext4
binderfs
+ cifs/index
xfs
pm/index
thunderbolt
diff --git a/MAINTAINERS b/MAINTAINERS
index 2055887f07ef..b6b9d8c67987 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4099,7 +4099,7 @@ L: samba-technical@lists.samba.org (moderated for non-subscribers)
W: http://linux-cifs.samba.org/
T: git git://git.samba.org/sfrench/cifs-2.6.git
S: Supported
-F: Documentation/filesystems/cifs/
+F: Documentation/admin-guide/cifs/
F: fs/cifs/
COMPACTPCI HOTPLUG CORE
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 17/26] docs: fs: convert docs without extension to ReST
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (20 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Steve French,
Mike Marshall, Martin Brandenburg, linux-doc, linux-cifs,
samba-technical, devel
There are 3 remaining files without an extension inside the fs docs
dir.
Manually convert them to ReST.
In the case of the nfs/exporting.rst file, as the nfs docs
aren't ported yet, I opted to convert and add a :orphan: there,
with should be removed when it gets added into a nfs-specific
part of the fs documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
...irectory-locking => directory-locking.rst} | 40 ++-
Documentation/filesystems/index.rst | 2 +
.../filesystems/{Locking => locking.rst} | 257 ++++++++++++------
.../nfs/{Exporting => exporting.rst} | 31 ++-
Documentation/filesystems/vfs.rst | 2 +-
fs/cifs/export.c | 2 +-
fs/exportfs/expfs.c | 2 +-
fs/isofs/export.c | 2 +-
fs/orangefs/file.c | 2 +-
include/linux/dcache.h | 2 +-
include/linux/exportfs.h | 2 +-
11 files changed, 225 insertions(+), 119 deletions(-)
rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
rename Documentation/filesystems/{Locking => locking.rst} (79%)
rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking.rst
similarity index 86%
rename from Documentation/filesystems/directory-locking
rename to Documentation/filesystems/directory-locking.rst
index 4e32cb961e5b..de12016ee419 100644
--- a/Documentation/filesystems/directory-locking
+++ b/Documentation/filesystems/directory-locking.rst
@@ -1,12 +1,17 @@
- Locking scheme used for directory operations is based on two
+=================
+Directory Locking
+=================
+
+
+Locking scheme used for directory operations is based on two
kinds of locks - per-inode (->i_rwsem) and per-filesystem
(->s_vfs_rename_mutex).
- When taking the i_rwsem on multiple non-directory objects, we
+When taking the i_rwsem on multiple non-directory objects, we
always acquire the locks in order by increasing address. We'll call
that "inode pointer" order in the following.
- For our purposes all operations fall in 5 classes:
+For our purposes all operations fall in 5 classes:
1) read access. Locking rules: caller locks directory we are accessing.
The lock is taken shared.
@@ -27,25 +32,29 @@ NB: we might get away with locking the the source (and target in exchange
case) shared.
5) link creation. Locking rules:
+
* lock parent
* check that source is not a directory
* lock source
* call the method.
+
All locks are exclusive.
6) cross-directory rename. The trickiest in the whole bunch. Locking
rules:
+
* lock the filesystem
* lock parents in "ancestors first" order.
* find source and target.
* if old parent is equal to or is a descendent of target
- fail with -ENOTEMPTY
+ fail with -ENOTEMPTY
* if new parent is equal to or is a descendent of source
- fail with -ELOOP
+ fail with -ELOOP
* If it's an exchange, lock both the source and the target.
* If the target exists, lock it. If the source is a non-directory,
lock it. If we need to lock both, do so in inode pointer order.
* call the method.
+
All ->i_rwsem are taken exclusive. Again, we might get away with locking
the the source (and target in exchange case) shared.
@@ -54,10 +63,11 @@ read, modified or removed by method will be locked by caller.
If no directory is its own ancestor, the scheme above is deadlock-free.
+
Proof:
First of all, at any moment we have a partial ordering of the
-objects - A < B iff A is an ancestor of B.
+ objects - A < B iff A is an ancestor of B.
That ordering can change. However, the following is true:
@@ -77,32 +87,32 @@ objects - A < B iff A is an ancestor of B.
non-directory object, except renames, which take locks on source and
target in inode pointer order in the case they are not directories.)
- Now consider the minimal deadlock. Each process is blocked on
+Now consider the minimal deadlock. Each process is blocked on
attempt to acquire some lock and already holds at least one lock. Let's
consider the set of contended locks. First of all, filesystem lock is
not contended, since any process blocked on it is not holding any locks.
Thus all processes are blocked on ->i_rwsem.
- By (3), any process holding a non-directory lock can only be
+By (3), any process holding a non-directory lock can only be
waiting on another non-directory lock with a larger address. Therefore
the process holding the "largest" such lock can always make progress, and
non-directory objects are not included in the set of contended locks.
- Thus link creation can't be a part of deadlock - it can't be
+Thus link creation can't be a part of deadlock - it can't be
blocked on source and it means that it doesn't hold any locks.
- Any contended object is either held by cross-directory rename or
+Any contended object is either held by cross-directory rename or
has a child that is also contended. Indeed, suppose that it is held by
operation other than cross-directory rename. Then the lock this operation
is blocked on belongs to child of that object due to (1).
- It means that one of the operations is cross-directory rename.
+It means that one of the operations is cross-directory rename.
Otherwise the set of contended objects would be infinite - each of them
would have a contended child and we had assumed that no object is its
own descendent. Moreover, there is exactly one cross-directory rename
(see above).
- Consider the object blocking the cross-directory rename. One
+Consider the object blocking the cross-directory rename. One
of its descendents is locked by cross-directory rename (otherwise we
would again have an infinite set of contended objects). But that
means that cross-directory rename is taking locks out of order. Due
@@ -112,7 +122,7 @@ try to acquire lock on descendent before the lock on ancestor.
Contradiction. I.e. deadlock is impossible. Q.E.D.
- These operations are guaranteed to avoid loop creation. Indeed,
+These operations are guaranteed to avoid loop creation. Indeed,
the only operation that could introduce loops is cross-directory rename.
Since the only new (parent, child) pair added by rename() is (new parent,
source), such loop would have to contain these objects and the rest of it
@@ -123,13 +133,13 @@ new parent had been equal to or a descendent of source since the moment when
we had acquired filesystem lock and rename() would fail with -ELOOP in that
case.
- While this locking scheme works for arbitrary DAGs, it relies on
+While this locking scheme works for arbitrary DAGs, it relies on
ability to check that directory is a descendent of another object. Current
implementation assumes that directory graph is a tree. This assumption is
also preserved by all operations (cross-directory rename on a tree that would
not introduce a cycle will leave it a tree and link() fails for directories).
- Notice that "directory" in the above == "anything that might have
+Notice that "directory" in the above == "anything that might have
children", so if we are going to introduce hybrid objects we will need
either to make sure that link(2) doesn't work for them or to make changes
in is_subdir() that would make it work even in presence of such beasts.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 2de2fe2ab078..08320c35d03b 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -20,6 +20,8 @@ algorithms work.
path-lookup
api-summary
splice
+ locking
+ directory-locking
Filesystem support layers
=========================
diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/locking.rst
similarity index 79%
rename from Documentation/filesystems/Locking
rename to Documentation/filesystems/locking.rst
index 204dd3ea36bb..fc3a0704553c 100644
--- a/Documentation/filesystems/Locking
+++ b/Documentation/filesystems/locking.rst
@@ -1,14 +1,22 @@
- The text below describes the locking rules for VFS-related methods.
+=======
+Locking
+=======
+
+The text below describes the locking rules for VFS-related methods.
It is (believed to be) up-to-date. *Please*, if you change anything in
prototypes or locking protocols - update this file. And update the relevant
instances in the tree, don't leave that to maintainers of filesystems/devices/
etc. At the very least, put the list of dubious cases in the end of this file.
Don't turn it into log - maintainers of out-of-the-tree code are supposed to
be able to use diff(1).
- Thing currently missing here: socket operations. Alexey?
---------------------------- dentry_operations --------------------------
-prototypes:
+Thing currently missing here: socket operations. Alexey?
+
+dentry_operations
+=================
+
+prototypes::
+
int (*d_revalidate)(struct dentry *, unsigned int);
int (*d_weak_revalidate)(struct dentry *, unsigned int);
int (*d_hash)(const struct dentry *, struct qstr *);
@@ -24,23 +32,30 @@ prototypes:
struct dentry *(*d_real)(struct dentry *, const struct inode *);
locking rules:
- rename_lock ->d_lock may block rcu-walk
-d_revalidate: no no yes (ref-walk) maybe
-d_weak_revalidate:no no yes no
-d_hash no no no maybe
-d_compare: yes no no maybe
-d_delete: no yes no no
-d_init: no no yes no
-d_release: no no yes no
-d_prune: no yes no no
-d_iput: no no yes no
-d_dname: no no no no
-d_automount: no no yes no
-d_manage: no no yes (ref-walk) maybe
-d_real no no yes no
---------------------------- inode_operations ---------------------------
-prototypes:
+================== =========== ======== ============== ========
+ops rename_lock ->d_lock may block rcu-walk
+================== =========== ======== ============== ========
+d_revalidate: no no yes (ref-walk) maybe
+d_weak_revalidate: no no yes no
+d_hash no no no maybe
+d_compare: yes no no maybe
+d_delete: no yes no no
+d_init: no no yes no
+d_release: no no yes no
+d_prune: no yes no no
+d_iput: no no yes no
+d_dname: no no no no
+d_automount: no no yes no
+d_manage: no no yes (ref-walk) maybe
+d_real no no yes no
+================== =========== ======== ============== ========
+
+inode_operations
+================
+
+prototypes::
+
int (*create) (struct inode *,struct dentry *,umode_t, bool);
struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
int (*link) (struct dentry *,struct inode *,struct dentry *);
@@ -68,7 +83,10 @@ prototypes:
locking rules:
all may block
- i_rwsem(inode)
+
+============ =============================================
+ops i_rwsem(inode)
+============ =============================================
lookup: shared
create: exclusive
link: exclusive (both)
@@ -89,17 +107,21 @@ fiemap: no
update_time: no
atomic_open: exclusive
tmpfile: no
+============ =============================================
Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
exclusive on victim.
cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
-See Documentation/filesystems/directory-locking for more detailed discussion
+See Documentation/filesystems/directory-locking.rst for more detailed discussion
of the locking scheme for directory operations.
------------------------ xattr_handler operations -----------------------
-prototypes:
+xattr_handler operations
+========================
+
+prototypes::
+
bool (*list)(struct dentry *dentry);
int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
struct inode *inode, const char *name, void *buffer,
@@ -110,13 +132,20 @@ prototypes:
locking rules:
all may block
- i_rwsem(inode)
+
+===== ==============
+ops i_rwsem(inode)
+===== ==============
list: no
get: no
set: exclusive
+===== ==============
+
+super_operations
+================
+
+prototypes::
---------------------------- super_operations ---------------------------
-prototypes:
struct inode *(*alloc_inode)(struct super_block *sb);
void (*free_inode)(struct inode *);
void (*destroy_inode)(struct inode *);
@@ -138,7 +167,10 @@ prototypes:
locking rules:
All may block [not true, see below]
- s_umount
+
+====================== ============ ========================
+ops s_umount note
+====================== ============ ========================
alloc_inode:
free_inode: called from RCU callback
destroy_inode:
@@ -157,6 +189,7 @@ show_options: no (namespace_sem)
quota_read: no (see below)
quota_write: no (see below)
bdev_try_to_free_page: no (see below)
+====================== ============ ========================
->statfs() has s_umount (shared) when called by ustat(2) (native or
compat), but that's an accident of bad API; s_umount is used to pin
@@ -164,31 +197,44 @@ the superblock down when we only have dev_t given us by userland to
identify the superblock. Everything else (statfs(), fstatfs(), etc.)
doesn't hold it when calling ->statfs() - superblock is pinned down
by resolving the pathname passed to syscall.
+
->quota_read() and ->quota_write() functions are both guaranteed to
be the only ones operating on the quota file by the quota code (via
dqio_sem) (unless an admin really wants to screw up something and
writes to quota files with quotas on). For other details about locking
see also dquot_operations section.
+
->bdev_try_to_free_page is called from the ->releasepage handler of
the block device inode. See there for more details.
---------------------------- file_system_type ---------------------------
-prototypes:
+file_system_type
+================
+
+prototypes::
+
struct dentry *(*mount) (struct file_system_type *, int,
const char *, void *);
void (*kill_sb) (struct super_block *);
+
locking rules:
- may block
+
+======= =========
+ops may block
+======= =========
mount yes
kill_sb yes
+======= =========
->mount() returns ERR_PTR or the root dentry; its superblock should be locked
on return.
+
->kill_sb() takes a write-locked superblock, does all shutdown work on it,
unlocks and drops the reference.
---------------------------- address_space_operations --------------------------
-prototypes:
+address_space_operations
+========================
+prototypes::
+
int (*writepage)(struct page *page, struct writeback_control *wbc);
int (*readpage)(struct file *, struct page *);
int (*writepages)(struct address_space *, struct writeback_control *);
@@ -218,14 +264,16 @@ prototypes:
locking rules:
All except set_page_dirty and freepage may block
- PageLocked(page) i_rwsem
+====================== ======================== =========
+ops PageLocked(page) i_rwsem
+====================== ======================== =========
writepage: yes, unlocks (see below)
readpage: yes, unlocks
writepages:
set_page_dirty no
readpages:
-write_begin: locks the page exclusive
-write_end: yes, unlocks exclusive
+write_begin: locks the page exclusive
+write_end: yes, unlocks exclusive
bmap:
invalidatepage: yes
releasepage: yes
@@ -239,17 +287,18 @@ is_partially_uptodate: yes
error_remove_page: yes
swap_activate: no
swap_deactivate: no
+====================== ======================== =========
- ->write_begin(), ->write_end() and ->readpage() may be called from
+->write_begin(), ->write_end() and ->readpage() may be called from
the request handler (/dev/loop).
- ->readpage() unlocks the page, either synchronously or via I/O
+->readpage() unlocks the page, either synchronously or via I/O
completion.
- ->readpages() populates the pagecache with the passed pages and starts
+->readpages() populates the pagecache with the passed pages and starts
I/O against them. They come unlocked upon I/O completion.
- ->writepage() is used for two purposes: for "memory cleansing" and for
+->writepage() is used for two purposes: for "memory cleansing" and for
"sync". These are quite different operations and the behaviour may differ
depending upon the mode.
@@ -297,70 +346,81 @@ will leave the page itself marked clean but it will be tagged as dirty in the
radix tree. This incoherency can lead to all sorts of hard-to-debug problems
in the filesystem like having dirty inodes at umount and losing written data.
- ->writepages() is used for periodic writeback and for syscall-initiated
+->writepages() is used for periodic writeback and for syscall-initiated
sync operations. The address_space should start I/O against at least
-*nr_to_write pages. *nr_to_write must be decremented for each page which is
-written. The address_space implementation may write more (or less) pages
-than *nr_to_write asks for, but it should try to be reasonably close. If
-nr_to_write is NULL, all dirty pages must be written.
+``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page
+which is written. The address_space implementation may write more (or less)
+pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
+If nr_to_write is NULL, all dirty pages must be written.
writepages should _only_ write pages which are present on
mapping->io_pages.
- ->set_page_dirty() is called from various places in the kernel
+->set_page_dirty() is called from various places in the kernel
when the target page is marked as needing writeback. It may be called
under spinlock (it cannot block) and is sometimes called with the page
not locked.
- ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
+->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
filesystems and by the swapper. The latter will eventually go away. Please,
keep it that way and don't breed new callers.
- ->invalidatepage() is called when the filesystem must attempt to drop
+->invalidatepage() is called when the filesystem must attempt to drop
some or all of the buffers from the page when it is being truncated. It
returns zero on success. If ->invalidatepage is zero, the kernel uses
block_invalidatepage() instead.
- ->releasepage() is called when the kernel is about to try to drop the
+->releasepage() is called when the kernel is about to try to drop the
buffers from the page in preparation for freeing it. It returns zero to
indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
the kernel assumes that the fs has no private interest in the buffers.
- ->freepage() is called when the kernel is done dropping the page
+->freepage() is called when the kernel is done dropping the page
from the page cache.
- ->launder_page() may be called prior to releasing a page if
+->launder_page() may be called prior to releasing a page if
it is still found to be dirty. It returns zero if the page was successfully
cleaned, or an error value if not. Note that in order to prevent the page
getting mapped back in and redirtied, it needs to be kept locked
across the entire operation.
- ->swap_activate will be called with a non-zero argument on
+->swap_activate will be called with a non-zero argument on
files backing (non block device backed) swapfiles. A return value
of zero indicates success, in which case this file can be used for
backing swapspace. The swapspace operations will be proxied to the
address space operations.
- ->swap_deactivate() will be called in the sys_swapoff()
+->swap_deactivate() will be called in the sys_swapoff()
path after ->swap_activate() returned success.
------------------------ file_lock_operations ------------------------------
-prototypes:
+file_lock_operations
+====================
+
+prototypes::
+
void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
void (*fl_release_private)(struct file_lock *);
locking rules:
- inode->i_lock may block
+
+=================== ============= =========
+ops inode->i_lock may block
+=================== ============= =========
fl_copy_lock: yes no
-fl_release_private: maybe maybe[1]
+fl_release_private: maybe maybe[1]_
+=================== ============= =========
-[1]: ->fl_release_private for flock or POSIX locks is currently allowed
-to block. Leases however can still be freed while the i_lock is held and
-so fl_release_private called on a lease should not block.
+.. [1]:
+ ->fl_release_private for flock or POSIX locks is currently allowed
+ to block. Leases however can still be freed while the i_lock is held and
+ so fl_release_private called on a lease should not block.
+
+lock_manager_operations
+=======================
+
+prototypes::
------------------------ lock_manager_operations ---------------------------
-prototypes:
void (*lm_notify)(struct file_lock *); /* unblock callback */
int (*lm_grant)(struct file_lock *, struct file_lock *, int);
void (*lm_break)(struct file_lock *); /* break_lease callback */
@@ -368,24 +428,33 @@ prototypes:
locking rules:
- inode->i_lock blocked_lock_lock may block
+========== ============= ================= =========
+ops inode->i_lock blocked_lock_lock may block
+========== ============= ================= =========
lm_notify: yes yes no
lm_grant: no no no
lm_break: yes no no
lm_change yes no no
+========== ============= ================= =========
+
+buffer_head
+===========
+
+prototypes::
---------------------------- buffer_head -----------------------------------
-prototypes:
void (*b_end_io)(struct buffer_head *bh, int uptodate);
locking rules:
- called from interrupts. In other words, extreme care is needed here.
+
+called from interrupts. In other words, extreme care is needed here.
bh is locked, but that's all warranties we have here. Currently only RAID1,
highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
call this method upon the IO completion.
---------------------------- block_device_operations -----------------------
-prototypes:
+block_device_operations
+=======================
+prototypes::
+
int (*open) (struct block_device *, fmode_t);
int (*release) (struct gendisk *, fmode_t);
int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
@@ -399,7 +468,10 @@ prototypes:
void (*swap_slot_free_notify) (struct block_device *, unsigned long);
locking rules:
- bd_mutex
+
+======================= ===================
+ops bd_mutex
+======================= ===================
open: yes
release: yes
ioctl: no
@@ -410,6 +482,7 @@ unlock_native_capacity: no
revalidate_disk: no
getgeo: no
swap_slot_free_notify: no (see below)
+======================= ===================
media_changed, unlock_native_capacity and revalidate_disk are called only from
check_disk_change().
@@ -418,8 +491,11 @@ swap_slot_free_notify is called with swap_lock and sometimes the page lock
held.
---------------------------- file_operations -------------------------------
-prototypes:
+file_operations
+===============
+
+prototypes::
+
loff_t (*llseek) (struct file *, loff_t, int);
ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
@@ -455,7 +531,6 @@ prototypes:
size_t, unsigned int);
int (*setlease)(struct file *, long, struct file_lock **, void **);
long (*fallocate)(struct file *, int, loff_t, loff_t);
-};
locking rules:
All may block.
@@ -490,8 +565,11 @@ in sys_read() and friends.
the lease within the individual filesystem to record the result of the
operation
---------------------------- dquot_operations -------------------------------
-prototypes:
+dquot_operations
+================
+
+prototypes::
+
int (*write_dquot) (struct dquot *);
int (*acquire_dquot) (struct dquot *);
int (*release_dquot) (struct dquot *);
@@ -503,20 +581,26 @@ a proper locking wrt the filesystem and call the generic quota operations.
What filesystem should expect from the generic quota functions:
- FS recursion Held locks when called
+============== ============ =========================
+ops FS recursion Held locks when called
+============== ============ =========================
write_dquot: yes dqonoff_sem or dqptr_sem
acquire_dquot: yes dqonoff_sem or dqptr_sem
release_dquot: yes dqonoff_sem or dqptr_sem
mark_dirty: no -
write_info: yes dqonoff_sem
+============== ============ =========================
FS recursion means calling ->quota_read() and ->quota_write() from superblock
operations.
More details about quota locking can be found in fs/dquot.c.
---------------------------- vm_operations_struct -----------------------------
-prototypes:
+vm_operations_struct
+====================
+
+prototypes::
+
void (*open)(struct vm_area_struct*);
void (*close)(struct vm_area_struct*);
vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
@@ -525,7 +609,10 @@ prototypes:
int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
locking rules:
- mmap_sem PageLocked(page)
+
+============= ======== ===========================
+ops mmap_sem PageLocked(page)
+============= ======== ===========================
open: yes
close: yes
fault: yes can return with page locked
@@ -533,8 +620,9 @@ map_pages: yes
page_mkwrite: yes can return with page locked
pfn_mkwrite: yes
access: yes
+============= ======== ===========================
- ->fault() is called when a previously not present pte is about
+->fault() is called when a previously not present pte is about
to be faulted in. The filesystem must find and return the page associated
with the passed in "pgoff" in the vm_fault structure. If it is possible that
the page may be truncated and/or invalidated, then the filesystem must lock
@@ -542,7 +630,7 @@ the page, then ensure it is not already truncated (the page lock will block
subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
locked. The VM will unlock the page.
- ->map_pages() is called when VM asks to map easy accessible pages.
+->map_pages() is called when VM asks to map easy accessible pages.
Filesystem should find and map pages associated with offsets from "start_pgoff"
till "end_pgoff". ->map_pages() is called with page table locked and must
not block. If it's not possible to reach a page without blocking,
@@ -551,25 +639,26 @@ page table entry. Pointer to entry associated with the page is passed in
"pte" field in vm_fault structure. Pointers to entries for other offsets
should be calculated relative to "pte".
- ->page_mkwrite() is called when a previously read-only pte is
+->page_mkwrite() is called when a previously read-only pte is
about to become writeable. The filesystem again must ensure that there are
no truncate/invalidate races, and then return with the page locked. If
the page has been truncated, the filesystem should not look up a new page
like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
will cause the VM to retry the fault.
- ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
+->pfn_mkwrite() is the same as page_mkwrite but when the pte is
VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
after this call is to make the pte read-write, unless pfn_mkwrite returns
an error.
- ->access() is called when get_user_pages() fails in
+->access() is called when get_user_pages() fails in
access_process_vm(), typically used to debug a process through
/proc/pid/mem or ptrace. This function is needed only for
VM_IO | VM_PFNMAP VMAs.
-================================================================================
+--------------------------------------------------------------------------------
+
Dubious stuff
(if you break something or notice that it is broken and do not fix it yourself
diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/exporting.rst
similarity index 91%
rename from Documentation/filesystems/nfs/Exporting
rename to Documentation/filesystems/nfs/exporting.rst
index 63889149f532..33d588a01ace 100644
--- a/Documentation/filesystems/nfs/Exporting
+++ b/Documentation/filesystems/nfs/exporting.rst
@@ -1,3 +1,4 @@
+:orphan:
Making Filesystems Exportable
=============================
@@ -42,9 +43,9 @@ filehandle fragment, there is no automatic creation of a path prefix
for the object. This leads to two related but distinct features of
the dcache that are not needed for normal filesystem access.
-1/ The dcache must sometimes contain objects that are not part of the
+1. The dcache must sometimes contain objects that are not part of the
proper prefix. i.e that are not connected to the root.
-2/ The dcache must be prepared for a newly found (via ->lookup) directory
+2. The dcache must be prepared for a newly found (via ->lookup) directory
to already have a (non-connected) dentry, and must be able to move
that dentry into place (based on the parent and name in the
->lookup). This is particularly needed for directories as
@@ -52,7 +53,7 @@ the dcache that are not needed for normal filesystem access.
To implement these features, the dcache has:
-a/ A dentry flag DCACHE_DISCONNECTED which is set on
+a. A dentry flag DCACHE_DISCONNECTED which is set on
any dentry that might not be part of the proper prefix.
This is set when anonymous dentries are created, and cleared when a
dentry is noticed to be a child of a dentry which is in the proper
@@ -71,48 +72,52 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on
dentries. That guarantees that we won't need to hunt them down upon
umount.
-b/ A primitive for creation of secondary roots - d_obtain_root(inode).
+b. A primitive for creation of secondary roots - d_obtain_root(inode).
Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the
per-superblock list (->s_roots), so they can be located at umount
time for eviction purposes.
-c/ Helper routines to allocate anonymous dentries, and to help attach
+c. Helper routines to allocate anonymous dentries, and to help attach
loose directory dentries at lookup time. They are:
+
d_obtain_alias(inode) will return a dentry for the given inode.
If the inode already has a dentry, one of those is returned.
+
If it doesn't, a new anonymous (IS_ROOT and
- DCACHE_DISCONNECTED) dentry is allocated and attached.
+ DCACHE_DISCONNECTED) dentry is allocated and attached.
+
In the case of a directory, care is taken that only one dentry
can ever be attached.
+
d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
either the passed-in dentry or a preexisting alias for the given inode
(such as an anonymous one created by d_obtain_alias), if appropriate.
It returns NULL when the passed-in dentry is used, following the calling
convention of ->lookup.
-
+
Filesystem Issues
-----------------
For a filesystem to be exportable it must:
-
- 1/ provide the filehandle fragment routines described below.
- 2/ make sure that d_splice_alias is used rather than d_add
+
+ 1. provide the filehandle fragment routines described below.
+ 2. make sure that d_splice_alias is used rather than d_add
when ->lookup finds an inode for a given parent and name.
- If inode is NULL, d_splice_alias(inode, dentry) is equivalent to
+ If inode is NULL, d_splice_alias(inode, dentry) is equivalent to::
d_add(dentry, inode), NULL
Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)
- Typically the ->lookup routine will simply end with a:
+ Typically the ->lookup routine will simply end with a::
return d_splice_alias(inode, dentry);
}
- A file system implementation declares that instances of the filesystem
+A file system implementation declares that instances of the filesystem
are exportable by setting the s_export_op field in the struct
super_block. This field must point to a "struct export_operations"
struct which has the following members:
diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 0f85ab21c2ca..7d4d09dd5e6d 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist.
VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on
are called from a process context. Filesystem locking is described in
-the document Documentation/filesystems/Locking.
+the document Documentation/filesystems/locking.rst.
Directory Entry Cache (dcache)
diff --git a/fs/cifs/export.c b/fs/cifs/export.c
index ce8b7f677c58..eb0bb8ca8e63 100644
--- a/fs/cifs/export.c
+++ b/fs/cifs/export.c
@@ -24,7 +24,7 @@
*/
/*
- * See Documentation/filesystems/nfs/Exporting
+ * See Documentation/filesystems/nfs/exporting.rst
* and examples in fs/exportfs
*
* Since cifs is a network file system, an "fsid" must be included for
diff --git a/fs/exportfs/expfs.c b/fs/exportfs/expfs.c
index f0e549783caf..09bc68708d28 100644
--- a/fs/exportfs/expfs.c
+++ b/fs/exportfs/expfs.c
@@ -7,7 +7,7 @@
* and for mapping back from file handles to dentries.
*
* For details on why we do all the strange and hairy things in here
- * take a look at Documentation/filesystems/nfs/Exporting.
+ * take a look at Documentation/filesystems/nfs/exporting.rst.
*/
#include <linux/exportfs.h>
#include <linux/fs.h>
diff --git a/fs/isofs/export.c b/fs/isofs/export.c
index 85a9093769a9..35768a63fb1d 100644
--- a/fs/isofs/export.c
+++ b/fs/isofs/export.c
@@ -10,7 +10,7 @@
*
* The following files are helpful:
*
- * Documentation/filesystems/nfs/Exporting
+ * Documentation/filesystems/nfs/exporting.rst
* fs/exportfs/expfs.c.
*/
diff --git a/fs/orangefs/file.c b/fs/orangefs/file.c
index 960f9a3c012d..a5612abc0936 100644
--- a/fs/orangefs/file.c
+++ b/fs/orangefs/file.c
@@ -555,7 +555,7 @@ static int orangefs_fsync(struct file *file,
* Change the file pointer position for an instance of an open file.
*
* \note If .llseek is overriden, we must acquire lock as described in
- * Documentation/filesystems/Locking.
+ * Documentation/filesystems/locking.rst.
*
* Future upgrade could support SEEK_DATA and SEEK_HOLE but would
* require much changes to the FS
diff --git a/include/linux/dcache.h b/include/linux/dcache.h
index 9451011ac014..10090f11ab95 100644
--- a/include/linux/dcache.h
+++ b/include/linux/dcache.h
@@ -151,7 +151,7 @@ struct dentry_operations {
/*
* Locking rules for dentry_operations callbacks are to be found in
- * Documentation/filesystems/Locking. Keep it updated!
+ * Documentation/filesystems/locking.rst. Keep it updated!
*
* FUrther descriptions are found in Documentation/filesystems/vfs.rst.
* Keep it updated too!
diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h
index 0d3037419bc7..cf6571fc9c01 100644
--- a/include/linux/exportfs.h
+++ b/include/linux/exportfs.h
@@ -139,7 +139,7 @@ struct fid {
* @get_parent: find the parent of a given directory
* @commit_metadata: commit metadata changes to stable storage
*
- * See Documentation/filesystems/nfs/Exporting for details on how to use
+ * See Documentation/filesystems/nfs/exporting.rst for details on how to use
* this interface correctly.
*
* encode_fh:
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 18/26] docs: fs: convert porting to ReST
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (21 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Mike Marshall,
Martin Brandenburg, linux-doc, devel
This file has its own proper style, except that, after a while,
the coding style gets violated and whitespaces are placed on
different ways.
As Sphinx and ReST are very sentitive to whitespace differences,
I had to opt if each entry after required/mandatory/... fields
should start with zero spaces or with a tab. I opted to start them
all from the zero position, in order to avoid needing to break lines
with more than 80 columns, with would make harder for review.
Most of the other changes at porting.rst were made to use an unified
notation with works nice as a text file while also produce a good html
output after being parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/filesystems/index.rst | 2 +
.../filesystems/{porting => porting.rst} | 824 +++++++++++-------
fs/orangefs/orangefs-kernel.h | 2 +-
3 files changed, 498 insertions(+), 330 deletions(-)
rename Documentation/filesystems/{porting => porting.rst} (49%)
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 08320c35d03b..96653ebefd7e 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -23,6 +23,8 @@ algorithms work.
locking
directory-locking
+ porting
+
Filesystem support layers
=========================
diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting.rst
similarity index 49%
rename from Documentation/filesystems/porting
rename to Documentation/filesystems/porting.rst
index 6b7a41cfcaed..66aa521e6376 100644
--- a/Documentation/filesystems/porting
+++ b/Documentation/filesystems/porting.rst
@@ -1,22 +1,28 @@
+====================
Changes since 2.5.0:
+====================
---
-[recommended]
+
+**recommended**
New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
- sb_set_blocksize() and sb_min_blocksize().
+sb_set_blocksize() and sb_min_blocksize().
Use them.
(sb_find_get_block() replaces 2.4's get_hash_table())
---
-[recommended]
+
+**recommended**
New methods: ->alloc_inode() and ->destroy_inode().
Remove inode->u.foo_inode_i
-Declare
+
+Declare::
+
struct foo_inode_info {
/* fs-private stuff */
struct inode vfs_inode;
@@ -40,7 +46,8 @@ typically between calling iget_locked() and unlocking the inode.
At some point that will become mandatory.
---
-[mandatory]
+
+**mandatory**
Change of file_system_type method (->read_super to ->get_sb)
@@ -48,14 +55,14 @@ Change of file_system_type method (->read_super to ->get_sb)
Turn your foo_read_super() into a function that would return 0 in case of
success and negative number in case of error (-EINVAL unless you have more
-informative error value to report). Call it foo_fill_super(). Now declare
+informative error value to report). Call it foo_fill_super(). Now declare::
-int foo_get_sb(struct file_system_type *fs_type,
+ int foo_get_sb(struct file_system_type *fs_type,
int flags, const char *dev_name, void *data, struct vfsmount *mnt)
-{
+ {
return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
mnt);
-}
+ }
(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
filesystem).
@@ -64,7 +71,8 @@ Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
foo_get_sb.
---
-[mandatory]
+
+**mandatory**
Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
Most likely there is no need to change anything, but if you relied on
@@ -73,7 +81,8 @@ change your internal locking. Otherwise exclusion warranties remain the
same (i.e. parents and victim are locked, etc.).
---
-[informational]
+
+**informational**
Now we have the exclusion between ->lookup() and directory removal (by
->rmdir() and ->rename()). If you used to need that exclusion and do
@@ -81,7 +90,8 @@ it by internal locking (most of filesystems couldn't care less) - you
can relax your locking.
---
-[mandatory]
+
+**mandatory**
->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
@@ -92,51 +102,60 @@ unlock_kernel() so that they would protect exactly what needs to be
protected.
---
-[mandatory]
+
+**mandatory**
BKL is also moved from around sb operations. BKL should have been shifted into
individual fs sb_op functions. If you don't need it, remove it.
---
-[informational]
+
+**informational**
check for ->link() target not being a directory is done by callers. Feel
free to drop it...
---
-[informational]
+
+**informational**
->link() callers hold ->i_mutex on the object we are linking to. Some of your
problems might be over...
---
-[mandatory]
+
+**mandatory**
new file_system_type method - kill_sb(superblock). If you are converting
-an existing filesystem, set it according to ->fs_flags:
+an existing filesystem, set it according to ->fs_flags::
+
FS_REQUIRES_DEV - kill_block_super
FS_LITTER - kill_litter_super
neither - kill_anon_super
+
FS_LITTER is gone - just remove it from fs_flags.
---
-[mandatory]
- FS_SINGLE is gone (actually, that had happened back when ->get_sb()
+**mandatory**
+
+FS_SINGLE is gone (actually, that had happened back when ->get_sb()
went in - and hadn't been documented ;-/). Just remove it from fs_flags
(and see ->get_sb() entry for other actions).
---
-[mandatory]
+
+**mandatory**
->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so
watch for ->i_mutex-grabbing code that might be used by your ->setattr().
Callers of notify_change() need ->i_mutex now.
---
-[recommended]
-New super_block field "struct export_operations *s_export_op" for
+**recommended**
+
+New super_block field ``struct export_operations *s_export_op`` for
explicit support for exporting, e.g. via NFS. The structure is fully
documented at its declaration in include/linux/fs.h, and in
Documentation/filesystems/nfs/Exporting.
@@ -149,17 +168,18 @@ support for this helper, particularly get_parent.
It is planned that this will be required for exporting once the code
settles down a bit.
-[mandatory]
+**mandatory**
s_export_op is now required for exporting a filesystem.
isofs, ext2, ext3, resierfs, fat
can be used as examples of very different filesystems.
---
-[mandatory]
+
+**mandatory**
iget4() and the read_inode2 callback have been superseded by iget5_locked()
-which has the following prototype,
+which has the following prototype::
struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
int (*test)(struct inode *, void *),
@@ -182,7 +202,8 @@ when appropriate. There is also a simpler iget_locked function that
just takes the superblock and inode number as arguments and does the
test and set for you.
-e.g.
+e.g.::
+
inode = iget_locked(sb, ino);
if (inode->i_state & I_NEW) {
err = read_inode_from_disk(inode);
@@ -198,27 +219,32 @@ should be called on the inode to render it dead, and an appropriate error
should be passed back to the caller.
---
-[recommended]
+
+**recommended**
->getattr() finally getting used. See instances in nfs, minix, etc.
---
-[mandatory]
+
+**mandatory**
->revalidate() is gone. If your filesystem had it - provide ->getattr()
and let it call whatever you had as ->revlidate() + (for symlinks that
had ->revalidate()) add calls in ->follow_link()/->readlink().
---
-[mandatory]
+
+**mandatory**
->d_parent changes are not protected by BKL anymore. Read access is safe
if at least one of the following is true:
+
* filesystem has no cross-directory rename()
* we know that parent had been locked (e.g. we are looking at
-->d_parent of ->lookup() argument).
+ ->d_parent of ->lookup() argument).
* we are called from ->rename().
* the child's ->d_lock is held
+
Audit your code and add locking if needed. Notice that any place that is
not protected by the conditions above is risky even in the old tree - you
had been relying on BKL and that's prone to screwups. Old tree had quite
@@ -226,20 +252,23 @@ a few holes of that kind - unprotected access to ->d_parent leading to
anything from oops to silent memory corruption.
---
-[mandatory]
- FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
+**mandatory**
+
+FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags
(see rootfs for one kind of solution and bdev/socket/pipe for another).
---
-[recommended]
- Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
+**recommended**
+
+Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter
is still alive, but only because of the mess in drivers/s390/block/dasd.c.
As soon as it gets fixed is_read_only() will die.
---
-[mandatory]
+
+**mandatory**
->permission() is called without BKL now. Grab it on entry, drop upon
return - that will guarantee the same locking you used to have. If
@@ -248,40 +277,44 @@ shift lock_kernel() and unlock_kernel() so that they would protect
exactly what needs to be protected.
---
-[mandatory]
+
+**mandatory**
->statfs() is now called without BKL held. BKL should have been
shifted into individual fs sb_op functions where it's not clear that
it's safe to remove it. If you don't need it, remove it.
---
-[mandatory]
- is_read_only() is gone; use bdev_read_only() instead.
+**mandatory**
+
+is_read_only() is gone; use bdev_read_only() instead.
---
-[mandatory]
- destroy_buffers() is gone; use invalidate_bdev().
+**mandatory**
+
+destroy_buffers() is gone; use invalidate_bdev().
---
-[mandatory]
- fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
+**mandatory**
+
+fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is
deliberate; as soon as struct block_device * is propagated in a reasonable
way by that code fixing will become trivial; until then nothing can be
done.
-[mandatory]
+**mandatory**
- block truncatation on error exit from ->write_begin, and ->direct_IO
+block truncatation on error exit from ->write_begin, and ->direct_IO
moved from generic methods (block_write_begin, cont_write_begin,
nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at
ext2_write_failed and callers for an example.
-[mandatory]
+**mandatory**
- ->truncate is gone. The whole truncate sequence needs to be
+->truncate is gone. The whole truncate sequence needs to be
implemented in ->setattr, which is now mandatory for filesystems
implementing on-disk size changes. Start with a copy of the old inode_setattr
and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
@@ -290,78 +323,86 @@ size update and on finally on-disk truncation which should not fail.
setattr_prepare (which used to be inode_change_ok) now includes the size checks
for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
-[mandatory]
+**mandatory**
- ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
+->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
be used instead. It gets called whenever the inode is evicted, whether it has
remaining links or not. Caller does *not* evict the pagecache or inode-associated
metadata buffers; the method has to use truncate_inode_pages_final() to get rid
of those. Caller makes sure async writeback cannot be running for the inode while
(or after) ->evict_inode() is called.
- ->drop_inode() returns int now; it's called on final iput() with
+->drop_inode() returns int now; it's called on final iput() with
inode->i_lock held and it returns true if filesystems wants the inode to be
dropped. As before, generic_drop_inode() is still the default and it's been
updated appropriately. generic_delete_inode() is also alive and it consists
simply of return 1. Note that all actual eviction work is done by caller after
->drop_inode() returns.
- As before, clear_inode() must be called exactly once on each call of
+As before, clear_inode() must be called exactly once on each call of
->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike
before, if you are using inode-associated metadata buffers (i.e.
mark_buffer_dirty_inode()), it's your responsibility to call
invalidate_inode_buffers() before clear_inode().
- NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
+NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput()
may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
free the on-disk inode, you may end up doing that while ->write_inode() is writing
to it.
---
-[mandatory]
- .d_delete() now only advises the dcache as to whether or not to cache
+**mandatory**
+
+.d_delete() now only advises the dcache as to whether or not to cache
unreferenced dentries, and is now only called when the dentry refcount goes to
0. Even on 0 refcount transition, it must be able to tolerate being called 0,
1, or more times (eg. constant, idempotent).
---
-[mandatory]
- .d_compare() calling convention and locking rules are significantly
+**mandatory**
+
+.d_compare() calling convention and locking rules are significantly
changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
look at examples of other filesystems) for guidance.
---
-[mandatory]
- .d_hash() calling convention and locking rules are significantly
+**mandatory**
+
+.d_hash() calling convention and locking rules are significantly
changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
look at examples of other filesystems) for guidance.
---
-[mandatory]
- dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
+
+**mandatory**
+
+dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
for details of what locks to replace dcache_lock with in order to protect
particular things. Most of the time, a filesystem only needs ->d_lock, which
protects *all* the dcache state of a given dentry.
---
-[mandatory]
+---
- Filesystems must RCU-free their inodes, if they can have been accessed
+**mandatory**
+
+Filesystems must RCU-free their inodes, if they can have been accessed
via rcu-walk path walk (basically, if the file can have had a path name in the
vfs namespace).
- Even though i_dentry and i_rcu share storage in a union, we will
+Even though i_dentry and i_rcu share storage in a union, we will
initialize the former in inode_init_always(), so just leave it alone in
the callback. It used to be necessary to clean it there, but not anymore
(starting at 3.2).
---
-[recommended]
- vfs now tries to do path walking in "rcu-walk mode", which avoids
+---
+
+**recommended**
+
+vfs now tries to do path walking in "rcu-walk mode", which avoids
atomic operations and scalability hazards on dentries and inodes (see
Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
(above) are examples of the changes required to support this. For more complex
@@ -371,46 +412,58 @@ the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
are rcu-walk aware, shown below. Filesystems should take advantage of this
where possible.
---
-[mandatory]
- d_revalidate is a callback that is made on every path element (if
+---
+
+**mandatory**
+
+d_revalidate is a callback that is made on every path element (if
the filesystem provides it), which requires dropping out of rcu-walk mode. This
may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
returned if the filesystem cannot handle rcu-walk. See
Documentation/filesystems/vfs.rst for more details.
- permission is an inode permission check that is called on many or all
+permission is an inode permission check that is called on many or all
directory inodes on the way down a path walk (to check for exec permission). It
must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See
Documentation/filesystems/vfs.rst for more details.
-
---
-[mandatory]
- In ->fallocate() you must check the mode option passed in. If your
+
+---
+
+**mandatory**
+
+In ->fallocate() you must check the mode option passed in. If your
filesystem does not support hole punching (deallocating space in the middle of a
file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
so the i_size should not change when hole punching, even when puching the end of
a file off.
---
-[mandatory]
- ->get_sb() is gone. Switch to use of ->mount(). Typically it's just
-a matter of switching from calling get_sb_... to mount_... and changing the
-function type. If you were doing it manually, just switch from setting ->mnt_root
-to some pointer to returning that pointer. On errors return ERR_PTR(...).
-
---
-[mandatory]
- ->permission() and generic_permission()have lost flags
+---
+
+**mandatory**
+
+->get_sb() is gone. Switch to use of ->mount(). Typically it's just
+a matter of switching from calling ``get_sb_``... to ``mount_``... and changing
+the function type. If you were doing it manually, just switch from setting
+->mnt_root to some pointer to returning that pointer. On errors return
+ERR_PTR(...).
+
+---
+
+**mandatory**
+
+->permission() and generic_permission()have lost flags
argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
- generic_permission() has also lost the check_acl argument; ACL checking
+
+generic_permission() has also lost the check_acl argument; ACL checking
has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
to read an ACL from disk.
---
-[mandatory]
- If you implement your own ->llseek() you must handle SEEK_HOLE and
+---
+
+**mandatory**
+
+If you implement your own ->llseek() you must handle SEEK_HOLE and
SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to
support it in some way. The generic handler assumes that the entire file is
data and there is a virtual hole at the end of the file. So if the provided
@@ -418,22 +471,25 @@ offset is less than i_size and SEEK_DATA is specified, return the same offset.
If the above is true for the offset and you are given SEEK_HOLE, return the end
of the file. If the offset is i_size or greater return -ENXIO in either case.
-[mandatory]
- If you have your own ->fsync() you must make sure to call
+**mandatory**
+
+If you have your own ->fsync() you must make sure to call
filemap_write_and_wait_range() so that all dirty pages are synced out properly.
You must also keep in mind that ->fsync() is not called with i_mutex held
anymore, so if you require i_mutex locking you must make sure to take it and
release it yourself.
---
-[mandatory]
- d_alloc_root() is gone, along with a lot of bugs caused by code
+---
+
+**mandatory**
+
+d_alloc_root() is gone, along with a lot of bugs caused by code
misusing it. Replacement: d_make_root(inode). On success d_make_root(inode)
allocates and returns a new dentry instantiated with the passed in inode.
On failure NULL is returned and the passed in inode is dropped so the reference
to inode is consumed in all cases and failure handling need not do any cleanup
for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL
-and also requires no further error handling. Typical usage is:
+and also requires no further error handling. Typical usage is::
inode = foofs_new_inode(....);
s->s_root = d_make_root(inode);
@@ -442,245 +498,355 @@ and also requires no further error handling. Typical usage is:
return -ENOMEM;
...
---
-[mandatory]
- The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
+---
+
+**mandatory**
+
+The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and
->lookup() do *not* take struct nameidata anymore; just the flags.
---
-[mandatory]
- ->create() doesn't take struct nameidata *; unlike the previous
+
+---
+
+**mandatory**
+
+->create() doesn't take ``struct nameidata *``; unlike the previous
two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that
local filesystems can ignore tha argument - they are guaranteed that the
object doesn't exist. It's remote/distributed ones that might care...
---
-[mandatory]
- FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
+
+---
+
+**mandatory**
+
+FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
in your dentry operations instead.
---
-[mandatory]
- vfs_readdir() is gone; switch to iterate_dir() instead
---
-[mandatory]
- ->readdir() is gone now; switch to ->iterate()
-[mandatory]
- vfs_follow_link has been removed. Filesystems must use nd_set_link
- from ->follow_link for normal symlinks, or nd_jump_link for magic
- /proc/<pid> style links.
---
-[mandatory]
- iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
- called with both ->i_lock and inode_hash_lock held; the former is *not*
- taken anymore, so verify that your callbacks do not rely on it (none
- of the in-tree instances did). inode_hash_lock is still held,
- of course, so they are still serialized wrt removal from inode hash,
- as well as wrt set() callback of iget5_locked().
---
-[mandatory]
- d_materialise_unique() is gone; d_splice_alias() does everything you
- need now. Remember that they have opposite orders of arguments ;-/
---
-[mandatory]
- f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
- it entirely.
---
-[mandatory]
- never call ->read() and ->write() directly; use __vfs_{read,write} or
- wrappers; instead of checking for ->write or ->read being NULL, look for
- FMODE_CAN_{WRITE,READ} in file->f_mode.
---
-[mandatory]
- do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
- instead.
---
-[mandatory]
+
+---
+
+**mandatory**
+
+vfs_readdir() is gone; switch to iterate_dir() instead
+
+---
+
+**mandatory**
+
+->readdir() is gone now; switch to ->iterate()
+
+**mandatory**
+
+vfs_follow_link has been removed. Filesystems must use nd_set_link
+from ->follow_link for normal symlinks, or nd_jump_link for magic
+/proc/<pid> style links.
+
+---
+
+**mandatory**
+
+iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
+called with both ->i_lock and inode_hash_lock held; the former is *not*
+taken anymore, so verify that your callbacks do not rely on it (none
+of the in-tree instances did). inode_hash_lock is still held,
+of course, so they are still serialized wrt removal from inode hash,
+as well as wrt set() callback of iget5_locked().
+
+---
+
+**mandatory**
+
+d_materialise_unique() is gone; d_splice_alias() does everything you
+need now. Remember that they have opposite orders of arguments ;-/
+
+---
+
+**mandatory**
+
+f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
+it entirely.
+
+---
+
+**mandatory**
+
+never call ->read() and ->write() directly; use __vfs_{read,write} or
+wrappers; instead of checking for ->write or ->read being NULL, look for
+FMODE_CAN_{WRITE,READ} in file->f_mode.
+
+---
+
+**mandatory**
+
+do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
+instead.
+
+---
+
+**mandatory**
->aio_read/->aio_write are gone. Use ->read_iter/->write_iter.
+
+---
+
+**recommended**
+
+for embedded ("fast") symlinks just set inode->i_link to wherever the
+symlink body is and use simple_follow_link() as ->follow_link().
+
+---
+
+**mandatory**
+
+calling conventions for ->follow_link() have changed. Instead of returning
+cookie and using nd_set_link() to store the body to traverse, we return
+the body to traverse and store the cookie using explicit void ** argument.
+nameidata isn't passed at all - nd_jump_link() doesn't need it and
+nd_[gs]et_link() is gone.
+
+---
+
+**mandatory**
+
+calling conventions for ->put_link() have changed. It gets inode instead of
+dentry, it does not get nameidata at all and it gets called only when cookie
+is non-NULL. Note that link body isn't available anymore, so if you need it,
+store it as cookie.
+
+---
+
+**mandatory**
+
+any symlink that might use page_follow_link_light/page_put_link() must
+have inode_nohighmem(inode) called before anything might start playing with
+its pagecache. No highmem pages should end up in the pagecache of such
+symlinks. That includes any preseeding that might be done during symlink
+creation. __page_symlink() will honour the mapping gfp flags, so once
+you've done inode_nohighmem() it's safe to use, but if you allocate and
+insert the page manually, make sure to use the right gfp flags.
+
+---
+
+**mandatory**
+
+->follow_link() is replaced with ->get_link(); same API, except that
+
+ * ->get_link() gets inode as a separate argument
+ * ->get_link() may be called in RCU mode - in that case NULL
+ dentry is passed
+
+---
+
+**mandatory**
+
+->get_link() gets struct delayed_call ``*done`` now, and should do
+set_delayed_call() where it used to set ``*cookie``.
+
+->put_link() is gone - just give the destructor to set_delayed_call()
+in ->get_link().
+
+---
+
+**mandatory**
+
+->getxattr() and xattr_handler.get() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode.
+
+---
+
+**mandatory**
+
+symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
+i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
+assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
+it's a symlink. Checking ->i_mode is really needed now. In-tree we had
+to fix shmem_destroy_callback() that used to take that kind of shortcut;
+watch out, since that shortcut is no longer valid.
+
+---
+
+**mandatory**
+
+->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
+they used to - they just take it exclusive. However, ->lookup() may be
+called with parent locked shared. Its instances must not
+
+ * use d_instantiate) and d_rehash() separately - use d_add() or
+ d_splice_alias() instead.
+ * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
+ * in the unlikely case when (read-only) access to filesystem
+ data structures needs exclusion for some reason, arrange it
+ yourself. None of the in-tree filesystems needed that.
+ * rely on ->d_parent and ->d_name not changing after dentry has
+ been fed to d_add() or d_splice_alias(). Again, none of the
+ in-tree instances relied upon that.
+
+We are guaranteed that lookups of the same name in the same directory
+will not happen in parallel ("same" in the sense of your ->d_compare()).
+Lookups on different names in the same directory can and do happen in
+parallel now.
+
---
-[recommended]
- for embedded ("fast") symlinks just set inode->i_link to wherever the
- symlink body is and use simple_follow_link() as ->follow_link().
---
-[mandatory]
- calling conventions for ->follow_link() have changed. Instead of returning
- cookie and using nd_set_link() to store the body to traverse, we return
- the body to traverse and store the cookie using explicit void ** argument.
- nameidata isn't passed at all - nd_jump_link() doesn't need it and
- nd_[gs]et_link() is gone.
---
-[mandatory]
- calling conventions for ->put_link() have changed. It gets inode instead of
- dentry, it does not get nameidata at all and it gets called only when cookie
- is non-NULL. Note that link body isn't available anymore, so if you need it,
- store it as cookie.
---
-[mandatory]
- any symlink that might use page_follow_link_light/page_put_link() must
- have inode_nohighmem(inode) called before anything might start playing with
- its pagecache. No highmem pages should end up in the pagecache of such
- symlinks. That includes any preseeding that might be done during symlink
- creation. __page_symlink() will honour the mapping gfp flags, so once
- you've done inode_nohighmem() it's safe to use, but if you allocate and
- insert the page manually, make sure to use the right gfp flags.
---
-[mandatory]
- ->follow_link() is replaced with ->get_link(); same API, except that
- * ->get_link() gets inode as a separate argument
- * ->get_link() may be called in RCU mode - in that case NULL
- dentry is passed
---
-[mandatory]
- ->get_link() gets struct delayed_call *done now, and should do
- set_delayed_call() where it used to set *cookie.
- ->put_link() is gone - just give the destructor to set_delayed_call()
- in ->get_link().
---
-[mandatory]
- ->getxattr() and xattr_handler.get() get dentry and inode passed separately.
- dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
- in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
- called before we attach dentry to inode.
---
-[mandatory]
- symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
- i_pipe/i_link union zeroed out at inode eviction. As the result, you can't
- assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
- it's a symlink. Checking ->i_mode is really needed now. In-tree we had
- to fix shmem_destroy_callback() that used to take that kind of shortcut;
- watch out, since that shortcut is no longer valid.
---
-[mandatory]
- ->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as
- they used to - they just take it exclusive. However, ->lookup() may be
- called with parent locked shared. Its instances must not
- * use d_instantiate) and d_rehash() separately - use d_add() or
- d_splice_alias() instead.
- * use d_rehash() alone - call d_add(new_dentry, NULL) instead.
- * in the unlikely case when (read-only) access to filesystem
- data structures needs exclusion for some reason, arrange it
- yourself. None of the in-tree filesystems needed that.
- * rely on ->d_parent and ->d_name not changing after dentry has
- been fed to d_add() or d_splice_alias(). Again, none of the
- in-tree instances relied upon that.
- We are guaranteed that lookups of the same name in the same directory
- will not happen in parallel ("same" in the sense of your ->d_compare()).
- Lookups on different names in the same directory can and do happen in
- parallel now.
---
-[recommended]
- ->iterate_shared() is added; it's a parallel variant of ->iterate().
- Exclusion on struct file level is still provided (as well as that
- between it and lseek on the same struct file), but if your directory
- has been opened several times, you can get these called in parallel.
- Exclusion between that method and all directory-modifying ones is
- still provided, of course.
-
- Often enough ->iterate() can serve as ->iterate_shared() without any
- changes - it is a read-only operation, after all. If you have any
- per-inode or per-dentry in-core data structures modified by ->iterate(),
- you might need something to serialize the access to them. If you
- do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
- that; look for in-tree examples.
-
- Old method is only used if the new one is absent; eventually it will
- be removed. Switch while you still can; the old one won't stay.
---
-[mandatory]
- ->atomic_open() calls without O_CREAT may happen in parallel.
---
-[mandatory]
- ->setxattr() and xattr_handler.set() get dentry and inode passed separately.
- dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
- in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
- called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
- ->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
---
-[mandatory]
- ->d_compare() doesn't get parent as a separate argument anymore. If you
- used it for finding the struct super_block involved, dentry->d_sb will
- work just as well; if it's something more complicated, use dentry->d_parent.
- Just be careful not to assume that fetching it more than once will yield
- the same value - in RCU mode it could change under you.
---
-[mandatory]
- ->rename() has an added flags argument. Any flags not handled by the
- filesystem should result in EINVAL being returned.
---
-[recommended]
- ->readlink is optional for symlinks. Don't set, unless filesystem needs
- to fake something for readlink(2).
---
-[mandatory]
- ->getattr() is now passed a struct path rather than a vfsmount and
- dentry separately, and it now has request_mask and query_flags arguments
- to specify the fields and sync type requested by statx. Filesystems not
- supporting any statx-specific features may ignore the new arguments.
---
-[mandatory]
- ->atomic_open() calling conventions have changed. Gone is int *opened,
- along with FILE_OPENED/FILE_CREATED. In place of those we have
- FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
- value for 'called finish_no_open(), open it yourself' case has become
- 0, not 1. Since finish_no_open() itself is returning 0 now, that part
- does not need any changes in ->atomic_open() instances.
---
-[mandatory]
- alloc_file() has become static now; two wrappers are to be used instead.
- alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
- when dentry needs to be created; that's the majority of old alloc_file()
- users. Calling conventions: on success a reference to new struct file
- is returned and callers reference to inode is subsumed by that. On
- failure, ERR_PTR() is returned and no caller's references are affected,
- so the caller needs to drop the inode reference it held.
- alloc_file_clone(file, flags, ops) does not affect any caller's references.
- On success you get a new struct file sharing the mount/dentry with the
- original, on failure - ERR_PTR().
---
-[mandatory]
- ->clone_file_range() and ->dedupe_file_range have been replaced with
- ->remap_file_range(). See Documentation/filesystems/vfs.rst for more
- information.
---
-[recommended]
- ->lookup() instances doing an equivalent of
- if (IS_ERR(inode))
- return ERR_CAST(inode);
- return d_splice_alias(inode, dentry);
- don't need to bother with the check - d_splice_alias() will do the
- right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
- inode to d_splice_alias() will also do the right thing (equivalent of
- d_add(dentry, NULL); return NULL;), so that kind of special cases
- also doesn't need a separate treatment.
---
-[strongly recommended]
- take the RCU-delayed parts of ->destroy_inode() into a new method -
- ->free_inode(). If ->destroy_inode() becomes empty - all the better,
- just get rid of it. Synchronous work (e.g. the stuff that can't
- be done from an RCU callback, or any WARN_ON() where we want the
- stack trace) *might* be movable to ->evict_inode(); however,
- that goes only for the things that are not needed to balance something
- done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
- might have accumulated over the life of in-core inode, ->evict_inode()
- might be a fit.
-
- Rules for inode destruction:
- * if ->destroy_inode() is non-NULL, it gets called
- * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
- * combination of NULL ->destroy_inode and NULL ->free_inode is
- treated as NULL/free_inode_nonrcu, to preserve the compatibility.
-
- Note that the callback (be it via ->free_inode() or explicit call_rcu()
- in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
- as the matter of fact, the superblock and all associated structures
- might be already gone. The filesystem driver is guaranteed to be still
- there, but that's it. Freeing memory in the callback is fine; doing
- more than that is possible, but requires a lot of care and is best
- avoided.
---
-[mandatory]
- DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
- default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
- business doing so.
---
-[mandatory]
- d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
- very suspect (and won't work in modules). Such uses are very likely to
- be misspelled d_alloc_anon().
+
+**recommended**
+
+->iterate_shared() is added; it's a parallel variant of ->iterate().
+Exclusion on struct file level is still provided (as well as that
+between it and lseek on the same struct file), but if your directory
+has been opened several times, you can get these called in parallel.
+Exclusion between that method and all directory-modifying ones is
+still provided, of course.
+
+Often enough ->iterate() can serve as ->iterate_shared() without any
+changes - it is a read-only operation, after all. If you have any
+per-inode or per-dentry in-core data structures modified by ->iterate(),
+you might need something to serialize the access to them. If you
+do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
+that; look for in-tree examples.
+
+Old method is only used if the new one is absent; eventually it will
+be removed. Switch while you still can; the old one won't stay.
+
+---
+
+**mandatory**
+
+->atomic_open() calls without O_CREAT may happen in parallel.
+
+---
+
+**mandatory**
+
+->setxattr() and xattr_handler.set() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances. Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
+->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
+
+---
+
+**mandatory**
+
+->d_compare() doesn't get parent as a separate argument anymore. If you
+used it for finding the struct super_block involved, dentry->d_sb will
+work just as well; if it's something more complicated, use dentry->d_parent.
+Just be careful not to assume that fetching it more than once will yield
+the same value - in RCU mode it could change under you.
+
+---
+
+**mandatory**
+
+->rename() has an added flags argument. Any flags not handled by the
+filesystem should result in EINVAL being returned.
+
+---
+
+
+**recommended**
+
+->readlink is optional for symlinks. Don't set, unless filesystem needs
+to fake something for readlink(2).
+
+---
+
+**mandatory**
+
+->getattr() is now passed a struct path rather than a vfsmount and
+dentry separately, and it now has request_mask and query_flags arguments
+to specify the fields and sync type requested by statx. Filesystems not
+supporting any statx-specific features may ignore the new arguments.
+
+---
+
+**mandatory**
+
+->atomic_open() calling conventions have changed. Gone is ``int *opened``,
+along with FILE_OPENED/FILE_CREATED. In place of those we have
+FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return
+value for 'called finish_no_open(), open it yourself' case has become
+0, not 1. Since finish_no_open() itself is returning 0 now, that part
+does not need any changes in ->atomic_open() instances.
+
+---
+
+**mandatory**
+
+alloc_file() has become static now; two wrappers are to be used instead.
+alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
+when dentry needs to be created; that's the majority of old alloc_file()
+users. Calling conventions: on success a reference to new struct file
+is returned and callers reference to inode is subsumed by that. On
+failure, ERR_PTR() is returned and no caller's references are affected,
+so the caller needs to drop the inode reference it held.
+alloc_file_clone(file, flags, ops) does not affect any caller's references.
+On success you get a new struct file sharing the mount/dentry with the
+original, on failure - ERR_PTR().
+
+---
+
+**mandatory**
+
+->clone_file_range() and ->dedupe_file_range have been replaced with
+->remap_file_range(). See Documentation/filesystems/vfs.rst for more
+information.
+
+---
+
+**recommended**
+
+->lookup() instances doing an equivalent of::
+
+ if (IS_ERR(inode))
+ return ERR_CAST(inode);
+ return d_splice_alias(inode, dentry);
+
+don't need to bother with the check - d_splice_alias() will do the
+right thing when given ERR_PTR(...) as inode. Moreover, passing NULL
+inode to d_splice_alias() will also do the right thing (equivalent of
+d_add(dentry, NULL); return NULL;), so that kind of special cases
+also doesn't need a separate treatment.
+
+---
+
+**strongly recommended**
+
+take the RCU-delayed parts of ->destroy_inode() into a new method -
+->free_inode(). If ->destroy_inode() becomes empty - all the better,
+just get rid of it. Synchronous work (e.g. the stuff that can't
+be done from an RCU callback, or any WARN_ON() where we want the
+stack trace) *might* be movable to ->evict_inode(); however,
+that goes only for the things that are not needed to balance something
+done by ->alloc_inode(). IOW, if it's cleaning up the stuff that
+might have accumulated over the life of in-core inode, ->evict_inode()
+might be a fit.
+
+Rules for inode destruction:
+
+ * if ->destroy_inode() is non-NULL, it gets called
+ * if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
+ * combination of NULL ->destroy_inode and NULL ->free_inode is
+ treated as NULL/free_inode_nonrcu, to preserve the compatibility.
+
+Note that the callback (be it via ->free_inode() or explicit call_rcu()
+in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
+as the matter of fact, the superblock and all associated structures
+might be already gone. The filesystem driver is guaranteed to be still
+there, but that's it. Freeing memory in the callback is fine; doing
+more than that is possible, but requires a lot of care and is best
+avoided.
+
+---
+
+**mandatory**
+
+DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
+default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
+business doing so.
+
+---
+
+**mandatory**
+
+d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
+very suspect (and won't work in modules). Such uses are very likely to
+be misspelled d_alloc_anon().
diff --git a/fs/orangefs/orangefs-kernel.h b/fs/orangefs/orangefs-kernel.h
index 572dd29fbd54..34a6c99fa29b 100644
--- a/fs/orangefs/orangefs-kernel.h
+++ b/fs/orangefs/orangefs-kernel.h
@@ -246,7 +246,7 @@ struct orangefs_read_options {
extern struct orangefs_stats orangefs_stats;
/*
- * NOTE: See Documentation/filesystems/porting for information
+ * NOTE: See Documentation/filesystems/porting.rst for information
* on implementing FOO_I and properly accessing fs private data
*/
static inline struct orangefs_inode_s *ORANGEFS_I(struct inode *inode)
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 19/26] docs: index.rst: don't use genindex for pdf output
2019-07-26 12:51 ` Mauro Carvalho Chehab
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vinod Koul, Sanyog Kale,
Pierre-Louis Bossart, David S. Miller, Jaroslav Kysela,
Takashi Iwai, linux-doc, dmaengine, alsa-devel, netdev
The genindex logic is meant to be used only for html output, as
pdf build has its own way to generate indexes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Vinod Koul <vkoul@kernel.org> # dmaengine and soundwire
---
Documentation/core-api/index.rst | 2 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
Documentation/networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
Documentation/sound/index.rst | 2 +-
6 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index dfd8fad1e1ec..fa16a0538dcb 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -49,7 +49,7 @@ Interfaces for kernel debugging
debug-objects
tracepoint
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index 3026fa975937..b9df904d0a79 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -47,7 +47,7 @@ This book adds some notes about PXA DMA
pxa_dma
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index 6db026028f27..234911a0db99 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -10,7 +10,7 @@ SoundWire Documentation
error_handling
locking
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index 2b7fefe72351..f724b7c69b9e 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -24,7 +24,7 @@ Contents:
google/gve
mellanox/mlx5
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a46fca264bee..6739066acadb 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -31,7 +31,7 @@ Contents:
tls
tls-offload
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 47b89f014e69..4d7d42acf6df 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation
hd-audio/index
cards/index
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 19/26] docs: index.rst: don't use genindex for pdf output
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vinod Koul, Sanyog Kale,
Pierre-Louis Bossart, David S. Miller, Jaroslav Kysela,
Takashi Iwai, linux-doc, dmaengine, alsa-devel, netdev
The genindex logic is meant to be used only for html output, as
pdf build has its own way to generate indexes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Vinod Koul <vkoul@kernel.org> # dmaengine and soundwire
---
Documentation/core-api/index.rst | 2 +-
Documentation/driver-api/dmaengine/index.rst | 2 +-
Documentation/driver-api/soundwire/index.rst | 2 +-
Documentation/networking/device_drivers/index.rst | 2 +-
Documentation/networking/index.rst | 2 +-
Documentation/sound/index.rst | 2 +-
6 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index dfd8fad1e1ec..fa16a0538dcb 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -49,7 +49,7 @@ Interfaces for kernel debugging
debug-objects
tracepoint
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index 3026fa975937..b9df904d0a79 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -47,7 +47,7 @@ This book adds some notes about PXA DMA
pxa_dma
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index 6db026028f27..234911a0db99 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -10,7 +10,7 @@ SoundWire Documentation
error_handling
locking
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index 2b7fefe72351..f724b7c69b9e 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -24,7 +24,7 @@ Contents:
google/gve
mellanox/mlx5
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a46fca264bee..6739066acadb 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -31,7 +31,7 @@ Contents:
tls
tls-offload
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 47b89f014e69..4d7d42acf6df 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation
hd-audio/index
cards/index
-.. only:: subproject
+.. only:: subproject and html
Indices
=======
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 20/26] docs: wimax: convert to ReST and add to admin-guide
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (23 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Inaky Perez-Gonzalez,
linux-wimax, linux-doc
Manually convert wimax documentation to ReST and add theit
to the Kernel doc body, inside the admin-guide.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/admin-guide/index.rst | 1 +
.../wimax/i2400m.rst} | 145 ++++++++++--------
Documentation/admin-guide/wimax/index.rst | 19 +++
.../wimax/wimax.rst} | 36 +++--
MAINTAINERS | 4 +-
5 files changed, 128 insertions(+), 77 deletions(-)
rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
create mode 100644 Documentation/admin-guide/wimax/index.rst
rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 6e6c23b6193a..083b7cc80ee4 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -107,6 +107,7 @@ configure specific aspects of kernel behavior to your liking.
pnp
rtc
svga
+ wimax/index
video-output
.. only:: subproject and html
diff --git a/Documentation/wimax/README.i2400m b/Documentation/admin-guide/wimax/i2400m.rst
similarity index 69%
rename from Documentation/wimax/README.i2400m
rename to Documentation/admin-guide/wimax/i2400m.rst
index 7dffd8919cb0..194388c0c351 100644
--- a/Documentation/wimax/README.i2400m
+++ b/Documentation/admin-guide/wimax/i2400m.rst
@@ -1,18 +1,23 @@
+.. include:: <isonum.txt>
- Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
+Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
- (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
This provides a driver for the Intel Wireless WiMAX Connection 2400m
and a basic Linux kernel WiMAX stack.
1. Requirements
+===============
* Linux installation with Linux kernel 2.6.22 or newer (if building
from a separate tree)
* Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
Wireless WiMAX/WiFi Link 5x50 series.
* build tools:
+
+ Linux kernel development package for the target kernel; to
build against your currently running kernel, you need to have
the kernel development package corresponding to the running
@@ -22,8 +27,10 @@
+ GNU C Compiler, make
2. Compilation and installation
+===============================
2.1. Compilation of the drivers included in the kernel
+------------------------------------------------------
Configure the kernel; to enable the WiMAX drivers select Drivers >
Networking Drivers > WiMAX device support. Enable all of them as
@@ -36,37 +43,39 @@
Compile and install your kernel as usual.
2.2. Compilation of the drivers distributed as an standalone module
+-------------------------------------------------------------------
- To compile
+ To compile::
-$ cd source/directory
-$ make
+ $ cd source/directory
+ $ make
Once built you can load and unload using the provided load.sh script;
load.sh will load the modules, load.sh u will unload them.
To install in the default kernel directories (and enable auto loading
- when the device is plugged):
+ when the device is plugged)::
-$ make install
-$ depmod -a
+ $ make install
+ $ depmod -a
If your kernel development files are located in a non standard
directory or if you want to build for a kernel that is not the
- currently running one, set KDIR to the right location:
+ currently running one, set KDIR to the right location::
-$ make KDIR=/path/to/kernel/dev/tree
+ $ make KDIR=/path/to/kernel/dev/tree
For more information, please contact linux-wimax@intel.com.
3. Installing the firmware
+--------------------------
The firmware can be obtained from http://linuxwimax.org or might have
been supplied with your hardware.
- It has to be installed in the target system:
- *
-$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
+ It has to be installed in the target system::
+
+ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
* NOTE: if your firmware came in an .rpm or .deb file, just install
it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
@@ -76,6 +85,7 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
with other types.
4. Design
+=========
This package contains two major parts: a WiMAX kernel stack and a
driver for the Intel i2400m.
@@ -102,16 +112,17 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
API calls should be replaced with the target OS's.
5. Usage
+========
To load the driver, follow the instructions in the install section;
once the driver is loaded, plug in the device (unless it is permanently
plugged in). The driver will enumerate the device, upload the firmware
and output messages in the kernel log (dmesg, /var/log/messages or
- /var/log/kern.log) such as:
+ /var/log/kern.log) such as::
-...
-i2400m_usb 5-4:1.0: firmware interface version 8.0.0
-i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
+ ...
+ i2400m_usb 5-4:1.0: firmware interface version 8.0.0
+ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
At this point the device is ready to work.
@@ -120,38 +131,42 @@ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
on how to scan, connect and disconnect.
5.1. Module parameters
+----------------------
Module parameters can be set at kernel or module load time or by
- echoing values:
+ echoing values::
-$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
+ $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
To make changes permanent, for example, for the i2400m module, you can
- also create a file named /etc/modprobe.d/i2400m containing:
+ also create a file named /etc/modprobe.d/i2400m containing::
-options i2400m idle_mode_disabled=1
+ options i2400m idle_mode_disabled=1
- To find which parameters are supported by a module, run:
+ To find which parameters are supported by a module, run::
-$ modinfo path/to/module.ko
+ $ modinfo path/to/module.ko
During kernel bootup (if the driver is linked in the kernel), specify
- the following to the kernel command line:
+ the following to the kernel command line::
-i2400m.PARAMETER=VALUE
+ i2400m.PARAMETER=VALUE
5.1.1. i2400m: idle_mode_disabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The i2400m module supports a parameter to disable idle mode. This
parameter, once set, will take effect only when the device is
reinitialized by the driver (eg: following a reset or a reconnect).
5.2. Debug operations: debugfs entries
+--------------------------------------
The driver will register debugfs entries that allow the user to tweak
debug settings. There are three main container directories where
entries are placed, which correspond to the three blocks a i2400m WiMAX
driver has:
+
* /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
controls
* /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
@@ -163,52 +178,55 @@ i2400m.PARAMETER=VALUE
/sys/kernel/debug, those paths will change.
5.2.1. Increasing debug output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The files named *dl_* indicate knobs for controlling the debug output
- of different submodules:
- *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+ of different submodules::
+
+ # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
+ /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
+ /sys/kernel/debug/wimax:wmx0/i2400m/dl_control
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
By reading the file you can obtain the current value of said debug
level; by writing to it, you can set it.
To increase the debug level of, for example, the i2400m's generic TX
- engine, just write:
+ engine, just write::
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+ $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
Increasing numbers yield increasing debug information; for details of
what is printed and the available levels, check the source. The code
uses 0 for disabled and increasing values until 8.
5.2.2. RX and TX statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
- data reception/delivery from the device:
+ data reception/delivery from the device::
-$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
-45 1 3 34 3104 48 480
+ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
+ 45 1 3 34 3104 48 480
+
+ The numbers reported are:
- The numbers reported are
* packets/RX-buffer: total, min, max
* RX-buffers: total RX buffers received, accumulated RX buffer size
in bytes, min size received, max size received
@@ -216,9 +234,9 @@ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
Thus, to find the average buffer size received, divide accumulated
RX-buffer / total RX-buffers.
- To clear the statistics back to 0, write anything to the rx_stats file:
+ To clear the statistics back to 0, write anything to the rx_stats file::
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
+ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
Likewise for TX.
@@ -227,14 +245,16 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
to the host. See drivers/net/wimax/i2400m/tx.c.
5.2.3. Tracing messages received from user space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To echo messages received from user space into the trace pipe that the
i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
- 1:
- *
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
+ 1::
+
+ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
5.2.4. Performing a device reset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By writing a 0, a 1 or a 2 to the file
/sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
@@ -242,18 +262,21 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
(bus specific) reset on the device.
5.2.5. Asking the device to enter power saving mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
device will attempt to enter power saving mode.
6. Troubleshooting
+==================
-6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed'
+6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
+----------------------------------------------------------------------
If upon connecting the device, the following is output in the kernel
- log:
+ log::
-i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
+ i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
This means that the driver cannot locate the firmware file named
/lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
diff --git a/Documentation/admin-guide/wimax/index.rst b/Documentation/admin-guide/wimax/index.rst
new file mode 100644
index 000000000000..fdf7c1f99ff5
--- /dev/null
+++ b/Documentation/admin-guide/wimax/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+WiMAX subsystem
+===============
+
+.. toctree::
+ :maxdepth: 2
+
+ wimax
+
+ i2400m
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/wimax/README.wimax b/Documentation/admin-guide/wimax/wimax.rst
similarity index 74%
rename from Documentation/wimax/README.wimax
rename to Documentation/admin-guide/wimax/wimax.rst
index b78c4378084e..817ee8ba2732 100644
--- a/Documentation/wimax/README.wimax
+++ b/Documentation/admin-guide/wimax/wimax.rst
@@ -1,12 +1,16 @@
+.. include:: <isonum.txt>
- Linux kernel WiMAX stack
+========================
+Linux kernel WiMAX stack
+========================
- (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
This provides a basic Linux kernel WiMAX stack to provide a common
control API for WiMAX devices, usable from kernel and user space.
1. Design
+=========
The WiMAX stack is designed to provide for common WiMAX control
services to current and future WiMAX devices from any vendor.
@@ -31,6 +35,7 @@
include/linux/wimax.h.
2. Usage
+========
For usage in a driver (registration, API, etc) please refer to the
instructions in the header file include/linux/wimax.h.
@@ -40,6 +45,7 @@
control.
2.1. Obtaining debug information: debugfs entries
+-------------------------------------------------
The WiMAX stack is compiled, by default, with debug messages that can
be used to diagnose issues. By default, said messages are disabled.
@@ -52,20 +58,22 @@
create more subentries below it.
2.1.1. Increasing debug output
+------------------------------
The files named *dl_* indicate knobs for controlling the debug output
- of different submodules of the WiMAX stack:
- *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
-/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+ of different submodules of the WiMAX stack::
- NOTE: Of course, if debugfs is mounted in a directory other than
+ # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+ /sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+
+ NOTE:
+ Of course, if debugfs is mounted in a directory other than
/sys/kernel/debug, those paths will change.
By reading the file you can obtain the current value of said debug
@@ -74,7 +82,7 @@
To increase the debug level of, for example, the id-table submodule,
just write:
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+ $ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
Increasing numbers yield increasing debug information; for details of
what is printed and the available levels, check the source. The code
diff --git a/MAINTAINERS b/MAINTAINERS
index b6b9d8c67987..c7656edee696 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8346,7 +8346,7 @@ M: linux-wimax@intel.com
L: wimax@linuxwimax.org (subscribers-only)
S: Supported
W: http://linuxwimax.org
-F: Documentation/wimax/README.i2400m
+F: Documentation/admin-guide/wimax/i2400m.rst
F: drivers/net/wimax/i2400m/
F: include/uapi/linux/wimax/i2400m.h
@@ -17349,7 +17349,7 @@ M: linux-wimax@intel.com
L: wimax@linuxwimax.org (subscribers-only)
S: Supported
W: http://linuxwimax.org
-F: Documentation/wimax/README.wimax
+F: Documentation/admin-guide/wimax/wimax.rst
F: include/linux/wimax/debug.h
F: include/net/wimax.h
F: include/uapi/linux/wimax.h
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 21/26] docs: mips: add to the documentation body as ReST
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (24 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Ralf Baechle,
Paul Burton, James Hogan, linux-doc, linux-mips
Manually convert the AU1xxx_IDE.README file to ReST and add
to a MIPS book as part of the main documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Paul Burton <paul.burton@mips.com>
---
Documentation/index.rst | 1 +
.../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +++++++++++--------
Documentation/mips/index.rst | 17 ++++
3 files changed, 70 insertions(+), 37 deletions(-)
rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
create mode 100644 Documentation/mips/index.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
index de7be1c31450..1ff03833276a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -149,6 +149,7 @@ implementation.
ia64/index
m68k/index
powerpc/index
+ mips/index
openrisc/index
parisc/index
riscv/index
diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/au1xxx_ide.rst
similarity index 67%
rename from Documentation/mips/AU1xxx_IDE.README
rename to Documentation/mips/au1xxx_ide.rst
index ff675a1b1422..2f9c2cff6738 100644
--- a/Documentation/mips/AU1xxx_IDE.README
+++ b/Documentation/mips/au1xxx_ide.rst
@@ -1,7 +1,14 @@
-README for MIPS AU1XXX IDE driver - Released 2005-07-15
+.. include:: <isonum.txt>
+
+======================
+MIPS AU1XXX IDE driver
+======================
+
+Released 2005-07-15
+
+About
+=====
-ABOUT
------
This file describes the 'drivers/ide/au1xxx-ide.c', related files and the
services they provide.
@@ -10,17 +17,17 @@ the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST'
section.
-LICENSE
--------
+License
+=======
-Copyright (c) 2003-2005 AMD, Personal Connectivity Solutions
+:Copyright: |copy| 2003-2005 AMD, Personal Connectivity Solutions
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 SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
@@ -35,31 +42,35 @@ 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.
-Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
+Note:
+ for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
Interface and Linux Device Driver" Application Note.
-FILES, CONFIGS AND COMPATIBILITY
---------------------------------
+Files, Configs and Compatibility
+================================
Two files are introduced:
a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h'
contains : struct _auide_hwif
- timing parameters for PIO mode 0/1/2/3/4
- timing parameters for MWDMA 0/1/2
+
+ - timing parameters for PIO mode 0/1/2/3/4
+ - timing parameters for MWDMA 0/1/2
b) 'drivers/ide/mips/au1xxx-ide.c'
contains the functionality of the AU1XXX IDE driver
Following extra configs variables are introduced:
- CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA - enable the PIO+DBDMA mode
- CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA - enable the MWDMA mode
+ CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA
+ - enable the PIO+DBDMA mode
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA
+ - enable the MWDMA mode
-SUPPORTED IDE MODES
--------------------
+Supported IDE Modes
+===================
The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all
MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode.
@@ -69,20 +80,21 @@ To change the PIO mode use the program hdparm with option -p, e.g.
-X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0.
-PERFORMANCE CONFIGURATIONS
---------------------------
+Performance Configurations
+==========================
-If the used system doesn't need USB support enable the following kernel configs:
+If the used system doesn't need USB support enable the following kernel
+configs::
-CONFIG_IDE=y
-CONFIG_BLK_DEV_IDE=y
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+ CONFIG_IDE=y
+ CONFIG_BLK_DEV_IDE=y
+ CONFIG_IDE_GENERIC=y
+ CONFIG_BLK_DEV_IDEPCI=y
+ CONFIG_BLK_DEV_GENERIC=y
+ CONFIG_BLK_DEV_IDEDMA_PCI=y
+ CONFIG_BLK_DEV_IDE_AU1XXX=y
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+ CONFIG_BLK_DEV_IDEDMA=y
Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable
the burst support on DBDMA controller.
@@ -90,20 +102,22 @@ the burst support on DBDMA controller.
If the used system need the USB support enable the following kernel configs for
high IDE to USB throughput.
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+::
+
+ CONFIG_IDE_GENERIC=y
+ CONFIG_BLK_DEV_IDEPCI=y
+ CONFIG_BLK_DEV_GENERIC=y
+ CONFIG_BLK_DEV_IDEDMA_PCI=y
+ CONFIG_BLK_DEV_IDE_AU1XXX=y
+ CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+ CONFIG_BLK_DEV_IDEDMA=y
Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to
disable the burst support on DBDMA controller.
-ACKNOWLEDGMENTS
----------------
+Acknowledgments
+===============
These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX
IDE driver from AMD.
@@ -112,4 +126,5 @@ Additional input also from:
Matthias Lenk <matthias.lenk@amd.com>
Happy hacking!
+
Enrico Walther <enrico.walther@amd.com>
diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst
new file mode 100644
index 000000000000..fd9023c8a89f
--- /dev/null
+++ b/Documentation/mips/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+MIPS architecture
+=================
+
+.. toctree::
+ :maxdepth: 2
+
+ au1xxx_ide
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 22/26] docs: hwmon: pxe1610: convert to ReST format and add to the index
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (25 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jean Delvare, Guenter Roeck,
Jonathan Corbet, linux-hwmon, linux-doc
This document was recently introduced. Convert it to ReST
just like the other hwmon documents, adding it to the hwmon index.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/hwmon/index.rst | 1 +
Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +++++++++++++++-----
2 files changed, 26 insertions(+), 8 deletions(-)
rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index ee090e51653a..4d5f5fec43a3 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -130,6 +130,7 @@ Hardware Monitoring Kernel Drivers
pcf8591
pmbus
powr1220
+ pxe1610
pwm-fan
raspberrypi-hwmon
sch5627
diff --git a/Documentation/hwmon/pxe1610 b/Documentation/hwmon/pxe1610.rst
similarity index 82%
rename from Documentation/hwmon/pxe1610
rename to Documentation/hwmon/pxe1610.rst
index 211cedeefb44..4f2388840d06 100644
--- a/Documentation/hwmon/pxe1610
+++ b/Documentation/hwmon/pxe1610.rst
@@ -2,19 +2,29 @@ Kernel driver pxe1610
=====================
Supported chips:
+
* Infineon PXE1610
+
Prefix: 'pxe1610'
+
Addresses scanned: -
+
Datasheet: Datasheet is not publicly available.
* Infineon PXE1110
+
Prefix: 'pxe1110'
+
Addresses scanned: -
+
Datasheet: Datasheet is not publicly available.
* Infineon PXM1310
+
Prefix: 'pxm1310'
+
Addresses scanned: -
+
Datasheet: Datasheet is not publicly available.
Author: Vijay Khemka <vijaykhemka@fb.com>
@@ -25,14 +35,19 @@ Description
PXE1610/PXE1110 are Multi-rail/Multiphase Digital Controllers
and compliant to
- -- Intel VR13 DC-DC converter specifications.
- -- Intel SVID protocol.
+
+ - Intel VR13 DC-DC converter specifications.
+ - Intel SVID protocol.
+
Used for Vcore power regulation for Intel VR13 based microprocessors
- -- Servers, Workstations, and High-end desktops
+
+ - Servers, Workstations, and High-end desktops
PXM1310 is a Multi-rail Controller and it is compliant to
- -- Intel VR13 DC-DC converter specifications.
- -- Intel SVID protocol.
+
+ - Intel VR13 DC-DC converter specifications.
+ - Intel SVID protocol.
+
Used for DDR3/DDR4 Memory power regulation for Intel VR13 and
IMVP8 based systems
@@ -44,10 +59,10 @@ This driver does not probe for PMBus devices. You will have
to instantiate devices explicitly.
Example: the following commands will load the driver for an PXE1610
-at address 0x70 on I2C bus #4:
+at address 0x70 on I2C bus #4::
-# modprobe pxe1610
-# echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
+ # modprobe pxe1610
+ # echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
It can also be instantiated by declaring in device tree
@@ -55,6 +70,7 @@ It can also be instantiated by declaring in device tree
Sysfs attributes
----------------
+====================== ====================================
curr1_label "iin"
curr1_input Measured input current
curr1_alarm Current high alarm
@@ -88,3 +104,4 @@ temp[1-3]_crit Critical high temperature
temp[1-3]_crit_alarm Chip temperature critical high alarm
temp[1-3]_max Maximum temperature
temp[1-3]_max_alarm Chip temperature high alarm
+====================== ====================================
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 23/26] docs: nios2: add it to the main Documentation body
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (26 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc
Rename and add the nios2 documentation to the documentation
body.
The nios2 document is already on an ReST compatible format.
All it needs is that the title of the document to be promoted
one level.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/index.rst | 1 +
Documentation/nios2/{README => nios2.rst} | 1 +
2 files changed, 2 insertions(+)
rename Documentation/nios2/{README => nios2.rst} (96%)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 1ff03833276a..d963db84fc42 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -150,6 +150,7 @@ implementation.
m68k/index
powerpc/index
mips/index
+ nios2/nios2
openrisc/index
parisc/index
riscv/index
diff --git a/Documentation/nios2/README b/Documentation/nios2/nios2.rst
similarity index 96%
rename from Documentation/nios2/README
rename to Documentation/nios2/nios2.rst
index 054a67d55563..43da3f7cee76 100644
--- a/Documentation/nios2/README
+++ b/Documentation/nios2/nios2.rst
@@ -1,3 +1,4 @@
+=================================
Linux on the Nios II architecture
=================================
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH v2 24/26] docs: net: convert two README files to ReST format
2019-07-26 12:51 ` Mauro Carvalho Chehab
` (27 preceding siblings ...)
(?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
Cc: Mauro Carvalho Chehab, David S. Miller, Jonathan Corbet,
Johannes Berg, netdev, linux-doc, linux-wireless
There are two README files there with doesn't have a .txt
extension nor are at ReST format.
In order to help with the docs conversion to ReST, rename those
and manually convert them to ReST format.
As there are lot more to be done for networking to be part of
the documentation body, for now mark those two files with
:orphan:, in order to supress a build warning.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
.../networking/caif/{README => caif.rst} | 88 +++++++++++++------
.../{README => mac80211_hwsim.rst} | 28 ++++--
MAINTAINERS | 2 +-
3 files changed, 81 insertions(+), 37 deletions(-)
rename Documentation/networking/caif/{README => caif.rst} (70%)
rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/caif.rst
similarity index 70%
rename from Documentation/networking/caif/README
rename to Documentation/networking/caif/caif.rst
index 757ccfaa1385..07afc8063d4d 100644
--- a/Documentation/networking/caif/README
+++ b/Documentation/networking/caif/caif.rst
@@ -1,18 +1,31 @@
-Copyright (C) ST-Ericsson AB 2010
-Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
-License terms: GNU General Public License (GPL) version 2
----------------------------------------------------------
+:orphan:
-=== Start ===
-If you have compiled CAIF for modules do:
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
-$modprobe crc_ccitt
-$modprobe caif
-$modprobe caif_socket
-$modprobe chnl_net
+================
+Using Linux CAIF
+================
-=== Preparing the setup with a STE modem ===
+
+:Copyright: |copy| ST-Ericsson AB 2010
+
+:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
+
+Start
+=====
+
+If you have compiled CAIF for modules do::
+
+ $modprobe crc_ccitt
+ $modprobe caif
+ $modprobe caif_socket
+ $modprobe chnl_net
+
+
+Preparing the setup with a STE modem
+====================================
If you are working on integration of CAIF you should make sure
that the kernel is built with module support.
@@ -32,24 +45,30 @@ module parameter "ser_use_stx".
Normally Frame Checksum is always used on UART, but this is also provided as a
module parameter "ser_use_fcs".
-$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
-$ ifconfig caif_ttyS0 up
+::
-PLEASE NOTE: There is a limitation in Android shell.
+ $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+ $ ifconfig caif_ttyS0 up
+
+PLEASE NOTE:
+ There is a limitation in Android shell.
It only accepts one argument to insmod/modprobe!
-=== Trouble shooting ===
+Trouble shooting
+================
There are debugfs parameters provided for serial communication.
/sys/kernel/debug/caif_serial/<tty-name>/
* ser_state: Prints the bit-mask status where
+
- 0x02 means SENDING, this is a transient state.
- 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
- and is blocking further send operation. Flow OFF has been propagated
- to all CAIF Channels using this TTY.
+ and is blocking further send operation. Flow OFF has been propagated
+ to all CAIF Channels using this TTY.
* tty_status: Prints the bit-mask tty status information
+
- 0x01 - tty->warned is on.
- 0x02 - tty->low_latency is on.
- 0x04 - tty->packed is on.
@@ -58,13 +77,17 @@ There are debugfs parameters provided for serial communication.
- 0x20 - tty->stopped is on.
* last_tx_msg: Binary blob Prints the last transmitted frame.
- This can be printed with
+
+ This can be printed with::
+
$od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
- The first two tx messages sent look like this. Note: The initial
- byte 02 is start of frame extension (STX) used for re-syncing
- upon errors.
- - Enumeration:
+ The first two tx messages sent look like this. Note: The initial
+ byte 02 is start of frame extension (STX) used for re-syncing
+ upon errors.
+
+ - Enumeration::
+
0000000 02 05 00 00 03 01 d2 02
| | | | | |
STX(1) | | | |
@@ -73,7 +96,9 @@ There are debugfs parameters provided for serial communication.
Command:Enumeration(1)
Link-ID(1)
Checksum(2)
- - Channel Setup:
+
+ - Channel Setup::
+
0000000 02 07 00 00 00 21 a1 00 48 df
| | | | | | | |
STX(1) | | | | | |
@@ -86,13 +111,18 @@ There are debugfs parameters provided for serial communication.
Checksum(2)
* last_rx_msg: Prints the last transmitted frame.
- The RX messages for LinkSetup look almost identical but they have the
- bit 0x20 set in the command bit, and Channel Setup has added one byte
- before Checksum containing Channel ID.
- NOTE: Several CAIF Messages might be concatenated. The maximum debug
+
+ The RX messages for LinkSetup look almost identical but they have the
+ bit 0x20 set in the command bit, and Channel Setup has added one byte
+ before Checksum containing Channel ID.
+
+ NOTE:
+ Several CAIF Messages might be concatenated. The maximum debug
buffer size is 128 bytes.
-== Error Scenarios:
+Error Scenarios
+===============
+
- last_tx_msg contains channel setup message and last_rx_msg is empty ->
The host seems to be able to send over the UART, at least the CAIF ldisc get
notified that sending is completed.
@@ -103,7 +133,9 @@ There are debugfs parameters provided for serial communication.
- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
might be problems transmitting over UART.
+
E.g. host and modem wiring is not correct you will typically see
tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
+
You will probably see the enumeration message in last_tx_message
and empty last_rx_message.
diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
similarity index 81%
rename from Documentation/networking/mac80211_hwsim/README
rename to Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
index 3566a725d19c..d2266ce5534e 100644
--- a/Documentation/networking/mac80211_hwsim/README
+++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
@@ -1,5 +1,13 @@
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================================================
mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
-Copyright (c) 2008, Jouni Malinen <j@w1.fi>
+===================================================================
+
+:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
@@ -7,6 +15,7 @@ published by the Free Software Foundation.
Introduction
+============
mac80211_hwsim is a Linux kernel module that can be used to simulate
arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
@@ -43,6 +52,7 @@ regardless of channel.
Simple example
+==============
This example shows how to use mac80211_hwsim to simulate two radios:
one to act as an access point and the other as a station that
@@ -50,17 +60,19 @@ associates with the AP. hostapd and wpa_supplicant are used to take
care of WPA2-PSK authentication. In addition, hostapd is also
processing access point side of association.
+::
-# Build mac80211_hwsim as part of kernel configuration
-# Load the module
-modprobe mac80211_hwsim
+ # Build mac80211_hwsim as part of kernel configuration
-# Run hostapd (AP) for wlan0
-hostapd hostapd.conf
+ # Load the module
+ modprobe mac80211_hwsim
-# Run wpa_supplicant (station) for wlan1
-wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
+ # Run hostapd (AP) for wlan0
+ hostapd hostapd.conf
+
+ # Run wpa_supplicant (station) for wlan1
+ wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
More test cases are available in hostap.git:
diff --git a/MAINTAINERS b/MAINTAINERS
index c7656edee696..4de2f288d1ec 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9568,7 +9568,7 @@ F: Documentation/networking/mac80211-injection.txt
F: include/net/mac80211.h
F: net/mac80211/
F: drivers/net/wireless/mac80211_hwsim.[ch]
-F: Documentation/networking/mac80211_hwsim/README
+F: Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
MAILBOX API
M: Jassi Brar <jassisinghbrar@gmail.com>
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* Re: [PATCH v2 00/26] ReST conversion of text files without .txt extension
2019-07-26 12:51 ` Mauro Carvalho Chehab
(?)
(?)
@ 2019-07-26 13:05 ` Mauro Carvalho Chehab
-1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-doc, linux-kernel, linux-pm, linux-arm-kernel,
linux-samsung-soc, linux-pci, linuxppc-dev, linux-scsi,
devicetree, linux-i2c, linux-hwmon, linux-spi, linux-iio,
linux-rtc, netdev, linux-parisc, openrisc, devel, linux-cifs,
samba-technical, devel, dmaengine, alsa-devel, linux-mips,
linux-wireless, rcu
Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
>
> This series is at:
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
>
> And it is based on yesterday's upstream tree.
>
> After this series, we have ~320 files left to be converted to ReST.
>
> v2:
> - Added 3 files submitted for v5.3 that weren't merged yet;
> - markdown patch broken into two, per Rob's request;
> - rebased on the top of upstream master branch
>
> Mauro Carvalho Chehab (26):
> docs: ABI: remove extension from sysfs-class-mic.txt
^ In time: this one was already merged.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 13:05 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
linux-mips, linux-i2c, devel, linux-cifs, linux-samsung-soc,
linux-scsi, devel, devicetree, linux-pm, rcu, openrisc,
linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
samba-technical, linux-kernel, linux-spi, dmaengine,
linuxppc-dev, linux-rtc
Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
>
> This series is at:
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
>
> And it is based on yesterday's upstream tree.
>
> After this series, we have ~320 files left to be converted to ReST.
>
> v2:
> - Added 3 files submitted for v5.3 that weren't merged yet;
> - markdown patch broken into two, per Rob's request;
> - rebased on the top of upstream master branch
>
> Mauro Carvalho Chehab (26):
> docs: ABI: remove extension from sysfs-class-mic.txt
^ In time: this one was already merged.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 13:05 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
linux-mips, linux-i2c, devel, linux-cifs, linux-samsung-soc,
linux-scsi, devel, devicetree, linux-pm, rcu, openrisc,
linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
samba-technical, linux-kernel, linux-spi, dmaengine,
linuxppc-dev, linux-rtc
Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
>
> This series is at:
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
>
> And it is based on yesterday's upstream tree.
>
> After this series, we have ~320 files left to be converted to ReST.
>
> v2:
> - Added 3 files submitted for v5.3 that weren't merged yet;
> - markdown patch broken into two, per Rob's request;
> - rebased on the top of upstream master branch
>
> Mauro Carvalho Chehab (26):
> docs: ABI: remove extension from sysfs-class-mic.txt
^ In time: this one was already merged.
Thanks,
Mauro
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
^ permalink raw reply [flat|nested] 75+ messages in thread
* [OpenRISC] [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 13:05 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
To: openrisc
Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:
> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
>
> This series is at:
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
>
> And it is based on yesterday's upstream tree.
>
> After this series, we have ~320 files left to be converted to ReST.
>
> v2:
> - Added 3 files submitted for v5.3 that weren't merged yet;
> - markdown patch broken into two, per Rob's request;
> - rebased on the top of upstream master branch
>
> Mauro Carvalho Chehab (26):
> docs: ABI: remove extension from sysfs-class-mic.txt
^ In time: this one was already merged.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
[not found] ` <20190726140028.38abb5fa@coco.lan>
@ 2019-07-26 17:55 ` Joel Fernandes
2019-07-26 18:45 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-26 17:55 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
On Fri, Jul 26, 2019 at 02:00:28PM -0300, Mauro Carvalho Chehab wrote:
> Hi Joel,
>
> Em Fri, 26 Jul 2019 12:20:02 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
>
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > There are 4 RCU articles that are written on html format.
> > >
> > > The way they are, they can't be part of the Linux Kernel
> > > documentation body nor share the styles and pdf output.
> > >
> > > So, convert them to ReST format.
> > >
> > > This way, make htmldocs and make pdfdocs will produce a
> > > documentation output that will be like the original ones, but
> > > will be part of the Linux Kernel documentation body.
> > >
> > > Part of the conversion was done with the help of pandoc, but
> > > the result had some broken things that had to be manually
> > > fixed.
> >
> > This looks Ok to me, but I also nervous something could have been done
> > incorrectly during the conversion.
> >
> > Could you list what were the "some broken things" that you had to manually
> > fix to make reviewing easier?
>
> There are a couple of things.
>
> At least the pandoc's version I used here has a bug: its conversion
> from html to ReST on those files only start after a <body> tag - or
> when the first quiz table starts. I only discovered that adding a
> <body> at the beginning of the file solve this book at the last
> conversions.
>
> So, for most html->ReST conversions, I manually converted the first
> part of the document, basically stripping html paragraph tags and
> by replacing highlights by the ReST syntax.
>
> Also, all the quiz tables seem to assume some javascript macro or
> css style that would be hiding the answer part until the mouse moves
> to it. Such macro/css was not there at the kernel tree. So, the quiz
> answers have the same color as the background, making them invisible.
> Even if we had such macro/css, this is not portable for pdf/LaTeX output
> (and I'm not sure if this would work with ePub).
>
> So, I ended by manually doing the table conversion.
>
> Finally, I double-checked if the conversions ended ok, addressing any
> issues that might have heppened.
>
> So, after both automatic conversion and manual fixes, I opened both the
> html files produced by Sphinx and the original ones and compared them
> line per line (except for the indexes, as Sphinx produces them
> automatically), in order to see if all information from the original
> files will be there on a format close to what we have on other ReST
> files, fixing any pending issues if any.
Thanks, I am in the process of going through these docs today and will let
you know anything I find. It would be nice to include the above challenges in
the changelog as well.
Some reason 'make htmldocs' needed me to install a whole bunch of
dependencies this time around.
By the way, that tools/memory-model/Documentation/explanation.txt is a useful
little document. Well not really little with over 1000 lines ;-). But it
would certainly benefit from ReST's / htmldocs ability to jump to labels and
search, etc since it is so long..
thanks,
- Joel
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
[not found] ` <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
[not found] ` <20190726162002.GA146401@google.com>
@ 2019-07-26 18:02 ` Joel Fernandes
2019-07-26 19:01 ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
2019-07-26 19:14 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
2019-07-30 21:22 ` Paul E. McKenney
2 siblings, 2 replies; 75+ messages in thread
From: Joel Fernandes @ 2019-07-26 18:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
[snip]
> +| until the assignment to ``gp``, by which time both fields are fully |
> +| initialized. So reordering the assignments to ``p->a`` and ``p->b`` |
> +| cannot possibly cause any problems. |
> ++-----------------------------------------------------------------------+
> +
> +It is tempting to assume that the reader need not do anything special to
> +control its accesses to the RCU-protected data, as shown in
> +``do_something_gp_buggy()`` below:
> +
> + ::
> +
> + 1 bool do_something_gp_buggy(void)
> + 2 {
> + 3 rcu_read_lock();
> + 4 p = gp; /* OPTIMIZATIONS GALORE!!! */
> + 5 if (p) {
> + 6 do_something(p->a, p->b);
> + 7 rcu_read_unlock();
> + 8 return true;
> + 9 }
> + 10 rcu_read_unlock();
> + 11 return false;
> + 12 }
> +
> +However, this temptation must be resisted because there are a
> +surprisingly large number of ways that the compiler (to say nothing of
> +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> +can trip this code up. For but one example, if the compiler were short
> +of registers, it might choose to refetch from ``gp`` rather than keeping
> +a separate copy in ``p`` as follows:
> +
> + ::
> +
> + 1 bool do_something_gp_buggy_optimized(void)
> + 2 {
> + 3 rcu_read_lock();
> + 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */
> + 5 do_something(gp->a, gp->b);
> + 6 rcu_read_unlock();
> + 7 return true;
> + 8 }
> + 9 rcu_read_unlock();
> + 10 return false;
> + 11 }
> +
> +If this function ran concurrently with a series of updates that replaced
> +the current structure with a new one, the fetches of ``gp->a`` and
> +``gp->b`` might well come from two different structures, which could
> +cause serious confusion. To prevent this (and much else besides),
> +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> +
> + ::
> +
> + 1 bool do_something_gp(void)
> + 2 {
> + 3 rcu_read_lock();
> + 4 p = rcu_dereference(gp);
> + 5 if (p) {
> + 6 do_something(p->a, p->b);
> + 7 rcu_read_unlock();
> + 8 return true;
> + 9 }
> + 10 rcu_read_unlock();
> + 11 return false;
> + 12 }
> +
> +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> +barriers in the Linux kernel. Should a `high-quality implementation of
> +C11 ``memory_order_consume``
> +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> +ever appear, then ``rcu_dereference()`` could be implemented as a
> +``memory_order_consume`` load. Regardless of the exact implementation, a
> +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> +outermost RCU read-side critical section containing that
> +``rcu_dereference()``, unless protection of the corresponding data
> +element has been passed from RCU to some other synchronization
> +mechanism, most commonly locking or `reference
> +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
From the make htmldocs output, this appears very poorly for me, I get
something like this in the browser:
The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
in the Linux kernel. Should a high-quality implementation of C11
``memory_order_consume` [PDF]
<http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
appear, then rcu_dereference() could be implemented as a memory_order_consume
load.
Is there a syntax issue here?
One more feedback,
the image under "RCU read-side critical section that started before the current
grace period:" should probably be blown up a bit.
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-26 17:55 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Joel Fernandes
@ 2019-07-26 18:45 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 18:45 UTC (permalink / raw)
To: Joel Fernandes
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
Em Fri, 26 Jul 2019 13:55:27 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Fri, Jul 26, 2019 at 02:00:28PM -0300, Mauro Carvalho Chehab wrote:
> > Hi Joel,
> >
> > Em Fri, 26 Jul 2019 12:20:02 -0400
> > Joel Fernandes <joel@joelfernandes.org> escreveu:
> >
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > There are 4 RCU articles that are written on html format.
> > > >
> > > Could you list what were the "some broken things" that you had to manually
> > > fix to make reviewing easier?
> >
> > There are a couple of things.
> >
> > At least the pandoc's version I used here has a bug: its conversion
> > from html to ReST on those files only start after a <body> tag - or
> > when the first quiz table starts. I only discovered that adding a
> > <body> at the beginning of the file solve this book at the last
> > conversions.
> >
> > So, for most html->ReST conversions, I manually converted the first
> > part of the document, basically stripping html paragraph tags and
> > by replacing highlights by the ReST syntax.
> >
> > Also, all the quiz tables seem to assume some javascript macro or
> > css style that would be hiding the answer part until the mouse moves
> > to it. Such macro/css was not there at the kernel tree. So, the quiz
> > answers have the same color as the background, making them invisible.
> > Even if we had such macro/css, this is not portable for pdf/LaTeX output
> > (and I'm not sure if this would work with ePub).
> >
> > So, I ended by manually doing the table conversion.
> >
> > Finally, I double-checked if the conversions ended ok, addressing any
> > issues that might have heppened.
> >
> > So, after both automatic conversion and manual fixes, I opened both the
> > html files produced by Sphinx and the original ones and compared them
> > line per line (except for the indexes, as Sphinx produces them
> > automatically), in order to see if all information from the original
> > files will be there on a format close to what we have on other ReST
> > files, fixing any pending issues if any.
>
> Thanks, I am in the process of going through these docs today and will let
> you know anything I find. It would be nice to include the above challenges in
> the changelog as well.
Ok, will add on a next spin - or if you prefer to pick via your tree - feel
free to add them.
> Some reason 'make htmldocs' needed me to install a whole bunch of
> dependencies this time around.
Yes, you need Sphinx, plus some LaTeX stuff - not only for PDF but
also due to some math expressions found on some books.
Just installing Sphinx + its dependencies is enough for this specific
book.
> By the way, that tools/memory-model/Documentation/explanation.txt is a useful
> little document. Well not really little with over 1000 lines ;-). But it
> would certainly benefit from ReST's / htmldocs ability to jump to labels and
> search, etc since it is so long..
tools/*/Documentation is currently out of the current docs build system.
Maybe if you pass SPHINXDIRS=../tools/memory-model/Documentation/ it
could allow you to build something out there.
Btw, did a quick hack here, just for testing:
$ ln -sf ../tools/memory-model/Documentation/ Documentation/tools
$ cp tools/memory-model/Documentation/explanation.txt tools/memory-model/Documentation/explanation.rst
Sphinx tried to build explanation.txt:
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:116: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:118: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:122: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:127: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:128: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:228: WARNING: Unexpected indentation.
...
So, it shouldn't be too hard to add it, but some adjustments will
be needed, specially at the code blocks.
Btw, if you want to play with it, the enclosing patch should give you
a good start.
As there aren't many files there, I suspect that converting them to
ReST should not be hard.
Thanks,
Mauro
[PATCH RFC] tools/memory-model: add it to the Documentation body
Add the cheatsheet file to the Documentation body.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0a564f3c336e..03ff920ac1cb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
admin-guide/index
kbuild/index
+ tools/index
Firmware-related documentation
------------------------------
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+ Prior Operation Subsequent Operation
+ --------------- ---------------------------
+ C Self R W RMW Self R W DR DW RMW SV
+ -- ---- - - --- ---- - - -- -- --- --
+
+ Store, e.g., WRITE_ONCE() Y Y
+ Load, e.g., READ_ONCE() Y Y Y Y
+ Unsuccessful RMW operation Y Y Y Y
+ rcu_dereference() Y Y Y Y
+ Successful *_acquire() R Y Y Y Y Y Y
+ Successful *_release() C Y Y Y W Y
+ smp_rmb() Y R Y Y R
+ smp_wmb() Y W Y Y W
+ smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
+ Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
+ smp_mb__before_atomic() CP Y Y Y a a a a Y
+ smp_mb__after_atomic() CP a a Y Y Y Y Y Y
+
+
+ Key: C: Ordering is cumulative
+ P: Ordering propagates
+ R: Read, for example, READ_ONCE(), or read portion of RMW
+ W: Write, for example, WRITE_ONCE(), or write portion of RMW
+ Y: Provides ordering
+ a: Provides ordering given intervening RMW atomic operation
+ DR: Dependent read (address dependency)
+ DW: Dependent write (address, data, or control dependency)
+ RMW: Atomic read-modify-write operation
+ SELF: Orders self, as opposed to accesses before and/or after
+ SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
- Prior Operation Subsequent Operation
- --------------- ---------------------------
- C Self R W RMW Self R W DR DW RMW SV
- -- ---- - - --- ---- - - -- -- --- --
-
-Store, e.g., WRITE_ONCE() Y Y
-Load, e.g., READ_ONCE() Y Y Y Y
-Unsuccessful RMW operation Y Y Y Y
-rcu_dereference() Y Y Y Y
-Successful *_acquire() R Y Y Y Y Y Y
-Successful *_release() C Y Y Y W Y
-smp_rmb() Y R Y Y R
-smp_wmb() Y W Y Y W
-smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
-Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
-smp_mb__before_atomic() CP Y Y Y a a a a Y
-smp_mb__after_atomic() CP a a Y Y Y Y Y Y
-
-
-Key: C: Ordering is cumulative
- P: Ordering propagates
- R: Read, for example, READ_ONCE(), or read portion of RMW
- W: Write, for example, WRITE_ONCE(), or write portion of RMW
- Y: Provides ordering
- a: Provides ordering given intervening RMW atomic operation
- DR: Dependent read (address dependency)
- DW: Dependent write (address, data, or control dependency)
- RMW: Atomic read-modify-write operation
- SELF: Orders self, as opposed to accesses before and/or after
- SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..23caee7a96cc
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Linux Tools
+===========
+
+.. toctree::
+ :maxdepth: 1
+
+ cheatsheet
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
^ permalink raw reply related [flat|nested] 75+ messages in thread
* [PATCH] tools: memory-model: add it to the Documentation body
2019-07-26 18:02 ` Joel Fernandes
@ 2019-07-26 19:01 ` Mauro Carvalho Chehab
2019-07-27 14:14 ` Joel Fernandes
2019-07-26 19:14 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
1 sibling, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 19:01 UTC (permalink / raw)
To: Joel Fernandes, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
The books at tools/memory-model/Documentation are very well
formatted. Congrats to the ones that wrote them!
The manual conversion to ReST is really trivial:
- Add document titles;
- change the bullets on some lists;
- mark code blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/core-api/refcount-vs-atomic.rst | 2 +-
Documentation/index.rst | 1 +
Documentation/tools/memory-model | 1 +
.../memory-model/Documentation/cheatsheet.rst | 36 +++++
.../memory-model/Documentation/cheatsheet.txt | 30 ----
.../{explanation.txt => explanation.rst} | 151 ++++++++++--------
tools/memory-model/Documentation/index.rst | 20 +++
.../{recipes.txt => recipes.rst} | 41 ++---
.../{references.txt => references.rst} | 46 +++---
tools/memory-model/README | 10 +-
10 files changed, 192 insertions(+), 146 deletions(-)
create mode 120000 Documentation/tools/memory-model
create mode 100644 tools/memory-model/Documentation/cheatsheet.rst
delete mode 100644 tools/memory-model/Documentation/cheatsheet.txt
rename tools/memory-model/Documentation/{explanation.txt => explanation.rst} (97%)
create mode 100644 tools/memory-model/Documentation/index.rst
rename tools/memory-model/Documentation/{recipes.txt => recipes.rst} (96%)
rename tools/memory-model/Documentation/{references.txt => references.rst} (71%)
diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 976e85adffe8..7e6500a6fa76 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ in order to help maintainers validate their code against the change in
these memory ordering guarantees.
The terms used through this document try to follow the formal LKMM defined in
-tools/memory-model/Documentation/explanation.txt.
+tools/memory-model/Documentation/explanation.rst.
memory-barriers.txt and atomic_t.txt provide more background to the
memory ordering in general and for atomic operations specifically.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0a564f3c336e..03ff920ac1cb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
admin-guide/index
kbuild/index
+ tools/index
Firmware-related documentation
------------------------------
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+ Prior Operation Subsequent Operation
+ --------------- ---------------------------
+ C Self R W RMW Self R W DR DW RMW SV
+ -- ---- - - --- ---- - - -- -- --- --
+
+ Store, e.g., WRITE_ONCE() Y Y
+ Load, e.g., READ_ONCE() Y Y Y Y
+ Unsuccessful RMW operation Y Y Y Y
+ rcu_dereference() Y Y Y Y
+ Successful *_acquire() R Y Y Y Y Y Y
+ Successful *_release() C Y Y Y W Y
+ smp_rmb() Y R Y Y R
+ smp_wmb() Y W Y Y W
+ smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
+ Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
+ smp_mb__before_atomic() CP Y Y Y a a a a Y
+ smp_mb__after_atomic() CP a a Y Y Y Y Y Y
+
+
+ Key: C: Ordering is cumulative
+ P: Ordering propagates
+ R: Read, for example, READ_ONCE(), or read portion of RMW
+ W: Write, for example, WRITE_ONCE(), or write portion of RMW
+ Y: Provides ordering
+ a: Provides ordering given intervening RMW atomic operation
+ DR: Dependent read (address dependency)
+ DW: Dependent write (address, data, or control dependency)
+ RMW: Atomic read-modify-write operation
+ SELF: Orders self, as opposed to accesses before and/or after
+ SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
- Prior Operation Subsequent Operation
- --------------- ---------------------------
- C Self R W RMW Self R W DR DW RMW SV
- -- ---- - - --- ---- - - -- -- --- --
-
-Store, e.g., WRITE_ONCE() Y Y
-Load, e.g., READ_ONCE() Y Y Y Y
-Unsuccessful RMW operation Y Y Y Y
-rcu_dereference() Y Y Y Y
-Successful *_acquire() R Y Y Y Y Y Y
-Successful *_release() C Y Y Y W Y
-smp_rmb() Y R Y Y R
-smp_wmb() Y W Y Y W
-smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
-Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
-smp_mb__before_atomic() CP Y Y Y a a a a Y
-smp_mb__after_atomic() CP a a Y Y Y Y Y Y
-
-
-Key: C: Ordering is cumulative
- P: Ordering propagates
- R: Read, for example, READ_ONCE(), or read portion of RMW
- W: Write, for example, WRITE_ONCE(), or write portion of RMW
- Y: Provides ordering
- a: Provides ordering given intervening RMW atomic operation
- DR: Dependent read (address dependency)
- DW: Dependent write (address, data, or control dependency)
- RMW: Atomic read-modify-write operation
- SELF: Orders self, as opposed to accesses before and/or after
- SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/explanation.txt b/tools/memory-model/Documentation/explanation.rst
similarity index 97%
rename from tools/memory-model/Documentation/explanation.txt
rename to tools/memory-model/Documentation/explanation.rst
index 68caa9a976d0..227ec75f8dc4 100644
--- a/tools/memory-model/Documentation/explanation.txt
+++ b/tools/memory-model/Documentation/explanation.rst
@@ -1,5 +1,6 @@
+========================================================
Explanation of the Linux-Kernel Memory Consistency Model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================================
:Author: Alan Stern <stern@rowland.harvard.edu>
:Created: October 2017
@@ -107,7 +108,7 @@ and the flag are memory locations shared between the two CPUs.
We can abstract out the important pieces of the driver code as follows
(the reason for using WRITE_ONCE() and READ_ONCE() instead of simple
-assignment statements is discussed later):
+assignment statements is discussed later)::
int buf = 0, flag = 0;
@@ -219,7 +220,7 @@ Ordering). This model predicts that the undesired outcome for the MP
pattern cannot occur, but in other respects it differs from Sequential
Consistency. One example is the Store Buffer (SB) pattern, in which
each CPU stores to its own shared location and then loads from the
-other CPU's location:
+other CPU's location::
int x = 0, y = 0;
@@ -264,7 +265,7 @@ The counterpart to ordering is a cycle. Ordering rules out cycles:
It's not possible to have X ordered before Y, Y ordered before Z, and
Z ordered before X, because this would mean that X is ordered before
itself. The analysis of the MP example under Sequential Consistency
-involved just such an impossible cycle:
+involved just such an impossible cycle::
W: P0 stores 1 to flag executes before
X: P1 loads 1 from flag executes before
@@ -388,7 +389,7 @@ The protections provided by READ_ONCE(), WRITE_ONCE(), and others are
not perfect; and under some circumstances it is possible for the
compiler to undermine the memory model. Here is an example. Suppose
both branches of an "if" statement store the same value to the same
-location:
+location::
r1 = READ_ONCE(x);
if (r1) {
@@ -402,7 +403,7 @@ location:
For this code, the LKMM predicts that the load from x will always be
executed before either of the stores to y. However, a compiler could
lift the stores out of the conditional, transforming the code into
-something resembling:
+something resembling::
r1 = READ_ONCE(x);
WRITE_ONCE(y, 2);
@@ -418,7 +419,7 @@ model's original prediction could be invalidated by the compiler.
Another issue arises from the fact that in C, arguments to many
operators and function calls can be evaluated in any order. For
-example:
+example::
r1 = f(5) + g(6);
@@ -440,7 +441,7 @@ control (ctrl).
A read and a write event are linked by a data dependency if the value
obtained by the read affects the value stored by the write. As a very
-simple example:
+simple example::
int x, y;
@@ -455,7 +456,7 @@ values of multiple reads.
A read event and another memory access event are linked by an address
dependency if the value obtained by the read affects the location
accessed by the other event. The second event can be either a read or
-a write. Here's another simple example:
+a write. Here's another simple example::
int a[20];
int i;
@@ -471,7 +472,7 @@ pointer.
Finally, a read event and another memory access event are linked by a
control dependency if the value obtained by the read affects whether
-the second event is executed at all. Simple example:
+the second event is executed at all. Simple example::
int x, y;
@@ -510,7 +511,7 @@ Usage of the rf relation implicitly assumes that loads will always
read from a single store. It doesn't apply properly in the presence
of load-tearing, where a load obtains some of its bits from one store
and some of them from another store. Fortunately, use of READ_ONCE()
-and WRITE_ONCE() will prevent load-tearing; it's not possible to have:
+and WRITE_ONCE() will prevent load-tearing; it's not possible to have::
int x = 0;
@@ -530,7 +531,7 @@ and end up with r1 = 0x1200 (partly from x's initial value and partly
from the value stored by P0).
On the other hand, load-tearing is unavoidable when mixed-size
-accesses are used. Consider this example:
+accesses are used. Consider this example::
union {
u32 w;
@@ -612,7 +613,7 @@ requirement that every store eventually becomes visible to every CPU.)
Any reasonable memory model will include cache coherence. Indeed, our
expectation of cache coherence is so deeply ingrained that violations
of its requirements look more like hardware bugs than programming
-errors:
+errors::
int x;
@@ -628,6 +629,8 @@ write-write coherence rule: Since the store of 23 comes later in
program order, it must also come later in x's coherence order and
thus must overwrite the store of 17.
+::
+
int x = 0;
P0()
@@ -644,6 +647,8 @@ program order, so it must not read from that store but rather from one
coming earlier in the coherence order (in this case, x's initial
value).
+::
+
int x = 0;
P0()
@@ -694,7 +699,7 @@ value that R reads is overwritten (directly or indirectly) by W, or
equivalently, when R reads from a store which comes earlier than W in
the coherence order.
-For example:
+For example::
int x = 0;
@@ -721,6 +726,8 @@ relations; it is not independent. Given a read event R and a write
event W for the same location, we will have R ->fr W if and only if
the write which R reads from is co-before W. In symbols,
+::
+
(R ->fr W) := (there exists W' with W' ->rf R and W' ->co W).
@@ -907,7 +914,7 @@ whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
X event comes before the Y event in the global ordering. The LKMM's
"coherence" axiom expresses this by requiring the union of these
relations not to have any cycles. This means it must not be possible
-to find events
+to find events::
X0 -> X1 -> X2 -> ... -> Xn -> X0,
@@ -929,7 +936,7 @@ this case) does not get altered between the read and the write events
making up the atomic operation. In particular, if two CPUs perform
atomic_inc(&x) concurrently, it must be guaranteed that the final
value of x will be the initial value plus two. We should never have
-the following sequence of events:
+the following sequence of events::
CPU 0 loads x obtaining 13;
CPU 1 loads x obtaining 13;
@@ -951,6 +958,8 @@ atomic read-modify-write and W' is the write event which R reads from,
there must not be any stores coming between W' and W in the coherence
order. Equivalently,
+::
+
(R ->rmw W) implies (there is no X with R ->fr X and X ->co W),
where the rmw relation links the read and write events making up each
@@ -1021,7 +1030,7 @@ includes address dependencies to loads in the ppo relation.
On the other hand, dependencies can indirectly affect the ordering of
two loads. This happens when there is a dependency from a load to a
-store and a second, po-later load reads from that store:
+store and a second, po-later load reads from that store::
R ->dep W ->rfi R',
@@ -1036,7 +1045,7 @@ R; if the speculation turns out to be wrong then the CPU merely has to
restart or abandon R'.
(In theory, a CPU might forward a store to a load when it runs across
-an address dependency like this:
+an address dependency like this::
r1 = READ_ONCE(ptr);
WRITE_ONCE(*r1, 17);
@@ -1048,7 +1057,7 @@ However, none of the architectures supported by the Linux kernel do
this.)
Two memory accesses of the same location must always be executed in
-program order if the second access is a store. Thus, if we have
+program order if the second access is a store. Thus, if we have::
R ->po-loc W
@@ -1056,7 +1065,7 @@ program order if the second access is a store. Thus, if we have
access the same location), the CPU is obliged to execute W after R.
If it executed W first then the memory subsystem would respond to R's
read request with the value stored by W (or an even later store), in
-violation of the read-write coherence rule. Similarly, if we had
+violation of the read-write coherence rule. Similarly, if we had::
W ->po-loc W'
@@ -1074,7 +1083,7 @@ AND THEN THERE WAS ALPHA
As mentioned above, the Alpha architecture is unique in that it does
not appear to respect address dependencies to loads. This means that
-code such as the following:
+code such as the following::
int x = 0;
int y = -1;
@@ -1128,7 +1137,7 @@ nothing at all on non-Alpha builds) after every READ_ONCE() and atomic
load. The effect of the fence is to cause the CPU not to execute any
po-later instructions until after the local cache has finished
processing all the stores it has already received. Thus, if the code
-was changed to:
+was changed to::
P1()
{
@@ -1199,7 +1208,7 @@ the first event in the coherence order and propagates to C before the
second event executes.
This is best explained with some examples. The simplest case looks
-like this:
+like this::
int x;
@@ -1225,7 +1234,7 @@ event, because P1's store came after P0's store in x's coherence
order, and P1's store propagated to P0 before P0's load executed.
An equally simple case involves two loads of the same location that
-read from different stores:
+read from different stores::
int x = 0;
@@ -1252,7 +1261,7 @@ P1's store propagated to P0 before P0's second load executed.
Less trivial examples of prop all involve fences. Unlike the simple
examples above, they can require that some instructions are executed
-out of program order. This next one should look familiar:
+out of program order. This next one should look familiar::
int buf = 0, flag = 0;
@@ -1303,7 +1312,7 @@ rfe link. You can concoct more exotic examples, containing more than
one fence, although this quickly leads to diminishing returns in terms
of complexity. For instance, here's an example containing a coe link
followed by two fences and an rfe link, utilizing the fact that
-release fences are A-cumulative:
+release fences are A-cumulative::
int x, y, z;
@@ -1363,7 +1372,7 @@ links. Let's see how this definition works out.
Consider first the case where E is a store (implying that the sequence
of links begins with coe). Then there are events W, X, Y, and Z such
-that:
+that::
E ->coe W ->cumul-fence* X ->rfe? Y ->strong-fence Z ->hb* F,
@@ -1390,7 +1399,7 @@ request with the value stored by W or an even later store,
contradicting the fact that E ->fre W.
A good example illustrating how pb works is the SB pattern with strong
-fences:
+fences::
int x = 0, y = 0;
@@ -1449,18 +1458,18 @@ span a full grace period. In more detail, the Guarantee says:
For any critical section C and any grace period G, at least
one of the following statements must hold:
-(1) C ends before G does, and in addition, every store that
- propagates to C's CPU before the end of C must propagate to
- every CPU before G ends.
+ (1) C ends before G does, and in addition, every store that
+ propagates to C's CPU before the end of C must propagate to
+ every CPU before G ends.
-(2) G starts before C does, and in addition, every store that
- propagates to G's CPU before the start of G must propagate
- to every CPU before C starts.
+ (2) G starts before C does, and in addition, every store that
+ propagates to G's CPU before the start of G must propagate
+ to every CPU before C starts.
In particular, it is not possible for a critical section to both start
before and end after a grace period.
-Here is a simple example of RCU in action:
+Here is a simple example of RCU in action::
int x, y;
@@ -1544,13 +1553,13 @@ the end of a critical section which starts before Z begins.
The LKMM goes on to define the rcu-fence relation as a sequence of
rcu-gp and rcu-rscsi links separated by rcu-link links, in which the
number of rcu-gp links is >= the number of rcu-rscsi links. For
-example:
+example::
X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
would imply that X ->rcu-fence V, because this sequence contains two
rcu-gp links and one rcu-rscsi link. (It also implies that
-X ->rcu-fence T and Z ->rcu-fence V.) On the other hand:
+X ->rcu-fence T and Z ->rcu-fence V.) On the other hand::
X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
@@ -1566,7 +1575,7 @@ E must execute before F; in fact, each synchronize_rcu() fence event
is linked to itself by rcu-fence as a degenerate case.)
To prove this in full generality requires some intellectual effort.
-We'll consider just a very simple case:
+We'll consider just a very simple case::
G ->rcu-gp W ->rcu-link Z ->rcu-rscsi F.
@@ -1621,7 +1630,7 @@ question, and let S be the synchronize_rcu() fence event for the grace
period. Saying that the critical section starts before S means there
are events Q and R where Q is po-after L (which marks the start of the
critical section), Q is "before" R in the sense used by the rcu-link
-relation, and R is po-before the grace period S. Thus we have:
+relation, and R is po-before the grace period S. Thus we have::
L ->rcu-link S.
@@ -1629,20 +1638,20 @@ Let W be the store mentioned above, let Y come before the end of the
critical section and witness that W propagates to the critical
section's CPU by reading from W, and let Z on some arbitrary CPU be a
witness that W has not propagated to that CPU, where Z happens after
-some event X which is po-after S. Symbolically, this amounts to:
+some event X which is po-after S. Symbolically, this amounts to::
S ->po X ->hb* Z ->fr W ->rf Y ->po U.
The fr link from Z to W indicates that W has not propagated to Z's CPU
at the time that Z executes. From this, it can be shown (see the
discussion of the rcu-link relation earlier) that S and U are related
-by rcu-link:
+by rcu-link::
S ->rcu-link U.
Since S is a grace period we have S ->rcu-gp S, and since L and U are
the start and end of the critical section C we have U ->rcu-rscsi L.
-From this we obtain:
+From this we obtain::
S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
@@ -1651,7 +1660,7 @@ the Grace Period Guarantee.
For something a little more down-to-earth, let's see how the axiom
works out in practice. Consider the RCU code example from above, this
-time with statement labels added:
+time with statement labels added::
int x, y;
@@ -1687,7 +1696,7 @@ Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
forbidden cycle, violating the "rcu" axiom. Hence the outcome is not
allowed by the LKMM, as we would expect.
-For contrast, let's see what can happen in a more complicated example:
+For contrast, let's see what can happen in a more complicated example::
int x, y, z;
@@ -1726,22 +1735,22 @@ L2 ->rcu-link U0. However this cycle is not forbidden, because the
sequence of relations contains fewer instances of rcu-gp (one) than of
rcu-rscsi (two). Consequently the outcome is allowed by the LKMM.
The following instruction timing diagram shows how it might actually
-occur:
+occur::
-P0 P1 P2
--------------------- -------------------- --------------------
-rcu_read_lock()
-WRITE_ONCE(y, 1)
- r1 = READ_ONCE(y)
- synchronize_rcu() starts
- . rcu_read_lock()
- . WRITE_ONCE(x, 1)
-r0 = READ_ONCE(x) .
-rcu_read_unlock() .
- synchronize_rcu() ends
- WRITE_ONCE(z, 1)
- r2 = READ_ONCE(z)
- rcu_read_unlock()
+ P0 P1 P2
+ -------------------- -------------------- --------------------
+ rcu_read_lock()
+ WRITE_ONCE(y, 1)
+ r1 = READ_ONCE(y)
+ synchronize_rcu() starts
+ . rcu_read_lock()
+ . WRITE_ONCE(x, 1)
+ r0 = READ_ONCE(x) .
+ rcu_read_unlock() .
+ synchronize_rcu() ends
+ WRITE_ONCE(z, 1)
+ r2 = READ_ONCE(z)
+ rcu_read_unlock()
This requires P0 and P2 to execute their loads and stores out of
program order, but of course they are allowed to do so. And as you
@@ -1767,26 +1776,26 @@ The LKMM includes locking. In fact, there is special code for locking
in the formal model, added in order to make tools run faster.
However, this special code is intended to be more or less equivalent
to concepts we have already covered. A spinlock_t variable is treated
-the same as an int, and spin_lock(&s) is treated almost the same as:
+the same as an int, and spin_lock(&s) is treated almost the same as::
while (cmpxchg_acquire(&s, 0, 1) != 0)
cpu_relax();
This waits until s is equal to 0 and then atomically sets it to 1,
and the read part of the cmpxchg operation acts as an acquire fence.
-An alternate way to express the same thing would be:
+An alternate way to express the same thing would be::
r = xchg_acquire(&s, 1);
along with a requirement that at the end, r = 0. Similarly,
-spin_trylock(&s) is treated almost the same as:
+spin_trylock(&s) is treated almost the same as::
return !cmpxchg_acquire(&s, 0, 1);
which atomically sets s to 1 if it is currently equal to 0 and returns
true if it succeeds (the read part of the cmpxchg operation acts as an
acquire fence only if the operation is successful). spin_unlock(&s)
-is treated almost the same as:
+is treated almost the same as::
smp_store_release(&s, 0);
@@ -1802,7 +1811,7 @@ requires that every instruction po-before the lock-release must
execute before any instruction po-after the lock-acquire. This would
naturally hold if the release and acquire operations were on different
CPUs, but the LKMM says it holds even when they are on the same CPU.
-For example:
+For example::
int x, y;
spinlock_t s;
@@ -1833,7 +1842,7 @@ MP pattern).
This requirement does not apply to ordinary release and acquire
fences, only to lock-related operations. For instance, suppose P0()
-in the example had been written as:
+in the example had been written as::
P0()
{
@@ -1847,7 +1856,7 @@ in the example had been written as:
Then the CPU would be allowed to forward the s = 1 value from the
smp_store_release() to the smp_load_acquire(), executing the
-instructions in the following order:
+instructions in the following order::
r3 = smp_load_acquire(&s); // Obtains r3 = 1
r2 = READ_ONCE(y);
@@ -1859,7 +1868,7 @@ and thus it could load y before x, obtaining r2 = 0 and r1 = 1.
Second, when a lock-acquire reads from a lock-release, and some other
stores W and W' occur po-before the lock-release and po-after the
lock-acquire respectively, the LKMM requires that W must propagate to
-each CPU before W' does. For example, consider:
+each CPU before W' does. For example, consider::
int x, y;
spinlock_t x;
@@ -1928,7 +1937,7 @@ smp_store_release().) The final effect is the same.
Although we didn't mention it above, the instruction execution
ordering provided by the smp_rmb() fence doesn't apply to read events
that are part of a non-value-returning atomic update. For instance,
-given:
+given::
atomic_inc(&x);
smp_rmb();
@@ -1967,14 +1976,14 @@ they behave as follows:
events.
Interestingly, RCU and locking each introduce the possibility of
-deadlock. When faced with code sequences such as:
+deadlock. When faced with code sequences such as::
spin_lock(&s);
spin_lock(&s);
spin_unlock(&s);
spin_unlock(&s);
-or:
+or::
rcu_read_lock();
synchronize_rcu();
@@ -1984,7 +1993,7 @@ what does the LKMM have to say? Answer: It says there are no allowed
executions at all, which makes sense. But this can also lead to
misleading results, because if a piece of code has multiple possible
executions, some of which deadlock, the model will report only on the
-non-deadlocking executions. For example:
+non-deadlocking executions. For example::
int x, y;
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..0e53d83a5a48
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Linux Memory Model Tools
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ explanation
+ recipes
+ references
+ cheatsheet
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.rst
similarity index 96%
rename from tools/memory-model/Documentation/recipes.txt
rename to tools/memory-model/Documentation/recipes.rst
index 7fe8d7aa3029..0229a431b1a2 100644
--- a/tools/memory-model/Documentation/recipes.txt
+++ b/tools/memory-model/Documentation/recipes.rst
@@ -1,3 +1,8 @@
+=======
+Recipes
+=======
+
+
This document provides "recipes", that is, litmus tests for commonly
occurring situations, as well as a few that illustrate subtly broken but
attractive nuisances. Many of these recipes include example code from
@@ -67,7 +72,7 @@ has acquired a given lock sees any changes previously seen or made by any
CPU before it released that same lock. Note that this statement is a bit
stronger than "Any CPU holding a given lock sees all changes made by any
CPU during the time that CPU was holding this same lock". For example,
-consider the following pair of code fragments:
+consider the following pair of code fragments::
/* See MP+polocks.litmus. */
void CPU0(void)
@@ -93,7 +98,7 @@ value of r1 must also be equal to 1. In contrast, the weaker rule would
say nothing about the final value of r1.
The converse to the basic rule also holds, as illustrated by the
-following litmus test:
+following litmus test::
/* See MP+porevlocks.litmus. */
void CPU0(void)
@@ -124,7 +129,7 @@ across multiple CPUs.
However, it is not necessarily the case that accesses ordered by
locking will be seen as ordered by CPUs not holding that lock.
-Consider this example:
+Consider this example::
/* See Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus. */
void CPU0(void)
@@ -157,7 +162,7 @@ CPU2() never acquired the lock, and thus did not benefit from the
lock's ordering properties.
Ordering can be extended to CPUs not holding the lock by careful use
-of smp_mb__after_spinlock():
+of smp_mb__after_spinlock()::
/* See Z6.0+pooncelock+poonceLock+pombonce.litmus. */
void CPU0(void)
@@ -214,7 +219,7 @@ Release and acquire
~~~~~~~~~~~~~~~~~~~
Use of smp_store_release() and smp_load_acquire() is one way to force
-the desired MP ordering. The general approach is shown below:
+the desired MP ordering. The general approach is shown below::
/* See MP+pooncerelease+poacquireonce.litmus. */
void CPU0(void)
@@ -245,7 +250,7 @@ Assign and dereference
Use of rcu_assign_pointer() and rcu_dereference() is quite similar to the
use of smp_store_release() and smp_load_acquire(), except that both
rcu_assign_pointer() and rcu_dereference() operate on RCU-protected
-pointers. The general approach is shown below:
+pointers. The general approach is shown below::
/* See MP+onceassign+derefonce.litmus. */
int z;
@@ -290,7 +295,7 @@ Write and read memory barriers
It is usually better to use smp_store_release() instead of smp_wmb()
and to use smp_load_acquire() instead of smp_rmb(). However, the older
smp_wmb() and smp_rmb() APIs are still heavily used, so it is important
-to understand their use cases. The general approach is shown below:
+to understand their use cases. The general approach is shown below::
/* See MP+fencewmbonceonce+fencermbonceonce.litmus. */
void CPU0(void)
@@ -312,7 +317,7 @@ smp_rmb() macro orders prior loads against later loads. Therefore, if
the final value of r0 is 1, the final value of r1 must also be 1.
The xlog_state_switch_iclogs() function in fs/xfs/xfs_log.c contains
-the following write-side code fragment:
+the following write-side code fragment::
log->l_curr_block -= log->l_logBBsize;
ASSERT(log->l_curr_block >= 0);
@@ -327,7 +332,7 @@ the corresponding read-side code fragment:
cur_block = READ_ONCE(log->l_curr_block);
Alternatively, consider the following comment in function
-perf_output_put_handle() in kernel/events/ring_buffer.c:
+perf_output_put_handle() in kernel/events/ring_buffer.c::
* kernel user
*
@@ -358,7 +363,7 @@ absence of any ordering it is quite possible that this may happen, as
can be seen in the LB+poonceonces.litmus litmus test.
One way of avoiding the counter-intuitive outcome is through the use of a
-control dependency paired with a full memory barrier:
+control dependency paired with a full memory barrier::
/* See LB+fencembonceonce+ctrlonceonce.litmus. */
void CPU0(void)
@@ -382,7 +387,7 @@ The A/D pairing from the ring-buffer use case shown earlier also
illustrates LB. Here is a repeat of the comment in
perf_output_put_handle() in kernel/events/ring_buffer.c, showing a
control dependency on the kernel side and a full memory barrier on
-the user side:
+the user side::
* kernel user
*
@@ -407,7 +412,7 @@ Release-acquire chains
Release-acquire chains are a low-overhead, flexible, and easy-to-use
method of maintaining order. However, they do have some limitations that
-need to be fully understood. Here is an example that maintains order:
+need to be fully understood. Here is an example that maintains order::
/* See ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus. */
void CPU0(void)
@@ -436,7 +441,7 @@ example, ordering would still be preserved if CPU1()'s smp_load_acquire()
invocation was replaced with READ_ONCE().
It is tempting to assume that CPU0()'s store to x is globally ordered
-before CPU1()'s store to z, but this is not the case:
+before CPU1()'s store to z, but this is not the case::
/* See Z6.0+pooncerelease+poacquirerelease+mbonceonce.litmus. */
void CPU0(void)
@@ -474,7 +479,7 @@ Store buffering
Store buffering can be thought of as upside-down load buffering, so
that one CPU first stores to one variable and then loads from a second,
while another CPU stores to the second variable and then loads from the
-first. Preserving order requires nothing less than full barriers:
+first. Preserving order requires nothing less than full barriers::
/* See SB+fencembonceonces.litmus. */
void CPU0(void)
@@ -498,7 +503,7 @@ this counter-intuitive outcome.
This pattern most famously appears as part of Dekker's locking
algorithm, but it has a much more practical use within the Linux kernel
of ordering wakeups. The following comment taken from waitqueue_active()
-in include/linux/wait.h shows the canonical pattern:
+in include/linux/wait.h shows the canonical pattern::
* CPU0 - waker CPU1 - waiter
*
@@ -550,16 +555,16 @@ The strength of memory ordering required for a given litmus test to
avoid a counter-intuitive outcome depends on the types of relations
linking the memory accesses for the outcome in question:
-o If all links are write-to-read links, then the weakest
+- If all links are write-to-read links, then the weakest
possible ordering within each CPU suffices. For example, in
the LB litmus test, a control dependency was enough to do the
job.
-o If all but one of the links are write-to-read links, then a
+- If all but one of the links are write-to-read links, then a
release-acquire chain suffices. Both the MP and the ISA2
litmus tests illustrate this case.
-o If more than one of the links are something other than
+- If more than one of the links are something other than
write-to-read links, then a full memory barrier is required
between each successive pair of non-write-to-read links. This
case is illustrated by the Z6.0 litmus tests, both in the
diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.rst
similarity index 71%
rename from tools/memory-model/Documentation/references.txt
rename to tools/memory-model/Documentation/references.rst
index b177f3e4a614..275876cd10b8 100644
--- a/tools/memory-model/Documentation/references.txt
+++ b/tools/memory-model/Documentation/references.rst
@@ -1,3 +1,7 @@
+==========
+References
+==========
+
This document provides background reading for memory models and related
tools. These documents are aimed at kernel hackers who are interested
in memory models.
@@ -6,64 +10,64 @@ in memory models.
Hardware manuals and models
===========================
-o SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
+- SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
Reference Manual Version 9". SPARC International Inc.
-o Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
+- Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
Reference Manual". Compaq Computer Corporation.
-o Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
+- Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
Itanium Processor Family Memory Ordering". Intel Corporation.
-o Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
+- Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
Software Developer’s Manual". Intel Corporation.
-o Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
+- Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
and Magnus O. Myreen. 2010. "x86-TSO: A Rigorous and Usable
Programmer's Model for x86 Multiprocessors". Commun. ACM 53, 7
(July, 2010), 89-97. http://doi.acm.org/10.1145/1785414.1785443
-o IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
+- IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
Corporation.
-o ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
+- ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
ARM Ltd.
-o Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
+- Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
Derek Williams. 2011. "Understanding POWER Multiprocessors". In
Proceedings of the 32Nd ACM SIGPLAN Conference on Programming
Language Design and Implementation (PLDI ’11). ACM, New York,
NY, USA, 175–186.
-o Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
+- Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
Peter Sewell, Luc Maranget, Jade Alglave, and Derek Williams.
2012. "Synchronising C/C++ and POWER". In Proceedings of the 33rd
ACM SIGPLAN Conference on Programming Language Design and
Implementation (PLDI '12). ACM, New York, NY, USA, 311-322.
-o ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
+- ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
for ARMv8-A architecture profile)". ARM Ltd.
-o Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
+- Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
For Programmers, Volume II-A: The MIPS64(R) Instruction,
Set Reference Manual". Imagination Technologies,
LTD. https://imgtec.com/?do-download=4302.
-o Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
+- Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
Sewell. 2016. "Modelling the ARMv8 Architecture, Operationally:
Concurrency and ISA". In Proceedings of the 43rd Annual ACM
SIGPLAN-SIGACT Symposium on Principles of Programming Languages
(POPL ’16). ACM, New York, NY, USA, 608–621.
-o Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
+- Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
Luc Maranget, Kathryn E. Gray, Ali Sezgin, Mark Batty, and Peter
Sewell. 2017. "Mixed-size Concurrency: ARM, POWER, C/C++11,
and SC". In Proceedings of the 44th ACM SIGPLAN Symposium on
Principles of Programming Languages (POPL 2017). ACM, New York,
NY, USA, 429–442.
-o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
+- Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
Susmit Sarkar, and Peter Sewell. 2018. "Simplifying ARM concurrency:
multicopy-atomic axiomatic and operational models for ARMv8". In
Proceedings of the ACM on Programming Languages, Volume 2, Issue
@@ -73,18 +77,18 @@ o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
Linux-kernel memory model
=========================
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2018. "Frightening small children and disconcerting
grown-ups: Concurrency in the Linux kernel". In Proceedings of
the 23rd International Conference on Architectural Support for
Programming Languages and Operating Systems (ASPLOS 2018). ACM,
New York, NY, USA, 405-418. Webpage: http://diy.inria.fr/linux/.
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2017. "A formal kernel memory-ordering model (part 1)"
Linux Weekly News. https://lwn.net/Articles/718628/
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2017. "A formal kernel memory-ordering model (part 2)"
Linux Weekly News. https://lwn.net/Articles/720550/
@@ -92,16 +96,16 @@ o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Memory-model tooling
====================
-o Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
+- Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
Notation". ACM Trans. Softw. Eng. Methodol. 11, 2 (April 2002),
256–290. http://doi.acm.org/10.1145/505145.505149
-o Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
+- Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
Cats: Modelling, Simulation, Testing, and Data Mining for Weak
Memory". ACM Trans. Program. Lang. Syst. 36, 2, Article 7 (July
2014), 7:1–7:74 pages.
-o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
+- Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
semantics of the weak consistency model specification language
cat". CoRR abs/1608.07531 (2016). http://arxiv.org/abs/1608.07531
@@ -109,6 +113,6 @@ o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
Memory-model comparisons
========================
-o Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
+- Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
Feng. 2016. "Linux-Kernel Memory Model". (6 June 2016).
http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0124r2.html.
diff --git a/tools/memory-model/README b/tools/memory-model/README
index 2b87f3971548..04bb1fa9ed76 100644
--- a/tools/memory-model/README
+++ b/tools/memory-model/README
@@ -105,16 +105,16 @@ for more information.
DESCRIPTION OF FILES
====================
-Documentation/cheatsheet.txt
+Documentation/cheatsheet.rst
Quick-reference guide to the Linux-kernel memory model.
-Documentation/explanation.txt
+Documentation/explanation.rst
Describes the memory model in detail.
-Documentation/recipes.txt
+Documentation/recipes.rst
Lists common memory-ordering patterns.
-Documentation/references.txt
+Documentation/references.rst
Provides background reading.
linux-kernel.bell
@@ -173,7 +173,7 @@ The Linux-kernel memory model has the following limitations:
of READ_ONCE() and WRITE_ONCE() limits the compiler's ability
to optimize, but there is Linux-kernel code that uses bare C
memory accesses. Handling this code is on the to-do list.
- For more information, see Documentation/explanation.txt (in
+ For more information, see Documentation/explanation.rst (in
particular, the "THE PROGRAM ORDER RELATION: po AND po-loc"
and "A WARNING" sections).
--
2.21.0
^ permalink raw reply related [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-26 18:02 ` Joel Fernandes
2019-07-26 19:01 ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
@ 2019-07-26 19:14 ` Mauro Carvalho Chehab
2019-07-30 22:06 ` Joel Fernandes
1 sibling, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 19:14 UTC (permalink / raw)
To: Joel Fernandes
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc, Markus Heiser
Em Fri, 26 Jul 2019 14:02:01 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> [snip]
> > +| until the assignment to ``gp``, by which time both fields are fully |
> > +| initialized. So reordering the assignments to ``p->a`` and ``p->b`` |
> > +| cannot possibly cause any problems. |
> > ++-----------------------------------------------------------------------+
> > +
> > +It is tempting to assume that the reader need not do anything special to
> > +control its accesses to the RCU-protected data, as shown in
> > +``do_something_gp_buggy()`` below:
> > +
> > + ::
> > +
> > + 1 bool do_something_gp_buggy(void)
> > + 2 {
> > + 3 rcu_read_lock();
> > + 4 p = gp; /* OPTIMIZATIONS GALORE!!! */
> > + 5 if (p) {
> > + 6 do_something(p->a, p->b);
> > + 7 rcu_read_unlock();
> > + 8 return true;
> > + 9 }
> > + 10 rcu_read_unlock();
> > + 11 return false;
> > + 12 }
> > +
> > +However, this temptation must be resisted because there are a
> > +surprisingly large number of ways that the compiler (to say nothing of
> > +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> > +can trip this code up. For but one example, if the compiler were short
> > +of registers, it might choose to refetch from ``gp`` rather than keeping
> > +a separate copy in ``p`` as follows:
> > +
> > + ::
> > +
> > + 1 bool do_something_gp_buggy_optimized(void)
> > + 2 {
> > + 3 rcu_read_lock();
> > + 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */
> > + 5 do_something(gp->a, gp->b);
> > + 6 rcu_read_unlock();
> > + 7 return true;
> > + 8 }
> > + 9 rcu_read_unlock();
> > + 10 return false;
> > + 11 }
> > +
> > +If this function ran concurrently with a series of updates that replaced
> > +the current structure with a new one, the fetches of ``gp->a`` and
> > +``gp->b`` might well come from two different structures, which could
> > +cause serious confusion. To prevent this (and much else besides),
> > +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> > +
> > + ::
> > +
> > + 1 bool do_something_gp(void)
> > + 2 {
> > + 3 rcu_read_lock();
> > + 4 p = rcu_dereference(gp);
> > + 5 if (p) {
> > + 6 do_something(p->a, p->b);
> > + 7 rcu_read_unlock();
> > + 8 return true;
> > + 9 }
> > + 10 rcu_read_unlock();
> > + 11 return false;
> > + 12 }
> > +
> > +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> > +barriers in the Linux kernel. Should a `high-quality implementation of
> > +C11 ``memory_order_consume``
> > +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> > +ever appear, then ``rcu_dereference()`` could be implemented as a
> > +``memory_order_consume`` load. Regardless of the exact implementation, a
> > +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> > +outermost RCU read-side critical section containing that
> > +``rcu_dereference()``, unless protection of the corresponding data
> > +element has been passed from RCU to some other synchronization
> > +mechanism, most commonly locking or `reference
> > +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
>
> From the make htmldocs output, this appears very poorly for me, I get
> something like this in the browser:
>
> The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
> in the Linux kernel. Should a high-quality implementation of C11
> ``memory_order_consume` [PDF]
> <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
> appear, then rcu_dereference() could be implemented as a memory_order_consume
> load.
>
> Is there a syntax issue here?
Maybe. I tested those with Sphinx 2.0.1. Didn't test with older versions.
I'll do some tests with Sphinx 1.7.9 (with is the current minimal
recommended version) and do some cleanup on those references.
> One more feedback,
> the image under "RCU read-side critical section that started before the current
> grace period:" should probably be blown up a bit.
Unfortunately, the Kernel Sphinx image extension doesn't allow image scaling.
We had to add our own image extension at the Kernel, as otherwise,
for every image, we would need to add one parser for PDF and another
one for SVG.
We would also need an extra parser for DOT.
Markus solved all the 3 image formats with a single extension, but
it currently doesn't allow passing the image size.
-
Markus,
Any reason for the kernel-image extension to not support scaling?
-
If this can't be easily solved at the kernel-image.py extension, a
simple alternative would be to simply scale the SVG file
directly. It should be trivial to re-scale with inkscape, although
the diff may be big.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-26 19:01 ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
@ 2019-07-27 14:14 ` Joel Fernandes
2019-07-27 15:37 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-27 14:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:
> The books at tools/memory-model/Documentation are very well
> formatted. Congrats to the ones that wrote them!
>
> The manual conversion to ReST is really trivial:
>
> - Add document titles;
> - change the bullets on some lists;
> - mark code blocks.
Thanks so much, some feedback:
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
(1)
I could not find the table of contents appear in the HTML output for this.
Basically this list in the beginning doesn't render:
1. INTRODUCTION
2. BACKGROUND
3. A SIMPLE EXAMPLE
4. A SELECTION OF MEMORY MODELS
5. ORDERING AND CYCLES
Could we add a proper TOC with sections? My motivation for ReST here would be
to make the sections jumpable since it is a large document.
Also could we make the different sections appear as a tree in the left
sidebar?
(2) Arguably several function names in the document HTML output should appear
in monospace fonting and/or referring to the documentation for real function
names, but these can be fixed as we go, I guess.
(3) Things like smp_load_acquire() and spin_lock() should probably refer to
the documentation for those elsewhere..
(4) I would argue that every occurence of
A ->(some dependency) B should be replaced with fixed size font in the HTML
results.
Arguably it is better IMO if the whole document is fixed size font in the
HTML output because so many things need to be fixed size, but that my just be
my opinion.
thanks,
- Joel
> ---
> Documentation/core-api/refcount-vs-atomic.rst | 2 +-
> Documentation/index.rst | 1 +
> Documentation/tools/memory-model | 1 +
> .../memory-model/Documentation/cheatsheet.rst | 36 +++++
> .../memory-model/Documentation/cheatsheet.txt | 30 ----
> .../{explanation.txt => explanation.rst} | 151 ++++++++++--------
> tools/memory-model/Documentation/index.rst | 20 +++
> .../{recipes.txt => recipes.rst} | 41 ++---
> .../{references.txt => references.rst} | 46 +++---
> tools/memory-model/README | 10 +-
> 10 files changed, 192 insertions(+), 146 deletions(-)
> create mode 120000 Documentation/tools/memory-model
> create mode 100644 tools/memory-model/Documentation/cheatsheet.rst
> delete mode 100644 tools/memory-model/Documentation/cheatsheet.txt
> rename tools/memory-model/Documentation/{explanation.txt => explanation.rst} (97%)
> create mode 100644 tools/memory-model/Documentation/index.rst
> rename tools/memory-model/Documentation/{recipes.txt => recipes.rst} (96%)
> rename tools/memory-model/Documentation/{references.txt => references.rst} (71%)
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-27 14:14 ` Joel Fernandes
@ 2019-07-27 15:37 ` Mauro Carvalho Chehab
2019-07-30 22:17 ` Joel Fernandes
0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-27 15:37 UTC (permalink / raw)
To: Joel Fernandes
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
Em Sat, 27 Jul 2019 14:14:53 +0000
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:
> > The books at tools/memory-model/Documentation are very well
> > formatted. Congrats to the ones that wrote them!
> >
> > The manual conversion to ReST is really trivial:
> >
> > - Add document titles;
> > - change the bullets on some lists;
> > - mark code blocks.
>
> Thanks so much, some feedback:
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> (1)
> I could not find the table of contents appear in the HTML output for this.
> Basically this list in the beginning doesn't render:
> 1. INTRODUCTION
> 2. BACKGROUND
> 3. A SIMPLE EXAMPLE
> 4. A SELECTION OF MEMORY MODELS
> 5. ORDERING AND CYCLES
Yes. It is written as a comment, like:
.. foo This is a comment block
Everything on this block
won't be parsed.
So it won't be parsed, but having a TOC like this isn't need, as
Sphinx generates it automatically via "toctree" markup.
> Could we add a proper TOC with sections? My motivation for ReST here would be
> to make the sections jumpable since it is a large document.
Just change the toctree depth at index.rst to 2 and you'll see an index
produced by Sphinx with both levels 1 (doc name) and level 2 (chapters):
.. toctree::
:maxdepth: 2
> Also could we make the different sections appear as a tree in the left
> sidebar?
The sidebar follows the maxdepth too.
>
> (2) Arguably several function names in the document HTML output should appear
> in monospace fonting and/or referring to the documentation for real function
> names, but these can be fixed as we go, I guess.
If you want monospaced fonts, just use: ``monospaced_symbol_foo`` within
any paragraph, or place the monospaced data inside a code-block:
::
This will be monospaced.
>
> (3) Things like smp_load_acquire() and spin_lock() should probably refer to
> the documentation for those elsewhere..
Jon added an automarkup extension on Kernel 5.2. So, all functions that
are defined elsewhere will automatically generate an hyperlink. For that to
happen, you need to add the kernel-doc markup at the *.h or *.c file where
the function is declared and use the kernel-doc markup somewhere within the
Kernel Documentation/.
>
> (4) I would argue that every occurence of
> A ->(some dependency) B should be replaced with fixed size font in the HTML
> results.
Just place those with ``A -> (some dependency)``. This will make them use
a fixed size font.
> Arguably it is better IMO if the whole document is fixed size font in the
> HTML output because so many things need to be fixed size, but that my just be
> my opinion.
Just my 2 cents here, but having the entire document using a fixed size
font makes it more boring to read. Having just the symbols with a fixed size
is a common convention used on technical books, and helps to make easier
to identify the symbols while reading the docs.
That's said, Sphinx doesn't have any tag to switch the font for the entire
document. All it can be done is to define a CSS and apply it for the
doc - or to place everything within a code-block, with will suppress all
markup tags, including cross-references for functions.
The problem with CSS is that you need to write both an html CSS file
and add LaTeX macros associated to this "CSS style" (technically, LaTeX
doesn't have a CSS concept, but Sphinx emulates it).
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
[not found] ` <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
[not found] ` <20190726162002.GA146401@google.com>
2019-07-26 18:02 ` Joel Fernandes
@ 2019-07-30 21:22 ` Paul E. McKenney
2019-07-30 21:50 ` Joel Fernandes
2019-07-30 21:50 ` Mauro Carvalho Chehab
2 siblings, 2 replies; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-30 21:22 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc
On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> There are 4 RCU articles that are written on html format.
>
> The way they are, they can't be part of the Linux Kernel
> documentation body nor share the styles and pdf output.
>
> So, convert them to ReST format.
>
> This way, make htmldocs and make pdfdocs will produce a
> documentation output that will be like the original ones, but
> will be part of the Linux Kernel documentation body.
>
> Part of the conversion was done with the help of pandoc, but
> the result had some broken things that had to be manually
> fixed.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
I am having some trouble applying these, at least in part due to UTF-8
sequences, for example double left quotation mark. These end up being
"=E2=80=9C", with a few space characters turned into "=20".
Any advice on how to apply these? Should I just pull commits from
somewhere?
Thanx, Paul
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 21:22 ` Paul E. McKenney
@ 2019-07-30 21:50 ` Joel Fernandes
2019-07-30 22:00 ` Mauro Carvalho Chehab
2019-07-30 21:50 ` Mauro Carvalho Chehab
1 sibling, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 21:50 UTC (permalink / raw)
To: Paul E. McKenney
Cc: Mauro Carvalho Chehab, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > There are 4 RCU articles that are written on html format.
> >
> > The way they are, they can't be part of the Linux Kernel
> > documentation body nor share the styles and pdf output.
> >
> > So, convert them to ReST format.
> >
> > This way, make htmldocs and make pdfdocs will produce a
> > documentation output that will be like the original ones, but
> > will be part of the Linux Kernel documentation body.
> >
> > Part of the conversion was done with the help of pandoc, but
> > the result had some broken things that had to be manually
> > fixed.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> I am having some trouble applying these, at least in part due to UTF-8
> sequences, for example double left quotation mark. These end up being
> "=E2=80=9C", with a few space characters turned into "=20".
>
> Any advice on how to apply these? Should I just pull commits from
> somewhere?
I was able to successfully apply and build this particular patch. I think
this is the only one in the series that applies to RCU.
Sadly, I can't find the patch in any of the public archives, but I could
perhaps email it to you as an .mbox attach which 'git am' should be able to
apply.
Mauro did say he was going to add some more details to changelog, or it could
be added when it is applied:
https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/
Let me know how else I can help! I am reviewing this patch further today.
thanks,
- Joel
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 21:22 ` Paul E. McKenney
2019-07-30 21:50 ` Joel Fernandes
@ 2019-07-30 21:50 ` Mauro Carvalho Chehab
2019-07-30 23:37 ` Paul E. McKenney
1 sibling, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 21:50 UTC (permalink / raw)
To: Paul E. McKenney
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc
Em Tue, 30 Jul 2019 14:22:50 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > There are 4 RCU articles that are written on html format.
> >
> > The way they are, they can't be part of the Linux Kernel
> > documentation body nor share the styles and pdf output.
> >
> > So, convert them to ReST format.
> >
> > This way, make htmldocs and make pdfdocs will produce a
> > documentation output that will be like the original ones, but
> > will be part of the Linux Kernel documentation body.
> >
> > Part of the conversion was done with the help of pandoc, but
> > the result had some broken things that had to be manually
> > fixed.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> I am having some trouble applying these, at least in part due to UTF-8
> sequences, for example double left quotation mark. These end up being
> "=E2=80=9C", with a few space characters turned into "=20".
>
> Any advice on how to apply these?
Didn't notice it ended with UTF-8 chars. It is probably because it came
from the html conversion.
I guess it shouldn't hurt keeping those, but if you prefer I can find
some time later to replace them.
> Should I just pull commits from somewhere?
Yeah, if you prefer, you can pull from this branch:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
It has just two patches: the RCU and tools/memory-model ones.
It is based on v5.3-rc2.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 21:50 ` Joel Fernandes
@ 2019-07-30 22:00 ` Mauro Carvalho Chehab
2019-07-30 22:21 ` Joel Fernandes
0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 22:00 UTC (permalink / raw)
To: Joel Fernandes
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
Em Tue, 30 Jul 2019 17:50:07 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > There are 4 RCU articles that are written on html format.
> > >
> > > The way they are, they can't be part of the Linux Kernel
> > > documentation body nor share the styles and pdf output.
> > >
> > > So, convert them to ReST format.
> > >
> > > This way, make htmldocs and make pdfdocs will produce a
> > > documentation output that will be like the original ones, but
> > > will be part of the Linux Kernel documentation body.
> > >
> > > Part of the conversion was done with the help of pandoc, but
> > > the result had some broken things that had to be manually
> > > fixed.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> >
> > I am having some trouble applying these, at least in part due to UTF-8
> > sequences, for example double left quotation mark. These end up being
> > "=E2=80=9C", with a few space characters turned into "=20".
> >
> > Any advice on how to apply these? Should I just pull commits from
> > somewhere?
>
> I was able to successfully apply and build this particular patch. I think
> this is the only one in the series that applies to RCU.
>
> Sadly, I can't find the patch in any of the public archives, but I could
> perhaps email it to you as an .mbox attach which 'git am' should be able to
> apply.
>
> Mauro did say he was going to add some more details to changelog, or it could
> be added when it is applied:
> https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/
Yeah, I'm also planning to address at least some of the issues you
pointed, in order to improve the html output, but got sidetracked by something
else and didn't find any time yet to finish. I'm adding some CI automation for
the media subsystem in order to help us dealing with the huge amount of patches
we receive there.
Feel free to add those details to the changelog. I may find some spare time
this week or the next one for the improvements you suggested, but those
could be sent on followup patches, once done.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-26 19:14 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
@ 2019-07-30 22:06 ` Joel Fernandes
0 siblings, 0 replies; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 22:06 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc, Markus Heiser
On Fri, Jul 26, 2019 at 04:14:05PM -0300, Mauro Carvalho Chehab wrote:
> Em Fri, 26 Jul 2019 14:02:01 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
>
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > [snip]
> > > +| until the assignment to ``gp``, by which time both fields are fully |
> > > +| initialized. So reordering the assignments to ``p->a`` and ``p->b`` |
> > > +| cannot possibly cause any problems. |
> > > ++-----------------------------------------------------------------------+
> > > +
> > > +It is tempting to assume that the reader need not do anything special to
> > > +control its accesses to the RCU-protected data, as shown in
> > > +``do_something_gp_buggy()`` below:
> > > +
> > > + ::
> > > +
> > > + 1 bool do_something_gp_buggy(void)
> > > + 2 {
> > > + 3 rcu_read_lock();
> > > + 4 p = gp; /* OPTIMIZATIONS GALORE!!! */
> > > + 5 if (p) {
> > > + 6 do_something(p->a, p->b);
> > > + 7 rcu_read_unlock();
> > > + 8 return true;
> > > + 9 }
> > > + 10 rcu_read_unlock();
> > > + 11 return false;
> > > + 12 }
> > > +
> > > +However, this temptation must be resisted because there are a
> > > +surprisingly large number of ways that the compiler (to say nothing of
> > > +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> > > +can trip this code up. For but one example, if the compiler were short
> > > +of registers, it might choose to refetch from ``gp`` rather than keeping
> > > +a separate copy in ``p`` as follows:
> > > +
> > > + ::
> > > +
> > > + 1 bool do_something_gp_buggy_optimized(void)
> > > + 2 {
> > > + 3 rcu_read_lock();
> > > + 4 if (gp) { /* OPTIMIZATIONS GALORE!!! */
> > > + 5 do_something(gp->a, gp->b);
> > > + 6 rcu_read_unlock();
> > > + 7 return true;
> > > + 8 }
> > > + 9 rcu_read_unlock();
> > > + 10 return false;
> > > + 11 }
> > > +
> > > +If this function ran concurrently with a series of updates that replaced
> > > +the current structure with a new one, the fetches of ``gp->a`` and
> > > +``gp->b`` might well come from two different structures, which could
> > > +cause serious confusion. To prevent this (and much else besides),
> > > +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> > > +
> > > + ::
> > > +
> > > + 1 bool do_something_gp(void)
> > > + 2 {
> > > + 3 rcu_read_lock();
> > > + 4 p = rcu_dereference(gp);
> > > + 5 if (p) {
> > > + 6 do_something(p->a, p->b);
> > > + 7 rcu_read_unlock();
> > > + 8 return true;
> > > + 9 }
> > > + 10 rcu_read_unlock();
> > > + 11 return false;
> > > + 12 }
> > > +
> > > +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> > > +barriers in the Linux kernel. Should a `high-quality implementation of
> > > +C11 ``memory_order_consume``
> > > +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> > > +ever appear, then ``rcu_dereference()`` could be implemented as a
> > > +``memory_order_consume`` load. Regardless of the exact implementation, a
> > > +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> > > +outermost RCU read-side critical section containing that
> > > +``rcu_dereference()``, unless protection of the corresponding data
> > > +element has been passed from RCU to some other synchronization
> > > +mechanism, most commonly locking or `reference
> > > +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.
> >
> > From the make htmldocs output, this appears very poorly for me, I get
> > something like this in the browser:
> >
> > The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
> > in the Linux kernel. Should a high-quality implementation of C11
> > ``memory_order_consume` [PDF]
> > <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
> > appear, then rcu_dereference() could be implemented as a memory_order_consume
> > load.
> >
> > Is there a syntax issue here?
>
> Maybe. I tested those with Sphinx 2.0.1. Didn't test with older versions.
>
> I'll do some tests with Sphinx 1.7.9 (with is the current minimal
> recommended version) and do some cleanup on those references.
Ok, one more thing is broken, clicking links such as "Parallelism Facts of
Life" does not jump to the corresponding section.
Would you mind fixing this, add the description of changes you made (which
you shared in an earlier reply), fixing the above Sphinx issue, and then
resend it?
Otherwise, I believe it looks sane.
> > One more feedback,
> > the image under "RCU read-side critical section that started before the current
> > grace period:" should probably be blown up a bit.
>
> Unfortunately, the Kernel Sphinx image extension doesn't allow image scaling.
The current scale appears fine to me, it is not a big deal since it is clear.
> We had to add our own image extension at the Kernel, as otherwise,
> for every image, we would need to add one parser for PDF and another
> one for SVG.
>
> We would also need an extra parser for DOT.
>
> Markus solved all the 3 image formats with a single extension, but
> it currently doesn't allow passing the image size.
Cool.
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-27 15:37 ` Mauro Carvalho Chehab
@ 2019-07-30 22:17 ` Joel Fernandes
2019-07-30 22:57 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 22:17 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
On Sat, Jul 27, 2019 at 12:37:54PM -0300, Mauro Carvalho Chehab wrote:
> Em Sat, 27 Jul 2019 14:14:53 +0000
> Joel Fernandes <joel@joelfernandes.org> escreveu:
>
> > On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:
> > > The books at tools/memory-model/Documentation are very well
> > > formatted. Congrats to the ones that wrote them!
> > >
> > > The manual conversion to ReST is really trivial:
> > >
> > > - Add document titles;
> > > - change the bullets on some lists;
> > > - mark code blocks.
> >
> > Thanks so much, some feedback:
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> >
> > (1)
> > I could not find the table of contents appear in the HTML output for this.
> > Basically this list in the beginning doesn't render:
> > 1. INTRODUCTION
> > 2. BACKGROUND
> > 3. A SIMPLE EXAMPLE
> > 4. A SELECTION OF MEMORY MODELS
> > 5. ORDERING AND CYCLES
>
> Yes. It is written as a comment, like:
>
> .. foo This is a comment block
>
> Everything on this block
>
> won't be parsed.
>
> So it won't be parsed, but having a TOC like this isn't need, as
> Sphinx generates it automatically via "toctree" markup.
Ok.
> > Could we add a proper TOC with sections? My motivation for ReST here would be
> > to make the sections jumpable since it is a large document.
>
> Just change the toctree depth at index.rst to 2 and you'll see an index
> produced by Sphinx with both levels 1 (doc name) and level 2 (chapters):
>
> .. toctree::
> :maxdepth: 2
Admittedly, I don't have much time at the moment to do these experiments :(
> > Also could we make the different sections appear as a tree in the left
> > sidebar?
>
> The sidebar follows the maxdepth too.
>
> >
> > (2) Arguably several function names in the document HTML output should appear
> > in monospace fonting and/or referring to the documentation for real function
> > names, but these can be fixed as we go, I guess.
>
> If you want monospaced fonts, just use: ``monospaced_symbol_foo`` within
> any paragraph, or place the monospaced data inside a code-block:
>
> ::
>
> This will be monospaced.
>
> >
> > (3) Things like smp_load_acquire() and spin_lock() should probably refer to
> > the documentation for those elsewhere..
>
> Jon added an automarkup extension on Kernel 5.2. So, all functions that
> are defined elsewhere will automatically generate an hyperlink. For that to
> happen, you need to add the kernel-doc markup at the *.h or *.c file where
> the function is declared and use the kernel-doc markup somewhere within the
> Kernel Documentation/.
>
> >
> > (4) I would argue that every occurence of
> > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > results.
>
> Just place those with ``A -> (some dependency)``. This will make them use
> a fixed size font.
Ok, understood all these. I guess my point was all of these will need to be
done to make this document useful from a ReST conversion standpoint. Until
then it is probably just better off being plain text - since there are so
many of those ``A -> (dep) B`` things.
> > Arguably it is better IMO if the whole document is fixed size font in the
> > HTML output because so many things need to be fixed size, but that my just be
> > my opinion.
>
> Just my 2 cents here, but having the entire document using a fixed size
> font makes it more boring to read. Having just the symbols with a fixed size
> is a common convention used on technical books, and helps to make easier
> to identify the symbols while reading the docs.
>
> That's said, Sphinx doesn't have any tag to switch the font for the entire
> document. All it can be done is to define a CSS and apply it for the
> doc - or to place everything within a code-block, with will suppress all
> markup tags, including cross-references for functions.
Ok, got it.
> The problem with CSS is that you need to write both an html CSS file
> and add LaTeX macros associated to this "CSS style" (technically, LaTeX
> doesn't have a CSS concept, but Sphinx emulates it).
Yeah I don't think we want to do CSS here. So the correct thing to do would
be to place all fixed-width things within double backticks, if someone had
the time to do it. I am currently spending time understanding the document's
content itself..
thanks for the effort, it could probably serve as a good future reference,
- Joel
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 22:00 ` Mauro Carvalho Chehab
@ 2019-07-30 22:21 ` Joel Fernandes
2019-07-30 23:00 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 22:21 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
On Tue, Jul 30, 2019 at 07:00:28PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 17:50:07 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
>
> > On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > There are 4 RCU articles that are written on html format.
> > > >
> > > > The way they are, they can't be part of the Linux Kernel
> > > > documentation body nor share the styles and pdf output.
> > > >
> > > > So, convert them to ReST format.
> > > >
> > > > This way, make htmldocs and make pdfdocs will produce a
> > > > documentation output that will be like the original ones, but
> > > > will be part of the Linux Kernel documentation body.
> > > >
> > > > Part of the conversion was done with the help of pandoc, but
> > > > the result had some broken things that had to be manually
> > > > fixed.
> > > >
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > >
> > > I am having some trouble applying these, at least in part due to UTF-8
> > > sequences, for example double left quotation mark. These end up being
> > > "=E2=80=9C", with a few space characters turned into "=20".
> > >
> > > Any advice on how to apply these? Should I just pull commits from
> > > somewhere?
> >
> > I was able to successfully apply and build this particular patch. I think
> > this is the only one in the series that applies to RCU.
> >
> > Sadly, I can't find the patch in any of the public archives, but I could
> > perhaps email it to you as an .mbox attach which 'git am' should be able to
> > apply.
> >
> > Mauro did say he was going to add some more details to changelog, or it could
> > be added when it is applied:
> > https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/
>
> Yeah, I'm also planning to address at least some of the issues you
> pointed, in order to improve the html output, but got sidetracked by something
> else and didn't find any time yet to finish. I'm adding some CI automation for
> the media subsystem in order to help us dealing with the huge amount of patches
> we receive there.
>
> Feel free to add those details to the changelog. I may find some spare time
> this week or the next one for the improvements you suggested, but those
> could be sent on followup patches, once done.
Ok, I will re-send this RCU patch with the changes, leave this one to me.
The other memory model one, needs a lot more work so we can keep that aside
for now till someone has the time.
thanks,
- Joel
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-30 22:17 ` Joel Fernandes
@ 2019-07-30 22:57 ` Mauro Carvalho Chehab
2019-07-31 13:52 ` Alan Stern
0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 22:57 UTC (permalink / raw)
To: Joel Fernandes
Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
Em Tue, 30 Jul 2019 18:17:01 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Sat, Jul 27, 2019 at 12:37:54PM -0300, Mauro Carvalho Chehab wrote:
> > Em Sat, 27 Jul 2019 14:14:53 +0000
> > Joel Fernandes <joel@joelfernandes.org> escreveu:
> >
> > > On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:
> > > > The books at tools/memory-model/Documentation are very well
> > > > formatted. Congrats to the ones that wrote them!
> > > >
> > > > The manual conversion to ReST is really trivial:
> > > >
> > > > - Add document titles;
> > > > - change the bullets on some lists;
> > > > - mark code blocks.
> > >
> > > Thanks so much, some feedback:
> > > >
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > >
> > > (1)
> > > I could not find the table of contents appear in the HTML output for this.
> > > Basically this list in the beginning doesn't render:
> > > 1. INTRODUCTION
> > > 2. BACKGROUND
> > > 3. A SIMPLE EXAMPLE
> > > 4. A SELECTION OF MEMORY MODELS
> > > 5. ORDERING AND CYCLES
> >
> > Yes. It is written as a comment, like:
> >
> > .. foo This is a comment block
> >
> > Everything on this block
> >
> > won't be parsed.
> >
> > So it won't be parsed, but having a TOC like this isn't need, as
> > Sphinx generates it automatically via "toctree" markup.
>
> Ok.
>
> > > Could we add a proper TOC with sections? My motivation for ReST here would be
> > > to make the sections jumpable since it is a large document.
> >
> > Just change the toctree depth at index.rst to 2 and you'll see an index
> > produced by Sphinx with both levels 1 (doc name) and level 2 (chapters):
> >
> > .. toctree::
> > :maxdepth: 2
>
> Admittedly, I don't have much time at the moment to do these experiments :(
>
> > > Also could we make the different sections appear as a tree in the left
> > > sidebar?
> >
> > The sidebar follows the maxdepth too.
> >
> > >
> > > (2) Arguably several function names in the document HTML output should appear
> > > in monospace fonting and/or referring to the documentation for real function
> > > names, but these can be fixed as we go, I guess.
> >
> > If you want monospaced fonts, just use: ``monospaced_symbol_foo`` within
> > any paragraph, or place the monospaced data inside a code-block:
> >
> > ::
> >
> > This will be monospaced.
> >
> > >
> > > (3) Things like smp_load_acquire() and spin_lock() should probably refer to
> > > the documentation for those elsewhere..
> >
> > Jon added an automarkup extension on Kernel 5.2. So, all functions that
> > are defined elsewhere will automatically generate an hyperlink. For that to
> > happen, you need to add the kernel-doc markup at the *.h or *.c file where
> > the function is declared and use the kernel-doc markup somewhere within the
> > Kernel Documentation/.
> >
> > >
> > > (4) I would argue that every occurence of
> > > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > > results.
> >
> > Just place those with ``A -> (some dependency)``. This will make them use
> > a fixed size font.
>
> Ok, understood all these. I guess my point was all of these will need to be
> done to make this document useful from a ReST conversion standpoint. Until
> then it is probably just better off being plain text - since there are so
> many of those ``A -> (dep) B`` things.
>
> > > Arguably it is better IMO if the whole document is fixed size font in the
> > > HTML output because so many things need to be fixed size, but that my just be
> > > my opinion.
> >
> > Just my 2 cents here, but having the entire document using a fixed size
> > font makes it more boring to read. Having just the symbols with a fixed size
> > is a common convention used on technical books, and helps to make easier
> > to identify the symbols while reading the docs.
> >
> > That's said, Sphinx doesn't have any tag to switch the font for the entire
> > document. All it can be done is to define a CSS and apply it for the
> > doc - or to place everything within a code-block, with will suppress all
> > markup tags, including cross-references for functions.
>
> Ok, got it.
>
> > The problem with CSS is that you need to write both an html CSS file
> > and add LaTeX macros associated to this "CSS style" (technically, LaTeX
> > doesn't have a CSS concept, but Sphinx emulates it).
>
> Yeah I don't think we want to do CSS here. So the correct thing to do would
> be to place all fixed-width things within double backticks, if someone had
> the time to do it. I am currently spending time understanding the document's
> content itself..
>
> thanks for the effort, it could probably serve as a good future reference,
On a very quick look, it seems that, if we replace:
(\S+\s->\S*\s\w+)
by:
``\1``
On an editor that would allow to manually replace the regex (like kate),
most of those can be get.
See patch enclosed.
Thanks,
Mauro
[PATCH] Use monotonic fonts for ``A -> (dep) B``
Manually replace:
(\S+\s->\S*\s\w+)
by:
``\1``
On their occurrences and fix a couple of places where it doesn't
hit well.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
diff --git a/tools/memory-model/Documentation/explanation.rst b/tools/memory-model/Documentation/explanation.rst
index 227ec75f8dc4..9b5d10cef0c2 100644
--- a/tools/memory-model/Documentation/explanation.rst
+++ b/tools/memory-model/Documentation/explanation.rst
@@ -332,7 +332,7 @@ can think of it as the order in which statements occur in the source
code after branches are taken into account and loops have been
unrolled. A better description might be the order in which
instructions are presented to a CPU's execution unit. Thus, we say
-that X is po-before Y (written as "X ->po Y" in formulas) if X occurs
+that X is po-before Y (written as ``X ->po Y`` in formulas) if X occurs
before Y in the instruction stream.
This is inherently a single-CPU relation; two instructions executing
@@ -485,9 +485,9 @@ which depends on the value obtained by the READ_ONCE(); hence there is
a control dependency from the load to the store.
It should be pretty obvious that events can only depend on reads that
-come earlier in program order. Symbolically, if we have R ->data X,
-R ->addr X, or R ->ctrl X (where R is a read event), then we must also
-have R ->po X. It wouldn't make sense for a computation to depend
+come earlier in program order. Symbolically, if we have ``R ->data X``,
+``R ->addr X``, or ``R ->ctrl X`` (where R is a read event), then we must also
+have ``R ->po X``. It wouldn't make sense for a computation to depend
somehow on a value that doesn't get loaded from shared memory until
later in the code!
@@ -498,7 +498,7 @@ THE READS-FROM RELATION: rf, rfi, and rfe
The reads-from relation (rf) links a write event to a read event when
the value loaded by the read is the value that was stored by the
write. In colloquial terms, the load "reads from" the store. We
-write W ->rf R to indicate that the load R reads from the store W. We
+write ``W ->rf R`` to indicate that the load R reads from the store W. We
further distinguish the cases where the load and the store occur on
the same CPU (internal reads-from, or rfi) and where they occur on
different CPUs (external reads-from, or rfe).
@@ -579,26 +579,26 @@ that value comes third, and so on.
You can think of the coherence order as being the order in which the
stores reach x's location in memory (or if you prefer a more
hardware-centric view, the order in which the stores get written to
-x's cache line). We write W ->co W' if W comes before W' in the
+x's cache line). We write ``W ->co W'`` if W comes before W' in the
coherence order, that is, if the value stored by W gets overwritten,
directly or indirectly, by the value stored by W'.
Coherence order is required to be consistent with program order. This
requirement takes the form of four coherency rules:
- Write-write coherence: If W ->po-loc W' (i.e., W comes before
+ Write-write coherence: If ``W ->po-loc W'`` (i.e., W comes before
W' in program order and they access the same location), where W
- and W' are two stores, then W ->co W'.
+ and W' are two stores, then ``W ->co W'``.
- Write-read coherence: If W ->po-loc R, where W is a store and R
+ Write-read coherence: If ``W ->po-loc R``, where W is a store and R
is a load, then R must read from W or from some other store
which comes after W in the coherence order.
- Read-write coherence: If R ->po-loc W, where R is a load and W
+ Read-write coherence: If ``R ->po-loc W``, where R is a load and W
is a store, then the store which R reads from must come before
W in the coherence order.
- Read-read coherence: If R ->po-loc R', where R and R' are two
+ Read-read coherence: If ``R ->po-loc R'``, where R and R' are two
loads, then either they read from the same store or else the
store read by R comes before the store read by R' in the
coherence order.
@@ -694,7 +694,7 @@ THE FROM-READS RELATION: fr, fri, and fre
The from-reads relation (fr) can be a little difficult for people to
grok. It describes the situation where a load reads a value that gets
-overwritten by a store. In other words, we have R ->fr W when the
+overwritten by a store. In other words, we have ``R ->fr W`` when the
value that R reads is overwritten (directly or indirectly) by W, or
equivalently, when R reads from a store which comes earlier than W in
the coherence order.
@@ -723,7 +723,7 @@ different CPUs).
Note that the fr relation is determined entirely by the rf and co
relations; it is not independent. Given a read event R and a write
-event W for the same location, we will have R ->fr W if and only if
+event W for the same location, we will have ``R ->fr W`` if and only if
the write which R reads from is co-before W. In symbols,
::
@@ -850,13 +850,13 @@ defined to link memory access events E and F whenever:
event occurs between them in program order; or
F is a release fence and some X comes before F in program order,
- where either X = E or else E ->rf X; or
+ where either ``X = E`` or else ``E ->rf X``; or
A strong fence event occurs between some X and F in program
- order, where either X = E or else E ->rf X.
+ order, where either ``X = E`` or else ``E ->rf X``.
The operational model requires that whenever W and W' are both stores
-and W ->cumul-fence W', then W must propagate to any given CPU
+and ``W ->cumul-fence W'``, then W must propagate to any given CPU
before W' does. However, for different CPUs C and C', it does not
require W to propagate to C before W' propagates to C'.
@@ -910,7 +910,7 @@ first for CPU 0, then CPU 1, etc.
You can check that the four coherency rules imply that the rf, co, fr,
and po-loc relations agree with this global ordering; in other words,
-whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
+whenever we have ``X ->rf Y`` or ``X ->co Y`` or ``X ->fr Y`` or ``X ->po-loc Y``, the
X event comes before the Y event in the global ordering. The LKMM's
"coherence" axiom expresses this by requiring the union of these
relations not to have any cycles. This means it must not be possible
@@ -977,7 +977,7 @@ po.
The operational model already includes a description of one such
situation: Fences are a source of ppo links. Suppose X and Y are
-memory accesses with X ->po Y; then the CPU must execute X before Y if
+memory accesses with ``X ->po Y``; then the CPU must execute X before Y if
any of the following hold:
A strong (smp_mb() or synchronize_rcu()) fence occurs between
@@ -996,7 +996,7 @@ any of the following hold:
Another possibility, not mentioned earlier but discussed in the next
section, is:
- X and Y are both loads, X ->addr Y (i.e., there is an address
+ X and Y are both loads, ``X ->addr Y`` (i.e., there is an address
dependency from X to Y), and X is a READ_ONCE() or an atomic
access.
@@ -1176,25 +1176,25 @@ The happens-before relation (hb) links memory accesses that have to
execute in a certain order. hb includes the ppo relation and two
others, one of which is rfe.
-W ->rfe R implies that W and R are on different CPUs. It also means
+``W ->rfe R`` implies that W and R are on different CPUs. It also means
that W's store must have propagated to R's CPU before R executed;
otherwise R could not have read the value stored by W. Therefore W
-must have executed before R, and so we have W ->hb R.
+must have executed before R, and so we have ``W ->hb R``.
-The equivalent fact need not hold if W ->rfi R (i.e., W and R are on
+The equivalent fact need not hold if ``W ->rfi R`` (i.e., W and R are on
the same CPU). As we have already seen, the operational model allows
W's value to be forwarded to R in such cases, meaning that R may well
execute before W does.
It's important to understand that neither coe nor fre is included in
hb, despite their similarities to rfe. For example, suppose we have
-W ->coe W'. This means that W and W' are stores to the same location,
+``W ->coe W'``. This means that W and W' are stores to the same location,
they execute on different CPUs, and W comes before W' in the coherence
order (i.e., W' overwrites W). Nevertheless, it is possible for W' to
execute before W, because the decision as to which store overwrites
the other is made later by the memory subsystem. When the stores are
nearly simultaneous, either one can come out on top. Similarly,
-R ->fre W means that W overwrites the value which R reads, but it
+``R ->fre W`` means that W overwrites the value which R reads, but it
doesn't mean that W has to execute after R. All that's necessary is
for the memory subsystem not to propagate W to R's CPU until after R
has executed, which is possible if W executes shortly before R.
@@ -1393,10 +1393,10 @@ The existence of a pb link from E to F implies that E must execute
before F. To see why, suppose that F executed first. Then W would
have propagated to E's CPU before E executed. If E was a store, the
memory subsystem would then be forced to make E come after W in the
-coherence order, contradicting the fact that E ->coe W. If E was a
+coherence order, contradicting the fact that ``E ->coe W``. If E was a
load, the memory subsystem would then be forced to satisfy E's read
request with the value stored by W or an even later store,
-contradicting the fact that E ->fre W.
+contradicting the fact that ``E ->fre W``.
A good example illustrating how pb works is the SB pattern with strong
fences::
@@ -1518,9 +1518,9 @@ entirely clear. The LKMM formalizes this notion by means of the
rcu-link relation. rcu-link encompasses a very general notion of
"before": If E and F are RCU fence events (i.e., rcu_read_lock(),
rcu_read_unlock(), or synchronize_rcu()) then among other things,
-E ->rcu-link F includes cases where E is po-before some memory-access
+``E ->rcu-link F`` includes cases where E is po-before some memory-access
event X, F is po-after some memory-access event Y, and we have any of
-X ->rfe Y, X ->co Y, or X ->fr Y.
+``X ->rfe Y``, ``X ->co Y``, or ``X ->fr Y``.
The formal definition of the rcu-link relation is more than a little
obscure, and we won't give it here. It is closely related to the pb
@@ -1532,22 +1532,22 @@ The LKMM also defines the rcu-gp and rcu-rscsi relations. They bring
grace periods and read-side critical sections into the picture, in the
following way:
- E ->rcu-gp F means that E and F are in fact the same event,
+ ``E ->rcu-gp F`` means that E and F are in fact the same event,
and that event is a synchronize_rcu() fence (i.e., a grace
period).
- E ->rcu-rscsi F means that E and F are the rcu_read_unlock()
+ ``E ->rcu-rscsi F`` means that E and F are the rcu_read_unlock()
and rcu_read_lock() fence events delimiting some read-side
critical section. (The 'i' at the end of the name emphasizes
that this relation is "inverted": It links the end of the
critical section to the start.)
If we think of the rcu-link relation as standing for an extended
-"before", then X ->rcu-gp Y ->rcu-link Z roughly says that X is a
+"before", then ``X ->rcu-gp Y ->rcu-link Z`` roughly says that X is a
grace period which ends before Z begins. (In fact it covers more than
this, because it also includes cases where some store propagates to
Z's CPU before Z begins but doesn't propagate to some other CPU until
-after X ends.) Similarly, X ->rcu-rscsi Y ->rcu-link Z says that X is
+after X ends.) Similarly, ``X ->rcu-rscsi Y ->rcu-link Z`` says that X is
the end of a critical section which starts before Z begins.
The LKMM goes on to define the rcu-fence relation as a sequence of
@@ -1557,18 +1557,18 @@ example::
X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
-would imply that X ->rcu-fence V, because this sequence contains two
+would imply that ``X ->rcu-fence V``, because this sequence contains two
rcu-gp links and one rcu-rscsi link. (It also implies that
-X ->rcu-fence T and Z ->rcu-fence V.) On the other hand::
+``X ->rcu-fence T`` and ``Z ->rcu-fence V``.) On the other hand::
X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
-does not imply X ->rcu-fence V, because the sequence contains only
+does not imply ``X ->rcu-fence V``, because the sequence contains only
one rcu-gp link but two rcu-rscsi links.
The rcu-fence relation is important because the Grace Period Guarantee
means that rcu-fence acts kind of like a strong fence. In particular,
-E ->rcu-fence F implies not only that E begins before F ends, but also
+``E ->rcu-fence F`` implies not only that E begins before F ends, but also
that any write po-before E will propagate to every CPU before any
instruction po-after F can execute. (However, it does not imply that
E must execute before F; in fact, each synchronize_rcu() fence event
@@ -1604,13 +1604,13 @@ covered by rcu-fence.
Finally, the LKMM defines the RCU-before (rb) relation in terms of
rcu-fence. This is done in essentially the same way as the pb
relation was defined in terms of strong-fence. We will omit the
-details; the end result is that E ->rb F implies E must execute
-before F, just as E ->pb F does (and for much the same reasons).
+details; the end result is that ``E ->rb F`` implies E must execute
+before F, just as ``E ->pb F`` does (and for much the same reasons).
Putting this all together, the LKMM expresses the Grace Period
Guarantee by requiring that the rb relation does not contain a cycle.
Equivalently, this "rcu" axiom requires that there are no events E
-and F with E ->rcu-link F ->rcu-fence E. Or to put it a third way,
+and F with ``E ->rcu-link F ->rcu-fence E``. Or to put it a third way,
the axiom requires that there are no cycles consisting of rcu-gp and
rcu-rscsi alternating with rcu-link, where the number of rcu-gp links
is >= the number of rcu-rscsi links.
@@ -1649,8 +1649,8 @@ by rcu-link::
S ->rcu-link U.
-Since S is a grace period we have S ->rcu-gp S, and since L and U are
-the start and end of the critical section C we have U ->rcu-rscsi L.
+Since S is a grace period we have ``S ->rcu-gp S``, and since L and U are
+the start and end of the critical section C we have ``U ->rcu-rscsi L``.
From this we obtain::
S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
@@ -1683,16 +1683,16 @@ time with statement labels added::
If r2 = 0 at the end then P0's store at Y overwrites the value that
-P1's load at W reads from, so we have W ->fre Y. Since S ->po W and
-also Y ->po U, we get S ->rcu-link U. In addition, S ->rcu-gp S
+P1's load at W reads from, so we have ``W ->fre Y``. Since ``S ->po W`` and
+also ``Y ->po U``, we get ``S ->rcu-link U``. In addition, ``S ->rcu-gp S``
because S is a grace period.
If r1 = 1 at the end then P1's load at Z reads from P0's store at X,
-so we have X ->rfe Z. Together with L ->po X and Z ->po S, this
-yields L ->rcu-link S. And since L and U are the start and end of a
-critical section, we have U ->rcu-rscsi L.
+so we have ``X ->rfe Z``. Together with ``L ->po X`` and ``Z ->po S``, this
+yields ``L ->rcu-link S``. And since L and U are the start and end of a
+critical section, we have ``U ->rcu-rscsi L``.
-Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
+Then ``U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U`` is a
forbidden cycle, violating the "rcu" axiom. Hence the outcome is not
allowed by the LKMM, as we would expect.
@@ -1729,9 +1729,9 @@ For contrast, let's see what can happen in a more complicated example::
U2: rcu_read_unlock();
}
-If r0 = r1 = r2 = 1 at the end, then similar reasoning to before shows
-that U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
-L2 ->rcu-link U0. However this cycle is not forbidden, because the
+If ``r0 = r1 = r2 = 1`` at the end, then similar reasoning to before shows
+that ``U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
+L2 ->rcu-link U0``. However this cycle is not forbidden, because the
sequence of relations contains fewer instances of rcu-gp (one) than of
rcu-rscsi (two). Consequently the outcome is allowed by the LKMM.
The following instruction timing diagram shows how it might actually
^ permalink raw reply related [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 22:21 ` Joel Fernandes
@ 2019-07-30 23:00 ` Mauro Carvalho Chehab
2019-07-30 23:15 ` Joel Fernandes
0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 23:00 UTC (permalink / raw)
To: Joel Fernandes
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
Em Tue, 30 Jul 2019 18:21:30 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:
> On Tue, Jul 30, 2019 at 07:00:28PM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Jul 2019 17:50:07 -0400
> > Joel Fernandes <joel@joelfernandes.org> escreveu:
> >
> > > On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > > There are 4 RCU articles that are written on html format.
> > > > >
> > > > > The way they are, they can't be part of the Linux Kernel
> > > > > documentation body nor share the styles and pdf output.
> > > > >
> > > > > So, convert them to ReST format.
> > > > >
> > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > documentation output that will be like the original ones, but
> > > > > will be part of the Linux Kernel documentation body.
> > > > >
> > > > > Part of the conversion was done with the help of pandoc, but
> > > > > the result had some broken things that had to be manually
> > > > > fixed.
> > > > >
> > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > > >
> > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > sequences, for example double left quotation mark. These end up being
> > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > >
> > > > Any advice on how to apply these? Should I just pull commits from
> > > > somewhere?
> > >
> > > I was able to successfully apply and build this particular patch. I think
> > > this is the only one in the series that applies to RCU.
> > >
> > > Sadly, I can't find the patch in any of the public archives, but I could
> > > perhaps email it to you as an .mbox attach which 'git am' should be able to
> > > apply.
> > >
> > > Mauro did say he was going to add some more details to changelog, or it could
> > > be added when it is applied:
> > > https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/
> >
> > Yeah, I'm also planning to address at least some of the issues you
> > pointed, in order to improve the html output, but got sidetracked by something
> > else and didn't find any time yet to finish. I'm adding some CI automation for
> > the media subsystem in order to help us dealing with the huge amount of patches
> > we receive there.
> >
> > Feel free to add those details to the changelog. I may find some spare time
> > this week or the next one for the improvements you suggested, but those
> > could be sent on followup patches, once done.
>
> Ok, I will re-send this RCU patch with the changes, leave this one to me.
>
> The other memory model one, needs a lot more work so we can keep that aside
> for now till someone has the time.
Yeah, feel free to do what fits best with regards to this one.
If you prefer to merge it instead, I'm enclosing the last version of it,
with that quick hack I just wrote, plus the change of the toctree for
it to produce the 2-level index.
Thanks,
Mauro
[PATCH] tools: memory-model: add it to the Documentation body
The books at tools/memory-model/Documentation are very well
formatted. Congrats to the ones that wrote them!
The manual conversion to ReST is really trivial:
- Add document titles;
- change the bullets on some lists;
- mark code blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 976e85adffe8..7e6500a6fa76 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ in order to help maintainers validate their code against the change in
these memory ordering guarantees.
The terms used through this document try to follow the formal LKMM defined in
-tools/memory-model/Documentation/explanation.txt.
+tools/memory-model/Documentation/explanation.rst.
memory-barriers.txt and atomic_t.txt provide more background to the
memory ordering in general and for atomic operations specifically.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 2df5a3da563c..5123770ba77e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
admin-guide/index
kbuild/index
+ tools/index
Firmware-related documentation
------------------------------
diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst
new file mode 100644
index 000000000000..f540d9cc75a1
--- /dev/null
+++ b/Documentation/tools/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Linux Tools
+===========
+
+.. toctree::
+ :maxdepth: 2
+
+ memory-model/index
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+ Prior Operation Subsequent Operation
+ --------------- ---------------------------
+ C Self R W RMW Self R W DR DW RMW SV
+ -- ---- - - --- ---- - - -- -- --- --
+
+ Store, e.g., WRITE_ONCE() Y Y
+ Load, e.g., READ_ONCE() Y Y Y Y
+ Unsuccessful RMW operation Y Y Y Y
+ rcu_dereference() Y Y Y Y
+ Successful *_acquire() R Y Y Y Y Y Y
+ Successful *_release() C Y Y Y W Y
+ smp_rmb() Y R Y Y R
+ smp_wmb() Y W Y Y W
+ smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
+ Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
+ smp_mb__before_atomic() CP Y Y Y a a a a Y
+ smp_mb__after_atomic() CP a a Y Y Y Y Y Y
+
+
+ Key: C: Ordering is cumulative
+ P: Ordering propagates
+ R: Read, for example, READ_ONCE(), or read portion of RMW
+ W: Write, for example, WRITE_ONCE(), or write portion of RMW
+ Y: Provides ordering
+ a: Provides ordering given intervening RMW atomic operation
+ DR: Dependent read (address dependency)
+ DW: Dependent write (address, data, or control dependency)
+ RMW: Atomic read-modify-write operation
+ SELF: Orders self, as opposed to accesses before and/or after
+ SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
- Prior Operation Subsequent Operation
- --------------- ---------------------------
- C Self R W RMW Self R W DR DW RMW SV
- -- ---- - - --- ---- - - -- -- --- --
-
-Store, e.g., WRITE_ONCE() Y Y
-Load, e.g., READ_ONCE() Y Y Y Y
-Unsuccessful RMW operation Y Y Y Y
-rcu_dereference() Y Y Y Y
-Successful *_acquire() R Y Y Y Y Y Y
-Successful *_release() C Y Y Y W Y
-smp_rmb() Y R Y Y R
-smp_wmb() Y W Y Y W
-smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
-Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
-smp_mb__before_atomic() CP Y Y Y a a a a Y
-smp_mb__after_atomic() CP a a Y Y Y Y Y Y
-
-
-Key: C: Ordering is cumulative
- P: Ordering propagates
- R: Read, for example, READ_ONCE(), or read portion of RMW
- W: Write, for example, WRITE_ONCE(), or write portion of RMW
- Y: Provides ordering
- a: Provides ordering given intervening RMW atomic operation
- DR: Dependent read (address dependency)
- DW: Dependent write (address, data, or control dependency)
- RMW: Atomic read-modify-write operation
- SELF: Orders self, as opposed to accesses before and/or after
- SV: Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/explanation.txt b/tools/memory-model/Documentation/explanation.rst
similarity index 92%
rename from tools/memory-model/Documentation/explanation.txt
rename to tools/memory-model/Documentation/explanation.rst
index 68caa9a976d0..9b5d10cef0c2 100644
--- a/tools/memory-model/Documentation/explanation.txt
+++ b/tools/memory-model/Documentation/explanation.rst
@@ -1,5 +1,6 @@
+========================================================
Explanation of the Linux-Kernel Memory Consistency Model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================================
:Author: Alan Stern <stern@rowland.harvard.edu>
:Created: October 2017
@@ -107,7 +108,7 @@ and the flag are memory locations shared between the two CPUs.
We can abstract out the important pieces of the driver code as follows
(the reason for using WRITE_ONCE() and READ_ONCE() instead of simple
-assignment statements is discussed later):
+assignment statements is discussed later)::
int buf = 0, flag = 0;
@@ -219,7 +220,7 @@ Ordering). This model predicts that the undesired outcome for the MP
pattern cannot occur, but in other respects it differs from Sequential
Consistency. One example is the Store Buffer (SB) pattern, in which
each CPU stores to its own shared location and then loads from the
-other CPU's location:
+other CPU's location::
int x = 0, y = 0;
@@ -264,7 +265,7 @@ The counterpart to ordering is a cycle. Ordering rules out cycles:
It's not possible to have X ordered before Y, Y ordered before Z, and
Z ordered before X, because this would mean that X is ordered before
itself. The analysis of the MP example under Sequential Consistency
-involved just such an impossible cycle:
+involved just such an impossible cycle::
W: P0 stores 1 to flag executes before
X: P1 loads 1 from flag executes before
@@ -331,7 +332,7 @@ can think of it as the order in which statements occur in the source
code after branches are taken into account and loops have been
unrolled. A better description might be the order in which
instructions are presented to a CPU's execution unit. Thus, we say
-that X is po-before Y (written as "X ->po Y" in formulas) if X occurs
+that X is po-before Y (written as ``X ->po Y`` in formulas) if X occurs
before Y in the instruction stream.
This is inherently a single-CPU relation; two instructions executing
@@ -388,7 +389,7 @@ The protections provided by READ_ONCE(), WRITE_ONCE(), and others are
not perfect; and under some circumstances it is possible for the
compiler to undermine the memory model. Here is an example. Suppose
both branches of an "if" statement store the same value to the same
-location:
+location::
r1 = READ_ONCE(x);
if (r1) {
@@ -402,7 +403,7 @@ location:
For this code, the LKMM predicts that the load from x will always be
executed before either of the stores to y. However, a compiler could
lift the stores out of the conditional, transforming the code into
-something resembling:
+something resembling::
r1 = READ_ONCE(x);
WRITE_ONCE(y, 2);
@@ -418,7 +419,7 @@ model's original prediction could be invalidated by the compiler.
Another issue arises from the fact that in C, arguments to many
operators and function calls can be evaluated in any order. For
-example:
+example::
r1 = f(5) + g(6);
@@ -440,7 +441,7 @@ control (ctrl).
A read and a write event are linked by a data dependency if the value
obtained by the read affects the value stored by the write. As a very
-simple example:
+simple example::
int x, y;
@@ -455,7 +456,7 @@ values of multiple reads.
A read event and another memory access event are linked by an address
dependency if the value obtained by the read affects the location
accessed by the other event. The second event can be either a read or
-a write. Here's another simple example:
+a write. Here's another simple example::
int a[20];
int i;
@@ -471,7 +472,7 @@ pointer.
Finally, a read event and another memory access event are linked by a
control dependency if the value obtained by the read affects whether
-the second event is executed at all. Simple example:
+the second event is executed at all. Simple example::
int x, y;
@@ -484,9 +485,9 @@ which depends on the value obtained by the READ_ONCE(); hence there is
a control dependency from the load to the store.
It should be pretty obvious that events can only depend on reads that
-come earlier in program order. Symbolically, if we have R ->data X,
-R ->addr X, or R ->ctrl X (where R is a read event), then we must also
-have R ->po X. It wouldn't make sense for a computation to depend
+come earlier in program order. Symbolically, if we have ``R ->data X``,
+``R ->addr X``, or ``R ->ctrl X`` (where R is a read event), then we must also
+have ``R ->po X``. It wouldn't make sense for a computation to depend
somehow on a value that doesn't get loaded from shared memory until
later in the code!
@@ -497,7 +498,7 @@ THE READS-FROM RELATION: rf, rfi, and rfe
The reads-from relation (rf) links a write event to a read event when
the value loaded by the read is the value that was stored by the
write. In colloquial terms, the load "reads from" the store. We
-write W ->rf R to indicate that the load R reads from the store W. We
+write ``W ->rf R`` to indicate that the load R reads from the store W. We
further distinguish the cases where the load and the store occur on
the same CPU (internal reads-from, or rfi) and where they occur on
different CPUs (external reads-from, or rfe).
@@ -510,7 +511,7 @@ Usage of the rf relation implicitly assumes that loads will always
read from a single store. It doesn't apply properly in the presence
of load-tearing, where a load obtains some of its bits from one store
and some of them from another store. Fortunately, use of READ_ONCE()
-and WRITE_ONCE() will prevent load-tearing; it's not possible to have:
+and WRITE_ONCE() will prevent load-tearing; it's not possible to have::
int x = 0;
@@ -530,7 +531,7 @@ and end up with r1 = 0x1200 (partly from x's initial value and partly
from the value stored by P0).
On the other hand, load-tearing is unavoidable when mixed-size
-accesses are used. Consider this example:
+accesses are used. Consider this example::
union {
u32 w;
@@ -578,26 +579,26 @@ that value comes third, and so on.
You can think of the coherence order as being the order in which the
stores reach x's location in memory (or if you prefer a more
hardware-centric view, the order in which the stores get written to
-x's cache line). We write W ->co W' if W comes before W' in the
+x's cache line). We write ``W ->co W'`` if W comes before W' in the
coherence order, that is, if the value stored by W gets overwritten,
directly or indirectly, by the value stored by W'.
Coherence order is required to be consistent with program order. This
requirement takes the form of four coherency rules:
- Write-write coherence: If W ->po-loc W' (i.e., W comes before
+ Write-write coherence: If ``W ->po-loc W'`` (i.e., W comes before
W' in program order and they access the same location), where W
- and W' are two stores, then W ->co W'.
+ and W' are two stores, then ``W ->co W'``.
- Write-read coherence: If W ->po-loc R, where W is a store and R
+ Write-read coherence: If ``W ->po-loc R``, where W is a store and R
is a load, then R must read from W or from some other store
which comes after W in the coherence order.
- Read-write coherence: If R ->po-loc W, where R is a load and W
+ Read-write coherence: If ``R ->po-loc W``, where R is a load and W
is a store, then the store which R reads from must come before
W in the coherence order.
- Read-read coherence: If R ->po-loc R', where R and R' are two
+ Read-read coherence: If ``R ->po-loc R'``, where R and R' are two
loads, then either they read from the same store or else the
store read by R comes before the store read by R' in the
coherence order.
@@ -612,7 +613,7 @@ requirement that every store eventually becomes visible to every CPU.)
Any reasonable memory model will include cache coherence. Indeed, our
expectation of cache coherence is so deeply ingrained that violations
of its requirements look more like hardware bugs than programming
-errors:
+errors::
int x;
@@ -628,6 +629,8 @@ write-write coherence rule: Since the store of 23 comes later in
program order, it must also come later in x's coherence order and
thus must overwrite the store of 17.
+::
+
int x = 0;
P0()
@@ -644,6 +647,8 @@ program order, so it must not read from that store but rather from one
coming earlier in the coherence order (in this case, x's initial
value).
+::
+
int x = 0;
P0()
@@ -689,12 +694,12 @@ THE FROM-READS RELATION: fr, fri, and fre
The from-reads relation (fr) can be a little difficult for people to
grok. It describes the situation where a load reads a value that gets
-overwritten by a store. In other words, we have R ->fr W when the
+overwritten by a store. In other words, we have ``R ->fr W`` when the
value that R reads is overwritten (directly or indirectly) by W, or
equivalently, when R reads from a store which comes earlier than W in
the coherence order.
-For example:
+For example::
int x = 0;
@@ -718,9 +723,11 @@ different CPUs).
Note that the fr relation is determined entirely by the rf and co
relations; it is not independent. Given a read event R and a write
-event W for the same location, we will have R ->fr W if and only if
+event W for the same location, we will have ``R ->fr W`` if and only if
the write which R reads from is co-before W. In symbols,
+::
+
(R ->fr W) := (there exists W' with W' ->rf R and W' ->co W).
@@ -843,13 +850,13 @@ defined to link memory access events E and F whenever:
event occurs between them in program order; or
F is a release fence and some X comes before F in program order,
- where either X = E or else E ->rf X; or
+ where either ``X = E`` or else ``E ->rf X``; or
A strong fence event occurs between some X and F in program
- order, where either X = E or else E ->rf X.
+ order, where either ``X = E`` or else ``E ->rf X``.
The operational model requires that whenever W and W' are both stores
-and W ->cumul-fence W', then W must propagate to any given CPU
+and ``W ->cumul-fence W'``, then W must propagate to any given CPU
before W' does. However, for different CPUs C and C', it does not
require W to propagate to C before W' propagates to C'.
@@ -903,11 +910,11 @@ first for CPU 0, then CPU 1, etc.
You can check that the four coherency rules imply that the rf, co, fr,
and po-loc relations agree with this global ordering; in other words,
-whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
+whenever we have ``X ->rf Y`` or ``X ->co Y`` or ``X ->fr Y`` or ``X ->po-loc Y``, the
X event comes before the Y event in the global ordering. The LKMM's
"coherence" axiom expresses this by requiring the union of these
relations not to have any cycles. This means it must not be possible
-to find events
+to find events::
X0 -> X1 -> X2 -> ... -> Xn -> X0,
@@ -929,7 +936,7 @@ this case) does not get altered between the read and the write events
making up the atomic operation. In particular, if two CPUs perform
atomic_inc(&x) concurrently, it must be guaranteed that the final
value of x will be the initial value plus two. We should never have
-the following sequence of events:
+the following sequence of events::
CPU 0 loads x obtaining 13;
CPU 1 loads x obtaining 13;
@@ -951,6 +958,8 @@ atomic read-modify-write and W' is the write event which R reads from,
there must not be any stores coming between W' and W in the coherence
order. Equivalently,
+::
+
(R ->rmw W) implies (there is no X with R ->fr X and X ->co W),
where the rmw relation links the read and write events making up each
@@ -968,7 +977,7 @@ po.
The operational model already includes a description of one such
situation: Fences are a source of ppo links. Suppose X and Y are
-memory accesses with X ->po Y; then the CPU must execute X before Y if
+memory accesses with ``X ->po Y``; then the CPU must execute X before Y if
any of the following hold:
A strong (smp_mb() or synchronize_rcu()) fence occurs between
@@ -987,7 +996,7 @@ any of the following hold:
Another possibility, not mentioned earlier but discussed in the next
section, is:
- X and Y are both loads, X ->addr Y (i.e., there is an address
+ X and Y are both loads, ``X ->addr Y`` (i.e., there is an address
dependency from X to Y), and X is a READ_ONCE() or an atomic
access.
@@ -1021,7 +1030,7 @@ includes address dependencies to loads in the ppo relation.
On the other hand, dependencies can indirectly affect the ordering of
two loads. This happens when there is a dependency from a load to a
-store and a second, po-later load reads from that store:
+store and a second, po-later load reads from that store::
R ->dep W ->rfi R',
@@ -1036,7 +1045,7 @@ R; if the speculation turns out to be wrong then the CPU merely has to
restart or abandon R'.
(In theory, a CPU might forward a store to a load when it runs across
-an address dependency like this:
+an address dependency like this::
r1 = READ_ONCE(ptr);
WRITE_ONCE(*r1, 17);
@@ -1048,7 +1057,7 @@ However, none of the architectures supported by the Linux kernel do
this.)
Two memory accesses of the same location must always be executed in
-program order if the second access is a store. Thus, if we have
+program order if the second access is a store. Thus, if we have::
R ->po-loc W
@@ -1056,7 +1065,7 @@ program order if the second access is a store. Thus, if we have
access the same location), the CPU is obliged to execute W after R.
If it executed W first then the memory subsystem would respond to R's
read request with the value stored by W (or an even later store), in
-violation of the read-write coherence rule. Similarly, if we had
+violation of the read-write coherence rule. Similarly, if we had::
W ->po-loc W'
@@ -1074,7 +1083,7 @@ AND THEN THERE WAS ALPHA
As mentioned above, the Alpha architecture is unique in that it does
not appear to respect address dependencies to loads. This means that
-code such as the following:
+code such as the following::
int x = 0;
int y = -1;
@@ -1128,7 +1137,7 @@ nothing at all on non-Alpha builds) after every READ_ONCE() and atomic
load. The effect of the fence is to cause the CPU not to execute any
po-later instructions until after the local cache has finished
processing all the stores it has already received. Thus, if the code
-was changed to:
+was changed to::
P1()
{
@@ -1167,25 +1176,25 @@ The happens-before relation (hb) links memory accesses that have to
execute in a certain order. hb includes the ppo relation and two
others, one of which is rfe.
-W ->rfe R implies that W and R are on different CPUs. It also means
+``W ->rfe R`` implies that W and R are on different CPUs. It also means
that W's store must have propagated to R's CPU before R executed;
otherwise R could not have read the value stored by W. Therefore W
-must have executed before R, and so we have W ->hb R.
+must have executed before R, and so we have ``W ->hb R``.
-The equivalent fact need not hold if W ->rfi R (i.e., W and R are on
+The equivalent fact need not hold if ``W ->rfi R`` (i.e., W and R are on
the same CPU). As we have already seen, the operational model allows
W's value to be forwarded to R in such cases, meaning that R may well
execute before W does.
It's important to understand that neither coe nor fre is included in
hb, despite their similarities to rfe. For example, suppose we have
-W ->coe W'. This means that W and W' are stores to the same location,
+``W ->coe W'``. This means that W and W' are stores to the same location,
they execute on different CPUs, and W comes before W' in the coherence
order (i.e., W' overwrites W). Nevertheless, it is possible for W' to
execute before W, because the decision as to which store overwrites
the other is made later by the memory subsystem. When the stores are
nearly simultaneous, either one can come out on top. Similarly,
-R ->fre W means that W overwrites the value which R reads, but it
+``R ->fre W`` means that W overwrites the value which R reads, but it
doesn't mean that W has to execute after R. All that's necessary is
for the memory subsystem not to propagate W to R's CPU until after R
has executed, which is possible if W executes shortly before R.
@@ -1199,7 +1208,7 @@ the first event in the coherence order and propagates to C before the
second event executes.
This is best explained with some examples. The simplest case looks
-like this:
+like this::
int x;
@@ -1225,7 +1234,7 @@ event, because P1's store came after P0's store in x's coherence
order, and P1's store propagated to P0 before P0's load executed.
An equally simple case involves two loads of the same location that
-read from different stores:
+read from different stores::
int x = 0;
@@ -1252,7 +1261,7 @@ P1's store propagated to P0 before P0's second load executed.
Less trivial examples of prop all involve fences. Unlike the simple
examples above, they can require that some instructions are executed
-out of program order. This next one should look familiar:
+out of program order. This next one should look familiar::
int buf = 0, flag = 0;
@@ -1303,7 +1312,7 @@ rfe link. You can concoct more exotic examples, containing more than
one fence, although this quickly leads to diminishing returns in terms
of complexity. For instance, here's an example containing a coe link
followed by two fences and an rfe link, utilizing the fact that
-release fences are A-cumulative:
+release fences are A-cumulative::
int x, y, z;
@@ -1363,7 +1372,7 @@ links. Let's see how this definition works out.
Consider first the case where E is a store (implying that the sequence
of links begins with coe). Then there are events W, X, Y, and Z such
-that:
+that::
E ->coe W ->cumul-fence* X ->rfe? Y ->strong-fence Z ->hb* F,
@@ -1384,13 +1393,13 @@ The existence of a pb link from E to F implies that E must execute
before F. To see why, suppose that F executed first. Then W would
have propagated to E's CPU before E executed. If E was a store, the
memory subsystem would then be forced to make E come after W in the
-coherence order, contradicting the fact that E ->coe W. If E was a
+coherence order, contradicting the fact that ``E ->coe W``. If E was a
load, the memory subsystem would then be forced to satisfy E's read
request with the value stored by W or an even later store,
-contradicting the fact that E ->fre W.
+contradicting the fact that ``E ->fre W``.
A good example illustrating how pb works is the SB pattern with strong
-fences:
+fences::
int x = 0, y = 0;
@@ -1449,18 +1458,18 @@ span a full grace period. In more detail, the Guarantee says:
For any critical section C and any grace period G, at least
one of the following statements must hold:
-(1) C ends before G does, and in addition, every store that
- propagates to C's CPU before the end of C must propagate to
- every CPU before G ends.
+ (1) C ends before G does, and in addition, every store that
+ propagates to C's CPU before the end of C must propagate to
+ every CPU before G ends.
-(2) G starts before C does, and in addition, every store that
- propagates to G's CPU before the start of G must propagate
- to every CPU before C starts.
+ (2) G starts before C does, and in addition, every store that
+ propagates to G's CPU before the start of G must propagate
+ to every CPU before C starts.
In particular, it is not possible for a critical section to both start
before and end after a grace period.
-Here is a simple example of RCU in action:
+Here is a simple example of RCU in action::
int x, y;
@@ -1509,9 +1518,9 @@ entirely clear. The LKMM formalizes this notion by means of the
rcu-link relation. rcu-link encompasses a very general notion of
"before": If E and F are RCU fence events (i.e., rcu_read_lock(),
rcu_read_unlock(), or synchronize_rcu()) then among other things,
-E ->rcu-link F includes cases where E is po-before some memory-access
+``E ->rcu-link F`` includes cases where E is po-before some memory-access
event X, F is po-after some memory-access event Y, and we have any of
-X ->rfe Y, X ->co Y, or X ->fr Y.
+``X ->rfe Y``, ``X ->co Y``, or ``X ->fr Y``.
The formal definition of the rcu-link relation is more than a little
obscure, and we won't give it here. It is closely related to the pb
@@ -1523,50 +1532,50 @@ The LKMM also defines the rcu-gp and rcu-rscsi relations. They bring
grace periods and read-side critical sections into the picture, in the
following way:
- E ->rcu-gp F means that E and F are in fact the same event,
+ ``E ->rcu-gp F`` means that E and F are in fact the same event,
and that event is a synchronize_rcu() fence (i.e., a grace
period).
- E ->rcu-rscsi F means that E and F are the rcu_read_unlock()
+ ``E ->rcu-rscsi F`` means that E and F are the rcu_read_unlock()
and rcu_read_lock() fence events delimiting some read-side
critical section. (The 'i' at the end of the name emphasizes
that this relation is "inverted": It links the end of the
critical section to the start.)
If we think of the rcu-link relation as standing for an extended
-"before", then X ->rcu-gp Y ->rcu-link Z roughly says that X is a
+"before", then ``X ->rcu-gp Y ->rcu-link Z`` roughly says that X is a
grace period which ends before Z begins. (In fact it covers more than
this, because it also includes cases where some store propagates to
Z's CPU before Z begins but doesn't propagate to some other CPU until
-after X ends.) Similarly, X ->rcu-rscsi Y ->rcu-link Z says that X is
+after X ends.) Similarly, ``X ->rcu-rscsi Y ->rcu-link Z`` says that X is
the end of a critical section which starts before Z begins.
The LKMM goes on to define the rcu-fence relation as a sequence of
rcu-gp and rcu-rscsi links separated by rcu-link links, in which the
number of rcu-gp links is >= the number of rcu-rscsi links. For
-example:
+example::
X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
-would imply that X ->rcu-fence V, because this sequence contains two
+would imply that ``X ->rcu-fence V``, because this sequence contains two
rcu-gp links and one rcu-rscsi link. (It also implies that
-X ->rcu-fence T and Z ->rcu-fence V.) On the other hand:
+``X ->rcu-fence T`` and ``Z ->rcu-fence V``.) On the other hand::
X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
-does not imply X ->rcu-fence V, because the sequence contains only
+does not imply ``X ->rcu-fence V``, because the sequence contains only
one rcu-gp link but two rcu-rscsi links.
The rcu-fence relation is important because the Grace Period Guarantee
means that rcu-fence acts kind of like a strong fence. In particular,
-E ->rcu-fence F implies not only that E begins before F ends, but also
+``E ->rcu-fence F`` implies not only that E begins before F ends, but also
that any write po-before E will propagate to every CPU before any
instruction po-after F can execute. (However, it does not imply that
E must execute before F; in fact, each synchronize_rcu() fence event
is linked to itself by rcu-fence as a degenerate case.)
To prove this in full generality requires some intellectual effort.
-We'll consider just a very simple case:
+We'll consider just a very simple case::
G ->rcu-gp W ->rcu-link Z ->rcu-rscsi F.
@@ -1595,13 +1604,13 @@ covered by rcu-fence.
Finally, the LKMM defines the RCU-before (rb) relation in terms of
rcu-fence. This is done in essentially the same way as the pb
relation was defined in terms of strong-fence. We will omit the
-details; the end result is that E ->rb F implies E must execute
-before F, just as E ->pb F does (and for much the same reasons).
+details; the end result is that ``E ->rb F`` implies E must execute
+before F, just as ``E ->pb F`` does (and for much the same reasons).
Putting this all together, the LKMM expresses the Grace Period
Guarantee by requiring that the rb relation does not contain a cycle.
Equivalently, this "rcu" axiom requires that there are no events E
-and F with E ->rcu-link F ->rcu-fence E. Or to put it a third way,
+and F with ``E ->rcu-link F ->rcu-fence E``. Or to put it a third way,
the axiom requires that there are no cycles consisting of rcu-gp and
rcu-rscsi alternating with rcu-link, where the number of rcu-gp links
is >= the number of rcu-rscsi links.
@@ -1621,7 +1630,7 @@ question, and let S be the synchronize_rcu() fence event for the grace
period. Saying that the critical section starts before S means there
are events Q and R where Q is po-after L (which marks the start of the
critical section), Q is "before" R in the sense used by the rcu-link
-relation, and R is po-before the grace period S. Thus we have:
+relation, and R is po-before the grace period S. Thus we have::
L ->rcu-link S.
@@ -1629,20 +1638,20 @@ Let W be the store mentioned above, let Y come before the end of the
critical section and witness that W propagates to the critical
section's CPU by reading from W, and let Z on some arbitrary CPU be a
witness that W has not propagated to that CPU, where Z happens after
-some event X which is po-after S. Symbolically, this amounts to:
+some event X which is po-after S. Symbolically, this amounts to::
S ->po X ->hb* Z ->fr W ->rf Y ->po U.
The fr link from Z to W indicates that W has not propagated to Z's CPU
at the time that Z executes. From this, it can be shown (see the
discussion of the rcu-link relation earlier) that S and U are related
-by rcu-link:
+by rcu-link::
S ->rcu-link U.
-Since S is a grace period we have S ->rcu-gp S, and since L and U are
-the start and end of the critical section C we have U ->rcu-rscsi L.
-From this we obtain:
+Since S is a grace period we have ``S ->rcu-gp S``, and since L and U are
+the start and end of the critical section C we have ``U ->rcu-rscsi L``.
+From this we obtain::
S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
@@ -1651,7 +1660,7 @@ the Grace Period Guarantee.
For something a little more down-to-earth, let's see how the axiom
works out in practice. Consider the RCU code example from above, this
-time with statement labels added:
+time with statement labels added::
int x, y;
@@ -1674,20 +1683,20 @@ time with statement labels added:
If r2 = 0 at the end then P0's store at Y overwrites the value that
-P1's load at W reads from, so we have W ->fre Y. Since S ->po W and
-also Y ->po U, we get S ->rcu-link U. In addition, S ->rcu-gp S
+P1's load at W reads from, so we have ``W ->fre Y``. Since ``S ->po W`` and
+also ``Y ->po U``, we get ``S ->rcu-link U``. In addition, ``S ->rcu-gp S``
because S is a grace period.
If r1 = 1 at the end then P1's load at Z reads from P0's store at X,
-so we have X ->rfe Z. Together with L ->po X and Z ->po S, this
-yields L ->rcu-link S. And since L and U are the start and end of a
-critical section, we have U ->rcu-rscsi L.
+so we have ``X ->rfe Z``. Together with ``L ->po X`` and ``Z ->po S``, this
+yields ``L ->rcu-link S``. And since L and U are the start and end of a
+critical section, we have ``U ->rcu-rscsi L``.
-Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
+Then ``U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U`` is a
forbidden cycle, violating the "rcu" axiom. Hence the outcome is not
allowed by the LKMM, as we would expect.
-For contrast, let's see what can happen in a more complicated example:
+For contrast, let's see what can happen in a more complicated example::
int x, y, z;
@@ -1720,28 +1729,28 @@ For contrast, let's see what can happen in a more complicated example:
U2: rcu_read_unlock();
}
-If r0 = r1 = r2 = 1 at the end, then similar reasoning to before shows
-that U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
-L2 ->rcu-link U0. However this cycle is not forbidden, because the
+If ``r0 = r1 = r2 = 1`` at the end, then similar reasoning to before shows
+that ``U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
+L2 ->rcu-link U0``. However this cycle is not forbidden, because the
sequence of relations contains fewer instances of rcu-gp (one) than of
rcu-rscsi (two). Consequently the outcome is allowed by the LKMM.
The following instruction timing diagram shows how it might actually
-occur:
-
-P0 P1 P2
--------------------- -------------------- --------------------
-rcu_read_lock()
-WRITE_ONCE(y, 1)
- r1 = READ_ONCE(y)
- synchronize_rcu() starts
- . rcu_read_lock()
- . WRITE_ONCE(x, 1)
-r0 = READ_ONCE(x) .
-rcu_read_unlock() .
- synchronize_rcu() ends
- WRITE_ONCE(z, 1)
- r2 = READ_ONCE(z)
- rcu_read_unlock()
+occur::
+
+ P0 P1 P2
+ -------------------- -------------------- --------------------
+ rcu_read_lock()
+ WRITE_ONCE(y, 1)
+ r1 = READ_ONCE(y)
+ synchronize_rcu() starts
+ . rcu_read_lock()
+ . WRITE_ONCE(x, 1)
+ r0 = READ_ONCE(x) .
+ rcu_read_unlock() .
+ synchronize_rcu() ends
+ WRITE_ONCE(z, 1)
+ r2 = READ_ONCE(z)
+ rcu_read_unlock()
This requires P0 and P2 to execute their loads and stores out of
program order, but of course they are allowed to do so. And as you
@@ -1767,26 +1776,26 @@ The LKMM includes locking. In fact, there is special code for locking
in the formal model, added in order to make tools run faster.
However, this special code is intended to be more or less equivalent
to concepts we have already covered. A spinlock_t variable is treated
-the same as an int, and spin_lock(&s) is treated almost the same as:
+the same as an int, and spin_lock(&s) is treated almost the same as::
while (cmpxchg_acquire(&s, 0, 1) != 0)
cpu_relax();
This waits until s is equal to 0 and then atomically sets it to 1,
and the read part of the cmpxchg operation acts as an acquire fence.
-An alternate way to express the same thing would be:
+An alternate way to express the same thing would be::
r = xchg_acquire(&s, 1);
along with a requirement that at the end, r = 0. Similarly,
-spin_trylock(&s) is treated almost the same as:
+spin_trylock(&s) is treated almost the same as::
return !cmpxchg_acquire(&s, 0, 1);
which atomically sets s to 1 if it is currently equal to 0 and returns
true if it succeeds (the read part of the cmpxchg operation acts as an
acquire fence only if the operation is successful). spin_unlock(&s)
-is treated almost the same as:
+is treated almost the same as::
smp_store_release(&s, 0);
@@ -1802,7 +1811,7 @@ requires that every instruction po-before the lock-release must
execute before any instruction po-after the lock-acquire. This would
naturally hold if the release and acquire operations were on different
CPUs, but the LKMM says it holds even when they are on the same CPU.
-For example:
+For example::
int x, y;
spinlock_t s;
@@ -1833,7 +1842,7 @@ MP pattern).
This requirement does not apply to ordinary release and acquire
fences, only to lock-related operations. For instance, suppose P0()
-in the example had been written as:
+in the example had been written as::
P0()
{
@@ -1847,7 +1856,7 @@ in the example had been written as:
Then the CPU would be allowed to forward the s = 1 value from the
smp_store_release() to the smp_load_acquire(), executing the
-instructions in the following order:
+instructions in the following order::
r3 = smp_load_acquire(&s); // Obtains r3 = 1
r2 = READ_ONCE(y);
@@ -1859,7 +1868,7 @@ and thus it could load y before x, obtaining r2 = 0 and r1 = 1.
Second, when a lock-acquire reads from a lock-release, and some other
stores W and W' occur po-before the lock-release and po-after the
lock-acquire respectively, the LKMM requires that W must propagate to
-each CPU before W' does. For example, consider:
+each CPU before W' does. For example, consider::
int x, y;
spinlock_t x;
@@ -1928,7 +1937,7 @@ smp_store_release().) The final effect is the same.
Although we didn't mention it above, the instruction execution
ordering provided by the smp_rmb() fence doesn't apply to read events
that are part of a non-value-returning atomic update. For instance,
-given:
+given::
atomic_inc(&x);
smp_rmb();
@@ -1967,14 +1976,14 @@ they behave as follows:
events.
Interestingly, RCU and locking each introduce the possibility of
-deadlock. When faced with code sequences such as:
+deadlock. When faced with code sequences such as::
spin_lock(&s);
spin_lock(&s);
spin_unlock(&s);
spin_unlock(&s);
-or:
+or::
rcu_read_lock();
synchronize_rcu();
@@ -1984,7 +1993,7 @@ what does the LKMM have to say? Answer: It says there are no allowed
executions at all, which makes sense. But this can also lead to
misleading results, because if a piece of code has multiple possible
executions, some of which deadlock, the model will report only on the
-non-deadlocking executions. For example:
+non-deadlocking executions. For example::
int x, y;
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..0e53d83a5a48
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Linux Memory Model Tools
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ explanation
+ recipes
+ references
+ cheatsheet
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.rst
similarity index 96%
rename from tools/memory-model/Documentation/recipes.txt
rename to tools/memory-model/Documentation/recipes.rst
index 7fe8d7aa3029..0229a431b1a2 100644
--- a/tools/memory-model/Documentation/recipes.txt
+++ b/tools/memory-model/Documentation/recipes.rst
@@ -1,3 +1,8 @@
+=======
+Recipes
+=======
+
+
This document provides "recipes", that is, litmus tests for commonly
occurring situations, as well as a few that illustrate subtly broken but
attractive nuisances. Many of these recipes include example code from
@@ -67,7 +72,7 @@ has acquired a given lock sees any changes previously seen or made by any
CPU before it released that same lock. Note that this statement is a bit
stronger than "Any CPU holding a given lock sees all changes made by any
CPU during the time that CPU was holding this same lock". For example,
-consider the following pair of code fragments:
+consider the following pair of code fragments::
/* See MP+polocks.litmus. */
void CPU0(void)
@@ -93,7 +98,7 @@ value of r1 must also be equal to 1. In contrast, the weaker rule would
say nothing about the final value of r1.
The converse to the basic rule also holds, as illustrated by the
-following litmus test:
+following litmus test::
/* See MP+porevlocks.litmus. */
void CPU0(void)
@@ -124,7 +129,7 @@ across multiple CPUs.
However, it is not necessarily the case that accesses ordered by
locking will be seen as ordered by CPUs not holding that lock.
-Consider this example:
+Consider this example::
/* See Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus. */
void CPU0(void)
@@ -157,7 +162,7 @@ CPU2() never acquired the lock, and thus did not benefit from the
lock's ordering properties.
Ordering can be extended to CPUs not holding the lock by careful use
-of smp_mb__after_spinlock():
+of smp_mb__after_spinlock()::
/* See Z6.0+pooncelock+poonceLock+pombonce.litmus. */
void CPU0(void)
@@ -214,7 +219,7 @@ Release and acquire
~~~~~~~~~~~~~~~~~~~
Use of smp_store_release() and smp_load_acquire() is one way to force
-the desired MP ordering. The general approach is shown below:
+the desired MP ordering. The general approach is shown below::
/* See MP+pooncerelease+poacquireonce.litmus. */
void CPU0(void)
@@ -245,7 +250,7 @@ Assign and dereference
Use of rcu_assign_pointer() and rcu_dereference() is quite similar to the
use of smp_store_release() and smp_load_acquire(), except that both
rcu_assign_pointer() and rcu_dereference() operate on RCU-protected
-pointers. The general approach is shown below:
+pointers. The general approach is shown below::
/* See MP+onceassign+derefonce.litmus. */
int z;
@@ -290,7 +295,7 @@ Write and read memory barriers
It is usually better to use smp_store_release() instead of smp_wmb()
and to use smp_load_acquire() instead of smp_rmb(). However, the older
smp_wmb() and smp_rmb() APIs are still heavily used, so it is important
-to understand their use cases. The general approach is shown below:
+to understand their use cases. The general approach is shown below::
/* See MP+fencewmbonceonce+fencermbonceonce.litmus. */
void CPU0(void)
@@ -312,7 +317,7 @@ smp_rmb() macro orders prior loads against later loads. Therefore, if
the final value of r0 is 1, the final value of r1 must also be 1.
The xlog_state_switch_iclogs() function in fs/xfs/xfs_log.c contains
-the following write-side code fragment:
+the following write-side code fragment::
log->l_curr_block -= log->l_logBBsize;
ASSERT(log->l_curr_block >= 0);
@@ -327,7 +332,7 @@ the corresponding read-side code fragment:
cur_block = READ_ONCE(log->l_curr_block);
Alternatively, consider the following comment in function
-perf_output_put_handle() in kernel/events/ring_buffer.c:
+perf_output_put_handle() in kernel/events/ring_buffer.c::
* kernel user
*
@@ -358,7 +363,7 @@ absence of any ordering it is quite possible that this may happen, as
can be seen in the LB+poonceonces.litmus litmus test.
One way of avoiding the counter-intuitive outcome is through the use of a
-control dependency paired with a full memory barrier:
+control dependency paired with a full memory barrier::
/* See LB+fencembonceonce+ctrlonceonce.litmus. */
void CPU0(void)
@@ -382,7 +387,7 @@ The A/D pairing from the ring-buffer use case shown earlier also
illustrates LB. Here is a repeat of the comment in
perf_output_put_handle() in kernel/events/ring_buffer.c, showing a
control dependency on the kernel side and a full memory barrier on
-the user side:
+the user side::
* kernel user
*
@@ -407,7 +412,7 @@ Release-acquire chains
Release-acquire chains are a low-overhead, flexible, and easy-to-use
method of maintaining order. However, they do have some limitations that
-need to be fully understood. Here is an example that maintains order:
+need to be fully understood. Here is an example that maintains order::
/* See ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus. */
void CPU0(void)
@@ -436,7 +441,7 @@ example, ordering would still be preserved if CPU1()'s smp_load_acquire()
invocation was replaced with READ_ONCE().
It is tempting to assume that CPU0()'s store to x is globally ordered
-before CPU1()'s store to z, but this is not the case:
+before CPU1()'s store to z, but this is not the case::
/* See Z6.0+pooncerelease+poacquirerelease+mbonceonce.litmus. */
void CPU0(void)
@@ -474,7 +479,7 @@ Store buffering
Store buffering can be thought of as upside-down load buffering, so
that one CPU first stores to one variable and then loads from a second,
while another CPU stores to the second variable and then loads from the
-first. Preserving order requires nothing less than full barriers:
+first. Preserving order requires nothing less than full barriers::
/* See SB+fencembonceonces.litmus. */
void CPU0(void)
@@ -498,7 +503,7 @@ this counter-intuitive outcome.
This pattern most famously appears as part of Dekker's locking
algorithm, but it has a much more practical use within the Linux kernel
of ordering wakeups. The following comment taken from waitqueue_active()
-in include/linux/wait.h shows the canonical pattern:
+in include/linux/wait.h shows the canonical pattern::
* CPU0 - waker CPU1 - waiter
*
@@ -550,16 +555,16 @@ The strength of memory ordering required for a given litmus test to
avoid a counter-intuitive outcome depends on the types of relations
linking the memory accesses for the outcome in question:
-o If all links are write-to-read links, then the weakest
+- If all links are write-to-read links, then the weakest
possible ordering within each CPU suffices. For example, in
the LB litmus test, a control dependency was enough to do the
job.
-o If all but one of the links are write-to-read links, then a
+- If all but one of the links are write-to-read links, then a
release-acquire chain suffices. Both the MP and the ISA2
litmus tests illustrate this case.
-o If more than one of the links are something other than
+- If more than one of the links are something other than
write-to-read links, then a full memory barrier is required
between each successive pair of non-write-to-read links. This
case is illustrated by the Z6.0 litmus tests, both in the
diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.rst
similarity index 71%
rename from tools/memory-model/Documentation/references.txt
rename to tools/memory-model/Documentation/references.rst
index b177f3e4a614..275876cd10b8 100644
--- a/tools/memory-model/Documentation/references.txt
+++ b/tools/memory-model/Documentation/references.rst
@@ -1,3 +1,7 @@
+==========
+References
+==========
+
This document provides background reading for memory models and related
tools. These documents are aimed at kernel hackers who are interested
in memory models.
@@ -6,64 +10,64 @@ in memory models.
Hardware manuals and models
===========================
-o SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
+- SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
Reference Manual Version 9". SPARC International Inc.
-o Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
+- Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
Reference Manual". Compaq Computer Corporation.
-o Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
+- Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
Itanium Processor Family Memory Ordering". Intel Corporation.
-o Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
+- Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
Software Developer’s Manual". Intel Corporation.
-o Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
+- Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
and Magnus O. Myreen. 2010. "x86-TSO: A Rigorous and Usable
Programmer's Model for x86 Multiprocessors". Commun. ACM 53, 7
(July, 2010), 89-97. http://doi.acm.org/10.1145/1785414.1785443
-o IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
+- IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
Corporation.
-o ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
+- ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
ARM Ltd.
-o Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
+- Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
Derek Williams. 2011. "Understanding POWER Multiprocessors". In
Proceedings of the 32Nd ACM SIGPLAN Conference on Programming
Language Design and Implementation (PLDI ’11). ACM, New York,
NY, USA, 175–186.
-o Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
+- Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
Peter Sewell, Luc Maranget, Jade Alglave, and Derek Williams.
2012. "Synchronising C/C++ and POWER". In Proceedings of the 33rd
ACM SIGPLAN Conference on Programming Language Design and
Implementation (PLDI '12). ACM, New York, NY, USA, 311-322.
-o ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
+- ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
for ARMv8-A architecture profile)". ARM Ltd.
-o Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
+- Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
For Programmers, Volume II-A: The MIPS64(R) Instruction,
Set Reference Manual". Imagination Technologies,
LTD. https://imgtec.com/?do-download=4302.
-o Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
+- Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
Sewell. 2016. "Modelling the ARMv8 Architecture, Operationally:
Concurrency and ISA". In Proceedings of the 43rd Annual ACM
SIGPLAN-SIGACT Symposium on Principles of Programming Languages
(POPL ’16). ACM, New York, NY, USA, 608–621.
-o Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
+- Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
Luc Maranget, Kathryn E. Gray, Ali Sezgin, Mark Batty, and Peter
Sewell. 2017. "Mixed-size Concurrency: ARM, POWER, C/C++11,
and SC". In Proceedings of the 44th ACM SIGPLAN Symposium on
Principles of Programming Languages (POPL 2017). ACM, New York,
NY, USA, 429–442.
-o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
+- Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
Susmit Sarkar, and Peter Sewell. 2018. "Simplifying ARM concurrency:
multicopy-atomic axiomatic and operational models for ARMv8". In
Proceedings of the ACM on Programming Languages, Volume 2, Issue
@@ -73,18 +77,18 @@ o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
Linux-kernel memory model
=========================
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2018. "Frightening small children and disconcerting
grown-ups: Concurrency in the Linux kernel". In Proceedings of
the 23rd International Conference on Architectural Support for
Programming Languages and Operating Systems (ASPLOS 2018). ACM,
New York, NY, USA, 405-418. Webpage: http://diy.inria.fr/linux/.
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2017. "A formal kernel memory-ordering model (part 1)"
Linux Weekly News. https://lwn.net/Articles/718628/
-o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Alan Stern. 2017. "A formal kernel memory-ordering model (part 2)"
Linux Weekly News. https://lwn.net/Articles/720550/
@@ -92,16 +96,16 @@ o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
Memory-model tooling
====================
-o Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
+- Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
Notation". ACM Trans. Softw. Eng. Methodol. 11, 2 (April 2002),
256–290. http://doi.acm.org/10.1145/505145.505149
-o Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
+- Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
Cats: Modelling, Simulation, Testing, and Data Mining for Weak
Memory". ACM Trans. Program. Lang. Syst. 36, 2, Article 7 (July
2014), 7:1–7:74 pages.
-o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
+- Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
semantics of the weak consistency model specification language
cat". CoRR abs/1608.07531 (2016). http://arxiv.org/abs/1608.07531
@@ -109,6 +113,6 @@ o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
Memory-model comparisons
========================
-o Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
+- Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
Feng. 2016. "Linux-Kernel Memory Model". (6 June 2016).
http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0124r2.html.
diff --git a/tools/memory-model/README b/tools/memory-model/README
index 2b87f3971548..04bb1fa9ed76 100644
--- a/tools/memory-model/README
+++ b/tools/memory-model/README
@@ -105,16 +105,16 @@ for more information.
DESCRIPTION OF FILES
====================
-Documentation/cheatsheet.txt
+Documentation/cheatsheet.rst
Quick-reference guide to the Linux-kernel memory model.
-Documentation/explanation.txt
+Documentation/explanation.rst
Describes the memory model in detail.
-Documentation/recipes.txt
+Documentation/recipes.rst
Lists common memory-ordering patterns.
-Documentation/references.txt
+Documentation/references.rst
Provides background reading.
linux-kernel.bell
@@ -173,7 +173,7 @@ The Linux-kernel memory model has the following limitations:
of READ_ONCE() and WRITE_ONCE() limits the compiler's ability
to optimize, but there is Linux-kernel code that uses bare C
memory accesses. Handling this code is on the to-do list.
- For more information, see Documentation/explanation.txt (in
+ For more information, see Documentation/explanation.rst (in
particular, the "THE PROGRAM ORDER RELATION: po AND po-loc"
and "A WARNING" sections).
^ permalink raw reply related [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 23:00 ` Mauro Carvalho Chehab
@ 2019-07-30 23:15 ` Joel Fernandes
0 siblings, 0 replies; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 23:15 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
linux-doc
On Tue, Jul 30, 2019 at 08:00:57PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 18:21:30 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
>
> > On Tue, Jul 30, 2019 at 07:00:28PM -0300, Mauro Carvalho Chehab wrote:
> > > Em Tue, 30 Jul 2019 17:50:07 -0400
> > > Joel Fernandes <joel@joelfernandes.org> escreveu:
> > >
> > > > On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> > > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > > > There are 4 RCU articles that are written on html format.
> > > > > >
> > > > > > The way they are, they can't be part of the Linux Kernel
> > > > > > documentation body nor share the styles and pdf output.
> > > > > >
> > > > > > So, convert them to ReST format.
> > > > > >
> > > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > > documentation output that will be like the original ones, but
> > > > > > will be part of the Linux Kernel documentation body.
> > > > > >
> > > > > > Part of the conversion was done with the help of pandoc, but
> > > > > > the result had some broken things that had to be manually
> > > > > > fixed.
> > > > > >
> > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > > > >
> > > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > > sequences, for example double left quotation mark. These end up being
> > > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > > >
> > > > > Any advice on how to apply these? Should I just pull commits from
> > > > > somewhere?
> > > >
> > > > I was able to successfully apply and build this particular patch. I think
> > > > this is the only one in the series that applies to RCU.
> > > >
> > > > Sadly, I can't find the patch in any of the public archives, but I could
> > > > perhaps email it to you as an .mbox attach which 'git am' should be able to
> > > > apply.
> > > >
> > > > Mauro did say he was going to add some more details to changelog, or it could
> > > > be added when it is applied:
> > > > https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/
> > >
> > > Yeah, I'm also planning to address at least some of the issues you
> > > pointed, in order to improve the html output, but got sidetracked by something
> > > else and didn't find any time yet to finish. I'm adding some CI automation for
> > > the media subsystem in order to help us dealing with the huge amount of patches
> > > we receive there.
> > >
> > > Feel free to add those details to the changelog. I may find some spare time
> > > this week or the next one for the improvements you suggested, but those
> > > could be sent on followup patches, once done.
> >
> > Ok, I will re-send this RCU patch with the changes, leave this one to me.
> >
> > The other memory model one, needs a lot more work so we can keep that aside
> > for now till someone has the time.
>
> Yeah, feel free to do what fits best with regards to this one.
>
> If you prefer to merge it instead, I'm enclosing the last version of it,
> with that quick hack I just wrote, plus the change of the toctree for
> it to produce the 2-level index.
Ok thanks a lot Mauro! It looks much better to me now. I can probably send
this one out too to Paul after the RCU ones are in, after some more careful
review..
However, I am curious what Paul and Alan think about it since some folks such
as PeterZ actively deal with memory model stuff and probably refer a lot to
this document, but don't like ReST (unlike us) and prefer plain text editors
without any markup. Hopefully this is not the case any more..
thanks,
- Joel
> Thanks,
> Mauro
>
> [PATCH] tools: memory-model: add it to the Documentation body
>
> The books at tools/memory-model/Documentation are very well
> formatted. Congrats to the ones that wrote them!
>
> The manual conversion to ReST is really trivial:
>
> - Add document titles;
> - change the bullets on some lists;
> - mark code blocks.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
> index 976e85adffe8..7e6500a6fa76 100644
> --- a/Documentation/core-api/refcount-vs-atomic.rst
> +++ b/Documentation/core-api/refcount-vs-atomic.rst
> @@ -17,7 +17,7 @@ in order to help maintainers validate their code against the change in
> these memory ordering guarantees.
>
> The terms used through this document try to follow the formal LKMM defined in
> -tools/memory-model/Documentation/explanation.txt.
> +tools/memory-model/Documentation/explanation.rst.
>
> memory-barriers.txt and atomic_t.txt provide more background to the
> memory ordering in general and for atomic operations specifically.
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 2df5a3da563c..5123770ba77e 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
>
> admin-guide/index
> kbuild/index
> + tools/index
>
> Firmware-related documentation
> ------------------------------
> diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst
> new file mode 100644
> index 000000000000..f540d9cc75a1
> --- /dev/null
> +++ b/Documentation/tools/index.rst
> @@ -0,0 +1,17 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===========
> +Linux Tools
> +===========
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + memory-model/index
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
> new file mode 120000
> index 000000000000..020ed38ce302
> --- /dev/null
> +++ b/Documentation/tools/memory-model
> @@ -0,0 +1 @@
> +../../tools/memory-model/Documentation/
> \ No newline at end of file
> diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
> new file mode 100644
> index 000000000000..35f8749b8a53
> --- /dev/null
> +++ b/tools/memory-model/Documentation/cheatsheet.rst
> @@ -0,0 +1,36 @@
> +===========
> +Cheat Sheet
> +===========
> +
> +::
> +
> + Prior Operation Subsequent Operation
> + --------------- ---------------------------
> + C Self R W RMW Self R W DR DW RMW SV
> + -- ---- - - --- ---- - - -- -- --- --
> +
> + Store, e.g., WRITE_ONCE() Y Y
> + Load, e.g., READ_ONCE() Y Y Y Y
> + Unsuccessful RMW operation Y Y Y Y
> + rcu_dereference() Y Y Y Y
> + Successful *_acquire() R Y Y Y Y Y Y
> + Successful *_release() C Y Y Y W Y
> + smp_rmb() Y R Y Y R
> + smp_wmb() Y W Y Y W
> + smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
> + Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
> + smp_mb__before_atomic() CP Y Y Y a a a a Y
> + smp_mb__after_atomic() CP a a Y Y Y Y Y Y
> +
> +
> + Key: C: Ordering is cumulative
> + P: Ordering propagates
> + R: Read, for example, READ_ONCE(), or read portion of RMW
> + W: Write, for example, WRITE_ONCE(), or write portion of RMW
> + Y: Provides ordering
> + a: Provides ordering given intervening RMW atomic operation
> + DR: Dependent read (address dependency)
> + DW: Dependent write (address, data, or control dependency)
> + RMW: Atomic read-modify-write operation
> + SELF: Orders self, as opposed to accesses before and/or after
> + SV: Orders later accesses to the same variable
> diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
> deleted file mode 100644
> index 33ba98d72b16..000000000000
> --- a/tools/memory-model/Documentation/cheatsheet.txt
> +++ /dev/null
> @@ -1,30 +0,0 @@
> - Prior Operation Subsequent Operation
> - --------------- ---------------------------
> - C Self R W RMW Self R W DR DW RMW SV
> - -- ---- - - --- ---- - - -- -- --- --
> -
> -Store, e.g., WRITE_ONCE() Y Y
> -Load, e.g., READ_ONCE() Y Y Y Y
> -Unsuccessful RMW operation Y Y Y Y
> -rcu_dereference() Y Y Y Y
> -Successful *_acquire() R Y Y Y Y Y Y
> -Successful *_release() C Y Y Y W Y
> -smp_rmb() Y R Y Y R
> -smp_wmb() Y W Y Y W
> -smp_mb() & synchronize_rcu() CP Y Y Y Y Y Y Y Y
> -Successful full non-void RMW CP Y Y Y Y Y Y Y Y Y Y Y
> -smp_mb__before_atomic() CP Y Y Y a a a a Y
> -smp_mb__after_atomic() CP a a Y Y Y Y Y Y
> -
> -
> -Key: C: Ordering is cumulative
> - P: Ordering propagates
> - R: Read, for example, READ_ONCE(), or read portion of RMW
> - W: Write, for example, WRITE_ONCE(), or write portion of RMW
> - Y: Provides ordering
> - a: Provides ordering given intervening RMW atomic operation
> - DR: Dependent read (address dependency)
> - DW: Dependent write (address, data, or control dependency)
> - RMW: Atomic read-modify-write operation
> - SELF: Orders self, as opposed to accesses before and/or after
> - SV: Orders later accesses to the same variable
> diff --git a/tools/memory-model/Documentation/explanation.txt b/tools/memory-model/Documentation/explanation.rst
> similarity index 92%
> rename from tools/memory-model/Documentation/explanation.txt
> rename to tools/memory-model/Documentation/explanation.rst
> index 68caa9a976d0..9b5d10cef0c2 100644
> --- a/tools/memory-model/Documentation/explanation.txt
> +++ b/tools/memory-model/Documentation/explanation.rst
> @@ -1,5 +1,6 @@
> +========================================================
> Explanation of the Linux-Kernel Memory Consistency Model
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +========================================================
>
> :Author: Alan Stern <stern@rowland.harvard.edu>
> :Created: October 2017
> @@ -107,7 +108,7 @@ and the flag are memory locations shared between the two CPUs.
>
> We can abstract out the important pieces of the driver code as follows
> (the reason for using WRITE_ONCE() and READ_ONCE() instead of simple
> -assignment statements is discussed later):
> +assignment statements is discussed later)::
>
> int buf = 0, flag = 0;
>
> @@ -219,7 +220,7 @@ Ordering). This model predicts that the undesired outcome for the MP
> pattern cannot occur, but in other respects it differs from Sequential
> Consistency. One example is the Store Buffer (SB) pattern, in which
> each CPU stores to its own shared location and then loads from the
> -other CPU's location:
> +other CPU's location::
>
> int x = 0, y = 0;
>
> @@ -264,7 +265,7 @@ The counterpart to ordering is a cycle. Ordering rules out cycles:
> It's not possible to have X ordered before Y, Y ordered before Z, and
> Z ordered before X, because this would mean that X is ordered before
> itself. The analysis of the MP example under Sequential Consistency
> -involved just such an impossible cycle:
> +involved just such an impossible cycle::
>
> W: P0 stores 1 to flag executes before
> X: P1 loads 1 from flag executes before
> @@ -331,7 +332,7 @@ can think of it as the order in which statements occur in the source
> code after branches are taken into account and loops have been
> unrolled. A better description might be the order in which
> instructions are presented to a CPU's execution unit. Thus, we say
> -that X is po-before Y (written as "X ->po Y" in formulas) if X occurs
> +that X is po-before Y (written as ``X ->po Y`` in formulas) if X occurs
> before Y in the instruction stream.
>
> This is inherently a single-CPU relation; two instructions executing
> @@ -388,7 +389,7 @@ The protections provided by READ_ONCE(), WRITE_ONCE(), and others are
> not perfect; and under some circumstances it is possible for the
> compiler to undermine the memory model. Here is an example. Suppose
> both branches of an "if" statement store the same value to the same
> -location:
> +location::
>
> r1 = READ_ONCE(x);
> if (r1) {
> @@ -402,7 +403,7 @@ location:
> For this code, the LKMM predicts that the load from x will always be
> executed before either of the stores to y. However, a compiler could
> lift the stores out of the conditional, transforming the code into
> -something resembling:
> +something resembling::
>
> r1 = READ_ONCE(x);
> WRITE_ONCE(y, 2);
> @@ -418,7 +419,7 @@ model's original prediction could be invalidated by the compiler.
>
> Another issue arises from the fact that in C, arguments to many
> operators and function calls can be evaluated in any order. For
> -example:
> +example::
>
> r1 = f(5) + g(6);
>
> @@ -440,7 +441,7 @@ control (ctrl).
>
> A read and a write event are linked by a data dependency if the value
> obtained by the read affects the value stored by the write. As a very
> -simple example:
> +simple example::
>
> int x, y;
>
> @@ -455,7 +456,7 @@ values of multiple reads.
> A read event and another memory access event are linked by an address
> dependency if the value obtained by the read affects the location
> accessed by the other event. The second event can be either a read or
> -a write. Here's another simple example:
> +a write. Here's another simple example::
>
> int a[20];
> int i;
> @@ -471,7 +472,7 @@ pointer.
>
> Finally, a read event and another memory access event are linked by a
> control dependency if the value obtained by the read affects whether
> -the second event is executed at all. Simple example:
> +the second event is executed at all. Simple example::
>
> int x, y;
>
> @@ -484,9 +485,9 @@ which depends on the value obtained by the READ_ONCE(); hence there is
> a control dependency from the load to the store.
>
> It should be pretty obvious that events can only depend on reads that
> -come earlier in program order. Symbolically, if we have R ->data X,
> -R ->addr X, or R ->ctrl X (where R is a read event), then we must also
> -have R ->po X. It wouldn't make sense for a computation to depend
> +come earlier in program order. Symbolically, if we have ``R ->data X``,
> +``R ->addr X``, or ``R ->ctrl X`` (where R is a read event), then we must also
> +have ``R ->po X``. It wouldn't make sense for a computation to depend
> somehow on a value that doesn't get loaded from shared memory until
> later in the code!
>
> @@ -497,7 +498,7 @@ THE READS-FROM RELATION: rf, rfi, and rfe
> The reads-from relation (rf) links a write event to a read event when
> the value loaded by the read is the value that was stored by the
> write. In colloquial terms, the load "reads from" the store. We
> -write W ->rf R to indicate that the load R reads from the store W. We
> +write ``W ->rf R`` to indicate that the load R reads from the store W. We
> further distinguish the cases where the load and the store occur on
> the same CPU (internal reads-from, or rfi) and where they occur on
> different CPUs (external reads-from, or rfe).
> @@ -510,7 +511,7 @@ Usage of the rf relation implicitly assumes that loads will always
> read from a single store. It doesn't apply properly in the presence
> of load-tearing, where a load obtains some of its bits from one store
> and some of them from another store. Fortunately, use of READ_ONCE()
> -and WRITE_ONCE() will prevent load-tearing; it's not possible to have:
> +and WRITE_ONCE() will prevent load-tearing; it's not possible to have::
>
> int x = 0;
>
> @@ -530,7 +531,7 @@ and end up with r1 = 0x1200 (partly from x's initial value and partly
> from the value stored by P0).
>
> On the other hand, load-tearing is unavoidable when mixed-size
> -accesses are used. Consider this example:
> +accesses are used. Consider this example::
>
> union {
> u32 w;
> @@ -578,26 +579,26 @@ that value comes third, and so on.
> You can think of the coherence order as being the order in which the
> stores reach x's location in memory (or if you prefer a more
> hardware-centric view, the order in which the stores get written to
> -x's cache line). We write W ->co W' if W comes before W' in the
> +x's cache line). We write ``W ->co W'`` if W comes before W' in the
> coherence order, that is, if the value stored by W gets overwritten,
> directly or indirectly, by the value stored by W'.
>
> Coherence order is required to be consistent with program order. This
> requirement takes the form of four coherency rules:
>
> - Write-write coherence: If W ->po-loc W' (i.e., W comes before
> + Write-write coherence: If ``W ->po-loc W'`` (i.e., W comes before
> W' in program order and they access the same location), where W
> - and W' are two stores, then W ->co W'.
> + and W' are two stores, then ``W ->co W'``.
>
> - Write-read coherence: If W ->po-loc R, where W is a store and R
> + Write-read coherence: If ``W ->po-loc R``, where W is a store and R
> is a load, then R must read from W or from some other store
> which comes after W in the coherence order.
>
> - Read-write coherence: If R ->po-loc W, where R is a load and W
> + Read-write coherence: If ``R ->po-loc W``, where R is a load and W
> is a store, then the store which R reads from must come before
> W in the coherence order.
>
> - Read-read coherence: If R ->po-loc R', where R and R' are two
> + Read-read coherence: If ``R ->po-loc R'``, where R and R' are two
> loads, then either they read from the same store or else the
> store read by R comes before the store read by R' in the
> coherence order.
> @@ -612,7 +613,7 @@ requirement that every store eventually becomes visible to every CPU.)
> Any reasonable memory model will include cache coherence. Indeed, our
> expectation of cache coherence is so deeply ingrained that violations
> of its requirements look more like hardware bugs than programming
> -errors:
> +errors::
>
> int x;
>
> @@ -628,6 +629,8 @@ write-write coherence rule: Since the store of 23 comes later in
> program order, it must also come later in x's coherence order and
> thus must overwrite the store of 17.
>
> +::
> +
> int x = 0;
>
> P0()
> @@ -644,6 +647,8 @@ program order, so it must not read from that store but rather from one
> coming earlier in the coherence order (in this case, x's initial
> value).
>
> +::
> +
> int x = 0;
>
> P0()
> @@ -689,12 +694,12 @@ THE FROM-READS RELATION: fr, fri, and fre
>
> The from-reads relation (fr) can be a little difficult for people to
> grok. It describes the situation where a load reads a value that gets
> -overwritten by a store. In other words, we have R ->fr W when the
> +overwritten by a store. In other words, we have ``R ->fr W`` when the
> value that R reads is overwritten (directly or indirectly) by W, or
> equivalently, when R reads from a store which comes earlier than W in
> the coherence order.
>
> -For example:
> +For example::
>
> int x = 0;
>
> @@ -718,9 +723,11 @@ different CPUs).
>
> Note that the fr relation is determined entirely by the rf and co
> relations; it is not independent. Given a read event R and a write
> -event W for the same location, we will have R ->fr W if and only if
> +event W for the same location, we will have ``R ->fr W`` if and only if
> the write which R reads from is co-before W. In symbols,
>
> +::
> +
> (R ->fr W) := (there exists W' with W' ->rf R and W' ->co W).
>
>
> @@ -843,13 +850,13 @@ defined to link memory access events E and F whenever:
> event occurs between them in program order; or
>
> F is a release fence and some X comes before F in program order,
> - where either X = E or else E ->rf X; or
> + where either ``X = E`` or else ``E ->rf X``; or
>
> A strong fence event occurs between some X and F in program
> - order, where either X = E or else E ->rf X.
> + order, where either ``X = E`` or else ``E ->rf X``.
>
> The operational model requires that whenever W and W' are both stores
> -and W ->cumul-fence W', then W must propagate to any given CPU
> +and ``W ->cumul-fence W'``, then W must propagate to any given CPU
> before W' does. However, for different CPUs C and C', it does not
> require W to propagate to C before W' propagates to C'.
>
> @@ -903,11 +910,11 @@ first for CPU 0, then CPU 1, etc.
>
> You can check that the four coherency rules imply that the rf, co, fr,
> and po-loc relations agree with this global ordering; in other words,
> -whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
> +whenever we have ``X ->rf Y`` or ``X ->co Y`` or ``X ->fr Y`` or ``X ->po-loc Y``, the
> X event comes before the Y event in the global ordering. The LKMM's
> "coherence" axiom expresses this by requiring the union of these
> relations not to have any cycles. This means it must not be possible
> -to find events
> +to find events::
>
> X0 -> X1 -> X2 -> ... -> Xn -> X0,
>
> @@ -929,7 +936,7 @@ this case) does not get altered between the read and the write events
> making up the atomic operation. In particular, if two CPUs perform
> atomic_inc(&x) concurrently, it must be guaranteed that the final
> value of x will be the initial value plus two. We should never have
> -the following sequence of events:
> +the following sequence of events::
>
> CPU 0 loads x obtaining 13;
> CPU 1 loads x obtaining 13;
> @@ -951,6 +958,8 @@ atomic read-modify-write and W' is the write event which R reads from,
> there must not be any stores coming between W' and W in the coherence
> order. Equivalently,
>
> +::
> +
> (R ->rmw W) implies (there is no X with R ->fr X and X ->co W),
>
> where the rmw relation links the read and write events making up each
> @@ -968,7 +977,7 @@ po.
>
> The operational model already includes a description of one such
> situation: Fences are a source of ppo links. Suppose X and Y are
> -memory accesses with X ->po Y; then the CPU must execute X before Y if
> +memory accesses with ``X ->po Y``; then the CPU must execute X before Y if
> any of the following hold:
>
> A strong (smp_mb() or synchronize_rcu()) fence occurs between
> @@ -987,7 +996,7 @@ any of the following hold:
> Another possibility, not mentioned earlier but discussed in the next
> section, is:
>
> - X and Y are both loads, X ->addr Y (i.e., there is an address
> + X and Y are both loads, ``X ->addr Y`` (i.e., there is an address
> dependency from X to Y), and X is a READ_ONCE() or an atomic
> access.
>
> @@ -1021,7 +1030,7 @@ includes address dependencies to loads in the ppo relation.
>
> On the other hand, dependencies can indirectly affect the ordering of
> two loads. This happens when there is a dependency from a load to a
> -store and a second, po-later load reads from that store:
> +store and a second, po-later load reads from that store::
>
> R ->dep W ->rfi R',
>
> @@ -1036,7 +1045,7 @@ R; if the speculation turns out to be wrong then the CPU merely has to
> restart or abandon R'.
>
> (In theory, a CPU might forward a store to a load when it runs across
> -an address dependency like this:
> +an address dependency like this::
>
> r1 = READ_ONCE(ptr);
> WRITE_ONCE(*r1, 17);
> @@ -1048,7 +1057,7 @@ However, none of the architectures supported by the Linux kernel do
> this.)
>
> Two memory accesses of the same location must always be executed in
> -program order if the second access is a store. Thus, if we have
> +program order if the second access is a store. Thus, if we have::
>
> R ->po-loc W
>
> @@ -1056,7 +1065,7 @@ program order if the second access is a store. Thus, if we have
> access the same location), the CPU is obliged to execute W after R.
> If it executed W first then the memory subsystem would respond to R's
> read request with the value stored by W (or an even later store), in
> -violation of the read-write coherence rule. Similarly, if we had
> +violation of the read-write coherence rule. Similarly, if we had::
>
> W ->po-loc W'
>
> @@ -1074,7 +1083,7 @@ AND THEN THERE WAS ALPHA
>
> As mentioned above, the Alpha architecture is unique in that it does
> not appear to respect address dependencies to loads. This means that
> -code such as the following:
> +code such as the following::
>
> int x = 0;
> int y = -1;
> @@ -1128,7 +1137,7 @@ nothing at all on non-Alpha builds) after every READ_ONCE() and atomic
> load. The effect of the fence is to cause the CPU not to execute any
> po-later instructions until after the local cache has finished
> processing all the stores it has already received. Thus, if the code
> -was changed to:
> +was changed to::
>
> P1()
> {
> @@ -1167,25 +1176,25 @@ The happens-before relation (hb) links memory accesses that have to
> execute in a certain order. hb includes the ppo relation and two
> others, one of which is rfe.
>
> -W ->rfe R implies that W and R are on different CPUs. It also means
> +``W ->rfe R`` implies that W and R are on different CPUs. It also means
> that W's store must have propagated to R's CPU before R executed;
> otherwise R could not have read the value stored by W. Therefore W
> -must have executed before R, and so we have W ->hb R.
> +must have executed before R, and so we have ``W ->hb R``.
>
> -The equivalent fact need not hold if W ->rfi R (i.e., W and R are on
> +The equivalent fact need not hold if ``W ->rfi R`` (i.e., W and R are on
> the same CPU). As we have already seen, the operational model allows
> W's value to be forwarded to R in such cases, meaning that R may well
> execute before W does.
>
> It's important to understand that neither coe nor fre is included in
> hb, despite their similarities to rfe. For example, suppose we have
> -W ->coe W'. This means that W and W' are stores to the same location,
> +``W ->coe W'``. This means that W and W' are stores to the same location,
> they execute on different CPUs, and W comes before W' in the coherence
> order (i.e., W' overwrites W). Nevertheless, it is possible for W' to
> execute before W, because the decision as to which store overwrites
> the other is made later by the memory subsystem. When the stores are
> nearly simultaneous, either one can come out on top. Similarly,
> -R ->fre W means that W overwrites the value which R reads, but it
> +``R ->fre W`` means that W overwrites the value which R reads, but it
> doesn't mean that W has to execute after R. All that's necessary is
> for the memory subsystem not to propagate W to R's CPU until after R
> has executed, which is possible if W executes shortly before R.
> @@ -1199,7 +1208,7 @@ the first event in the coherence order and propagates to C before the
> second event executes.
>
> This is best explained with some examples. The simplest case looks
> -like this:
> +like this::
>
> int x;
>
> @@ -1225,7 +1234,7 @@ event, because P1's store came after P0's store in x's coherence
> order, and P1's store propagated to P0 before P0's load executed.
>
> An equally simple case involves two loads of the same location that
> -read from different stores:
> +read from different stores::
>
> int x = 0;
>
> @@ -1252,7 +1261,7 @@ P1's store propagated to P0 before P0's second load executed.
>
> Less trivial examples of prop all involve fences. Unlike the simple
> examples above, they can require that some instructions are executed
> -out of program order. This next one should look familiar:
> +out of program order. This next one should look familiar::
>
> int buf = 0, flag = 0;
>
> @@ -1303,7 +1312,7 @@ rfe link. You can concoct more exotic examples, containing more than
> one fence, although this quickly leads to diminishing returns in terms
> of complexity. For instance, here's an example containing a coe link
> followed by two fences and an rfe link, utilizing the fact that
> -release fences are A-cumulative:
> +release fences are A-cumulative::
>
> int x, y, z;
>
> @@ -1363,7 +1372,7 @@ links. Let's see how this definition works out.
>
> Consider first the case where E is a store (implying that the sequence
> of links begins with coe). Then there are events W, X, Y, and Z such
> -that:
> +that::
>
> E ->coe W ->cumul-fence* X ->rfe? Y ->strong-fence Z ->hb* F,
>
> @@ -1384,13 +1393,13 @@ The existence of a pb link from E to F implies that E must execute
> before F. To see why, suppose that F executed first. Then W would
> have propagated to E's CPU before E executed. If E was a store, the
> memory subsystem would then be forced to make E come after W in the
> -coherence order, contradicting the fact that E ->coe W. If E was a
> +coherence order, contradicting the fact that ``E ->coe W``. If E was a
> load, the memory subsystem would then be forced to satisfy E's read
> request with the value stored by W or an even later store,
> -contradicting the fact that E ->fre W.
> +contradicting the fact that ``E ->fre W``.
>
> A good example illustrating how pb works is the SB pattern with strong
> -fences:
> +fences::
>
> int x = 0, y = 0;
>
> @@ -1449,18 +1458,18 @@ span a full grace period. In more detail, the Guarantee says:
> For any critical section C and any grace period G, at least
> one of the following statements must hold:
>
> -(1) C ends before G does, and in addition, every store that
> - propagates to C's CPU before the end of C must propagate to
> - every CPU before G ends.
> + (1) C ends before G does, and in addition, every store that
> + propagates to C's CPU before the end of C must propagate to
> + every CPU before G ends.
>
> -(2) G starts before C does, and in addition, every store that
> - propagates to G's CPU before the start of G must propagate
> - to every CPU before C starts.
> + (2) G starts before C does, and in addition, every store that
> + propagates to G's CPU before the start of G must propagate
> + to every CPU before C starts.
>
> In particular, it is not possible for a critical section to both start
> before and end after a grace period.
>
> -Here is a simple example of RCU in action:
> +Here is a simple example of RCU in action::
>
> int x, y;
>
> @@ -1509,9 +1518,9 @@ entirely clear. The LKMM formalizes this notion by means of the
> rcu-link relation. rcu-link encompasses a very general notion of
> "before": If E and F are RCU fence events (i.e., rcu_read_lock(),
> rcu_read_unlock(), or synchronize_rcu()) then among other things,
> -E ->rcu-link F includes cases where E is po-before some memory-access
> +``E ->rcu-link F`` includes cases where E is po-before some memory-access
> event X, F is po-after some memory-access event Y, and we have any of
> -X ->rfe Y, X ->co Y, or X ->fr Y.
> +``X ->rfe Y``, ``X ->co Y``, or ``X ->fr Y``.
>
> The formal definition of the rcu-link relation is more than a little
> obscure, and we won't give it here. It is closely related to the pb
> @@ -1523,50 +1532,50 @@ The LKMM also defines the rcu-gp and rcu-rscsi relations. They bring
> grace periods and read-side critical sections into the picture, in the
> following way:
>
> - E ->rcu-gp F means that E and F are in fact the same event,
> + ``E ->rcu-gp F`` means that E and F are in fact the same event,
> and that event is a synchronize_rcu() fence (i.e., a grace
> period).
>
> - E ->rcu-rscsi F means that E and F are the rcu_read_unlock()
> + ``E ->rcu-rscsi F`` means that E and F are the rcu_read_unlock()
> and rcu_read_lock() fence events delimiting some read-side
> critical section. (The 'i' at the end of the name emphasizes
> that this relation is "inverted": It links the end of the
> critical section to the start.)
>
> If we think of the rcu-link relation as standing for an extended
> -"before", then X ->rcu-gp Y ->rcu-link Z roughly says that X is a
> +"before", then ``X ->rcu-gp Y ->rcu-link Z`` roughly says that X is a
> grace period which ends before Z begins. (In fact it covers more than
> this, because it also includes cases where some store propagates to
> Z's CPU before Z begins but doesn't propagate to some other CPU until
> -after X ends.) Similarly, X ->rcu-rscsi Y ->rcu-link Z says that X is
> +after X ends.) Similarly, ``X ->rcu-rscsi Y ->rcu-link Z`` says that X is
> the end of a critical section which starts before Z begins.
>
> The LKMM goes on to define the rcu-fence relation as a sequence of
> rcu-gp and rcu-rscsi links separated by rcu-link links, in which the
> number of rcu-gp links is >= the number of rcu-rscsi links. For
> -example:
> +example::
>
> X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
>
> -would imply that X ->rcu-fence V, because this sequence contains two
> +would imply that ``X ->rcu-fence V``, because this sequence contains two
> rcu-gp links and one rcu-rscsi link. (It also implies that
> -X ->rcu-fence T and Z ->rcu-fence V.) On the other hand:
> +``X ->rcu-fence T`` and ``Z ->rcu-fence V``.) On the other hand::
>
> X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
>
> -does not imply X ->rcu-fence V, because the sequence contains only
> +does not imply ``X ->rcu-fence V``, because the sequence contains only
> one rcu-gp link but two rcu-rscsi links.
>
> The rcu-fence relation is important because the Grace Period Guarantee
> means that rcu-fence acts kind of like a strong fence. In particular,
> -E ->rcu-fence F implies not only that E begins before F ends, but also
> +``E ->rcu-fence F`` implies not only that E begins before F ends, but also
> that any write po-before E will propagate to every CPU before any
> instruction po-after F can execute. (However, it does not imply that
> E must execute before F; in fact, each synchronize_rcu() fence event
> is linked to itself by rcu-fence as a degenerate case.)
>
> To prove this in full generality requires some intellectual effort.
> -We'll consider just a very simple case:
> +We'll consider just a very simple case::
>
> G ->rcu-gp W ->rcu-link Z ->rcu-rscsi F.
>
> @@ -1595,13 +1604,13 @@ covered by rcu-fence.
> Finally, the LKMM defines the RCU-before (rb) relation in terms of
> rcu-fence. This is done in essentially the same way as the pb
> relation was defined in terms of strong-fence. We will omit the
> -details; the end result is that E ->rb F implies E must execute
> -before F, just as E ->pb F does (and for much the same reasons).
> +details; the end result is that ``E ->rb F`` implies E must execute
> +before F, just as ``E ->pb F`` does (and for much the same reasons).
>
> Putting this all together, the LKMM expresses the Grace Period
> Guarantee by requiring that the rb relation does not contain a cycle.
> Equivalently, this "rcu" axiom requires that there are no events E
> -and F with E ->rcu-link F ->rcu-fence E. Or to put it a third way,
> +and F with ``E ->rcu-link F ->rcu-fence E``. Or to put it a third way,
> the axiom requires that there are no cycles consisting of rcu-gp and
> rcu-rscsi alternating with rcu-link, where the number of rcu-gp links
> is >= the number of rcu-rscsi links.
> @@ -1621,7 +1630,7 @@ question, and let S be the synchronize_rcu() fence event for the grace
> period. Saying that the critical section starts before S means there
> are events Q and R where Q is po-after L (which marks the start of the
> critical section), Q is "before" R in the sense used by the rcu-link
> -relation, and R is po-before the grace period S. Thus we have:
> +relation, and R is po-before the grace period S. Thus we have::
>
> L ->rcu-link S.
>
> @@ -1629,20 +1638,20 @@ Let W be the store mentioned above, let Y come before the end of the
> critical section and witness that W propagates to the critical
> section's CPU by reading from W, and let Z on some arbitrary CPU be a
> witness that W has not propagated to that CPU, where Z happens after
> -some event X which is po-after S. Symbolically, this amounts to:
> +some event X which is po-after S. Symbolically, this amounts to::
>
> S ->po X ->hb* Z ->fr W ->rf Y ->po U.
>
> The fr link from Z to W indicates that W has not propagated to Z's CPU
> at the time that Z executes. From this, it can be shown (see the
> discussion of the rcu-link relation earlier) that S and U are related
> -by rcu-link:
> +by rcu-link::
>
> S ->rcu-link U.
>
> -Since S is a grace period we have S ->rcu-gp S, and since L and U are
> -the start and end of the critical section C we have U ->rcu-rscsi L.
> -From this we obtain:
> +Since S is a grace period we have ``S ->rcu-gp S``, and since L and U are
> +the start and end of the critical section C we have ``U ->rcu-rscsi L``.
> +From this we obtain::
>
> S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
>
> @@ -1651,7 +1660,7 @@ the Grace Period Guarantee.
>
> For something a little more down-to-earth, let's see how the axiom
> works out in practice. Consider the RCU code example from above, this
> -time with statement labels added:
> +time with statement labels added::
>
> int x, y;
>
> @@ -1674,20 +1683,20 @@ time with statement labels added:
>
>
> If r2 = 0 at the end then P0's store at Y overwrites the value that
> -P1's load at W reads from, so we have W ->fre Y. Since S ->po W and
> -also Y ->po U, we get S ->rcu-link U. In addition, S ->rcu-gp S
> +P1's load at W reads from, so we have ``W ->fre Y``. Since ``S ->po W`` and
> +also ``Y ->po U``, we get ``S ->rcu-link U``. In addition, ``S ->rcu-gp S``
> because S is a grace period.
>
> If r1 = 1 at the end then P1's load at Z reads from P0's store at X,
> -so we have X ->rfe Z. Together with L ->po X and Z ->po S, this
> -yields L ->rcu-link S. And since L and U are the start and end of a
> -critical section, we have U ->rcu-rscsi L.
> +so we have ``X ->rfe Z``. Together with ``L ->po X`` and ``Z ->po S``, this
> +yields ``L ->rcu-link S``. And since L and U are the start and end of a
> +critical section, we have ``U ->rcu-rscsi L``.
>
> -Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
> +Then ``U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U`` is a
> forbidden cycle, violating the "rcu" axiom. Hence the outcome is not
> allowed by the LKMM, as we would expect.
>
> -For contrast, let's see what can happen in a more complicated example:
> +For contrast, let's see what can happen in a more complicated example::
>
> int x, y, z;
>
> @@ -1720,28 +1729,28 @@ For contrast, let's see what can happen in a more complicated example:
> U2: rcu_read_unlock();
> }
>
> -If r0 = r1 = r2 = 1 at the end, then similar reasoning to before shows
> -that U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
> -L2 ->rcu-link U0. However this cycle is not forbidden, because the
> +If ``r0 = r1 = r2 = 1`` at the end, then similar reasoning to before shows
> +that ``U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
> +L2 ->rcu-link U0``. However this cycle is not forbidden, because the
> sequence of relations contains fewer instances of rcu-gp (one) than of
> rcu-rscsi (two). Consequently the outcome is allowed by the LKMM.
> The following instruction timing diagram shows how it might actually
> -occur:
> -
> -P0 P1 P2
> --------------------- -------------------- --------------------
> -rcu_read_lock()
> -WRITE_ONCE(y, 1)
> - r1 = READ_ONCE(y)
> - synchronize_rcu() starts
> - . rcu_read_lock()
> - . WRITE_ONCE(x, 1)
> -r0 = READ_ONCE(x) .
> -rcu_read_unlock() .
> - synchronize_rcu() ends
> - WRITE_ONCE(z, 1)
> - r2 = READ_ONCE(z)
> - rcu_read_unlock()
> +occur::
> +
> + P0 P1 P2
> + -------------------- -------------------- --------------------
> + rcu_read_lock()
> + WRITE_ONCE(y, 1)
> + r1 = READ_ONCE(y)
> + synchronize_rcu() starts
> + . rcu_read_lock()
> + . WRITE_ONCE(x, 1)
> + r0 = READ_ONCE(x) .
> + rcu_read_unlock() .
> + synchronize_rcu() ends
> + WRITE_ONCE(z, 1)
> + r2 = READ_ONCE(z)
> + rcu_read_unlock()
>
> This requires P0 and P2 to execute their loads and stores out of
> program order, but of course they are allowed to do so. And as you
> @@ -1767,26 +1776,26 @@ The LKMM includes locking. In fact, there is special code for locking
> in the formal model, added in order to make tools run faster.
> However, this special code is intended to be more or less equivalent
> to concepts we have already covered. A spinlock_t variable is treated
> -the same as an int, and spin_lock(&s) is treated almost the same as:
> +the same as an int, and spin_lock(&s) is treated almost the same as::
>
> while (cmpxchg_acquire(&s, 0, 1) != 0)
> cpu_relax();
>
> This waits until s is equal to 0 and then atomically sets it to 1,
> and the read part of the cmpxchg operation acts as an acquire fence.
> -An alternate way to express the same thing would be:
> +An alternate way to express the same thing would be::
>
> r = xchg_acquire(&s, 1);
>
> along with a requirement that at the end, r = 0. Similarly,
> -spin_trylock(&s) is treated almost the same as:
> +spin_trylock(&s) is treated almost the same as::
>
> return !cmpxchg_acquire(&s, 0, 1);
>
> which atomically sets s to 1 if it is currently equal to 0 and returns
> true if it succeeds (the read part of the cmpxchg operation acts as an
> acquire fence only if the operation is successful). spin_unlock(&s)
> -is treated almost the same as:
> +is treated almost the same as::
>
> smp_store_release(&s, 0);
>
> @@ -1802,7 +1811,7 @@ requires that every instruction po-before the lock-release must
> execute before any instruction po-after the lock-acquire. This would
> naturally hold if the release and acquire operations were on different
> CPUs, but the LKMM says it holds even when they are on the same CPU.
> -For example:
> +For example::
>
> int x, y;
> spinlock_t s;
> @@ -1833,7 +1842,7 @@ MP pattern).
>
> This requirement does not apply to ordinary release and acquire
> fences, only to lock-related operations. For instance, suppose P0()
> -in the example had been written as:
> +in the example had been written as::
>
> P0()
> {
> @@ -1847,7 +1856,7 @@ in the example had been written as:
>
> Then the CPU would be allowed to forward the s = 1 value from the
> smp_store_release() to the smp_load_acquire(), executing the
> -instructions in the following order:
> +instructions in the following order::
>
> r3 = smp_load_acquire(&s); // Obtains r3 = 1
> r2 = READ_ONCE(y);
> @@ -1859,7 +1868,7 @@ and thus it could load y before x, obtaining r2 = 0 and r1 = 1.
> Second, when a lock-acquire reads from a lock-release, and some other
> stores W and W' occur po-before the lock-release and po-after the
> lock-acquire respectively, the LKMM requires that W must propagate to
> -each CPU before W' does. For example, consider:
> +each CPU before W' does. For example, consider::
>
> int x, y;
> spinlock_t x;
> @@ -1928,7 +1937,7 @@ smp_store_release().) The final effect is the same.
> Although we didn't mention it above, the instruction execution
> ordering provided by the smp_rmb() fence doesn't apply to read events
> that are part of a non-value-returning atomic update. For instance,
> -given:
> +given::
>
> atomic_inc(&x);
> smp_rmb();
> @@ -1967,14 +1976,14 @@ they behave as follows:
> events.
>
> Interestingly, RCU and locking each introduce the possibility of
> -deadlock. When faced with code sequences such as:
> +deadlock. When faced with code sequences such as::
>
> spin_lock(&s);
> spin_lock(&s);
> spin_unlock(&s);
> spin_unlock(&s);
>
> -or:
> +or::
>
> rcu_read_lock();
> synchronize_rcu();
> @@ -1984,7 +1993,7 @@ what does the LKMM have to say? Answer: It says there are no allowed
> executions at all, which makes sense. But this can also lead to
> misleading results, because if a piece of code has multiple possible
> executions, some of which deadlock, the model will report only on the
> -non-deadlocking executions. For example:
> +non-deadlocking executions. For example::
>
> int x, y;
>
> diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
> new file mode 100644
> index 000000000000..0e53d83a5a48
> --- /dev/null
> +++ b/tools/memory-model/Documentation/index.rst
> @@ -0,0 +1,20 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +========================
> +Linux Memory Model Tools
> +========================
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + explanation
> + recipes
> + references
> + cheatsheet
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.rst
> similarity index 96%
> rename from tools/memory-model/Documentation/recipes.txt
> rename to tools/memory-model/Documentation/recipes.rst
> index 7fe8d7aa3029..0229a431b1a2 100644
> --- a/tools/memory-model/Documentation/recipes.txt
> +++ b/tools/memory-model/Documentation/recipes.rst
> @@ -1,3 +1,8 @@
> +=======
> +Recipes
> +=======
> +
> +
> This document provides "recipes", that is, litmus tests for commonly
> occurring situations, as well as a few that illustrate subtly broken but
> attractive nuisances. Many of these recipes include example code from
> @@ -67,7 +72,7 @@ has acquired a given lock sees any changes previously seen or made by any
> CPU before it released that same lock. Note that this statement is a bit
> stronger than "Any CPU holding a given lock sees all changes made by any
> CPU during the time that CPU was holding this same lock". For example,
> -consider the following pair of code fragments:
> +consider the following pair of code fragments::
>
> /* See MP+polocks.litmus. */
> void CPU0(void)
> @@ -93,7 +98,7 @@ value of r1 must also be equal to 1. In contrast, the weaker rule would
> say nothing about the final value of r1.
>
> The converse to the basic rule also holds, as illustrated by the
> -following litmus test:
> +following litmus test::
>
> /* See MP+porevlocks.litmus. */
> void CPU0(void)
> @@ -124,7 +129,7 @@ across multiple CPUs.
>
> However, it is not necessarily the case that accesses ordered by
> locking will be seen as ordered by CPUs not holding that lock.
> -Consider this example:
> +Consider this example::
>
> /* See Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus. */
> void CPU0(void)
> @@ -157,7 +162,7 @@ CPU2() never acquired the lock, and thus did not benefit from the
> lock's ordering properties.
>
> Ordering can be extended to CPUs not holding the lock by careful use
> -of smp_mb__after_spinlock():
> +of smp_mb__after_spinlock()::
>
> /* See Z6.0+pooncelock+poonceLock+pombonce.litmus. */
> void CPU0(void)
> @@ -214,7 +219,7 @@ Release and acquire
> ~~~~~~~~~~~~~~~~~~~
>
> Use of smp_store_release() and smp_load_acquire() is one way to force
> -the desired MP ordering. The general approach is shown below:
> +the desired MP ordering. The general approach is shown below::
>
> /* See MP+pooncerelease+poacquireonce.litmus. */
> void CPU0(void)
> @@ -245,7 +250,7 @@ Assign and dereference
> Use of rcu_assign_pointer() and rcu_dereference() is quite similar to the
> use of smp_store_release() and smp_load_acquire(), except that both
> rcu_assign_pointer() and rcu_dereference() operate on RCU-protected
> -pointers. The general approach is shown below:
> +pointers. The general approach is shown below::
>
> /* See MP+onceassign+derefonce.litmus. */
> int z;
> @@ -290,7 +295,7 @@ Write and read memory barriers
> It is usually better to use smp_store_release() instead of smp_wmb()
> and to use smp_load_acquire() instead of smp_rmb(). However, the older
> smp_wmb() and smp_rmb() APIs are still heavily used, so it is important
> -to understand their use cases. The general approach is shown below:
> +to understand their use cases. The general approach is shown below::
>
> /* See MP+fencewmbonceonce+fencermbonceonce.litmus. */
> void CPU0(void)
> @@ -312,7 +317,7 @@ smp_rmb() macro orders prior loads against later loads. Therefore, if
> the final value of r0 is 1, the final value of r1 must also be 1.
>
> The xlog_state_switch_iclogs() function in fs/xfs/xfs_log.c contains
> -the following write-side code fragment:
> +the following write-side code fragment::
>
> log->l_curr_block -= log->l_logBBsize;
> ASSERT(log->l_curr_block >= 0);
> @@ -327,7 +332,7 @@ the corresponding read-side code fragment:
> cur_block = READ_ONCE(log->l_curr_block);
>
> Alternatively, consider the following comment in function
> -perf_output_put_handle() in kernel/events/ring_buffer.c:
> +perf_output_put_handle() in kernel/events/ring_buffer.c::
>
> * kernel user
> *
> @@ -358,7 +363,7 @@ absence of any ordering it is quite possible that this may happen, as
> can be seen in the LB+poonceonces.litmus litmus test.
>
> One way of avoiding the counter-intuitive outcome is through the use of a
> -control dependency paired with a full memory barrier:
> +control dependency paired with a full memory barrier::
>
> /* See LB+fencembonceonce+ctrlonceonce.litmus. */
> void CPU0(void)
> @@ -382,7 +387,7 @@ The A/D pairing from the ring-buffer use case shown earlier also
> illustrates LB. Here is a repeat of the comment in
> perf_output_put_handle() in kernel/events/ring_buffer.c, showing a
> control dependency on the kernel side and a full memory barrier on
> -the user side:
> +the user side::
>
> * kernel user
> *
> @@ -407,7 +412,7 @@ Release-acquire chains
>
> Release-acquire chains are a low-overhead, flexible, and easy-to-use
> method of maintaining order. However, they do have some limitations that
> -need to be fully understood. Here is an example that maintains order:
> +need to be fully understood. Here is an example that maintains order::
>
> /* See ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus. */
> void CPU0(void)
> @@ -436,7 +441,7 @@ example, ordering would still be preserved if CPU1()'s smp_load_acquire()
> invocation was replaced with READ_ONCE().
>
> It is tempting to assume that CPU0()'s store to x is globally ordered
> -before CPU1()'s store to z, but this is not the case:
> +before CPU1()'s store to z, but this is not the case::
>
> /* See Z6.0+pooncerelease+poacquirerelease+mbonceonce.litmus. */
> void CPU0(void)
> @@ -474,7 +479,7 @@ Store buffering
> Store buffering can be thought of as upside-down load buffering, so
> that one CPU first stores to one variable and then loads from a second,
> while another CPU stores to the second variable and then loads from the
> -first. Preserving order requires nothing less than full barriers:
> +first. Preserving order requires nothing less than full barriers::
>
> /* See SB+fencembonceonces.litmus. */
> void CPU0(void)
> @@ -498,7 +503,7 @@ this counter-intuitive outcome.
> This pattern most famously appears as part of Dekker's locking
> algorithm, but it has a much more practical use within the Linux kernel
> of ordering wakeups. The following comment taken from waitqueue_active()
> -in include/linux/wait.h shows the canonical pattern:
> +in include/linux/wait.h shows the canonical pattern::
>
> * CPU0 - waker CPU1 - waiter
> *
> @@ -550,16 +555,16 @@ The strength of memory ordering required for a given litmus test to
> avoid a counter-intuitive outcome depends on the types of relations
> linking the memory accesses for the outcome in question:
>
> -o If all links are write-to-read links, then the weakest
> +- If all links are write-to-read links, then the weakest
> possible ordering within each CPU suffices. For example, in
> the LB litmus test, a control dependency was enough to do the
> job.
>
> -o If all but one of the links are write-to-read links, then a
> +- If all but one of the links are write-to-read links, then a
> release-acquire chain suffices. Both the MP and the ISA2
> litmus tests illustrate this case.
>
> -o If more than one of the links are something other than
> +- If more than one of the links are something other than
> write-to-read links, then a full memory barrier is required
> between each successive pair of non-write-to-read links. This
> case is illustrated by the Z6.0 litmus tests, both in the
> diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.rst
> similarity index 71%
> rename from tools/memory-model/Documentation/references.txt
> rename to tools/memory-model/Documentation/references.rst
> index b177f3e4a614..275876cd10b8 100644
> --- a/tools/memory-model/Documentation/references.txt
> +++ b/tools/memory-model/Documentation/references.rst
> @@ -1,3 +1,7 @@
> +==========
> +References
> +==========
> +
> This document provides background reading for memory models and related
> tools. These documents are aimed at kernel hackers who are interested
> in memory models.
> @@ -6,64 +10,64 @@ in memory models.
> Hardware manuals and models
> ===========================
>
> -o SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
> +- SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
> Reference Manual Version 9". SPARC International Inc.
>
> -o Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
> +- Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
> Reference Manual". Compaq Computer Corporation.
>
> -o Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
> +- Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
> Itanium Processor Family Memory Ordering". Intel Corporation.
>
> -o Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
> +- Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
> Software Developer’s Manual". Intel Corporation.
>
> -o Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
> +- Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
> and Magnus O. Myreen. 2010. "x86-TSO: A Rigorous and Usable
> Programmer's Model for x86 Multiprocessors". Commun. ACM 53, 7
> (July, 2010), 89-97. http://doi.acm.org/10.1145/1785414.1785443
>
> -o IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
> +- IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
> Corporation.
>
> -o ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
> +- ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
> ARM Ltd.
>
> -o Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
> +- Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
> Derek Williams. 2011. "Understanding POWER Multiprocessors". In
> Proceedings of the 32Nd ACM SIGPLAN Conference on Programming
> Language Design and Implementation (PLDI ’11). ACM, New York,
> NY, USA, 175–186.
>
> -o Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
> +- Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
> Peter Sewell, Luc Maranget, Jade Alglave, and Derek Williams.
> 2012. "Synchronising C/C++ and POWER". In Proceedings of the 33rd
> ACM SIGPLAN Conference on Programming Language Design and
> Implementation (PLDI '12). ACM, New York, NY, USA, 311-322.
>
> -o ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
> +- ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
> for ARMv8-A architecture profile)". ARM Ltd.
>
> -o Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
> +- Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
> For Programmers, Volume II-A: The MIPS64(R) Instruction,
> Set Reference Manual". Imagination Technologies,
> LTD. https://imgtec.com/?do-download=4302.
>
> -o Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
> +- Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
> Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
> Sewell. 2016. "Modelling the ARMv8 Architecture, Operationally:
> Concurrency and ISA". In Proceedings of the 43rd Annual ACM
> SIGPLAN-SIGACT Symposium on Principles of Programming Languages
> (POPL ’16). ACM, New York, NY, USA, 608–621.
>
> -o Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
> +- Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
> Luc Maranget, Kathryn E. Gray, Ali Sezgin, Mark Batty, and Peter
> Sewell. 2017. "Mixed-size Concurrency: ARM, POWER, C/C++11,
> and SC". In Proceedings of the 44th ACM SIGPLAN Symposium on
> Principles of Programming Languages (POPL 2017). ACM, New York,
> NY, USA, 429–442.
>
> -o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
> +- Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
> Susmit Sarkar, and Peter Sewell. 2018. "Simplifying ARM concurrency:
> multicopy-atomic axiomatic and operational models for ARMv8". In
> Proceedings of the ACM on Programming Languages, Volume 2, Issue
> @@ -73,18 +77,18 @@ o Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
> Linux-kernel memory model
> =========================
>
> -o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> +- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> Alan Stern. 2018. "Frightening small children and disconcerting
> grown-ups: Concurrency in the Linux kernel". In Proceedings of
> the 23rd International Conference on Architectural Support for
> Programming Languages and Operating Systems (ASPLOS 2018). ACM,
> New York, NY, USA, 405-418. Webpage: http://diy.inria.fr/linux/.
>
> -o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> +- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> Alan Stern. 2017. "A formal kernel memory-ordering model (part 1)"
> Linux Weekly News. https://lwn.net/Articles/718628/
>
> -o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> +- Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> Alan Stern. 2017. "A formal kernel memory-ordering model (part 2)"
> Linux Weekly News. https://lwn.net/Articles/720550/
>
> @@ -92,16 +96,16 @@ o Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> Memory-model tooling
> ====================
>
> -o Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
> +- Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
> Notation". ACM Trans. Softw. Eng. Methodol. 11, 2 (April 2002),
> 256–290. http://doi.acm.org/10.1145/505145.505149
>
> -o Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
> +- Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
> Cats: Modelling, Simulation, Testing, and Data Mining for Weak
> Memory". ACM Trans. Program. Lang. Syst. 36, 2, Article 7 (July
> 2014), 7:1–7:74 pages.
>
> -o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
> +- Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
> semantics of the weak consistency model specification language
> cat". CoRR abs/1608.07531 (2016). http://arxiv.org/abs/1608.07531
>
> @@ -109,6 +113,6 @@ o Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
> Memory-model comparisons
> ========================
>
> -o Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
> +- Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
> Feng. 2016. "Linux-Kernel Memory Model". (6 June 2016).
> http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0124r2.html.
> diff --git a/tools/memory-model/README b/tools/memory-model/README
> index 2b87f3971548..04bb1fa9ed76 100644
> --- a/tools/memory-model/README
> +++ b/tools/memory-model/README
> @@ -105,16 +105,16 @@ for more information.
> DESCRIPTION OF FILES
> ====================
>
> -Documentation/cheatsheet.txt
> +Documentation/cheatsheet.rst
> Quick-reference guide to the Linux-kernel memory model.
>
> -Documentation/explanation.txt
> +Documentation/explanation.rst
> Describes the memory model in detail.
>
> -Documentation/recipes.txt
> +Documentation/recipes.rst
> Lists common memory-ordering patterns.
>
> -Documentation/references.txt
> +Documentation/references.rst
> Provides background reading.
>
> linux-kernel.bell
> @@ -173,7 +173,7 @@ The Linux-kernel memory model has the following limitations:
> of READ_ONCE() and WRITE_ONCE() limits the compiler's ability
> to optimize, but there is Linux-kernel code that uses bare C
> memory accesses. Handling this code is on the to-do list.
> - For more information, see Documentation/explanation.txt (in
> + For more information, see Documentation/explanation.rst (in
> particular, the "THE PROGRAM ORDER RELATION: po AND po-loc"
> and "A WARNING" sections).
>
>
>
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 21:50 ` Mauro Carvalho Chehab
@ 2019-07-30 23:37 ` Paul E. McKenney
2019-07-31 0:04 ` Paul E. McKenney
0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-30 23:37 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc
On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 14:22:50 -0700
> "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
>
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > There are 4 RCU articles that are written on html format.
> > >
> > > The way they are, they can't be part of the Linux Kernel
> > > documentation body nor share the styles and pdf output.
> > >
> > > So, convert them to ReST format.
> > >
> > > This way, make htmldocs and make pdfdocs will produce a
> > > documentation output that will be like the original ones, but
> > > will be part of the Linux Kernel documentation body.
> > >
> > > Part of the conversion was done with the help of pandoc, but
> > > the result had some broken things that had to be manually
> > > fixed.
> > >
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> >
> > I am having some trouble applying these, at least in part due to UTF-8
> > sequences, for example double left quotation mark. These end up being
> > "=E2=80=9C", with a few space characters turned into "=20".
> >
> > Any advice on how to apply these?
>
> Didn't notice it ended with UTF-8 chars. It is probably because it came
> from the html conversion.
Or maybe there are some email issues somewhere along the way.
> I guess it shouldn't hurt keeping those, but if you prefer I can find
> some time later to replace them.
>
> > Should I just pull commits from somewhere?
>
> Yeah, if you prefer, you can pull from this branch:
>
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
>
> It has just two patches: the RCU and tools/memory-model ones.
>
> It is based on v5.3-rc2.
And that does apply, thank you!
Thanx, Paul
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-30 23:37 ` Paul E. McKenney
@ 2019-07-31 0:04 ` Paul E. McKenney
2019-07-31 0:47 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-31 0:04 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc
On Tue, Jul 30, 2019 at 04:37:20PM -0700, Paul E. McKenney wrote:
> On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Jul 2019 14:22:50 -0700
> > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> >
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > There are 4 RCU articles that are written on html format.
> > > >
> > > > The way they are, they can't be part of the Linux Kernel
> > > > documentation body nor share the styles and pdf output.
> > > >
> > > > So, convert them to ReST format.
> > > >
> > > > This way, make htmldocs and make pdfdocs will produce a
> > > > documentation output that will be like the original ones, but
> > > > will be part of the Linux Kernel documentation body.
> > > >
> > > > Part of the conversion was done with the help of pandoc, but
> > > > the result had some broken things that had to be manually
> > > > fixed.
> > > >
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > >
> > > I am having some trouble applying these, at least in part due to UTF-8
> > > sequences, for example double left quotation mark. These end up being
> > > "=E2=80=9C", with a few space characters turned into "=20".
> > >
> > > Any advice on how to apply these?
> >
> > Didn't notice it ended with UTF-8 chars. It is probably because it came
> > from the html conversion.
>
> Or maybe there are some email issues somewhere along the way.
>
> > I guess it shouldn't hurt keeping those, but if you prefer I can find
> > some time later to replace them.
> >
> > > Should I just pull commits from somewhere?
> >
> > Yeah, if you prefer, you can pull from this branch:
> >
> > https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> >
> > It has just two patches: the RCU and tools/memory-model ones.
> >
> > It is based on v5.3-rc2.
>
> And that does apply, thank you!
And "make htmldocs" does produce real HTML! At first glance anyway,
quite impressive.
However, "make pdfdocs" gives me this complaint:
! Dimension too large.
\color@b@x ... #3}\kern \fboxsep }\dimen@ \ht \z@
\advance \dimen@ \fboxsep ...
l.5092 \end{sphinxVerbatim}
This appears to come from Documentation/output/latex/RCU.tex.
There is nevertheless an RCU.pdf in this directory. It is not
bad, but has a figure full of XML on PDF page 21. And a few later
on as well.
On the HTML side, the quick quizzes have immediately visible answers,
which defeats the purpose. The original HTML used a white font,
so that you selected the answer with your mouse to make it visible.
Can something similar be done with Sphinx? Another approach is to
gather the answers into a separate file and link to them.
I believe that Joel already noted that internal links are not working.
The external links that I tried work just fine, though. As do the
links from the table of contents.
Thanx, Paul
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-31 0:04 ` Paul E. McKenney
@ 2019-07-31 0:47 ` Mauro Carvalho Chehab
2019-07-31 1:06 ` Paul E. McKenney
0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31 0:47 UTC (permalink / raw)
To: Paul E. McKenney
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc
Em Tue, 30 Jul 2019 17:04:55 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> On Tue, Jul 30, 2019 at 04:37:20PM -0700, Paul E. McKenney wrote:
> > On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:
> > > Em Tue, 30 Jul 2019 14:22:50 -0700
> > > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> > >
> > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > > There are 4 RCU articles that are written on html format.
> > > > >
> > > > > The way they are, they can't be part of the Linux Kernel
> > > > > documentation body nor share the styles and pdf output.
> > > > >
> > > > > So, convert them to ReST format.
> > > > >
> > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > documentation output that will be like the original ones, but
> > > > > will be part of the Linux Kernel documentation body.
> > > > >
> > > > > Part of the conversion was done with the help of pandoc, but
> > > > > the result had some broken things that had to be manually
> > > > > fixed.
> > > > >
> > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > > >
> > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > sequences, for example double left quotation mark. These end up being
> > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > >
> > > > Any advice on how to apply these?
> > >
> > > Didn't notice it ended with UTF-8 chars. It is probably because it came
> > > from the html conversion.
> >
> > Or maybe there are some email issues somewhere along the way.
> >
> > > I guess it shouldn't hurt keeping those, but if you prefer I can find
> > > some time later to replace them.
> > >
> > > > Should I just pull commits from somewhere?
> > >
> > > Yeah, if you prefer, you can pull from this branch:
> > >
> > > https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> > >
> > > It has just two patches: the RCU and tools/memory-model ones.
> > >
> > > It is based on v5.3-rc2.
> >
> > And that does apply, thank you!
>
> And "make htmldocs" does produce real HTML! At first glance anyway,
> quite impressive.
Yeah, its output is pretty decent.
> However, "make pdfdocs" gives me this complaint:
>
> ! Dimension too large.
> \color@b@x ... #3}\kern \fboxsep }\dimen@ \ht \z@
> \advance \dimen@ \fboxsep ...
> l.5092 \end{sphinxVerbatim}
>
> This appears to come from Documentation/output/latex/RCU.tex.
> There is nevertheless an RCU.pdf in this directory. It is not
> bad, but has a figure full of XML on PDF page 21. And a few later
> on as well.
PDF output is indeed an issue. The way it works is that it first
generates a LaTeX and then it uses texlive to produce the PDF.
There is a rst2pdf tool with handles it directly, but it is a way more
problematic. I have an experimental patch with enables it. Maybe
some day it could be applied, but upstream for the tool needs a lot
more work.
With regards to the LaTeX/PDF output, on media, we had to tweak the
documents in order for them to produce a good LaTeX/PDF output on tables.
Usually, before some tables, we add something like this:
.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|
in order to teach LaTeX the size of each column.
If the table is really big, the only way for it to fit is to reduce
the font size, using a raw LaTeX syntax. See, for example:
Documentation/media/uapi/v4l/dev-subdev.rst
There, we use things like:
.. raw:: latex
\scriptsize
.. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|
+-----------------+ ...
| Some long table | ...
+-----------------+ ...
...
+-----------------+ ...
.. raw:: latex
\normalsize
In order to use a small font for the table.
Neither "raw:: latex" nor "tabularcolumns" tag affect html.
There is another trick too. By default, Sphinx LaTeX output uses a
type of table that should fit into a single page ("tabular").
If the table has more than 30 columns, it switches to another type
("longtable"), with can be split into multiple pages.
As the quiz tables usually have only 4 columns, it will always try
the unbreakable tabular table. If it doesn't fit, PDF will break.
In order to avoid that, just add:
.. cssclass:: longtable
Before the offended table. This will make Sphinx to use LaTeX
longtable instead of tabular ones.
This won't affect html output.
> On the HTML side, the quick quizzes have immediately visible answers,
> which defeats the purpose. The original HTML used a white font,
> so that you selected the answer with your mouse to make it visible.
>
> Can something similar be done with Sphinx? Another approach is to
> gather the answers into a separate file and link to them.
Yeah, I guess you used a css style that would make the answer visible
when the mouse is inside it on your original lwn.net set of articles.
Sphinx has a directive to use css, so, the short answer is: yes, you
can.
For html, you would need to add a css specific for the RCU quiz,
placing it under Documentation/sphinx directory. Then, use the
".. css" directive to handle that.
You should notice, however, that this will be ignored for
LaTeX/pdf output.
I guess you can place this on another file, or perhaps place at the
end of the document, having a link for the quiz answers.
Another alternative would be to make the answer as a footnote.
> I believe that Joel already noted that internal links are not working.
> The external links that I tried work just fine, though. As do the
> links from the table of contents.
Yeah. Funny enough, when I tested here, they worked fine. Maybe
this is due to the Sphinx version I used here at the time I wrote
it.
Anyway, Joel already submitted a patch addressing this one.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-31 0:47 ` Mauro Carvalho Chehab
@ 2019-07-31 1:06 ` Paul E. McKenney
2019-07-31 1:33 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-31 1:06 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc
On Tue, Jul 30, 2019 at 09:47:22PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 17:04:55 -0700
> "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
>
> > On Tue, Jul 30, 2019 at 04:37:20PM -0700, Paul E. McKenney wrote:
> > > On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:
> > > > Em Tue, 30 Jul 2019 14:22:50 -0700
> > > > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> > > >
> > > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > > > There are 4 RCU articles that are written on html format.
> > > > > >
> > > > > > The way they are, they can't be part of the Linux Kernel
> > > > > > documentation body nor share the styles and pdf output.
> > > > > >
> > > > > > So, convert them to ReST format.
> > > > > >
> > > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > > documentation output that will be like the original ones, but
> > > > > > will be part of the Linux Kernel documentation body.
> > > > > >
> > > > > > Part of the conversion was done with the help of pandoc, but
> > > > > > the result had some broken things that had to be manually
> > > > > > fixed.
> > > > > >
> > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> > > > >
> > > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > > sequences, for example double left quotation mark. These end up being
> > > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > > >
> > > > > Any advice on how to apply these?
> > > >
> > > > Didn't notice it ended with UTF-8 chars. It is probably because it came
> > > > from the html conversion.
> > >
> > > Or maybe there are some email issues somewhere along the way.
> > >
> > > > I guess it shouldn't hurt keeping those, but if you prefer I can find
> > > > some time later to replace them.
> > > >
> > > > > Should I just pull commits from somewhere?
> > > >
> > > > Yeah, if you prefer, you can pull from this branch:
> > > >
> > > > https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> > > >
> > > > It has just two patches: the RCU and tools/memory-model ones.
> > > >
> > > > It is based on v5.3-rc2.
> > >
> > > And that does apply, thank you!
> >
> > And "make htmldocs" does produce real HTML! At first glance anyway,
> > quite impressive.
>
> Yeah, its output is pretty decent.
>
> > However, "make pdfdocs" gives me this complaint:
> >
> > ! Dimension too large.
> > \color@b@x ... #3}\kern \fboxsep }\dimen@ \ht \z@
> > \advance \dimen@ \fboxsep ...
> > l.5092 \end{sphinxVerbatim}
> >
> > This appears to come from Documentation/output/latex/RCU.tex.
> > There is nevertheless an RCU.pdf in this directory. It is not
> > bad, but has a figure full of XML on PDF page 21. And a few later
> > on as well.
>
> PDF output is indeed an issue. The way it works is that it first
> generates a LaTeX and then it uses texlive to produce the PDF.
>
> There is a rst2pdf tool with handles it directly, but it is a way more
> problematic. I have an experimental patch with enables it. Maybe
> some day it could be applied, but upstream for the tool needs a lot
> more work.
>
> With regards to the LaTeX/PDF output, on media, we had to tweak the
> documents in order for them to produce a good LaTeX/PDF output on tables.
>
> Usually, before some tables, we add something like this:
>
> .. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|
>
> in order to teach LaTeX the size of each column.
>
> If the table is really big, the only way for it to fit is to reduce
> the font size, using a raw LaTeX syntax. See, for example:
>
> Documentation/media/uapi/v4l/dev-subdev.rst
>
> There, we use things like:
>
> .. raw:: latex
>
> \scriptsize
>
> .. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|
>
>
> +-----------------+ ...
> | Some long table | ...
> +-----------------+ ...
> ...
> +-----------------+ ...
>
>
> .. raw:: latex
>
> \normalsize
>
> In order to use a small font for the table.
>
> Neither "raw:: latex" nor "tabularcolumns" tag affect html.
>
> There is another trick too. By default, Sphinx LaTeX output uses a
> type of table that should fit into a single page ("tabular").
>
> If the table has more than 30 columns, it switches to another type
> ("longtable"), with can be split into multiple pages.
>
> As the quiz tables usually have only 4 columns, it will always try
> the unbreakable tabular table. If it doesn't fit, PDF will break.
>
> In order to avoid that, just add:
>
> .. cssclass:: longtable
>
> Before the offended table. This will make Sphinx to use LaTeX
> longtable instead of tabular ones.
>
> This won't affect html output.
Would it be fair to say that html output is what is currently supported,
and that PDF output is a future thing?
> > On the HTML side, the quick quizzes have immediately visible answers,
> > which defeats the purpose. The original HTML used a white font,
> > so that you selected the answer with your mouse to make it visible.
> >
> > Can something similar be done with Sphinx? Another approach is to
> > gather the answers into a separate file and link to them.
>
> Yeah, I guess you used a css style that would make the answer visible
> when the mouse is inside it on your original lwn.net set of articles.
>
> Sphinx has a directive to use css, so, the short answer is: yes, you
> can.
>
> For html, you would need to add a css specific for the RCU quiz,
> placing it under Documentation/sphinx directory. Then, use the
> ".. css" directive to handle that.
>
> You should notice, however, that this will be ignored for
> LaTeX/pdf output.
>
> I guess you can place this on another file, or perhaps place at the
> end of the document, having a link for the quiz answers.
>
> Another alternative would be to make the answer as a footnote.
Making it CSS for HTML and a footnote for PDF seems eminently
reasonable to me!
> > I believe that Joel already noted that internal links are not working.
> > The external links that I tried work just fine, though. As do the
> > links from the table of contents.
>
> Yeah. Funny enough, when I tested here, they worked fine. Maybe
> this is due to the Sphinx version I used here at the time I wrote
> it.
>
> Anyway, Joel already submitted a patch addressing this one.
And it works for me, anyway! ;-)
Thanx, Paul
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
2019-07-31 1:06 ` Paul E. McKenney
@ 2019-07-31 1:33 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31 1:33 UTC (permalink / raw)
To: Paul E. McKenney
Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
Joel Fernandes, Jonathan Corbet, rcu, linux-doc
Em Tue, 30 Jul 2019 18:06:24 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> On Tue, Jul 30, 2019 at 09:47:22PM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Jul 2019 17:04:55 -0700
> > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> > > This appears to come from Documentation/output/latex/RCU.tex.
> > > There is nevertheless an RCU.pdf in this directory. It is not
> > > bad, but has a figure full of XML on PDF page 21. And a few later
> > > on as well.
> >
> > PDF output is indeed an issue. The way it works is that it first
> > generates a LaTeX and then it uses texlive to produce the PDF.
>
> Would it be fair to say that html output is what is currently supported,
> and that PDF output is a future thing?
Sure.
Anyway, if you want to fix PDF later, I suspect that simply adding:
.. cssclass:: longtable
Before each quiz table should be enough to fix, as the tables there seem
to be simple enough.
After fixed, the PDF and LaTeX output are usually decent.
> > > On the HTML side, the quick quizzes have immediately visible answers,
> > > which defeats the purpose. The original HTML used a white font,
> > > so that you selected the answer with your mouse to make it visible.
> > >
> > > Can something similar be done with Sphinx? Another approach is to
> > > gather the answers into a separate file and link to them.
> >
> > Yeah, I guess you used a css style that would make the answer visible
> > when the mouse is inside it on your original lwn.net set of articles.
> >
> > Sphinx has a directive to use css, so, the short answer is: yes, you
> > can.
> >
> > For html, you would need to add a css specific for the RCU quiz,
> > placing it under Documentation/sphinx directory. Then, use the
> > ".. css" directive to handle that.
> >
> > You should notice, however, that this will be ignored for
> > LaTeX/pdf output.
> >
> > I guess you can place this on another file, or perhaps place at the
> > end of the document, having a link for the quiz answers.
> >
> > Another alternative would be to make the answer as a footnote.
>
> Making it CSS for HTML and a footnote for PDF seems eminently
> reasonable to me!
You should either do CSS or PDF, as otherwise you will end with dirty
hacks like:
.. only:: html
<some quiz table with answers using css>
.. only: latex
<some quiz table with answers using footnotes>
E. g. you'll need to place the quiz twice, making it harder to maintain
and messier.
Btw, the LaTeX may also parse a css tag, processing it via some custom
macro (with should be added at Documentation/conf.py.
> > > I believe that Joel already noted that internal links are not working.
> > > The external links that I tried work just fine, though. As do the
> > > links from the table of contents.
> >
> > Yeah. Funny enough, when I tested here, they worked fine. Maybe
> > this is due to the Sphinx version I used here at the time I wrote
> > it.
> >
> > Anyway, Joel already submitted a patch addressing this one.
>
> And it works for me, anyway! ;-)
Great!
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-30 22:57 ` Mauro Carvalho Chehab
@ 2019-07-31 13:52 ` Alan Stern
0 siblings, 0 replies; 75+ messages in thread
From: Alan Stern @ 2019-07-31 13:52 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 18:17:01 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
> > > > (4) I would argue that every occurence of
> > > > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > > > results.
> > >
> > > Just place those with ``A -> (some dependency)``. This will make them use
> > > a fixed size font.
> >
> > Ok, understood all these. I guess my point was all of these will need to be
> > done to make this document useful from a ReST conversion standpoint. Until
> > then it is probably just better off being plain text - since there are so
> > many of those ``A -> (dep) B`` things.
> On a very quick look, it seems that, if we replace:
>
> (\S+\s->\S*\s\w+)
>
> by:
> ``\1``
>
>
> On an editor that would allow to manually replace the regex (like kate),
> most of those can be get.
>
> See patch enclosed.
Some time ago I considered the problem of converting this file to ReST
format. But I gave up on the idea, because the necessary changes were
so widespread and the resulting text file would not be easily readable.
Replacing things of the form "A ->dep B" just scratches the surface.
That document teems with variable names, formulas, code extracts, and
other things which would all need to be rendered in a different font
style. The density of the markup required to do this would be
phenomenally high.
In my opinion it simply was not worthwhile.
Alan Stern
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
@ 2019-07-31 13:52 ` Alan Stern
0 siblings, 0 replies; 75+ messages in thread
From: Alan Stern @ 2019-07-31 13:52 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
linux-arch
On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 18:17:01 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
> > > > (4) I would argue that every occurence of
> > > > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > > > results.
> > >
> > > Just place those with ``A -> (some dependency)``. This will make them use
> > > a fixed size font.
> >
> > Ok, understood all these. I guess my point was all of these will need to be
> > done to make this document useful from a ReST conversion standpoint. Until
> > then it is probably just better off being plain text - since there are so
> > many of those ``A -> (dep) B`` things.
> On a very quick look, it seems that, if we replace:
>
> (\S+\s->\S*\s\w+)
>
> by:
> ``\1``
>
>
> On an editor that would allow to manually replace the regex (like kate),
> most of those can be get.
>
> See patch enclosed.
Some time ago I considered the problem of converting this file to ReST
format. But I gave up on the idea, because the necessary changes were
so widespread and the resulting text file would not be easily readable.
Replacing things of the form "A ->dep B" just scratches the surface.
That document teems with variable names, formulas, code extracts, and
other things which would all need to be rendered in a different font
style. The density of the markup required to do this would be
phenomenally high.
In my opinion it simply was not worthwhile.
Alan Stern
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-31 13:52 ` Alan Stern
(?)
@ 2019-07-31 15:19 ` Akira Yokosawa
2019-07-31 20:25 ` Paul E. McKenney
-1 siblings, 1 reply; 75+ messages in thread
From: Akira Yokosawa @ 2019-07-31 15:19 UTC (permalink / raw)
To: Alan Stern, Mauro Carvalho Chehab
Cc: Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
Jade Alglave, Luc Maranget, Paul E. McKenney, Daniel Lustig,
Ingo Molnar, Jason Gunthorpe, SeongJae Park, linux-arch
On Wed, 31 Jul 2019 09:52:05 -0400, Alan Stern wrote:
> On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:
>
>> Em Tue, 30 Jul 2019 18:17:01 -0400
>> Joel Fernandes <joel@joelfernandes.org> escreveu:
>
>>>>> (4) I would argue that every occurence of
>>>>> A ->(some dependency) B should be replaced with fixed size font in the HTML
>>>>> results.
>>>>
>>>> Just place those with ``A -> (some dependency)``. This will make them use
>>>> a fixed size font.
>>>
>>> Ok, understood all these. I guess my point was all of these will need to be
>>> done to make this document useful from a ReST conversion standpoint. Until
>>> then it is probably just better off being plain text - since there are so
>>> many of those ``A -> (dep) B`` things.
>
>> On a very quick look, it seems that, if we replace:
>>
>> (\S+\s->\S*\s\w+)
>>
>> by:
>> ``\1``
>>
>>
>> On an editor that would allow to manually replace the regex (like kate),
>> most of those can be get.
>>
>> See patch enclosed.
>
> Some time ago I considered the problem of converting this file to ReST
> format. But I gave up on the idea, because the necessary changes were
> so widespread and the resulting text file would not be easily readable.
>
> Replacing things of the form "A ->dep B" just scratches the surface.
> That document teems with variable names, formulas, code extracts, and
> other things which would all need to be rendered in a different font
> style. The density of the markup required to do this would be
> phenomenally high.
>
> In my opinion it simply was not worthwhile.
+1 on keeping this and the other .txt files of LKMM intact.
Thanks, Akira
>
> Alan Stern
>
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
2019-07-26 12:51 ` [PATCH v2 01/26] docs: power: add it to to the main documentation index Mauro Carvalho Chehab
@ 2019-07-31 19:03 ` Jonathan Corbet
2019-07-31 19:16 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Jonathan Corbet @ 2019-07-31 19:03 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm
On Fri, 26 Jul 2019 09:51:11 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> The power docs are orphaned at the documentation body.
>
> While it could likely be moved to be inside some guide, I'm opting to just
> adding it to the main index.rst, removing the :orphan: and adding the SPDX
> header.
>
> The reason is similar to what it was done for other driver-specific
> subsystems: the docs there contain a mix of Kernelspace, uAPI and
> admin-guide. So, better to keep them on its own directory,
> while the docs there are not properly classified.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
So this one went upstream with the PDF fixes pull, right? I'm a little
surprised to see it here now.
Thanks,
jon
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
2019-07-31 19:03 ` Jonathan Corbet
@ 2019-07-31 19:16 ` Mauro Carvalho Chehab
2019-07-31 19:34 ` Jonathan Corbet
0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31 19:16 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm
Em Wed, 31 Jul 2019 13:03:38 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Fri, 26 Jul 2019 09:51:11 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > The power docs are orphaned at the documentation body.
> >
> > While it could likely be moved to be inside some guide, I'm opting to just
> > adding it to the main index.rst, removing the :orphan: and adding the SPDX
> > header.
> >
> > The reason is similar to what it was done for other driver-specific
> > subsystems: the docs there contain a mix of Kernelspace, uAPI and
> > admin-guide. So, better to keep them on its own directory,
> > while the docs there are not properly classified.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>
> So this one went upstream with the PDF fixes pull, right? I'm a little
> surprised to see it here now.
Yeah, this specific patch went together with the PDF fixes.
The remaining ones in this series aren't there yet.
From this series, besides this patch, you can also exclude patch
25/26, as it seems that Paul will merge via RCU tree.
The remaining ones apply cleanly on the top of docs-next
(I tested applying them on the top of your tree yesterday).
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
2019-07-31 19:16 ` Mauro Carvalho Chehab
@ 2019-07-31 19:34 ` Jonathan Corbet
2019-07-31 19:58 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 75+ messages in thread
From: Jonathan Corbet @ 2019-07-31 19:34 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm
On Wed, 31 Jul 2019 16:16:06 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> The remaining ones in this series aren't there yet.
>
> From this series, besides this patch, you can also exclude patch
> 25/26, as it seems that Paul will merge via RCU tree.
>
> The remaining ones apply cleanly on the top of docs-next
> (I tested applying them on the top of your tree yesterday).
Hmm...really?
- [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
Seems to already be applied.
- [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of
docs
Gives me the dreaded "could not build fake ancestor" error, I
don't really understand why.
- [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI
bookset
- [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide
book
Likewise
I've applied the others, so we're getting closer...
jon
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
2019-07-31 19:34 ` Jonathan Corbet
@ 2019-07-31 19:58 ` Mauro Carvalho Chehab
2019-07-31 20:02 ` Jonathan Corbet
0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31 19:58 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm
Em Wed, 31 Jul 2019 13:34:43 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Wed, 31 Jul 2019 16:16:06 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
>
> > The remaining ones in this series aren't there yet.
> >
> > From this series, besides this patch, you can also exclude patch
> > 25/26, as it seems that Paul will merge via RCU tree.
> >
> > The remaining ones apply cleanly on the top of docs-next
> > (I tested applying them on the top of your tree yesterday).
>
> Hmm...really?
>
> - [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
>
> Seems to already be applied.
>
> - [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of
> docs
>
> Gives me the dreaded "could not build fake ancestor" error, I
> don't really understand why.
That's new! What Sphinx version are you using?
Btw, on my build here (Sphinx 2.0.1 on Python3), I can't see this error.
>
> - [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI
> bookset
> - [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide
> book
>
> Likewise
>
> I've applied the others, so we're getting closer...
Weird...
I did a rebase here on the top of your current docs/docs-next... they
apply fine. Had to do just a small trivial fix on one of the patches.
Anyway, thanks for merging those... I have now just 5 patches.
Btw, it seems that there are now 5 new broken links:
MAINTAINERS: Documentation/filesystems/jfs.txt
MAINTAINERS: Documentation/filesystems/ufs.txt
drivers/hwtracing/coresight/Kconfig: Documentation/trace/coresight-cpu-debug.txt
fs/jfs/Kconfig: file:Documentation/filesystems/jfs.txt
fs/ufs/Kconfig: file:Documentation/filesystems/ufs.txt
4 of them related to the two fs patches applied today.
I'll send you a fix together with the remaining patches in a few.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
2019-07-31 19:58 ` Mauro Carvalho Chehab
@ 2019-07-31 20:02 ` Jonathan Corbet
0 siblings, 0 replies; 75+ messages in thread
From: Jonathan Corbet @ 2019-07-31 20:02 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm
On Wed, 31 Jul 2019 16:58:59 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > - [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of
> > docs
> >
> > Gives me the dreaded "could not build fake ancestor" error, I
> > don't really understand why.
>
> That's new! What Sphinx version are you using?
That's a "git am" error, sphinx doesn't enter into the picture...
jon
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-31 15:19 ` Akira Yokosawa
@ 2019-07-31 20:25 ` Paul E. McKenney
2019-08-30 11:32 ` Peter Zijlstra
0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-31 20:25 UTC (permalink / raw)
To: Akira Yokosawa
Cc: Alan Stern, Mauro Carvalho Chehab, Joel Fernandes,
Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
Jonathan Corbet, Andrea Parri, Will Deacon, Peter Zijlstra,
Boqun Feng, Nicholas Piggin, David Howells, Jade Alglave,
Luc Maranget, Daniel Lustig, Ingo Molnar, Jason Gunthorpe,
SeongJae Park, linux-arch
On Thu, Aug 01, 2019 at 12:19:25AM +0900, Akira Yokosawa wrote:
> On Wed, 31 Jul 2019 09:52:05 -0400, Alan Stern wrote:
> > On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:
> >
> >> Em Tue, 30 Jul 2019 18:17:01 -0400
> >> Joel Fernandes <joel@joelfernandes.org> escreveu:
> >
> >>>>> (4) I would argue that every occurence of
> >>>>> A ->(some dependency) B should be replaced with fixed size font in the HTML
> >>>>> results.
> >>>>
> >>>> Just place those with ``A -> (some dependency)``. This will make them use
> >>>> a fixed size font.
> >>>
> >>> Ok, understood all these. I guess my point was all of these will need to be
> >>> done to make this document useful from a ReST conversion standpoint. Until
> >>> then it is probably just better off being plain text - since there are so
> >>> many of those ``A -> (dep) B`` things.
> >
> >> On a very quick look, it seems that, if we replace:
> >>
> >> (\S+\s->\S*\s\w+)
> >>
> >> by:
> >> ``\1``
> >>
> >>
> >> On an editor that would allow to manually replace the regex (like kate),
> >> most of those can be get.
> >>
> >> See patch enclosed.
> >
> > Some time ago I considered the problem of converting this file to ReST
> > format. But I gave up on the idea, because the necessary changes were
> > so widespread and the resulting text file would not be easily readable.
> >
> > Replacing things of the form "A ->dep B" just scratches the surface.
> > That document teems with variable names, formulas, code extracts, and
> > other things which would all need to be rendered in a different font
> > style. The density of the markup required to do this would be
> > phenomenally high.
> >
> > In my opinion it simply was not worthwhile.
>
> +1 on keeping this and the other .txt files of LKMM intact.
Looks like a pretty clear consensus thus far. Any objections to keeping
these .txt for the time being?
Thanx, Paul
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-07-31 20:25 ` Paul E. McKenney
@ 2019-08-30 11:32 ` Peter Zijlstra
2019-09-01 13:35 ` Paul E. McKenney
0 siblings, 1 reply; 75+ messages in thread
From: Peter Zijlstra @ 2019-08-30 11:32 UTC (permalink / raw)
To: Paul E. McKenney
Cc: Akira Yokosawa, Alan Stern, Mauro Carvalho Chehab,
Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
Boqun Feng, Nicholas Piggin, David Howells, Jade Alglave,
Luc Maranget, Daniel Lustig, Ingo Molnar, Jason Gunthorpe,
SeongJae Park, linux-arch
On Wed, Jul 31, 2019 at 01:25:17PM -0700, Paul E. McKenney wrote:
> Looks like a pretty clear consensus thus far. Any objections to keeping
> these .txt for the time being?
Obviously I'm a huge proponent of abandoning RST and an advocate for
normal .txt files ;-)
^ permalink raw reply [flat|nested] 75+ messages in thread
* Re: [PATCH] tools: memory-model: add it to the Documentation body
2019-08-30 11:32 ` Peter Zijlstra
@ 2019-09-01 13:35 ` Paul E. McKenney
0 siblings, 0 replies; 75+ messages in thread
From: Paul E. McKenney @ 2019-09-01 13:35 UTC (permalink / raw)
To: Peter Zijlstra
Cc: Akira Yokosawa, Alan Stern, Mauro Carvalho Chehab,
Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
Boqun Feng, Nicholas Piggin, David Howells, Jade Alglave,
Luc Maranget, Daniel Lustig, Ingo Molnar, Jason Gunthorpe,
SeongJae Park, linux-arch
On Fri, Aug 30, 2019 at 01:32:16PM +0200, Peter Zijlstra wrote:
> On Wed, Jul 31, 2019 at 01:25:17PM -0700, Paul E. McKenney wrote:
> > Looks like a pretty clear consensus thus far. Any objections to keeping
> > these .txt for the time being?
>
> Obviously I'm a huge proponent of abandoning RST and an advocate for
> normal .txt files ;-)
Oh? I hadn't noticed. ;-)
Thanx, Paul
^ permalink raw reply [flat|nested] 75+ messages in thread
end of thread, other threads:[~2019-09-01 13:36 UTC | newest]
Thread overview: 75+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-07-26 12:51 [PATCH v2 00/26] ReST conversion of text files without .txt extension Mauro Carvalho Chehab
2019-07-26 12:51 ` [OpenRISC] " Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 01/26] docs: power: add it to to the main documentation index Mauro Carvalho Chehab
2019-07-31 19:03 ` Jonathan Corbet
2019-07-31 19:16 ` Mauro Carvalho Chehab
2019-07-31 19:34 ` Jonathan Corbet
2019-07-31 19:58 ` Mauro Carvalho Chehab
2019-07-31 20:02 ` Jonathan Corbet
2019-07-26 12:51 ` [PATCH v2 02/26] docs: thermal: add it to the driver API Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 04/26] docs: ubifs-authentication.md: convert to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 05/26] docs: writing-schema.md: convert from markdown " Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 06/26] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of docs Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 09/26] docs: ipmb: place it at driver-api and convert to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 10/26] docs: packing: move it to core-api book and adjust markups Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 11/26] docs: admin-guide: add auxdisplay files to it after conversion to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 12/26] docs: README.buddha: convert to ReST and add to m68k book Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 13/26] docs: parisc: convert to ReST and add to documentation body Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 14/26] docs: openrisc: " Mauro Carvalho Chehab
2019-07-26 12:51 ` [OpenRISC] " Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 15/26] docs: isdn: convert to ReST and add to kAPI bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide book Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 17/26] docs: fs: convert docs without extension to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 18/26] docs: fs: convert porting " Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 19/26] docs: index.rst: don't use genindex for pdf output Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 20/26] docs: wimax: convert to ReST and add to admin-guide Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 21/26] docs: mips: add to the documentation body as ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 22/26] docs: hwmon: pxe1610: convert to ReST format and add to the index Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 23/26] docs: nios2: add it to the main Documentation body Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 24/26] docs: net: convert two README files to ReST format Mauro Carvalho Chehab
2019-07-26 13:05 ` [PATCH v2 00/26] ReST conversion of text files without .txt extension Mauro Carvalho Chehab
2019-07-26 13:05 ` [OpenRISC] " Mauro Carvalho Chehab
2019-07-26 13:05 ` Mauro Carvalho Chehab
2019-07-26 13:05 ` Mauro Carvalho Chehab
[not found] ` <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
[not found] ` <20190726162002.GA146401@google.com>
[not found] ` <20190726140028.38abb5fa@coco.lan>
2019-07-26 17:55 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Joel Fernandes
2019-07-26 18:45 ` Mauro Carvalho Chehab
2019-07-26 18:02 ` Joel Fernandes
2019-07-26 19:01 ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
2019-07-27 14:14 ` Joel Fernandes
2019-07-27 15:37 ` Mauro Carvalho Chehab
2019-07-30 22:17 ` Joel Fernandes
2019-07-30 22:57 ` Mauro Carvalho Chehab
2019-07-31 13:52 ` Alan Stern
2019-07-31 13:52 ` Alan Stern
2019-07-31 15:19 ` Akira Yokosawa
2019-07-31 20:25 ` Paul E. McKenney
2019-08-30 11:32 ` Peter Zijlstra
2019-09-01 13:35 ` Paul E. McKenney
2019-07-26 19:14 ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
2019-07-30 22:06 ` Joel Fernandes
2019-07-30 21:22 ` Paul E. McKenney
2019-07-30 21:50 ` Joel Fernandes
2019-07-30 22:00 ` Mauro Carvalho Chehab
2019-07-30 22:21 ` Joel Fernandes
2019-07-30 23:00 ` Mauro Carvalho Chehab
2019-07-30 23:15 ` Joel Fernandes
2019-07-30 21:50 ` Mauro Carvalho Chehab
2019-07-30 23:37 ` Paul E. McKenney
2019-07-31 0:04 ` Paul E. McKenney
2019-07-31 0:47 ` Mauro Carvalho Chehab
2019-07-31 1:06 ` Paul E. McKenney
2019-07-31 1:33 ` Mauro Carvalho Chehab
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.