Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1645044 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2017-05-19 03:40 +0200 |
| Last post | 2017-05-23 11:20 +0200 |
| Articles | 18 — 4 participants |
Back to article view | Back to linux.kernel
[PATCH 00/29] Standardize doc formats - part 3 Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 10/29] robust-futexes.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 23/29] vfio-mediated-device.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
Re: [PATCH 23/29] vfio-mediated-device.txt: standardize document format Kirti Wankhede <kwankhede@nvidia.com> - 2017-05-22 21:50 +0200
[PATCH 19/29] svga.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
Re: [PATCH 19/29] svga.txt: standardize document format Martin Mares <mj@ucw.cz> - 2017-05-19 16:10 +0200
[PATCH 09/29] robust-futex-ABI.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 06/29] rbtree.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 13/29] SAK.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 14/29] sgi-ioc4.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 15/29] siphash.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 03/29] preempt-locking.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 05/29] pwm.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 27/29] xz.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 12/29] rtc.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 20/29] sync_file.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
[PATCH 16/29] SM501.txt: standardize document format Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2017-05-19 03:40 +0200
Re: [PATCH 01/29] pinctrl.txt: standardize document format Linus Walleij <linus.walleij@linaro.org> - 2017-05-23 11:20 +0200
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 00/29] Standardize doc formats - part 3 |
| Message-ID | <tIETU-39a-9@gated-at.bofh.it> |
Each document under Documentation/*.txt has its own format. Some follow markup notations, some don't even have a title! In order to try to get some order on it, change the document style to the standard we're adopting after the adoption of ReStructured Text. The documents touched on this series now build fine with Sphinx, if renamed to *.rst extension. The main goal with this is to teach people by example about what format is expected on newer documents. It also helps to add those files to Kernel books. In order to make things more palatable, I'm spliting the conversion into three parts. This is part 3. Mauro Carvalho Chehab (29): pinctrl.txt: standardize document format pnp.txt: standardize document format preempt-locking.txt: standardize document format printk-formats.txt: standardize document format pwm.txt: standardize document format rbtree.txt: standardize document format remoteproc.txt: standardize document format rfkill.txt: standardize document format robust-futex-ABI.txt: standardize document format robust-futexes.txt: standardize document format rpmsg.txt: standardize document format rtc.txt: standardize document format SAK.txt: standardize document format sgi-ioc4.txt: standardize document format siphash.txt: standardize document format SM501.txt: standardize document format smsc_ece1099.txt: standardize document format static-keys.txt: standardize document format svga.txt: standardize document format sync_file.txt: standardize document format this_cpu_ops.txt: standardize document format unaligned-memory-access.txt: standardize document format vfio-mediated-device.txt: standardize document format vfio.txt: standardize document format video-output.txt: standardize document format xillybus.txt: standardize document format xz.txt: standardize document format zorro.txt: standardize document format dell_rbu.txt: standardize document format Documentation/SAK.txt | 65 +- Documentation/SM501.txt | 9 +- Documentation/dell_rbu.txt | 81 ++- Documentation/pinctrl.txt | 1104 +++++++++++++++-------------- Documentation/pnp.txt | 343 +++++---- Documentation/preempt-locking.txt | 40 +- Documentation/printk-formats.txt | 416 ++++++----- Documentation/pwm.txt | 46 +- Documentation/rbtree.txt | 88 +-- Documentation/remoteproc.txt | 320 +++++---- Documentation/rfkill.txt | 47 +- Documentation/robust-futex-ABI.txt | 14 +- Documentation/robust-futexes.txt | 12 +- Documentation/rpmsg.txt | 340 +++++---- Documentation/rtc.txt | 44 +- Documentation/sgi-ioc4.txt | 4 + Documentation/siphash.txt | 186 ++--- Documentation/smsc_ece1099.txt | 4 + Documentation/static-keys.txt | 199 +++--- Documentation/svga.txt | 146 ++-- Documentation/sync_file.txt | 23 +- Documentation/this_cpu_ops.txt | 49 +- Documentation/unaligned-memory-access.txt | 57 +- Documentation/vfio-mediated-device.txt | 252 +++---- Documentation/vfio.txt | 261 +++---- Documentation/video-output.txt | 54 +- Documentation/xillybus.txt | 29 +- Documentation/xz.txt | 182 ++--- Documentation/zorro.txt | 59 +- 29 files changed, 2437 insertions(+), 2037 deletions(-) -- 2.9.4
[toc] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 10/29] robust-futexes.txt: standardize document format |
| Message-ID | <tIF3A-3cN-13@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - add a title for the document; - mark literal blocks; Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/robust-futexes.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Documentation/robust-futexes.txt b/Documentation/robust-futexes.txt index 61c22d608759..6c42c75103eb 100644 --- a/Documentation/robust-futexes.txt +++ b/Documentation/robust-futexes.txt @@ -1,4 +1,8 @@ -Started by: Ingo Molnar <mingo@redhat.com> +======================================== +A description of what robust futexes are +======================================== + +:Started by: Ingo Molnar <mingo@redhat.com> Background ---------- @@ -163,7 +167,7 @@ Implementation details ---------------------- The patch adds two new syscalls: one to register the userspace list, and -one to query the registered list pointer: +one to query the registered list pointer:: asmlinkage long sys_set_robust_list(struct robust_list_head __user *head, @@ -185,7 +189,7 @@ straightforward. The kernel doesn't have any internal distinction between robust and normal futexes. If a futex is found to be held at exit time, the kernel sets the -following bit of the futex word: +following bit of the futex word:: #define FUTEX_OWNER_DIED 0x40000000 @@ -193,7 +197,7 @@ and wakes up the next futex waiter (if any). User-space does the rest of the cleanup. Otherwise, robust futexes are acquired by glibc by putting the TID into -the futex field atomically. Waiters set the FUTEX_WAITERS bit: +the futex field atomically. Waiters set the FUTEX_WAITERS bit:: #define FUTEX_WAITERS 0x80000000 -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 23/29] vfio-mediated-device.txt: standardize document format |
| Message-ID | <tIF3z-3cN-1@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different
format. Some doesn't even have titles!
In this specific document, the title, copyright and authorship
are added as if it were a C file!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- convert document preambule to the proper format;
- mark literal blocks;
- adjust identation;
- use numbered lists for references.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/vfio-mediated-device.txt | 252 +++++++++++++++++----------------
1 file changed, 130 insertions(+), 122 deletions(-)
diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
index e5e57b40f8af..1b3950346532 100644
--- a/Documentation/vfio-mediated-device.txt
+++ b/Documentation/vfio-mediated-device.txt
@@ -1,14 +1,17 @@
-/*
- * VFIO Mediated devices
- *
- * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
- * Author: Neo Jia <cjia@nvidia.com>
- * Kirti Wankhede <kwankhede@nvidia.com>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2 as
- * published by the Free Software Foundation.
- */
+.. include:: <isonum.txt>
+
+=====================
+VFIO Mediated devices
+=====================
+
+:Copyright: |copy| 2016, NVIDIA CORPORATION. All rights reserved.
+:Author: Neo Jia <cjia@nvidia.com>
+:Author: Kirti Wankhede <kwankhede@nvidia.com>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
+
Virtual Function I/O (VFIO) Mediated devices[1]
===============================================
@@ -42,7 +45,7 @@ removes it from a VFIO group.
The following high-level block diagram shows the main components and interfaces
in the VFIO mediated driver framework. The diagram shows NVIDIA, Intel, and IBM
-devices as examples, as these devices are the first devices to use this module.
+devices as examples, as these devices are the first devices to use this module::
+---------------+
| |
@@ -91,7 +94,7 @@ Registration Interface for a Mediated Bus Driver
------------------------------------------------
The registration interface for a mediated bus driver provides the following
-structure to represent a mediated device's driver:
+structure to represent a mediated device's driver::
/*
* struct mdev_driver [2] - Mediated device's driver
@@ -110,14 +113,14 @@ structure to represent a mediated device's driver:
A mediated bus driver for mdev should use this structure in the function calls
to register and unregister itself with the core driver:
-* Register:
+* Register::
- extern int mdev_register_driver(struct mdev_driver *drv,
+ extern int mdev_register_driver(struct mdev_driver *drv,
struct module *owner);
-* Unregister:
+* Unregister::
- extern void mdev_unregister_driver(struct mdev_driver *drv);
+ extern void mdev_unregister_driver(struct mdev_driver *drv);
The mediated bus driver is responsible for adding mediated devices to the VFIO
group when devices are bound to the driver and removing mediated devices from
@@ -152,15 +155,15 @@ The callbacks in the mdev_parent_ops structure are as follows:
* mmap: mmap emulation callback
A driver should use the mdev_parent_ops structure in the function call to
-register itself with the mdev core driver:
+register itself with the mdev core driver::
-extern int mdev_register_device(struct device *dev,
- const struct mdev_parent_ops *ops);
+ extern int mdev_register_device(struct device *dev,
+ const struct mdev_parent_ops *ops);
However, the mdev_parent_ops structure is not required in the function call
-that a driver should use to unregister itself with the mdev core driver:
+that a driver should use to unregister itself with the mdev core driver::
-extern void mdev_unregister_device(struct device *dev);
+ extern void mdev_unregister_device(struct device *dev);
Mediated Device Management Interface Through sysfs
@@ -183,30 +186,32 @@ with the mdev core driver.
Directories and files under the sysfs for Each Physical Device
--------------------------------------------------------------
-|- [parent physical device]
-|--- Vendor-specific-attributes [optional]
-|--- [mdev_supported_types]
-| |--- [<type-id>]
-| | |--- create
-| | |--- name
-| | |--- available_instances
-| | |--- device_api
-| | |--- description
-| | |--- [devices]
-| |--- [<type-id>]
-| | |--- create
-| | |--- name
-| | |--- available_instances
-| | |--- device_api
-| | |--- description
-| | |--- [devices]
-| |--- [<type-id>]
-| |--- create
-| |--- name
-| |--- available_instances
-| |--- device_api
-| |--- description
-| |--- [devices]
+::
+
+ |- [parent physical device]
+ |--- Vendor-specific-attributes [optional]
+ |--- [mdev_supported_types]
+ | |--- [<type-id>]
+ | | |--- create
+ | | |--- name
+ | | |--- available_instances
+ | | |--- device_api
+ | | |--- description
+ | | |--- [devices]
+ | |--- [<type-id>]
+ | | |--- create
+ | | |--- name
+ | | |--- available_instances
+ | | |--- device_api
+ | | |--- description
+ | | |--- [devices]
+ | |--- [<type-id>]
+ | |--- create
+ | |--- name
+ | |--- available_instances
+ | |--- device_api
+ | |--- description
+ | |--- [devices]
* [mdev_supported_types]
@@ -219,12 +224,12 @@ Directories and files under the sysfs for Each Physical Device
The [<type-id>] name is created by adding the device driver string as a prefix
to the string provided by the vendor driver. This format of this name is as
- follows:
+ follows::
sprintf(buf, "%s-%s", dev_driver_string(parent->dev), group->name);
(or using mdev_parent_dev(mdev) to arrive at the parent device outside
- of the core mdev code)
+ of the core mdev code)
* device_api
@@ -239,7 +244,7 @@ Directories and files under the sysfs for Each Physical Device
* [device]
This directory contains links to the devices of type <type-id> that have been
-created.
+ created.
* name
@@ -253,21 +258,25 @@ created.
Directories and Files Under the sysfs for Each mdev Device
----------------------------------------------------------
-|- [parent phy device]
-|--- [$MDEV_UUID]
+::
+
+ |- [parent phy device]
+ |--- [$MDEV_UUID]
|--- remove
|--- mdev_type {link to its type}
|--- vendor-specific-attributes [optional]
* remove (write only)
+
Writing '1' to the 'remove' file destroys the mdev device. The vendor driver can
fail the remove() callback if that device is active and the vendor driver
doesn't support hot unplug.
-Example:
+Example::
+
# echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
-Mediated device Hot plug:
+Mediated device Hot plug
------------------------
Mediated devices can be created and assigned at runtime. The procedure to hot
@@ -277,13 +286,13 @@ Translation APIs for Mediated Devices
=====================================
The following APIs are provided for translating user pfn to host pfn in a VFIO
-driver:
+driver::
-extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
- int npage, int prot, unsigned long *phys_pfn);
+ extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
+ int npage, int prot, unsigned long *phys_pfn);
-extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
- int npage);
+ extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
+ int npage);
These functions call back into the back-end IOMMU module by using the pin_pages
and unpin_pages callbacks of the struct vfio_iommu_driver_ops[4]. Currently
@@ -304,81 +313,80 @@ card.
This step creates a dummy device, /sys/devices/virtual/mtty/mtty/
- Files in this device directory in sysfs are similar to the following:
+ Files in this device directory in sysfs are similar to the following::
- # tree /sys/devices/virtual/mtty/mtty/
- /sys/devices/virtual/mtty/mtty/
- |-- mdev_supported_types
- | |-- mtty-1
- | | |-- available_instances
- | | |-- create
- | | |-- device_api
- | | |-- devices
- | | `-- name
- | `-- mtty-2
- | |-- available_instances
- | |-- create
- | |-- device_api
- | |-- devices
- | `-- name
- |-- mtty_dev
- | `-- sample_mtty_dev
- |-- power
- | |-- autosuspend_delay_ms
- | |-- control
- | |-- runtime_active_time
- | |-- runtime_status
- | `-- runtime_suspended_time
- |-- subsystem -> ../../../../class/mtty
- `-- uevent
+ # tree /sys/devices/virtual/mtty/mtty/
+ /sys/devices/virtual/mtty/mtty/
+ |-- mdev_supported_types
+ | |-- mtty-1
+ | | |-- available_instances
+ | | |-- create
+ | | |-- device_api
+ | | |-- devices
+ | | `-- name
+ | `-- mtty-2
+ | |-- available_instances
+ | |-- create
+ | |-- device_api
+ | |-- devices
+ | `-- name
+ |-- mtty_dev
+ | `-- sample_mtty_dev
+ |-- power
+ | |-- autosuspend_delay_ms
+ | |-- control
+ | |-- runtime_active_time
+ | |-- runtime_status
+ | `-- runtime_suspended_time
+ |-- subsystem -> ../../../../class/mtty
+ `-- uevent
2. Create a mediated device by using the dummy device that you created in the
- previous step.
+ previous step::
- # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \
+ # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \
/sys/devices/virtual/mtty/mtty/mdev_supported_types/mtty-2/create
-3. Add parameters to qemu-kvm.
+3. Add parameters to qemu-kvm::
- -device vfio-pci,\
- sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
+ -device vfio-pci,\
+ sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
4. Boot the VM.
In the Linux guest VM, with no hardware on the host, the device appears
- as follows:
+ as follows::
- # lspci -s 00:05.0 -xxvv
- 00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
- Subsystem: Device 4348:3253
- Physical Slot: 5
- Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
- Stepping- SERR- FastB2B- DisINTx-
- Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
- <TAbort- <MAbort- >SERR- <PERR- INTx-
- Interrupt: pin A routed to IRQ 10
- Region 0: I/O ports at c150 [size=8]
- Region 1: I/O ports at c158 [size=8]
- Kernel driver in use: serial
- 00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
- 10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
- 20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
- 30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
+ # lspci -s 00:05.0 -xxvv
+ 00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
+ Subsystem: Device 4348:3253
+ Physical Slot: 5
+ Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
+ Stepping- SERR- FastB2B- DisINTx-
+ Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
+ <TAbort- <MAbort- >SERR- <PERR- INTx-
+ Interrupt: pin A routed to IRQ 10
+ Region 0: I/O ports at c150 [size=8]
+ Region 1: I/O ports at c158 [size=8]
+ Kernel driver in use: serial
+ 00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
+ 10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
+ 20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
+ 30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
- In the Linux guest VM, dmesg output for the device is as follows:
+ In the Linux guest VM, dmesg output for the device is as follows:
- serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ
-10
- 0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
- 0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
+ serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ 10
+ 0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
+ 0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
-5. In the Linux guest VM, check the serial ports.
+5. In the Linux guest VM, check the serial ports::
- # setserial -g /dev/ttyS*
- /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
- /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
- /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
+ # setserial -g /dev/ttyS*
+ /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
+ /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
+ /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
6. Using minicom or any terminal emulation program, open port /dev/ttyS1 or
/dev/ttyS2 with hardware flow control disabled.
@@ -388,14 +396,14 @@ card.
Data is loop backed from hosts mtty driver.
-8. Destroy the mediated device that you created.
+8. Destroy the mediated device that you created::
- # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
+ # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
References
==========
-[1] See Documentation/vfio.txt for more information on VFIO.
-[2] struct mdev_driver in include/linux/mdev.h
-[3] struct mdev_parent_ops in include/linux/mdev.h
-[4] struct vfio_iommu_driver_ops in include/linux/vfio.h
+1. See Documentation/vfio.txt for more information on VFIO.
+2. struct mdev_driver in include/linux/mdev.h
+3. struct mdev_parent_ops in include/linux/mdev.h
+4. struct vfio_iommu_driver_ops in include/linux/vfio.h
--
2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Kirti Wankhede <kwankhede@nvidia.com> |
|---|---|
| Date | 2017-05-22 21:50 +0200 |
| Subject | Re: [PATCH 23/29] vfio-mediated-device.txt: standardize document format |
| Message-ID | <tK1v4-1nY-31@gated-at.bofh.it> |
| In reply to | #1645046 |
On 5/19/2017 6:56 AM, Mauro Carvalho Chehab wrote:
> Each text file under Documentation follows a different
> format. Some doesn't even have titles!
>
> In this specific document, the title, copyright and authorship
> are added as if it were a C file!
>
> Change its representation to follow the adopted standard,
> using ReST markups for it to be parseable by Sphinx:
> - convert document preambule to the proper format;
> - mark literal blocks;
> - adjust identation;
> - use numbered lists for references.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Looks good to me.
Reviewed by: Kirti Wankhede <kwankhede@nvidia.com>
Thanks,
Kirti
> ---
> Documentation/vfio-mediated-device.txt | 252 +++++++++++++++++----------------
> 1 file changed, 130 insertions(+), 122 deletions(-)
>
> diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.txt
> index e5e57b40f8af..1b3950346532 100644
> --- a/Documentation/vfio-mediated-device.txt
> +++ b/Documentation/vfio-mediated-device.txt
> @@ -1,14 +1,17 @@
> -/*
> - * VFIO Mediated devices
> - *
> - * Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
> - * Author: Neo Jia <cjia@nvidia.com>
> - * Kirti Wankhede <kwankhede@nvidia.com>
> - *
> - * This program is free software; you can redistribute it and/or modify
> - * it under the terms of the GNU General Public License version 2 as
> - * published by the Free Software Foundation.
> - */
> +.. include:: <isonum.txt>
> +
> +=====================
> +VFIO Mediated devices
> +=====================
> +
> +:Copyright: |copy| 2016, NVIDIA CORPORATION. All rights reserved.
> +:Author: Neo Jia <cjia@nvidia.com>
> +:Author: Kirti Wankhede <kwankhede@nvidia.com>
> +
> +This program is free software; you can redistribute it and/or modify
> +it under the terms of the GNU General Public License version 2 as
> +published by the Free Software Foundation.
> +
>
> Virtual Function I/O (VFIO) Mediated devices[1]
> ===============================================
> @@ -42,7 +45,7 @@ removes it from a VFIO group.
>
> The following high-level block diagram shows the main components and interfaces
> in the VFIO mediated driver framework. The diagram shows NVIDIA, Intel, and IBM
> -devices as examples, as these devices are the first devices to use this module.
> +devices as examples, as these devices are the first devices to use this module::
>
> +---------------+
> | |
> @@ -91,7 +94,7 @@ Registration Interface for a Mediated Bus Driver
> ------------------------------------------------
>
> The registration interface for a mediated bus driver provides the following
> -structure to represent a mediated device's driver:
> +structure to represent a mediated device's driver::
>
> /*
> * struct mdev_driver [2] - Mediated device's driver
> @@ -110,14 +113,14 @@ structure to represent a mediated device's driver:
> A mediated bus driver for mdev should use this structure in the function calls
> to register and unregister itself with the core driver:
>
> -* Register:
> +* Register::
>
> - extern int mdev_register_driver(struct mdev_driver *drv,
> + extern int mdev_register_driver(struct mdev_driver *drv,
> struct module *owner);
>
> -* Unregister:
> +* Unregister::
>
> - extern void mdev_unregister_driver(struct mdev_driver *drv);
> + extern void mdev_unregister_driver(struct mdev_driver *drv);
>
> The mediated bus driver is responsible for adding mediated devices to the VFIO
> group when devices are bound to the driver and removing mediated devices from
> @@ -152,15 +155,15 @@ The callbacks in the mdev_parent_ops structure are as follows:
> * mmap: mmap emulation callback
>
> A driver should use the mdev_parent_ops structure in the function call to
> -register itself with the mdev core driver:
> +register itself with the mdev core driver::
>
> -extern int mdev_register_device(struct device *dev,
> - const struct mdev_parent_ops *ops);
> + extern int mdev_register_device(struct device *dev,
> + const struct mdev_parent_ops *ops);
>
> However, the mdev_parent_ops structure is not required in the function call
> -that a driver should use to unregister itself with the mdev core driver:
> +that a driver should use to unregister itself with the mdev core driver::
>
> -extern void mdev_unregister_device(struct device *dev);
> + extern void mdev_unregister_device(struct device *dev);
>
>
> Mediated Device Management Interface Through sysfs
> @@ -183,30 +186,32 @@ with the mdev core driver.
> Directories and files under the sysfs for Each Physical Device
> --------------------------------------------------------------
>
> -|- [parent physical device]
> -|--- Vendor-specific-attributes [optional]
> -|--- [mdev_supported_types]
> -| |--- [<type-id>]
> -| | |--- create
> -| | |--- name
> -| | |--- available_instances
> -| | |--- device_api
> -| | |--- description
> -| | |--- [devices]
> -| |--- [<type-id>]
> -| | |--- create
> -| | |--- name
> -| | |--- available_instances
> -| | |--- device_api
> -| | |--- description
> -| | |--- [devices]
> -| |--- [<type-id>]
> -| |--- create
> -| |--- name
> -| |--- available_instances
> -| |--- device_api
> -| |--- description
> -| |--- [devices]
> +::
> +
> + |- [parent physical device]
> + |--- Vendor-specific-attributes [optional]
> + |--- [mdev_supported_types]
> + | |--- [<type-id>]
> + | | |--- create
> + | | |--- name
> + | | |--- available_instances
> + | | |--- device_api
> + | | |--- description
> + | | |--- [devices]
> + | |--- [<type-id>]
> + | | |--- create
> + | | |--- name
> + | | |--- available_instances
> + | | |--- device_api
> + | | |--- description
> + | | |--- [devices]
> + | |--- [<type-id>]
> + | |--- create
> + | |--- name
> + | |--- available_instances
> + | |--- device_api
> + | |--- description
> + | |--- [devices]
>
> * [mdev_supported_types]
>
> @@ -219,12 +224,12 @@ Directories and files under the sysfs for Each Physical Device
>
> The [<type-id>] name is created by adding the device driver string as a prefix
> to the string provided by the vendor driver. This format of this name is as
> - follows:
> + follows::
>
> sprintf(buf, "%s-%s", dev_driver_string(parent->dev), group->name);
>
> (or using mdev_parent_dev(mdev) to arrive at the parent device outside
> - of the core mdev code)
> + of the core mdev code)
>
> * device_api
>
> @@ -239,7 +244,7 @@ Directories and files under the sysfs for Each Physical Device
> * [device]
>
> This directory contains links to the devices of type <type-id> that have been
> -created.
> + created.
>
> * name
>
> @@ -253,21 +258,25 @@ created.
> Directories and Files Under the sysfs for Each mdev Device
> ----------------------------------------------------------
>
> -|- [parent phy device]
> -|--- [$MDEV_UUID]
> +::
> +
> + |- [parent phy device]
> + |--- [$MDEV_UUID]
> |--- remove
> |--- mdev_type {link to its type}
> |--- vendor-specific-attributes [optional]
>
> * remove (write only)
> +
> Writing '1' to the 'remove' file destroys the mdev device. The vendor driver can
> fail the remove() callback if that device is active and the vendor driver
> doesn't support hot unplug.
>
> -Example:
> +Example::
> +
> # echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove
>
> -Mediated device Hot plug:
> +Mediated device Hot plug
> ------------------------
>
> Mediated devices can be created and assigned at runtime. The procedure to hot
> @@ -277,13 +286,13 @@ Translation APIs for Mediated Devices
> =====================================
>
> The following APIs are provided for translating user pfn to host pfn in a VFIO
> -driver:
> +driver::
>
> -extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
> - int npage, int prot, unsigned long *phys_pfn);
> + extern int vfio_pin_pages(struct device *dev, unsigned long *user_pfn,
> + int npage, int prot, unsigned long *phys_pfn);
>
> -extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
> - int npage);
> + extern int vfio_unpin_pages(struct device *dev, unsigned long *user_pfn,
> + int npage);
>
> These functions call back into the back-end IOMMU module by using the pin_pages
> and unpin_pages callbacks of the struct vfio_iommu_driver_ops[4]. Currently
> @@ -304,81 +313,80 @@ card.
>
> This step creates a dummy device, /sys/devices/virtual/mtty/mtty/
>
> - Files in this device directory in sysfs are similar to the following:
> + Files in this device directory in sysfs are similar to the following::
>
> - # tree /sys/devices/virtual/mtty/mtty/
> - /sys/devices/virtual/mtty/mtty/
> - |-- mdev_supported_types
> - | |-- mtty-1
> - | | |-- available_instances
> - | | |-- create
> - | | |-- device_api
> - | | |-- devices
> - | | `-- name
> - | `-- mtty-2
> - | |-- available_instances
> - | |-- create
> - | |-- device_api
> - | |-- devices
> - | `-- name
> - |-- mtty_dev
> - | `-- sample_mtty_dev
> - |-- power
> - | |-- autosuspend_delay_ms
> - | |-- control
> - | |-- runtime_active_time
> - | |-- runtime_status
> - | `-- runtime_suspended_time
> - |-- subsystem -> ../../../../class/mtty
> - `-- uevent
> + # tree /sys/devices/virtual/mtty/mtty/
> + /sys/devices/virtual/mtty/mtty/
> + |-- mdev_supported_types
> + | |-- mtty-1
> + | | |-- available_instances
> + | | |-- create
> + | | |-- device_api
> + | | |-- devices
> + | | `-- name
> + | `-- mtty-2
> + | |-- available_instances
> + | |-- create
> + | |-- device_api
> + | |-- devices
> + | `-- name
> + |-- mtty_dev
> + | `-- sample_mtty_dev
> + |-- power
> + | |-- autosuspend_delay_ms
> + | |-- control
> + | |-- runtime_active_time
> + | |-- runtime_status
> + | `-- runtime_suspended_time
> + |-- subsystem -> ../../../../class/mtty
> + `-- uevent
>
> 2. Create a mediated device by using the dummy device that you created in the
> - previous step.
> + previous step::
>
> - # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \
> + # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" > \
> /sys/devices/virtual/mtty/mtty/mdev_supported_types/mtty-2/create
>
> -3. Add parameters to qemu-kvm.
> +3. Add parameters to qemu-kvm::
>
> - -device vfio-pci,\
> - sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
> + -device vfio-pci,\
> + sysfsdev=/sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001
>
> 4. Boot the VM.
>
> In the Linux guest VM, with no hardware on the host, the device appears
> - as follows:
> + as follows::
>
> - # lspci -s 00:05.0 -xxvv
> - 00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
> - Subsystem: Device 4348:3253
> - Physical Slot: 5
> - Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
> - Stepping- SERR- FastB2B- DisINTx-
> - Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
> - <TAbort- <MAbort- >SERR- <PERR- INTx-
> - Interrupt: pin A routed to IRQ 10
> - Region 0: I/O ports at c150 [size=8]
> - Region 1: I/O ports at c158 [size=8]
> - Kernel driver in use: serial
> - 00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
> - 10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
> - 20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
> - 30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
> + # lspci -s 00:05.0 -xxvv
> + 00:05.0 Serial controller: Device 4348:3253 (rev 10) (prog-if 02 [16550])
> + Subsystem: Device 4348:3253
> + Physical Slot: 5
> + Control: I/O+ Mem- BusMaster- SpecCycle- MemWINV- VGASnoop- ParErr-
> + Stepping- SERR- FastB2B- DisINTx-
> + Status: Cap- 66MHz- UDF- FastB2B- ParErr- DEVSEL=medium >TAbort-
> + <TAbort- <MAbort- >SERR- <PERR- INTx-
> + Interrupt: pin A routed to IRQ 10
> + Region 0: I/O ports at c150 [size=8]
> + Region 1: I/O ports at c158 [size=8]
> + Kernel driver in use: serial
> + 00: 48 43 53 32 01 00 00 02 10 02 00 07 00 00 00 00
> + 10: 51 c1 00 00 59 c1 00 00 00 00 00 00 00 00 00 00
> + 20: 00 00 00 00 00 00 00 00 00 00 00 00 48 43 53 32
> + 30: 00 00 00 00 00 00 00 00 00 00 00 00 0a 01 00 00
>
> - In the Linux guest VM, dmesg output for the device is as follows:
> + In the Linux guest VM, dmesg output for the device is as follows:
>
> - serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ
> -10
> - 0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
> - 0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
> + serial 0000:00:05.0: PCI INT A -> Link[LNKA] -> GSI 10 (level, high) -> IRQ 10
> + 0000:00:05.0: ttyS1 at I/O 0xc150 (irq = 10) is a 16550A
> + 0000:00:05.0: ttyS2 at I/O 0xc158 (irq = 10) is a 16550A
>
>
> -5. In the Linux guest VM, check the serial ports.
> +5. In the Linux guest VM, check the serial ports::
>
> - # setserial -g /dev/ttyS*
> - /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
> - /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
> - /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
> + # setserial -g /dev/ttyS*
> + /dev/ttyS0, UART: 16550A, Port: 0x03f8, IRQ: 4
> + /dev/ttyS1, UART: 16550A, Port: 0xc150, IRQ: 10
> + /dev/ttyS2, UART: 16550A, Port: 0xc158, IRQ: 10
>
> 6. Using minicom or any terminal emulation program, open port /dev/ttyS1 or
> /dev/ttyS2 with hardware flow control disabled.
> @@ -388,14 +396,14 @@ card.
>
> Data is loop backed from hosts mtty driver.
>
> -8. Destroy the mediated device that you created.
> +8. Destroy the mediated device that you created::
>
> - # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
> + # echo 1 > /sys/bus/mdev/devices/83b8f4f2-509f-382f-3c1e-e6bfe0fa1001/remove
>
> References
> ==========
>
> -[1] See Documentation/vfio.txt for more information on VFIO.
> -[2] struct mdev_driver in include/linux/mdev.h
> -[3] struct mdev_parent_ops in include/linux/mdev.h
> -[4] struct vfio_iommu_driver_ops in include/linux/vfio.h
> +1. See Documentation/vfio.txt for more information on VFIO.
> +2. struct mdev_driver in include/linux/mdev.h
> +3. struct mdev_parent_ops in include/linux/mdev.h
> +4. struct vfio_iommu_driver_ops in include/linux/vfio.h
>
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 19/29] svga.txt: standardize document format |
| Message-ID | <tIF3A-3cN-15@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Use standard notation for titles;
- Use the note mark;
- mark literal blocks;
- adjust identation;
- mark the table.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/svga.txt | 146 +++++++++++++++++++++++++++----------------------
1 file changed, 80 insertions(+), 66 deletions(-)
diff --git a/Documentation/svga.txt b/Documentation/svga.txt
index cd66ec836e4f..119f1515b1ac 100644
--- a/Documentation/svga.txt
+++ b/Documentation/svga.txt
@@ -1,24 +1,31 @@
- Video Mode Selection Support 2.13
- (c) 1995--1999 Martin Mares, <mj@ucw.cz>
---------------------------------------------------------------------------------
+.. include:: <isonum.txt>
-1. Intro
-~~~~~~~~
- This small document describes the "Video Mode Selection" feature which
+=================================
+Video Mode Selection Support 2.13
+=================================
+
+:Copyright: |copy| 1995--1999 Martin Mares, <mj@ucw.cz>
+
+Intro
+~~~~~
+
+This small document describes the "Video Mode Selection" feature which
allows the use of various special video modes supported by the video BIOS. Due
to usage of the BIOS, the selection is limited to boot time (before the
kernel decompression starts) and works only on 80X86 machines.
- ** Short intro for the impatient: Just use vga=ask for the first time,
- ** enter `scan' on the video mode prompt, pick the mode you want to use,
- ** remember its mode ID (the four-digit hexadecimal number) and then
- ** set the vga parameter to this number (converted to decimal first).
+.. note::
- The video mode to be used is selected by a kernel parameter which can be
+ Short intro for the impatient: Just use vga=ask for the first time,
+ enter ``scan`` on the video mode prompt, pick the mode you want to use,
+ remember its mode ID (the four-digit hexadecimal number) and then
+ set the vga parameter to this number (converted to decimal first).
+
+The video mode to be used is selected by a kernel parameter which can be
specified in the kernel Makefile (the SVGA_MODE=... line) or by the "vga=..."
option of LILO (or some other boot loader you use) or by the "vidmode" utility
(present in standard Linux utility packages). You can use the following values
-of this parameter:
+of this parameter::
NORMAL_VGA - Standard 80x25 mode available on all display adapters.
@@ -37,77 +44,79 @@ of this parameter:
for exact meaning of the ID). Warning: rdev and LILO don't support
hexadecimal numbers -- you have to convert it to decimal manually.
-2. Menu
-~~~~~~~
- The ASK_VGA mode causes the kernel to offer a video mode menu upon
+Menu
+~~~~
+
+The ASK_VGA mode causes the kernel to offer a video mode menu upon
bootup. It displays a "Press <RETURN> to see video modes available, <SPACE>
to continue or wait 30 secs" message. If you press <RETURN>, you enter the
menu, if you press <SPACE> or wait 30 seconds, the kernel will boot up in
the standard 80x25 mode.
- The menu looks like:
+The menu looks like::
-Video adapter: <name-of-detected-video-adapter>
-Mode: COLSxROWS:
-0 0F00 80x25
-1 0F01 80x50
-2 0F02 80x43
-3 0F03 80x26
-....
-Enter mode number or `scan': <flashing-cursor-here>
+ Video adapter: <name-of-detected-video-adapter>
+ Mode: COLSxROWS:
+ 0 0F00 80x25
+ 1 0F01 80x50
+ 2 0F02 80x43
+ 3 0F03 80x26
+ ....
+ Enter mode number or ``scan``: <flashing-cursor-here>
- <name-of-detected-video-adapter> tells what video adapter did Linux detect
+<name-of-detected-video-adapter> tells what video adapter did Linux detect
-- it's either a generic adapter name (MDA, CGA, HGC, EGA, VGA, VESA VGA [a VGA
with VESA-compliant BIOS]) or a chipset name (e.g., Trident). Direct detection
of chipsets is turned off by default (see CONFIG_VIDEO_SVGA in chapter 4 to see
how to enable it if you really want) as it's inherently unreliable due to
absolutely insane PC design.
- "0 0F00 80x25" means that the first menu item (the menu items are numbered
+"0 0F00 80x25" means that the first menu item (the menu items are numbered
from "0" to "9" and from "a" to "z") is a 80x25 mode with ID=0x0f00 (see the
next section for a description of mode IDs).
- <flashing-cursor-here> encourages you to enter the item number or mode ID
+<flashing-cursor-here> encourages you to enter the item number or mode ID
you wish to set and press <RETURN>. If the computer complains something about
"Unknown mode ID", it is trying to tell you that it isn't possible to set such
a mode. It's also possible to press only <RETURN> which leaves the current mode.
- The mode list usually contains a few basic modes and some VESA modes. In
+The mode list usually contains a few basic modes and some VESA modes. In
case your chipset has been detected, some chipset-specific modes are shown as
well (some of these might be missing or unusable on your machine as different
BIOSes are often shipped with the same card and the mode numbers depend purely
on the VGA BIOS).
- The modes displayed on the menu are partially sorted: The list starts with
+The modes displayed on the menu are partially sorted: The list starts with
the standard modes (80x25 and 80x50) followed by "special" modes (80x28 and
80x43), local modes (if the local modes feature is enabled), VESA modes and
finally SVGA modes for the auto-detected adapter.
- If you are not happy with the mode list offered (e.g., if you think your card
+If you are not happy with the mode list offered (e.g., if you think your card
is able to do more), you can enter "scan" instead of item number / mode ID. The
program will try to ask the BIOS for all possible video mode numbers and test
what happens then. The screen will be probably flashing wildly for some time and
strange noises will be heard from inside the monitor and so on and then, really
all consistent video modes supported by your BIOS will appear (plus maybe some
-`ghost modes'). If you are afraid this could damage your monitor, don't use this
-function.
+``ghost modes``). If you are afraid this could damage your monitor, don't use
+this function.
- After scanning, the mode ordering is a bit different: the auto-detected SVGA
-modes are not listed at all and the modes revealed by `scan' are shown before
+After scanning, the mode ordering is a bit different: the auto-detected SVGA
+modes are not listed at all and the modes revealed by ``scan`` are shown before
all VESA modes.
-3. Mode IDs
-~~~~~~~~~~~
- Because of the complexity of all the video stuff, the video mode IDs
+Mode IDs
+~~~~~~~~
+
+Because of the complexity of all the video stuff, the video mode IDs
used here are also a bit complex. A video mode ID is a 16-bit number usually
expressed in a hexadecimal notation (starting with "0x"). You can set a mode
by entering its mode directly if you know it even if it isn't shown on the menu.
-The ID numbers can be divided to three regions:
+The ID numbers can be divided to those regions::
0x0000 to 0x00ff - menu item references. 0x0000 is the first item. Don't use
outside the menu as this can change from boot to boot (especially if you
- have used the `scan' feature).
+ have used the ``scan`` feature).
0x0100 to 0x017f - standard BIOS modes. The ID is a BIOS video mode number
(as presented to INT 10, function 00) increased by 0x0100.
@@ -142,53 +151,54 @@ The ID numbers can be divided to three regions:
0xffff equivalent to 0x0f00 (standard 80x25)
0xfffe equivalent to 0x0f01 (EGA 80x43 or VGA 80x50)
- If you add 0x8000 to the mode ID, the program will try to recalculate
+If you add 0x8000 to the mode ID, the program will try to recalculate
vertical display timing according to mode parameters, which can be used to
eliminate some annoying bugs of certain VGA BIOSes (usually those used for
cards with S3 chipsets and old Cirrus Logic BIOSes) -- mainly extra lines at the
end of the display.
-4. Options
-~~~~~~~~~~
- Some options can be set in the source text (in arch/i386/boot/video.S).
+Options
+~~~~~~~
+
+Some options can be set in the source text (in arch/i386/boot/video.S).
All of them are simple #define's -- change them to #undef's when you want to
switch them off. Currently supported:
- CONFIG_VIDEO_SVGA - enables autodetection of SVGA cards. This is switched
+CONFIG_VIDEO_SVGA - enables autodetection of SVGA cards. This is switched
off by default as it's a bit unreliable due to terribly bad PC design. If you
-really want to have the adapter autodetected (maybe in case the `scan' feature
+really want to have the adapter autodetected (maybe in case the ``scan`` feature
doesn't work on your machine), switch this on and don't cry if the results
are not completely sane. In case you really need this feature, please drop me
a mail as I think of removing it some day.
- CONFIG_VIDEO_VESA - enables autodetection of VESA modes. If it doesn't work
+CONFIG_VIDEO_VESA - enables autodetection of VESA modes. If it doesn't work
on your machine (or displays a "Error: Scanning of VESA modes failed" message),
you can switch it off and report as a bug.
- CONFIG_VIDEO_COMPACT - enables compacting of the video mode list. If there
+CONFIG_VIDEO_COMPACT - enables compacting of the video mode list. If there
are more modes with the same screen size, only the first one is kept (see above
for more info on mode ordering). However, in very strange cases it's possible
that the first "version" of the mode doesn't work although some of the others
do -- in this case turn this switch off to see the rest.
- CONFIG_VIDEO_RETAIN - enables retaining of screen contents when switching
+CONFIG_VIDEO_RETAIN - enables retaining of screen contents when switching
video modes. Works only with some boot loaders which leave enough room for the
buffer. (If you have old LILO, you can adjust heap_end_ptr and loadflags
in setup.S, but it's better to upgrade the boot loader...)
- CONFIG_VIDEO_LOCAL - enables inclusion of "local modes" in the list. The
+CONFIG_VIDEO_LOCAL - enables inclusion of "local modes" in the list. The
local modes are added automatically to the beginning of the list not depending
on hardware configuration. The local modes are listed in the source text after
the "local_mode_table:" line. The comment before this line describes the format
of the table (which also includes a video card name to be displayed on the
top of the menu).
- CONFIG_VIDEO_400_HACK - force setting of 400 scan lines for standard VGA
+CONFIG_VIDEO_400_HACK - force setting of 400 scan lines for standard VGA
modes. This option is intended to be used on certain buggy BIOSes which draw
some useless logo using font download and then fail to reset the correct mode.
Don't use unless needed as it forces resetting the video card.
- CONFIG_VIDEO_GFX_HACK - includes special hack for setting of graphics modes
+CONFIG_VIDEO_GFX_HACK - includes special hack for setting of graphics modes
to be used later by special drivers (e.g., 800x600 on IBM ThinkPad -- see
ftp://ftp.phys.keio.ac.jp/pub/XFree86/800x600/XF86Configs/XF86Config.IBM_TP560).
Allows to set _any_ BIOS mode including graphic ones and forcing specific
@@ -196,33 +206,36 @@ text screen resolution instead of peeking it from BIOS variables. Don't use
unless you think you know what you're doing. To activate this setup, use
mode number 0x0f08 (see section 3).
-5. Still doesn't work?
-~~~~~~~~~~~~~~~~~~~~~~
- When the mode detection doesn't work (e.g., the mode list is incorrect or
+Still doesn't work?
+~~~~~~~~~~~~~~~~~~~
+
+When the mode detection doesn't work (e.g., the mode list is incorrect or
the machine hangs instead of displaying the menu), try to switch off some of
the configuration options listed in section 4. If it fails, you can still use
your kernel with the video mode set directly via the kernel parameter.
- In either case, please send me a bug report containing what _exactly_
+In either case, please send me a bug report containing what _exactly_
happens and how do the configuration switches affect the behaviour of the bug.
- If you start Linux from M$-DOS, you might also use some DOS tools for
+If you start Linux from M$-DOS, you might also use some DOS tools for
video mode setting. In this case, you must specify the 0x0f04 mode ("leave
current settings") to Linux, because if you don't and you use any non-standard
mode, Linux will switch to 80x25 automatically.
- If you set some extended mode and there's one or more extra lines on the
+If you set some extended mode and there's one or more extra lines on the
bottom of the display containing already scrolled-out text, your VGA BIOS
contains the most common video BIOS bug called "incorrect vertical display
end setting". Adding 0x8000 to the mode ID might fix the problem. Unfortunately,
this must be done manually -- no autodetection mechanisms are available.
- If you have a VGA card and your display still looks as on EGA, your BIOS
+If you have a VGA card and your display still looks as on EGA, your BIOS
is probably broken and you need to set the CONFIG_VIDEO_400_HACK switch to
force setting of the correct mode.
-6. History
-~~~~~~~~~~
+History
+~~~~~~~
+
+=============== ================================================================
1.0 (??-Nov-95) First version supporting all adapters supported by the old
setup.S + Cirrus Logic 54XX. Present in some 1.3.4? kernels
and then removed due to instability on some machines.
@@ -260,17 +273,18 @@ force setting of the correct mode.
original version written by hhanemaa@cs.ruu.nl, patched by
Jeff Chua, rewritten by me).
- Screen store/restore fixed.
-2.8 (14-Apr-96) - Previous release was not compilable without CONFIG_VIDEO_SVGA.
+2.8 (14-Apr-96) - Previous release was not compilable without CONFIG_VIDEO_SVGA.
- Better recognition of text modes during mode scan.
2.9 (12-May-96) - Ignored VESA modes 0x80 - 0xff (more VESA BIOS bugs!)
-2.10 (11-Nov-96)- The whole thing made optional.
+2.10(11-Nov-96) - The whole thing made optional.
- Added the CONFIG_VIDEO_400_HACK switch.
- Added the CONFIG_VIDEO_GFX_HACK switch.
- Code cleanup.
-2.11 (03-May-97)- Yet another cleanup, now including also the documentation.
- - Direct testing of SVGA adapters turned off by default, `scan'
+2.11(03-May-97) - Yet another cleanup, now including also the documentation.
+ - Direct testing of SVGA adapters turned off by default, ``scan``
offered explicitly on the prompt line.
- Removed the doc section describing adding of new probing
functions as I try to get rid of _all_ hardware probing here.
-2.12 (25-May-98)- Added support for VESA frame buffer graphics.
-2.13 (14-May-99)- Minor documentation fixes.
+2.12(25-May-98) Added support for VESA frame buffer graphics.
+2.13(14-May-99) Minor documentation fixes.
+=============== ================================================================
--
2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Martin Mares <mj@ucw.cz> |
|---|---|
| Date | 2017-05-19 16:10 +0200 |
| Subject | Re: [PATCH 19/29] svga.txt: standardize document format |
| Message-ID | <tIQLo-3eE-5@gated-at.bofh.it> |
| In reply to | #1645048 |
> diff --git a/Documentation/svga.txt b/Documentation/svga.txt > index cd66ec836e4f..119f1515b1ac 100644 > --- a/Documentation/svga.txt > +++ b/Documentation/svga.txt > @@ -1,24 +1,31 @@ Acked-By: Martin Mares <mj@ucw.cz> Have a nice fortnight -- Martin `MJ' Mares <mj@ucw.cz> http://mj.ucw.cz/ Faculty of Math and Physics, Charles University, Prague, Czech Rep., Earth Press any key to quit or any other key to continue
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 09/29] robust-futex-ABI.txt: standardize document format |
| Message-ID | <tIF3A-3cN-19@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- promote document title;
- use :Author: for authorship;
- mark literal blocks;
- add blank lines.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/robust-futex-ABI.txt | 14 +++++++++-----
1 file changed, 9 insertions(+), 5 deletions(-)
diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/robust-futex-ABI.txt
index 16eb314f56cc..8a5d34abf726 100644
--- a/Documentation/robust-futex-ABI.txt
+++ b/Documentation/robust-futex-ABI.txt
@@ -1,7 +1,9 @@
-Started by Paul Jackson <pj@sgi.com>
-
+====================
The robust futex ABI
---------------------
+====================
+
+:Author: Started by Paul Jackson <pj@sgi.com>
+
Robust_futexes provide a mechanism that is used in addition to normal
futexes, for kernel assist of cleanup of held locks on task exit.
@@ -32,7 +34,7 @@ probably causing deadlock or other such failure of the other threads
waiting on the same locks.
A thread that anticipates possibly using robust_futexes should first
-issue the system call:
+issue the system call::
asmlinkage long
sys_set_robust_list(struct robust_list_head __user *head, size_t len);
@@ -91,7 +93,7 @@ that lock using the futex mechanism.
When a thread has invoked the above system call to indicate it
anticipates using robust_futexes, the kernel stores the passed in 'head'
pointer for that task. The task may retrieve that value later on by
-using the system call:
+using the system call::
asmlinkage long
sys_get_robust_list(int pid, struct robust_list_head __user **head_ptr,
@@ -135,6 +137,7 @@ manipulating this list), the user code must observe the following
protocol on 'lock entry' insertion and removal:
On insertion:
+
1) set the 'list_op_pending' word to the address of the 'lock entry'
to be inserted,
2) acquire the futex lock,
@@ -143,6 +146,7 @@ On insertion:
4) clear the 'list_op_pending' word.
On removal:
+
1) set the 'list_op_pending' word to the address of the 'lock entry'
to be removed,
2) remove the lock entry for this lock from the 'head' list,
--
2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 06/29] rbtree.txt: standardize document format |
| Message-ID | <tIF3A-3cN-21@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Mark document title;
- Use :Author: for authorship;
- mark a sub-section title as such;
- mark literal blocks;
- adjust identation where needed.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/rbtree.txt | 88 +++++++++++++++++++++++++-----------------------
1 file changed, 46 insertions(+), 42 deletions(-)
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt
index b9d9cc57be18..b8a8c70b0188 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.txt
@@ -1,7 +1,10 @@
+=================================
Red-black Trees (rbtree) in Linux
-January 18, 2007
-Rob Landley <rob@landley.net>
-=============================
+=================================
+
+
+:Date: January 18, 2007
+:Author: Rob Landley <rob@landley.net>
What are red-black trees, and what are they for?
------------------------------------------------
@@ -56,7 +59,7 @@ user of the rbtree code.
Creating a new rbtree
---------------------
-Data nodes in an rbtree tree are structures containing a struct rb_node member:
+Data nodes in an rbtree tree are structures containing a struct rb_node member::
struct mytype {
struct rb_node node;
@@ -78,7 +81,7 @@ Searching for a value in an rbtree
Writing a search function for your tree is fairly straightforward: start at the
root, compare each value, and follow the left or right branch as necessary.
-Example:
+Example::
struct mytype *my_search(struct rb_root *root, char *string)
{
@@ -110,7 +113,7 @@ The search for insertion differs from the previous search by finding the
location of the pointer on which to graft the new node. The new node also
needs a link to its parent node for rebalancing purposes.
-Example:
+Example::
int my_insert(struct rb_root *root, struct mytype *data)
{
@@ -140,11 +143,11 @@ Example:
Removing or replacing existing data in an rbtree
------------------------------------------------
-To remove an existing node from a tree, call:
+To remove an existing node from a tree, call::
void rb_erase(struct rb_node *victim, struct rb_root *tree);
-Example:
+Example::
struct mytype *data = mysearch(&mytree, "walrus");
@@ -153,7 +156,7 @@ Example:
myfree(data);
}
-To replace an existing node in a tree with a new one with the same key, call:
+To replace an existing node in a tree with a new one with the same key, call::
void rb_replace_node(struct rb_node *old, struct rb_node *new,
struct rb_root *tree);
@@ -166,7 +169,7 @@ Iterating through the elements stored in an rbtree (in sort order)
Four functions are provided for iterating through an rbtree's contents in
sorted order. These work on arbitrary trees, and should not need to be
-modified or wrapped (except for locking purposes):
+modified or wrapped (except for locking purposes)::
struct rb_node *rb_first(struct rb_root *tree);
struct rb_node *rb_last(struct rb_root *tree);
@@ -184,7 +187,7 @@ which the containing data structure may be accessed with the container_of()
macro, and individual members may be accessed directly via
rb_entry(node, type, member).
-Example:
+Example::
struct rb_node *node;
for (node = rb_first(&mytree); node; node = rb_next(node))
@@ -241,7 +244,8 @@ user should have a single rb_erase_augmented() call site in order to limit
compiled code size.
-Sample usage:
+Sample usage
+^^^^^^^^^^^^
Interval tree is an example of augmented rb tree. Reference -
"Introduction to Algorithms" by Cormen, Leiserson, Rivest and Stein.
@@ -259,12 +263,12 @@ This "extra information" stored in each node is the maximum hi
information can be maintained at each node just be looking at the node
and its immediate children. And this will be used in O(log n) lookup
for lowest match (lowest start address among all possible matches)
-with something like:
+with something like::
-struct interval_tree_node *
-interval_tree_first_match(struct rb_root *root,
- unsigned long start, unsigned long last)
-{
+ struct interval_tree_node *
+ interval_tree_first_match(struct rb_root *root,
+ unsigned long start, unsigned long last)
+ {
struct interval_tree_node *node;
if (!root->rb_node)
@@ -301,13 +305,13 @@ interval_tree_first_match(struct rb_root *root,
}
return NULL; /* No match */
}
-}
+ }
-Insertion/removal are defined using the following augmented callbacks:
+Insertion/removal are defined using the following augmented callbacks::
-static inline unsigned long
-compute_subtree_last(struct interval_tree_node *node)
-{
+ static inline unsigned long
+ compute_subtree_last(struct interval_tree_node *node)
+ {
unsigned long max = node->last, subtree_last;
if (node->rb.rb_left) {
subtree_last = rb_entry(node->rb.rb_left,
@@ -322,10 +326,10 @@ compute_subtree_last(struct interval_tree_node *node)
max = subtree_last;
}
return max;
-}
+ }
-static void augment_propagate(struct rb_node *rb, struct rb_node *stop)
-{
+ static void augment_propagate(struct rb_node *rb, struct rb_node *stop)
+ {
while (rb != stop) {
struct interval_tree_node *node =
rb_entry(rb, struct interval_tree_node, rb);
@@ -335,20 +339,20 @@ static void augment_propagate(struct rb_node *rb, struct rb_node *stop)
node->__subtree_last = subtree_last;
rb = rb_parent(&node->rb);
}
-}
+ }
-static void augment_copy(struct rb_node *rb_old, struct rb_node *rb_new)
-{
+ static void augment_copy(struct rb_node *rb_old, struct rb_node *rb_new)
+ {
struct interval_tree_node *old =
rb_entry(rb_old, struct interval_tree_node, rb);
struct interval_tree_node *new =
rb_entry(rb_new, struct interval_tree_node, rb);
new->__subtree_last = old->__subtree_last;
-}
+ }
-static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new)
-{
+ static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new)
+ {
struct interval_tree_node *old =
rb_entry(rb_old, struct interval_tree_node, rb);
struct interval_tree_node *new =
@@ -356,15 +360,15 @@ static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new)
new->__subtree_last = old->__subtree_last;
old->__subtree_last = compute_subtree_last(old);
-}
+ }
-static const struct rb_augment_callbacks augment_callbacks = {
+ static const struct rb_augment_callbacks augment_callbacks = {
augment_propagate, augment_copy, augment_rotate
-};
+ };
-void interval_tree_insert(struct interval_tree_node *node,
- struct rb_root *root)
-{
+ void interval_tree_insert(struct interval_tree_node *node,
+ struct rb_root *root)
+ {
struct rb_node **link = &root->rb_node, *rb_parent = NULL;
unsigned long start = node->start, last = node->last;
struct interval_tree_node *parent;
@@ -383,10 +387,10 @@ void interval_tree_insert(struct interval_tree_node *node,
node->__subtree_last = last;
rb_link_node(&node->rb, rb_parent, link);
rb_insert_augmented(&node->rb, root, &augment_callbacks);
-}
+ }
-void interval_tree_remove(struct interval_tree_node *node,
- struct rb_root *root)
-{
+ void interval_tree_remove(struct interval_tree_node *node,
+ struct rb_root *root)
+ {
rb_erase_augmented(&node->rb, root, &augment_callbacks);
-}
+ }
--
2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 13/29] SAK.txt: standardize document format |
| Message-ID | <tIF3A-3cN-25@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - mark document title; - use :Author: and :Date: for authorship; - adjust notation for literals and bold; - mark literal blocks; - adjust identation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/SAK.txt | 65 +++++++++++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/Documentation/SAK.txt b/Documentation/SAK.txt index 74be14679ed8..260e1d3687bd 100644 --- a/Documentation/SAK.txt +++ b/Documentation/SAK.txt @@ -1,5 +1,9 @@ -Linux 2.4.2 Secure Attention Key (SAK) handling -18 March 2001, Andrew Morton +========================================= +Linux Secure Attention Key (SAK) handling +========================================= + +:Date: 18 March 2001 +:Author: Andrew Morton An operating system's Secure Attention Key is a security tool which is provided as protection against trojan password capturing programs. It @@ -13,7 +17,7 @@ this sequence. It is only available if the kernel was compiled with sysrq support. The proper way of generating a SAK is to define the key sequence using -`loadkeys'. This will work whether or not sysrq support is compiled +``loadkeys``. This will work whether or not sysrq support is compiled into the kernel. SAK works correctly when the keyboard is in raw mode. This means that @@ -25,64 +29,63 @@ What key sequence should you use? Well, CTRL-ALT-DEL is used to reboot the machine. CTRL-ALT-BACKSPACE is magical to the X server. We'll choose CTRL-ALT-PAUSE. -In your rc.sysinit (or rc.local) file, add the command +In your rc.sysinit (or rc.local) file, add the command:: echo "control alt keycode 101 = SAK" | /bin/loadkeys And that's it! Only the superuser may reprogram the SAK key. -NOTES -===== +.. note:: -1: Linux SAK is said to be not a "true SAK" as is required by - systems which implement C2 level security. This author does not - know why. + 1. Linux SAK is said to be not a "true SAK" as is required by + systems which implement C2 level security. This author does not + know why. -2: On the PC keyboard, SAK kills all applications which have - /dev/console opened. + 2. On the PC keyboard, SAK kills all applications which have + /dev/console opened. - Unfortunately this includes a number of things which you don't - actually want killed. This is because these applications are - incorrectly holding /dev/console open. Be sure to complain to your - Linux distributor about this! + Unfortunately this includes a number of things which you don't + actually want killed. This is because these applications are + incorrectly holding /dev/console open. Be sure to complain to your + Linux distributor about this! - You can identify processes which will be killed by SAK with the - command + You can identify processes which will be killed by SAK with the + command:: # ls -l /proc/[0-9]*/fd/* | grep console l-wx------ 1 root root 64 Mar 18 00:46 /proc/579/fd/0 -> /dev/console - Then: + Then:: # ps aux|grep 579 root 579 0.0 0.1 1088 436 ? S 00:43 0:00 gpm -t ps/2 - So `gpm' will be killed by SAK. This is a bug in gpm. It should - be closing standard input. You can work around this by finding the - initscript which launches gpm and changing it thusly: + So ``gpm`` will be killed by SAK. This is a bug in gpm. It should + be closing standard input. You can work around this by finding the + initscript which launches gpm and changing it thusly: - Old: + Old:: daemon gpm - New: + New:: daemon gpm < /dev/null - Vixie cron also seems to have this problem, and needs the same treatment. + Vixie cron also seems to have this problem, and needs the same treatment. - Also, one prominent Linux distribution has the following three - lines in its rc.sysinit and rc scripts: + Also, one prominent Linux distribution has the following three + lines in its rc.sysinit and rc scripts:: exec 3<&0 exec 4>&1 exec 5>&2 - These commands cause *all* daemons which are launched by the - initscripts to have file descriptors 3, 4 and 5 attached to - /dev/console. So SAK kills them all. A workaround is to simply - delete these lines, but this may cause system management - applications to malfunction - test everything well. + These commands cause **all** daemons which are launched by the + initscripts to have file descriptors 3, 4 and 5 attached to + /dev/console. So SAK kills them all. A workaround is to simply + delete these lines, but this may cause system management + applications to malfunction - test everything well. -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 14/29] sgi-ioc4.txt: standardize document format |
| Message-ID | <tIF3B-3cN-35@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx. In this case, just adding a title is enough. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/sgi-ioc4.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/sgi-ioc4.txt b/Documentation/sgi-ioc4.txt index 876c96ae38db..72709222d3c0 100644 --- a/Documentation/sgi-ioc4.txt +++ b/Documentation/sgi-ioc4.txt @@ -1,3 +1,7 @@ +==================================== +SGI IOC4 PCI (multi function) device +==================================== + The SGI IOC4 PCI device is a bit of a strange beast, so some notes on it are in order. -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 15/29] siphash.txt: standardize document format |
| Message-ID | <tIF3B-3cN-33@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- Mark titles;
- Mark literal blocks;
- Use :Author: for authorship;
- Don't sumerate chapters;
- Adjust identation.
NOTE:
This file has actually two documents inside it, the first
one describing siphash, the second one describing halfsiphash.
It is likely a good idea to split them when it gets moved to
security/ (which is where it probably belongs).
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/siphash.txt | 186 +++++++++++++++++++++++++---------------------
1 file changed, 100 insertions(+), 86 deletions(-)
diff --git a/Documentation/siphash.txt b/Documentation/siphash.txt
index 908d348ff777..9965821ab333 100644
--- a/Documentation/siphash.txt
+++ b/Documentation/siphash.txt
@@ -1,6 +1,8 @@
- SipHash - a short input PRF
------------------------------------------------
-Written by Jason A. Donenfeld <jason@zx2c4.com>
+===========================
+SipHash - a short input PRF
+===========================
+
+:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
SipHash is a cryptographically secure PRF -- a keyed hash function -- that
performs very well for short inputs, hence the name. It was designed by
@@ -13,58 +15,61 @@ an input buffer or several input integers. It spits out an integer that is
indistinguishable from random. You may then use that integer as part of secure
sequence numbers, secure cookies, or mask it off for use in a hash table.
-1. Generating a key
+Generating a key
+================
Keys should always be generated from a cryptographically secure source of
-random numbers, either using get_random_bytes or get_random_once:
+random numbers, either using get_random_bytes or get_random_once::
-siphash_key_t key;
-get_random_bytes(&key, sizeof(key));
-
-If you're not deriving your key from here, you're doing it wrong.
-
-2. Using the functions
-
-There are two variants of the function, one that takes a list of integers, and
-one that takes a buffer:
-
-u64 siphash(const void *data, size_t len, const siphash_key_t *key);
-
-And:
-
-u64 siphash_1u64(u64, const siphash_key_t *key);
-u64 siphash_2u64(u64, u64, const siphash_key_t *key);
-u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);
-u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);
-u64 siphash_1u32(u32, const siphash_key_t *key);
-u64 siphash_2u32(u32, u32, const siphash_key_t *key);
-u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);
-u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);
-
-If you pass the generic siphash function something of a constant length, it
-will constant fold at compile-time and automatically choose one of the
-optimized functions.
-
-3. Hashtable key function usage:
-
-struct some_hashtable {
- DECLARE_HASHTABLE(hashtable, 8);
siphash_key_t key;
-};
+ get_random_bytes(&key, sizeof(key));
-void init_hashtable(struct some_hashtable *table)
-{
- get_random_bytes(&table->key, sizeof(table->key));
-}
+If you're not deriving your key from here, you're doing it wrong.
-static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
-{
- return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
-}
+Using the functions
+===================
+
+There are two variants of the function, one that takes a list of integers, and
+one that takes a buffer::
+
+ u64 siphash(const void *data, size_t len, const siphash_key_t *key);
+
+And::
+
+ u64 siphash_1u64(u64, const siphash_key_t *key);
+ u64 siphash_2u64(u64, u64, const siphash_key_t *key);
+ u64 siphash_3u64(u64, u64, u64, const siphash_key_t *key);
+ u64 siphash_4u64(u64, u64, u64, u64, const siphash_key_t *key);
+ u64 siphash_1u32(u32, const siphash_key_t *key);
+ u64 siphash_2u32(u32, u32, const siphash_key_t *key);
+ u64 siphash_3u32(u32, u32, u32, const siphash_key_t *key);
+ u64 siphash_4u32(u32, u32, u32, u32, const siphash_key_t *key);
+
+If you pass the generic siphash function something of a constant length, it
+will constant fold at compile-time and automatically choose one of the
+optimized functions.
+
+Hashtable key function usage::
+
+ struct some_hashtable {
+ DECLARE_HASHTABLE(hashtable, 8);
+ siphash_key_t key;
+ };
+
+ void init_hashtable(struct some_hashtable *table)
+ {
+ get_random_bytes(&table->key, sizeof(table->key));
+ }
+
+ static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
+ {
+ return &table->hashtable[siphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
+ }
You may then iterate like usual over the returned hash bucket.
-4. Security
+Security
+========
SipHash has a very high security margin, with its 128-bit key. So long as the
key is kept secret, it is impossible for an attacker to guess the outputs of
@@ -73,7 +78,8 @@ is significant.
Linux implements the "2-4" variant of SipHash.
-5. Struct-passing Pitfalls
+Struct-passing Pitfalls
+=======================
Often times the XuY functions will not be large enough, and instead you'll
want to pass a pre-filled struct to siphash. When doing this, it's important
@@ -81,30 +87,32 @@ to always ensure the struct has no padding holes. The easiest way to do this
is to simply arrange the members of the struct in descending order of size,
and to use offsetendof() instead of sizeof() for getting the size. For
performance reasons, if possible, it's probably a good thing to align the
-struct to the right boundary. Here's an example:
+struct to the right boundary. Here's an example::
-const struct {
- struct in6_addr saddr;
- u32 counter;
- u16 dport;
-} __aligned(SIPHASH_ALIGNMENT) combined = {
- .saddr = *(struct in6_addr *)saddr,
- .counter = counter,
- .dport = dport
-};
-u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret);
+ const struct {
+ struct in6_addr saddr;
+ u32 counter;
+ u16 dport;
+ } __aligned(SIPHASH_ALIGNMENT) combined = {
+ .saddr = *(struct in6_addr *)saddr,
+ .counter = counter,
+ .dport = dport
+ };
+ u64 h = siphash(&combined, offsetofend(typeof(combined), dport), &secret);
-6. Resources
+Resources
+=========
Read the SipHash paper if you're interested in learning more:
https://131002.net/siphash/siphash.pdf
+-------------------------------------------------------------------------------
-~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~=~
-
+===============================================
HalfSipHash - SipHash's insecure younger cousin
------------------------------------------------
-Written by Jason A. Donenfeld <jason@zx2c4.com>
+===============================================
+
+:Author: Written by Jason A. Donenfeld <jason@zx2c4.com>
On the off-chance that SipHash is not fast enough for your needs, you might be
able to justify using HalfSipHash, a terrifying but potentially useful
@@ -120,7 +128,8 @@ then when you can be absolutely certain that the outputs will never be
transmitted out of the kernel. This is only remotely useful over `jhash` as a
means of mitigating hashtable flooding denial of service attacks.
-1. Generating a key
+Generating a key
+================
Keys should always be generated from a cryptographically secure source of
random numbers, either using get_random_bytes or get_random_once:
@@ -130,44 +139,49 @@ get_random_bytes(&key, sizeof(key));
If you're not deriving your key from here, you're doing it wrong.
-2. Using the functions
+Using the functions
+===================
There are two variants of the function, one that takes a list of integers, and
-one that takes a buffer:
+one that takes a buffer::
-u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key);
+ u32 hsiphash(const void *data, size_t len, const hsiphash_key_t *key);
-And:
+And::
-u32 hsiphash_1u32(u32, const hsiphash_key_t *key);
-u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key);
-u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key);
-u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key);
+ u32 hsiphash_1u32(u32, const hsiphash_key_t *key);
+ u32 hsiphash_2u32(u32, u32, const hsiphash_key_t *key);
+ u32 hsiphash_3u32(u32, u32, u32, const hsiphash_key_t *key);
+ u32 hsiphash_4u32(u32, u32, u32, u32, const hsiphash_key_t *key);
If you pass the generic hsiphash function something of a constant length, it
will constant fold at compile-time and automatically choose one of the
optimized functions.
-3. Hashtable key function usage:
+Hashtable key function usage
+============================
-struct some_hashtable {
- DECLARE_HASHTABLE(hashtable, 8);
- hsiphash_key_t key;
-};
+::
-void init_hashtable(struct some_hashtable *table)
-{
- get_random_bytes(&table->key, sizeof(table->key));
-}
+ struct some_hashtable {
+ DECLARE_HASHTABLE(hashtable, 8);
+ hsiphash_key_t key;
+ };
-static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
-{
- return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
-}
+ void init_hashtable(struct some_hashtable *table)
+ {
+ get_random_bytes(&table->key, sizeof(table->key));
+ }
+
+ static inline hlist_head *some_hashtable_bucket(struct some_hashtable *table, struct interesting_input *input)
+ {
+ return &table->hashtable[hsiphash(input, sizeof(*input), &table->key) & (HASH_SIZE(table->hashtable) - 1)];
+ }
You may then iterate like usual over the returned hash bucket.
-4. Performance
+Performance
+===========
HalfSipHash is roughly 3 times slower than JenkinsHash. For many replacements,
this will not be a problem, as the hashtable lookup isn't the bottleneck. And
--
2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 03/29] preempt-locking.txt: standardize document format |
| Message-ID | <tIF3B-3cN-39@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - mark titles; - mark literal blocks; - adjust identation where needed; - use :Author: for authorship. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/preempt-locking.txt | 40 ++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/Documentation/preempt-locking.txt b/Documentation/preempt-locking.txt index e89ce6624af2..c945062be66c 100644 --- a/Documentation/preempt-locking.txt +++ b/Documentation/preempt-locking.txt @@ -1,10 +1,13 @@ - Proper Locking Under a Preemptible Kernel: - Keeping Kernel Code Preempt-Safe - Robert Love <rml@tech9.net> - Last Updated: 28 Aug 2002 +=========================================================================== +Proper Locking Under a Preemptible Kernel: Keeping Kernel Code Preempt-Safe +=========================================================================== +:Author: Robert Love <rml@tech9.net> +:Last Updated: 28 Aug 2002 -INTRODUCTION + +Introduction +============ A preemptible kernel creates new locking issues. The issues are the same as @@ -17,9 +20,10 @@ requires protecting these situations. RULE #1: Per-CPU data structures need explicit protection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Two similar problems arise. An example code snippet: +Two similar problems arise. An example code snippet:: struct this_needs_locking tux[NR_CPUS]; tux[smp_processor_id()] = some_value; @@ -35,6 +39,7 @@ You can also use put_cpu() and get_cpu(), which will disable preemption. RULE #2: CPU state must be protected. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Under preemption, the state of the CPU must be protected. This is arch- @@ -52,6 +57,7 @@ However, fpu__restore() must be called with preemption disabled. RULE #3: Lock acquire and release must be performed by same task +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A lock acquired in one task must be released by the same task. This @@ -61,17 +67,20 @@ like this, acquire and release the task in the same code path and have the caller wait on an event by the other task. -SOLUTION +Solution +======== Data protection under preemption is achieved by disabling preemption for the duration of the critical region. -preempt_enable() decrement the preempt counter -preempt_disable() increment the preempt counter -preempt_enable_no_resched() decrement, but do not immediately preempt -preempt_check_resched() if needed, reschedule -preempt_count() return the preempt counter +:: + + preempt_enable() decrement the preempt counter + preempt_disable() increment the preempt counter + preempt_enable_no_resched() decrement, but do not immediately preempt + preempt_check_resched() if needed, reschedule + preempt_count() return the preempt counter The functions are nestable. In other words, you can call preempt_disable n-times in a code path, and preemption will not be reenabled until the n-th @@ -89,7 +98,7 @@ So use this implicit preemption-disabling property only if you know that the affected codepath does not do any of this. Best policy is to use this only for small, atomic code that you wrote and which calls no complex functions. -Example: +Example:: cpucache_t *cc; /* this is per-CPU */ preempt_disable(); @@ -102,7 +111,7 @@ Example: return 0; Notice how the preemption statements must encompass every reference of the -critical variables. Another example: +critical variables. Another example:: int buf[NR_CPUS]; set_cpu_val(buf); @@ -114,7 +123,8 @@ This code is not preempt-safe, but see how easily we can fix it by simply moving the spin_lock up two lines. -PREVENTING PREEMPTION USING INTERRUPT DISABLING +Preventing preemption using interrupt disabling +=============================================== It is possible to prevent a preemption event using local_irq_disable and -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 05/29] pwm.txt: standardize document format |
| Message-ID | <tIF3B-3cN-55@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different
format. Some doesn't even have titles!
Change its representation to follow the adopted standard,
using ReST markups for it to be parseable by Sphinx:
- mark document title;
- mark literal blocks;
- better format the parameters.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/pwm.txt | 46 ++++++++++++++++++++++++++++------------------
1 file changed, 28 insertions(+), 18 deletions(-)
diff --git a/Documentation/pwm.txt b/Documentation/pwm.txt
index 789b27c6ec99..8fbf0aa3ba2d 100644
--- a/Documentation/pwm.txt
+++ b/Documentation/pwm.txt
@@ -1,4 +1,6 @@
+======================================
Pulse Width Modulation (PWM) interface
+======================================
This provides an overview about the Linux PWM interface
@@ -16,7 +18,7 @@ Users of the legacy PWM API use unique IDs to refer to PWM devices.
Instead of referring to a PWM device via its unique ID, board setup code
should instead register a static mapping that can be used to match PWM
-consumers to providers, as given in the following example:
+consumers to providers, as given in the following example::
static struct pwm_lookup board_pwm_lookup[] = {
PWM_LOOKUP("tegra-pwm", 0, "pwm-backlight", NULL,
@@ -40,9 +42,9 @@ New users should use the pwm_get() function and pass to it the consumer
device or a consumer name. pwm_put() is used to free the PWM device. Managed
variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist.
-After being requested, a PWM has to be configured using:
+After being requested, a PWM has to be configured using::
-int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
+ int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state);
This API controls both the PWM period/duty_cycle config and the
enable/disable state.
@@ -72,11 +74,14 @@ interface is provided to use the PWMs from userspace. It is exposed at
pwmchipN, where N is the base of the PWM chip. Inside the directory you
will find:
-npwm - The number of PWM channels this chip supports (read-only).
+ npwm
+ The number of PWM channels this chip supports (read-only).
-export - Exports a PWM channel for use with sysfs (write-only).
+ export
+ Exports a PWM channel for use with sysfs (write-only).
-unexport - Unexports a PWM channel from sysfs (write-only).
+ unexport
+ Unexports a PWM channel from sysfs (write-only).
The PWM channels are numbered using a per-chip index from 0 to npwm-1.
@@ -84,21 +89,26 @@ When a PWM channel is exported a pwmX directory will be created in the
pwmchipN directory it is associated with, where X is the number of the
channel that was exported. The following properties will then be available:
-period - The total period of the PWM signal (read/write).
- Value is in nanoseconds and is the sum of the active and inactive
- time of the PWM.
+ period
+ The total period of the PWM signal (read/write).
+ Value is in nanoseconds and is the sum of the active and inactive
+ time of the PWM.
-duty_cycle - The active time of the PWM signal (read/write).
- Value is in nanoseconds and must be less than the period.
+ duty_cycle
+ The active time of the PWM signal (read/write).
+ Value is in nanoseconds and must be less than the period.
-polarity - Changes the polarity of the PWM signal (read/write).
- Writes to this property only work if the PWM chip supports changing
- the polarity. The polarity can only be changed if the PWM is not
- enabled. Value is the string "normal" or "inversed".
+ polarity
+ Changes the polarity of the PWM signal (read/write).
+ Writes to this property only work if the PWM chip supports changing
+ the polarity. The polarity can only be changed if the PWM is not
+ enabled. Value is the string "normal" or "inversed".
-enable - Enable/disable the PWM signal (read/write).
- 0 - disabled
- 1 - enabled
+ enable
+ Enable/disable the PWM signal (read/write).
+
+ - 0 - disabled
+ - 1 - enabled
Implementing a PWM driver
-------------------------
--
2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 27/29] xz.txt: standardize document format |
| Message-ID | <tIF3C-3cN-57@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - Use marks for titles; - Adjust indentation. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/xz.txt | 182 ++++++++++++++++++++++++++------------------------- 1 file changed, 94 insertions(+), 88 deletions(-) diff --git a/Documentation/xz.txt b/Documentation/xz.txt index 2cf3e2608de3..b2220d03aa50 100644 --- a/Documentation/xz.txt +++ b/Documentation/xz.txt @@ -1,121 +1,127 @@ - +============================ XZ data compression in Linux ============================ Introduction +============ - XZ is a general purpose data compression format with high compression - ratio and relatively fast decompression. The primary compression - algorithm (filter) is LZMA2. Additional filters can be used to improve - compression ratio even further. E.g. Branch/Call/Jump (BCJ) filters - improve compression ratio of executable data. +XZ is a general purpose data compression format with high compression +ratio and relatively fast decompression. The primary compression +algorithm (filter) is LZMA2. Additional filters can be used to improve +compression ratio even further. E.g. Branch/Call/Jump (BCJ) filters +improve compression ratio of executable data. - The XZ decompressor in Linux is called XZ Embedded. It supports - the LZMA2 filter and optionally also BCJ filters. CRC32 is supported - for integrity checking. The home page of XZ Embedded is at - <http://tukaani.org/xz/embedded.html>, where you can find the - latest version and also information about using the code outside - the Linux kernel. +The XZ decompressor in Linux is called XZ Embedded. It supports +the LZMA2 filter and optionally also BCJ filters. CRC32 is supported +for integrity checking. The home page of XZ Embedded is at +<http://tukaani.org/xz/embedded.html>, where you can find the +latest version and also information about using the code outside +the Linux kernel. - For userspace, XZ Utils provide a zlib-like compression library - and a gzip-like command line tool. XZ Utils can be downloaded from - <http://tukaani.org/xz/>. +For userspace, XZ Utils provide a zlib-like compression library +and a gzip-like command line tool. XZ Utils can be downloaded from +<http://tukaani.org/xz/>. XZ related components in the kernel +=================================== - The xz_dec module provides XZ decompressor with single-call (buffer - to buffer) and multi-call (stateful) APIs. The usage of the xz_dec - module is documented in include/linux/xz.h. +The xz_dec module provides XZ decompressor with single-call (buffer +to buffer) and multi-call (stateful) APIs. The usage of the xz_dec +module is documented in include/linux/xz.h. - The xz_dec_test module is for testing xz_dec. xz_dec_test is not - useful unless you are hacking the XZ decompressor. xz_dec_test - allocates a char device major dynamically to which one can write - .xz files from userspace. The decompressed output is thrown away. - Keep an eye on dmesg to see diagnostics printed by xz_dec_test. - See the xz_dec_test source code for the details. +The xz_dec_test module is for testing xz_dec. xz_dec_test is not +useful unless you are hacking the XZ decompressor. xz_dec_test +allocates a char device major dynamically to which one can write +.xz files from userspace. The decompressed output is thrown away. +Keep an eye on dmesg to see diagnostics printed by xz_dec_test. +See the xz_dec_test source code for the details. - For decompressing the kernel image, initramfs, and initrd, there - is a wrapper function in lib/decompress_unxz.c. Its API is the - same as in other decompress_*.c files, which is defined in - include/linux/decompress/generic.h. +For decompressing the kernel image, initramfs, and initrd, there +is a wrapper function in lib/decompress_unxz.c. Its API is the +same as in other decompress_*.c files, which is defined in +include/linux/decompress/generic.h. - scripts/xz_wrap.sh is a wrapper for the xz command line tool found - from XZ Utils. The wrapper sets compression options to values suitable - for compressing the kernel image. +scripts/xz_wrap.sh is a wrapper for the xz command line tool found +from XZ Utils. The wrapper sets compression options to values suitable +for compressing the kernel image. - For kernel makefiles, two commands are provided for use with - $(call if_needed). The kernel image should be compressed with - $(call if_needed,xzkern) which will use a BCJ filter and a big LZMA2 - dictionary. It will also append a four-byte trailer containing the - uncompressed size of the file, which is needed by the boot code. - Other things should be compressed with $(call if_needed,xzmisc) - which will use no BCJ filter and 1 MiB LZMA2 dictionary. +For kernel makefiles, two commands are provided for use with +$(call if_needed). The kernel image should be compressed with +$(call if_needed,xzkern) which will use a BCJ filter and a big LZMA2 +dictionary. It will also append a four-byte trailer containing the +uncompressed size of the file, which is needed by the boot code. +Other things should be compressed with $(call if_needed,xzmisc) +which will use no BCJ filter and 1 MiB LZMA2 dictionary. Notes on compression options +============================ - Since the XZ Embedded supports only streams with no integrity check or - CRC32, make sure that you don't use some other integrity check type - when encoding files that are supposed to be decoded by the kernel. With - liblzma, you need to use either LZMA_CHECK_NONE or LZMA_CHECK_CRC32 - when encoding. With the xz command line tool, use --check=none or - --check=crc32. +Since the XZ Embedded supports only streams with no integrity check or +CRC32, make sure that you don't use some other integrity check type +when encoding files that are supposed to be decoded by the kernel. With +liblzma, you need to use either LZMA_CHECK_NONE or LZMA_CHECK_CRC32 +when encoding. With the xz command line tool, use --check=none or +--check=crc32. - Using CRC32 is strongly recommended unless there is some other layer - which will verify the integrity of the uncompressed data anyway. - Double checking the integrity would probably be waste of CPU cycles. - Note that the headers will always have a CRC32 which will be validated - by the decoder; you can only change the integrity check type (or - disable it) for the actual uncompressed data. +Using CRC32 is strongly recommended unless there is some other layer +which will verify the integrity of the uncompressed data anyway. +Double checking the integrity would probably be waste of CPU cycles. +Note that the headers will always have a CRC32 which will be validated +by the decoder; you can only change the integrity check type (or +disable it) for the actual uncompressed data. - In userspace, LZMA2 is typically used with dictionary sizes of several - megabytes. The decoder needs to have the dictionary in RAM, thus big - dictionaries cannot be used for files that are intended to be decoded - by the kernel. 1 MiB is probably the maximum reasonable dictionary - size for in-kernel use (maybe more is OK for initramfs). The presets - in XZ Utils may not be optimal when creating files for the kernel, - so don't hesitate to use custom settings. Example: +In userspace, LZMA2 is typically used with dictionary sizes of several +megabytes. The decoder needs to have the dictionary in RAM, thus big +dictionaries cannot be used for files that are intended to be decoded +by the kernel. 1 MiB is probably the maximum reasonable dictionary +size for in-kernel use (maybe more is OK for initramfs). The presets +in XZ Utils may not be optimal when creating files for the kernel, +so don't hesitate to use custom settings. Example:: - xz --check=crc32 --lzma2=dict=512KiB inputfile + xz --check=crc32 --lzma2=dict=512KiB inputfile - An exception to above dictionary size limitation is when the decoder - is used in single-call mode. Decompressing the kernel itself is an - example of this situation. In single-call mode, the memory usage - doesn't depend on the dictionary size, and it is perfectly fine to - use a big dictionary: for maximum compression, the dictionary should - be at least as big as the uncompressed data itself. +An exception to above dictionary size limitation is when the decoder +is used in single-call mode. Decompressing the kernel itself is an +example of this situation. In single-call mode, the memory usage +doesn't depend on the dictionary size, and it is perfectly fine to +use a big dictionary: for maximum compression, the dictionary should +be at least as big as the uncompressed data itself. Future plans +============ - Creating a limited XZ encoder may be considered if people think it is - useful. LZMA2 is slower to compress than e.g. Deflate or LZO even at - the fastest settings, so it isn't clear if LZMA2 encoder is wanted - into the kernel. +Creating a limited XZ encoder may be considered if people think it is +useful. LZMA2 is slower to compress than e.g. Deflate or LZO even at +the fastest settings, so it isn't clear if LZMA2 encoder is wanted +into the kernel. - Support for limited random-access reading is planned for the - decompression code. I don't know if it could have any use in the - kernel, but I know that it would be useful in some embedded projects - outside the Linux kernel. +Support for limited random-access reading is planned for the +decompression code. I don't know if it could have any use in the +kernel, but I know that it would be useful in some embedded projects +outside the Linux kernel. Conformance to the .xz file format specification +================================================ - There are a couple of corner cases where things have been simplified - at expense of detecting errors as early as possible. These should not - matter in practice all, since they don't cause security issues. But - it is good to know this if testing the code e.g. with the test files - from XZ Utils. +There are a couple of corner cases where things have been simplified +at expense of detecting errors as early as possible. These should not +matter in practice all, since they don't cause security issues. But +it is good to know this if testing the code e.g. with the test files +from XZ Utils. Reporting bugs +============== - Before reporting a bug, please check that it's not fixed already - at upstream. See <http://tukaani.org/xz/embedded.html> to get the - latest code. +Before reporting a bug, please check that it's not fixed already +at upstream. See <http://tukaani.org/xz/embedded.html> to get the +latest code. - Report bugs to <lasse.collin@tukaani.org> or visit #tukaani on - Freenode and talk to Larhzu. I don't actively read LKML or other - kernel-related mailing lists, so if there's something I should know, - you should email to me personally or use IRC. +Report bugs to <lasse.collin@tukaani.org> or visit #tukaani on +Freenode and talk to Larhzu. I don't actively read LKML or other +kernel-related mailing lists, so if there's something I should know, +you should email to me personally or use IRC. - Don't bother Igor Pavlov with questions about the XZ implementation - in the kernel or about XZ Utils. While these two implementations - include essential code that is directly based on Igor Pavlov's code, - these implementations aren't maintained nor supported by him. +Don't bother Igor Pavlov with questions about the XZ implementation +in the kernel or about XZ Utils. While these two implementations +include essential code that is directly based on Igor Pavlov's code, +these implementations aren't maintained nor supported by him. -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 12/29] rtc.txt: standardize document format |
| Message-ID | <tIF3C-3cN-61@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - adjust identation of the titles; - mark a table as such; - don't capitalize chapter names. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/rtc.txt | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index ddc366026e00..47feb4414b7e 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -1,6 +1,6 @@ - - Real Time Clock (RTC) Drivers for Linux - ======================================= +======================================= +Real Time Clock (RTC) Drivers for Linux +======================================= When Linux developers talk about a "Real Time Clock", they usually mean something that tracks wall clock time and is battery backed so that it @@ -32,8 +32,8 @@ only issue an alarm up to 24 hours in the future, other hardware may be able to schedule one any time in the upcoming century. - Old PC/AT-Compatible driver: /dev/rtc - -------------------------------------- +Old PC/AT-Compatible driver: /dev/rtc +-------------------------------------- All PCs (even Alpha machines) have a Real Time Clock built into them. Usually they are built into the chipset of the computer, but some may @@ -105,8 +105,8 @@ that will be using this driver. See the code at the end of this document. (The original /dev/rtc driver was written by Paul Gortmaker.) - New portable "RTC Class" drivers: /dev/rtcN - -------------------------------------------- +New portable "RTC Class" drivers: /dev/rtcN +-------------------------------------------- Because Linux supports many non-ACPI and non-PC platforms, some of which have more than one RTC style clock, it needed a more portable solution @@ -136,35 +136,37 @@ a high functionality RTC is integrated into the SOC. That system might read the system clock from the discrete RTC, but use the integrated one for all other tasks, because of its greater functionality. -SYSFS INTERFACE +SYSFS interface --------------- The sysfs interface under /sys/class/rtc/rtcN provides access to various rtc attributes without requiring the use of ioctls. All dates and times are in the RTC's timezone, rather than in system time. -date: RTC-provided date -hctosys: 1 if the RTC provided the system time at boot via the +================ ============================================================== +date RTC-provided date +hctosys 1 if the RTC provided the system time at boot via the CONFIG_RTC_HCTOSYS kernel option, 0 otherwise -max_user_freq: The maximum interrupt rate an unprivileged user may request +max_user_freq The maximum interrupt rate an unprivileged user may request from this RTC. -name: The name of the RTC corresponding to this sysfs directory -since_epoch: The number of seconds since the epoch according to the RTC -time: RTC-provided time -wakealarm: The time at which the clock will generate a system wakeup +name The name of the RTC corresponding to this sysfs directory +since_epoch The number of seconds since the epoch according to the RTC +time RTC-provided time +wakealarm The time at which the clock will generate a system wakeup event. This is a one shot wakeup event, so must be reset - after wake if a daily wakeup is required. Format is seconds since - the epoch by default, or if there's a leading +, seconds in the - future, or if there is a leading +=, seconds ahead of the current - alarm. -offset: The amount which the rtc clock has been adjusted in firmware. + after wake if a daily wakeup is required. Format is seconds + since the epoch by default, or if there's a leading +, seconds + in the future, or if there is a leading +=, seconds ahead of + the current alarm. +offset The amount which the rtc clock has been adjusted in firmware. Visible only if the driver supports clock offset adjustment. The unit is parts per billion, i.e. The number of clock ticks which are added to or removed from the rtc's base clock per billion ticks. A positive value makes a day pass more slowly, longer, and a negative value makes a day pass more quickly. +================ ============================================================== -IOCTL INTERFACE +IOCTL interface --------------- The ioctl() calls supported by /dev/rtc are also supported by the RTC class -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 20/29] sync_file.txt: standardize document format |
| Message-ID | <tIF3C-3cN-67@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - Use markup for document title and authorship; - Mark literal blocks; - Use a numbered list for references. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/sync_file.txt | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.txt index c3d033a06e8d..496fb2c3b3e6 100644 --- a/Documentation/sync_file.txt +++ b/Documentation/sync_file.txt @@ -1,8 +1,8 @@ - Sync File API Guide - ~~~~~~~~~~~~~~~~~~~ +=================== +Sync File API Guide +=================== - Gustavo Padovan - <gustavo at padovan dot org> +:Author: Gustavo Padovan <gustavo at padovan dot org> This document serves as a guide for device drivers writers on what the sync_file API is, and how drivers can support it. Sync file is the carrier of @@ -46,16 +46,17 @@ Creating Sync Files When a driver needs to send an out-fence userspace it creates a sync_file. -Interface: +Interface:: + struct sync_file *sync_file_create(struct dma_fence *fence); The caller pass the out-fence and gets back the sync_file. That is just the first step, next it needs to install an fd on sync_file->file. So it gets an -fd: +fd:: fd = get_unused_fd_flags(O_CLOEXEC); -and installs it on sync_file->file: +and installs it on sync_file->file:: fd_install(fd, sync_file->file); @@ -71,7 +72,8 @@ When userspace needs to send an in-fence to the driver it passes file descriptor of the Sync File to the kernel. The kernel can then retrieve the fences from it. -Interface: +Interface:: + struct dma_fence *sync_file_get_fence(int fd); @@ -79,5 +81,6 @@ The returned reference is owned by the caller and must be disposed of afterwards using dma_fence_put(). In case of error, a NULL is returned instead. References: -[1] struct sync_file in include/linux/sync_file.h -[2] All interfaces mentioned above defined in include/linux/sync_file.h + +1. struct sync_file in include/linux/sync_file.h +2. All interfaces mentioned above defined in include/linux/sync_file.h -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2017-05-19 03:40 +0200 |
| Subject | [PATCH 16/29] SM501.txt: standardize document format |
| Message-ID | <tIF3C-3cN-75@gated-at.bofh.it> |
| In reply to | #1645044 |
Each text file under Documentation follows a different format. Some doesn't even have titles! Change its representation to follow the adopted standard, using ReST markups for it to be parseable by Sphinx: - adjust document title; - use the copyright markup. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/SM501.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/SM501.txt b/Documentation/SM501.txt index 561826f82093..882507453ba4 100644 --- a/Documentation/SM501.txt +++ b/Documentation/SM501.txt @@ -1,7 +1,10 @@ - SM501 Driver - ============ +.. include:: <isonum.txt> -Copyright 2006, 2007 Simtec Electronics +============ +SM501 Driver +============ + +:Copyright: |copy| 2006, 2007 Simtec Electronics The Silicon Motion SM501 multimedia companion chip is a multifunction device which may provide numerous interfaces including USB host controller USB gadget, -- 2.9.4
[toc] | [prev] | [next] | [standalone]
| From | Linus Walleij <linus.walleij@linaro.org> |
|---|---|
| Date | 2017-05-23 11:20 +0200 |
| Subject | Re: [PATCH 01/29] pinctrl.txt: standardize document format |
| Message-ID | <tKe8W-19m-7@gated-at.bofh.it> |
| In reply to | #1645044 |
On Fri, May 19, 2017 at 3:25 AM, Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote: > Each text file under Documentation follows a different > format. Some doesn't even have titles! > > Change its representation to follow the adopted standard, > using ReST markups for it to be parseable by Sphinx. > > This document is almost following the standard stile. > > There are only two things to adjust on it: > > - promote the level of the document title; > - mark literal blocks as such. > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> I applied the patch fixing some of the indentation mistakes pointed out by Geert. Should the file be renamed pinctrl.rst now? Yours, Linus Walleij
[toc] | [prev] | [standalone]
Back to top | Article view | linux.kernel
csiph-web