From 2c3c1048746a4622d8c89a29670120dc8fab93c4 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 20:49:45 +0200 Subject: Adding upstream version 6.1.76. Signed-off-by: Daniel Baumann --- Documentation/admin-guide/LSM/LoadPin.rst | 31 + Documentation/admin-guide/LSM/SELinux.rst | 33 + Documentation/admin-guide/LSM/SafeSetID.rst | 118 + Documentation/admin-guide/LSM/Smack.rst | 861 +++ Documentation/admin-guide/LSM/Yama.rst | 75 + Documentation/admin-guide/LSM/apparmor.rst | 51 + Documentation/admin-guide/LSM/index.rst | 49 + Documentation/admin-guide/LSM/tomoyo.rst | 65 + Documentation/admin-guide/README.rst | 339 + Documentation/admin-guide/abi-obsolete.rst | 11 + Documentation/admin-guide/abi-removed.rst | 5 + Documentation/admin-guide/abi-stable.rst | 14 + Documentation/admin-guide/abi-testing.rst | 20 + Documentation/admin-guide/abi.rst | 11 + Documentation/admin-guide/acpi/cppc_sysfs.rst | 78 + .../admin-guide/acpi/fan_performance_states.rst | 90 + Documentation/admin-guide/acpi/index.rst | 14 + .../admin-guide/acpi/initrd_table_override.rst | 115 + Documentation/admin-guide/acpi/ssdt-overlays.rst | 181 + Documentation/admin-guide/aoe/aoe.rst | 150 + Documentation/admin-guide/aoe/autoload.sh | 17 + Documentation/admin-guide/aoe/examples.rst | 23 + Documentation/admin-guide/aoe/index.rst | 17 + Documentation/admin-guide/aoe/status.sh | 30 + Documentation/admin-guide/aoe/todo.rst | 17 + Documentation/admin-guide/aoe/udev-install.sh | 33 + Documentation/admin-guide/aoe/udev.txt | 26 + .../admin-guide/auxdisplay/cfag12864b.rst | 98 + Documentation/admin-guide/auxdisplay/index.rst | 16 + Documentation/admin-guide/auxdisplay/ks0108.rst | 50 + Documentation/admin-guide/bcache.rst | 656 ++ Documentation/admin-guide/binderfs.rst | 87 + Documentation/admin-guide/binfmt-misc.rst | 151 + .../blockdev/drbd/DRBD-8.3-data-packets.svg | 588 ++ .../blockdev/drbd/DRBD-data-packets.svg | 459 ++ .../admin-guide/blockdev/drbd/conn-states-8.dot | 18 + .../blockdev/drbd/data-structure-v9.rst | 42 + .../admin-guide/blockdev/drbd/disk-states-8.dot | 16 + .../drbd/drbd-connection-state-overview.dot | 85 + .../admin-guide/blockdev/drbd/figures.rst | 30 + Documentation/admin-guide/blockdev/drbd/index.rst | 19 + .../admin-guide/blockdev/drbd/peer-states-8.dot | 8 + Documentation/admin-guide/blockdev/floppy.rst | 255 + Documentation/admin-guide/blockdev/index.rst | 16 + Documentation/admin-guide/blockdev/nbd.rst | 31 + Documentation/admin-guide/blockdev/paride.rst | 439 ++ Documentation/admin-guide/blockdev/ramdisk.rst | 153 + Documentation/admin-guide/blockdev/zram.rst | 440 ++ Documentation/admin-guide/bootconfig.rst | 323 + Documentation/admin-guide/braille-console.rst | 38 + Documentation/admin-guide/btmrvl.rst | 124 + Documentation/admin-guide/bug-bisect.rst | 76 + Documentation/admin-guide/bug-hunting.rst | 378 ++ .../admin-guide/cgroup-v1/blkio-controller.rst | 301 + Documentation/admin-guide/cgroup-v1/cgroups.rst | 695 ++ Documentation/admin-guide/cgroup-v1/cpuacct.rst | 50 + Documentation/admin-guide/cgroup-v1/cpusets.rst | 879 +++ Documentation/admin-guide/cgroup-v1/devices.rst | 132 + .../admin-guide/cgroup-v1/freezer-subsystem.rst | 127 + Documentation/admin-guide/cgroup-v1/hugetlb.rst | 135 + Documentation/admin-guide/cgroup-v1/index.rst | 31 + Documentation/admin-guide/cgroup-v1/memcg_test.rst | 344 + Documentation/admin-guide/cgroup-v1/memory.rst | 993 +++ Documentation/admin-guide/cgroup-v1/misc.rst | 4 + Documentation/admin-guide/cgroup-v1/net_cls.rst | 44 + Documentation/admin-guide/cgroup-v1/net_prio.rst | 57 + Documentation/admin-guide/cgroup-v1/pids.rst | 92 + Documentation/admin-guide/cgroup-v1/rdma.rst | 117 + Documentation/admin-guide/cgroup-v2.rst | 2968 +++++++++ Documentation/admin-guide/cifs/authors.rst | 69 + Documentation/admin-guide/cifs/changes.rst | 9 + Documentation/admin-guide/cifs/index.rst | 21 + Documentation/admin-guide/cifs/introduction.rst | 53 + Documentation/admin-guide/cifs/todo.rst | 135 + Documentation/admin-guide/cifs/usage.rst | 870 +++ Documentation/admin-guide/cifs/winucase_convert.pl | 62 + Documentation/admin-guide/clearing-warn-once.rst | 9 + Documentation/admin-guide/cpu-load.rst | 117 + Documentation/admin-guide/cputopology.rst | 101 + Documentation/admin-guide/dell_rbu.rst | 128 + .../admin-guide/device-mapper/cache-policies.rst | 131 + Documentation/admin-guide/device-mapper/cache.rst | 337 + Documentation/admin-guide/device-mapper/delay.rst | 31 + .../admin-guide/device-mapper/dm-clone.rst | 333 + .../admin-guide/device-mapper/dm-crypt.rst | 181 + .../admin-guide/device-mapper/dm-dust.rst | 305 + Documentation/admin-guide/device-mapper/dm-ebs.rst | 51 + .../admin-guide/device-mapper/dm-flakey.rst | 74 + Documentation/admin-guide/device-mapper/dm-ima.rst | 715 ++ .../admin-guide/device-mapper/dm-init.rst | 133 + .../admin-guide/device-mapper/dm-integrity.rst | 292 + Documentation/admin-guide/device-mapper/dm-io.rst | 75 + Documentation/admin-guide/device-mapper/dm-log.rst | 57 + .../admin-guide/device-mapper/dm-queue-length.rst | 48 + .../admin-guide/device-mapper/dm-raid.rst | 423 ++ .../admin-guide/device-mapper/dm-service-time.rst | 101 + .../admin-guide/device-mapper/dm-uevent.rst | 110 + .../admin-guide/device-mapper/dm-zoned.rst | 194 + Documentation/admin-guide/device-mapper/era.rst | 116 + Documentation/admin-guide/device-mapper/index.rst | 46 + Documentation/admin-guide/device-mapper/kcopyd.rst | 47 + Documentation/admin-guide/device-mapper/linear.rst | 63 + .../admin-guide/device-mapper/log-writes.rst | 145 + .../admin-guide/device-mapper/persistent-data.rst | 88 + .../admin-guide/device-mapper/snapshot.rst | 196 + .../admin-guide/device-mapper/statistics.rst | 225 + .../admin-guide/device-mapper/striped.rst | 61 + Documentation/admin-guide/device-mapper/switch.rst | 141 + .../device-mapper/thin-provisioning.rst | 427 ++ .../admin-guide/device-mapper/unstriped.rst | 135 + Documentation/admin-guide/device-mapper/verity.rst | 249 + .../admin-guide/device-mapper/writecache.rst | 114 + Documentation/admin-guide/device-mapper/zero.rst | 37 + Documentation/admin-guide/devices.rst | 268 + Documentation/admin-guide/devices.txt | 3086 +++++++++ Documentation/admin-guide/dynamic-debug-howto.rst | 376 ++ Documentation/admin-guide/edid.rst | 60 + Documentation/admin-guide/efi-stub.rst | 100 + Documentation/admin-guide/ext4.rst | 627 ++ Documentation/admin-guide/features.rst | 3 + .../admin-guide/filesystem-monitoring.rst | 78 + Documentation/admin-guide/gpio/gpio-aggregator.rst | 111 + Documentation/admin-guide/gpio/gpio-mockup.rst | 51 + Documentation/admin-guide/gpio/gpio-sim.rst | 134 + Documentation/admin-guide/gpio/index.rst | 20 + Documentation/admin-guide/gpio/sysfs.rst | 167 + Documentation/admin-guide/highuid.rst | 80 + .../admin-guide/hw-vuln/core-scheduling.rst | 226 + .../admin-guide/hw-vuln/cross-thread-rsb.rst | 92 + .../admin-guide/hw-vuln/gather_data_sampling.rst | 109 + Documentation/admin-guide/hw-vuln/index.rst | 23 + Documentation/admin-guide/hw-vuln/l1d_flush.rst | 69 + Documentation/admin-guide/hw-vuln/l1tf.rst | 615 ++ Documentation/admin-guide/hw-vuln/mds.rst | 311 + Documentation/admin-guide/hw-vuln/multihit.rst | 167 + .../hw-vuln/processor_mmio_stale_data.rst | 260 + .../special-register-buffer-data-sampling.rst | 150 + Documentation/admin-guide/hw-vuln/spectre.rst | 756 +++ Documentation/admin-guide/hw-vuln/srso.rst | 133 + .../admin-guide/hw-vuln/tsx_async_abort.rst | 277 + Documentation/admin-guide/hw_random.rst | 105 + Documentation/admin-guide/index.rst | 131 + Documentation/admin-guide/init.rst | 48 + Documentation/admin-guide/initrd.rst | 383 ++ Documentation/admin-guide/iostats.rst | 210 + Documentation/admin-guide/java.rst | 423 ++ Documentation/admin-guide/jfs.rst | 66 + Documentation/admin-guide/kdump/gdbmacros.txt | 323 + Documentation/admin-guide/kdump/index.rst | 20 + Documentation/admin-guide/kdump/kdump.rst | 597 ++ Documentation/admin-guide/kdump/vmcoreinfo.rst | 597 ++ Documentation/admin-guide/kernel-parameters.rst | 224 + Documentation/admin-guide/kernel-parameters.txt | 7025 ++++++++++++++++++++ .../admin-guide/kernel-per-CPU-kthreads.rst | 334 + Documentation/admin-guide/laptops/asus-laptop.rst | 271 + .../admin-guide/laptops/disk-shock-protection.rst | 151 + Documentation/admin-guide/laptops/index.rst | 17 + Documentation/admin-guide/laptops/laptop-mode.rst | 770 +++ Documentation/admin-guide/laptops/lg-laptop.rst | 82 + Documentation/admin-guide/laptops/sony-laptop.rst | 174 + Documentation/admin-guide/laptops/sonypi.rst | 158 + .../admin-guide/laptops/thinkpad-acpi.rst | 1662 +++++ Documentation/admin-guide/laptops/toshiba_haps.rst | 87 + Documentation/admin-guide/lcd-panel-cgram.rst | 27 + Documentation/admin-guide/ldm.rst | 121 + Documentation/admin-guide/lockup-watchdogs.rst | 83 + Documentation/admin-guide/md.rst | 765 +++ .../admin-guide/media/au0828-cardlist.rst | 39 + Documentation/admin-guide/media/avermedia.rst | 94 + Documentation/admin-guide/media/bt8xx.rst | 157 + Documentation/admin-guide/media/bttv-cardlist.rst | 683 ++ Documentation/admin-guide/media/bttv.rst | 1762 +++++ Documentation/admin-guide/media/building.rst | 357 + Documentation/admin-guide/media/cafe_ccic.rst | 62 + Documentation/admin-guide/media/cardlist.rst | 29 + Documentation/admin-guide/media/cec-drivers.rst | 10 + Documentation/admin-guide/media/ci.rst | 77 + Documentation/admin-guide/media/cpia2.rst | 145 + Documentation/admin-guide/media/cx18-cardlist.rst | 17 + .../admin-guide/media/cx231xx-cardlist.rst | 99 + .../admin-guide/media/cx23885-cardlist.rst | 267 + Documentation/admin-guide/media/cx88-cardlist.rst | 383 ++ Documentation/admin-guide/media/cx88.rst | 58 + Documentation/admin-guide/media/davinci-vpbe.rst | 65 + Documentation/admin-guide/media/dvb-drivers.rst | 16 + .../admin-guide/media/dvb-usb-a800-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-af9005-cardlist.rst | 20 + .../admin-guide/media/dvb-usb-af9015-cardlist.rst | 80 + .../admin-guide/media/dvb-usb-af9035-cardlist.rst | 74 + .../admin-guide/media/dvb-usb-anysee-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-au6610-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-az6007-cardlist.rst | 20 + .../admin-guide/media/dvb-usb-az6027-cardlist.rst | 24 + .../admin-guide/media/dvb-usb-ce6230-cardlist.rst | 18 + .../media/dvb-usb-cinergyT2-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-cxusb-cardlist.rst | 40 + .../admin-guide/media/dvb-usb-dib0700-cardlist.rst | 162 + .../media/dvb-usb-dibusb-mb-cardlist.rst | 42 + .../media/dvb-usb-dibusb-mc-cardlist.rst | 30 + .../admin-guide/media/dvb-usb-digitv-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-dtt200u-cardlist.rst | 22 + .../admin-guide/media/dvb-usb-dtv5100-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-dvbsky-cardlist.rst | 42 + .../admin-guide/media/dvb-usb-dw2102-cardlist.rst | 56 + .../admin-guide/media/dvb-usb-ec168-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-gl861-cardlist.rst | 20 + .../admin-guide/media/dvb-usb-gp8psk-cardlist.rst | 22 + .../admin-guide/media/dvb-usb-lmedm04-cardlist.rst | 20 + .../admin-guide/media/dvb-usb-m920x-cardlist.rst | 26 + .../media/dvb-usb-mxl111sf-cardlist.rst | 36 + .../media/dvb-usb-nova-t-usb2-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-opera1-cardlist.rst | 16 + .../media/dvb-usb-pctv452e-cardlist.rst | 20 + .../media/dvb-usb-rtl28xxu-cardlist.rst | 80 + .../media/dvb-usb-technisat-usb2-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-ttusb2-cardlist.rst | 24 + .../admin-guide/media/dvb-usb-umt-010-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-vp702x-cardlist.rst | 16 + .../admin-guide/media/dvb-usb-vp7045-cardlist.rst | 18 + .../admin-guide/media/dvb-usb-zd1301-cardlist.rst | 16 + Documentation/admin-guide/media/dvb.rst | 12 + Documentation/admin-guide/media/dvb_intro.rst | 616 ++ Documentation/admin-guide/media/dvb_references.rst | 29 + .../admin-guide/media/em28xx-cardlist.rst | 440 ++ Documentation/admin-guide/media/faq.rst | 216 + Documentation/admin-guide/media/fimc.rst | 153 + .../admin-guide/media/frontend-cardlist.rst | 226 + Documentation/admin-guide/media/gspca-cardlist.rst | 451 ++ Documentation/admin-guide/media/i2c-cardlist.rst | 296 + Documentation/admin-guide/media/imx.rst | 714 ++ .../admin-guide/media/imx6q-sabreauto.dot | 51 + Documentation/admin-guide/media/imx6q-sabresd.dot | 56 + Documentation/admin-guide/media/imx7.rst | 221 + Documentation/admin-guide/media/index.rst | 63 + Documentation/admin-guide/media/intro.rst | 27 + Documentation/admin-guide/media/ipu3.rst | 600 ++ Documentation/admin-guide/media/ipu3_rcb.svg | 331 + Documentation/admin-guide/media/ivtv-cardlist.rst | 139 + Documentation/admin-guide/media/ivtv.rst | 218 + Documentation/admin-guide/media/lmedm04.rst | 107 + Documentation/admin-guide/media/meye.rst | 93 + Documentation/admin-guide/media/misc-cardlist.rst | 28 + Documentation/admin-guide/media/omap3isp.rst | 92 + Documentation/admin-guide/media/omap4_camera.rst | 62 + Documentation/admin-guide/media/opera-firmware.rst | 33 + .../admin-guide/media/other-usb-cardlist.rst | 92 + Documentation/admin-guide/media/pci-cardlist.rst | 109 + Documentation/admin-guide/media/philips.rst | 247 + .../admin-guide/media/platform-cardlist.rst | 91 + Documentation/admin-guide/media/pulse8-cec.rst | 13 + Documentation/admin-guide/media/qcom_camss.rst | 185 + .../admin-guide/media/qcom_camss_8x96_graph.dot | 106 + .../admin-guide/media/qcom_camss_graph.dot | 43 + Documentation/admin-guide/media/radio-cardlist.rst | 44 + Documentation/admin-guide/media/rcar-fdp1.rst | 39 + .../admin-guide/media/remote-controller.rst | 76 + Documentation/admin-guide/media/rkisp1.dot | 18 + Documentation/admin-guide/media/rkisp1.rst | 197 + .../admin-guide/media/saa7134-cardlist.rst | 803 +++ Documentation/admin-guide/media/saa7134.rst | 89 + .../admin-guide/media/saa7164-cardlist.rst | 71 + Documentation/admin-guide/media/si470x.rst | 167 + Documentation/admin-guide/media/si4713.rst | 192 + Documentation/admin-guide/media/si476x.rst | 160 + Documentation/admin-guide/media/siano-cardlist.rst | 56 + Documentation/admin-guide/media/technisat.rst | 100 + .../admin-guide/media/tm6000-cardlist.rst | 83 + Documentation/admin-guide/media/ttusb-dec.rst | 45 + Documentation/admin-guide/media/tuner-cardlist.rst | 100 + Documentation/admin-guide/media/usb-cardlist.rst | 156 + Documentation/admin-guide/media/v4l-drivers.rst | 34 + Documentation/admin-guide/media/vimc.dot | 26 + Documentation/admin-guide/media/vimc.rst | 110 + Documentation/admin-guide/media/vivid.rst | 1416 ++++ Documentation/admin-guide/media/zoran-cardlist.rst | 51 + Documentation/admin-guide/media/zr364xx.rst | 102 + Documentation/admin-guide/mm/cma_debugfs.rst | 25 + Documentation/admin-guide/mm/concepts.rst | 223 + Documentation/admin-guide/mm/damon/index.rst | 17 + Documentation/admin-guide/mm/damon/lru_sort.rst | 294 + Documentation/admin-guide/mm/damon/reclaim.rst | 265 + Documentation/admin-guide/mm/damon/start.rst | 127 + Documentation/admin-guide/mm/damon/usage.rst | 702 ++ Documentation/admin-guide/mm/hugetlbpage.rst | 475 ++ .../admin-guide/mm/idle_page_tracking.rst | 121 + Documentation/admin-guide/mm/index.rst | 45 + Documentation/admin-guide/mm/ksm.rst | 243 + Documentation/admin-guide/mm/memory-hotplug.rst | 677 ++ Documentation/admin-guide/mm/multigen_lru.rst | 162 + Documentation/admin-guide/mm/nommu-mmap.rst | 283 + .../admin-guide/mm/numa_memory_policy.rst | 516 ++ Documentation/admin-guide/mm/numaperf.rst | 178 + Documentation/admin-guide/mm/pagemap.rst | 232 + Documentation/admin-guide/mm/shrinker_debugfs.rst | 135 + Documentation/admin-guide/mm/soft-dirty.rst | 47 + Documentation/admin-guide/mm/swap_numa.rst | 80 + Documentation/admin-guide/mm/transhuge.rst | 429 ++ Documentation/admin-guide/mm/userfaultfd.rst | 354 + Documentation/admin-guide/mm/zswap.rst | 168 + Documentation/admin-guide/module-signing.rst | 285 + Documentation/admin-guide/mono.rst | 70 + .../admin-guide/namespaces/compatibility-list.rst | 43 + Documentation/admin-guide/namespaces/index.rst | 11 + .../admin-guide/namespaces/resource-control.rst | 18 + Documentation/admin-guide/nfs/index.rst | 14 + Documentation/admin-guide/nfs/nfs-client.rst | 144 + Documentation/admin-guide/nfs/nfs-idmapper.rst | 78 + Documentation/admin-guide/nfs/nfs-rdma.rst | 292 + .../admin-guide/nfs/nfsd-admin-interfaces.rst | 40 + Documentation/admin-guide/nfs/nfsroot.rst | 364 + .../admin-guide/nfs/pnfs-block-server.rst | 42 + Documentation/admin-guide/nfs/pnfs-scsi-server.rst | 24 + Documentation/admin-guide/numastat.rst | 55 + Documentation/admin-guide/parport.rst | 286 + Documentation/admin-guide/perf-security.rst | 325 + Documentation/admin-guide/perf/alibaba_pmu.rst | 100 + Documentation/admin-guide/perf/arm-ccn.rst | 61 + Documentation/admin-guide/perf/arm-cmn.rst | 65 + Documentation/admin-guide/perf/arm_dsu_pmu.rst | 29 + Documentation/admin-guide/perf/hisi-pcie-pmu.rst | 106 + Documentation/admin-guide/perf/hisi-pmu.rst | 114 + Documentation/admin-guide/perf/hns3-pmu.rst | 136 + Documentation/admin-guide/perf/imx-ddr.rst | 71 + Documentation/admin-guide/perf/index.rst | 21 + Documentation/admin-guide/perf/qcom_l2_pmu.rst | 39 + Documentation/admin-guide/perf/qcom_l3_pmu.rst | 26 + Documentation/admin-guide/perf/thunderx2-pmu.rst | 44 + Documentation/admin-guide/perf/xgene-pmu.rst | 49 + Documentation/admin-guide/pm/amd-pstate.rst | 479 ++ Documentation/admin-guide/pm/cpufreq.rst | 708 ++ Documentation/admin-guide/pm/cpufreq_drivers.rst | 274 + Documentation/admin-guide/pm/cpuidle.rst | 662 ++ Documentation/admin-guide/pm/index.rst | 12 + .../admin-guide/pm/intel-speed-select.rst | 939 +++ Documentation/admin-guide/pm/intel_epb.rst | 41 + Documentation/admin-guide/pm/intel_idle.rst | 272 + Documentation/admin-guide/pm/intel_pstate.rst | 770 +++ .../pm/intel_uncore_frequency_scaling.rst | 60 + Documentation/admin-guide/pm/sleep-states.rst | 291 + Documentation/admin-guide/pm/strategies.rst | 56 + Documentation/admin-guide/pm/suspend-flows.rst | 270 + Documentation/admin-guide/pm/system-wide.rst | 11 + Documentation/admin-guide/pm/working-state.rst | 18 + Documentation/admin-guide/pnp.rst | 288 + Documentation/admin-guide/pstore-blk.rst | 234 + Documentation/admin-guide/ramoops.rst | 164 + Documentation/admin-guide/rapidio.rst | 107 + Documentation/admin-guide/ras.rst | 1219 ++++ Documentation/admin-guide/reporting-issues.rst | 1764 +++++ .../admin-guide/reporting-regressions.rst | 451 ++ Documentation/admin-guide/rtc.rst | 140 + Documentation/admin-guide/security-bugs.rst | 93 + Documentation/admin-guide/serial-console.rst | 115 + Documentation/admin-guide/spkguide.txt | 1620 +++++ Documentation/admin-guide/svga.rst | 250 + .../admin-guide/syscall-user-dispatch.rst | 90 + Documentation/admin-guide/sysctl/abi.rst | 34 + Documentation/admin-guide/sysctl/fs.rst | 384 ++ Documentation/admin-guide/sysctl/index.rst | 98 + Documentation/admin-guide/sysctl/kernel.rst | 1596 +++++ Documentation/admin-guide/sysctl/net.rst | 499 ++ Documentation/admin-guide/sysctl/sunrpc.rst | 25 + Documentation/admin-guide/sysctl/user.rst | 84 + Documentation/admin-guide/sysctl/vm.rst | 1046 +++ Documentation/admin-guide/sysfs-rules.rst | 192 + Documentation/admin-guide/sysrq.rst | 294 + Documentation/admin-guide/tainted-kernels.rst | 184 + Documentation/admin-guide/thunderbolt.rst | 336 + Documentation/admin-guide/ufs.rst | 68 + Documentation/admin-guide/unicode.rst | 189 + Documentation/admin-guide/vga-softcursor.rst | 62 + Documentation/admin-guide/video-output.rst | 34 + Documentation/admin-guide/xfs.rst | 543 ++ 373 files changed, 86032 insertions(+) create mode 100644 Documentation/admin-guide/LSM/LoadPin.rst create mode 100644 Documentation/admin-guide/LSM/SELinux.rst create mode 100644 Documentation/admin-guide/LSM/SafeSetID.rst create mode 100644 Documentation/admin-guide/LSM/Smack.rst create mode 100644 Documentation/admin-guide/LSM/Yama.rst create mode 100644 Documentation/admin-guide/LSM/apparmor.rst create mode 100644 Documentation/admin-guide/LSM/index.rst create mode 100644 Documentation/admin-guide/LSM/tomoyo.rst create mode 100644 Documentation/admin-guide/README.rst create mode 100644 Documentation/admin-guide/abi-obsolete.rst create mode 100644 Documentation/admin-guide/abi-removed.rst create mode 100644 Documentation/admin-guide/abi-stable.rst create mode 100644 Documentation/admin-guide/abi-testing.rst create mode 100644 Documentation/admin-guide/abi.rst create mode 100644 Documentation/admin-guide/acpi/cppc_sysfs.rst create mode 100644 Documentation/admin-guide/acpi/fan_performance_states.rst create mode 100644 Documentation/admin-guide/acpi/index.rst create mode 100644 Documentation/admin-guide/acpi/initrd_table_override.rst create mode 100644 Documentation/admin-guide/acpi/ssdt-overlays.rst create mode 100644 Documentation/admin-guide/aoe/aoe.rst create mode 100644 Documentation/admin-guide/aoe/autoload.sh create mode 100644 Documentation/admin-guide/aoe/examples.rst create mode 100644 Documentation/admin-guide/aoe/index.rst create mode 100644 Documentation/admin-guide/aoe/status.sh create mode 100644 Documentation/admin-guide/aoe/todo.rst create mode 100644 Documentation/admin-guide/aoe/udev-install.sh create mode 100644 Documentation/admin-guide/aoe/udev.txt create mode 100644 Documentation/admin-guide/auxdisplay/cfag12864b.rst create mode 100644 Documentation/admin-guide/auxdisplay/index.rst create mode 100644 Documentation/admin-guide/auxdisplay/ks0108.rst create mode 100644 Documentation/admin-guide/bcache.rst create mode 100644 Documentation/admin-guide/binderfs.rst create mode 100644 Documentation/admin-guide/binfmt-misc.rst create mode 100644 Documentation/admin-guide/blockdev/drbd/DRBD-8.3-data-packets.svg create mode 100644 Documentation/admin-guide/blockdev/drbd/DRBD-data-packets.svg create mode 100644 Documentation/admin-guide/blockdev/drbd/conn-states-8.dot create mode 100644 Documentation/admin-guide/blockdev/drbd/data-structure-v9.rst create mode 100644 Documentation/admin-guide/blockdev/drbd/disk-states-8.dot create mode 100644 Documentation/admin-guide/blockdev/drbd/drbd-connection-state-overview.dot create mode 100644 Documentation/admin-guide/blockdev/drbd/figures.rst create mode 100644 Documentation/admin-guide/blockdev/drbd/index.rst create mode 100644 Documentation/admin-guide/blockdev/drbd/peer-states-8.dot create mode 100644 Documentation/admin-guide/blockdev/floppy.rst create mode 100644 Documentation/admin-guide/blockdev/index.rst create mode 100644 Documentation/admin-guide/blockdev/nbd.rst create mode 100644 Documentation/admin-guide/blockdev/paride.rst create mode 100644 Documentation/admin-guide/blockdev/ramdisk.rst create mode 100644 Documentation/admin-guide/blockdev/zram.rst create mode 100644 Documentation/admin-guide/bootconfig.rst create mode 100644 Documentation/admin-guide/braille-console.rst create mode 100644 Documentation/admin-guide/btmrvl.rst create mode 100644 Documentation/admin-guide/bug-bisect.rst create mode 100644 Documentation/admin-guide/bug-hunting.rst create mode 100644 Documentation/admin-guide/cgroup-v1/blkio-controller.rst create mode 100644 Documentation/admin-guide/cgroup-v1/cgroups.rst create mode 100644 Documentation/admin-guide/cgroup-v1/cpuacct.rst create mode 100644 Documentation/admin-guide/cgroup-v1/cpusets.rst create mode 100644 Documentation/admin-guide/cgroup-v1/devices.rst create mode 100644 Documentation/admin-guide/cgroup-v1/freezer-subsystem.rst create mode 100644 Documentation/admin-guide/cgroup-v1/hugetlb.rst create mode 100644 Documentation/admin-guide/cgroup-v1/index.rst create mode 100644 Documentation/admin-guide/cgroup-v1/memcg_test.rst create mode 100644 Documentation/admin-guide/cgroup-v1/memory.rst create mode 100644 Documentation/admin-guide/cgroup-v1/misc.rst create mode 100644 Documentation/admin-guide/cgroup-v1/net_cls.rst create mode 100644 Documentation/admin-guide/cgroup-v1/net_prio.rst create mode 100644 Documentation/admin-guide/cgroup-v1/pids.rst create mode 100644 Documentation/admin-guide/cgroup-v1/rdma.rst create mode 100644 Documentation/admin-guide/cgroup-v2.rst create mode 100644 Documentation/admin-guide/cifs/authors.rst create mode 100644 Documentation/admin-guide/cifs/changes.rst create mode 100644 Documentation/admin-guide/cifs/index.rst create mode 100644 Documentation/admin-guide/cifs/introduction.rst create mode 100644 Documentation/admin-guide/cifs/todo.rst create mode 100644 Documentation/admin-guide/cifs/usage.rst create mode 100755 Documentation/admin-guide/cifs/winucase_convert.pl create mode 100644 Documentation/admin-guide/clearing-warn-once.rst create mode 100644 Documentation/admin-guide/cpu-load.rst create mode 100644 Documentation/admin-guide/cputopology.rst create mode 100644 Documentation/admin-guide/dell_rbu.rst create mode 100644 Documentation/admin-guide/device-mapper/cache-policies.rst create mode 100644 Documentation/admin-guide/device-mapper/cache.rst create mode 100644 Documentation/admin-guide/device-mapper/delay.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-clone.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-crypt.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-dust.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-ebs.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-flakey.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-ima.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-init.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-integrity.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-io.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-log.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-queue-length.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-raid.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-service-time.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-uevent.rst create mode 100644 Documentation/admin-guide/device-mapper/dm-zoned.rst create mode 100644 Documentation/admin-guide/device-mapper/era.rst create mode 100644 Documentation/admin-guide/device-mapper/index.rst create mode 100644 Documentation/admin-guide/device-mapper/kcopyd.rst create mode 100644 Documentation/admin-guide/device-mapper/linear.rst create mode 100644 Documentation/admin-guide/device-mapper/log-writes.rst create mode 100644 Documentation/admin-guide/device-mapper/persistent-data.rst create mode 100644 Documentation/admin-guide/device-mapper/snapshot.rst create mode 100644 Documentation/admin-guide/device-mapper/statistics.rst create mode 100644 Documentation/admin-guide/device-mapper/striped.rst create mode 100644 Documentation/admin-guide/device-mapper/switch.rst create mode 100644 Documentation/admin-guide/device-mapper/thin-provisioning.rst create mode 100644 Documentation/admin-guide/device-mapper/unstriped.rst create mode 100644 Documentation/admin-guide/device-mapper/verity.rst create mode 100644 Documentation/admin-guide/device-mapper/writecache.rst create mode 100644 Documentation/admin-guide/device-mapper/zero.rst create mode 100644 Documentation/admin-guide/devices.rst create mode 100644 Documentation/admin-guide/devices.txt create mode 100644 Documentation/admin-guide/dynamic-debug-howto.rst create mode 100644 Documentation/admin-guide/edid.rst create mode 100644 Documentation/admin-guide/efi-stub.rst create mode 100644 Documentation/admin-guide/ext4.rst create mode 100644 Documentation/admin-guide/features.rst create mode 100644 Documentation/admin-guide/filesystem-monitoring.rst create mode 100644 Documentation/admin-guide/gpio/gpio-aggregator.rst create mode 100644 Documentation/admin-guide/gpio/gpio-mockup.rst create mode 100644 Documentation/admin-guide/gpio/gpio-sim.rst create mode 100644 Documentation/admin-guide/gpio/index.rst create mode 100644 Documentation/admin-guide/gpio/sysfs.rst create mode 100644 Documentation/admin-guide/highuid.rst create mode 100644 Documentation/admin-guide/hw-vuln/core-scheduling.rst create mode 100644 Documentation/admin-guide/hw-vuln/cross-thread-rsb.rst create mode 100644 Documentation/admin-guide/hw-vuln/gather_data_sampling.rst create mode 100644 Documentation/admin-guide/hw-vuln/index.rst create mode 100644 Documentation/admin-guide/hw-vuln/l1d_flush.rst create mode 100644 Documentation/admin-guide/hw-vuln/l1tf.rst create mode 100644 Documentation/admin-guide/hw-vuln/mds.rst create mode 100644 Documentation/admin-guide/hw-vuln/multihit.rst create mode 100644 Documentation/admin-guide/hw-vuln/processor_mmio_stale_data.rst create mode 100644 Documentation/admin-guide/hw-vuln/special-register-buffer-data-sampling.rst create mode 100644 Documentation/admin-guide/hw-vuln/spectre.rst create mode 100644 Documentation/admin-guide/hw-vuln/srso.rst create mode 100644 Documentation/admin-guide/hw-vuln/tsx_async_abort.rst create mode 100644 Documentation/admin-guide/hw_random.rst create mode 100644 Documentation/admin-guide/index.rst create mode 100644 Documentation/admin-guide/init.rst create mode 100644 Documentation/admin-guide/initrd.rst create mode 100644 Documentation/admin-guide/iostats.rst create mode 100644 Documentation/admin-guide/java.rst create mode 100644 Documentation/admin-guide/jfs.rst create mode 100644 Documentation/admin-guide/kdump/gdbmacros.txt create mode 100644 Documentation/admin-guide/kdump/index.rst create mode 100644 Documentation/admin-guide/kdump/kdump.rst create mode 100644 Documentation/admin-guide/kdump/vmcoreinfo.rst create mode 100644 Documentation/admin-guide/kernel-parameters.rst create mode 100644 Documentation/admin-guide/kernel-parameters.txt create mode 100644 Documentation/admin-guide/kernel-per-CPU-kthreads.rst create mode 100644 Documentation/admin-guide/laptops/asus-laptop.rst create mode 100644 Documentation/admin-guide/laptops/disk-shock-protection.rst create mode 100644 Documentation/admin-guide/laptops/index.rst create mode 100644 Documentation/admin-guide/laptops/laptop-mode.rst create mode 100644 Documentation/admin-guide/laptops/lg-laptop.rst create mode 100644 Documentation/admin-guide/laptops/sony-laptop.rst create mode 100644 Documentation/admin-guide/laptops/sonypi.rst create mode 100644 Documentation/admin-guide/laptops/thinkpad-acpi.rst create mode 100644 Documentation/admin-guide/laptops/toshiba_haps.rst create mode 100644 Documentation/admin-guide/lcd-panel-cgram.rst create mode 100644 Documentation/admin-guide/ldm.rst create mode 100644 Documentation/admin-guide/lockup-watchdogs.rst create mode 100644 Documentation/admin-guide/md.rst create mode 100644 Documentation/admin-guide/media/au0828-cardlist.rst create mode 100644 Documentation/admin-guide/media/avermedia.rst create mode 100644 Documentation/admin-guide/media/bt8xx.rst create mode 100644 Documentation/admin-guide/media/bttv-cardlist.rst create mode 100644 Documentation/admin-guide/media/bttv.rst create mode 100644 Documentation/admin-guide/media/building.rst create mode 100644 Documentation/admin-guide/media/cafe_ccic.rst create mode 100644 Documentation/admin-guide/media/cardlist.rst create mode 100644 Documentation/admin-guide/media/cec-drivers.rst create mode 100644 Documentation/admin-guide/media/ci.rst create mode 100644 Documentation/admin-guide/media/cpia2.rst create mode 100644 Documentation/admin-guide/media/cx18-cardlist.rst create mode 100644 Documentation/admin-guide/media/cx231xx-cardlist.rst create mode 100644 Documentation/admin-guide/media/cx23885-cardlist.rst create mode 100644 Documentation/admin-guide/media/cx88-cardlist.rst create mode 100644 Documentation/admin-guide/media/cx88.rst create mode 100644 Documentation/admin-guide/media/davinci-vpbe.rst create mode 100644 Documentation/admin-guide/media/dvb-drivers.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-a800-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-af9005-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-af9015-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-af9035-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-anysee-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-au6610-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-az6007-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-az6027-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-ce6230-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-cinergyT2-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-cxusb-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-dib0700-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-dibusb-mb-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-dibusb-mc-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-digitv-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-dtt200u-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-dtv5100-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-dvbsky-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-dw2102-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-ec168-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-gl861-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-gp8psk-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-lmedm04-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-m920x-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-mxl111sf-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-nova-t-usb2-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-opera1-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-pctv452e-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-rtl28xxu-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-technisat-usb2-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-ttusb2-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-umt-010-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-vp702x-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-vp7045-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb-usb-zd1301-cardlist.rst create mode 100644 Documentation/admin-guide/media/dvb.rst create mode 100644 Documentation/admin-guide/media/dvb_intro.rst create mode 100644 Documentation/admin-guide/media/dvb_references.rst create mode 100644 Documentation/admin-guide/media/em28xx-cardlist.rst create mode 100644 Documentation/admin-guide/media/faq.rst create mode 100644 Documentation/admin-guide/media/fimc.rst create mode 100644 Documentation/admin-guide/media/frontend-cardlist.rst create mode 100644 Documentation/admin-guide/media/gspca-cardlist.rst create mode 100644 Documentation/admin-guide/media/i2c-cardlist.rst create mode 100644 Documentation/admin-guide/media/imx.rst create mode 100644 Documentation/admin-guide/media/imx6q-sabreauto.dot create mode 100644 Documentation/admin-guide/media/imx6q-sabresd.dot create mode 100644 Documentation/admin-guide/media/imx7.rst create mode 100644 Documentation/admin-guide/media/index.rst create mode 100644 Documentation/admin-guide/media/intro.rst create mode 100644 Documentation/admin-guide/media/ipu3.rst create mode 100644 Documentation/admin-guide/media/ipu3_rcb.svg create mode 100644 Documentation/admin-guide/media/ivtv-cardlist.rst create mode 100644 Documentation/admin-guide/media/ivtv.rst create mode 100644 Documentation/admin-guide/media/lmedm04.rst create mode 100644 Documentation/admin-guide/media/meye.rst create mode 100644 Documentation/admin-guide/media/misc-cardlist.rst create mode 100644 Documentation/admin-guide/media/omap3isp.rst create mode 100644 Documentation/admin-guide/media/omap4_camera.rst create mode 100644 Documentation/admin-guide/media/opera-firmware.rst create mode 100644 Documentation/admin-guide/media/other-usb-cardlist.rst create mode 100644 Documentation/admin-guide/media/pci-cardlist.rst create mode 100644 Documentation/admin-guide/media/philips.rst create mode 100644 Documentation/admin-guide/media/platform-cardlist.rst create mode 100644 Documentation/admin-guide/media/pulse8-cec.rst create mode 100644 Documentation/admin-guide/media/qcom_camss.rst create mode 100644 Documentation/admin-guide/media/qcom_camss_8x96_graph.dot create mode 100644 Documentation/admin-guide/media/qcom_camss_graph.dot create mode 100644 Documentation/admin-guide/media/radio-cardlist.rst create mode 100644 Documentation/admin-guide/media/rcar-fdp1.rst create mode 100644 Documentation/admin-guide/media/remote-controller.rst create mode 100644 Documentation/admin-guide/media/rkisp1.dot create mode 100644 Documentation/admin-guide/media/rkisp1.rst create mode 100644 Documentation/admin-guide/media/saa7134-cardlist.rst create mode 100644 Documentation/admin-guide/media/saa7134.rst create mode 100644 Documentation/admin-guide/media/saa7164-cardlist.rst create mode 100644 Documentation/admin-guide/media/si470x.rst create mode 100644 Documentation/admin-guide/media/si4713.rst create mode 100644 Documentation/admin-guide/media/si476x.rst create mode 100644 Documentation/admin-guide/media/siano-cardlist.rst create mode 100644 Documentation/admin-guide/media/technisat.rst create mode 100644 Documentation/admin-guide/media/tm6000-cardlist.rst create mode 100644 Documentation/admin-guide/media/ttusb-dec.rst create mode 100644 Documentation/admin-guide/media/tuner-cardlist.rst create mode 100644 Documentation/admin-guide/media/usb-cardlist.rst create mode 100644 Documentation/admin-guide/media/v4l-drivers.rst create mode 100644 Documentation/admin-guide/media/vimc.dot create mode 100644 Documentation/admin-guide/media/vimc.rst create mode 100644 Documentation/admin-guide/media/vivid.rst create mode 100644 Documentation/admin-guide/media/zoran-cardlist.rst create mode 100644 Documentation/admin-guide/media/zr364xx.rst create mode 100644 Documentation/admin-guide/mm/cma_debugfs.rst create mode 100644 Documentation/admin-guide/mm/concepts.rst create mode 100644 Documentation/admin-guide/mm/damon/index.rst create mode 100644 Documentation/admin-guide/mm/damon/lru_sort.rst create mode 100644 Documentation/admin-guide/mm/damon/reclaim.rst create mode 100644 Documentation/admin-guide/mm/damon/start.rst create mode 100644 Documentation/admin-guide/mm/damon/usage.rst create mode 100644 Documentation/admin-guide/mm/hugetlbpage.rst create mode 100644 Documentation/admin-guide/mm/idle_page_tracking.rst create mode 100644 Documentation/admin-guide/mm/index.rst create mode 100644 Documentation/admin-guide/mm/ksm.rst create mode 100644 Documentation/admin-guide/mm/memory-hotplug.rst create mode 100644 Documentation/admin-guide/mm/multigen_lru.rst create mode 100644 Documentation/admin-guide/mm/nommu-mmap.rst create mode 100644 Documentation/admin-guide/mm/numa_memory_policy.rst create mode 100644 Documentation/admin-guide/mm/numaperf.rst create mode 100644 Documentation/admin-guide/mm/pagemap.rst create mode 100644 Documentation/admin-guide/mm/shrinker_debugfs.rst create mode 100644 Documentation/admin-guide/mm/soft-dirty.rst create mode 100644 Documentation/admin-guide/mm/swap_numa.rst create mode 100644 Documentation/admin-guide/mm/transhuge.rst create mode 100644 Documentation/admin-guide/mm/userfaultfd.rst create mode 100644 Documentation/admin-guide/mm/zswap.rst create mode 100644 Documentation/admin-guide/module-signing.rst create mode 100644 Documentation/admin-guide/mono.rst create mode 100644 Documentation/admin-guide/namespaces/compatibility-list.rst create mode 100644 Documentation/admin-guide/namespaces/index.rst create mode 100644 Documentation/admin-guide/namespaces/resource-control.rst create mode 100644 Documentation/admin-guide/nfs/index.rst create mode 100644 Documentation/admin-guide/nfs/nfs-client.rst create mode 100644 Documentation/admin-guide/nfs/nfs-idmapper.rst create mode 100644 Documentation/admin-guide/nfs/nfs-rdma.rst create mode 100644 Documentation/admin-guide/nfs/nfsd-admin-interfaces.rst create mode 100644 Documentation/admin-guide/nfs/nfsroot.rst create mode 100644 Documentation/admin-guide/nfs/pnfs-block-server.rst create mode 100644 Documentation/admin-guide/nfs/pnfs-scsi-server.rst create mode 100644 Documentation/admin-guide/numastat.rst create mode 100644 Documentation/admin-guide/parport.rst create mode 100644 Documentation/admin-guide/perf-security.rst create mode 100644 Documentation/admin-guide/perf/alibaba_pmu.rst create mode 100644 Documentation/admin-guide/perf/arm-ccn.rst create mode 100644 Documentation/admin-guide/perf/arm-cmn.rst create mode 100644 Documentation/admin-guide/perf/arm_dsu_pmu.rst create mode 100644 Documentation/admin-guide/perf/hisi-pcie-pmu.rst create mode 100644 Documentation/admin-guide/perf/hisi-pmu.rst create mode 100644 Documentation/admin-guide/perf/hns3-pmu.rst create mode 100644 Documentation/admin-guide/perf/imx-ddr.rst create mode 100644 Documentation/admin-guide/perf/index.rst create mode 100644 Documentation/admin-guide/perf/qcom_l2_pmu.rst create mode 100644 Documentation/admin-guide/perf/qcom_l3_pmu.rst create mode 100644 Documentation/admin-guide/perf/thunderx2-pmu.rst create mode 100644 Documentation/admin-guide/perf/xgene-pmu.rst create mode 100644 Documentation/admin-guide/pm/amd-pstate.rst create mode 100644 Documentation/admin-guide/pm/cpufreq.rst create mode 100644 Documentation/admin-guide/pm/cpufreq_drivers.rst create mode 100644 Documentation/admin-guide/pm/cpuidle.rst create mode 100644 Documentation/admin-guide/pm/index.rst create mode 100644 Documentation/admin-guide/pm/intel-speed-select.rst create mode 100644 Documentation/admin-guide/pm/intel_epb.rst create mode 100644 Documentation/admin-guide/pm/intel_idle.rst create mode 100644 Documentation/admin-guide/pm/intel_pstate.rst create mode 100644 Documentation/admin-guide/pm/intel_uncore_frequency_scaling.rst create mode 100644 Documentation/admin-guide/pm/sleep-states.rst create mode 100644 Documentation/admin-guide/pm/strategies.rst create mode 100644 Documentation/admin-guide/pm/suspend-flows.rst create mode 100644 Documentation/admin-guide/pm/system-wide.rst create mode 100644 Documentation/admin-guide/pm/working-state.rst create mode 100644 Documentation/admin-guide/pnp.rst create mode 100644 Documentation/admin-guide/pstore-blk.rst create mode 100644 Documentation/admin-guide/ramoops.rst create mode 100644 Documentation/admin-guide/rapidio.rst create mode 100644 Documentation/admin-guide/ras.rst create mode 100644 Documentation/admin-guide/reporting-issues.rst create mode 100644 Documentation/admin-guide/reporting-regressions.rst create mode 100644 Documentation/admin-guide/rtc.rst create mode 100644 Documentation/admin-guide/security-bugs.rst create mode 100644 Documentation/admin-guide/serial-console.rst create mode 100644 Documentation/admin-guide/spkguide.txt create mode 100644 Documentation/admin-guide/svga.rst create mode 100644 Documentation/admin-guide/syscall-user-dispatch.rst create mode 100644 Documentation/admin-guide/sysctl/abi.rst create mode 100644 Documentation/admin-guide/sysctl/fs.rst create mode 100644 Documentation/admin-guide/sysctl/index.rst create mode 100644 Documentation/admin-guide/sysctl/kernel.rst create mode 100644 Documentation/admin-guide/sysctl/net.rst create mode 100644 Documentation/admin-guide/sysctl/sunrpc.rst create mode 100644 Documentation/admin-guide/sysctl/user.rst create mode 100644 Documentation/admin-guide/sysctl/vm.rst create mode 100644 Documentation/admin-guide/sysfs-rules.rst create mode 100644 Documentation/admin-guide/sysrq.rst create mode 100644 Documentation/admin-guide/tainted-kernels.rst create mode 100644 Documentation/admin-guide/thunderbolt.rst create mode 100644 Documentation/admin-guide/ufs.rst create mode 100644 Documentation/admin-guide/unicode.rst create mode 100644 Documentation/admin-guide/vga-softcursor.rst create mode 100644 Documentation/admin-guide/video-output.rst create mode 100644 Documentation/admin-guide/xfs.rst (limited to 'Documentation/admin-guide') diff --git a/Documentation/admin-guide/LSM/LoadPin.rst b/Documentation/admin-guide/LSM/LoadPin.rst new file mode 100644 index 000000000..dd3ca68b5 --- /dev/null +++ b/Documentation/admin-guide/LSM/LoadPin.rst @@ -0,0 +1,31 @@ +======= +LoadPin +======= + +LoadPin is a Linux Security Module that ensures all kernel-loaded files +(modules, firmware, etc) all originate from the same filesystem, with +the expectation that such a filesystem is backed by a read-only device +such as dm-verity or CDROM. This allows systems that have a verified +and/or unchangeable filesystem to enforce module and firmware loading +restrictions without needing to sign the files individually. + +The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and +can be controlled at boot-time with the kernel command line option +"``loadpin.enforce``". By default, it is enabled, but can be disabled at +boot ("``loadpin.enforce=0``"). + +LoadPin starts pinning when it sees the first file loaded. If the +block device backing the filesystem is not read-only, a sysctl is +created to toggle pinning: ``/proc/sys/kernel/loadpin/enabled``. (Having +a mutable filesystem means pinning is mutable too, but having the +sysctl allows for easy testing on systems with a mutable filesystem.) + +It's also possible to exclude specific file types from LoadPin using kernel +command line option "``loadpin.exclude``". By default, all files are +included, but they can be excluded using kernel command line option such +as "``loadpin.exclude=kernel-module,kexec-image``". This allows to use +different mechanisms such as ``CONFIG_MODULE_SIG`` and +``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while +still use LoadPin to protect the integrity of other files kernel loads. The +full list of valid file types can be found in ``kernel_read_file_str`` +defined in ``include/linux/kernel_read_file.h``. diff --git a/Documentation/admin-guide/LSM/SELinux.rst b/Documentation/admin-guide/LSM/SELinux.rst new file mode 100644 index 000000000..520a1c2c6 --- /dev/null +++ b/Documentation/admin-guide/LSM/SELinux.rst @@ -0,0 +1,33 @@ +======= +SELinux +======= + +If you want to use SELinux, chances are you will want +to use the distro-provided policies, or install the +latest reference policy release from + + https://github.com/SELinuxProject/refpolicy + +However, if you want to install a dummy policy for +testing, you can do using ``mdp`` provided under +scripts/selinux. Note that this requires the selinux +userspace to be installed - in particular you will +need checkpolicy to compile a kernel, and setfiles and +fixfiles to label the filesystem. + + 1. Compile the kernel with selinux enabled. + 2. Type ``make`` to compile ``mdp``. + 3. Make sure that you are not running with + SELinux enabled and a real policy. If + you are, reboot with selinux disabled + before continuing. + 4. Run install_policy.sh:: + + cd scripts/selinux + sh install_policy.sh + +Step 4 will create a new dummy policy valid for your +kernel, with a single selinux user, role, and type. +It will compile the policy, will set your ``SELINUXTYPE`` to +``dummy`` in ``/etc/selinux/config``, install the compiled policy +as ``dummy``, and relabel your filesystem. diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst new file mode 100644 index 000000000..0ec34863c --- /dev/null +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -0,0 +1,118 @@ +========= +SafeSetID +========= +SafeSetID is an LSM module that gates the setid family of syscalls to restrict +UID/GID transitions from a given UID/GID to only those approved by a +system-wide allowlist. These restrictions also prohibit the given UIDs/GIDs +from obtaining auxiliary privileges associated with CAP_SET{U/G}ID, such as +allowing a user to set up user namespace UID/GID mappings. + + +Background +========== +In absence of file capabilities, processes spawned on a Linux system that need +to switch to a different user must be spawned with CAP_SETUID privileges. +CAP_SETUID is granted to programs running as root or those running as a non-root +user that have been explicitly given the CAP_SETUID runtime capability. It is +often preferable to use Linux runtime capabilities rather than file +capabilities, since using file capabilities to run a program with elevated +privileges opens up possible security holes since any user with access to the +file can exec() that program to gain the elevated privileges. + +While it is possible to implement a tree of processes by giving full +CAP_SET{U/G}ID capabilities, this is often at odds with the goals of running a +tree of processes under non-root user(s) in the first place. Specifically, +since CAP_SETUID allows changing to any user on the system, including the root +user, it is an overpowered capability for what is needed in this scenario, +especially since programs often only call setuid() to drop privileges to a +lesser-privileged user -- not elevate privileges. Unfortunately, there is no +generally feasible way in Linux to restrict the potential UIDs that a user can +switch to through setuid() beyond allowing a switch to any user on the system. +This SafeSetID LSM seeks to provide a solution for restricting setid +capabilities in such a way. + +The main use case for this LSM is to allow a non-root program to transition to +other untrusted uids without full blown CAP_SETUID capabilities. The non-root +program would still need CAP_SETUID to do any kind of transition, but the +additional restrictions imposed by this LSM would mean it is a "safer" version +of CAP_SETUID since the non-root program cannot take advantage of CAP_SETUID to +do any unapproved actions (e.g. setuid to uid 0 or create/enter new user +namespace). The higher level goal is to allow for uid-based sandboxing of system +services without having to give out CAP_SETUID all over the place just so that +non-root programs can drop to even-lesser-privileged uids. This is especially +relevant when one non-root daemon on the system should be allowed to spawn other +processes as different uids, but its undesirable to give the daemon a +basically-root-equivalent CAP_SETUID. + + +Other Approaches Considered +=========================== + +Solve this problem in userspace +------------------------------- +For candidate applications that would like to have restricted setid capabilities +as implemented in this LSM, an alternative option would be to simply take away +setid capabilities from the application completely and refactor the process +spawning semantics in the application (e.g. by using a privileged helper program +to do process spawning and UID/GID transitions). Unfortunately, there are a +number of semantics around process spawning that would be affected by this, such +as fork() calls where the program doesn't immediately call exec() after the +fork(), parent processes specifying custom environment variables or command line +args for spawned child processes, or inheritance of file handles across a +fork()/exec(). Because of this, as solution that uses a privileged helper in +userspace would likely be less appealing to incorporate into existing projects +that rely on certain process-spawning semantics in Linux. + +Use user namespaces +------------------- +Another possible approach would be to run a given process tree in its own user +namespace and give programs in the tree setid capabilities. In this way, +programs in the tree could change to any desired UID/GID in the context of their +own user namespace, and only approved UIDs/GIDs could be mapped back to the +initial system user namespace, affectively preventing privilege escalation. +Unfortunately, it is not generally feasible to use user namespaces in isolation, +without pairing them with other namespace types, which is not always an option. +Linux checks for capabilities based off of the user namespace that "owns" some +entity. For example, Linux has the notion that network namespaces are owned by +the user namespace in which they were created. A consequence of this is that +capability checks for access to a given network namespace are done by checking +whether a task has the given capability in the context of the user namespace +that owns the network namespace -- not necessarily the user namespace under +which the given task runs. Therefore spawning a process in a new user namespace +effectively prevents it from accessing the network namespace owned by the +initial namespace. This is a deal-breaker for any application that expects to +retain the CAP_NET_ADMIN capability for the purpose of adjusting network +configurations. Using user namespaces in isolation causes problems regarding +other system interactions, including use of pid namespaces and device creation. + +Use an existing LSM +------------------- +None of the other in-tree LSMs have the capability to gate setid transitions, or +even employ the security_task_fix_setuid hook at all. SELinux says of that hook: +"Since setuid only affects the current process, and since the SELinux controls +are not based on the Linux identity attributes, SELinux does not need to control +this operation." + + +Directions for use +================== +This LSM hooks the setid syscalls to make sure transitions are allowed if an +applicable restriction policy is in place. Policies are configured through +securityfs by writing to the safesetid/uid_allowlist_policy and +safesetid/gid_allowlist_policy files at the location where securityfs is +mounted. The format for adding a policy is ':' or ':', +using literal numbers, and ending with a newline character such as '123:456\n'. +Writing an empty string "" will flush the policy. Again, configuring a policy +for a UID/GID will prevent that UID/GID from obtaining auxiliary setid +privileges, such as allowing a user to set up user namespace UID/GID mappings. + +Note on GID policies and setgroups() +==================================== +In v5.9 we are adding support for limiting CAP_SETGID privileges as was done +previously for CAP_SETUID. However, for compatibility with common sandboxing +related code conventions in userspace, we currently allow arbitrary +setgroups() calls for processes with CAP_SETGID restrictions. Until we add +support in a future release for restricting setgroups() calls, these GID +policies add no meaningful security. setgroups() restrictions will be enforced +once we have the policy checking code in place, which will rely on GID policy +configuration code added in v5.9. diff --git a/Documentation/admin-guide/LSM/Smack.rst b/Documentation/admin-guide/LSM/Smack.rst new file mode 100644 index 000000000..6d44f4fdb --- /dev/null +++ b/Documentation/admin-guide/LSM/Smack.rst @@ -0,0 +1,861 @@ +===== +Smack +===== + + + "Good for you, you've decided to clean the elevator!" + - The Elevator, from Dark Star + +Smack is the Simplified Mandatory Access Control Kernel. +Smack is a kernel based implementation of mandatory access +control that includes simplicity in its primary design goals. + +Smack is not the only Mandatory Access Control scheme +available for Linux. Those new to Mandatory Access Control +are encouraged to compare Smack with the other mechanisms +available to determine which is best suited to the problem +at hand. + +Smack consists of three major components: + + - The kernel + - Basic utilities, which are helpful but not required + - Configuration data + +The kernel component of Smack is implemented as a Linux +Security Modules (LSM) module. It requires netlabel and +works best with file systems that support extended attributes, +although xattr support is not strictly required. +It is safe to run a Smack kernel under a "vanilla" distribution. + +Smack kernels use the CIPSO IP option. Some network +configurations are intolerant of IP options and can impede +access to systems that use them as Smack does. + +Smack is used in the Tizen operating system. Please +go to http://wiki.tizen.org for information about how +Smack is used in Tizen. + +The current git repository for Smack user space is: + + git://github.com/smack-team/smack.git + +This should make and install on most modern distributions. +There are five commands included in smackutil: + +chsmack: + display or set Smack extended attribute values + +smackctl: + load the Smack access rules + +smackaccess: + report if a process with one label has access + to an object with another + +These two commands are obsolete with the introduction of +the smackfs/load2 and smackfs/cipso2 interfaces. + +smackload: + properly formats data for writing to smackfs/load + +smackcipso: + properly formats data for writing to smackfs/cipso + +In keeping with the intent of Smack, configuration data is +minimal and not strictly required. The most important +configuration step is mounting the smackfs pseudo filesystem. +If smackutil is installed the startup script will take care +of this, but it can be manually as well. + +Add this line to ``/etc/fstab``:: + + smackfs /sys/fs/smackfs smackfs defaults 0 0 + +The ``/sys/fs/smackfs`` directory is created by the kernel. + +Smack uses extended attributes (xattrs) to store labels on filesystem +objects. The attributes are stored in the extended attribute security +name space. A process must have ``CAP_MAC_ADMIN`` to change any of these +attributes. + +The extended attributes that Smack uses are: + +SMACK64 + Used to make access control decisions. In almost all cases + the label given to a new filesystem object will be the label + of the process that created it. + +SMACK64EXEC + The Smack label of a process that execs a program file with + this attribute set will run with this attribute's value. + +SMACK64MMAP + Don't allow the file to be mmapped by a process whose Smack + label does not allow all of the access permitted to a process + with the label contained in this attribute. This is a very + specific use case for shared libraries. + +SMACK64TRANSMUTE + Can only have the value "TRUE". If this attribute is present + on a directory when an object is created in the directory and + the Smack rule (more below) that permitted the write access + to the directory includes the transmute ("t") mode the object + gets the label of the directory instead of the label of the + creating process. If the object being created is a directory + the SMACK64TRANSMUTE attribute is set as well. + +SMACK64IPIN + This attribute is only available on file descriptors for sockets. + Use the Smack label in this attribute for access control + decisions on packets being delivered to this socket. + +SMACK64IPOUT + This attribute is only available on file descriptors for sockets. + Use the Smack label in this attribute for access control + decisions on packets coming from this socket. + +There are multiple ways to set a Smack label on a file:: + + # attr -S -s SMACK64 -V "value" path + # chsmack -a value path + +A process can see the Smack label it is running with by +reading ``/proc/self/attr/current``. A process with ``CAP_MAC_ADMIN`` +can set the process Smack by writing there. + +Most Smack configuration is accomplished by writing to files +in the smackfs filesystem. This pseudo-filesystem is mounted +on ``/sys/fs/smackfs``. + +access + Provided for backward compatibility. The access2 interface + is preferred and should be used instead. + This interface reports whether a subject with the specified + Smack label has a particular access to an object with a + specified Smack label. Write a fixed format access rule to + this file. The next read will indicate whether the access + would be permitted. The text will be either "1" indicating + access, or "0" indicating denial. + +access2 + This interface reports whether a subject with the specified + Smack label has a particular access to an object with a + specified Smack label. Write a long format access rule to + this file. The next read will indicate whether the access + would be permitted. The text will be either "1" indicating + access, or "0" indicating denial. + +ambient + This contains the Smack label applied to unlabeled network + packets. + +change-rule + This interface allows modification of existing access control rules. + The format accepted on write is:: + + "%s %s %s %s" + + where the first string is the subject label, the second the + object label, the third the access to allow and the fourth the + access to deny. The access strings may contain only the characters + "rwxat-". If a rule for a given subject and object exists it will be + modified by enabling the permissions in the third string and disabling + those in the fourth string. If there is no such rule it will be + created using the access specified in the third and the fourth strings. + +cipso + Provided for backward compatibility. The cipso2 interface + is preferred and should be used instead. + This interface allows a specific CIPSO header to be assigned + to a Smack label. The format accepted on write is:: + + "%24s%4d%4d"["%4d"]... + + The first string is a fixed Smack label. The first number is + the level to use. The second number is the number of categories. + The following numbers are the categories:: + + "level-3-cats-5-19 3 2 5 19" + +cipso2 + This interface allows a specific CIPSO header to be assigned + to a Smack label. The format accepted on write is:: + + "%s%4d%4d"["%4d"]... + + The first string is a long Smack label. The first number is + the level to use. The second number is the number of categories. + The following numbers are the categories:: + + "level-3-cats-5-19 3 2 5 19" + +direct + This contains the CIPSO level used for Smack direct label + representation in network packets. + +doi + This contains the CIPSO domain of interpretation used in + network packets. + +ipv6host + This interface allows specific IPv6 internet addresses to be + treated as single label hosts. Packets are sent to single + label hosts only from processes that have Smack write access + to the host label. All packets received from single label hosts + are given the specified label. The format accepted on write is:: + + "%h:%h:%h:%h:%h:%h:%h:%h label" or + "%h:%h:%h:%h:%h:%h:%h:%h/%d label". + + The "::" address shortcut is not supported. + If label is "-DELETE" a matched entry will be deleted. + +load + Provided for backward compatibility. The load2 interface + is preferred and should be used instead. + This interface allows access control rules in addition to + the system defined rules to be specified. The format accepted + on write is:: + + "%24s%24s%5s" + + where the first string is the subject label, the second the + object label, and the third the requested access. The access + string may contain only the characters "rwxat-", and specifies + which sort of access is allowed. The "-" is a placeholder for + permissions that are not allowed. The string "r-x--" would + specify read and execute access. Labels are limited to 23 + characters in length. + +load2 + This interface allows access control rules in addition to + the system defined rules to be specified. The format accepted + on write is:: + + "%s %s %s" + + where the first string is the subject label, the second the + object label, and the third the requested access. The access + string may contain only the characters "rwxat-", and specifies + which sort of access is allowed. The "-" is a placeholder for + permissions that are not allowed. The string "r-x--" would + specify read and execute access. + +load-self + Provided for backward compatibility. The load-self2 interface + is preferred and should be used instead. + This interface allows process specific access rules to be + defined. These rules are only consulted if access would + otherwise be permitted, and are intended to provide additional + restrictions on the process. The format is the same as for + the load interface. + +load-self2 + This interface allows process specific access rules to be + defined. These rules are only consulted if access would + otherwise be permitted, and are intended to provide additional + restrictions on the process. The format is the same as for + the load2 interface. + +logging + This contains the Smack logging state. + +mapped + This contains the CIPSO level used for Smack mapped label + representation in network packets. + +netlabel + This interface allows specific internet addresses to be + treated as single label hosts. Packets are sent to single + label hosts without CIPSO headers, but only from processes + that have Smack write access to the host label. All packets + received from single label hosts are given the specified + label. The format accepted on write is:: + + "%d.%d.%d.%d label" or "%d.%d.%d.%d/%d label". + + If the label specified is "-CIPSO" the address is treated + as a host that supports CIPSO headers. + +onlycap + This contains labels processes must have for CAP_MAC_ADMIN + and ``CAP_MAC_OVERRIDE`` to be effective. If this file is empty + these capabilities are effective at for processes with any + label. The values are set by writing the desired labels, separated + by spaces, to the file or cleared by writing "-" to the file. + +ptrace + This is used to define the current ptrace policy + + 0 - default: + this is the policy that relies on Smack access rules. + For the ``PTRACE_READ`` a subject needs to have a read access on + object. For the ``PTRACE_ATTACH`` a read-write access is required. + + 1 - exact: + this is the policy that limits ``PTRACE_ATTACH``. Attach is + only allowed when subject's and object's labels are equal. + ``PTRACE_READ`` is not affected. Can be overridden with ``CAP_SYS_PTRACE``. + + 2 - draconian: + this policy behaves like the 'exact' above with an + exception that it can't be overridden with ``CAP_SYS_PTRACE``. + +revoke-subject + Writing a Smack label here sets the access to '-' for all access + rules with that subject label. + +unconfined + If the kernel is configured with ``CONFIG_SECURITY_SMACK_BRINGUP`` + a process with ``CAP_MAC_ADMIN`` can write a label into this interface. + Thereafter, accesses that involve that label will be logged and + the access permitted if it wouldn't be otherwise. Note that this + is dangerous and can ruin the proper labeling of your system. + It should never be used in production. + +relabel-self + This interface contains a list of labels to which the process can + transition to, by writing to ``/proc/self/attr/current``. + Normally a process can change its own label to any legal value, but only + if it has ``CAP_MAC_ADMIN``. This interface allows a process without + ``CAP_MAC_ADMIN`` to relabel itself to one of labels from predefined list. + A process without ``CAP_MAC_ADMIN`` can change its label only once. When it + does, this list will be cleared. + The values are set by writing the desired labels, separated + by spaces, to the file or cleared by writing "-" to the file. + +If you are using the smackload utility +you can add access rules in ``/etc/smack/accesses``. They take the form:: + + subjectlabel objectlabel access + +access is a combination of the letters rwxatb which specify the +kind of access permitted a subject with subjectlabel on an +object with objectlabel. If there is no rule no access is allowed. + +Look for additional programs on http://schaufler-ca.com + +The Simplified Mandatory Access Control Kernel (Whitepaper) +=========================================================== + +Casey Schaufler +casey@schaufler-ca.com + +Mandatory Access Control +------------------------ + +Computer systems employ a variety of schemes to constrain how information is +shared among the people and services using the machine. Some of these schemes +allow the program or user to decide what other programs or users are allowed +access to pieces of data. These schemes are called discretionary access +control mechanisms because the access control is specified at the discretion +of the user. Other schemes do not leave the decision regarding what a user or +program can access up to users or programs. These schemes are called mandatory +access control mechanisms because you don't have a choice regarding the users +or programs that have access to pieces of data. + +Bell & LaPadula +--------------- + +From the middle of the 1980's until the turn of the century Mandatory Access +Control (MAC) was very closely associated with the Bell & LaPadula security +model, a mathematical description of the United States Department of Defense +policy for marking paper documents. MAC in this form enjoyed a following +within the Capital Beltway and Scandinavian supercomputer centers but was +often sited as failing to address general needs. + +Domain Type Enforcement +----------------------- + +Around the turn of the century Domain Type Enforcement (DTE) became popular. +This scheme organizes users, programs, and data into domains that are +protected from each other. This scheme has been widely deployed as a component +of popular Linux distributions. The administrative overhead required to +maintain this scheme and the detailed understanding of the whole system +necessary to provide a secure domain mapping leads to the scheme being +disabled or used in limited ways in the majority of cases. + +Smack +----- + +Smack is a Mandatory Access Control mechanism designed to provide useful MAC +while avoiding the pitfalls of its predecessors. The limitations of Bell & +LaPadula are addressed by providing a scheme whereby access can be controlled +according to the requirements of the system and its purpose rather than those +imposed by an arcane government policy. The complexity of Domain Type +Enforcement and avoided by defining access controls in terms of the access +modes already in use. + +Smack Terminology +----------------- + +The jargon used to talk about Smack will be familiar to those who have dealt +with other MAC systems and shouldn't be too difficult for the uninitiated to +pick up. There are four terms that are used in a specific way and that are +especially important: + + Subject: + A subject is an active entity on the computer system. + On Smack a subject is a task, which is in turn the basic unit + of execution. + + Object: + An object is a passive entity on the computer system. + On Smack files of all types, IPC, and tasks can be objects. + + Access: + Any attempt by a subject to put information into or get + information from an object is an access. + + Label: + Data that identifies the Mandatory Access Control + characteristics of a subject or an object. + +These definitions are consistent with the traditional use in the security +community. There are also some terms from Linux that are likely to crop up: + + Capability: + A task that possesses a capability has permission to + violate an aspect of the system security policy, as identified by + the specific capability. A task that possesses one or more + capabilities is a privileged task, whereas a task with no + capabilities is an unprivileged task. + + Privilege: + A task that is allowed to violate the system security + policy is said to have privilege. As of this writing a task can + have privilege either by possessing capabilities or by having an + effective user of root. + +Smack Basics +------------ + +Smack is an extension to a Linux system. It enforces additional restrictions +on what subjects can access which objects, based on the labels attached to +each of the subject and the object. + +Labels +~~~~~~ + +Smack labels are ASCII character strings. They can be up to 255 characters +long, but keeping them to twenty-three characters is recommended. +Single character labels using special characters, that being anything +other than a letter or digit, are reserved for use by the Smack development +team. Smack labels are unstructured, case sensitive, and the only operation +ever performed on them is comparison for equality. Smack labels cannot +contain unprintable characters, the "/" (slash), the "\" (backslash), the "'" +(quote) and '"' (double-quote) characters. +Smack labels cannot begin with a '-'. This is reserved for special options. + +There are some predefined labels:: + + _ Pronounced "floor", a single underscore character. + ^ Pronounced "hat", a single circumflex character. + * Pronounced "star", a single asterisk character. + ? Pronounced "huh", a single question mark character. + @ Pronounced "web", a single at sign character. + +Every task on a Smack system is assigned a label. The Smack label +of a process will usually be assigned by the system initialization +mechanism. + +Access Rules +~~~~~~~~~~~~ + +Smack uses the traditional access modes of Linux. These modes are read, +execute, write, and occasionally append. There are a few cases where the +access mode may not be obvious. These include: + + Signals: + A signal is a write operation from the subject task to + the object task. + + Internet Domain IPC: + Transmission of a packet is considered a + write operation from the source task to the destination task. + +Smack restricts access based on the label attached to a subject and the label +attached to the object it is trying to access. The rules enforced are, in +order: + + 1. Any access requested by a task labeled "*" is denied. + 2. A read or execute access requested by a task labeled "^" + is permitted. + 3. A read or execute access requested on an object labeled "_" + is permitted. + 4. Any access requested on an object labeled "*" is permitted. + 5. Any access requested by a task on an object with the same + label is permitted. + 6. Any access requested that is explicitly defined in the loaded + rule set is permitted. + 7. Any other access is denied. + +Smack Access Rules +~~~~~~~~~~~~~~~~~~ + +With the isolation provided by Smack access separation is simple. There are +many interesting cases where limited access by subjects to objects with +different labels is desired. One example is the familiar spy model of +sensitivity, where a scientist working on a highly classified project would be +able to read documents of lower classifications and anything she writes will +be "born" highly classified. To accommodate such schemes Smack includes a +mechanism for specifying rules allowing access between labels. + +Access Rule Format +~~~~~~~~~~~~~~~~~~ + +The format of an access rule is:: + + subject-label object-label access + +Where subject-label is the Smack label of the task, object-label is the Smack +label of the thing being accessed, and access is a string specifying the sort +of access allowed. The access specification is searched for letters that +describe access modes: + + a: indicates that append access should be granted. + r: indicates that read access should be granted. + w: indicates that write access should be granted. + x: indicates that execute access should be granted. + t: indicates that the rule requests transmutation. + b: indicates that the rule should be reported for bring-up. + +Uppercase values for the specification letters are allowed as well. +Access mode specifications can be in any order. Examples of acceptable rules +are:: + + TopSecret Secret rx + Secret Unclass R + Manager Game x + User HR w + Snap Crackle rwxatb + New Old rRrRr + Closed Off - + +Examples of unacceptable rules are:: + + Top Secret Secret rx + Ace Ace r + Odd spells waxbeans + +Spaces are not allowed in labels. Since a subject always has access to files +with the same label specifying a rule for that case is pointless. Only +valid letters (rwxatbRWXATB) and the dash ('-') character are allowed in +access specifications. The dash is a placeholder, so "a-r" is the same +as "ar". A lone dash is used to specify that no access should be allowed. + +Applying Access Rules +~~~~~~~~~~~~~~~~~~~~~ + +The developers of Linux rarely define new sorts of things, usually importing +schemes and concepts from other systems. Most often, the other systems are +variants of Unix. Unix has many endearing properties, but consistency of +access control models is not one of them. Smack strives to treat accesses as +uniformly as is sensible while keeping with the spirit of the underlying +mechanism. + +File system objects including files, directories, named pipes, symbolic links, +and devices require access permissions that closely match those used by mode +bit access. To open a file for reading read access is required on the file. To +search a directory requires execute access. Creating a file with write access +requires both read and write access on the containing directory. Deleting a +file requires read and write access to the file and to the containing +directory. It is possible that a user may be able to see that a file exists +but not any of its attributes by the circumstance of having read access to the +containing directory but not to the differently labeled file. This is an +artifact of the file name being data in the directory, not a part of the file. + +If a directory is marked as transmuting (SMACK64TRANSMUTE=TRUE) and the +access rule that allows a process to create an object in that directory +includes 't' access the label assigned to the new object will be that +of the directory, not the creating process. This makes it much easier +for two processes with different labels to share data without granting +access to all of their files. + +IPC objects, message queues, semaphore sets, and memory segments exist in flat +namespaces and access requests are only required to match the object in +question. + +Process objects reflect tasks on the system and the Smack label used to access +them is the same Smack label that the task would use for its own access +attempts. Sending a signal via the kill() system call is a write operation +from the signaler to the recipient. Debugging a process requires both reading +and writing. Creating a new task is an internal operation that results in two +tasks with identical Smack labels and requires no access checks. + +Sockets are data structures attached to processes and sending a packet from +one process to another requires that the sender have write access to the +receiver. The receiver is not required to have read access to the sender. + +Setting Access Rules +~~~~~~~~~~~~~~~~~~~~ + +The configuration file /etc/smack/accesses contains the rules to be set at +system startup. The contents are written to the special file +/sys/fs/smackfs/load2. Rules can be added at any time and take effect +immediately. For any pair of subject and object labels there can be only +one rule, with the most recently specified overriding any earlier +specification. + +Task Attribute +~~~~~~~~~~~~~~ + +The Smack label of a process can be read from /proc//attr/current. A +process can read its own Smack label from /proc/self/attr/current. A +privileged process can change its own Smack label by writing to +/proc/self/attr/current but not the label of another process. + +File Attribute +~~~~~~~~~~~~~~ + +The Smack label of a filesystem object is stored as an extended attribute +named SMACK64 on the file. This attribute is in the security namespace. It can +only be changed by a process with privilege. + +Privilege +~~~~~~~~~ + +A process with CAP_MAC_OVERRIDE or CAP_MAC_ADMIN is privileged. +CAP_MAC_OVERRIDE allows the process access to objects it would +be denied otherwise. CAP_MAC_ADMIN allows a process to change +Smack data, including rules and attributes. + +Smack Networking +~~~~~~~~~~~~~~~~ + +As mentioned before, Smack enforces access control on network protocol +transmissions. Every packet sent by a Smack process is tagged with its Smack +label. This is done by adding a CIPSO tag to the header of the IP packet. Each +packet received is expected to have a CIPSO tag that identifies the label and +if it lacks such a tag the network ambient label is assumed. Before the packet +is delivered a check is made to determine that a subject with the label on the +packet has write access to the receiving process and if that is not the case +the packet is dropped. + +CIPSO Configuration +~~~~~~~~~~~~~~~~~~~ + +It is normally unnecessary to specify the CIPSO configuration. The default +values used by the system handle all internal cases. Smack will compose CIPSO +label values to match the Smack labels being used without administrative +intervention. Unlabeled packets that come into the system will be given the +ambient label. + +Smack requires configuration in the case where packets from a system that is +not Smack that speaks CIPSO may be encountered. Usually this will be a Trusted +Solaris system, but there are other, less widely deployed systems out there. +CIPSO provides 3 important values, a Domain Of Interpretation (DOI), a level, +and a category set with each packet. The DOI is intended to identify a group +of systems that use compatible labeling schemes, and the DOI specified on the +Smack system must match that of the remote system or packets will be +discarded. The DOI is 3 by default. The value can be read from +/sys/fs/smackfs/doi and can be changed by writing to /sys/fs/smackfs/doi. + +The label and category set are mapped to a Smack label as defined in +/etc/smack/cipso. + +A Smack/CIPSO mapping has the form:: + + smack level [category [category]*] + +Smack does not expect the level or category sets to be related in any +particular way and does not assume or assign accesses based on them. Some +examples of mappings:: + + TopSecret 7 + TS:A,B 7 1 2 + SecBDE 5 2 4 6 + RAFTERS 7 12 26 + +The ":" and "," characters are permitted in a Smack label but have no special +meaning. + +The mapping of Smack labels to CIPSO values is defined by writing to +/sys/fs/smackfs/cipso2. + +In addition to explicit mappings Smack supports direct CIPSO mappings. One +CIPSO level is used to indicate that the category set passed in the packet is +in fact an encoding of the Smack label. The level used is 250 by default. The +value can be read from /sys/fs/smackfs/direct and changed by writing to +/sys/fs/smackfs/direct. + +Socket Attributes +~~~~~~~~~~~~~~~~~ + +There are two attributes that are associated with sockets. These attributes +can only be set by privileged tasks, but any task can read them for their own +sockets. + + SMACK64IPIN: + The Smack label of the task object. A privileged + program that will enforce policy may set this to the star label. + + SMACK64IPOUT: + The Smack label transmitted with outgoing packets. + A privileged program may set this to match the label of another + task with which it hopes to communicate. + +Smack Netlabel Exceptions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You will often find that your labeled application has to talk to the outside, +unlabeled world. To do this there's a special file /sys/fs/smackfs/netlabel +where you can add some exceptions in the form of:: + + @IP1 LABEL1 or + @IP2/MASK LABEL2 + +It means that your application will have unlabeled access to @IP1 if it has +write access on LABEL1, and access to the subnet @IP2/MASK if it has write +access on LABEL2. + +Entries in the /sys/fs/smackfs/netlabel file are matched by longest mask +first, like in classless IPv4 routing. + +A special label '@' and an option '-CIPSO' can be used there:: + + @ means Internet, any application with any label has access to it + -CIPSO means standard CIPSO networking + +If you don't know what CIPSO is and don't plan to use it, you can just do:: + + echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel + echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel + +If you use CIPSO on your 192.168.0.0/16 local network and need also unlabeled +Internet access, you can have:: + + echo 127.0.0.1 -CIPSO > /sys/fs/smackfs/netlabel + echo 192.168.0.0/16 -CIPSO > /sys/fs/smackfs/netlabel + echo 0.0.0.0/0 @ > /sys/fs/smackfs/netlabel + +Writing Applications for Smack +------------------------------ + +There are three sorts of applications that will run on a Smack system. How an +application interacts with Smack will determine what it will have to do to +work properly under Smack. + +Smack Ignorant Applications +--------------------------- + +By far the majority of applications have no reason whatever to care about the +unique properties of Smack. Since invoking a program has no impact on the +Smack label associated with the process the only concern likely to arise is +whether the process has execute access to the program. + +Smack Relevant Applications +--------------------------- + +Some programs can be improved by teaching them about Smack, but do not make +any security decisions themselves. The utility ls(1) is one example of such a +program. + +Smack Enforcing Applications +---------------------------- + +These are special programs that not only know about Smack, but participate in +the enforcement of system policy. In most cases these are the programs that +set up user sessions. There are also network services that provide information +to processes running with various labels. + +File System Interfaces +---------------------- + +Smack maintains labels on file system objects using extended attributes. The +Smack label of a file, directory, or other file system object can be obtained +using getxattr(2):: + + len = getxattr("/", "security.SMACK64", value, sizeof (value)); + +will put the Smack label of the root directory into value. A privileged +process can set the Smack label of a file system object with setxattr(2):: + + len = strlen("Rubble"); + rc = setxattr("/foo", "security.SMACK64", "Rubble", len, 0); + +will set the Smack label of /foo to "Rubble" if the program has appropriate +privilege. + +Socket Interfaces +----------------- + +The socket attributes can be read using fgetxattr(2). + +A privileged process can set the Smack label of outgoing packets with +fsetxattr(2):: + + len = strlen("Rubble"); + rc = fsetxattr(fd, "security.SMACK64IPOUT", "Rubble", len, 0); + +will set the Smack label "Rubble" on packets going out from the socket if the +program has appropriate privilege:: + + rc = fsetxattr(fd, "security.SMACK64IPIN, "*", strlen("*"), 0); + +will set the Smack label "*" as the object label against which incoming +packets will be checked if the program has appropriate privilege. + +Administration +-------------- + +Smack supports some mount options: + + smackfsdef=label: + specifies the label to give files that lack + the Smack label extended attribute. + + smackfsroot=label: + specifies the label to assign the root of the + file system if it lacks the Smack extended attribute. + + smackfshat=label: + specifies a label that must have read access to + all labels set on the filesystem. Not yet enforced. + + smackfsfloor=label: + specifies a label to which all labels set on the + filesystem must have read access. Not yet enforced. + + smackfstransmute=label: + behaves exactly like smackfsroot except that it also + sets the transmute flag on the root of the mount + +These mount options apply to all file system types. + +Smack auditing +-------------- + +If you want Smack auditing of security events, you need to set CONFIG_AUDIT +in your kernel configuration. +By default, all denied events will be audited. You can change this behavior by +writing a single character to the /sys/fs/smackfs/logging file:: + + 0 : no logging + 1 : log denied (default) + 2 : log accepted + 3 : log denied & accepted + +Events are logged as 'key=value' pairs, for each event you at least will get +the subject, the object, the rights requested, the action, the kernel function +that triggered the event, plus other pairs depending on the type of event +audited. + +Bringup Mode +------------ + +Bringup mode provides logging features that can make application +configuration and system bringup easier. Configure the kernel with +CONFIG_SECURITY_SMACK_BRINGUP to enable these features. When bringup +mode is enabled accesses that succeed due to rules marked with the "b" +access mode will logged. When a new label is introduced for processes +rules can be added aggressively, marked with the "b". The logging allows +tracking of which rules actual get used for that label. + +Another feature of bringup mode is the "unconfined" option. Writing +a label to /sys/fs/smackfs/unconfined makes subjects with that label +able to access any object, and objects with that label accessible to +all subjects. Any access that is granted because a label is unconfined +is logged. This feature is dangerous, as files and directories may +be created in places they couldn't if the policy were being enforced. diff --git a/Documentation/admin-guide/LSM/Yama.rst b/Documentation/admin-guide/LSM/Yama.rst new file mode 100644 index 000000000..d9cd937eb --- /dev/null +++ b/Documentation/admin-guide/LSM/Yama.rst @@ -0,0 +1,75 @@ +==== +Yama +==== + +Yama is a Linux Security Module that collects system-wide DAC security +protections that are not handled by the core kernel itself. This is +selectable at build-time with ``CONFIG_SECURITY_YAMA``, and can be controlled +at run-time through sysctls in ``/proc/sys/kernel/yama``: + +ptrace_scope +============ + +As Linux grows in popularity, it will become a larger target for +malware. One particularly troubling weakness of the Linux process +interfaces is that a single user is able to examine the memory and +running state of any of their processes. For example, if one application +(e.g. Pidgin) was compromised, it would be possible for an attacker to +attach to other running processes (e.g. Firefox, SSH sessions, GPG agent, +etc) to extract additional credentials and continue to expand the scope +of their attack without resorting to user-assisted phishing. + +This is not a theoretical problem. `SSH session hijacking +`_ +and `arbitrary code injection +`_ attacks already +exist and remain possible if ptrace is allowed to operate as before. +Since ptrace is not commonly used by non-developers and non-admins, system +builders should be allowed the option to disable this debugging system. + +For a solution, some applications use ``prctl(PR_SET_DUMPABLE, ...)`` to +specifically disallow such ptrace attachment (e.g. ssh-agent), but many +do not. A more general solution is to only allow ptrace directly from a +parent to a child process (i.e. direct "gdb EXE" and "strace EXE" still +work), or with ``CAP_SYS_PTRACE`` (i.e. "gdb --pid=PID", and "strace -p PID" +still work as root). + +In mode 1, software that has defined application-specific relationships +between a debugging process and its inferior (crash handlers, etc), +``prctl(PR_SET_PTRACER, pid, ...)`` can be used. An inferior can declare which +other process (and its descendants) are allowed to call ``PTRACE_ATTACH`` +against it. Only one such declared debugging process can exists for +each inferior at a time. For example, this is used by KDE, Chromium, and +Firefox's crash handlers, and by Wine for allowing only Wine processes +to ptrace each other. If a process wishes to entirely disable these ptrace +restrictions, it can call ``prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY, ...)`` +so that any otherwise allowed process (even those in external pid namespaces) +may attach. + +The sysctl settings (writable only with ``CAP_SYS_PTRACE``) are: + +0 - classic ptrace permissions: + a process can ``PTRACE_ATTACH`` to any other + process running under the same uid, as long as it is dumpable (i.e. + did not transition uids, start privileged, or have called + ``prctl(PR_SET_DUMPABLE...)`` already). Similarly, ``PTRACE_TRACEME`` is + unchanged. + +1 - restricted ptrace: + a process must have a predefined relationship + with the inferior it wants to call ``PTRACE_ATTACH`` on. By default, + this relationship is that of only its descendants when the above + classic criteria is also met. To change the relationship, an + inferior can call ``prctl(PR_SET_PTRACER, debugger, ...)`` to declare + an allowed debugger PID to call ``PTRACE_ATTACH`` on the inferior. + Using ``PTRACE_TRACEME`` is unchanged. + +2 - admin-only attach: + only processes with ``CAP_SYS_PTRACE`` may use ptrace, either with + ``PTRACE_ATTACH`` or through children calling ``PTRACE_TRACEME``. + +3 - no attach: + no processes may use ptrace with ``PTRACE_ATTACH`` nor via + ``PTRACE_TRACEME``. Once set, this sysctl value cannot be changed. + +The original children-only logic was based on the restrictions in grsecurity. diff --git a/Documentation/admin-guide/LSM/apparmor.rst b/Documentation/admin-guide/LSM/apparmor.rst new file mode 100644 index 000000000..6cf81bbd7 --- /dev/null +++ b/Documentation/admin-guide/LSM/apparmor.rst @@ -0,0 +1,51 @@ +======== +AppArmor +======== + +What is AppArmor? +================= + +AppArmor is MAC style security extension for the Linux kernel. It implements +a task centered policy, with task "profiles" being created and loaded +from user space. Tasks on the system that do not have a profile defined for +them run in an unconfined state which is equivalent to standard Linux DAC +permissions. + +How to enable/disable +===================== + +set ``CONFIG_SECURITY_APPARMOR=y`` + +If AppArmor should be selected as the default security module then set:: + + CONFIG_DEFAULT_SECURITY="apparmor" + CONFIG_SECURITY_APPARMOR_BOOTPARAM_VALUE=1 + +Build the kernel + +If AppArmor is not the default security module it can be enabled by passing +``security=apparmor`` on the kernel's command line. + +If AppArmor is the default security module it can be disabled by passing +``apparmor=0, security=XXXX`` (where ``XXXX`` is valid security module), on the +kernel's command line. + +For AppArmor to enforce any restrictions beyond standard Linux DAC permissions +policy must be loaded into the kernel from user space (see the Documentation +and tools links). + +Documentation +============= + +Documentation can be found on the wiki, linked below. + +Links +===== + +Mailing List - apparmor@lists.ubuntu.com + +Wiki - http://wiki.apparmor.net + +User space tools - https://gitlab.com/apparmor + +Kernel module - git://git.kernel.org/pub/scm/linux/kernel/git/jj/linux-apparmor diff --git a/Documentation/admin-guide/LSM/index.rst b/Documentation/admin-guide/LSM/index.rst new file mode 100644 index 000000000..a6ba95fba --- /dev/null +++ b/Documentation/admin-guide/LSM/index.rst @@ -0,0 +1,49 @@ +=========================== +Linux Security Module Usage +=========================== + +The Linux Security Module (LSM) framework provides a mechanism for +various security checks to be hooked by new kernel extensions. The name +"module" is a bit of a misnomer since these extensions are not actually +loadable kernel modules. Instead, they are selectable at build-time via +CONFIG_DEFAULT_SECURITY and can be overridden at boot-time via the +``"security=..."`` kernel command line argument, in the case where multiple +LSMs were built into a given kernel. + +The primary users of the LSM interface are Mandatory Access Control +(MAC) extensions which provide a comprehensive security policy. Examples +include SELinux, Smack, Tomoyo, and AppArmor. In addition to the larger +MAC extensions, other extensions can be built using the LSM to provide +specific changes to system operation when these tweaks are not available +in the core functionality of Linux itself. + +The Linux capabilities modules will always be included. This may be +followed by any number of "minor" modules and at most one "major" module. +For more details on capabilities, see ``capabilities(7)`` in the Linux +man-pages project. + +A list of the active security modules can be found by reading +``/sys/kernel/security/lsm``. This is a comma separated list, and +will always include the capability module. The list reflects the +order in which checks are made. The capability module will always +be first, followed by any "minor" modules (e.g. Yama) and then +the one "major" module (e.g. SELinux) if there is one configured. + +Process attributes associated with "major" security modules should +be accessed and maintained using the special files in ``/proc/.../attr``. +A security module may maintain a module specific subdirectory there, +named after the module. ``/proc/.../attr/smack`` is provided by the Smack +security module and contains all its special files. The files directly +in ``/proc/.../attr`` remain as legacy interfaces for modules that provide +subdirectories. + +.. toctree:: + :maxdepth: 1 + + apparmor + LoadPin + SELinux + Smack + tomoyo + Yama + SafeSetID diff --git a/Documentation/admin-guide/LSM/tomoyo.rst b/Documentation/admin-guide/LSM/tomoyo.rst new file mode 100644 index 000000000..4bc9c2b4d --- /dev/null +++ b/Documentation/admin-guide/LSM/tomoyo.rst @@ -0,0 +1,65 @@ +====== +TOMOYO +====== + +What is TOMOYO? +=============== + +TOMOYO is a name-based MAC extension (LSM module) for the Linux kernel. + +LiveCD-based tutorials are available at + +http://tomoyo.sourceforge.jp/1.8/ubuntu12.04-live.html +http://tomoyo.sourceforge.jp/1.8/centos6-live.html + +Though these tutorials use non-LSM version of TOMOYO, they are useful for you +to know what TOMOYO is. + +How to enable TOMOYO? +===================== + +Build the kernel with ``CONFIG_SECURITY_TOMOYO=y`` and pass ``security=tomoyo`` on +kernel's command line. + +Please see http://tomoyo.osdn.jp/2.5/ for details. + +Where is documentation? +======================= + +User <-> Kernel interface documentation is available at +https://tomoyo.osdn.jp/2.5/policy-specification/index.html . + +Materials we prepared for seminars and symposiums are available at +https://osdn.jp/projects/tomoyo/docs/?category_id=532&language_id=1 . +Below lists are chosen from three aspects. + +What is TOMOYO? + TOMOYO Linux Overview + https://osdn.jp/projects/tomoyo/docs/lca2009-takeda.pdf + TOMOYO Linux: pragmatic and manageable security for Linux + https://osdn.jp/projects/tomoyo/docs/freedomhectaipei-tomoyo.pdf + TOMOYO Linux: A Practical Method to Understand and Protect Your Own Linux Box + https://osdn.jp/projects/tomoyo/docs/PacSec2007-en-no-demo.pdf + +What can TOMOYO do? + Deep inside TOMOYO Linux + https://osdn.jp/projects/tomoyo/docs/lca2009-kumaneko.pdf + The role of "pathname based access control" in security. + https://osdn.jp/projects/tomoyo/docs/lfj2008-bof.pdf + +History of TOMOYO? + Realities of Mainlining + https://osdn.jp/projects/tomoyo/docs/lfj2008.pdf + +What is future plan? +==================== + +We believe that inode based security and name based security are complementary +and both should be used together. But unfortunately, so far, we cannot enable +multiple LSM modules at the same time. We feel sorry that you have to give up +SELinux/SMACK/AppArmor etc. when you want to use TOMOYO. + +We hope that LSM becomes stackable in future. Meanwhile, you can use non-LSM +version of TOMOYO, available at http://tomoyo.osdn.jp/1.8/ . +LSM version of TOMOYO is a subset of non-LSM version of TOMOYO. We are planning +to port non-LSM version's functionalities to LSM versions. diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst new file mode 100644 index 000000000..9a969c015 --- /dev/null +++ b/Documentation/admin-guide/README.rst @@ -0,0 +1,339 @@ +.. _readme: + +Linux kernel release 6.x +============================================= + +These are the release notes for Linux version 6. Read them carefully, +as they tell you what this is all about, explain how to install the +kernel, and what to do if something goes wrong. + +What is Linux? +-------------- + + Linux is a clone of the operating system Unix, written from scratch by + Linus Torvalds with assistance from a loosely-knit team of hackers across + the Net. It aims towards POSIX and Single UNIX Specification compliance. + + It has all the features you would expect in a modern fully-fledged Unix, + including true multitasking, virtual memory, shared libraries, demand + loading, shared copy-on-write executables, proper memory management, + and multistack networking including IPv4 and IPv6. + + It is distributed under the GNU General Public License v2 - see the + accompanying COPYING file for more details. + +On what hardware does it run? +----------------------------- + + Although originally developed first for 32-bit x86-based PCs (386 or higher), + today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and + UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, + IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64 Xtensa, and + ARC architectures. + + Linux is easily portable to most general-purpose 32- or 64-bit architectures + as long as they have a paged memory management unit (PMMU) and a port of the + GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has + also been ported to a number of architectures without a PMMU, although + functionality is then obviously somewhat limited. + Linux has also been ported to itself. You can now run the kernel as a + userspace application - this is called UserMode Linux (UML). + +Documentation +------------- + + - There is a lot of documentation available both in electronic form on + the Internet and in books, both Linux-specific and pertaining to + general UNIX questions. I'd recommend looking into the documentation + subdirectories on any Linux FTP site for the LDP (Linux Documentation + Project) books. This README is not meant to be documentation on the + system: there are much better sources available. + + - There are various README files in the Documentation/ subdirectory: + these typically contain kernel-specific installation notes for some + drivers for example. Please read the + :ref:`Documentation/process/changes.rst ` file, as it + contains information about the problems, which may result by upgrading + your kernel. + +Installing the kernel source +---------------------------- + + - If you install the full sources, put the kernel tarball in a + directory where you have permissions (e.g. your home directory) and + unpack it:: + + xz -cd linux-6.x.tar.xz | tar xvf - + + Replace "X" with the version number of the latest kernel. + + Do NOT use the /usr/src/linux area! This area has a (usually + incomplete) set of kernel headers that are used by the library header + files. They should match the library, and not get messed up by + whatever the kernel-du-jour happens to be. + + - You can also upgrade between 6.x releases by patching. Patches are + distributed in the xz format. To install by patching, get all the + newer patch files, enter the top level directory of the kernel source + (linux-6.x) and execute:: + + xz -cd ../patch-6.x.xz | patch -p1 + + Replace "x" for all versions bigger than the version "x" of your current + source tree, **in_order**, and you should be ok. You may want to remove + the backup files (some-file-name~ or some-file-name.orig), and make sure + that there are no failed patches (some-file-name# or some-file-name.rej). + If there are, either you or I have made a mistake. + + Unlike patches for the 6.x kernels, patches for the 6.x.y kernels + (also known as the -stable kernels) are not incremental but instead apply + directly to the base 6.x kernel. For example, if your base kernel is 6.0 + and you want to apply the 6.0.3 patch, you must not first apply the 6.0.1 + and 6.0.2 patches. Similarly, if you are running kernel version 6.0.2 and + want to jump to 6.0.3, you must first reverse the 6.0.2 patch (that is, + patch -R) **before** applying the 6.0.3 patch. You can read more on this in + :ref:`Documentation/process/applying-patches.rst `. + + Alternatively, the script patch-kernel can be used to automate this + process. It determines the current kernel version and applies any + patches found:: + + linux/scripts/patch-kernel linux + + The first argument in the command above is the location of the + kernel source. Patches are applied from the current directory, but + an alternative directory can be specified as the second argument. + + - Make sure you have no stale .o files and dependencies lying around:: + + cd linux + make mrproper + + You should now have the sources correctly installed. + +Software requirements +--------------------- + + Compiling and running the 6.x kernels requires up-to-date + versions of various software packages. Consult + :ref:`Documentation/process/changes.rst ` for the minimum version numbers + required and how to get updates for these packages. Beware that using + excessively old versions of these packages can cause indirect + errors that are very difficult to track down, so don't assume that + you can just update packages when obvious problems arise during + build or operation. + +Build directory for the kernel +------------------------------ + + When compiling the kernel, all output files will per default be + stored together with the kernel source code. + Using the option ``make O=output/dir`` allows you to specify an alternate + place for the output files (including .config). + Example:: + + kernel source code: /usr/src/linux-6.x + build directory: /home/name/build/kernel + + To configure and build the kernel, use:: + + cd /usr/src/linux-6.x + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + Please note: If the ``O=output/dir`` option is used, then it must be + used for all invocations of make. + +Configuring the kernel +---------------------- + + Do not skip this step even if you are only upgrading one minor + version. New configuration options are added in each release, and + odd problems will turn up if the configuration files are not set up + as expected. If you want to carry your existing configuration to a + new version with minimal work, use ``make oldconfig``, which will + only ask you for the answers to new questions. + + - Alternative configuration commands are:: + + "make config" Plain text interface. + + "make menuconfig" Text based color menus, radiolists & dialogs. + + "make nconfig" Enhanced text based color menus. + + "make xconfig" Qt based configuration tool. + + "make gconfig" GTK+ based configuration tool. + + "make oldconfig" Default all questions based on the contents of + your existing ./.config file and asking about + new config symbols. + + "make olddefconfig" + Like above, but sets new symbols to their default + values without prompting. + + "make defconfig" Create a ./.config file by using the default + symbol values from either arch/$ARCH/defconfig + or arch/$ARCH/configs/${PLATFORM}_defconfig, + depending on the architecture. + + "make ${PLATFORM}_defconfig" + Create a ./.config file by using the default + symbol values from + arch/$ARCH/configs/${PLATFORM}_defconfig. + Use "make help" to get a list of all available + platforms of your architecture. + + "make allyesconfig" + Create a ./.config file by setting symbol + values to 'y' as much as possible. + + "make allmodconfig" + Create a ./.config file by setting symbol + values to 'm' as much as possible. + + "make allnoconfig" Create a ./.config file by setting symbol + values to 'n' as much as possible. + + "make randconfig" Create a ./.config file by setting symbol + values to random values. + + "make localmodconfig" Create a config based on current config and + loaded modules (lsmod). Disables any module + option that is not needed for the loaded modules. + + To create a localmodconfig for another machine, + store the lsmod of that machine into a file + and pass it in as a LSMOD parameter. + + Also, you can preserve modules in certain folders + or kconfig files by specifying their paths in + parameter LMC_KEEP. + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod \ + LMC_KEEP="drivers/usb:drivers/gpu:fs" \ + localmodconfig + + The above also works when cross compiling. + + "make localyesconfig" Similar to localmodconfig, except it will convert + all module options to built in (=y) options. You can + also preserve modules by LMC_KEEP. + + "make kvm_guest.config" Enable additional options for kvm guest kernel + support. + + "make xen.config" Enable additional options for xen dom0 guest kernel + support. + + "make tinyconfig" Configure the tiniest possible kernel. + + You can find more information on using the Linux kernel config tools + in Documentation/kbuild/kconfig.rst. + + - NOTES on ``make config``: + + - Having unnecessary drivers will make the kernel bigger, and can + under some circumstances lead to problems: probing for a + nonexistent controller card may confuse your other controllers. + + - A kernel with math-emulation compiled in will still use the + coprocessor if one is present: the math emulation will just + never get used in that case. The kernel will be slightly larger, + but will work on different machines regardless of whether they + have a math coprocessor or not. + + - The "kernel hacking" configuration details usually result in a + bigger or slower kernel (or both), and can even make the kernel + less stable by configuring some routines to actively try to + break bad code to find kernel problems (kmalloc()). Thus you + should probably answer 'n' to the questions for "development", + "experimental", or "debugging" features. + +Compiling the kernel +-------------------- + + - Make sure you have at least gcc 5.1 available. + For more information, refer to :ref:`Documentation/process/changes.rst `. + + - Do a ``make`` to create a compressed kernel image. It is also + possible to do ``make install`` if you have lilo installed to suit the + kernel makefiles, but you may want to check your particular lilo setup first. + + To do the actual install, you have to be root, but none of the normal + build should require that. Don't take the name of root in vain. + + - If you configured any of the parts of the kernel as ``modules``, you + will also have to do ``make modules_install``. + + - Verbose kernel compile/build output: + + Normally, the kernel build system runs in a fairly quiet mode (but not + totally silent). However, sometimes you or other kernel developers need + to see compile, link, or other commands exactly as they are executed. + For this, use "verbose" build mode. This is done by passing + ``V=1`` to the ``make`` command, e.g.:: + + make V=1 all + + To have the build system also tell the reason for the rebuild of each + target, use ``V=2``. The default is ``V=0``. + + - Keep a backup kernel handy in case something goes wrong. This is + especially true for the development releases, since each new release + contains new code which has not been debugged. Make sure you keep a + backup of the modules corresponding to that kernel, as well. If you + are installing a new kernel with the same version number as your + working kernel, make a backup of your modules directory before you + do a ``make modules_install``. + + Alternatively, before compiling, use the kernel config option + "LOCALVERSION" to append a unique suffix to the regular kernel version. + LOCALVERSION can be set in the "General Setup" menu. + + - In order to boot your new kernel, you'll need to copy the kernel + image (e.g. .../linux/arch/x86/boot/bzImage after compilation) + to the place where your regular bootable kernel is found. + + - Booting a kernel directly from a floppy without the assistance of a + bootloader such as LILO, is no longer supported. + + If you boot Linux from the hard drive, chances are you use LILO, which + uses the kernel image as specified in the file /etc/lilo.conf. The + kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or + /boot/bzImage. To use the new kernel, save a copy of the old image + and copy the new image over the old one. Then, you MUST RERUN LILO + to update the loading map! If you don't, you won't be able to boot + the new kernel image. + + Reinstalling LILO is usually a matter of running /sbin/lilo. + You may wish to edit /etc/lilo.conf to specify an entry for your + old kernel image (say, /vmlinux.old) in case the new one does not + work. See the LILO docs for more information. + + After reinstalling LILO, you should be all set. Shutdown the system, + reboot, and enjoy! + + If you ever need to change the default root device, video mode, + etc. in the kernel image, use your bootloader's boot options + where appropriate. No need to recompile the kernel to change + these parameters. + + - Reboot with the new kernel and enjoy. + +If something goes wrong +----------------------- + +If you have problems that seem to be due to kernel bugs, please follow the +instructions at 'Documentation/admin-guide/reporting-issues.rst'. + +Hints on understanding kernel bug reports are in +'Documentation/admin-guide/bug-hunting.rst'. More on debugging the kernel +with gdb is in 'Documentation/dev-tools/gdb-kernel-debugging.rst' and +'Documentation/dev-tools/kgdb.rst'. diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst new file mode 100644 index 000000000..594e697aa --- /dev/null +++ b/Documentation/admin-guide/abi-obsolete.rst @@ -0,0 +1,11 @@ +ABI obsolete symbols +==================== + +Documents interfaces that are still remaining in the kernel, but are +marked to be removed at some later point in time. + +The description of the interface will document the reason why it is +obsolete and when it can be expected to be removed. + +.. kernel-abi:: ABI/obsolete + :rst: diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst new file mode 100644 index 000000000..f9e000c81 --- /dev/null +++ b/Documentation/admin-guide/abi-removed.rst @@ -0,0 +1,5 @@ +ABI removed symbols +=================== + +.. kernel-abi:: ABI/removed + :rst: diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst new file mode 100644 index 000000000..fc3361d84 --- /dev/null +++ b/Documentation/admin-guide/abi-stable.rst @@ -0,0 +1,14 @@ +ABI stable symbols +================== + +Documents the interfaces that the developer has defined to be stable. + +Userspace programs are free to use these interfaces with no +restrictions, and backward compatibility for them will be guaranteed +for at least 2 years. + +Most interfaces (like syscalls) are expected to never change and always +be available. + +.. kernel-abi:: ABI/stable + :rst: diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst new file mode 100644 index 000000000..19767926b --- /dev/null +++ b/Documentation/admin-guide/abi-testing.rst @@ -0,0 +1,20 @@ +ABI testing symbols +=================== + +Documents interfaces that are felt to be stable, +as the main development of this interface has been completed. + +The interface can be changed to add new features, but the +current interface will not break by doing this, unless grave +errors or security problems are found in them. + +Userspace programs can start to rely on these interfaces, but they must +be aware of changes that can occur before these interfaces move to +be marked stable. + +Programs that use these interfaces are strongly encouraged to add their +name to the description of these interfaces, so that the kernel +developers can easily notify them if any changes occur. + +.. kernel-abi:: ABI/testing + :rst: diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst new file mode 100644 index 000000000..bcab3ef25 --- /dev/null +++ b/Documentation/admin-guide/abi.rst @@ -0,0 +1,11 @@ +===================== +Linux ABI description +===================== + +.. toctree:: + :maxdepth: 2 + + abi-stable + abi-testing + abi-obsolete + abi-removed diff --git a/Documentation/admin-guide/acpi/cppc_sysfs.rst b/Documentation/admin-guide/acpi/cppc_sysfs.rst new file mode 100644 index 000000000..e53d76365 --- /dev/null +++ b/Documentation/admin-guide/acpi/cppc_sysfs.rst @@ -0,0 +1,78 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================================== +Collaborative Processor Performance Control (CPPC) +================================================== + +.. _cppc_sysfs: + +CPPC +==== + +CPPC defined in the ACPI spec describes a mechanism for the OS to manage the +performance of a logical processor on a contiguous and abstract performance +scale. CPPC exposes a set of registers to describe abstract performance scale, +to request performance levels and to measure per-cpu delivered performance. + +For more details on CPPC please refer to the ACPI specification at: + +http://uefi.org/specifications + +Some of the CPPC registers are exposed via sysfs under:: + + /sys/devices/system/cpu/cpuX/acpi_cppc/ + +for each cpu X:: + + $ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/ + /sys/devices/system/cpu/cpu0/acpi_cppc/: + total 0 + -r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs + -r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf + -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq + -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf + -r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf + -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq + -r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf + -r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf + -r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time + +* highest_perf : Highest performance of this processor (abstract scale). +* nominal_perf : Highest sustained performance of this processor + (abstract scale). +* lowest_nonlinear_perf : Lowest performance of this processor with nonlinear + power savings (abstract scale). +* lowest_perf : Lowest performance of this processor (abstract scale). + +* lowest_freq : CPU frequency corresponding to lowest_perf (in MHz). +* nominal_freq : CPU frequency corresponding to nominal_perf (in MHz). + The above frequencies should only be used to report processor performance in + frequency instead of abstract scale. These values should not be used for any + functional decisions. + +* feedback_ctrs : Includes both Reference and delivered performance counter. + Reference counter ticks up proportional to processor's reference performance. + Delivered counter ticks up proportional to processor's delivered performance. +* wraparound_time: Minimum time for the feedback counters to wraparound + (seconds). +* reference_perf : Performance level at which reference performance counter + accumulates (abstract scale). + + +Computing Average Delivered Performance +======================================= + +Below describes the steps to compute the average performance delivered by +taking two different snapshots of feedback counters at time T1 and T2. + + T1: Read feedback_ctrs as fbc_t1 + Wait or run some workload + + T2: Read feedback_ctrs as fbc_t2 + +:: + + delivered_counter_delta = fbc_t2[del] - fbc_t1[del] + reference_counter_delta = fbc_t2[ref] - fbc_t1[ref] + + delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta diff --git a/Documentation/admin-guide/acpi/fan_performance_states.rst b/Documentation/admin-guide/acpi/fan_performance_states.rst new file mode 100644 index 000000000..b9e4b4d14 --- /dev/null +++ b/Documentation/admin-guide/acpi/fan_performance_states.rst @@ -0,0 +1,90 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +ACPI Fan Performance States +=========================== + +When the optional _FPS object is present under an ACPI device representing a +fan (for example, PNP0C0B or INT3404), the ACPI fan driver creates additional +"state*" attributes in the sysfs directory of the ACPI device in question. +These attributes list properties of fan performance states. + +For more information on _FPS refer to the ACPI specification at: + +http://uefi.org/specifications + +For instance, the contents of the INT3404 ACPI device sysfs directory +may look as follows:: + + $ ls -l /sys/bus/acpi/devices/INT3404:00/ + total 0 + ... + -r--r--r-- 1 root root 4096 Dec 13 20:38 state0 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state1 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state10 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state11 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state2 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state3 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state4 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state5 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state6 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state7 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state8 + -r--r--r-- 1 root root 4096 Dec 13 20:38 state9 + -r--r--r-- 1 root root 4096 Dec 13 01:00 status + ... + +where each of the "state*" files represents one performance state of the fan +and contains a colon-separated list of 5 integer numbers (fields) with the +following interpretation:: + + control_percent:trip_point_index:speed_rpm:noise_level_mdb:power_mw + +* ``control_percent``: The percent value to be used to set the fan speed to a + specific level using the _FSL object (0-100). + +* ``trip_point_index``: The active cooling trip point number that corresponds + to this performance state (0-9). + +* ``speed_rpm``: Speed of the fan in rotations per minute. + +* ``noise_level_mdb``: Audible noise emitted by the fan in this state in + millidecibels. + +* ``power_mw``: Power draw of the fan in this state in milliwatts. + +For example:: + + $cat /sys/bus/acpi/devices/INT3404:00/state1 + 25:0:3200:12500:1250 + +When a given field is not populated or its value provided by the platform +firmware is invalid, the "not-defined" string is shown instead of the value. + +ACPI Fan Fine Grain Control +============================= + +When _FIF object specifies support for fine grain control, then fan speed +can be set from 0 to 100% with the recommended minimum "step size" via +_FSL object. User can adjust fan speed using thermal sysfs cooling device. + +Here use can look at fan performance states for a reference speed (speed_rpm) +and set it by changing cooling device cur_state. If the fine grain control +is supported then user can also adjust to some other speeds which are +not defined in the performance states. + +The support of fine grain control is presented via sysfs attribute +"fine_grain_control". If fine grain control is present, this attribute +will show "1" otherwise "0". + +This sysfs attribute is presented in the same directory as performance states. + +ACPI Fan Performance Feedback +============================= + +The optional _FST object provides status information for the fan device. +This includes field to provide current fan speed in revolutions per minute +at which the fan is rotating. + +This speed is presented in the sysfs using the attribute "fan_speed_rpm", +in the same directory as performance states. diff --git a/Documentation/admin-guide/acpi/index.rst b/Documentation/admin-guide/acpi/index.rst new file mode 100644 index 000000000..b078fdb8f --- /dev/null +++ b/Documentation/admin-guide/acpi/index.rst @@ -0,0 +1,14 @@ +============ +ACPI Support +============ + +Here we document in detail how to interact with various mechanisms in +the Linux ACPI support. + +.. toctree:: + :maxdepth: 1 + + initrd_table_override + ssdt-overlays + cppc_sysfs + fan_performance_states diff --git a/Documentation/admin-guide/acpi/initrd_table_override.rst b/Documentation/admin-guide/acpi/initrd_table_override.rst new file mode 100644 index 000000000..bb24fa6b5 --- /dev/null +++ b/Documentation/admin-guide/acpi/initrd_table_override.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ +Upgrading ACPI tables via initrd +================================ + +What is this about +================== + +If the ACPI_TABLE_UPGRADE compile option is true, it is possible to +upgrade the ACPI execution environment that is defined by the ACPI tables +via upgrading the ACPI tables provided by the BIOS with an instrumented, +modified, more recent version one, or installing brand new ACPI tables. + +When building initrd with kernel in a single image, option +ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this +feature to work. + +For a full list of ACPI tables that can be upgraded/installed, take a look +at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in +drivers/acpi/tables.c. + +All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should +be overridable, except: + + - ACPI_SIG_RSDP (has a signature of 6 bytes) + - ACPI_SIG_FACS (does not have an ordinary ACPI table header) + +Both could get implemented as well. + + +What is this for +================ + +Complain to your platform/BIOS vendor if you find a bug which is so severe +that a workaround is not accepted in the Linux kernel. And this facility +allows you to upgrade the buggy tables before your platform/BIOS vendor +releases an upgraded BIOS binary. + +This facility can be used by platform/BIOS vendors to provide a Linux +compatible environment without modifying the underlying platform firmware. + +This facility also provides a powerful feature to easily debug and test +ACPI BIOS table compatibility with the Linux kernel by modifying old +platform provided ACPI tables or inserting new ACPI tables. + +It can and should be enabled in any kernel because there is no functional +change with not instrumented initrds. + + +How does it work +================ +:: + + # Extract the machine's ACPI tables: + cd /tmp + acpidump >acpidump + acpixtract -a acpidump + # Disassemble, modify and recompile them: + iasl -d *.dat + # For example add this statement into a _PRT (PCI Routing Table) function + # of the DSDT: + Store("HELLO WORLD", debug) + # And increase the OEM Revision. For example, before modification: + DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000) + # After modification: + DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001) + iasl -sa dsdt.dsl + # Add the raw ACPI tables to an uncompressed cpio archive. + # They must be put into a /kernel/firmware/acpi directory inside the cpio + # archive. Note that if the table put here matches a platform table + # (similar Table Signature, and similar OEMID, and similar OEM Table ID) + # with a more recent OEM Revision, the platform table will be upgraded by + # this table. If the table put here doesn't match a platform table + # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table + # ID), this table will be appended. + mkdir -p kernel/firmware/acpi + cp dsdt.aml kernel/firmware/acpi + # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed + # (see osl.c): + iasl -sa facp.dsl + iasl -sa ssdt1.dsl + cp facp.aml kernel/firmware/acpi + cp ssdt1.aml kernel/firmware/acpi + # The uncompressed cpio archive must be the first. Other, typically + # compressed cpio archives, must be concatenated on top of the uncompressed + # one. Following command creates the uncompressed cpio archive and + # concatenates the original initrd on top: + find kernel | cpio -H newc --create > /boot/instrumented_initrd + cat /boot/initrd >>/boot/instrumented_initrd + # reboot with increased acpi debug level, e.g. boot params: + acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF + # and check your syslog: + [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT] + [ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD" + +iasl is able to disassemble and recompile quite a lot different, +also static ACPI tables. + + +Where to retrieve userspace tools +================================= + +iasl and acpixtract are part of Intel's ACPICA project: +https://acpica.org/ + +and should be packaged by distributions (for example in the acpica package +on SUSE). + +acpidump can be found in Len Browns pmtools: +ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump + +This tool is also part of the acpica package on SUSE. +Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels: +/sys/firmware/acpi/tables diff --git a/Documentation/admin-guide/acpi/ssdt-overlays.rst b/Documentation/admin-guide/acpi/ssdt-overlays.rst new file mode 100644 index 000000000..b5fbf54dc --- /dev/null +++ b/Documentation/admin-guide/acpi/ssdt-overlays.rst @@ -0,0 +1,181 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +SSDT Overlays +============= + +In order to support ACPI open-ended hardware configurations (e.g. development +boards) we need a way to augment the ACPI configuration provided by the firmware +image. A common example is connecting sensors on I2C / SPI buses on development +boards. + +Although this can be accomplished by creating a kernel platform driver or +recompiling the firmware image with updated ACPI tables, neither is practical: +the former proliferates board specific kernel code while the latter requires +access to firmware tools which are often not publicly available. + +Because ACPI supports external references in AML code a more practical +way to augment firmware ACPI configuration is by dynamically loading +user defined SSDT tables that contain the board specific information. + +For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the +Minnowboard MAX development board exposed via the LSE connector [1], the +following ASL code can be used:: + + DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003) + { + External (\_SB.I2C6, DeviceObj) + + Scope (\_SB.I2C6) + { + Device (STAC) + { + Name (_HID, "BMA222E") + Name (RBUF, ResourceTemplate () + { + I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80, + AddressingMode7Bit, "\\_SB.I2C6", 0x00, + ResourceConsumer, ,) + GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000, + "\\_SB.GPO2", 0x00, ResourceConsumer, , ) + { // Pin list + 0 + } + }) + + Method (_CRS, 0, Serialized) + { + Return (RBUF) + } + } + } + } + +which can then be compiled to AML binary format:: + + $ iasl minnowmax.asl + + Intel ACPI Component Architecture + ASL Optimizing Compiler version 20140214-64 [Mar 29 2014] + Copyright (c) 2000 - 2014 Intel Corporation + + ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords + AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes + +[1] https://www.elinux.org/Minnowboard:MinnowMax#Low_Speed_Expansion_.28Top.29 + +The resulting AML code can then be loaded by the kernel using one of the methods +below. + +Loading ACPI SSDTs from initrd +============================== + +This option allows loading of user defined SSDTs from initrd and it is useful +when the system does not support EFI or when there is not enough EFI storage. + +It works in a similar way with initrd based ACPI tables override/upgrade: SSDT +AML code must be placed in the first, uncompressed, initrd under the +"kernel/firmware/acpi" path. Multiple files can be used and this will translate +in loading multiple tables. Only SSDT and OEM tables are allowed. See +initrd_table_override.txt for more details. + +Here is an example:: + + # Add the raw ACPI tables to an uncompressed cpio archive. + # They must be put into a /kernel/firmware/acpi directory inside the + # cpio archive. + # The uncompressed cpio archive must be the first. + # Other, typically compressed cpio archives, must be + # concatenated on top of the uncompressed one. + mkdir -p kernel/firmware/acpi + cp ssdt.aml kernel/firmware/acpi + + # Create the uncompressed cpio archive and concatenate the original initrd + # on top: + find kernel | cpio -H newc --create > /boot/instrumented_initrd + cat /boot/initrd >>/boot/instrumented_initrd + +Loading ACPI SSDTs from EFI variables +===================================== + +This is the preferred method, when EFI is supported on the platform, because it +allows a persistent, OS independent way of storing the user defined SSDTs. There +is also work underway to implement EFI support for loading user defined SSDTs +and using this method will make it easier to convert to the EFI loading +mechanism when that will arrive. To enable it, the +CONFIG_EFI_CUSTOM_SSDT_OVERLAYS shoyld be chosen to y. + +In order to load SSDTs from an EFI variable the ``"efivar_ssdt=..."`` kernel +command line parameter can be used (the name has a limitation of 16 characters). +The argument for the option is the variable name to use. If there are multiple +variables with the same name but with different vendor GUIDs, all of them will +be loaded. + +In order to store the AML code in an EFI variable the efivarfs filesystem can be +used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all +recent distribution. + +Creating a new file in /sys/firmware/efi/efivars will automatically create a new +EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI +variable. Please note that the file name needs to be specially formatted as +"Name-GUID" and that the first 4 bytes in the file (little-endian format) +represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in +include/linux/efi.h). Writing to the file must also be done with one write +operation. + +For example, you can use the following bash script to create/update an EFI +variable with the content from a given file:: + + #!/bin/sh -e + + while [ -n "$1" ]; do + case "$1" in + "-f") filename="$2"; shift;; + "-g") guid="$2"; shift;; + *) name="$1";; + esac + shift + done + + usage() + { + echo "Syntax: ${0##*/} -f filename [ -g guid ] name" + exit 1 + } + + [ -n "$name" -a -f "$filename" ] || usage + + EFIVARFS="/sys/firmware/efi/efivars" + + [ -d "$EFIVARFS" ] || exit 2 + + if stat -tf $EFIVARFS | grep -q -v de5e81e4; then + mount -t efivarfs none $EFIVARFS + fi + + # try to pick up an existing GUID + [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-) + + # use a randomly generated GUID + [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)" + + # efivarfs expects all of the data in one write + tmp=$(mktemp) + /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp + dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp) + rm $tmp + +Loading ACPI SSDTs from configfs +================================ + +This option allows loading of user defined SSDTs from user space via the configfs +interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be +mounted. In the following examples, we assume that configfs has been mounted in +/sys/kernel/config. + +New tables can be loading by creating new directories in /sys/kernel/config/acpi/table +and writing the SSDT AML code in the aml attribute:: + + cd /sys/kernel/config/acpi/table + mkdir my_ssdt + cat ~/ssdt.aml > my_ssdt/aml diff --git a/Documentation/admin-guide/aoe/aoe.rst b/Documentation/admin-guide/aoe/aoe.rst new file mode 100644 index 000000000..a05e75136 --- /dev/null +++ b/Documentation/admin-guide/aoe/aoe.rst @@ -0,0 +1,150 @@ +Introduction +============ + +ATA over Ethernet is a network protocol that provides simple access to +block storage on the LAN. + + http://support.coraid.com/documents/AoEr11.txt + +The EtherDrive (R) HOWTO for 2.6 and 3.x kernels is found at ... + + http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO.html + +It has many tips and hints! Please see, especially, recommended +tunings for virtual memory: + + http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO-5.html#ss5.19 + +The aoetools are userland programs that are designed to work with this +driver. The aoetools are on sourceforge. + + http://aoetools.sourceforge.net/ + +The scripts in this Documentation/admin-guide/aoe directory are intended to +document the use of the driver and are not necessary if you install +the aoetools. + + +Creating Device Nodes +===================== + + Users of udev should find the block device nodes created + automatically, but to create all the necessary device nodes, use the + udev configuration rules provided in udev.txt (in this directory). + + There is a udev-install.sh script that shows how to install these + rules on your system. + + There is also an autoload script that shows how to edit + /etc/modprobe.d/aoe.conf to ensure that the aoe module is loaded when + necessary. Preloading the aoe module is preferable to autoloading, + however, because AoE discovery takes a few seconds. It can be + confusing when an AoE device is not present the first time the a + command is run but appears a second later. + +Using Device Nodes +================== + + "cat /dev/etherd/err" blocks, waiting for error diagnostic output, + like any retransmitted packets. + + "echo eth2 eth4 > /dev/etherd/interfaces" tells the aoe driver to + limit ATA over Ethernet traffic to eth2 and eth4. AoE traffic from + untrusted networks should be ignored as a matter of security. See + also the aoe_iflist driver option described below. + + "echo > /dev/etherd/discover" tells the driver to find out what AoE + devices are available. + + In the future these character devices may disappear and be replaced + by sysfs counterparts. Using the commands in aoetools insulates + users from these implementation details. + + The block devices are named like this:: + + e{shelf}.{slot} + e{shelf}.{slot}p{part} + + ... so that "e0.2" is the third blade from the left (slot 2) in the + first shelf (shelf address zero). That's the whole disk. The first + partition on that disk would be "e0.2p1". + +Using sysfs +=========== + + Each aoe block device in /sys/block has the extra attributes of + state, mac, and netif. The state attribute is "up" when the device + is ready for I/O and "down" if detected but unusable. The + "down,closewait" state shows that the device is still open and + cannot come up again until it has been closed. + + The mac attribute is the ethernet address of the remote AoE device. + The netif attribute is the network interface on the localhost + through which we are communicating with the remote AoE device. + + There is a script in this directory that formats this information in + a convenient way. Users with aoetools should use the aoe-stat + command:: + + root@makki root# sh Documentation/admin-guide/aoe/status.sh + e10.0 eth3 up + e10.1 eth3 up + e10.2 eth3 up + e10.3 eth3 up + e10.4 eth3 up + e10.5 eth3 up + e10.6 eth3 up + e10.7 eth3 up + e10.8 eth3 up + e10.9 eth3 up + e4.0 eth1 up + e4.1 eth1 up + e4.2 eth1 up + e4.3 eth1 up + e4.4 eth1 up + e4.5 eth1 up + e4.6 eth1 up + e4.7 eth1 up + e4.8 eth1 up + e4.9 eth1 up + + Use /sys/module/aoe/parameters/aoe_iflist (or better, the driver + option discussed below) instead of /dev/etherd/interfaces to limit + AoE traffic to the network interfaces in the given + whitespace-separated list. Unlike the old character device, the + sysfs entry can be read from as well as written to. + + It's helpful to trigger discovery after setting the list of allowed + interfaces. The aoetools package provides an aoe-discover script + for this purpose. You can also directly use the + /dev/etherd/discover special file described above. + +Driver Options +============== + + There is a boot option for the built-in aoe driver and a + corresponding module parameter, aoe_iflist. Without this option, + all network interfaces may be used for ATA over Ethernet. Here is a + usage example for the module parameter:: + + modprobe aoe_iflist="eth1 eth3" + + The aoe_deadsecs module parameter determines the maximum number of + seconds that the driver will wait for an AoE device to provide a + response to an AoE command. After aoe_deadsecs seconds have + elapsed, the AoE device will be marked as "down". A value of zero + is supported for testing purposes and makes the aoe driver keep + trying AoE commands forever. + + The aoe_maxout module parameter has a default of 128. This is the + maximum number of unresponded packets that will be sent to an AoE + target at one time. + + The aoe_dyndevs module parameter defaults to 1, meaning that the + driver will assign a block device minor number to a discovered AoE + target based on the order of its discovery. With dynamic minor + device numbers in use, a greater range of AoE shelf and slot + addresses can be supported. Users with udev will never have to + think about minor numbers. Using aoe_dyndevs=0 allows device nodes + to be pre-created using a static minor-number scheme with the + aoe-mkshelf script in the aoetools. diff --git a/Documentation/admin-guide/aoe/autoload.sh b/Documentation/admin-guide/aoe/autoload.sh new file mode 100644 index 000000000..815dff469 --- /dev/null +++ b/Documentation/admin-guide/aoe/autoload.sh @@ -0,0 +1,17 @@ +#!/bin/sh +# set aoe to autoload by installing the +# aliases in /etc/modprobe.d/ + +f=/etc/modprobe.d/aoe.conf + +if test ! -r $f || test ! -w $f; then + echo "cannot configure $f for module autoloading" 1>&2 + exit 1 +fi + +grep major-152 $f >/dev/null +if [ $? = 1 ]; then + echo alias block-major-152 aoe >> $f + echo alias char-major-152 aoe >> $f +fi + diff --git a/Documentation/admin-guide/aoe/examples.rst b/Documentation/admin-guide/aoe/examples.rst new file mode 100644 index 000000000..91f3198e5 --- /dev/null +++ b/Documentation/admin-guide/aoe/examples.rst @@ -0,0 +1,23 @@ +Example of udev rules +--------------------- + + .. include:: udev.txt + :literal: + +Example of udev install rules script +------------------------------------ + + .. literalinclude:: udev-install.sh + :language: shell + +Example script to get status +---------------------------- + + .. literalinclude:: status.sh + :language: shell + +Example of AoE autoload script +------------------------------ + + .. literalinclude:: autoload.sh + :language: shell diff --git a/Documentation/admin-guide/aoe/index.rst b/Documentation/admin-guide/aoe/index.rst new file mode 100644 index 000000000..d71c5df15 --- /dev/null +++ b/Documentation/admin-guide/aoe/index.rst @@ -0,0 +1,17 @@ +======================= +ATA over Ethernet (AoE) +======================= + +.. toctree:: + :maxdepth: 1 + + aoe + todo + examples + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/admin-guide/aoe/status.sh b/Documentation/admin-guide/aoe/status.sh new file mode 100644 index 000000000..eeec7baae --- /dev/null +++ b/Documentation/admin-guide/aoe/status.sh @@ -0,0 +1,30 @@ +#! /bin/sh +# collate and present sysfs information about AoE storage +# +# A more complete version of this script is aoe-stat, in the +# aoetools. + +set -e +format="%8s\t%8s\t%8s\n" +me=`basename $0` +sysd=${sysfs_dir:-/sys} + +# printf "$format" device mac netif state + +# Suse 9.1 Pro doesn't put /sys in /etc/mtab +#test -z "`mount | grep sysfs`" && { +test ! -d "$sysd/block" && { + echo "$me Error: sysfs is not mounted" 1>&2 + exit 1 +} + +for d in `ls -d $sysd/block/etherd* 2>/dev/null | grep -v p` end; do + # maybe ls comes up empty, so we use "end" + test $d = end && continue + + dev=`echo "$d" | sed 's/.*!//'` + printf "$format" \ + "$dev" \ + "`cat \"$d/netif\"`" \ + "`cat \"$d/state\"`" +done | sort diff --git a/Documentation/admin-guide/aoe/todo.rst b/Documentation/admin-guide/aoe/todo.rst new file mode 100644 index 000000000..dea8db5a3 --- /dev/null +++ b/Documentation/admin-guide/aoe/todo.rst @@ -0,0 +1,17 @@ +TODO +==== + +There is a potential for deadlock when allocating a struct sk_buff for +data that needs to be written out to aoe storage. If the data is +being written from a dirty page in order to free that page, and if +there are no other pages available, then deadlock may occur when a +free page is needed for the sk_buff allocation. This situation has +not been observed, but it would be nice to eliminate any potential for +deadlock under memory pressure. + +Because ATA over Ethernet is not fragmented by the kernel's IP code, +the destructor member of the struct sk_buff is available to the aoe +driver. By using a mempool for allocating all but the first few +sk_buffs, and by registering a destructor, we should be able to +efficiently allocate sk_buffs without introducing any potential for +deadlock. diff --git a/Documentation/admin-guide/aoe/udev-install.sh b/Documentation/admin-guide/aoe/udev-install.sh new file mode 100644 index 000000000..15e86f58c --- /dev/null +++ b/Documentation/admin-guide/aoe/udev-install.sh @@ -0,0 +1,33 @@ +# install the aoe-specific udev rules from udev.txt into +# the system's udev configuration +# + +me="`basename $0`" + +# find udev.conf, often /etc/udev/udev.conf +# (or environment can specify where to find udev.conf) +# +if test -z "$conf"; then + if test -r /etc/udev/udev.conf; then + conf=/etc/udev/udev.conf + else + conf="`find /etc -type f -name udev.conf 2> /dev/null`" + if test -z "$conf" || test ! -r "$conf"; then + echo "$me Error: no udev.conf found" 1>&2 + exit 1 + fi + fi +fi + +# find the directory where udev rules are stored, often +# /etc/udev/rules.d +# +rules_d="`sed -n '/^udev_rules=/{ s!udev_rules=!!; s!\"!!g; p; }' $conf`" +if test -z "$rules_d" ; then + rules_d=/etc/udev/rules.d +fi +if test ! -d "$rules_d"; then + echo "$me Error: cannot find udev rules directory" 1>&2 + exit 1 +fi +sh -xc "cp `dirname $0`/udev.txt $rules_d/60-aoe.rules" diff --git a/Documentation/admin-guide/aoe/udev.txt b/Documentation/admin-guide/aoe/udev.txt new file mode 100644 index 000000000..5fb756466 --- /dev/null +++ b/Documentation/admin-guide/aoe/udev.txt @@ -0,0 +1,26 @@ +# These rules tell udev what device nodes to create for aoe support. +# They may be installed along the following lines. Check the section +# 8 udev manpage to see whether your udev supports SUBSYSTEM, and +# whether it uses one or two equal signs for SUBSYSTEM and KERNEL. +# +# ecashin@makki ~$ su +# Password: +# bash# find /etc -type f -name udev.conf +# /etc/udev/udev.conf +# bash# grep udev_rules= /etc/udev/udev.conf +# udev_rules="/etc/udev/rules.d/" +# bash# ls /etc/udev/rules.d/ +# 10-wacom.rules 50-udev.rules +# bash# cp /path/to/linux/Documentation/admin-guide/aoe/udev.txt \ +# /etc/udev/rules.d/60-aoe.rules +# + +# aoe char devices +SUBSYSTEM=="aoe", KERNEL=="discover", NAME="etherd/%k", GROUP="disk", MODE="0220" +SUBSYSTEM=="aoe", KERNEL=="err", NAME="etherd/%k", GROUP="disk", MODE="0440" +SUBSYSTEM=="aoe", KERNEL=="interfaces", NAME="etherd/%k", GROUP="disk", MODE="0220" +SUBSYSTEM=="aoe", KERNEL=="revalidate", NAME="etherd/%k", GROUP="disk", MODE="0220" +SUBSYSTEM=="aoe", KERNEL=="flush", NAME="etherd/%k", GROUP="disk", MODE="0220" + +# aoe block devices +KERNEL=="etherd*", GROUP="disk" diff --git a/Documentation/admin-guide/auxdisplay/cfag12864b.rst b/Documentation/admin-guide/auxdisplay/cfag12864b.rst new file mode 100644 index 000000000..da385d851 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst @@ -0,0 +1,98 @@ +=================================== +cfag12864b LCD Driver Documentation +=================================== + +:License: GPLv2 +:Author & Maintainer: Miguel Ojeda +:Date: 2006-10-27 + + + +.. INDEX + + 1. DRIVER INFORMATION + 2. DEVICE INFORMATION + 3. WIRING + 4. USERSPACE PROGRAMMING + +1. Driver Information +--------------------- + +This driver supports a cfag12864b LCD. + + +2. Device Information +--------------------- + +:Manufacturer: Crystalfontz +:Device Name: Crystalfontz 12864b LCD Series +:Device Code: cfag12864b +:Webpage: http://www.crystalfontz.com +:Device Webpage: http://www.crystalfontz.com/products/12864b/ +:Type: LCD (Liquid Crystal Display) +:Width: 128 +:Height: 64 +:Colors: 2 (B/N) +:Controller: ks0108 +:Controllers: 2 +:Pages: 8 each controller +:Addresses: 64 each page +:Data size: 1 byte each address +:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte + + +3. Wiring +--------- + +The cfag12864b LCD Series don't have official wiring. + +The common wiring is done to the parallel port as shown:: + + Parallel Port cfag12864b + + Name Pin# Pin# Name + + Strobe ( 1)------------------------------(17) Enable + Data 0 ( 2)------------------------------( 4) Data 0 + Data 1 ( 3)------------------------------( 5) Data 1 + Data 2 ( 4)------------------------------( 6) Data 2 + Data 3 ( 5)------------------------------( 7) Data 3 + Data 4 ( 6)------------------------------( 8) Data 4 + Data 5 ( 7)------------------------------( 9) Data 5 + Data 6 ( 8)------------------------------(10) Data 6 + Data 7 ( 9)------------------------------(11) Data 7 + (10) [+5v]---( 1) Vdd + (11) [GND]---( 2) Ground + (12) [+5v]---(14) Reset + (13) [GND]---(15) Read / Write + Line (14)------------------------------(13) Controller Select 1 + (15) + Init (16)------------------------------(12) Controller Select 2 + Select (17)------------------------------(16) Data / Instruction + Ground (18)---[GND] [+5v]---(19) LED + + Ground (19)---[GND] + Ground (20)---[GND] E A Values: + Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm + Ground (22)---[GND] | - P1 = Preset = 10 Kohm + Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm + Ground (24)---[GND] | | + Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED - + + +4. Userspace Programming +------------------------ + +The cfag12864bfb describes a framebuffer device (/dev/fbX). + +It has a size of 1024 bytes = 1 Kbyte. +Each bit represents one pixel. If the bit is high, the pixel will +turn on. If the pixel is low, the pixel will turn off. + +You can use the framebuffer as a file: fopen, fwrite, fclose... +Although the LCD won't get updated until the next refresh time arrives. + +Also, you can mmap the framebuffer: open & mmap, munmap & close... +which is the best option for most uses. + +Check samples/auxdisplay/cfag12864b-example.c +for a real working userspace complete program with usage examples. diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst new file mode 100644 index 000000000..e466f0595 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/index.rst @@ -0,0 +1,16 @@ +========================= +Auxiliary Display Support +========================= + +.. toctree:: + :maxdepth: 1 + + ks0108.rst + cfag12864b.rst + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/admin-guide/auxdisplay/ks0108.rst b/Documentation/admin-guide/auxdisplay/ks0108.rst new file mode 100644 index 000000000..a7d3fe509 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/ks0108.rst @@ -0,0 +1,50 @@ +========================================== +ks0108 LCD Controller Driver Documentation +========================================== + +:License: GPLv2 +:Author & Maintainer: Miguel Ojeda +:Date: 2006-10-27 + + + +.. INDEX + + 1. DRIVER INFORMATION + 2. DEVICE INFORMATION + 3. WIRING + + +1. Driver Information +--------------------- + +This driver supports the ks0108 LCD controller. + + +2. Device Information +--------------------- + +:Manufacturer: Samsung +:Device Name: KS0108 LCD Controller +:Device Code: ks0108 +:Webpage: - +:Device Webpage: - +:Type: LCD Controller (Liquid Crystal Display Controller) +:Width: 64 +:Height: 64 +:Colors: 2 (B/N) +:Pages: 8 +:Addresses: 64 each page +:Data size: 1 byte each address +:Memory size: 8 * 64 * 1 = 512 bytes + + +3. Wiring +--------- + +The driver supports data parallel port wiring. + +If you aren't building LCD related hardware, you should check +your LCD specific wiring information in the same folder. + +For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst diff --git a/Documentation/admin-guide/bcache.rst b/Documentation/admin-guide/bcache.rst new file mode 100644 index 000000000..8d3a2d045 --- /dev/null +++ b/Documentation/admin-guide/bcache.rst @@ -0,0 +1,656 @@ +============================ +A block layer cache (bcache) +============================ + +Say you've got a big slow raid 6, and an ssd or three. Wouldn't it be +nice if you could use them as cache... Hence bcache. + +The bcache wiki can be found at: + https://bcache.evilpiepirate.org + +This is the git repository of bcache-tools: + https://git.kernel.org/pub/scm/linux/kernel/git/colyli/bcache-tools.git/ + +The latest bcache kernel code can be found from mainline Linux kernel: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/ + +It's designed around the performance characteristics of SSDs - it only allocates +in erase block sized buckets, and it uses a hybrid btree/log to track cached +extents (which can be anywhere from a single sector to the bucket size). It's +designed to avoid random writes at all costs; it fills up an erase block +sequentially, then issues a discard before reusing it. + +Both writethrough and writeback caching are supported. Writeback defaults to +off, but can be switched on and off arbitrarily at runtime. Bcache goes to +great lengths to protect your data - it reliably handles unclean shutdown. (It +doesn't even have a notion of a clean shutdown; bcache simply doesn't return +writes as completed until they're on stable storage). + +Writeback caching can use most of the cache for buffering writes - writing +dirty data to the backing device is always done sequentially, scanning from the +start to the end of the index. + +Since random IO is what SSDs excel at, there generally won't be much benefit +to caching large sequential IO. Bcache detects sequential IO and skips it; +it also keeps a rolling average of the IO sizes per task, and as long as the +average is above the cutoff it will skip all IO from that task - instead of +caching the first 512k after every seek. Backups and large file copies should +thus entirely bypass the cache. + +In the event of a data IO error on the flash it will try to recover by reading +from disk or invalidating cache entries. For unrecoverable errors (meta data +or dirty data), caching is automatically disabled; if dirty data was present +in the cache it first disables writeback caching and waits for all dirty data +to be flushed. + +Getting started: +You'll need bcache util from the bcache-tools repository. Both the cache device +and backing device must be formatted before use:: + + bcache make -B /dev/sdb + bcache make -C /dev/sdc + +`bcache make` has the ability to format multiple devices at the same time - if +you format your backing devices and cache device at the same time, you won't +have to manually attach:: + + bcache make -B /dev/sda /dev/sdb -C /dev/sdc + +If your bcache-tools is not updated to latest version and does not have the +unified `bcache` utility, you may use the legacy `make-bcache` utility to format +bcache device with same -B and -C parameters. + +bcache-tools now ships udev rules, and bcache devices are known to the kernel +immediately. Without udev, you can manually register devices like this:: + + echo /dev/sdb > /sys/fs/bcache/register + echo /dev/sdc > /sys/fs/bcache/register + +Registering the backing device makes the bcache device show up in /dev; you can +now format it and use it as normal. But the first time using a new bcache +device, it'll be running in passthrough mode until you attach it to a cache. +If you are thinking about using bcache later, it is recommended to setup all your +slow devices as bcache backing devices without a cache, and you can choose to add +a caching device later. +See 'ATTACHING' section below. + +The devices show up as:: + + /dev/bcache + +As well as (with udev):: + + /dev/bcache/by-uuid/ + /dev/bcache/by-label/