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
#2 lore raw

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

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
#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
#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
#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
#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
#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
#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
#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.

#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
#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
#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
#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.

#82 lore raw

PATCH 51/57 docs: arm: convert text files to ReST format

In reply to Mauro Carvalho Chehab

Converts ARM the text files to ReST, preparing them to be an architecture book.

---
 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/index.rst                       |   1 +
 75 files changed, 1532 insertions(+), 1107 deletions(-)
 delete mode 100644 Documentation/arm/SA1100/empeg
Documentation/arm/Booting +45 -26
index f1f965ce93d6..4babb6c6ae1e 100644
@@ -1,7 +1,9 @@
-			Booting ARM Linux
-			=================
+=================
+Booting ARM Linux
+=================
 
 Author:	Russell King
+
 Date  : 18 May 2002
 
 The following documentation is relevant to 2.4.18-rmk6 and beyond.
@@ -25,8 +27,10 @@ following:
 1. Setup and initialise RAM
 ---------------------------
 
-Existing boot loaders:		MANDATORY
-New boot loaders:		MANDATORY
+Existing boot loaders:
+	MANDATORY
+New boot loaders:
+	MANDATORY
 
 The boot loader is expected to find and initialise all RAM that the
 kernel will use for volatile data storage in the system.  It performs
@@ -39,8 +43,10 @@ sees fit.)
 2. Initialise one serial port
 -----------------------------
 
-Existing boot loaders:		OPTIONAL, RECOMMENDED
-New boot loaders:		OPTIONAL, RECOMMENDED
+Existing boot loaders:
+	OPTIONAL, RECOMMENDED
+New boot loaders:
+	OPTIONAL, RECOMMENDED
 
 The boot loader should initialise and enable one serial port on the
 target.  This allows the kernel serial driver to automatically detect
@@ -57,8 +63,10 @@ serial format options as described in
 3. Detect the machine type
 --------------------------
 
-Existing boot loaders:		OPTIONAL
-New boot loaders:		MANDATORY except for DT-only platforms
+Existing boot loaders:
+	OPTIONAL
+New boot loaders:
+	MANDATORY except for DT-only platforms
 
 The boot loader should detect the machine type its running on by some
 method.  Whether this is a hard coded value or some algorithm that
@@ -74,8 +82,10 @@ necessary, but assures that it will not match any existing types.
 4. Setup boot data
 ------------------
 
-Existing boot loaders:		OPTIONAL, HIGHLY RECOMMENDED
-New boot loaders:		MANDATORY
+Existing boot loaders:
+	OPTIONAL, HIGHLY RECOMMENDED
+New boot loaders:
+	MANDATORY
 
 The boot loader must provide either a tagged list or a dtb image for
 passing configuration data to the kernel.  The physical address of the
@@ -97,15 +107,15 @@ entirety; some tags behave as the former, others the latter.
 
 The boot loader must pass at a minimum the size and location of
 the system memory, and root filesystem location.  Therefore, the
-minimum tagged list should look:
+minimum tagged list should look::
 
-	+-----------+
-base ->	| ATAG_CORE |  |
-	+-----------+  |
-	| ATAG_MEM  |  | increasing address
-	+-----------+  |
-	| ATAG_NONE |  |
-	+-----------+  v
+		+-----------+
+  base ->	| ATAG_CORE |  |
+		+-----------+  |
+		| ATAG_MEM  |  | increasing address
+		+-----------+  |
+		| ATAG_NONE |  |
+		+-----------+  v
 
 The tagged list should be stored in system RAM.
 
@@ -134,8 +144,10 @@ A safe location is just above the 128MiB boundary from start of RAM.
 5. Load initramfs.
 ------------------
 
-Existing boot loaders:		OPTIONAL
-New boot loaders:		OPTIONAL
+Existing boot loaders:
+	OPTIONAL
+New boot loaders:
+	OPTIONAL
 
 If an initramfs is in use then, as with the dtb, it must be placed in
 a region of memory where the kernel decompressor will not overwrite it
@@ -149,8 +161,10 @@ recommended above.
 6. Calling the kernel image
 ---------------------------
 
-Existing boot loaders:		MANDATORY
-New boot loaders:		MANDATORY
+Existing boot loaders:
+	MANDATORY
+New boot loaders:
+	MANDATORY
 
 There are two options for calling the kernel zImage.  If the zImage
 is stored in flash, and is linked correctly to be run from flash,
@@ -174,12 +188,14 @@ In any case, the following conditions must be met:
   you many hours of debug.
 
 - CPU register settings
-  r0 = 0,
-  r1 = machine type number discovered in (3) above.
-  r2 = physical address of tagged list in system RAM, or
-       physical address of device tree block (dtb) in system RAM
+
+  - r0 = 0,
+  - r1 = machine type number discovered in (3) above.
+  - r2 = physical address of tagged list in system RAM, or
+    physical address of device tree block (dtb) in system RAM
 
 - CPU mode
+
   All forms of interrupts must be disabled (IRQs and FIQs)
 
   For CPUs which do not include the ARM virtualization extensions, the
@@ -195,8 +211,11 @@ In any case, the following conditions must be met:
   entered in SVC mode.
 
 - Caches, MMUs
+
   The MMU must be off.
+
   Instruction cache may be on or off.
+
   Data cache must be off.
 
   If the kernel is entered in HYP mode, the above requirements apply to
Documentation/arm/IXP4xx +31 -30

135 lines not on this page · raw message

Documentation/arm/Interrupts +44 -42

141 lines not on this page · raw message

Documentation/arm/Marvell/README +315 -222

629 lines not on this page · raw message

Documentation/arm/Microchip/README +49 -14

160 lines not on this page · raw message

Documentation/arm/Netwinder +33 -26

95 lines not on this page · raw message

Documentation/arm/OMAP/DSS +61 -51

167 lines not on this page · raw message

Documentation/arm/OMAP/README +7 -0
index 90c6c57d61e8..f440c0f4613f 100644
@@ -1,7 +1,13 @@
+============
+OMAP history
+============
+
 This file contains documentation for running mainline
 kernel on omaps.
 
+======		======================================================
 KERNEL		NEW DEPENDENCIES
+======		======================================================
 v4.3+		Update is needed for custom .config files to make sure
 		CONFIG_REGULATOR_PBIAS is enabled for MMC1 to work
 		properly.
@@ -9,3 +15,4 @@ v4.3+		Update is needed for custom .config files to make sure
 v4.18+		Update is needed for custom .config files to make sure
 		CONFIG_MMC_SDHCI_OMAP is enabled for all MMC instances
 		to work in DRA7 and K2G based boards.
+======		======================================================
Documentation/arm/OMAP/omap_pm +33 -22

109 lines not on this page · raw message

Documentation/arm/Porting +8 -6
index a492233931b9..bd21958bdb2d 100644
@@ -1,3 +1,7 @@
+=======
+Porting
+=======
+
 Taken from list archive at http://lists.arm.linux.org.uk/pipermail/linux-arm-kernel/2001-July/004064.html
 
 Initial definitions
@@ -89,8 +93,7 @@ DATAADDR
 	Virtual address for the kernel data segment.  Must not be defined
 	when using the decompressor.
 
-VMALLOC_START
-VMALLOC_END
+VMALLOC_START / VMALLOC_END
 	Virtual addresses bounding the vmalloc() area.  There must not be
 	any static mappings in this area; vmalloc will overwrite them.
 	The addresses must also be in the kernel segment (see above).
@@ -107,13 +110,13 @@ Architecture Specific Macros
 ----------------------------
 
 BOOT_MEM(pram,pio,vio)
-	`pram' specifies the physical start address of RAM.  Must always
+	`pram` specifies the physical start address of RAM.  Must always
 	be present, and should be the same as PHYS_OFFSET.
 
-	`pio' is the physical address of an 8MB region containing IO for
+	`pio` is the physical address of an 8MB region containing IO for
 	use with the debugging macros in arch/arm/kernel/debug-armv.S.
 
-	`vio' is the virtual address of the 8MB debugging region.
+	`vio` is the virtual address of the 8MB debugging region.
 
 	It is expected that the debugging region will be re-initialised
 	by the architecture specific code later in the code (via the
@@ -132,4 +135,3 @@ MAPIO(func)
 
 INITIRQ(func)
 	Machine specific function to initialise interrupts.
-
Documentation/arm/README +30 -20

106 lines not on this page · raw message

Documentation/arm/SA1100/ADSBitsy +11 -3
index f9f62e8c0719..c179cb26b682 100644
@@ -1,4 +1,7 @@
+===============================
 ADS Bitsy Single Board Computer
+===============================
+
 (It is different from Bitsy(iPAQ) of Compaq)
 
 For more details, contact Applied Data Systems or see
@@ -15,7 +18,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000.
 Linux can  be used with the ADS BootLoader that ships with the
 newer rev boards. See their documentation on how to load Linux.
 
-Supported peripherals:
+Supported peripherals
+=====================
+
 - SA1100 LCD frame buffer (8/16bpp...sort of)
 - SA1111 USB Master
 - SA1100 serial port
@@ -25,10 +30,13 @@ Supported peripherals:
 - serial ports (ttyS[0-2])
   - ttyS0 is default for serial console
 
-To do:
+To do
+=====
+
 - everything else!  :-)
 
-Notes:
+Notes
+=====
 
 - The flash on board is divided into 3 partitions.
   You should be careful to use flash on board.
Documentation/arm/SA1100/Assabet +93 -92

303 lines not on this page · raw message

Documentation/arm/SA1100/Brutus +24 -21

76 lines not on this page · raw message

Documentation/arm/SA1100/CERF +8 -2
index b3d845301ef1..7fa71b609bf9 100644
@@ -1,3 +1,7 @@
+==============
+CerfBoard/Cube
+==============
+
 *** The StrongARM version of the CerfBoard/Cube has been discontinued ***
 
 The Intrinsyc CerfBoard is a StrongARM 1110-based computer on a board
@@ -9,7 +13,9 @@ Intrinsyc website, http://www.intrinsyc.com.
 This document describes the support in the Linux kernel for the
 Intrinsyc CerfBoard.
 
-Supported in this version:
+Supported in this version
+=========================
+
    - CompactFlash+ slot (select PCMCIA in General Setup and any options
      that may be required)
    - Onboard Crystal CS8900 Ethernet controller (Cerf CS8900A support in
@@ -19,7 +25,7 @@ Supported in this version:
 In order to get this kernel onto your Cerf, you need a server that runs
 both BOOTP and TFTP. Detailed instructions should have come with your
 evaluation kit on how to use the bootloader. This series of commands
-will suffice:
+will suffice::
 
    make ARCH=arm CROSS_COMPILE=arm-linux- cerfcube_defconfig
    make ARCH=arm CROSS_COMPILE=arm-linux- zImage
Documentation/arm/SA1100/FreeBird +15 -11
index ab9193663b2b..81043d0c6d64 100644
@@ -1,21 +1,25 @@
+========
+Freebird
+========
+
 Freebird-1.1 is produced by Legend(C), Inc.
-http://web.archive.org/web/*/http://www.legend.com.cn
+`http://web.archive.org/web/*/http://www.legend.com.cn`
 and software/linux maintained by Coventive(C), Inc.
 (http://www.coventive.com)
 
 Based on the Nicolas's strongarm kernel tree.
 
-===============================================================
 Maintainer:
 
-Chester Kuo <[email protected]>
-	    <[email protected]>
+Chester Kuo
+	- <[email protected]>
+	- <[email protected]>
 
-Author :
-Tim wu <[email protected]>
-CIH <[email protected]>
-Eric Peng <[email protected]>
-Jeff Lee <[email protected]>
-Allen Cheng
-Tony Liu <[email protected]>
+Author:
 
+- Tim wu <[email protected]>
+- CIH <[email protected]>
+- Eric Peng <[email protected]>
+- Jeff Lee <[email protected]>
+- Allen Cheng
+- Tony Liu <[email protected]>
Documentation/arm/SA1100/GraphicsClient +25 -21

87 lines not on this page · raw message

Documentation/arm/SA1100/GraphicsMaster +10 -3
index 9145088a0ba2..e39892514f0c 100644
@@ -1,4 +1,6 @@
+========================================
 ADS GraphicsMaster Single Board Computer
+========================================
 
 For more details, contact Applied Data Systems or see
 http://www.applieddata.net/products.html
@@ -15,7 +17,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000.
 Linux can  be used with the ADS BootLoader that ships with the
 newer rev boards. See their documentation on how to load Linux.
 
-Supported peripherals:
+Supported peripherals
+=====================
+
 - SA1100 LCD frame buffer (8/16bpp...sort of)
 - SA1111 USB Master
 - on-board SMC 92C96 ethernet NIC
@@ -31,10 +35,13 @@ Supported peripherals:
   See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
   and example user space code. ps/2 keybd is multiplexed through this driver
 
-To do:
+To do
+=====
+
 - everything else!  :-)
 
-Notes:
+Notes
+=====
 
 - The flash on board is divided into 3 partitions.  mtd0 is where
   the zImage is stored.  It's been marked as read-only to keep you
Documentation/arm/SA1100/HUW_WEBPANEL +6 -2
index fd56b48d4833..1dc7ccb165f0 100644
@@ -1,9 +1,14 @@
+=======================
+Hoeft & Wessel Webpanel
+=======================
+
 The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG
 
 If you want more information, please visit
 http://www.hoeft-wessel.de
 
-To build the kernel:
+To build the kernel::
+
 	make huw_webpanel_config
 	make oldconfig
 	[accept all defaults]
@@ -14,4 +19,3 @@ Roman Jordan         [email protected]
 Christoph Schulz    [email protected]
 
 2000/12/18/
-
Documentation/arm/SA1100/Itsy +11 -3
index 44b94997fa0d..f49896ba3ef1 100644
@@ -1,3 +1,7 @@
+====
+Itsy
+====
+
 Itsy is a research project done by the Western Research Lab, and Systems
 Research Center in Palo Alto, CA. The Itsy project is one of several
 research projects at Compaq that are related to pocket computing.
@@ -7,6 +11,7 @@ For more information, see:
 	http://www.hpl.hp.com/downloads/crl/itsy/
 
 Notes on initial 2.4 Itsy support (8/27/2000) :
+
 The port was done on an Itsy version 1.5 machine with a daughtercard with
 64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for
 serial console (to see what you're doing).  No other devices have been
@@ -18,8 +23,10 @@ Finally, you will need to cd to arch/arm/boot/tools and execute a make there
 to build the params-itsy program used to boot the kernel.
 
 In order to install the port of 2.4 to the itsy, You will need to set the
-configuration parameters in the monitor as follows:
-Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0
+configuration parameters in the monitor as follows::
+
+	Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0
+
 Make sure the start-routine address is set to 0x00060000.
 
 Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the
@@ -29,7 +36,8 @@ flash menu)  Flash the kernel in arch/arm/boot/zImage into 0x08340000
 handhelds.org.
 
 The serial connection we established was at:
- 8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the
+
+8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the
 params-itsy program, and in the kernel itself.  This can be changed, but
 not easily. The monitor parameters are easily changed, the params program
 setup is assembly outl's, and the kernel is a configuration item specific to
Documentation/arm/SA1100/LART +2 -1
index 6d412b685598..94c0568d1095 100644
@@ -1,5 +1,6 @@
+====================================
 Linux Advanced Radio Terminal (LART)
-------------------------------------
+====================================
 
 The LART is a small (7.5 x 10cm) SA-1100 board, designed for embedded
 applications. It has 32 MB DRAM, 4MB Flash ROM, double RS232 and all
Documentation/arm/SA1100/PLEB +4 -2
index b9c8a631a351..d5b732967aa3 100644
@@ -1,3 +1,7 @@
+====
+PLEB
+====
+
 The PLEB project was started as a student initiative at the School of
 Computer Science and Engineering, University of New South Wales to make a
 pocket computer capable of running the Linux Kernel.
@@ -7,5 +11,3 @@ PLEB support has yet to be fully integrated.
 For more information, see:
 
 	http://www.cse.unsw.edu.au
-
-
Documentation/arm/SA1100/Pangolin +8 -2
index 077a6120e129..f0c5c1618553 100644
@@ -1,16 +1,22 @@
+========
+Pangolin
+========
+
 Pangolin is a StrongARM 1110-based evaluation platform produced
 by Dialogue Technology (http://www.dialogue.com.tw/).
 It has EISA slots for ease of configuration with SDRAM/Flash
 memory card, USB/Serial/Audio card, Compact Flash card,
 PCMCIA/IDE card and TFT-LCD card.
 
-To compile for Pangolin, you must issue the following commands:
+To compile for Pangolin, you must issue the following commands::
 
 	make pangolin_config
 	make oldconfig
 	make zImage
 
-Supported peripherals:
+Supported peripherals
+=====================
+
 - SA1110 serial port (UART1/UART2/UART3)
 - flash memory access
 - compact flash driver
Documentation/arm/SA1100/Tifon +2 -2
index dd1934d9c851..c26e910b9ea7 100644
@@ -1,7 +1,7 @@
+=====
 Tifon
------
+=====
 
 More info has to come...
 
 Contact: Peter Danielsson <[email protected]>
-
Documentation/arm/SA1100/Yopy +4 -1
index e14f16d836ac..5b35a5f61a44 100644
@@ -1,2 +1,5 @@
-See http://www.yopydeveloper.org for more.
+====
+Yopy
+====
 
+See http://www.yopydeveloper.org for more.
Documentation/arm/SA1100/empeg deleted +0 -2
deleted file mode 100644
index 4ece4849a42c..000000000000
@@ -1,2 +0,0 @@
-See ../empeg/README
-
Documentation/arm/SA1100/nanoEngine +3 -3
index 48a7934f95f6..47f1a14cf98a 100644
@@ -1,11 +1,11 @@
+==========
 nanoEngine
-----------
+==========
 
-"nanoEngine" is a SA1110 based single board computer from 
+"nanoEngine" is a SA1110 based single board computer from
 Bright Star Engineering Inc.  See www.brightstareng.com/arm
 for more info.
 (Ref: Stuart Adams <[email protected]>)
 
 Also visit Larry Doolittle's "Linux for the nanoEngine" site:
 http://www.brightstareng.com/arm/nanoeng.htm
-
Documentation/arm/SA1100/serial_UART +32 -28

74 lines not on this page · raw message

Documentation/arm/SPEAr/overview.txt +11 -9
index 1b049be6c84f..8a1a87aca427 100644
@@ -1,5 +1,6 @@
-			SPEAr ARM Linux Overview
-			==========================
+========================
+SPEAr ARM Linux Overview
+========================
 
 Introduction
 ------------
@@ -30,17 +31,18 @@ Introduction
 		- SPEAr1340 (SOC)
 			- SPEAr1340 Evaluation Board
 
-  Configuration
-  -------------
+Configuration
+-------------
 
   A generic configuration is provided for each machine, and can be used as the
-  default by
+  default by::
+
 	make spear13xx_defconfig
 	make spear3xx_defconfig
 	make spear6xx_defconfig
 
-  Layout
-  ------
+Layout
+------
 
   The common files for multiple machine families (SPEAr3xx, SPEAr6xx and
   SPEAr13xx) are located in the platform code contained in arch/arm/plat-spear
@@ -57,7 +59,7 @@ Introduction
   support Flattened Device Tree.
 
 
-  Document Author
-  ---------------
+Document Author
+---------------
 
   Viresh Kumar <[email protected]>, (c) 2010-2012 ST Microelectronics
Documentation/arm/Samsung-S3C24XX/CPUfreq.txt +3 -2
index fa968aa99d67..2ddc26c03b1f 100644
@@ -1,5 +1,6 @@
-		S3C24XX CPUfreq support
-		=======================
+=======================
+S3C24XX CPUfreq support
+=======================
 
 Introduction
 ------------
Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt +3 -2
index b87292e05f2f..7863c93652f8 100644
@@ -1,5 +1,6 @@
-		Simtec Electronics EB2410ITX (BAST)
-		===================================
+===================================
+Simtec Electronics EB2410ITX (BAST)
+===================================
 
 	http://www.simtec.co.uk/products/EB2410ITX/
 
Documentation/arm/Samsung-S3C24XX/GPIO.txt +11 -10
index e8f918b96123..021930591ace 100644
@@ -1,5 +1,6 @@
-			S3C24XX GPIO Control
-			====================
+====================
+S3C24XX GPIO Control
+====================
 
 Introduction
 ------------
@@ -26,16 +27,16 @@ GPIOLIB
   listed below will be removed (they may be marked as __deprecated
   in the near future).
 
-  The following functions now either have a s3c_ specific variant
+  The following functions now either have a `s3c_` specific variant
   or are merged into gpiolib. See the definitions in
   arch/arm/plat-samsung/include/plat/gpio-cfg.h:
 
-  s3c2410_gpio_setpin()		gpio_set_value() or gpio_direction_output()
-  s3c2410_gpio_getpin()		gpio_get_value() or gpio_direction_input()
-  s3c2410_gpio_getirq()		gpio_to_irq()
-  s3c2410_gpio_cfgpin()		s3c_gpio_cfgpin()
-  s3c2410_gpio_getcfg()		s3c_gpio_getcfg()
-  s3c2410_gpio_pullup()		s3c_gpio_setpull()
+  - s3c2410_gpio_setpin()	gpio_set_value() or gpio_direction_output()
+  - s3c2410_gpio_getpin()	gpio_get_value() or gpio_direction_input()
+  - s3c2410_gpio_getirq()	gpio_to_irq()
+  - s3c2410_gpio_cfgpin()	s3c_gpio_cfgpin()
+  - s3c2410_gpio_getcfg()	s3c_gpio_getcfg()
+  - s3c2410_gpio_pullup()	s3c_gpio_setpull()
 
 
 GPIOLIB conversion
@@ -77,7 +78,7 @@ out s3c2410 API, then here are some notes on the process.
 6) s3c2410_gpio_getirq() should be directly replaceable with the
    gpio_to_irq() call.
 
-The s3c2410_gpio and gpio_ calls have always operated on the same gpio
+The s3c2410_gpio and `gpio_` calls have always operated on the same gpio
 numberspace, so there is no problem with converting the gpio numbering
 between the calls.
 
Documentation/arm/Samsung-S3C24XX/H1940.txt +3 -2
index b738859b1fc0..62a562c178e3 100644
@@ -1,5 +1,6 @@
-		HP IPAQ H1940
-		=============
+=============
+HP IPAQ H1940
+=============
 
 http://www.handhelds.org/projects/h1940.html
 
Documentation/arm/Samsung-S3C24XX/NAND.txt +3 -3
index bc478a3409b8..938995694ee7 100644
@@ -1,5 +1,6 @@
-			S3C24XX NAND Support
-			====================
+====================
+S3C24XX NAND Support
+====================
 
 Introduction
 ------------
@@ -27,4 +28,3 @@ Document Author
 ---------------
 
 Ben Dooks, Copyright 2007 Simtec Electronics
-
Documentation/arm/Samsung-S3C24XX/Overview.txt +8 -7
index 00d3c3141e21..0d8e59df7512 100644
@@ -1,5 +1,6 @@
-			S3C24XX ARM Linux Overview
-			==========================
+==========================
+S3C24XX ARM Linux Overview
+==========================
 
 
 
@@ -276,18 +277,18 @@ Platform Data
        kmalloc()s an area of memory, and copies the __initdata
        and then sets the relevant device's platform data. Making
        the function `__init` takes care of ensuring it is discarded
-       with the rest of the initialisation code
+       with the rest of the initialisation code::
 
-       static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd)
-       {
-           struct s3c2410_xxx_mach_info *npd;
+         static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd)
+         {
+             struct s3c2410_xxx_mach_info *npd;
 
 	   npd = kmalloc(sizeof(struct s3c2410_xxx_mach_info), GFP_KERNEL);
 	   if (npd) {
 	      memcpy(npd, pd, sizeof(struct s3c2410_xxx_mach_info));
 	      s3c_device_xxx.dev.platform_data = npd;
 	   } else {
-              printk(KERN_ERR "no memory for xxx platform data\n");
+                printk(KERN_ERR "no memory for xxx platform data\n");
 	   }
 	}
 
Documentation/arm/Samsung-S3C24XX/S3C2412.txt +3 -2
index dc1fd362d3c1..68b985fc6bf4 100644
@@ -1,5 +1,6 @@
-		S3C2412 ARM Linux Overview
-		==========================
+==========================
+S3C2412 ARM Linux Overview
+==========================
 
 Introduction
 ------------
Documentation/arm/Samsung-S3C24XX/S3C2413.txt +4 -3
index 909bdc7dd7b5..1f51e207fc46 100644
@@ -1,5 +1,6 @@
-		S3C2413 ARM Linux Overview
-		==========================
+==========================
+S3C2413 ARM Linux Overview
+==========================
 
 Introduction
 ------------
@@ -10,7 +11,7 @@ Introduction
 
 
 Camera Interface
----------------
+----------------
 
   This block is currently not supported.
 
Documentation/arm/Samsung-S3C24XX/SMDK2440.txt +3 -2
index 429390bd4684..524fd0b4afaf 100644
@@ -1,5 +1,6 @@
-		Samsung/Meritech SMDK2440
-		=========================
+=========================
+Samsung/Meritech SMDK2440
+=========================
 
 Introduction
 ------------
Documentation/arm/Samsung-S3C24XX/Suspend.txt +10 -10
index cb4f0c0cdf9d..b4f3ae9fe76e 100644
@@ -1,5 +1,6 @@
-			S3C24XX Suspend Support
-			=======================
+=======================
+S3C24XX Suspend Support
+=======================
 
 
 Introduction
@@ -57,16 +58,16 @@ Machine Support
   and will end up initialising all compiled machines' pm init!
 
   The following is an example of code used for testing wakeup from
-  an falling edge on IRQ_EINT0:
+  an falling edge on IRQ_EINT0::
 
 
-static irqreturn_t button_irq(int irq, void *pw)
-{
+    static irqreturn_t button_irq(int irq, void *pw)
+    {
 	return IRQ_HANDLED;
-}
+    }
 
-statuc void __init machine_init(void)
-{
+    statuc void __init machine_init(void)
+    {
 	...
 
 	request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING,
@@ -75,7 +76,7 @@ statuc void __init machine_init(void)
 	enable_irq_wake(IRQ_EINT0);
 
 	s3c_pm_init();
-}
+    }
 
 
 Debugging
@@ -134,4 +135,3 @@ Document Author
 ---------------
 
 Ben Dooks, Copyright 2004 Simtec Electronics
-
Documentation/arm/Samsung-S3C24XX/USB-Host.txt +7 -9
index f82b1faefad5..c84268bd1884 100644
@@ -1,5 +1,6 @@
-			S3C24XX USB Host support
-			========================
+========================
+S3C24XX USB Host support
+========================
 
 
 
@@ -13,7 +14,7 @@ Configuration
 
   Enable at least the following kernel options:
 
-  menuconfig:
+  menuconfig::
 
    Device Drivers  --->
      USB support  --->
@@ -22,8 +23,9 @@ Configuration
 
 
   .config:
-    CONFIG_USB
-    CONFIG_USB_OHCI_HCD
+
+    - CONFIG_USB
+    - CONFIG_USB_OHCI_HCD
 
 
   Once these options are configured, the standard set of USB device
@@ -60,17 +62,14 @@ Platform Data
   The ports are numbered 0 and 1.
 
   power_control:
-
     Called to enable or disable the power on the port.
 
   enable_oc:
-
     Called to enable or disable the over-current monitoring.
     This should claim or release the resources being used to
     check the power condition on the port, such as an IRQ.
 
   report_oc:
-
     The OHCI driver fills this field in for the over-current code
     to call when there is a change to the over-current state on
     an port. The ports argument is a bitmask of 1 bit per port,
@@ -80,7 +79,6 @@ Platform Data
     ensure this is called correctly.
 
   port[x]:
-
     This is struct describes each port, 0 or 1. The platform driver
     should set the flags field of each port to S3C_HCDFLG_USED if
     the port is enabled.
Documentation/arm/Samsung/Bootloader-interface.txt +20 -7
index d17ed518a7ea..a56f325dae78 100644
@@ -1,7 +1,9 @@
-      Interface between kernel and boot loaders on Exynos boards
-      ==========================================================
+==========================================================
+Interface between kernel and boot loaders on Exynos boards
+==========================================================
 
 Author: Krzysztof Kozlowski
+
 Date  : 6 June 2015
 
 The document tries to describe currently used interface between Linux kernel
@@ -17,8 +19,10 @@ executing kernel.
 1. Non-Secure mode
 
 Address:      sysram_ns_base_addr
+
+============= ============================================ ==================
 Offset        Value                                        Purpose
-=============================================================================
+============= ============================================ ==================
 0x08          exynos_cpu_resume_ns, mcpm_entry_point       System suspend
 0x0c          0x00000bad (Magic cookie)                    System suspend
 0x1c          exynos4_secondary_startup                    Secondary CPU boot
@@ -27,22 +31,28 @@ Offset        Value                                        Purpose
 0x24          exynos_cpu_resume_ns                         AFTR
 0x28 + 4*cpu  0x8 (Magic cookie, Exynos3250)               AFTR
 0x28          0x0 or last value during resume (Exynos542x) System suspend
+============= ============================================ ==================
 
 
 2. Secure mode
 
 Address:      sysram_base_addr
+
+============= ============================================ ==================
 Offset        Value                                        Purpose
-=============================================================================
+============= ============================================ ==================
 0x00          exynos4_secondary_startup                    Secondary CPU boot
 0x04          exynos4_secondary_startup (Exynos542x)       Secondary CPU boot
 4*cpu         exynos4_secondary_startup (Exynos4412)       Secondary CPU boot
 0x20          exynos_cpu_resume (Exynos4210 r1.0)          AFTR
 0x24          0xfcba0d10 (Magic cookie, Exynos4210 r1.0)   AFTR
+============= ============================================ ==================
 
 Address:      pmu_base_addr
+
+============= ============================================ ==================
 Offset        Value                                        Purpose
-=============================================================================
+============= ============================================ ==================
 0x0800        exynos_cpu_resume                            AFTR, suspend
 0x0800        mcpm_entry_point (Exynos542x with MCPM)      AFTR, suspend
 0x0804        0xfcba0d10 (Magic cookie)                    AFTR
@@ -50,15 +60,18 @@ Offset        Value                                        Purpose
 0x0814        exynos4_secondary_startup (Exynos4210 r1.1)  Secondary CPU boot
 0x0818        0xfcba0d10 (Magic cookie, Exynos4210 r1.1)   AFTR
 0x081C        exynos_cpu_resume (Exynos4210 r1.1)          AFTR
-
+============= ============================================ ==================
 
 3. Other (regardless of secure/non-secure mode)
 
 Address:      pmu_base_addr
+
+============= =============================== ===============================
 Offset        Value                           Purpose
-=============================================================================
+============= =============================== ===============================
 0x0908        Non-zero                        Secondary CPU boot up indicator
                                               on Exynos3250 and Exynos542x
+============= =============================== ===============================
 
 
 4. Glossary
Documentation/arm/Samsung/GPIO.txt +3 -2
index 795adfd88081..37f991f8076d 100644
@@ -1,5 +1,6 @@
-		Samsung GPIO implementation
-		===========================
+===========================
+Samsung GPIO implementation
+===========================
 
 Introduction
 ------------
Documentation/arm/Samsung/Overview.txt +7 -4
index 8f7309bad460..98164270ae40 100644
@@ -1,5 +1,6 @@
-		Samsung ARM Linux Overview
-		==========================
+==========================
+Samsung ARM Linux Overview
+==========================
 
 Introduction
 ------------
@@ -32,8 +33,10 @@ Configuration
   A number of configurations are supplied, as there is no current way of
   unifying all the SoCs into one kernel.
 
-  s5pc110_defconfig - S5PC110 specific default configuration
-  s5pv210_defconfig - S5PV210 specific default configuration
+  s5pc110_defconfig
+	- S5PC110 specific default configuration
+  s5pv210_defconfig
+	- S5PV210 specific default configuration
 
 
 Layout
Documentation/arm/Setup +14 -35

107 lines not on this page · raw message

Documentation/arm/VFP/release-notes.txt +3 -1
index 28a2795705ca..c6b04937cee3 100644

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

Documentation/arm/cluster-pm-race-avoidance.txt +106 -71

177 lines not on this page · raw message

Documentation/arm/firmware.txt +8 -6
index 7f175dbb427e..efd844baec1d 100644

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

Documentation/arm/kernel_mode_neon.txt +3 -0
index b9e060c5b61e..9bfb71a2a9b9 100644

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

Documentation/arm/kernel_user_helpers.txt +40 -39

79 lines not on this page · raw message

Documentation/arm/keystone/Overview.txt +33 -14

47 lines not on this page · raw message

Documentation/arm/keystone/knav-qmss.txt +5 -1
index fcdb9fd5f53a..7f7638d80b42 100644

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

Documentation/arm/mem_alignment +8 -3
index 6335fcacbba9..7bef27367c9a 100644

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

Documentation/arm/memory.txt +7 -2
index 546a39048eb0..0521b4ce5c96 100644

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

Documentation/arm/nwfpe/NOTES +3 -0
index 40577b5a49d3..102e55af8439 100644

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

Documentation/arm/nwfpe/README +7 -3
index 771871de0c8b..35cd90dacbff 100644

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

Documentation/arm/nwfpe/README.FPE +15 -9
index 26f5d7bb9a41..cbb320960fc4 100644

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

Documentation/arm/nwfpe/TODO +26 -21

47 lines not on this page · raw message

Documentation/arm/pxa/mfp.txt +54 -52

106 lines not on this page · raw message

Documentation/arm/sti/overview.txt +12 -9
index 1a4e93d6027f..70743617a74f 100644

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

Documentation/arm/sti/stih407-overview.txt +5 -4
index 3343f32f58bc..027e75bc7b7c 100644

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

Documentation/arm/sti/stih415-overview.txt +5 -3
index 1383e33f265d..b67452d610c4 100644

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

Documentation/arm/sti/stih416-overview.txt +3 -2
index 558444c201c6..93f17d74d8db 100644

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

Documentation/arm/sti/stih418-overview.txt +5 -4
index 1cd8fc80646d..b563c1f4fe5a 100644

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

Documentation/arm/stm32/stm32f429-overview.rst +2 -3
index 18feda97f483..a7ebe8ea6697 100644

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

Documentation/arm/stm32/stm32f746-overview.rst +2 -3
index b5f4b6ce7656..78befddc7740 100644

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

Documentation/arm/stm32/stm32f769-overview.rst +2 -3
index 228656ced2fe..e482980ddf21 100644

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

Documentation/arm/stm32/stm32h743-overview.rst +2 -3
index 3458dc00095d..4e15f1a42730 100644

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

Documentation/arm/stm32/stm32mp157-overview.rst +1 -0
index 62e176d47ca7..f62fdc8e7d8d 100644

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

Documentation/arm/sunxi/README +73 -25

98 lines not on this page · raw message

Documentation/arm/sunxi/clocks.txt +4 -3
index e09a88aa3136..23bd03f3e21f 100644

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

Documentation/arm/swp_emulation +12 -12
index af903d22fd93..6a608a9c3715 100644

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

Documentation/arm/tcm.txt +30 -24

54 lines not on this page · raw message

Documentation/arm/uefi.txt +23 -16
index 6543a0adea8a..f868330df6be 100644

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

Documentation/arm/vlocks.txt +5 -4
index 45731672c564..a40a1742110b 100644

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

Documentation/index.rst +1 -0
index 80a421cb935e..e0a669552193 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.

#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
#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.

#78 lore raw

PATCH 47/57 docs: console.txt: convert to ReST format

In reply to Mauro Carvalho Chehab

Convert this small file to ReST in preparation for adding it to the driver-api book.

---
 Documentation/console/console.txt | 61 +++++++++++++++++--------------
 1 file changed, 33 insertions(+), 28 deletions(-)
Documentation/console/console.txt +33 -28
index d73c2ab4beda..8b0205d27a71 100644
@@ -1,3 +1,4 @@
+===============
 Console Drivers
 ===============
 
@@ -17,25 +18,26 @@ of driver occupying the consoles.) They can only take over the console that is
 occupied by the system driver. In the same token, if the modular driver is
 released by the console, the system driver will take over.
 
-Modular drivers, from the programmer's point of view, have to call:
+Modular drivers, from the programmer's point of view, have to call::
 
 	 do_take_over_console() - load and bind driver to console layer
 	 give_up_console() - unload driver; it will only work if driver
 			     is fully unbound
 
-In newer kernels, the following are also available:
+In newer kernels, the following are also available::
 
 	 do_register_con_driver()
 	 do_unregister_con_driver()
 
 If sysfs is enabled, the contents of /sys/class/vtconsole can be
 examined. This shows the console backends currently registered by the
-system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus:
+system which are named vtcon<n> where <n> is an integer from 0 to 15.
+Thus::
 
        ls /sys/class/vtconsole
        .  ..  vtcon0  vtcon1
 
-Each directory in /sys/class/vtconsole has 3 files:
+Each directory in /sys/class/vtconsole has 3 files::
 
      ls /sys/class/vtconsole/vtcon0
      .  ..  bind  name  uevent
@@ -46,27 +48,29 @@ What do these files signify?
         read, or acts to bind or unbind the driver to the virtual consoles
         when written to. The possible values are:
 
-	0 - means the driver is not bound and if echo'ed, commands the driver
+	0
+	  - means the driver is not bound and if echo'ed, commands the driver
 	    to unbind
 
-        1 - means the driver is bound and if echo'ed, commands the driver to
+        1
+	  - means the driver is bound and if echo'ed, commands the driver to
 	    bind
 
-     2. name - read-only file. Shows the name of the driver in this format:
+     2. name - read-only file. Shows the name of the driver in this format::
 
-	cat /sys/class/vtconsole/vtcon0/name
-	(S) VGA+
+	  cat /sys/class/vtconsole/vtcon0/name
+	  (S) VGA+
 
-	    '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
-	    commanded to bind or unbind
+	      '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
+	      commanded to bind or unbind
 
-	    'VGA+' is the name of the driver
+	      'VGA+' is the name of the driver
 
-	cat /sys/class/vtconsole/vtcon1/name
-	(M) frame buffer device
+	  cat /sys/class/vtconsole/vtcon1/name
+	  (M) frame buffer device
 
-	    In this case, '(M)' stands for a (M)odular driver, one that can be
-	    directly commanded to bind or unbind.
+	      In this case, '(M)' stands for a (M)odular driver, one that can be
+	      directly commanded to bind or unbind.
 
      3. uevent - ignore this file
 
@@ -75,14 +79,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other
 hand, will bind the driver to the consoles that are currently occupied by a
 system driver.
 
-NOTE1: Binding and unbinding must be selected in Kconfig. It's under:
+NOTE1:
+  Binding and unbinding must be selected in Kconfig. It's under::
 
-Device Drivers -> Character devices -> Support for binding and unbinding
-console drivers
+    Device Drivers ->
+	Character devices ->
+		Support for binding and unbinding console drivers
 
-NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
-unbinding will not succeed. An example of an application that sets the console
-to KD_GRAPHICS is X.
+NOTE2:
+  If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
+  unbinding will not succeed. An example of an application that sets the
+  console to KD_GRAPHICS is X.
 
 How useful is this feature? This is very useful for console driver
 developers. By unbinding the driver from the console layer, one can unload the
@@ -92,10 +99,10 @@ framebuffer console to VGA console and vice versa, this feature also makes
 this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
 for more details.)
 
-Notes for developers:
-=====================
+Notes for developers
+====================
 
-do_take_over_console() is now broken up into:
+do_take_over_console() is now broken up into::
 
      do_register_con_driver()
      do_bind_con_driver() - private function
@@ -104,7 +111,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must
 be fully unbound for this call to succeed. con_is_bound() will check if the
 driver is bound or not.
 
-Guidelines for console driver writers:
+Guidelines for console driver writers
 =====================================
 
 In order for binding to and unbinding from the console to properly work,
@@ -140,6 +147,4 @@ The current crop of console drivers should still work correctly, but binding
 and unbinding them may cause problems. With minimal fixes, these drivers can
 be made to work correctly.
 
-==========================
 Antonino Daplas <[email protected]>
-
Signature · 1 line
2.20.1
#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
#84 lore raw

PATCH 53/57 docs: xen-tpmfront.txt: convert the file to ReST format

In reply to Mauro Carvalho Chehab

In order to be able to add this file to the security book, we need first to convert it to reST.

---
 Documentation/security/tpm/xen-tpmfront.txt | 101 +++++++++++---------
 1 file changed, 56 insertions(+), 45 deletions(-)
Documentation/security/tpm/xen-tpmfront.txt +56 -45
index 69346de87ff3..00d5b1db227d 100644
@@ -1,4 +1,6 @@
+=============================
 Virtual TPM interface for Xen
+=============================
 
 Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
 
@@ -6,7 +8,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for
 Xen. The reader is assumed to have familiarity with building and installing Xen,
 Linux, and a basic understanding of the TPM and vTPM concepts.
 
-INTRODUCTION
+Introduction
+------------
 
 The goal of this work is to provide a TPM functionality to a virtual guest
 operating system (in Xen terms, a DomU).  This allows programs to interact with
@@ -24,81 +27,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by
 IBM and Intel corporation.
 
 
-DESIGN OVERVIEW
+Design Overview
 ---------------
 
-The architecture of vTPM is described below:
+The architecture of vTPM is described below::
 
-+------------------+
-|    Linux DomU    | ...
-|       |  ^       |
-|       v  |       |
-|   xen-tpmfront   |
-+------------------+
-        |  ^
-        v  |
-+------------------+
-| mini-os/tpmback  |
-|       |  ^       |
-|       v  |       |
-|  vtpm-stubdom    | ...
-|       |  ^       |
-|       v  |       |
-| mini-os/tpmfront |
-+------------------+
-        |  ^
-        v  |
-+------------------+
-| mini-os/tpmback  |
-|       |  ^       |
-|       v  |       |
-| vtpmmgr-stubdom  |
-|       |  ^       |
-|       v  |       |
-| mini-os/tpm_tis  |
-+------------------+
-        |  ^
-        v  |
-+------------------+
-|   Hardware TPM   |
-+------------------+
+  +------------------+
+  |    Linux DomU    | ...
+  |       |  ^       |
+  |       v  |       |
+  |   xen-tpmfront   |
+  +------------------+
+          |  ^
+          v  |
+  +------------------+
+  | mini-os/tpmback  |
+  |       |  ^       |
+  |       v  |       |
+  |  vtpm-stubdom    | ...
+  |       |  ^       |
+  |       v  |       |
+  | mini-os/tpmfront |
+  +------------------+
+          |  ^
+          v  |
+  +------------------+
+  | mini-os/tpmback  |
+  |       |  ^       |
+  |       v  |       |
+  | vtpmmgr-stubdom  |
+  |       |  ^       |
+  |       v  |       |
+  | mini-os/tpm_tis  |
+  +------------------+
+          |  ^
+          v  |
+  +------------------+
+  |   Hardware TPM   |
+  +------------------+
 
- * Linux DomU: The Linux based guest that wants to use a vTPM. There may be
+* Linux DomU:
+	       The Linux based guest that wants to use a vTPM. There may be
 	       more than one of these.
 
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
+* xen-tpmfront.ko:
+		    Linux kernel virtual TPM frontend driver. This driver
                     provides vTPM access to a Linux-based DomU.
 
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
+* mini-os/tpmback:
+		    Mini-os TPM backend driver. The Linux frontend driver
 		    connects to this backend driver to facilitate communications
 		    between the Linux DomU and its vTPM. This driver is also
 		    used by vtpmmgr-stubdom to communicate with vtpm-stubdom.
 
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
+* vtpm-stubdom:
+		 A mini-os stub domain that implements a vTPM. There is a
 		 one to one mapping between running vtpm-stubdom instances and
                  logical vtpms on the system. The vTPM Platform Configuration
                  Registers (PCRs) are normally all initialized to zero.
 
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
+* mini-os/tpmfront:
+		     Mini-os TPM frontend driver. The vTPM mini-os domain
 		     vtpm-stubdom uses this driver to communicate with
 		     vtpmmgr-stubdom. This driver is also used in mini-os
 		     domains such as pv-grub that talk to the vTPM domain.
 
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is
+* vtpmmgr-stubdom:
+		    A mini-os domain that implements the vTPM manager. There is
 		    only one vTPM manager and it should be running during the
 		    entire lifetime of the machine.  This domain regulates
 		    access to the physical TPM on the system and secures the
 		    persistent state of each vTPM.
 
- * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+* mini-os/tpm_tis:
+		    Mini-os TPM version 1.2 TPM Interface Specification (TIS)
                     driver. This driver used by vtpmmgr-stubdom to talk directly to
                     the hardware TPM. Communication is facilitated by mapping
                     hardware memory pages into vtpmmgr-stubdom.
 
- * Hardware TPM: The physical TPM that is soldered onto the motherboard.
+* Hardware TPM:
+		The physical TPM that is soldered onto the motherboard.
 
 
-INTEGRATION WITH XEN
+Integration With Xen
 --------------------
 
 Support for the vTPM driver was added in Xen using the libxl toolstack in Xen
Signature · 1 line
2.20.1
#85 lore raw

PATCH 54/57 docs: bus-devices: ti-gpmc.txt: convert it to ReST

In reply to Mauro Carvalho Chehab

In order to be able to add this file to a book, it needs first to be converted to ReST.

---
 Documentation/bus-devices/ti-gpmc.txt | 156 +++++++++++++++++---------
 1 file changed, 105 insertions(+), 51 deletions(-)
Documentation/bus-devices/ti-gpmc.txt +105 -51
index c434fcfc5e4c..afed53688904 100644
@@ -1,5 +1,6 @@
-GPMC (General Purpose Memory Controller):
-=========================================
+========================================
+GPMC (General Purpose Memory Controller)
+========================================
 
 GPMC is an unified memory controller dedicated to interfacing external
 memory devices like
@@ -49,75 +50,128 @@ most of the datasheets & hardware (to be exact none of those supported
 in mainline having custom timing routine) and by simulation.
 
 gpmc timing dependency on peripheral timings:
+
 [<gpmc_timing>: <peripheral timing1>, <peripheral timing2> ...]
 
 1. common
-cs_on: t_ceasu
-adv_on: t_avdasu, t_ceavd
+
+cs_on:
+	t_ceasu
+adv_on:
+	t_avdasu, t_ceavd
 
 2. sync common
-sync_clk: clk
-page_burst_access: t_bacc
-clk_activation: t_ces, t_avds
+
+sync_clk:
+	clk
+page_burst_access:
+	t_bacc
+clk_activation:
+	t_ces, t_avds
 
 3. read async muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu, t_aavdh
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+	t_avdp_r
+oe_on:
+	t_oeasu, t_aavdh
+access:
+	t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+	t_rd_cycle, t_cez_r, t_oez
 
 4. read async non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+	t_avdp_r
+oe_on:
+	t_oeasu
+access:
+	t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+	t_rd_cycle, t_cez_r, t_oez
 
 5. read sync muxed
-adv_rd_off: t_avdp_r, t_avdh
-oe_on: t_oeasu, t_ach, cyc_aavdh_oe
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+	t_avdp_r, t_avdh
+oe_on:
+	t_oeasu, t_ach, cyc_aavdh_oe
+access:
+	t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+	t_cez_r, t_oez, t_ce_rdyz
 
 6. read sync non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+	t_avdp_r
+oe_on:
+	t_oeasu
+access:
+	t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+	t_cez_r, t_oez, t_ce_rdyz
 
 7. write async muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_aavdh, cyc_aavhd_we
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+	t_avdp_w
+we_on, wr_data_mux_bus:
+	t_weasu, t_aavdh, cyc_aavhd_we
+we_off:
+	t_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_wr_cycle
 
 8. write async non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+	t_avdp_w
+we_on, wr_data_mux_bus:
+	t_weasu
+we_off:
+	t_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_wr_cycle
 
 9. write sync muxed
-adv_wr_off: t_avdp_w, t_avdh
-we_on, wr_data_mux_bus: t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
+
+adv_wr_off:
+	t_avdp_w, t_avdh
+we_on, wr_data_mux_bus:
+	t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
+we_off:
+	t_wpl, cyc_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_ce_rdyz
 
 10. write sync non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_rdyo
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
 
+adv_wr_off:
+	t_avdp_w
+we_on, wr_data_mux_bus:
+	t_weasu, t_rdyo
+we_off:
+	t_wpl, cyc_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_ce_rdyz
 
-Note: Many of gpmc timings are dependent on other gpmc timings (a few
-gpmc timings purely dependent on other gpmc timings, a reason that
-some of the gpmc timings are missing above), and it will result in
-indirect dependency of peripheral timings to gpmc timings other than
-mentioned above, refer timing routine for more details. To know what
-these peripheral timings correspond to, please see explanations in
-struct gpmc_device_timings definition. And for gpmc timings refer
-IP details (link above).
+
+Note:
+  Many of gpmc timings are dependent on other gpmc timings (a few
+  gpmc timings purely dependent on other gpmc timings, a reason that
+  some of the gpmc timings are missing above), and it will result in
+  indirect dependency of peripheral timings to gpmc timings other than
+  mentioned above, refer timing routine for more details. To know what
+  these peripheral timings correspond to, please see explanations in
+  struct gpmc_device_timings definition. And for gpmc timings refer
+  IP details (link above).
Signature · 1 line
2.20.1
#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
#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
#68 lore raw

PATCH 39/57 docs: xilinx: convert eemi.txt to ReST

In reply to Mauro Carvalho Chehab

This is a very trivial conversion: adjust the title markup and add a few literal block markups to produce a better visual when parsed and avoid warnings.

---
 Documentation/xilinx/eemi.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/xilinx/eemi.txt +4 -4
index 0ab686c173be..8ca82c782ba6 100644
@@ -1,6 +1,6 @@
----------------------------------------------------------------------
+====================================
 Xilinx Zynq MPSoC EEMI Documentation
----------------------------------------------------------------------
+====================================
 
 Xilinx Zynq MPSoC Firmware Interface
 -------------------------------------
@@ -21,7 +21,7 @@ The zynqmp-firmware driver maintain all EEMI APIs in zynqmp_eemi_ops
 structure. Any driver who want to communicate with PMC using EEMI APIs
 can call zynqmp_pm_get_eemi_ops().
 
-Example of EEMI ops:
+Example of EEMI ops::
 
 	/* zynqmp-firmware driver maintain all EEMI APIs */
 	struct zynqmp_eemi_ops {
@@ -34,7 +34,7 @@ Example of EEMI ops:
 		.query_data = zynqmp_pm_query_data,
 	};
 
-Example of EEMI ops usage:
+Example of EEMI ops usage::
 
 	static const struct zynqmp_eemi_ops *eemi_ops;
 	u32 ret_payload[PAYLOAD_ARG_CNT];
Signature · 7 lines
2.20.1


_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
#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
#69 lore raw

PATCH 40/57 docs: scheduler: convert files to ReST

In reply to Mauro Carvalho Chehab

In order to prepare to add them to the Kernel API book, convert the files to ReST format.

---
 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 ++-
 10 files changed, 290 insertions(+), 226 deletions(-)
Documentation/scheduler/completion.txt +20 -18
index e5b9df4d8078..9f039b4f4b09 100644
@@ -1,3 +1,4 @@
+================================================
 Completions - "wait for completion" barrier APIs
 ================================================
 
@@ -46,7 +47,7 @@ it has to wait for it.
 
 To use completions you need to #include <linux/completion.h> and
 create a static or dynamic variable of type 'struct completion',
-which has only two fields:
+which has only two fields::
 
 	struct completion {
 		unsigned int done;
@@ -57,7 +58,7 @@ This provides the ->wait waitqueue to place tasks on for waiting (if any), and
 the ->done completion flag for indicating whether it's completed or not.
 
 Completions should be named to refer to the event that is being synchronized on.
-A good example is:
+A good example is::
 
 	wait_for_completion(&early_console_added);
 
@@ -81,7 +82,7 @@ have taken place, even if these wait functions return prematurely due to a timeo
 or a signal triggering.
 
 Initializing of dynamically allocated completion objects is done via a call to
-init_completion():
+init_completion()::
 
 	init_completion(&dynamic_object->done);
 
@@ -100,7 +101,8 @@ but be aware of other races.
 
 For static declaration and initialization, macros are available.
 
-For static (or global) declarations in file scope you can use DECLARE_COMPLETION():
+For static (or global) declarations in file scope you can use
+DECLARE_COMPLETION()::
 
 	static DECLARE_COMPLETION(setup_done);
 	DECLARE_COMPLETION(setup_done);
@@ -111,7 +113,7 @@ initialized to 'not done' and doesn't require an init_completion() call.
 When a completion is declared as a local variable within a function,
 then the initialization should always use DECLARE_COMPLETION_ONSTACK()
 explicitly, not just to make lockdep happy, but also to make it clear
-that limited scope had been considered and is intentional:
+that limited scope had been considered and is intentional::
 
 	DECLARE_COMPLETION_ONSTACK(setup_done)
 
@@ -140,11 +142,11 @@ Waiting for completions:
 ------------------------
 
 For a thread to wait for some concurrent activity to finish, it
-calls wait_for_completion() on the initialized completion structure:
+calls wait_for_completion() on the initialized completion structure::
 
 	void wait_for_completion(struct completion *done)
 
-A typical usage scenario is:
+A typical usage scenario is::
 
 	CPU#1					CPU#2
 
@@ -192,17 +194,17 @@ A common problem that occurs is to have unclean assignment of return types,
 so take care to assign return-values to variables of the proper type.
 
 Checking for the specific meaning of return values also has been found
-to be quite inaccurate, e.g. constructs like:
+to be quite inaccurate, e.g. constructs like::
 
 	if (!wait_for_completion_interruptible_timeout(...))
 
 ... would execute the same code path for successful completion and for the
-interrupted case - which is probably not what you want.
+interrupted case - which is probably not what you want::
 
 	int wait_for_completion_interruptible(struct completion *done)
 
 This function marks the task TASK_INTERRUPTIBLE while it is waiting.
-If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise.
+If a signal was received while waiting it will return -ERESTARTSYS; 0 otherwise::
 
 	unsigned long wait_for_completion_timeout(struct completion *done, unsigned long timeout)
 
@@ -214,7 +216,7 @@ Timeouts are preferably calculated with msecs_to_jiffies() or usecs_to_jiffies()
 to make the code largely HZ-invariant.
 
 If the returned timeout value is deliberately ignored a comment should probably explain
-why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc()).
+why (e.g. see drivers/mfd/wm8350-core.c wm8350_read_auxadc())::
 
 	long wait_for_completion_interruptible_timeout(struct completion *done, unsigned long timeout)
 
@@ -225,14 +227,14 @@ jiffies if completion occurred.
 
 Further variants include _killable which uses TASK_KILLABLE as the
 designated tasks state and will return -ERESTARTSYS if it is interrupted,
-or 0 if completion was achieved.  There is a _timeout variant as well:
+or 0 if completion was achieved.  There is a _timeout variant as well::
 
 	long wait_for_completion_killable(struct completion *done)
 	long wait_for_completion_killable_timeout(struct completion *done, unsigned long timeout)
 
 The _io variants wait_for_completion_io() behave the same as the non-_io
 variants, except for accounting waiting time as 'waiting on IO', which has
-an impact on how the task is accounted in scheduling/IO stats:
+an impact on how the task is accounted in scheduling/IO stats::
 
 	void wait_for_completion_io(struct completion *done)
 	unsigned long wait_for_completion_io_timeout(struct completion *done, unsigned long timeout)
@@ -243,11 +245,11 @@ Signaling completions:
 
 A thread that wants to signal that the conditions for continuation have been
 achieved calls complete() to signal exactly one of the waiters that it can
-continue:
+continue::
 
 	void complete(struct completion *done)
 
-... or calls complete_all() to signal all current and future waiters:
+... or calls complete_all() to signal all current and future waiters::
 
 	void complete_all(struct completion *done)
 
@@ -268,7 +270,7 @@ probably are a design bug.
 
 Signaling completion from IRQ context is fine as it will appropriately
 lock with spin_lock_irqsave()/spin_unlock_irqrestore() and it will never
-sleep. 
+sleep.
 
 
 try_wait_for_completion()/completion_done():
@@ -276,14 +278,14 @@ try_wait_for_completion()/completion_done():
 
 The try_wait_for_completion() function will not put the thread on the wait
 queue but rather returns false if it would need to enqueue (block) the thread,
-else it consumes one posted completion and returns true.
+else it consumes one posted completion and returns true::
 
 	bool try_wait_for_completion(struct completion *done)
 
 Finally, to check the state of a completion without changing it in any way,
 call completion_done(), which returns false if there are no posted
 completions that were not yet consumed by waiters (implying that there are
-waiters) and true otherwise;
+waiters) and true otherwise::
 
 	bool completion_done(struct completion *done)
 
Documentation/scheduler/sched-arch.txt +10 -8
index a2f27bbf2cba..0eaec669790a 100644
@@ -1,4 +1,6 @@
-	CPU Scheduler implementation hints for architecture specific code
+=================================================================
+CPU Scheduler implementation hints for architecture specific code
+=================================================================
 
 	Nick Piggin, 2005
 
@@ -35,9 +37,10 @@ Your cpu_idle routines need to obey the following rules:
 4. The only time interrupts need to be disabled when checking
    need_resched is if we are about to sleep the processor until
    the next interrupt (this doesn't provide any protection of
-   need_resched, it prevents losing an interrupt).
+   need_resched, it prevents losing an interrupt):
+
+	4a. Common problem with this type of sleep appears to be::
 
-	4a. Common problem with this type of sleep appears to be:
 	        local_irq_disable();
 	        if (!need_resched()) {
 	                local_irq_enable();
@@ -51,10 +54,10 @@ Your cpu_idle routines need to obey the following rules:
    although it may be reasonable to do some background work or enter
    a low CPU priority.
 
-   	5a. If TIF_POLLING_NRFLAG is set, and we do decide to enter
-	    an interrupt sleep, it needs to be cleared then a memory
-	    barrier issued (followed by a test of need_resched with
-	    interrupts disabled, as explained in 3).
+      - 5a. If TIF_POLLING_NRFLAG is set, and we do decide to enter
+	an interrupt sleep, it needs to be cleared then a memory
+	barrier issued (followed by a test of need_resched with
+	interrupts disabled, as explained in 3).
 
 arch/x86/kernel/process.c has examples of both polling and
 sleeping idle functions.
@@ -71,4 +74,3 @@ sh64 - Is sleeping racy vs interrupts? (See #4a)
 
 sparc - IRQs on at this point(?), change local_irq_save to _disable.
       - TODO: needs secondary CPUs to disable preempt (See #1)
-
Documentation/scheduler/sched-bwc.txt +17 -11
index f6b1873f68ab..4ee2bd2f791d 100644
@@ -1,3 +1,4 @@
+=====================
 CFS Bandwidth Control
 =====================
 
@@ -27,7 +28,8 @@ cpu.cfs_quota_us: the total available run-time within a period (in microseconds)
 cpu.cfs_period_us: the length of a period (in microseconds)
 cpu.stat: exports throttling statistics [explained further below]
 
-The default values are:
+The default values are::
+
 	cpu.cfs_period_us=100ms
 	cpu.cfs_quota=-1
 
@@ -55,7 +57,8 @@ For efficiency run-time is transferred between the global pool and CPU local
 on large systems.  The amount transferred each time such an update is required
 is described as the "slice".
 
-This is tunable via procfs:
+This is tunable via procfs::
+
 	/proc/sys/kernel/sched_cfs_bandwidth_slice_us (default=5ms)
 
 Larger slice values will reduce transfer overheads, while smaller values allow
@@ -66,6 +69,7 @@ Statistics
 A group's bandwidth statistics are exported via 3 fields in cpu.stat.
 
 cpu.stat:
+
 - nr_periods: Number of enforcement intervals that have elapsed.
 - nr_throttled: Number of times the group has been throttled/limited.
 - throttled_time: The total time duration (in nanoseconds) for which entities
@@ -78,12 +82,15 @@ Hierarchical considerations
 The interface enforces that an individual entity's bandwidth is always
 attainable, that is: max(c_i) <= C. However, over-subscription in the
 aggregate case is explicitly allowed to enable work-conserving semantics
-within a hierarchy.
+within a hierarchy:
+
   e.g. \Sum (c_i) may exceed C
+
 [ Where C is the parent's bandwidth, and c_i its children ]
 
 
 There are two ways in which a group may become throttled:
+
 	a. it fully consumes its own quota within a period
 	b. a parent's quota is fully consumed within its period
 
@@ -92,7 +99,7 @@ be allowed to until the parent's runtime is refreshed.
 
 Examples
 --------
-1. Limit a group to 1 CPU worth of runtime.
+1. Limit a group to 1 CPU worth of runtime::
 
 	If period is 250ms and quota is also 250ms, the group will get
 	1 CPU worth of runtime every 250ms.
@@ -100,10 +107,10 @@ Examples
 	# echo 250000 > cpu.cfs_quota_us /* quota = 250ms */
 	# echo 250000 > cpu.cfs_period_us /* period = 250ms */
 
-2. Limit a group to 2 CPUs worth of runtime on a multi-CPU machine.
+2. Limit a group to 2 CPUs worth of runtime on a multi-CPU machine
 
-	With 500ms period and 1000ms quota, the group can get 2 CPUs worth of
-	runtime every 500ms.
+   With 500ms period and 1000ms quota, the group can get 2 CPUs worth of
+   runtime every 500ms::
 
 	# echo 1000000 > cpu.cfs_quota_us /* quota = 1000ms */
 	# echo 500000 > cpu.cfs_period_us /* period = 500ms */
@@ -112,11 +119,10 @@ Examples
 
 3. Limit a group to 20% of 1 CPU.
 
-	With 50ms period, 10ms quota will be equivalent to 20% of 1 CPU.
+   With 50ms period, 10ms quota will be equivalent to 20% of 1 CPU::
 
 	# echo 10000 > cpu.cfs_quota_us /* quota = 10ms */
 	# echo 50000 > cpu.cfs_period_us /* period = 50ms */
 
-	By using a small period here we are ensuring a consistent latency
-	response at the expense of burst capacity.
-
+   By using a small period here we are ensuring a consistent latency
+   response at the expense of burst capacity.
Documentation/scheduler/sched-deadline.txt +155 -138

499 lines not on this page · raw message

Documentation/scheduler/sched-design-CFS.txt +11 -4
index edd861c94c1b..82406685365a 100644
@@ -1,9 +1,10 @@
-                      =============
-                      CFS Scheduler
-                      =============
+=============
+CFS Scheduler
+=============
 
 
 1.  OVERVIEW
+============
 
 CFS stands for "Completely Fair Scheduler," and is the new "desktop" process
 scheduler implemented by Ingo Molnar and merged in Linux 2.6.23.  It is the
@@ -27,6 +28,7 @@ is its actual runtime normalized to the total number of running tasks.
 
 
 2.  FEW IMPLEMENTATION DETAILS
+==============================
 
 In CFS the virtual runtime is expressed and tracked via the per-task
 p->se.vruntime (nanosec-unit) value.  This way, it's possible to accurately
@@ -49,6 +51,7 @@ algorithm variants to recognize sleepers.
 
 
 3.  THE RBTREE
+==============
 
 CFS's design is quite radical: it does not use the old data structures for the
 runqueues, but it uses a time-ordered rbtree to build a "timeline" of future
@@ -84,6 +87,7 @@ picked and the current task is preempted.
 
 
 4.  SOME FEATURES OF CFS
+========================
 
 CFS uses nanosecond granularity accounting and does not rely on any jiffies or
 other HZ detail.  Thus the CFS scheduler has no notion of "timeslices" in the
@@ -113,6 +117,7 @@ result.
 
 
 5. Scheduling policies
+======================
 
 CFS implements three scheduling policies:
 
@@ -137,6 +142,7 @@ SCHED_IDLE.
 
 
 6.  SCHEDULING CLASSES
+======================
 
 The new CFS scheduler has been designed in such a way to introduce "Scheduling
 Classes," an extensible hierarchy of scheduler modules.  These modules
@@ -197,6 +203,7 @@ This is the (partial) list of the hooks:
 
 
 7.  GROUP SCHEDULER EXTENSIONS TO CFS
+=====================================
 
 Normally, the scheduler operates on individual tasks and strives to provide
 fair CPU time to each task.  Sometimes, it may be desirable to group tasks and
@@ -219,7 +226,7 @@ SCHED_BATCH) tasks.
 
 When CONFIG_FAIR_GROUP_SCHED is defined, a "cpu.shares" file is created for each
 group created using the pseudo filesystem.  See example steps below to create
-task groups and modify their CPU share using the "cgroups" pseudo filesystem.
+task groups and modify their CPU share using the "cgroups" pseudo filesystem::
 
 	# mount -t tmpfs cgroup_root /sys/fs/cgroup
 	# mkdir /sys/fs/cgroup/cpu
Documentation/scheduler/sched-domains.txt +7 -1
index 4af80b1c05aa..f7504226f445 100644
@@ -1,3 +1,7 @@
+=================
+Scheduler Domains
+=================
+
 Each CPU has a "base" scheduling domain (struct sched_domain). The domain
 hierarchy is built from these base domains via the ->parent pointer. ->parent
 MUST be NULL terminated, and domain structures should be per-CPU as they are
@@ -46,7 +50,9 @@ CPU's runqueue and the newly found busiest one and starts moving tasks from it
 to our runqueue. The exact number of tasks amounts to an imbalance previously
 computed while iterating over this sched domain's groups.
 
-*** Implementing sched domains ***
+Implementing sched domains
+==========================
+
 The "base" domain will "span" the first level of the hierarchy. In the case
 of SMT, you'll span all siblings of the physical CPU, with each group being
 a single virtual CPU.
Documentation/scheduler/sched-energy.txt +26 -21

140 lines not on this page · raw message

Documentation/scheduler/sched-nice-design.txt +5 -1
index 3ac1e46d5365..0571f1b47e64 100644
@@ -1,3 +1,7 @@
+=====================
+Scheduler Nice Design
+=====================
+
 This document explains the thinking about the revamped and streamlined
 nice-levels implementation in the new Linux scheduler.
 
@@ -14,7 +18,7 @@ much stronger than they were before in 2.4 (and people were happy about
 that change), and we also intentionally calibrated the linear timeslice
 rule so that nice +19 level would be _exactly_ 1 jiffy. To better
 understand it, the timeslice graph went like this (cheesy ASCII art
-alert!):
+alert!)::
 
 
                    A
Documentation/scheduler/sched-rt-group.txt +15 -13
index d8fce3e78457..79b30a21c51a 100644
@@ -1,18 +1,18 @@
-				Real-Time group scheduling
-				--------------------------
+==========================
+Real-Time group scheduling
+==========================
 
-CONTENTS
-========
+.. CONTENTS
 
-0. WARNING
-1. Overview
-  1.1 The problem
-  1.2 The solution
-2. The interface
-  2.1 System-wide settings
-  2.2 Default behaviour
-  2.3 Basis for grouping tasks
-3. Future plans
+   0. WARNING
+   1. Overview
+     1.1 The problem
+     1.2 The solution
+   2. The interface
+     2.1 System-wide settings
+     2.2 Default behaviour
+     2.3 Basis for grouping tasks
+   3. Future plans
 
 
 0. WARNING
@@ -159,9 +159,11 @@ Consider two sibling groups A and B; both have 50% bandwidth, but A's
 period is twice the length of B's.
 
 * group A: period=100000us, runtime=50000us
+
 	- this runs for 0.05s once every 0.1s
 
 * group B: period= 50000us, runtime=25000us
+
 	- this runs for 0.025s twice every 0.1s (or once every 0.05 sec).
 
 This means that currently a while (1) loop in A will run for the full period of
Documentation/scheduler/sched-stats.txt +24 -11
index 8259b34a66ae..0cb0aa714545 100644
@@ -1,3 +1,7 @@
+====================
+Scheduler Statistics
+====================
+
 Version 15 of schedstats dropped counters for some sched_yield:
 yld_exp_empty, yld_act_empty and yld_both_empty. Otherwise, it is
 identical to version 14.
@@ -35,19 +39,23 @@ CPU statistics
 cpu<N> 1 2 3 4 5 6 7 8 9
 
 First field is a sched_yield() statistic:
+
      1) # of times sched_yield() was called
 
 Next three are schedule() statistics:
+
      2) This field is a legacy array expiration count field used in the O(1)
 	scheduler. We kept it for ABI compatibility, but it is always set to zero.
      3) # of times schedule() was called
      4) # of times schedule() left the processor idle
 
 Next two are try_to_wake_up() statistics:
+
      5) # of times try_to_wake_up() was called
      6) # of times try_to_wake_up() was called to wake up the local cpu
 
 Next three are statistics describing scheduling latency:
+
      7) sum of all time spent running by tasks on this processor (in jiffies)
      8) sum of all time spent waiting to run by tasks on this processor (in
         jiffies)
@@ -67,24 +75,23 @@ The first field is a bit mask indicating what cpus this domain operates over.
 The next 24 are a variety of load_balance() statistics in grouped into types
 of idleness (idle, busy, and newly idle):
 
-     1) # of times in this domain load_balance() was called when the
+    1)  # of times in this domain load_balance() was called when the
         cpu was idle
-     2) # of times in this domain load_balance() checked but found
+    2)  # of times in this domain load_balance() checked but found
         the load did not require balancing when the cpu was idle
-     3) # of times in this domain load_balance() tried to move one or
+    3)  # of times in this domain load_balance() tried to move one or
         more tasks and failed, when the cpu was idle
-     4) sum of imbalances discovered (if any) with each call to
+    4)  sum of imbalances discovered (if any) with each call to
         load_balance() in this domain when the cpu was idle
-     5) # of times in this domain pull_task() was called when the cpu
+    5)  # of times in this domain pull_task() was called when the cpu
         was idle
-     6) # of times in this domain pull_task() was called even though
+    6)  # of times in this domain pull_task() was called even though
         the target task was cache-hot when idle
-     7) # of times in this domain load_balance() was called but did
+    7)  # of times in this domain load_balance() was called but did
         not find a busier queue while the cpu was idle
-     8) # of times in this domain a busier queue was found while the
+    8)  # of times in this domain a busier queue was found while the
         cpu was idle but no busier group was found
-
-     9) # of times in this domain load_balance() was called when the
+    9)  # of times in this domain load_balance() was called when the
         cpu was busy
     10) # of times in this domain load_balance() checked but found the
         load did not require balancing when busy
@@ -117,21 +124,25 @@ of idleness (idle, busy, and newly idle):
         was just becoming idle but no busier group was found
 
    Next three are active_load_balance() statistics:
+
     25) # of times active_load_balance() was called
     26) # of times active_load_balance() tried to move a task and failed
     27) # of times active_load_balance() successfully moved a task
 
    Next three are sched_balance_exec() statistics:
+
     28) sbe_cnt is not used
     29) sbe_balanced is not used
     30) sbe_pushed is not used
 
    Next three are sched_balance_fork() statistics:
+
     31) sbf_cnt is not used
     32) sbf_balanced is not used
     33) sbf_pushed is not used
 
    Next three are try_to_wake_up() statistics:
+
     34) # of times in this domain try_to_wake_up() awoke a task that
         last ran on a different cpu in this domain
     35) # of times in this domain try_to_wake_up() moved a task to the
@@ -139,10 +150,11 @@ of idleness (idle, busy, and newly idle):
     36) # of times in this domain try_to_wake_up() started passive balancing
 
 /proc/<pid>/schedstat
-----------------
+---------------------
 schedstats also adds a new /proc/<pid>/schedstat file to include some of
 the same information on a per-process level.  There are three fields in
 this file correlating for that process to:
+
      1) time spent on the cpu
      2) time spent waiting on a runqueue
      3) # of timeslices run on this cpu
@@ -151,4 +163,5 @@ A program could be easily written to make use of these extra fields to
 report on how well a particular process or set of processes is faring
 under the scheduler's policies.  A simple version of such a program is
 available at
+
     http://eaglet.rain.com/rick/linux/schedstat/v12/latency.c
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
#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
#86 lore raw

PATCH 55/57 docs: nvmem: convert file to ReST format

In reply to Mauro Carvalho Chehab

In order to be able to add it into a doc book, we need first convert it to ReST.

---
 Documentation/nvmem/nvmem.txt | 110 ++++++++++++++++++----------------
 1 file changed, 57 insertions(+), 53 deletions(-)
Documentation/nvmem/nvmem.txt +57 -53
index fc2fe4b18655..c93a9c6cd878 100644
@@ -1,5 +1,8 @@
-			    NVMEM SUBSYSTEM
-	  Srinivas Kandagatla <[email protected]>
+===============
+NVMEM Subsystem
+===============
+
+ Srinivas Kandagatla <[email protected]>
 
 This document explains the NVMEM Framework along with the APIs provided,
 and how to use it.
@@ -40,54 +43,54 @@ nvmem_device pointer.
 
 nvmem_unregister(nvmem) is used to unregister a previously registered provider.
 
-For example, a simple qfprom case:
+For example, a simple qfprom case::
 
-static struct nvmem_config econfig = {
+  static struct nvmem_config econfig = {
 	.name = "qfprom",
 	.owner = THIS_MODULE,
-};
+  };
 
-static int qfprom_probe(struct platform_device *pdev)
-{
+  static int qfprom_probe(struct platform_device *pdev)
+  {
 	...
 	econfig.dev = &pdev->dev;
 	nvmem = nvmem_register(&econfig);
 	...
-}
+  }
 
 It is mandatory that the NVMEM provider has a regmap associated with its
 struct device. Failure to do would return error code from nvmem_register().
 
 Users of board files can define and register nvmem cells using the
-nvmem_cell_table struct:
+nvmem_cell_table struct::
 
-static struct nvmem_cell_info foo_nvmem_cells[] = {
+  static struct nvmem_cell_info foo_nvmem_cells[] = {
 	{
 		.name		= "macaddr",
 		.offset		= 0x7f00,
 		.bytes		= ETH_ALEN,
 	}
-};
+  };
 
-static struct nvmem_cell_table foo_nvmem_cell_table = {
+  static struct nvmem_cell_table foo_nvmem_cell_table = {
 	.nvmem_name		= "i2c-eeprom",
 	.cells			= foo_nvmem_cells,
 	.ncells			= ARRAY_SIZE(foo_nvmem_cells),
-};
+  };
 
-nvmem_add_cell_table(&foo_nvmem_cell_table);
+  nvmem_add_cell_table(&foo_nvmem_cell_table);
 
 Additionally it is possible to create nvmem cell lookup entries and register
-them with the nvmem framework from machine code as shown in the example below:
+them with the nvmem framework from machine code as shown in the example below::
 
-static struct nvmem_cell_lookup foo_nvmem_lookup = {
+  static struct nvmem_cell_lookup foo_nvmem_lookup = {
 	.nvmem_name		= "i2c-eeprom",
 	.cell_name		= "macaddr",
 	.dev_id			= "foo_mac.0",
 	.con_id			= "mac-address",
-};
+  };
 
-nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
+  nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
 
 NVMEM Consumers
 +++++++++++++++
@@ -99,43 +102,43 @@ read from and to NVMEM.
 =================================
 
 NVMEM cells are the data entries/fields in the NVMEM.
-The NVMEM framework provides 3 APIs to read/write NVMEM cells.
+The NVMEM framework provides 3 APIs to read/write NVMEM cells::
 
-struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
-struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
+  struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
+  struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
 
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+  void nvmem_cell_put(struct nvmem_cell *cell);
+  void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
 
-void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
-int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
+  void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
+  int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
 
-*nvmem_cell_get() apis will get a reference to nvmem cell for a given id,
+`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
 and nvmem_cell_read/write() can then read or write to the cell.
-Once the usage of the cell is finished the consumer should call *nvmem_cell_put()
-to free all the allocation memory for the cell.
+Once the usage of the cell is finished the consumer should call
+`*nvmem_cell_put()` to free all the allocation memory for the cell.
 
 4. Direct NVMEM device based consumer APIs
 ==========================================
 
 In some instances it is necessary to directly read/write the NVMEM.
-To facilitate such consumers NVMEM framework provides below apis.
+To facilitate such consumers NVMEM framework provides below apis::
 
-struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
-struct nvmem_device *devm_nvmem_device_get(struct device *dev,
+  struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
+  struct nvmem_device *devm_nvmem_device_get(struct device *dev,
 					   const char *name);
-void nvmem_device_put(struct nvmem_device *nvmem);
-int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
+  void nvmem_device_put(struct nvmem_device *nvmem);
+  int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
 		      size_t bytes, void *buf);
-int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
+  int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
 		       size_t bytes, void *buf);
-int nvmem_device_cell_read(struct nvmem_device *nvmem,
+  int nvmem_device_cell_read(struct nvmem_device *nvmem,
 			   struct nvmem_cell_info *info, void *buf);
-int nvmem_device_cell_write(struct nvmem_device *nvmem,
+  int nvmem_device_cell_write(struct nvmem_device *nvmem,
 			    struct nvmem_cell_info *info, void *buf);
 
 Before the consumers can read/write NVMEM directly, it should get hold
-of nvmem_controller from one of the *nvmem_device_get() api.
+of nvmem_controller from one of the `*nvmem_device_get()` api.
 
 The difference between these apis and cell based apis is that these apis always
 take nvmem_device as parameter.
@@ -145,12 +148,12 @@ take nvmem_device as parameter.
 
 When a consumer no longer needs the NVMEM, it has to release the reference
 to the NVMEM it has obtained using the APIs mentioned in the above section.
-The NVMEM framework provides 2 APIs to release a reference to the NVMEM.
+The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
 
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void nvmem_device_put(struct nvmem_device *nvmem);
-void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
+  void nvmem_cell_put(struct nvmem_cell *cell);
+  void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+  void nvmem_device_put(struct nvmem_device *nvmem);
+  void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
 
 Both these APIs are used to release a reference to the NVMEM and
 devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
@@ -162,20 +165,21 @@ Userspace
 6. Userspace binary interface
 ==============================
 
-Userspace can read/write the raw NVMEM file located at
-/sys/bus/nvmem/devices/*/nvmem
+Userspace can read/write the raw NVMEM file located at::
 
-ex:
+	/sys/bus/nvmem/devices/*/nvmem
 
-hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ex::
 
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-*
-00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-...
-*
-0001000
+  hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+  0000000 0000 0000 0000 0000 0000 0000 0000 0000
+  *
+  00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+  0000000 0000 0000 0000 0000 0000 0000 0000 0000
+  ...
+  *
+  0001000
 
 7. DeviceTree Binding
 =====================
Signature · 1 line
2.20.1
#70 lore raw

PATCH 41/57 docs: EDID/HOWTO.txt: convert to ReST and move to kernel-API

In reply to Mauro Carvalho Chehab

Sphinx need to know when a paragraph ends. So, do some adjustments at the file for it to be properly parsed.

---
 Documentation/EDID/HOWTO.txt | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)
Documentation/EDID/HOWTO.txt +18 -11
index 539871c3b785..9a9b512e0ac9 100644
@@ -1,3 +1,7 @@
+====
+EDID
+====
+
 In the good old days when graphics parameters were configured explicitly
 in a file called xorg.conf, even broken hardware could be managed.
 
@@ -34,16 +38,19 @@ Makefile. Please note that the EDID data structure expects the timing
 values in a different way as compared to the standard X11 format.
 
 X11:
-HTimings:  hdisp hsyncstart hsyncend htotal
-VTimings:  vdisp vsyncstart vsyncend vtotal
+  HTimings:
+    hdisp hsyncstart hsyncend htotal
+  VTimings:
+    vdisp vsyncstart vsyncend vtotal
 
-EDID:
-#define XPIX hdisp
-#define XBLANK htotal-hdisp
-#define XOFFSET hsyncstart-hdisp
-#define XPULSE hsyncend-hsyncstart
+EDID::
 
-#define YPIX vdisp
-#define YBLANK vtotal-vdisp
-#define YOFFSET vsyncstart-vdisp
-#define YPULSE vsyncend-vsyncstart
+  #define XPIX hdisp
+  #define XBLANK htotal-hdisp
+  #define XOFFSET hsyncstart-hdisp
+  #define XPULSE hsyncend-hsyncstart
+
+  #define YPIX vdisp
+  #define YBLANK vtotal-vdisp
+  #define YOFFSET vsyncstart-vdisp
+  #define YPULSE vsyncend-vsyncstart
Signature · 1 line
2.20.1
#71 lore raw

PATCH 42/57 docs: connector.txt: convert to ReST

In reply to Mauro Carvalho Chehab

As it has some function definitions, move them to connector.h.

---
 Documentation/connector/connector.txt | 128 +++++++++-----------------
 include/linux/connector.h             |  63 ++++++++++++-
 2 files changed, 105 insertions(+), 86 deletions(-)
Documentation/connector/connector.txt +43 -85
index ab7ca897fab7..2cf9b5adfe2a 100644
@@ -1,6 +1,6 @@
-/*****************************************/
-Kernel Connector.
-/*****************************************/
+================
+Kernel Connector
+================
 
 Kernel connector - new netlink based userspace <-> kernel space easy
 to use communication module.
@@ -12,94 +12,55 @@ identifier, the appropriate callback will be called.
 
 From the userspace point of view it's quite straightforward:
 
-	socket();
-	bind();
-	send();
-	recv();
+	- socket();
+	- bind();
+	- send();
+	- recv();
 
 But if kernelspace wants to use the full power of such connections, the
 driver writer must create special sockets, must know about struct sk_buff
 handling, etc...  The Connector driver allows any kernelspace agents to use
 netlink based networking for inter-process communication in a significantly
-easier way:
+easier way::
 
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
-void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
-void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
+  int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+  void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
+  void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
 
-struct cb_id
-{
+  struct cb_id
+  {
 	__u32			idx;
 	__u32			val;
-};
+  };
 
 idx and val are unique identifiers which must be registered in the
-connector.h header for in-kernel usage.  void (*callback) (void *) is a
+connector.h header for in-kernel usage.  `void (*callback) (void *)` is a
 callback function which will be called when a message with above idx.val
 is received by the connector core.  The argument for that function must
-be dereferenced to struct cn_msg *.
+be dereferenced to `struct cn_msg *`::
 
-struct cn_msg
-{
+  struct cn_msg
+  {
 	struct cb_id		id;
 
 	__u32			seq;
 	__u32			ack;
 
-	__u32			len;		/* Length of the following data */
+	__u32			len;	/* Length of the following data */
 	__u8			data[0];
-};
+  };
 
-/*****************************************/
-Connector interfaces.
-/*****************************************/
+Connector interfaces
+====================
 
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ .. kernel-doc:: include/linux/connector.h
 
- Registers new callback with connector core.
+ Note:
+   When registering new callback user, connector core assigns
+   netlink group to the user which is equal to its id.idx.
 
- struct cb_id *id		- unique connector's user identifier.
-				  It must be registered in connector.h for legal in-kernel users.
- char *name			- connector's callback symbolic name.
- void (*callback) (struct cn..)	- connector's callback.
-				  cn_msg and the sender's credentials
-
-
-void cn_del_callback(struct cb_id *id);
-
- Unregisters new callback with connector core.
-
- struct cb_id *id		- unique connector's user identifier.
-
-
-int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask);
-int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask);
-
- Sends message to the specified groups.  It can be safely called from
- softirq context, but may silently fail under strong memory pressure.
- If there are no listeners for given group -ESRCH can be returned.
-
- struct cn_msg *		- message header(with attached data).
- u16 len			- for *_multi multiple cn_msg messages can be sent
- u32 port			- destination port.
- 				  If non-zero the message will be sent to the
-				  given port, which should be set to the
-				  original sender.
- u32 __group			- destination group.
-				  If port and __group is zero, then appropriate group will
-				  be searched through all registered connector users,
-				  and message will be delivered to the group which was
-				  created for user with the same ID as in msg.
-				  If __group is not zero, then message will be delivered
-				  to the specified group.
- int gfp_mask			- GFP mask.
-
- Note: When registering new callback user, connector core assigns
- netlink group to the user which is equal to its id.idx.
-
-/*****************************************/
-Protocol description.
-/*****************************************/
+Protocol description
+====================
 
 The current framework offers a transport layer with fixed headers.  The
 recommended protocol which uses such a header is as following:
@@ -132,9 +93,8 @@ driver (it also registers itself with id={-1, -1}).
 As example of this usage can be found in the cn_test.c module which
 uses the connector to request notification and to send messages.
 
-/*****************************************/
-Reliability.
-/*****************************************/
+Reliability
+===========
 
 Netlink itself is not a reliable protocol.  That means that messages can
 be lost due to memory pressure or process' receiving queue overflowed,
@@ -142,32 +102,31 @@ so caller is warned that it must be prepared.  That is why the struct
 cn_msg [main connector's message header] contains u32 seq and u32 ack
 fields.
 
-/*****************************************/
-Userspace usage.
-/*****************************************/
+Userspace usage
+===============
 
 2.6.14 has a new netlink socket implementation, which by default does not
 allow people to send data to netlink groups other than 1.
 So, if you wish to use a netlink socket (for example using connector)
 with a different group number, the userspace application must subscribe to
-that group first.  It can be achieved by the following pseudocode:
+that group first.  It can be achieved by the following pseudocode::
 
-s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
+  s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
 
-l_local.nl_family = AF_NETLINK;
-l_local.nl_groups = 12345;
-l_local.nl_pid = 0;
+  l_local.nl_family = AF_NETLINK;
+  l_local.nl_groups = 12345;
+  l_local.nl_pid = 0;
 
-if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
+  if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
 	perror("bind");
 	close(s);
 	return -1;
-}
+  }
 
-{
+  {
 	int on = l_local.nl_groups;
 	setsockopt(s, 270, 1, &on, sizeof(on));
-}
+  }
 
 Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
 option.  To drop a multicast subscription, one should call the above socket
@@ -180,16 +139,15 @@ group number 12345, you must increment CN_NETLINK_USERS to that number.
 Additional 0xf numbers are allocated to be used by non-in-kernel users.
 
 Due to this limitation, group 0xffffffff does not work now, so one can
-not use add/remove connector's group notifications, but as far as I know, 
+not use add/remove connector's group notifications, but as far as I know,
 only cn_test.c test module used it.
 
 Some work in netlink area is still being done, so things can be changed in
 2.6.15 timeframe, if it will happen, documentation will be updated for that
 kernel.
 
-/*****************************************/
 Code samples
-/*****************************************/
+============
 
 Sample code for a connector test module and user space can be found
 in samples/connector/. To build this code, enable CONFIG_CONNECTOR
include/linux/connector.h +62 -1

72 lines not on this page · raw message

Signature · 1 line
2.20.1
#72 lore raw

PATCH 43/57 docs: lcd-panel-cgram.txt convert it to ReST and move to admin-guide

In reply to Mauro Carvalho Chehab

This small text file describes the usage of parallel port LCD displays from userspace PoV. So, a good candidate for the admin guide.

---
 Documentation/auxdisplay/lcd-panel-cgram.txt | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)
Documentation/auxdisplay/lcd-panel-cgram.txt +5 -2
index 7f82c905763d..a3eb00c62f53 100644
@@ -1,3 +1,7 @@
+======================================
+Parallel port LCD/Keypad Panel support
+======================================
+
 Some LCDs allow you to define up to 8 characters, mapped to ASCII
 characters 0 to 7. The escape code to define a new character is
 '\e[LG' followed by one digit from 0 to 7, representing the character
@@ -7,7 +11,7 @@ illuminated pixel with LSB on the right. Lines are numbered from the
 top of the character to the bottom. On a 5x7 matrix, only the 5 lower
 bits of the 7 first bytes are used for each character. If the string
 is incomplete, only complete lines will be redefined. Here are some
-examples :
+examples::
 
   printf "\e[LG0010101050D1F0C04;"  => 0 = [enter]
   printf "\e[LG1040E1F0000000000;"  => 1 = [up]
@@ -21,4 +25,3 @@ examples :
   printf "\e[LG00002061E1E060200;"  => small speaker
 
 Willy
-
Signature · 1 line
2.20.1
#74 lore raw

PATCH 45/57 docs: m68k: convert it to ReST file format and add to arch bookset

In reply to Mauro Carvalho Chehab

Convert the m68k kernel-options.txt file to ReST.

The conversion is trivial, as the document is already on a format close enough to ReST. Just some small adjustments were needed in order to make it both good for being parsed while keeping it on a good txt shape.

---
 Documentation/m68k/kernel-options.txt | 319 ++++++++++++++------------
 1 file changed, 173 insertions(+), 146 deletions(-)
Documentation/m68k/kernel-options.txt +173 -146
index 79d21246c75a..cabd9419740d 100644
@@ -1,22 +1,24 @@
-
-
-				  Command Line Options for Linux/m68k
-				  ===================================
+===================================
+Command Line Options for Linux/m68k
+===================================
 
 Last Update: 2 May 1999
+
 Linux/m68k version: 2.2.6
+
 Author: [email protected] (Roman Hodek)
+
 Update: [email protected] (Jes Sorensen) and [email protected] (Chris Lawrence)
 
 0) Introduction
 ===============
 
-  Often I've been asked which command line options the Linux/m68k
+Often I've been asked which command line options the Linux/m68k
 kernel understands, or how the exact syntax for the ... option is, or
 ... about the option ... . I hope, this document supplies all the
 answers...
 
-  Note that some options might be outdated, their descriptions being
+Note that some options might be outdated, their descriptions being
 incomplete or missing. Please update the information and send in the
 patches.
 
@@ -38,11 +40,11 @@ argument contains an '=', it is of class 2, and the definition is put
 into init's environment. All other arguments are passed to init as
 command line options.
 
-  This document describes the valid kernel options for Linux/m68k in
+This document describes the valid kernel options for Linux/m68k in
 the version mentioned at the start of this file. Later revisions may
 add new such options, and some may be missing in older versions.
 
-  In general, the value (the part after the '=') of an option is a
+In general, the value (the part after the '=') of an option is a
 list of values separated by commas. The interpretation of these values
 is up to the driver that "owns" the option. This association of
 options with drivers is also the reason that some are further
@@ -55,21 +57,21 @@ subdivided.
 2.1) root=
 ----------
 
-Syntax: root=/dev/<device>
-    or: root=<hex_number>
+:Syntax: root=/dev/<device>
+:or:     root=<hex_number>
 
 This tells the kernel which device it should mount as the root
 filesystem. The device must be a block device with a valid filesystem
 on it.
 
-  The first syntax gives the device by name. These names are converted
+The first syntax gives the device by name. These names are converted
 into a major/minor number internally in the kernel in an unusual way.
 Normally, this "conversion" is done by the device files in /dev, but
 this isn't possible here, because the root filesystem (with /dev)
 isn't mounted yet... So the kernel parses the name itself, with some
 hardcoded name to number mappings. The name must always be a
 combination of two or three letters, followed by a decimal number.
-Valid names are:
+Valid names are::
 
   /dev/ram: -> 0x0100 (initial ramdisk)
   /dev/hda: -> 0x0300 (first IDE disk)
@@ -81,7 +83,7 @@ Valid names are:
   /dev/sde: -> 0x0840 (fifth SCSI disk)
   /dev/fd : -> 0x0200 (floppy disk)
 
-  The name must be followed by a decimal number, that stands for the
+The name must be followed by a decimal number, that stands for the
 partition number. Internally, the value of the number is just
 added to the device number mentioned in the table above. The
 exceptions are /dev/ram and /dev/fd, where /dev/ram refers to an
@@ -100,12 +102,12 @@ the kernel command line.
 
 [Strange and maybe uninteresting stuff ON]
 
-  This unusual translation of device names has some strange
+This unusual translation of device names has some strange
 consequences: If, for example, you have a symbolic link from /dev/fd
 to /dev/fd0D720 as an abbreviation for floppy driver #0 in DD format,
 you cannot use this name for specifying the root device, because the
 kernel cannot see this symlink before mounting the root FS and it
-isn't in the table above. If you use it, the root device will not be 
+isn't in the table above. If you use it, the root device will not be
 set at all, without an error message. Another example: You cannot use a
 partition on e.g. the sixth SCSI disk as the root filesystem, if you
 want to specify it by name. This is, because only the devices up to
@@ -118,7 +120,7 @@ knowledge that each disk uses 16 minors, and write "root=/dev/sde17"
 
 [Strange and maybe uninteresting stuff OFF]
 
-  If the device containing your root partition isn't in the table
+If the device containing your root partition isn't in the table
 above, you can also specify it by major and minor numbers. These are
 written in hex, with no prefix and no separator between. E.g., if you
 have a CD with contents appropriate as a root filesystem in the first
@@ -136,6 +138,7 @@ known partition UUID as the starting point.  For example,
 if partition 5 of the device has the UUID of
 00112233-4455-6677-8899-AABBCCDDEEFF then partition 3 may be found as
 follows:
+
   PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2
 
 Authoritative information can be found in
@@ -145,8 +148,8 @@ Authoritative information can be found in
 2.2) ro, rw
 -----------
 
-Syntax: ro
-    or: rw
+:Syntax: ro
+:or:     rw
 
 These two options tell the kernel whether it should mount the root
 filesystem read-only or read-write. The default is read-only, except
@@ -156,7 +159,7 @@ for ramdisks, which default to read-write.
 2.3) debug
 ----------
 
-Syntax: debug
+:Syntax: debug
 
 This raises the kernel log level to 10 (the default is 7). This is the
 same level as set by the "dmesg" command, just that the maximum level
@@ -166,7 +169,7 @@ selectable by dmesg is 8.
 2.4) debug=
 -----------
 
-Syntax: debug=<device>
+:Syntax: debug=<device>
 
 This option causes certain kernel messages be printed to the selected
 debugging device. This can aid debugging the kernel, since the
@@ -175,7 +178,7 @@ devices are possible depends on the machine type. There are no checks
 for the validity of the device name. If the device isn't implemented,
 nothing happens.
 
-  Messages logged this way are in general stack dumps after kernel
+Messages logged this way are in general stack dumps after kernel
 memory faults or bad kernel traps, and kernel panics. To be exact: all
 messages of level 0 (panic messages) and all messages printed while
 the log level is 8 or more (their level doesn't matter). Before stack
@@ -185,19 +188,27 @@ at least 8 can also be set by the "debug" command line option (see
 
 Devices possible for Amiga:
 
- - "ser": built-in serial port; parameters: 9600bps, 8N1
- - "mem": Save the messages to a reserved area in chip mem. After
+ - "ser":
+	  built-in serial port; parameters: 9600bps, 8N1
+ - "mem":
+	  Save the messages to a reserved area in chip mem. After
           rebooting, they can be read under AmigaOS with the tool
           'dmesg'.
 
 Devices possible for Atari:
 
- - "ser1": ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
- - "ser2": SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
- - "ser" : default serial port
+ - "ser1":
+	   ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
+ - "ser2":
+	   SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
+ - "ser" :
+	   default serial port
            This is "ser2" for a Falcon, and "ser1" for any other machine
- - "midi": The MIDI port; parameters: 31250bps, 8N1
- - "par" : parallel port
+ - "midi":
+	   The MIDI port; parameters: 31250bps, 8N1
+ - "par" :
+	   parallel port
+
            The printing routine for this implements a timeout for the
            case there's no printer connected (else the kernel would
            lock up). The timeout is not exact, but usually a few
@@ -205,26 +216,29 @@ Devices possible for Atari:
 
 
 2.6) ramdisk_size=
--------------
+------------------
 
-Syntax: ramdisk_size=<size>
+:Syntax: ramdisk_size=<size>
 
-  This option instructs the kernel to set up a ramdisk of the given
+This option instructs the kernel to set up a ramdisk of the given
 size in KBytes. Do not use this option if the ramdisk contents are
 passed by bootstrap! In this case, the size is selected automatically
 and should not be overwritten.
 
-  The only application is for root filesystems on floppy disks, that
+The only application is for root filesystems on floppy disks, that
 should be loaded into memory. To do that, select the corresponding
 size of the disk as ramdisk size, and set the root device to the disk
 drive (with "root=").
 
 
 2.7) swap=
+
+  I can't find any sign of this option in 2.2.6.
+
 2.8) buff=
 -----------
 
-  I can't find any sign of these options in 2.2.6.
+  I can't find any sign of this option in 2.2.6.
 
 
 3) General Device Options (Amiga and Atari)
@@ -233,13 +247,13 @@ drive (with "root=").
 3.1) ether=
 -----------
 
-Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
+:Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
 
-  <dev-name> is the name of a net driver, as specified in
+<dev-name> is the name of a net driver, as specified in
 drivers/net/Space.c in the Linux source. Most prominent are eth0, ...
 eth3, sl0, ... sl3, ppp0, ..., ppp3, dummy, and lo.
 
-  The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
+The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
 settings by this options. Also, the existing ethernet drivers for
 Linux/m68k (ariadne, a2065, hydra) don't use them because Zorro boards
 are really Plug-'n-Play, so the "ether=" option is useless altogether
@@ -249,9 +263,9 @@ for Linux/m68k.
 3.2) hd=
 --------
 
-Syntax: hd=<cylinders>,<heads>,<sectors>
+:Syntax: hd=<cylinders>,<heads>,<sectors>
 
-  This option sets the disk geometry of an IDE disk. The first hd=
+This option sets the disk geometry of an IDE disk. The first hd=
 option is for the first IDE disk, the second for the second one.
 (I.e., you can give this option twice.) In most cases, you won't have
 to use this option, since the kernel can obtain the geometry data
@@ -262,9 +276,9 @@ disks.
 3.3) max_scsi_luns=
 -------------------
 
-Syntax: max_scsi_luns=<n>
+:Syntax: max_scsi_luns=<n>
 
-  Sets the maximum number of LUNs (logical units) of SCSI devices to
+Sets the maximum number of LUNs (logical units) of SCSI devices to
 be scanned. Valid values for <n> are between 1 and 8. Default is 8 if
 "Probe all LUNs on each SCSI device" was selected during the kernel
 configuration, else 1.
@@ -273,9 +287,9 @@ configuration, else 1.
 3.4) st=
 --------
 
-Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
+:Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
 
-  Sets several parameters of the SCSI tape driver. <buffer_size> is
+Sets several parameters of the SCSI tape driver. <buffer_size> is
 the number of 512-byte buffers reserved for tape operations for each
 device. <write_thres> sets the number of blocks which must be filled
 to start an actual write operation to the tape. Maximum value is the
@@ -286,9 +300,9 @@ buffers allocated for all tape devices.
 3.5) dmasound=
 --------------
 
-Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
+:Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
 
-  This option controls some configurations of the Linux/m68k DMA sound
+This option controls some configurations of the Linux/m68k DMA sound
 driver (Amiga and Atari): <buffers> is the number of buffers you want
 to use (minimum 4, default 4), <buffer-size> is the size of each
 buffer in kilobytes (minimum 4, default 32) and <catch-radius> says
@@ -305,20 +319,22 @@ don't need to expand the sound.
 4.1) video=
 -----------
 
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
 
 The <fbname> parameter specifies the name of the frame buffer,
-eg. most atari users will want to specify `atafb' here. The
+eg. most atari users will want to specify `atafb` here. The
 <sub-options> is a comma-separated list of the sub-options listed
 below.
 
-NB: Please notice that this option was renamed from `atavideo' to
-    `video' during the development of the 1.3.x kernels, thus you
+NB:
+    Please notice that this option was renamed from `atavideo` to
+    `video` during the development of the 1.3.x kernels, thus you
     might need to update your boot-scripts if upgrading to 2.x from
     an 1.2.x kernel.
 
-NBB: The behavior of video= was changed in 2.1.57 so the recommended
-option is to specify the name of the frame buffer.
+NBB:
+    The behavior of video= was changed in 2.1.57 so the recommended
+    option is to specify the name of the frame buffer.
 
 4.1.1) Video Mode
 -----------------
@@ -341,11 +357,11 @@ mode, if the hardware allows. Currently defined names are:
  - falh2           : 896x608x1, Falcon only
  - falh16          : 896x608x4, Falcon only
 
-  If no video mode is given on the command line, the kernel tries the
+If no video mode is given on the command line, the kernel tries the
 modes names "default<n>" in turn, until one is possible with the
 hardware in use.
 
-  A video mode setting doesn't make sense, if the external driver is
+A video mode setting doesn't make sense, if the external driver is
 activated by a "external:" sub-option.
 
 4.1.2) inverse
@@ -358,17 +374,17 @@ option, you can make the background white.
 4.1.3) font
 -----------
 
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
 
 Specify the font to use in text modes. Currently you can choose only
-between `VGA8x8', `VGA8x16' and `PEARL8x8'. `VGA8x8' is default, if the
+between `VGA8x8`, `VGA8x16` and `PEARL8x8`. `VGA8x8` is default, if the
 vertical size of the display is less than 400 pixel rows. Otherwise, the
-`VGA8x16' font is the default.
+`VGA8x16` font is the default.
 
-4.1.4) hwscroll_
-----------------
+4.1.4) `hwscroll_`
+------------------
 
-Syntax: hwscroll_<n>
+:Syntax: `hwscroll_<n>`
 
 The number of additional lines of video memory to reserve for
 speeding up the scrolling ("hardware scrolling"). Hardware scrolling
@@ -378,7 +394,7 @@ possible with plain STs and graphics cards (The former because the
 base address must be on a 256 byte boundary there, the latter because
 the kernel doesn't know how to set the base address at all.)
 
-  By default, <n> is set to the number of visible text lines on the
+By default, <n> is set to the number of visible text lines on the
 display. Thus, the amount of video memory is doubled, compared to no
 hardware scrolling. You can turn off the hardware scrolling altogether
 by setting <n> to 0.
@@ -386,31 +402,31 @@ by setting <n> to 0.
 4.1.5) internal:
 ----------------
 
-Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
+:Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
 
 This option specifies the capabilities of some extended internal video
 hardware, like e.g. OverScan. <xres> and <yres> give the (extended)
 dimensions of the screen.
 
-  If your OverScan needs a black border, you have to write the last
+If your OverScan needs a black border, you have to write the last
 three arguments of the "internal:". <xres_max> is the maximum line
 length the hardware allows, <yres_max> the maximum number of lines.
 <offset> is the offset of the visible part of the screen memory to its
 physical start, in bytes.
 
-  Often, extended interval video hardware has to be activated somehow.
+Often, extended interval video hardware has to be activated somehow.
 For this, see the "sw_*" options below.
 
 4.1.6) external:
 ----------------
 
-Syntax:
-  external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>\
-           [;<colw>[;<coltype>[;<xres_virtual>]]]]]
+:Syntax:
+  external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>
+  [;<colw>[;<coltype>[;<xres_virtual>]]]]]
 
-[I had to break this line...]
+.. I had to break this line...
 
-  This is probably the most complicated parameter... It specifies that
+This is probably the most complicated parameter... It specifies that
 you have some external video hardware (a graphics board), and how to
 use it under Linux/m68k. The kernel cannot know more about the hardware
 than you tell it here! The kernel also is unable to set or change any
@@ -418,38 +434,44 @@ video modes, since it doesn't know about any board internal. So, you
 have to switch to that video mode before you start Linux, and cannot
 switch to another mode once Linux has started.
 
-  The first 3 parameters of this sub-option should be obvious: <xres>,
+The first 3 parameters of this sub-option should be obvious: <xres>,
 <yres> and <depth> give the dimensions of the screen and the number of
 planes (depth). The depth is the logarithm to base 2 of the number
 of colors possible. (Or, the other way round: The number of colors is
 2^depth).
 
-  You have to tell the kernel furthermore how the video memory is
+You have to tell the kernel furthermore how the video memory is
 organized. This is done by a letter as <org> parameter:
 
- 'n': "normal planes", i.e. one whole plane after another
- 'i': "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
+ 'n':
+      "normal planes", i.e. one whole plane after another
+ 'i':
+      "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
       of the next, and so on... This mode is used only with the
-	  built-in Atari video modes, I think there is no card that
-	  supports this mode.
- 'p': "packed pixels", i.e. <depth> consecutive bits stand for all
-	  planes of one pixel; this is the most common mode for 8 planes
-	  (256 colors) on graphic cards
- 't': "true color" (more or less packed pixels, but without a color
-	  lookup table); usually depth is 24
+      built-in Atari video modes, I think there is no card that
+      supports this mode.
+ 'p':
+      "packed pixels", i.e. <depth> consecutive bits stand for all
+      planes of one pixel; this is the most common mode for 8 planes
+      (256 colors) on graphic cards
+ 't':
+      "true color" (more or less packed pixels, but without a color
+      lookup table); usually depth is 24
 
 For monochrome modes (i.e., <depth> is 1), the <org> letter has a
 different meaning:
 
- 'n': normal colors, i.e. 0=white, 1=black
- 'i': inverted colors, i.e. 0=black, 1=white
+ 'n':
+      normal colors, i.e. 0=white, 1=black
+ 'i':
+      inverted colors, i.e. 0=black, 1=white
 
-  The next important information about the video hardware is the base
+The next important information about the video hardware is the base
 address of the video memory. That is given in the <scrmem> parameter,
 as a hexadecimal number with a "0x" prefix. You have to find out this
 address in the documentation of your hardware.
 
-  The next parameter, <scrlen>, tells the kernel about the size of the
+The next parameter, <scrlen>, tells the kernel about the size of the
 video memory. If it's missing, the size is calculated from <xres>,
 <yres>, and <depth>. For now, it is not useful to write a value here.
 It would be used only for hardware scrolling (which isn't possible
@@ -460,7 +482,7 @@ empty, either by ending the "external:" after the video address or by
 writing two consecutive semicolons, if you want to give a <vgabase>
 (it is allowed to leave this parameter empty).
 
-  The <vgabase> parameter is optional. If it is not given, the kernel
+The <vgabase> parameter is optional. If it is not given, the kernel
 cannot read or write any color registers of the video hardware, and
 thus you have to set appropriate colors before you start Linux. But if
 your card is somehow VGA compatible, you can tell the kernel the base
@@ -472,18 +494,18 @@ uses the addresses vgabase+0x3c7...vgabase+0x3c9. The <vgabase>
 parameter is written in hexadecimal with a "0x" prefix, just as
 <scrmem>.
 
-  <colw> is meaningful only if <vgabase> is specified. It tells the
+<colw> is meaningful only if <vgabase> is specified. It tells the
 kernel how wide each of the color register is, i.e. the number of bits
 per single color (red/green/blue). Default is 6, another quite usual
 value is 8.
 
-  Also <coltype> is used together with <vgabase>. It tells the kernel
+Also <coltype> is used together with <vgabase>. It tells the kernel
 about the color register model of your gfx board. Currently, the types
 "vga" (which is also the default) and "mv300" (SANG MV300) are
 implemented.
 
-  Parameter <xres_virtual> is required for ProMST or ET4000 cards where
-the physical linelength differs from the visible length. With ProMST, 
+Parameter <xres_virtual> is required for ProMST or ET4000 cards where
+the physical linelength differs from the visible length. With ProMST,
 xres_virtual must be set to 2048. For ET4000, xres_virtual depends on the
 initialisation of the video-card.
 If you're missing a corresponding yres_virtual: the external part is legacy,
@@ -499,13 +521,13 @@ currently works only with the ScreenWonder!
 4.1.8) monitorcap:
 -------------------
 
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
 
 This describes the capabilities of a multisync monitor. Don't use it
 with a fixed-frequency monitor! For now, only the Falcon frame buffer
 uses the settings of "monitorcap:".
 
-  <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
 your monitor can work with, in Hz. <hmin> and <hmax> are the same for
 the horizontal frequency, in kHz.
 
@@ -520,28 +542,28 @@ If this option is given, the framebuffer device doesn't do any video
 mode calculations and settings on its own. The only Atari fb device
 that does this currently is the Falcon.
 
-  What you reach with this: Settings for unknown video extensions
+What you reach with this: Settings for unknown video extensions
 aren't overridden by the driver, so you can still use the mode found
 when booting, when the driver doesn't know to set this mode itself.
 But this also means, that you can't switch video modes anymore...
 
-  An example where you may want to use "keep" is the ScreenBlaster for
+An example where you may want to use "keep" is the ScreenBlaster for
 the Falcon.
 
 
 4.2) atamouse=
 --------------
 
-Syntax: atamouse=<x-threshold>,[<y-threshold>]
+:Syntax: atamouse=<x-threshold>,[<y-threshold>]
 
-  With this option, you can set the mouse movement reporting threshold.
+With this option, you can set the mouse movement reporting threshold.
 This is the number of pixels of mouse movement that have to accumulate
 before the IKBD sends a new mouse packet to the kernel. Higher values
 reduce the mouse interrupt load and thus reduce the chance of keyboard
 overruns. Lower values give a slightly faster mouse responses and
 slightly better mouse tracking.
 
-  You can set the threshold in x and y separately, but usually this is
+You can set the threshold in x and y separately, but usually this is
 of little practical use. If there's just one number in the option, it
 is used for both dimensions. The default value is 2 for both
 thresholds.
@@ -550,7 +572,7 @@ thresholds.
 4.3) ataflop=
 -------------
 
-Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
+:Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
 
    The drive type may be 0, 1, or 2, for DD, HD, and ED, resp. This
    setting affects how many buffers are reserved and which formats are
@@ -563,15 +585,15 @@ Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
    no for the Medusa and yes for all others.
 
    With the two following parameters, you can change the default
-   steprate used for drive A and B, resp. 
+   steprate used for drive A and B, resp.
 
 
 4.4) atascsi=
 -------------
 
-Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
+:Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
 
-  This option sets some parameters for the Atari native SCSI driver.
+This option sets some parameters for the Atari native SCSI driver.
 Generally, any number of arguments can be omitted from the end. And
 for each of the numbers, a negative value means "use default". The
 defaults depend on whether TT-style or Falcon-style SCSI is used.
@@ -597,11 +619,14 @@ ignored (others aren't affected).
     32). Default: 8/1. (Note: Values > 1 seem to cause problems on a
     Falcon, cause not yet known.)
 
-      The <cmd_per_lun> value at a great part determines the amount of
+    The <cmd_per_lun> value at a great part determines the amount of
     memory SCSI reserves for itself. The formula is rather
     complicated, but I can give you some hints:
-      no scatter-gather  : cmd_per_lun * 232 bytes
-      full scatter-gather: cmd_per_lun * approx. 17 Kbytes
+
+      no scatter-gather:
+	cmd_per_lun * 232 bytes
+      full scatter-gather:
+	cmd_per_lun * approx. 17 Kbytes
 
   <scat-gat>:
     Size of the scatter-gather table, i.e. the number of requests
@@ -634,19 +659,23 @@ ignored (others aren't affected).
 4.5 switches=
 -------------
 
-Syntax: switches=<list of switches>
+:Syntax: switches=<list of switches>
 
-  With this option you can switch some hardware lines that are often
+With this option you can switch some hardware lines that are often
 used to enable/disable certain hardware extensions. Examples are
 OverScan, overclocking, ...
 
-  The <list of switches> is a comma-separated list of the following
+The <list of switches> is a comma-separated list of the following
 items:
 
-  ikbd: set RTS of the keyboard ACIA high
-  midi: set RTS of the MIDI ACIA high
-  snd6: set bit 6 of the PSG port A
-  snd7: set bit 6 of the PSG port A
+  ikbd:
+	set RTS of the keyboard ACIA high
+  midi:
+	set RTS of the MIDI ACIA high
+  snd6:
+	set bit 6 of the PSG port A
+  snd7:
+	set bit 6 of the PSG port A
 
 It doesn't make sense to mention a switch more than once (no
 difference to only once), but you can give as many switches as you
@@ -654,16 +683,16 @@ want to enable different features. The switch lines are set as early
 as possible during kernel initialization (even before determining the
 present hardware.)
 
-  All of the items can also be prefixed with "ov_", i.e. "ov_ikbd",
-"ov_midi", ... These options are meant for switching on an OverScan
+All of the items can also be prefixed with `ov_`, i.e. `ov_ikbd`,
+`ov_midi`, ... These options are meant for switching on an OverScan
 video extension. The difference to the bare option is that the
 switch-on is done after video initialization, and somehow synchronized
 to the HBLANK. A speciality is that ov_ikbd and ov_midi are switched
 off before rebooting, so that OverScan is disabled and TOS boots
 correctly.
 
-  If you give an option both, with and without the "ov_" prefix, the
-earlier initialization ("ov_"-less) takes precedence. But the
+If you give an option both, with and without the `ov_` prefix, the
+earlier initialization (`ov_`-less) takes precedence. But the
 switching-off on reset still happens in this case.
 
 5) Options for Amiga Only:
@@ -672,10 +701,10 @@ switching-off on reset still happens in this case.
 5.1) video=
 -----------
 
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
 
 The <fbname> parameter specifies the name of the frame buffer, valid
-options are `amifb', `cyber', 'virge', `retz3' and `clgen', provided
+options are `amifb`, `cyber`, 'virge', `retz3` and `clgen`, provided
 that the respective frame buffer devices have been compiled into the
 kernel (or compiled as loadable modules). The behavior of the <fbname>
 option was changed in 2.1.57 so it is now recommended to specify this
@@ -697,9 +726,11 @@ predefined video modes are available:
 NTSC modes:
  - ntsc            : 640x200, 15 kHz, 60 Hz
  - ntsc-lace       : 640x400, 15 kHz, 60 Hz interlaced
+
 PAL modes:
  - pal             : 640x256, 15 kHz, 50 Hz
  - pal-lace        : 640x512, 15 kHz, 50 Hz interlaced
+
 ECS modes:
  - multiscan       : 640x480, 29 kHz, 57 Hz
  - multiscan-lace  : 640x960, 29 kHz, 57 Hz interlaced
@@ -715,6 +746,7 @@ ECS modes:
  - dblpal-lace     : 640x1024, 27 kHz, 47 Hz interlaced
  - dblntsc         : 640x200, 27 kHz, 57 Hz doublescan
  - dblpal          : 640x256, 27 kHz, 47 Hz doublescan
+
 VGA modes:
  - vga             : 640x480, 31 kHz, 60 Hz
  - vga70           : 640x400, 31 kHz, 70 Hz
@@ -726,7 +758,7 @@ chipset and 8-bit color for the AGA chipset.
 5.1.2) depth
 ------------
 
-Syntax: depth:<nr. of bit-planes>
+:Syntax: depth:<nr. of bit-planes>
 
 Specify the number of bit-planes for the selected video-mode.
 
@@ -739,32 +771,32 @@ Use inverted display (black on white). Functionally the same as the
 5.1.4) font
 -----------
 
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
 
 Specify the font to use in text modes. Functionally the same as the
-"font" sub-option for the Atari, except that `PEARL8x8' is used instead
-of `VGA8x8' if the vertical size of the display is less than 400 pixel
+"font" sub-option for the Atari, except that `PEARL8x8` is used instead
+of `VGA8x8` if the vertical size of the display is less than 400 pixel
 rows.
 
 5.1.5) monitorcap:
 -------------------
 
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
 
 This describes the capabilities of a multisync monitor. For now, only
 the color frame buffer uses the settings of "monitorcap:".
 
-  <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
 your monitor can work with, in Hz. <hmin> and <hmax> are the same for
 the horizontal frequency, in kHz.
 
-  The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
+The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
 
 
 5.2) fd_def_df0=
 ----------------
 
-Syntax: fd_def_df0=<value>
+:Syntax: fd_def_df0=<value>
 
 Sets the df0 value for "silent" floppy drives. The value should be in
 hexadecimal with "0x" prefix.
@@ -773,7 +805,7 @@ hexadecimal with "0x" prefix.
 5.3) wd33c93=
 -------------
 
-Syntax: wd33c93=<sub-options...>
+:Syntax: wd33c93=<sub-options...>
 
 These options affect the A590/A2091, A3000 and GVP Series II SCSI
 controllers.
@@ -784,9 +816,9 @@ below.
 5.3.1) nosync
 -------------
 
-Syntax: nosync:bitmask
+:Syntax: nosync:bitmask
 
-  bitmask is a byte where the 1st 7 bits correspond with the 7
+bitmask is a byte where the 1st 7 bits correspond with the 7
 possible SCSI devices. Set a bit to prevent sync negotiation on that
 device. To maintain backwards compatibility, a command-line such as
 "wd33c93=255" will be automatically translated to
@@ -796,35 +828,35 @@ all devices, eg. nosync:0xff.
 5.3.2) period
 -------------
 
-Syntax: period:ns
+:Syntax: period:ns
 
-  `ns' is the minimum # of nanoseconds in a SCSI data transfer
+`ns` is the minimum # of nanoseconds in a SCSI data transfer
 period. Default is 500; acceptable values are 250 - 1000.
 
 5.3.3) disconnect
 -----------------
 
-Syntax: disconnect:x
+:Syntax: disconnect:x
 
-  Specify x = 0 to never allow disconnects, 2 to always allow them.
+Specify x = 0 to never allow disconnects, 2 to always allow them.
 x = 1 does 'adaptive' disconnects, which is the default and generally
 the best choice.
 
 5.3.4) debug
 ------------
 
-Syntax: debug:x
+:Syntax: debug:x
 
-  If `DEBUGGING_ON' is defined, x is a bit mask that causes various
+If `DEBUGGING_ON` is defined, x is a bit mask that causes various
 types of debug output to printed - see the DB_xxx defines in
 wd33c93.h.
 
 5.3.5) clock
 ------------
 
-Syntax: clock:x
+:Syntax: clock:x
 
-  x = clock input in MHz for WD33c93 chip. Normal values would be from
+x = clock input in MHz for WD33c93 chip. Normal values would be from
 8 through 20. The default value depends on your hostadapter(s),
 default for the A3000 internal controller is 14, for the A2091 it's 8
 and for the GVP hostadapters it's either 8 or 14, depending on the
@@ -834,15 +866,15 @@ hostadapters.
 5.3.6) next
 -----------
 
-  No argument. Used to separate blocks of keywords when there's more
+No argument. Used to separate blocks of keywords when there's more
 than one wd33c93-based host adapter in the system.
 
 5.3.7) nodma
 ------------
 
-Syntax: nodma:x
+:Syntax: nodma:x
 
-  If x is 1 (or if the option is just written as "nodma"), the WD33c93
+If x is 1 (or if the option is just written as "nodma"), the WD33c93
 controller will not use DMA (= direct memory access) to access the
 Amiga's memory.  This is useful for some systems (like A3000's and
 A4000's with the A3640 accelerator, revision 3.0) that have problems
@@ -853,32 +885,27 @@ possible.
 5.4) gvp11=
 -----------
 
-Syntax: gvp11=<addr-mask>
+:Syntax: gvp11=<addr-mask>
 
-  The earlier versions of the GVP driver did not handle DMA
+The earlier versions of the GVP driver did not handle DMA
 address-mask settings correctly which made it necessary for some
 people to use this option, in order to get their GVP controller
 running under Linux. These problems have hopefully been solved and the
 use of this option is now highly unrecommended!
 
-  Incorrect use can lead to unpredictable behavior, so please only use
+Incorrect use can lead to unpredictable behavior, so please only use
 this option if you *know* what you are doing and have a reason to do
 so. In any case if you experience problems and need to use this
 option, please inform us about it by mailing to the Linux/68k kernel
 mailing list.
 
-  The address mask set by this option specifies which addresses are
+The address mask set by this option specifies which addresses are
 valid for DMA with the GVP Series II SCSI controller. An address is
 valid, if no bits are set except the bits that are set in the mask,
 too.
 
-  Some versions of the GVP can only DMA into a 24 bit address range,
+Some versions of the GVP can only DMA into a 24 bit address range,
 some can address a 25 bit address range while others can use the whole
 32 bit address range for DMA. The correct setting depends on your
 controller and should be autodetected by the driver. An example is the
 24 bit region which is specified by a mask of 0x00fffffe.
-
-
-/* Local Variables: */
-/* mode: text       */
-/* End:             */
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
#75 lore raw

PATCH 46/57 docs: cma/debugfs.txt: convert to ReST and move to admin-guide/mm

In reply to Mauro Carvalho Chehab

The debugfs interface for CMA should be there together with other mm-related documents.

Convert this small file to ReST and move it to its rightful place.

The conversion is actually quite simple: just add a title for the document. In order to make it to look better for the audience, also mark the "echo" command as a literal block.

---
 Documentation/cma/debugfs.txt | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)
Documentation/cma/debugfs.txt +5 -1
index 6cef20a8cedc..4e06ffabd78a 100644
@@ -1,3 +1,7 @@
+=====================
+CMA Debugfs Interface
+=====================
+
 The CMA debugfs interface is useful to retrieve basic information out of the
 different CMA areas and to test allocation/release in each of the areas.
 
@@ -12,7 +16,7 @@ The structure of the files created under that directory is as follows:
  - [RO] count: Amount of memory in the CMA area.
  - [RO] order_per_bit: Order of pages represented by one bit.
  - [RO] bitmap: The bitmap of page states in the zone.
- - [WO] alloc: Allocate N pages from that CMA area. For example:
+ - [WO] alloc: Allocate N pages from that CMA area. For example::
 
 	echo 5 > <debugfs>/cma/cma-2/alloc
 
Signature · 1 line
2.20.1
#87 lore raw

PATCH 56/57 docs: phy: convert samsung-usb2.txt to ReST format

In reply to Mauro Carvalho Chehab

In order to merge it into a Sphinx book, we need first to convert to ReST.

---
 Documentation/phy/samsung-usb2.txt | 60 +++++++++++++++---------------
 1 file changed, 31 insertions(+), 29 deletions(-)
Documentation/phy/samsung-usb2.txt +31 -29
index ed12d437189d..c48c8b9797b9 100644
@@ -1,9 +1,9 @@
-.------------------------------------------------------------------------------+
-|			Samsung USB 2.0 PHY adaptation layer		       |
-+-----------------------------------------------------------------------------+'
+====================================
+Samsung USB 2.0 PHY adaptation layer
+====================================
 
-| 1. Description
-+----------------
+1. Description
+--------------
 
 The architecture of the USB 2.0 PHY module in Samsung SoCs is similar
 among many SoCs. In spite of the similarities it proved difficult to
@@ -14,8 +14,8 @@ the PHY powering up process had to be altered. This adaptation layer is
 a compromise between having separate drivers and having a single driver
 with added support for many special cases.
 
-| 2. Files description
-+----------------------
+2. Files description
+--------------------
 
 - phy-samsung-usb2.c
    This is the main file of the adaptation layer. This file contains
@@ -32,44 +32,45 @@ with added support for many special cases.
    driver. In addition it should contain extern declarations for
    structures that describe particular SoCs.
 
-| 3. Supporting SoCs
-+--------------------
+3. Supporting SoCs
+------------------
 
 To support a new SoC a new file should be added to the drivers/phy
 directory. Each SoC's configuration is stored in an instance of the
-struct samsung_usb2_phy_config.
+struct samsung_usb2_phy_config::
 
-struct samsung_usb2_phy_config {
+  struct samsung_usb2_phy_config {
 	const struct samsung_usb2_common_phy *phys;
 	int (*rate_to_clk)(unsigned long, u32 *);
 	unsigned int num_phys;
 	bool has_mode_switch;
-};
+  };
 
-The num_phys is the number of phys handled by the driver. *phys is an
+The num_phys is the number of phys handled by the driver. `*phys` is an
 array that contains the configuration for each phy. The has_mode_switch
 property is a boolean flag that determines whether the SoC has USB host
 and device on a single pair of pins. If so, a special register has to
 be modified to change the internal routing of these pins between a USB
 device or host module.
 
-For example the configuration for Exynos 4210 is following:
+For example the configuration for Exynos 4210 is following::
 
-const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
+  const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
 	.has_mode_switch        = 0,
 	.num_phys		= EXYNOS4210_NUM_PHYS,
 	.phys			= exynos4210_phys,
 	.rate_to_clk		= exynos4210_rate_to_clk,
-}
+  }
+
+- `int (*rate_to_clk)(unsigned long, u32 *)`
 
-- int (*rate_to_clk)(unsigned long, u32 *)
 	The rate_to_clk callback is to convert the rate of the clock
 	used as the reference clock for the PHY module to the value
 	that should be written in the hardware register.
 
-The exynos4210_phys configuration array is as follows:
+The exynos4210_phys configuration array is as follows::
 
-static const struct samsung_usb2_common_phy exynos4210_phys[] = {
+  static const struct samsung_usb2_common_phy exynos4210_phys[] = {
 	{
 		.label		= "device",
 		.id		= EXYNOS4210_DEVICE,
@@ -95,29 +96,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
 		.power_off	= exynos4210_power_off,
 	},
 	{},
-};
+  };
+
+- `int (*power_on)(struct samsung_usb2_phy_instance *);`
+  `int (*power_off)(struct samsung_usb2_phy_instance *);`
 
-- int (*power_on)(struct samsung_usb2_phy_instance *);
-- int (*power_off)(struct samsung_usb2_phy_instance *);
 	These two callbacks are used to power on and power off the phy
 	by modifying appropriate registers.
 
 Final change to the driver is adding appropriate compatible value to the
 phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were
-added to the struct of_device_id samsung_usb2_phy_of_match[] array:
+added to the struct of_device_id samsung_usb2_phy_of_match[] array::
 
-#ifdef CONFIG_PHY_EXYNOS4210_USB2
+  #ifdef CONFIG_PHY_EXYNOS4210_USB2
 	{
 		.compatible = "samsung,exynos4210-usb2-phy",
 		.data = &exynos4210_usb2_phy_config,
 	},
-#endif
+  #endif
 
 To add further flexibility to the driver the Kconfig file enables to
 include support for selected SoCs in the compiled driver. The Kconfig
-entry for Exynos 4210 is following:
+entry for Exynos 4210 is following::
 
-config PHY_EXYNOS4210_USB2
+  config PHY_EXYNOS4210_USB2
 	bool "Support for Exynos 4210"
 	depends on PHY_SAMSUNG_USB2
 	depends on CPU_EXYNOS4210
@@ -128,8 +130,8 @@ config PHY_EXYNOS4210_USB2
 	  phys are available - device, host, HSCI0 and HSCI1.
 
 The newly created file that supports the new SoC has to be also added to the
-Makefile. In case of Exynos 4210 the added line is following:
+Makefile. In case of Exynos 4210 the added line is following::
 
-obj-$(CONFIG_PHY_EXYNOS4210_USB2)       += phy-exynos4210-usb2.o
+  obj-$(CONFIG_PHY_EXYNOS4210_USB2)       += phy-exynos4210-usb2.o
 
 After completing these steps the support for the new SoC should be ready.
Signature · 1 line
2.20.1
#88 lore raw

PATCH 57/57 docs: Prepare files to be renamed to *.rst

In reply to Mauro Carvalho Chehab

Remove some blank spaces at the end of the lines.

---
 Documentation/bt8xxgpio.txt             |  1 -
 Documentation/bus-virt-phys-mapping.txt | 50 ++++++++++++------------
 Documentation/highuid.txt               |  2 +-
 Documentation/kobject.txt               |  2 +-
 Documentation/ldm.txt                   |  3 +-
 Documentation/memory-barriers.txt       |  2 +-
 Documentation/numastat.txt              |  1 -
 Documentation/pnp.txt                   | 11 +++---
 Documentation/preempt-locking.txt       |  2 +-
 Documentation/rbtree.txt                | 52 ++++++++++++-------------
 Documentation/rtc.txt                   |  6 +--
 Documentation/zorro.txt                 |  5 +--
 12 files changed, 66 insertions(+), 71 deletions(-)
Documentation/bt8xxgpio.txt +0 -1
index a845feb074de..4f937bead52c 100644
@@ -59,4 +59,3 @@ The GPIO pins are marked with G00-G23::
            | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
            ^
            This is pin 1
-
Documentation/bus-virt-phys-mapping.txt +25 -25

131 lines not on this page · raw message

Documentation/highuid.txt +1 -1
index 6ee70465c0ea..1ab59d7807d1 100644
@@ -19,7 +19,7 @@ What's left to be done for 32-bit UIDs on all Linux architectures:
   underlying filesystem, because quota records are written at offsets
   corresponding to the UID in question.
   Further investigation is needed to see if the quota system can cope
-  properly with huge UIDs. If it can deal with 64-bit file offsets on all 
+  properly with huge UIDs. If it can deal with 64-bit file offsets on all
   architectures, this should not be a problem.
 
 - Decide whether or not to keep backwards compatibility with the system
Documentation/kobject.txt +1 -1
index ff4c25098119..fa0009ca0bc7 100644
@@ -270,7 +270,7 @@ such a method has a form like::
 
     void my_object_release(struct kobject *kobj)
     {
-    	    struct my_object *mine = container_of(kobj, struct my_object, kobj);
+	    struct my_object *mine = container_of(kobj, struct my_object, kobj);
 
 	    /* Perform any additional cleanup on this object, then... */
 	    kfree(mine);
Documentation/ldm.txt +1 -2
index 12c571368e73..90ccf24ebfdd 100644
@@ -75,7 +75,7 @@ When Linux boots, you will see something like::
 Compiling LDM Support
 ---------------------
 
-To enable LDM, choose the following two options: 
+To enable LDM, choose the following two options:
 
   - "Advanced partition selection" CONFIG_PARTITION_ADVANCED
   - "Windows Logical Disk Manager (Dynamic Disk) support" CONFIG_LDM_PARTITION
@@ -118,4 +118,3 @@ me.
 Cheers,
     FlatCap - Richard Russon
     [email protected]
-
Documentation/memory-barriers.txt +1 -1
index 4e0446230205..f585022aed8f 100644
@@ -334,7 +334,7 @@ And there are anti-guarantees:
      of the standard containing this guarantee is Section 3.14, which
      defines "memory location" as follows:
 
-     	memory location
+	memory location
 		either an object of scalar type, or a maximal sequence
 		of adjacent bit-fields all having nonzero width
 
Documentation/numastat.txt +0 -1
index aaf1667489f8..d6f07ca00c27 100644
@@ -27,4 +27,3 @@ interleave_hit 	Interleaving wanted to allocate from this node
 For easier reading you can use the numastat utility from the numactl package
 (http://oss.sgi.com/projects/libnuma/). Note that it only works
 well right now on machines with a small number of CPUs.
-
Documentation/pnp.txt +5 -6
index bab2d10631f0..c103acb9ad99 100644
@@ -10,7 +10,7 @@ Overview
 --------
 
 Plug and Play provides a means of detecting and setting resources for legacy or
-otherwise unconfigurable devices.  The Linux Plug and Play Layer provides these 
+otherwise unconfigurable devices.  The Linux Plug and Play Layer provides these
 services to compatible drivers.
 
 
@@ -18,7 +18,7 @@ The User Interface
 ------------------
 
 The Linux Plug and Play user interface provides a means to activate PnP devices
-for legacy and user level drivers that do not support Linux Plug and Play.  The 
+for legacy and user level drivers that do not support Linux Plug and Play.  The
 user interface is integrated into sysfs.
 
 In addition to the standard sysfs file the following are created in each
@@ -113,9 +113,9 @@ The Unified Plug and Play Layer
 -------------------------------
 
 All Plug and Play drivers, protocols, and services meet at a central location
-called the Plug and Play Layer.  This layer is responsible for the exchange of 
-information between PnP drivers and PnP protocols.  Thus it automatically 
-forwards commands to the proper protocol.  This makes writing PnP drivers 
+called the Plug and Play Layer.  This layer is responsible for the exchange of
+information between PnP drivers and PnP protocols.  Thus it automatically
+forwards commands to the proper protocol.  This makes writing PnP drivers
 significantly easier.
 
 The following functions are available from the Plug and Play Layer:
@@ -289,4 +289,3 @@ They are as follows::
 				     unsigned short vendor,
 				     unsigned short function,
 				     struct pnp_dev *from)
-
Documentation/preempt-locking.txt +1 -1
index 509f5a422d57..47ad9688dc11 100644
@@ -16,7 +16,7 @@ requires explicit additional locking for very few additional situations.
 
 This document is for all kernel hackers.  Developing code in the kernel
 requires protecting these situations.
- 
+
 
 RULE #1: Per-CPU data structures need explicit protection
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Documentation/rbtree.txt +26 -26

93 lines not on this page · raw message

Documentation/rtc.txt +3 -3
index 688c95b11919..c7647de33c69 100644
@@ -86,9 +86,9 @@ a different value to /proc/sys/dev/rtc/max-user-freq. Note that the
 interrupt handler is only a few lines of code to minimize any possibility
 of this effect.
 
-Also, if the kernel time is synchronized with an external source, the 
-kernel will write the time back to the CMOS clock every 11 minutes. In 
-the process of doing this, the kernel briefly turns off RTC periodic 
+Also, if the kernel time is synchronized with an external source, the
+kernel will write the time back to the CMOS clock every 11 minutes. In
+the process of doing this, the kernel briefly turns off RTC periodic
 interrupts, so be aware of this if you are doing serious work. If you
 don't synchronize the kernel time with an external source (via ntp or
 whatever) then the kernel will keep its hands off the RTC, allowing you
Documentation/zorro.txt +2 -3
index 664072b017e3..59fb1634d903 100644
@@ -77,7 +77,7 @@ The treatment of these regions depends on the type of Zorro space:
 
   - Zorro II address space is always mapped and does not have to be mapped
     explicitly using z_ioremap().
-    
+
     Conversion from bus/physical Zorro II addresses to kernel virtual addresses
     and vice versa is done using::
 
@@ -86,7 +86,7 @@ The treatment of these regions depends on the type of Zorro space:
 
   - Zorro III address space must be mapped explicitly using z_ioremap() first
     before it can be accessed::
- 
+
 	virt_addr = z_ioremap(bus_addr, size);
 	...
 	z_iounmap(virt_addr);
@@ -101,4 +101,3 @@ References
 #. linux/arch/m68k/include/asm/zorro.h
 #. linux/drivers/zorro
 #. /proc/bus/zorro
-
Signature · 1 line
2.20.1
#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
#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
#67 lore raw

PATCH 38/57 docs: x86: convert text files to ReST

In reply to Mauro Carvalho Chehab

Convert the x86/x86_64 text files to ReST and prepare them to be part of a new architecture book.

---
 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 ++-
 22 files changed, 1575 insertions(+), 1272 deletions(-)
Documentation/x86/amd-memory-encryption.txt +7 -3
index afc41f544dab..bcefc00847f4 100644
@@ -1,3 +1,7 @@
+=====================
+AMD memory encryption
+=====================
+
 Secure Memory Encryption (SME) and Secure Encrypted Virtualization (SEV) are
 features found on AMD processors.
 
@@ -34,7 +38,7 @@ is operating in 64-bit or 32-bit PAE mode, in all other modes the SEV hardware
 forces the memory encryption bit to 1.
 
 Support for SME and SEV can be determined through the CPUID instruction. The
-CPUID function 0x8000001f reports information related to SME:
+CPUID function 0x8000001f reports information related to SME::
 
 	0x8000001f[eax]:
 		Bit[0] indicates support for SME
@@ -48,14 +52,14 @@ CPUID function 0x8000001f reports information related to SME:
 			   addresses)
 
 If support for SME is present, MSR 0xc00100010 (MSR_K8_SYSCFG) can be used to
-determine if SME is enabled and/or to enable memory encryption:
+determine if SME is enabled and/or to enable memory encryption::
 
 	0xc0010010:
 		Bit[23]   0 = memory encryption features are disabled
 			  1 = memory encryption features are enabled
 
 If SEV is supported, MSR 0xc0010131 (MSR_AMD64_SEV) can be used to determine if
-SEV is active:
+SEV is active::
 
 	0xc0010131:
 		Bit[0]	  0 = memory encryption is not active
Documentation/x86/boot.txt +305 -273

992 lines not on this page · raw message

Documentation/x86/earlyprintk.txt +37 -32

127 lines not on this page · raw message

Documentation/x86/entry_64.txt +8 -3
index c1df8eba9dfd..5fde68a19f57 100644
@@ -1,3 +1,8 @@
+=====================
+Entries at entry_64.S
+=====================
+
+
 This file documents some of the kernel entries in
 arch/x86/entry/entry_64.S.  A lot of this explanation is adapted from
 an email from Ingo Molnar:
@@ -59,7 +64,7 @@ Now, there's a secondary complication: there's a cheap way to test
 which mode the CPU is in and an expensive way.
 
 The cheap way is to pick this info off the entry frame on the kernel
-stack, from the CS of the ptregs area of the kernel stack:
+stack, from the CS of the ptregs area of the kernel stack::
 
 	xorl %ebx,%ebx
 	testl $3,CS+8(%rsp)
@@ -67,7 +72,7 @@ stack, from the CS of the ptregs area of the kernel stack:
 	SWAPGS
 
 The expensive (paranoid) way is to read back the MSR_GS_BASE value
-(which is what SWAPGS modifies):
+(which is what SWAPGS modifies)::
 
 	movl $1,%ebx
 	movl $MSR_GS_BASE,%ecx
@@ -76,7 +81,7 @@ The expensive (paranoid) way is to read back the MSR_GS_BASE value
 	js 1f   /* negative -> in kernel */
 	SWAPGS
 	xorl %ebx,%ebx
-1:	ret
+  1:	ret
 
 If we are at an interrupt or user-trap/gate-alike boundary then we can
 use the faster check: the stack will be a reliable indicator of
Documentation/x86/exception-tables.txt +141 -104

366 lines not on this page · raw message

Documentation/x86/i386/IO-APIC.txt +12 -11
index 15f5baf7e1b6..4a9d2e4dfe5d 100644
@@ -1,3 +1,7 @@
+=======
+IO-APIC
+=======
+
 Most (all) Intel-MP compliant SMP boards have the so-called 'IO-APIC',
 which is an enhanced interrupt controller. It enables us to route
 hardware interrupts to multiple CPUs, or to CPU groups. Without an
@@ -13,9 +17,8 @@ usually worked around by the kernel. If your MP-compliant SMP board does
 not boot Linux, then consult the linux-smp mailing list archives first.
 
 If your box boots fine with enabled IO-APIC IRQs, then your
-/proc/interrupts will look like this one:
+/proc/interrupts will look like this one::
 
-   ---------------------------->
   hell:~> cat /proc/interrupts
              CPU0
     0:    1360293    IO-APIC-edge  timer
@@ -28,7 +31,6 @@ If your box boots fine with enabled IO-APIC IRQs, then your
   NMI:          0
   ERR:          0
   hell:~>
-  <----------------------------
 
 Some interrupts are still listed as 'XT PIC', but this is not a problem;
 none of those IRQ sources is performance-critical.
@@ -37,14 +39,14 @@ none of those IRQ sources is performance-critical.
 In the unlikely case that your board does not create a working mp-table,
 you can use the pirq= boot parameter to 'hand-construct' IRQ entries. This
 is non-trivial though and cannot be automated. One sample /etc/lilo.conf
-entry:
+entry::
 
 	append="pirq=15,11,10"
 
 The actual numbers depend on your system, on your PCI cards and on their
 PCI slot position. Usually PCI slots are 'daisy chained' before they are
 connected to the PCI chipset IRQ routing facility (the incoming PIRQ1-4
-lines):
+lines)::
 
                ,-.        ,-.        ,-.        ,-.        ,-.
      PIRQ4 ----| |-.    ,-| |-.    ,-| |-.    ,-| |--------| |
@@ -56,7 +58,7 @@ lines):
      PIRQ1 ----| |-  `----| |-  `----| |-  `----| |--------| |
                `-'        `-'        `-'        `-'        `-'
 
-Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD:
+Every PCI card emits a PCI IRQ, which can be INTA, INTB, INTC or INTD::
 
                                ,-.
                          INTD--| |
@@ -78,19 +80,19 @@ to have non shared interrupts). Slot5 should be used for videocards, they
 do not use interrupts normally, thus they are not daisy chained either.
 
 so if you have your SCSI card (IRQ11) in Slot1, Tulip card (IRQ9) in
-Slot2, then you'll have to specify this pirq= line:
+Slot2, then you'll have to specify this pirq= line::
 
 	append="pirq=11,9"
 
 the following script tries to figure out such a default pirq= line from
-your PCI configuration:
+your PCI configuration::
 
 	echo -n pirq=; echo `scanpci | grep T_L | cut -c56-` | sed 's/ /,/g'
 
 note that this script won't work if you have skipped a few slots or if your
 board does not do default daisy-chaining. (or the IO-APIC has the PIRQ pins
 connected in some strange way). E.g. if in the above case you have your SCSI
-card (IRQ11) in Slot3, and have Slot1 empty:
+card (IRQ11) in Slot3, and have Slot1 empty::
 
 	append="pirq=0,9,11"
 
@@ -105,7 +107,7 @@ won't function properly (e.g. if it's inserted as a module).
 If you have 2 PCI buses, then you can use up to 8 pirq values, although such
 boards tend to have a good configuration.
 
-Be prepared that it might happen that you need some strange pirq line:
+Be prepared that it might happen that you need some strange pirq line::
 
 	append="pirq=0,0,0,0,0,0,9,11"
 
@@ -116,4 +118,3 @@ [email protected] if you have any problems that are not covered
 by this document.
 
 -- mingo
-
Documentation/x86/intel_mpx.txt +33 -22

100 lines not on this page · raw message

Documentation/x86/microcode.txt +29 -22

89 lines not on this page · raw message

Documentation/x86/mtrr.txt +232 -210

512 lines not on this page · raw message

Documentation/x86/orc-unwinder.txt +1 -0
index cd4b29be29af..3a8d6d324cfa 100644
@@ -1,3 +1,4 @@
+============
 ORC unwinder
 ============
 
Documentation/x86/pat.txt +113 -104

277 lines not on this page · raw message

Documentation/x86/protection-keys.txt +20 -13
index ecb0d2dadfb7..93becb2385b3 100644
@@ -1,3 +1,7 @@
+==========================================
+Memory Protection Keys for Userspace (PKU)
+==========================================
+
 Memory Protection Keys for Userspace (PKU aka PKEYs) is a feature
 which is found on Intel's Skylake "Scalable Processor" Server CPUs.
 It will be avalable in future non-server parts.
@@ -23,9 +27,10 @@ even though there is theoretically space in the PAE PTEs.  These
 permissions are enforced on data access only and have no effect on
 instruction fetches.
 
-=========================== Syscalls ===========================
+Syscalls
+========
 
-There are 3 system calls which directly interact with pkeys:
+There are 3 system calls which directly interact with pkeys::
 
 	int pkey_alloc(unsigned long flags, unsigned long init_access_rights)
 	int pkey_free(int pkey);
@@ -36,7 +41,7 @@ Before a pkey can be used, it must first be allocated with
 pkey_alloc().  An application calls the WRPKRU instruction
 directly in order to change access permissions to memory covered
 with a key.  In this example WRPKRU is wrapped by a C function
-called pkey_set().
+called pkey_set()::
 
 	int real_prot = PROT_READ|PROT_WRITE;
 	pkey = pkey_alloc(0, PKEY_DISABLE_WRITE);
@@ -45,43 +50,45 @@ called pkey_set().
 	... application runs here
 
 Now, if the application needs to update the data at 'ptr', it can
-gain access, do the update, then remove its write access:
+gain access, do the update, then remove its write access::
 
 	pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE
 	*ptr = foo; // assign something
 	pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again
 
 Now when it frees the memory, it will also free the pkey since it
-is no longer in use:
+is no longer in use::
 
 	munmap(ptr, PAGE_SIZE);
 	pkey_free(pkey);
 
-(Note: pkey_set() is a wrapper for the RDPKRU and WRPKRU instructions.
- An example implementation can be found in
- tools/testing/selftests/x86/protection_keys.c)
+Note:
+  pkey_set() is a wrapper for the RDPKRU and WRPKRU instructions.
+  An example implementation can be found in
+  tools/testing/selftests/x86/protection_keys.c
 
-=========================== Behavior ===========================
+Behavior
+========
 
 The kernel attempts to make protection keys consistent with the
-behavior of a plain mprotect().  For instance if you do this:
+behavior of a plain mprotect().  For instance if you do this::
 
 	mprotect(ptr, size, PROT_NONE);
 	something(ptr);
 
-you can expect the same effects with protection keys when doing this:
+you can expect the same effects with protection keys when doing this::
 
 	pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ);
 	pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey);
 	something(ptr);
 
 That should be true whether something() is a direct access to 'ptr'
-like:
+like::
 
 	*ptr = foo;
 
 or when the kernel does the access on the application's behalf like
-with a read():
+with a read()::
 
 	read(fd, ptr, 1);
 
Documentation/x86/pti.txt +7 -1
index 5cd58439ad2d..8ba2a4b8c146 100644
@@ -1,3 +1,7 @@
+====================
+Page Table Isolation
+====================
+
 Overview
 ========
 
@@ -60,6 +64,7 @@ Protection against side-channel attacks is important.  But,
 this protection comes at a cost:
 
 1. Increased Memory Use
+
   a. Each process now needs an order-1 PGD instead of order-0.
      (Consumes an additional 4k per process).
   b. The 'cpu_entry_area' structure must be 2MB in size and 2MB
@@ -68,6 +73,7 @@ this protection comes at a cost:
      is decompressed, but no space in the kernel image itself.
 
 2. Runtime Cost
+
   a. CR3 manipulation to switch between the page table copies
      must be done at interrupt, syscall, and exception entry
      and exit (it can be skipped when the kernel is interrupted,
@@ -124,7 +130,7 @@ Possible Future Work
    boot-time switching.
 
 Testing
-========
+=======
 
 To test stability of PTI, the following test procedure is recommended,
 ideally doing all of these in parallel:
Documentation/x86/resctrl_ui.txt +332 -289

277 lines not on this page · raw message

Documentation/x86/tlb.txt +9 -3
index 6a0607b99ed8..073a0f6827c8 100644

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

Documentation/x86/topology.txt +14 -12
index 2953e3ec9a02..4ad29eb0fc6d 100644

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

Documentation/x86/usb-legacy-support.txt +18 -15
index 1894cdfc69d9..ea18db8c7441 100644

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

Documentation/x86/x86_64/5level-paging.txt +10 -4
index 2432a5ef86d9..fb7a12a83ad7 100644

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

Documentation/x86/x86_64/boot-options.txt +71 -27

98 lines not on this page · raw message

Documentation/x86/x86_64/mm.txt +122 -90

212 lines not on this page · raw message

Documentation/x86/x86_64/uefi.txt +17 -4
index a5e2b4fdb170..7b564b0aa02e 100644

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

Documentation/x86/zero-page.txt +37 -30

67 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.

#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
#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
#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
#73 lore raw

PATCH 44/57 docs: lp855x-driver.txt: convert to ReST and move to kernel-api

In reply to Mauro Carvalho Chehab

This small file seems to be an attempt to start documenting backlight drivers.

It contains descriptions of the controls for the driver with could sound as an somewhat user-faced description, but it's main focus is to describe, instead, the data that should be passed via platform data and some driver-specific stuff.

---
 Documentation/backlight/lp855x-driver.txt | 65 ++++++++++++++---------
 1 file changed, 40 insertions(+), 25 deletions(-)
Documentation/backlight/lp855x-driver.txt +40 -25
index 01bce243d3d7..1e0b224fc397 100644
@@ -1,9 +1,11 @@
+====================
 Kernel driver lp855x
 ====================
 
 Backlight driver for LP855x ICs
 
 Supported chips:
+
 	Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
 	LP8557
 
@@ -14,53 +16,66 @@ Description
 
 * Brightness control
 
-Brightness can be controlled by the pwm input or the i2c command.
-The lp855x driver supports both cases.
+  Brightness can be controlled by the pwm input or the i2c command.
+  The lp855x driver supports both cases.
 
 * Device attributes
 
-1) bl_ctl_mode
-Backlight control mode.
-Value : pwm based or register based
+  1) bl_ctl_mode
 
-2) chip_id
-The lp855x chip id.
-Value : lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
+  Backlight control mode.
+
+  Value: pwm based or register based
+
+  2) chip_id
+
+  The lp855x chip id.
+
+  Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
 
 Platform data for lp855x
 ------------------------
 
 For supporting platform specific data, the lp855x platform data can be used.
 
-* name : Backlight driver name. If it is not defined, default name is set.
-* device_control : Value of DEVICE CONTROL register.
-* initial_brightness : Initial value of backlight brightness.
-* period_ns : Platform specific PWM period value. unit is nano.
-	     Only valid when brightness is pwm input mode.
-* size_program : Total size of lp855x_rom_data.
-* rom_data : List of new eeprom/eprom registers.
+* name:
+	Backlight driver name. If it is not defined, default name is set.
+* device_control:
+	Value of DEVICE CONTROL register.
+* initial_brightness:
+	Initial value of backlight brightness.
+* period_ns:
+	Platform specific PWM period value. unit is nano.
+	Only valid when brightness is pwm input mode.
+* size_program:
+	Total size of lp855x_rom_data.
+* rom_data:
+	List of new eeprom/eprom registers.
 
-example 1) lp8552 platform data : i2c register mode with new eeprom data
+Examples
+========
 
-#define EEPROM_A5_ADDR	0xA5
-#define EEPROM_A5_VAL	0x4f	/* EN_VSYNC=0 */
+1) lp8552 platform data: i2c register mode with new eeprom data::
 
-static struct lp855x_rom_data lp8552_eeprom_arr[] = {
+    #define EEPROM_A5_ADDR	0xA5
+    #define EEPROM_A5_VAL	0x4f	/* EN_VSYNC=0 */
+
+    static struct lp855x_rom_data lp8552_eeprom_arr[] = {
 	{EEPROM_A5_ADDR, EEPROM_A5_VAL},
-};
+    };
 
-static struct lp855x_platform_data lp8552_pdata = {
+    static struct lp855x_platform_data lp8552_pdata = {
 	.name = "lcd-bl",
 	.device_control = I2C_CONFIG(LP8552),
 	.initial_brightness = INITIAL_BRT,
 	.size_program = ARRAY_SIZE(lp8552_eeprom_arr),
 	.rom_data = lp8552_eeprom_arr,
-};
+    };
 
-example 2) lp8556 platform data : pwm input mode with default rom data
+2) lp8556 platform data: pwm input mode with default rom data::
 
-static struct lp855x_platform_data lp8556_pdata = {
+    static struct lp855x_platform_data lp8556_pdata = {
 	.device_control = PWM_CONFIG(LP8556),
 	.initial_brightness = INITIAL_BRT,
 	.period_ns = 1000000,
-};
+    };
Signature · 1 line
2.20.1