Skip to contentSkip to conversation

Convert files to ReST

PATCH In review Mauro Carvalho Chehab 16 participants 91 messages Apr 16, 2019 – May 6, 2019 Page 1 of 2

Subsystems (41)
lore
Share & tools
lore
#0 lore raw

cover Convert files to ReST

This series convert lots of files to be properly parsed by Sphinx as ReST files.

As it touches on lot of stuff, the series is based on linux-next.

I have a separate patch series with do the actual rename and adjustment of references. I opted to submit this first, as it sounds easier to merge this way, as each subsystem maintainer can apply the conversion directly on their trees (or at docs tree), avoiding merge conflects.

Both this series and the next steps are on my devel git tree, at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=all_with_indexes-v3

The final output in html can be seen at:

https://www.infradead.org/~mchehab/rst_conversion/

Mauro Carvalho Chehab (57):
docs: trace: fix some Sphinx warnings
docs: acpi: convert text files to ReST
docs: aoe: convert text files to ReST
docs: arm64: convert documentation to ReST format
docs: cdrom/cdrom-standard.tex: convert from LaTeX to ReST
docs: cdrom: convert remaining files to ReST
docs: cgroup-v1: convert to ReST file format
docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler
docs: cpu-freq: convert files to ReST
docs: device-mapper: convert it to ReST format
docs: extcon: move it to acpi dir and convert it to ReST
docs: fault-injection: convert it to ReST format
docs: fb: convert documentation to ReST format
docs: fpga: convert it to ReST
docs: gpio: convert it to ReST
docs: ide: convert it to ReST format
docs: infiniband: convert it to ReST format
docs: kbuild: convert it to ReST output
docs: kdump: convert it to ReST
docs: livepatch: convert it to ReST format
docs: locking: convert docs to ReST format
docs: mic: convert it to ReST format
docs: netlabel: convert it to ReST
docs: pcmcia: convert it to ReST format
docs: power: convert docs to ReST
docs: powerpc: convert docs to ReST
docs: pps/pps.txt convert it to ReST and move to API book
docs: ptp.txt: convert to ReST and move to driver-api
docs: riscv: convert it to ReST format
docs: s390: Debugging390.txt: convert table to ascii artwork
docs: s390: convert text files to ReST format
s390: include/asm/debug.h add kerneldoc markups
docs: serial: convert it to ReST format
docs: target: convert it to ReST format
docs: timers: convert documentation to ReST
docs: usb: convert documents to ReST
docs: watchdog: convert documents to ReST format
docs: x86: convert text files to ReST
docs: xilinx: convert eemi.txt to ReST
docs: scheduler: convert files to ReST
docs: EDID/HOWTO.txt: convert to ReST and move to kernel-API
docs: connector.txt: convert to ReST
docs: lcd-panel-cgram.txt convert it to ReST and move to admin-guide
docs: lp855x-driver.txt: convert to ReST and move to kernel-api
docs: m68k: convert it to ReST file format and add to arch bookset
docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm
docs: console.txt: convert to ReST format
docs: pti_intel_mid.txt: convert to ReST
docs: early-userspace: convert docs to ReST
docs: driver-model: convert it to ReST format
docs: arm: convert text files to ReST format
docs: memory-devices: convert ti-emif.txt to ReST format
docs: xen-tpmfront.txt: convert the file to ReST format
docs: bus-devices: ti-gpmc.txt: convert it to ReST
docs: nvmem: convert file to ReST format
docs: phy: convert samsung-usb2.txt to ReST format
docs: Prepare files to be renamed to *.rst

 Documentation/EDID/HOWTO.txt                  |   29 +-
 Documentation/acpi/DSD-properties-rules.txt   |    4 +-
 Documentation/acpi/acpi-lid.txt               |   37 +-
 Documentation/acpi/aml-debugger.txt           |   31 +-
 Documentation/acpi/apei/einj.txt              |   59 +-
 Documentation/acpi/apei/output_format.txt     |  247 +-
 Documentation/acpi/cppc_sysfs.txt             |   52 +-
 Documentation/acpi/debug.txt                  |   20 +-
 .../drivers/extcon-intel-int3496.txt}         |   14 +-
 .../acpi/dsd/data-node-references.txt         |   11 +-
 Documentation/acpi/dsd/graph.txt              |   24 +-
 Documentation/acpi/dsd/leds.txt               |   18 +-
 Documentation/acpi/dsdt-override.txt          |    4 +-
 Documentation/acpi/enumeration.txt            |   42 +-
 Documentation/acpi/gpio-properties.txt        |   42 +-
 Documentation/acpi/i2c-muxes.txt              |   21 +-
 Documentation/acpi/initrd_table_override.txt  |   90 +-
 Documentation/acpi/linuxized-acpica.txt       |   58 +-
 Documentation/acpi/lpit.txt                   |    8 +-
 Documentation/acpi/method-customizing.txt     |   48 +-
 Documentation/acpi/method-tracing.txt         |  132 +-
 Documentation/acpi/namespace.txt              |  323 +-
 Documentation/acpi/osi.txt                    |    3 +-
 Documentation/acpi/scan_handlers.txt          |    9 +-
 Documentation/acpi/ssdt-overlays.txt          |  128 +-
 Documentation/acpi/video_extension.txt        |   16 +-
 Documentation/aoe/aoe.txt                     |   63 +-
 Documentation/aoe/todo.txt                    |    3 +
 Documentation/aoe/udev.txt                    |    2 +-
 Documentation/arm/Booting                     |   71 +-
 Documentation/arm/IXP4xx                      |   61 +-
 Documentation/arm/Interrupts                  |   86 +-
 Documentation/arm/Marvell/README              |  537 ++--
 Documentation/arm/Microchip/README            |   63 +-
 Documentation/arm/Netwinder                   |   59 +-
 Documentation/arm/OMAP/DSS                    |  112 +-
 Documentation/arm/OMAP/README                 |    7 +
 Documentation/arm/OMAP/omap_pm                |   55 +-
 Documentation/arm/Porting                     |   14 +-
 Documentation/arm/README                      |   50 +-
 Documentation/arm/SA1100/ADSBitsy             |   14 +-
 Documentation/arm/SA1100/Assabet              |  185 +-
 Documentation/arm/SA1100/Brutus               |   45 +-
 Documentation/arm/SA1100/CERF                 |   10 +-
 Documentation/arm/SA1100/FreeBird             |   26 +-
 Documentation/arm/SA1100/GraphicsClient       |   46 +-
 Documentation/arm/SA1100/GraphicsMaster       |   13 +-
 Documentation/arm/SA1100/HUW_WEBPANEL         |    8 +-
 Documentation/arm/SA1100/Itsy                 |   14 +-
 Documentation/arm/SA1100/LART                 |    3 +-
 Documentation/arm/SA1100/PLEB                 |    6 +-
 Documentation/arm/SA1100/Pangolin             |   10 +-
 Documentation/arm/SA1100/Tifon                |    4 +-
 Documentation/arm/SA1100/Yopy                 |    5 +-
 Documentation/arm/SA1100/empeg                |    2 -
 Documentation/arm/SA1100/nanoEngine           |    6 +-
 Documentation/arm/SA1100/serial_UART          |   60 +-
 Documentation/arm/SPEAr/overview.txt          |   20 +-
 Documentation/arm/Samsung-S3C24XX/CPUfreq.txt |    5 +-
 .../arm/Samsung-S3C24XX/EB2410ITX.txt         |    5 +-
 Documentation/arm/Samsung-S3C24XX/GPIO.txt    |   21 +-
 Documentation/arm/Samsung-S3C24XX/H1940.txt   |    5 +-
 Documentation/arm/Samsung-S3C24XX/NAND.txt    |    6 +-
 .../arm/Samsung-S3C24XX/Overview.txt          |   15 +-
 Documentation/arm/Samsung-S3C24XX/S3C2412.txt |    5 +-
 Documentation/arm/Samsung-S3C24XX/S3C2413.txt |    7 +-
 .../arm/Samsung-S3C24XX/SMDK2440.txt          |    5 +-
 Documentation/arm/Samsung-S3C24XX/Suspend.txt |   20 +-
 .../arm/Samsung-S3C24XX/USB-Host.txt          |   16 +-
 .../arm/Samsung/Bootloader-interface.txt      |   27 +-
 Documentation/arm/Samsung/GPIO.txt            |    5 +-
 Documentation/arm/Samsung/Overview.txt        |   11 +-
 Documentation/arm/Setup                       |   49 +-
 Documentation/arm/VFP/release-notes.txt       |    4 +-
 .../arm/cluster-pm-race-avoidance.txt         |  177 +-
 Documentation/arm/firmware.txt                |   14 +-
 Documentation/arm/kernel_mode_neon.txt        |    3 +
 Documentation/arm/kernel_user_helpers.txt     |   79 +-
 Documentation/arm/keystone/Overview.txt       |   47 +-
 Documentation/arm/keystone/knav-qmss.txt      |    6 +-
 Documentation/arm/mem_alignment               |   11 +-
 Documentation/arm/memory.txt                  |    9 +-
 Documentation/arm/nwfpe/NOTES                 |    3 +
 Documentation/arm/nwfpe/README                |   10 +-
 Documentation/arm/nwfpe/README.FPE            |   24 +-
 Documentation/arm/nwfpe/TODO                  |   47 +-
 Documentation/arm/pxa/mfp.txt                 |  106 +-
 Documentation/arm/sti/overview.txt            |   21 +-
 Documentation/arm/sti/stih407-overview.txt    |    9 +-
 Documentation/arm/sti/stih415-overview.txt    |    8 +-
 Documentation/arm/sti/stih416-overview.txt    |    5 +-
 Documentation/arm/sti/stih418-overview.txt    |    9 +-
 .../arm/stm32/stm32f429-overview.rst          |    5 +-
 .../arm/stm32/stm32f746-overview.rst          |    5 +-
 .../arm/stm32/stm32f769-overview.rst          |    5 +-
 .../arm/stm32/stm32h743-overview.rst          |    5 +-
 .../arm/stm32/stm32mp157-overview.rst         |    1 +
 Documentation/arm/sunxi/README                |   98 +-
 Documentation/arm/sunxi/clocks.txt            |    7 +-
 Documentation/arm/swp_emulation               |   24 +-
 Documentation/arm/tcm.txt                     |   54 +-
 Documentation/arm/uefi.txt                    |   39 +-
 Documentation/arm/vlocks.txt                  |    9 +-
 Documentation/arm64/acpi_object_usage.txt     |  288 +-
 Documentation/arm64/arm-acpi.txt              |  153 +-
 Documentation/arm64/booting.txt               |   91 +-
 Documentation/arm64/cpu-feature-registers.txt |  190 +-
 Documentation/arm64/elf_hwcaps.txt            |   50 +-
 Documentation/arm64/hugetlbpage.txt           |    7 +-
 Documentation/arm64/legacy_instructions.txt   |   43 +-
 Documentation/arm64/memory.txt                |   91 +-
 .../arm64/pointer-authentication.txt          |    2 +
 Documentation/arm64/silicon-errata.txt        |   63 +-
 Documentation/arm64/sve.txt                   |   10 +-
 Documentation/arm64/tagged-pointers.txt       |    6 +-
 Documentation/auxdisplay/lcd-panel-cgram.txt  |    7 +-
 Documentation/backlight/lp855x-driver.txt     |   65 +-
 Documentation/bt8xxgpio.txt                   |    1 -
 Documentation/bus-devices/ti-gpmc.txt         |  157 +-
 Documentation/bus-virt-phys-mapping.txt       |   50 +-
 Documentation/cdrom/Makefile                  |   21 -
 Documentation/cdrom/cdrom-standard.tex        | 1026 -------
 Documentation/cdrom/cdrom-standard.txt        | 1063 +++++++
 Documentation/cdrom/ide-cd                    |  178 +-
 Documentation/cdrom/packet-writing.txt        |   27 +-
 Documentation/cgroup-v1/blkio-controller.txt  |  103 +-
 Documentation/cgroup-v1/cgroups.txt           |  180 +-
 Documentation/cgroup-v1/cpuacct.txt           |   15 +-
 Documentation/cgroup-v1/cpusets.txt           |  203 +-
 Documentation/cgroup-v1/devices.txt           |   40 +-
 Documentation/cgroup-v1/freezer-subsystem.txt |   14 +-
 Documentation/cgroup-v1/hugetlb.txt           |   31 +-
 Documentation/cgroup-v1/memcg_test.txt        |  259 +-
 Documentation/cgroup-v1/memory.txt            |  449 +--
 Documentation/cgroup-v1/net_cls.txt           |   37 +-
 Documentation/cgroup-v1/net_prio.txt          |   24 +-
 Documentation/cgroup-v1/pids.txt              |   78 +-
 Documentation/cgroup-v1/rdma.txt              |   66 +-
 Documentation/cma/debugfs.txt                 |    6 +-
 Documentation/connector/connector.txt         |  128 +-
 Documentation/console/console.txt             |   61 +-
 Documentation/cpu-freq/amd-powernow.txt       |   11 +-
 Documentation/cpu-freq/core.txt               |   66 +-
 Documentation/cpu-freq/cpu-drivers.txt        |  217 +-
 Documentation/cpu-freq/cpufreq-nforce2.txt    |   12 +-
 Documentation/cpu-freq/cpufreq-stats.txt      |  141 +-
 Documentation/cpu-freq/pcc-cpufreq.txt        |  102 +-
 .../device-mapper/cache-policies.txt          |   24 +-
 Documentation/device-mapper/cache.txt         |  206 +-
 Documentation/device-mapper/delay.txt         |   29 +-
 Documentation/device-mapper/dm-crypt.txt      |   57 +-
 Documentation/device-mapper/dm-flakey.txt     |   45 +-
 Documentation/device-mapper/dm-init.txt       |   75 +-
 Documentation/device-mapper/dm-integrity.txt  |   55 +-
 Documentation/device-mapper/dm-io.txt         |   14 +-
 Documentation/device-mapper/dm-log.txt        |    5 +-
 .../device-mapper/dm-queue-length.txt         |   25 +-
 Documentation/device-mapper/dm-raid.txt       |  225 +-
 .../device-mapper/dm-service-time.txt         |   68 +-
 Documentation/device-mapper/dm-uevent.txt     |  143 +-
 Documentation/device-mapper/dm-zoned.txt      |   10 +-
 Documentation/device-mapper/era.txt           |   36 +-
 Documentation/device-mapper/kcopyd.txt        |   10 +-
 Documentation/device-mapper/linear.txt        |  100 +-
 Documentation/device-mapper/log-writes.txt    |   91 +-
 .../device-mapper/persistent-data.txt         |    4 +
 Documentation/device-mapper/snapshot.txt      |  116 +-
 Documentation/device-mapper/statistics.txt    |   62 +-
 Documentation/device-mapper/striped.txt       |   68 +-
 Documentation/device-mapper/switch.txt        |   47 +-
 .../device-mapper/thin-provisioning.txt       |   68 +-
 Documentation/device-mapper/unstriped.txt     |  111 +-
 Documentation/device-mapper/verity.txt        |   20 +-
 Documentation/device-mapper/writecache.txt    |   13 +-
 Documentation/device-mapper/zero.txt          |   14 +-
 Documentation/driver-model/binding.txt        |   20 +-
 Documentation/driver-model/bus.txt            |   69 +-
 Documentation/driver-model/class.txt          |   74 +-
 .../driver-model/design-patterns.txt          |  106 +-
 Documentation/driver-model/device.txt         |   57 +-
 Documentation/driver-model/devres.txt         |   50 +-
 Documentation/driver-model/driver.txt         |  112 +-
 Documentation/driver-model/overview.txt       |   37 +-
 Documentation/driver-model/platform.txt       |   30 +-
 Documentation/driver-model/porting.txt        |  333 +--
 Documentation/early-userspace/README          |    3 +
 .../early-userspace/buffer-format.txt         |   19 +-
 .../fault-injection/fault-injection.txt       |  265 +-
 .../fault-injection/notifier-error-inject.txt |   18 +-
 .../fault-injection/nvme-fault-injection.txt  |  174 +-
 .../fault-injection/provoke-crashes.txt       |   40 +-
 Documentation/fb/api.txt                      |   29 +-
 Documentation/fb/arkfb.txt                    |    8 +-
 Documentation/fb/aty128fb.txt                 |   31 +-
 Documentation/fb/cirrusfb.txt                 |   47 +-
 Documentation/fb/cmap_xfbdev.txt              |   57 +-
 Documentation/fb/deferred_io.txt              |   28 +-
 Documentation/fb/efifb.txt                    |   18 +-
 Documentation/fb/ep93xx-fb.txt                |   25 +-
 Documentation/fb/fbcon.txt                    |  177 +-
 Documentation/fb/framebuffer.txt              |   79 +-
 Documentation/fb/gxfb.txt                     |   22 +-
 Documentation/fb/intel810.txt                 |   77 +-
 Documentation/fb/intelfb.txt                  |   62 +-
 Documentation/fb/internals.txt                |   24 +-
 Documentation/fb/lxfb.txt                     |   23 +-
 Documentation/fb/matroxfb.txt                 |  526 ++--
 Documentation/fb/metronomefb.txt              |    8 +-
 Documentation/fb/modedb.txt                   |   44 +-
 Documentation/fb/pvr2fb.txt                   |   55 +-
 Documentation/fb/pxafb.txt                    |   81 +-
 Documentation/fb/s3fb.txt                     |    8 +-
 Documentation/fb/sa1100fb.txt                 |   23 +-
 Documentation/fb/sh7760fb.txt                 |  153 +-
 Documentation/fb/sisfb.txt                    |   40 +-
 Documentation/fb/sm501.txt                    |    7 +-
 Documentation/fb/sm712fb.txt                  |   18 +-
 Documentation/fb/sstfb.txt                    |  231 +-
 Documentation/fb/tgafb.txt                    |   30 +-
 Documentation/fb/tridentfb.txt                |   34 +-
 Documentation/fb/udlfb.txt                    |   55 +-
 Documentation/fb/uvesafb.txt                  |  128 +-
 Documentation/fb/vesafb.txt                   |  121 +-
 Documentation/fb/viafb.txt                    |  393 +--
 Documentation/fb/vt8623fb.txt                 |   10 +-
 Documentation/fpga/dfl.txt                    |   58 +-
 Documentation/gpio/sysfs.txt                  |   39 +-
 Documentation/highuid.txt                     |    2 +-
 Documentation/ide/ide-tape.txt                |   23 +-
 Documentation/ide/ide.txt                     |  147 +-
 Documentation/ide/warm-plug-howto.txt         |   10 +-
 Documentation/index.rst                       |    1 +
 Documentation/infiniband/core_locking.txt     |   64 +-
 Documentation/infiniband/ipoib.txt            |   24 +-
 Documentation/infiniband/opa_vnic.txt         |  108 +-
 Documentation/infiniband/sysfs.txt            |    4 +-
 Documentation/infiniband/tag_matching.txt     |    5 +
 Documentation/infiniband/user_mad.txt         |   33 +-
 Documentation/infiniband/user_verbs.txt       |   12 +-
 Documentation/kbuild/headers_install.txt      |    5 +-
 Documentation/kbuild/kbuild.txt               |  119 +-
 Documentation/kbuild/kconfig-language.txt     |  232 +-
 .../kbuild/kconfig-macro-language.txt         |   37 +-
 Documentation/kbuild/kconfig.txt              |  136 +-
 Documentation/kbuild/makefiles.txt            |  518 ++--
 Documentation/kbuild/modules.txt              |  166 +-
 Documentation/kdump/kdump.txt                 |  131 +-
 Documentation/kdump/vmcoreinfo.txt            |   59 +-
 Documentation/kobject.txt                     |    2 +-
 Documentation/ldm.txt                         |    3 +-
 Documentation/livepatch/callbacks.txt         |   12 +-
 .../livepatch/cumulative-patches.txt          |   14 +-
 Documentation/livepatch/livepatch.txt         |   56 +-
 Documentation/livepatch/module-elf-format.txt |  211 +-
 Documentation/livepatch/shadow-vars.txt       |   65 +-
 Documentation/locking/lockdep-design.txt      |   41 +-
 Documentation/locking/lockstat.txt            |  219 +-
 Documentation/locking/locktorture.txt         |  105 +-
 Documentation/locking/mutex-design.txt        |   26 +-
 Documentation/locking/rt-mutex-design.txt     |  135 +-
 Documentation/locking/rt-mutex.txt            |   30 +-
 Documentation/locking/spinlocks.txt           |   32 +-
 Documentation/locking/ww-mutex-design.txt     |   82 +-
 Documentation/m68k/kernel-options.txt         |  319 +-
 Documentation/memory-barriers.txt             |    2 +-
 Documentation/memory-devices/ti-emif.txt      |   25 +-
 Documentation/mic/mic_overview.txt            |    6 +-
 Documentation/mic/scif_overview.txt           |   58 +-
 Documentation/netlabel/cipso_ipv4.txt         |   19 +-
 Documentation/netlabel/introduction.txt       |   16 +-
 Documentation/netlabel/lsm_interface.txt      |   16 +-
 Documentation/numastat.txt                    |    1 -
 Documentation/nvmem/nvmem.txt                 |  110 +-
 Documentation/pcmcia/devicetable.txt          |    4 +
 Documentation/pcmcia/driver-changes.txt       |   35 +-
 Documentation/pcmcia/driver.txt               |   18 +-
 Documentation/pcmcia/locking.txt              |   39 +-
 Documentation/phy/samsung-usb2.txt            |   60 +-
 Documentation/pnp.txt                         |   11 +-
 Documentation/power/apm-acpi.txt              |   10 +-
 Documentation/power/basic-pm-debugging.txt    |   77 +-
 Documentation/power/charger-manager.txt       |  101 +-
 Documentation/power/drivers-testing.txt       |    5 +
 Documentation/power/energy-model.txt          |  101 +-
 Documentation/power/freezing-of-tasks.txt     |   91 +-
 Documentation/power/interface.txt             |   20 +-
 Documentation/power/opp.txt                   |  175 +-
 Documentation/power/pci.txt                   |   77 +-
 Documentation/power/pm_qos_interface.txt      |  127 +-
 Documentation/power/power_supply_class.txt    |  269 +-
 Documentation/power/powercap/powercap.txt     |  297 +-
 Documentation/power/regulator/consumer.txt    |  141 +-
 Documentation/power/regulator/design.txt      |    9 +-
 Documentation/power/regulator/machine.txt     |   47 +-
 Documentation/power/regulator/overview.txt    |   51 +-
 Documentation/power/regulator/regulator.txt   |   18 +-
 Documentation/power/runtime_pm.txt            |  234 +-
 Documentation/power/s2ram.txt                 |   20 +-
 .../power/suspend-and-cpuhotplug.txt          |   42 +-
 .../power/suspend-and-interrupts.txt          |    2 +
 Documentation/power/swsusp-and-swap-files.txt |   15 +-
 Documentation/power/swsusp-dmcrypt.txt        |  118 +-
 Documentation/power/swsusp.txt                |  639 ++--
 Documentation/power/tricks.txt                |    6 +-
 Documentation/power/userland-swsusp.txt       |   53 +-
 Documentation/power/video.txt                 |  156 +-
 Documentation/powerpc/DAWR-POWER9.txt         |   10 +-
 Documentation/powerpc/bootwrapper.txt         |   28 +-
 Documentation/powerpc/cpu_families.txt        |   23 +-
 Documentation/powerpc/cpu_features.txt        |    6 +-
 Documentation/powerpc/cxl.txt                 |   46 +-
 Documentation/powerpc/cxlflash.txt            |    8 +-
 Documentation/powerpc/dscr.txt                |   18 +-
 .../powerpc/eeh-pci-error-recovery.txt        |  108 +-
 .../powerpc/firmware-assisted-dump.txt        |  117 +-
 Documentation/powerpc/hvcs.txt                |  108 +-
 Documentation/powerpc/isa-versions.rst        |   13 +-
 Documentation/powerpc/mpc52xx.txt             |   12 +-
 .../powerpc/pci_iov_resource_on_powernv.txt   |   15 +-
 Documentation/powerpc/pmu-ebb.txt             |    1 +
 Documentation/powerpc/ptrace.txt              |  169 +-
 Documentation/powerpc/qe_firmware.txt         |   37 +-
 Documentation/powerpc/syscall64-abi.txt       |   29 +-
 .../powerpc/transactional_memory.txt          |   45 +-
 Documentation/pps/pps.txt                     |   67 +-
 Documentation/preempt-locking.txt             |    2 +-
 Documentation/pti/pti_intel_mid.txt           |  135 +-
 Documentation/ptp/ptp.txt                     |   26 +-
 Documentation/rbtree.txt                      |   52 +-
 Documentation/riscv/pmu.txt                   |   98 +-
 Documentation/rtc.txt                         |    6 +-
 Documentation/s390/3270.txt                   |   85 +-
 Documentation/s390/CommonIO                   |   47 +-
 Documentation/s390/DASD                       |   33 +-
 Documentation/s390/Debugging390.txt           | 2599 ++++++++++-------
 Documentation/s390/cds.txt                    |  354 ++-
 Documentation/s390/driver-model.txt           |  179 +-
 Documentation/s390/monreader.txt              |   85 +-
 Documentation/s390/qeth.txt                   |   36 +-
 Documentation/s390/s390dbf.txt                |  639 ++--
 Documentation/s390/vfio-ap.txt                |  487 +--
 Documentation/s390/vfio-ccw.txt               |   88 +-
 Documentation/s390/zfcpdump.txt               |    2 +
 Documentation/scheduler/completion.txt        |   38 +-
 Documentation/scheduler/sched-arch.txt        |   18 +-
 Documentation/scheduler/sched-bwc.txt         |   28 +-
 Documentation/scheduler/sched-deadline.txt    |  293 +-
 Documentation/scheduler/sched-design-CFS.txt  |   15 +-
 Documentation/scheduler/sched-domains.txt     |    8 +-
 Documentation/scheduler/sched-energy.txt      |   47 +-
 Documentation/scheduler/sched-nice-design.txt |    6 +-
 Documentation/scheduler/sched-rt-group.txt    |   28 +-
 Documentation/scheduler/sched-stats.txt       |   35 +-
 Documentation/security/tpm/xen-tpmfront.txt   |  101 +-
 Documentation/serial/README.cycladesZ         |    5 +-
 Documentation/serial/driver                   |  113 +-
 Documentation/serial/moxa-smartio             |  750 ++---
 Documentation/serial/n_gsm.txt                |   81 +-
 Documentation/serial/rocket.txt               |  144 +-
 Documentation/serial/serial-iso7816.txt       |   21 +-
 Documentation/serial/serial-rs485.txt         |   22 +-
 Documentation/serial/tty.txt                  |  111 +-
 Documentation/target/tcm_mod_builder.txt      |  200 +-
 Documentation/target/tcmu-design.txt          |  268 +-
 Documentation/timers/NO_HZ.txt                |   40 +-
 Documentation/timers/highres.txt              |   11 +-
 Documentation/timers/hpet.txt                 |    4 +-
 Documentation/timers/hrtimers.txt             |    6 +-
 Documentation/timers/timekeeping.txt          |    3 +-
 Documentation/timers/timers-howto.txt         |   15 +-
 Documentation/trace/ftrace.rst                |    1 +
 Documentation/trace/histogram.rst             |   86 +-
 Documentation/usb/WUSB-Design-overview.txt    |   56 +-
 Documentation/usb/acm.txt                     |  156 +-
 Documentation/usb/authorization.txt           |   75 +-
 Documentation/usb/chipidea.txt                |  101 +-
 Documentation/usb/dwc3.txt                    |   12 +-
 Documentation/usb/ehci.txt                    |   42 +-
 Documentation/usb/functionfs.txt              |   17 +-
 Documentation/usb/gadget-testing.txt          |  609 ++--
 Documentation/usb/gadget_configfs.txt         |  302 +-
 Documentation/usb/gadget_hid.txt              |  175 +-
 Documentation/usb/gadget_multi.txt            |   43 +-
 Documentation/usb/gadget_printer.txt          |  155 +-
 Documentation/usb/gadget_serial.txt           |   73 +-
 Documentation/usb/iuu_phoenix.txt             |   34 +-
 Documentation/usb/mass-storage.txt            |   19 +-
 Documentation/usb/misc_usbsevseg.txt          |    9 +-
 Documentation/usb/mtouchusb.txt               |   42 +-
 Documentation/usb/ohci.txt                    |    5 +-
 Documentation/usb/rio.txt                     |   83 +-
 Documentation/usb/usb-help.txt                |   21 +-
 Documentation/usb/usb-serial.txt              |  203 +-
 Documentation/usb/usbip_protocol.txt          |  552 ++--
 Documentation/usb/usbmon.txt                  |  100 +-
 .../convert_drivers_to_kernel_api.txt         |  109 +-
 Documentation/watchdog/hpwdt.txt              |   23 +-
 Documentation/watchdog/mlx-wdt.txt            |   24 +-
 Documentation/watchdog/pcwd-watchdog.txt      |   13 +-
 Documentation/watchdog/watchdog-api.txt       |   76 +-
 .../watchdog/watchdog-kernel-api.txt          |   89 +-
 .../watchdog/watchdog-parameters.txt          |  672 +++--
 Documentation/watchdog/watchdog-pm.txt        |    3 +
 Documentation/watchdog/wdt.txt                |   31 +-
 Documentation/x86/amd-memory-encryption.txt   |   10 +-
 Documentation/x86/boot.txt                    |  578 ++--
 Documentation/x86/earlyprintk.txt             |   69 +-
 Documentation/x86/entry_64.txt                |   11 +-
 Documentation/x86/exception-tables.txt        |  245 +-
 Documentation/x86/i386/IO-APIC.txt            |   23 +-
 Documentation/x86/intel_mpx.txt               |   55 +-
 Documentation/x86/microcode.txt               |   51 +-
 Documentation/x86/mtrr.txt                    |  442 +--
 Documentation/x86/orc-unwinder.txt            |    1 +
 Documentation/x86/pat.txt                     |  217 +-
 Documentation/x86/protection-keys.txt         |   33 +-
 Documentation/x86/pti.txt                     |    8 +-
 Documentation/x86/resctrl_ui.txt              |  621 ++--
 Documentation/x86/tlb.txt                     |   12 +-
 Documentation/x86/topology.txt                |   26 +-
 Documentation/x86/usb-legacy-support.txt      |   33 +-
 Documentation/x86/x86_64/5level-paging.txt    |   14 +-
 Documentation/x86/x86_64/boot-options.txt     |   98 +-
 Documentation/x86/x86_64/mm.txt               |  212 +-
 Documentation/x86/x86_64/uefi.txt             |   21 +-
 Documentation/x86/zero-page.txt               |   67 +-
 Documentation/xilinx/eemi.txt                 |    8 +-
 Documentation/zorro.txt                       |    5 +-
 MAINTAINERS                                   |    2 +-
 arch/arm64/kernel/kexec_image.c               |    2 +-
 arch/s390/include/asm/debug.h                 |  231 ++
 drivers/cdrom/cdrom.c                         |    2 +-
 include/linux/connector.h                     |   63 +-
 433 files changed, 21459 insertions(+), 16370 deletions(-)
 rename Documentation/{extcon/intel-int3496.txt => acpi/drivers/extcon-intel-int3496.txt} (66%)
 delete mode 100644 Documentation/arm/SA1100/empeg
 delete mode 100644 Documentation/cdrom/Makefile
 delete mode 100644 Documentation/cdrom/cdrom-standard.tex
 create mode 100644 Documentation/cdrom/cdrom-standard.txt
Signature · 1 line
2.20.1
#1 lore raw

PATCH 1/57 docs: trace: fix some Sphinx warnings

There are some warnings produced when building trace. Fix them.

---
 Documentation/trace/ftrace.rst    |  1 +
 Documentation/trace/histogram.rst | 86 ++++++++++++++++---------------
 2 files changed, 45 insertions(+), 42 deletions(-)
Documentation/trace/ftrace.rst +1 -0
index 809b39d066ee..f60079259669 100644
@@ -1435,6 +1435,7 @@ trace has provided some very helpful debugging information.
 
 If we prefer function graph output instead of function, we can set
 display-graph option::
+
  with echo 1 > options/display-graph
 
   # tracer: irqsoff
Documentation/trace/histogram.rst +44 -42

118 lines not on this page · raw message

Signature · 1 line
2.20.1
#2 lore raw

PATCH 2/57 docs: acpi: convert text files to ReST

In reply to Mauro Carvalho Chehab

Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.

---
 Documentation/acpi/DSD-properties-rules.txt   |   4 +-
 Documentation/acpi/acpi-lid.txt               |  37 +-
 Documentation/acpi/aml-debugger.txt           |  31 +-
 Documentation/acpi/apei/einj.txt              |  59 ++--
 Documentation/acpi/apei/output_format.txt     | 247 +++++++-------
 Documentation/acpi/cppc_sysfs.txt             |  52 +--
 Documentation/acpi/debug.txt                  |  20 +-
 .../acpi/dsd/data-node-references.txt         |  11 +-
 Documentation/acpi/dsd/graph.txt              |  24 +-
 Documentation/acpi/dsd/leds.txt               |  18 +-
 Documentation/acpi/dsdt-override.txt          |   4 +-
 Documentation/acpi/enumeration.txt            |  42 +--
 Documentation/acpi/gpio-properties.txt        |  42 +--
 Documentation/acpi/i2c-muxes.txt              |  21 +-
 Documentation/acpi/initrd_table_override.txt  |  90 ++---
 Documentation/acpi/linuxized-acpica.txt       |  58 ++--
 Documentation/acpi/lpit.txt                   |   8 +-
 Documentation/acpi/method-customizing.txt     |  48 ++-
 Documentation/acpi/method-tracing.txt         | 132 ++++---
 Documentation/acpi/namespace.txt              | 323 +++++++++---------
 Documentation/acpi/osi.txt                    |   3 +-
 Documentation/acpi/scan_handlers.txt          |   9 +-
 Documentation/acpi/ssdt-overlays.txt          | 128 +++----
 Documentation/acpi/video_extension.txt        |  16 +-
 24 files changed, 794 insertions(+), 633 deletions(-)
Documentation/acpi/DSD-properties-rules.txt +3 -1
index 3e4862bdad98..2b0307a897c1 100644
@@ -1,5 +1,6 @@
+==================================
 _DSD Device Properties Usage Rules
-----------------------------------
+==================================
 
 Properties, Property Sets and Property Subsets
 ----------------------------------------------
@@ -94,4 +95,5 @@ References
 ----------
 
 [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
+
 [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
Documentation/acpi/acpi-lid.txt +27 -10
index effe7af3a5af..a4bc51ee2db1 100644
@@ -1,10 +1,14 @@
+=========================================================
 Special Usage Model of the ACPI Control Method Lid Device
+=========================================================
 
 Copyright (C) 2016, Intel Corporation
-Author: Lv Zheng <[email protected]>
 
+:Author: Lv Zheng <[email protected]>
 
-Abstract:
+
+Abstract
+========
 
 Platforms containing lids convey lid state (open/close) to OSPMs using a
 control method lid device. To implement this, the AML tables issue
@@ -20,6 +24,7 @@ expections of the Linux ACPI lid device driver.
 
 
 1. Restrictions of the returning value of the _LID control method
+=================================================================
 
 The _LID control method is described to return the "current" lid state.
 However the word of "current" has ambiguity, some buggy AML tables return
@@ -31,6 +36,8 @@ with cached value, the initial returning value is likely not reliable.
 There are platforms always retun "closed" as initial lid state.
 
 2. Restrictions of the lid state change notifications
+=====================================================
+
 
 There are buggy AML tables never notifying when the lid device state is
 changed to "opened". Thus the "opened" notification is not guaranteed. But
@@ -40,26 +47,32 @@ trigger some system power saving operations on Windows. Since it is fully
 tested, it is reliable from all AML tables.
 
 3. Expections for the userspace users of the ACPI lid device driver
+===================================================================
 
 The ACPI button driver exports the lid state to the userspace via the
 following file:
+
   /proc/acpi/button/lid/LID0/state
+
 This file actually calls the _LID control method described above. And given
 the previous explanation, it is not reliable enough on some platforms. So
 it is advised for the userspace program to not to solely rely on this file
 to determine the actual lid state.
 
 The ACPI button driver emits the following input event to the userspace:
-  SW_LID
-The ACPI lid device driver is implemented to try to deliver the platform
-triggered events to the userspace. However, given the fact that the buggy
-firmware cannot make sure "opened"/"closed" events are paired, the ACPI
-button driver uses the following 3 modes in order not to trigger issues.
+
+SW_LID
+  The ACPI lid device driver is implemented to try to deliver the platform
+  triggered events to the userspace. However, given the fact that the buggy
+  firmware cannot make sure "opened"/"closed" events are paired, the ACPI
+  button driver uses the following 3 modes in order not to trigger issues.
 
 If the userspace hasn't been prepared to ignore the unreliable "opened"
 events and the unreliable initial state notification, Linux users can use
 the following kernel parameters to handle the possible issues:
-A. button.lid_init_state=method:
+
+A. `button.lid_init_state=method`:
+
    When this option is specified, the ACPI button driver reports the
    initial lid state using the returning value of the _LID control method
    and whether the "opened"/"closed" events are paired fully relies on the
@@ -69,7 +82,9 @@ A. button.lid_init_state=method:
    notification is missing.
    This option is the default behavior during the period the userspace
    isn't ready to handle the buggy AML tables.
-B. button.lid_init_state=open:
+
+B. `button.lid_init_state=open`:
+
    When this option is specified, the ACPI button driver always reports the
    initial lid state as "opened" and whether the "opened"/"closed" events
    are paired fully relies on the firmware implementation.
@@ -80,7 +95,9 @@ B. button.lid_init_state=open:
 If the userspace has been prepared to ignore the unreliable "opened" events
 and the unreliable initial state notification, Linux users should always
 use the following kernel parameter:
-C. button.lid_init_state=ignore:
+
+C. `button.lid_init_state=ignore`:
+
    When this option is specified, the ACPI button driver never reports the
    initial lid state and there is a compensation mechanism implemented to
    ensure that the reliable "closed" notifications can always be delievered
Documentation/acpi/aml-debugger.txt +17 -14
index 75ebeb64ab29..22144e0c496d 100644
@@ -1,6 +1,9 @@
+================
 The AML Debugger
+================
 
 Copyright (C) 2016, Intel Corporation
+
 Author: Lv Zheng <[email protected]>
 
 
@@ -10,16 +13,16 @@ kernel.
 1. Build the debugger
 
    The following kernel configuration items are required to enable the AML
-   debugger interface from the Linux kernel:
+   debugger interface from the Linux kernel::
 
-   CONFIG_ACPI_DEBUGGER=y
-   CONFIG_ACPI_DEBUGGER_USER=m
+     CONFIG_ACPI_DEBUGGER=y
+     CONFIG_ACPI_DEBUGGER_USER=m
 
    The userspace utilities can be built from the kernel source tree using
-   the following commands:
+   the following commands::
 
-   $ cd tools
-   $ make acpi
+     $ cd tools
+     $ make acpi
 
    The resultant userspace tool binary is then located at:
 
@@ -31,11 +34,11 @@ kernel.
 2. Start the userspace debugger interface
 
    After booting the kernel with the debugger built-in, the debugger can be
-   started by using the following commands:
+   started by using the following commands::
 
-   # mount -t debugfs none /sys/kernel/debug
-   # modprobe acpi_dbg
-   # tools/power/acpi/acpidbg
+     # mount -t debugfs none /sys/kernel/debug
+     # modprobe acpi_dbg
+     # tools/power/acpi/acpidbg
 
    That spawns the interactive AML debugger environment where you can execute
    debugger commands.
@@ -51,9 +54,9 @@ kernel.
 3. Stop the userspace debugger interface
 
    The interactive debugger interface can be closed by pressing Ctrl+C or using
-   the "quit" or "exit" commands.  When finished, unload the module with:
+   the "quit" or "exit" commands.  When finished, unload the module with::
 
-   # rmmod acpi_dbg
+     # rmmod acpi_dbg
 
    The module unloading may fail if there is an acpidbg instance running.
 
@@ -61,6 +64,6 @@ kernel.
 
    It may be useful to run the AML debugger in a test script. "acpidbg" supports
    this in a special "batch" mode.  For example, the following command outputs
-   the entire ACPI namespace:
+   the entire ACPI namespace::
 
-   # acpidbg -b "namespace"
+     # acpidbg -b "namespace"
Documentation/acpi/apei/einj.txt +31 -28

109 lines not on this page · raw message

Documentation/acpi/apei/output_format.txt +124 -123

252 lines not on this page · raw message

Documentation/acpi/cppc_sysfs.txt +28 -24

77 lines not on this page · raw message

Documentation/acpi/debug.txt +11 -9
index 65bf47c46b6d..259a12a1e6a9 100644
@@ -1,4 +1,6 @@
-			ACPI Debug Output
+=================
+ACPI Debug Output
+=================
 
 
 The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
@@ -33,7 +35,7 @@ to /sys/module/acpi/parameters/debug_layer.
 
 The possible components are defined in include/acpi/acoutput.h and
 include/acpi/acpi_drivers.h.  Reading /sys/module/acpi/parameters/debug_layer
-shows the supported mask values, currently these:
+shows the supported mask values, currently these::
 
     ACPI_UTILITIES                  0x00000001
     ACPI_HARDWARE                   0x00000002
@@ -81,7 +83,7 @@ to /sys/module/acpi/parameters/debug_level.
 
 The possible levels are defined in include/acpi/acoutput.h.  Reading
 /sys/module/acpi/parameters/debug_level shows the supported mask values,
-currently these:
+currently these::
 
     ACPI_LV_INIT                    0x00000001
     ACPI_LV_DEBUG_OBJECT            0x00000002
@@ -115,7 +117,7 @@ currently these:
 Examples
 --------
 
-For example, drivers/acpi/bus.c contains this:
+For example, drivers/acpi/bus.c contains this::
 
     #define _COMPONENT              ACPI_BUS_COMPONENT
     ...
@@ -127,22 +129,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
 definition.)
 
 Enable all AML "Debug" output (stores to the Debug object while interpreting
-AML) during boot:
+AML) during boot::
 
     acpi.debug_layer=0xffffffff acpi.debug_level=0x2
 
-Enable PCI and PCI interrupt routing debug messages:
+Enable PCI and PCI interrupt routing debug messages::
 
     acpi.debug_layer=0x400000 acpi.debug_level=0x4
 
-Enable all ACPI hardware-related messages:
+Enable all ACPI hardware-related messages::
 
     acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
 
-Enable all ACPI_DB_INFO messages after boot:
+Enable all ACPI_DB_INFO messages after boot::
 
     # echo 0x4 > /sys/module/acpi/parameters/debug_level
 
-Show all valid component values:
+Show all valid component values::
 
     # cat /sys/module/acpi/parameters/debug_layer
Documentation/acpi/dsd/data-node-references.txt +9 -2
index c3871565c8cf..9ccd02bf060c 100644
@@ -1,4 +1,9 @@
+====================
+Data Node References
+====================
+
 Copyright (C) 2018 Intel Corporation
+
 Author: Sakari Ailus <[email protected]>
 
 
@@ -30,6 +35,8 @@ extension key.
 Example
 -------
 
+::
+
 	In the ASL snippet below, the "reference" _DSD property [2] contains a
 	device object reference to DEV0 and under that device object, a
 	hierarchical data extension key "node@1" referring to the NOD1 object
@@ -81,9 +88,9 @@ References
 ----------
 
 [1] Hierarchical Data Extension UUID For _DSD.
-    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+    http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
     referenced 2018-07-17.
 
 [2] Device Properties UUID For _DSD.
-    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+    http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
     referenced 2016-10-04.
Documentation/acpi/dsd/graph.txt +14 -10
index b9ce910781dc..618deddcf512 100644
@@ -1,4 +1,6 @@
+======
 Graphs
+======
 
 
 _DSD
@@ -40,7 +42,7 @@ All port nodes are located under the device's "_DSD" node in the hierarchical
 data extension tree. The data extension related to each port node must begin
 with "port" and must be followed by the "@" character and the number of the port
 as its key. The target object it refers to should be called "PRTX", where "X" is
-the number of the port. An example of such a package would be:
+the number of the port. An example of such a package would be::
 
     Package() { "port@4", PRT4 }
 
@@ -49,7 +51,7 @@ data extension key of the endpoint nodes must begin with
 "endpoint" and must be followed by the "@" character and the number of the
 endpoint. The object it refers to should be called "EPXY", where "X" is the
 number of the port and "Y" is the number of the endpoint. An example of such a
-package would be:
+package would be::
 
     Package() { "endpoint@0", EP40 }
 
@@ -65,7 +67,7 @@ The endpoint reference uses property extension with "remote-endpoint" property
 name followed by a reference in the same package. Such references consist of the
 the remote device reference, the first package entry of the port data extension
 reference under the device and finally the first package entry of the endpoint
-data extension reference under the port. Individual references thus appear as:
+data extension reference under the port. Individual references thus appear as::
 
     Package() { device, "port@X", "endpoint@Y" }
 
@@ -75,7 +77,7 @@ endpoint.
 The references to endpoints must be always done both ways, to the
 remote endpoint and back from the referred remote endpoint node.
 
-A simple example of this is show below:
+A simple example of this is show below::
 
     Scope (\_SB.PCI0.I2C2)
     {
@@ -151,23 +153,25 @@ References
 ----------
 
 [1] _DSD (Device Specific Data) Implementation Guide.
-    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
+    http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
     referenced 2016-10-03.
 
-[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
+[2] Devicetree.
+    http://www.devicetree.org, referenced 2016-10-03.
 
-[3] Documentation/devicetree/bindings/graph.txt
+[3] Linux Kernel device tree graph rules.
+    Documentation/devicetree/bindings/graph.txt
 
 [4] Device Properties UUID For _DSD.
-    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+    http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
     referenced 2016-10-04.
 
 [5] Hierarchical Data Extension UUID For _DSD.
-    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+    URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
     referenced 2016-10-04.
 
 [6] Advanced Configuration and Power Interface Specification.
-    <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
+    http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
     referenced 2016-10-04.
 
 [7] _DSD Device Properties Usage Rules.
Documentation/acpi/dsd/leds.txt +12 -6
index 81a63af42ed2..82ccd5cfb1fd 100644
@@ -1,4 +1,6 @@
+========================================
 Describing and referring to LEDs in ACPI
+========================================
 
 Individual LEDs are described by hierarchical data extension [6] nodes under the
 device node, the LED driver chip. The "reg" property in the LED specific nodes
@@ -26,7 +28,7 @@ followed by the referred object name. That object shall be named "LED" followed
 by the number of the LED.
 
 An ASL example of a camera sensor device and a LED driver device for two LEDs.
-Objects not relevant for LEDs or the references to them have been omitted.
+Objects not relevant for LEDs or the references to them have been omitted::
 
 	Device (LED)
 	{
@@ -72,10 +74,14 @@ Objects not relevant for LEDs or the references to them have been omitted.
 
 where
 
-	LED	LED driver device
-	LED0	First LED
-	LED1	Second LED
-	SEN	Camera sensor device (or another device the LED is
+	LED
+		LED driver device
+	LED0
+		First LED
+	LED1
+		Second LED
+	SEN
+		Camera sensor device (or another device the LED is
 		related to)
 
 [1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21.
@@ -96,4 +102,4 @@ where
     <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
     referenced 2019-02-21.
 
-[7] Documentation/acpi/dsd/data-node-reference.txt
+[7] Documentation/acpi/dsd/data-node-references.txt
Documentation/acpi/dsdt-override.txt +3 -1
index 784841caa6e6..d483b1957be1 100644
@@ -1,4 +1,6 @@
-Linux supports a method of overriding the BIOS DSDT:
+===================================================
+Linux supports a method of overriding the BIOS DSDT
+===================================================
 
 CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel.
 
Documentation/acpi/enumeration.txt +22 -20

139 lines not on this page · raw message

Documentation/acpi/gpio-properties.txt +23 -19

111 lines not on this page · raw message

Documentation/acpi/i2c-muxes.txt +11 -10
index 9fcc4f0b885e..5481cf1ad272 100644
@@ -1,20 +1,21 @@
+==============
 ACPI I2C Muxes
---------------
+==============
 
 Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
 Device () scope per mux channel.
 
-Consider this topology:
+Consider this topology::
 
-+------+   +------+
-| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
-|      |   | 0x70 |--CH01--> i2c client B (0x50)
-+------+   +------+
+  +------+   +------+
+  | SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
+  |      |   | 0x70 |--CH01--> i2c client B (0x50)
+  +------+   +------+
 
-which corresponds to the following ASL:
+which corresponds to the following ASL::
 
-Device (SMB1)
-{
+  Device (SMB1)
+  {
     Name (_HID, ...)
     Device (MUX0)
     {
@@ -55,4 +56,4 @@ Device (SMB1)
             }
         }
     }
-}
+  }
Documentation/acpi/initrd_table_override.txt +48 -42

116 lines not on this page · raw message

Documentation/acpi/linuxized-acpica.txt +38 -20

157 lines not on this page · raw message

Documentation/acpi/lpit.txt +7 -1
index b426398d2e97..b01c97c6f739 100644
@@ -1,3 +1,7 @@
+=====================
+Low Power Idle states
+=====================
+
 To enumerate platform Low Power Idle states, Intel platforms are using
 “Low Power Idle Table” (LPIT). More details about this table can be
 downloaded from:
@@ -8,11 +12,13 @@ Residencies for each low power state can be read via FFH
 
 On platforms supporting S0ix sleep states, there can be two types of
 residencies:
+
 - CPU PKG C10 (Read via FFH interface)
 - Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface)
 
 The following attributes are added dynamically to the cpuidle
-sysfs attribute group:
+sysfs attribute group::
+
 	/sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us
 	/sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us
 
Documentation/acpi/method-customizing.txt +31 -17

93 lines not on this page · raw message

Documentation/acpi/method-tracing.txt +81 -51

193 lines not on this page · raw message

Documentation/acpi/namespace.txt +170 -153

414 lines not on this page · raw message

Documentation/acpi/osi.txt +2 -1
index 50cde0ceb9b0..401518ca15cc 100644
@@ -1,5 +1,6 @@
+==========================
 ACPI _OSI and _REV methods
---------------------------
+==========================
 
 An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
 to find out what the operating system supports. Eg. If BIOS
Documentation/acpi/scan_handlers.txt +6 -3
index 3246ccf15992..fa8265f272d5 100644
@@ -1,6 +1,9 @@
+==================
 ACPI Scan Handlers
+==================
 
 Copyright (C) 2012, Intel Corporation
+
 Author: Rafael J. Wysocki <[email protected]>
 
 During system initialization and ACPI-based device hot-add, the ACPI namespace
@@ -30,14 +33,14 @@ to configure that link so that the kernel can use it.
 Those additional configuration tasks usually depend on the type of the hardware
 component represented by the given device node which can be determined on the
 basis of the device node's hardware ID (HID).  They are performed by objects
-called ACPI scan handlers represented by the following structure:
+called ACPI scan handlers represented by the following structure::
 
-struct acpi_scan_handler {
+  struct acpi_scan_handler {
 	const struct acpi_device_id *ids;
 	struct list_head list_node;
 	int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
 	void (*detach)(struct acpi_device *dev);
-};
+  };
 
 where ids is the list of IDs of device nodes the given handler is supposed to
 take care of, list_node is the hook to the global list of ACPI scan handlers
Documentation/acpi/ssdt-overlays.txt +67 -61

184 lines not on this page · raw message

Documentation/acpi/video_extension.txt +9 -7
index 79bf6a4921be..7a5882a567b9 100644
@@ -1,5 +1,6 @@
+=====================
 ACPI video extensions
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 This driver implement the ACPI Extensions For Display Adapters for
 integrated graphics devices on motherboard, as specified in ACPI 2.0
@@ -32,10 +33,10 @@ type: firmware
 
 Note that ACPI video backlight driver will always use index for
 brightness, actual_brightness and max_brightness. So if we have
-the following _BCL package:
+the following _BCL package::
 
-Method (_BCL, 0, NotSerialized)
-{
+  Method (_BCL, 0, NotSerialized)
+  {
 	Return (Package (0x0C)
 	{
 		0x64,
@@ -51,7 +52,7 @@ Method (_BCL, 0, NotSerialized)
 		0x5A,
 		0x64
 	})
-}
+  }
 
 The first two levels are for when laptop are on AC or on battery and are
 not used by Linux currently. The remaining 10 levels are supported levels
@@ -65,10 +66,11 @@ inclusive.
 2 Notify user space about hotkey event
 
 There are generally two cases for hotkey event reporting:
+
 i) For some laptops, when user presses the hotkey, a scancode will be
    generated and sent to user space through the input device created by
    the keyboard driver as a key type input event, with proper remap, the
-   following key code will appear to user space:
+   following key code will appear to user space::
 
 	EV_KEY, KEY_BRIGHTNESSUP
 	EV_KEY, KEY_BRIGHTNESSDOWN
@@ -82,7 +84,7 @@ ii) For some laptops, the press of the hotkey will not generate the
     about the event. The event value is defined in the ACPI spec. ACPI
     video driver will generate an key type input event according to the
     notify value it received and send the event to user space through the
-    input device it created:
+    input device it created::
 
 	event		keycode
 	0x86		KEY_BRIGHTNESSUP
Signature · 1 line
2.20.1
#3 lore raw

Re: [PATCH 02/57] docs: acpi: convert text files to ReST

Quoted 5 lines · Mauro Carvalho Chehab

Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.

There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2

I'd prefer that one to continue, honestly.

Thanks,
Rafael

#4 lore raw

Re: [PATCH 02/57] docs: acpi: convert text files to ReST

Em Tue, 16 Apr 2019 10:17:11 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:

Quoted 8 lines
Quoted 5 lines · Mauro Carvalho Chehab

Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.

Quoted 4 lines

There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2

I'd prefer that one to continue, honestly.

Agreed. I didn't notice the patchset.

Btw, please notice patch 11/57:

Subject: [PATCH 11/57] docs: extcon: move it to acpi dir and convert it to ReST

IMO, it makes sense to move the extcon driver to ACPI, as it sounds to be just another ACPI driver.

Thanks,
Mauro

#5 lore raw

Re: [PATCH 02/57] docs: acpi: convert text files to ReST

Quoted 17 lines · Mauro Carvalho Chehab

Em Tue, 16 Apr 2019 10:17:11 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:

Quoted 8 lines
Quoted 5 lines · Mauro Carvalho Chehab

Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.

Quoted 4 lines

There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2

I'd prefer that one to continue, honestly.

Quoted 8 lines

Agreed. I didn't notice the patchset.

Btw, please notice patch 11/57:

Subject: [PATCH 11/57] docs: extcon: move it to acpi dir and convert it to ReST

IMO, it makes sense to move the extcon driver to ACPI, as it sounds to be just another ACPI driver.

But that can be done later, on top of the Changbin Du's changes.

Thanks,
Rafael

#6 lore raw

Re: [PATCH 02/57] docs: acpi: convert text files to ReST

In reply to Rafael J. Wysocki
Quoted 11 lines · Rafael J. Wysocki
Quoted 5 lines · Mauro Carvalho Chehab

Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.

There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2

I will update the serias asap. I am just a little busy these days. My conversion includes pci, acpi and x86, others are not touched.

Quoted 4 lines

I'd prefer that one to continue, honestly.

Thanks,
Rafael

Signature · 2 lines
Cheers,
Changbin Du
#7 lore raw

Re: [PATCH 02/57] docs: acpi: convert text files to ReST

Em Tue, 16 Apr 2019 14:55:19 +0000
Changbin Du <[email protected]> escreveu:

Quoted 9 lines · Rafael J. Wysocki
Quoted 8 lines
Quoted 5 lines · Mauro Carvalho Chehab

Most of the files are already in good shape, making easier to convert them to ReST by adding proper title markups and addressing some identation and markups to properly format the document.

Quoted 5 lines
Quoted 3 lines

There is concurrent work on this under way, please see
https://marc.info/?t=155381845300002&r=2&w=2

I will update the serias asap. I am just a little busy these days. My conversion includes pci, acpi and x86, others are not touched.

Ok, I sent a new patch series without pci, acpi and x86.

While these aren't merged upstream, I'm keeping my old patches on my tree:

	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=805b16dd336dd3c27733f02ec8164b2a182972a3
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=c950031ccb87ea14ff4c56f2433072d580db3572
	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_v2&id=4f8afce866dcd8067206b3ee493ed0b682694f49

If you find anything there that would be interesting for your series, feel free to pick from them. Everything is based on linux-next.

Thanks,
Mauro

#8 lore raw

PATCH 3/57 docs: aoe: convert text files to ReST

In reply to Mauro Carvalho Chehab

There are only two files within Documentation/aoe dir that are documentation. The remaining ones are examples and shell scripts.

Convert the two AoE files to ReST format.

---
 Documentation/aoe/aoe.txt  | 63 +++++++++++++++++++++-----------------
 Documentation/aoe/todo.txt |  3 ++
 Documentation/aoe/udev.txt |  2 +-
 3 files changed, 39 insertions(+), 29 deletions(-)
Documentation/aoe/aoe.txt +35 -28
index c71487d399d1..58747ecec71d 100644
@@ -1,3 +1,6 @@
+Introduction
+============
+
 ATA over Ethernet is a network protocol that provides simple access to
 block storage on the LAN.
 
@@ -22,7 +25,8 @@ document the use of the driver and are not necessary if you install
 the aoetools.
 
 
-CREATING DEVICE NODES
+Creating Device Nodes
+=====================
 
   Users of udev should find the block device nodes created
   automatically, but to create all the necessary device nodes, use the
@@ -38,7 +42,8 @@ CREATING DEVICE NODES
   confusing when an AoE device is not present the first time the a
   command is run but appears a second later.
 
-USING DEVICE NODES
+Using Device Nodes
+==================
 
   "cat /dev/etherd/err" blocks, waiting for error diagnostic output,
   like any retransmitted packets.
@@ -55,7 +60,7 @@ USING DEVICE NODES
   by sysfs counterparts.  Using the commands in aoetools insulates
   users from these implementation details.
 
-  The block devices are named like this:
+  The block devices are named like this::
 
 	e{shelf}.{slot}
 	e{shelf}.{slot}p{part}
@@ -64,7 +69,8 @@ USING DEVICE NODES
   first shelf (shelf address zero).  That's the whole disk.  The first
   partition on that disk would be "e0.2p1".
 
-USING SYSFS
+Using sysfs
+===========
 
   Each aoe block device in /sys/block has the extra attributes of
   state, mac, and netif.  The state attribute is "up" when the device
@@ -78,29 +84,29 @@ USING SYSFS
 
   There is a script in this directory that formats this information in
   a convenient way.  Users with aoetools should use the aoe-stat
-  command.
+  command::
 
-  root@makki root# sh Documentation/aoe/status.sh 
-     e10.0            eth3              up
-     e10.1            eth3              up
-     e10.2            eth3              up
-     e10.3            eth3              up
-     e10.4            eth3              up
-     e10.5            eth3              up
-     e10.6            eth3              up
-     e10.7            eth3              up
-     e10.8            eth3              up
-     e10.9            eth3              up
-      e4.0            eth1              up
-      e4.1            eth1              up
-      e4.2            eth1              up
-      e4.3            eth1              up
-      e4.4            eth1              up
-      e4.5            eth1              up
-      e4.6            eth1              up
-      e4.7            eth1              up
-      e4.8            eth1              up
-      e4.9            eth1              up
+    root@makki root# sh Documentation/aoe/status.sh
+       e10.0            eth3              up
+       e10.1            eth3              up
+       e10.2            eth3              up
+       e10.3            eth3              up
+       e10.4            eth3              up
+       e10.5            eth3              up
+       e10.6            eth3              up
+       e10.7            eth3              up
+       e10.8            eth3              up
+       e10.9            eth3              up
+        e4.0            eth1              up
+        e4.1            eth1              up
+        e4.2            eth1              up
+        e4.3            eth1              up
+        e4.4            eth1              up
+        e4.5            eth1              up
+        e4.6            eth1              up
+        e4.7            eth1              up
+        e4.8            eth1              up
+        e4.9            eth1              up
 
   Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver
   option discussed below) instead of /dev/etherd/interfaces to limit
@@ -113,12 +119,13 @@ USING SYSFS
   for this purpose.  You can also directly use the
   /dev/etherd/discover special file described above.
 
-DRIVER OPTIONS
+Driver Options
+==============
 
   There is a boot option for the built-in aoe driver and a
   corresponding module parameter, aoe_iflist.  Without this option,
   all network interfaces may be used for ATA over Ethernet.  Here is a
-  usage example for the module parameter.
+  usage example for the module parameter::
 
     modprobe aoe_iflist="eth1 eth3"
 
Documentation/aoe/todo.txt +3 -0
index c09dfad4aed8..dea8db5a33e1 100644
@@ -1,3 +1,6 @@
+TODO
+====
+
 There is a potential for deadlock when allocating a struct sk_buff for
 data that needs to be written out to aoe storage.  If the data is
 being written from a dirty page in order to free that page, and if
Documentation/aoe/udev.txt +1 -1
index 1f06daf03f5b..54feda5a0772 100644
@@ -11,7 +11,7 @@
 #   udev_rules="/etc/udev/rules.d/"
 #   bash# ls /etc/udev/rules.d/
 #   10-wacom.rules  50-udev.rules
-#   bash# cp /path/to/linux-2.6.xx/Documentation/aoe/udev.txt \
+#   bash# cp /path/to/linux/Documentation/aoe/udev.txt \
 #           /etc/udev/rules.d/60-aoe.rules
 #  
 
Signature · 1 line
2.20.1
#9 lore raw

PATCH 4/57 docs: arm64: convert documentation to ReST format

In reply to Mauro Carvalho Chehab

The documentation is in pretty much ReST format. Just some small adjustments in order to fix tables and to make Sphinx to recognize certain format blocks are required.

---
 Documentation/arm64/acpi_object_usage.txt     | 288 ++++++++++++------
 Documentation/arm64/arm-acpi.txt              | 153 +++++-----
 Documentation/arm64/booting.txt               |  91 ++++--
 Documentation/arm64/cpu-feature-registers.txt | 190 ++++++------
 Documentation/arm64/elf_hwcaps.txt            |  50 +--
 Documentation/arm64/hugetlbpage.txt           |   7 +-
 Documentation/arm64/legacy_instructions.txt   |  43 ++-
 Documentation/arm64/memory.txt                |  91 +++---
 .../arm64/pointer-authentication.txt          |   2 +
 Documentation/arm64/silicon-errata.txt        |  63 +++-
 Documentation/arm64/sve.txt                   |  10 +-
 Documentation/arm64/tagged-pointers.txt       |   6 +-
 arch/arm64/kernel/kexec_image.c               |   2 +-
 13 files changed, 595 insertions(+), 401 deletions(-)
Documentation/arm64/acpi_object_usage.txt +202 -86
index c77010c5c1f0..d51b69dc624d 100644
@@ -1,5 +1,7 @@
+===========
 ACPI Tables
------------
+===========
+
 The expectations of individual ACPI tables are discussed in the list that
 follows.
 
@@ -11,54 +13,71 @@ outside of the UEFI Forum (see Section 5.2.6 of the specification).
 
 For ACPI on arm64, tables also fall into the following categories:
 
-       -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
+       -  Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT
 
-       -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
+       -  Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT
 
-       -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
+       -  Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, IORT,
           MCHI, MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO,
 	  TCPA, TPM2, UEFI, XENV
 
-       -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
+       -  Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT,
           MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT
 
+====== ========================================================================
 Table  Usage for ARMv8 Linux
------  ----------------------------------------------------------------
+====== ========================================================================
 BERT   Section 18.3 (signature == "BERT")
-       == Boot Error Record Table ==
+
+       **Boot Error Record Table**
+
        Must be supplied if RAS support is provided by the platform.  It
        is recommended this table be supplied.
 
 BOOT   Signature Reserved (signature == "BOOT")
-       == simple BOOT flag table ==
+
+       **simple BOOT flag table**
+
        Microsoft only table, will not be supported.
 
 BGRT   Section 5.2.22 (signature == "BGRT")
-       == Boot Graphics Resource Table ==
+
+       **Boot Graphics Resource Table**
+
        Optional, not currently supported, with no real use-case for an
        ARM server.
 
 CPEP   Section 5.2.18 (signature == "CPEP")
-       == Corrected Platform Error Polling table ==
+
+       **Corrected Platform Error Polling table**
+
        Optional, not currently supported, and not recommended until such
        time as ARM-compatible hardware is available, and the specification
        suitably modified.
 
 CSRT   Signature Reserved (signature == "CSRT")
-       == Core System Resources Table ==
+
+       **Core System Resources Table**
+
        Optional, not currently supported.
 
 DBG2   Signature Reserved (signature == "DBG2")
-       == DeBuG port table 2 ==
+
+       **DeBuG port table 2**
+
        License has changed and should be usable.  Optional if used instead
        of earlycon=<device> on the command line.
 
 DBGP   Signature Reserved (signature == "DBGP")
-       == DeBuG Port table ==
+
+       **DeBuG Port table**
+
        Microsoft only table, will not be supported.
 
 DSDT   Section 5.2.11.1 (signature == "DSDT")
-       == Differentiated System Description Table ==
+
+       **Differentiated System Description Table**
+
        A DSDT is required; see also SSDT.
 
        ACPI tables contain only one DSDT but can contain one or more SSDTs,
@@ -66,22 +85,30 @@ DSDT   Section 5.2.11.1 (signature == "DSDT")
        but cannot modify or replace anything in the DSDT.
 
 DMAR   Signature Reserved (signature == "DMAR")
-       == DMA Remapping table ==
+
+       **DMA Remapping table**
+
        x86 only table, will not be supported.
 
 DRTM   Signature Reserved (signature == "DRTM")
-       == Dynamic Root of Trust for Measurement table ==
+
+       **Dynamic Root of Trust for Measurement table**
+
        Optional, not currently supported.
 
 ECDT   Section 5.2.16 (signature == "ECDT")
-       == Embedded Controller Description Table ==
+
+       **Embedded Controller Description Table**
+
        Optional, not currently supported, but could be used on ARM if and
        only if one uses the GPE_BIT field to represent an IRQ number, since
        there are no GPE blocks defined in hardware reduced mode.  This would
        need to be modified in the ACPI specification.
 
 EINJ   Section 18.6 (signature == "EINJ")
-       == Error Injection table ==
+
+       **Error Injection table**
+
        This table is very useful for testing platform response to error
        conditions; it allows one to inject an error into the system as
        if it had actually occurred.  However, this table should not be
@@ -89,27 +116,35 @@ EINJ   Section 18.6 (signature == "EINJ")
        and executed with the ACPICA tools only during testing.
 
 ERST   Section 18.5 (signature == "ERST")
-       == Error Record Serialization Table ==
+
+       **Error Record Serialization Table**
+
        On a platform supports RAS, this table must be supplied if it is not
        UEFI-based; if it is UEFI-based, this table may be supplied. When this
        table is not present, UEFI run time service will be utilized to save
        and retrieve hardware error information to and from a persistent store.
 
 ETDT   Signature Reserved (signature == "ETDT")
-       == Event Timer Description Table ==
+
+       **Event Timer Description Table**
+
        Obsolete table, will not be supported.
 
 FACS   Section 5.2.10 (signature == "FACS")
-       == Firmware ACPI Control Structure ==
+
+       **Firmware ACPI Control Structure**
+
        It is unlikely that this table will be terribly useful.  If it is
        provided, the Global Lock will NOT be used since it is not part of
        the hardware reduced profile, and only 64-bit address fields will
        be considered valid.
 
 FADT   Section 5.2.9 (signature == "FACP")
-       == Fixed ACPI Description Table ==
+
+       **Fixed ACPI Description Table**
        Required for arm64.
 
+
        The HW_REDUCED_ACPI flag must be set.  All of the fields that are
        to be ignored when HW_REDUCED_ACPI is set are expected to be set to
        zero.
@@ -118,22 +153,28 @@ FADT   Section 5.2.9 (signature == "FACP")
        used, not FIRMWARE_CTRL.
 
        If PSCI is used (as is recommended), make sure that ARM_BOOT_ARCH is
-       filled in properly -- that the PSCI_COMPLIANT flag is set and that
+       filled in properly - that the PSCI_COMPLIANT flag is set and that
        PSCI_USE_HVC is set or unset as needed (see table 5-37).
 
        For the DSDT that is also required, the X_DSDT field is to be used,
        not the DSDT field.
 
 FPDT   Section 5.2.23 (signature == "FPDT")
-       == Firmware Performance Data Table ==
+
+       **Firmware Performance Data Table**
+
        Optional, not currently supported.
 
 GTDT   Section 5.2.24 (signature == "GTDT")
-       == Generic Timer Description Table ==
+
+       **Generic Timer Description Table**
+
        Required for arm64.
 
 HEST   Section 18.3.2 (signature == "HEST")
-       == Hardware Error Source Table ==
+
+       **Hardware Error Source Table**
+
        ARM-specific error sources have been defined; please use those or the
        PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER
        Bridge), or use type 9 (Generic Hardware Error Source).  Firmware first
@@ -144,122 +185,174 @@ HEST   Section 18.3.2 (signature == "HEST")
        is recommended this table be supplied.
 
 HPET   Signature Reserved (signature == "HPET")
-       == High Precision Event timer Table ==
+
+       **High Precision Event timer Table**
+
        x86 only table, will not be supported.
 
 IBFT   Signature Reserved (signature == "IBFT")
-       == iSCSI Boot Firmware Table ==
+
+       **iSCSI Boot Firmware Table**
+
        Microsoft defined table, support TBD.
 
 IORT   Signature Reserved (signature == "IORT")
-       == Input Output Remapping Table ==
+
+       **Input Output Remapping Table**
+
        arm64 only table, required in order to describe IO topology, SMMUs,
        and GIC ITSs, and how those various components are connected together,
        such as identifying which components are behind which SMMUs/ITSs.
        This table will only be required on certain SBSA platforms (e.g.,
-       when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it 
+       when using GICv3-ITS and an SMMU); on SBSA Level 0 platforms, it
        remains optional.
 
 IVRS   Signature Reserved (signature == "IVRS")
-       == I/O Virtualization Reporting Structure ==
+
+       **I/O Virtualization Reporting Structure**
+
        x86_64 (AMD) only table, will not be supported.
 
 LPIT   Signature Reserved (signature == "LPIT")
-       == Low Power Idle Table ==
+
+       **Low Power Idle Table**
+
        x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor
        descriptions and power states on ARM platforms should use the DSDT
        and define processor container devices (_HID ACPI0010, Section 8.4,
        and more specifically 8.4.3 and and 8.4.4).
 
 MADT   Section 5.2.12 (signature == "APIC")
-       == Multiple APIC Description Table ==
+
+       **Multiple APIC Description Table**
+
        Required for arm64.  Only the GIC interrupt controller structures
        should be used (types 0xA - 0xF).
 
 MCFG   Signature Reserved (signature == "MCFG")
-       == Memory-mapped ConFiGuration space ==
+
+       **Memory-mapped ConFiGuration space**
+
        If the platform supports PCI/PCIe, an MCFG table is required.
 
 MCHI   Signature Reserved (signature == "MCHI")
-       == Management Controller Host Interface table ==
+
+       **Management Controller Host Interface table**
+
        Optional, not currently supported.
 
 MPST   Section 5.2.21 (signature == "MPST")
-       == Memory Power State Table ==
+
+       **Memory Power State Table**
+
        Optional, not currently supported.
 
 MSCT   Section 5.2.19 (signature == "MSCT")
-       == Maximum System Characteristic Table ==
+
+       **Maximum System Characteristic Table**
+
        Optional, not currently supported.
 
 MSDM   Signature Reserved (signature == "MSDM")
-       == Microsoft Data Management table ==
+
+       **Microsoft Data Management table**
+
        Microsoft only table, will not be supported.
 
 NFIT   Section 5.2.25 (signature == "NFIT")
-       == NVDIMM Firmware Interface Table ==
+
+       **NVDIMM Firmware Interface Table**
+
        Optional, not currently supported.
 
 OEMx   Signature of "OEMx" only
-       == OEM Specific Tables ==
+
+       **OEM Specific Tables**
+
        All tables starting with a signature of "OEM" are reserved for OEM
        use.  Since these are not meant to be of general use but are limited
        to very specific end users, they are not recommended for use and are
        not supported by the kernel for arm64.
 
 PCCT   Section 14.1 (signature == "PCCT)
-       == Platform Communications Channel Table ==
+
+       **Platform Communications Channel Table**
+
        Recommend for use on arm64; use of PCC is recommended when using CPPC
        to control performance and power for platform processors.
 
 PMTT   Section 5.2.21.12 (signature == "PMTT")
-       == Platform Memory Topology Table ==
+
+       **Platform Memory Topology Table**
+
        Optional, not currently supported.
 
 PSDT   Section 5.2.11.3 (signature == "PSDT")
-       == Persistent System Description Table ==
+
+       **Persistent System Description Table**
+
        Obsolete table, will not be supported.
 
 RASF   Section 5.2.20 (signature == "RASF")
-       == RAS Feature table ==
+
+       **RAS Feature table**
+
        Optional, not currently supported.
 
 RSDP   Section 5.2.5 (signature == "RSD PTR")
-       == Root System Description PoinTeR ==
+
+       **Root System Description PoinTeR**
+
        Required for arm64.
 
 RSDT   Section 5.2.7 (signature == "RSDT")
-       == Root System Description Table ==
+
+       **Root System Description Table**
+
        Since this table can only provide 32-bit addresses, it is deprecated
        on arm64, and will not be used.  If provided, it will be ignored.
 
 SBST   Section 5.2.14 (signature == "SBST")
-       == Smart Battery Subsystem Table ==
+
+       **Smart Battery Subsystem Table**
+
        Optional, not currently supported.
 
 SLIC   Signature Reserved (signature == "SLIC")
-       == Software LIcensing table ==
+
+       **Software LIcensing table**
+
        Microsoft only table, will not be supported.
 
 SLIT   Section 5.2.17 (signature == "SLIT")
-       == System Locality distance Information Table ==
+
+       **System Locality distance Information Table**
+
        Optional in general, but required for NUMA systems.
 
 SPCR   Signature Reserved (signature == "SPCR")
-       == Serial Port Console Redirection table ==
+
+       **Serial Port Console Redirection table**
+
        Required for arm64.
 
 SPMI   Signature Reserved (signature == "SPMI")
-       == Server Platform Management Interface table ==
+
+       **Server Platform Management Interface table**
+
        Optional, not currently supported.
 
 SRAT   Section 5.2.16 (signature == "SRAT")
-       == System Resource Affinity Table ==
+
+       **System Resource Affinity Table**
+
        Optional, but if used, only the GICC Affinity structures are read.
        To support arm64 NUMA, this table is required.
 
 SSDT   Section 5.2.11.2 (signature == "SSDT")
-       == Secondary System Description Table ==
+
+       **Secondary System Description Table**
+
        These tables are a continuation of the DSDT; these are recommended
        for use with devices that can be added to a running system, but can
        also serve the purpose of dividing up device descriptions into more
@@ -272,49 +365,69 @@ SSDT   Section 5.2.11.2 (signature == "SSDT")
        one DSDT but can contain many SSDTs.
 
 STAO   Signature Reserved (signature == "STAO")
-       == _STA Override table ==
+
+       **_STA Override table**
+
        Optional, but only necessary in virtualized environments in order to
        hide devices from guest OSs.
 
 TCPA   Signature Reserved (signature == "TCPA")
-       == Trusted Computing Platform Alliance table ==
+
+       **Trusted Computing Platform Alliance table**
+
        Optional, not currently supported, and may need changes to fully
        interoperate with arm64.
 
 TPM2   Signature Reserved (signature == "TPM2")
-       == Trusted Platform Module 2 table ==
+
+       **Trusted Platform Module 2 table**
+
        Optional, not currently supported, and may need changes to fully
        interoperate with arm64.
 
 UEFI   Signature Reserved (signature == "UEFI")
-       == UEFI ACPI data table ==
+
+       **UEFI ACPI data table**
+
        Optional, not currently supported.  No known use case for arm64,
        at present.
 
 WAET   Signature Reserved (signature == "WAET")
-       == Windows ACPI Emulated devices Table ==
+
+       **Windows ACPI Emulated devices Table**
+
        Microsoft only table, will not be supported.
 
 WDAT   Signature Reserved (signature == "WDAT")
-       == Watch Dog Action Table ==
+
+       **Watch Dog Action Table**
+
        Microsoft only table, will not be supported.
 
 WDRT   Signature Reserved (signature == "WDRT")
-       == Watch Dog Resource Table ==
+
+       **Watch Dog Resource Table**
+
        Microsoft only table, will not be supported.
 
 WPBT   Signature Reserved (signature == "WPBT")
-       == Windows Platform Binary Table ==
+
+       **Windows Platform Binary Table**
+
        Microsoft only table, will not be supported.
 
 XENV   Signature Reserved (signature == "XENV")
-       == Xen project table ==
+
+       **Xen project table**
+
        Optional, used only by Xen at present.
 
 XSDT   Section 5.2.8 (signature == "XSDT")
-       == eXtended System Description Table ==
+
+       **eXtended System Description Table**
+
        Required for arm64.
-
+====== ========================================================================
 
 ACPI Objects
 ------------
@@ -323,10 +436,11 @@ shown in the list that follows; any object not explicitly mentioned below
 should be used as needed for a particular platform or particular subsystem,
 such as power management or PCI.
 
+===== ================ ========================================================
 Name   Section         Usage for ARMv8 Linux
-----   ------------    -------------------------------------------------
+===== ================ ========================================================
 _CCA   6.2.17          This method must be defined for all bus masters
-                       on arm64 -- there are no assumptions made about
+                       on arm64 - there are no assumptions made about
                        whether such devices are cache coherent or not.
                        The _CCA value is inherited by all descendants of
                        these devices so it does not need to be repeated.
@@ -422,8 +536,8 @@ _OSC   6.2.11          This method can be a global method in ACPI (i.e.,
                        by the kernel community, then register it with the
                        UEFI Forum.
 
-\_OSI  5.7.2           Deprecated on ARM64.  As far as ACPI firmware is 
-		       concerned, _OSI is not to be used to determine what 
+\_OSI  5.7.2           Deprecated on ARM64.  As far as ACPI firmware is
+		       concerned, _OSI is not to be used to determine what
 		       sort of system is being used or what functionality
 		       is provided.  The _OSC method is to be used instead.
 
@@ -447,7 +561,7 @@ _PSx   7.3.2-5         Use as needed; power management specific.  If _PS0 is
                        usage, change them in these methods.
 
 _RDI   8.4.4.4         Recommended for use with processor definitions (_HID
-		       ACPI0010) on arm64.  This should only be used in 
+		       ACPI0010) on arm64.  This should only be used in
 		       conjunction with _LPI.
 
 \_REV  5.7.4           Always returns the latest version of ACPI supported.
@@ -476,6 +590,7 @@ _SWS   7.4.3           Use as needed; power management specific; this may
 
 _UID   6.1.12          Recommended for distinguishing devices of the same
                        class; define it if at all possible.
+===== ================ ========================================================
 
 
 
@@ -488,7 +603,7 @@ platforms, ACPI events must be signaled differently.
 
 There are two options: GPIO-signaled interrupts (Section 5.6.5), and
 interrupt-signaled events (Section 5.6.9).  Interrupt-signaled events are a
-new feature in the ACPI 6.1 specification.  Either -- or both -- can be used
+new feature in the ACPI 6.1 specification.  Either - or both - can be used
 on a given platform, and which to use may be dependent of limitations in any
 given SoC.  If possible, interrupt-signaled events are recommended.
 
@@ -564,39 +679,40 @@ supported.
 
 The following classes of objects are not supported:
 
-       -- Section 9.2: ambient light sensor devices
+       -  Section 9.2: ambient light sensor devices
 
-       -- Section 9.3: battery devices
+       -  Section 9.3: battery devices
 
-       -- Section 9.4: lids (e.g., laptop lids)
+       -  Section 9.4: lids (e.g., laptop lids)
 
-       -- Section 9.8.2: IDE controllers
+       -  Section 9.8.2: IDE controllers
 
-       -- Section 9.9: floppy controllers
+       -  Section 9.9: floppy controllers
 
-       -- Section 9.10: GPE block devices
+       -  Section 9.10: GPE block devices
 
-       -- Section 9.15: PC/AT RTC/CMOS devices
+       -  Section 9.15: PC/AT RTC/CMOS devices
 
-       -- Section 9.16: user presence detection devices
+       -  Section 9.16: user presence detection devices
 
-       -- Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
+       -  Section 9.17: I/O APIC devices; all GICs must be enumerable via MADT
 
-       -- Section 9.18: time and alarm devices (see 9.15)
+       -  Section 9.18: time and alarm devices (see 9.15)
 
-       -- Section 10: power source and power meter devices
+       -  Section 10: power source and power meter devices
 
-       -- Section 11: thermal management
+       -  Section 11: thermal management
 
-       -- Section 12: embedded controllers interface
+       -  Section 12: embedded controllers interface
 
-       -- Section 13: SMBus interfaces
+       -  Section 13: SMBus interfaces
 
 
 This also means that there is no support for the following objects:
 
+====   =========================== ====   ==========
 Name   Section                     Name   Section
-----   ------------                ----   ------------
+====   =========================== ====   ==========
 _ALC   9.3.4                       _FDM   9.10.3
 _ALI   9.3.2                       _FIX   6.2.7
 _ALP   9.3.6                       _GAI   10.4.5
@@ -619,4 +735,4 @@ _DCK   6.5.2                       _UPD   9.16.1
 _EC    12.12                       _UPP   9.16.2
 _FDE   9.10.1                      _WPC   10.5.2
 _FDI   9.10.2                      _WPP   10.5.3
-
+====   =========================== ====   ==========
Documentation/arm64/arm-acpi.txt +81 -72

272 lines not on this page · raw message

Documentation/arm64/booting.txt +59 -32

164 lines not on this page · raw message

Documentation/arm64/cpu-feature-registers.txt +99 -91

311 lines not on this page · raw message

Documentation/arm64/elf_hwcaps.txt +10 -40

169 lines not on this page · raw message

Documentation/arm64/hugetlbpage.txt +5 -2
index cfae87dc653b..b44f939e5210 100644
@@ -1,3 +1,4 @@
+====================
 HugeTLBpage on ARM64
 ====================
 
@@ -31,8 +32,10 @@ and level of the page table.
 
 The following hugepage sizes are supported -
 
-         CONT PTE    PMD    CONT PMD    PUD
-         --------    ---    --------    ---
+  ====== ========   ====    ========    ===
+  -      CONT PTE    PMD    CONT PMD    PUD
+  ====== ========   ====    ========    ===
   4K:         64K     2M         32M     1G
   16K:         2M    32M          1G
   64K:         2M   512M         16G
+  ====== ========   ====    ========    ===
Documentation/arm64/legacy_instructions.txt +27 -16

69 lines not on this page · raw message

Documentation/arm64/memory.txt +46 -45

120 lines not on this page · raw message

Documentation/arm64/pointer-authentication.txt +2 -0
index 5baca42ba146..f8b9af8b6490 100644
@@ -1,7 +1,9 @@
+=======================================
 Pointer authentication in AArch64 Linux
 =======================================
 
 Author: Mark Rutland <[email protected]>
+
 Date: 2017-07-19
 
 This document briefly describes the provision of pointer authentication
Documentation/arm64/silicon-errata.txt +52 -11

115 lines not on this page · raw message

Documentation/arm64/sve.txt +7 -3
index 7169a0ec41d8..d73c8e04b22b 100644
@@ -1,7 +1,9 @@
-            Scalable Vector Extension support for AArch64 Linux
-            ===================================================
+===================================================
+Scalable Vector Extension support for AArch64 Linux
+===================================================
 
 Author: Dave Martin <[email protected]>
+
 Date:   4 August 2017
 
 This document outlines briefly the interface provided to userspace by Linux in
@@ -409,7 +411,7 @@ In A64 state, SVE adds the following:
 
 * FPSR and FPCR are retained from ARMv8-A, and interact with SVE floating-point
   operations in a similar way to the way in which they interact with ARMv8
-  floating-point operations.
+  floating-point operations::
 
          8VL-1                       128               0  bit index
         +----          ////            -----------------+
@@ -466,6 +468,8 @@ ARMv8-A defines the following floating-point / SIMD register state:
 * 32 128-bit vector registers V0..V31
 * 2 32-bit status/control registers FPSR, FPCR
 
+::
+
          127           0  bit index
         +---------------+
      V0 |               |
Documentation/arm64/tagged-pointers.txt +4 -2
index a25a99e82bb1..2acdec3ebbeb 100644
@@ -1,7 +1,9 @@
-		Tagged virtual addresses in AArch64 Linux
-		=========================================
+=========================================
+Tagged virtual addresses in AArch64 Linux
+=========================================
 
 Author: Will Deacon <[email protected]>
+
 Date  : 12 June 2013
 
 This document briefly describes the provision of tagged virtual
arch/arm64/kernel/kexec_image.c +1 -1
index 07bf740bea91..31cc2f423aa8 100644
@@ -53,7 +53,7 @@ static void *image_load(struct kimage *image,
 
 	/*
 	 * We require a kernel with an unambiguous Image header. Per
-	 * Documentation/booting.txt, this is the case when image_size
+	 * Documentation/arm64/booting.txt, this is the case when image_size
 	 * is non-zero (practically speaking, since v3.17).
 	 */
 	h = (struct arm64_image_header *)kernel;
Signature · 7 lines
2.20.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
#10 lore raw

PATCH 5/57 docs: cdrom/cdrom-standard.tex: convert from LaTeX to ReST

In reply to Mauro Carvalho Chehab

Instead of having a Latex document directly there, convert it to ReST format, as this is the Kernel format for docs.

For now, let's keep the extension as .txt in order to avoid warnings when building the documentation with Sphinx.

A later patch will rename it to .rst and add it to the building system.

---
 Documentation/cdrom/Makefile           |   21 -
 Documentation/cdrom/cdrom-standard.tex | 1026 -----------------------
 Documentation/cdrom/cdrom-standard.txt | 1063 ++++++++++++++++++++++++
 drivers/cdrom/cdrom.c                  |    2 +-
 4 files changed, 1064 insertions(+), 1048 deletions(-)
 delete mode 100644 Documentation/cdrom/Makefile
 delete mode 100644 Documentation/cdrom/cdrom-standard.tex
 create mode 100644 Documentation/cdrom/cdrom-standard.txt
Documentation/cdrom/Makefile deleted +0 -21
deleted file mode 100644
index a19e321928e1..000000000000
@@ -1,21 +0,0 @@
-LATEXFILE = cdrom-standard
-
-all:
-	make clean
-	latex $(LATEXFILE)
-	latex $(LATEXFILE)
-	@if [ -x `which gv` ]; then \
-		`dvips -q -t letter -o $(LATEXFILE).ps $(LATEXFILE).dvi` ;\
-		`gv -antialias -media letter -nocenter $(LATEXFILE).ps` ;\
-	else \
-		`xdvi $(LATEXFILE).dvi &` ;\
-	fi
-	make sortofclean
-
-clean:
-	rm -f $(LATEXFILE).ps $(LATEXFILE).dvi $(LATEXFILE).aux $(LATEXFILE).log 
-
-sortofclean:
-	rm -f $(LATEXFILE).aux $(LATEXFILE).log 
-
-
Documentation/cdrom/cdrom-standard.tex deleted +0 -1026

1,026 lines not on this page · raw message

Documentation/cdrom/cdrom-standard.txt new file +1063 -0

1,063 lines not on this page · raw message

drivers/cdrom/cdrom.c +1 -1
index 933268b8d6a5..5d1e0a4a7d84 100644
@@ -7,7 +7,7 @@
    License.  See linux/COPYING for more information.
 
    Uniform CD-ROM driver for Linux.
-   See Documentation/cdrom/cdrom-standard.tex for usage information.
+   See Documentation/cdrom/cdrom-standard.txt for usage information.
 
    The routines in the file provide a uniform interface between the
    software that uses CD-ROMs and the various low-level drivers that
Signature · 1 line
2.20.1
#11 lore raw

PATCH 6/57 docs: cdrom: convert remaining files to ReST

In reply to Mauro Carvalho Chehab

The stuff there is almost already at ReST format. A conversion for them is trivial: just add a missing titles and fix some scape codes for them to match ReST syntax.

---
 Documentation/cdrom/ide-cd             | 178 +++++++++++++------------
 Documentation/cdrom/packet-writing.txt |  27 ++--
 2 files changed, 108 insertions(+), 97 deletions(-)
Documentation/cdrom/ide-cd +91 -87
index a5f2a7f1ff46..dadc94ef6b6c 100644
@@ -1,18 +1,20 @@
 IDE-CD driver documentation
-Originally by scott snyder  <[email protected]> (19 May 1996)
-Carrying on the torch is: Erik Andersen <[email protected]>
-New maintainers (19 Oct 1998): Jens Axboe <[email protected]>
+===========================
+
+:Originally by: scott snyder  <[email protected]> (19 May 1996)
+:Carrying on the torch is: Erik Andersen <[email protected]>
+:New maintainers (19 Oct 1998): Jens Axboe <[email protected]>
 
 1. Introduction
 ---------------
 
-The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant 
+The ide-cd driver should work with all ATAPI ver 1.2 to ATAPI 2.6 compliant
 CDROM drives which attach to an IDE interface.  Note that some CDROM vendors
 (including Mitsumi, Sony, Creative, Aztech, and Goldstar) have made
 both ATAPI-compliant drives and drives which use a proprietary
 interface.  If your drive uses one of those proprietary interfaces,
 this driver will not work with it (but one of the other CDROM drivers
-probably will).  This driver will not work with `ATAPI' drives which
+probably will).  This driver will not work with `ATAPI` drives which
 attach to the parallel port.  In addition, there is at least one drive
 (CyCDROM CR520ie) which attaches to the IDE port but is not ATAPI;
 this driver will not work with drives like that either (but see the
@@ -31,7 +33,7 @@ This driver provides the following features:
    from audio tracks.  The program cdda2wav can be used for this.
    Note, however, that only some drives actually support this.
 
- - There is now support for CDROM changers which comply with the 
+ - There is now support for CDROM changers which comply with the
    ATAPI 2.6 draft standard (such as the NEC CDR-251).  This additional
    functionality includes a function call to query which slot is the
    currently selected slot, a function call to query which slots contain
@@ -49,11 +51,11 @@ This driver provides the following features:
    driver.
 
 1. Make sure that the ide and ide-cd drivers are compiled into the
-   kernel you're using.  When configuring the kernel, in the section 
-   entitled "Floppy, IDE, and other block devices", say either `Y' 
-   (which will compile the support directly into the kernel) or `M'
+   kernel you're using.  When configuring the kernel, in the section
+   entitled "Floppy, IDE, and other block devices", say either `Y`
+   (which will compile the support directly into the kernel) or `M`
    (to compile support as a module which can be loaded and unloaded)
-   to the options: 
+   to the options::
 
       ATA/ATAPI/MFM/RLL support
       Include IDE/ATAPI CDROM support
@@ -72,35 +74,35 @@ This driver provides the following features:
    address and an IRQ number, the standard assignments being
    0x1f0 and 14 for the primary interface and 0x170 and 15 for the
    secondary interface.  Each interface can control up to two devices,
-   where each device can be a hard drive, a CDROM drive, a floppy drive, 
-   or a tape drive.  The two devices on an interface are called `master'
-   and `slave'; this is usually selectable via a jumper on the drive.
+   where each device can be a hard drive, a CDROM drive, a floppy drive,
+   or a tape drive.  The two devices on an interface are called `master`
+   and `slave`; this is usually selectable via a jumper on the drive.
 
    Linux names these devices as follows.  The master and slave devices
-   on the primary IDE interface are called `hda' and `hdb',
+   on the primary IDE interface are called `hda` and `hdb`,
    respectively.  The drives on the secondary interface are called
-   `hdc' and `hdd'.  (Interfaces at other locations get other letters
+   `hdc` and `hdd`.  (Interfaces at other locations get other letters
    in the third position; see Documentation/ide/ide.txt.)
 
    If you want your CDROM drive to be found automatically by the
    driver, you should make sure your IDE interface uses either the
    primary or secondary addresses mentioned above.  In addition, if
    the CDROM drive is the only device on the IDE interface, it should
-   be jumpered as `master'.  (If for some reason you cannot configure
+   be jumpered as `master`.  (If for some reason you cannot configure
    your system in this manner, you can probably still use the driver.
    You may have to pass extra configuration information to the kernel
    when you boot, however.  See Documentation/ide/ide.txt for more
    information.)
 
 4. Boot the system.  If the drive is recognized, you should see a
-   message which looks like
+   message which looks like::
 
      hdb: NEC CD-ROM DRIVE:260, ATAPI CDROM drive
 
    If you do not see this, see section 5 below.
 
 5. You may want to create a symbolic link /dev/cdrom pointing to the
-   actual device.  You can do this with the command
+   actual device.  You can do this with the command::
 
      ln -s  /dev/hdX  /dev/cdrom
 
@@ -108,14 +110,14 @@ This driver provides the following features:
    drive is installed.
 
 6. You should be able to see any error messages from the driver with
-   the `dmesg' command.
+   the `dmesg` command.
 
 
 3. Basic usage
 --------------
 
-An ISO 9660 CDROM can be mounted by putting the disc in the drive and 
-typing (as root)
+An ISO 9660 CDROM can be mounted by putting the disc in the drive and
+typing (as root)::
 
   mount -t iso9660 /dev/cdrom /mnt/cdrom
 
@@ -123,7 +125,7 @@ where it is assumed that /dev/cdrom is a link pointing to the actual
 device (as described in step 5 of the last section) and /mnt/cdrom is
 an empty directory.  You should now be able to see the contents of the
 CDROM under the /mnt/cdrom directory.  If you want to eject the CDROM,
-you must first dismount it with a command like
+you must first dismount it with a command like::
 
   umount /mnt/cdrom
 
@@ -148,7 +150,7 @@ such as cdda2wav.  The only types of drive which I've heard support
 this are Sony and Toshiba drives.  You will get errors if you try to
 use this function on a drive which does not support it.
 
-For supported changers, you can use the `cdchange' program (appended to
+For supported changers, you can use the `cdchange` program (appended to
 the end of this file) to switch between changer slots.  Note that the
 drive should be unmounted before attempting this.  The program takes
 two arguments:  the CDROM device, and the slot number to which you wish
@@ -165,7 +167,7 @@ Documentation/ide/ide.txt for current information about the underlying
 IDE support code.  Some of these items apply only to earlier versions
 of the driver, but are mentioned here for completeness.
 
-In most cases, you should probably check with `dmesg' for any errors
+In most cases, you should probably check with `dmesg` for any errors
 from the driver.
 
 a. Drive is not detected during booting.
@@ -184,9 +186,9 @@ a. Drive is not detected during booting.
 
    - If the autoprobing is not finding your drive, you can tell the
      driver to assume that one exists by using a lilo option of the
-     form `hdX=cdrom', where X is the drive letter corresponding to
-     where your drive is installed.  Note that if you do this and you 
-     see a boot message like
+     form `hdX=cdrom`, where X is the drive letter corresponding to
+     where your drive is installed.  Note that if you do this and you
+     see a boot message like::
 
        hdX: ATAPI cdrom (?)
 
@@ -220,7 +222,7 @@ b. Timeout/IRQ errors.
     probably not making it to the host.
 
   - IRQ problems may also be indicated by the message
-    `IRQ probe failed (<n>)' while booting.  If <n> is zero, that
+    `IRQ probe failed (<n>)` while booting.  If <n> is zero, that
     means that the system did not see an interrupt from the drive when
     it was expecting one (on any feasible IRQ).  If <n> is negative,
     that means the system saw interrupts on multiple IRQ lines, when
@@ -240,27 +242,27 @@ b. Timeout/IRQ errors.
     there are hardware problems with the interrupt setup; they
     apparently don't use interrupts.
 
-  - If you own a Pioneer DR-A24X, you _will_ get nasty error messages 
+  - If you own a Pioneer DR-A24X, you _will_ get nasty error messages
     on boot such as "irq timeout: status=0x50 { DriveReady SeekComplete }"
     The Pioneer DR-A24X CDROM drives are fairly popular these days.
     Unfortunately, these drives seem to become very confused when we perform
     the standard Linux ATA disk drive probe. If you own one of these drives,
-    you can bypass the ATA probing which confuses these CDROM drives, by 
-    adding `append="hdX=noprobe hdX=cdrom"' to your lilo.conf file and running 
-    lilo (again where X is the drive letter corresponding to where your drive 
+    you can bypass the ATA probing which confuses these CDROM drives, by
+    adding `append="hdX=noprobe hdX=cdrom"` to your lilo.conf file and running
+    lilo (again where X is the drive letter corresponding to where your drive
     is installed.)
-    
+
 c. System hangups.
 
   - If the system locks up when you try to access the CDROM, the most
     likely cause is that you have a buggy IDE adapter which doesn't
     properly handle simultaneous transactions on multiple interfaces.
     The most notorious of these is the CMD640B chip.  This problem can
-    be worked around by specifying the `serialize' option when
+    be worked around by specifying the `serialize` option when
     booting.  Recent kernels should be able to detect the need for
     this automatically in most cases, but the detection is not
     foolproof.  See Documentation/ide/ide.txt for more information
-    about the `serialize' option and the CMD640B.
+    about the `serialize` option and the CMD640B.
 
   - Note that many MS-DOS CDROM drivers will work with such buggy
     hardware, apparently because they never attempt to overlap CDROM
@@ -269,14 +271,14 @@ c. System hangups.
 
 d. Can't mount a CDROM.
 
-  - If you get errors from mount, it may help to check `dmesg' to see
+  - If you get errors from mount, it may help to check `dmesg` to see
     if there are any more specific errors from the driver or from the
     filesystem.
 
   - Make sure there's a CDROM loaded in the drive, and that's it's an
     ISO 9660 disc.  You can't mount an audio CD.
 
-  - With the CDROM in the drive and unmounted, try something like
+  - With the CDROM in the drive and unmounted, try something like::
 
       cat /dev/cdrom | od | more
 
@@ -284,9 +286,9 @@ d. Can't mount a CDROM.
     OK, and the problem is at the filesystem level (i.e., the CDROM is
     not ISO 9660 or has errors in the filesystem structure).
 
-  - If you see `not a block device' errors, check that the definitions
+  - If you see `not a block device` errors, check that the definitions
     of the device special files are correct.  They should be as
-    follows:
+    follows::
 
       brw-rw----   1 root     disk       3,   0 Nov 11 18:48 /dev/hda
       brw-rw----   1 root     disk       3,  64 Nov 11 18:48 /dev/hdb
@@ -301,7 +303,7 @@ d. Can't mount a CDROM.
     If you have a /dev/cdrom symbolic link, check that it is pointing
     to the correct device file.
 
-    If you hear people talking of the devices `hd1a' and `hd1b', these
+    If you hear people talking of the devices `hd1a` and `hd1b`, these
     were old names for what are now called hdc and hdd.  Those names
     should be considered obsolete.
 
@@ -311,8 +313,8 @@ d. Can't mount a CDROM.
     always give meaningful error messages.
 
 
-e. Directory listings are unpredictably truncated, and `dmesg' shows
-   `buffer botch' error messages from the driver.
+e. Directory listings are unpredictably truncated, and `dmesg` shows
+   `buffer botch` error messages from the driver.
 
   - There was a bug in the version of the driver in 1.2.x kernels
     which could cause this.  It was fixed in 1.3.0.  If you can't
@@ -335,34 +337,36 @@ f. Data corruption.
 5. cdchange.c
 -------------
 
-/*
- * cdchange.c  [-v]  <device>  [<slot>]
- *
- * This loads a CDROM from a specified slot in a changer, and displays 
- * information about the changer status.  The drive should be unmounted before 
- * using this program.
- *
- * Changer information is displayed if either the -v flag is specified
- * or no slot was specified.
- *
- * Based on code originally from Gerhard Zuber <[email protected]>.
- * Changer status information, and rewrite for the new Uniform CDROM driver
- * interface by Erik Andersen <[email protected]>.
- */
+::
 
-#include <stdio.h>
-#include <stdlib.h>
-#include <errno.h>
-#include <string.h>
-#include <unistd.h>
-#include <fcntl.h>
-#include <sys/ioctl.h>
-#include <linux/cdrom.h>
+  /*
+   * cdchange.c  [-v]  <device>  [<slot>]
+   *
+   * This loads a CDROM from a specified slot in a changer, and displays
+   * information about the changer status.  The drive should be unmounted before
+   * using this program.
+   *
+   * Changer information is displayed if either the -v flag is specified
+   * or no slot was specified.
+   *
+   * Based on code originally from Gerhard Zuber <[email protected]>.
+   * Changer status information, and rewrite for the new Uniform CDROM driver
+   * interface by Erik Andersen <[email protected]>.
+   */
 
+  #include <stdio.h>
+  #include <stdlib.h>
+  #include <errno.h>
+  #include <string.h>
+  #include <unistd.h>
+  #include <fcntl.h>
+  #include <sys/ioctl.h>
+  #include <linux/cdrom.h>
 
-int
-main (int argc, char **argv)
-{
+
+  int
+  main (int argc, char **argv)
+  {
 	char *program;
 	char *device;
 	int fd;           /* file descriptor for CD-ROM device */
@@ -382,30 +386,30 @@ main (int argc, char **argv)
 		fprintf (stderr, "       Slots are numbered 1 -- n.\n");
 		exit (1);
 	}
- 
+
        if (strcmp (argv[0], "-v") == 0) {
                 verbose = 1;
                 ++argv;
                 --argc;
         }
- 
+
 	device = argv[0];
- 
+
 	if (argc == 2)
 		slot = atoi (argv[1]) - 1;
 
-	/* open device */ 
+	/* open device */
 	fd = open(device, O_RDONLY | O_NONBLOCK);
 	if (fd < 0) {
-		fprintf (stderr, "%s: open failed for `%s': %s\n",
+		fprintf (stderr, "%s: open failed for `%s`: %s\n",
 			 program, device, strerror (errno));
 		exit (1);
 	}
 
-	/* Check CD player status */ 
+	/* Check CD player status */
 	total_slots_available = ioctl (fd, CDROM_CHANGER_NSLOTS);
 	if (total_slots_available <= 1 ) {
-		fprintf (stderr, "%s: Device `%s' is not an ATAPI "
+		fprintf (stderr, "%s: Device `%s` is not an ATAPI "
 			"compliant CD changer.\n", program, device);
 		exit (1);
 	}
@@ -418,7 +422,7 @@ main (int argc, char **argv)
 			exit (1);
 		}
 
-		/* load */ 
+		/* load */
 		slot=ioctl (fd, CDROM_SELECT_DISC, slot);
 		if (slot<0) {
 			fflush(stdout);
@@ -462,14 +466,14 @@ main (int argc, char **argv)
 
 		for (x_slot=0; x_slot<total_slots_available; x_slot++) {
 			printf ("Slot %2d: ", x_slot+1);
-             		status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
-             		if (status<0) {
-             		     perror(" CDROM_DRIVE_STATUS");
-             		} else switch(status) {
+			status = ioctl (fd, CDROM_DRIVE_STATUS, x_slot);
+			if (status<0) {
+			     perror(" CDROM_DRIVE_STATUS");
+			} else switch(status) {
 			case CDS_DISC_OK:
 				printf ("Disc present.");
 				break;
-			case CDS_NO_DISC: 
+			case CDS_NO_DISC:
 				printf ("Empty slot.");
 				break;
 			case CDS_TRAY_OPEN:
@@ -507,11 +511,11 @@ main (int argc, char **argv)
 				break;
 			}
 			}
-                  	status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
-                  	if (status<0) {
+			status = ioctl (fd, CDROM_MEDIA_CHANGED, x_slot);
+			if (status<0) {
 				perror(" CDROM_MEDIA_CHANGED");
-                  	}
-		  	switch (status) {
+			}
+			switch (status) {
 			case 1:
 				printf ("Changed.\n");
 				break;
@@ -525,10 +529,10 @@ main (int argc, char **argv)
 	/* close device */
 	status = close (fd);
 	if (status != 0) {
-		fprintf (stderr, "%s: close failed for `%s': %s\n",
+		fprintf (stderr, "%s: close failed for `%s`: %s\n",
 			 program, device, strerror (errno));
 		exit (1);
 	}
- 
+
 	exit (0);
-}
+  }
Documentation/cdrom/packet-writing.txt +17 -10
index 2834170d821e..c5c957195a5a 100644
@@ -1,3 +1,7 @@
+==============
+Packet writing
+==============
+
 Getting started quick
 ---------------------
 
@@ -10,13 +14,16 @@ Getting started quick
   Download from http://sourceforge.net/projects/linux-udf/
 
 - Grab a new CD-RW disc and format it (assuming CD-RW is hdc, substitute
-  as appropriate):
+  as appropriate)::
+
 	# cdrwtool -d /dev/hdc -q
 
-- Setup your writer
+- Setup your writer::
+
 	# pktsetup dev_name /dev/hdc
 
-- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy!
+- Now you can mount /dev/pktcdvd/dev_name and copy files to it. Enjoy::
+
 	# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
 
 
@@ -25,11 +32,11 @@ Packet writing for DVD-RW media
 
 DVD-RW discs can be written to much like CD-RW discs if they are in
 the so called "restricted overwrite" mode. To put a disc in restricted
-overwrite mode, run:
+overwrite mode, run::
 
 	# dvd+rw-format /dev/hdc
 
-You can then use the disc the same way you would use a CD-RW disc:
+You can then use the disc the same way you would use a CD-RW disc::
 
 	# pktsetup dev_name /dev/hdc
 	# mount /dev/pktcdvd/dev_name /cdrom -t udf -o rw,noatime
@@ -41,7 +48,7 @@ Packet writing for DVD+RW media
 According to the DVD+RW specification, a drive supporting DVD+RW discs
 shall implement "true random writes with 2KB granularity", which means
 that it should be possible to put any filesystem with a block size >=
-2KB on such a disc. For example, it should be possible to do:
+2KB on such a disc. For example, it should be possible to do::
 
 	# dvd+rw-format /dev/hdc   (only needed if the disc has never
 	                            been formatted)
@@ -54,7 +61,7 @@ follow the specification, but suffer bad performance problems if the
 writes are not 32KB aligned.
 
 Both problems can be solved by using the pktcdvd driver, which always
-generates aligned writes.
+generates aligned writes::
 
 	# dvd+rw-format /dev/hdc
 	# pktsetup dev_name /dev/hdc
@@ -83,7 +90,7 @@ Notes
 
 - Since the pktcdvd driver makes the disc appear as a regular block
   device with a 2KB block size, you can put any filesystem you like on
-  the disc. For example, run:
+  the disc. For example, run::
 
 	# /sbin/mke2fs /dev/pktcdvd/dev_name
 
@@ -97,7 +104,7 @@ Since Linux 2.6.20, the pktcdvd module has a sysfs interface
 and can be controlled by it. For example the "pktcdvd" tool uses
 this interface. (see http://tom.ist-im-web.de/download/pktcdvd )
 
-"pktcdvd" works similar to "pktsetup", e.g.:
+"pktcdvd" works similar to "pktsetup", e.g.::
 
 	# pktcdvd -a dev_name /dev/hdc
 	# mkudffs /dev/pktcdvd/dev_name
@@ -115,7 +122,7 @@ For a description of the sysfs interface look into the file:
 Using the pktcdvd debugfs interface
 -----------------------------------
 
-To read pktcdvd device infos in human readable form, do:
+To read pktcdvd device infos in human readable form, do::
 
 	# cat /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/info
 
Signature · 1 line
2.20.1
#12 lore raw

PATCH 7/57 docs: cgroup-v1: convert to ReST file format

In reply to Mauro Carvalho Chehab

Convert the cgroup-v1 files to ReST format, in order to allow a later addition to the admin-guide.

---
 Documentation/cgroup-v1/blkio-controller.txt  |  96 ++--
 Documentation/cgroup-v1/cgroups.txt           | 180 +++----
 Documentation/cgroup-v1/cpuacct.txt           |  15 +-
 Documentation/cgroup-v1/cpusets.txt           | 203 ++++----
 Documentation/cgroup-v1/devices.txt           |  40 +-
 Documentation/cgroup-v1/freezer-subsystem.txt |  14 +-
 Documentation/cgroup-v1/hugetlb.txt           |  31 +-
 Documentation/cgroup-v1/memcg_test.txt        | 259 ++++++----
 Documentation/cgroup-v1/memory.txt            | 449 +++++++++++-------
 Documentation/cgroup-v1/net_cls.txt           |  37 +-
 Documentation/cgroup-v1/net_prio.txt          |  24 +-
 Documentation/cgroup-v1/pids.txt              |  78 +--
 Documentation/cgroup-v1/rdma.txt              |  66 +--
 13 files changed, 890 insertions(+), 602 deletions(-)
Documentation/cgroup-v1/blkio-controller.txt +56 -40
index 673dc34d3f78..2c1b907afc14 100644
@@ -1,5 +1,7 @@
-				Block IO Controller
-				===================
+===================
+Block IO Controller
+===================
+
 Overview
 ========
 cgroup subsys "blkio" implements the block io controller. There seems to be
@@ -22,28 +24,35 @@ Proportional Weight division of bandwidth
 You can do a very simple testing of running two dd threads in two different
 cgroups. Here is what you can do.
 
-- Enable Block IO controller
+- Enable Block IO controller::
+
 	CONFIG_BLK_CGROUP=y
 
-- Enable group scheduling in CFQ
+- Enable group scheduling in CFQ:
+
+
 	CONFIG_CFQ_GROUP_IOSCHED=y
 
 - Compile and boot into kernel and mount IO controller (blkio); see
   cgroups.txt, Why are cgroups needed?.
 
+  ::
+
 	mount -t tmpfs cgroup_root /sys/fs/cgroup
 	mkdir /sys/fs/cgroup/blkio
 	mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
 
-- Create two cgroups
+- Create two cgroups::
+
 	mkdir -p /sys/fs/cgroup/blkio/test1/ /sys/fs/cgroup/blkio/test2
 
-- Set weights of group test1 and test2
+- Set weights of group test1 and test2::
+
 	echo 1000 > /sys/fs/cgroup/blkio/test1/blkio.weight
 	echo 500 > /sys/fs/cgroup/blkio/test2/blkio.weight
 
 - Create two same size files (say 512MB each) on same disk (file1, file2) and
-  launch two dd threads in different cgroup to read those files.
+  launch two dd threads in different cgroup to read those files::
 
 	sync
 	echo 3 > /proc/sys/vm/drop_caches
@@ -65,24 +74,27 @@ cgroups. Here is what you can do.
 
 Throttling/Upper Limit policy
 -----------------------------
-- Enable Block IO controller
+- Enable Block IO controller::
+
 	CONFIG_BLK_CGROUP=y
 
-- Enable throttling in block layer
+- Enable throttling in block layer::
+
 	CONFIG_BLK_DEV_THROTTLING=y
 
-- Mount blkio controller (see cgroups.txt, Why are cgroups needed?)
+- Mount blkio controller (see cgroups.txt, Why are cgroups needed?)::
+
         mount -t cgroup -o blkio none /sys/fs/cgroup/blkio
 
 - Specify a bandwidth rate on particular device for root group. The format
-  for policy is "<major>:<minor>  <bytes_per_second>".
+  for policy is "<major>:<minor>  <bytes_per_second>"::
 
         echo "8:16  1048576" > /sys/fs/cgroup/blkio/blkio.throttle.read_bps_device
 
   Above will put a limit of 1MB/second on reads happening for root group
   on device having major/minor number 8:16.
 
-- Run dd to read a file and see if rate is throttled to 1MB/s or not.
+- Run dd to read a file and see if rate is throttled to 1MB/s or not::
 
         # dd iflag=direct if=/mnt/common/zerofile of=/dev/null bs=4K count=1024
         1024+0 records in
@@ -99,7 +111,7 @@ throttling's hierarchy support is enabled iff "sane_behavior" is
 enabled from cgroup side, which currently is a development option and
 not publicly available.
 
-If somebody created a hierarchy like as follows.
+If somebody created a hierarchy like as follows::
 
 			root
 			/  \
@@ -115,7 +127,7 @@ directly generated by tasks in that cgroup.
 
 Throttling without "sane_behavior" enabled from cgroup side will
 practically treat all groups at same level as if it looks like the
-following.
+following::
 
 				pivot
 			     /  /   \  \
@@ -152,27 +164,31 @@ Proportional weight policy files
 	  These rules override the default value of group weight as specified
 	  by blkio.weight.
 
-	  Following is the format.
+	  Following is the format::
 
-	  # echo dev_maj:dev_minor weight > blkio.weight_device
-	  Configure weight=300 on /dev/sdb (8:16) in this cgroup
-	  # echo 8:16 300 > blkio.weight_device
-	  # cat blkio.weight_device
-	  dev     weight
-	  8:16    300
+	    # echo dev_maj:dev_minor weight > blkio.weight_device
 
-	  Configure weight=500 on /dev/sda (8:0) in this cgroup
-	  # echo 8:0 500 > blkio.weight_device
-	  # cat blkio.weight_device
-	  dev     weight
-	  8:0     500
-	  8:16    300
+	  Configure weight=300 on /dev/sdb (8:16) in this cgroup::
 
-	  Remove specific weight for /dev/sda in this cgroup
-	  # echo 8:0 0 > blkio.weight_device
-	  # cat blkio.weight_device
-	  dev     weight
-	  8:16    300
+	    # echo 8:16 300 > blkio.weight_device
+	    # cat blkio.weight_device
+	    dev     weight
+	    8:16    300
+
+	  Configure weight=500 on /dev/sda (8:0) in this cgroup::
+
+	    # echo 8:0 500 > blkio.weight_device
+	    # cat blkio.weight_device
+	    dev     weight
+	    8:0     500
+	    8:16    300
+
+	  Remove specific weight for /dev/sda in this cgroup::
+
+	    # echo 8:0 0 > blkio.weight_device
+	    # cat blkio.weight_device
+	    dev     weight
+	    8:16    300
 
 - blkio.leaf_weight[_device]
 	- Equivalents of blkio.weight[_device] for the purpose of
@@ -297,30 +313,30 @@ Throttling/Upper limit policy files
 - blkio.throttle.read_bps_device
 	- Specifies upper limit on READ rate from the device. IO rate is
 	  specified in bytes per second. Rules are per device. Following is
-	  the format.
+	  the format::
 
-  echo "<major>:<minor>  <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device
+	    echo "<major>:<minor>  <rate_bytes_per_second>" > /cgrp/blkio.throttle.read_bps_device
 
 - blkio.throttle.write_bps_device
 	- Specifies upper limit on WRITE rate to the device. IO rate is
 	  specified in bytes per second. Rules are per device. Following is
-	  the format.
+	  the format::
 
-  echo "<major>:<minor>  <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device
+	    echo "<major>:<minor>  <rate_bytes_per_second>" > /cgrp/blkio.throttle.write_bps_device
 
 - blkio.throttle.read_iops_device
 	- Specifies upper limit on READ rate from the device. IO rate is
 	  specified in IO per second. Rules are per device. Following is
-	  the format.
+	  the format::
 
-  echo "<major>:<minor>  <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device
+	   echo "<major>:<minor>  <rate_io_per_second>" > /cgrp/blkio.throttle.read_iops_device
 
 - blkio.throttle.write_iops_device
 	- Specifies upper limit on WRITE rate to the device. IO rate is
 	  specified in io per second. Rules are per device. Following is
-	  the format.
+	  the format::
 
-  echo "<major>:<minor>  <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device
+	    echo "<major>:<minor>  <rate_io_per_second>" > /cgrp/blkio.throttle.write_iops_device
 
 Note: If both BW and IOPS rules are specified for a device, then IO is
       subjected to both the constraints.
Documentation/cgroup-v1/cgroups.txt +99 -81

348 lines not on this page · raw message

Documentation/cgroup-v1/cpuacct.txt +8 -7
index 9d73cc0cadb9..d30ed81d2ad7 100644
@@ -1,5 +1,6 @@
+=========================
 CPU Accounting Controller
--------------------------
+=========================
 
 The CPU accounting controller is used to group tasks using cgroups and
 account the CPU usage of these groups of tasks.
@@ -8,9 +9,9 @@ The CPU accounting controller supports multi-hierarchy groups. An accounting
 group accumulates the CPU usage of all of its child groups and the tasks
 directly present in its group.
 
-Accounting groups can be created by first mounting the cgroup filesystem.
+Accounting groups can be created by first mounting the cgroup filesystem::
 
-# mount -t cgroup -ocpuacct none /sys/fs/cgroup
+  # mount -t cgroup -ocpuacct none /sys/fs/cgroup
 
 With the above step, the initial or the parent accounting group becomes
 visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
@@ -19,11 +20,11 @@ the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
 by this group which is essentially the CPU time obtained by all the tasks
 in the system.
 
-New accounting groups can be created under the parent group /sys/fs/cgroup.
+New accounting groups can be created under the parent group /sys/fs/cgroup::
 
-# cd /sys/fs/cgroup
-# mkdir g1
-# echo $$ > g1/tasks
+  # cd /sys/fs/cgroup
+  # mkdir g1
+  # echo $$ > g1/tasks
 
 The above steps create a new group g1 and move the current shell
 process (bash) into it. CPU time consumed by this bash and its children
Documentation/cgroup-v1/cpusets.txt +115 -88

336 lines not on this page · raw message

Documentation/cgroup-v1/devices.txt +28 -12
index 3c1095ca02ea..73033448a3e1 100644
@@ -1,6 +1,9 @@
+===========================
 Device Whitelist Controller
+===========================
 
-1. Description:
+1. Description
+==============
 
 Implement a cgroup to track and enforce open and mknod restrictions
 on device files.  A device cgroup associates a device access
@@ -16,24 +19,26 @@ devices from the whitelist or add new entries.  A child cgroup can
 never receive a device access which is denied by its parent.
 
 2. User Interface
+=================
 
 An entry is added using devices.allow, and removed using
-devices.deny.  For instance
+devices.deny.  For instance::
 
 	echo 'c 1:3 mr' > /sys/fs/cgroup/1/devices.allow
 
 allows cgroup 1 to read and mknod the device usually known as
-/dev/null.  Doing
+/dev/null.  Doing::
 
 	echo a > /sys/fs/cgroup/1/devices.deny
 
-will remove the default 'a *:* rwm' entry. Doing
+will remove the default 'a *:* rwm' entry. Doing::
 
 	echo a > /sys/fs/cgroup/1/devices.allow
 
 will add the 'a *:* rwm' entry to the whitelist.
 
 3. Security
+===========
 
 Any task can move itself between cgroups.  This clearly won't
 suffice, but we can decide the best way to adequately restrict
@@ -50,6 +55,7 @@ A cgroup may not be granted more permissions than the cgroup's
 parent has.
 
 4. Hierarchy
+============
 
 device cgroups maintain hierarchy by making sure a cgroup never has more
 access permissions than its parent.  Every time an entry is written to
@@ -58,7 +64,8 @@ from their whitelist and all the locally set whitelist entries will be
 re-evaluated.  In case one of the locally set whitelist entries would provide
 more access than the cgroup's parent, it'll be removed from the whitelist.
 
-Example:
+Example::
+
       A
      / \
         B
@@ -67,10 +74,12 @@ Example:
     A            allow		"b 8:* rwm", "c 116:1 rw"
     B            deny		"c 1:3 rwm", "c 116:2 rwm", "b 3:* rwm"
 
-If a device is denied in group A:
+If a device is denied in group A::
+
 	# echo "c 116:* r" > A/devices.deny
+
 it'll propagate down and after revalidating B's entries, the whitelist entry
-"c 116:2 rwm" will be removed:
+"c 116:2 rwm" will be removed::
 
     group        whitelist entries                        denied devices
     A            all                                      "b 8:* rwm", "c 116:* rw"
@@ -79,7 +88,8 @@ it'll propagate down and after revalidating B's entries, the whitelist entry
 In case parent's exceptions change and local exceptions are not allowed
 anymore, they'll be deleted.
 
-Notice that new whitelist entries will not be propagated:
+Notice that new whitelist entries will not be propagated::
+
       A
      / \
         B
@@ -88,24 +98,30 @@ Notice that new whitelist entries will not be propagated:
     A            "c 1:3 rwm", "c 1:5 r"                   all the rest
     B            "c 1:3 rwm", "c 1:5 r"                   all the rest
 
-when adding "c *:3 rwm":
+when adding `c *:3 rwm`::
+
 	# echo "c *:3 rwm" >A/devices.allow
 
-the result:
+the result::
+
     group        whitelist entries                        denied devices
     A            "c *:3 rwm", "c 1:5 r"                   all the rest
     B            "c 1:3 rwm", "c 1:5 r"                   all the rest
 
-but now it'll be possible to add new entries to B:
+but now it'll be possible to add new entries to B::
+
 	# echo "c 2:3 rwm" >B/devices.allow
 	# echo "c 50:3 r" >B/devices.allow
-or even
+
+or even::
+
 	# echo "c *:3 rwm" >B/devices.allow
 
 Allowing or denying all by writing 'a' to devices.allow or devices.deny will
 not be possible once the device cgroups has children.
 
 4.1 Hierarchy (internal implementation)
+---------------------------------------
 
 device cgroups is implemented internally using a behavior (ALLOW, DENY) and a
 list of exceptions.  The internal state is controlled using the same user
Documentation/cgroup-v1/freezer-subsystem.txt +9 -5
index e831cb2b8394..582d3427de3f 100644
@@ -1,3 +1,7 @@
+==============
+Cgroup Freezer
+==============
+
 The cgroup freezer is useful to batch job management system which start
 and stop sets of tasks in order to schedule the resources of a machine
 according to the desires of a system administrator. This sort of program
@@ -23,7 +27,7 @@ blocked, or ignored it can be seen by waiting or ptracing parent tasks.
 SIGCONT is especially unsuitable since it can be caught by the task. Any
 programs designed to watch for SIGSTOP and SIGCONT could be broken by
 attempting to use SIGSTOP and SIGCONT to stop and resume tasks. We can
-demonstrate this problem using nested bash shells:
+demonstrate this problem using nested bash shells::
 
 	$ echo $$
 	16644
@@ -93,19 +97,19 @@ The following cgroupfs files are created by cgroup freezer.
 The root cgroup is non-freezable and the above interface files don't
 exist.
 
-* Examples of usage :
+* Examples of usage::
 
    # mkdir /sys/fs/cgroup/freezer
    # mount -t cgroup -ofreezer freezer /sys/fs/cgroup/freezer
    # mkdir /sys/fs/cgroup/freezer/0
    # echo $some_pid > /sys/fs/cgroup/freezer/0/tasks
 
-to get status of the freezer subsystem :
+to get status of the freezer subsystem::
 
    # cat /sys/fs/cgroup/freezer/0/freezer.state
    THAWED
 
-to freeze all tasks in the container :
+to freeze all tasks in the container::
 
    # echo FROZEN > /sys/fs/cgroup/freezer/0/freezer.state
    # cat /sys/fs/cgroup/freezer/0/freezer.state
@@ -113,7 +117,7 @@ to freeze all tasks in the container :
    # cat /sys/fs/cgroup/freezer/0/freezer.state
    FROZEN
 
-to unfreeze all tasks in the container :
+to unfreeze all tasks in the container::
 
    # echo THAWED > /sys/fs/cgroup/freezer/0/freezer.state
    # cat /sys/fs/cgroup/freezer/0/freezer.state
Documentation/cgroup-v1/hugetlb.txt +16 -15
index 106245c3aecc..7056a185914b 100644
@@ -1,5 +1,6 @@
+==================
 HugeTLB Controller
--------------------
+==================
 
 The HugeTLB controller allows to limit the HugeTLB usage per control group and
 enforces the controller limit during page fault. Since HugeTLB doesn't
@@ -16,16 +17,16 @@ With the above step, the initial or the parent HugeTLB group becomes
 visible at /sys/fs/cgroup. At bootup, this group includes all the tasks in
 the system. /sys/fs/cgroup/tasks lists the tasks in this cgroup.
 
-New groups can be created under the parent group /sys/fs/cgroup.
+New groups can be created under the parent group /sys/fs/cgroup::
 
-# cd /sys/fs/cgroup
-# mkdir g1
-# echo $$ > g1/tasks
+  # cd /sys/fs/cgroup
+  # mkdir g1
+  # echo $$ > g1/tasks
 
 The above steps create a new group g1 and move the current shell
 process (bash) into it.
 
-Brief summary of control files
+Brief summary of control files::
 
  hugetlb.<hugepagesize>.limit_in_bytes     # set/show limit of "hugepagesize" hugetlb usage
  hugetlb.<hugepagesize>.max_usage_in_bytes # show max "hugepagesize" hugetlb  usage recorded
@@ -33,13 +34,13 @@ Brief summary of control files
  hugetlb.<hugepagesize>.failcnt		   # show the number of allocation failure due to HugeTLB limit
 
 For a system supporting two hugepage size (16M and 16G) the control
-files include:
+files include::
 
-hugetlb.16GB.limit_in_bytes
-hugetlb.16GB.max_usage_in_bytes
-hugetlb.16GB.usage_in_bytes
-hugetlb.16GB.failcnt
-hugetlb.16MB.limit_in_bytes
-hugetlb.16MB.max_usage_in_bytes
-hugetlb.16MB.usage_in_bytes
-hugetlb.16MB.failcnt
+  hugetlb.16GB.limit_in_bytes
+  hugetlb.16GB.max_usage_in_bytes
+  hugetlb.16GB.usage_in_bytes
+  hugetlb.16GB.failcnt
+  hugetlb.16MB.limit_in_bytes
+  hugetlb.16MB.max_usage_in_bytes
+  hugetlb.16MB.usage_in_bytes
+  hugetlb.16MB.failcnt
Documentation/cgroup-v1/memcg_test.txt +167 -92

408 lines not on this page · raw message

Documentation/cgroup-v1/memory.txt +280 -169

851 lines not on this page · raw message

Documentation/cgroup-v1/net_cls.txt +21 -16
index ec182346dea2..a2cf272af7a0 100644
@@ -1,5 +1,6 @@
+=========================
 Network classifier cgroup
--------------------------
+=========================
 
 The Network classifier cgroup provides an interface to
 tag network packets with a class identifier (classid).
@@ -17,23 +18,27 @@ values is 0xAAAABBBB; AAAA is the major handle number and BBBB
 is the minor handle number.
 Reading net_cls.classid yields a decimal result.
 
-Example:
-mkdir /sys/fs/cgroup/net_cls
-mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls
-mkdir /sys/fs/cgroup/net_cls/0
-echo 0x100001 >  /sys/fs/cgroup/net_cls/0/net_cls.classid
-	- setting a 10:1 handle.
+Example::
 
-cat /sys/fs/cgroup/net_cls/0/net_cls.classid
-1048577
+	mkdir /sys/fs/cgroup/net_cls
+	mount -t cgroup -onet_cls net_cls /sys/fs/cgroup/net_cls
+	mkdir /sys/fs/cgroup/net_cls/0
+	echo 0x100001 >  /sys/fs/cgroup/net_cls/0/net_cls.classid
 
-configuring tc:
-tc qdisc add dev eth0 root handle 10: htb
+- setting a 10:1 handle::
 
-tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit
- - creating traffic class 10:1
+	cat /sys/fs/cgroup/net_cls/0/net_cls.classid
+	1048577
 
-tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup
+- configuring tc::
 
-configuring iptables, basic example:
-iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP
+	tc qdisc add dev eth0 root handle 10: htb
+	tc class add dev eth0 parent 10: classid 10:1 htb rate 40mbit
+
+- creating traffic class 10:1::
+
+	tc filter add dev eth0 parent 10: protocol ip prio 10 handle 1: cgroup
+
+configuring iptables, basic example::
+
+	iptables -A OUTPUT -m cgroup ! --cgroup 0x100001 -j DROP
Documentation/cgroup-v1/net_prio.txt +13 -11
index a82cbd28ea8a..b40905871c64 100644
@@ -1,5 +1,6 @@
+=======================
 Network priority cgroup
--------------------------
+=======================
 
 The Network priority cgroup provides an interface to allow an administrator to
 dynamically set the priority of network traffic generated by various
@@ -14,9 +15,9 @@ SO_PRIORITY socket option.  This however, is not always possible because:
 
 This cgroup allows an administrator to assign a process to a group which defines
 the priority of egress traffic on a given interface. Network priority groups can
-be created by first mounting the cgroup filesystem.
+be created by first mounting the cgroup filesystem::
 
-# mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio
+	# mount -t cgroup -onet_prio none /sys/fs/cgroup/net_prio
 
 With the above step, the initial group acting as the parent accounting group
 becomes visible at '/sys/fs/cgroup/net_prio'.  This group includes all tasks in
@@ -25,17 +26,18 @@ the system. '/sys/fs/cgroup/net_prio/tasks' lists the tasks in this cgroup.
 Each net_prio cgroup contains two files that are subsystem specific
 
 net_prio.prioidx
-This file is read-only, and is simply informative.  It contains a unique integer
-value that the kernel uses as an internal representation of this cgroup.
+  This file is read-only, and is simply informative.  It contains a unique
+  integer value that the kernel uses as an internal representation of this
+  cgroup.
 
 net_prio.ifpriomap
-This file contains a map of the priorities assigned to traffic originating from
-processes in this group and egressing the system on various interfaces. It
-contains a list of tuples in the form <ifname priority>.  Contents of this file
-can be modified by echoing a string into the file using the same tuple format.
-for example:
+  This file contains a map of the priorities assigned to traffic originating
+  from processes in this group and egressing the system on various interfaces.
+  It contains a list of tuples in the form <ifname priority>.  Contents of this
+  file can be modified by echoing a string into the file using the same tuple
+  format. For example::
 
-echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap
+	echo "eth0 5" > /sys/fs/cgroups/net_prio/iscsi/net_prio.ifpriomap
 
 This command would force any traffic originating from processes belonging to the
 iscsi net_prio cgroup and egressing on interface eth0 to have the priority of
Documentation/cgroup-v1/pids.txt +41 -37

101 lines not on this page · raw message

Documentation/cgroup-v1/rdma.txt +37 -29

80 lines not on this page · raw message

Signature · 1 line
2.20.1
#13 lore raw

PATCH 8/57 docs: cgroup-v1/blkio-controller.rst: add a note about CFQ scheduler

In reply to Mauro Carvalho Chehab

The CFQ scheduler was removed on this changeset:

commit f382fb0bcef4c37dc049e9f6963e3baf204d815c
Author: Jens Axboe <[email protected]>
Date: Fri Oct 12 10:14:46 2018 -0600

block: remove legacy IO schedulers

Retain the deadline documentation, as that carries over to mq-deadline as well.

However, the cgroups-v1 documentation still mentions it and points to a removed file that used to belong to such scheduler.

Add a note about that, as someone needs to fix the document pointing to another scheduler, if cgroups-v1 blockio is not dependent of CFQ scheduler.

---
 Documentation/cgroup-v1/blkio-controller.txt | 7 +++++++
 1 file changed, 7 insertions(+)
Documentation/cgroup-v1/blkio-controller.txt +7 -0
index 2c1b907afc14..2836c2c31e63 100644
@@ -17,6 +17,13 @@ one is throttling policy which can be used to specify upper IO rate limits
 on devices. This policy is implemented in generic block layer and can be
 used on leaf nodes as well as higher level logical devices like device mapper.
 
+.. note::
+
+   While this document mentions the CFQ scheduler, it got removed at
+   Kernel 4.20, as there are other schedulers that are more efficient.
+
+   Someone needs to update this file in order to reflect such change.
+
 HOWTO
 =====
 Proportional Weight division of bandwidth
Signature · 1 line
2.20.1
#14 lore raw

PATCH 9/57 docs: cpu-freq: convert files to ReST

In reply to Mauro Carvalho Chehab

In order to be able to build html and pdf files, convert the documentation to ReST format.

---
 Documentation/cpu-freq/amd-powernow.txt    |  11 +-
 Documentation/cpu-freq/core.txt            |  66 +++----
 Documentation/cpu-freq/cpu-drivers.txt     | 217 +++++++++++----------
 Documentation/cpu-freq/cpufreq-nforce2.txt |  12 +-
 Documentation/cpu-freq/cpufreq-stats.txt   | 141 ++++++-------
 Documentation/cpu-freq/pcc-cpufreq.txt     | 102 +++++-----
 6 files changed, 281 insertions(+), 268 deletions(-)
Documentation/cpu-freq/amd-powernow.txt +9 -2
index 254da155fa47..50b2c45c3a2c 100644
@@ -1,3 +1,7 @@
+=============================
+AMD powernow driver specifics
+=============================
+
 
 PowerNow! and Cool'n'Quiet are AMD names for frequency
 management capabilities in AMD processors. As the hardware
@@ -23,16 +27,19 @@ not supply these tables.
 7th Generation: powernow-k7: Athlon, Duron, Geode.
 
 8th Generation: powernow-k8: Athlon, Athlon 64, Opteron, Sempron.
+
 Documentation on this functionality in 8th generation processors
 is available in the "BIOS and Kernel Developer's Guide", publication
-26094, in chapter 9, available for download from www.amd.com. 
+26094, in chapter 9, available for download from www.amd.com.
 
 BIOS supplied data, for powernow-k7 and for powernow-k8, may be
 from either the PSB table or from ACPI objects. The ACPI support
 is only available if the kernel config sets CONFIG_ACPI_PROCESSOR.
+
 The powernow-k8 driver will attempt to use ACPI if so configured,
 and fall back to PST if that fails.
+
 The powernow-k7 driver will try to use the PSB support first, and
 fall back to ACPI if the PSB support fails. A module parameter,
-acpi_force, is provided to force ACPI support to be used instead 
+acpi_force, is provided to force ACPI support to be used instead
 of PSB support.
Documentation/cpu-freq/core.txt +31 -35

107 lines not on this page · raw message

Documentation/cpu-freq/cpu-drivers.txt +113 -104

301 lines not on this page · raw message

Documentation/cpu-freq/cpufreq-nforce2.txt +8 -4
index babce1315026..d40700bd5083 100644
@@ -1,3 +1,6 @@
+=================================
+nVidia nForce2 platform specifics
+=================================
 
 The cpufreq-nforce2 driver changes the FSB on nVidia nForce2 platforms.
 
@@ -6,14 +9,15 @@ can be controlled independently from the PCI/AGP clock.
 
 The module has two options:
 
+        ======== ======================================
 	fid: 	 multiplier * 10 (for example 8.5 = 85)
 	min_fsb: minimum FSB
+        ======== ======================================
 
 If not set, fid is calculated from the current CPU speed and the FSB.
 min_fsb defaults to FSB at boot time - 50 MHz.
 
-IMPORTANT: The available range is limited downwards!
-           Also the minimum available FSB can differ, for systems 
+IMPORTANT:
+           The available range is limited downwards!
+           Also the minimum available FSB can differ, for systems
            booting with 200 MHz, 150 should always work.
-
-
Documentation/cpu-freq/cpufreq-stats.txt +71 -70

176 lines not on this page · raw message

Documentation/cpu-freq/pcc-cpufreq.txt +49 -53

138 lines not on this page · raw message

Signature · 1 line
2.20.1
#15 lore raw

Re: [PATCH 09/57] docs: cpu-freq: convert files to ReST

Quoted 5 lines · Mauro Carvalho Chehab

In order to be able to build html and pdf files, convert the documentation to ReST format.

Please don't convert these files.

They need more work than just semi-automatic conversion and the material in them needs to go under driver-api.

This is quite hight in my TODO list.

Thanks,
Rafael

#16 lore raw

Re: [PATCH 09/57] docs: cpu-freq: convert files to ReST

Em Tue, 16 Apr 2019 10:21:31 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:

Quoted 11 lines
Quoted 5 lines · Mauro Carvalho Chehab

In order to be able to build html and pdf files, convert the documentation to ReST format.

Please don't convert these files.

They need more work than just semi-automatic conversion

Except for one exception (at patch 32/57), the ReST conversion on this patch set was manually made. I basically renamed the files to .rst, checked the errors and fixed, trying to preserve the original document style as much as possible, while providing a good visual for the html output.

I suspect that trying to write a script for such kind of conversion is not an easy task, as some documents within the Kernel tree have their own personal style, (there was even one written in LaTeX at the CDROM docs), and I suspect that a script would end by adding extra unwanted markups.

Quoted 1 line

and the material in them needs to go under driver-api.

Yeah, those documents make sense to be at the driver-api set.

The rationale why I placed the patch with actually renames on a separate patchset (already on my devel tree, but yet to be submitted) is that, this way, it should be easy for maintainers to pick the conversion patch, apply on their trees, and, if they're not ready yet, postpone the actual rename/move thing.

Quoted 1 line

This is quite hight in my TODO list.

OK. Feel free to use this patch as a starting point if you want.

Regards,
Mauro

#17 lore raw

PATCH 10/57 docs: device-mapper: convert it to ReST format

In reply to Mauro Carvalho Chehab

Convert the Device Mapper documentation to ReST.

---
 .../device-mapper/cache-policies.txt          |  24 +-
 Documentation/device-mapper/cache.txt         | 206 +++++++++-------
 Documentation/device-mapper/delay.txt         |  29 ++-
 Documentation/device-mapper/dm-crypt.txt      |  57 +++--
 Documentation/device-mapper/dm-flakey.txt     |  45 ++--
 Documentation/device-mapper/dm-init.txt       |  75 +++---
 Documentation/device-mapper/dm-integrity.txt  |  55 +++--
 Documentation/device-mapper/dm-io.txt         |  14 +-
 Documentation/device-mapper/dm-log.txt        |   5 +-
 .../device-mapper/dm-queue-length.txt         |  25 +-
 Documentation/device-mapper/dm-raid.txt       | 225 +++++++++++-------
 .../device-mapper/dm-service-time.txt         |  68 +++---
 Documentation/device-mapper/dm-uevent.txt     | 143 ++++++-----
 Documentation/device-mapper/dm-zoned.txt      |  10 +-
 Documentation/device-mapper/era.txt           |  36 +--
 Documentation/device-mapper/kcopyd.txt        |  10 +-
 Documentation/device-mapper/linear.txt        | 100 ++++----
 Documentation/device-mapper/log-writes.txt    |  91 +++----
 .../device-mapper/persistent-data.txt         |   4 +
 Documentation/device-mapper/snapshot.txt      | 116 ++++-----
 Documentation/device-mapper/statistics.txt    |  62 ++---
 Documentation/device-mapper/striped.txt       |  68 +++---
 Documentation/device-mapper/switch.txt        |  47 ++--
 .../device-mapper/thin-provisioning.txt       |  68 ++++--
 Documentation/device-mapper/unstriped.txt     | 111 +++++----
 Documentation/device-mapper/verity.txt        |  20 +-
 Documentation/device-mapper/writecache.txt    |  13 +-
 Documentation/device-mapper/zero.txt          |  14 +-
 28 files changed, 1012 insertions(+), 729 deletions(-)
Documentation/device-mapper/cache-policies.txt +17 -7
index 86786d87d9a8..b17fe352fc41 100644
@@ -1,3 +1,4 @@
+=============================
 Guidance for writing policies
 =============================
 
@@ -30,7 +31,7 @@ multiqueue (mq)
 
 This policy is now an alias for smq (see below).
 
-The following tunables are accepted, but have no effect:
+The following tunables are accepted, but have no effect::
 
 	'sequential_threshold <#nr_sequential_ios>'
 	'random_threshold <#nr_random_ios>'
@@ -56,7 +57,9 @@ mq policy's hints to be dropped.  Also, performance of the cache may
 degrade slightly until smq recalculates the origin device's hotspots
 that should be cached.
 
-Memory usage:
+Memory usage
+^^^^^^^^^^^^
+
 The mq policy used a lot of memory; 88 bytes per cache block on a 64
 bit machine.
 
@@ -69,7 +72,9 @@ cache block).
 All this means smq uses ~25bytes per cache block.  Still a lot of
 memory, but a substantial improvement nontheless.
 
-Level balancing:
+Level balancing
+^^^^^^^^^^^^^^^
+
 mq placed entries in different levels of the multiqueue structures
 based on their hit count (~ln(hit count)).  This meant the bottom
 levels generally had the most entries, and the top ones had very
@@ -94,7 +99,9 @@ is used to decide which blocks to promote.  If the hotspot queue is
 performing badly then it starts moving entries more quickly between
 levels.  This lets it adapt to new IO patterns very quickly.
 
-Performance:
+Performance
+^^^^^^^^^^^
+
 Testing smq shows substantially better performance than mq.
 
 cleaner
@@ -105,16 +112,19 @@ The cleaner writes back all dirty blocks in a cache to decommission it.
 Examples
 ========
 
-The syntax for a table is:
+The syntax for a table is::
+
 	cache <metadata dev> <cache dev> <origin dev> <block size>
 	<#feature_args> [<feature arg>]*
 	<policy> <#policy_args> [<policy arg>]*
 
-The syntax to send a message using the dmsetup command is:
+The syntax to send a message using the dmsetup command is::
+
 	dmsetup message <mapped device> 0 sequential_threshold 1024
 	dmsetup message <mapped device> 0 random_threshold 8
 
-Using dmsetup:
+Using dmsetup::
+
 	dmsetup create blah --table "0 268435456 cache /dev/sdb /dev/sdc \
 	    /dev/sdd 512 0 mq 4 sequential_threshold 1024 random_threshold 8"
 	creates a 128GB large mapped device named 'blah' with the
Documentation/device-mapper/cache.txt +116 -90

258 lines not on this page · raw message

Documentation/device-mapper/delay.txt +16 -13
index 6426c45273cb..917ba8c33359 100644
@@ -1,10 +1,12 @@
+========
 dm-delay
 ========
 
 Device-Mapper's "delay" target delays reads and/or writes
 and maps them to different devices.
 
-Parameters:
+Parameters::
+
     <device> <offset> <delay> [<write_device> <write_offset> <write_delay>
 			       [<flush_device> <flush_offset> <flush_delay>]]
 
@@ -14,15 +16,16 @@ Delays are specified in milliseconds.
 
 Example scripts
 ===============
-[[
-#!/bin/sh
-# Create device delaying rw operation for 500ms
-echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed
-]]
-
-[[
-#!/bin/sh
-# Create device delaying only write operation for 500ms and
-# splitting reads and writes to different devices $1 $2
-echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed
-]]
+
+::
+
+	#!/bin/sh
+	# Create device delaying rw operation for 500ms
+	echo "0 `blockdev --getsz $1` delay $1 0 500" | dmsetup create delayed
+
+::
+
+	#!/bin/sh
+	# Create device delaying only write operation for 500ms and
+	# splitting reads and writes to different devices $1 $2
+	echo "0 `blockdev --getsz $1` delay $1 0 0 $2 0 500" | dmsetup create delayed
Documentation/device-mapper/dm-crypt.txt +34 -23

87 lines not on this page · raw message

Documentation/device-mapper/dm-flakey.txt +31 -14

68 lines not on this page · raw message

Documentation/device-mapper/dm-init.txt +43 -32

140 lines not on this page · raw message

Documentation/device-mapper/dm-integrity.txt +40 -15

123 lines not on this page · raw message

Documentation/device-mapper/dm-io.txt +7 -7
index 3b5d9a52cdcf..d2492917a1f5 100644
@@ -1,3 +1,4 @@
+=====
 dm-io
 =====
 
@@ -7,7 +8,7 @@ version.
 
 The user must set up an io_region structure to describe the desired location
 of the I/O. Each io_region indicates a block-device along with the starting
-sector and size of the region.
+sector and size of the region::
 
    struct io_region {
       struct block_device *bdev;
@@ -19,7 +20,7 @@ Dm-io can read from one io_region or write to one or more io_regions. Writes
 to multiple regions are specified by an array of io_region structures.
 
 The first I/O service type takes a list of memory pages as the data buffer for
-the I/O, along with an offset into the first page.
+the I/O, along with an offset into the first page::
 
    struct page_list {
       struct page_list *next;
@@ -35,7 +36,7 @@ the I/O, along with an offset into the first page.
 
 The second I/O service type takes an array of bio vectors as the data buffer
 for the I/O. This service can be handy if the caller has a pre-assembled bio,
-but wants to direct different portions of the bio to different devices.
+but wants to direct different portions of the bio to different devices::
 
    int dm_io_sync_bvec(unsigned int num_regions, struct io_region *where,
                        int rw, struct bio_vec *bvec,
@@ -47,7 +48,7 @@ but wants to direct different portions of the bio to different devices.
 The third I/O service type takes a pointer to a vmalloc'd memory buffer as the
 data buffer for the I/O. This service can be handy if the caller needs to do
 I/O to a large region but doesn't want to allocate a large number of individual
-memory pages.
+memory pages::
 
    int dm_io_sync_vm(unsigned int num_regions, struct io_region *where, int rw,
                      void *data, unsigned long *error_bits);
@@ -55,11 +56,11 @@ memory pages.
                       void *data, io_notify_fn fn, void *context);
 
 Callers of the asynchronous I/O services must include the name of a completion
-callback routine and a pointer to some context data for the I/O.
+callback routine and a pointer to some context data for the I/O::
 
    typedef void (*io_notify_fn)(unsigned long error, void *context);
 
-The "error" parameter in this callback, as well as the "*error" parameter in
+The "error" parameter in this callback, as well as the `*error` parameter in
 all of the synchronous versions, is a bitset (instead of a simple error value).
 In the case of an write-I/O to multiple regions, this bitset allows dm-io to
 indicate success or failure on each individual region.
@@ -72,4 +73,3 @@ always available in order to avoid unnecessary waiting while performing I/O.
 When the user is finished using the dm-io services, they should call
 dm_io_put() and specify the same number of pages that were given on the
 dm_io_get() call.
-
Documentation/device-mapper/dm-log.txt +4 -1
index c155ac569c44..ba4fce39bc27 100644
@@ -1,3 +1,4 @@
+=====================
 Device-Mapper Logging
 =====================
 The device-mapper logging code is used by some of the device-mapper
@@ -16,11 +17,13 @@ dm_dirty_log_type in include/linux/dm-dirty-log.h).  Various different
 logging implementations are available and provide different
 capabilities.  The list includes:
 
+==============	==============================================================
 Type		Files
-====		=====
+==============	==============================================================
 disk		drivers/md/dm-log.c
 core		drivers/md/dm-log.c
 userspace	drivers/md/dm-log-userspace* include/linux/dm-log-userspace.h
+==============	==============================================================
 
 The "disk" log type
 -------------------
Documentation/device-mapper/dm-queue-length.txt +17 -8
index f4db2562175c..d8e381c1cb02 100644
@@ -1,3 +1,4 @@
+===============
 dm-queue-length
 ===============
 
@@ -6,12 +7,18 @@ which selects a path with the least number of in-flight I/Os.
 The path selector name is 'queue-length'.
 
 Table parameters for each path: [<repeat_count>]
+
+::
+
 	<repeat_count>: The number of I/Os to dispatch using the selected
 			path before switching to the next path.
 			If not given, internal default is used. To check
 			the default value, see the activated table.
 
 Status for each path: <status> <fail-count> <in-flight>
+
+::
+
 	<status>: 'A' if the path is active, 'F' if the path is failed.
 	<fail-count>: The number of path failures.
 	<in-flight>: The number of in-flight I/Os on the path.
@@ -29,11 +36,13 @@ Examples
 ========
 In case that 2 paths (sda and sdb) are used with repeat_count == 128.
 
-# echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \
-  dmsetup create test
-#
-# dmsetup table
-test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128
-#
-# dmsetup status
-test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0
+::
+
+  # echo "0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128" \
+    dmsetup create test
+  #
+  # dmsetup table
+  test: 0 10 multipath 0 0 1 1 queue-length 0 2 1 8:0 128 8:16 128
+  #
+  # dmsetup status
+  test: 0 10 multipath 2 0 0 0 1 1 E 0 2 1 8:0 A 0 0 8:16 A 0 0
Documentation/device-mapper/dm-raid.txt +145 -80

401 lines not on this page · raw message

Documentation/device-mapper/dm-service-time.txt +39 -29

99 lines not on this page · raw message

Documentation/device-mapper/dm-uevent.txt +78 -65

173 lines not on this page · raw message

Documentation/device-mapper/dm-zoned.txt +6 -4
index 736fcc78d193..07f56ebc1730 100644
@@ -1,3 +1,4 @@
+========
 dm-zoned
 ========
 
@@ -133,12 +134,13 @@ A zoned block device must first be formatted using the dmzadm tool. This
 will analyze the device zone configuration, determine where to place the
 metadata sets on the device and initialize the metadata sets.
 
-Ex:
+Ex::
 
-dmzadm --format /dev/sdxx
+	dmzadm --format /dev/sdxx
 
 For a formatted device, the target can be created normally with the
 dmsetup utility. The only parameter that dm-zoned requires is the
-underlying zoned block device name. Ex:
+underlying zoned block device name. Ex::
 
-echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | dmsetup create dmz-`basename ${dev}`
+	echo "0 `blockdev --getsize ${dev}` zoned ${dev}" | \
+	dmsetup create dmz-`basename ${dev}`
Documentation/device-mapper/era.txt +22 -14
index 3c6d01be3560..90dd5c670b9f 100644
@@ -1,3 +1,7 @@
+======
+dm-era
+======
+
 Introduction
 ============
 
@@ -14,12 +18,14 @@ coherency after rolling back a vendor snapshot.
 Constructor
 ===========
 
- era <metadata dev> <origin dev> <block size>
+era <metadata dev> <origin dev> <block size>
 
- metadata dev    : fast device holding the persistent metadata
- origin dev	 : device holding data blocks that may change
- block size      : block size of origin data device, granularity that is
-		     tracked by the target
+ ================ ======================================================
+ metadata dev     fast device holding the persistent metadata
+ origin dev	  device holding data blocks that may change
+ block size       block size of origin data device, granularity that is
+		  tracked by the target
+ ================ ======================================================
 
 Messages
 ========
@@ -49,14 +55,16 @@ Status
 <metadata block size> <#used metadata blocks>/<#total metadata blocks>
 <current era> <held metadata root | '-'>
 
-metadata block size	 : Fixed block size for each metadata block in
-			     sectors
-#used metadata blocks	 : Number of metadata blocks used
-#total metadata blocks	 : Total number of metadata blocks
-current era		 : The current era
-held metadata root	 : The location, in blocks, of the metadata root
-			     that has been 'held' for userspace read
-			     access. '-' indicates there is no held root
+========================= ==============================================
+metadata block size	  Fixed block size for each metadata block in
+			  sectors
+#used metadata blocks	  Number of metadata blocks used
+#total metadata blocks	  Total number of metadata blocks
+current era		  The current era
+held metadata root	  The location, in blocks, of the metadata root
+			  that has been 'held' for userspace read
+			  access. '-' indicates there is no held root
+========================= ==============================================
 
 Detailed use case
 =================
@@ -88,7 +96,7 @@ Memory usage
 
 The target uses a bitset to record writes in the current era.  It also
 has a spare bitset ready for switching over to a new era.  Other than
-that it uses a few 4k blocks for updating metadata.
+that it uses a few 4k blocks for updating metadata::
 
    (4 * nr_blocks) bytes + buffers
 
Documentation/device-mapper/kcopyd.txt +5 -5
index 820382c4cecf..7651d395127f 100644
@@ -1,3 +1,4 @@
+======
 kcopyd
 ======
 
@@ -7,7 +8,7 @@ notification. It is used by dm-snapshot and dm-mirror.
 
 Users of kcopyd must first create a client and indicate how many memory pages
 to set aside for their copy jobs. This is done with a call to
-kcopyd_client_create().
+kcopyd_client_create()::
 
    int kcopyd_client_create(unsigned int num_pages,
                             struct kcopyd_client **result);
@@ -16,7 +17,7 @@ To start a copy job, the user must set up io_region structures to describe
 the source and destinations of the copy. Each io_region indicates a
 block-device along with the starting sector and size of the region. The source
 of the copy is given as one io_region structure, and the destinations of the
-copy are given as an array of io_region structures.
+copy are given as an array of io_region structures::
 
    struct io_region {
       struct block_device *bdev;
@@ -26,7 +27,7 @@ copy are given as an array of io_region structures.
 
 To start the copy, the user calls kcopyd_copy(), passing in the client
 pointer, pointers to the source and destination io_regions, the name of a
-completion callback routine, and a pointer to some context data for the copy.
+completion callback routine, and a pointer to some context data for the copy::
 
    int kcopyd_copy(struct kcopyd_client *kc, struct io_region *from,
                    unsigned int num_dests, struct io_region *dests,
@@ -41,7 +42,6 @@ write error occurred during the copy.
 
 When a user is done with all their copy jobs, they should call
 kcopyd_client_destroy() to delete the kcopyd client, which will release the
-associated memory pages.
+associated memory pages::
 
    void kcopyd_client_destroy(struct kcopyd_client *kc);
-
Documentation/device-mapper/linear.txt +51 -49

110 lines not on this page · raw message

Documentation/device-mapper/log-writes.txt +48 -43

145 lines not on this page · raw message

Documentation/device-mapper/persistent-data.txt +4 -0
index a333bcb3a6c2..2065c3c5a091 100644
@@ -1,3 +1,7 @@
+===============
+Persistent data
+===============
+
 Introduction
 ============
 
Documentation/device-mapper/snapshot.txt +60 -56

176 lines not on this page · raw message

Documentation/device-mapper/statistics.txt +32 -30

161 lines not on this page · raw message

Documentation/device-mapper/striped.txt +36 -32

87 lines not on this page · raw message

Documentation/device-mapper/switch.txt +25 -22

72 lines not on this page · raw message

Documentation/device-mapper/thin-provisioning.txt +42 -26

190 lines not on this page · raw message

Documentation/device-mapper/unstriped.txt +61 -50

134 lines not on this page · raw message

Documentation/device-mapper/verity.txt +15 -5
index b3d2e4a42255..a4d1c1476d72 100644
@@ -1,5 +1,6 @@
+=========
 dm-verity
-==========
+=========
 
 Device-Mapper's "verity" target provides transparent integrity checking of
 block devices using a cryptographic digest provided by the kernel crypto API.
@@ -7,6 +8,9 @@ This target is read-only.
 
 Construction Parameters
 =======================
+
+::
+
     <version> <dev> <hash_dev>
     <data_block_size> <hash_block_size>
     <num_data_blocks> <hash_start_block>
@@ -160,7 +164,9 @@ calculating the parent node.
 
 The tree looks something like:
 
-alg = sha256, num_blocks = 32768, block_size = 4096
+	alg = sha256, num_blocks = 32768, block_size = 4096
+
+::
 
                                  [   root    ]
                                 /    . . .    \
@@ -189,6 +195,7 @@ block boundary) are the hash blocks which are stored a depth at a time
 
 The full specification of kernel parameters and on-disk metadata format
 is available at the cryptsetup project's wiki page
+
   https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity
 
 Status
@@ -198,7 +205,8 @@ If any check failed, C (for Corruption) is returned.
 
 Example
 =======
-Set up a device:
+Set up a device::
+
   # dmsetup create vroot --readonly --table \
     "0 2097152 verity 1 /dev/sda1 /dev/sda2 4096 4096 262144 1 sha256 "\
     "4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076 "\
@@ -209,11 +217,13 @@ the hash tree or activate the kernel device. This is available from
 the cryptsetup upstream repository https://gitlab.com/cryptsetup/cryptsetup/
 (as a libcryptsetup extension).
 
-Create hash on the device:
+Create hash on the device::
+
   # veritysetup format /dev/sda1 /dev/sda2
   ...
   Root hash: 4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
 
-Activate the device:
+Activate the device::
+
   # veritysetup create vroot /dev/sda1 /dev/sda2 \
     4392712ba01368efdf14b05c76f9e4df0d53664630b5d48632ed17a137f39076
Documentation/device-mapper/writecache.txt +11 -2
index 01532b3008ae..d3d7690f5e8d 100644
@@ -1,3 +1,7 @@
+=================
+Writecache target
+=================
+
 The writecache target caches writes on persistent memory or on SSD. It
 doesn't cache reads because reads are supposed to be cached in page cache
 in normal RAM.
@@ -6,15 +10,18 @@ When the device is constructed, the first sector should be zeroed or the
 first sector should contain valid superblock from previous invocation.
 
 Constructor parameters:
+
 1. type of the cache device - "p" or "s"
-	p - persistent memory
-	s - SSD
+
+	- p - persistent memory
+	- s - SSD
 2. the underlying device that will be cached
 3. the cache device
 4. block size (4096 is recommended; the maximum block size is the page
    size)
 5. the number of optional parameters (the parameters with an argument
    count as two)
+
 	start_sector n		(default: 0)
 		offset from the start of cache device in 512-byte sectors
 	high_watermark n	(default: 50)
@@ -43,6 +50,7 @@ Constructor parameters:
 		applicable only to persistent memory - don't use the FUA
 		flag when writing back data and send the FLUSH request
 		afterwards
+
 		- some underlying devices perform better with fua, some
 		  with nofua. The user should test it
 
@@ -60,6 +68,7 @@ Messages:
 		flush the cache device on next suspend. Use this message
 		when you are going to remove the cache device. The proper
 		sequence for removing the cache device is:
+
 		1. send the "flush_on_suspend" message
 		2. load an inactive table with a linear target that maps
 		   to the underlying device
Documentation/device-mapper/zero.txt +7 -7
index 20fb38e7fa7e..11fb5cf4597c 100644
@@ -1,3 +1,4 @@
+=======
 dm-zero
 =======
 
@@ -18,20 +19,19 @@ filesystem limitations.
 
 To create a sparse device, start by creating a dm-zero device that's the
 desired size of the sparse device. For this example, we'll assume a 10TB
-sparse device.
+sparse device::
 
-TEN_TERABYTES=`expr 10 \* 1024 \* 1024 \* 1024 \* 2`   # 10 TB in sectors
-echo "0 $TEN_TERABYTES zero" | dmsetup create zero1
+  TEN_TERABYTES=`expr 10 \* 1024 \* 1024 \* 1024 \* 2`   # 10 TB in sectors
+  echo "0 $TEN_TERABYTES zero" | dmsetup create zero1
 
 Then create a snapshot of the zero device, using any available block-device as
 the COW device. The size of the COW device will determine the amount of real
 space available to the sparse device. For this example, we'll assume /dev/sdb1
-is an available 10GB partition.
+is an available 10GB partition::
 
-echo "0 $TEN_TERABYTES snapshot /dev/mapper/zero1 /dev/sdb1 p 128" | \
-   dmsetup create sparse1
+  echo "0 $TEN_TERABYTES snapshot /dev/mapper/zero1 /dev/sdb1 p 128" | \
+     dmsetup create sparse1
 
 This will create a 10TB sparse device called /dev/mapper/sparse1 that has
 10GB of actual storage space available. If more than 10GB of data is written
 to this device, it will start returning I/O errors.
-
Signature · 1 line
2.20.1
#18 lore raw

Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

Quoted 1 line · Mauro Carvalho Chehab

Convert the Device Mapper documentation to ReST.

Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.

Please advise, thanks.
Mike

maintainer
#19 lore raw

Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:

Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.

This is a discussion that was mostly resolved some years ago...

Classic Documentation/ is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.

The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:

https://www.kernel.org/doc/html/latest/

Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.

Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.

Thanks,

jon

#20 lore raw

Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

Em Tue, 16 Apr 2019 08:00:24 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 15 lines
Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:

Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.

This is a discussion that was mostly resolved some years ago...

Classic Documentation/ is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.

Quoted 6 lines

The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:

https://www.kernel.org/doc/html/latest/

Just to mention, in the specific case of the device-mapper patch, this is the result of those changes (after renaming the files to .rst, and adding an index file):

https://www.infradead.org/~mchehab/rst_conversion/device-mapper/index.html

Quoted 14 lines

Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.

Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.

Quoted 3 lines

Thanks,

jon

Thanks,
Mauro

#21 lore raw

Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

In reply to Jonathan Corbet
Quoted 27 lines · Jonathan Corbet
Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:

Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.

This is a discussion that was mostly resolved some years ago...

Classic Documentation/ is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.

The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:

https://www.kernel.org/doc/html/latest/

Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.

Quoted 5 lines

Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.

Thanks for the context. I clearly just haven't followed the evolution. Certainly looks like a solid improvement.

Think the last piece I'm missing is: how does one edit a .rst document without having to know to sprinkle syntactic sugar around? Does emacs have a ReST mode? If not what client interface are people using to properly change these documents?

(apologies if this is all spelled out nicely in Documentation/ somewhere, but please help this man learn to fish).

Thanks,
Mike

maintainer
#22 lore raw

Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

Quoted 4 lines · On Tue, 16 Apr 2019 11:48:59 -0400 Mike Snitzer <[email protected]> wrote:

Think the last piece I'm missing is: how does one edit a .rst document without having to know to sprinkle syntactic sugar around? Does emacs have a ReST mode? If not what client interface are people using to properly change these documents?

There is an RST mode for Emacs, yes. But you likely don't really need it. RST is a simple format and, in general, we try to keep the markup to a minimum so that the plain-text files remain as readable as possible. Most of our documents are 99% RST before anybody gets around to formally converting them.

Quoted 2 lines

(apologies if this is all spelled out nicely in Documentation/ somewhere, but please help this man learn to fish).

Basics in Documentation/doc-guide (or
https://www.kernel.org/doc/html/latest/doc-guide/index.html). There's also some history and overview in:

	https://lwn.net/Articles/692704/
	https://lwn.net/Articles/692705/

Thanks,

jon

#23 lore raw

Re: [PATCH 10/57] docs: device-mapper: convert it to ReST format

In reply to Mike Snitzer

Em Tue, 16 Apr 2019 11:48:59 -0400
Mike Snitzer <[email protected]> escreveu:

Quoted 36 lines
Quoted 27 lines · Jonathan Corbet
Quoted 3 lines · On Tue, 16 Apr 2019 09:28:52 -0400 Mike Snitzer <[email protected]> wrote:

Can you help me understand why this is the direction text based Documenation is taking in the Linux kernel? All I see is markup, and escaping of characters, that is a chore to administer over time.

This is a discussion that was mostly resolved some years ago...

Classic Documentation/ is a jumbled collection of unorganized text files, some of which contain highly useful information and others of which haven't had much to offer since about 1996. We are working to turn it into an organized collection where, hopefully, some thought has actually been given to the people who will be reading it.

The ReST conversion, in particular, allows us to link documents into a larger structure, create indexes and cross references, and produce output in formats like HTML and PDF. It lets us present the documentation like this:

https://www.kernel.org/doc/html/latest/

Among other things, making the documentation more accessible in this way makes it easier and more rewarding for developers to improve it, and I believe we are seeing the results of that. Linus called out the documentation work in the 5.1-rc1 announcement, for example.

Quoted 5 lines

Nobody has complained about the maintenance burden of RST docs - so far as I have heard, anyway. Things do break occasionally, but problems in the docs build almost always result from code changes that mess up the kerneldoc comments rather than RST changes, and it's been that way for as long as I've been paying attention.

Quoted 7 lines

Thanks for the context. I clearly just haven't followed the evolution. Certainly looks like a solid improvement.

Think the last piece I'm missing is: how does one edit a .rst document without having to know to sprinkle syntactic sugar around? Does emacs have a ReST mode? If not what client interface are people using to properly change these documents?

I guess the main point is that, after writing a .rst file, run "make htmldocs" and see how it fits :-)

As Jon mentioned, a large number of documents (even some written lots of years ago) already fits into ReST, and keeping it simpler makes easier for plain text file readers.

We do have some documents (like the media book), were we use a lot of the markup stuff, as those documents came from DocBook and it is full of cross-references, complex tables, images, examples, etc, but for most subsystems, you're safe with the usual stuff.

Quoted 3 lines

(apologies if this is all spelled out nicely in Documentation/ somewhere, but please help this man learn to fish).

A few tips if you want to write documents that are easy to read as text files and produce nice output after parsed:

1) it is written to document Python. So, it is indentation sensitive. Usually most of the fixes are just to properly indent things;

2) By default, it identifies line breaks with two \n. The exceptions are literal blocks like:

::
foo
bar

and things like:

foo
bar

(in this case, it will bold **foo**)

Another trick that I use to avoid the need of adding an extra \n is to convert itemized lists into a table, with:

	===
	foo
	bar
	===

3) Things like "struct *foo" usually produces error, as a single
* is interpreted as italic. The parser will look for another *. As it won't find, it will produce an error. So, this need to be escaped somehow.

While you can escape such special characters like * and _ with an inverted bar, like "struct \*foo", that looks ugly for casual text file readers.

Instead, I do either::

struct *foo

or, if I want it in the middle of a text, I use struct *foo. IMO, placing it on a literal block (::) looks visually better for both text and html modes.

Thanks,
Mauro

#24 lore raw

PATCH 11/57 docs: extcon: move it to acpi dir and convert it to ReST

In reply to Mauro Carvalho Chehab

The intel-int3496.txt file is a documentation for an ACPI driver.

There's no reason to keep it on a separate directory.

So, instead of keeping it on some random location, move it to a sub-directory inside the ACPI documentation dir.

For now, keep it with .txt extension, in order to avoid Sphinx build noise. A later patch should change it to .rst and movin it to be together with other acpi docs.

---
 .../drivers/extcon-intel-int3496.txt}              | 14 ++++++++++----
 MAINTAINERS                                        |  2 +-
 2 files changed, 11 insertions(+), 5 deletions(-)
 rename Documentation/{extcon/intel-int3496.txt => acpi/drivers/extcon-intel-int3496.txt} (66%)
Documentation/acpi/drivers/extcon-intel-int3496.txt renamed from Documentation/extcon/intel-int3496.txt +10 -4
similarity index 66%
rename from Documentation/extcon/intel-int3496.txt
rename to Documentation/acpi/drivers/extcon-intel-int3496.txt
index 8155dbc7fad3..5137ca834b54 100644
@@ -1,5 +1,6 @@
+=====================================================
 Intel INT3496 ACPI device extcon driver documentation
------------------------------------------------------
+=====================================================
 
 The Intel INT3496 ACPI device extcon driver is a driver for ACPI
 devices with an acpi-id of INT3496, such as found for example on
@@ -13,15 +14,20 @@ between an USB host and an USB peripheral controller.
 The ACPI devices exposes this functionality by returning an array with up
 to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call:
 
-Index 0: The input gpio for the id-pin, this is always present and valid
-Index 1: The output gpio for enabling Vbus output from the device to the otg
+=======  =====================================================================
+Index 0  The input gpio for the id-pin, this is always present and valid
+Index 1  The output gpio for enabling Vbus output from the device to the otg
          port, write 1 to enable the Vbus output (this gpio descriptor may
          be absent or invalid)
-Index 2: The output gpio for muxing of the data pins between the USB host and
+Index 2  The output gpio for muxing of the data pins between the USB host and
          the USB peripheral controller, write 1 to mux to the peripheral
          controller
+=======  =====================================================================
 
 There is a mapping between indices and GPIO connection IDs as follows
+
+	======= =======
 	id	index 0
 	vbus	index 1
 	mux	index 2
+	======= =======
MAINTAINERS +1 -1
index 8de292192227..99822421b447 100644
@@ -5958,7 +5958,7 @@ S:	Maintained
 F:	drivers/extcon/
 F:	include/linux/extcon/
 F:	include/linux/extcon.h
-F:	Documentation/extcon/
+F:	Documentation/acpi/drivers/extcon-intel-int3496.txt
 F:	Documentation/devicetree/bindings/extcon/
 
 EXYNOS DP DRIVER
Signature · 1 line
2.20.1
#25 lore raw

PATCH 12/57 docs: fault-injection: convert it to ReST format

In reply to Mauro Carvalho Chehab

Instead of using plain text, convert it to ReST format, in order for the docs to be parsed and produce html and pdf output.

---
 .../fault-injection/fault-injection.txt       | 265 +++++++++---------
 .../fault-injection/notifier-error-inject.txt |  18 +-
 .../fault-injection/nvme-fault-injection.txt  | 174 ++++++------
 .../fault-injection/provoke-crashes.txt       |  40 ++-
 4 files changed, 263 insertions(+), 234 deletions(-)
Documentation/fault-injection/fault-injection.txt +138 -127
index a17517a083c3..f51bb21d20e4 100644
@@ -1,3 +1,4 @@
+===========================================
 Fault injection capabilities infrastructure
 ===========================================
 
@@ -7,36 +8,36 @@ See also drivers/md/md-faulty.c and "every_nth" module option for scsi_debug.
 Available fault injection capabilities
 --------------------------------------
 
-o failslab
+- failslab
 
   injects slab allocation failures. (kmalloc(), kmem_cache_alloc(), ...)
 
-o fail_page_alloc
+- fail_page_alloc
 
   injects page allocation failures. (alloc_pages(), get_free_pages(), ...)
 
-o fail_futex
+- fail_futex
 
   injects futex deadlock and uaddr fault errors.
 
-o fail_make_request
+- fail_make_request
 
   injects disk IO errors on devices permitted by setting
   /sys/block/<device>/make-it-fail or
   /sys/block/<device>/<partition>/make-it-fail. (generic_make_request())
 
-o fail_mmc_request
+- fail_mmc_request
 
   injects MMC data errors on devices permitted by setting
   debugfs entries under /sys/kernel/debug/mmc0/fail_mmc_request
 
-o fail_function
+- fail_function
 
   injects error return on specific functions, which are marked by
   ALLOW_ERROR_INJECTION() macro, by setting debugfs entries
   under /sys/kernel/debug/fail_function. No boot option supported.
 
-o NVMe fault injection
+- NVMe fault injection
 
   inject NVMe status code and retry flag on devices permitted by setting
   debugfs entries under /sys/kernel/debug/nvme*/fault_inject. The default
@@ -47,7 +48,8 @@ o NVMe fault injection
 Configure fault-injection capabilities behavior
 -----------------------------------------------
 
-o debugfs entries
+debugfs entries
+^^^^^^^^^^^^^^^
 
 fault-inject-debugfs kernel module provides some debugfs entries for runtime
 configuration of fault-injection capabilities.
@@ -55,6 +57,7 @@ configuration of fault-injection capabilities.
 - /sys/kernel/debug/fail*/probability:
 
 	likelihood of failure injection, in percent.
+
 	Format: <percent>
 
 	Note that one-failure-per-hundred is a very high error rate
@@ -83,6 +86,7 @@ configuration of fault-injection capabilities.
 - /sys/kernel/debug/fail*/verbose
 
 	Format: { 0 | 1 | 2 }
+
 	specifies the verbosity of the messages when failure is
 	injected.  '0' means no messages; '1' will print only a single
 	log line per failure; '2' will print a call trace too -- useful
@@ -91,14 +95,15 @@ configuration of fault-injection capabilities.
 - /sys/kernel/debug/fail*/task-filter:
 
 	Format: { 'Y' | 'N' }
+
 	A value of 'N' disables filtering by process (default).
 	Any positive value limits failures to only processes indicated by
 	/proc/<pid>/make-it-fail==1.
 
-- /sys/kernel/debug/fail*/require-start:
-- /sys/kernel/debug/fail*/require-end:
-- /sys/kernel/debug/fail*/reject-start:
-- /sys/kernel/debug/fail*/reject-end:
+- /sys/kernel/debug/fail*/require-start,
+  /sys/kernel/debug/fail*/require-end,
+  /sys/kernel/debug/fail*/reject-start,
+  /sys/kernel/debug/fail*/reject-end:
 
 	specifies the range of virtual addresses tested during
 	stacktrace walking.  Failure is injected only if some caller
@@ -116,6 +121,7 @@ configuration of fault-injection capabilities.
 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem:
 
 	Format: { 'Y' | 'N' }
+
 	default is 'N', setting it to 'Y' won't inject failures into
 	highmem/user allocations.
 
@@ -123,6 +129,7 @@ configuration of fault-injection capabilities.
 - /sys/kernel/debug/fail_page_alloc/ignore-gfp-wait:
 
 	Format: { 'Y' | 'N' }
+
 	default is 'N', setting it to 'Y' will inject failures
 	only into non-sleep allocations (GFP_ATOMIC allocations).
 
@@ -134,12 +141,14 @@ configuration of fault-injection capabilities.
 - /sys/kernel/debug/fail_futex/ignore-private:
 
 	Format: { 'Y' | 'N' }
+
 	default is 'N', setting it to 'Y' will disable failure injections
 	when dealing with private (address space) futexes.
 
 - /sys/kernel/debug/fail_function/inject:
 
 	Format: { 'function-name' | '!function-name' | '' }
+
 	specifies the target function of error injection by name.
 	If the function name leads '!' prefix, given function is
 	removed from injection list. If nothing specified ('')
@@ -160,10 +169,11 @@ configuration of fault-injection capabilities.
 	function for given function. This will be created when
 	user specifies new injection entry.
 
-o Boot option
+Boot option
+^^^^^^^^^^^
 
 In order to inject faults while debugfs is not available (early boot time),
-use the boot option:
+use the boot option::
 
 	failslab=
 	fail_page_alloc=
@@ -171,10 +181,11 @@ use the boot option:
 	fail_futex=
 	mmc_core.fail_request=<interval>,<probability>,<space>,<times>
 
-o proc entries
+proc entries
+^^^^^^^^^^^^
 
-- /proc/<pid>/fail-nth:
-- /proc/self/task/<tid>/fail-nth:
+- /proc/<pid>/fail-nth,
+  /proc/self/task/<tid>/fail-nth:
 
 	Write to this file of integer N makes N-th call in the task fail.
 	Read from this file returns a integer value. A value of '0' indicates
@@ -191,16 +202,16 @@ o proc entries
 How to add new fault injection capability
 -----------------------------------------
 
-o #include <linux/fault-inject.h>
+- #include <linux/fault-inject.h>
 
-o define the fault attributes
+- define the fault attributes
 
   DECLARE_FAULT_ATTR(name);
 
   Please see the definition of struct fault_attr in fault-inject.h
   for details.
 
-o provide a way to configure fault attributes
+- provide a way to configure fault attributes
 
 - boot option
 
@@ -222,126 +233,126 @@ o provide a way to configure fault attributes
   single kernel module, it is better to provide module parameters to
   configure the fault attributes.
 
-o add a hook to insert failures
+- add a hook to insert failures
 
-  Upon should_fail() returning true, client code should inject a failure.
+  Upon should_fail() returning true, client code should inject a failure:
 
 	should_fail(attr, size);
 
 Application Examples
 --------------------
 
-o Inject slab allocation failures into module init/exit code
+- Inject slab allocation failures into module init/exit code::
 
-#!/bin/bash
+    #!/bin/bash
 
-FAILTYPE=failslab
-echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+    FAILTYPE=failslab
+    echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
+    echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+    echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+    echo -1 > /sys/kernel/debug/$FAILTYPE/times
+    echo 0 > /sys/kernel/debug/$FAILTYPE/space
+    echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+    echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
 
-faulty_system()
-{
+    faulty_system()
+    {
 	bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
-}
+    }
 
-if [ $# -eq 0 ]
-then
+    if [ $# -eq 0 ]
+    then
 	echo "Usage: $0 modulename [ modulename ... ]"
 	exit 1
-fi
+    fi
 
-for m in $*
-do
+    for m in $*
+    do
 	echo inserting $m...
 	faulty_system modprobe $m
 
 	echo removing $m...
 	faulty_system modprobe -r $m
-done
+    done
 
 ------------------------------------------------------------------------------
 
-o Inject page allocation failures only for a specific module
+- Inject page allocation failures only for a specific module::
 
-#!/bin/bash
+    #!/bin/bash
 
-FAILTYPE=fail_page_alloc
-module=$1
+    FAILTYPE=fail_page_alloc
+    module=$1
 
-if [ -z $module ]
-then
+    if [ -z $module ]
+    then
 	echo "Usage: $0 <modulename>"
 	exit 1
-fi
+    fi
 
-modprobe $module
+    modprobe $module
 
-if [ ! -d /sys/module/$module/sections ]
-then
+    if [ ! -d /sys/module/$module/sections ]
+    then
 	echo Module $module is not loaded
 	exit 1
-fi
+    fi
 
-cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
-cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
+    cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
+    cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end
 
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 10 > /sys/kernel/debug/$FAILTYPE/probability
-echo 100 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
-echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
-echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
+    echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+    echo 10 > /sys/kernel/debug/$FAILTYPE/probability
+    echo 100 > /sys/kernel/debug/$FAILTYPE/interval
+    echo -1 > /sys/kernel/debug/$FAILTYPE/times
+    echo 0 > /sys/kernel/debug/$FAILTYPE/space
+    echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
+    echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
+    echo 1 > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
+    echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth
 
-trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
+    trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT
 
-echo "Injecting errors into the module $module... (interrupt to stop)"
-sleep 1000000
+    echo "Injecting errors into the module $module... (interrupt to stop)"
+    sleep 1000000
 
 ------------------------------------------------------------------------------
 
-o Inject open_ctree error while btrfs mount
+- Inject open_ctree error while btrfs mount::
 
-#!/bin/bash
+    #!/bin/bash
 
-rm -f testfile.img
-dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
-DEVICE=$(losetup --show -f testfile.img)
-mkfs.btrfs -f $DEVICE
-mkdir -p tmpmnt
+    rm -f testfile.img
+    dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
+    DEVICE=$(losetup --show -f testfile.img)
+    mkfs.btrfs -f $DEVICE
+    mkdir -p tmpmnt
 
-FAILTYPE=fail_function
-FAILFUNC=open_ctree
-echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
-echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
-echo N > /sys/kernel/debug/$FAILTYPE/task-filter
-echo 100 > /sys/kernel/debug/$FAILTYPE/probability
-echo 0 > /sys/kernel/debug/$FAILTYPE/interval
-echo -1 > /sys/kernel/debug/$FAILTYPE/times
-echo 0 > /sys/kernel/debug/$FAILTYPE/space
-echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
+    FAILTYPE=fail_function
+    FAILFUNC=open_ctree
+    echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
+    echo -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
+    echo N > /sys/kernel/debug/$FAILTYPE/task-filter
+    echo 100 > /sys/kernel/debug/$FAILTYPE/probability
+    echo 0 > /sys/kernel/debug/$FAILTYPE/interval
+    echo -1 > /sys/kernel/debug/$FAILTYPE/times
+    echo 0 > /sys/kernel/debug/$FAILTYPE/space
+    echo 1 > /sys/kernel/debug/$FAILTYPE/verbose
 
-mount -t btrfs $DEVICE tmpmnt
-if [ $? -ne 0 ]
-then
+    mount -t btrfs $DEVICE tmpmnt
+    if [ $? -ne 0 ]
+    then
 	echo "SUCCESS!"
-else
+    else
 	echo "FAILED!"
 	umount tmpmnt
-fi
+    fi
 
-echo > /sys/kernel/debug/$FAILTYPE/inject
+    echo > /sys/kernel/debug/$FAILTYPE/inject
 
-rmdir tmpmnt
-losetup -d $DEVICE
-rm testfile.img
+    rmdir tmpmnt
+    losetup -d $DEVICE
+    rm testfile.img
 
 
 Tool to run command with failslab or fail_page_alloc
@@ -354,43 +365,43 @@ see the following examples.
 Examples:
 
 Run a command "make -C tools/testing/selftests/ run_tests" with injecting slab
-allocation failure.
+allocation failure::
 
 	# ./tools/testing/fault-injection/failcmd.sh \
 		-- make -C tools/testing/selftests/ run_tests
 
 Same as above except to specify 100 times failures at most instead of one time
-at most by default.
+at most by default::
 
 	# ./tools/testing/fault-injection/failcmd.sh --times=100 \
 		-- make -C tools/testing/selftests/ run_tests
 
 Same as above except to inject page allocation failure instead of slab
-allocation failure.
+allocation failure::
 
 	# env FAILCMD_TYPE=fail_page_alloc \
 		./tools/testing/fault-injection/failcmd.sh --times=100 \
-                -- make -C tools/testing/selftests/ run_tests
+		-- make -C tools/testing/selftests/ run_tests
 
 Systematic faults using fail-nth
 ---------------------------------
 
 The following code systematically faults 0-th, 1-st, 2-nd and so on
-capabilities in the socketpair() system call.
+capabilities in the socketpair() system call::
 
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <sys/socket.h>
-#include <sys/syscall.h>
-#include <fcntl.h>
-#include <unistd.h>
-#include <string.h>
-#include <stdlib.h>
-#include <stdio.h>
-#include <errno.h>
+  #include <sys/types.h>
+  #include <sys/stat.h>
+  #include <sys/socket.h>
+  #include <sys/syscall.h>
+  #include <fcntl.h>
+  #include <unistd.h>
+  #include <string.h>
+  #include <stdlib.h>
+  #include <stdio.h>
+  #include <errno.h>
 
-int main()
-{
+  int main()
+  {
 	int i, err, res, fail_nth, fds[2];
 	char buf[128];
 
@@ -413,23 +424,23 @@ int main()
 			break;
 	}
 	return 0;
-}
+  }
 
-An example output:
+An example output::
 
-1-th fault Y: res=-1/23
-2-th fault Y: res=-1/23
-3-th fault Y: res=-1/12
-4-th fault Y: res=-1/12
-5-th fault Y: res=-1/23
-6-th fault Y: res=-1/23
-7-th fault Y: res=-1/23
-8-th fault Y: res=-1/12
-9-th fault Y: res=-1/12
-10-th fault Y: res=-1/12
-11-th fault Y: res=-1/12
-12-th fault Y: res=-1/12
-13-th fault Y: res=-1/12
-14-th fault Y: res=-1/12
-15-th fault Y: res=-1/12
-16-th fault N: res=0/12
+	1-th fault Y: res=-1/23
+	2-th fault Y: res=-1/23
+	3-th fault Y: res=-1/12
+	4-th fault Y: res=-1/12
+	5-th fault Y: res=-1/23
+	6-th fault Y: res=-1/23
+	7-th fault Y: res=-1/23
+	8-th fault Y: res=-1/12
+	9-th fault Y: res=-1/12
+	10-th fault Y: res=-1/12
+	11-th fault Y: res=-1/12
+	12-th fault Y: res=-1/12
+	13-th fault Y: res=-1/12
+	14-th fault Y: res=-1/12
+	15-th fault Y: res=-1/12
+	16-th fault N: res=0/12
Documentation/fault-injection/notifier-error-inject.txt +11 -7
index e861d761de24..1668b6e48d3a 100644
@@ -14,7 +14,8 @@ modules that can be used to test the following notifiers.
 PM notifier error injection module
 ----------------------------------
 This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
+
+  /sys/kernel/debug/notifier-error-inject/pm/actions/<notifier event>/error
 
 Possible PM notifier events to be failed are:
 
@@ -22,7 +23,7 @@ Possible PM notifier events to be failed are:
  * PM_SUSPEND_PREPARE
  * PM_RESTORE_PREPARE
 
-Example: Inject PM suspend error (-12 = -ENOMEM)
+Example: Inject PM suspend error (-12 = -ENOMEM)::
 
 	# cd /sys/kernel/debug/notifier-error-inject/pm/
 	# echo -12 > actions/PM_SUSPEND_PREPARE/error
@@ -32,14 +33,15 @@ Example: Inject PM suspend error (-12 = -ENOMEM)
 Memory hotplug notifier error injection module
 ----------------------------------------------
 This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
+
+  /sys/kernel/debug/notifier-error-inject/memory/actions/<notifier event>/error
 
 Possible memory notifier events to be failed are:
 
  * MEM_GOING_ONLINE
  * MEM_GOING_OFFLINE
 
-Example: Inject memory hotplug offline error (-12 == -ENOMEM)
+Example: Inject memory hotplug offline error (-12 == -ENOMEM)::
 
 	# cd /sys/kernel/debug/notifier-error-inject/memory
 	# echo -12 > actions/MEM_GOING_OFFLINE/error
@@ -49,7 +51,8 @@ Example: Inject memory hotplug offline error (-12 == -ENOMEM)
 powerpc pSeries reconfig notifier error injection module
 --------------------------------------------------------
 This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
+
+  /sys/kernel/debug/notifier-error-inject/pSeries-reconfig/actions/<notifier event>/error
 
 Possible pSeries reconfig notifier events to be failed are:
 
@@ -61,7 +64,8 @@ Possible pSeries reconfig notifier events to be failed are:
 Netdevice notifier error injection module
 ----------------------------------------------
 This feature is controlled through debugfs interface
-/sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
+
+  /sys/kernel/debug/notifier-error-inject/netdev/actions/<notifier event>/error
 
 Netdevice notifier events which can be failed are:
 
@@ -75,7 +79,7 @@ Netdevice notifier events which can be failed are:
  * NETDEV_PRECHANGEUPPER
  * NETDEV_CHANGEUPPER
 
-Example: Inject netdevice mtu change error (-22 == -EINVAL)
+Example: Inject netdevice mtu change error (-22 == -EINVAL)::
 
 	# cd /sys/kernel/debug/notifier-error-inject/netdev
 	# echo -22 > actions/NETDEV_CHANGEMTU/error
Documentation/fault-injection/nvme-fault-injection.txt +89 -85

190 lines not on this page · raw message

Documentation/fault-injection/provoke-crashes.txt +25 -15
index 7a9d3d81525b..9279a3e12278 100644
@@ -1,3 +1,7 @@
+===============
+Provoke crashes
+===============
+
 The lkdtm module provides an interface to crash or injure the kernel at
 predefined crashpoints to evaluate the reliability of crash dumps obtained
 using different dumping solutions. The module uses KPROBEs to instrument
@@ -8,31 +12,37 @@ support.
 You can provide the way either through module arguments when inserting
 the module, or through a debugfs interface.
 
-Usage: insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
-				[cpoint_count={>0}]
+Usage::
 
-  recur_count : Recursion level for the stack overflow test. Default is 10.
+	insmod lkdtm.ko [recur_count={>0}] cpoint_name=<> cpoint_type=<>
+			[cpoint_count={>0}]
 
-  cpoint_name : Crash point where the kernel is to be crashed. It can be
-	 one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
-	 FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
-	 IDE_CORE_CP, DIRECT
+recur_count
+	Recursion level for the stack overflow test. Default is 10.
 
-  cpoint_type : Indicates the action to be taken on hitting the crash point.
-     It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
-     CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
-     WRITE_AFTER_FREE,
+cpoint_name
+	Crash point where the kernel is to be crashed. It can be
+	one of INT_HARDWARE_ENTRY, INT_HW_IRQ_EN, INT_TASKLET_ENTRY,
+	FS_DEVRW, MEM_SWAPOUT, TIMERADD, SCSI_DISPATCH_CMD,
+	IDE_CORE_CP, DIRECT
 
-  cpoint_count : Indicates the number of times the crash point is to be hit
-    to trigger an action. The default is 10.
+cpoint_type
+	Indicates the action to be taken on hitting the crash point.
+	It can be one of PANIC, BUG, EXCEPTION, LOOP, OVERFLOW,
+	CORRUPT_STACK, UNALIGNED_LOAD_STORE_WRITE, OVERWRITE_ALLOCATION,
+	WRITE_AFTER_FREE,
+
+cpoint_count
+	Indicates the number of times the crash point is to be hit
+	to trigger an action. The default is 10.
 
 You can also induce failures by mounting debugfs and writing the type to
-<mountpoint>/provoke-crash/<crashpoint>. E.g.,
+<mountpoint>/provoke-crash/<crashpoint>. E.g.::
 
   mount -t debugfs debugfs /mnt
   echo EXCEPTION > /mnt/provoke-crash/INT_HARDWARE_ENTRY
 
 
-A special file is `DIRECT' which will induce the crash directly without
+A special file is `DIRECT` which will induce the crash directly without
 KPROBE instrumentation. This mode is the only one available when the module
 is built on a kernel without KPROBEs support.
Signature · 1 line
2.20.1
#26 lore raw

PATCH 13/57 docs: fb: convert documentation to ReST format

In reply to Mauro Carvalho Chehab

Convert all documents here from plain txt to ReST format, in order to allow parsing them with the documentation build system.

---
 Documentation/fb/api.txt         |  29 +-
 Documentation/fb/arkfb.txt       |   8 +-
 Documentation/fb/aty128fb.txt    |  31 +-
 Documentation/fb/cirrusfb.txt    |  47 ++-
 Documentation/fb/cmap_xfbdev.txt |  57 ++--
 Documentation/fb/deferred_io.txt |  28 +-
 Documentation/fb/efifb.txt       |  18 +-
 Documentation/fb/ep93xx-fb.txt   |  25 +-
 Documentation/fb/fbcon.txt       | 177 ++++++-----
 Documentation/fb/framebuffer.txt |  79 +++--
 Documentation/fb/gxfb.txt        |  22 +-
 Documentation/fb/intel810.txt    |  77 +++--
 Documentation/fb/intelfb.txt     |  62 ++--
 Documentation/fb/internals.txt   |  24 +-
 Documentation/fb/lxfb.txt        |  23 +-
 Documentation/fb/matroxfb.txt    | 526 ++++++++++++++++---------------
 Documentation/fb/metronomefb.txt |   8 +-
 Documentation/fb/modedb.txt      |  44 +--
 Documentation/fb/pvr2fb.txt      |  55 ++--
 Documentation/fb/pxafb.txt       |  81 +++--
 Documentation/fb/s3fb.txt        |   8 +-
 Documentation/fb/sa1100fb.txt    |  23 +-
 Documentation/fb/sh7760fb.txt    | 153 +++++----
 Documentation/fb/sisfb.txt       |  40 +--
 Documentation/fb/sm501.txt       |   7 +-
 Documentation/fb/sm712fb.txt     |  18 +-
 Documentation/fb/sstfb.txt       | 231 ++++++++------
 Documentation/fb/tgafb.txt       |  30 +-
 Documentation/fb/tridentfb.txt   |  34 +-
 Documentation/fb/udlfb.txt       |  55 ++--
 Documentation/fb/uvesafb.txt     | 128 ++++----
 Documentation/fb/vesafb.txt      | 121 +++----
 Documentation/fb/viafb.txt       | 393 +++++++++++++----------
 Documentation/fb/vt8623fb.txt    |  10 +-
 34 files changed, 1455 insertions(+), 1217 deletions(-)
Documentation/fb/api.txt +15 -14
index d52cf1e3b975..79ec33dded74 100644
@@ -1,5 +1,6 @@
-			The Frame Buffer Device API
-			---------------------------
+===========================
+The Frame Buffer Device API
+===========================
 
 Last revised: June 21, 2011
 
@@ -21,13 +22,13 @@ deal with different behaviours.
 ---------------
 
 Device and driver capabilities are reported in the fixed screen information
-capabilities field.
+capabilities field::
 
-struct fb_fix_screeninfo {
+  struct fb_fix_screeninfo {
 	...
 	__u16 capabilities;		/* see FB_CAP_*			*/
 	...
-};
+  };
 
 Application should use those capabilities to find out what features they can
 expect from the device and driver.
@@ -151,9 +152,9 @@ fb_fix_screeninfo and fb_var_screeninfo structure respectively.
 struct fb_fix_screeninfo stores device independent unchangeable information
 about the frame buffer device and the current format. Those information can't
 be directly modified by applications, but can be changed by the driver when an
-application modifies the format.
+application modifies the format::
 
-struct fb_fix_screeninfo {
+  struct fb_fix_screeninfo {
 	char id[16];			/* identification string eg "TT Builtin" */
 	unsigned long smem_start;	/* Start of frame buffer mem */
 					/* (physical address) */
@@ -172,13 +173,13 @@ struct fb_fix_screeninfo {
 					/*  specific chip/card we have	*/
 	__u16 capabilities;		/* see FB_CAP_*			*/
 	__u16 reserved[2];		/* Reserved for future compatibility */
-};
+  };
 
 struct fb_var_screeninfo stores device independent changeable information
 about a frame buffer device, its current format and video mode, as well as
-other miscellaneous parameters.
+other miscellaneous parameters::
 
-struct fb_var_screeninfo {
+  struct fb_var_screeninfo {
 	__u32 xres;			/* visible resolution		*/
 	__u32 yres;
 	__u32 xres_virtual;		/* virtual resolution		*/
@@ -216,7 +217,7 @@ struct fb_var_screeninfo {
 	__u32 rotate;			/* angle we rotate counter clockwise */
 	__u32 colorspace;		/* colorspace for FOURCC-based modes */
 	__u32 reserved[4];		/* Reserved for future compatibility */
-};
+  };
 
 To modify variable information, applications call the FBIOPUT_VSCREENINFO
 ioctl with a pointer to a fb_var_screeninfo structure. If the call is
@@ -255,14 +256,14 @@ monochrome, grayscale or pseudocolor visuals, although this is not required.
 
 - For truecolor and directcolor formats, applications set the grayscale field
   to zero, and the red, blue, green and transp fields to describe the layout of
-  color components in memory.
+  color components in memory::
 
-struct fb_bitfield {
+    struct fb_bitfield {
 	__u32 offset;			/* beginning of bitfield	*/
 	__u32 length;			/* length of bitfield		*/
 	__u32 msb_right;		/* != 0 : Most significant bit is */
 					/* right */
-};
+    };
 
   Pixel values are bits_per_pixel wide and are split in non-overlapping red,
   green, blue and alpha (transparency) components. Location and size of each
Documentation/fb/arkfb.txt +4 -4
index e8487a9d6a05..aeca8773dd7e 100644
@@ -1,6 +1,6 @@
-
-	arkfb - fbdev driver for ARK Logic chips
-	========================================
+========================================
+arkfb - fbdev driver for ARK Logic chips
+========================================
 
 
 Supported Hardware
@@ -47,7 +47,7 @@ Missing Features
 (alias TODO list)
 
 	* secondary (not initialized by BIOS) device support
-   	* big endian support
+	* big endian support
 	* DPMS support
 	* MMIO support
 	* interlaced mode variant
Documentation/fb/aty128fb.txt +17 -14
index b605204fcfe1..e3859071270f 100644
@@ -1,8 +1,9 @@
-[This file is cloned from VesaFB/matroxfb]
-
+=================
 What is aty128fb?
 =================
 
+.. [This file is cloned from VesaFB/matroxfb]
+
 This is a driver for a graphic framebuffer for ATI Rage128 based devices
 on Intel and PPC boxes.
 
@@ -24,14 +25,14 @@ How to use it?
 ==============
 
 Switching modes is done using the  video=aty128fb:<resolution>... modedb
-boot parameter or using `fbset' program.
+boot parameter or using `fbset` program.
 
 See Documentation/fb/modedb.txt for more information on modedb
 resolutions.
 
 You should compile in both vgacon (to boot if you remove your Rage128 from
 box) and aty128fb (for graphics mode). You should not compile-in vesafb
-unless you have primary display on non-Rage128 VBE2.0 device (see 
+unless you have primary display on non-Rage128 VBE2.0 device (see
 Documentation/fb/vesafb.txt for details).
 
 
@@ -48,16 +49,18 @@ Configuration
 =============
 
 You can pass kernel command line options to vesafb with
-`video=aty128fb:option1,option2:value2,option3' (multiple options should
-be separated by comma, values are separated from options by `:'). 
+`video=aty128fb:option1,option2:value2,option3` (multiple options should
+be separated by comma, values are separated from options by `:`).
 Accepted options:
 
-noaccel  - do not use acceleration engine. It is default.
-accel    - use acceleration engine. Not finished.
-vmode:x  - chooses PowerMacintosh video mode <x>. Deprecated.
-cmode:x  - chooses PowerMacintosh colour mode <x>. Deprecated.
-<XxX@X>  - selects startup videomode. See modedb.txt for detailed
-	   explanation. Default is 640x480x8bpp.
+========= =======================================================
+noaccel   do not use acceleration engine. It is default.
+accel     use acceleration engine. Not finished.
+vmode:x   chooses PowerMacintosh video mode <x>. Deprecated.
+cmode:x   chooses PowerMacintosh colour mode <x>. Deprecated.
+<XxX@X>   selects startup videomode. See modedb.txt for detailed
+	  explanation. Default is 640x480x8bpp.
+========= =======================================================
 
 
 Limitations
@@ -65,8 +68,8 @@ Limitations
 
 There are known and unknown bugs, features and misfeatures.
 Currently there are following known bugs:
- + This driver is still experimental and is not finished.  Too many
+
+ - This driver is still experimental and is not finished.  Too many
    bugs/errata to list here.
 
---
 Brad Douglas <[email protected]>
Documentation/fb/cirrusfb.txt +22 -25

69 lines not on this page · raw message

Documentation/fb/cmap_xfbdev.txt +30 -27

82 lines not on this page · raw message

Documentation/fb/deferred_io.txt +16 -12
index 748328370250..7300cff255a3 100644
@@ -1,5 +1,6 @@
+===========
 Deferred IO
------------
+===========
 
 Deferred IO is a way to delay and repurpose IO. It uses host memory as a
 buffer and the MMU pagefault as a pretrigger for when to perform the device
@@ -16,7 +17,7 @@ works:
 - app continues writing to that page with no additional cost. this is
   the key benefit.
 - the workqueue task comes in and mkcleans the pages on the list, then
- completes the work associated with updating the framebuffer. this is
+  completes the work associated with updating the framebuffer. this is
   the real work talking to the device.
 - app tries to write to the address (that has now been mkcleaned)
 - get pagefault and the above sequence occurs again
@@ -47,29 +48,32 @@ How to use it: (for fbdev drivers)
 ----------------------------------
 The following example may be helpful.
 
-1. Setup your structure. Eg:
+1. Setup your structure. Eg::
 
-static struct fb_deferred_io hecubafb_defio = {
-	.delay		= HZ,
-	.deferred_io	= hecubafb_dpy_deferred_io,
-};
+	static struct fb_deferred_io hecubafb_defio = {
+		.delay		= HZ,
+		.deferred_io	= hecubafb_dpy_deferred_io,
+	};
 
 The delay is the minimum delay between when the page_mkwrite trigger occurs
 and when the deferred_io callback is called. The deferred_io callback is
 explained below.
 
-2. Setup your deferred IO callback. Eg:
-static void hecubafb_dpy_deferred_io(struct fb_info *info,
-				struct list_head *pagelist)
+2. Setup your deferred IO callback. Eg::
+
+	static void hecubafb_dpy_deferred_io(struct fb_info *info,
+					     struct list_head *pagelist)
 
 The deferred_io callback is where you would perform all your IO to the display
 device. You receive the pagelist which is the list of pages that were written
 to during the delay. You must not modify this list. This callback is called
 from a workqueue.
 
-3. Call init
+3. Call init::
+
 	info->fbdefio = &hecubafb_defio;
 	fb_deferred_io_init(info);
 
-4. Call cleanup
+4. Call cleanup::
+
 	fb_deferred_io_cleanup(info);
Documentation/fb/efifb.txt +10 -8
index 1a85c1bdaf38..04840331a00e 100644
@@ -1,6 +1,6 @@
-
+==============
 What is efifb?
-===============
+==============
 
 This is a generic EFI platform driver for Intel based Apple computers.
 efifb is only for EFI booted Intel Macs.
@@ -8,16 +8,17 @@ efifb is only for EFI booted Intel Macs.
 Supported Hardware
 ==================
 
-iMac 17"/20"
-Macbook
-Macbook Pro 15"/17"
-MacMini
+- iMac 17"/20"
+- Macbook
+- Macbook Pro 15"/17"
+- MacMini
 
 How to use it?
 ==============
 
 efifb does not have any kind of autodetection of your machine.
-You have to add the following kernel parameters in your elilo.conf:
+You have to add the following kernel parameters in your elilo.conf::
+
 	Macbook :
 		video=efifb:macbook
 	MacMini :
@@ -29,9 +30,10 @@ You have to add the following kernel parameters in your elilo.conf:
 
 Accepted options:
 
+======= ===========================================================
 nowc	Don't map the framebuffer write combined. This can be used
 	to workaround side-effects and slowdowns on other CPU cores
 	when large amounts of console data are written.
+======= ===========================================================
 
---
 Edgar Hucek <[email protected]>
Documentation/fb/ep93xx-fb.txt +15 -10
index 5af1bd9effae..50b6f8103a49 100644
@@ -4,7 +4,7 @@ Driver for EP93xx LCD controller
 
 The EP93xx LCD controller can drive both standard desktop monitors and
 embedded LCD displays. If you have a standard desktop monitor then you
-can use the standard Linux video mode database. In your board file:
+can use the standard Linux video mode database. In your board file::
 
 	static struct ep93xxfb_mach_info some_board_fb_info = {
 		.num_modes	= EP93XXFB_USE_MODEDB,
@@ -12,7 +12,7 @@ can use the standard Linux video mode database. In your board file:
 	};
 
 If you have an embedded LCD display then you need to define a video
-mode for it as follows:
+mode for it as follows::
 
 	static struct fb_videomode some_board_video_modes[] = {
 		{
@@ -27,7 +27,7 @@ are in pixel clocks. See Documentation/fb/framebuffer.txt for further
 details.
 
 The ep93xxfb_mach_info structure for your board should look like the
-following:
+following::
 
 	static struct ep93xxfb_mach_info some_board_fb_info = {
 		.num_modes	= ARRAY_SIZE(some_board_video_modes),
@@ -37,7 +37,7 @@ following:
 	};
 
 The framebuffer device can be registered by adding the following to
-your board initialisation function:
+your board initialisation function::
 
 	ep93xx_register_fb(&some_board_fb_info);
 
@@ -50,6 +50,7 @@ to configure the controller. The video attributes flags are fully
 documented in section 7 of the EP93xx users' guide. The following
 flags are available:
 
+=============================== ==========================================
 EP93XXFB_PCLK_FALLING		Clock data on the falling edge of the
 				pixel clock. The default is to clock
 				data on the rising edge.
@@ -62,10 +63,12 @@ EP93XXFB_SYNC_HORIZ_HIGH	Horizontal sync is active high. By
 
 EP93XXFB_SYNC_VERT_HIGH		Vertical sync is active high. By
 				default the vertical sync is active high.
+=============================== ==========================================
 
 The physical address of the framebuffer can be controlled using the
 following flags:
 
+=============================== ======================================
 EP93XXFB_USE_SDCSN0		Use SDCSn[0] for the framebuffer. This
 				is the default setting.
 
@@ -74,6 +77,7 @@ EP93XXFB_USE_SDCSN1		Use SDCSn[1] for the framebuffer.
 EP93XXFB_USE_SDCSN2		Use SDCSn[2] for the framebuffer.
 
 EP93XXFB_USE_SDCSN3		Use SDCSn[3] for the framebuffer.
+=============================== ======================================
 
 ==================
 Platform callbacks
@@ -87,7 +91,7 @@ blanked or unblanked.
 
 The setup and teardown devices pass the platform_device structure as
 an argument. The fb_info and ep93xxfb_mach_info structures can be
-obtained as follows:
+obtained as follows::
 
 	static int some_board_fb_setup(struct platform_device *pdev)
 	{
@@ -101,17 +105,17 @@ obtained as follows:
 Setting the video mode
 ======================
 
-The video mode is set using the following syntax:
+The video mode is set using the following syntax::
 
 	video=XRESxYRES[-BPP][@REFRESH]
 
 If the EP93xx video driver is built-in then the video mode is set on
-the Linux kernel command line, for example:
+the Linux kernel command line, for example::
 
 	video=ep93xx-fb:800x600-16@60
 
 If the EP93xx video driver is built as a module then the video mode is
-set when the module is installed:
+set when the module is installed::
 
 	modprobe ep93xx-fb video=320x240
 
@@ -121,13 +125,14 @@ Screenpage bug
 
 At least on the EP9315 there is a silicon bug which causes bit 27 of
 the VIDSCRNPAGE (framebuffer physical offset) to be tied low. There is
-an unofficial errata for this bug at:
+an unofficial errata for this bug at::
+
 	http://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2
 
 By default the EP93xx framebuffer driver checks if the allocated physical
 address has bit 27 set. If it does, then the memory is freed and an
 error is returned. The check can be disabled by adding the following
-option when loading the driver:
+option when loading the driver::
 
       ep93xx-fb.check_screenpage_bug=0
 
Documentation/fb/fbcon.txt +90 -87

326 lines not on this page · raw message

Documentation/fb/framebuffer.txt +45 -34

202 lines not on this page · raw message

Documentation/fb/gxfb.txt +12 -10
index 2f640903bbb2..eecbb4026ccb 100644
@@ -1,7 +1,8 @@
-[This file is cloned from VesaFB/aty128fb]
-
+=============
 What is gxfb?
-=================
+=============
+
+.. [This file is cloned from VesaFB/aty128fb]
 
 This is a graphics framebuffer driver for AMD Geode GX2 based processors.
 
@@ -23,7 +24,7 @@ How to use it?
 ==============
 
 Switching modes is done using  gxfb.mode_option=<resolution>... boot
-parameter or using `fbset' program.
+parameter or using `fbset` program.
 
 See Documentation/fb/modedb.txt for more information on modedb
 resolutions.
@@ -42,11 +43,12 @@ You can pass kernel command line options to gxfb with gxfb.<option>.
 For example, gxfb.mode_option=800x600@75.
 Accepted options:
 
-mode_option	- specify the video mode.  Of the form
-		  <x>x<y>[-<bpp>][@<refresh>]
-vram		- size of video ram (normally auto-detected)
-vt_switch	- enable vt switching during suspend/resume.  The vt
-		  switch is slow, but harmless.
+================ ==================================================
+mode_option	 specify the video mode.  Of the form
+		 <x>x<y>[-<bpp>][@<refresh>]
+vram		 size of video ram (normally auto-detected)
+vt_switch	 enable vt switching during suspend/resume.  The vt
+		 switch is slow, but harmless.
+================ ==================================================
 
---
 Andres Salomon <[email protected]>
Documentation/fb/intel810.txt +43 -34

172 lines not on this page · raw message

Documentation/fb/intelfb.txt +34 -28

124 lines not on this page · raw message

Documentation/fb/internals.txt +14 -10
index 9b2a2b2f3e57..696b50aa7c24 100644
@@ -1,13 +1,19 @@
+=============================
+Frame Buffer device internals
+=============================
 
 This is a first start for some documentation about frame buffer device
 internals.
 
-Geert Uytterhoeven <[email protected]>, 21 July 1998
-James Simmons <[email protected]>, Nov 26 2002
+Authors:
+
+- Geert Uytterhoeven <[email protected]>, 21 July 1998
+- James Simmons <[email protected]>, Nov 26 2002
 
 --------------------------------------------------------------------------------
 
-	    ***  STRUCTURES USED BY THE FRAME BUFFER DEVICE API  ***
+Structures used by the frame buffer device API
+==============================================
 
 The following structures play a role in the game of frame buffer devices. They
 are defined in <linux/fb.h>.
@@ -40,19 +46,18 @@ are defined in <linux/fb.h>.
     Generic information, API and low level information about a specific frame
     buffer device instance (slot number, board address, ...).
 
-  - struct `par'
+  - struct `par`
 
     Device dependent information that uniquely defines the video mode for this
     particular piece of hardware.
 
 
---------------------------------------------------------------------------------
-
-	    ***  VISUALS USED BY THE FRAME BUFFER DEVICE API  ***
+Visuals used by the frame buffer device API
+===========================================
 
 
 Monochrome (FB_VISUAL_MONO01 and FB_VISUAL_MONO10)
--------------------------------------------------
+--------------------------------------------------
 Each pixel is either black or white.
 
 
@@ -70,7 +75,7 @@ The pixel value is broken up into red, green, and blue fields.
 
 Direct color (FB_VISUAL_DIRECTCOLOR)
 ------------------------------------
-The pixel value is broken up into red, green, and blue fields, each of which 
+The pixel value is broken up into red, green, and blue fields, each of which
 are looked up in separate red, green, and blue lookup tables.
 
 
@@ -79,4 +84,3 @@ Grayscale displays
 Grayscale and static grayscale are special variants of pseudo color and static
 pseudo color, where the red, green and blue components are always equal to
 each other.
-
Documentation/fb/lxfb.txt +13 -10
index 38b3ca6f6ca7..796172f261cb 100644
@@ -1,7 +1,9 @@
-[This file is cloned from VesaFB/aty128fb]
-
+=============
 What is lxfb?
-=================
+=============
+
+.. [This file is cloned from VesaFB/aty128fb]
+
 
 This is a graphics framebuffer driver for AMD Geode LX based processors.
 
@@ -23,7 +25,7 @@ How to use it?
 ==============
 
 Switching modes is done using  lxfb.mode_option=<resolution>... boot
-parameter or using `fbset' program.
+parameter or using `fbset` program.
 
 See Documentation/fb/modedb.txt for more information on modedb
 resolutions.
@@ -42,11 +44,12 @@ You can pass kernel command line options to lxfb with lxfb.<option>.
 For example, lxfb.mode_option=800x600@75.
 Accepted options:
 
-mode_option	- specify the video mode.  Of the form
-		  <x>x<y>[-<bpp>][@<refresh>]
-vram		- size of video ram (normally auto-detected)
-vt_switch	- enable vt switching during suspend/resume.  The vt
-		  switch is slow, but harmless.
+================ ==================================================
+mode_option	 specify the video mode.  Of the form
+		 <x>x<y>[-<bpp>][@<refresh>]
+vram		 size of video ram (normally auto-detected)
+vt_switch	 enable vt switching during suspend/resume.  The vt
+		 switch is slow, but harmless.
+================ ==================================================
 
---
 Andres Salomon <[email protected]>
Documentation/fb/matroxfb.txt +278 -248

631 lines not on this page · raw message

Documentation/fb/metronomefb.txt +5 -3
index 237ca412582d..63e1d31a7e54 100644
@@ -1,6 +1,9 @@
-			Metronomefb
-			-----------
+===========
+Metronomefb
+===========
+
 Maintained by Jaya Kumar <jayakumar.lkml.gmail.com>
+
 Last revised: Mar 10, 2008
 
 Metronomefb is a driver for the Metronome display controller. The controller
@@ -33,4 +36,3 @@ the physical media.
 Metronomefb uses the deferred IO interface so that it can provide a memory
 mappable frame buffer. It has been tested with tinyx (Xfbdev). It is known
 to work at this time with xeyes, xclock, xloadimage, xpdf.
-
Documentation/fb/modedb.txt +24 -20

93 lines not on this page · raw message

Documentation/fb/pvr2fb.txt +28 -27

77 lines not on this page · raw message

Documentation/fb/pxafb.txt +56 -25

178 lines not on this page · raw message

Documentation/fb/s3fb.txt +4 -4
index 2c97770bdbaa..e809d69c21a7 100644
@@ -1,6 +1,6 @@
-
-	s3fb - fbdev driver for S3 Trio/Virge chips
-	===========================================
+===========================================
+s3fb - fbdev driver for S3 Trio/Virge chips
+===========================================
 
 
 Supported Hardware
@@ -56,7 +56,7 @@ Missing Features
 (alias TODO list)
 
 	* secondary (not initialized by BIOS) device support
-   	* big endian support
+	* big endian support
 	* Zorro bus support
 	* MMIO support
 	* 24 bpp mode support on more cards
Documentation/fb/sa1100fb.txt +12 -11
index f1b4220464df..67e2650e017d 100644
@@ -1,17 +1,19 @@
-[This file is cloned from VesaFB/matroxfb]
-
+=================
 What is sa1100fb?
 =================
 
+.. [This file is cloned from VesaFB/matroxfb]
+
+
 This is a driver for a graphic framebuffer for the SA-1100 LCD
 controller.
 
 Configuration
 ==============
 
-For most common passive displays, giving the option
+For most common passive displays, giving the option::
 
-video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value>
+  video=sa1100fb:bpp:<value>,lccr0:<value>,lccr1:<value>,lccr2:<value>,lccr3:<value>
 
 on the kernel command line should be enough to configure the
 controller. The bits per pixel (bpp) value should be 4, 8, 12, or
@@ -27,13 +29,12 @@ sa1100fb_init_fbinfo(), sa1100fb_activate_var(),
 sa1100fb_disable_lcd_controller(), and sa1100fb_enable_lcd_controller()
 will probably be necessary.
 
-Accepted options:
+Accepted options::
 
-bpp:<value>	Configure for <value> bits per pixel
-lccr0:<value>	Configure LCD control register 0 (11.7.3)
-lccr1:<value>	Configure LCD control register 1 (11.7.4)
-lccr2:<value>	Configure LCD control register 2 (11.7.5)
-lccr3:<value>	Configure LCD control register 3 (11.7.6)
+	bpp:<value>	Configure for <value> bits per pixel
+	lccr0:<value>	Configure LCD control register 0 (11.7.3)
+	lccr1:<value>	Configure LCD control register 1 (11.7.4)
+	lccr2:<value>	Configure LCD control register 2 (11.7.5)
+	lccr3:<value>	Configure LCD control register 3 (11.7.6)
 
---
 Mark Huang <[email protected]>
Documentation/fb/sh7760fb.txt +76 -77

176 lines not on this page · raw message

Documentation/fb/sisfb.txt +21 -19
index 2e68e503e72f..8f4e502ea12e 100644
@@ -1,4 +1,4 @@
-
+==============
 What is sisfb?
 ==============
 
@@ -41,11 +41,11 @@ statement to add the parameters to the kernel command line. Please see lilo's
 parameters are given with the modprobe (or insmod) command.
 
 Example for sisfb as part of the static kernel: Add the following line to your
-lilo.conf:
+lilo.conf::
 
      append="video=sisfb:mode:1024x768x16,mem:12288,rate:75"
 
-Example for sisfb as a module: Start sisfb by typing
+Example for sisfb as a module: Start sisfb by typing::
 
      modprobe sisfb mode=1024x768x16 rate=75 mem=12288
 
@@ -57,7 +57,7 @@ described above or the vesa keyword instead of mode). If compiled as a module,
 the parameter format reads mode=none or mode=1024x768x16 (or whatever mode you
 want to use). Using a "=" for a ":" (and vice versa) is a huge difference!
 Additionally: If you give more than one argument to the in-kernel sisfb, the
-arguments are separated with ",". For example:
+arguments are separated with ",". For example::
 
    video=sisfb:mode:1024x768x16,rate:75,mem:12288
 
@@ -73,6 +73,7 @@ supported options including some explanation.
 
 The desired display mode can be specified using the keyword "mode" with
 a parameter in one of the following formats:
+
   - XxYxDepth or
   - XxY-Depth or
   - XxY-Depth@Rate or
@@ -130,29 +131,30 @@ Configuration
 
 (Some) accepted options:
 
-off      - Disable sisfb. This option is only understood if sisfb is
-           in-kernel, not a module.
-mem:X    - size of memory for the console, rest will be used for DRI/DRM. X
-           is in kilobytes. On 300 series, the default is 4096, 8192 or
+=========  ==================================================================
+off        Disable sisfb. This option is only understood if sisfb is
+	   in-kernel, not a module.
+mem:X      size of memory for the console, rest will be used for DRI/DRM. X
+	   is in kilobytes. On 300 series, the default is 4096, 8192 or
 	   16384 (each in kilobyte) depending on how much video ram the card
-           has. On 315/330 series, the default is the maximum available ram
+	   has. On 315/330 series, the default is the maximum available ram
 	   (since DRI/DRM is not supported for these chipsets).
-noaccel  - do not use 2D acceleration engine. (Default: use acceleration)
-noypan   - disable y-panning and scroll by redrawing the entire screen.
-           This is much slower than y-panning. (Default: use y-panning)
-vesa:X   - selects startup videomode. X is number from 0 to 0x1FF and
-           represents the VESA mode number (can be given in decimal or
+noaccel    do not use 2D acceleration engine. (Default: use acceleration)
+noypan     disable y-panning and scroll by redrawing the entire screen.
+	   This is much slower than y-panning. (Default: use y-panning)
+vesa:X     selects startup videomode. X is number from 0 to 0x1FF and
+	   represents the VESA mode number (can be given in decimal or
 	   hexadecimal form, the latter prefixed with "0x").
-mode:X   - selects startup videomode. Please see above for the format of
-           "X".
+mode:X     selects startup videomode. Please see above for the format of
+	   "X".
+=========  ==================================================================
 
 Boolean options such as "noaccel" or "noypan" are to be given without a
 parameter if sisfb is in-kernel (for example "video=sisfb:noypan). If
 sisfb is a module, these are to be set to 1 (for example "modprobe sisfb
 noypan=1").
 
---
+
 Thomas Winischhofer <[email protected]>
+
 May 27, 2004
-
-
Documentation/fb/sm501.txt +6 -1
index 187f3b3ccb6c..03e02c8042a7 100644
@@ -1,6 +1,11 @@
+=======
+sm501fb
+=======
+
 Configuration:
 
-You can pass the following kernel command line options to sm501 videoframebuffer:
+You can pass the following kernel command line options to sm501
+videoframebuffer::
 
 	sm501fb.bpp=	SM501 Display driver:
 			Specify bits-per-pixel if not specified by 'mode'
Documentation/fb/sm712fb.txt +11 -7
index c388442edf51..994dad3b0238 100644
@@ -1,5 +1,6 @@
+================
 What is sm712fb?
-=================
+================
 
 This is a graphics framebuffer driver for Silicon Motion SM712 based processors.
 
@@ -15,13 +16,16 @@ You should not compile-in vesafb.
 
 Currently supported video modes are:
 
-[Graphic modes]
+Graphic modes
+-------------
 
-bpp | 640x480  800x600  1024x768  1280x1024
-----+--------------------------------------------
-  8 | 0x301    0x303    0x305    0x307
- 16 | 0x311    0x314    0x317    0x31A
- 24 | 0x312    0x315    0x318    0x31B
+===  =======  =======  ========  =========
+bpp  640x480  800x600  1024x768  1280x1024
+===  =======  =======  ========  =========
+  8  0x301    0x303    0x305     0x307
+ 16  0x311    0x314    0x317     0x31A
+ 24  0x312    0x315    0x318     0x31B
+===  =======  =======  ========  =========
 
 Missing Features
 ================
Documentation/fb/sstfb.txt +132 -99

189 lines not on this page · raw message

Documentation/fb/tgafb.txt +16 -14
index 250083ada8fb..0c50d2134aa4 100644

Lines of this file are not shown. View the raw message.

Documentation/fb/tridentfb.txt +21 -13
index 45d9de5b13a3..d651157f7486 100644

Lines of this file are not shown. View the raw message.

Documentation/fb/udlfb.txt +29 -26

55 lines not on this page · raw message

Documentation/fb/uvesafb.txt +66 -62

128 lines not on this page · raw message

Documentation/fb/vesafb.txt +66 -55

121 lines not on this page · raw message

Documentation/fb/viafb.txt +219 -174

393 lines not on this page · raw message

Documentation/fb/vt8623fb.txt +5 -5
index f654576c56b7..ba1730937dd8 100644

Lines of this file are not shown. View the raw message.

The rest of this diff is not shown. View the raw message.

Signature · 6 lines
2.20.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Part of the diff is not shown here. View the raw message.

Acked-by on v1 13/57
#27 lore raw

Re: [PATCH 13/57] docs: fb: convert documentation to ReST format

Quoted 5 lines · Mauro Carvalho Chehab

Convert all documents here from plain txt to ReST format, in order to allow parsing them with the documentation build system.

Best regards,
--
Bartlomiej Zolnierkiewicz
Samsung R&D Institute Poland
Samsung Electronics

#28 lore raw

PATCH 14/57 docs: fpga: convert it to ReST

In reply to Mauro Carvalho Chehab

The dfl.txt file is almost there. It needs just a few adjustments to be properly parsed.

---
 Documentation/fpga/dfl.txt | 58 +++++++++++++++++++++-----------------
 1 file changed, 32 insertions(+), 26 deletions(-)
Documentation/fpga/dfl.txt +32 -26
index 6df4621c3f2a..2f125abd777f 100644
@@ -1,9 +1,12 @@
-===============================================================================
-              FPGA Device Feature List (DFL) Framework Overview
--------------------------------------------------------------------------------
-                Enno Luebbers <[email protected]>
-                Xiao Guangrong <[email protected]>
-                Wu Hao <[email protected]>
+=================================================
+FPGA Device Feature List (DFL) Framework Overview
+=================================================
+
+Authors:
+
+- Enno Luebbers <[email protected]>
+- Xiao Guangrong <[email protected]>
+- Wu Hao <[email protected]>
 
 The Device Feature List (DFL) FPGA framework (and drivers according to this
 this framework) hides the very details of low layer hardwares and provides
@@ -19,7 +22,7 @@ Device Feature List (DFL) defines a linked list of feature headers within the
 device MMIO space to provide an extensible way of adding features. Software can
 walk through these predefined data structures to enumerate FPGA features:
 FPGA Interface Unit (FIU), Accelerated Function Unit (AFU) and Private Features,
-as illustrated below:
+as illustrated below::
 
     Header            Header            Header            Header
  +----------+  +-->+----------+  +-->+----------+  +-->+----------+
@@ -81,9 +84,9 @@ and release it using close().
 
 The following functions are exposed through ioctls:
 
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Program bitstream (DFL_FPGA_FME_PORT_PR)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Program bitstream (DFL_FPGA_FME_PORT_PR)
 
 More functions are exposed through sysfs
 (/sys/class/fpga_region/regionX/dfl-fme.n/):
@@ -118,18 +121,19 @@ port by using open() on the port device node and release it using close().
 
 The following functions are exposed through ioctls:
 
- Get driver API version (DFL_FPGA_GET_API_VERSION)
- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
- Get port info (DFL_FPGA_PORT_GET_INFO)
- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
- Reset AFU (*DFL_FPGA_PORT_RESET)
+- Get driver API version (DFL_FPGA_GET_API_VERSION)
+- Check for extensions (DFL_FPGA_CHECK_EXTENSION)
+- Get port info (DFL_FPGA_PORT_GET_INFO)
+- Get MMIO region info (DFL_FPGA_PORT_GET_REGION_INFO)
+- Map DMA buffer (DFL_FPGA_PORT_DMA_MAP)
+- Unmap DMA buffer (DFL_FPGA_PORT_DMA_UNMAP)
+- Reset AFU (DFL_FPGA_PORT_RESET)
 
-*DFL_FPGA_PORT_RESET: reset the FPGA Port and its AFU. Userspace can do Port
-reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
-never cause any system level issue, only functional failure (e.g. DMA or PR
-operation failure) and be recoverable from the failure.
+DFL_FPGA_PORT_RESET:
+  reset the FPGA Port and its AFU. Userspace can do Port
+  reset at any time, e.g. during DMA or Partial Reconfiguration. But it should
+  never cause any system level issue, only functional failure (e.g. DMA or PR
+  operation failure) and be recoverable from the failure.
 
 User-space applications can also mmap() accelerator MMIO regions.
 
@@ -143,6 +147,8 @@ More functions are exposed through sysfs:
 DFL Framework Overview
 ======================
 
+::
+
          +----------+    +--------+ +--------+ +--------+
          |   FME    |    |  AFU   | |  AFU   | |  AFU   |
          |  Module  |    | Module | | Module | | Module |
@@ -151,7 +157,7 @@ DFL Framework Overview
                  | FPGA Container Device |    Device Feature List
                  |  (FPGA Base Region)   |         Framework
                  +-----------------------+
---------------------------------------------------------------------
+  ------------------------------------------------------------------
                +----------------------------+
                |   FPGA DFL Device Module   |
                | (e.g. PCIE/Platform Device)|
@@ -220,7 +226,7 @@ the sysfs hierarchy under /sys/class/fpga_region.
 In the example below, two DFL based FPGA devices are installed in the host. Each
 fpga device has one FME and two ports (AFUs).
 
-FPGA regions are created under /sys/class/fpga_region/
+FPGA regions are created under /sys/class/fpga_region/::
 
 	/sys/class/fpga_region/region0
 	/sys/class/fpga_region/region1
@@ -231,7 +237,7 @@ Application needs to search each regionX folder, if feature device is found,
 (e.g. "dfl-port.n" or "dfl-fme.m" is found), then it's the base
 fpga region which represents the FPGA device.
 
-Each base region has one FME and two ports (AFUs) as child devices:
+Each base region has one FME and two ports (AFUs) as child devices::
 
 	/sys/class/fpga_region/region0/dfl-fme.0
 	/sys/class/fpga_region/region0/dfl-port.0
@@ -243,7 +249,7 @@ Each base region has one FME and two ports (AFUs) as child devices:
 	/sys/class/fpga_region/region3/dfl-port.3
 	...
 
-In general, the FME/AFU sysfs interfaces are named as follows:
+In general, the FME/AFU sysfs interfaces are named as follows::
 
 	/sys/class/fpga_region/<regionX>/<dfl-fme.n>/
 	/sys/class/fpga_region/<regionX>/<dfl-port.m>/
@@ -251,7 +257,7 @@ In general, the FME/AFU sysfs interfaces are named as follows:
 with 'n' consecutively numbering all FMEs and 'm' consecutively numbering all
 ports.
 
-The device nodes used for ioctl() or mmap() can be referenced through:
+The device nodes used for ioctl() or mmap() can be referenced through::
 
 	/sys/class/fpga_region/<regionX>/<dfl-fme.n>/dev
 	/sys/class/fpga_region/<regionX>/<dfl-port.n>/dev
Signature · 1 line
2.20.1
#29 lore raw

PATCH 15/57 docs: gpio: convert it to ReST

In reply to Mauro Carvalho Chehab

The API described at sysfs.txt is deprecated.

Still, as it is still part of the Kernel (and will likely be there for some time, as we don't simply remove APIs). So, it makes sense to keep it there.

The conversion of this file is trivial.

---
 Documentation/gpio/sysfs.txt | 39 +++++++++++++++++++++++-------------
 1 file changed, 25 insertions(+), 14 deletions(-)
Documentation/gpio/sysfs.txt +25 -14
index 58eeab81f349..ec09ffd983e7 100644
@@ -1,10 +1,12 @@
 GPIO Sysfs Interface for Userspace
 ==================================
 
-THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
-Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
-ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
-NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
+.. warning::
+
+  THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
+  Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
+  ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
+  NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
 
 Refer to the examples in tools/gpio/* for an introduction to the new
 character device ABI. Also see the userspace header in
@@ -51,13 +53,15 @@ The control interfaces are write-only:
 
     /sys/class/gpio/
 
-    	"export" ... Userspace may ask the kernel to export control of
+	"export" ...
+		Userspace may ask the kernel to export control of
 		a GPIO to userspace by writing its number to this file.
 
 		Example:  "echo 19 > export" will create a "gpio19" node
 		for GPIO #19, if that's not requested by kernel code.
 
-    	"unexport" ... Reverses the effect of exporting to userspace.
+	"unexport" ...
+		Reverses the effect of exporting to userspace.
 
 		Example:  "echo 19 > unexport" will remove a "gpio19"
 		node exported using the "export" file.
@@ -67,7 +71,8 @@ and have the following read/write attributes:
 
     /sys/class/gpio/gpioN/
 
-	"direction" ... reads as either "in" or "out". This value may
+	"direction" ...
+		reads as either "in" or "out". This value may
 		normally be written. Writing as "out" defaults to
 		initializing the value as low. To ensure glitch free
 		operation, values "low" and "high" may be written to
@@ -78,7 +83,8 @@ and have the following read/write attributes:
 		it was exported by kernel code that didn't explicitly
 		allow userspace to reconfigure this GPIO's direction.
 
-	"value" ... reads as either 0 (low) or 1 (high). If the GPIO
+	"value" ...
+		reads as either 0 (low) or 1 (high). If the GPIO
 		is configured as an output, this value may be written;
 		any nonzero value is treated as high.
 
@@ -92,14 +98,16 @@ and have the following read/write attributes:
 		file and read the new value or close the file and re-open it
 		to read the value.
 
-	"edge" ... reads as either "none", "rising", "falling", or
+	"edge" ...
+		reads as either "none", "rising", "falling", or
 		"both". Write these strings to select the signal edge(s)
 		that will make poll(2) on the "value" file return.
 
 		This file exists only if the pin can be configured as an
 		interrupt generating input pin.
 
-	"active_low" ... reads as either 0 (false) or 1 (true). Write
+	"active_low" ...
+		reads as either 0 (false) or 1 (true). Write
 		any nonzero value to invert the value attribute both
 		for reading and writing. Existing and subsequent
 		poll(2) support configuration via the edge attribute
@@ -112,11 +120,14 @@ read-only attributes:
 
     /sys/class/gpio/gpiochipN/
 
-    	"base" ... same as N, the first GPIO managed by this chip
+	"base" ...
+		same as N, the first GPIO managed by this chip
 
-    	"label" ... provided for diagnostics (not always unique)
+	"label" ...
+		provided for diagnostics (not always unique)
 
-        "ngpio" ... how many GPIOs this manages (N to N + ngpio - 1)
+	"ngpio" ...
+		how many GPIOs this manages (N to N + ngpio - 1)
 
 Board documentation should in most cases cover what GPIOs are used for
 what purposes. However, those numbers are not always stable; GPIOs on
@@ -129,7 +140,7 @@ the correct GPIO number to use for a given signal.
 Exporting from Kernel code
 --------------------------
 Kernel code can explicitly manage exports of GPIOs which have already been
-requested using gpio_request():
+requested using gpio_request()::
 
 	/* export the GPIO to userspace */
 	int gpiod_export(struct gpio_desc *desc, bool direction_may_change);
Signature · 1 line
2.20.1
Acked-by on v1 15/57
#30 lore raw

Re: [PATCH 15/57] docs: gpio: convert it to ReST

Quoted 9 lines · Mauro Carvalho Chehab

The API described at sysfs.txt is deprecated.

Still, as it is still part of the Kernel (and will likely be there for some time, as we don't simply remove APIs). So, it makes sense to keep it there.

The conversion of this file is trivial.

Mauro will you merge this or do you want me to merge it?

Yours,
Linus Walleij

#31 lore raw

Re: [PATCH 15/57] docs: gpio: convert it to ReST

Em Tue, 23 Apr 2019 12:52:04 +0200
Linus Walleij <[email protected]> escreveu:

Quoted 9 lines
Quoted 6 lines · Mauro Carvalho Chehab

The API described at sysfs.txt is deprecated.

Still, as it is still part of the Kernel (and will likely be there for some time, as we don't simply remove APIs). So, it makes sense to keep it there.

Quoted 7 lines
Quoted 3 lines

The conversion of this file is trivial.

Mauro will you merge this or do you want me to merge it?

Linus,

Just answered on the other e-mail: better to merge via your tree. Just notice that this version was superseded by

[PATCH v2 15/79] docs: gpio: convert docs to ReST and rename to *.rst

As it also does the rename to .rst.

Thanks,
Mauro

#32 lore raw

PATCH 16/57 docs: ide: convert it to ReST format

In reply to Mauro Carvalho Chehab

Convert the IDE documentation to ReST format, in order to prepare for its addition inside a book.

---
 Documentation/ide/ide-tape.txt        |  23 ++--
 Documentation/ide/ide.txt             | 147 ++++++++++++++------------
 Documentation/ide/warm-plug-howto.txt |  10 +-
 3 files changed, 96 insertions(+), 84 deletions(-)
Documentation/ide/ide-tape.txt +13 -10
index 3f348a0b21d8..3e061d9c0e38 100644
@@ -1,4 +1,6 @@
-IDE ATAPI streaming tape driver.
+===============================
+IDE ATAPI streaming tape driver
+===============================
 
 This driver is a part of the Linux ide driver.
 
@@ -10,14 +12,14 @@ to the request-list of the block device, and waits for their completion.
 The block device major and minor numbers are determined from the
 tape's relative position in the ide interfaces, as explained in ide.c.
 
-The character device interface consists of the following devices:
+The character device interface consists of the following devices::
 
-ht0		major 37, minor 0	first  IDE tape, rewind on close.
-ht1		major 37, minor 1	second IDE tape, rewind on close.
-...
-nht0		major 37, minor 128	first  IDE tape, no rewind on close.
-nht1		major 37, minor 129	second IDE tape, no rewind on close.
-...
+  ht0		major 37, minor 0	first  IDE tape, rewind on close.
+  ht1		major 37, minor 1	second IDE tape, rewind on close.
+  ...
+  nht0		major 37, minor 128	first  IDE tape, no rewind on close.
+  nht1		major 37, minor 129	second IDE tape, no rewind on close.
+  ...
 
 The general magnetic tape commands compatible interface, as defined by
 include/linux/mtio.h, is accessible through the character device.
@@ -40,9 +42,10 @@ Testing was done with a 2 GB CONNER CTMA 4000 IDE ATAPI Streaming Tape Drive.
 Here are some words from the first releases of hd.c, which are quoted
 in ide.c and apply here as well:
 
-| Special care is recommended.  Have Fun!
+* Special care is recommended.  Have Fun!
 
-Possible improvements:
+Possible improvements
+=====================
 
 1. Support for the ATAPI overlap protocol.
 
Documentation/ide/ide.txt +78 -69

227 lines not on this page · raw message

Documentation/ide/warm-plug-howto.txt +5 -5
index 98152bcd515a..c245242ef2f1 100644
@@ -1,14 +1,14 @@
-
+===================
 IDE warm-plug HOWTO
 ===================
 
-To warm-plug devices on a port 'idex':
+To warm-plug devices on a port 'idex'::
 
-# echo -n "1" > /sys/class/ide_port/idex/delete_devices
+	# echo -n "1" > /sys/class/ide_port/idex/delete_devices
 
-unplug old device(s) and plug new device(s)
+unplug old device(s) and plug new device(s)::
 
-# echo -n "1" > /sys/class/ide_port/idex/scan
+	# echo -n "1" > /sys/class/ide_port/idex/scan
 
 done
 
Signature · 1 line
2.20.1
#33 lore raw

PATCH 17/57 docs: infiniband: convert it to ReST format

In reply to Mauro Carvalho Chehab

The InfiniBand docs are plain text with no markups. So, all we needed to do were to add the title markups and some markup sequences in order to properly parse tables, lists and literal blocks.

---
 Documentation/infiniband/core_locking.txt |  64 +++++++------
 Documentation/infiniband/ipoib.txt        |  24 +++--
 Documentation/infiniband/opa_vnic.txt     | 108 ++++++++++++----------
 Documentation/infiniband/sysfs.txt        |   4 +-
 Documentation/infiniband/tag_matching.txt |   5 +
 Documentation/infiniband/user_mad.txt     |  33 +++++--
 Documentation/infiniband/user_verbs.txt   |  12 ++-
 7 files changed, 149 insertions(+), 101 deletions(-)
Documentation/infiniband/core_locking.txt +35 -29
index 4b1f36b6ada0..f34669beb4fe 100644
@@ -1,4 +1,6 @@
-INFINIBAND MIDLAYER LOCKING
+===========================
+InfiniBand Midlayer Locking
+===========================
 
   This guide is an attempt to make explicit the locking assumptions
   made by the InfiniBand midlayer.  It describes the requirements on
@@ -6,45 +8,47 @@ INFINIBAND MIDLAYER LOCKING
   protocols that use the midlayer.
 
 Sleeping and interrupt context
+==============================
 
   With the following exceptions, a low-level driver implementation of
   all of the methods in struct ib_device may sleep.  The exceptions
   are any methods from the list:
 
-    create_ah
-    modify_ah
-    query_ah
-    destroy_ah
-    post_send
-    post_recv
-    poll_cq
-    req_notify_cq
-    map_phys_fmr
+    - create_ah
+    - modify_ah
+    - query_ah
+    - destroy_ah
+    - post_send
+    - post_recv
+    - poll_cq
+    - req_notify_cq
+    - map_phys_fmr
 
   which may not sleep and must be callable from any context.
 
   The corresponding functions exported to upper level protocol
   consumers:
 
-    ib_create_ah
-    ib_modify_ah
-    ib_query_ah
-    ib_destroy_ah
-    ib_post_send
-    ib_post_recv
-    ib_req_notify_cq
-    ib_map_phys_fmr
+    - ib_create_ah
+    - ib_modify_ah
+    - ib_query_ah
+    - ib_destroy_ah
+    - ib_post_send
+    - ib_post_recv
+    - ib_req_notify_cq
+    - ib_map_phys_fmr
 
   are therefore safe to call from any context.
 
   In addition, the function
 
-    ib_dispatch_event
+    - ib_dispatch_event
 
   used by low-level drivers to dispatch asynchronous events through
   the midlayer is also safe to call from any context.
 
 Reentrancy
+----------
 
   All of the methods in struct ib_device exported by a low-level
   driver must be fully reentrant.  The low-level driver is required to
@@ -62,6 +66,7 @@ Reentrancy
   information between different calls of ib_poll_cq() is not defined.
 
 Callbacks
+---------
 
   A low-level driver must not perform a callback directly from the
   same callchain as an ib_device method call.  For example, it is not
@@ -74,18 +79,18 @@ Callbacks
   completion event handlers for the same CQ are not called
   simultaneously.  The driver must guarantee that only one CQ event
   handler for a given CQ is running at a time.  In other words, the
-  following situation is not allowed:
+  following situation is not allowed::
 
-        CPU1                                    CPU2
+          CPU1                                    CPU2
 
-  low-level driver ->
-    consumer CQ event callback:
-      /* ... */
-      ib_req_notify_cq(cq, ...);
-                                        low-level driver ->
-      /* ... */                           consumer CQ event callback:
-                                            /* ... */
-      return from CQ event handler
+    low-level driver ->
+      consumer CQ event callback:
+        /* ... */
+        ib_req_notify_cq(cq, ...);
+                                          low-level driver ->
+        /* ... */                           consumer CQ event callback:
+                                              /* ... */
+        return from CQ event handler
 
   The context in which completion event and asynchronous event
   callbacks run is not defined.  Depending on the low-level driver, it
@@ -93,6 +98,7 @@ Callbacks
   Upper level protocol consumers may not sleep in a callback.
 
 Hot-plug
+--------
 
   A low-level driver announces that a device is ready for use by
   consumers when it calls ib_register_device(), all initialization
Documentation/infiniband/ipoib.txt +17 -7
index 47c1dd9818f2..0dd36154c0c9 100644
@@ -1,4 +1,6 @@
-IP OVER INFINIBAND
+==================
+IP over InfiniBand
+==================
 
   The ib_ipoib driver is an implementation of the IP over InfiniBand
   protocol as specified by RFC 4391 and 4392, issued by the IETF ipoib
@@ -8,16 +10,17 @@ IP OVER INFINIBAND
   masqueraded to the kernel as ethernet interfaces).
 
 Partitions and P_Keys
+=====================
 
   When the IPoIB driver is loaded, it creates one interface for each
   port using the P_Key at index 0.  To create an interface with a
   different P_Key, write the desired P_Key into the main interface's
-  /sys/class/net/<intf name>/create_child file.  For example:
+  /sys/class/net/<intf name>/create_child file.  For example::
 
     echo 0x8001 > /sys/class/net/ib0/create_child
 
   This will create an interface named ib0.8001 with P_Key 0x8001.  To
-  remove a subinterface, use the "delete_child" file:
+  remove a subinterface, use the "delete_child" file::
 
     echo 0x8001 > /sys/class/net/ib0/delete_child
 
@@ -28,6 +31,7 @@ Partitions and P_Keys
   rtnl_link_ops, where children created using either way behave the same.
 
 Datagram vs Connected modes
+===========================
 
   The IPoIB driver supports two modes of operation: datagram and
   connected.  The mode is set and read through an interface's
@@ -51,6 +55,7 @@ Datagram vs Connected modes
   networking stack to use the smaller UD MTU for these neighbours.
 
 Stateless offloads
+==================
 
   If the IB HW supports IPoIB stateless offloads, IPoIB advertises
   TCP/IP checksum and/or Large Send (LSO) offloading capability to the
@@ -60,9 +65,10 @@ Stateless offloads
   on/off using ethtool calls.  Currently LRO is supported only for
   checksum offload capable devices.
 
-  Stateless offloads are supported only in datagram mode.  
+  Stateless offloads are supported only in datagram mode.
 
 Interrupt moderation
+====================
 
   If the underlying IB device supports CQ event moderation, one can
   use ethtool to set interrupt mitigation parameters and thus reduce
@@ -71,6 +77,7 @@ Interrupt moderation
   moderation is supported.
 
 Debugging Information
+=====================
 
   By compiling the IPoIB driver with CONFIG_INFINIBAND_IPOIB_DEBUG set
   to 'y', tracing messages are compiled into the driver.  They are
@@ -79,7 +86,7 @@ Debugging Information
   runtime through files in /sys/module/ib_ipoib/.
 
   CONFIG_INFINIBAND_IPOIB_DEBUG also enables files in the debugfs
-  virtual filesystem.  By mounting this filesystem, for example with
+  virtual filesystem.  By mounting this filesystem, for example with::
 
     mount -t debugfs none /sys/kernel/debug
 
@@ -96,10 +103,13 @@ Debugging Information
   performance, because it adds tests to the fast path.
 
 References
+==========
 
   Transmission of IP over InfiniBand (IPoIB) (RFC 4391)
-    http://ietf.org/rfc/rfc4391.txt 
+    http://ietf.org/rfc/rfc4391.txt
+
   IP over InfiniBand (IPoIB) Architecture (RFC 4392)
-    http://ietf.org/rfc/rfc4392.txt 
+    http://ietf.org/rfc/rfc4392.txt
+
   IP over InfiniBand: Connected Mode (RFC 4755)
     http://ietf.org/rfc/rfc4755.txt
Documentation/infiniband/opa_vnic.txt +57 -51

137 lines not on this page · raw message

Documentation/infiniband/sysfs.txt +3 -1
index 9fab5062f84b..f0abd6fa48f4 100644
@@ -1,4 +1,6 @@
-SYSFS FILES
+===========
+Sysfs files
+===========
 
 The sysfs interface has moved to
 Documentation/ABI/stable/sysfs-class-infiniband.
Documentation/infiniband/tag_matching.txt +5 -0
index d2a3bf819226..ef56ea585f92 100644
@@ -1,12 +1,16 @@
+==================
 Tag matching logic
+==================
 
 The MPI standard defines a set of rules, known as tag-matching, for matching
 source send operations to destination receives.  The following parameters must
 match the following source and destination parameters:
+
 *	Communicator
 *	User tag - wild card may be specified by the receiver
 *	Source rank – wild car may be specified by the receiver
 *	Destination rank – wild
+
 The ordering rules require that when more than one pair of send and receive
 message envelopes may match, the pair that includes the earliest posted-send
 and the earliest posted-receive is the pair that must be used to satisfy the
@@ -35,6 +39,7 @@ the header to initiate an RDMA READ operation directly to the matching buffer.
 A fin message needs to be received in order for the buffer to be reused.
 
 Tag matching implementation
+===========================
 
 There are two types of matching objects used, the posted receive list and the
 unexpected message list. The application posts receive buffers through calls
Documentation/infiniband/user_mad.txt +23 -10
index 7aca13a54a3a..d88abfc0e370 100644
@@ -1,6 +1,9 @@
-USERSPACE MAD ACCESS
+====================
+Userspace MAD access
+====================
 
 Device files
+============
 
   Each port of each InfiniBand device has a "umad" device and an
   "issm" device attached.  For example, a two-port HCA will have two
@@ -8,12 +11,13 @@ Device files
   device of each type (for switch port 0).
 
 Creating MAD agents
+===================
 
   A MAD agent can be created by filling in a struct ib_user_mad_reg_req
   and then calling the IB_USER_MAD_REGISTER_AGENT ioctl on a file
   descriptor for the appropriate device file.  If the registration
   request succeeds, a 32-bit id will be returned in the structure.
-  For example:
+  For example::
 
 	struct ib_user_mad_reg_req req = { /* ... */ };
 	ret = ioctl(fd, IB_USER_MAD_REGISTER_AGENT, (char *) &req);
@@ -26,12 +30,14 @@ Creating MAD agents
   ioctl.  Also, all agents registered through a file descriptor will
   be unregistered when the descriptor is closed.
 
-  2014 -- a new registration ioctl is now provided which allows additional
+  2014
+       a new registration ioctl is now provided which allows additional
        fields to be provided during registration.
        Users of this registration call are implicitly setting the use of
        pkey_index (see below).
 
 Receiving MADs
+==============
 
   MADs are received using read().  The receive side now supports
   RMPP. The buffer passed to read() must be at least one
@@ -41,7 +47,8 @@ Receiving MADs
   MAD (RMPP), the errno is set to ENOSPC and the length of the
   buffer needed is set in mad.length.
 
-  Example for normal MAD (non RMPP) reads:
+  Example for normal MAD (non RMPP) reads::
+
 	struct ib_user_mad *mad;
 	mad = malloc(sizeof *mad + 256);
 	ret = read(fd, mad, sizeof *mad + 256);
@@ -50,7 +57,8 @@ Receiving MADs
 		free(mad);
 	}
 
-  Example for RMPP reads:
+  Example for RMPP reads::
+
 	struct ib_user_mad *mad;
 	mad = malloc(sizeof *mad + 256);
 	ret = read(fd, mad, sizeof *mad + 256);
@@ -76,11 +84,12 @@ Receiving MADs
   poll()/select() may be used to wait until a MAD can be read.
 
 Sending MADs
+============
 
   MADs are sent using write().  The agent ID for sending should be
   filled into the id field of the MAD, the destination LID should be
   filled into the lid field, and so on.  The send side does support
-  RMPP so arbitrary length MAD can be sent. For example:
+  RMPP so arbitrary length MAD can be sent. For example::
 
 	struct ib_user_mad *mad;
 
@@ -97,6 +106,7 @@ Sending MADs
 		perror("write");
 
 Transaction IDs
+===============
 
   Users of the umad devices can use the lower 32 bits of the
   transaction ID field (that is, the least significant half of the
@@ -105,6 +115,7 @@ Transaction IDs
   the kernel and will be overwritten before a MAD is sent.
 
 P_Key Index Handling
+====================
 
   The old ib_umad interface did not allow setting the P_Key index for
   MADs that are sent and did not provide a way for obtaining the P_Key
@@ -119,6 +130,7 @@ P_Key Index Handling
   default, and the IB_USER_MAD_ENABLE_PKEY ioctl will be removed.
 
 Setting IsSM Capability Bit
+===========================
 
   To set the IsSM capability bit for a port, simply open the
   corresponding issm device file.  If the IsSM bit is already set,
@@ -129,25 +141,26 @@ Setting IsSM Capability Bit
   the issm file.
 
 /dev files
+==========
 
   To create the appropriate character device files automatically with
-  udev, a rule like
+  udev, a rule like::
 
     KERNEL=="umad*", NAME="infiniband/%k"
     KERNEL=="issm*", NAME="infiniband/%k"
 
-  can be used.  This will create device nodes named
+  can be used.  This will create device nodes named::
 
     /dev/infiniband/umad0
     /dev/infiniband/issm0
 
   for the first port, and so on.  The InfiniBand device and port
-  associated with these devices can be determined from the files
+  associated with these devices can be determined from the files::
 
     /sys/class/infiniband_mad/umad0/ibdev
     /sys/class/infiniband_mad/umad0/port
 
-  and
+  and::
 
     /sys/class/infiniband_mad/issm0/ibdev
     /sys/class/infiniband_mad/issm0/port
Documentation/infiniband/user_verbs.txt +9 -3
index 47ebf2f80b2b..8ddc4b1cfef2 100644
@@ -1,4 +1,6 @@
-USERSPACE VERBS ACCESS
+======================
+Userspace verbs access
+======================
 
   The ib_uverbs module, built by enabling CONFIG_INFINIBAND_USER_VERBS,
   enables direct userspace access to IB hardware via "verbs," as
@@ -13,6 +15,7 @@ USERSPACE VERBS ACCESS
   libmthca userspace driver be installed.
 
 User-kernel communication
+=========================
 
   Userspace communicates with the kernel for slow path, resource
   management operations via the /dev/infiniband/uverbsN character
@@ -28,6 +31,7 @@ User-kernel communication
   system call.
 
 Resource management
+===================
 
   Since creation and destruction of all IB resources is done by
   commands passed through a file descriptor, the kernel can keep track
@@ -41,6 +45,7 @@ Resource management
   prevent one process from touching another process's resources.
 
 Memory pinning
+==============
 
   Direct userspace I/O requires that memory regions that are potential
   I/O targets be kept resident at the same physical address.  The
@@ -54,13 +59,14 @@ Memory pinning
   number of pages pinned by a process.
 
 /dev files
+==========
 
   To create the appropriate character device files automatically with
-  udev, a rule like
+  udev, a rule like::
 
     KERNEL=="uverbs*", NAME="infiniband/%k"
 
-  can be used.  This will create device nodes named
+  can be used.  This will create device nodes named::
 
     /dev/infiniband/uverbs0
 
Signature · 1 line
2.20.1
#34 lore raw

PATCH 18/57 docs: kbuild: convert it to ReST output

In reply to Mauro Carvalho Chehab

The kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections.

Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups.

---
 Documentation/kbuild/headers_install.txt      |   5 +-
 Documentation/kbuild/kbuild.txt               | 119 ++--
 Documentation/kbuild/kconfig-language.txt     | 232 ++++----
 .../kbuild/kconfig-macro-language.txt         |  37 +-
 Documentation/kbuild/kconfig.txt              | 136 +++--
 Documentation/kbuild/makefiles.txt            | 518 +++++++++++-------
 Documentation/kbuild/modules.txt              | 166 +++---
 7 files changed, 720 insertions(+), 493 deletions(-)
Documentation/kbuild/headers_install.txt +3 -2
index f0153adb95e2..1ab7294e41ac 100644
@@ -1,3 +1,4 @@
+=============================================
 Exporting kernel headers for use by userspace
 =============================================
 
@@ -22,14 +23,14 @@ older kernel.
 
 The "make headers_install" command can be run in the top level directory of the
 kernel source code (or using a standard out-of-tree build).  It takes two
-optional arguments:
+optional arguments::
 
   make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr
 
 ARCH indicates which architecture to produce headers for, and defaults to the
 current architecture.  The linux/asm directory of the exported kernel headers
 is platform-specific, to see a complete list of supported architectures use
-the command:
+the command::
 
   ls -d include/asm-* | sed 's/.*-//'
 
Documentation/kbuild/kbuild.txt +68 -51

305 lines not on this page · raw message

Documentation/kbuild/kconfig-language.txt +126 -106

487 lines not on this page · raw message

Documentation/kbuild/kconfig-macro-language.txt +21 -16
index 07da2ea68dce..35b3263b7e40 100644
@@ -1,3 +1,7 @@
+======================
+Kconfig macro language
+======================
+
 Concept
 -------
 
@@ -7,7 +11,7 @@ targets and prerequisites. The other is a macro language for performing textual
 substitution.
 
 There is clear distinction between the two language stages. For example, you
-can write a makefile like follows:
+can write a makefile like follows::
 
     APP := foo
     SRC := foo.c
@@ -17,7 +21,7 @@ can write a makefile like follows:
             $(CC) -o $(APP) $(SRC)
 
 The macro language replaces the variable references with their expanded form,
-and handles as if the source file were input like follows:
+and handles as if the source file were input like follows::
 
     foo: foo.c
             gcc -o foo foo.c
@@ -26,7 +30,7 @@ Then, Make analyzes the dependency graph and determines the targets to be
 updated.
 
 The idea is quite similar in Kconfig - it is possible to describe a Kconfig
-file like this:
+file like this::
 
     CC := gcc
 
@@ -34,7 +38,7 @@ file like this:
             def_bool $(shell, $(srctree)/scripts/gcc-check-foo.sh $(CC))
 
 The macro language in Kconfig processes the source file into the following
-intermediate:
+intermediate::
 
     config CC_HAS_FOO
             def_bool y
@@ -69,7 +73,7 @@ variable. The righthand side of += is expanded immediately if the lefthand
 side was originally defined as a simple variable. Otherwise, its evaluation is
 deferred.
 
-The variable reference can take parameters, in the following form:
+The variable reference can take parameters, in the following form::
 
   $(name,arg1,arg2,arg3)
 
@@ -141,7 +145,7 @@ Make vs Kconfig
 Kconfig adopts Make-like macro language, but the function call syntax is
 slightly different.
 
-A function call in Make looks like this:
+A function call in Make looks like this::
 
   $(func-name arg1,arg2,arg3)
 
@@ -149,14 +153,14 @@ The function name and the first argument are separated by at least one
 whitespace. Then, leading whitespaces are trimmed from the first argument,
 while whitespaces in the other arguments are kept. You need to use a kind of
 trick to start the first parameter with spaces. For example, if you want
-to make "info" function print "  hello", you can write like follows:
+to make "info" function print "  hello", you can write like follows::
 
   empty :=
   space := $(empty) $(empty)
   $(info $(space)$(space)hello)
 
 Kconfig uses only commas for delimiters, and keeps all whitespaces in the
-function call. Some people prefer putting a space after each comma delimiter:
+function call. Some people prefer putting a space after each comma delimiter::
 
   $(func-name, arg1, arg2, arg3)
 
@@ -166,7 +170,7 @@ Make - for example, $(subst .c, .o, $(sources)) is a typical mistake; it
 replaces ".c" with " .o".
 
 In Make, a user-defined function is referenced by using a built-in function,
-'call', like this:
+'call', like this::
 
     $(call my-func,arg1,arg2,arg3)
 
@@ -179,12 +183,12 @@ Likewise, $(info hello, world) prints "hello, world" to stdout. You could say
 this is _useful_ inconsistency.
 
 In Kconfig, for simpler implementation and grammatical consistency, commas that
-appear in the $( ) context are always delimiters. It means
+appear in the $( ) context are always delimiters. It means::
 
   $(shell, echo hello, world)
 
 is an error because it is passing two parameters where the 'shell' function
-accepts only one. To pass commas in arguments, you can use the following trick:
+accepts only one. To pass commas in arguments, you can use the following trick::
 
   comma := ,
   $(shell, echo hello$(comma) world)
@@ -195,7 +199,7 @@ Caveats
 
 A variable (or function) cannot be expanded across tokens. So, you cannot use
 a variable as a shorthand for an expression that consists of multiple tokens.
-The following works:
+The following works::
 
     RANGE_MIN := 1
     RANGE_MAX := 3
@@ -204,7 +208,7 @@ The following works:
             int "foo"
             range $(RANGE_MIN) $(RANGE_MAX)
 
-But, the following does not work:
+But, the following does not work::
 
     RANGES := 1 3
 
@@ -213,7 +217,7 @@ But, the following does not work:
             range $(RANGES)
 
 A variable cannot be expanded to any keyword in Kconfig.  The following does
-not work:
+not work::
 
     MY_TYPE := tristate
 
@@ -223,7 +227,8 @@ not work:
 
 Obviously from the design, $(shell command) is expanded in the textual
 substitution phase. You cannot pass symbols to the 'shell' function.
-The following does not work as expected.
+
+The following does not work as expected::
 
     config ENDIAN_FLAG
             string
@@ -234,7 +239,7 @@ The following does not work as expected.
             def_bool $(shell $(srctree)/scripts/gcc-check-flag ENDIAN_FLAG)
 
 Instead, you can do like follows so that any function call is statically
-expanded.
+expanded::
 
     config CC_HAS_ENDIAN_FLAG
             bool
Documentation/kbuild/kconfig.txt +82 -54

307 lines not on this page · raw message

Documentation/kbuild/makefiles.txt +322 -196

1,268 lines not on this page · raw message

Documentation/kbuild/modules.txt +98 -68

405 lines not on this page · raw message

Signature · 1 line
2.20.1
#35 lore raw

Re: [PATCH 18/57] docs: kbuild: convert it to ReST output

Quoted 7 lines · Mauro Carvalho Chehab

The kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections.

Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups.

Sorry for my ignorance, but shouldn't ReST use
the extension '.rst' instead of '.txt' ?

Quoted 11 lines
---
 Documentation/kbuild/headers_install.txt      |   5 +-
 Documentation/kbuild/kbuild.txt               | 119 ++--
 Documentation/kbuild/kconfig-language.txt     | 232 ++++----
 .../kbuild/kconfig-macro-language.txt         |  37 +-
 Documentation/kbuild/kconfig.txt              | 136 +++--
 Documentation/kbuild/makefiles.txt            | 518 +++++++++++-------
 Documentation/kbuild/modules.txt              | 166 +++---
 7 files changed, 720 insertions(+), 493 deletions(-)
Signature · 2 lines
Best Regards
Masahiro Yamada
#36 lore raw

Re: [PATCH 18/57] docs: kbuild: convert it to ReST output

Em Thu, 18 Apr 2019 18:25:45 +0900
Masahiro Yamada <[email protected]> escreveu:

Quoted 7 lines
Quoted 5 lines · Mauro Carvalho Chehab

The kbuild documentation clearly shows that the documents there are written at different times: some use markdown, some use their own peculiar logic to split sections.

Quoted 5 lines
Quoted 2 lines

Convert everything to ReST without affecting too much the author's style and avoiding adding uneeded markups.

Sorry for my ignorance, but shouldn't ReST use
the extension '.rst' instead of '.txt' ?

Yes. I have a patch with the rename step, but the problem is that doing such renames on 57 different subdirs and then adding all of them to the existing index.rst files (in order to add into a bookset) would cause huge merge conflicts - and keeping them renamed without adding into an index would cause a *lot* new warnings when building them.

So, IMO, the best would be to have the fixup stuff merged first, and then do the renames/merges at once, after subsystem maintainers pick the patches from this rst fixup series.

If you want to see the renaming patch, it is at:

	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=all_with_indexes-v3&id=9cfeb3eb6d48d1aeff9d2ddd84880ab1dc782b00

(I'll probably split it later into per-subdir renames)

The results of this patch, plus the rename one, is at:

https://www.infradead.org/~mchehab/rst_conversion/kbuild/index.html

Quoted 15 lines
Quoted 4 lines
Quoted 10 lines
---
 Documentation/kbuild/headers_install.txt      |   5 +-
 Documentation/kbuild/kbuild.txt               | 119 ++--
 Documentation/kbuild/kconfig-language.txt     | 232 ++++----
 .../kbuild/kconfig-macro-language.txt         |  37 +-
 Documentation/kbuild/kconfig.txt              | 136 +++--
 Documentation/kbuild/makefiles.txt            | 518 +++++++++++-------
 Documentation/kbuild/modules.txt              | 166 +++---
 7 files changed, 720 insertions(+), 493 deletions(-)

Thanks,
Mauro

#37 lore raw

PATCH 19/57 docs: kdump: convert it to ReST

In reply to Mauro Carvalho Chehab

Convert kdump documentation to ReST and add it to the user faced manual, as the documents are mainly focused on sysadmins that would be enabling kdump.

Note: the vmcoreinfo.rst has one very long title for sub-sections. I opted to break this one, in order to make it easier to display in html.

---
 Documentation/kdump/kdump.txt      | 131 +++++++++++++++++------------
 Documentation/kdump/vmcoreinfo.txt |  59 ++++++-------
 2 files changed, 104 insertions(+), 86 deletions(-)
Documentation/kdump/kdump.txt +78 -53
index 51814450a7f8..1da2d7b765f6 100644
@@ -71,9 +71,8 @@ This is a symlink to the latest version.
 
 The latest kexec-tools git tree is available at:
 
-git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
-and
-http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
+- http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
 
 There is also a gitweb interface available at
 http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
@@ -81,25 +80,25 @@ http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
 More information about kexec-tools can be found at
 http://horms.net/projects/kexec/
 
-3) Unpack the tarball with the tar command, as follows:
+3) Unpack the tarball with the tar command, as follows::
 
-   tar xvpzf kexec-tools.tar.gz
+	tar xvpzf kexec-tools.tar.gz
 
-4) Change to the kexec-tools directory, as follows:
+4) Change to the kexec-tools directory, as follows::
 
-   cd kexec-tools-VERSION
+	cd kexec-tools-VERSION
 
-5) Configure the package, as follows:
+5) Configure the package, as follows::
 
-   ./configure
+	./configure
 
-6) Compile the package, as follows:
+6) Compile the package, as follows::
 
-   make
+	make
 
-7) Install the package, as follows:
+7) Install the package, as follows::
 
-   make install
+	make install
 
 
 Build the system and dump-capture kernels
@@ -126,25 +125,25 @@ dump-capture kernels for enabling kdump support.
 System kernel config options
 ----------------------------
 
-1) Enable "kexec system call" in "Processor type and features."
+1) Enable "kexec system call" in "Processor type and features."::
 
-   CONFIG_KEXEC=y
+	CONFIG_KEXEC=y
 
 2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
-   filesystems." This is usually enabled by default.
+   filesystems." This is usually enabled by default::
 
-   CONFIG_SYSFS=y
+	CONFIG_SYSFS=y
 
    Note that "sysfs file system support" might not appear in the "Pseudo
    filesystems" menu if "Configure standard kernel features (for small
    systems)" is not enabled in "General Setup." In this case, check the
-   .config file itself to ensure that sysfs is turned on, as follows:
+   .config file itself to ensure that sysfs is turned on, as follows::
 
-   grep 'CONFIG_SYSFS' .config
+	grep 'CONFIG_SYSFS' .config
 
-3) Enable "Compile the kernel with debug info" in "Kernel hacking."
+3) Enable "Compile the kernel with debug info" in "Kernel hacking."::
 
-   CONFIG_DEBUG_INFO=Y
+	CONFIG_DEBUG_INFO=Y
 
    This causes the kernel to be built with debug symbols. The dump
    analysis tools require a vmlinux with debug symbols in order to read
@@ -154,29 +153,32 @@ Dump-capture kernel config options (Arch Independent)
 -----------------------------------------------------
 
 1) Enable "kernel crash dumps" support under "Processor type and
-   features":
+   features"::
 
-   CONFIG_CRASH_DUMP=y
+	CONFIG_CRASH_DUMP=y
 
-2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems".
+2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems"::
+
+	CONFIG_PROC_VMCORE=y
 
-   CONFIG_PROC_VMCORE=y
    (CONFIG_PROC_VMCORE is set by default when CONFIG_CRASH_DUMP is selected.)
 
 Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
 --------------------------------------------------------------------
 
 1) On i386, enable high memory support under "Processor type and
-   features":
+   features"::
 
-   CONFIG_HIGHMEM64G=y
-   or
-   CONFIG_HIGHMEM4G
+	CONFIG_HIGHMEM64G=y
+
+   or::
+
+	CONFIG_HIGHMEM4G
 
 2) On i386 and x86_64, disable symmetric multi-processing support
-   under "Processor type and features":
+   under "Processor type and features"::
 
-   CONFIG_SMP=n
+	CONFIG_SMP=n
 
    (If CONFIG_SMP=y, then specify maxcpus=1 on the kernel command line
    when loading the dump-capture kernel, see section "Load the Dump-capture
@@ -184,9 +186,9 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
 
 3) If one wants to build and use a relocatable kernel,
    Enable "Build a relocatable kernel" support under "Processor type and
-   features"
+   features"::
 
-   CONFIG_RELOCATABLE=y
+	CONFIG_RELOCATABLE=y
 
 4) Use a suitable value for "Physical address where the kernel is
    loaded" (under "Processor type and features"). This only appears when
@@ -211,13 +213,13 @@ Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
 Dump-capture kernel config options (Arch Dependent, ppc64)
 ----------------------------------------------------------
 
-1) Enable "Build a kdump crash kernel" support under "Kernel" options:
+1) Enable "Build a kdump crash kernel" support under "Kernel" options::
 
-   CONFIG_CRASH_DUMP=y
+	CONFIG_CRASH_DUMP=y
 
-2)   Enable "Build a relocatable kernel" support
+2)   Enable "Build a relocatable kernel" support::
 
-   CONFIG_RELOCATABLE=y
+	CONFIG_RELOCATABLE=y
 
    Make and install the kernel and its modules.
 
@@ -231,11 +233,13 @@ Dump-capture kernel config options (Arch Dependent, ia64)
 
   The crashkernel region can be automatically placed by the system
   kernel at run time. This is done by specifying the base address as 0,
-  or omitting it all together.
+  or omitting it all together::
 
-  crashkernel=256M@0
-  or
-  crashkernel=256M
+	crashkernel=256M@0
+
+  or::
+
+	crashkernel=256M
 
   If the start address is specified, note that the start address of the
   kernel will be aligned to 64Mb, so if the start address is not then
@@ -245,9 +249,9 @@ Dump-capture kernel config options (Arch Dependent, arm)
 ----------------------------------------------------------
 
 -   To use a relocatable kernel,
-    Enable "AUTO_ZRELADDR" support under "Boot" options:
+    Enable "AUTO_ZRELADDR" support under "Boot" options::
 
-    AUTO_ZRELADDR=y
+	AUTO_ZRELADDR=y
 
 Dump-capture kernel config options (Arch Dependent, arm64)
 ----------------------------------------------------------
@@ -265,12 +269,12 @@ on the value of System RAM -- that's mostly for distributors that pre-setup
 the kernel command line to avoid a unbootable system after some memory has
 been removed from the machine.
 
-The syntax is:
+The syntax is::
 
     crashkernel=<range1>:<size1>[,<range2>:<size2>,...][@offset]
     range=start-[end]
 
-For example:
+For example::
 
     crashkernel=512M-2G:64M,2G-:128M
 
@@ -326,35 +330,46 @@ can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz
 of dump-capture kernel. Following is the summary.
 
 For i386 and x86_64:
+
 	- Use vmlinux if kernel is not relocatable.
 	- Use bzImage/vmlinuz if kernel is relocatable.
+
 For ppc64:
+
 	- Use vmlinux
+
 For ia64:
+
 	- Use vmlinux or vmlinuz.gz
+
 For s390x:
+
 	- Use image or bzImage
+
 For arm:
+
 	- Use zImage
+
 For arm64:
+
 	- Use vmlinux or Image
 
 If you are using an uncompressed vmlinux image then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
 
    kexec -p <dump-capture-kernel-vmlinux-image> \
    --initrd=<initrd-for-dump-capture-kernel> --args-linux \
    --append="root=<root-dev> <arch-specific-options>"
 
 If you are using a compressed bzImage/vmlinuz, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
 
    kexec -p <dump-capture-kernel-bzImage> \
    --initrd=<initrd-for-dump-capture-kernel> \
    --append="root=<root-dev> <arch-specific-options>"
 
 If you are using a compressed zImage, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
 
    kexec --type zImage -p <dump-capture-kernel-bzImage> \
    --initrd=<initrd-for-dump-capture-kernel> \
@@ -362,7 +377,7 @@ to load dump-capture kernel.
    --append="root=<root-dev> <arch-specific-options>"
 
 If you are using an uncompressed Image, then use following command
-to load dump-capture kernel.
+to load dump-capture kernel::
 
    kexec -p <dump-capture-kernel-Image> \
    --initrd=<initrd-for-dump-capture-kernel> \
@@ -376,18 +391,23 @@ Following are the arch specific command line options to be used while
 loading dump-capture kernel.
 
 For i386, x86_64 and ia64:
+
 	"1 irqpoll maxcpus=1 reset_devices"
 
 For ppc64:
+
 	"1 maxcpus=1 noirqdistrib reset_devices"
 
 For s390x:
+
 	"1 maxcpus=1 cgroup_disable=memory"
 
 For arm:
+
 	"1 maxcpus=1 reset_devices"
 
 For arm64:
+
 	"1 maxcpus=1 reset_devices"
 
 Notes on loading the dump-capture kernel:
@@ -464,7 +484,7 @@ Write Out the Dump File
 =======================
 
 After the dump-capture kernel is booted, write out the dump file with
-the following command:
+the following command::
 
    cp /proc/vmcore <dump-file>
 
@@ -476,7 +496,7 @@ Before analyzing the dump image, you should reboot into a stable kernel.
 
 You can do limited analysis using GDB on the dump file copied out of
 /proc/vmcore. Use the debug vmlinux built with -g and run the following
-command:
+command::
 
    gdb vmlinux <dump-file>
 
@@ -504,6 +524,11 @@ to achieve the same behaviour.
 Contact
 =======
 
-Vivek Goyal ([email protected])
-Maneesh Soni ([email protected])
+- Vivek Goyal ([email protected])
+- Maneesh Soni ([email protected])
 
+GDB macros
+==========
+
+.. include:: gdbmacros.txt
+   :literal:
Documentation/kdump/vmcoreinfo.txt +26 -33

155 lines not on this page · raw message

Signature · 7 lines
2.20.1


_______________________________________________
kexec mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/kexec
#38 lore raw

PATCH 20/57 docs: livepatch: convert it to ReST format

In reply to Mauro Carvalho Chehab

Convert livepatch documentation to ReST format. The changes are mostly trivial, as the documents are already on a good shape. Just a few markup changes are needed for Sphinx to properly parse the docs.

---
 Documentation/livepatch/callbacks.txt         |  12 +-
 .../livepatch/cumulative-patches.txt          |  14 +-
 Documentation/livepatch/livepatch.txt         |  56 ++---
 Documentation/livepatch/module-elf-format.txt | 211 ++++++++++--------
 Documentation/livepatch/shadow-vars.txt       |  65 ++++--
 5 files changed, 199 insertions(+), 159 deletions(-)
Documentation/livepatch/callbacks.txt +8 -4
index 182e31d4abce..d76d1f0d9fcf 100644
@@ -30,16 +30,20 @@ be patched, irrespective of the target klp_object's current state.
 
 Callbacks can be registered for the following livepatch actions:
 
-  * Pre-patch    - before a klp_object is patched
+  * Pre-patch
+                 - before a klp_object is patched
 
-  * Post-patch   - after a klp_object has been patched and is active
+  * Post-patch
+                 - after a klp_object has been patched and is active
                    across all tasks
 
-  * Pre-unpatch  - before a klp_object is unpatched (ie, patched code is
+  * Pre-unpatch
+                 - before a klp_object is unpatched (ie, patched code is
                    active), used to clean up post-patch callback
                    resources
 
-  * Post-unpatch - after a klp_object has been patched, all code has
+  * Post-unpatch
+                 - after a klp_object has been patched, all code has
                    been restored and no tasks are running patched code,
                    used to cleanup pre-patch callback resources
 
Documentation/livepatch/cumulative-patches.txt +7 -7
index 0012808e8d44..1931f318976a 100644
@@ -18,7 +18,7 @@ Usage
 -----
 
 The atomic replace can be enabled by setting "replace" flag in struct klp_patch,
-for example:
+for example::
 
 	static struct klp_patch patch = {
 		.mod = THIS_MODULE,
@@ -49,19 +49,19 @@ Features
 
 The atomic replace allows:
 
-  + Atomically revert some functions in a previous patch while
+  - Atomically revert some functions in a previous patch while
     upgrading other functions.
 
-  + Remove eventual performance impact caused by core redirection
+  - Remove eventual performance impact caused by core redirection
     for functions that are no longer patched.
 
-  + Decrease user confusion about dependencies between livepatches.
+  - Decrease user confusion about dependencies between livepatches.
 
 
 Limitations:
 ------------
 
-  + Once the operation finishes, there is no straightforward way
+  - Once the operation finishes, there is no straightforward way
     to reverse it and restore the replaced patches atomically.
 
     A good practice is to set .replace flag in any released livepatch.
@@ -74,7 +74,7 @@ Limitations:
     only when the transition was not forced.
 
 
-  + Only the (un)patching callbacks from the _new_ cumulative livepatch are
+  - Only the (un)patching callbacks from the _new_ cumulative livepatch are
     executed. Any callbacks from the replaced patches are ignored.
 
     In other words, the cumulative patch is responsible for doing any actions
@@ -93,7 +93,7 @@ Limitations:
     enabled patches were called.
 
 
-  + There is no special handling of shadow variables. Livepatch authors
+  - There is no special handling of shadow variables. Livepatch authors
     must create their own rules how to pass them from one cumulative
     patch to the other. Especially that they should not blindly remove
     them in module_exit() functions.
Documentation/livepatch/livepatch.txt +29 -27

128 lines not on this page · raw message

Documentation/livepatch/module-elf-format.txt +114 -97

272 lines not on this page · raw message

Documentation/livepatch/shadow-vars.txt +41 -24

143 lines not on this page · raw message

Signature · 1 line
2.20.1
maintainer Reviewed-by on v1 20/57
#39 lore raw

Re: [PATCH 20/57] docs: livepatch: convert it to ReST format

Quoted 6 lines · Mauro Carvalho Chehab

Convert livepatch documentation to ReST format. The changes are mostly trivial, as the documents are already on a good shape. Just a few markup changes are needed for Sphinx to properly parse the docs.

Thanks a lot for the conversion. I tried html output and it looks very well.

Just a question. This patch does only the formatting. The documentation is not really generated because the file is not renamed to .rst. Also it is not referenced from any top level documents. Is it by intention?

I am happy even for the conversion, so:

Best Regards,
Petr

#40 lore raw

Re: [PATCH 20/57] docs: livepatch: convert it to ReST format

Em Tue, 16 Apr 2019 10:43:54 +0200
Petr Mladek <[email protected]> escreveu:

Quoted 8 lines · Mauro Carvalho Chehab
Quoted 6 lines

Convert livepatch documentation to ReST format. The changes are mostly trivial, as the documents are already on a good shape. Just a few markup changes are needed for Sphinx to properly parse the docs.

Quoted 7 lines

Thanks a lot for the conversion. I tried html output and it looks very well.

Just a question. This patch does only the formatting. The documentation is not really generated because the file is not renamed to .rst. Also it is not referenced from any top level documents. Is it by intention?

Yes. The rationale is simple: renaming to .rst would require to add them on an index file (or otherwise build would produce lots of warnings). As this series is doing a lot of such conversions, assuming that some of those patches will go through different trees, that would cause lots of conflicts at the main index files.

So, it sounds better to apply the conversion first and then, on a better moment (maybe late during the merge window), do the rename and add to the index files.

Quoted 8 lines

I am happy even for the conversion, so:

Best Regards,
Petr

Thanks,
Mauro

#41 lore raw

PATCH 21/57 docs: locking: convert docs to ReST format

In reply to Mauro Carvalho Chehab

Convert the locking documents to ReST and add them to the kernel development book where it belongs.

Most of the stuff here is just to make Sphinx to properly parse the text file, as they're already in good shape, not requiring massive changes in order to be parsed.

---
 Documentation/locking/lockdep-design.txt  |  41 ++--
 Documentation/locking/lockstat.txt        | 219 ++++++++++++----------
 Documentation/locking/locktorture.txt     | 105 +++++++----
 Documentation/locking/mutex-design.txt    |  26 ++-
 Documentation/locking/rt-mutex-design.txt | 135 +++++++------
 Documentation/locking/rt-mutex.txt        |  30 +--
 Documentation/locking/spinlocks.txt       |  32 ++--
 Documentation/locking/ww-mutex-design.txt |  82 ++++----
 8 files changed, 385 insertions(+), 285 deletions(-)
Documentation/locking/lockdep-design.txt +23 -18
index 39fae143c9cb..49707a5029c5 100644
@@ -2,6 +2,7 @@ Runtime locking correctness validator
 =====================================
 
 started by Ingo Molnar <[email protected]>
+
 additions by Arjan van de Ven <[email protected]>
 
 Lock-class
@@ -42,7 +43,7 @@ Where STATE can be either one of (kernel/locking/lockdep_states.h)
 - 'ever used'                                       [ == !unused        ]
 
 When locking rules are violated, these state bits are presented in the
-locking error messages, inside curlies. A contrived example:
+locking error messages, inside curlies. A contrived example::
 
    modprobe/2287 is trying to acquire lock:
     (&sio_locks[i].lock){-.-.}, at: [<c02867fd>] mutex_lock+0x21/0x24
@@ -54,10 +55,12 @@ locking error messages, inside curlies. A contrived example:
 The bit position indicates STATE, STATE-read, for each of the states listed
 above, and the character displayed in each indicates:
 
+   ===  ===================================================
    '.'  acquired while irqs disabled and not in irq context
    '-'  acquired in irq context
    '+'  acquired with irqs enabled
    '?'  acquired in irq context with irqs enabled.
+   ===  ===================================================
 
 Unused mutexes cannot be part of the cause of an error.
 
@@ -67,7 +70,7 @@ Single-lock state rules:
 
 A softirq-unsafe lock-class is automatically hardirq-unsafe as well. The
 following states are exclusive, and only one of them is allowed to be
-set for any lock-class:
+set for any lock-class::
 
  <hardirq-safe> and <hardirq-unsafe>
  <softirq-safe> and <softirq-unsafe>
@@ -81,7 +84,7 @@ Multi-lock dependency rules:
 The same lock-class must not be acquired twice, because this could lead
 to lock recursion deadlocks.
 
-Furthermore, two locks may not be taken in different order:
+Furthermore, two locks may not be taken in different order::
 
  <L1> -> <L2>
  <L2> -> <L1>
@@ -92,7 +95,7 @@ other locking sequence between the acquire-lock operations, the
 validator will still track all dependencies between locks.)
 
 Furthermore, the following usage based lock dependencies are not allowed
-between any two lock-classes:
+between any two lock-classes::
 
    <hardirq-safe>   ->  <hardirq-unsafe>
    <softirq-safe>   ->  <softirq-unsafe>
@@ -148,16 +151,16 @@ the ordering is not static.
 In order to teach the validator about this correct usage model, new
 versions of the various locking primitives were added that allow you to
 specify a "nesting level". An example call, for the block device mutex,
-looks like this:
+looks like this::
 
-enum bdev_bd_mutex_lock_class
-{
+  enum bdev_bd_mutex_lock_class
+  {
        BD_MUTEX_NORMAL,
        BD_MUTEX_WHOLE,
        BD_MUTEX_PARTITION
-};
+  };
 
- mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
+mutex_lock_nested(&bdev->bd_contains->bd_mutex, BD_MUTEX_PARTITION);
 
 In this case the locking is done on a bdev object that is known to be a
 partition.
@@ -178,7 +181,7 @@ must be held: lockdep_assert_held*(&lock) and lockdep_*pin_lock(&lock).
 As the name suggests, lockdep_assert_held* family of macros assert that a
 particular lock is held at a certain time (and generate a WARN() otherwise).
 This annotation is largely used all over the kernel, e.g. kernel/sched/
-core.c
+core.c::
 
   void update_rq_clock(struct rq *rq)
   {
@@ -197,7 +200,7 @@ out to be especially helpful to debug code with callbacks, where an upper
 layer assumes a lock remains taken, but a lower layer thinks it can maybe drop
 and reacquire the lock ("unwittingly" introducing races). lockdep_pin_lock()
 returns a 'struct pin_cookie' that is then used by lockdep_unpin_lock() to check
-that nobody tampered with the lock, e.g. kernel/sched/sched.h
+that nobody tampered with the lock, e.g. kernel/sched/sched.h::
 
   static inline void rq_pin_lock(struct rq *rq, struct rq_flags *rf)
   {
@@ -224,7 +227,7 @@ correctness) in the sense that for every simple, standalone single-task
 locking sequence that occurred at least once during the lifetime of the
 kernel, the validator proves it with a 100% certainty that no
 combination and timing of these locking sequences can cause any class of
-lock related deadlock. [*]
+lock related deadlock. [1]_
 
 I.e. complex multi-CPU and multi-task locking scenarios do not have to
 occur in practice to prove a deadlock: only the simple 'component'
@@ -243,7 +246,9 @@ possible combination of locking interaction between CPUs, combined with
 every possible hardirq and softirq nesting scenario (which is impossible
 to do in practice).
 
-[*] assuming that the validator itself is 100% correct, and no other
+.. [1]
+
+    assuming that the validator itself is 100% correct, and no other
     part of the system corrupts the state of the validator in any way.
     We also assume that all NMI/SMM paths [which could interrupt
     even hardirq-disabled codepaths] are correct and do not interfere
@@ -254,7 +259,7 @@ to do in practice).
 Performance:
 ------------
 
-The above rules require _massive_ amounts of runtime checking. If we did
+The above rules require **massive** amounts of runtime checking. If we did
 that for every lock taken and for every irqs-enable event, it would
 render the system practically unusably slow. The complexity of checking
 is O(N^2), so even with just a few hundred lock-classes we'd have to do
@@ -313,17 +318,17 @@ be harder to do than to say.
 
 Of course, if you do run out of lock classes, the next thing to do is
 to find the offending lock classes.  First, the following command gives
-you the number of lock classes currently in use along with the maximum:
+you the number of lock classes currently in use along with the maximum::
 
 	grep "lock-classes" /proc/lockdep_stats
 
-This command produces the following output on a modest system:
+This command produces the following output on a modest system::
 
-	 lock-classes:                          748 [max: 8191]
+	lock-classes:                          748 [max: 8191]
 
 If the number allocated (748 above) increases continually over time,
 then there is likely a leak.  The following command can be used to
-identify the leaking lock classes:
+identify the leaking lock classes::
 
 	grep "BD" /proc/lockdep
 
Documentation/locking/lockstat.txt +120 -99

268 lines not on this page · raw message

Documentation/locking/locktorture.txt +65 -40

185 lines not on this page · raw message

Documentation/locking/mutex-design.txt +18 -8
index 818aca19612f..4d8236b81fa5 100644
@@ -1,6 +1,9 @@
+=======================
 Generic Mutex Subsystem
+=======================
 
 started by Ingo Molnar <[email protected]>
+
 updated by Davidlohr Bueso <[email protected]>
 
 What are mutexes?
@@ -23,7 +26,7 @@ Implementation
 Mutexes are represented by 'struct mutex', defined in include/linux/mutex.h
 and implemented in kernel/locking/mutex.c. These locks use an atomic variable
 (->owner) to keep track of the lock state during its lifetime.  Field owner
-actually contains 'struct task_struct *' to the current lock owner and it is
+actually contains `struct task_struct *` to the current lock owner and it is
 therefore NULL if not currently owned. Since task_struct pointers are aligned
 at at least L1_CACHE_BYTES, low bits (3) are used to store extra state (e.g.,
 if waiter list is non-empty).  In its most basic form it also includes a
@@ -101,29 +104,36 @@ features that make lock debugging easier and faster:
 
 Interfaces
 ----------
-Statically define the mutex:
+Statically define the mutex::
+
    DEFINE_MUTEX(name);
 
-Dynamically initialize the mutex:
+Dynamically initialize the mutex::
+
    mutex_init(mutex);
 
-Acquire the mutex, uninterruptible:
+Acquire the mutex, uninterruptible::
+
    void mutex_lock(struct mutex *lock);
    void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
    int  mutex_trylock(struct mutex *lock);
 
-Acquire the mutex, interruptible:
+Acquire the mutex, interruptible::
+
    int mutex_lock_interruptible_nested(struct mutex *lock,
 				       unsigned int subclass);
    int mutex_lock_interruptible(struct mutex *lock);
 
-Acquire the mutex, interruptible, if dec to 0:
+Acquire the mutex, interruptible, if dec to 0::
+
    int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
 
-Unlock the mutex:
+Unlock the mutex::
+
    void mutex_unlock(struct mutex *lock);
 
-Test if the mutex is taken:
+Test if the mutex is taken::
+
    int mutex_is_locked(struct mutex *lock);
 
 Disadvantages
Documentation/locking/rt-mutex-design.txt +75 -60

288 lines not on this page · raw message

Documentation/locking/rt-mutex.txt +17 -13
index 35793e003041..c365dc302081 100644
@@ -1,5 +1,6 @@
+==================================
 RT-mutex subsystem with PI support
-----------------------------------
+==================================
 
 RT-mutexes with priority inheritance are used to support PI-futexes,
 which enable pthread_mutex_t priority inheritance attributes
@@ -46,27 +47,30 @@ The state of the rt-mutex is tracked via the owner field of the rt-mutex
 structure:
 
 lock->owner holds the task_struct pointer of the owner. Bit 0 is used to
-keep track of the "lock has waiters" state.
+keep track of the "lock has waiters" state:
 
- owner        bit0
+ ============ ======= ================================================
+ owner        bit0    Notes
+ ============ ======= ================================================
  NULL         0       lock is free (fast acquire possible)
  NULL         1       lock is free and has waiters and the top waiter
-			is going to take the lock*
+		      is going to take the lock [1]_
  taskpointer  0       lock is held (fast release possible)
- taskpointer  1       lock is held and has waiters**
+ taskpointer  1       lock is held and has waiters [2]_
+ ============ ======= ================================================
 
 The fast atomic compare exchange based acquire and release is only
 possible when bit 0 of lock->owner is 0.
 
-(*) It also can be a transitional state when grabbing the lock
-with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
-we need to set the bit0 before looking at the lock, and the owner may be
-NULL in this small time, hence this can be a transitional state.
+.. [1] It also can be a transitional state when grabbing the lock
+       with ->wait_lock is held. To prevent any fast path cmpxchg to the lock,
+       we need to set the bit0 before looking at the lock, and the owner may
+       be NULL in this small time, hence this can be a transitional state.
 
-(**) There is a small time when bit 0 is set but there are no
-waiters. This can happen when grabbing the lock in the slow path.
-To prevent a cmpxchg of the owner releasing the lock, we need to
-set this bit before looking at the lock.
+.. [2] There is a small time when bit 0 is set but there are no
+       waiters. This can happen when grabbing the lock in the slow path.
+       To prevent a cmpxchg of the owner releasing the lock, we need to
+       set this bit before looking at the lock.
 
 BTW, there is still technically a "Pending Owner", it's just not called
 that anymore. The pending owner happens to be the top_waiter of a lock
Documentation/locking/spinlocks.txt +21 -11
index ff35e40bdf5b..098107fb7d86 100644
@@ -1,8 +1,13 @@
+===============
+Locking lessons
+===============
+
 Lesson 1: Spin locks
+====================
 
-The most basic primitive for locking is spinlock.
+The most basic primitive for locking is spinlock::
 
-static DEFINE_SPINLOCK(xxx_lock);
+  static DEFINE_SPINLOCK(xxx_lock);
 
 	unsigned long flags;
 
@@ -19,23 +24,25 @@ worry about UP vs SMP issues: the spinlocks work correctly under both.
    NOTE! Implications of spin_locks for memory are further described in:
 
      Documentation/memory-barriers.txt
+
        (5) LOCK operations.
+
        (6) UNLOCK operations.
 
 The above is usually pretty simple (you usually need and want only one
 spinlock for most things - using more than one spinlock can make things a
 lot more complex and even slower and is usually worth it only for
-sequences that you _know_ need to be split up: avoid it at all cost if you
+sequences that you **know** need to be split up: avoid it at all cost if you
 aren't sure).
 
 This is really the only really hard part about spinlocks: once you start
 using spinlocks they tend to expand to areas you might not have noticed
 before, because you have to make sure the spinlocks correctly protect the
-shared data structures _everywhere_ they are used. The spinlocks are most
+shared data structures **everywhere** they are used. The spinlocks are most
 easily added to places that are completely independent of other code (for
 example, internal driver data structures that nobody else ever touches).
 
-   NOTE! The spin-lock is safe only when you _also_ use the lock itself
+   NOTE! The spin-lock is safe only when you **also** use the lock itself
    to do locking across CPU's, which implies that EVERYTHING that
    touches a shared variable has to agree about the spinlock they want
    to use.
@@ -43,6 +50,7 @@ example, internal driver data structures that nobody else ever touches).
 ----
 
 Lesson 2: reader-writer spinlocks.
+==================================
 
 If your data accesses have a very natural pattern where you usually tend
 to mostly read from the shared variables, the reader-writer locks
@@ -54,7 +62,7 @@ to change the variables it has to get an exclusive write lock.
    simple spinlocks.  Unless the reader critical section is long, you
    are better off just using spinlocks.
 
-The routines look the same as above:
+The routines look the same as above::
 
    rwlock_t xxx_lock = __RW_LOCK_UNLOCKED(xxx_lock);
 
@@ -71,7 +79,7 @@ The routines look the same as above:
 The above kind of lock may be useful for complex data structures like
 linked lists, especially searching for entries without changing the list
 itself.  The read lock allows many concurrent readers.  Anything that
-_changes_ the list will have to get the write lock.
+**changes** the list will have to get the write lock.
 
    NOTE! RCU is better for list traversal, but requires careful
    attention to design detail (see Documentation/RCU/listRCU.txt).
@@ -87,10 +95,11 @@ to get the write-lock at the very beginning.
 ----
 
 Lesson 3: spinlocks revisited.
+==============================
 
 The single spin-lock primitives above are by no means the only ones. They
 are the most safe ones, and the ones that work under all circumstances,
-but partly _because_ they are safe they are also fairly slow. They are slower
+but partly **because** they are safe they are also fairly slow. They are slower
 than they'd need to be, because they do have to disable interrupts
 (which is just a single instruction on a x86, but it's an expensive one -
 and on other architectures it can be worse).
@@ -98,7 +107,7 @@ and on other architectures it can be worse).
 If you have a case where you have to protect a data structure across
 several CPU's and you want to use spinlocks you can potentially use
 cheaper versions of the spinlocks. IFF you know that the spinlocks are
-never used in interrupt handlers, you can use the non-irq versions:
+never used in interrupt handlers, you can use the non-irq versions::
 
 	spin_lock(&lock);
 	...
@@ -110,7 +119,7 @@ This is useful if you know that the data in question is only ever
 manipulated from a "process context", ie no interrupts involved.
 
 The reasons you mustn't use these versions if you have interrupts that
-play with the spinlock is that you can get deadlocks:
+play with the spinlock is that you can get deadlocks::
 
 	spin_lock(&lock);
 	...
@@ -147,9 +156,10 @@ indeed), while write-locks need to protect themselves against interrupts.
 ----
 
 Reference information:
+======================
 
 For dynamic initialization, use spin_lock_init() or rwlock_init() as
-appropriate:
+appropriate::
 
    spinlock_t xxx_lock;
    rwlock_t xxx_rw_lock;
Documentation/locking/ww-mutex-design.txt +46 -36

209 lines not on this page · raw message

Signature · 1 line
2.20.1
#42 lore raw

PATCH 22/57 docs: mic: convert it to ReST format

In reply to Mauro Carvalho Chehab

Convert Intel Many Integrated Core architecture docs to ReST.

The conversion is trivial: just add title and literal block markups, and adjust some identation.

---
 Documentation/mic/mic_overview.txt  |  6 ++-
 Documentation/mic/scif_overview.txt | 58 +++++++++++++++++------------
 2 files changed, 39 insertions(+), 25 deletions(-)
Documentation/mic/mic_overview.txt +5 -1
index 074adbdf83a4..17d956bdaf7c 100644
@@ -1,3 +1,7 @@
+======================================================
+Intel Many Integrated Core (MIC) architecture overview
+======================================================
+
 An Intel MIC X100 device is a PCIe form factor add-in coprocessor
 card based on the Intel Many Integrated Core (MIC) architecture
 that runs a Linux OS. It is a PCIe endpoint in a platform and therefore
@@ -45,7 +49,7 @@ Here is a block diagram of the various components described above. The
 virtio backends are situated on the host rather than the card given better
 single threaded performance for the host compared to MIC, the ability of
 the host to initiate DMA's to/from the card using the MIC DMA engine and
-the fact that the virtio block storage backend can only be on the host.
+the fact that the virtio block storage backend can only be on the host::
 
                +----------+           |             +----------+
                | Card OS  |           |             | Host OS  |
Documentation/mic/scif_overview.txt +34 -24

87 lines not on this page · raw message

Signature · 1 line
2.20.1
#43 lore raw

PATCH 23/57 docs: netlabel: convert it to ReST

In reply to Mauro Carvalho Chehab

Convert netlabel documentation to ReST.

This was trivial: just add proper title markups.

---
 Documentation/netlabel/cipso_ipv4.txt    | 19 +++++++++++++------
 Documentation/netlabel/introduction.txt  | 16 +++++++++++-----
 Documentation/netlabel/lsm_interface.txt | 16 +++++++++++-----
 3 files changed, 35 insertions(+), 16 deletions(-)
Documentation/netlabel/cipso_ipv4.txt +13 -6
index a6075481fd60..cbd3f3231221 100644
@@ -1,10 +1,13 @@
+===================================
 NetLabel CIPSO/IPv4 Protocol Engine
-==============================================================================
+===================================
+
 Paul Moore, [email protected]
 
 May 17, 2006
 
- * Overview
+Overview
+========
 
 The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial
 IP Security Option (CIPSO) draft from July 16, 1992.  A copy of this
@@ -13,7 +16,8 @@ draft can be found in this directory
 it to an RFC standard it has become a de-facto standard for labeled
 networking and is used in many trusted operating systems.
 
- * Outbound Packet Processing
+Outbound Packet Processing
+==========================
 
 The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by
 adding the CIPSO label to the socket.  This causes all packets leaving the
@@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is
 configured to use CIPSO for packet labeling then a CIPSO IP option will be
 generated and attached to the socket.
 
- * Inbound Packet Processing
+Inbound Packet Processing
+=========================
 
 The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the
 IP layer without any special handling required by the LSM.  However, in order
@@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet.
 This is typically done at the socket layer using the 'socket_sock_rcv_skb()'
 LSM hook.
 
- * Label Translation
+Label Translation
+=================
 
 The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security
 attributes such as sensitivity level and category to values which are
@@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the
 NetLabel user space communication layer.  Each DOI definition can have a
 different security attribute mapping table.
 
- * Label Translation Cache
+Label Translation Cache
+=======================
 
 The NetLabel system provides a framework for caching security attribute
 mappings from the network labels to the corresponding LSM identifiers.  The
Documentation/netlabel/introduction.txt +11 -5
index 3caf77bcff0f..9333bbb0adc1 100644
@@ -1,10 +1,13 @@
+=====================
 NetLabel Introduction
-==============================================================================
+=====================
+
 Paul Moore, [email protected]
 
 August 2, 2006
 
- * Overview
+Overview
+========
 
 NetLabel is a mechanism which can be used by kernel security modules to attach
 security attributes to outgoing network packets generated from user space
@@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets.  It
 is composed of three main components, the protocol engines, the communication
 layer, and the kernel security module API.
 
- * Protocol Engines
+Protocol Engines
+================
 
 The protocol engines are responsible for both applying and retrieving the
 network packet's security attributes.  If any translation between the network
@@ -24,7 +28,8 @@ the NetLabel kernel security module API described below.
 Detailed information about each NetLabel protocol engine can be found in this
 directory.
 
- * Communication Layer
+Communication Layer
+===================
 
 The communication layer exists to allow NetLabel configuration and monitoring
 from user space.  The NetLabel communication layer uses a message based
@@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family
 names can be found in the 'net/netlabel/' directory as comments in the
 header files as well as in 'include/net/netlabel.h'.
 
- * Security Module API
+Security Module API
+===================
 
 The purpose of the NetLabel security module API is to provide a protocol
 independent interface to the underlying NetLabel protocol engines.  In addition
Documentation/netlabel/lsm_interface.txt +11 -5
index 638c74f7de7f..026fc267f798 100644
@@ -1,10 +1,13 @@
+========================================
 NetLabel Linux Security Module Interface
-==============================================================================
+========================================
+
 Paul Moore, [email protected]
 
 May 17, 2006
 
- * Overview
+Overview
+========
 
 NetLabel is a mechanism which can set and retrieve security attributes from
 network packets.  It is intended to be used by LSM developers who want to make
@@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols.
 The NetLabel security module API is defined in 'include/net/netlabel.h' but a
 brief overview is given below.
 
- * NetLabel Security Attributes
+NetLabel Security Attributes
+============================
 
 Since NetLabel supports multiple different packet labeling protocols and LSMs
 it uses the concept of security attributes to refer to the packet's security
@@ -24,7 +28,8 @@ configuration.  It is up to the LSM developer to translate the NetLabel
 security attributes into whatever security identifiers are in use for their
 particular LSM.
 
- * NetLabel LSM Protocol Operations
+NetLabel LSM Protocol Operations
+================================
 
 These are the functions which allow the LSM developer to manipulate the labels
 on outgoing packets as well as read the labels on incoming packets.  Functions
@@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly.  These high
 level functions are translated into low level protocol operations based on how
 the administrator has configured the NetLabel subsystem.
 
- * NetLabel Label Mapping Cache Operations
+NetLabel Label Mapping Cache Operations
+=======================================
 
 Depending on the exact configuration, translation between the network packet
 label and the internal LSM security identifier can be time consuming.  The
Signature · 1 line
2.20.1
maintainer Acked-by on v1 23/57
#44 lore raw

Re: [PATCH 23/57] docs: netlabel: convert it to ReST

Quoted 11 lines · Mauro Carvalho Chehab

Convert netlabel documentation to ReST.

This was trivial: just add proper title markups.

---
 Documentation/netlabel/cipso_ipv4.txt    | 19 +++++++++++++------
 Documentation/netlabel/introduction.txt  | 16 +++++++++++-----
 Documentation/netlabel/lsm_interface.txt | 16 +++++++++++-----
 3 files changed, 35 insertions(+), 16 deletions(-)

Thanks for doing this. I should probably revisit these docs to make sure they are still valid/correct; if nothing else that email address is from two employers ago (my apologies to the current email address holder).

Quoted 163 lines
Documentation/netlabel/cipso_ipv4.txt +13 -6
index a6075481fd60..cbd3f3231221 100644
@@ -1,10 +1,13 @@
+===================================
 NetLabel CIPSO/IPv4 Protocol Engine
-==============================================================================
+===================================
+
 Paul Moore, [email protected]
 
 May 17, 2006
 
- * Overview
+Overview
+========
 
 The NetLabel CIPSO/IPv4 protocol engine is based on the IETF Commercial
 IP Security Option (CIPSO) draft from July 16, 1992.  A copy of this
@@ -13,7 +16,8 @@ draft can be found in this directory
 it to an RFC standard it has become a de-facto standard for labeled
 networking and is used in many trusted operating systems.
 
- * Outbound Packet Processing
+Outbound Packet Processing
+==========================
 
 The CIPSO/IPv4 protocol engine applies the CIPSO IP option to packets by
 adding the CIPSO label to the socket.  This causes all packets leaving the
@@ -24,7 +28,8 @@ label by using the NetLabel security module API; if the NetLabel "domain" is
 configured to use CIPSO for packet labeling then a CIPSO IP option will be
 generated and attached to the socket.
 
- * Inbound Packet Processing
+Inbound Packet Processing
+=========================
 
 The CIPSO/IPv4 protocol engine validates every CIPSO IP option it finds at the
 IP layer without any special handling required by the LSM.  However, in order
@@ -33,7 +38,8 @@ NetLabel security module API to extract the security attributes of the packet.
 This is typically done at the socket layer using the 'socket_sock_rcv_skb()'
 LSM hook.
 
- * Label Translation
+Label Translation
+=================
 
 The CIPSO/IPv4 protocol engine contains a mechanism to translate CIPSO security
 attributes such as sensitivity level and category to values which are
@@ -42,7 +48,8 @@ Domain Of Interpretation (DOI) definition and are configured through the
 NetLabel user space communication layer.  Each DOI definition can have a
 different security attribute mapping table.
 
- * Label Translation Cache
+Label Translation Cache
+=======================
 
 The NetLabel system provides a framework for caching security attribute
 mappings from the network labels to the corresponding LSM identifiers.  The
Documentation/netlabel/introduction.txt +11 -5
index 3caf77bcff0f..9333bbb0adc1 100644
@@ -1,10 +1,13 @@
+=====================
 NetLabel Introduction
-==============================================================================
+=====================
+
 Paul Moore, [email protected]
 
 August 2, 2006
 
- * Overview
+Overview
+========
 
 NetLabel is a mechanism which can be used by kernel security modules to attach
 security attributes to outgoing network packets generated from user space
@@ -12,7 +15,8 @@ applications and read security attributes from incoming network packets.  It
 is composed of three main components, the protocol engines, the communication
 layer, and the kernel security module API.
 
- * Protocol Engines
+Protocol Engines
+================
 
 The protocol engines are responsible for both applying and retrieving the
 network packet's security attributes.  If any translation between the network
@@ -24,7 +28,8 @@ the NetLabel kernel security module API described below.
 Detailed information about each NetLabel protocol engine can be found in this
 directory.
 
- * Communication Layer
+Communication Layer
+===================
 
 The communication layer exists to allow NetLabel configuration and monitoring
 from user space.  The NetLabel communication layer uses a message based
@@ -33,7 +38,8 @@ formatting of these NetLabel messages as well as the Generic NETLINK family
 names can be found in the 'net/netlabel/' directory as comments in the
 header files as well as in 'include/net/netlabel.h'.
 
- * Security Module API
+Security Module API
+===================
 
 The purpose of the NetLabel security module API is to provide a protocol
 independent interface to the underlying NetLabel protocol engines.  In addition
Documentation/netlabel/lsm_interface.txt +11 -6
index 638c74f7de7f..026fc267f798 100644
@@ -1,10 +1,13 @@
+========================================
 NetLabel Linux Security Module Interface
-==============================================================================
+========================================
+
 Paul Moore, [email protected]
 
 May 17, 2006
 
- * Overview
+Overview
+========
 
 NetLabel is a mechanism which can set and retrieve security attributes from
 network packets.  It is intended to be used by LSM developers who want to make
@@ -12,7 +15,8 @@ use of a common code base for several different packet labeling protocols.
 The NetLabel security module API is defined in 'include/net/netlabel.h' but a
 brief overview is given below.
 
- * NetLabel Security Attributes
+NetLabel Security Attributes
+============================
 
 Since NetLabel supports multiple different packet labeling protocols and LSMs
 it uses the concept of security attributes to refer to the packet's security
@@ -24,7 +28,8 @@ configuration.  It is up to the LSM developer to translate the NetLabel
 security attributes into whatever security identifiers are in use for their
 particular LSM.
 
- * NetLabel LSM Protocol Operations
+NetLabel LSM Protocol Operations
+================================
 
 These are the functions which allow the LSM developer to manipulate the labels
 on outgoing packets as well as read the labels on incoming packets.  Functions
@@ -32,7 +37,8 @@ exist to operate both on sockets as well as the sk_buffs directly.  These high
 level functions are translated into low level protocol operations based on how
 the administrator has configured the NetLabel subsystem.
 
- * NetLabel Label Mapping Cache Operations
+NetLabel Label Mapping Cache Operations
+=======================================
 
 Depending on the exact configuration, translation between the network packet
 label and the internal LSM security identifier can be time consuming.  The
--

2.20.1

Signature · 2 lines
paul moore
www.paul-moore.com
#45 lore raw

PATCH 24/57 docs: pcmcia: convert it to ReST format

In reply to Mauro Carvalho Chehab

Convert the pcmcia docs to ReST format. Most of the changes here are trivial, making Sphinx properly identify titles, lists and literal blocks.

---
 Documentation/pcmcia/devicetable.txt    |  4 +++
 Documentation/pcmcia/driver-changes.txt | 35 ++++++++++++++--------
 Documentation/pcmcia/driver.txt         | 18 ++++++------
 Documentation/pcmcia/locking.txt        | 39 +++++++++++++++++--------
 4 files changed, 63 insertions(+), 33 deletions(-)
Documentation/pcmcia/devicetable.txt +4 -0
index 5f3e00ab54c4..fd1d60d12ca1 100644
@@ -1,3 +1,7 @@
+============
+Device table
+============
+
 Matching of PCMCIA devices to drivers is done using one or more of the
 following criteria:
 
Documentation/pcmcia/driver-changes.txt +23 -12
index 78355c4c268a..33fe9ebec049 100644
@@ -1,15 +1,21 @@
+==============
+Driver changes
+==============
+
 This file details changes in 2.6 which affect PCMCIA card driver authors:
+
 * pcmcia_loop_config() and autoconfiguration (as of 2.6.36)
-   If struct pcmcia_device *p_dev->config_flags is set accordingly,
+   If `struct pcmcia_device *p_dev->config_flags` is set accordingly,
    pcmcia_loop_config() now sets up certain configuration values
    automatically, though the driver may still override the settings
    in the callback function. The following autoconfiguration options
    are provided at the moment:
-	CONF_AUTO_CHECK_VCC : check for matching Vcc
-	CONF_AUTO_SET_VPP   : set Vpp
-	CONF_AUTO_AUDIO     : auto-enable audio line, if required
-	CONF_AUTO_SET_IO    : set ioport resources (->resource[0,1])
-	CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
+
+	- CONF_AUTO_CHECK_VCC : check for matching Vcc
+	- CONF_AUTO_SET_VPP   : set Vpp
+	- CONF_AUTO_AUDIO     : auto-enable audio line, if required
+	- CONF_AUTO_SET_IO    : set ioport resources (->resource[0,1])
+	- CONF_AUTO_SET_IOMEM : set first iomem resource (->resource[2])
 
 * pcmcia_request_configuration -> pcmcia_enable_device (as of 2.6.36)
    pcmcia_request_configuration() got renamed to pcmcia_enable_device(),
@@ -19,14 +25,14 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
 
 * pcmcia_request_window changes (as of 2.6.36)
    Instead of win_req_t, drivers are now requested to fill out
-   struct pcmcia_device *p_dev->resource[2,3,4,5] for up to four ioport
+   `struct pcmcia_device *p_dev->resource[2,3,4,5]` for up to four ioport
    ranges. After a call to pcmcia_request_window(), the regions found there
    are reserved and may be used immediately -- until pcmcia_release_window()
    is called.
 
 * pcmcia_request_io changes (as of 2.6.36)
    Instead of io_req_t, drivers are now requested to fill out
-   struct pcmcia_device *p_dev->resource[0,1] for up to two ioport
+   `struct pcmcia_device *p_dev->resource[0,1]` for up to two ioport
    ranges. After a call to pcmcia_request_io(), the ports found there
    are reserved, after calling pcmcia_request_configuration(), they may
    be used.
@@ -42,7 +48,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
 * New IRQ request rules (as of 2.6.35)
    Instead of the old pcmcia_request_irq() interface, drivers may now
    choose between:
-   - calling request_irq/free_irq directly. Use the IRQ from *p_dev->irq.
+
+   - calling request_irq/free_irq directly. Use the IRQ from `*p_dev->irq`.
    - use pcmcia_request_irq(p_dev, handler_t); the PCMCIA core will
      clean up automatically on calls to pcmcia_disable_device() or
      device ejection.
@@ -72,13 +79,16 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
    exports for them were removed.
 
 * Unify detach and REMOVAL event code, as well as attach and INSERTION
-  code (as of 2.6.16)
+  code (as of 2.6.16)::
+
        void (*remove)          (struct pcmcia_device *dev);
        int (*probe)            (struct pcmcia_device *dev);
 
-* Move suspend, resume and reset out of event handler (as of 2.6.16)
+* Move suspend, resume and reset out of event handler (as of 2.6.16)::
+
        int (*suspend)          (struct pcmcia_device *dev);
        int (*resume)           (struct pcmcia_device *dev);
+
   should be initialized in struct pcmcia_driver, and handle
   (SUSPEND == RESET_PHYSICAL) and (RESUME == CARD_RESET) events
 
@@ -117,7 +127,8 @@ This file details changes in 2.6 which affect PCMCIA card driver authors:
 * core functions no longer available (as of 2.6.11)
    The following functions have been removed from the kernel source
    because they are unused by all in-kernel drivers, and no external
-   driver was reported to rely on them:
+   driver was reported to rely on them::
+
 	pcmcia_get_first_region()
 	pcmcia_get_next_region()
 	pcmcia_modify_window()
Documentation/pcmcia/driver.txt +9 -9
index 0ac167920778..5c4fe84d51c1 100644
@@ -1,16 +1,16 @@
+=============
 PCMCIA Driver
--------------
-
+=============
 
 sysfs
 -----
 
 New PCMCIA IDs may be added to a device driver pcmcia_device_id table at
-runtime as shown below:
+runtime as shown below::
 
-echo "match_flags manf_id card_id func_id function device_no \
-prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
-/sys/bus/pcmcia/drivers/{driver}/new_id
+  echo "match_flags manf_id card_id func_id function device_no \
+  prod_id_hash[0] prod_id_hash[1] prod_id_hash[2] prod_id_hash[3]" > \
+  /sys/bus/pcmcia/drivers/{driver}/new_id
 
 All fields are passed in as hexadecimal values (no leading 0x).
 The meaning is described in the PCMCIA specification, the match_flags is
@@ -22,9 +22,9 @@ PCMCIA device listed in its (newly updated) pcmcia_device_id list.
 
 A common use-case is to add a new device according to the manufacturer ID
 and the card ID (form the manf_id and card_id file in the device tree).
-For this, just use:
+For this, just use::
 
-echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
-        /sys/bus/pcmcia/drivers/{driver}/new_id
+  echo "0x3 manf_id card_id 0 0 0 0 0 0 0" > \
+    /sys/bus/pcmcia/drivers/{driver}/new_id
 
 after loading the driver.
Documentation/pcmcia/locking.txt +27 -12
index b2c9b478906b..e35257139c89 100644
@@ -1,3 +1,7 @@
+=======
+Locking
+=======
+
 This file explains the locking and exclusion scheme used in the PCCARD
 and PCMCIA subsystems.
 
@@ -5,16 +9,21 @@ and PCMCIA subsystems.
 A) Overview, Locking Hierarchy:
 ===============================
 
-pcmcia_socket_list_rwsem	- protects only the list of sockets
-- skt_mutex			- serializes card insert / ejection
-  - ops_mutex			- serializes socket operation
+pcmcia_socket_list_rwsem
+	- protects only the list of sockets
+
+- skt_mutex
+	- serializes card insert / ejection
+
+  - ops_mutex
+	- serializes socket operation
 
 
 B) Exclusion
 ============
 
 The following functions and callbacks to struct pcmcia_socket must
-be called with "skt_mutex" held:
+be called with "skt_mutex" held::
 
 	socket_detect_change()
 	send_event()
@@ -31,7 +40,7 @@ be called with "skt_mutex" held:
 	struct pcmcia_callback	*callback
 
 The following functions and callbacks to struct pcmcia_socket must
-be called with "ops_mutex" held:
+be called with "ops_mutex" held::
 
 	socket_reset()
 	socket_setup()
@@ -39,7 +48,7 @@ be called with "ops_mutex" held:
 	struct pccard_operations	*ops
 	struct pccard_resource_ops	*resource_ops;
 
-Note that send_event() and struct pcmcia_callback *callback must not be
+Note that send_event() and `struct pcmcia_callback *callback` must not be
 called with "ops_mutex" held.
 
 
@@ -60,19 +69,23 @@ The resource_ops and their data are protected by ops_mutex.
 The "main" struct pcmcia_socket is protected as follows (read-only fields
 or single-use fields not mentioned):
 
-- by pcmcia_socket_list_rwsem:
+- by pcmcia_socket_list_rwsem::
+
 	struct list_head	socket_list;
 
-- by thread_lock:
+- by thread_lock::
+
 	unsigned int		thread_events;
 
-- by skt_mutex:
+- by skt_mutex::
+
 	u_int			suspended_state;
 	void			(*tune_bridge);
 	struct pcmcia_callback	*callback;
 	int			resume_status;
 
-- by ops_mutex:
+- by ops_mutex::
+
 	socket_state_t		socket;
 	u_int			state;
 	u_short			lock_count;
@@ -100,7 +113,8 @@ The "main" struct pcmcia_device is protected as follows (read-only fields
 or single-use fields not mentioned):
 
 
-- by pcmcia_socket->ops_mutex:
+- by pcmcia_socket->ops_mutex::
+
 	struct list_head	socket_device_list;
 	struct config_t		*function_config;
 	u16			_irq:1;
@@ -111,7 +125,8 @@ or single-use fields not mentioned):
 	u16			suspended:1;
 	u16			_removed:1;
 
-- by the PCMCIA driver:
+- by the PCMCIA driver::
+
 	io_req_t		io;
 	irq_req_t		irq;
 	config_req_t		conf;
Signature · 1 line
2.20.1
#47 lore raw

PATCH 25/57 docs: power: convert docs to ReST

In reply to Mauro Carvalho Chehab

Convert the PM documents to ReST, in order to allow them to build with Sphinx.

---
 Documentation/power/apm-acpi.txt              |  10 +-
 Documentation/power/basic-pm-debugging.txt    |  77 ++-
 Documentation/power/charger-manager.txt       | 101 +--
 Documentation/power/drivers-testing.txt       |   5 +
 Documentation/power/energy-model.txt          | 101 +--
 Documentation/power/freezing-of-tasks.txt     |  91 +--
 Documentation/power/interface.txt             |  20 +-
 Documentation/power/opp.txt                   | 175 +++--
 Documentation/power/pci.txt                   |  77 ++-
 Documentation/power/pm_qos_interface.txt      | 127 ++--
 Documentation/power/power_supply_class.txt    | 269 +++++---
 Documentation/power/powercap/powercap.txt     | 297 ++++----
 Documentation/power/regulator/consumer.txt    | 141 ++--
 Documentation/power/regulator/design.txt      |   9 +-
 Documentation/power/regulator/machine.txt     |  47 +-
 Documentation/power/regulator/overview.txt    |  51 +-
 Documentation/power/regulator/regulator.txt   |  18 +-
 Documentation/power/runtime_pm.txt            | 234 ++++---
 Documentation/power/s2ram.txt                 |  20 +-
 .../power/suspend-and-cpuhotplug.txt          |  42 +-
 .../power/suspend-and-interrupts.txt          |   2 +
 Documentation/power/swsusp-and-swap-files.txt |  15 +-
 Documentation/power/swsusp-dmcrypt.txt        | 118 ++--
 Documentation/power/swsusp.txt                | 639 ++++++++++--------
 Documentation/power/tricks.txt                |   6 +-
 Documentation/power/userland-swsusp.txt       |  53 +-
 Documentation/power/video.txt                 | 156 +++--
 27 files changed, 1637 insertions(+), 1264 deletions(-)
Documentation/power/apm-acpi.txt +7 -3
index 6cc423d3662e..5b90d947126d 100644
@@ -1,5 +1,7 @@
+============
 APM or ACPI?
-------------
+============
+
 If you have a relatively recent x86 mobile, desktop, or server system,
 odds are it supports either Advanced Power Management (APM) or
 Advanced Configuration and Power Interface (ACPI).  ACPI is the newer
@@ -28,5 +30,7 @@ and be sure that they are started sometime in the system boot process.
 Go ahead and start both.  If ACPI or APM is not available on your
 system the associated daemon will exit gracefully.
 
-  apmd:   http://ftp.debian.org/pool/main/a/apmd/
-  acpid:  http://acpid.sf.net/
+  =====  =======================================
+  apmd   http://ftp.debian.org/pool/main/a/apmd/
+  acpid  http://acpid.sf.net/
+  =====  =======================================
Documentation/power/basic-pm-debugging.txt +46 -31

176 lines not on this page · raw message

Documentation/power/charger-manager.txt +53 -48

174 lines not on this page · raw message

Documentation/power/drivers-testing.txt +5 -0
index 638afdf4d6b8..10f65eac1328 100644
@@ -1,7 +1,11 @@
+====================================================
 Testing suspend and resume support in device drivers
+====================================================
+
 	(C) 2007 Rafael J. Wysocki <[email protected]>, GPL
 
 1. Preparing the test system
+============================
 
 Unfortunately, to effectively test the support for the system-wide suspend and
 resume transitions in a driver, it is necessary to suspend and resume a fully
@@ -18,6 +22,7 @@ testing the new driver.  Please see Documentation/power/basic-pm-debugging.txt
 for more information about the debugging of suspend/resume functionality.
 
 2. Testing the driver
+=====================
 
 Once you have resolved the suspend/resume-related problems with your test system
 without the new driver, you are ready to test it:
Documentation/power/energy-model.txt +52 -49

133 lines not on this page · raw message

Documentation/power/freezing-of-tasks.txt +52 -39

169 lines not on this page · raw message

Documentation/power/interface.txt +11 -9
index 27df7f98668a..6e22a4d02d4b 100644
@@ -1,4 +1,6 @@
+===========================================
 Power Management Interface for System Sleep
+===========================================
 
 Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <[email protected]>
 
@@ -11,10 +13,10 @@ mounted at /sys).
 
 Reading from it returns a list of supported sleep states, encoded as:
 
-'freeze' (Suspend-to-Idle)
-'standby' (Power-On Suspend)
-'mem' (Suspend-to-RAM)
-'disk' (Suspend-to-Disk)
+- 'freeze' (Suspend-to-Idle)
+- 'standby' (Power-On Suspend)
+- 'mem' (Suspend-to-RAM)
+- 'disk' (Suspend-to-Disk)
 
 Suspend-to-Idle is always supported.  Suspend-to-Disk is always supported
 too as long the kernel has been configured to support hibernation at all
@@ -32,11 +34,11 @@ Specifically, it tells the kernel what to do after creating a hibernation image.
 
 Reading from it returns a list of supported options encoded as:
 
-'platform' (put the system into sleep using a platform-provided method)
-'shutdown' (shut the system down)
-'reboot' (reboot the system)
-'suspend' (trigger a Suspend-to-RAM transition)
-'test_resume' (resume-after-hibernation test mode)
+- 'platform' (put the system into sleep using a platform-provided method)
+- 'shutdown' (shut the system down)
+- 'reboot' (reboot the system)
+- 'suspend' (trigger a Suspend-to-RAM transition)
+- 'test_resume' (resume-after-hibernation test mode)
 
 The currently selected option is printed in square brackets.
 
Documentation/power/opp.txt +106 -69

320 lines not on this page · raw message

Documentation/power/pci.txt +59 -18

360 lines not on this page · raw message

Documentation/power/pm_qos_interface.txt +70 -57

203 lines not on this page · raw message

Documentation/power/power_supply_class.txt +160 -109

303 lines not on this page · raw message

Documentation/power/powercap/powercap.txt +159 -138

359 lines not on this page · raw message

Documentation/power/regulator/consumer.txt +76 -65

264 lines not on this page · raw message

Documentation/power/regulator/design.txt +7 -2
index fdd919b96830..3b09c6841dc4 100644
@@ -1,3 +1,4 @@
+==========================
 Regulator API design notes
 ==========================
 
@@ -14,7 +15,9 @@ Safety
    have different power requirements, and not all components with power
    requirements are visible to software.
 
-  => The API should make no changes to the hardware state unless it has
+.. note::
+
+     The API should make no changes to the hardware state unless it has
      specific knowledge that these changes are safe to perform on this
      particular system.
 
@@ -28,6 +31,8 @@ Consumer use cases
  - Many of the power supplies in the system will be shared between many
    different consumers.
 
-  => The consumer API should be structured so that these use cases are
+.. note::
+
+     The consumer API should be structured so that these use cases are
      very easy to handle and so that consumers will work with shared
      supplies without any additional effort.
Documentation/power/regulator/machine.txt +24 -23

101 lines not on this page · raw message

Documentation/power/regulator/overview.txt +29 -22

104 lines not on this page · raw message

Documentation/power/regulator/regulator.txt +10 -8
index b17e5833ce21..794b3256fbb9 100644
@@ -1,3 +1,4 @@
+==========================
 Regulator Driver Interface
 ==========================
 
@@ -8,23 +9,24 @@ regulator drivers to register their services with the core framework.
 Registration
 ============
 
-Drivers can register a regulator by calling :-
+Drivers can register a regulator by calling::
 
-struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
-					 const struct regulator_config *config);
+  struct regulator_dev *regulator_register(struct regulator_desc *regulator_desc,
+					   const struct regulator_config *config);
 
 This will register the regulator's capabilities and operations to the regulator
 core.
 
-Regulators can be unregistered by calling :-
+Regulators can be unregistered by calling::
 
-void regulator_unregister(struct regulator_dev *rdev);
+  void regulator_unregister(struct regulator_dev *rdev);
 
 
 Regulator Events
 ================
+
 Regulators can send events (e.g. overtemperature, undervoltage, etc) to
-consumer drivers by calling :-
+consumer drivers by calling::
 
-int regulator_notifier_call_chain(struct regulator_dev *rdev,
-				  unsigned long event, void *data);
+  int regulator_notifier_call_chain(struct regulator_dev *rdev,
+				    unsigned long event, void *data);
Documentation/power/runtime_pm.txt +123 -111

204 lines not on this page · raw message

Documentation/power/s2ram.txt +11 -9
index 4685aee197fd..d739aa7c742c 100644

Lines of this file are not shown. View the raw message.

Documentation/power/suspend-and-cpuhotplug.txt +26 -16

42 lines not on this page · raw message

Documentation/power/suspend-and-interrupts.txt +2 -0
index 8afb29a8604a..4cda6617709a 100644

Lines of this file are not shown. View the raw message.

Documentation/power/swsusp-and-swap-files.txt +9 -6
index f281886de490..b3188d9ca538 100644

Lines of this file are not shown. View the raw message.

Documentation/power/swsusp-dmcrypt.txt +60 -58

118 lines not on this page · raw message

Documentation/power/swsusp.txt +347 -292

639 lines not on this page · raw message

Documentation/power/tricks.txt +4 -2
index a1b8f7249f4c..ca787f142c3f 100644

Lines of this file are not shown. View the raw message.

Documentation/power/userland-swsusp.txt +37 -16

53 lines not on this page · raw message

Documentation/power/video.txt +92 -64

156 lines not on this page · raw message

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.20.1

Part of the diff is not shown here. View the raw message.

Acked-by on v1 25/57
#48 lore raw

Re: [PATCH 25/57] docs: power: convert docs to ReST

Quoted 4 lines · Mauro Carvalho Chehab

Convert the PM documents to ReST, in order to allow them to build with Sphinx.

Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
#49 lore raw

Re: [PATCH 25/57] docs: power: convert docs to ReST

In reply to Mauro Carvalho Chehab
Quoted 2 lines · CEST Mauro Carvalho Chehab

Convert the PM documents to ReST, in order to allow them to build with Sphinx.

And what exactly is the motivation for doing that?

There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.

Thanks,
Rafael

#50 lore raw

Re: [PATCH 25/57] docs: power: convert docs to ReST

Em Tue, 16 Apr 2019 10:59:23 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:

Quoted 5 lines · CEST Mauro Carvalho Chehab
Quoted 2 lines

Convert the PM documents to ReST, in order to allow them to build with Sphinx.

And what exactly is the motivation for doing that?

Providing a little of context, I tried to submit a patchset that would just place existing documents on a sort of "staging" way, without actually reformatting:

	https://lkml.org/lkml/2019/4/10/244

Jon had some concerns about such approach.

So, I split into one patch per subsystem. Then, I looked on each, and opted to do the conversion, as, on several cases, the conversion seemed to be easy enough.

My selfish motivation is that I was returning from vacations and wanted to review some stuff at the Kernel docs, but, discovered that, despite we started migrating the documentation on May, 2016, still the vast majority of documents that weren't converted.

For me, the main motivation for the conversion are:

1) Documents will be grouped into books and chapters, with makes easier to study them;
2) The Sphinx javascript is very convenient for seeking a document and a keyword within the body of the document;
3) Using a browser to read documentation allows to better scale the document to the screen I'm using.

That's said, sometimes I just prefer to convert the document to a PDF and read it on my tablet. PDF tools also provide similar features.

In other words, for my own consumption, I prefer reading documents using document tools, instead of reading in plain text.

Quoted 1 line

There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.

Feel free to use this patch as an starting point. If you prefer, I can split into smaller sets, but my main goal here is just to help to speedup the conversion.

Thanks,
Mauro

#51 lore raw

Re: [PATCH 25/57] docs: power: convert docs to ReST

Quoted 36 lines · Mauro Carvalho Chehab

Em Tue, 16 Apr 2019 10:59:23 +0200
"Rafael J. Wysocki" <[email protected]> escreveu:

Quoted 5 lines · CEST Mauro Carvalho Chehab
Quoted 2 lines

Convert the PM documents to ReST, in order to allow them to build with Sphinx.

And what exactly is the motivation for doing that?

Providing a little of context, I tried to submit a patchset that would just place existing documents on a sort of "staging" way, without actually reformatting:

        https://lkml.org/lkml/2019/4/10/244

Jon had some concerns about such approach.

So, I split into one patch per subsystem. Then, I looked on each, and opted to do the conversion, as, on several cases, the conversion seemed to be easy enough.

My selfish motivation is that I was returning from vacations and wanted to review some stuff at the Kernel docs, but, discovered that, despite we started migrating the documentation on May, 2016, still the vast majority of documents that weren't converted.

For me, the main motivation for the conversion are:

1) Documents will be grouped into books and chapters, with makes easier to study them;
2) The Sphinx javascript is very convenient for seeking a document and a keyword within the body of the document;
3) Using a browser to read documentation allows to better scale the document to the screen I'm using.

Quoted 7 lines

That's said, sometimes I just prefer to convert the document to a PDF and read it on my tablet. PDF tools also provide similar features.

In other words, for my own consumption, I prefer reading documents using document tools, instead of reading in plain text.

I see, thanks!

Quoted 5 lines
Quoted 1 line

There are plans for some of these files to be converted already, some of them need to be merged or split and it just is not worth it to convert some others.

Feel free to use this patch as an starting point. If you prefer, I can split into smaller sets, but my main goal here is just to help to speedup the conversion.

OK, we'll see. Thank you!

#52 lore raw

PATCH 26/57 docs: powerpc: convert docs to ReST

In reply to Mauro Carvalho Chehab

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.

---
 Documentation/powerpc/DAWR-POWER9.txt         |  10 +-
 Documentation/powerpc/bootwrapper.txt         |  28 ++-
 Documentation/powerpc/cpu_families.txt        |  23 +--
 Documentation/powerpc/cpu_features.txt        |   6 +-
 Documentation/powerpc/cxl.txt                 |  46 +++--
 Documentation/powerpc/cxlflash.txt            |   8 +-
 Documentation/powerpc/dscr.txt                |  18 +-
 .../powerpc/eeh-pci-error-recovery.txt        | 108 +++++------
 .../powerpc/firmware-assisted-dump.txt        | 117 ++++++------
 Documentation/powerpc/hvcs.txt                | 108 ++++++-----
 Documentation/powerpc/isa-versions.rst        |  13 +-
 Documentation/powerpc/mpc52xx.txt             |  12 +-
 .../powerpc/pci_iov_resource_on_powernv.txt   |  15 +-
 Documentation/powerpc/pmu-ebb.txt             |   1 +
 Documentation/powerpc/ptrace.txt              | 169 +++++++++---------
 Documentation/powerpc/qe_firmware.txt         |  37 ++--
 Documentation/powerpc/syscall64-abi.txt       |  29 +--
 .../powerpc/transactional_memory.txt          |  45 ++---
 18 files changed, 447 insertions(+), 346 deletions(-)
Documentation/powerpc/DAWR-POWER9.txt +5 -5
index 2feaa6619658..882e5af02b9c 100644
@@ -1,10 +1,11 @@
+=====================
 DAWR issues on POWER9
-============================
+=====================
 
 On POWER9 the 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:
+this commit::
 
     commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
     Author: Michael Neuling <[email protected]>
@@ -12,7 +13,7 @@ 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
@@ -55,4 +56,3 @@ guest is migrated to a POWER9 host, the watchpoint will be lost on the
 POWER9. Loads and stores to the watchpoint locations will not be
 trapped in GDB. The watchpoint is remembered, so if the guest is
 migrated back to the POWER8 host, it will start working again.
-
Documentation/powerpc/bootwrapper.txt +21 -7
index d60fced5e1cc..a6292afba573 100644
@@ -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
Documentation/powerpc/cpu_families.txt +12 -11
index fc08e22feb1a..1e063c5440c3 100644
@@ -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       |
Documentation/powerpc/cpu_features.txt +5 -1
index ae09df8722c8..b7bcdd2f41bb 100644
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
 Hollis Blanchard <[email protected]>
 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
Documentation/powerpc/cxl.txt +32 -14

133 lines not on this page · raw message

Documentation/powerpc/cxlflash.txt +6 -2
index a64bdaa0a1cf..9d79962f1999 100644
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
 Introduction
 ============
 
@@ -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.
Documentation/powerpc/dscr.txt +11 -7
index ece300c64f76..2ab99006014c 100644
@@ -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
Documentation/powerpc/eeh-pci-error-recovery.txt +55 -53

176 lines not on this page · raw message

Documentation/powerpc/firmware-assisted-dump.txt +63 -54

253 lines not on this page · raw message

Documentation/powerpc/hvcs.txt +61 -47

343 lines not on this page · raw message

Documentation/powerpc/isa-versions.rst +7 -6
index 812e20cc898c..a363d8c1603c 100644
@@ -1,11 +1,12 @@
+==========================
 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
@@ -22,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
@@ -58,9 +59,9 @@ Power5     No
 PPC970     No
 ========== ====
 
-========== ====================
+========== ====================================
 CPU        Transactional Memory
-========== ====================
+========== ====================================
 Power9     Yes (* see transactional_memory.txt)
 Power8     Yes
 Power7     No
@@ -71,4 +72,4 @@ Power5++   No
 Power5+    No
 Power5     No
 PPC970     No
-========== ====================
+========== ====================================
Documentation/powerpc/mpc52xx.txt +8 -4
index 0d540a31ea1a..8676ac63e077 100644
@@ -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
Documentation/powerpc/pci_iov_resource_on_powernv.txt +13 -2
index b55c5cd83f8d..f5a5793e1613 100644
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
 Wei Yang <[email protected]>
+
 Benjamin Herrenschmidt <[email protected]>
+
 Bjorn Helgaas <[email protected]>
+
 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.
Documentation/powerpc/pmu-ebb.txt +1 -0
index 73cd163dbfb8..4f474758eb55 100644
@@ -1,3 +1,4 @@
+========================
 PMU Event Based Branches
 ========================
 
Documentation/powerpc/ptrace.txt +87 -82

212 lines not on this page · raw message

Documentation/powerpc/qe_firmware.txt +19 -18
index e7ac24aec4ff..42f5103140c9 100644
@@ -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
 ============================================
Documentation/powerpc/syscall64-abi.txt +17 -12
index fa716a0d88bd..e49f69f941b9 100644
@@ -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
 ----------
Documentation/powerpc/transactional_memory.txt +24 -21

91 lines not on this page · raw message

Signature · 1 line
2.20.1
#53 lore raw

PATCH 27/57 docs: pps/pps.txt convert it to ReST and move to API book

In reply to Mauro Carvalho Chehab

This file is already in a good shape: just its title and adding some literal block markups is needed for it to be part of the document.

While it has a small chapter with sysfs stuff, most of the document is focused on driver development.

---
 Documentation/pps/pps.txt | 67 ++++++++++++++++++++-------------------
 1 file changed, 34 insertions(+), 33 deletions(-)
Documentation/pps/pps.txt +34 -33
index 99f5d8c4c652..262151a6dad5 100644
@@ -1,8 +1,8 @@
+======================
+PPS - Pulse Per Second
+======================
 
-			PPS - Pulse Per Second
-			----------------------
-
-(C) Copyright 2007 Rodolfo Giometti <[email protected]>
+Copyright (C) 2007 Rodolfo Giometti <[email protected]>
 
 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
@@ -88,7 +88,7 @@ Coding example
 --------------
 
 To register a PPS source into the kernel you should define a struct
-pps_source_info as follows:
+pps_source_info as follows::
 
     static struct pps_source_info pps_ktimer_info = {
 	    .name         = "ktimer",
@@ -101,12 +101,12 @@ pps_source_info as follows:
     };
 
 and then calling the function pps_register_source() in your
-initialization routine as follows:
+initialization routine as follows::
 
     source = pps_register_source(&pps_ktimer_info,
 			PPS_CAPTUREASSERT | PPS_OFFSETASSERT);
 
-The pps_register_source() prototype is:
+The pps_register_source() prototype is::
 
   int pps_register_source(struct pps_source_info *info, int default_params)
 
@@ -118,7 +118,7 @@ pps_source_info which describe the capabilities of the driver).
 
 Once you have registered a new PPS source into the system you can
 signal an assert event (for example in the interrupt handler routine)
-just using:
+just using::
 
     pps_event(source, &ts, PPS_CAPTUREASSERT, ptr)
 
@@ -134,13 +134,13 @@ Please see the file drivers/pps/clients/pps-ktimer.c for example code.
 SYSFS support
 -------------
 
-If the SYSFS filesystem is enabled in the kernel it provides a new class:
+If the SYSFS filesystem is enabled in the kernel it provides a new class::
 
    $ ls /sys/class/pps/
    pps0/  pps1/  pps2/
 
 Every directory is the ID of a PPS sources defined in the system and
-inside you find several files:
+inside you find several files::
 
    $ ls -F /sys/class/pps/pps0/
    assert     dev        mode       path       subsystem@
@@ -148,7 +148,7 @@ inside you find several files:
 
 
 Inside each "assert" and "clear" file you can find the timestamp and a
-sequence number:
+sequence number::
 
    $ cat /sys/class/pps/pps0/assert
    1170026870.983207967#8
@@ -175,11 +175,11 @@ and the userland tools available in your distribution's pps-tools package,
 http://linuxpps.org , or https://github.com/redlab-i/pps-tools.
 
 Once you have enabled the compilation of pps-ktimer just modprobe it (if
-not statically compiled):
+not statically compiled)::
 
    # modprobe pps-ktimer
 
-and the run ppstest as follow:
+and the run ppstest as follow::
 
    $ ./ppstest /dev/pps1
    trying PPS source "/dev/pps1"
@@ -204,26 +204,27 @@ nor affordable. The cheap way is to load a PPS generator on one of the
 computers (master) and PPS clients on others (slaves), and use very simple
 cables to deliver signals using parallel ports, for example.
 
-Parallel port cable pinout:
-pin	name	master      slave
-1	STROBE	  *------     *
-2	D0	  *     |     *
-3	D1	  *     |     *
-4	D2	  *     |     *
-5	D3	  *     |     *
-6	D4	  *     |     *
-7	D5	  *     |     *
-8	D6	  *     |     *
-9	D7	  *     |     *
-10	ACK	  *     ------*
-11	BUSY	  *           *
-12	PE	  *           *
-13	SEL	  *           *
-14	AUTOFD	  *           *
-15	ERROR	  *           *
-16	INIT	  *           *
-17	SELIN	  *           *
-18-25	GND	  *-----------*
+Parallel port cable pinout::
+
+	pin	name	master      slave
+	1	STROBE	  *------     *
+	2	D0	  *     |     *
+	3	D1	  *     |     *
+	4	D2	  *     |     *
+	5	D3	  *     |     *
+	6	D4	  *     |     *
+	7	D5	  *     |     *
+	8	D6	  *     |     *
+	9	D7	  *     |     *
+	10	ACK	  *     ------*
+	11	BUSY	  *           *
+	12	PE	  *           *
+	13	SEL	  *           *
+	14	AUTOFD	  *           *
+	15	ERROR	  *           *
+	16	INIT	  *           *
+	17	SELIN	  *           *
+	18-25	GND	  *-----------*
 
 Please note that parallel port interrupt occurs only on high->low transition,
 so it is used for PPS assert edge. PPS clear edge can be determined only
Signature · 1 line
2.20.1
#54 lore raw

PATCH 28/57 docs: ptp.txt: convert to ReST and move to driver-api

In reply to Mauro Carvalho Chehab

The conversion is trivial: just adjust title markups.

---
 Documentation/ptp/ptp.txt | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)
Documentation/ptp/ptp.txt +17 -9
index 11e904ee073f..65c84a72e9fc 100644
@@ -1,5 +1,6 @@
-
-* PTP hardware clock infrastructure for Linux
+===========================================
+PTP hardware clock infrastructure for Linux
+===========================================
 
   This patch set introduces support for IEEE 1588 PTP clocks in
   Linux. Together with the SO_TIMESTAMPING socket options, this
@@ -22,7 +23,8 @@
     - Period output signals configurable from user space
     - Synchronization of the Linux system time via the PPS subsystem
 
-** PTP hardware clock kernel API
+PTP hardware clock kernel API
+=============================
 
    A PTP clock driver registers itself with the class driver. The
    class driver handles all of the dealings with user space. The
@@ -36,7 +38,8 @@
    development, it can be useful to have more than one clock in a
    single system, in order to allow performance comparisons.
 
-** PTP hardware clock user space API
+PTP hardware clock user space API
+=================================
 
    The class driver also creates a character device for each
    registered clock. User space can use an open file descriptor from
@@ -49,7 +52,8 @@
    ancillary clock features. User space can receive time stamped
    events via blocking read() and poll().
 
-** Writing clock drivers
+Writing clock drivers
+=====================
 
    Clock drivers include include/linux/ptp_clock_kernel.h and register
    themselves by presenting a 'struct ptp_clock_info' to the
@@ -66,14 +70,17 @@
    class driver, since the lock may also be needed by the clock
    driver's interrupt service routine.
 
-** Supported hardware
+Supported hardware
+==================
+
+   * Freescale eTSEC gianfar
 
-   + Freescale eTSEC gianfar
      - 2 Time stamp external triggers, programmable polarity (opt. interrupt)
      - 2 Alarm registers (optional interrupt)
      - 3 Periodic signals (optional interrupt)
 
-   + National DP83640
+   * National DP83640
+
      - 6 GPIOs programmable as inputs or outputs
      - 6 GPIOs with dedicated functions (LED/JTAG/clock) can also be
        used as general inputs or outputs
@@ -81,6 +88,7 @@
      - GPIO outputs can produce periodic signals
      - 1 interrupt pin
 
-   + Intel IXP465
+   * Intel IXP465
+
      - Auxiliary Slave/Master Mode Snapshot (optional interrupt)
      - Target Time (optional interrupt)
Signature · 1 line
2.20.1
#55 lore raw

PATCH 29/57 docs: riscv: convert it to ReST format

In reply to Mauro Carvalho Chehab

The conversion here is trivial:
- Adjust the document title's markup
- Do some whitespace alignment;
- mark literal blocks;
- Use ReST way to markup indented lists.

---
 Documentation/riscv/pmu.txt | 98 ++++++++++++++++++++-----------------
 1 file changed, 52 insertions(+), 46 deletions(-)
Documentation/riscv/pmu.txt +52 -46
index b29f03a6d82f..acb216b99c26 100644
@@ -1,5 +1,7 @@
+===================================
 Supporting PMUs on RISC-V platforms
-==========================================
+===================================
+
 Alan Kao <[email protected]>, Mar 2018
 
 Introduction
@@ -77,13 +79,13 @@ Note that some features can be done in this stage as well:
 (2) privilege level setting (user space only, kernel space only, both);
 (3) destructor setting.  Normally it is sufficient to apply *riscv_destroy_event*;
 (4) tweaks for non-sampling events, which will be utilized by functions such as
-*perf_adjust_period*, usually something like the follows:
+    *perf_adjust_period*, usually something like the follows::
 
-if (!is_sampling_event(event)) {
-        hwc->sample_period = x86_pmu.max_period;
-        hwc->last_period = hwc->sample_period;
-        local64_set(&hwc->period_left, hwc->sample_period);
-}
+      if (!is_sampling_event(event)) {
+              hwc->sample_period = x86_pmu.max_period;
+              hwc->last_period = hwc->sample_period;
+              local64_set(&hwc->period_left, hwc->sample_period);
+      }
 
 In the case of *riscv_base_pmu*, only (3) is provided for now.
 
@@ -94,10 +96,10 @@ In the case of *riscv_base_pmu*, only (3) is provided for now.
 3.1. Interrupt Initialization
 
 This often occurs at the beginning of the *event_init* method. In common
-practice, this should be a code segment like
+practice, this should be a code segment like::
 
-int x86_reserve_hardware(void)
-{
+  int x86_reserve_hardware(void)
+  {
         int err = 0;
 
         if (!atomic_inc_not_zero(&pmc_refcount)) {
@@ -114,7 +116,7 @@ int x86_reserve_hardware(void)
         }
 
         return err;
-}
+  }
 
 And the magic is in *reserve_pmc_hardware*, which usually does atomic
 operations to make implemented IRQ accessible from some global function pointer.
@@ -128,28 +130,28 @@ which will be introduced in the next section.)
 
 3.2. IRQ Structure
 
-Basically, a IRQ runs the following pseudo code:
+Basically, a IRQ runs the following pseudo code::
 
-for each hardware counter that triggered this overflow
+  for each hardware counter that triggered this overflow
 
-    get the event of this counter
+      get the event of this counter
 
-    // following two steps are defined as *read()*,
-    // check the section Reading/Writing Counters for details.
-    count the delta value since previous interrupt
-    update the event->count (# event occurs) by adding delta, and
-               event->hw.period_left by subtracting delta
+      // following two steps are defined as *read()*,
+      // check the section Reading/Writing Counters for details.
+      count the delta value since previous interrupt
+      update the event->count (# event occurs) by adding delta, and
+                 event->hw.period_left by subtracting delta
 
-    if the event overflows
-        sample data
-        set the counter appropriately for the next overflow
+      if the event overflows
+          sample data
+          set the counter appropriately for the next overflow
 
-        if the event overflows again
-            too frequently, throttle this event
-        fi
-    fi
+          if the event overflows again
+              too frequently, throttle this event
+          fi
+      fi
 
-end for
+  end for
 
 However as of this writing, none of the RISC-V implementations have designed an
 interrupt for perf, so the details are to be completed in the future.
@@ -195,23 +197,26 @@ A normal flow of these state transitions are as follows:
   At this stage, a general event is bound to a physical counter, if any.
   The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, because it is now
   stopped, and the (software) event count does not need updating.
-** *start* is then called, and the counter is enabled.
-   With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
-   previous section for detail).
-   Nothing is written if the flag does not contain PERF_EF_RELOAD.
-   The state now is reset to none, because it is neither stopped nor updated
-   (the counting already started)
+
+  - *start* is then called, and the counter is enabled.
+    With flag PERF_EF_RELOAD, it writes an appropriate value to the counter (check
+    previous section for detail).
+    Nothing is written if the flag does not contain PERF_EF_RELOAD.
+    The state now is reset to none, because it is neither stopped nor updated
+    (the counting already started)
+
 * When being context-switched out, *del* is called.  It then checks out all the
   events in the PMU and calls *stop* to update their counts.
-** *stop* is called by *del*
-   and the perf core with flag PERF_EF_UPDATE, and it often shares the same
-   subroutine as *read* with the same logic.
-   The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
 
-** Life cycle of these two pairs: *add* and *del* are called repeatedly as
-  tasks switch in-and-out; *start* and *stop* is also called when the perf core
-  needs a quick stop-and-start, for instance, when the interrupt period is being
-  adjusted.
+  - *stop* is called by *del*
+    and the perf core with flag PERF_EF_UPDATE, and it often shares the same
+    subroutine as *read* with the same logic.
+    The state changes to PERF_HES_STOPPED and PERF_HES_UPTODATE, again.
+
+  - Life cycle of these two pairs: *add* and *del* are called repeatedly as
+    tasks switch in-and-out; *start* and *stop* is also called when the perf core
+    needs a quick stop-and-start, for instance, when the interrupt period is being
+    adjusted.
 
 Current implementation is sufficient for now and can be easily extended to
 features in the future.
@@ -225,25 +230,26 @@ A. Related Structures
   Both structures are designed to be read-only.
 
   *struct pmu* defines some function pointer interfaces, and most of them take
-*struct perf_event* as a main argument, dealing with perf events according to
-perf's internal state machine (check kernel/events/core.c for details).
+  *struct perf_event* as a main argument, dealing with perf events according to
+  perf's internal state machine (check kernel/events/core.c for details).
 
   *struct riscv_pmu* defines PMU-specific parameters.  The naming follows the
-convention of all other architectures.
+  convention of all other architectures.
 
 * struct perf_event: include/linux/perf_event.h
 * struct hw_perf_event
 
   The generic structure that represents perf events, and the hardware-related
-details.
+  details.
 
 * struct riscv_hw_events: arch/riscv/include/asm/perf_event.h
 
   The structure that holds the status of events, has two fixed members:
-the number of events and the array of the events.
+  the number of events and the array of the events.
 
 References
 ----------
 
 [1] https://github.com/riscv/riscv-linux/pull/124
+
 [2] https://groups.google.com/a/groups.riscv.org/forum/#!topic/sw-dev/f19TmCNP6yA
Signature · 7 lines
2.20.1


_______________________________________________
linux-riscv mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-riscv
#56 lore raw

PATCH 30/57 docs: s390: Debugging390.txt: convert table to ascii artwork

In reply to Mauro Carvalho Chehab

The first bit/value table inside the document is very hard to read and won't fit ReST format. Convert it to a nice ascii artwork table with makes it easier to read and is compatible with ReST format parser on Sphinx.

---
 Documentation/s390/Debugging390.txt | 210 ++++++++++++++++------------
 1 file changed, 120 insertions(+), 90 deletions(-)
Documentation/s390/Debugging390.txt +120 -90
index 5ae7f868a007..c35804c238ad 100644
@@ -78,96 +78,126 @@ e.g. switching address translation off requires that you
 have a logical=physical mapping for the address you are
 currently running at.
 
-      Bit           Value
-s/390 z/Architecture
-0       0     Reserved ( must be 0 ) otherwise specification exception occurs.
-
-1       1     Program Event Recording 1 PER enabled, 
-	      PER is used to facilitate debugging e.g. single stepping.
-
-2-4    2-4    Reserved ( must be 0 ). 
-
-5       5     Dynamic address translation 1=DAT on.
-
-6       6     Input/Output interrupt Mask
-
-7	7     External interrupt Mask used primarily for interprocessor
-	      signalling and clock interrupts.
-
-8-11  8-11    PSW Key used for complex memory protection mechanism
-	      (not used under linux)
-
-12      12    1 on s/390 0 on z/Architecture
-
-13      13    Machine Check Mask 1=enable machine check interrupts
-
-14	14    Wait State. Set this to 1 to stop the processor except for
-	      interrupts and give  time to other LPARS. Used in CPU idle in
-	      the kernel to increase overall usage of processor resources.
-
-15      15    Problem state ( if set to 1 certain instructions are disabled )
-	      all linux user programs run with this bit 1 
-	      ( useful info for debugging under VM ).
-
-16-17 16-17   Address Space Control
-
-	      00 Primary Space Mode:
-	      The register CR1 contains the primary address-space control ele-
-	      ment (PASCE), which points to the primary space region/segment
-	      table origin.
-
-	      01 Access register mode
-
-	      10 Secondary Space Mode:
-	      The register CR7 contains the secondary address-space control
-	      element (SASCE), which points to the secondary space region or
-	      segment table origin.
-
-	      11 Home Space Mode:
-	      The register CR13 contains the home space address-space control
-	      element (HASCE), which points to the home space region/segment
-	      table origin.
-
-	      See "Address Spaces on Linux for s/390 & z/Architecture" below
-	      for more information about address space usage in Linux.
-
-18-19 18-19   Condition codes (CC)
-
-20    20      Fixed point overflow mask if 1=FPU exceptions for this event 
-              occur ( normally 0 ) 
-
-21    21      Decimal overflow mask if 1=FPU exceptions for this event occur 
-              ( normally 0 )
-
-22    22      Exponent underflow mask if 1=FPU exceptions for this event occur 
-              ( normally 0 )
-
-23    23      Significance Mask if 1=FPU exceptions for this event occur 
-              ( normally 0 )
-
-24-31 24-30   Reserved Must be 0.
-
-      31      Extended Addressing Mode
-      32      Basic Addressing Mode
-              Used to set addressing mode
-	      PSW 31   PSW 32
-                0         0        24 bit
-                0         1        31 bit
-                1         1        64 bit
-
-32             1=31 bit addressing mode 0=24 bit addressing mode (for backward 
-               compatibility), linux always runs with this bit set to 1
-
-33-64          Instruction address.
-      33-63    Reserved must be 0
-      64-127   Address
-               In 24 bits mode bits 64-103=0 bits 104-127 Address 
-               In 31 bits mode bits 64-96=0 bits 97-127 Address
-               Note: unlike 31 bit mode on s/390 bit 96 must be zero
-	       when loading the address with LPSWE otherwise a 
-               specification exception occurs, LPSW is fully backward
-               compatible.
-
++-------------------------+-------------------------------------------------+
+|          Bit            |                                                 |
++--------+----------------+                     Value                       |
+| s/390  | z/Architecture |                                                 |
++========+================+=================================================+
+| 0      |     0          | Reserved (must be 0) otherwise specification    |
+|        |                | exception occurs.                               |
++--------+----------------+-------------------------------------------------+
+| 1      |     1          | Program Event Recording 1 PER enabled,          |
+|        |                | PER is used to facilitate debugging e.g.        |
+|        |                | single stepping.                                |
++--------+----------------+-------------------------------------------------+
+| 2-4    |    2-4         | Reserved (must be 0).                           |
++--------+----------------+-------------------------------------------------+
+| 5      |     5          | Dynamic address translation 1=DAT on.           |
++--------+----------------+-------------------------------------------------+
+| 6      |     6          | Input/Output interrupt Mask                     |
++--------+----------------+-------------------------------------------------+
+| 7      |     7          | External interrupt Mask used primarily for      |
+|        |                | interprocessor signalling and clock interrupts. |
++--------+----------------+-------------------------------------------------+
+| 8-11   |   8-11         | PSW Key used for complex memory protection      |
+|        |                | mechanism (not used under linux)                |
++--------+----------------+-------------------------------------------------+
+| 12     |     12         | 1 on s/390 0 on z/Architecture                  |
++--------+----------------+-------------------------------------------------+
+| 13     |     13         | Machine Check Mask 1=enable machine check       |
+|        |                | interrupts                                      |
++--------+----------------+-------------------------------------------------+
+| 14     |     14         | Wait State. Set this to 1 to stop the processor |
+|        |                | except for interrupts and give  time to other   |
+|        |                | LPARS. Used in CPU idle in the kernel to        |
+|        |                | increase overall usage of processor resources.  |
++--------+----------------+-------------------------------------------------+
+| 15     |     15         | Problem state (if set to 1 certain instructions |
+|        |                | are disabled). All linux user programs run with |
+|        |                | this bit 1 (useful info for debugging under VM).|
++--------+----------------+-------------------------------------------------+
+| 16-17  |    16-17       | Address Space Control                           |
+|        |                |                                                 |
+|        |                | 00 Primary Space Mode:                          |
+|        |                |                                                 |
+|        |                | The register CR1 contains the primary           |
+|        |                | address-space control element (PASCE), which    |
+|        |                | points to the primary space region/segment      |
+|        |                | table origin.                                   |
+|        |                |                                                 |
+|        |                | 01 Access register mode                         |
+|        |                |                                                 |
+|        |                | 10 Secondary Space Mode:                        |
+|        |                |                                                 |
+|        |                | The register CR7 contains the secondary         |
+|        |                | address-space control element (SASCE), which    |
+|        |                | points to the secondary space region or         |
+|        |                | segment table origin.                           |
+|        |                |                                                 |
+|        |                | 11 Home Space Mode:                             |
+|        |                |                                                 |
+|        |                | The register CR13 contains the home space       |
+|        |                | address-space control element (HASCE), which    |
+|        |                | points to the home space region/segment         |
+|        |                | table origin.                                   |
+|        |                |                                                 |
+|        |                | See "Address Spaces on Linux for s/390 &        |
+|        |                | z/Architecture" below for more information      |
+|        |                | about address space usage in Linux.             |
++--------+----------------+-------------------------------------------------+
+| 18-19  |    18-19       | Condition codes (CC)                            |
++--------+----------------+-------------------------------------------------+
+| 20     |    20          | Fixed point overflow mask if 1=FPU exceptions   |
+|        |                | for this event occur (normally 0)               |
++--------+----------------+-------------------------------------------------+
+| 21     |    21          | Decimal overflow mask if 1=FPU exceptions for   |
+|        |                | this event occur (normally 0)                   |
++--------+----------------+-------------------------------------------------+
+| 22     |    22          | Exponent underflow mask if 1=FPU exceptions     |
+|        |                | for this event occur (normally 0)               |
++--------+----------------+-------------------------------------------------+
+| 23     |    23          | Significance Mask if 1=FPU exceptions for this  |
+|        |                | event occur (normally 0)                        |
++--------+----------------+-------------------------------------------------+
+| 24-31  |    24-30       | Reserved Must be 0.                             |
+|        +----------------+-------------------------------------------------+
+|        |    31          | Extended Addressing Mode                        |
+|        +----------------+-------------------------------------------------+
+|        |    32          | Basic Addressing Mode                           |
+|        |                |                                                 |
+|        |                | Used to set addressing mode                     |
+|        |                |                                                 |
+|        |                |    +---------+----------+----------+            |
+|        |                |    | PSW 31  | PSW 32   |          |            |
+|        |                |    +---------+----------+----------+            |
+|        |                |    |   0     |    0     |  24 bit  |            |
+|        |                |    +---------+----------+----------+            |
+|        |                |    |   0     |    1     |  31 bit  |            |
+|        |                |    +---------+----------+----------+            |
+|        |                |    |   1     |    1     |  64 bit  |            |
+|        |                |    +---------+----------+----------+            |
++--------+----------------+-------------------------------------------------+
+| 32     |                | 1=31 bit addressing mode 0=24 bit addressing    |
+|        |                | mode (for backward compatibility), linux        |
+|        |                | always runs with this bit set to 1              |
++--------+----------------+-------------------------------------------------+
+| 33-64  |                | Instruction address.                            |
+|        +----------------+-------------------------------------------------+
+|        |    33-63       | Reserved must be 0                              |
+|        +----------------+-------------------------------------------------+
+|        |    64-127      | Address                                         |
+|        |                |                                                 |
+|        |                |   - In 24 bits mode bits 64-103=0 bits 104-127  |
+|        |                |     Address                                     |
+|        |                |   - In 31 bits mode bits 64-96=0 bits 97-127    |
+|        |                |     Address                                     |
+|        |                |                                                 |
+|        |                | Note:                                           |
+|        |                |     unlike 31 bit mode on s/390 bit 96 must be  |
+|        |                |     zero when loading the address with LPSWE    |
+|        |                |     otherwise a specification exception occurs, |
+|        |                |     LPSW is fully backward compatible.          |
++--------+----------------+-------------------------------------------------+
 
 Prefix Page(s)
 --------------
Signature · 1 line
2.20.1
#57 lore raw

PATCH 31/57 docs: s390: convert text files to ReST format

In reply to Mauro Carvalho Chehab

Convert all text files with s390 documentation to ReST format.

Tried to preserve as much as possible the original document format. Still, some of the files required some work in order for it to be visible on both plain text and after converted to html.

---
 Documentation/s390/3270.txt         |   85 +-
 Documentation/s390/CommonIO         |   47 +-
 Documentation/s390/DASD             |   33 +-
 Documentation/s390/Debugging390.txt | 2389 ++++++++++++++++-----------
 Documentation/s390/cds.txt          |  354 ++--
 Documentation/s390/driver-model.txt |  179 +-
 Documentation/s390/monreader.txt    |   85 +-
 Documentation/s390/qeth.txt         |   36 +-
 Documentation/s390/s390dbf.txt      |  781 +++++----
 Documentation/s390/vfio-ap.txt      |  487 +++---
 Documentation/s390/vfio-ccw.txt     |   88 +-
 Documentation/s390/zfcpdump.txt     |    2 +
 12 files changed, 2686 insertions(+), 1880 deletions(-)
Documentation/s390/3270.txt +56 -29
index 7c715de99774..e09e77954238 100644
@@ -1,13 +1,17 @@
+===============================
 IBM 3270 Display System support
+===============================
 
 This file describes the driver that supports local channel attachment
 of IBM 3270 devices.  It consists of three sections:
+
 	* Introduction
 	* Installation
 	* Operation
 
 
-INTRODUCTION.
+Introduction
+============
 
 This paper describes installing and operating 3270 devices under
 Linux/390.  A 3270 device is a block-mode rows-and-columns terminal of
@@ -17,12 +21,12 @@ twenty and thirty years ago.
 You may have 3270s in-house and not know it.  If you're using the
 VM-ESA operating system, define a 3270 to your virtual machine by using
 the command "DEF GRAF <hex-address>"  This paper presumes you will be
-defining four 3270s with the CP/CMS commands
+defining four 3270s with the CP/CMS commands:
 
-	DEF GRAF 620
-	DEF GRAF 621
-	DEF GRAF 622
-	DEF GRAF 623
+	- DEF GRAF 620
+	- DEF GRAF 621
+	- DEF GRAF 622
+	- DEF GRAF 623
 
 Your network connection from VM-ESA allows you to use x3270, tn3270, or
 another 3270 emulator, started from an xterm window on your PC or
@@ -34,7 +38,8 @@ This paper covers installation of the driver and operation of a
 dialed-in x3270.
 
 
-INSTALLATION.
+Installation
+============
 
 You install the driver by installing a patch, doing a kernel build, and
 running the configuration script (config3270.sh, in this directory).
@@ -59,13 +64,15 @@ Use #CP TERM CONMODE 3270 to change it to 3270.  If you generate only
 at boot time to a 3270 if it is a 3215.
 
 In brief, these are the steps:
+
 	1. Install the tub3270 patch
-	2. (If a module) add a line to a file in /etc/modprobe.d/*.conf
+	2. (If a module) add a line to a file in `/etc/modprobe.d/*.conf`
 	3. (If VM) define devices with DEF GRAF
 	4. Reboot
 	5. Configure
 
 To test that everything works, assuming VM and x3270,
+
 	1. Bring up an x3270 window.
 	2. Use the DIAL command in that window.
 	3. You should immediately see a Linux login screen.
@@ -74,7 +81,8 @@ Here are the installation steps in detail:
 
 	1.  The 3270 driver is a part of the official Linux kernel
 	source.  Build a tree with the kernel source and any necessary
-	patches.  Then do
+	patches.  Then do::
+
 		make oldconfig
 		(If you wish to disable 3215 console support, edit
 		.config; change CONFIG_TN3215's value to "n";
@@ -84,20 +92,22 @@ Here are the installation steps in detail:
 		make modules_install
 
 	2. (Perform this step only if you have configured tub3270 as a
-	module.)  Add a line to a file /etc/modprobe.d/*.conf to automatically
+	module.)  Add a line to a file `/etc/modprobe.d/*.conf` to automatically
 	load the driver when it's needed.  With this line added, you will see
 	login prompts appear on your 3270s as soon as boot is complete (or
 	with emulated 3270s, as soon as you dial into your vm guest using the
 	command "DIAL <vmguestname>").  Since the line-mode major number is
-	227, the line to add should be:
+	227, the line to add should be::
+
 		alias char-major-227 tub3270
 
 	3. Define graphic devices to your vm guest machine, if you
 	haven't already.  Define them before you reboot (reipl):
-		DEFINE GRAF 620
-		DEFINE GRAF 621
-		DEFINE GRAF 622
-		DEFINE GRAF 623
+
+		- DEFINE GRAF 620
+		- DEFINE GRAF 621
+		- DEFINE GRAF 622
+		- DEFINE GRAF 623
 
 	4. Reboot.  The reboot process scans hardware devices, including
 	3270s, and this enables the tub3270 driver once loaded to respond
@@ -107,21 +117,23 @@ Here are the installation steps in detail:
 
 	5. Run the 3270 configuration script config3270.  It is
 	distributed in this same directory, Documentation/s390, as
-	config3270.sh.	Inspect the output script it produces,
+	config3270.sh.  Inspect the output script it produces,
 	/tmp/mkdev3270, and then run that script.  This will create the
 	necessary character special device files and make the necessary
 	changes to /etc/inittab.
 
 	Then notify /sbin/init that /etc/inittab has changed, by issuing
-	the telinit command with the q operand:
+	the telinit command with the q operand::
+
 		cd Documentation/s390
 		sh config3270.sh
 		sh /tmp/mkdev3270
 		telinit q
 
-	This should be sufficient for your first time.	If your 3270
+	This should be sufficient for your first time.  If your 3270
 	configuration has changed and you're reusing config3270, you
-	should follow these steps:
+	should follow these steps::
+
 		Change 3270 configuration
 		Reboot
 		Run config3270 and /tmp/mkdev3270
@@ -132,8 +144,10 @@ Here are the testing steps in detail:
 	1. Bring up an x3270 window, or use an actual hardware 3278 or
 	3279, or use the 3270 emulator of your choice.  You would be
 	running the emulator on your PC or workstation.  You would use
-	the command, for example,
+	the command, for example::
+
 		x3270 vm-esa-domain-name &
+
 	if you wanted a 3278 Model 4 with 43 rows of 80 columns, the
 	default model number.  The driver does not take advantage of
 	extended attributes.
@@ -144,7 +158,8 @@ Here are the testing steps in detail:
 
 	2. Use the DIAL command instead of the LOGIN command to connect
 	to one of the virtual 3270s you defined with the DEF GRAF
-	commands:
+	commands::
+
 		dial my-vm-guest-name
 
 	3. You should immediately see a login prompt from your
@@ -171,14 +186,17 @@ Here are the testing steps in detail:
 	Wrong major number?  Wrong minor number?  There's your
 	problem!
 
-	D. Do you get the message
+	D. Do you get the message::
+
 		 "HCPDIA047E my-vm-guest-name 0620 does not exist"?
+
 	If so, you must issue the command "DEF GRAF 620" from your VM
 	3215 console and then reboot the system.
 
 
 
 OPERATION.
+==========
 
 The driver defines three areas on the 3270 screen:  the log area, the
 input area, and the status area.
@@ -203,8 +221,10 @@ which indicates no scrolling will occur.  (If you hit ENTER with "Linux
 Running" and nothing typed, the application receives a newline.)
 
 You may change the scrolling timeout value.  For example, the following
-command line:
+command line::
+
 	echo scrolltime=60 > /proc/tty/driver/tty3270
+
 changes the scrolling timeout value to 60 sec.  Set scrolltime to 0 if
 you wish to prevent scrolling entirely.
 
@@ -228,7 +248,8 @@ cause an EOF also by typing "^D" and hitting ENTER.
 No PF key is preassigned to cause a job suspension, but you may cause a
 job suspension by typing "^Z" and hitting ENTER.  You may wish to
 assign this function to a PF key.  To make PF7 cause job suspension,
-execute the command:
+execute the command::
+
 	echo pf7=^z > /proc/tty/driver/tty3270
 
 If the input you type does not end with the two characters "^n", the
@@ -243,8 +264,10 @@ command is entered into the stack only when the input area is not made
 invisible (such as for password entry) and it is not identical to the
 current top entry.  PF10 rotates backward through the command stack;
 PF11 rotates forward.  You may assign the backward function to any PF
-key (or PA key, for that matter), say, PA3, with the command:
+key (or PA key, for that matter), say, PA3, with the command::
+
 	echo -e pa3=\\033k > /proc/tty/driver/tty3270
+
 This assigns the string ESC-k to PA3.  Similarly, the string ESC-j
 performs the forward function.  (Rationale:  In bash with vi-mode line
 editing, ESC-k and ESC-j retrieve backward and forward history.
@@ -252,15 +275,19 @@ Suggestions welcome.)
 
 Is a stack size of twenty commands not to your liking?  Change it on
 the fly.  To change to saving the last 100 commands, execute the
-command:
+command::
+
 	echo recallsize=100 > /proc/tty/driver/tty3270
 
 Have a command you issue frequently?  Assign it to a PF or PA key!  Use
-the command
-	echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270 
+the command::
+
+	echo pf24="mkdir foobar; cd foobar" > /proc/tty/driver/tty3270
+
 to execute the commands mkdir foobar and cd foobar immediately when you
 hit PF24.  Want to see the command line first, before you execute it?
-Use the -n option of the echo command:
+Use the -n option of the echo command::
+
 	echo -n pf24="mkdir foo; cd foo" > /proc/tty/driver/tty3270
 
 
Documentation/s390/CommonIO +31 -16

108 lines not on this page · raw message

Documentation/s390/DASD +22 -11
index 9963f1e9c98a..9e22247285c8 100644
@@ -1,4 +1,6 @@
+==================
 DASD device driver
+==================
 
 S/390's disk devices (DASDs) are managed by Linux via the DASD device
 driver. It is valid for all types of DASDs and represents them to
@@ -14,14 +16,14 @@ parameters are to be given in hexadecimal notation without a leading
 If you supply kernel parameters the different instances are processed
 in order of appearance and a minor number is reserved for any device
 covered by the supplied range up to 64 volumes. Additional DASDs are
-ignored. If you do not supply the 'dasd=' kernel parameter at all, the 
+ignored. If you do not supply the 'dasd=' kernel parameter at all, the
 DASD driver registers all supported DASDs of your system to a minor
 number in ascending order of the subchannel number.
 
 The driver currently supports ECKD-devices and there are stubs for
 support of the FBA and CKD architectures. For the FBA architecture
 only some smart data structures are missing to make the support
-complete. 
+complete.
 We performed our testing on 3380 and 3390 type disks of different
 sizes, under VM and on the bare hardware (LPAR), using internal disks
 of the multiprise as well as a RAMAC virtual array. Disks exported by
@@ -34,19 +36,22 @@ accessibility of the DASD from other OSs. In a later stage we will
 provide support of partitions, maybe VTOC oriented or using a kind of
 partition table in the label record.
 
-USAGE
+Usage
+=====
 
 -Low-level format (?CKD only)
 For using an ECKD-DASD as a Linux harddisk you have to low-level
 format the tracks by issuing the BLKDASDFORMAT-ioctl on that
 device. This will erase any data on that volume including IBM volume
-labels, VTOCs etc. The ioctl may take a 'struct format_data *' or
-'NULL' as an argument.  
-typedef struct {
+labels, VTOCs etc. The ioctl may take a `struct format_data *` or
+'NULL' as an argument::
+
+  typedef struct {
 	int start_unit;
 	int stop_unit;
 	int blksize;
-} format_data_t;
+  } format_data_t;
+
 When a NULL argument is passed to the BLKDASDFORMAT ioctl the whole
 disk is formatted to a blocksize of 1024 bytes. Otherwise start_unit
 and stop_unit are the first and last track to be formatted. If
@@ -56,17 +61,23 @@ up to the last track. blksize can be any power of two between 512 and
 1kB blocks anyway and you gain approx. 50% of capacity increasing your
 blksize from 512 byte to 1kB.
 
--Make a filesystem
+Make a filesystem
+=================
+
 Then you can mk??fs the filesystem of your choice on that volume or
 partition. For reasons of sanity you should build your filesystem on
-the partition /dev/dd?1 instead of the whole volume. You only lose 3kB	
+the partition /dev/dd?1 instead of the whole volume. You only lose 3kB
 but may be sure that you can reuse your data after introduction of a
 real partition table.
 
-BUGS:
+Bugs
+====
+
 - Performance sometimes is rather low because we don't fully exploit clustering
 
-TODO-List:
+TODO-List
+=========
+
 - Add IBM'S Disk layout to genhd
 - Enhance driver to use more than one major number
 - Enable usage as a module
Documentation/s390/Debugging390.txt +1415 -974

2,600 lines not on this page · raw message

Documentation/s390/cds.txt +206 -148

354 lines not on this page · raw message

Documentation/s390/driver-model.txt +110 -69

179 lines not on this page · raw message

Documentation/s390/monreader.txt +50 -35

85 lines not on this page · raw message

Documentation/s390/qeth.txt +25 -11
index aa06fcf5f8c2..f02fdaa68de0 100644

Lines of this file are not shown. View the raw message.

Documentation/s390/s390dbf.txt +454 -327

781 lines not on this page · raw message

Documentation/s390/vfio-ap.txt +258 -229

487 lines not on this page · raw message

Documentation/s390/vfio-ccw.txt +57 -31

88 lines not on this page · raw message

Documentation/s390/zfcpdump.txt +2 -0
index b064aa59714d..54e8e7caf7e7 100644

Lines of this file are not shown. View the raw message.

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.20.1

Part of the diff is not shown here. View the raw message.

#58 lore raw

PATCH 32/57 s390: include/asm/debug.h add kerneldoc markups

In reply to Mauro Carvalho Chehab

Instead of keeping the documentation inside s390dbf.txt, move them to arch/s390/include/asm/debug.h, using standard kernel-doc markups.

Those were converted to kerneldoc using this specially made script and manually editted:

<script>
use strict;

my $mode = "";
my $parameter = "";
my $ret = "";
my $descr = "";

sub add_var($)

{
	my $ln = shift;

	$ln =~ s/^\s+//;
	$ln =~ s/\s+$//;

	return if ($ln eq "");

	$ln =~ s/^(\S+)\s+/$1\t/;

	print " * \@$ln\n";
}

sub add_return($)

{
	my $ln = shift;

	print " *\n * Return:\n" if ($mode ne "Return Value:");

	$ln =~ s/^\s+//;
	$ln =~ s/\s+$//;

	return if ($ln eq "");

	print " * -   $ln\n";
}

sub add_description($)

{
	my $ln = shift;

	print " *\n * \n" if ($mode ne "Description:");

	$ln =~ s/^\s+//;
	$ln =~ s/\s+$//;

	return if ($ln eq "");

	print " * $ln\n";
}

sub flush_results()

{
	print " */\n\n";
}
while (<>) {
	if (m/^[\-]+$/) {
		flush_results();
		$mode = "";
		$parameter = "";
		$ret = "";
		$descr = "";
		next;
	}
	if (m/(Parameter:)(.*)/) {
		print " *\n" if ($mode eq "func");
		add_var($2);
		$mode = $1;
		next;
	}
	if (m/(Return Value:)(.*)/) {
		add_return($2);
		$mode = $1;
		next;
	}
	if (m/(Description:)(.*)/) {
		add_description($2);
		$mode = $1;
		next;
	}
	if ($mode eq "Parameter:") {
		add_var($_);
		next;
	}
	if ($mode eq "Return Value:") {
		add_return($_);
		next;
	}
	if ($mode eq "Description:") {
		add_description($_);
		next;
	}
	next if (m/^\s*$/);

	if (m/^\S+.*\s\*?(\S+)\s*\(/) {
		if ($mode eq "") {
			print "/**\n * $1()\n";
		} else {
			print " * $1()\n";
		}
		$mode="func";
	}
}

flush_results();
</script>

---
 Documentation/s390/s390dbf.txt | 322 +--------------------------------
 arch/s390/include/asm/debug.h  | 231 +++++++++++++++++++++++
 2 files changed, 232 insertions(+), 321 deletions(-)
Documentation/s390/s390dbf.txt +1 -321
index 549dba50fc3b..b0ca0d142ea1 100644
@@ -107,327 +107,7 @@ will stay deactivated.
 Kernel Interfaces:
 ------------------
 
-----------------------------------------------------------------------------
-
-::
-
-  debug_info_t *debug_register(char *name, int pages, int nr_areas,
-			       int buf_size);
-
-Parameter:
-	      name:
-			   Name of debug log (e.g. used for debugfs entry)
-	      pages:
-			   Number of pages, which will be allocated per area
-	      nr_areas:
-			   Number of debug areas
-	      buf_size:
-			   Size of data area in each debug entry
-
-Return Value:
-	Handle for generated debug area
-
-	  NULL if register failed
-
-Description:  Allocates memory for a debug log
-	      Must not be called within an interrupt handler
-
-----------------------------------------------------------------------------
-
-::
-
-  debug_info_t *debug_register_mode(char *name, int pages, int nr_areas,
-				    int buf_size, mode_t mode, uid_t uid,
-				    gid_t gid);
-
-Parameter:
-	      name:
-			   Name of debug log (e.g. used for debugfs entry)
-	      pages:
-			   Number of pages, which will be allocated per area
-	      nr_areas:
-			   Number of debug areas
-	      buf_size:
-			   Size of data area in each debug entry
-	      mode:
-			   File mode for debugfs files. E.g. S_IRWXUGO
-	      uid:
-			   User ID for debugfs files. Currently only 0 is
-			   supported.
-	      gid:
-			   Group ID for debugfs files. Currently only 0 is
-			   supported.
-
-Return Value:
-	      Handle for generated debug area
-
-		NULL if register failed
-
-Description:
-	      Allocates memory for a debug log
-	      Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
-  void debug_unregister (debug_info_t * id);
-
-Parameter:
-	       id:
-		    handle for debug log
-
-Return Value:
-	       none
-
-Description:
-	       frees memory for a debug log and removes all registered debug
-	       views.
-
-	       Must not be called within an interrupt handler
-
----------------------------------------------------------------------------
-
-::
-
-  void debug_set_level (debug_info_t * id, int new_level);
-
-Parameter:     id:        handle for debug log
-	       new_level: new debug level
-
-Return Value:
-	       none
-
-Description:
-	       Sets new actual debug level if new_level is valid.
-
----------------------------------------------------------------------------
-
-::
-
-  bool debug_level_enabled (debug_info_t * id, int level);
-
-Parameter:
-	      id:
-			  handle for debug log
-	      level:
-			  debug level
-
-Return Value:
-	      True if level is less or equal to the current debug level.
-
-Description:
-	      Returns true if debug events for the specified level would be
-	      logged. Otherwise returns false.
-
----------------------------------------------------------------------------
-
-::
-
-  void debug_stop_all(void);
-
-Parameter:
-	       none
-
-Return Value:
-	       none
-
-Description:
-	       stops the debug feature if stopping is allowed. Currently
-	       used in case of a kernel oops.
-
----------------------------------------------------------------------------
-
-::
-
-  debug_entry_t* debug_event (debug_info_t* id, int level, void* data,
-			      int length);
-
-Parameter:
-	       id:
-		       handle for debug log
-	       level:
-		       debug level
-	       data:
-		       pointer to data for debug entry
-	       length:
-		       length of data in bytes
-
-Return Value:
-	       Address of written debug entry
-
-Description:
-	       writes debug entry to active debug area (if level <= actual
-	       debug level)
-
----------------------------------------------------------------------------
-
-::
-
-  debug_entry_t* debug_int_event (debug_info_t * id, int level,
-				  unsigned int data);
-  debug_entry_t* debug_long_event(debug_info_t * id, int level,
-				  unsigned long data);
-
-Parameter:
-	       id:
-		       handle for debug log
-	       level:
-		       debug level
-	       data:
-		       integer value for debug entry
-
-Return Value:
-	       Address of written debug entry
-
-Description:
-	       writes debug entry to active debug area (if level <= actual
-	       debug level)
-
----------------------------------------------------------------------------
-
-::
-
-  debug_entry_t* debug_text_event (debug_info_t * id, int level,
-				   const char* data);
-
-Parameter:
-	       id:
-		       handle for debug log
-	       level:
-		       debug level
-	       data:
-		       string for debug entry
-
-Return Value:
-	       Address of written debug entry
-
-Description:
-	       writes debug entry in ascii format to active debug area
-	       (if level <= actual debug level)
-
----------------------------------------------------------------------------
-
-::
-
-  debug_entry_t* debug_sprintf_event (debug_info_t * id, int level,
-				      char* string,...);
-
-Parameter:
-	       id:
-		      handle for debug log
-	       level:
-		      debug level
-	       string:
-		      format string for debug entry
-	       ...:
-		      varargs used as in sprintf()
-
-Return Value:  Address of written debug entry
-
-Description:
-	       writes debug entry with format string and varargs (longs) to
-	       active debug area (if level $<=$ actual debug level).
-	       floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-::
-
-  debug_entry_t* debug_exception (debug_info_t* id, int level, void* data,
-				  int length);
-
-Parameter:
-	       id:
-		       handle for debug log
-	       level:
-		       debug level
-	       data:
-		       pointer to data for debug entry
-	       length:
-		       length of data in bytes
-
-Return Value:
-	       Address of written debug entry
-
-Description:
-	       writes debug entry to active debug area (if level <= actual
-	       debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-::
-  debug_entry_t* debug_int_exception (debug_info_t * id, int level,
-				      unsigned int data);
-  debug_entry_t* debug_long_exception(debug_info_t * id, int level,
-				      unsigned long data);
-
-Parameter:     id:     handle for debug log
-	       level:  debug level
-	       data:   integer value for debug entry
-
-Return Value:  Address of written debug entry
-
-Description:   writes debug entry to active debug area (if level <= actual
-	       debug level) and switches to next debug area
-
----------------------------------------------------------------------------
-
-debug_entry_t* debug_text_exception (debug_info_t * id, int level,
-				     const char* data);
-
-Parameter:     id:     handle for debug log
-	       level:  debug level
-	       data:   string for debug entry
-
-Return Value:  Address of written debug entry
-
-Description:   writes debug entry in ascii format to active debug area
-	       (if level <= actual debug level) and switches to next debug
-	       area
-
----------------------------------------------------------------------------
-
-debug_entry_t* debug_sprintf_exception (debug_info_t * id, int level,
-					char* string,...);
-
-Parameter:     id:    handle for debug log
-	       level: debug level
-	       string: format string for debug entry
-	       ...: varargs used as in sprintf()
-
-Return Value:  Address of written debug entry
-
-Description:   writes debug entry with format string and varargs (longs) to
-	       active debug area (if level $<=$ actual debug level) and
-	       switches to next debug area.
-	       floats and long long datatypes cannot be used as varargs.
-
----------------------------------------------------------------------------
-
-int debug_register_view (debug_info_t * id, struct debug_view *view);
-
-Parameter:     id:    handle for debug log
-	       view:  pointer to debug view struct
-
-Return Value:  0  : ok
-	       < 0: Error
-
-Description:   registers new debug view and creates debugfs dir entry
-
----------------------------------------------------------------------------
-
-int debug_unregister_view (debug_info_t * id, struct debug_view *view);
-
-Parameter:     id:    handle for debug log
-	       view:  pointer to debug view struct
-
-Return Value:  0  : ok
-	       < 0: Error
-
-Description:   unregisters debug view and removes debugfs dir entry
-
-
+.. kernel-doc:: arch/s390/include/asm/debug.h
 
 Predefined views:
 -----------------
arch/s390/include/asm/debug.h +231 -0

317 lines not on this page · raw message

Signature · 1 line
2.20.1
#59 lore raw

PATCH 33/57 docs: serial: convert it to ReST format

In reply to Mauro Carvalho Chehab

The converted files are focused at the Kernel internal API, so, this is a good candidate for the kernel API set of books.

---
 Documentation/serial/README.cycladesZ   |   5 +-
 Documentation/serial/driver             | 113 +++-
 Documentation/serial/moxa-smartio       | 750 +++++++++++++-----------
 Documentation/serial/n_gsm.txt          |  81 +--
 Documentation/serial/rocket.txt         | 144 +++--
 Documentation/serial/serial-iso7816.txt |  21 +-
 Documentation/serial/serial-rs485.txt   |  22 +-
 Documentation/serial/tty.txt            | 111 ++--
 8 files changed, 719 insertions(+), 528 deletions(-)
Documentation/serial/README.cycladesZ +4 -1
index 024a69443cc2..532ff67e2f1c 100644
@@ -1,8 +1,11 @@
+================
+Cyclades-Z notes
+================
 
 The Cyclades-Z must have firmware loaded onto the card before it will
 operate.  This operation should be performed during system startup,
 
 The firmware, loader program and the latest device driver code are
 available from Cyclades at
+
     ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/
-
Documentation/serial/driver +88 -25

386 lines not on this page · raw message

Documentation/serial/moxa-smartio +421 -329

896 lines not on this page · raw message

Documentation/serial/n_gsm.txt +44 -37

109 lines not on this page · raw message

Documentation/serial/rocket.txt +70 -74

213 lines not on this page · raw message

Documentation/serial/serial-iso7816.txt +14 -7
index 3193d24a2b0f..d990143de0c6 100644
@@ -1,11 +1,15 @@
-                        ISO7816 SERIAL COMMUNICATIONS
+=============================
+ISO7816 Serial Communications
+=============================
 
-1. INTRODUCTION
+1. Introduction
+===============
 
   ISO/IEC7816 is a series of standards specifying integrated circuit cards (ICC)
   also known as smart cards.
 
-2. HARDWARE-RELATED CONSIDERATIONS
+2. Hardware-related considerations
+==================================
 
   Some CPUs/UARTs (e.g., Microchip AT91) contain a built-in mode capable of
   handling communication with a smart card.
@@ -15,7 +19,8 @@
   available at user-level to allow switching from one mode to the other, and
   vice versa.
 
-3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL
+3. Data Structures Already Available in the Kernel
+==================================================
 
   The Linux kernel provides the serial_iso7816 structure (see [1]) to handle
   ISO7816 communications. This data structure is used to set and configure
@@ -27,10 +32,11 @@
   to TIOCGISO7816 and TIOCSISO7816 ioctls (see below). The iso7816_config
   callback receives a pointer to struct serial_iso7816.
 
-4. USAGE FROM USER-LEVEL
+4. Usage from user-level
+========================
 
   From user-level, ISO7816 configuration can be get/set using the previous
-  ioctls. For instance, to set ISO7816 you can use the following code:
+  ioctls. For instance, to set ISO7816 you can use the following code::
 
 	#include <linux/serial.h>
 
@@ -78,6 +84,7 @@
 		/* Error handling. See errno. */
 	}
 
-5. REFERENCES
+5. References
+=============
 
  [1]    include/uapi/linux/serial.h
Documentation/serial/serial-rs485.txt +15 -7
index ce0c1a9b8aab..6bc824f948f9 100644
@@ -1,6 +1,9 @@
-                        RS485 SERIAL COMMUNICATIONS
+===========================
+RS485 Serial Communications
+===========================
 
-1. INTRODUCTION
+1. Introduction
+===============
 
    EIA-485, also known as TIA/EIA-485 or RS-485, is a standard defining the
    electrical characteristics of drivers and receivers for use in balanced
@@ -9,7 +12,8 @@
    because it can be used effectively over long distances and in electrically
    noisy environments.
 
-2. HARDWARE-RELATED CONSIDERATIONS
+2. Hardware-related Considerations
+==================================
 
    Some CPUs/UARTs (e.g., Atmel AT91 or 16C950 UART) contain a built-in
    half-duplex mode capable of automatically controlling line direction by
@@ -22,7 +26,8 @@
    available at user-level to allow switching from one mode to the other, and
    vice versa.
 
-3. DATA STRUCTURES ALREADY AVAILABLE IN THE KERNEL
+3. Data Structures Already Available in the Kernel
+==================================================
 
    The Linux kernel provides the serial_rs485 structure (see [1]) to handle
    RS485 communications. This data structure is used to set and configure RS485
@@ -38,10 +43,11 @@
    to TIOCSRS485 and TIOCGRS485 ioctls (see below). The rs485_config callback
    receives a pointer to struct serial_rs485.
 
-4. USAGE FROM USER-LEVEL
+4. Usage from user-level
+========================
 
    From user-level, RS485 configuration can be get/set using the previous
-   ioctls. For instance, to set RS485 you can use the following code:
+   ioctls. For instance, to set RS485 you can use the following code::
 
 	#include <linux/serial.h>
 
@@ -89,7 +95,9 @@
 		/* Error handling. See errno. */
 	}
 
-5. REFERENCES
+5. References
+=============
 
  [1]	include/uapi/linux/serial.h
+
  [2]	Documentation/devicetree/bindings/serial/rs485.txt
Documentation/serial/tty.txt +63 -48

294 lines not on this page · raw message

Signature · 1 line
2.20.1
#60 lore raw

PATCH 34/57 docs: target: convert it to ReST format

In reply to Mauro Carvalho Chehab

Convert the TCM docs to ReST format and add them to the bookset.

This has a mix of userspace-faced and Kernelspace faced docs. Still, it sounds a better candidate to be added at the kernel API set of docs.

---
 Documentation/target/tcm_mod_builder.txt | 200 ++++++++---------
 Documentation/target/tcmu-design.txt     | 268 ++++++++++++-----------
 2 files changed, 248 insertions(+), 220 deletions(-)
Documentation/target/tcm_mod_builder.txt +102 -98
index ae22f7005540..9bfc9822e2bd 100644
@@ -1,145 +1,149 @@
->>>>>>>>>> The TCM v4 fabric module script generator <<<<<<<<<<
+=========================================
+The TCM v4 fabric module script generator
+=========================================
 
 Greetings all,
 
 This document is intended to be a mini-HOWTO for using the tcm_mod_builder.py
 script to generate a brand new functional TCM v4 fabric .ko module of your very own,
 that once built can be immediately be loaded to start access the new TCM/ConfigFS
-fabric skeleton, by simply using:
+fabric skeleton, by simply using::
 
 	modprobe $TCM_NEW_MOD
 	mkdir -p /sys/kernel/config/target/$TCM_NEW_MOD
 
 This script will create a new drivers/target/$TCM_NEW_MOD/, and will do the following
 
-	*) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
+	1) Generate new API callers for drivers/target/target_core_fabric_configs.c logic
 	   ->make_tpg(), ->drop_tpg(), ->make_wwn(), ->drop_wwn().  These are created
 	   into $TCM_NEW_MOD/$TCM_NEW_MOD_configfs.c
-	*) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
+	2) Generate basic infrastructure for loading/unloading LKMs and TCM/ConfigFS fabric module
 	   using a skeleton struct target_core_fabric_ops API template.
-	*) Based on user defined T10 Proto_Ident for the new fabric module being built,
+	3) Based on user defined T10 Proto_Ident for the new fabric module being built,
 	   the TransportID / Initiator and Target WWPN related handlers for
 	   SPC-3 persistent reservation are automatically generated in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
 	   using drivers/target/target_core_fabric_lib.c logic.
-	*) NOP API calls for all other Data I/O path and fabric dependent attribute logic
+	4) NOP API calls for all other Data I/O path and fabric dependent attribute logic
 	   in $TCM_NEW_MOD/$TCM_NEW_MOD_fabric.c
 
 tcm_mod_builder.py depends upon the mandatory '-p $PROTO_IDENT' and '-m
-$FABRIC_MOD_name' parameters, and actually running the script looks like:
+$FABRIC_MOD_name' parameters, and actually running the script looks like::
 
-target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
-tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
-Set fabric_mod_name: tcm_nab5000
-Set fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Using proto_ident: iSCSI
-Creating fabric_mod_dir:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
-Using tcm_mod_scan_fabric_ops:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
-Writing file:
-/mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
-Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
-Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
+  target:/mnt/sdb/lio-core-2.6.git/Documentation/target# python tcm_mod_builder.py -p iSCSI -m tcm_nab5000
+  tcm_dir: /mnt/sdb/lio-core-2.6.git/Documentation/target/../../
+  Set fabric_mod_name: tcm_nab5000
+  Set fabric_mod_dir:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+  Using proto_ident: iSCSI
+  Creating fabric_mod_dir:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000
+  Writing file:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_base.h
+  Using tcm_mod_scan_fabric_ops:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../include/target/target_core_fabric_ops.h
+  Writing file:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.c
+  Writing file:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_fabric.h
+  Writing file:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/tcm_nab5000_configfs.c
+  Writing file:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kbuild
+  Writing file:
+  /mnt/sdb/lio-core-2.6.git/Documentation/target/../../drivers/target/tcm_nab5000/Kconfig
+  Would you like to add tcm_nab5000to drivers/target/Kbuild..? [yes,no]: yes
+  Would you like to add tcm_nab5000to drivers/target/Kconfig..? [yes,no]: yes
 
 At the end of tcm_mod_builder.py. the script will ask to add the following
-line to drivers/target/Kbuild:
+line to drivers/target/Kbuild::
 
 	obj-$(CONFIG_TCM_NAB5000)       += tcm_nab5000/
 
-and the same for drivers/target/Kconfig:
+and the same for drivers/target/Kconfig::
 
 	source "drivers/target/tcm_nab5000/Kconfig"
 
-*) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item:
+#) Run 'make menuconfig' and select the new CONFIG_TCM_NAB5000 item::
 
 	<M>   TCM_NAB5000 fabric module
 
-*) Build using 'make modules', once completed you will have:
+#) Build using 'make modules', once completed you will have::
 
-target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
-total 1348
-drwxr-xr-x 2 root root   4096 2010-10-05 03:23 .
-drwxr-xr-x 9 root root   4096 2010-10-05 03:22 ..
--rw-r--r-- 1 root root    282 2010-10-05 03:22 Kbuild
--rw-r--r-- 1 root root    171 2010-10-05 03:22 Kconfig
--rw-r--r-- 1 root root     49 2010-10-05 03:23 modules.order
--rw-r--r-- 1 root root    738 2010-10-05 03:22 tcm_nab5000_base.h
--rw-r--r-- 1 root root   9096 2010-10-05 03:22 tcm_nab5000_configfs.c
--rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
--rw-r--r-- 1 root root  40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
--rw-r--r-- 1 root root   5414 2010-10-05 03:22 tcm_nab5000_fabric.c
--rw-r--r-- 1 root root   2016 2010-10-05 03:22 tcm_nab5000_fabric.h
--rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
--rw-r--r-- 1 root root  40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
--rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
--rw-r--r-- 1 root root    265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
--rw-r--r-- 1 root root    459 2010-10-05 03:23 tcm_nab5000.mod.c
--rw-r--r-- 1 root root  23896 2010-10-05 03:23 tcm_nab5000.mod.o
--rw-r--r-- 1 root root  22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
--rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
--rw-r--r-- 1 root root    211 2010-10-05 03:23 .tcm_nab5000.o.cmd
+    target:/mnt/sdb/lio-core-2.6.git# ls -la drivers/target/tcm_nab5000/
+    total 1348
+    drwxr-xr-x 2 root root   4096 2010-10-05 03:23 .
+    drwxr-xr-x 9 root root   4096 2010-10-05 03:22 ..
+    -rw-r--r-- 1 root root    282 2010-10-05 03:22 Kbuild
+    -rw-r--r-- 1 root root    171 2010-10-05 03:22 Kconfig
+    -rw-r--r-- 1 root root     49 2010-10-05 03:23 modules.order
+    -rw-r--r-- 1 root root    738 2010-10-05 03:22 tcm_nab5000_base.h
+    -rw-r--r-- 1 root root   9096 2010-10-05 03:22 tcm_nab5000_configfs.c
+    -rw-r--r-- 1 root root 191200 2010-10-05 03:23 tcm_nab5000_configfs.o
+    -rw-r--r-- 1 root root  40504 2010-10-05 03:23 .tcm_nab5000_configfs.o.cmd
+    -rw-r--r-- 1 root root   5414 2010-10-05 03:22 tcm_nab5000_fabric.c
+    -rw-r--r-- 1 root root   2016 2010-10-05 03:22 tcm_nab5000_fabric.h
+    -rw-r--r-- 1 root root 190932 2010-10-05 03:23 tcm_nab5000_fabric.o
+    -rw-r--r-- 1 root root  40713 2010-10-05 03:23 .tcm_nab5000_fabric.o.cmd
+    -rw-r--r-- 1 root root 401861 2010-10-05 03:23 tcm_nab5000.ko
+    -rw-r--r-- 1 root root    265 2010-10-05 03:23 .tcm_nab5000.ko.cmd
+    -rw-r--r-- 1 root root    459 2010-10-05 03:23 tcm_nab5000.mod.c
+    -rw-r--r-- 1 root root  23896 2010-10-05 03:23 tcm_nab5000.mod.o
+    -rw-r--r-- 1 root root  22655 2010-10-05 03:23 .tcm_nab5000.mod.o.cmd
+    -rw-r--r-- 1 root root 379022 2010-10-05 03:23 tcm_nab5000.o
+    -rw-r--r-- 1 root root    211 2010-10-05 03:23 .tcm_nab5000.o.cmd
 
-*) Load the new module, create a lun_0 configfs group, and add new TCM Core
-   IBLOCK backstore symlink to port:
+#) Load the new module, create a lun_0 configfs group, and add new TCM Core
+   IBLOCK backstore symlink to port::
 
-target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
-target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
-target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
+    target:/mnt/sdb/lio-core-2.6.git# insmod drivers/target/tcm_nab5000.ko
+    target:/mnt/sdb/lio-core-2.6.git# mkdir -p /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0
+    target:/mnt/sdb/lio-core-2.6.git# cd /sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0/
+    target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# ln -s /sys/kernel/config/target/core/iblock_0/lvm_test0 nab5000_port
 
-target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
-target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
-/sys/kernel/config/target/nab5000/
-|-- discovery_auth
-|-- iqn.foo
-|   `-- tpgt_1
-|       |-- acls
-|       |-- attrib
-|       |-- lun
-|       |   `-- lun_0
-|       |       |-- alua_tg_pt_gp
-|       |       |-- alua_tg_pt_offline
-|       |       |-- alua_tg_pt_status
-|       |       |-- alua_tg_pt_write_md
-|	|	`-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
-|       |-- np
-|       `-- param
-`-- version
+    target:/sys/kernel/config/target/nab5000/iqn.foo/tpgt_1/lun/lun_0# cd -
+    target:/mnt/sdb/lio-core-2.6.git# tree /sys/kernel/config/target/nab5000/
+    /sys/kernel/config/target/nab5000/
+    |-- discovery_auth
+    |-- iqn.foo
+    |   `-- tpgt_1
+    |       |-- acls
+    |       |-- attrib
+    |       |-- lun
+    |       |   `-- lun_0
+    |       |       |-- alua_tg_pt_gp
+    |       |       |-- alua_tg_pt_offline
+    |       |       |-- alua_tg_pt_status
+    |       |       |-- alua_tg_pt_write_md
+    |	|	`-- nab5000_port -> ../../../../../../target/core/iblock_0/lvm_test0
+    |       |-- np
+    |       `-- param
+    `-- version
 
-target:/mnt/sdb/lio-core-2.6.git# lsmod
-Module                  Size  Used by
-tcm_nab5000             3935  4
-iscsi_target_mod      193211  0
-target_core_stgt        8090  0
-target_core_pscsi      11122  1
-target_core_file        9172  2
-target_core_iblock      9280  1
-target_core_mod       228575  31
-tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
-libfc                  73681  0
-scsi_debug             56265  0
-scsi_tgt                8666  1 target_core_stgt
-configfs               20644  2 target_core_mod
+    target:/mnt/sdb/lio-core-2.6.git# lsmod
+    Module                  Size  Used by
+    tcm_nab5000             3935  4
+    iscsi_target_mod      193211  0
+    target_core_stgt        8090  0
+    target_core_pscsi      11122  1
+    target_core_file        9172  2
+    target_core_iblock      9280  1
+    target_core_mod       228575  31
+    tcm_nab5000,iscsi_target_mod,target_core_stgt,target_core_pscsi,target_core_file,target_core_iblock
+    libfc                  73681  0
+    scsi_debug             56265  0
+    scsi_tgt                8666  1 target_core_stgt
+    configfs               20644  2 target_core_mod
 
 ----------------------------------------------------------------------
 
-Future TODO items:
+Future TODO items
+=================
 
-	*) Add more T10 proto_idents
-	*) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
+	1) Add more T10 proto_idents
+	2) Make tcm_mod_dump_fabric_ops() smarter and generate function pointer
 	   defs directly from include/target/target_core_fabric_ops.h:struct target_core_fabric_ops
 	   structure members.
 
 October 5th, 2010
+
 Nicholas A. Bellinger <[email protected]>
Documentation/target/tcmu-design.txt +146 -122

393 lines not on this page · raw message

Signature · 1 line
2.20.1
#61 lore raw

PATCH 35/57 docs: timers: convert documentation to ReST

In reply to Mauro Carvalho Chehab

The conversion here is really trivial: just a bunch of title markups and very few puntual changes is enough to make it to be parsed by Sphinx and generate a nice html.

---
 Documentation/timers/NO_HZ.txt        | 40 ++++++++++++++++-----------
 Documentation/timers/highres.txt      | 11 ++++----
 Documentation/timers/hpet.txt         |  4 ++-
 Documentation/timers/hrtimers.txt     |  6 ++--
 Documentation/timers/timekeeping.txt  |  3 +-
 Documentation/timers/timers-howto.txt | 15 +++++++---
 6 files changed, 49 insertions(+), 30 deletions(-)
Documentation/timers/NO_HZ.txt +24 -16
index 9591092da5e0..065db217cb04 100644
@@ -1,4 +1,6 @@
-		NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
+NO_HZ: Reducing Scheduling-Clock Ticks
+======================================
 
 
 This document describes Kconfig options and boot parameters that can
@@ -28,7 +30,8 @@ by a third section on RCU-specific considerations, a fourth section
 discussing testing, and a fifth and final section listing known issues.
 
 
-NEVER OMIT SCHEDULING-CLOCK TICKS
+Never Omit Scheduling-Clock Ticks
+=================================
 
 Very old versions of Linux from the 1990s and the very early 2000s
 are incapable of omitting scheduling-clock ticks.  It turns out that
@@ -59,7 +62,8 @@ degrade your applications performance.  If this describes your workload,
 you should read the following two sections.
 
 
-OMIT SCHEDULING-CLOCK TICKS FOR IDLE CPUs
+Omit Scheduling-Clock Ticks For Idle CPUs
+=========================================
 
 If a CPU is idle, there is little point in sending it a scheduling-clock
 interrupt.  After all, the primary purpose of a scheduling-clock interrupt
@@ -97,7 +101,8 @@ By default, CONFIG_NO_HZ_IDLE=y kernels boot with "nohz=on", enabling
 dyntick-idle mode.
 
 
-OMIT SCHEDULING-CLOCK TICKS FOR CPUs WITH ONLY ONE RUNNABLE TASK
+Omit Scheduling-Clock Ticks For CPUs With Only One Runnable Task
+================================================================
 
 If a CPU has only one runnable task, there is little point in sending it
 a scheduling-clock interrupt because there is no other task to switch to.
@@ -174,7 +179,8 @@ However, the drawbacks listed above mean that adaptive ticks should not
 (yet) be enabled by default.
 
 
-RCU IMPLICATIONS
+RCU Implications
+================
 
 There are situations in which idle CPUs cannot be permitted to
 enter either dyntick-idle mode or adaptive-tick mode, the most
@@ -199,7 +205,8 @@ scheduler will decide where to run them, which might or might not be
 where you want them to run.
 
 
-TESTING
+Testing
+=======
 
 So you enable all the OS-jitter features described in this document,
 but do not see any change in your workload's behavior.  Is this because
@@ -222,9 +229,10 @@ We do not currently have a good way to remove OS jitter from single-CPU
 systems.
 
 
-KNOWN ISSUES
+Known Issues
+============
 
-o	Dyntick-idle slows transitions to and from idle slightly.
+*	Dyntick-idle slows transitions to and from idle slightly.
 	In practice, this has not been a problem except for the most
 	aggressive real-time workloads, which have the option of disabling
 	dyntick-idle mode, an option that most of them take.  However,
@@ -248,13 +256,13 @@ o	Dyntick-idle slows transitions to and from idle slightly.
 		this parameter effectively disables Turbo Mode on Intel
 		CPUs, which can significantly reduce maximum performance.
 
-o	Adaptive-ticks slows user/kernel transitions slightly.
+*	Adaptive-ticks slows user/kernel transitions slightly.
 	This is not expected to be a problem for computationally intensive
 	workloads, which have few such transitions.  Careful benchmarking
 	will be required to determine whether or not other workloads
 	are significantly affected by this effect.
 
-o	Adaptive-ticks does not do anything unless there is only one
+*	Adaptive-ticks does not do anything unless there is only one
 	runnable task for a given CPU, even though there are a number
 	of other situations where the scheduling-clock tick is not
 	needed.  To give but one example, consider a CPU that has one
@@ -275,7 +283,7 @@ o	Adaptive-ticks does not do anything unless there is only one
 
 	Better handling of these sorts of situations is future work.
 
-o	A reboot is required to reconfigure both adaptive idle and RCU
+*	A reboot is required to reconfigure both adaptive idle and RCU
 	callback offloading.  Runtime reconfiguration could be provided
 	if needed, however, due to the complexity of reconfiguring RCU at
 	runtime, there would need to be an earthshakingly good reason.
@@ -283,12 +291,12 @@ o	A reboot is required to reconfigure both adaptive idle and RCU
 	simply offloading RCU callbacks from all CPUs and pinning them
 	where you want them whenever you want them pinned.
 
-o	Additional configuration is required to deal with other sources
+*	Additional configuration is required to deal with other sources
 	of OS jitter, including interrupts and system-utility tasks
 	and processes.  This configuration normally involves binding
 	interrupts and tasks to particular CPUs.
 
-o	Some sources of OS jitter can currently be eliminated only by
+*	Some sources of OS jitter can currently be eliminated only by
 	constraining the workload.  For example, the only way to eliminate
 	OS jitter due to global TLB shootdowns is to avoid the unmapping
 	operations (such as kernel module unload operations) that
@@ -299,17 +307,17 @@ o	Some sources of OS jitter can currently be eliminated only by
 	helpful, especially when combined with the mlock() and mlockall()
 	system calls.
 
-o	Unless all CPUs are idle, at least one CPU must keep the
+*	Unless all CPUs are idle, at least one CPU must keep the
 	scheduling-clock interrupt going in order to support accurate
 	timekeeping.
 
-o	If there might potentially be some adaptive-ticks CPUs, there
+*	If there might potentially be some adaptive-ticks CPUs, there
 	will be at least one CPU keeping the scheduling-clock interrupt
 	going, even if all CPUs are otherwise idle.
 
 	Better handling of this situation is ongoing work.
 
-o	Some process-handling operations still require the occasional
+*	Some process-handling operations still require the occasional
 	scheduling-clock tick.	These operations include calculating CPU
 	load, maintaining sched average, computing CFS entity vruntime,
 	computing avenrun, and carrying out load balancing.  They are
Documentation/timers/highres.txt +6 -5
index 8f9741592123..f93528e6f1c8 100644
@@ -1,5 +1,6 @@
+=====================================================
 High resolution timers and dynamic ticks design notes
------------------------------------------------------
+=====================================================
 
 Further information can be found in the paper of the OLS 2006 talk "hrtimers
 and beyond". The paper is part of the OLS 2006 Proceedings Volume 1, which can
@@ -35,6 +36,7 @@ also figure #2 (OLS slides p. 15)
 
 The main differences to the timer wheel, which holds the armed timer_list type
 timers are:
+
        - time ordered enqueueing into a rb-tree
        - independent of ticks (the processing is based on nanoseconds)
 
@@ -55,7 +57,8 @@ merged into the 2.6.18 kernel.
 
 Further information about the Generic Time Of Day framework is available in the
 OLS 2005 Proceedings Volume 1:
-http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
+
+	http://www.linuxsymposium.org/2005/linuxsymposium_procv1.pdf
 
 The paper "We Are Not Getting Any Younger: A New Approach to Time and
 Timers" was written by J. Stultz, D.V. Hart, & N. Aravamudan.
@@ -100,6 +103,7 @@ accounting, profiling, and high resolution timers.
 
 The management layer assigns one or more of the following functions to a clock
 event device:
+
       - system global periodic tick (jiffies update)
       - cpu local update_process_times
       - cpu local profiling
@@ -244,6 +248,3 @@ extended to x86_64 and ARM already. Initial (work in progress) support is also
 available for MIPS and PowerPC.
 
 	  Thomas, Ingo
-
-
-
Documentation/timers/hpet.txt +3 -1
index 895345ec513b..c9d05d3caaca 100644
@@ -1,4 +1,6 @@
-		High Precision Event Timer Driver for Linux
+===========================================
+High Precision Event Timer Driver for Linux
+===========================================
 
 The High Precision Event Timer (HPET) hardware follows a specification
 by Intel and Microsoft, revision 1.
Documentation/timers/hrtimers.txt +3 -3
index 588d85724f10..c1c20a693e8f 100644
@@ -1,6 +1,6 @@
-
+======================================================
 hrtimers - subsystem for high-resolution kernel timers
-----------------------------------------------------
+======================================================
 
 This patch introduces a new subsystem for high-resolution kernel timers.
 
@@ -146,7 +146,7 @@ the clock_getres() interface. This will return whatever real resolution
 a given clock has - be it low-res, high-res, or artificially-low-res.
 
 hrtimers - testing and verification
-----------------------------------
+-----------------------------------
 
 We used the high-resolution clock subsystem ontop of hrtimers to verify
 the hrtimer implementation details in praxis, and we also ran the posix
Documentation/timers/timekeeping.txt +2 -1
index 2d1732b0a868..f83e98852e2c 100644
@@ -1,5 +1,6 @@
+===========================================================
 Clock sources, Clock events, sched_clock() and delay timers
------------------------------------------------------------
+===========================================================
 
 This document tries to briefly explain some basic kernel timekeeping
 abstractions. It partly pertains to the drivers usually found in
Documentation/timers/timers-howto.txt +11 -4
index 038f8c77a076..7e3167bec2b1 100644
@@ -1,5 +1,6 @@
+===================================================================
 delays - Information on the various kernel delay / sleep mechanisms
--------------------------------------------------------------------
+===================================================================
 
 This document seeks to answer the common question: "What is the
 RightWay (TM) to insert a delay?"
@@ -17,7 +18,7 @@ code in an atomic context?"  This should be followed closely by "Does
 it really need to delay in atomic context?" If so...
 
 ATOMIC CONTEXT:
-	You must use the *delay family of functions. These
+	You must use the `*delay` family of functions. These
 	functions use the jiffie estimation of clock speed
 	and will busy wait for enough loop cycles to achieve
 	the desired delay:
@@ -35,21 +36,26 @@ ATOMIC CONTEXT:
 	be refactored to allow for the use of msleep.
 
 NON-ATOMIC CONTEXT:
-	You should use the *sleep[_range] family of functions.
+	You should use the `*sleep[_range]` family of functions.
 	There are a few more options here, while any of them may
 	work correctly, using the "right" sleep function will
 	help the scheduler, power management, and just make your
 	driver better :)
 
 	-- Backed by busy-wait loop:
+
 		udelay(unsigned long usecs)
+
 	-- Backed by hrtimers:
+
 		usleep_range(unsigned long min, unsigned long max)
+
 	-- Backed by jiffies / legacy_timers
+
 		msleep(unsigned long msecs)
 		msleep_interruptible(unsigned long msecs)
 
-	Unlike the *delay family, the underlying mechanism
+	Unlike the `*delay` family, the underlying mechanism
 	driving each of these calls varies, thus there are
 	quirks you should be aware of.
 
@@ -70,6 +76,7 @@ NON-ATOMIC CONTEXT:
 		- Why not msleep for (1ms - 20ms)?
 			Explained originally here:
 				http://lkml.org/lkml/2007/8/3/250
+
 			msleep(1~20) may not do what the caller intends, and
 			will often sleep longer (~20 ms actual sleep for any
 			value given in the 1~20ms range). In many cases this
Signature · 1 line
2.20.1
#62 lore raw

PATCH 36/57 docs: usb: convert documents to ReST

In reply to Mauro Carvalho Chehab

Convert USB documents to ReST, in order to prepare for adding it to the kernel API book, as most of the stuff there are driver or subsystem-related.

---
 Documentation/usb/WUSB-Design-overview.txt |  56 +-
 Documentation/usb/acm.txt                  | 156 +++---
 Documentation/usb/authorization.txt        |  75 +--
 Documentation/usb/chipidea.txt             | 101 ++--
 Documentation/usb/dwc3.txt                 |  12 +-
 Documentation/usb/ehci.txt                 |  42 +-
 Documentation/usb/functionfs.txt           |  17 +-
 Documentation/usb/gadget-testing.txt       | 609 ++++++++++++---------
 Documentation/usb/gadget_configfs.txt      | 302 +++++-----
 Documentation/usb/gadget_hid.txt           | 175 +++---
 Documentation/usb/gadget_multi.txt         |  43 +-
 Documentation/usb/gadget_printer.txt       | 155 +++---
 Documentation/usb/gadget_serial.txt        |  73 +--
 Documentation/usb/iuu_phoenix.txt          |  34 +-
 Documentation/usb/mass-storage.txt         |  19 +-
 Documentation/usb/misc_usbsevseg.txt       |   9 +-
 Documentation/usb/mtouchusb.txt            |  42 +-
 Documentation/usb/ohci.txt                 |   5 +-
 Documentation/usb/rio.txt                  |  83 +--
 Documentation/usb/usb-help.txt             |  21 +-
 Documentation/usb/usb-serial.txt           | 203 ++++---
 Documentation/usb/usbip_protocol.txt       | 552 ++++++++++---------
 Documentation/usb/usbmon.txt               | 100 ++--
 23 files changed, 1654 insertions(+), 1230 deletions(-)
Documentation/usb/WUSB-Design-overview.txt +37 -19
index fdb47637720e..dc5e21609bb5 100644
@@ -1,7 +1,9 @@
-
+================================
 Linux UWB + Wireless USB + WiNET
+================================
+
+   Copyright (C) 2005-2006 Intel Corporation
 
-   (C) 2005-2006 Intel Corporation
    Inaky Perez-Gonzalez <[email protected]>
 
    This program is free software; you can redistribute it and/or
@@ -29,6 +31,7 @@ drivers for the USB based UWB radio controllers defined in the
 Wireless USB 1.0 specification (including Wireless USB host controller
 and an Intel WiNET controller).
 
+.. Contents
    1. Introduction
          1. HWA: Host Wire adapters, your Wireless USB dongle
 
@@ -51,7 +54,8 @@ and an Intel WiNET controller).
    4. Glossary
 
 
-    Introduction
+Introduction
+============
 
 UWB is a wide-band communication protocol that is to serve also as the
 low-level protocol for others (much like TCP sits on IP). Currently
@@ -93,7 +97,8 @@ The different logical parts of this driver are:
       do the actual WUSB.
 
 
-      HWA: Host Wire adapters, your Wireless USB dongle
+HWA: Host Wire adapters, your Wireless USB dongle
+-------------------------------------------------
 
 WUSB also defines a device called a Host Wire Adaptor (HWA), which in
 mere terms is a USB dongle that enables your PC to have UWB and Wireless
@@ -125,7 +130,8 @@ The HWA itself is broken in two or three main interfaces:
       their type and kick into gear.
 
 
-      DWA: Device Wired Adaptor, a Wireless USB hub for wired devices
+DWA: Device Wired Adaptor, a Wireless USB hub for wired devices
+---------------------------------------------------------------
 
 These are the complement to HWAs. They are a USB host for connecting
 wired devices, but it is connected to your PC connected via Wireless
@@ -137,7 +143,8 @@ code with the HWA-RC driver; there is a bunch of factorization work that
 has been done to support that in upcoming releases.
 
 
-      WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter
+WHCI: Wireless Host Controller Interface, the PCI WUSB host adapter
+-------------------------------------------------------------------
 
 This is your usual PCI device that implements WHCI. Similar in concept
 to EHCI, it allows your wireless USB devices (including DWAs) to connect
@@ -148,7 +155,8 @@ There is still no driver support for this, but will be in upcoming
 releases.
 
 
-    The UWB stack
+The UWB stack
+=============
 
 The main mission of the UWB stack is to keep a tally of which devices
 are in radio proximity to allow drivers to connect to them. As well, it
@@ -156,7 +164,8 @@ provides an API for controlling the local radio controllers (RCs from
 now on), such as to start/stop beaconing, scan, allocate bandwidth, etc.
 
 
-      Devices and hosts: the basic structure
+Devices and hosts: the basic structure
+--------------------------------------
 
 The main building block here is the UWB device (struct uwb_dev). For
 each device that pops up in radio presence (ie: the UWB host receives a
@@ -187,7 +196,8 @@ the USB connected HWA. Eventually, drivers/whci-rc.c will do the same
 for the PCI connected WHCI controller.
 
 
-      Host Controller life cycle
+Host Controller life cycle
+--------------------------
 
 So let's say we connect a dongle to the system: it is detected and
 firmware uploaded if needed [for Intel's i1480
@@ -209,7 +219,8 @@ When a dongle is disconnected, /drivers/uwb/hwa-rc.c:hwarc_disconnect()/
 takes time of tearing everything down safely (or not...).
 
 
-      On the air: beacons and enumerating the radio neighborhood
+On the air: beacons and enumerating the radio neighborhood
+----------------------------------------------------------
 
 So assuming we have devices and we have agreed for a channel to connect
 on (let's say 9), we put the new RC to beacon:
@@ -235,12 +246,14 @@ are received in some time, the device is considered gone and wiped out
 the beacon cache of dead devices].
 
 
-      Device lists
+Device lists
+------------
 
 All UWB devices are kept in the list of the struct bus_type uwb_bus_type.
 
 
-      Bandwidth allocation
+Bandwidth allocation
+--------------------
 
 The UWB stack maintains a local copy of DRP availability through
 processing of incoming *DRP Availability Change* notifications. This
@@ -260,7 +273,8 @@ completion. [Note: The bandwidth reservation work is in progress and
 subject to change.]
 
 
-    Wireless USB Host Controller drivers
+Wireless USB Host Controller drivers
+====================================
 
 *WARNING* This section needs a lot of work!
 
@@ -296,7 +310,8 @@ starts sending MMCs.
 
 Now it all depends on external stimuli.
 
-*New device connection*
+New device connection
+---------------------
 
 A new device pops up, it scans the radio looking for MMCs that give out
 the existence of Wireless USB channels. Once one (or more) are found,
@@ -322,7 +337,8 @@ has seen the port status changes, as we have been toggling them. It will
 start enumerating and doing transfers through usb_hcd->urb_enqueue() to
 read descriptors and move our data.
 
-*Device life cycle and keep alives*
+Device life cycle and keep alives
+---------------------------------
 
 Every time there is a successful transfer to/from a device, we update a
 per-device activity timestamp. If not, every now and then we check and
@@ -340,7 +356,8 @@ device list looking for whom needs refreshing.
 If the device wants to disconnect, it will either die (ugly) or send a
 /DN_Disconnect/ that will prompt a disconnection from the system.
 
-*Sending and receiving data*
+Sending and receiving data
+--------------------------
 
 Data is sent and received through /Remote Pipes/ (rpipes). An rpipe is
 /aimed/ at an endpoint in a WUSB device. This is the same for HWAs and
@@ -394,7 +411,8 @@ finalize the transfer.
 For IN xfers, we only issue URBs for the segments we want to read and
 then wait for the xfer result data.
 
-*URB mapping into xfers*
+URB mapping into xfers
+^^^^^^^^^^^^^^^^^^^^^^
 
 This is done by hwahc_op_urb_[en|de]queue(). In enqueue() we aim an
 rpipe to the endpoint where we have to transmit, create a transfer
@@ -407,7 +425,8 @@ and not yet done and when all that is done, the xfer callback will be
 called--this will call the URB callback.
 
 
-    Glossary
+Glossary
+========
 
 *DWA* -- Device Wire Adapter
 
@@ -436,4 +455,3 @@ the host.
 
 Design-overview.txt-1.8 (last edited 2006-11-04 12:22:24 by
 InakyPerezGonzalez)
-
Documentation/usb/acm.txt +80 -76

207 lines not on this page · raw message

Documentation/usb/authorization.txt +41 -34

140 lines not on this page · raw message

Documentation/usb/chipidea.txt +69 -32

155 lines not on this page · raw message

Documentation/usb/dwc3.txt +10 -2
index 1d02c01d1c7c..f94a7ba16573 100644
@@ -1,6 +1,11 @@
+===========
+DWC3 driver
+===========
+
+
+TODO
+~~~~
 
- TODO
-~~~~~~
 Please pick something while reading :)
 
 - Convert interrupt handler to per-ep-thread-irq
@@ -9,6 +14,7 @@ Please pick something while reading :)
   until the command completes which is bad.
 
   Implementation idea:
+
   - dwc core implements a demultiplexing irq chip for interrupts per
     endpoint. The interrupt numbers are allocated during probe and belong
     to the device. If MSI provides per-endpoint interrupt this dummy
@@ -19,6 +25,7 @@ Please pick something while reading :)
   - dwc3_send_gadget_ep_cmd() will sleep in wait_for_completion_timeout()
     until the command completes.
   - the interrupt handler is split into the following pieces:
+
     - primary handler of the device
       goes through every event and calls generic_handle_irq() for event
       it. On return from generic_handle_irq() in acknowledges the event
@@ -40,6 +47,7 @@ Please pick something while reading :)
       for command completion.
 
   Latency:
+
    There should be no increase in latency since the interrupt-thread has a
    high priority and will be run before an average task in user land
    (except the user changed priorities).
Documentation/usb/ehci.txt +29 -13

106 lines not on this page · raw message

Documentation/usb/functionfs.txt +9 -8
index eaaaea019fc7..7fdc6d840ac5 100644
@@ -1,4 +1,6 @@
-*How FunctionFS works*
+====================
+How FunctionFS works
+====================
 
 From kernel point of view it is just a composite function with some
 unique behaviour.  It may be added to an USB configuration only after
@@ -38,13 +40,13 @@ when mounting.
 
 One can imagine a gadget that has an Ethernet, MTP and HID interfaces
 where the last two are implemented via FunctionFS.  On user space
-level it would look like this:
+level it would look like this::
 
-$ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid
-$ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp
-$ ( cd /dev/ffs-mtp && mtp-daemon ) &
-$ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid
-$ ( cd /dev/ffs-hid && hid-daemon ) &
+  $ insmod g_ffs.ko idVendor=<ID> iSerialNumber=<string> functions=mtp,hid
+  $ mkdir /dev/ffs-mtp && mount -t functionfs mtp /dev/ffs-mtp
+  $ ( cd /dev/ffs-mtp && mtp-daemon ) &
+  $ mkdir /dev/ffs-hid && mount -t functionfs hid /dev/ffs-hid
+  $ ( cd /dev/ffs-hid && hid-daemon ) &
 
 On kernel level the gadget checks ffs_data->dev_name to identify
 whether it's FunctionFS designed for MTP ("mtp") or HID ("hid").
@@ -64,4 +66,3 @@ have been written to their ep0's.
 
 Conversely, the gadget is unregistered after the first USB function
 closes its endpoints.
-
Documentation/usb/gadget-testing.txt +362 -247

950 lines not on this page · raw message

Documentation/usb/gadget_configfs.txt +154 -148

444 lines not on this page · raw message

Documentation/usb/gadget_hid.txt +90 -85

282 lines not on this page · raw message

Documentation/usb/gadget_multi.txt +29 -14

112 lines not on this page · raw message

Documentation/usb/gadget_printer.txt +84 -71

318 lines not on this page · raw message

Documentation/usb/gadget_serial.txt +38 -35

58 lines not on this page · raw message

Documentation/usb/iuu_phoenix.txt +22 -12
index e5f048067da4..b76268728450 100644

Lines of this file are not shown. View the raw message.

Documentation/usb/mass-storage.txt +14 -5
index e89803a5a960..d181b47c3cb6 100644

Lines of this file are not shown. View the raw message.

Documentation/usb/misc_usbsevseg.txt +7 -2
index 0f6be4f9930b..6274aee083ed 100644

Lines of this file are not shown. View the raw message.

Documentation/usb/mtouchusb.txt +27 -15

42 lines not on this page · raw message

Documentation/usb/ohci.txt +4 -1
index 99320d9fa523..bb3c49719e6b 100644

Lines of this file are not shown. View the raw message.

Documentation/usb/rio.txt +47 -36

83 lines not on this page · raw message

Documentation/usb/usb-help.txt +11 -10
index 4273ca2b86ba..dc23ecd4d802 100644

Lines of this file are not shown. View the raw message.

Documentation/usb/usb-serial.txt +127 -76

203 lines not on this page · raw message

Documentation/usb/usbip_protocol.txt +303 -249

552 lines not on this page · raw message

Documentation/usb/usbmon.txt +60 -40

100 lines not on this page · raw message

The rest of this diff is not shown. View the raw message.

Part of the diff is not shown here. View the raw message.

#63 lore raw

Re: [PATCH 36/57] docs: usb: convert documents to ReST

Quoted 21 lines · Mauro Carvalho Chehab

Convert USB documents to ReST, in order to prepare for adding it to the kernel API book, as most of the stuff there are driver or subsystem-related.

---
 Documentation/usb/WUSB-Design-overview.txt |  56 +-
 Documentation/usb/acm.txt                  | 156 +++---
 Documentation/usb/authorization.txt        |  75 +--
 Documentation/usb/chipidea.txt             | 101 ++--
 Documentation/usb/dwc3.txt                 |  12 +-
 Documentation/usb/ehci.txt                 |  42 +-
 Documentation/usb/functionfs.txt           |  17 +-
 Documentation/usb/gadget-testing.txt       | 609 ++++++++++++---------
 Documentation/usb/gadget_configfs.txt      | 302 +++++-----
 Documentation/usb/gadget_hid.txt           | 175 +++---
 Documentation/usb/gadget_multi.txt         |  43 +-
 Documentation/usb/gadget_printer.txt       | 155 +++---
 Documentation/usb/gadget_serial.txt        |  73 +--
 Documentation/usb/iuu_phoenix.txt          |  34 +-
 Documentation/usb/mass-storage.txt         |  19 +-
Quoted 8 lines
 Documentation/usb/misc_usbsevseg.txt       |   9 +-
 Documentation/usb/mtouchusb.txt            |  42 +-
 Documentation/usb/ohci.txt                 |   5 +-
 Documentation/usb/rio.txt                  |  83 +--
 Documentation/usb/usb-help.txt             |  21 +-
 Documentation/usb/usb-serial.txt           | 203 ++++---
 Documentation/usb/usbip_protocol.txt       | 552 ++++++++++---------
 Documentation/usb/usbmon.txt               | 100 ++--

should you change extension to .rst while at that?

#64 lore raw

Re: [PATCH 36/57] docs: usb: convert documents to ReST

Em Tue, 16 Apr 2019 09:12:32 +0300
Felipe Balbi <[email protected]> escreveu:

Quoted 32 lines
Quoted 21 lines · Mauro Carvalho Chehab

Convert USB documents to ReST, in order to prepare for adding it to the kernel API book, as most of the stuff there are driver or subsystem-related.

---
 Documentation/usb/WUSB-Design-overview.txt |  56 +-
 Documentation/usb/acm.txt                  | 156 +++---
 Documentation/usb/authorization.txt        |  75 +--
 Documentation/usb/chipidea.txt             | 101 ++--
 Documentation/usb/dwc3.txt                 |  12 +-
 Documentation/usb/ehci.txt                 |  42 +-
 Documentation/usb/functionfs.txt           |  17 +-
 Documentation/usb/gadget-testing.txt       | 609 ++++++++++++---------
 Documentation/usb/gadget_configfs.txt      | 302 +++++-----
 Documentation/usb/gadget_hid.txt           | 175 +++---
 Documentation/usb/gadget_multi.txt         |  43 +-
 Documentation/usb/gadget_printer.txt       | 155 +++---
 Documentation/usb/gadget_serial.txt        |  73 +--
 Documentation/usb/iuu_phoenix.txt          |  34 +-
 Documentation/usb/mass-storage.txt         |  19 +-
Quoted 8 lines
 Documentation/usb/misc_usbsevseg.txt       |   9 +-
 Documentation/usb/mtouchusb.txt            |  42 +-
 Documentation/usb/ohci.txt                 |   5 +-
 Documentation/usb/rio.txt                  |  83 +--
 Documentation/usb/usb-help.txt             |  21 +-
 Documentation/usb/usb-serial.txt           | 203 ++++---
 Documentation/usb/usbip_protocol.txt       | 552 ++++++++++---------
 Documentation/usb/usbmon.txt               | 100 ++--  
Quoted 1 line

should you change extension to .rst while at that?

I did that on a first version (not submitted):

	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=all_with_indexes&id=d7eec4678dbfeb1a40c58bca7a157c8a4c39fa04

but I opted do the postpone the rename to a new series yet to be sent.

The problem is that renaming it will make Sphinx to try to build them, causing lots of warnings because they won't be inside an index file. Adding index would touch Documentation/index (or Documentation/drivers-api), with would cause merge conflicts.

Once this patch gets merged upstream, a renaming patch can happen anytime. It probably makes sense to do all renames at once, late at a merge window.

Thanks,
Mauro

#65 lore raw

PATCH 37/57 docs: watchdog: convert documents to ReST format

In reply to Mauro Carvalho Chehab

Convert those documents and prepare them to be part of the kernel API book, as most of the stuff there are related to the Kernel interfaces.

Still, in the future, it would make sense to split the docs, as some of the stuff is clearly focused on sysadmin tasks.

---
 .../convert_drivers_to_kernel_api.txt         | 109 +--
 Documentation/watchdog/hpwdt.txt              |  23 +-
 Documentation/watchdog/mlx-wdt.txt            |  24 +-
 Documentation/watchdog/pcwd-watchdog.txt      |  13 +-
 Documentation/watchdog/watchdog-api.txt       |  76 +-
 .../watchdog/watchdog-kernel-api.txt          |  89 ++-
 .../watchdog/watchdog-parameters.txt          | 672 +++++++++++++-----
 Documentation/watchdog/watchdog-pm.txt        |   3 +
 Documentation/watchdog/wdt.txt                |  31 +-
 9 files changed, 733 insertions(+), 307 deletions(-)
Documentation/watchdog/convert_drivers_to_kernel_api.txt +55 -54
index 9fffb2958d13..dd934cc08e40 100644
@@ -1,6 +1,8 @@
+=========================================================
 Converting old watchdog drivers to the watchdog framework
+=========================================================
+
 by Wolfram Sang <[email protected]>
-=========================================================
 
 Before the watchdog framework came into the kernel, every driver had to
 implement the API on its own. Now, as the framework factored out the common
@@ -69,16 +71,16 @@ Here is a overview of the functions and probably needed actions:
   -ENOIOCTLCMD, the IOCTLs of the framework will be tried, too. Any other error
   is directly given to the user.
 
-Example conversion:
+Example conversion::
 
--static const struct file_operations s3c2410wdt_fops = {
--       .owner          = THIS_MODULE,
--       .llseek         = no_llseek,
--       .write          = s3c2410wdt_write,
--       .unlocked_ioctl = s3c2410wdt_ioctl,
--       .open           = s3c2410wdt_open,
--       .release        = s3c2410wdt_release,
--};
+  -static const struct file_operations s3c2410wdt_fops = {
+  -       .owner          = THIS_MODULE,
+  -       .llseek         = no_llseek,
+  -       .write          = s3c2410wdt_write,
+  -       .unlocked_ioctl = s3c2410wdt_ioctl,
+  -       .open           = s3c2410wdt_open,
+  -       .release        = s3c2410wdt_release,
+  -};
 
 Check the functions for device-specific stuff and keep it for later
 refactoring. The rest can go.
@@ -89,24 +91,24 @@ Remove the miscdevice
 
 Since the file_operations are gone now, you can also remove the 'struct
 miscdevice'. The framework will create it on watchdog_dev_register() called by
-watchdog_register_device().
+watchdog_register_device()::
 
--static struct miscdevice s3c2410wdt_miscdev = {
--       .minor          = WATCHDOG_MINOR,
--       .name           = "watchdog",
--       .fops           = &s3c2410wdt_fops,
--};
+  -static struct miscdevice s3c2410wdt_miscdev = {
+  -       .minor          = WATCHDOG_MINOR,
+  -       .name           = "watchdog",
+  -       .fops           = &s3c2410wdt_fops,
+  -};
 
 
 Remove obsolete includes and defines
 ------------------------------------
 
 Because of the simplifications, a few defines are probably unused now. Remove
-them. Includes can be removed, too. For example:
+them. Includes can be removed, too. For example::
 
-- #include <linux/fs.h>
-- #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
-- #include <linux/uaccess.h> (if no custom IOCTLs are used)
+  - #include <linux/fs.h>
+  - #include <linux/miscdevice.h> (if MODULE_ALIAS_MISCDEV is not used)
+  - #include <linux/uaccess.h> (if no custom IOCTLs are used)
 
 
 Add the watchdog operations
@@ -121,30 +123,30 @@ change the function header. Other changes are most likely not needed, because
 here simply happens the direct hardware access. If you have device-specific
 code left from the above steps, it should be refactored into these callbacks.
 
-Here is a simple example:
+Here is a simple example::
 
-+static struct watchdog_ops s3c2410wdt_ops = {
-+       .owner = THIS_MODULE,
-+       .start = s3c2410wdt_start,
-+       .stop = s3c2410wdt_stop,
-+       .ping = s3c2410wdt_keepalive,
-+       .set_timeout = s3c2410wdt_set_heartbeat,
-+};
+  +static struct watchdog_ops s3c2410wdt_ops = {
+  +       .owner = THIS_MODULE,
+  +       .start = s3c2410wdt_start,
+  +       .stop = s3c2410wdt_stop,
+  +       .ping = s3c2410wdt_keepalive,
+  +       .set_timeout = s3c2410wdt_set_heartbeat,
+  +};
 
-A typical function-header change looks like:
+A typical function-header change looks like::
 
--static void s3c2410wdt_keepalive(void)
-+static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
- {
-...
-+
-+       return 0;
- }
+  -static void s3c2410wdt_keepalive(void)
+  +static int s3c2410wdt_keepalive(struct watchdog_device *wdd)
+   {
+  ...
+  +
+  +       return 0;
+   }
 
-...
+  ...
 
--       s3c2410wdt_keepalive();
-+       s3c2410wdt_keepalive(&s3c2410_wdd);
+  -       s3c2410wdt_keepalive();
+  +       s3c2410wdt_keepalive(&s3c2410_wdd);
 
 
 Add the watchdog device
@@ -159,12 +161,12 @@ static variables. Those have to be converted to use the members in
 watchdog_device. Note that the timeout values are unsigned int. Some drivers
 use signed int, so this has to be converted, too.
 
-Here is a simple example for a watchdog device:
+Here is a simple example for a watchdog device::
 
-+static struct watchdog_device s3c2410_wdd = {
-+       .info = &s3c2410_wdt_ident,
-+       .ops = &s3c2410wdt_ops,
-+};
+  +static struct watchdog_device s3c2410_wdd = {
+  +       .info = &s3c2410_wdt_ident,
+  +       .ops = &s3c2410wdt_ops,
+  +};
 
 
 Handle the 'nowayout' feature
@@ -173,12 +175,12 @@ Handle the 'nowayout' feature
 A few drivers use nowayout statically, i.e. there is no module parameter for it
 and only CONFIG_WATCHDOG_NOWAYOUT determines if the feature is going to be
 used. This needs to be converted by initializing the status variable of the
-watchdog_device like this:
+watchdog_device like this::
 
         .status = WATCHDOG_NOWAYOUT_INIT_STATUS,
 
 Most drivers, however, also allow runtime configuration of nowayout, usually
-by adding a module parameter. The conversion for this would be something like:
+by adding a module parameter. The conversion for this would be something like::
 
 	watchdog_set_nowayout(&s3c2410_wdd, nowayout);
 
@@ -191,15 +193,15 @@ Register the watchdog device
 
 Replace misc_register(&miscdev) with watchdog_register_device(&watchdog_dev).
 Make sure the return value gets checked and the error message, if present,
-still fits. Also convert the unregister case.
+still fits. Also convert the unregister case::
 
--       ret = misc_register(&s3c2410wdt_miscdev);
-+       ret = watchdog_register_device(&s3c2410_wdd);
+  -       ret = misc_register(&s3c2410wdt_miscdev);
+  +       ret = watchdog_register_device(&s3c2410_wdd);
 
-...
+  ...
 
--       misc_deregister(&s3c2410wdt_miscdev);
-+       watchdog_unregister_device(&s3c2410_wdd);
+  -       misc_deregister(&s3c2410wdt_miscdev);
+  +       watchdog_unregister_device(&s3c2410_wdd);
 
 
 Update the Kconfig-entry
@@ -207,7 +209,7 @@ Update the Kconfig-entry
 
 The entry for the driver now needs to select WATCHDOG_CORE:
 
-+       select WATCHDOG_CORE
+  +       select WATCHDOG_CORE
 
 
 Create a patch and send it to upstream
@@ -215,4 +217,3 @@ Create a patch and send it to upstream
 
 Make sure you understood Documentation/process/submitting-patches.rst and send your patch to
 [email protected]. We are looking forward to it :)
-
Documentation/watchdog/hpwdt.txt +15 -8
index 55df692c5595..a8c6751321de 100644
@@ -1,7 +1,12 @@
+===========================
+HPE iLO NMI Watchdog Driver
+===========================
+
+for iLO based ProLiant Servers
+==============================
+
 Last reviewed: 08/20/2018
 
-                     HPE iLO NMI Watchdog Driver
-                   for iLO based ProLiant Servers
 
  The HPE iLO NMI Watchdog driver is a kernel module that provides basic
  watchdog functionality and handler for the iLO "Generate NMI to System"
@@ -20,21 +25,24 @@ Last reviewed: 08/20/2018
 
  The hpwdt driver also has the following module parameters:
 
- soft_margin - allows the user to set the watchdog timer value.
+ ============  ================================================================
+ soft_margin   allows the user to set the watchdog timer value.
                Default value is 30 seconds.
- timeout     - an alias of soft_margin.
- pretimeout  - allows the user to set the watchdog pretimeout value.
+ timeout       an alias of soft_margin.
+ pretimeout    allows the user to set the watchdog pretimeout value.
                This is the number of seconds before timeout when an
                NMI is delivered to the system. Setting the value to
                zero disables the pretimeout NMI.
                Default value is 9 seconds.
- nowayout    - basic watchdog parameter that does not allow the timer to
+ nowayout      basic watchdog parameter that does not allow the timer to
                be restarted or an impending ASR to be escaped.
                Default value is set when compiling the kernel. If it is set
                to "Y", then there is no way of disabling the watchdog once
                it has been started.
+ ============  ================================================================
 
- NOTE: More information about watchdog drivers in general, including the ioctl
+ NOTE:
+       More information about watchdog drivers in general, including the ioctl
        interface to /dev/watchdog can be found in
        Documentation/watchdog/watchdog-api.txt and Documentation/IPMI.txt.
 
@@ -63,4 +71,3 @@ Last reviewed: 08/20/2018
 
  The HPE iLO NMI Watchdog Driver and documentation were originally developed
  by Tom Mingarelli.
-
Documentation/watchdog/mlx-wdt.txt +14 -10
index 66eeb78505c3..bf5bafac47f0 100644
@@ -1,5 +1,9 @@
-		Mellanox watchdog drivers
-		for x86 based system switches
+=========================
+Mellanox watchdog drivers
+=========================
+
+for x86 based system switches
+=============================
 
 This driver provides watchdog functionality for various Mellanox
 Ethernet and Infiniband switch systems.
@@ -9,16 +13,16 @@ Mellanox watchdog device is implemented in a programmable logic device.
 There are 2 types of HW watchdog implementations.
 
 Type 1:
-Actual HW timeout can be defined as a power of 2 msec.
-e.g. timeout 20 sec will be rounded up to 32768 msec.
-The maximum timeout period is 32 sec (32768 msec.),
-Get time-left isn't supported
+  Actual HW timeout can be defined as a power of 2 msec.
+  e.g. timeout 20 sec will be rounded up to 32768 msec.
+  The maximum timeout period is 32 sec (32768 msec.),
+  Get time-left isn't supported
 
 Type 2:
-Actual HW timeout is defined in sec. and it's the same as
-a user-defined timeout.
-Maximum timeout is 255 sec.
-Get time-left is supported.
+  Actual HW timeout is defined in sec. and it's the same as
+  a user-defined timeout.
+  Maximum timeout is 255 sec.
+  Get time-left is supported.
 
 Type 1 HW watchdog implementation exist in old systems and
 all new systems have type 2 HW watchdog.
Documentation/watchdog/pcwd-watchdog.txt +9 -4
index b8e60a441a43..405e2a370082 100644
@@ -1,8 +1,13 @@
+===================================
+Berkshire Products PC Watchdog Card
+===================================
+
 Last reviewed: 10/05/2007
 
-                     Berkshire Products PC Watchdog Card
-                   Support for ISA Cards  Revision A and C
-           Documentation and Driver by Ken Hollis <[email protected]>
+Support for ISA Cards  Revision A and C
+=======================================
+
+Documentation and Driver by Ken Hollis <[email protected]>
 
  The PC Watchdog is a card that offers the same type of functionality that
  the WDT card does, only it doesn't require an IRQ to run.  Furthermore,
@@ -33,6 +38,7 @@ Last reviewed: 10/05/2007
 	WDIOC_GETSUPPORT
 		This returns the support of the card itself.  This
 		returns in structure "PCWDS" which returns:
+
 			options = WDIOS_TEMPPANIC
 				  (This card supports temperature)
 			firmware_version = xxxx
@@ -63,4 +69,3 @@ Last reviewed: 10/05/2007
 
  -- Ken Hollis
     ([email protected])
-
Documentation/watchdog/watchdog-api.txt +55 -21

240 lines not on this page · raw message

Documentation/watchdog/watchdog-kernel-api.txt +61 -28

248 lines not on this page · raw message

Documentation/watchdog/watchdog-parameters.txt +499 -173

909 lines not on this page · raw message

Documentation/watchdog/watchdog-pm.txt +3 -0
index 7a4dd46e0d24..646e1f28f31f 100644
@@ -1,5 +1,7 @@
+===============================================
 The Linux WatchDog Timer Power Management Guide
 ===============================================
+
 Last reviewed: 17-Dec-2018
 
 Wolfram Sang <[email protected]>
@@ -16,4 +18,5 @@ On resume, a watchdog timer shall be reset to its selected value to give
 userspace enough time to resume. [1] [2]
 
 [1] https://patchwork.kernel.org/patch/10252209/
+
 [2] https://patchwork.kernel.org/patch/10711625/
Documentation/watchdog/wdt.txt +22 -9
index ed2f0b860869..d97b0361535b 100644
@@ -1,11 +1,14 @@
+============================================================
+WDT Watchdog Timer Interfaces For The Linux Operating System
+============================================================
+
 Last Reviewed: 10/05/2007
 
-	WDT Watchdog Timer Interfaces For The Linux Operating System
-		Alan Cox <[email protected]>
+Alan Cox <[email protected]>
 
-	ICS	WDT501-P
-	ICS	WDT501-P (no fan tachometer)
-	ICS	WDT500-P
+	- ICS	WDT501-P
+	- ICS	WDT501-P (no fan tachometer)
+	- ICS	WDT500-P
 
 All the interfaces provide /dev/watchdog, which when open must be written
 to within a timeout or the machine will reboot. Each write delays the reboot
@@ -21,19 +24,26 @@ degrees Fahrenheit. Each read returns a single byte giving the temperature.
 The third interface logs kernel messages on additional alert events.
 
 The ICS ISA-bus wdt card cannot be safely probed for. Instead you need to
-pass IO address and IRQ boot parameters.  E.g.:
+pass IO address and IRQ boot parameters.  E.g.::
+
 	wdt.io=0x240 wdt.irq=11
 
 Other "wdt" driver parameters are:
+
+	===========	======================================================
 	heartbeat	Watchdog heartbeat in seconds (default 60)
 	nowayout	Watchdog cannot be stopped once started (kernel
-				build parameter)
+			build parameter)
 	tachometer	WDT501-P Fan Tachometer support (0=disable, default=0)
 	type		WDT501-P Card type (500 or 501, default=500)
+	===========	======================================================
 
 Features
 --------
-		WDT501P		WDT500P
+
+================   =======	   =======
+		   WDT501P	   WDT500P
+================   =======	   =======
 Reboot Timer	   X               X
 External Reboot	   X	           X
 I/O Port Monitor   o		   o
@@ -42,9 +52,12 @@ Fan Speed          X		   o
 Power Under	   X               o
 Power Over         X               o
 Overheat           X               o
+================   =======	   =======
 
 The external event interfaces on the WDT boards are not currently supported.
 Minor numbers are however allocated for it.
 
 
-Example Watchdog Driver:  see samples/watchdog/watchdog-simple.c
+Example Watchdog Driver:
+
+	see samples/watchdog/watchdog-simple.c
Signature · 1 line
2.20.1