From 32630d526b9faaec02fa1d26582d91c01f6d476c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 11:52:34 -0300 Subject: [PATCH 01/67] MAINTAINERS: add entries for some documentation scripts There are some documentation scripts I wrote with doesn't have any maintainer at maintainer's file. Add them to the DOCUMENTATION entry, in order to have Jon and linux-doc ML c/c on those patches, plus a new entry to ensure that I'll be c/c when people send patches to those. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- MAINTAINERS | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/MAINTAINERS b/MAINTAINERS index ff3ae2be2746..6d397fa03436 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -4947,7 +4947,9 @@ M: Jonathan Corbet L: linux-doc@vger.kernel.org S: Maintained F: Documentation/ +F: scripts/documentation-file-ref-check F: scripts/kernel-doc +F: scripts/sphinx-pre-install X: Documentation/ABI/ X: Documentation/firmware-guide/acpi/ X: Documentation/devicetree/ @@ -4963,6 +4965,14 @@ L: linux-doc@vger.kernel.org S: Maintained F: Documentation/translations/it_IT +DOCUMENTATION SCRIPTS +M: Mauro Carvalho Chehab +L: linux-doc@vger.kernel.org +S: Maintained +F: scripts/documentation-file-ref-check +F: scripts/sphinx-pre-install +F: Documentation/sphinx/parse-headers.pl + DONGWOON DW9714 LENS VOICE COIL DRIVER M: Sakari Ailus L: linux-media@vger.kernel.org From da422ade5c879355f7410859069ef4f957c303d4 Mon Sep 17 00:00:00 2001 From: Mark Rutland Date: Tue, 23 Jul 2019 14:22:03 +0100 Subject: [PATCH 02/67] Documentation/features/locking: update lists The locking feature lists don't match reality as of v5.3-rc1: * arm64 moved to queued spinlocks in commit: c11090474d70590170cf5fa6afe85864ab494b37 ("arm64: locking: Replace ticket lock implementation with qspinlock") * xtensa moved to queued spinlocks and rwlocks in commit: 579afe866f52adcd921272a224ab36733051059c ("xtensa: use generic spinlock/rwlock implementation") * architecture-specific rwsem support was removed in commit: 46ad0840b1584b92b5ff2cc3ed0b011dd6b8e0f1 ("locking/rwsem: Remove arch specific rwsem files") So update the feature lists accordingly, and remove the now redundant rwsem-optimized list. Signed-off-by: Mark Rutland Signed-off-by: Jonathan Corbet --- .../locking/queued-rwlocks/arch-support.txt | 2 +- .../locking/queued-spinlocks/arch-support.txt | 4 +-- .../locking/rwsem-optimized/arch-support.txt | 34 ------------------- 3 files changed, 3 insertions(+), 37 deletions(-) delete mode 100644 Documentation/features/locking/rwsem-optimized/arch-support.txt diff --git a/Documentation/features/locking/queued-rwlocks/arch-support.txt b/Documentation/features/locking/queued-rwlocks/arch-support.txt index c683da198f31..ee922746a64c 100644 --- a/Documentation/features/locking/queued-rwlocks/arch-support.txt +++ b/Documentation/features/locking/queued-rwlocks/arch-support.txt @@ -30,5 +30,5 @@ | um: | TODO | | unicore32: | TODO | | x86: | ok | - | xtensa: | TODO | + | xtensa: | ok | ----------------------- diff --git a/Documentation/features/locking/queued-spinlocks/arch-support.txt b/Documentation/features/locking/queued-spinlocks/arch-support.txt index e3080b82aefd..c52116c1a049 100644 --- a/Documentation/features/locking/queued-spinlocks/arch-support.txt +++ b/Documentation/features/locking/queued-spinlocks/arch-support.txt @@ -9,7 +9,7 @@ | alpha: | TODO | | arc: | TODO | | arm: | TODO | - | arm64: | TODO | + | arm64: | ok | | c6x: | TODO | | csky: | TODO | | h8300: | TODO | @@ -30,5 +30,5 @@ | um: | TODO | | unicore32: | TODO | | x86: | ok | - | xtensa: | TODO | + | xtensa: | ok | ----------------------- diff --git a/Documentation/features/locking/rwsem-optimized/arch-support.txt b/Documentation/features/locking/rwsem-optimized/arch-support.txt deleted file mode 100644 index 7521d7500fbe..000000000000 --- a/Documentation/features/locking/rwsem-optimized/arch-support.txt +++ /dev/null @@ -1,34 +0,0 @@ -# -# Feature name: rwsem-optimized -# Kconfig: !RWSEM_GENERIC_SPINLOCK -# description: arch provides optimized rwsem APIs -# - ----------------------- - | arch |status| - ----------------------- - | alpha: | ok | - | arc: | TODO | - | arm: | ok | - | arm64: | ok | - | c6x: | TODO | - | csky: | TODO | - | h8300: | TODO | - | hexagon: | TODO | - | ia64: | ok | - | m68k: | TODO | - | microblaze: | TODO | - | mips: | TODO | - | nds32: | TODO | - | nios2: | TODO | - | openrisc: | TODO | - | parisc: | TODO | - | powerpc: | TODO | - | riscv: | TODO | - | s390: | ok | - | sh: | ok | - | sparc: | ok | - | um: | ok | - | unicore32: | TODO | - | x86: | ok | - | xtensa: | ok | - ----------------------- From 38a449ff533c9a21c254473a9f0cf59b6f420f50 Mon Sep 17 00:00:00 2001 From: Sheriff Esseson Date: Tue, 23 Jul 2019 12:48:13 +0100 Subject: [PATCH 03/67] Documentation: filesystem: fix "Removed Sysctls" table the "Removed Sysctls" section is a table - bring it alive with ReST. Signed-off-by: Sheriff Esseson Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/xfs.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Documentation/admin-guide/xfs.rst b/Documentation/admin-guide/xfs.rst index e76665a8f2f2..fb5b39f73059 100644 --- a/Documentation/admin-guide/xfs.rst +++ b/Documentation/admin-guide/xfs.rst @@ -337,11 +337,12 @@ None at present. Removed Sysctls =============== +============================= ======= Name Removed - ---- ------- +============================= ======= fs.xfs.xfsbufd_centisec v4.0 fs.xfs.age_buffer_centisecs v4.0 - +============================= ======= Error handling ============== From c6e0396124de72d6ab7f8c8e01af7f79ee1aa698 Mon Sep 17 00:00:00 2001 From: Andy Shevchenko Date: Tue, 23 Jul 2019 19:57:50 +0300 Subject: [PATCH 04/67] coda: Fix typo in the struct CodaCred documentation Documentation mistakenly refers to a different type while explaining the contents of the struct CodaCred. Fix the typo in the struct CodaCred description in the documentation. Signed-off-by: Andy Shevchenko Signed-off-by: Jonathan Corbet --- Documentation/filesystems/coda.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/filesystems/coda.txt b/Documentation/filesystems/coda.txt index 545262c167c3..1711ad48e38a 100644 --- a/Documentation/filesystems/coda.txt +++ b/Documentation/filesystems/coda.txt @@ -421,14 +421,14 @@ kernel support. The CodaCred structure defines a variety of user and group ids as - they are set for the calling process. The vuid_t and guid_t are 32 bit + they are set for the calling process. The vuid_t and vgid_t are 32 bit unsigned integers. It also defines group membership in an array. On Unix the CodaCred has proven sufficient to implement good security semantics for Coda but the structure may have to undergo modification for the Windows environment when these mature. struct CodaCred { - vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid*/ + vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, effective, set, fs uid */ vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */ vgid_t cr_groups[NGROUPS]; /* Group membership for caller */ }; From 257e26c6403c23714db69d6e21c58b0d92636c4e Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 31 Jul 2019 11:02:11 +0200 Subject: [PATCH 05/67] docs: arm: Remove orphan sh-mobile directory This directory is empty, except for a .gitignore file, listing an executable file that can no longer be built since commit c6535e1e0361157e ("Documentation: Remove ZBOOT MMC/SDHI utility and docs"). Signed-off-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/arm/sh-mobile/.gitignore | 1 - 1 file changed, 1 deletion(-) delete mode 100644 Documentation/arm/sh-mobile/.gitignore diff --git a/Documentation/arm/sh-mobile/.gitignore b/Documentation/arm/sh-mobile/.gitignore deleted file mode 100644 index c928dbf3cc88..000000000000 --- a/Documentation/arm/sh-mobile/.gitignore +++ /dev/null @@ -1 +0,0 @@ -vrl4 From 074b326ee5e73c8e7a10d0eebbc6a1b56e1253d2 Mon Sep 17 00:00:00 2001 From: Chao Yu Date: Wed, 31 Jul 2019 19:45:10 +0800 Subject: [PATCH 06/67] mailmap: add entry to connect my email addresses I've used several email accounts to contribute codes, samsung's one is obsolete, so let me add entry to map them, in order to let people find me easily when they blame my codes. Signed-off-by: Chao Yu Signed-off-by: Jonathan Corbet --- .mailmap | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.mailmap b/.mailmap index 0fef932de3db..477debe3d960 100644 --- a/.mailmap +++ b/.mailmap @@ -47,6 +47,8 @@ Boris Brezillon Boris Brezillon Brian Avery Brian King +Chao Yu +Chao Yu Christoph Hellwig Christophe Ricard Corey Minyard From 803deeaaea10a87b7d92bd2eccbc637711390a04 Mon Sep 17 00:00:00 2001 From: Federico Vaga Date: Mon, 29 Jul 2019 23:58:56 +0200 Subject: [PATCH 07/67] doc:it_IT: align translation to mainline The patch translates the following patches in Italian: 1fb12b35e5ff kbuild: Raise the minimum required binutils version to 2.21 9c3c0c204814 isdn: remove isdn4linux Signed-off-by: Federico Vaga Signed-off-by: Jonathan Corbet --- .../translations/it_IT/process/changes.rst | 22 ++++--------------- 1 file changed, 4 insertions(+), 18 deletions(-) diff --git a/Documentation/translations/it_IT/process/changes.rst b/Documentation/translations/it_IT/process/changes.rst index d0874327f301..94a6499742ac 100644 --- a/Documentation/translations/it_IT/process/changes.rst +++ b/Documentation/translations/it_IT/process/changes.rst @@ -26,16 +26,15 @@ Prima di pensare d'avere trovato un baco, aggiornate i seguenti programmi usando, il comando indicato dovrebbe dirvelo. Questa lista presume che abbiate già un kernel Linux funzionante. In aggiunta, -non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete un -modem ISDN, per esempio, probabilmente non dovreste preoccuparvi di -isdn4k-utils. +non tutti gli strumenti sono necessari ovunque; ovviamente, se non avete una +PC Card, per esempio, probabilmente non dovreste preoccuparvi di pcmciautils. ====================== ================= ======================================== Programma Versione minima Comando per verificare la versione ====================== ================= ======================================== GNU C 4.6 gcc --version GNU make 3.81 make --version -binutils 2.20 ld -v +binutils 2.21 ld -v flex 2.5.35 flex --version bison 2.0 bison --version util-linux 2.10o fdformat --version @@ -49,7 +48,6 @@ btrfs-progs 0.18 btrfsck pcmciautils 004 pccardctl -V quota-tools 3.09 quota -V PPP 2.4.0 pppd --version -isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version nfs-utils 1.0.5 showmount --version procps 3.2.0 ps --version oprofile 0.9 oprofiled --version @@ -81,10 +79,7 @@ Per compilare il kernel vi servirà GNU make 3.81 o successivo. Binutils -------- -Il sistema di compilazione, dalla versione 4.13, per la produzione dei passi -intermedi, si è convertito all'uso di *thin archive* (`ar T`) piuttosto che -all'uso del *linking* incrementale (`ld -r`). Questo richiede binutils 2.20 o -successivo. +Per generare il kernel è necessario avere Binutils 2.21 o superiore. pkg-config ---------- @@ -286,11 +281,6 @@ col seguente comando:: mknod /dev/ppp c 108 0 -Isdn4k-utils ------------- - -Per via della modifica del campo per il numero di telefono, il pacchetto -isdn4k-utils dev'essere ricompilato o (preferibilmente) aggiornato. NFS-utils --------- @@ -456,10 +446,6 @@ PPP - -Isdn4k-utils ------------- - -- NFS-utils --------- From 370910efdb6ece4a391afbc047c39e2d1b61374c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 16:29:10 -0300 Subject: [PATCH 08/67] MAINTAINERS: fix broken ref for ABI sysfs-bus-counter-ftm-quaddec There's a typo here: sysfs-bus-counter-ftm-quadddec -> sysfs-bus-counter-ftm-quaddec Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 6d397fa03436..757b28717918 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6327,7 +6327,7 @@ FLEXTIMER FTM-QUADDEC DRIVER M: Patrick Havelange L: linux-iio@vger.kernel.org S: Maintained -F: Documentation/ABI/testing/sysfs-bus-counter-ftm-quadddec +F: Documentation/ABI/testing/sysfs-bus-counter-ftm-quaddec F: Documentation/devicetree/bindings/counter/ftm-quaddec.txt F: drivers/counter/ftm-quaddec.c From b26bb0faf8f5d7fccb2e1827f33012177ac9d217 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 16:29:11 -0300 Subject: [PATCH 09/67] MAINTAINERS: fix reference to net phy ABI file The file sysfs-bus-mdio got removed in favor of sysfs-class-net-phydev, with contained a duplicated set of information. Fixes: a6cd0d2d493a ("Documentation: net-sysfs: Remove duplicate PHY device documentation") Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 757b28717918..f105a80f4d73 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6071,7 +6071,7 @@ M: Florian Fainelli M: Heiner Kallweit L: netdev@vger.kernel.org S: Maintained -F: Documentation/ABI/testing/sysfs-bus-mdio +F: Documentation/ABI/testing/sysfs-class-net-phydev F: Documentation/devicetree/bindings/net/ethernet-phy.yaml F: Documentation/devicetree/bindings/net/mdio* F: Documentation/networking/phy.rst From 7530c497592e04f5da69fe968c09622b489f2921 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 16:29:12 -0300 Subject: [PATCH 10/67] MAINTAINERS: fix a renamed DT reference Fix this rename: Documentation/devicetree/bindings/i2c/{i2c-mv64xxx.txt -> marvell,mv64xxx-i2c.yaml} Fixes: f8bbde72ef44 ("dt-bindings: i2c: mv64xxx: Add YAML schemas") Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index f105a80f4d73..811218cc2355 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7517,7 +7517,7 @@ I2C MV64XXX MARVELL AND ALLWINNER DRIVER M: Gregory CLEMENT L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/devicetree/bindings/i2c/i2c-mv64xxx.txt +F: Documentation/devicetree/bindings/i2c/marvell,mv64xxx-i2c.yaml F: drivers/i2c/busses/i2c-mv64xxx.c I2C OVER PARALLEL PORT From 23aa16489c06e6739c7c99e9fdccf723d2691a5d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 16:29:13 -0300 Subject: [PATCH 11/67] docs: cgroup-v1/blkio-controller.rst: remove a CFQ left over changeset fb5772cbfe48 ("blkio-controller.txt: Remove references to CFQ") removed cgroup references to CFQ, but it kept one left. Get rid of it. Fixes: fb5772cbfe48 ("blkio-controller.txt: Remove references to CFQ") Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/cgroup-v1/blkio-controller.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst index 1d7d962933be..36d43ae7dc13 100644 --- a/Documentation/admin-guide/cgroup-v1/blkio-controller.rst +++ b/Documentation/admin-guide/cgroup-v1/blkio-controller.rst @@ -130,12 +130,6 @@ Proportional weight policy files dev weight 8:16 300 -- blkio.leaf_weight[_device] - - Equivalents of blkio.weight[_device] for the purpose of - deciding how much weight tasks in the given cgroup has while - competing with the cgroup's child cgroups. For details, - please refer to Documentation/block/cfq-iosched.txt. - - blkio.time - disk time allocated to cgroup per device in milliseconds. First two fields specify the major and minor number of the device and From 54bfe6feba0e9ead1172cf26381f7dce5df10e51 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 16:29:14 -0300 Subject: [PATCH 12/67] docs: zh_CN: howto.rst: fix a broken reference There's a broken reference there pointing to the long gone DocBook dir. While I don't read chinese, Google translator translates it to: "The generated documentation will be placed in the Documentation/DocBook/ directory." Well, we know that the output will be Documentation/output dir. So, let's fix this one. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/translations/zh_CN/process/howto.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index 5b671178b17b..c4ff8356b88d 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -147,7 +147,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍 内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何 -妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内 +妥善处理加锁的规则。生成的文档会放在 Documentation/output/目录下。在内 核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册 页等不同格式的文档:: From 638b642f82bb8ee81fe00bdbb70b5ff0885df1a5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 18:01:55 -0300 Subject: [PATCH 13/67] docs: riscv: convert boot-image-header.txt to ReST Convert this small file to ReST format by: - Using a proper markup for the document title; - marking a code block as such; - use tags for Author and date; - use tables for bit map fields. While here, fix a broken reference for a document with is planned but is not here yet. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Atish Patra Signed-off-by: Jonathan Corbet --- ...image-header.txt => boot-image-header.rst} | 39 ++++++++++++------- Documentation/riscv/index.rst | 1 + 2 files changed, 26 insertions(+), 14 deletions(-) rename Documentation/riscv/{boot-image-header.txt => boot-image-header.rst} (72%) diff --git a/Documentation/riscv/boot-image-header.txt b/Documentation/riscv/boot-image-header.rst similarity index 72% rename from Documentation/riscv/boot-image-header.txt rename to Documentation/riscv/boot-image-header.rst index 1b73fea23b39..43e9bd0731d5 100644 --- a/Documentation/riscv/boot-image-header.txt +++ b/Documentation/riscv/boot-image-header.rst @@ -1,22 +1,25 @@ - Boot image header in RISC-V Linux - ============================================= +================================= +Boot image header in RISC-V Linux +================================= -Author: Atish Patra -Date : 20 May 2019 +:Author: Atish Patra +:Date: 20 May 2019 This document only describes the boot image header details for RISC-V Linux. -The complete booting guide will be available at Documentation/riscv/booting.txt. -The following 64-byte header is present in decompressed Linux kernel image. +TODO: + Write a complete booting guide. + +The following 64-byte header is present in decompressed Linux kernel image:: u32 code0; /* Executable code */ - u32 code1; /* Executable code */ + u32 code1; /* Executable code */ u64 text_offset; /* Image load offset, little endian */ u64 image_size; /* Effective Image size, little endian */ u64 flags; /* kernel flags, little endian */ u32 version; /* Version of this header */ - u32 res1 = 0; /* Reserved */ - u64 res2 = 0; /* Reserved */ + u32 res1 = 0; /* Reserved */ + u64 res2 = 0; /* Reserved */ u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ u32 res3; /* Reserved for additional RISC-V specific header */ u32 res4; /* Reserved for PE COFF offset */ @@ -25,16 +28,21 @@ This header format is compliant with PE/COFF header and largely inspired from ARM64 header. Thus, both ARM64 & RISC-V header can be combined into one common header in future. -Notes: +Notes +===== + - This header can also be reused to support EFI stub for RISC-V in future. EFI specification needs PE/COFF image header in the beginning of the kernel image in order to load it as an EFI application. In order to support EFI stub, code0 should be replaced with "MZ" magic string and res5(at offset 0x3c) should point to the rest of the PE/COFF header. -- version field indicate header version number. - Bits 0:15 - Minor version - Bits 16:31 - Major version +- version field indicate header version number + + ========== ============= + Bits 0:15 Minor version + Bits 16:31 Major version + ========== ============= This preserves compatibility across newer and older version of the header. The current version is defined as 0.1. @@ -44,7 +52,10 @@ Notes: extension for RISC-V in future. For current version, it is set to be zero. - In current header, the flag field has only one field. - Bit 0: Kernel endianness. 1 if BE, 0 if LE. + + ===== ==================================== + Bit 0 Kernel endianness. 1 if BE, 0 if LE. + ===== ==================================== - Image size is mandatory for boot loader to load kernel image. Booting will fail otherwise. diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst index e3ca0922a8c2..215fd3c1f2d5 100644 --- a/Documentation/riscv/index.rst +++ b/Documentation/riscv/index.rst @@ -5,6 +5,7 @@ RISC-V architecture .. toctree:: :maxdepth: 1 + boot-image-header pmu .. only:: subproject and html From e226b4f0e04f4cd5396041661a27eae5aa370bb3 Mon Sep 17 00:00:00 2001 From: Federico Vaga Date: Sat, 6 Jul 2019 23:01:00 +0200 Subject: [PATCH 14/67] doc: email-clients miscellaneous fixes Fixed some style inconsistencies and remove old statement referring to kmail missing feature (saving email from the view window is possible). Signed-off-by: Federico Vaga Signed-off-by: Jonathan Corbet --- Documentation/process/email-clients.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index 07faa5457bcb..5273d06c8ff6 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -40,7 +40,7 @@ Emailed patches should be in ASCII or UTF-8 encoding only. If you configure your email client to send emails with UTF-8 encoding, you avoid some possible charset problems. -Email clients should generate and maintain References: or In-Reply-To: +Email clients should generate and maintain "References:" or "In-Reply-To:" headers so that mail threading is not broken. Copy-and-paste (or cut-and-paste) usually does not work for patches @@ -89,7 +89,7 @@ Claws Mail (GUI) Works. Some people use this successfully for patches. -To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) +To insert a patch use :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) or an external editor. If the inserted patch has to be edited in the Claws composition window @@ -132,8 +132,8 @@ wrapping. At the bottom of your email, put the commonly-used patch delimiter before inserting your patch: three hyphens (``---``). -Then from the :menuselection:`Message` menu item, select insert file and -choose your patch. +Then from the :menuselection:`Message` menu item, select +:menuselection:`insert file` and choose your patch. As an added bonus you can customise the message creation toolbar menu and put the :menuselection:`insert file` icon there. @@ -149,18 +149,16 @@ patches so do not GPG sign them. Signing patches that have been inserted as inlined text will make them tricky to extract from their 7-bit encoding. If you absolutely must send patches as attachments instead of inlining -them as text, right click on the attachment and select properties, and -highlight :menuselection:`Suggest automatic display` to make the attachment +them as text, right click on the attachment and select :menuselection:`properties`, +and highlight :menuselection:`Suggest automatic display` to make the attachment inlined to make it more viewable. When saving patches that are sent as inlined text, select the email that contains the patch from the message list pane, right click and select :menuselection:`save as`. You can use the whole email unmodified as a patch -if it was properly composed. There is no option currently to save the email -when you are actually viewing it in its own window -- there has been a request -filed at kmail's bugzilla and hopefully this will be addressed. Emails are -saved as read-write for user only so you will have to chmod them to make them -group and world readable if you copy them elsewhere. +if it was properly composed. Emails are saved as read-write for user only so +you will have to chmod them to make them group and world readable if you copy +them elsewhere. Lotus Notes (GUI) ***************** From ac841c4e457c1fae6f661108f811b554c8581976 Mon Sep 17 00:00:00 2001 From: Shobhit Kukreti Date: Wed, 10 Jul 2019 08:29:01 -0700 Subject: [PATCH 15/67] Documentation: filesystems: Convert jfs.txt to This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs Signed-off-by: Shobhit Kukreti Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 1 + .../jfs.txt => admin-guide/jfs.rst} | 44 ++++++++++++------- 2 files changed, 30 insertions(+), 15 deletions(-) rename Documentation/{filesystems/jfs.txt => admin-guide/jfs.rst} (51%) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 33feab2f4084..2376cb91b83c 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -78,6 +78,7 @@ configure specific aspects of kernel behavior to your liking. ext4 binderfs xfs + jfs pm/index thunderbolt LSM/index diff --git a/Documentation/filesystems/jfs.txt b/Documentation/admin-guide/jfs.rst similarity index 51% rename from Documentation/filesystems/jfs.txt rename to Documentation/admin-guide/jfs.rst index 41fd757997b3..9e12d936bc90 100644 --- a/Documentation/filesystems/jfs.txt +++ b/Documentation/admin-guide/jfs.rst @@ -1,45 +1,59 @@ +=========================================== IBM's Journaled File System (JFS) for Linux +=========================================== JFS Homepage: http://jfs.sourceforge.net/ The following mount options are supported: + (*) == default -iocharset=name Character set to use for converting from Unicode to +iocharset=name + Character set to use for converting from Unicode to ASCII. The default is to do no conversion. Use iocharset=utf8 for UTF-8 translations. This requires CONFIG_NLS_UTF8 to be set in the kernel .config file. iocharset=none specifies the default behavior explicitly. -resize=value Resize the volume to blocks. JFS only supports +resize=value + Resize the volume to blocks. JFS only supports growing a volume, not shrinking it. This option is only valid during a remount, when the volume is mounted read-write. The resize keyword with no value will grow the volume to the full size of the partition. -nointegrity Do not write to the journal. The primary use of this option +nointegrity + Do not write to the journal. The primary use of this option is to allow for higher performance when restoring a volume from backup media. The integrity of the volume is not guaranteed if the system abnormally abends. -integrity(*) Commit metadata changes to the journal. Use this option to +integrity(*) + Commit metadata changes to the journal. Use this option to remount a volume where the nointegrity option was previously specified in order to restore normal behavior. -errors=continue Keep going on a filesystem error. -errors=remount-ro(*) Remount the filesystem read-only on an error. -errors=panic Panic and halt the machine if an error occurs. +errors=continue + Keep going on a filesystem error. +errors=remount-ro(*) + Remount the filesystem read-only on an error. +errors=panic + Panic and halt the machine if an error occurs. -uid=value Override on-disk uid with specified value -gid=value Override on-disk gid with specified value -umask=value Override on-disk umask with specified octal value. For - directories, the execute bit will be set if the corresponding +uid=value + Override on-disk uid with specified value +gid=value + Override on-disk gid with specified value +umask=value + Override on-disk umask with specified octal value. For + directories, the execute bit will be set if the corresponding read bit is set. -discard=minlen This enables/disables the use of discard/TRIM commands. -discard The discard/TRIM commands are sent to the underlying -nodiscard(*) block device when blocks are freed. This is useful for SSD - devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl +discard=minlen, discard/nodiscard(*) + This enables/disables the use of discard/TRIM commands. + The discard/TRIM commands are sent to the underlying + block device when blocks are freed. This is useful for SSD + devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl command is also available together with the nodiscard option. The value of minlen specifies the minimum blockcount, when a TRIM command to the block device is considered useful. From 34d5f4f269a21c7b5d64b4db0391d36511f1ac1a Mon Sep 17 00:00:00 2001 From: Shobhit Kukreti Date: Wed, 10 Jul 2019 08:31:23 -0700 Subject: [PATCH 16/67] Documentation: filesystems: Convert ufs.txt to reStructuredText format This converts the plain text documentation of ufs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs Signed-off-by: Shobhit Kukreti Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 1 + .../ufs.txt => admin-guide/ufs.rst} | 36 +++++++++++-------- 2 files changed, 23 insertions(+), 14 deletions(-) rename Documentation/{filesystems/ufs.txt => admin-guide/ufs.rst} (69%) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 2376cb91b83c..592107a3295f 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -79,6 +79,7 @@ configure specific aspects of kernel behavior to your liking. binderfs xfs jfs + ufs pm/index thunderbolt LSM/index diff --git a/Documentation/filesystems/ufs.txt b/Documentation/admin-guide/ufs.rst similarity index 69% rename from Documentation/filesystems/ufs.txt rename to Documentation/admin-guide/ufs.rst index 7a602adeca2b..55d15297f8d7 100644 --- a/Documentation/filesystems/ufs.txt +++ b/Documentation/admin-guide/ufs.rst @@ -1,37 +1,45 @@ -USING UFS +========= +Using UFS ========= mount -t ufs -o ufstype=type_of_ufs device dir -UFS OPTIONS +UFS Options =========== ufstype=type_of_ufs UFS is a file system widely used in different operating systems. The problem are differences among implementations. Features of some implementations are undocumented, so its hard to recognize - type of ufs automatically. That's why user must specify type of + type of ufs automatically. That's why user must specify type of ufs manually by mount option ufstype. Possible values are: - old old format of ufs + old + old format of ufs default value, supported as read-only - 44bsd used in FreeBSD, NetBSD, OpenBSD + 44bsd + used in FreeBSD, NetBSD, OpenBSD supported as read-write - ufs2 used in FreeBSD 5.x + ufs2 + used in FreeBSD 5.x supported as read-write - 5xbsd synonym for ufs2 + 5xbsd + synonym for ufs2 - sun used in SunOS (Solaris) + sun + used in SunOS (Solaris) supported as read-write - sunx86 used in SunOS for Intel (Solarisx86) + sunx86 + used in SunOS for Intel (Solarisx86) supported as read-write - hp used in HP-UX + hp + used in HP-UX supported as read-only nextstep @@ -47,14 +55,14 @@ ufstype=type_of_ufs supported as read-only -POSSIBLE PROBLEMS -================= +Possible Problems +----------------- See next section, if you have any. -BUG REPORTS -=========== +Bug Reports +----------- Any ufs bug report you can send to daniel.pirkl@email.cz or to dushistov@mail.ru (do not send partition tables bug reports). From fe13225fdc3f7b79e2921869a13386f48b30bf79 Mon Sep 17 00:00:00 2001 From: Phong Tran Date: Thu, 11 Jul 2019 23:52:01 +0700 Subject: [PATCH 17/67] Documentation: coresight: convert txt to rst This changes from plain text to reStructuredText as suggestion in doc-guide [1] [1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html Some adaptations such as: literal block, ``inline literal`` and alignment text,... Signed-off-by: Phong Tran Reviewed-by: Mauro Carvalho Chehab Acked-by: Mathieu Poirier Signed-off-by: Jonathan Corbet --- ...-cpu-debug.txt => coresight-cpu-debug.rst} | 65 ++-- .../trace/{coresight.txt => coresight.rst} | 358 +++++++++--------- Documentation/trace/index.rst | 2 + MAINTAINERS | 4 +- 4 files changed, 226 insertions(+), 203 deletions(-) rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%) rename Documentation/trace/{coresight.txt => coresight.rst} (56%) diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst similarity index 84% rename from Documentation/trace/coresight-cpu-debug.txt rename to Documentation/trace/coresight-cpu-debug.rst index 1a660a39e3c0..993dd294b81b 100644 --- a/Documentation/trace/coresight-cpu-debug.txt +++ b/Documentation/trace/coresight-cpu-debug.rst @@ -1,8 +1,9 @@ - Coresight CPU Debug Module - ========================== +========================== +Coresight CPU Debug Module +========================== - Author: Leo Yan - Date: April 5th, 2017 + :Author: Leo Yan + :Date: April 5th, 2017 Introduction ------------ @@ -69,6 +70,7 @@ Before accessing debug registers, we should ensure the clock and power domain have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1 Debug registers', the debug registers are spread into two domains: the debug domain and the CPU domain. +:: +---------------+ | | @@ -125,18 +127,21 @@ If you want to enable debugging functionality at boot time, you can add "coresight_cpu_debug.enable=1" to the kernel command line parameter. The driver also can work as module, so can enable the debugging when insmod -module: -# insmod coresight_cpu_debug.ko debug=1 +module:: + + # insmod coresight_cpu_debug.ko debug=1 When boot time or insmod module you have not enabled the debugging, the driver uses the debugfs file system to provide a knob to dynamically enable or disable debugging: -To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable: -# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable +To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:: -To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable: -# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable + # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable + +To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:: + + # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable As explained in chapter "Clock and power domain", if you are working on one platform which has idle states to power off debug logic and the power @@ -154,34 +159,34 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency" interface (see Documentation/power/pm_qos_interface.rst for more details). As specified in the PM QoS documentation the requested parameter will stay in effect until the file descriptor is released. -For example: +For example:: -# exec 3<> /dev/cpu_dma_latency; echo 0 >&3 -... -Do some work... -... -# exec 3<>- + # exec 3<> /dev/cpu_dma_latency; echo 0 >&3 + ... + Do some work... + ... + # exec 3<>- The same can also be done from an application program. Disable specific CPU's specific idle state from cpuidle sysfs (see -Documentation/admin-guide/pm/cpuidle.rst): -# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable +Documentation/admin-guide/pm/cpuidle.rst):: + # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable Output format ------------- -Here is an example of the debugging output format: +Here is an example of the debugging output format:: -ARM external debug module: -coresight-cpu-debug 850000.debug: CPU[0]: -coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) -coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8 -coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 -coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) -coresight-cpu-debug 852000.debug: CPU[1]: -coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) -coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358 -coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 -coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) + ARM external debug module: + coresight-cpu-debug 850000.debug: CPU[0]: + coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) + coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8 + coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 + coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) + coresight-cpu-debug 852000.debug: CPU[1]: + coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) + coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358 + coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 + coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst similarity index 56% rename from Documentation/trace/coresight.txt rename to Documentation/trace/coresight.rst index b027d61b27a6..72f4b7ef1bad 100644 --- a/Documentation/trace/coresight.txt +++ b/Documentation/trace/coresight.rst @@ -1,8 +1,9 @@ - Coresight - HW Assisted Tracing on ARM - ====================================== +====================================== +Coresight - HW Assisted Tracing on ARM +====================================== - Author: Mathieu Poirier - Date: September 11th, 2014 + :Author: Mathieu Poirier + :Date: September 11th, 2014 Introduction ------------ @@ -26,7 +27,7 @@ implementation, either storing the compressed stream in a memory buffer or creating an interface to the outside world where data can be transferred to a host without fear of filling up the onboard coresight memory buffer. -At typical coresight system would look like this: +At typical coresight system would look like this:: ***************************************************************** **************************** AMBA AXI ****************************===|| @@ -95,15 +96,24 @@ Acronyms and Classification Acronyms: -PTM: Program Trace Macrocell -ETM: Embedded Trace Macrocell -STM: System trace Macrocell -ETB: Embedded Trace Buffer -ITM: Instrumentation Trace Macrocell -TPIU: Trace Port Interface Unit -TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router -TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO -CTI: Cross Trigger Interface +PTM: + Program Trace Macrocell +ETM: + Embedded Trace Macrocell +STM: + System trace Macrocell +ETB: + Embedded Trace Buffer +ITM: + Instrumentation Trace Macrocell +TPIU: + Trace Port Interface Unit +TMC-ETR: + Trace Memory Controller, configured as Embedded Trace Router +TMC-ETF: + Trace Memory Controller, configured as Embedded Trace FIFO +CTI: + Cross Trigger Interface Classification: @@ -118,7 +128,7 @@ Misc: Device Tree Bindings ----------------------- +-------------------- See Documentation/devicetree/bindings/arm/coresight.txt for details. @@ -133,79 +143,79 @@ The coresight framework provides a central point to represent, configure and manage coresight devices on a platform. Any coresight compliant device can register with the framework for as long as they use the right APIs: -struct coresight_device *coresight_register(struct coresight_desc *desc); -void coresight_unregister(struct coresight_device *csdev); +.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc); +.. c:function:: void coresight_unregister(struct coresight_device *csdev); -The registering function is taking a "struct coresight_device *csdev" and -register the device with the core framework. The unregister function takes -a reference to a "struct coresight_device", obtained at registration time. +The registering function is taking a ``struct coresight_desc *desc`` and +register the device with the core framework. The unregister function takes +a reference to a ``struct coresight_device *csdev`` obtained at registration time. If everything goes well during the registration process the new devices will -show up under /sys/bus/coresight/devices, as showns here for a TC2 platform: +show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:: -root:~# ls /sys/bus/coresight/devices/ -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm -root:~# + root:~# ls /sys/bus/coresight/devices/ + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm + root:~# -The functions take a "struct coresight_device", which looks like this: +The functions take a ``struct coresight_device``, which looks like this:: -struct coresight_desc { - enum coresight_dev_type type; - struct coresight_dev_subtype subtype; - const struct coresight_ops *ops; - struct coresight_platform_data *pdata; - struct device *dev; - const struct attribute_group **groups; -}; + struct coresight_desc { + enum coresight_dev_type type; + struct coresight_dev_subtype subtype; + const struct coresight_ops *ops; + struct coresight_platform_data *pdata; + struct device *dev; + const struct attribute_group **groups; + }; The "coresight_dev_type" identifies what the device is, i.e, source link or sink while the "coresight_dev_subtype" will characterise that type further. -The "struct coresight_ops" is mandatory and will tell the framework how to +The ``struct coresight_ops`` is mandatory and will tell the framework how to perform base operations related to the components, each component having -a different set of requirement. For that "struct coresight_ops_sink", -"struct coresight_ops_link" and "struct coresight_ops_source" have been +a different set of requirement. For that ``struct coresight_ops_sink``, +``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been provided. -The next field, "struct coresight_platform_data *pdata" is acquired by calling -"of_get_coresight_platform_data()", as part of the driver's _probe routine and -"struct device *dev" gets the device reference embedded in the "amba_device": +The next field ``struct coresight_platform_data *pdata`` is acquired by calling +``of_get_coresight_platform_data()``, as part of the driver's _probe routine and +``struct device *dev`` gets the device reference embedded in the ``amba_device``:: -static int etm_probe(struct amba_device *adev, const struct amba_id *id) -{ - ... - ... - drvdata->dev = &adev->dev; - ... -} + static int etm_probe(struct amba_device *adev, const struct amba_id *id) + { + ... + ... + drvdata->dev = &adev->dev; + ... + } Specific class of device (source, link, or sink) have generic operations -that can be performed on them (see "struct coresight_ops"). The -"**groups" is a list of sysfs entries pertaining to operations +that can be performed on them (see ``struct coresight_ops``). The ``**groups`` +is a list of sysfs entries pertaining to operations specific to that component only. "Implementation defined" customisations are expected to be accessed and controlled using those entries. - Device Naming scheme ------------------------- +-------------------- + The devices that appear on the "coresight" bus were named the same as their parent devices, i.e, the real devices that appears on AMBA bus or the platform bus. Thus the names were based on the Linux Open Firmware layer naming convention, which follows the base physical address of the device followed by the device -type. e.g: +type. e.g:: -root:~# ls /sys/bus/coresight/devices/ - 20010000.etf 20040000.funnel 20100000.stm 22040000.etm - 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu - 20070000.etr 20120000.replicator 220c0000.funnel - 23040000.etm 23140000.etm 23340000.etm + root:~# ls /sys/bus/coresight/devices/ + 20010000.etf 20040000.funnel 20100000.stm 22040000.etm + 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu + 20070000.etr 20120000.replicator 220c0000.funnel + 23040000.etm 23140000.etm 23340000.etm However, with the introduction of ACPI support, the names of the real devices are a bit cryptic and non-obvious. Thus, a new naming scheme was introduced to use more generic names based on the type of the device. The -following rules apply: +following rules apply:: 1) Devices that are bound to CPUs, are named based on the CPU logical number. @@ -220,11 +230,11 @@ following rules apply: e.g, tmc_etf0, tmc_etr0, funnel0, funnel1 -Thus, with the new scheme the devices could appear as : +Thus, with the new scheme the devices could appear as :: -root:~# ls /sys/bus/coresight/devices/ - etm0 etm1 etm2 etm3 etm4 etm5 funnel0 - funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 + root:~# ls /sys/bus/coresight/devices/ + etm0 etm1 etm2 etm3 etm4 etm5 funnel0 + funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 Some of the examples below might refer to old naming scheme and some to the newer scheme, to give a confirmation that what you see on your @@ -234,9 +244,12 @@ the system under specified locations. How to use the tracer modules ----------------------------- -There are two ways to use the Coresight framework: 1) using the perf cmd line -tools and 2) interacting directly with the Coresight devices using the sysFS -interface. Preference is given to the former as using the sysFS interface +There are two ways to use the Coresight framework: + +1. using the perf cmd line tools. +2. interacting directly with the Coresight devices using the sysFS interface. + +Preference is given to the former as using the sysFS interface requires a deep understanding of the Coresight HW. The following sections provide details on using both methods. @@ -245,107 +258,107 @@ provide details on using both methods. Before trace collection can start, a coresight sink needs to be identified. There is no limit on the amount of sinks (nor sources) that can be enabled at any given moment. As a generic operation, all device pertaining to the sink -class will have an "active" entry in sysfs: +class will have an "active" entry in sysfs:: -root:/sys/bus/coresight/devices# ls -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm -root:/sys/bus/coresight/devices# ls 20010000.etb -enable_sink status trigger_cntr -root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink -root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink -1 -root:/sys/bus/coresight/devices# + root:/sys/bus/coresight/devices# ls + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm + root:/sys/bus/coresight/devices# ls 20010000.etb + enable_sink status trigger_cntr + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink + 1 + root:/sys/bus/coresight/devices# At boot time the current etm3x driver will configure the first address comparator with "_stext" and "_etext", essentially tracing any instruction that falls within that range. As such "enabling" a source will immediately -trigger a trace capture: +trigger a trace capture:: -root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source -root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source -1 -root:/sys/bus/coresight/devices# cat 20010000.etb/status -Depth: 0x2000 -Status: 0x1 -RAM read ptr: 0x0 -RAM wrt ptr: 0x19d3 <----- The write pointer is moving -Trigger cnt: 0x0 -Control: 0x1 -Flush status: 0x0 -Flush ctrl: 0x2001 -root:/sys/bus/coresight/devices# + root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source + root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source + 1 + root:/sys/bus/coresight/devices# cat 20010000.etb/status + Depth: 0x2000 + Status: 0x1 + RAM read ptr: 0x0 + RAM wrt ptr: 0x19d3 <----- The write pointer is moving + Trigger cnt: 0x0 + Control: 0x1 + Flush status: 0x0 + Flush ctrl: 0x2001 + root:/sys/bus/coresight/devices# -Trace collection is stopped the same way: +Trace collection is stopped the same way:: -root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source -root:/sys/bus/coresight/devices# + root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source + root:/sys/bus/coresight/devices# -The content of the ETB buffer can be harvested directly from /dev: +The content of the ETB buffer can be harvested directly from /dev:: -root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ -of=~/cstrace.bin - -64+0 records in -64+0 records out -32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s -root:/sys/bus/coresight/devices# + root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ + of=~/cstrace.bin + 64+0 records in + 64+0 records out + 32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s + root:/sys/bus/coresight/devices# The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32. Following is a DS-5 output of an experimental loop that increments a variable up to a certain value. The example is simple and yet provides a glimpse of the wealth of possibilities that coresight provides. +:: -Info Tracing enabled -Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} -Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc -Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 -Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Timestamp Timestamp: 17106715833 -Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] -Instruction 0 0x8026B550 E3530004 false CMP r3,#4 -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c -Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 -Instruction 0 0x8026B564 E1A0100D false MOV r1,sp -Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 -Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f -Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] -Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 -Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] -Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] -Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 -Info Tracing enabled -Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc -Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} -Timestamp Timestamp: 17107041535 + Info Tracing enabled + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Timestamp Timestamp: 17106715833 + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 + Info Tracing enabled + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} + Timestamp Timestamp: 17107041535 2) Using perf framework: @@ -370,19 +383,18 @@ A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is listed along with configuration options within forward slashes '/'. Since a Coresight system will typically have more than one sink, the name of the sink to work with needs to be specified as an event option. -On newer kernels the available sinks are listed in sysFS under: -($SYSFS)/bus/event_source/devices/cs_etm/sinks/ +On newer kernels the available sinks are listed in sysFS under +($SYSFS)/bus/event_source/devices/cs_etm/sinks/:: root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls tmc_etf0 tmc_etr0 tpiu0 On older kernels, this may need to be found from the list of coresight devices, -available under ($SYSFS)/bus/coresight/devices/: +available under ($SYSFS)/bus/coresight/devices/:: root:~# ls /sys/bus/coresight/devices/ etm0 etm1 etm2 etm3 etm4 etm5 funnel0 funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 - root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program As mentioned above in section "Device Naming scheme", the names of the devices could @@ -395,14 +407,14 @@ to use for the trace session. More information on the above and other example on how to use Coresight with the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub -repository [3]. +repository [#third]_. 2.1) AutoFDO analysis using the perf tools: perf can be used to record and analyze trace of programs. Execution can be recorded using 'perf record' with the cs_etm event, -specifying the name of the sink to record to, e.g: +specifying the name of the sink to record to, e.g:: perf record -e cs_etm/@tmc_etr0/u --per-thread @@ -421,12 +433,14 @@ Generating coverage files for Feedback Directed Optimization: AutoFDO 'perf inject' accepts the --itrace option in which case tracing data is removed and replaced with the synthesized events. e.g. +:: perf inject --itrace --strip -i perf.data -o perf.data.new Below is an example of using ARM ETM for autoFDO. It requires autofdo (https://github.com/google/autofdo) and gcc version 5. The bubble sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial). +:: $ gcc-5 -O3 sort.c -o sort $ taskset -c 2 ./sort @@ -455,28 +469,30 @@ difference is that clients are driving the trace capture rather than the program flow through the code. As with any other CoreSight component, specifics about the STM tracer can be -found in sysfs with more information on each entry being found in [1]: +found in sysfs with more information on each entry being found in [#first]_:: -root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0 -enable_source hwevent_select port_enable subsystem uevent -hwevent_enable mgmt port_select traceid -root@genericarmv8:~# + root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0 + enable_source hwevent_select port_enable subsystem uevent + hwevent_enable mgmt port_select traceid + root@genericarmv8:~# Like any other source a sink needs to be identified and the STM enabled before -being used: +being used:: -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source From there user space applications can request and use channels using the devfs -interface provided for that purpose by the generic STM API: +interface provided for that purpose by the generic STM API:: -root@genericarmv8:~# ls -l /dev/stm0 -crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0 -root@genericarmv8:~# + root@genericarmv8:~# ls -l /dev/stm0 + crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0 + root@genericarmv8:~# -Details on how to use the generic STM API can be found here [2]. +Details on how to use the generic STM API can be found here [#second]_. -[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm -[2]. Documentation/trace/stm.rst -[3]. https://github.com/Linaro/perf-opencsd +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm + +.. [#second] Documentation/trace/stm.rst + +.. [#third] https://github.com/Linaro/perf-opencsd diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index 6b4107cf4b98..b7891cb1ab4d 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -23,3 +23,5 @@ Linux Tracing Technologies intel_th stm sys-t + coresight + coresight-cpu-debug diff --git a/MAINTAINERS b/MAINTAINERS index 811218cc2355..7a07cda43592 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1582,8 +1582,8 @@ R: Suzuki K Poulose L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers) S: Maintained F: drivers/hwtracing/coresight/* -F: Documentation/trace/coresight.txt -F: Documentation/trace/coresight-cpu-debug.txt +F: Documentation/trace/coresight.rst +F: Documentation/trace/coresight-cpu-debug.rst F: Documentation/devicetree/bindings/arm/coresight.txt F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt F: Documentation/ABI/testing/sysfs-bus-coresight-devices-* From eaf7b46083a7e341a23ab3d6042e0ccc115b0914 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:12 -0300 Subject: [PATCH 18/67] docs: thermal: add it to the driver API The file contents mostly describes driver internals. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/driver-api/index.rst | 1 + .../{ => driver-api}/thermal/cpu-cooling-api.rst | 0 .../{ => driver-api}/thermal/exynos_thermal.rst | 0 .../thermal/exynos_thermal_emulation.rst | 0 Documentation/{ => driver-api}/thermal/index.rst | 2 +- .../{ => driver-api}/thermal/intel_powerclamp.rst | 0 .../{ => driver-api}/thermal/nouveau_thermal.rst | 0 .../{ => driver-api}/thermal/power_allocator.rst | 0 Documentation/{ => driver-api}/thermal/sysfs-api.rst | 12 ++++++------ .../thermal/x86_pkg_temperature_thermal.rst | 2 +- MAINTAINERS | 2 +- include/linux/thermal.h | 4 ++-- 12 files changed, 12 insertions(+), 11 deletions(-) rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%) rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%) rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%) rename Documentation/{ => driver-api}/thermal/index.rst (86%) rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%) rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%) rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%) rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%) rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%) diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index d12a80f386a6..37ac052ded85 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -65,6 +65,7 @@ available subsections can be seen below. dmaengine/index slimbus soundwire/index + thermal/index fpga/index acpi/index backlight/lp855x-driver.rst diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst similarity index 100% rename from Documentation/thermal/cpu-cooling-api.rst rename to Documentation/driver-api/thermal/cpu-cooling-api.rst diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst similarity index 100% rename from Documentation/thermal/exynos_thermal.rst rename to Documentation/driver-api/thermal/exynos_thermal.rst diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst similarity index 100% rename from Documentation/thermal/exynos_thermal_emulation.rst rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst similarity index 86% rename from Documentation/thermal/index.rst rename to Documentation/driver-api/thermal/index.rst index 8c1c00146cad..5ba61d19c6ae 100644 --- a/Documentation/thermal/index.rst +++ b/Documentation/driver-api/thermal/index.rst @@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 ======= Thermal diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst similarity index 100% rename from Documentation/thermal/intel_powerclamp.rst rename to Documentation/driver-api/thermal/intel_powerclamp.rst diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst similarity index 100% rename from Documentation/thermal/nouveau_thermal.rst rename to Documentation/driver-api/thermal/nouveau_thermal.rst diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst similarity index 100% rename from Documentation/thermal/power_allocator.rst rename to Documentation/driver-api/thermal/power_allocator.rst diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst similarity index 98% rename from Documentation/thermal/sysfs-api.rst rename to Documentation/driver-api/thermal/sysfs-api.rst index e4930761d3e5..fab2c9b36d08 100644 --- a/Documentation/thermal/sysfs-api.rst +++ b/Documentation/driver-api/thermal/sysfs-api.rst @@ -552,7 +552,7 @@ emul_temp sustainable_power An estimate of the sustained power that can be dissipated by the thermal zone. Used by the power allocator governor. For - more information see Documentation/thermal/power_allocator.rst + more information see Documentation/driver-api/thermal/power_allocator.rst Unit: milliwatts @@ -563,7 +563,7 @@ k_po controller during temperature overshoot. Temperature overshoot is when the current temperature is above the "desired temperature" trip point. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional @@ -572,7 +572,7 @@ k_pu controller during temperature undershoot. Temperature undershoot is when the current temperature is below the "desired temperature" trip point. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional @@ -580,14 +580,14 @@ k_i The integral term of the power allocator governor's PID controller. This term allows the PID controller to compensate for long term drift. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional k_d The derivative term of the power allocator governor's PID controller. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst RW, Optional @@ -598,7 +598,7 @@ integral_cutoff example, if integral_cutoff is 0, then the integral term only accumulates error when temperature is above the desired temperature trip point. For more information see - Documentation/thermal/power_allocator.rst + Documentation/driver-api/thermal/power_allocator.rst Unit: millidegree Celsius diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst similarity index 94% rename from Documentation/thermal/x86_pkg_temperature_thermal.rst rename to Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst index f134dbd3f5a9..2ac42ccd236f 100644 --- a/Documentation/thermal/x86_pkg_temperature_thermal.rst +++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst @@ -40,7 +40,7 @@ This contains two trip points: - trip_point_1_temp User can set any temperature between 0 to TJ-Max temperature. Temperature units -are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for +are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for thermal sys-fs details. Any value other than 0 in these trip points, can trigger thermal notifications. diff --git a/MAINTAINERS b/MAINTAINERS index 7a07cda43592..6326445952f6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -15916,7 +15916,7 @@ M: Viresh Kumar M: Javi Merino L: linux-pm@vger.kernel.org S: Supported -F: Documentation/thermal/cpu-cooling-api.rst +F: Documentation/driver-api/thermal/cpu-cooling-api.rst F: drivers/thermal/cpu_cooling.c F: include/linux/cpu_cooling.h diff --git a/include/linux/thermal.h b/include/linux/thermal.h index 681047f8cc05..e45659c75920 100644 --- a/include/linux/thermal.h +++ b/include/linux/thermal.h @@ -251,7 +251,7 @@ struct thermal_bind_params { * platform characterization. This value is relative to the * rest of the weights so a cooling device whose weight is * double that of another cooling device is twice as - * effective. See Documentation/thermal/sysfs-api.rst for more + * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more * information. */ int weight; @@ -259,7 +259,7 @@ struct thermal_bind_params { /* * This is a bit mask that gives the binding relation between this * thermal zone and cdev, for a particular trip point. - * See Documentation/thermal/sysfs-api.rst for more information. + * See Documentation/driver-api/thermal/sysfs-api.rst for more information. */ int trip_mask; From 09f4c750a8c7d1fc0b7bb3a7aa1de55de897a375 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:14 -0300 Subject: [PATCH 19/67] docs: ubifs-authentication.md: convert to ReST The documentation standard is ReST and not markdown. Signed-off-by: Mauro Carvalho Chehab Acked-by: Rob Herring Signed-off-by: Jonathan Corbet --- ...entication.md => ubifs-authentication.rst} | 70 ++++++++++++------- 1 file changed, 44 insertions(+), 26 deletions(-) rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%) diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.rst similarity index 95% rename from Documentation/filesystems/ubifs-authentication.md rename to Documentation/filesystems/ubifs-authentication.rst index 23e698167141..6a9584f6ff46 100644 --- a/Documentation/filesystems/ubifs-authentication.md +++ b/Documentation/filesystems/ubifs-authentication.rst @@ -1,8 +1,11 @@ -% UBIFS Authentication -% sigma star gmbh -% 2018 +:orphan: -# Introduction +.. UBIFS Authentication +.. sigma star gmbh +.. 2018 + +Introduction +============ UBIFS utilizes the fscrypt framework to provide confidentiality for file contents and file names. This prevents attacks where an attacker is able to @@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also be possible to use UBIFS authentication without using encryption. -## MTD, UBI & UBIFS +MTD, UBI & UBIFS +---------------- On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform interface to access raw flash devices. One of the more prominent subsystems that @@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear leveling and some flash specifics are left to UBI, while UBIFS focuses on scalability, performance and recoverability. - +:: +------------+ +*******+ +-----------+ +-----+ | | * UBIFS * | UBI-BLOCK | | ... | @@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in [UBIFS-WP]. -### UBIFS Index & Tree Node Cache +UBIFS Index & Tree Node Cache +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file @@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes marked as dirty are written to the flash to update the persisted index. -### Journal +Journal +~~~~~~~ To avoid wearing out the flash, the index is only persisted (*commited*) when -certain conditions are met (eg. `fsync(2)`). The journal is used to record +certain conditions are met (eg. ``fsync(2)``). The journal is used to record any changes (in form of inode nodes, data nodes etc.) between commits of the index. During mount, the journal is read from the flash and replayed onto the TNC (which will be created on-demand from the on-flash index). UBIFS reserves a bunch of LEBs just for the journal called *log area*. The amount of log area LEBs is configured on filesystem creation (using -`mkfs.ubifs`) and stored in the superblock node. The log area contains only +``mkfs.ubifs``) and stored in the superblock node. The log area contains only two types of nodes: *reference nodes* and *commit start nodes*. A commit start node is written whenever an index commit is performed. Reference nodes are written on every journal update. Each reference node points to the position of @@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt because of a power cut. If the recovery fails, UBIFS will not mount. An error for every other LEB will directly cause UBIFS to fail the mount operation. +:: | ---- LOG AREA ---- | ---------- MAIN AREA ------------ | @@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation. containing their buds -### LEB Property Tree/Table +LEB Property Tree/Table +~~~~~~~~~~~~~~~~~~~~~~~ The LEB property tree is used to store per-LEB information. This includes the -LEB type and amount of free and *dirty* (old, obsolete content) space [1] on +LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on the LEB. The type is important, because UBIFS never mixes index nodes with data nodes on a single LEB and thus each LEB has a specific purpose. This again is useful for free space calculations. See [UBIFS-WP] for more details. @@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every commit. Thus, saving the LPT is an atomic operation. -[1] Since LEBs can only be appended and never overwritten, there is a -difference between free space ie. the remaining space left on the LEB to be -written to without erasing it and previously written content that is obsolete -but can't be overwritten without erasing the full LEB. +.. [1] Since LEBs can only be appended and never overwritten, there is a + difference between free space ie. the remaining space left on the LEB to be + written to without erasing it and previously written content that is obsolete + but can't be overwritten without erasing the full LEB. -# UBIFS Authentication +UBIFS Authentication +==================== This chapter introduces UBIFS authentication which enables UBIFS to verify the authenticity and integrity of metadata and file contents stored on flash. -## Threat Model +Threat Model +------------ UBIFS authentication enables detection of offline data modification. While it does not prevent it, it enables (trusted) code to check the integrity and @@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to ensure that only trusted code is executed on a device. -## Authentication +Authentication +-------------- To be able to fully trust data read from flash, all UBIFS data structures stored on flash are authenticated. That is: @@ -236,7 +247,8 @@ stored on flash are authenticated. That is: - The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting -### Index Authentication +Index Authentication +~~~~~~~~~~~~~~~~~~~~ Through UBIFS' concept of a wandering tree, it already takes care of only updating and persisting changed parts from leaf node up to the root node @@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces the storage overhead which is precious for users of UBIFS (ie. embedded devices). +:: +---------------+ | Master Node | @@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted atomically together with its respective node. -### Journal Authentication +Journal Authentication +~~~~~~~~~~~~~~~~~~~~~~ The journal is authenticated too. Since the journal is continuously written it is necessary to also add authentication information frequently to the @@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last authentication node. The tail of the journal which may not have a authentication node cannot be authenticated and is skipped during journal replay. -We get this picture for journal authentication: +We get this picture for journal authentication:: ,,,,,,,, ,......,........................................... @@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only modified on feature flag or similar changes, but never on file changes. -### LPT Authentication +LPT Authentication +~~~~~~~~~~~~~~~~~~ The location of the LPT root node on the flash is stored in the UBIFS master node. Since the LPT is written and read atomically on every commit, there is @@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the LTP hash stored there with the hash computed from the read on-flash LPT. -## Key Management +Key Management +-------------- For simplicity, UBIFS authentication uses a single key to compute the HMACs of superblock, master, commit start and reference nodes. This key has to be @@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2 [FSCRYPT-POLICY2]. -# Future Extensions +Future Extensions +================= In certain cases where a vendor wants to provide an authenticated filesystem image to customers, it should be possible to do so without sharing the secret @@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key will then have to be provided beforehand in the normal way. -# References +References +========== [CRYPTSETUP2] http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html From ccf988b66d697efcd0ceccc2398e0d9b909cd17c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:16 -0300 Subject: [PATCH 20/67] docs: i2c: convert to ReST and add to driver-api bookset Convert each file at I2C subsystem, renaming them to .rst and adding to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Wolfram Sang Acked-by: Alexandre Belloni Acked-by: Jonathan Cameron Signed-off-by: Jonathan Corbet --- .../devicetree/bindings/i2c/i2c-mux-gpmux.txt | 2 +- Documentation/driver-api/ipmb.rst | 2 +- Documentation/hwmon/adm1021.rst | 2 +- Documentation/hwmon/adm1275.rst | 2 +- Documentation/hwmon/hih6130.rst | 2 +- Documentation/hwmon/ibm-cffps.rst | 2 +- Documentation/hwmon/lm25066.rst | 2 +- Documentation/hwmon/max16064.rst | 2 +- Documentation/hwmon/max16065.rst | 2 +- Documentation/hwmon/max20751.rst | 2 +- Documentation/hwmon/max34440.rst | 2 +- Documentation/hwmon/max6650.rst | 2 +- Documentation/hwmon/max8688.rst | 2 +- Documentation/hwmon/menf21bmc.rst | 2 +- Documentation/hwmon/pcf8591.rst | 2 +- Documentation/hwmon/sht3x.rst | 2 +- Documentation/hwmon/shtc1.rst | 2 +- Documentation/hwmon/tmp103.rst | 2 +- Documentation/hwmon/tps40422.rst | 2 +- Documentation/hwmon/ucd9000.rst | 2 +- Documentation/hwmon/ucd9200.rst | 2 +- Documentation/hwmon/via686a.rst | 2 +- Documentation/hwmon/zl6100.rst | 2 +- .../busses/{i2c-ali1535 => i2c-ali1535.rst} | 13 +- .../busses/{i2c-ali1563 => i2c-ali1563.rst} | 3 + .../busses/{i2c-ali15x3 => i2c-ali15x3.rst} | 64 +++--- Documentation/i2c/busses/i2c-amd-mp2 | 23 -- Documentation/i2c/busses/i2c-amd-mp2.rst | 25 +++ .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} | 8 +- .../busses/{i2c-amd8111 => i2c-amd8111.rst} | 14 +- .../{i2c-diolan-u2c => i2c-diolan-u2c.rst} | 3 + .../i2c/busses/{i2c-i801 => i2c-i801.rst} | 33 +-- .../i2c/busses/{i2c-ismt => i2c-ismt.rst} | 20 +- .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst} | 6 + .../busses/{i2c-nforce2 => i2c-nforce2.rst} | 33 +-- .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} | 6 +- .../i2c/busses/{i2c-ocores => i2c-ocores.rst} | 22 +- Documentation/i2c/busses/i2c-parport | 178 --------------- ...2c-parport-light => i2c-parport-light.rst} | 8 +- Documentation/i2c/busses/i2c-parport.rst | 190 ++++++++++++++++ .../busses/{i2c-pca-isa => i2c-pca-isa.rst} | 9 +- .../i2c/busses/{i2c-piix4 => i2c-piix4.rst} | 18 +- .../busses/{i2c-sis5595 => i2c-sis5595.rst} | 19 +- Documentation/i2c/busses/i2c-sis630 | 58 ----- Documentation/i2c/busses/i2c-sis630.rst | 63 ++++++ .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} | 31 ++- .../busses/{i2c-taos-evm => i2c-taos-evm.rst} | 8 +- .../i2c/busses/{i2c-via => i2c-via.rst} | 28 ++- .../i2c/busses/{i2c-viapro => i2c-viapro.rst} | 12 +- Documentation/i2c/busses/index.rst | 33 +++ .../i2c/busses/{scx200_acb => scx200_acb.rst} | 9 +- .../i2c/{dev-interface => dev-interface.rst} | 94 ++++---- ...-considerations => dma-considerations.rst} | 0 .../i2c/{fault-codes => fault-codes.rst} | 5 +- .../i2c/{functionality => functionality.rst} | 22 +- ...ult-injection => gpio-fault-injection.rst} | 12 +- .../i2c/{i2c-protocol => i2c-protocol.rst} | 28 ++- Documentation/i2c/{i2c-stub => i2c-stub.rst} | 20 +- .../i2c/{i2c-topology => i2c-topology.rst} | 68 +++--- Documentation/i2c/index.rst | 37 ++++ ...ting-devices => instantiating-devices.rst} | 45 ++-- .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} | 26 +-- ...e-parameters => old-module-parameters.rst} | 27 ++- ...eprom-backend => slave-eeprom-backend.rst} | 4 +- .../{slave-interface => slave-interface.rst} | 33 +-- .../{smbus-protocol => smbus-protocol.rst} | 86 +++++--- Documentation/i2c/{summary => summary.rst} | 6 +- ...en-bit-addresses => ten-bit-addresses.rst} | 5 + ...pgrading-clients => upgrading-clients.rst} | 204 +++++++++--------- .../{writing-clients => writing-clients.rst} | 94 ++++---- Documentation/index.rst | 1 + Documentation/spi/spi-sc18is602 | 2 +- MAINTAINERS | 48 ++--- drivers/hwmon/atxp1.c | 2 +- drivers/hwmon/smm665.c | 2 +- drivers/i2c/Kconfig | 4 +- drivers/i2c/busses/Kconfig | 2 +- drivers/i2c/busses/i2c-i801.c | 2 +- drivers/i2c/busses/i2c-taos-evm.c | 2 +- drivers/i2c/i2c-core-base.c | 4 +- drivers/iio/dummy/iio_simple_dummy.c | 2 +- drivers/rtc/rtc-ds1374.c | 2 +- include/linux/i2c.h | 2 +- 83 files changed, 1090 insertions(+), 784 deletions(-) rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%) rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%) rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%) delete mode 100644 Documentation/i2c/busses/i2c-amd-mp2 create mode 100644 Documentation/i2c/busses/i2c-amd-mp2.rst rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%) rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%) rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%) rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%) rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%) rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%) rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%) rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%) rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%) delete mode 100644 Documentation/i2c/busses/i2c-parport rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%) create mode 100644 Documentation/i2c/busses/i2c-parport.rst rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%) rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%) rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%) delete mode 100644 Documentation/i2c/busses/i2c-sis630 create mode 100644 Documentation/i2c/busses/i2c-sis630.rst rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%) rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%) rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%) rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%) create mode 100644 Documentation/i2c/busses/index.rst rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%) rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%) rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%) rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%) rename Documentation/i2c/{functionality => functionality.rst} (91%) rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%) rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%) rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%) rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%) create mode 100644 Documentation/i2c/index.rst rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%) rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%) rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%) rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%) rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%) rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%) rename Documentation/i2c/{summary => summary.rst} (96%) rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%) rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%) rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%) diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt index 2907dab56298..8b444b94e92f 100644 --- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt +++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt @@ -42,7 +42,7 @@ Optional properties: This means that no unrelated I2C transactions are allowed on the parent I2C adapter for the complete multiplexed I2C transaction. The properties of mux-locked and parent-locked multiplexers are discussed - in more detail in Documentation/i2c/i2c-topology. + in more detail in Documentation/i2c/i2c-topology.rst. For each i2c child node, an I2C child bus will be created. They will be numbered based on their order in the device tree. diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst index 7e2265144157..3ec3baed84c4 100644 --- a/Documentation/driver-api/ipmb.rst +++ b/Documentation/driver-api/ipmb.rst @@ -83,7 +83,7 @@ Instantiate the device ---------------------- After loading the driver, you can instantiate the device as -described in 'Documentation/i2c/instantiating-devices'. +described in 'Documentation/i2c/instantiating-devices.rst'. If you have multiple BMCs, each connected to your Satellite MC via a different I2C bus, you can instantiate a device for each of those BMCs. diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst index 6cbb0f75fe00..116fb2019956 100644 --- a/Documentation/hwmon/adm1021.rst +++ b/Documentation/hwmon/adm1021.rst @@ -142,7 +142,7 @@ loading the adm1021 module, then things are good. If nothing happens when loading the adm1021 module, and you are certain that your specific Xeon processor model includes compatible sensors, you will have to explicitly instantiate the sensor chips from user-space. See -method 4 in Documentation/i2c/instantiating-devices. Possible slave +method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that only temp2 will be correct and temp1 will have to be ignored. diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst index 9a1913e5b4d9..49966ed70ec6 100644 --- a/Documentation/hwmon/adm1275.rst +++ b/Documentation/hwmon/adm1275.rst @@ -75,7 +75,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. The ADM1075, unlike many other PMBus devices, does not support internal voltage diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst index 649bd4be4fc2..e95d373eb693 100644 --- a/Documentation/hwmon/hih6130.rst +++ b/Documentation/hwmon/hih6130.rst @@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27) can be used in the board setup code. -Please see Documentation/i2c/instantiating-devices for details on how to +Please see Documentation/i2c/instantiating-devices.rst for details on how to instantiate I2C devices. sysfs-Interface diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst index 52e74e39463a..ef8f3f806968 100644 --- a/Documentation/hwmon/ibm-cffps.rst +++ b/Documentation/hwmon/ibm-cffps.rst @@ -17,7 +17,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst index da15e3094c8c..30e6e77fb3c8 100644 --- a/Documentation/hwmon/lm25066.rst +++ b/Documentation/hwmon/lm25066.rst @@ -76,7 +76,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst index 6d5e9538991f..c06249292557 100644 --- a/Documentation/hwmon/max16064.rst +++ b/Documentation/hwmon/max16064.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst index fa5c852a178c..45f69f334f25 100644 --- a/Documentation/hwmon/max16065.rst +++ b/Documentation/hwmon/max16065.rst @@ -79,7 +79,7 @@ Usage Notes This driver does not probe for devices, since there is no register which can be safely used to identify the chip. You will have to instantiate -the devices explicitly. Please see Documentation/i2c/instantiating-devices for +the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. WARNING: Do not access chip registers using the i2cdump command, and do not use diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst index aa4469be6674..fe701e07eaf5 100644 --- a/Documentation/hwmon/max20751.rst +++ b/Documentation/hwmon/max20751.rst @@ -30,7 +30,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst index 939138e12b02..5744df100a5d 100644 --- a/Documentation/hwmon/max34440.rst +++ b/Documentation/hwmon/max34440.rst @@ -83,7 +83,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. For MAX34446, the value of the currX_crit attribute determines if current or diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst index 253482add082..7952b6ecaa2d 100644 --- a/Documentation/hwmon/max6650.rst +++ b/Documentation/hwmon/max6650.rst @@ -55,7 +55,7 @@ Usage notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Module parameters diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst index 009487759c61..71e7f2cbe2e2 100644 --- a/Documentation/hwmon/max8688.rst +++ b/Documentation/hwmon/max8688.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst index 1f0c6b2235ab..978691d5956d 100644 --- a/Documentation/hwmon/menf21bmc.rst +++ b/Documentation/hwmon/menf21bmc.rst @@ -28,7 +28,7 @@ Usage Notes This driver is part of the MFD driver named "menf21bmc" and does not auto-detect devices. You will have to instantiate the MFD driver explicitly. -Please see Documentation/i2c/instantiating-devices for +Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst index e98bd542a441..5c4e85f53177 100644 --- a/Documentation/hwmon/pcf8591.rst +++ b/Documentation/hwmon/pcf8591.rst @@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface The PCF8591 is plainly impossible to detect! Thus the driver won't even try. You have to explicitly instantiate the device at the relevant address (in the interval [0x48..0x4f]) either through platform data, or -using the sysfs interface. See Documentation/i2c/instantiating-devices +using the sysfs interface. See Documentation/i2c/instantiating-devices.rst for details. Directories are being created for each instantiated PCF8591: diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst index 978a7117e4b2..95a850d5b2c1 100644 --- a/Documentation/hwmon/sht3x.rst +++ b/Documentation/hwmon/sht3x.rst @@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500. The device communicates with the I2C protocol. Sensors can have the I2C addresses 0x44 or 0x45, depending on the wiring. See -Documentation/i2c/instantiating-devices for methods to instantiate the device. +Documentation/i2c/instantiating-devices.rst for methods to instantiate the device. There are two options configurable by means of sht3x_platform_data: diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst index aa116332ba26..70c1192bbd8c 100644 --- a/Documentation/hwmon/shtc1.rst +++ b/Documentation/hwmon/shtc1.rst @@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1 chip, which has the same electrical interface. The device communicates with the I2C protocol. All sensors are set to I2C -address 0x70. See Documentation/i2c/instantiating-devices for methods to +address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to instantiate the device. There are two options configurable by means of shtc1_platform_data: diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst index 15d25806d585..205de6148fcb 100644 --- a/Documentation/hwmon/tmp103.rst +++ b/Documentation/hwmon/tmp103.rst @@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see Documentation/hwmon/sysfs-interface.rst under Temperatures). Please refer how to instantiate this driver: -Documentation/i2c/instantiating-devices +Documentation/i2c/instantiating-devices.rst diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst index b691e30479dd..8fe3e1c3572e 100644 --- a/Documentation/hwmon/tps40422.rst +++ b/Documentation/hwmon/tps40422.rst @@ -28,7 +28,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst index ebc4f2b3bfea..746f21fcb48c 100644 --- a/Documentation/hwmon/ucd9000.rst +++ b/Documentation/hwmon/ucd9000.rst @@ -64,7 +64,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst index b819dfd75f71..4f0e7c3ca6f4 100644 --- a/Documentation/hwmon/ucd9200.rst +++ b/Documentation/hwmon/ucd9200.rst @@ -40,7 +40,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst index a343c35df740..7ab9ddebcf79 100644 --- a/Documentation/hwmon/via686a.rst +++ b/Documentation/hwmon/via686a.rst @@ -40,7 +40,7 @@ all as a 686A. The Via 686a southbridge has integrated hardware monitor functionality. It also has an I2C bus, but this driver only supports the hardware monitor. -For the I2C bus driver, see +For the I2C bus driver, see The Via 686a implements three temperature sensors, two fan rotation speed sensors, five voltage sensors and alarms. diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst index 41513bb7fe51..968aff10ce0a 100644 --- a/Documentation/hwmon/zl6100.rst +++ b/Documentation/hwmon/zl6100.rst @@ -121,7 +121,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. .. warning:: diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst similarity index 82% rename from Documentation/i2c/busses/i2c-ali1535 rename to Documentation/i2c/busses/i2c-ali1535.rst index 5d46342e486a..6941064730dc 100644 --- a/Documentation/i2c/busses/i2c-ali1535 +++ b/Documentation/i2c/busses/i2c-ali1535.rst @@ -1,16 +1,19 @@ +========================= Kernel driver i2c-ali1535 +========================= Supported adapters: * Acer Labs, Inc. ALI 1535 (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ Authors: - Frodo Looijaard , - Philip Edelbrock , - Mark D. Studebaker , - Dan Eaton , - Stephen Rousset + - Frodo Looijaard , + - Philip Edelbrock , + - Mark D. Studebaker , + - Dan Eaton , + - Stephen Rousset Description ----------- diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst similarity index 93% rename from Documentation/i2c/busses/i2c-ali1563 rename to Documentation/i2c/busses/i2c-ali1563.rst index 41b1a077e4c7..eec32c3ba92a 100644 --- a/Documentation/i2c/busses/i2c-ali1563 +++ b/Documentation/i2c/busses/i2c-ali1563.rst @@ -1,7 +1,10 @@ +========================= Kernel driver i2c-ali1563 +========================= Supported adapters: * Acer Labs, Inc. ALI 1563 (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst similarity index 72% rename from Documentation/i2c/busses/i2c-ali15x3 rename to Documentation/i2c/busses/i2c-ali15x3.rst index 42888d8ac124..d4c1a2a419cb 100644 --- a/Documentation/i2c/busses/i2c-ali15x3 +++ b/Documentation/i2c/busses/i2c-ali15x3.rst @@ -1,20 +1,23 @@ +========================= Kernel driver i2c-ali15x3 +========================= Supported adapters: * Acer Labs, Inc. ALI 1533 and 1543C (south bridge) + Datasheet: Now under NDA http://www.ali.com.tw/ Authors: - Frodo Looijaard , - Philip Edelbrock , - Mark D. Studebaker + - Frodo Looijaard , + - Philip Edelbrock , + - Mark D. Studebaker Module Parameters ----------------- * force_addr: int - Initialize the base address of the i2c controller + Initialize the base address of the i2c controller Notes @@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in lspci. Don't use this unless the driver complains that the base address is not set. -Example: 'modprobe i2c-ali15x3 force_addr=0xe800' +Example:: + + modprobe i2c-ali15x3 force_addr=0xe800 SMBus periodically hangs on ASUS P5A motherboards and can only be cleared by a power cycle. Cause unknown (see Issues below). @@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI) M1541 and M1543C South Bridges. The M1543C is a South bridge for desktop systems. + The M1541 is a South bridge for portable systems. + They are part of the following ALI chipsets: * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and - 100MHz CPU Front Side bus + 100MHz CPU Front Side bus * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz - CPU Front Side bus + CPU Front Side bus + Some Aladdin V motherboards: - Asus P5A - Atrend ATC-5220 - BCM/GVC VP1541 - Biostar M5ALA - Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't - enable the 7101 device! **) - Iwill XA100 Plus - Micronics C200 - Microstar (MSI) MS-5169 + - Asus P5A + - Atrend ATC-5220 + - BCM/GVC VP1541 + - Biostar M5ALA + - Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't + enable the 7101 device!) + - Iwill XA100 Plus + - Micronics C200 + - Microstar (MSI) MS-5169 * "Aladdin IV" includes the M1541 Socket 7 North bridge - with host bus up to 83.3 MHz. + with host bus up to 83.3 MHz. For an overview of these chips see http://www.acerlabs.com. At this time the full data sheets on the web site are password protected, however if you contact the ALI office in San Jose they may give you the password. The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An -output of lspci will show something similar to the following: +output of lspci will show something similar to the following:: 00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03) 00:03.0 Bridge: Acer Laboratories Inc. M7101 <= THIS IS THE ONE WE NEED 00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3) 00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1) -** IMPORTANT ** -** If you have a M1533 or M1543C on the board and you get -** "ali15x3: Error: Can't detect ali15x3!" -** then run lspci. -** If you see the 1533 and 5229 devices but NOT the 7101 device, -** then you must enable ACPI, the PMU, SMB, or something similar -** in the BIOS. -** The driver won't work if it can't find the M7101 device. +.. important:: + + If you have a M1533 or M1543C on the board and you get + "ali15x3: Error: Can't detect ali15x3!" + then run lspci. + + If you see the 1533 and 5229 devices but NOT the 7101 device, + then you must enable ACPI, the PMU, SMB, or something similar + in the BIOS. + + The driver won't work if it can't find the M7101 device. The SMB controller is part of the M7101 device, which is an ACPI-compliant Power Management Unit (PMU). @@ -109,4 +120,3 @@ There may be electrical problems on this board. On the P5A, the W83781D sensor chip is on both the ISA and SMBus. Therefore the SMBus hangs can generally be avoided by accessing the W83781D on the ISA bus only. - diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2 deleted file mode 100644 index 6571487171f4..000000000000 --- a/Documentation/i2c/busses/i2c-amd-mp2 +++ /dev/null @@ -1,23 +0,0 @@ -Kernel driver i2c-amd-mp2 - -Supported adapters: - * AMD MP2 PCIe interface - -Datasheet: not publicly available. - -Authors: - Shyam Sundar S K - Nehal Shah - Elie Morisse - -Description ------------ - -The MP2 is an ARM processor programmed as an I2C controller and communicating -with the x86 host through PCI. - -If you see something like this: - -03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 - -in your 'lspci -v', then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd-mp2.rst b/Documentation/i2c/busses/i2c-amd-mp2.rst new file mode 100644 index 000000000000..ebc2fa899325 --- /dev/null +++ b/Documentation/i2c/busses/i2c-amd-mp2.rst @@ -0,0 +1,25 @@ +========================= +Kernel driver i2c-amd-mp2 +========================= + +Supported adapters: + * AMD MP2 PCIe interface + +Datasheet: not publicly available. + +Authors: + - Shyam Sundar S K + - Nehal Shah + - Elie Morisse + +Description +----------- + +The MP2 is an ARM processor programmed as an I2C controller and communicating +with the x86 host through PCI. + +If you see something like this:: + + 03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6 + +in your ``lspci -v``, then this driver is for your device. diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst similarity index 79% rename from Documentation/i2c/busses/i2c-amd756 rename to Documentation/i2c/busses/i2c-amd756.rst index 67f30874d0bf..bc93f392a4fc 100644 --- a/Documentation/i2c/busses/i2c-amd756 +++ b/Documentation/i2c/busses/i2c-amd756.rst @@ -1,18 +1,22 @@ +======================== Kernel driver i2c-amd756 +======================== Supported adapters: * AMD 756 * AMD 766 * AMD 768 * AMD 8111 + Datasheets: Publicly available on AMD website * nVidia nForce + Datasheet: Unavailable Authors: - Frodo Looijaard , - Philip Edelbrock + - Frodo Looijaard , + - Philip Edelbrock Description ----------- diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst similarity index 66% rename from Documentation/i2c/busses/i2c-amd8111 rename to Documentation/i2c/busses/i2c-amd8111.rst index 460dd6635fd2..d08bf0a7f0ac 100644 --- a/Documentation/i2c/busses/i2c-amd8111 +++ b/Documentation/i2c/busses/i2c-amd8111.rst @@ -1,4 +1,6 @@ +========================= Kernel driver i2c-adm8111 +========================= Supported adapters: * AMD-8111 SMBus 2.0 PCI interface @@ -13,14 +15,14 @@ Author: Vojtech Pavlik Description ----------- -If you see something like this: +If you see something like this:: -00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02) - Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 - Flags: medium devsel, IRQ 19 - I/O ports at d400 [size=32] + 00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02) + Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 + Flags: medium devsel, IRQ 19 + I/O ports at d400 [size=32] -in your 'lspci -v', then this driver is for your chipset. +in your ``lspci -v``, then this driver is for your chipset. Process Call Support -------------------- diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst similarity index 91% rename from Documentation/i2c/busses/i2c-diolan-u2c rename to Documentation/i2c/busses/i2c-diolan-u2c.rst index 0d6018c316c7..c18cbdcdf73c 100644 --- a/Documentation/i2c/busses/i2c-diolan-u2c +++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst @@ -1,7 +1,10 @@ +============================ Kernel driver i2c-diolan-u2c +============================ Supported adapters: * Diolan U2C-12 I2C-USB adapter + Documentation: http://www.diolan.com/i2c/u2c12.html diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst similarity index 89% rename from Documentation/i2c/busses/i2c-i801 rename to Documentation/i2c/busses/i2c-i801.rst index f426c13c63a9..2a570c214880 100644 --- a/Documentation/i2c/busses/i2c-i801 +++ b/Documentation/i2c/busses/i2c-i801.rst @@ -1,4 +1,7 @@ +====================== Kernel driver i2c-i801 +====================== + Supported adapters: * Intel 82801AA and 82801AB (ICH and ICH0 - part of the @@ -39,28 +42,33 @@ Supported adapters: * Intel Comet Lake (PCH) * Intel Elkhart Lake (PCH) * Intel Tiger Lake (PCH) + Datasheets: Publicly available at the Intel website On Intel Patsburg and later chipsets, both the normal host SMBus controller and the additional 'Integrated Device Function' controllers are supported. -Authors: - Mark Studebaker - Jean Delvare +Authors: + - Mark Studebaker + - Jean Delvare Module Parameters ----------------- * disable_features (bit vector) + Disable selected features normally supported by the device. This makes it possible to work around possible driver or hardware bugs if the feature in question doesn't work as intended for whatever reason. Bit values: + + ==== ========================================= 0x01 disable SMBus PEC 0x02 disable the block buffer 0x08 disable the I2C block read functionality 0x10 don't use interrupts 0x20 disable SMBus Host Notify + ==== ========================================= Description @@ -73,7 +81,7 @@ Pentium-based PCs, '815E' chipset, and others. The ICH chips contain at least SEVEN separate PCI functions in TWO logical PCI devices. An output of lspci will show something similar to the -following: +following:: 00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01) 00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01) @@ -139,14 +147,14 @@ and you think there's something interesting on the SMBus (e.g. a hardware monitoring chip), you need to add your board to the list. The motherboard is identified using the subvendor and subdevice IDs of the -host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0": +host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``:: -00:00.0 Class 0600: 8086:2570 (rev 02) - Subsystem: 1043:80f2 - Flags: bus master, fast devsel, latency 0 - Memory at fc000000 (32-bit, prefetchable) [size=32M] - Capabilities: [e4] #09 [2106] - Capabilities: [a0] AGP version 3.0 + 00:00.0 Class 0600: 8086:2570 (rev 02) + Subsystem: 1043:80f2 + Flags: bus master, fast devsel, latency 0 + Memory at fc000000 (32-bit, prefetchable) [size=32M] + Capabilities: [e4] #09 [2106] + Capabilities: [a0] AGP version 3.0 Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043 (Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic @@ -165,7 +173,8 @@ kernel. It's very convenient if you just want to check if there's anything interesting on your hidden ICH SMBus. -********************** +---------------------------------------------------------------------------- + The lm_sensors project gratefully acknowledges the support of Texas Instruments in the initial development of this driver. diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst similarity index 81% rename from Documentation/i2c/busses/i2c-ismt rename to Documentation/i2c/busses/i2c-ismt.rst index 737355822c0b..8e74919a3fdf 100644 --- a/Documentation/i2c/busses/i2c-ismt +++ b/Documentation/i2c/busses/i2c-ismt.rst @@ -1,4 +1,7 @@ +====================== Kernel driver i2c-ismt +====================== + Supported adapters: * Intel S12xx series SOCs @@ -11,16 +14,21 @@ Module Parameters ----------------- * bus_speed (unsigned int) + Allows changing of the bus speed. Normally, the bus speed is set by the BIOS and never needs to be changed. However, some SMBus analyzers are too slow for monitoring the bus during debug, thus the need for this module parameter. Specify the bus speed in kHz. + Available bus frequency settings: - 0 no change - 80 kHz - 100 kHz - 400 kHz - 1000 kHz + + ==== ========= + 0 no change + 80 kHz + 100 kHz + 400 kHz + 1000 kHz + ==== ========= Description @@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers targeted primarily at the microserver and storage markets. The S12xx series contain a pair of PCI functions. An output of lspci will show -something similar to the following: +something similar to the following:: 00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0 00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1 diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst similarity index 88% rename from Documentation/i2c/busses/i2c-mlxcpld rename to Documentation/i2c/busses/i2c-mlxcpld.rst index 925904aa9b57..9a0b2916aa71 100644 --- a/Documentation/i2c/busses/i2c-mlxcpld +++ b/Documentation/i2c/busses/i2c-mlxcpld.rst @@ -1,9 +1,12 @@ +================== Driver i2c-mlxcpld +================== Author: Michael Shych This is the Mellanox I2C controller logic, implemented in Lattice CPLD device. + Device supports: - Master mode. - One physical bus. @@ -20,6 +23,8 @@ The next transaction types are supported: - Write Byte/Block. Registers: + +=============== === ======================================================================= CPBLTY 0x0 - capability reg. Bits [6:5] - transaction length. b01 - 72B is supported, 36B in other case. @@ -49,3 +54,4 @@ DATAx 0xa - 0x54 - 68 bytes data buffer regs. For read transactions address is sent in a separate transaction and specified in the four first bytes (DATA0 - DATA3). Data is read starting from DATA0. +=============== === ======================================================================= diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst similarity index 58% rename from Documentation/i2c/busses/i2c-nforce2 rename to Documentation/i2c/busses/i2c-nforce2.rst index 9698c396b830..83181445268f 100644 --- a/Documentation/i2c/busses/i2c-nforce2 +++ b/Documentation/i2c/busses/i2c-nforce2.rst @@ -1,10 +1,12 @@ +========================= Kernel driver i2c-nforce2 +========================= Supported adapters: - * nForce2 MCP 10de:0064 - * nForce2 Ultra 400 MCP 10de:0084 - * nForce3 Pro150 MCP 10de:00D4 - * nForce3 250Gb MCP 10de:00E4 + * nForce2 MCP 10de:0064 + * nForce2 Ultra 400 MCP 10de:0084 + * nForce3 Pro150 MCP 10de:00D4 + * nForce3 250Gb MCP 10de:00E4 * nForce4 MCP 10de:0052 * nForce4 MCP-04 10de:0034 * nForce MCP51 10de:0264 @@ -16,26 +18,27 @@ Supported adapters: * nForce MCP78S 10de:0752 * nForce MCP79 10de:0AA2 -Datasheet: not publicly available, but seems to be similar to the +Datasheet: + not publicly available, but seems to be similar to the AMD-8111 SMBus 2.0 adapter. Authors: - Hans-Frieder Vogt , - Thomas Leibold , - Patrick Dreker - + - Hans-Frieder Vogt , + - Thomas Leibold , + - Patrick Dreker + Description ----------- i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP. -If your 'lspci -v' listing shows something like the following, +If your ``lspci -v`` listing shows something like the following:: -00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2) - Subsystem: Asustek Computer, Inc.: Unknown device 0c11 - Flags: 66Mhz, fast devsel, IRQ 5 - I/O ports at c000 [size=32] - Capabilities: + 00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2) + Subsystem: Asustek Computer, Inc.: Unknown device 0c11 + Flags: 66Mhz, fast devsel, IRQ 5 + I/O ports at c000 [size=32] + Capabilities: then this driver should support the SMBuses of your motherboard. diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst similarity index 63% rename from Documentation/i2c/busses/i2c-nvidia-gpu rename to Documentation/i2c/busses/i2c-nvidia-gpu.rst index 31884d2b2eb5..38fb8a4c8756 100644 --- a/Documentation/i2c/busses/i2c-nvidia-gpu +++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst @@ -1,4 +1,6 @@ +============================ Kernel driver i2c-nvidia-gpu +============================ Datasheet: not publicly available. @@ -11,8 +13,8 @@ Description i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing and later GPUs and it is used to communicate with Type-C controller on GPUs. -If your 'lspci -v' listing shows something like the following, +If your ``lspci -v`` listing shows something like the following:: -01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) + 01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1) then this driver should support the I2C controller of your GPU. diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst similarity index 82% rename from Documentation/i2c/busses/i2c-ocores rename to Documentation/i2c/busses/i2c-ocores.rst index 9caaf7df1b2f..f5e175f2a2a6 100644 --- a/Documentation/i2c/busses/i2c-ocores +++ b/Documentation/i2c/busses/i2c-ocores.rst @@ -1,4 +1,6 @@ +======================== Kernel driver i2c-ocores +======================== Supported adapters: * OpenCores.org I2C controller by Richard Herveille (see datasheet link) @@ -23,9 +25,9 @@ distance between registers and the input clock speed. There is also a possibility to attach a list of i2c_board_info which the i2c-ocores driver will add to the bus upon creation. -E.G. something like: +E.G. something like:: -static struct resource ocores_resources[] = { + static struct resource ocores_resources[] = { [0] = { .start = MYI2C_BASEADDR, .end = MYI2C_BASEADDR + 8, @@ -36,10 +38,10 @@ static struct resource ocores_resources[] = { .end = MYI2C_IRQ, .flags = IORESOURCE_IRQ, }, -}; + }; -/* optional board info */ -struct i2c_board_info ocores_i2c_board_info[] = { + /* optional board info */ + struct i2c_board_info ocores_i2c_board_info[] = { { I2C_BOARD_INFO("tsc2003", 0x48), .platform_data = &tsc2003_platform_data, @@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = { I2C_BOARD_INFO("adv7180", 0x42 >> 1), .irq = ADV_IRQ } -}; + }; -static struct ocores_i2c_platform_data myi2c_data = { + static struct ocores_i2c_platform_data myi2c_data = { .regstep = 2, /* two bytes between registers */ .clock_khz = 50000, /* input clock of 50MHz */ .devices = ocores_i2c_board_info, /* optional table of devices */ .num_devices = ARRAY_SIZE(ocores_i2c_board_info), /* table size */ -}; + }; -static struct platform_device myi2c = { + static struct platform_device myi2c = { .name = "ocores-i2c", .dev = { .platform_data = &myi2c_data, }, .num_resources = ARRAY_SIZE(ocores_resources), .resource = ocores_resources, -}; + }; diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport deleted file mode 100644 index c3dbb3bfd814..000000000000 --- a/Documentation/i2c/busses/i2c-parport +++ /dev/null @@ -1,178 +0,0 @@ -Kernel driver i2c-parport - -Author: Jean Delvare - -This is a unified driver for several i2c-over-parallel-port adapters, -such as the ones made by Philips, Velleman or ELV. This driver is -meant as a replacement for the older, individual drivers: - * i2c-philips-par - * i2c-elv - * i2c-velleman - * video/i2c-parport (NOT the same as this one, dedicated to home brew - teletext adapters) - -It currently supports the following devices: - * (type=0) Philips adapter - * (type=1) home brew teletext adapter - * (type=2) Velleman K8000 adapter - * (type=3) ELV adapter - * (type=4) Analog Devices ADM1032 evaluation board - * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 - * (type=6) Barco LPT->DVI (K5800236) adapter - * (type=7) One For All JP1 parallel port adapter - * (type=8) VCT-jig - -These devices use different pinout configurations, so you have to tell -the driver what you have, using the type module parameter. There is no -way to autodetect the devices. Support for different pinout configurations -can be easily added when needed. - -Earlier kernels defaulted to type=0 (Philips). But now, if the type -parameter is missing, the driver will simply fail to initialize. - -SMBus alert support is available on adapters which have this line properly -connected to the parallel port's interrupt pin. - - -Building your own adapter -------------------------- - -If you want to build you own i2c-over-parallel-port adapter, here is -a sample electronics schema (credits go to Sylvain Munaut): - -Device PC -Side ___________________Vdd (+) Side - | | | - --- --- --- - | | | | | | - |R| |R| |R| - | | | | | | - --- --- --- - | | | - | | /| | -SCL ----------x--------o |-----------x------------------- pin 2 - | \| | | - | | | - | |\ | | -SDA ----------x----x---| o---x--------------------------- pin 13 - | |/ | - | | - | /| | - ---------o |----------------x-------------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - -Remarks: - - This is the exact pinout and electronics used on the Analog Devices - evaluation boards. - /| - - All inverters -o |- must be 74HC05, they must be open collector output. - \| - - All resitors are 10k. - - Pins 18-25 of the parallel port connected to GND. - - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. - The ADM1032 evaluation board uses D4-D7. Beware that the amount of - current you can draw from the parallel port is limited. Also note that - all connected lines MUST BE driven at the same state, else you'll short - circuit the output buffers! So plugging the I2C adapter after loading - the i2c-parport module might be a good safety since data line state - prior to init may be unknown. - - This is 5V! - - Obviously you cannot read SCL (so it's not really standard-compliant). - Pretty easy to add, just copy the SDA part and use another input pin. - That would give (ELV compatible pinout): - - -Device PC -Side ______________________________Vdd (+) Side - | | | | - --- --- --- --- - | | | | | | | | - |R| |R| |R| |R| - | | | | | | | | - --- --- --- --- - | | | | - | | |\ | | -SCL ----------x--------x--| o---x------------------------ pin 15 - | | |/ | - | | | - | | /| | - | ---o |-------------x-------------- pin 2 - | \| | | - | | | - | | | - | |\ | | -SDA ---------------x---x--| o--------x------------------- pin 10 - | |/ | - | | - | /| | - ---o |------------------x--------- pin 3 - \| | | - | | - --- --- - | | | | - |R| |R| - | | | | - --- --- - | | - ### ### - GND GND - - -If possible, you should use the same pinout configuration as existing -adapters do, so you won't even have to change the code. - - -Similar (but different) drivers -------------------------------- - -This driver is NOT the same as the i2c-pport driver found in the i2c -package. The i2c-pport driver makes use of modern parallel port features so -that you don't need additional electronics. It has other restrictions -however, and was not ported to Linux 2.6 (yet). - -This driver is also NOT the same as the i2c-pcf-epp driver found in the -lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as -an I2C bus directly. Instead, it uses it to control an external I2C bus -master. That driver was not ported to Linux 2.6 (yet) either. - - -Legacy documentation for Velleman adapter ------------------------------------------ - -Useful links: -Velleman http://www.velleman.be/ -Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html - -The project has lead to new libs for the Velleman K8000 and K8005: - LIBK8000 v1.99.1 and LIBK8005 v0.21 -With these libs, you can control the K8000 interface card and the K8005 -stepper motor card with the simple commands which are in the original -Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and -many more, using /dev/velleman. - http://home.wanadoo.nl/hihihi/libk8000.htm - http://home.wanadoo.nl/hihihi/libk8005.htm - http://struyve.mine.nu:8080/index.php?block=k8000 - http://sourceforge.net/projects/libk8005/ - - -One For All JP1 parallel port adapter -------------------------------------- - -The JP1 project revolves around a set of remote controls which expose -the I2C bus their internal configuration EEPROM lives on via a 6 pin -jumper in the battery compartment. More details can be found at: - -http://www.hifi-remote.com/jp1/ - -Details of the simple parallel port hardware can be found at: - -http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst similarity index 91% rename from Documentation/i2c/busses/i2c-parport-light rename to Documentation/i2c/busses/i2c-parport-light.rst index 7071b8ba0af4..e73af975d2c8 100644 --- a/Documentation/i2c/busses/i2c-parport-light +++ b/Documentation/i2c/busses/i2c-parport-light.rst @@ -1,13 +1,15 @@ +=============================== Kernel driver i2c-parport-light +=============================== Author: Jean Delvare -This driver is a light version of i2c-parport. It doesn't depend +This driver is a light version of i2c-parport. It doesn't depend on the parport driver, and uses direct I/O access instead. This might be preferred on embedded systems where wasting memory for the clean but heavy parport handling is not an option. The drawback is a reduced portability -and the impossibility to daisy-chain other parallel port devices. - +and the impossibility to daisy-chain other parallel port devices. + Please see i2c-parport for documentation. Module parameters: diff --git a/Documentation/i2c/busses/i2c-parport.rst b/Documentation/i2c/busses/i2c-parport.rst new file mode 100644 index 000000000000..a9b4e8133700 --- /dev/null +++ b/Documentation/i2c/busses/i2c-parport.rst @@ -0,0 +1,190 @@ +========================= +Kernel driver i2c-parport +========================= + +Author: Jean Delvare + +This is a unified driver for several i2c-over-parallel-port adapters, +such as the ones made by Philips, Velleman or ELV. This driver is +meant as a replacement for the older, individual drivers: + + * i2c-philips-par + * i2c-elv + * i2c-velleman + * video/i2c-parport + (NOT the same as this one, dedicated to home brew teletext adapters) + +It currently supports the following devices: + + * (type=0) Philips adapter + * (type=1) home brew teletext adapter + * (type=2) Velleman K8000 adapter + * (type=3) ELV adapter + * (type=4) Analog Devices ADM1032 evaluation board + * (type=5) Analog Devices evaluation boards: ADM1025, ADM1030, ADM1031 + * (type=6) Barco LPT->DVI (K5800236) adapter + * (type=7) One For All JP1 parallel port adapter + * (type=8) VCT-jig + +These devices use different pinout configurations, so you have to tell +the driver what you have, using the type module parameter. There is no +way to autodetect the devices. Support for different pinout configurations +can be easily added when needed. + +Earlier kernels defaulted to type=0 (Philips). But now, if the type +parameter is missing, the driver will simply fail to initialize. + +SMBus alert support is available on adapters which have this line properly +connected to the parallel port's interrupt pin. + + +Building your own adapter +------------------------- + +If you want to build you own i2c-over-parallel-port adapter, here is +a sample electronics schema (credits go to Sylvain Munaut):: + + Device PC + Side ___________________Vdd (+) Side + | | | + --- --- --- + | | | | | | + |R| |R| |R| + | | | | | | + --- --- --- + | | | + | | /| | + SCL ----------x--------o |-----------x------------------- pin 2 + | \| | | + | | | + | |\ | | + SDA ----------x----x---| o---x--------------------------- pin 13 + | |/ | + | | + | /| | + ---------o |----------------x-------------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + +Remarks: + - This is the exact pinout and electronics used on the Analog Devices + evaluation boards. + - All inverters:: + + /| + -o |- + \| + + must be 74HC05, they must be open collector output. + - All resitors are 10k. + - Pins 18-25 of the parallel port connected to GND. + - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high. + The ADM1032 evaluation board uses D4-D7. Beware that the amount of + current you can draw from the parallel port is limited. Also note that + all connected lines MUST BE driven at the same state, else you'll short + circuit the output buffers! So plugging the I2C adapter after loading + the i2c-parport module might be a good safety since data line state + prior to init may be unknown. + - This is 5V! + - Obviously you cannot read SCL (so it's not really standard-compliant). + Pretty easy to add, just copy the SDA part and use another input pin. + That would give (ELV compatible pinout):: + + + Device PC + Side ______________________________Vdd (+) Side + | | | | + --- --- --- --- + | | | | | | | | + |R| |R| |R| |R| + | | | | | | | | + --- --- --- --- + | | | | + | | |\ | | + SCL ----------x--------x--| o---x------------------------ pin 15 + | | |/ | + | | | + | | /| | + | ---o |-------------x-------------- pin 2 + | \| | | + | | | + | | | + | |\ | | + SDA ---------------x---x--| o--------x------------------- pin 10 + | |/ | + | | + | /| | + ---o |------------------x--------- pin 3 + \| | | + | | + --- --- + | | | | + |R| |R| + | | | | + --- --- + | | + ### ### + GND GND + + +If possible, you should use the same pinout configuration as existing +adapters do, so you won't even have to change the code. + + +Similar (but different) drivers +------------------------------- + +This driver is NOT the same as the i2c-pport driver found in the i2c +package. The i2c-pport driver makes use of modern parallel port features so +that you don't need additional electronics. It has other restrictions +however, and was not ported to Linux 2.6 (yet). + +This driver is also NOT the same as the i2c-pcf-epp driver found in the +lm_sensors package. The i2c-pcf-epp driver doesn't use the parallel port as +an I2C bus directly. Instead, it uses it to control an external I2C bus +master. That driver was not ported to Linux 2.6 (yet) either. + + +Legacy documentation for Velleman adapter +----------------------------------------- + +Useful links: + +- Velleman http://www.velleman.be/ +- Velleman K8000 Howto http://howto.htlw16.ac.at/k8000-howto.html + +The project has lead to new libs for the Velleman K8000 and K8005: + + LIBK8000 v1.99.1 and LIBK8005 v0.21 + +With these libs, you can control the K8000 interface card and the K8005 +stepper motor card with the simple commands which are in the original +Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and +many more, using /dev/velleman. + + - http://home.wanadoo.nl/hihihi/libk8000.htm + - http://home.wanadoo.nl/hihihi/libk8005.htm + - http://struyve.mine.nu:8080/index.php?block=k8000 + - http://sourceforge.net/projects/libk8005/ + + +One For All JP1 parallel port adapter +------------------------------------- + +The JP1 project revolves around a set of remote controls which expose +the I2C bus their internal configuration EEPROM lives on via a 6 pin +jumper in the battery compartment. More details can be found at: + +http://www.hifi-remote.com/jp1/ + +Details of the simple parallel port hardware can be found at: + +http://www.hifi-remote.com/jp1/hardware.shtml diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst similarity index 72% rename from Documentation/i2c/busses/i2c-pca-isa rename to Documentation/i2c/busses/i2c-pca-isa.rst index b044e5265488..a254010c8055 100644 --- a/Documentation/i2c/busses/i2c-pca-isa +++ b/Documentation/i2c/busses/i2c-pca-isa.rst @@ -1,6 +1,9 @@ +========================= Kernel driver i2c-pca-isa +========================= Supported adapters: + This driver supports ISA boards using the Philips PCA 9564 Parallel bus to I2C bus controller @@ -10,11 +13,11 @@ Module Parameters ----------------- * base int - I/O base address + I/O base address * irq int - IRQ interrupt + IRQ interrupt * clock int - Clock rate as described in table 1 of PCA9564 datasheet + Clock rate as described in table 1 of PCA9564 datasheet Description ----------- diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst similarity index 92% rename from Documentation/i2c/busses/i2c-piix4 rename to Documentation/i2c/busses/i2c-piix4.rst index 2703bc3acad0..cc9000259223 100644 --- a/Documentation/i2c/busses/i2c-piix4 +++ b/Documentation/i2c/busses/i2c-piix4.rst @@ -1,4 +1,6 @@ +======================= Kernel driver i2c-piix4 +======================= Supported adapters: * Intel 82371AB PIIX4 and PIIX4E @@ -20,9 +22,9 @@ Supported adapters: * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge Datasheet: Publicly available at the SMSC website http://www.smsc.com -Authors: - Frodo Looijaard - Philip Edelbrock +Authors: + - Frodo Looijaard + - Philip Edelbrock Module Parameters @@ -39,16 +41,16 @@ Description The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of functionality. Among other things, it implements the PCI bus. One of its -minor functions is implementing a System Management Bus. This is a true +minor functions is implementing a System Management Bus. This is a true SMBus - you can not access it on I2C levels. The good news is that it natively understands SMBus commands and you do not have to worry about timing problems. The bad news is that non-SMBus devices connected to it can confuse it mightily. Yes, this is known to happen... -Do 'lspci -v' and see whether it contains an entry like this: +Do ``lspci -v`` and see whether it contains an entry like this:: -0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02) - Flags: medium devsel, IRQ 9 + 0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02) + Flags: medium devsel, IRQ 9 Bus and device numbers may differ, but the function number must be identical (like many PCI devices, the PIIX4 incorporates a number of @@ -91,7 +93,7 @@ the SMI mode. device is located at 00:0f.0. 2) Now you just need to change the value in 0xD2 register. Get it first with command: lspci -xxx -s 00:0f.0 - If the value is 0x3 then you need to change it to 0x1 + If the value is 0x3 then you need to change it to 0x1: setpci -s 00:0f.0 d2.b=1 Please note that you don't need to do that in all cases, just when the SMBus is diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst similarity index 74% rename from Documentation/i2c/busses/i2c-sis5595 rename to Documentation/i2c/busses/i2c-sis5595.rst index ecd21fb49a8f..b85630c84a96 100644 --- a/Documentation/i2c/busses/i2c-sis5595 +++ b/Documentation/i2c/busses/i2c-sis5595.rst @@ -1,9 +1,11 @@ +========================= Kernel driver i2c-sis5595 +========================= Authors: - Frodo Looijaard , - Mark D. Studebaker , - Philip Edelbrock + - Frodo Looijaard , + - Mark D. Studebaker , + - Philip Edelbrock Supported adapters: * Silicon Integrated Systems Corp. SiS5595 Southbridge @@ -11,14 +13,19 @@ Supported adapters: Note: all have mfr. ID 0x1039. + ========= ====== SUPPORTED PCI ID + ========= ====== 5595 0008 + ========= ====== Note: these chips contain a 0008 device which is incompatible with the 5595. We recognize these by the presence of the listed "blacklist" PCI ID and refuse to load. + ============= ====== ================ NOT SUPPORTED PCI ID BLACKLIST PCI ID + ============= ====== ================ 540 0008 0540 550 0008 0550 5513 0008 5511 @@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039. 735 0008 0735 745 0008 0745 746 0008 0746 + ============= ====== ================ Module Parameters ----------------- -* force_addr=0xaddr Set the I/O base address. Useful for boards +================== ===================================================== +force_addr=0xaddr Set the I/O base address. Useful for boards that don't set the address in the BIOS. Does not do a PCI force; the device must still be present in lspci. Don't use this unless the driver complains that the base address is not set. +================== ===================================================== Description ----------- @@ -56,4 +66,3 @@ WARNING: If you are trying to access the integrated sensors on the SiS5595 chip, you want the sis5595 driver for those, not this driver. This driver is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP drivers to access chips on the bus. - diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630 deleted file mode 100644 index ee7943631074..000000000000 --- a/Documentation/i2c/busses/i2c-sis630 +++ /dev/null @@ -1,58 +0,0 @@ -Kernel driver i2c-sis630 - -Supported adapters: - * Silicon Integrated Systems Corp (SiS) - 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) - 730 chipset - 964 chipset - * Possible other SiS chipsets ? - -Author: Alexander Malysh - Amaury Decrême - SiS964 support - -Module Parameters ------------------ - -* force = [1|0] Forcibly enable the SIS630. DANGEROUS! - This can be interesting for chipsets not named - above to check if it works for you chipset, but DANGEROUS! - -* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, - what your BIOS use). DANGEROUS! This should be a bit - faster, but freeze some systems (i.e. my Laptop). - SIS630/730 chip only. - - -Description ------------ - -This SMBus only driver is known to work on motherboards with the above -named chipsets. - -If you see something like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31) -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 - -or like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02) -00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 - -or like this: - -00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] - LPC Controller (rev 36) - -in your 'lspci' output , then this driver is for your chipset. - -Thank You ---------- -Philip Edelbrock -- testing SiS730 support -Mark M. Hoffman -- bug fixes - -To anyone else which I forgot here ;), thanks! - diff --git a/Documentation/i2c/busses/i2c-sis630.rst b/Documentation/i2c/busses/i2c-sis630.rst new file mode 100644 index 000000000000..9fcd74b18781 --- /dev/null +++ b/Documentation/i2c/busses/i2c-sis630.rst @@ -0,0 +1,63 @@ +======================== +Kernel driver i2c-sis630 +======================== + +Supported adapters: + * Silicon Integrated Systems Corp (SiS) + 630 chipset (Datasheet: available at http://www.sfr-fresh.com/linux) + 730 chipset + 964 chipset + * Possible other SiS chipsets ? + +Author: + - Alexander Malysh + - Amaury Decrême - SiS964 support + +Module Parameters +----------------- + +================== ===================================================== +force = [1|0] Forcibly enable the SIS630. DANGEROUS! + This can be interesting for chipsets not named + above to check if it works for you chipset, + but DANGEROUS! + +high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default, + what your BIOS use). DANGEROUS! This should be a bit + faster, but freeze some systems (i.e. my Laptop). + SIS630/730 chip only. +================== ===================================================== + + +Description +----------- + +This SMBus only driver is known to work on motherboards with the above +named chipsets. + +If you see something like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31) + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + +or like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02) + 00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + +or like this:: + + 00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02) + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO] + LPC Controller (rev 36) + +in your ``lspci`` output , then this driver is for your chipset. + +Thank You +--------- +Philip Edelbrock +- testing SiS730 support +Mark M. Hoffman +- bug fixes + +To anyone else which I forgot here ;), thanks! diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst similarity index 74% rename from Documentation/i2c/busses/i2c-sis96x rename to Documentation/i2c/busses/i2c-sis96x.rst index 0b979f3252a4..437cc1d89588 100644 --- a/Documentation/i2c/busses/i2c-sis96x +++ b/Documentation/i2c/busses/i2c-sis96x.rst @@ -1,13 +1,18 @@ +======================== Kernel driver i2c-sis96x +======================== Replaces 2.4.x i2c-sis645 Supported adapters: + * Silicon Integrated Systems Corp (SiS) + Any combination of these host bridges: 645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746 + and these south bridges: - 961, 962, 963(L) + 961, 962, 963(L) Author: Mark M. Hoffman @@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different place. Thanks to Alexander Malysh for providing the SiS630 datasheet (and driver). -The command "lspci" as root should produce something like these lines: +The command ``lspci`` as root should produce something like these lines:: -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 -00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513 + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 -or perhaps this... +or perhaps this:: -00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 -00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 -00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 + 00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645 + 00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961 + 00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016 (kernel versions later than 2.4.18 may fill in the "Unknown"s) @@ -50,7 +55,7 @@ TO DOs ------ * The driver does not support SMBus block reads/writes; I may add them if a -scenario is found where they're needed. + scenario is found where they're needed. Thank You @@ -58,16 +63,20 @@ Thank You Mark D. Studebaker - design hints and bug fixes + Alexander Maylsh - ditto, plus an important datasheet... almost the one I really wanted + Hans-Günter Lütke Uphues - patch for SiS735 + Robert Zwerus - testing for SiS645DX + Kianusch Sayah Karadji - patch for SiS645DX/962 + Ken Healy - patch for SiS655 To anyone else who has written w/ feedback, thanks! - diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst similarity index 91% rename from Documentation/i2c/busses/i2c-taos-evm rename to Documentation/i2c/busses/i2c-taos-evm.rst index 60299555dcf0..f342e313ee3d 100644 --- a/Documentation/i2c/busses/i2c-taos-evm +++ b/Documentation/i2c/busses/i2c-taos-evm.rst @@ -1,4 +1,6 @@ +========================== Kernel driver i2c-taos-evm +========================== Author: Jean Delvare @@ -23,10 +25,10 @@ Using this driver In order to use this driver, you'll need the serport driver, and the inputattach tool, which is part of the input-utils package. The following commands will tell the kernel that you have a TAOS EVM on the first -serial port: +serial port:: -# modprobe serport -# inputattach --taos-evm /dev/ttyS0 + # modprobe serport + # inputattach --taos-evm /dev/ttyS0 Technical details diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst similarity index 54% rename from Documentation/i2c/busses/i2c-via rename to Documentation/i2c/busses/i2c-via.rst index 343870661ac3..846aa17d80a2 100644 --- a/Documentation/i2c/busses/i2c-via +++ b/Documentation/i2c/busses/i2c-via.rst @@ -1,4 +1,6 @@ +===================== Kernel driver i2c-via +===================== Supported adapters: * VIA Technologies, InC. VT82C586B @@ -12,23 +14,27 @@ Description i2c-via is an i2c bus driver for motherboards with VIA chipset. The following VIA pci chipsets are supported: - - MVP3, VP3, VP2/97, VPX/97 + - MVP3, VP3, VP2/97, VPX/97 - others with South bridge VT82C586B -Your lspci listing must show this : +Your ``lspci`` listing must show this :: Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10) - Problems? - - Q: You have VT82C586B on the motherboard, but not in the listing. - - A: Go to your BIOS setup, section PCI devices or similar. - Turn USB support on, and try again. +Problems? +--------- - Q: No error messages, but still i2c doesn't seem to work. + Q: + You have VT82C586B on the motherboard, but not in the listing. - A: This can happen. This driver uses the pins VIA recommends in their + A: + Go to your BIOS setup, section PCI devices or similar. + Turn USB support on, and try again. + + Q: + No error messages, but still i2c doesn't seem to work. + + A: + This can happen. This driver uses the pins VIA recommends in their datasheets, but there are several ways the motherboard manufacturer can actually wire the lines. - diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst similarity index 87% rename from Documentation/i2c/busses/i2c-viapro rename to Documentation/i2c/busses/i2c-viapro.rst index ab64ce21c254..1762f0cf93d0 100644 --- a/Documentation/i2c/busses/i2c-viapro +++ b/Documentation/i2c/busses/i2c-viapro.rst @@ -1,4 +1,6 @@ +======================== Kernel driver i2c-viapro +======================== Supported adapters: * VIA Technologies, Inc. VT82C596A/B @@ -26,9 +28,9 @@ Supported adapters: Datasheet: available on http://linux.via.com.tw Authors: - Kyösti Mälkki , - Mark D. Studebaker , - Jean Delvare + - Kyösti Mälkki , + - Mark D. Studebaker , + - Jean Delvare Module Parameters ----------------- @@ -44,8 +46,9 @@ Description i2c-viapro is a true SMBus host driver for motherboards with one of the supported VIA south bridges. -Your lspci -n listing must show one of these : +Your ``lspci -n`` listing must show one of these : + ================ ====================== device 1106:3050 (VT82C596A function 3) device 1106:3051 (VT82C596B function 3) device 1106:3057 (VT82C686 function 4) @@ -61,6 +64,7 @@ Your lspci -n listing must show one of these : device 1106:8353 (VX800/VX820) device 1106:8409 (VX855/VX875) device 1106:8410 (VX900) + ================ ====================== If none of these show up, you should look in the BIOS for settings like enable ACPI / SMBus or even USB. diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst new file mode 100644 index 000000000000..97ca4d510816 --- /dev/null +++ b/Documentation/i2c/busses/index.rst @@ -0,0 +1,33 @@ +. SPDX-License-Identifier: GPL-2.0 + +=============== +I2C Bus Drivers +=============== + +.. toctree:: + :maxdepth: 1 + + i2c-ali1535 + i2c-ali1563 + i2c-ali15x3 + i2c-amd756 + i2c-amd8111 + i2c-amd-mp2 + i2c-diolan-u2c + i2c-i801 + i2c-ismt + i2c-mlxcpld + i2c-nforce2 + i2c-nvidia-gpu + i2c-ocores + i2c-parport-light + i2c-parport + i2c-pca-isa + i2c-piix4 + i2c-sis5595 + i2c-sis630 + i2c-sis96x + i2c-taos-evm + i2c-viapro + i2c-via + scx200_acb diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst similarity index 86% rename from Documentation/i2c/busses/scx200_acb rename to Documentation/i2c/busses/scx200_acb.rst index ce83c871fe95..8dc7c352508c 100644 --- a/Documentation/i2c/busses/scx200_acb +++ b/Documentation/i2c/busses/scx200_acb.rst @@ -1,4 +1,6 @@ +======================== Kernel driver scx200_acb +======================== Author: Christer Weinigel @@ -25,8 +27,11 @@ Device-specific notes The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820. If the scx200_acb driver is built into the kernel, add the following -parameter to your boot command line: +parameter to your boot command line:: + scx200_acb.base=0x810,0x820 + If the scx200_acb driver is built as a module, add the following line to -a configuration file in /etc/modprobe.d/ instead: +a configuration file in /etc/modprobe.d/ instead:: + options scx200_acb base=0x810,0x820 diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst similarity index 71% rename from Documentation/i2c/dev-interface rename to Documentation/i2c/dev-interface.rst index fbed645ccd75..69c23a3c2b1b 100644 --- a/Documentation/i2c/dev-interface +++ b/Documentation/i2c/dev-interface.rst @@ -1,3 +1,7 @@ +==================== +I2C Device Interface +==================== + Usually, i2c devices are controlled by a kernel driver. But it is also possible to access all devices on an adapter from userspace, through the /dev interface. You need to load module i2c-dev for this. @@ -18,7 +22,7 @@ C example ========= So let's say you want to access an i2c adapter from a C program. -First, you need to include these two headers: +First, you need to include these two headers:: #include #include @@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this. Adapter numbers are assigned somewhat dynamically, so you can not assume much about them. They can even change from one boot to the next. -Next thing, open the device file, as follows: +Next thing, open the device file, as follows:: int file; int adapter_nr = 2; /* probably dynamically determined */ @@ -42,7 +46,7 @@ Next thing, open the device file, as follows: } When you have opened the device, you must specify with what device -address you want to communicate: +address you want to communicate:: int addr = 0x40; /* The I2C address */ @@ -53,7 +57,7 @@ address you want to communicate: Well, you are all set up now. You can now use SMBus commands or plain I2C to communicate with your device. SMBus commands are preferred if -the device supports them. Both are illustrated below. +the device supports them. Both are illustrated below:: __u8 reg = 0x10; /* Device register to access */ __s32 res; @@ -100,35 +104,35 @@ Full interface description The following IOCTLs are defined: -ioctl(file, I2C_SLAVE, long addr) +``ioctl(file, I2C_SLAVE, long addr)`` Change slave address. The address is passed in the 7 lower bits of the argument (except for 10 bit addresses, passed in the 10 lower bits in this case). -ioctl(file, I2C_TENBIT, long select) +``ioctl(file, I2C_TENBIT, long select)`` Selects ten bit addresses if select not equals 0, selects normal 7 bit addresses if select equals 0. Default 0. This request is only valid if the adapter has I2C_FUNC_10BIT_ADDR. -ioctl(file, I2C_PEC, long select) +``ioctl(file, I2C_PEC, long select)`` Selects SMBus PEC (packet error checking) generation and verification if select not equals 0, disables if select equals 0. Default 0. Used only for SMBus transactions. This request only has an effect if the the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just doesn't have any effect. -ioctl(file, I2C_FUNCS, unsigned long *funcs) - Gets the adapter functionality and puts it in *funcs. +``ioctl(file, I2C_FUNCS, unsigned long *funcs)`` + Gets the adapter functionality and puts it in ``*funcs``. -ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) +``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)`` Do combined read/write transaction without stop in between. Only valid if the adapter has I2C_FUNC_I2C. The argument is - a pointer to a + a pointer to a:: - struct i2c_rdwr_ioctl_data { + struct i2c_rdwr_ioctl_data { struct i2c_msg *msgs; /* ptr to array of simple messages */ int nmsgs; /* number of messages to exchange */ - } + } The msgs[] themselves contain further pointers into data buffers. The function will write or read data to or from that buffers depending @@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset) The slave address and whether to use ten bit address mode has to be set in each message, overriding the values set with the above ioctl's. -ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args) - If possible, use the provided i2c_smbus_* methods described below instead +``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)`` + If possible, use the provided ``i2c_smbus_*`` methods described below instead of issuing direct ioctls. You can do plain i2c transactions by using read(2) and write(2) calls. @@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through ioctl I2C_SLAVE before you try to access the device. You can do SMBus level transactions (see documentation file smbus-protocol -for details) through the following functions: +for details) through the following functions:: + __s32 i2c_smbus_write_quick(int file, __u8 value); __s32 i2c_smbus_read_byte(int file); __s32 i2c_smbus_write_byte(int file, __u8 value); @@ -157,6 +162,7 @@ for details) through the following functions: __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values); __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length, __u8 *values); + All these transactions return -1 on failure; you can read errno to see what happened. The 'write' transactions return 0 on success; the 'read' transactions return the read value, except for read_block, which @@ -174,39 +180,39 @@ Implementation details For the interested, here's the code flow which happens inside the kernel when you use the /dev interface to I2C: -1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in -section "C example" above. +1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in + section "C example" above. -2* These open() and ioctl() calls are handled by the i2c-dev kernel -driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), -respectively. You can think of i2c-dev as a generic I2C chip driver -that can be programmed from user-space. +2) These open() and ioctl() calls are handled by the i2c-dev kernel + driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(), + respectively. You can think of i2c-dev as a generic I2C chip driver + that can be programmed from user-space. -3* Some ioctl() calls are for administrative tasks and are handled by -i2c-dev directly. Examples include I2C_SLAVE (set the address of the -device you want to access) and I2C_PEC (enable or disable SMBus error -checking on future transactions.) +3) Some ioctl() calls are for administrative tasks and are handled by + i2c-dev directly. Examples include I2C_SLAVE (set the address of the + device you want to access) and I2C_PEC (enable or disable SMBus error + checking on future transactions.) -4* Other ioctl() calls are converted to in-kernel function calls by -i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter -functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which -performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). +4) Other ioctl() calls are converted to in-kernel function calls by + i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter + functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which + performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer(). -The i2c-dev driver is responsible for checking all the parameters that -come from user-space for validity. After this point, there is no -difference between these calls that came from user-space through i2c-dev -and calls that would have been performed by kernel I2C chip drivers -directly. This means that I2C bus drivers don't need to implement -anything special to support access from user-space. + The i2c-dev driver is responsible for checking all the parameters that + come from user-space for validity. After this point, there is no + difference between these calls that came from user-space through i2c-dev + and calls that would have been performed by kernel I2C chip drivers + directly. This means that I2C bus drivers don't need to implement + anything special to support access from user-space. -5* These i2c.h functions are wrappers to the actual implementation of -your I2C bus driver. Each adapter must declare callback functions -implementing these standard calls. i2c.h:i2c_get_functionality() calls -i2c_adapter.algo->functionality(), while -i2c-core-smbus.c:i2c_smbus_xfer() calls either -adapter.algo->smbus_xfer() if it is implemented, or if not, -i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls -i2c_adapter.algo->master_xfer(). +5) These i2c.h functions are wrappers to the actual implementation of + your I2C bus driver. Each adapter must declare callback functions + implementing these standard calls. i2c.h:i2c_get_functionality() calls + i2c_adapter.algo->functionality(), while + i2c-core-smbus.c:i2c_smbus_xfer() calls either + adapter.algo->smbus_xfer() if it is implemented, or if not, + i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls + i2c_adapter.algo->master_xfer(). After your I2C bus driver has processed these requests, execution runs up the call chain, with almost no processing done, except by i2c-dev to diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst similarity index 100% rename from Documentation/i2c/DMA-considerations rename to Documentation/i2c/dma-considerations.rst diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst similarity index 98% rename from Documentation/i2c/fault-codes rename to Documentation/i2c/fault-codes.rst index 0cee0fc545b4..80b14e718b52 100644 --- a/Documentation/i2c/fault-codes +++ b/Documentation/i2c/fault-codes.rst @@ -1,3 +1,7 @@ +===================== +I2C/SMBUS Fault Codes +===================== + This is a summary of the most important conventions for use of fault codes in the I2C/SMBus stack. @@ -125,4 +129,3 @@ ETIMEDOUT when a slave stretches clocks too far. I2C has no such timeouts, but it's normal for I2C adapters to impose some arbitrary limits (much longer than SMBus!) too. - diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst similarity index 91% rename from Documentation/i2c/functionality rename to Documentation/i2c/functionality.rst index 4aae8ed15873..377507c56162 100644 --- a/Documentation/i2c/functionality +++ b/Documentation/i2c/functionality.rst @@ -1,11 +1,15 @@ +======================= +I2C/SMBus Functionality +======================= + INTRODUCTION ------------ -Because not every I2C or SMBus adapter implements everything in the +Because not every I2C or SMBus adapter implements everything in the I2C specifications, a client can not trust that everything it needs is implemented when it is given the option to attach to an adapter: the client needs some way to check whether an adapter has the needed -functionality. +functionality. FUNCTIONALITY CONSTANTS @@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS For the most up-to-date list of functionality constants, please check ! + =============================== ============================================== I2C_FUNC_I2C Plain i2c-level commands (Pure SMBus adapters typically can not do these) I2C_FUNC_10BIT_ADDR Handles the 10-bit address extensions @@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command I2C_FUNC_SMBUS_READ_I2C_BLOCK Handles the SMBus read_i2c_block_data command I2C_FUNC_SMBUS_WRITE_I2C_BLOCK Handles the SMBus write_i2c_block_data command + =============================== ============================================== A few combinations of the above flags are also defined for your convenience: + ========================= ====================================== I2C_FUNC_SMBUS_BYTE Handles the SMBus read_byte and write_byte commands I2C_FUNC_SMBUS_BYTE_DATA Handles the SMBus read_byte_data @@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience: I2C_FUNC_SMBUS_EMUL Handles all SMBus commands that can be emulated by a real I2C adapter (using the transparent emulation layer) + ========================= ====================================== In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as part of I2C_FUNC_PROTOCOL_MANGLING. @@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION ---------------------- When you write a new adapter driver, you will have to implement a -function callback `functionality'. Typical implementations are given +function callback ``functionality``. Typical implementations are given below. A typical SMBus-only adapter would list all the SMBus transactions it -supports. This example comes from the i2c-piix4 driver: +supports. This example comes from the i2c-piix4 driver:: static u32 piix4_func(struct i2c_adapter *adapter) { @@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver: } A typical full-I2C adapter would use the following (from the i2c-pxa -driver): +driver):: static u32 i2c_pxa_functionality(struct i2c_adapter *adap) { @@ -94,7 +102,7 @@ CLIENT CHECKING Before a client tries to attach to an adapter, or even do tests to check whether one of the devices it supports is present on an adapter, it should check whether the needed functionality is present. The typical way to do -this is (from the lm75 driver): +this is (from the lm75 driver):: static int lm75_detect(...) { @@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have to use the /dev interface. You will still have to check whether the functionality you need is supported, of course. This is done using the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is -below: +below:: int file; if (file = open("/dev/i2c-0", O_RDWR) < 0) { diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst similarity index 97% rename from Documentation/i2c/gpio-fault-injection rename to Documentation/i2c/gpio-fault-injection.rst index c87f416d53dd..9dca6ec7d266 100644 --- a/Documentation/i2c/gpio-fault-injection +++ b/Documentation/i2c/gpio-fault-injection.rst @@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost should be detected beforehand. Also note, that SCL going down is monitored using interrupts, so the interrupt latency might cause the first bits to be not corrupted. A good starting point for using this fault injector on an otherwise -idle bus is: +idle bus is:: -# echo 200 > lose_arbitration & -# i2cget -y 0x3f + # echo 200 > lose_arbitration & + # i2cget -y 0x3f Panic during transfer ===================== @@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The process is interruptible, though. Start of a transfer is detected by waiting for SCL going down by the master -under test. A good starting point for using this fault injector is: +under test. A good starting point for using this fault injector is:: -# echo 0 > inject_panic & -# i2cget -y + # echo 0 > inject_panic & + # i2cget -y Note that there doesn't need to be a device listening to the address you are using. Results may vary depending on that, though. diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst similarity index 83% rename from Documentation/i2c/i2c-protocol rename to Documentation/i2c/i2c-protocol.rst index ff6d6cee6c7e..2f8fcf671b2e 100644 --- a/Documentation/i2c/i2c-protocol +++ b/Documentation/i2c/i2c-protocol.rst @@ -1,8 +1,13 @@ +============ +I2C Protocol +============ + This document describes the i2c protocol. Or will, when it is finished :-) Key to symbols ============== +=============== ============================================================= S (1 bit) : Start bit P (1 bit) : Stop bit Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. @@ -15,33 +20,35 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh for 16 bit data. Count (8 bits): A data byte containing the length of a block operation. -[..]: Data sent by I2C device, as opposed to data sent by the host adapter. +[..]: Data sent by I2C device, as opposed to data sent by the + host adapter. +=============== ============================================================= Simple send transaction -====================== +======================= -This corresponds to i2c_master_send. +This corresponds to i2c_master_send:: S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P Simple receive transaction -=========================== +========================== -This corresponds to i2c_master_recv +This corresponds to i2c_master_recv:: S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P Combined transactions -==================== +===================== This corresponds to i2c_transfer They are just like the above transactions, but instead of a stop bit P a start bit S is sent and the transaction continues. An example of -a byte read, followed by a byte write: +a byte read, followed by a byte write:: S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P @@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK: I2C_M_NOSTART: In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some point. For example, setting I2C_M_NOSTART on the second partial message - generates something like: + generates something like:: + S Addr Rd [A] [Data] NA Data [A] P + If you set the I2C_M_NOSTART variable for the first partial message, we do not generate Addr, but we do generate the startbit S. This will probably confuse all other clients on your bus, so don't try this. @@ -79,7 +88,8 @@ I2C_M_NOSTART: I2C_M_REV_DIR_ADDR: This toggles the Rd/Wr flag. That is, if you want to do a write, but need to emit an Rd instead of a Wr, or vice versa, you set this - flag. For example: + flag. For example:: + S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P I2C_M_STOP: diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst similarity index 93% rename from Documentation/i2c/i2c-stub rename to Documentation/i2c/i2c-stub.rst index a16924fbd289..a6fc6916d6bc 100644 --- a/Documentation/i2c/i2c-stub +++ b/Documentation/i2c/i2c-stub.rst @@ -1,6 +1,9 @@ -MODULE: i2c-stub +======== +i2c-stub +======== -DESCRIPTION: +Description +=========== This module is a very simple fake I2C/SMBus driver. It implements six types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w) @@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always return the number of bytes selected with the largest write so far. The typical use-case is like this: + 1. load this module 2. use i2cset (from the i2c-tools project) to pre-load some data 3. load the target chip driver module @@ -36,7 +40,8 @@ The typical use-case is like this: There's a script named i2c-stub-from-dump in the i2c-tools package which can load register values automatically from a chip dump. -PARAMETERS: +Parameters +========== int chip_addr[10]: The SMBus addresses to emulate chips at. @@ -47,18 +52,15 @@ unsigned long functionality: value 0x1f0000 would only enable the quick, byte and byte data commands. -u8 bank_reg[10] -u8 bank_mask[10] -u8 bank_start[10] -u8 bank_end[10]: +u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]: Optional bank settings. They tell which bits in which register select the active bank, as well as the range of banked registers. -CAVEATS: +Caveats +======= If your target driver polls some byte or word waiting for it to change, the stub could lock it up. Use i2cset to unlock it. If you spam it hard enough, printk can be lossy. This module really wants something like relayfs. - diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst similarity index 89% rename from Documentation/i2c/i2c-topology rename to Documentation/i2c/i2c-topology.rst index f74d78b53d4d..0c1ae95f6a97 100644 --- a/Documentation/i2c/i2c-topology +++ b/Documentation/i2c/i2c-topology.rst @@ -1,3 +1,4 @@ +============ I2C topology ============ @@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices. that has to be operated before the device can be accessed. Etc +=== These constructs are represented as i2c adapter trees by Linux, where each adapter has a parent adapter (except the root adapter) and zero or @@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be useful to know if a mux is mux-locked or if it is parent-locked. The following list was correct at the time of writing: -In drivers/i2c/muxes/ +In drivers/i2c/muxes/: + +====================== ============================================= i2c-arb-gpio-challenge Parent-locked i2c-mux-gpio Normally parent-locked, mux-locked iff all involved gpio pins are controlled by the @@ -52,18 +56,25 @@ i2c-mux-pinctrl Normally parent-locked, mux-locked iff all involved pinctrl devices are controlled by the same i2c root adapter that they mux. i2c-mux-reg Parent-locked +====================== ============================================= -In drivers/iio/ +In drivers/iio/: + +====================== ============================================= gyro/mpu3050 Mux-locked imu/inv_mpu6050/ Mux-locked +====================== ============================================= -In drivers/media/ +In drivers/media/: + +======================= ============================================= dvb-frontends/lgdt3306a Mux-locked dvb-frontends/m88ds3103 Parent-locked dvb-frontends/rtl2830 Parent-locked dvb-frontends/rtl2832 Mux-locked dvb-frontends/si2168 Mux-locked usb/cx231xx/ Parent-locked +======================= ============================================= Mux-locked muxes @@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different stages of the transaction. This has the benefit that the mux driver may be easier and cleaner to implement, but it has some caveats. +==== ===================================================================== ML1. If you build a topology with a mux-locked mux being the parent of a parent-locked mux, this might break the expectation from the parent-locked mux that the root adapter is locked during the @@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state, Otherwise garbage may appear on the bus as seen from devices behind the mux, when an unrelated i2c transfer is in flight during the non-i2c mux-changing operation. +==== ===================================================================== Mux-locked Example ------------------ + +:: + .----------. .--------. .--------. | mux- |-----| dev D1 | | root |--+--| locked | '--------' @@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g. __i2c_transfer), or a deadlock will follow. There are a couple of caveats. +==== ==================================================================== PL1. If you build a topology with a parent-locked mux being the child of another mux, this might break a possible assumption from the child mux that the root adapter is unused between its select op @@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio, caused by these subsystems are unlocked. This can be convoluted to accomplish, maybe even impossible if an acceptably clean solution is sought. +==== ==================================================================== Parent-locked Example --------------------- +:: + .----------. .--------. .--------. | parent- |-----| dev D1 | | root |--+--| locked | '--------' @@ -177,20 +197,20 @@ Parent-locked Example When there is an access to D1, this happens: - 1. Someone issues an i2c-transfer to D1. - 2. M1 locks muxes on its parent (the root adapter in this case). - 3. M1 locks its parent adapter. - 4. M1 calls ->select to ready the mux. - 5. If M1 does any i2c-transfers (on this root adapter) as part of - its select, those transfers must be unlocked i2c-transfers so - that they do not deadlock the root adapter. - 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an - unlocked i2c-transfer, so that it does not deadlock the parent - adapter. - 7. M1 calls ->deselect, if it has one. - 8. Same rules as in step 5, but for ->deselect. - 9. M1 unlocks its parent adapter. -10. M1 unlocks muxes on its parent. + 1. Someone issues an i2c-transfer to D1. + 2. M1 locks muxes on its parent (the root adapter in this case). + 3. M1 locks its parent adapter. + 4. M1 calls ->select to ready the mux. + 5. If M1 does any i2c-transfers (on this root adapter) as part of + its select, those transfers must be unlocked i2c-transfers so + that they do not deadlock the root adapter. + 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an + unlocked i2c-transfer, so that it does not deadlock the parent + adapter. + 7. M1 calls ->deselect, if it has one. + 8. Same rules as in step 5, but for ->deselect. + 9. M1 unlocks its parent adapter. + 10. M1 unlocks muxes on its parent. This means that accesses to both D2 and D3 are locked out for the full @@ -203,7 +223,7 @@ Complex Examples Parent-locked mux as parent of parent-locked mux ------------------------------------------------ -This is a useful topology, but it can be bad. +This is a useful topology, but it can be bad:: .----------. .----------. .--------. .--------. | parent- |-----| parent- |-----| dev D1 | @@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely. Mux-locked mux as parent of mux-locked mux ------------------------------------------ -This is a good topology. +This is a good topology:: .----------. .----------. .--------. .--------. | mux- |-----| mux- |-----| dev D1 | @@ -248,7 +268,7 @@ are still possibly interleaved. Mux-locked mux as parent of parent-locked mux --------------------------------------------- -This is probably a bad topology. +This is probably a bad topology:: .----------. .----------. .--------. .--------. | mux- |-----| parent- |-----| dev D1 | @@ -282,7 +302,7 @@ auto-closing, the topology is fine. Parent-locked mux as parent of mux-locked mux --------------------------------------------- -This is a good topology. +This is a good topology:: .----------. .----------. .--------. .--------. | parent- |-----| mux- |-----| dev D1 | @@ -306,7 +326,7 @@ adapter is locked directly. Two mux-locked sibling muxes ---------------------------- -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | @@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time. Two parent-locked sibling muxes ------------------------------- -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | @@ -354,7 +374,7 @@ out. Mux-locked and parent-locked sibling muxes ------------------------------------------ -This is a good topology. +This is a good topology:: .--------. .----------. .--| dev D1 | diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst new file mode 100644 index 000000000000..cd8d020f7ac5 --- /dev/null +++ b/Documentation/i2c/index.rst @@ -0,0 +1,37 @@ +. SPDX-License-Identifier: GPL-2.0 + +=================== +I2C/SMBus Subsystem +=================== + +.. toctree:: + :maxdepth: 1 + + dev-interface + dma-considerations + fault-codes + functionality + gpio-fault-injection + i2c-protocol + i2c-stub + i2c-topology + instantiating-devices + old-module-parameters + slave-eeprom-backend + slave-interface + smbus-protocol + summary + ten-bit-addresses + upgrading-clients + writing-clients + + muxes/i2c-mux-gpio + + busses/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst similarity index 93% rename from Documentation/i2c/instantiating-devices rename to Documentation/i2c/instantiating-devices.rst index 345e9ea8281a..1238f1fa3382 100644 --- a/Documentation/i2c/instantiating-devices +++ b/Documentation/i2c/instantiating-devices.rst @@ -1,3 +1,4 @@ +============================== How to instantiate I2C devices ============================== @@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C devices which live on this bus. This is done with an array of struct i2c_board_info which is registered by calling i2c_register_board_info(). -Example (from omap2 h4): +Example (from omap2 h4):: -static struct i2c_board_info h4_i2c_board_info[] __initdata = { + static struct i2c_board_info h4_i2c_board_info[] __initdata = { { I2C_BOARD_INFO("isp1301_omap", 0x2d), .irq = OMAP_GPIO_IRQ(125), @@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = { I2C_BOARD_INFO("24c01", 0x57), .platform_data = &m24c01, }, -}; + }; -static void __init omap_h4_init(void) -{ + static void __init omap_h4_init(void) + { (...) i2c_register_board_info(1, h4_i2c_board_info, ARRAY_SIZE(h4_i2c_board_info)); (...) -} + } The above code declares 3 devices on I2C bus 1, including their respective addresses and custom data needed by their drivers. When the I2C bus in @@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree This method has the same implications as method 1a. The declaration of I2C devices is here done via devicetree as subnodes of the master controller. -Example: +Example:: i2c1: i2c@400a0000 { /* ... master properties skipped ... */ @@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead, you can instantiate your I2C devices explicitly. This is done by filling a struct i2c_board_info and calling i2c_new_device(). -Example (from the sfe4001 network driver): +Example (from the sfe4001 network driver):: -static struct i2c_board_info sfe4001_hwmon_info = { + static struct i2c_board_info sfe4001_hwmon_info = { I2C_BOARD_INFO("max6647", 0x4e), -}; + }; -int sfe4001_init(struct efx_nic *efx) -{ + int sfe4001_init(struct efx_nic *efx) + { (...) efx->board_info.hwmon_client = i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info); (...) -} + } The above code instantiates 1 I2C device on the I2C bus which is on the network adapter in question. @@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer changing its design without notice). In this case, you can call i2c_new_probed_device() instead of i2c_new_device(). -Example (from the nxp OHCI driver): +Example (from the nxp OHCI driver):: -static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; + static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END }; -static int usb_hcd_nxp_probe(struct platform_device *pdev) -{ + static int usb_hcd_nxp_probe(struct platform_device *pdev) + { (...) struct i2c_adapter *i2c_adap; struct i2c_board_info i2c_info; @@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev) normal_i2c, NULL); i2c_put_adapter(i2c_adap); (...) -} + } The above code instantiates up to 1 I2C device on the I2C bus which is on the OHCI adapter in question. It first tries at address 0x2c, if nothing @@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their drivers are loaded, and if any is found, an I2C device will be instantiated automatically. In order to prevent any misbehavior of this mechanism, the following restrictions apply: + * The I2C device driver must implement the detect() method, which identifies a supported device by reading from arbitrary registers. * Only buses which are likely to have a supported device and agree to be @@ -189,6 +191,7 @@ first. Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6 kernels will find out that this method 3 is essentially similar to what was done there. Two significant differences are: + * Probing is only one way to instantiate I2C devices now, while it was the only way back then. Where possible, methods 1 and 2 should be preferred. Method 3 should only be used when there is no other way, as it can have @@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C segment, the address is sufficient to uniquely identify the device to be deleted. -Example: -# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device +Example:: + + # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device While this interface should only be used when in-kernel device declaration can't be done, there is a variety of cases where it can be helpful: + * The I2C driver usually detects devices (method 3 above) but the bus segment your device lives on doesn't have the proper class bit set and thus detection doesn't trigger. diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst similarity index 85% rename from Documentation/i2c/muxes/i2c-mux-gpio rename to Documentation/i2c/muxes/i2c-mux-gpio.rst index 893ecdfe6e43..7d27444035c3 100644 --- a/Documentation/i2c/muxes/i2c-mux-gpio +++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst @@ -1,4 +1,6 @@ +========================== Kernel driver i2c-mux-gpio +========================== Author: Peter Korsgaard @@ -8,7 +10,7 @@ Description i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments from a master I2C bus and a hardware MUX controlled through GPIO pins. -E.G.: +E.G.:: ---------- ---------- Bus segment 1 - - - - - | | SCL/SDA | |-------------- | | @@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used to control it. See include/linux/platform_data/i2c-mux-gpio.h for details. E.G. something like this for a MUX providing 4 bus segments -controlled through 3 GPIO pins: +controlled through 3 GPIO pins:: -#include -#include + #include + #include -static const unsigned myboard_gpiomux_gpios[] = { + static const unsigned myboard_gpiomux_gpios[] = { AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24 -}; + }; -static const unsigned myboard_gpiomux_values[] = { + static const unsigned myboard_gpiomux_values[] = { 0, 1, 2, 3 -}; + }; -static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { + static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { .parent = 1, .base_nr = 2, /* optional */ .values = myboard_gpiomux_values, @@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = { .gpios = myboard_gpiomux_gpios, .n_gpios = ARRAY_SIZE(myboard_gpiomux_gpios), .idle = 4, /* optional */ -}; + }; -static struct platform_device myboard_i2cmux = { + static struct platform_device myboard_i2cmux = { .name = "i2c-mux-gpio", .id = 0, .dev = { .platform_data = &myboard_i2cmux_data, }, -}; + }; If you don't know the absolute GPIO pin numbers at registration time, you can instead provide a chip name (.chip_name) and relative GPIO pin diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst similarity index 75% rename from Documentation/i2c/old-module-parameters rename to Documentation/i2c/old-module-parameters.rst index 8e2b629d533c..a1939512ad66 100644 --- a/Documentation/i2c/old-module-parameters +++ b/Documentation/i2c/old-module-parameters.rst @@ -1,3 +1,4 @@ +================================================= I2C device driver binding control from user-space ================================================= @@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface. Attaching a driver to an I2C device ----------------------------------- -Old method (module parameters): -# modprobe probe=1,0x2d -# modprobe force=1,0x2d -# modprobe force_=1,0x2d +Old method (module parameters):: -New method (sysfs interface): -# echo 0x2d > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe probe=1,0x2d + # modprobe force=1,0x2d + # modprobe force_=1,0x2d + +New method (sysfs interface):: + + # echo 0x2d > /sys/bus/i2c/devices/i2c-1/new_device Preventing a driver from attaching to an I2C device --------------------------------------------------- -Old method (module parameters): -# modprobe ignore=1,0x2f +Old method (module parameters):: -New method (sysfs interface): -# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device -# modprobe + # modprobe ignore=1,0x2f + +New method (sysfs interface):: + + # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device + # modprobe Of course, it is important to instantiate the "dummy" device before loading the driver. The dummy device will be handled by i2c-core itself, preventing diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst similarity index 90% rename from Documentation/i2c/slave-eeprom-backend rename to Documentation/i2c/slave-eeprom-backend.rst index 04f8d8a9b817..0b8cd83698e0 100644 --- a/Documentation/i2c/slave-eeprom-backend +++ b/Documentation/i2c/slave-eeprom-backend.rst @@ -1,3 +1,4 @@ +============================== Linux I2C slave eeprom backend ============================== @@ -5,10 +6,9 @@ by Wolfram Sang in 2014-15 This is a proof-of-concept backend which acts like an EEPROM on the connected I2C bus. The memory contents can be modified from userspace via this file -located in sysfs: +located in sysfs:: /sys/bus/i2c/devices//slave-eeprom As of 2015, Linux doesn't support poll on binary sysfs files, so there is no notification when another master changed the content. - diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst similarity index 94% rename from Documentation/i2c/slave-interface rename to Documentation/i2c/slave-interface.rst index 7e2a228f21bc..c769bd6a15bf 100644 --- a/Documentation/i2c/slave-interface +++ b/Documentation/i2c/slave-interface.rst @@ -1,3 +1,4 @@ +===================================== Linux I2C slave interface description ===================================== @@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as needed. The backend driver and the I2C bus driver communicate via events. Here is a small graph visualizing the data flow and the means by which data is transported. The dotted line marks only one example. The backend could also -use a character device, be in-kernel only, or something completely different: +use a character device, be in-kernel only, or something completely different:: e.g. sysfs I2C slave events I/O registers @@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference is that i2c slave backends have their own address space. So, you have to add 0x1000 to the address you would originally request. An example for instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64 -on bus 1: +on bus 1:: # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device @@ -54,7 +55,7 @@ drivers and writing backends will be given. I2C slave events ---------------- -The bus driver sends an event to the backend using the following function: +The bus driver sends an event to the backend using the following function:: ret = i2c_slave_event(client, event, &val) @@ -69,8 +70,9 @@ Event types: * I2C_SLAVE_WRITE_REQUESTED (mandatory) -'val': unused -'ret': always 0 + 'val': unused + + 'ret': always 0 Another I2C master wants to write data to us. This event should be sent once our own address and the write bit was detected. The data did not arrive yet, so @@ -79,8 +81,9 @@ to be done, though. * I2C_SLAVE_READ_REQUESTED (mandatory) -'val': backend returns first byte to be sent -'ret': always 0 + 'val': backend returns first byte to be sent + + 'ret': always 0 Another I2C master wants to read data from us. This event should be sent once our own address and the read bit was detected. After returning, the bus driver @@ -88,8 +91,9 @@ should transmit the first byte. * I2C_SLAVE_WRITE_RECEIVED (mandatory) -'val': bus driver delivers received byte -'ret': 0 if the byte should be acked, some errno if the byte should be nacked + 'val': bus driver delivers received byte + + 'ret': 0 if the byte should be acked, some errno if the byte should be nacked Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret' is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte @@ -97,8 +101,9 @@ should be nacked. * I2C_SLAVE_READ_PROCESSED (mandatory) -'val': backend returns next byte to be sent -'ret': always 0 + 'val': backend returns next byte to be sent + + 'ret': always 0 The bus driver requests the next byte to be sent to another I2C master in 'val'. Important: This does not mean that the previous byte has been acked, it @@ -111,8 +116,9 @@ your backend, though. * I2C_SLAVE_STOP (mandatory) -'val': unused -'ret': always 0 + 'val': unused + + 'ret': always 0 A stop condition was received. This can happen anytime and the backend should reset its state machine for I2C transfers to be able to receive new requests. @@ -190,4 +196,3 @@ this time of writing. Some points to keep in mind when using buffers: * A master can send STOP at any time. For partially transferred buffers, this means additional code to handle this exception. Such code tends to be error-prone. - diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst similarity index 82% rename from Documentation/i2c/smbus-protocol rename to Documentation/i2c/smbus-protocol.rst index 092d474f5843..e30eb1d274c6 100644 --- a/Documentation/i2c/smbus-protocol +++ b/Documentation/i2c/smbus-protocol.rst @@ -1,3 +1,4 @@ +====================== SMBus Protocol Summary ====================== @@ -27,17 +28,18 @@ Each transaction type corresponds to a functionality flag. Before calling a transaction function, a device driver should always check (just once) for the corresponding functionality flag to ensure that the underlying I2C adapter supports the transaction in question. See - for the details. + for the details. Key to symbols ============== +=============== ============================================================= S (1 bit) : Start bit P (1 bit) : Stop bit Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0. -A, NA (1 bit) : Accept and reverse accept bit. -Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to +A, NA (1 bit) : Accept and reverse accept bit. +Addr (7 bits): I2C 7 bit address. Note that this can be expanded as usual to get a 10 bit I2C address. Comm (8 bits): Command byte, a data byte which often selects a register on the device. @@ -45,15 +47,17 @@ Data (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh for 16 bit data. Count (8 bits): A data byte containing the length of a block operation. -[..]: Data sent by I2C device, as opposed to data sent by the host adapter. +[..]: Data sent by I2C device, as opposed to data sent by the host + adapter. +=============== ============================================================= SMBus Quick Command =================== -This sends a single bit to the device, at the place of the Rd/Wr bit. +This sends a single bit to the device, at the place of the Rd/Wr bit:: -A Addr Rd/Wr [A] P + A Addr Rd/Wr [A] P Functionality flag: I2C_FUNC_SMBUS_QUICK @@ -64,9 +68,9 @@ SMBus Receive Byte: i2c_smbus_read_byte() This reads a single byte from a device, without specifying a device register. Some devices are so simple that this interface is enough; for others, it is a shorthand if you want to read the same register as in -the previous SMBus command. +the previous SMBus command:: -S Addr Rd [A] [Data] NA P + S Addr Rd [A] [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BYTE @@ -77,7 +81,9 @@ SMBus Send Byte: i2c_smbus_write_byte() This operation is the reverse of Receive Byte: it sends a single byte to a device. See Receive Byte for more information. -S Addr Wr [A] Data [A] P +:: + + S Addr Wr [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE @@ -86,9 +92,9 @@ SMBus Read Byte: i2c_smbus_read_byte_data() ============================================ This reads a single byte from a device, from a designated register. -The register is specified through the Comm byte. +The register is specified through the Comm byte:: -S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P + S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA @@ -98,9 +104,9 @@ SMBus Read Word: i2c_smbus_read_word_data() This operation is very like Read Byte; again, data is read from a device, from a designated register that is specified through the Comm -byte. But this time, the data is a complete word (16 bits). +byte. But this time, the data is a complete word (16 bits):: -S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P + S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA @@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The register is specified through the Comm byte. This is the opposite of the Read Byte operation. -S Addr Wr [A] Comm [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA @@ -126,9 +134,9 @@ SMBus Write Word: i2c_smbus_write_word_data() This is the opposite of the Read Word operation. 16 bits of data is written to a device, to the designated register that is -specified through the Comm byte. +specified through the Comm byte.:: -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA @@ -141,10 +149,10 @@ SMBus Process Call: =================== This command selects a device register (through the Comm byte), sends -16 bits of data to it, and reads 16 bits of data in return. +16 bits of data to it, and reads 16 bits of data in return:: -S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] - S Addr Rd [A] [DataLow] A [DataHigh] NA P + S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] + S Addr Rd [A] [DataLow] A [DataHigh] NA P Functionality flag: I2C_FUNC_SMBUS_PROC_CALL @@ -152,12 +160,14 @@ Functionality flag: I2C_FUNC_SMBUS_PROC_CALL SMBus Block Read: i2c_smbus_read_block_data() ============================================== -This command reads a block of up to 32 bytes from a device, from a +This command reads a block of up to 32 bytes from a device, from a designated register that is specified through the Comm byte. The amount of data is specified by the device in the Count byte. -S Addr Wr [A] Comm [A] - S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P +:: + + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA @@ -165,11 +175,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA SMBus Block Write: i2c_smbus_write_block_data() ================================================ -The opposite of the Block Read command, this writes up to 32 bytes to +The opposite of the Block Read command, this writes up to 32 bytes to a device, to a designated register that is specified through the Comm byte. The amount of data is specified in the Count byte. -S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA @@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in Revision 2.0 of the specification. This command selects a device register (through the Comm byte), sends -1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return. +1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return:: -S Addr Wr [A] Comm [A] Count [A] Data [A] ... - S Addr Rd [A] [Count] A [Data] ... A P + S Addr Wr [A] Comm [A] Count [A] Data [A] ... + S Addr Rd [A] [Count] A [Data] ... A P Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL @@ -197,9 +209,12 @@ SMBus host acting as a slave. It is the same form as Write Word, with the command code replaced by the alerting device's address. -[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] +:: + + [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P] This is implemented in the following way in the Linux kernel: + * I2C bus drivers which support SMBus Host Notify should report I2C_FUNC_SMBUS_HOST_NOTIFY. * I2C bus drivers trigger SMBus Host Notify by a call to @@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master to know which slave triggered the interrupt. This is implemented the following way in the Linux kernel: + * I2C bus drivers which support SMBus alert should call i2c_setup_smbus_alert() to setup SMBus alert support. * I2C drivers for devices which can trigger SMBus alerts should implement @@ -261,11 +277,11 @@ but the SMBus layer places a limit of 32 bytes. I2C Block Read: i2c_smbus_read_i2c_block_data() ================================================ -This command reads a block of bytes from a device, from a -designated register that is specified through the Comm byte. +This command reads a block of bytes from a device, from a +designated register that is specified through the Comm byte:: -S Addr Wr [A] Comm [A] - S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P + S Addr Wr [A] Comm [A] + S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK @@ -273,11 +289,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK I2C Block Write: i2c_smbus_write_i2c_block_data() ================================================== -The opposite of the Block Read command, this writes bytes to +The opposite of the Block Read command, this writes bytes to a device, to a designated register that is specified through the Comm byte. Note that command lengths of 0, 2, or more bytes are supported as they are indistinguishable from data. -S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P +:: + + S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst similarity index 96% rename from Documentation/i2c/summary rename to Documentation/i2c/summary.rst index 809541ab352f..3a24eac17375 100644 --- a/Documentation/i2c/summary +++ b/Documentation/i2c/summary.rst @@ -1,7 +1,8 @@ +============= I2C and SMBus ============= -I2C (pronounce: I squared C) is a protocol developed by Philips. It is a +I2C (pronounce: I squared C) is a protocol developed by Philips. It is a slow two-wire protocol (variable speed, up to 400 kHz), with a high speed extension (3.4 MHz). It provides an inexpensive bus for connecting many types of devices with infrequent or low bandwidth communications needs. @@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages. Terminology =========== -When we talk about I2C, we use the following terms: +When we talk about I2C, we use the following terms:: + Bus -> Algorithm Adapter Device -> Driver diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst similarity index 95% rename from Documentation/i2c/ten-bit-addresses rename to Documentation/i2c/ten-bit-addresses.rst index 7b2d11e53a49..5c765aff16d5 100644 --- a/Documentation/i2c/ten-bit-addresses +++ b/Documentation/i2c/ten-bit-addresses.rst @@ -1,3 +1,7 @@ +===================== +I2C Ten-bit Addresses +===================== + The I2C protocol knows about two kinds of device addresses: normal 7 bit addresses, and an extended set of 10 bit addresses. The sets of addresses do not intersect: the 7 bit address 0x10 is not the same as the 10 bit @@ -12,6 +16,7 @@ See the I2C specification for the details. The current 10 bit address support is minimal. It should work, however you can expect some problems along the way: + * Not all bus drivers support 10-bit addresses. Some don't because the hardware doesn't support them (SMBus doesn't require 10-bit address support for example), some don't because nobody bothered adding the diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst similarity index 54% rename from Documentation/i2c/upgrading-clients rename to Documentation/i2c/upgrading-clients.rst index 96392cc5b5c7..27d29032c138 100644 --- a/Documentation/i2c/upgrading-clients +++ b/Documentation/i2c/upgrading-clients.rst @@ -1,3 +1,4 @@ +================================================= Upgrading I2C Drivers to the new 2.6 Driver Model ================================================= @@ -13,21 +14,22 @@ the old to the new new binding methods. Example old-style driver ------------------------ +:: -struct example_state { + struct example_state { struct i2c_client client; .... -}; + }; -static struct i2c_driver example_driver; + static struct i2c_driver example_driver; -static unsigned short ignore[] = { I2C_CLIENT_END }; -static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + static unsigned short ignore[] = { I2C_CLIENT_END }; + static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; -I2C_CLIENT_INSMOD; + I2C_CLIENT_INSMOD; -static int example_attach(struct i2c_adapter *adap, int addr, int kind) -{ + static int example_attach(struct i2c_adapter *adap, int addr, int kind) + { struct example_state *state; struct device *dev = &adap->dev; /* to use for dev_ reports */ int ret; @@ -59,31 +61,31 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind) dev_info(dev, "example client created\n"); return 0; -} + } -static int example_detach(struct i2c_client *client) -{ + static int example_detach(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); i2c_detach_client(client); kfree(state); return 0; -} + } -static int example_attach_adapter(struct i2c_adapter *adap) -{ + static int example_attach_adapter(struct i2c_adapter *adap) + { return i2c_probe(adap, &addr_data, example_attach); -} + } -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", .pm = &example_pm_ops, }, .attach_adapter = example_attach_adapter, .detach_client = example_detach, -}; + }; Updating the client @@ -93,38 +95,38 @@ The new style binding model will check against a list of supported devices and their associated address supplied by the code registering the busses. This means that the driver .attach_adapter and .detach_client methods can be removed, along with the addr_data, -as follows: +as follows:: -- static struct i2c_driver example_driver; + - static struct i2c_driver example_driver; -- static unsigned short ignore[] = { I2C_CLIENT_END }; -- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; + - static unsigned short ignore[] = { I2C_CLIENT_END }; + - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END }; -- I2C_CLIENT_INSMOD; + - I2C_CLIENT_INSMOD; -- static int example_attach_adapter(struct i2c_adapter *adap) -- { -- return i2c_probe(adap, &addr_data, example_attach); -- } + - static int example_attach_adapter(struct i2c_adapter *adap) + - { + - return i2c_probe(adap, &addr_data, example_attach); + - } - static struct i2c_driver example_driver = { -- .attach_adapter = example_attach_adapter, -- .detach_client = example_detach, - } + static struct i2c_driver example_driver = { + - .attach_adapter = example_attach_adapter, + - .detach_client = example_detach, + } -Add the probe and remove methods to the i2c_driver, as so: +Add the probe and remove methods to the i2c_driver, as so:: - static struct i2c_driver example_driver = { -+ .probe = example_probe, -+ .remove = example_remove, - } + static struct i2c_driver example_driver = { + + .probe = example_probe, + + .remove = example_remove, + } Change the example_attach method to accept the new parameters -which include the i2c_client that it will be working with: +which include the i2c_client that it will be working with:: -- static int example_attach(struct i2c_adapter *adap, int addr, int kind) -+ static int example_probe(struct i2c_client *client, -+ const struct i2c_device_id *id) + - static int example_attach(struct i2c_adapter *adap, int addr, int kind) + + static int example_probe(struct i2c_client *client, + + const struct i2c_device_id *id) Change the name of example_attach to example_probe to align it with the i2c_driver entry names. The rest of the probe routine will now need to be @@ -132,57 +134,59 @@ changed as the i2c_client has already been setup for use. The necessary client fields have already been setup before the probe function is called, so the following client setup -can be removed: +can be removed:: -- example->client.addr = addr; -- example->client.flags = 0; -- example->client.adapter = adap; -- -- strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); + - example->client.addr = addr; + - example->client.flags = 0; + - example->client.adapter = adap; + - + - strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name)); -The i2c_set_clientdata is now: +The i2c_set_clientdata is now:: -- i2c_set_clientdata(&state->client, state); -+ i2c_set_clientdata(client, state); + - i2c_set_clientdata(&state->client, state); + + i2c_set_clientdata(client, state); The call to i2c_attach_client is no longer needed, if the probe routine exits successfully, then the driver will be automatically -attached by the core. Change the probe routine as so: +attached by the core. Change the probe routine as so:: -- ret = i2c_attach_client(&state->i2c_client); -- if (ret < 0) { -- dev_err(dev, "failed to attach client\n"); -- kfree(state); -- return ret; -- } + - ret = i2c_attach_client(&state->i2c_client); + - if (ret < 0) { + - dev_err(dev, "failed to attach client\n"); + - kfree(state); + - return ret; + - } Remove the storage of 'struct i2c_client' from the 'struct example_state' as we are provided with the i2c_client in our example_probe. Instead we store a pointer to it for when it is needed. -struct example_state { -- struct i2c_client client; -+ struct i2c_client *client; +:: -the new i2c client as so: + struct example_state { + - struct i2c_client client; + + struct i2c_client *client; -- struct device *dev = &adap->dev; /* to use for dev_ reports */ -+ struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ +the new i2c client as so:: + + - struct device *dev = &adap->dev; /* to use for dev_ reports */ + + struct device *dev = &i2c_client->dev; /* to use for dev_ reports */ And remove the change after our client is attached, as the driver no -longer needs to register a new client structure with the core: +longer needs to register a new client structure with the core:: -- dev = &state->i2c_client.dev; + - dev = &state->i2c_client.dev; In the probe routine, ensure that the new state has the client stored -in it: +in it:: -static int example_probe(struct i2c_client *i2c_client, + static int example_probe(struct i2c_client *i2c_client, const struct i2c_device_id *id) -{ + { struct example_state *state; - struct device *dev = &i2c_client->dev; + struct device *dev = &i2c_client->dev; int ret; state = kzalloc(sizeof(struct example_state), GFP_KERNEL); @@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client, return -ENOMEM; } -+ state->client = i2c_client; + + state->client = i2c_client; Update the detach method, by changing the name to _remove and to delete the i2c_detach_client call. It is possible that you can also remove the ret variable as it is not needed for any of the core functions. -- static int example_detach(struct i2c_client *client) -+ static int example_remove(struct i2c_client *client) -{ +:: + + - static int example_detach(struct i2c_client *client) + + static int example_remove(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); -- i2c_detach_client(client); + - i2c_detach_client(client); And finally ensure that we have the correct ID table for the i2c-core -and other utilities: +and other utilities:: -+ struct i2c_device_id example_idtable[] = { -+ { "example", 0 }, -+ { } -+}; -+ -+MODULE_DEVICE_TABLE(i2c, example_idtable); + + struct i2c_device_id example_idtable[] = { + + { "example", 0 }, + + { } + +}; + + + +MODULE_DEVICE_TABLE(i2c, example_idtable); -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", }, -+ .id_table = example_ids, + + .id_table = example_ids, -Our driver should now look like this: +Our driver should now look like this:: -struct example_state { + struct example_state { struct i2c_client *client; .... -}; + }; -static int example_probe(struct i2c_client *client, - const struct i2c_device_id *id) -{ + static int example_probe(struct i2c_client *client, + const struct i2c_device_id *id) + { struct example_state *state; struct device *dev = &client->dev; @@ -250,25 +256,25 @@ static int example_probe(struct i2c_client *client, dev_info(dev, "example client created\n"); return 0; -} + } -static int example_remove(struct i2c_client *client) -{ + static int example_remove(struct i2c_client *client) + { struct example_state *state = i2c_get_clientdata(client); kfree(state); return 0; -} + } -static struct i2c_device_id example_idtable[] = { + static struct i2c_device_id example_idtable[] = { { "example", 0 }, { } -}; + }; -MODULE_DEVICE_TABLE(i2c, example_idtable); + MODULE_DEVICE_TABLE(i2c, example_idtable); -static struct i2c_driver example_driver = { - .driver = { + static struct i2c_driver example_driver = { + .driver = { .owner = THIS_MODULE, .name = "example", .pm = &example_pm_ops, @@ -276,4 +282,4 @@ static struct i2c_driver example_driver = { .id_table = example_idtable, .probe = example_probe, .remove = example_remove, -}; + }; diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst similarity index 91% rename from Documentation/i2c/writing-clients rename to Documentation/i2c/writing-clients.rst index a755b141fa4a..dddf0a14ab7c 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients.rst @@ -1,3 +1,7 @@ +=================== +Writing I2C Clients +=================== + This is a small guide for those who want to write kernel drivers for I2C or SMBus devices, using Linux as the protocol host/master (not slave). @@ -12,7 +16,7 @@ General remarks Try to keep the kernel namespace as clean as possible. The best way to do this is to use a unique prefix for all global symbols. This is especially important for exported symbols, but it is a good idea to do -it for non-exported symbols too. We will use the prefix `foo_' in this +it for non-exported symbols too. We will use the prefix ``foo_`` in this tutorial. @@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you provide. A client structure holds device-specific information like the driver model device node, and its I2C address. -static struct i2c_device_id foo_idtable[] = { +:: + + static struct i2c_device_id foo_idtable[] = { { "foo", my_id_for_foo }, { "bar", my_id_for_bar }, { } -}; + }; -MODULE_DEVICE_TABLE(i2c, foo_idtable); + MODULE_DEVICE_TABLE(i2c, foo_idtable); -static struct i2c_driver foo_driver = { + static struct i2c_driver foo_driver = { .driver = { .name = "foo", .pm = &foo_pm_ops, /* optional */ @@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = { .shutdown = foo_shutdown, /* optional */ .command = foo_command, /* optional, deprecated */ -} + } The name field is the driver name, and must not contain spaces. It should match the module name (if the driver can be compiled as a module), @@ -64,16 +70,18 @@ below. Extra client data ================= -Each client structure has a special `data' field that can point to any +Each client structure has a special ``data`` field that can point to any structure at all. You should use this to keep device-specific data. +:: + /* store the value */ void i2c_set_clientdata(struct i2c_client *client, void *data); /* retrieve the value */ void *i2c_get_clientdata(const struct i2c_client *client); -Note that starting with kernel 2.6.34, you don't have to set the `data' field +Note that starting with kernel 2.6.34, you don't have to set the ``data`` field to NULL in remove() or if probe() failed anymore. The i2c-core does this automatically on these occasions. Those are also the only times the core will touch this field. @@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily be encapsulated. The below functions are simple examples, and should not be copied -literally. +literally:: -int foo_read_value(struct i2c_client *client, u8 reg) -{ + int foo_read_value(struct i2c_client *client, u8 reg) + { if (reg < 0x10) /* byte-sized register */ return i2c_smbus_read_byte_data(client, reg); else /* word-sized register */ return i2c_smbus_read_word_data(client, reg); -} + } -int foo_write_value(struct i2c_client *client, u8 reg, u16 value) -{ + int foo_write_value(struct i2c_client *client, u8 reg, u16 value) + { if (reg == 0x10) /* Impossible to write - driver error! */ return -EINVAL; else if (reg < 0x10) /* byte-sized register */ return i2c_smbus_write_byte_data(client, reg, value); else /* word-sized register */ return i2c_smbus_write_word_data(client, reg, value); -} + } Probing and attaching @@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other kind of driver in Linux: they provide a probe() method to bind to those devices, and a remove() method to unbind. +:: + static int foo_probe(struct i2c_client *client, const struct i2c_device_id *id); static int foo_remove(struct i2c_client *client); @@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted, you have to do some initializing. Fortunately, just registering the driver module is usually enough. -static int __init foo_init(void) -{ +:: + + static int __init foo_init(void) + { return i2c_add_driver(&foo_driver); -} -module_init(foo_init); + } + module_init(foo_init); -static void __exit foo_cleanup(void) -{ + static void __exit foo_cleanup(void) + { i2c_del_driver(&foo_driver); -} -module_exit(foo_cleanup); + } + module_exit(foo_cleanup); -The module_i2c_driver() macro can be used to reduce above code. + The module_i2c_driver() macro can be used to reduce above code. -module_i2c_driver(foo_driver); + module_i2c_driver(foo_driver); -Note that some functions are marked by `__init'. These functions can +Note that some functions are marked by ``__init``. These functions can be removed after kernel booting (or module loading) is completed. -Likewise, functions marked by `__exit' are dropped by the compiler when +Likewise, functions marked by ``__exit`` are dropped by the compiler when the code is built into the kernel, as they would never be called. Driver Information ================== -/* Substitute your own name and email address */ -MODULE_AUTHOR("Frodo Looijaard " -MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); +:: -/* a few non-GPL license types are also allowed */ -MODULE_LICENSE("GPL"); + /* Substitute your own name and email address */ + MODULE_AUTHOR("Frodo Looijaard " + MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices"); + + /* a few non-GPL license types are also allowed */ + MODULE_LICENSE("GPL"); Power Management @@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C! Plain I2C communication ----------------------- +:: + int i2c_master_send(struct i2c_client *client, const char *buf, int count); int i2c_master_recv(struct i2c_client *client, char *buf, int count); @@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be less than 64k since msg.len is u16.) Returned is the actual number of bytes read/written. +:: + int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, int num); @@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains for each message the client address, the number of bytes of the message and the message data itself. -You can read the file `i2c-protocol' for more information about the +You can read the file ``i2c-protocol`` for more information about the actual I2C protocol. SMBus communication ------------------- +:: + s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data); @@ -357,6 +377,8 @@ SMBus communication This is the generic SMBus function. All functions below are implemented in terms of it. Never use this function directly! +:: + s32 i2c_smbus_read_byte(struct i2c_client *client); s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value); s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command); @@ -376,7 +398,7 @@ in terms of it. Never use this function directly! const u8 *values); These ones were removed from i2c-core because they had no users, but could -be added back later if needed: +be added back later if needed:: s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); s32 i2c_smbus_process_call(struct i2c_client *client, @@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read value, except for block transactions, which return the number of values read. The block buffers need not be longer than 32 bytes. -You can read the file `smbus-protocol' for more information about the +You can read the file ``smbus-protocol`` for more information about the actual SMBus protocol. @@ -397,7 +419,7 @@ General purpose routines ======================== Below all general purpose routines are listed, that were not mentioned -before. +before:: /* Return the adapter number for a specific adapter */ int i2c_adapter_id(struct i2c_adapter *adap); diff --git a/Documentation/index.rst b/Documentation/index.rst index 2df5a3da563c..9b45af84fd29 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -104,6 +104,7 @@ needed). fb/index fpga/index hid/index + i2c/index iio/index infiniband/index leds/index diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602 index a45702865a38..0feffd5af411 100644 --- a/Documentation/spi/spi-sc18is602 +++ b/Documentation/spi/spi-sc18is602 @@ -17,7 +17,7 @@ kernel's SPI core subsystem. The driver does not probe for supported chips, since the SI18IS602/603 does not support Chip ID registers. You will have to instantiate the devices explicitly. -Please see Documentation/i2c/instantiating-devices for details. +Please see Documentation/i2c/instantiating-devices.rst for details. Usage Notes diff --git a/MAINTAINERS b/MAINTAINERS index 6326445952f6..a3d5dd341088 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -666,7 +666,7 @@ ALI1563 I2C DRIVER M: Rudolf Marek L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-ali1563 +F: Documentation/i2c/busses/i2c-ali1563.rst F: drivers/i2c/busses/i2c-ali1563.c ALLEGRO DVT VIDEO IP CORE DRIVER @@ -6741,7 +6741,7 @@ L: linux-i2c@vger.kernel.org S: Supported F: drivers/i2c/muxes/i2c-mux-gpio.c F: include/linux/platform_data/i2c-mux-gpio.h -F: Documentation/i2c/muxes/i2c-mux-gpio +F: Documentation/i2c/muxes/i2c-mux-gpio.rst GENERIC HDLC (WAN) DRIVERS M: Krzysztof Halasa @@ -7497,14 +7497,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU M: Ajay Gupta L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-nvidia-gpu +F: Documentation/i2c/busses/i2c-nvidia-gpu.rst F: drivers/i2c/busses/i2c-nvidia-gpu.c I2C MUXES M: Peter Rosin L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/i2c-topology +F: Documentation/i2c/i2c-topology.rst F: Documentation/i2c/muxes/ F: Documentation/devicetree/bindings/i2c/i2c-mux* F: Documentation/devicetree/bindings/i2c/i2c-arb* @@ -7524,8 +7524,8 @@ I2C OVER PARALLEL PORT M: Jean Delvare L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-parport -F: Documentation/i2c/busses/i2c-parport-light +F: Documentation/i2c/busses/i2c-parport.rst +F: Documentation/i2c/busses/i2c-parport-light.rst F: drivers/i2c/busses/i2c-parport.c F: drivers/i2c/busses/i2c-parport-light.c @@ -7559,7 +7559,7 @@ I2C-TAOS-EVM DRIVER M: Jean Delvare L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-taos-evm +F: Documentation/i2c/busses/i2c-taos-evm.rst F: drivers/i2c/busses/i2c-taos-evm.c I2C-TINY-USB DRIVER @@ -7573,19 +7573,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC M: Jean Delvare L: linux-i2c@vger.kernel.org S: Maintained -F: Documentation/i2c/busses/i2c-ali1535 -F: Documentation/i2c/busses/i2c-ali1563 -F: Documentation/i2c/busses/i2c-ali15x3 -F: Documentation/i2c/busses/i2c-amd756 -F: Documentation/i2c/busses/i2c-amd8111 -F: Documentation/i2c/busses/i2c-i801 -F: Documentation/i2c/busses/i2c-nforce2 -F: Documentation/i2c/busses/i2c-piix4 -F: Documentation/i2c/busses/i2c-sis5595 -F: Documentation/i2c/busses/i2c-sis630 -F: Documentation/i2c/busses/i2c-sis96x -F: Documentation/i2c/busses/i2c-via -F: Documentation/i2c/busses/i2c-viapro +F: Documentation/i2c/busses/i2c-ali1535.rst +F: Documentation/i2c/busses/i2c-ali1563.rst +F: Documentation/i2c/busses/i2c-ali15x3.rst +F: Documentation/i2c/busses/i2c-amd756.rst +F: Documentation/i2c/busses/i2c-amd8111.rst +F: Documentation/i2c/busses/i2c-i801.rst +F: Documentation/i2c/busses/i2c-nforce2.rst +F: Documentation/i2c/busses/i2c-piix4.rst +F: Documentation/i2c/busses/i2c-sis5595.rst +F: Documentation/i2c/busses/i2c-sis630.rst +F: Documentation/i2c/busses/i2c-sis96x.rst +F: Documentation/i2c/busses/i2c-via.rst +F: Documentation/i2c/busses/i2c-viapro.rst F: drivers/i2c/busses/i2c-ali1535.c F: drivers/i2c/busses/i2c-ali1563.c F: drivers/i2c/busses/i2c-ali15x3.c @@ -7614,7 +7614,7 @@ M: Seth Heasley M: Neil Horman L: linux-i2c@vger.kernel.org F: drivers/i2c/busses/i2c-ismt.c -F: Documentation/i2c/busses/i2c-ismt +F: Documentation/i2c/busses/i2c-ismt.rst I2C/SMBUS STUB DRIVER M: Jean Delvare @@ -10355,7 +10355,7 @@ L: linux-i2c@vger.kernel.org S: Supported F: drivers/i2c/busses/i2c-mlxcpld.c F: drivers/i2c/muxes/i2c-mux-mlxcpld.c -F: Documentation/i2c/busses/i2c-mlxcpld +F: Documentation/i2c/busses/i2c-mlxcpld.rst MELLANOX MLXCPLD LED DRIVER M: Vadim Pasternak @@ -11976,7 +11976,7 @@ M: Andrew Lunn L: linux-i2c@vger.kernel.org S: Maintained F: Documentation/devicetree/bindings/i2c/i2c-ocores.txt -F: Documentation/i2c/busses/i2c-ocores +F: Documentation/i2c/busses/i2c-ocores.rst F: drivers/i2c/busses/i2c-ocores.c F: include/linux/platform_data/i2c-ocores.h @@ -14280,7 +14280,7 @@ F: net/sctp/ SCx200 CPU SUPPORT M: Jim Cromie S: Odd Fixes -F: Documentation/i2c/busses/scx200_acb +F: Documentation/i2c/busses/scx200_acb.rst F: arch/x86/platform/scx200/ F: drivers/watchdog/scx200_wdt.c F: drivers/i2c/busses/scx200* diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c index e232fa948833..79b8df258371 100644 --- a/drivers/hwmon/atxp1.c +++ b/drivers/hwmon/atxp1.c @@ -5,7 +5,7 @@ * * The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is * not auto-detected by the driver and must be instantiated explicitly. - * See Documentation/i2c/instantiating-devices for more information. + * See Documentation/i2c/instantiating-devices.rst for more information. */ #include diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c index d8c91c2cb8cf..9ae0dc28b9cf 100644 --- a/drivers/hwmon/smm665.c +++ b/drivers/hwmon/smm665.c @@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc) if (rv != -ENXIO) { /* * We expect ENXIO to reflect NACK - * (per Documentation/i2c/fault-codes). + * (per Documentation/i2c/fault-codes.rst). * Everything else is an error. */ dev_dbg(&client->dev, diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig index abedd55a1264..1474e57ecafc 100644 --- a/drivers/i2c/Kconfig +++ b/drivers/i2c/Kconfig @@ -54,7 +54,7 @@ config I2C_CHARDEV Say Y here to use i2c-* device files, usually found in the /dev directory on your system. They make it possible to have user-space programs use the I2C bus. Information on how to do this is - contained in the file . + contained in the file . This support is also available as a module. If so, the module will be called i2c-dev. @@ -107,7 +107,7 @@ config I2C_STUB especially for certain kinds of sensor chips. If you do build this module, be sure to read the notes and warnings - in . + in . If you don't know what to do here, definitely say N. diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig index 09367fc014c3..22fcf554257b 100644 --- a/drivers/i2c/busses/Kconfig +++ b/drivers/i2c/busses/Kconfig @@ -1206,7 +1206,7 @@ config I2C_PARPORT and makes it easier to add support for new devices. An adapter type parameter is now mandatory. Please read the file - Documentation/i2c/busses/i2c-parport for details. + Documentation/i2c/busses/i2c-parport.rst for details. Another driver exists, named i2c-parport-light, which doesn't depend on the parport driver. This is meant for embedded systems. Don't say diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c index f2956936c3f2..c2f087d20420 100644 --- a/drivers/i2c/busses/i2c-i801.c +++ b/drivers/i2c/busses/i2c-i801.c @@ -77,7 +77,7 @@ * SMBus Host Notify yes * Interrupt processing yes * - * See the file Documentation/i2c/busses/i2c-i801 for details. + * See the file Documentation/i2c/busses/i2c-i801.rst for details. */ #include diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c index c82e78f57386..37347c93e8e0 100644 --- a/drivers/i2c/busses/i2c-taos-evm.c +++ b/drivers/i2c/busses/i2c-taos-evm.c @@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr, /* * Voluntarily dropping error code of kstrtou8 since all * error code that it could return are invalid according - * to Documentation/i2c/fault-codes. + * to Documentation/i2c/fault-codes.rst. */ if (kstrtou8(p + 1, 16, &data->byte)) return -EPROTO; diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c index f26ed495d384..2e6dcf8ecbc9 100644 --- a/drivers/i2c/i2c-core-base.c +++ b/drivers/i2c/i2c-core-base.c @@ -2206,7 +2206,7 @@ static int i2c_detect_address(struct i2c_client *temp_client, dev_warn(&adapter->dev, "This adapter will soon drop class based instantiation of devices. " "Please make sure client 0x%02x gets instantiated by other means. " - "Check 'Documentation/i2c/instantiating-devices' for details.\n", + "Check 'Documentation/i2c/instantiating-devices.rst' for details.\n", info.addr); dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n", @@ -2236,7 +2236,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver) if (adapter->class == I2C_CLASS_DEPRECATED) { dev_dbg(&adapter->dev, "This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. " - "If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n", + "If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n", driver->driver.name); return 0; } diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c index 8f99c005458a..d28974ad9e0e 100644 --- a/drivers/iio/dummy/iio_simple_dummy.c +++ b/drivers/iio/dummy/iio_simple_dummy.c @@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd) * Varies depending on bus type of the device. As there is no device * here, call probe directly. For information on device registration * i2c: - * Documentation/i2c/writing-clients + * Documentation/i2c/writing-clients.rst * spi: * Documentation/spi/spi-summary */ diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c index 225a8df1d4e9..367497914c10 100644 --- a/drivers/rtc/rtc-ds1374.c +++ b/drivers/rtc/rtc-ds1374.c @@ -14,7 +14,7 @@ */ /* * It would be more efficient to use i2c msgs/i2c_transfer directly but, as - * recommened in .../Documentation/i2c/writing-clients section + * recommended in .../Documentation/i2c/writing-clients.rst section * "Sending and receiving", using SMBus level communication is preferred. */ diff --git a/include/linux/i2c.h b/include/linux/i2c.h index fa5552c2307b..c0a78c069117 100644 --- a/include/linux/i2c.h +++ b/include/linux/i2c.h @@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info, * * The return codes from the @master_xfer{_atomic} fields should indicate the * type of error code that occurred during the transfer, as documented in the - * Kernel Documentation file Documentation/i2c/fault-codes. + * Kernel Documentation file Documentation/i2c/fault-codes.rst. */ struct i2c_algorithm { /* From f6ae22d64433fd8e08654adad7966299da931bb9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:19 -0300 Subject: [PATCH 21/67] docs: ipmb: place it at driver-api and convert to ReST No new doc should be added at the main Documentation/ directory. Instead, new docs should be added as ReST files, within the Kernel documentation body. Fixes: 51bd6f291583 ("Add support for IPMB driver") Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/driver-api/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 37ac052ded85..38e638abe3eb 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -76,6 +76,7 @@ available subsections can be seen below. dell_rbu edid eisa + ipmb isa isapnp generic-counter From 1ec779b9fabcdbfaa06971b5c2a4d9a6e4b45b3a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:20 -0300 Subject: [PATCH 22/67] docs: packing: move it to core-api book and adjust markups The packing.txt file was misplaced, as docs should be part of a documentation book, and not at the root dir. So, move it to the core-api directory and add to its index. Also, ensure that the file will be properly parsed and the bitmap ascii artwork will use a monotonic font. Fixes: 554aae35007e ("lib: Add support for generic packing operations") Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Vladimir Oltean Tested-by: Vladimir Oltean Reviewed-by: Mike Rapoport Signed-off-by: Jonathan Corbet --- Documentation/core-api/index.rst | 1 + .../{packing.txt => core-api/packing.rst} | 81 +++++++++++-------- MAINTAINERS | 2 +- 3 files changed, 51 insertions(+), 33 deletions(-) rename Documentation/{packing.txt => core-api/packing.rst} (61%) diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index da0ed972d224..dfd8fad1e1ec 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -25,6 +25,7 @@ Core utilities librs genalloc errseq + packing printk-formats circular-buffers generic-radix-tree diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst similarity index 61% rename from Documentation/packing.txt rename to Documentation/core-api/packing.rst index f830c98645f1..d8c341fe383e 100644 --- a/Documentation/packing.txt +++ b/Documentation/core-api/packing.rst @@ -30,6 +30,7 @@ The solution ------------ This API deals with 2 basic operations: + - Packing a CPU-usable number into a memory buffer (with hardware constraints/quirks) - Unpacking a memory buffer (which has hardware constraints/quirks) @@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit. 1. Normally (no quirks), we would do it like this: -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 -7 6 5 4 -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 -3 2 1 0 +:: + + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the LSByte (0) of the u64 sits at memory offset 7. @@ -63,10 +66,12 @@ comments as "logical" notation. 2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this: -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 -7 6 5 4 -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 -3 2 1 0 +:: + + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but inverts bit offsets inside a byte. @@ -74,10 +79,12 @@ inverts bit offsets inside a byte. 3. If QUIRK_LITTLE_ENDIAN is set, we do it like this: -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 -4 5 6 7 -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 -0 1 2 3 +:: + + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every byte from each 4-byte word is placed at its mirrored position compared to @@ -86,18 +93,22 @@ the boundary of that word. 4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it like this: -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 -4 5 6 7 -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 -0 1 2 3 +:: + + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this: -31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 -3 2 1 0 -63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 -7 6 5 4 +:: + + 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 + 3 2 1 0 + 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32 + 7 6 5 4 In this case the 8 byte memory region is interpreted as follows: first 4 bytes correspond to the least significant 4-byte word, next 4 bytes to @@ -107,28 +118,34 @@ the more significant 4-byte word. 6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like this: -24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 -3 2 1 0 -56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 -7 6 5 4 +:: + + 24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23 8 9 10 11 12 13 14 15 0 1 2 3 4 5 6 7 + 3 2 1 0 + 56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39 + 7 6 5 4 7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like this: -7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 -0 1 2 3 -39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 -4 5 6 7 +:: + + 7 6 5 4 3 2 1 0 15 14 13 12 11 10 9 8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24 + 0 1 2 3 + 39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56 + 4 5 6 7 8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT are set, it looks like this: -0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 -0 1 2 3 -32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 -4 5 6 7 +:: + + 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 + 0 1 2 3 + 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 + 4 5 6 7 We always think of our offsets as if there were no quirk, and we translate diff --git a/MAINTAINERS b/MAINTAINERS index a3d5dd341088..11525de0bd16 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12099,7 +12099,7 @@ L: netdev@vger.kernel.org S: Supported F: lib/packing.c F: include/linux/packing.h -F: Documentation/packing.txt +F: Documentation/core-api/packing.rst PADATA PARALLEL EXECUTION MECHANISM M: Steffen Klassert From 76b5a6e8427159ad2b3b8764ebd6f3f5213be97e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:21 -0300 Subject: [PATCH 23/67] docs: admin-guide: add auxdisplay files to it after conversion to ReST Those two files describe userspace-faced information. While part of it might fit on uAPI, it sounds to me that the admin guide is the best place for them. Signed-off-by: Mauro Carvalho Chehab Acked-by: Miguel Ojeda Signed-off-by: Jonathan Corbet --- .../admin-guide/auxdisplay/cfag12864b.rst | 98 ++++++++++++++++ .../admin-guide/auxdisplay/index.rst | 16 +++ .../admin-guide/auxdisplay/ks0108.rst | 50 +++++++++ Documentation/admin-guide/index.rst | 1 + Documentation/auxdisplay/cfag12864b | 105 ------------------ Documentation/auxdisplay/ks0108 | 55 --------- MAINTAINERS | 2 +- drivers/auxdisplay/Kconfig | 2 +- 8 files changed, 167 insertions(+), 162 deletions(-) create mode 100644 Documentation/admin-guide/auxdisplay/cfag12864b.rst create mode 100644 Documentation/admin-guide/auxdisplay/index.rst create mode 100644 Documentation/admin-guide/auxdisplay/ks0108.rst delete mode 100644 Documentation/auxdisplay/cfag12864b delete mode 100644 Documentation/auxdisplay/ks0108 diff --git a/Documentation/admin-guide/auxdisplay/cfag12864b.rst b/Documentation/admin-guide/auxdisplay/cfag12864b.rst new file mode 100644 index 000000000000..18c2865bd322 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst @@ -0,0 +1,98 @@ +=================================== +cfag12864b LCD Driver Documentation +=================================== + +:License: GPLv2 +:Author & Maintainer: Miguel Ojeda Sandonis +:Date: 2006-10-27 + + + +.. INDEX + + 1. DRIVER INFORMATION + 2. DEVICE INFORMATION + 3. WIRING + 4. USERSPACE PROGRAMMING + +1. Driver Information +--------------------- + +This driver supports a cfag12864b LCD. + + +2. Device Information +--------------------- + +:Manufacturer: Crystalfontz +:Device Name: Crystalfontz 12864b LCD Series +:Device Code: cfag12864b +:Webpage: http://www.crystalfontz.com +:Device Webpage: http://www.crystalfontz.com/products/12864b/ +:Type: LCD (Liquid Crystal Display) +:Width: 128 +:Height: 64 +:Colors: 2 (B/N) +:Controller: ks0108 +:Controllers: 2 +:Pages: 8 each controller +:Addresses: 64 each page +:Data size: 1 byte each address +:Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte + + +3. Wiring +--------- + +The cfag12864b LCD Series don't have official wiring. + +The common wiring is done to the parallel port as shown:: + + Parallel Port cfag12864b + + Name Pin# Pin# Name + + Strobe ( 1)------------------------------(17) Enable + Data 0 ( 2)------------------------------( 4) Data 0 + Data 1 ( 3)------------------------------( 5) Data 1 + Data 2 ( 4)------------------------------( 6) Data 2 + Data 3 ( 5)------------------------------( 7) Data 3 + Data 4 ( 6)------------------------------( 8) Data 4 + Data 5 ( 7)------------------------------( 9) Data 5 + Data 6 ( 8)------------------------------(10) Data 6 + Data 7 ( 9)------------------------------(11) Data 7 + (10) [+5v]---( 1) Vdd + (11) [GND]---( 2) Ground + (12) [+5v]---(14) Reset + (13) [GND]---(15) Read / Write + Line (14)------------------------------(13) Controller Select 1 + (15) + Init (16)------------------------------(12) Controller Select 2 + Select (17)------------------------------(16) Data / Instruction + Ground (18)---[GND] [+5v]---(19) LED + + Ground (19)---[GND] + Ground (20)---[GND] E A Values: + Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm + Ground (22)---[GND] | - P1 = Preset = 10 Kohm + Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm + Ground (24)---[GND] | | + Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED - + + +4. Userspace Programming +------------------------ + +The cfag12864bfb describes a framebuffer device (/dev/fbX). + +It has a size of 1024 bytes = 1 Kbyte. +Each bit represents one pixel. If the bit is high, the pixel will +turn on. If the pixel is low, the pixel will turn off. + +You can use the framebuffer as a file: fopen, fwrite, fclose... +Although the LCD won't get updated until the next refresh time arrives. + +Also, you can mmap the framebuffer: open & mmap, munmap & close... +which is the best option for most uses. + +Check samples/auxdisplay/cfag12864b-example.c +for a real working userspace complete program with usage examples. diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst new file mode 100644 index 000000000000..e466f0595248 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/index.rst @@ -0,0 +1,16 @@ +========================= +Auxiliary Display Support +========================= + +.. toctree:: + :maxdepth: 1 + + ks0108.rst + cfag12864b.rst + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/admin-guide/auxdisplay/ks0108.rst b/Documentation/admin-guide/auxdisplay/ks0108.rst new file mode 100644 index 000000000000..c0b7faf73136 --- /dev/null +++ b/Documentation/admin-guide/auxdisplay/ks0108.rst @@ -0,0 +1,50 @@ +========================================== +ks0108 LCD Controller Driver Documentation +========================================== + +:License: GPLv2 +:Author & Maintainer: Miguel Ojeda Sandonis +:Date: 2006-10-27 + + + +.. INDEX + + 1. DRIVER INFORMATION + 2. DEVICE INFORMATION + 3. WIRING + + +1. Driver Information +--------------------- + +This driver supports the ks0108 LCD controller. + + +2. Device Information +--------------------- + +:Manufacturer: Samsung +:Device Name: KS0108 LCD Controller +:Device Code: ks0108 +:Webpage: - +:Device Webpage: - +:Type: LCD Controller (Liquid Crystal Display Controller) +:Width: 64 +:Height: 64 +:Colors: 2 (B/N) +:Pages: 8 +:Addresses: 64 each page +:Data size: 1 byte each address +:Memory size: 8 * 64 * 1 = 512 bytes + + +3. Wiring +--------- + +The driver supports data parallel port wiring. + +If you aren't building LCD related hardware, you should check +your LCD specific wiring information in the same folder. + +For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 592107a3295f..200e47820c37 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -100,6 +100,7 @@ configure specific aspects of kernel behavior to your liking. iostats kernel-per-CPU-kthreads laptops/index + auxdisplay/index lcd-panel-cgram ldm lockup-watchdogs diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/auxdisplay/cfag12864b deleted file mode 100644 index 12fd51b8de75..000000000000 --- a/Documentation/auxdisplay/cfag12864b +++ /dev/null @@ -1,105 +0,0 @@ - =================================== - cfag12864b LCD Driver Documentation - =================================== - -License: GPLv2 -Author & Maintainer: Miguel Ojeda Sandonis -Date: 2006-10-27 - - - --------- -0. INDEX --------- - - 1. DRIVER INFORMATION - 2. DEVICE INFORMATION - 3. WIRING - 4. USERSPACE PROGRAMMING - - ---------------------- -1. DRIVER INFORMATION ---------------------- - -This driver supports a cfag12864b LCD. - - ---------------------- -2. DEVICE INFORMATION ---------------------- - -Manufacturer: Crystalfontz -Device Name: Crystalfontz 12864b LCD Series -Device Code: cfag12864b -Webpage: http://www.crystalfontz.com -Device Webpage: http://www.crystalfontz.com/products/12864b/ -Type: LCD (Liquid Crystal Display) -Width: 128 -Height: 64 -Colors: 2 (B/N) -Controller: ks0108 -Controllers: 2 -Pages: 8 each controller -Addresses: 64 each page -Data size: 1 byte each address -Memory size: 2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte - - ---------- -3. WIRING ---------- - -The cfag12864b LCD Series don't have official wiring. - -The common wiring is done to the parallel port as shown: - -Parallel Port cfag12864b - - Name Pin# Pin# Name - -Strobe ( 1)------------------------------(17) Enable -Data 0 ( 2)------------------------------( 4) Data 0 -Data 1 ( 3)------------------------------( 5) Data 1 -Data 2 ( 4)------------------------------( 6) Data 2 -Data 3 ( 5)------------------------------( 7) Data 3 -Data 4 ( 6)------------------------------( 8) Data 4 -Data 5 ( 7)------------------------------( 9) Data 5 -Data 6 ( 8)------------------------------(10) Data 6 -Data 7 ( 9)------------------------------(11) Data 7 - (10) [+5v]---( 1) Vdd - (11) [GND]---( 2) Ground - (12) [+5v]---(14) Reset - (13) [GND]---(15) Read / Write - Line (14)------------------------------(13) Controller Select 1 - (15) - Init (16)------------------------------(12) Controller Select 2 -Select (17)------------------------------(16) Data / Instruction -Ground (18)---[GND] [+5v]---(19) LED + -Ground (19)---[GND] -Ground (20)---[GND] E A Values: -Ground (21)---[GND] [GND]---[P1]---(18) Vee - R = Resistor = 22 ohm -Ground (22)---[GND] | - P1 = Preset = 10 Kohm -Ground (23)---[GND] ---- S ------( 3) V0 - P2 = Preset = 1 Kohm -Ground (24)---[GND] | | -Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED - - - ------------------------- -4. USERSPACE PROGRAMMING ------------------------- - -The cfag12864bfb describes a framebuffer device (/dev/fbX). - -It has a size of 1024 bytes = 1 Kbyte. -Each bit represents one pixel. If the bit is high, the pixel will -turn on. If the pixel is low, the pixel will turn off. - -You can use the framebuffer as a file: fopen, fwrite, fclose... -Although the LCD won't get updated until the next refresh time arrives. - -Also, you can mmap the framebuffer: open & mmap, munmap & close... -which is the best option for most uses. - -Check samples/auxdisplay/cfag12864b-example.c -for a real working userspace complete program with usage examples. diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/auxdisplay/ks0108 deleted file mode 100644 index 8ddda0c8ceef..000000000000 --- a/Documentation/auxdisplay/ks0108 +++ /dev/null @@ -1,55 +0,0 @@ - ========================================== - ks0108 LCD Controller Driver Documentation - ========================================== - -License: GPLv2 -Author & Maintainer: Miguel Ojeda Sandonis -Date: 2006-10-27 - - - --------- -0. INDEX --------- - - 1. DRIVER INFORMATION - 2. DEVICE INFORMATION - 3. WIRING - - ---------------------- -1. DRIVER INFORMATION ---------------------- - -This driver supports the ks0108 LCD controller. - - ---------------------- -2. DEVICE INFORMATION ---------------------- - -Manufacturer: Samsung -Device Name: KS0108 LCD Controller -Device Code: ks0108 -Webpage: - -Device Webpage: - -Type: LCD Controller (Liquid Crystal Display Controller) -Width: 64 -Height: 64 -Colors: 2 (B/N) -Pages: 8 -Addresses: 64 each page -Data size: 1 byte each address -Memory size: 8 * 64 * 1 = 512 bytes - - ---------- -3. WIRING ---------- - -The driver supports data parallel port wiring. - -If you aren't building LCD related hardware, you should check -your LCD specific wiring information in the same folder. - -For example, check Documentation/auxdisplay/cfag12864b. diff --git a/MAINTAINERS b/MAINTAINERS index 11525de0bd16..a27e36f491b3 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9001,7 +9001,7 @@ F: kernel/kprobes.c KS0108 LCD CONTROLLER DRIVER M: Miguel Ojeda Sandonis S: Maintained -F: Documentation/auxdisplay/ks0108 +F: Documentation/admin-guide/auxdisplay/ks0108.rst F: drivers/auxdisplay/ks0108.c F: include/linux/ks0108.h diff --git a/drivers/auxdisplay/Kconfig b/drivers/auxdisplay/Kconfig index dd61fdd400f0..6b476e663e80 100644 --- a/drivers/auxdisplay/Kconfig +++ b/drivers/auxdisplay/Kconfig @@ -97,7 +97,7 @@ config CFAG12864B say Y. You also need the ks0108 LCD Controller driver. For help about how to wire your LCD to the parallel port, - check Documentation/auxdisplay/cfag12864b + check Documentation/admin-guide/auxdisplay/cfag12864b.rst Depends on the x86 arch and the framebuffer support. From 6d6486a0c59759681e75d1a2bd6684c501fcbd0e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:22 -0300 Subject: [PATCH 24/67] docs: README.buddha: convert to ReST and add to m68k book Adjust the file for it to be properly parsed by Sphinx, adding it to the index of the book it belongs. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- .../m68k/{README.buddha => buddha-driver.rst} | 95 +++++++++---------- Documentation/m68k/index.rst | 1 + 2 files changed, 48 insertions(+), 48 deletions(-) rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%) diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/buddha-driver.rst similarity index 73% rename from Documentation/m68k/README.buddha rename to Documentation/m68k/buddha-driver.rst index 3ea9827ba3c7..20e401413991 100644 --- a/Documentation/m68k/README.buddha +++ b/Documentation/m68k/buddha-driver.rst @@ -1,3 +1,6 @@ +===================================== +Amiga Buddha and Catweasel IDE Driver +===================================== The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by Geert Uytterhoeven based on the following specifications: @@ -12,12 +15,12 @@ described in their manuals, no tricks have been used (for example leaving some address lines out of the equations...). If you want to configure the board yourself (for example let a Linux kernel configure the card), look at the Commodore -Docs. Reading the nibbles should give this information: +Docs. Reading the nibbles should give this information:: -Vendor number: 4626 ($1212) -product number: 0 (42 for Catweasel Z-II) -Serial number: 0 -Rom-vector: $1000 + Vendor number: 4626 ($1212) + product number: 0 (42 for Catweasel Z-II) + Serial number: 0 + Rom-vector: $1000 The card should be a Z-II board, size 64K, not for freemem list, Rom-Vektor is valid, no second Autoconfig-board on the @@ -34,6 +37,7 @@ otherwise your chance is only 1:16 to find the board :-). The local memory-map is even active when mapped to $e8: +============== =========================================== $0-$7e Autokonfig-space, see Z-II docs. $80-$7fd reserved @@ -50,50 +54,51 @@ $a00-$aff IDE-Select 2 (Port 1, Register set 0) $b00-$bff IDE-Select 3 (Port 1, Register set 1) $c00-$cff IDE-Select 4 (Port 2, Register set 0, - Catweasel only!) + Catweasel only!) $d00-$dff IDE-Select 5 (Port 3, Register set 1, - Catweasel only!) + Catweasel only!) -$e00-$eff local expansion port, on Catweasel Z-II the +$e00-$eff local expansion port, on Catweasel Z-II the Catweasel registers are also mapped here. Never touch, use multidisk.device! - -$f00 read only, Byte-access: Bit 7 shows the - level of the IRQ-line of IDE port 0. + +$f00 read only, Byte-access: Bit 7 shows the + level of the IRQ-line of IDE port 0. $f01-$f3f mirror of $f00 -$f40 read only, Byte-access: Bit 7 shows the - level of the IRQ-line of IDE port 1. +$f40 read only, Byte-access: Bit 7 shows the + level of the IRQ-line of IDE port 1. $f41-$f7f mirror of $f40 -$f80 read only, Byte-access: Bit 7 shows the - level of the IRQ-line of IDE port 2. +$f80 read only, Byte-access: Bit 7 shows the + level of the IRQ-line of IDE port 2. (Catweasel only!) $f81-$fbf mirror of $f80 $fc0 write-only: Writing any value to this - register enables IRQs to be passed from the - IDE ports to the Zorro bus. This mechanism - has been implemented to be compatible with + register enables IRQs to be passed from the + IDE ports to the Zorro bus. This mechanism + has been implemented to be compatible with harddisks that are either defective or have - a buggy firmware and pull the IRQ line up - while starting up. If interrupts would - always be passed to the bus, the computer - might not start up. Once enabled, this flag - can not be disabled again. The level of the - flag can not be determined by software + a buggy firmware and pull the IRQ line up + while starting up. If interrupts would + always be passed to the bus, the computer + might not start up. Once enabled, this flag + can not be disabled again. The level of the + flag can not be determined by software (what for? Write to me if it's necessary!). $fc1-$fff mirror of $fc0 $1000-$ffff Buddha-Rom with offset $1000 in the rom - chip. The addresses $0 to $fff of the rom + chip. The addresses $0 to $fff of the rom chip cannot be read. Rom is Byte-wide and mapped to even addresses. +============== =========================================== The IDE ports issue an INT2. You can read the level of the IRQ-lines of the IDE-ports by reading from the three (two @@ -128,7 +133,8 @@ must always be set to 1 to be compatible with later Buddha versions (if I'll ever update this one). I presume that I'll never use the lower four bits, but they have to be set to 1 by definition. - The values in this table have to be shifted 5 bits to the + +The values in this table have to be shifted 5 bits to the left and or'd with $1f (this sets the lower 5 bits). All the timings have in common: Select and IOR/IOW rise at @@ -138,44 +144,36 @@ values are no multiple of 71. One clock-cycle is 71ns long (exactly 70,5 at 14,18 Mhz on PAL systems). value 0 (Default after reset) - -497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles) -(same timing as the Amiga 1200 does on it's IDE port without -accelerator card) + 497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles) + (same timing as the Amiga 1200 does on it's IDE port without + accelerator card) value 1 - -639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles) + 639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles) value 2 - -781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles) + 781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles) value 3 - -355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) + 355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) value 4 - -355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles) + 355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles) value 5 - -355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles) + 355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles) value 6 - -1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles) + 1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles) value 7 - -355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) + 355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle) When accessing IDE registers with A6=1 (for example $84x), the timing will always be mode 0 8-bit compatible, no matter what you have selected in the speed register: -781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive. +781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive. All the timings with a very short select-signal (the 355ns fast accesses) depend on the accelerator card used in the @@ -204,7 +202,8 @@ always shows a "no IRQ here" on the Buddha, and accesses to the third IDE port are going into data's Nirwana on the Buddha. - Jens Schönfeld february 19th, 1997 - updated may 27th, 1997 - eMail: sysop@nostlgic.tng.oche.de +Jens Schönfeld february 19th, 1997 +updated may 27th, 1997 + +eMail: sysop@nostlgic.tng.oche.de diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst index 3a5ba7fe1703..b89cb6a86d9b 100644 --- a/Documentation/m68k/index.rst +++ b/Documentation/m68k/index.rst @@ -8,6 +8,7 @@ m68k Architecture :maxdepth: 2 kernel-options + buddha-driver .. only:: subproject and html From e77e9187ae1caf2d83dd5e7f0c1466254b644a4c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:23 -0300 Subject: [PATCH 25/67] docs: parisc: convert to ReST and add to documentation body Manually convert the two PA-RISC documents to ReST, adding them to the Linux documentation body. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + .../parisc/{debugging => debugging.rst} | 7 +++ Documentation/parisc/index.rst | 18 ++++++ .../parisc/{registers => registers.rst} | 59 +++++++++++++------ 4 files changed, 68 insertions(+), 17 deletions(-) rename Documentation/parisc/{debugging => debugging.rst} (94%) create mode 100644 Documentation/parisc/index.rst rename Documentation/parisc/{registers => registers.rst} (70%) diff --git a/Documentation/index.rst b/Documentation/index.rst index 9b45af84fd29..771affb4dd3a 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -147,6 +147,7 @@ implementation. ia64/index m68k/index powerpc/index + parisc/index riscv/index s390/index sh/index diff --git a/Documentation/parisc/debugging b/Documentation/parisc/debugging.rst similarity index 94% rename from Documentation/parisc/debugging rename to Documentation/parisc/debugging.rst index 7d75223fa18d..de1b60402c5b 100644 --- a/Documentation/parisc/debugging +++ b/Documentation/parisc/debugging.rst @@ -1,8 +1,13 @@ +================= +PA-RISC Debugging +================= + okay, here are some hints for debugging the lower-level parts of linux/parisc. 1. Absolute addresses +===================== A lot of the assembly code currently runs in real mode, which means absolute addresses are used instead of virtual addresses as in the @@ -12,6 +17,7 @@ currently). 2. HPMCs +======== When real-mode code tries to access non-existent memory, you'll get an HPMC instead of a kernel oops. To debug an HPMC, try to find @@ -27,6 +33,7 @@ access it. 3. Q bit fun +============ Certain, very critical code has to clear the Q bit in the PSW. What happens when the Q bit is cleared is the CPU does not update the diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst new file mode 100644 index 000000000000..aa3ee0470425 --- /dev/null +++ b/Documentation/parisc/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +PA-RISC Architecture +==================== + +.. toctree:: + :maxdepth: 2 + + debugging + registers + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers.rst similarity index 70% rename from Documentation/parisc/registers rename to Documentation/parisc/registers.rst index 10c7d1730f5d..59c8ecf3e856 100644 --- a/Documentation/parisc/registers +++ b/Documentation/parisc/registers.rst @@ -1,11 +1,16 @@ +================================ Register Usage for Linux/PA-RISC +================================ [ an asterisk is used for planned usage which is currently unimplemented ] - General Registers as specified by ABI +General Registers as specified by ABI +===================================== - Control Registers +Control Registers +----------------- +=============================== =============================================== CR 0 (Recovery Counter) used for ptrace CR 1-CR 7(undefined) unused CR 8 (Protection ID) per-process value* @@ -29,26 +34,35 @@ CR28 (TR 4) not used CR29 (TR 5) not used CR30 (TR 6) current / 0 CR31 (TR 7) Temporary register, used in various places +=============================== =============================================== - Space Registers (kernel mode) +Space Registers (kernel mode) +----------------------------- +=============================== =============================================== SR0 temporary space register SR4-SR7 set to 0 SR1 temporary space register SR2 kernel should not clobber this SR3 used for userspace accesses (current process) +=============================== =============================================== - Space Registers (user mode) +Space Registers (user mode) +--------------------------- +=============================== =============================================== SR0 temporary space register SR1 temporary space register SR2 holds space of linux gateway page SR3 holds user address space value while in kernel SR4-SR7 Defines short address space for user/kernel +=============================== =============================================== - Processor Status Word +Processor Status Word +--------------------- +=============================== =============================================== W (64-bit addresses) 0 E (Little-endian) 0 S (Secure Interval Timer) 0 @@ -69,15 +83,19 @@ Q (collect interruption state) 1 (0 in code directly preceding an rfi) P (Protection Identifiers) 1* D (Data address translation) 1, 0 while executing real-mode code I (external interrupt mask) used by cli()/sti() macros +=============================== =============================================== - "Invisible" Registers +"Invisible" Registers +--------------------- +=============================== =============================================== PSW default W value 0 PSW default E value 0 Shadow Registers used by interruption handler code TOC enable bit 1 +=============================== =============================================== -========================================================================= +------------------------------------------------------------------------- The PA-RISC architecture defines 7 registers as "shadow registers". Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce @@ -85,7 +103,8 @@ the state save and restore time by eliminating the need for general register (GR) saves and restores in interruption handlers. Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25. -========================================================================= +------------------------------------------------------------------------- + Register usage notes, originally from John Marvin, with some additional notes from Randolph Chung. @@ -96,10 +115,12 @@ course, you need to save them if you care about them, before calling another procedure. Some of the above registers do have special meanings that you should be aware of: - r1: The addil instruction is hardwired to place its result in r1, + r1: + The addil instruction is hardwired to place its result in r1, so if you use that instruction be aware of that. - r2: This is the return pointer. In general you don't want to + r2: + This is the return pointer. In general you don't want to use this, since you need the pointer to get back to your caller. However, it is grouped with this set of registers since the caller can't rely on the value being the same @@ -107,23 +128,27 @@ that you should be aware of: and return through that register after trashing r2, and that should not cause a problem for the calling routine. - r19-r22: these are generally regarded as temporary registers. + r19-r22: + these are generally regarded as temporary registers. Note that in 64 bit they are arg7-arg4. - r23-r26: these are arg3-arg0, i.e. you can use them if you + r23-r26: + these are arg3-arg0, i.e. you can use them if you don't care about the values that were passed in anymore. - r28,r29: are ret0 and ret1. They are what you pass return values + r28,r29: + are ret0 and ret1. They are what you pass return values in. r28 is the primary return. When returning small structures r29 may also be used to pass data back to the caller. - r30: stack pointer + r30: + stack pointer - r31: the ble instruction puts the return pointer in here. + r31: + the ble instruction puts the return pointer in here. -r3-r18,r27,r30 need to be saved and restored. r3-r18 are just + r3-r18,r27,r30 need to be saved and restored. r3-r18 are just general purpose registers. r27 is the data pointer, and is used to make references to global variables easier. r30 is the stack pointer. - From 32fc3cd8ba2375b0ee385a42ba2a1aad5547816e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:24 -0300 Subject: [PATCH 26/67] docs: openrisc: convert to ReST and add to documentation body Manually convert the two openRisc documents to ReST, adding them to the Linux documentation body. Signed-off-by: Mauro Carvalho Chehab Acked-by: Stafford Horne Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + Documentation/openrisc/index.rst | 18 +++++++++++++ .../openrisc/{README => openrisc_port.rst} | 25 +++++++++++++------ Documentation/openrisc/{TODO => todo.rst} | 9 ++++--- 4 files changed, 43 insertions(+), 10 deletions(-) create mode 100644 Documentation/openrisc/index.rst rename Documentation/openrisc/{README => openrisc_port.rst} (80%) rename Documentation/openrisc/{TODO => todo.rst} (78%) diff --git a/Documentation/index.rst b/Documentation/index.rst index 771affb4dd3a..14ccbc499683 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -147,6 +147,7 @@ implementation. ia64/index m68k/index powerpc/index + openrisc/index parisc/index riscv/index s390/index diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst new file mode 100644 index 000000000000..748b3eea1707 --- /dev/null +++ b/Documentation/openrisc/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +OpenRISC Architecture +===================== + +.. toctree:: + :maxdepth: 2 + + openrisc_port + todo + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst similarity index 80% rename from Documentation/openrisc/README rename to Documentation/openrisc/openrisc_port.rst index 777a893d533d..a18747a8d191 100644 --- a/Documentation/openrisc/README +++ b/Documentation/openrisc/openrisc_port.rst @@ -1,3 +1,4 @@ +============== OpenRISC Linux ============== @@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k). For information about OpenRISC processors and ongoing development: + ======= ============================= website http://openrisc.io email openrisc@lists.librecores.org + ======= ============================= --------------------------------------------------------------------- @@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page. Instructions for building the different toolchains can be found on openrisc.io or Stafford's toolchain build and release scripts. + ========== ================================================= binaries https://github.com/openrisc/or1k-gcc/releases toolchains https://openrisc.io/software building https://github.com/stffrdhrn/or1k-toolchain-build + ========== ================================================= 2) Building -Build the Linux kernel as usual +Build the Linux kernel as usual:: make ARCH=openrisc defconfig make ARCH=openrisc @@ -43,6 +48,8 @@ development board with the OpenRISC SoC. During the build FPGA RTL is code downloaded from the FuseSoC IP cores repository and built using the FPGA vendor tools. Binaries are loaded onto the board with openocd. +:: + git clone https://github.com/olofk/fusesoc cd fusesoc sudo pip install -e . @@ -65,7 +72,9 @@ platform. Please follow the OpenRISC instructions on the QEMU website to get Linux running on QEMU. You can build QEMU yourself, but your Linux distribution likely provides binary packages to support OpenRISC. + ============= ====================================================== qemu openrisc https://wiki.qemu.org/Documentation/Platforms/OpenRISC + ============= ====================================================== --------------------------------------------------------------------- @@ -75,36 +84,38 @@ Terminology In the code, the following particles are used on symbols to limit the scope to more or less specific processor implementations: +========= ======================================= openrisc: the OpenRISC class of processors or1k: the OpenRISC 1000 family of processors or1200: the OpenRISC 1200 processor +========= ======================================= --------------------------------------------------------------------- History ======== -18. 11. 2003 Matjaz Breskvar (phoenix@bsemi.com) +18-11-2003 Matjaz Breskvar (phoenix@bsemi.com) initial port of linux to OpenRISC/or32 architecture. all the core stuff is implemented and seams usable. -08. 12. 2003 Matjaz Breskvar (phoenix@bsemi.com) +08-12-2003 Matjaz Breskvar (phoenix@bsemi.com) complete change of TLB miss handling. rewrite of exceptions handling. fully functional sash-3.6 in default initrd. a much improved version with changes all around. -10. 04. 2004 Matjaz Breskvar (phoenix@bsemi.com) +10-04-2004 Matjaz Breskvar (phoenix@bsemi.com) alot of bugfixes all over. ethernet support, functional http and telnet servers. running many standard linux apps. -26. 06. 2004 Matjaz Breskvar (phoenix@bsemi.com) +26-06-2004 Matjaz Breskvar (phoenix@bsemi.com) port to 2.6.x -30. 11. 2004 Matjaz Breskvar (phoenix@bsemi.com) +30-11-2004 Matjaz Breskvar (phoenix@bsemi.com) lots of bugfixes and enhancments. added opencores framebuffer driver. -09. 10. 2010 Jonas Bonn (jonas@southpole.se) +09-10-2010 Jonas Bonn (jonas@southpole.se) major rewrite to bring up to par with upstream Linux 2.6.36 diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst similarity index 78% rename from Documentation/openrisc/TODO rename to Documentation/openrisc/todo.rst index c43d4e1d14eb..420b18b87eda 100644 --- a/Documentation/openrisc/TODO +++ b/Documentation/openrisc/todo.rst @@ -1,12 +1,15 @@ +==== +TODO +==== + The OpenRISC Linux port is fully functional and has been tracking upstream since 2.6.35. There are, however, remaining items to be completed within the coming months. Here's a list of known-to-be-less-than-stellar items that are due for investigation shortly, i.e. our TODO list: --- Implement the rest of the DMA API... dma_map_sg, etc. +- Implement the rest of the DMA API... dma_map_sg, etc. --- Finish the renaming cleanup... there are references to or32 in the code +- Finish the renaming cleanup... there are references to or32 in the code which was an older name for the architecture. The name we've settled on is or1k and this change is slowly trickling through the stack. For the time being, or32 is equivalent to or1k. - From 5a5e045bb3b839405e3a58b02a3333d33812214c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:25 -0300 Subject: [PATCH 27/67] docs: isdn: convert to ReST and add to kAPI bookset The ISDN documentation is a mix of admin guide, uAPI and kAPI. Ideally, it should be split. Yet, not sure if it would worth the troble. Anyway, we have the same kind of mix on several drivers specific documentation. So, just like the others, keep the directory at the root Documentation/ tree, just adding a pointer to it at the kAPI section, as the documentation was written with the Kernel developers in mind. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + .../isdn/{README.avmb1 => avmb1.rst} | 227 ++++++++----- Documentation/isdn/{CREDITS => credits.rst} | 7 +- .../isdn/{README.gigaset => gigaset.rst} | 300 +++++++++++------- .../isdn/{README.hysdn => hysdn.rst} | 127 ++++---- Documentation/isdn/index.rst | 24 ++ .../{INTERFACE.CAPI => interface_capi.rst} | 174 ++++++---- .../isdn/{README.mISDN => m_isdn.rst} | 5 +- drivers/staging/isdn/hysdn/Kconfig | 2 +- 9 files changed, 536 insertions(+), 331 deletions(-) rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%) rename Documentation/isdn/{CREDITS => credits.rst} (96%) rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%) rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%) create mode 100644 Documentation/isdn/index.rst rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%) rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%) diff --git a/Documentation/index.rst b/Documentation/index.rst index 14ccbc499683..cd50e82710e0 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -106,6 +106,7 @@ needed). hid/index i2c/index iio/index + isdn/index infiniband/index leds/index media/index diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst similarity index 50% rename from Documentation/isdn/README.avmb1 rename to Documentation/isdn/avmb1.rst index 9e075484ef1e..de3961e67553 100644 --- a/Documentation/isdn/README.avmb1 +++ b/Documentation/isdn/avmb1.rst @@ -1,4 +1,6 @@ -Driver for active AVM Controller. +================================ +Driver for active AVM Controller +================================ The driver provides a kernel capi2.0 Interface (kernelcapi) and on top of this a User-Level-CAPI2.0-interface (capi) @@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils. t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware Currently supported cards: - B1 ISA (all versions) - B1 PCI - T1/T1B (HEMA card) - M1 - M2 - B1 PCMCIA + + - B1 ISA (all versions) + - B1 PCI + - T1/T1B (HEMA card) + - M1 + - M2 + - B1 PCMCIA Installing ---------- You need at least /dev/capi20 to load the firmware. -mknod /dev/capi20 c 68 0 -mknod /dev/capi20.00 c 68 1 -mknod /dev/capi20.01 c 68 2 -. -. -. -mknod /dev/capi20.19 c 68 20 +:: + + mknod /dev/capi20 c 68 0 + mknod /dev/capi20.00 c 68 1 + mknod /dev/capi20.01 c 68 2 + . + . + . + mknod /dev/capi20.19 c 68 20 Running ------- @@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware. AVM GmbH provides several t4-files for the different D-channel protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn. -if you configure as modules load the modules this way: +if you configure as modules load the modules this way:: -insmod /lib/modules/current/misc/capiutil.o -insmod /lib/modules/current/misc/b1.o -insmod /lib/modules/current/misc/kernelcapi.o -insmod /lib/modules/current/misc/capidrv.o -insmod /lib/modules/current/misc/capi.o + insmod /lib/modules/current/misc/capiutil.o + insmod /lib/modules/current/misc/b1.o + insmod /lib/modules/current/misc/kernelcapi.o + insmod /lib/modules/current/misc/capidrv.o + insmod /lib/modules/current/misc/capi.o -if you have an B1-PCI card load the module b1pci.o -insmod /lib/modules/current/misc/b1pci.o -and load the firmware with -avmcapictrl load /lib/isdn/b1.t4 1 +if you have an B1-PCI card load the module b1pci.o:: + + insmod /lib/modules/current/misc/b1pci.o + +and load the firmware with:: + + avmcapictrl load /lib/isdn/b1.t4 1 if you have an B1-ISA card load the module b1isa.o -and add the card by calling -avmcapictrl add 0x150 15 -and load the firmware by calling -avmcapictrl load /lib/isdn/b1.t4 1 +and add the card by calling:: + + avmcapictrl add 0x150 15 + +and load the firmware by calling:: + + avmcapictrl load /lib/isdn/b1.t4 1 if you have an T1-ISA card load the module t1isa.o -and add the card by calling -avmcapictrl add 0x450 15 T1 0 -and load the firmware by calling -avmcapictrl load /lib/isdn/t1.t4 1 +and add the card by calling:: + + avmcapictrl add 0x450 15 T1 0 + +and load the firmware by calling:: + + avmcapictrl load /lib/isdn/t1.t4 1 if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o before you insert the card. Leased Lines with B1 -------------------- + Init card and load firmware. + For an D64S use "FV: 1" as phone number + For an D64S2 use "FV: 1" and "FV: 2" for multilink or "FV: 1,2" to use CAPI channel bundling. /proc-Interface ----------------- -/proc/capi: +/proc/capi:: + dr-xr-xr-x 2 root root 0 Jul 1 14:03 . dr-xr-xr-x 82 root root 0 Jun 30 19:08 .. -r--r--r-- 1 root root 0 Jul 1 14:03 applications @@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling. /proc/capi/applications: applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen - level3cnt: capi_register parameter - datablkcnt: capi_register parameter - ncci-cnt: current number of nccis (connections) - recvqueuelen: number of messages on receive queue - for example: -1 -2 16 2048 1 0 -2 2 7 2048 1 0 + level3cnt: + capi_register parameter + datablkcnt: + capi_register parameter + ncci-cnt: + current number of nccis (connections) + recvqueuelen: + number of messages on receive queue + + for example:: + + 1 -2 16 2048 1 0 + 2 2 7 2048 1 0 /proc/capi/applstats: applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg - recvctlmsg: capi messages received without DATA_B3_IND - recvdatamsg: capi DATA_B3_IND received - sentctlmsg: capi messages sent without DATA_B3_REQ - sentdatamsg: capi DATA_B3_REQ sent - for example: -1 2057 1699 1721 1699 + recvctlmsg: + capi messages received without DATA_B3_IND + recvdatamsg: + capi DATA_B3_IND received + sentctlmsg: + capi messages sent without DATA_B3_REQ + sentdatamsg: + capi DATA_B3_REQ sent + + for example:: + + 1 2057 1699 1721 1699 /proc/capi/capi20: statistics of capi.o (/dev/capi20) minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - minor: minor device number of capi device - nopen: number of calls to devices open - nrecvdropmsg: capi messages dropped (messages in recvqueue in close) - nrecvctlmsg: capi messages received without DATA_B3_IND - nrecvdatamsg: capi DATA_B3_IND received - nsentctlmsg: capi messages sent without DATA_B3_REQ - nsentdatamsg: capi DATA_B3_REQ sent + minor: + minor device number of capi device + nopen: + number of calls to devices open + nrecvdropmsg: + capi messages dropped (messages in recvqueue in close) + nrecvctlmsg: + capi messages received without DATA_B3_IND + nrecvdatamsg: + capi DATA_B3_IND received + nsentctlmsg: + capi messages sent without DATA_B3_REQ + nsentdatamsg: + capi DATA_B3_REQ sent - for example: -1 2 18 0 16 2 + for example:: + + 1 2 18 0 16 2 /proc/capi/capidrv: statistics of capidrv.o (capi messages) nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - nrecvctlmsg: capi messages received without DATA_B3_IND - nrecvdatamsg: capi DATA_B3_IND received - nsentctlmsg: capi messages sent without DATA_B3_REQ - nsentdatamsg: capi DATA_B3_REQ sent + nrecvctlmsg: + capi messages received without DATA_B3_IND + nrecvdatamsg: + capi DATA_B3_IND received + nsentctlmsg: + capi messages sent without DATA_B3_REQ + nsentdatamsg: + capi DATA_B3_REQ sent + for example: -2780 2226 2256 2226 + 2780 2226 2256 2226 /proc/capi/controller: controller drivername state cardname controllerinfo - for example: -1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19 -2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0 -3 b1pcmcia running m2-150 B1 3.07-01 0x150 5 + + for example:: + + 1 b1pci running b1pci-e000 B1 3.07-01 0xe000 19 + 2 t1isa running t1isa-450 B1 3.07-01 0x450 11 0 + 3 b1pcmcia running m2-150 B1 3.07-01 0x150 5 /proc/capi/contrstats: controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg - nrecvctlmsg: capi messages received without DATA_B3_IND - nrecvdatamsg: capi DATA_B3_IND received - nsentctlmsg: capi messages sent without DATA_B3_REQ - nsentdatamsg: capi DATA_B3_REQ sent - for example: -1 2845 2272 2310 2274 -2 2 0 2 0 -3 2 0 2 0 + nrecvctlmsg: + capi messages received without DATA_B3_IND + nrecvdatamsg: + capi DATA_B3_IND received + nsentctlmsg: + capi messages sent without DATA_B3_REQ + nsentdatamsg: + capi DATA_B3_REQ sent + + for example:: + + 1 2845 2272 2310 2274 + 2 2 0 2 0 + 3 2 0 2 0 /proc/capi/driver: drivername ncontroller - for example: -b1pci 1 -t1isa 1 -b1pcmcia 1 -b1isa 0 + + for example:: + + b1pci 1 + t1isa 1 + b1pcmcia 1 + b1isa 0 /proc/capi/ncci: apllid ncci winsize sendwindow - for example: -1 0x10101 8 0 + + for example:: + + 1 0x10101 8 0 /proc/capi/users: kernelmodules that use the kernelcapi. name - for example: -capidrv -capi20 + + for example:: + + capidrv + capi20 Questions --------- + Check out the FAQ (ftp.isdn4linux.de) or subscribe to the linux-avmb1@calle.in-berlin.de mailing list by sending a mail to majordomo@calle.in-berlin.de with @@ -178,9 +236,10 @@ in the body. German documentation and several scripts can be found at ftp://ftp.avm.de/cardware/b1/linux/ -Bugs +Bugs ---- -If you find any please let me know. + +If you find any please let me know. Enjoy, diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst similarity index 96% rename from Documentation/isdn/CREDITS rename to Documentation/isdn/credits.rst index c1679e913fca..319323f2091f 100644 --- a/Documentation/isdn/CREDITS +++ b/Documentation/isdn/credits.rst @@ -1,3 +1,7 @@ +======= +Credits +======= + I want to thank all who contributed to this project and especially to: (in alphabetical order) @@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de) For creating and maintaining the FAQ. Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de) - For creating the FAQ, and the leafsite HOWTO. + For creating the FAQ, and the leafsite HOWTO. Michael 'Ghandi' Herold (michael@abadonna.franken.de) For contribution of the vbox answering machine. @@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de) Thomas Uhl (uhl@think.de) For distributing the cards. For pushing me to work ;-) - diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst similarity index 74% rename from Documentation/isdn/README.gigaset rename to Documentation/isdn/gigaset.rst index f6184b637182..98b4ec521c51 100644 --- a/Documentation/isdn/README.gigaset +++ b/Documentation/isdn/gigaset.rst @@ -1,33 +1,36 @@ +========================== GigaSet 307x Device Driver ========================== 1. Requirements - ------------ +================= + 1.1. Hardware - -------- +------------- + This driver supports the connection of the Gigaset 307x/417x family of ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB connection. The following devices are reported to be compatible: Bases: - Siemens Gigaset 3070/3075 isdn - Siemens Gigaset 4170/4175 isdn - Siemens Gigaset SX205/255 - Siemens Gigaset SX353 - T-Com Sinus 45 [AB] isdn - T-Com Sinus 721X[A] [SE] - Vox Chicago 390 ISDN (KPN Telecom) + - Siemens Gigaset 3070/3075 isdn + - Siemens Gigaset 4170/4175 isdn + - Siemens Gigaset SX205/255 + - Siemens Gigaset SX353 + - T-Com Sinus 45 [AB] isdn + - T-Com Sinus 721X[A] [SE] + - Vox Chicago 390 ISDN (KPN Telecom) RS232 data boxes: - Siemens Gigaset M101 Data - T-Com Sinus 45 Data 1 + - Siemens Gigaset M101 Data + - T-Com Sinus 45 Data 1 USB data boxes: - Siemens Gigaset M105 Data - Siemens Gigaset USB Adapter DECT - T-Com Sinus 45 Data 2 - T-Com Sinus 721 data - Chicago 390 USB (KPN) + - Siemens Gigaset M105 Data + - Siemens Gigaset USB Adapter DECT + - T-Com Sinus 45 Data 2 + - T-Com Sinus 721 data + - Chicago 390 USB (KPN) See also http://www.erbze.info/sinus_gigaset.htm (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and @@ -37,17 +40,21 @@ GigaSet 307x Device Driver with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.) If you have another device that works with our driver, please let us know. - Chances of getting an USB device to work are good if the output of - lsusb - at the command line contains one of the following: - ID 0681:0001 - ID 0681:0002 - ID 0681:0009 - ID 0681:0021 - ID 0681:0022 + Chances of getting an USB device to work are good if the output of:: + + lsusb + + at the command line contains one of the following:: + + ID 0681:0001 + ID 0681:0002 + ID 0681:0009 + ID 0681:0021 + ID 0681:0022 1.2. Software - -------- +------------- + The driver works with the Kernel CAPI subsystem and can be used with any software which is able to use CAPI 2.0 for ISDN connections (voice or data). @@ -58,9 +65,11 @@ GigaSet 307x Device Driver 2. How to use the driver - --------------------- +========================== + 2.1. Modules - ------- +------------ + For the devices to work, the proper kernel modules have to be loaded. This normally happens automatically when the system detects the USB device (base, M105) or when the line discipline is attached (M101). It @@ -71,13 +80,17 @@ GigaSet 307x Device Driver which uses the regular serial port driver to access the device, and must therefore be attached to the serial device to which the M101 is connected. The ldattach(8) command (included in util-linux-ng release 2.14 or later) - can be used for that purpose, for example: + can be used for that purpose, for example:: + ldattach GIGASET_M101 /dev/ttyS1 + This will open the device file, attach the line discipline to it, and then sleep in the background, keeping the device open so that the line discipline remains active. To deactivate it, kill the daemon, for example - with + with:: + killall ldattach + before disconnecting the device. To have this happen automatically at system startup/shutdown on an LSB compatible system, create and activate an appropriate LSB startup script /etc/init.d/gigaset. (The init name @@ -86,9 +99,10 @@ GigaSet 307x Device Driver The modules accept the following parameters: - Module Parameter Meaning + =============== ========== ========================================== + Module Parameter Meaning - gigaset debug debug level (see section 3.2.) + gigaset debug debug level (see section 3.2.) startmode initial operation mode (see section 2.5.): bas_gigaset ) 1=CAPI (default), 0=Unimodem @@ -96,11 +110,14 @@ GigaSet 307x Device Driver usb_gigaset ) cidmode initial Call-ID mode setting (see section 2.5.): 1=on (default), 0=off + =============== ========== ========================================== + Depending on your distribution you may want to create a separate module configuration file like /etc/modprobe.d/gigaset.conf for these. 2.2. Device nodes for user space programs - ------------------------------------ +----------------------------------------- + The device can be accessed from user space (eg. by the user space tools mentioned in 1.2.) through the device nodes: @@ -113,46 +130,56 @@ GigaSet 307x Device Driver You can also set a "default device" for the user space tools to use when no device node is given as parameter, by creating a symlink /dev/ttyG to - one of them, eg.: + one of them, eg.:: ln -s /dev/ttyGB0 /dev/ttyG The devices accept the following device specific ioctl calls (defined in gigaset_dev.h): - ioctl(int fd, GIGASET_REDIR, int *cmd); + ``ioctl(int fd, GIGASET_REDIR, int *cmd);`` + If cmd==1, the device is set to be controlled exclusively through the character device node; access from the ISDN subsystem is blocked. + If cmd==0, the device is set to be used from the ISDN subsystem and does not communicate through the character device node. - ioctl(int fd, GIGASET_CONFIG, int *cmd); + ``ioctl(int fd, GIGASET_CONFIG, int *cmd);`` + (ser_gigaset and usb_gigaset only) + If cmd==1, the device is set to adapter configuration mode where commands are interpreted by the M10x DECT adapter itself instead of being forwarded to the base station. In this mode, the device accepts the commands described in Siemens document "AT-Kommando Alignment M10x Data" for setting the operation mode, associating with a base station and querying parameters like field strengh and signal quality. + Note that there is no ioctl command for leaving adapter configuration mode and returning to regular operation. In order to leave adapter configuration mode, write the command ATO to the device. - ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]); + ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);`` + (usb_gigaset only) + Set the break characters on an M105's internal serial adapter to the six bytes stored in brkchars[]. Unused bytes should be set to zero. ioctl(int fd, GIGASET_VERSION, unsigned version[4]); Retrieve version information from the driver. version[0] must be set to one of: + - GIGVER_DRIVER: retrieve driver version - GIGVER_COMPAT: retrieve interface compatibility version - GIGVER_FWBASE: retrieve the firmware version of the base + Upon return, version[] is filled with the requested version information. 2.3. CAPI - ---- +--------- + The devices will show up as CAPI controllers as soon as the corresponding driver module is loaded, and can then be used with CAPI 2.0 kernel and user space applications. For user space access, @@ -165,21 +192,22 @@ GigaSet 307x Device Driver driver. 2.5. Unimodem mode - ------------- - In this mode the device works like a modem connected to a serial port - (the /dev/ttyGU0, ... mentioned above) which understands the commands +------------------ - ATZ init, reset - => OK or ERROR - ATD - ATDT dial - => OK, CONNECT, - BUSY, - NO DIAL TONE, - NO CARRIER, - NO ANSWER - +++ change to command mode when connected - ATH hangup + In this mode the device works like a modem connected to a serial port + (the /dev/ttyGU0, ... mentioned above) which understands the commands:: + + ATZ init, reset + => OK or ERROR + ATD + ATDT dial + => OK, CONNECT, + BUSY, + NO DIAL TONE, + NO CARRIER, + NO ANSWER + +++ change to command mode when connected + ATH hangup You can use some configuration tool of your distribution to configure this "modem" or configure pppd/wvdial manually. There are some example ppp @@ -189,40 +217,52 @@ GigaSet 307x Device Driver control lines. This means you must use "Stupid Mode" if you are using wvdial or you should use the nocrtscts option of pppd. You must also assure that the ppp_async module is loaded with the parameter - flag_time=0. You can do this e.g. by adding a line like + flag_time=0. You can do this e.g. by adding a line like:: - options ppp_async flag_time=0 + options ppp_async flag_time=0 - to an appropriate module configuration file, like - /etc/modprobe.d/gigaset.conf. + to an appropriate module configuration file, like:: + + /etc/modprobe.d/gigaset.conf. Unimodem mode is needed for making some devices [e.g. SX100] work which do not support the regular Gigaset command set. If debug output (see - section 3.2.) shows something like this when dialing: - CMD Received: ERROR - Available Params: 0 - Connection State: 0, Response: -1 - gigaset_process_response: resp_code -1 in ConState 0 ! - Timeout occurred + section 3.2.) shows something like this when dialing:: + + CMD Received: ERROR + Available Params: 0 + Connection State: 0, Response: -1 + gigaset_process_response: resp_code -1 in ConState 0 ! + Timeout occurred + then switching to unimodem mode may help. If you have installed the command line tool gigacontr, you can enter - unimodem mode using - gigacontr --mode unimodem - You can switch back using - gigacontr --mode isdn + unimodem mode using:: + + gigacontr --mode unimodem + + You can switch back using:: + + gigacontr --mode isdn You can also put the driver directly into Unimodem mode when it's loaded, by passing the module parameter startmode=0 to the hardware specific - module, e.g. + module, e.g.:: + modprobe usb_gigaset startmode=0 - or by adding a line like + + or by adding a line like:: + options usb_gigaset startmode=0 - to an appropriate module configuration file, like - /etc/modprobe.d/gigaset.conf + + to an appropriate module configuration file, like:: + + /etc/modprobe.d/gigaset.conf 2.6. Call-ID (CID) mode - ------------------ +----------------------- + Call-IDs are numbers used to tag commands to, and responses from, the Gigaset base in order to support the simultaneous handling of multiple ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem @@ -238,6 +278,7 @@ GigaSet 307x Device Driver During active operation, the driver switches to the necessary mode automatically. However, for the reasons above, the mode chosen when the device is not in use (idle) can be selected by the user. + - If you want to receive incoming calls, you can use the default settings (CID mode). - If you have several DECT data devices (M10x) which you want to use @@ -247,25 +288,27 @@ GigaSet 307x Device Driver If you want both of these at once, you are out of luck. You can also use the tty class parameter "cidmode" of the device to - change its CID mode while the driver is loaded, eg. - echo 0 > /sys/class/tty/ttyGU0/cidmode + change its CID mode while the driver is loaded, eg.:: + + echo 0 > /sys/class/tty/ttyGU0/cidmode 2.7. Dialing Numbers - --------------- - The called party number provided by an application for dialing out must +-------------------- +provided by an application for dialing out must be a public network number according to the local dialing plan, without any dial prefix for getting an outside line. Internal calls can be made by providing an internal extension number - prefixed with "**" (two asterisks) as the called party number. So to dial - eg. the first registered DECT handset, give "**11" as the called party - number. Dialing "***" (three asterisks) calls all extensions + prefixed with ``**`` (two asterisks) as the called party number. So to dial + eg. the first registered DECT handset, give ``**11`` as the called party + number. Dialing ``***`` (three asterisks) calls all extensions simultaneously (global call). Unimodem mode does not support internal calls. 2.8. Unregistered Wireless Devices (M101/M105) - ----------------------------------------- +---------------------------------------------- + The main purpose of the ser_gigaset and usb_gigaset drivers is to allow the M101 and M105 wireless devices to be used as ISDN devices for ISDN connections through a Gigaset base. Therefore they assume that the device @@ -279,73 +322,91 @@ GigaSet 307x Device Driver modes. See the gigacontr(8) manpage for details. 3. Troubleshooting - --------------- +==================== + 3.1. Solutions to frequently reported problems - ----------------------------------------- - Problem: - You have a slow provider and isdn4linux gives up dialing too early. - Solution: - Load the isdn module using the dialtimeout option. You can do this e.g. - by adding a line like - - options isdn dialtimeout=15 - - to /etc/modprobe.d/gigaset.conf or a similar file. +---------------------------------------------- Problem: - The isdnlog program emits error messages or just doesn't work. + You have a slow provider and isdn4linux gives up dialing too early. Solution: - Isdnlog supports only the HiSax driver. Do not attempt to use it with + Load the isdn module using the dialtimeout option. You can do this e.g. + by adding a line like:: + + options isdn dialtimeout=15 + + to /etc/modprobe.d/gigaset.conf or a similar file. + + Problem: + The isdnlog program emits error messages or just doesn't work. + Solution: + Isdnlog supports only the HiSax driver. Do not attempt to use it with other drivers such as Gigaset. Problem: - You have two or more DECT data adapters (M101/M105) and only the - first one you turn on works. + You have two or more DECT data adapters (M101/M105) and only the + first one you turn on works. Solution: - Select Unimodem mode for all DECT data adapters. (see section 2.5.) + Select Unimodem mode for all DECT data adapters. (see section 2.5.) Problem: - Messages like this: + Messages like this:: + usb_gigaset 3-2:1.0: Could not initialize the device. + appear in your syslog. Solution: Check whether your M10x wireless device is correctly registered to the Gigaset base. (see section 2.7.) 3.2. Telling the driver to provide more information - ---------------------------------------------- +--------------------------------------------------- Building the driver with the "Gigaset debugging" kernel configuration option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional information useful for debugging. You can control the amount of debugging information the driver produces by - writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g. - echo 0 > /sys/module/gigaset/parameters/debug + writing an appropriate value to /sys/module/gigaset/parameters/debug, + e.g.:: + + echo 0 > /sys/module/gigaset/parameters/debug + switches off debugging output completely, - echo 0x302020 > /sys/module/gigaset/parameters/debug + + :: + + echo 0x302020 > /sys/module/gigaset/parameters/debug + enables a reasonable set of debugging output messages. These values are bit patterns where every bit controls a certain type of debugging output. See the constants DEBUG_* in the source file gigaset.h for details. The initial value can be set using the debug parameter when loading the - module "gigaset", e.g. by adding a line - options gigaset debug=0 + module "gigaset", e.g. by adding a line:: + + options gigaset debug=0 + to your module configuration file, eg. /etc/modprobe.d/gigaset.conf Generated debugging information can be found - - as output of the command - dmesg + - as output of the command:: + + dmesg + - in system log files written by your syslog daemon, usually in /var/log/, e.g. /var/log/messages. 3.3. Reporting problems and bugs - --------------------------- +-------------------------------- If you can't solve problems with the driver on your own, feel free to use one of the forums, bug trackers, or mailing lists on - https://sourceforge.net/projects/gigaset307x + + https://sourceforge.net/projects/gigaset307x + or write an electronic mail to the maintainers. Try to provide as much information as possible, such as + - distribution - kernel version (uname -r) - gcc version (gcc --version) @@ -362,7 +423,7 @@ GigaSet 307x Device Driver appropriate forums and newsgroups. 3.4. Reporting problem solutions - --------------------------- +-------------------------------- If you solved a problem with our drivers, wrote startup scripts for your distribution, ... feel free to contact us (using one of the places mentioned in 3.3.). We'd like to add scripts, hints, documentation @@ -370,34 +431,35 @@ GigaSet 307x Device Driver 4. Links, other software - --------------------- +========================== + - Sourceforge project developing this driver and associated tools - https://sourceforge.net/projects/gigaset307x + https://sourceforge.net/projects/gigaset307x - Yahoo! Group on the Siemens Gigaset family of devices - https://de.groups.yahoo.com/group/Siemens-Gigaset + https://de.groups.yahoo.com/group/Siemens-Gigaset - Siemens Gigaset/T-Sinus compatibility table - http://www.erbze.info/sinus_gigaset.htm + http://www.erbze.info/sinus_gigaset.htm (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) 5. Credits - ------- +============ + Thanks to Karsten Keil - for his help with isdn4linux + for his help with isdn4linux Deti Fliegl - for his base driver code + for his base driver code Dennis Dietrich - for his kernel 2.6 patches + for his kernel 2.6 patches Andreas Rummel - for his work and logs to get unimodem mode working + for his work and logs to get unimodem mode working Andreas Degert - for his logs and patches to get cx 100 working + for his logs and patches to get cx 100 working Dietrich Feist - for his generous donation of one M105 and two M101 cordless adapters + for his generous donation of one M105 and two M101 cordless adapters Christoph Schweers - for his generous donation of a M34 device + for his generous donation of a M34 device and all the other people who sent logs and other information. - diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst similarity index 80% rename from Documentation/isdn/README.hysdn rename to Documentation/isdn/hysdn.rst index eeca11f00ccd..0a168d1cbffc 100644 --- a/Documentation/isdn/README.hysdn +++ b/Documentation/isdn/hysdn.rst @@ -1,4 +1,7 @@ -$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $ +============ +Hysdn Driver +============ + The hysdn driver has been written by Werner Cornelius (werner@isdn4linux.de or werner@titro.de) for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver @@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany. along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -Table of contents -================= +.. Table of contents -1. About the driver + 1. About the driver -2. Loading/Unloading the driver + 2. Loading/Unloading the driver -3. Entries in the /proc filesystem + 3. Entries in the /proc filesystem -4. The /proc/net/hysdn/cardconfX file + 4. The /proc/net/hysdn/cardconfX file -5. The /proc/net/hysdn/cardlogX file + 5. The /proc/net/hysdn/cardlogX file -6. Where to get additional info and help + 6. Where to get additional info and help 1. About the driver +=================== - The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active + The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active PCI isdn cards Champ, Ergo and Metro. To enable support for this cards enable ISDN support in the kernel config and support for HYSDN cards in - the active cards submenu. The driver may only be compiled and used if + the active cards submenu. The driver may only be compiled and used if support for loadable modules and the process filesystem have been enabled. These cards provide two different interfaces to the kernel. Without the @@ -52,22 +55,23 @@ Table of contents handlers for various protocols like ppp and others as well as config info and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de. - With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 - compliant devices with either CAPI 2.0 applications + With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 + compliant devices with either CAPI 2.0 applications (check isdn4k-utils) or -using the capidrv module- as a regular - isdn4linux device. This is done via the same mechanism as with the + isdn4linux device. This is done via the same mechanism as with the active AVM cards and in fact uses the same module. - + 2. Loading/Unloading the driver +=============================== The module has no command line parameters and auto detects up to 10 cards in the id-range 0-9. If a loaded driver shall be unloaded all open files in the /proc/net/hysdn - subdir need to be closed and all ethernet interfaces allocated by this + subdir need to be closed and all ethernet interfaces allocated by this driver must be shut down. Otherwise the module counter will avoid a module unload. - + If you are using the CAPI 2.0-interface, make sure to load/modprobe the kernelcapi-module first. @@ -76,52 +80,57 @@ Table of contents any avm-specific modules). 3. Entries in the /proc filesystem +================================== - When the module has been loaded it adds the directory hysdn in the - /proc/net tree. This directory contains exactly 2 file entries for each + When the module has been loaded it adds the directory hysdn in the + /proc/net tree. This directory contains exactly 2 file entries for each card. One is called cardconfX and the other cardlogX, where X is the - card id number from 0 to 9. + card id number from 0 to 9. The cards are numbered in the order found in the PCI config data. 4. The /proc/net/hysdn/cardconfX file +===================================== - This file may be read to get by everyone to get info about the cards type, + This file may be read to get by everyone to get info about the cards type, actual state, available features and used resources. The first 3 entries (id, bus and slot) are PCI info fields, the following type field gives the information about the cards type: - 4 -> Ergo card (server card with 2 b-chans) - 5 -> Metro card (server card with 4 or 8 b-chans) - 6 -> Champ card (client card with 2 b-chans) + - 4 -> Ergo card (server card with 2 b-chans) + - 5 -> Metro card (server card with 4 or 8 b-chans) + - 6 -> Champ card (client card with 2 b-chans) The following 3 fields show the hardware assignments for irq, iobase and the dual ported memory (dp-mem). + The fields b-chans and fax-chans announce the available card resources of this types for the user. + The state variable indicates the actual drivers state for this card with the following assignments. - 0 -> card has not been booted since driver load - 1 -> card booting is actually in progess - 2 -> card is in an error state due to a previous boot failure - 3 -> card is booted and active + - 0 -> card has not been booted since driver load + - 1 -> card booting is actually in progess + - 2 -> card is in an error state due to a previous boot failure + - 3 -> card is booted and active And the last field (device) shows the name of the ethernet device assigned to this card. Up to the first successful boot this field only shows a - to tell that no net device has been allocated up to now. Once a net device has been allocated it remains assigned to this card, even if a card is - rebooted and an boot error occurs. + rebooted and an boot error occurs. - Writing to the cardconfX file boots the card or transfers config lines to - the cards firmware. The type of data is automatically detected when the + Writing to the cardconfX file boots the card or transfers config lines to + the cards firmware. The type of data is automatically detected when the first data is written. Only root has write access to this file. The firmware boot files are normally called hyclient.pof for client cards and hyserver.pof for server cards. After successfully writing the boot file, complete config files or single config lines may be copied to this file. - If an error occurs the return value given to the writing process has the + If an error occurs the return value given to the writing process has the following additional codes (decimal): + ==== ============================================ 1000 Another process is currently bootng the card 1001 Invalid firmware header 1002 Boards dual-port RAM test failed @@ -131,34 +140,39 @@ Table of contents 1006 Second boot stage failure 1007 Timeout waiting for card ready during boot 1008 Operation only allowed in booted state - 1009 Config line too long - 1010 Invalid channel number + 1009 Config line too long + 1010 Invalid channel number 1011 Timeout sending config data + ==== ============================================ - Additional info about error reasons may be fetched from the log output. + Additional info about error reasons may be fetched from the log output. 5. The /proc/net/hysdn/cardlogX file - - The cardlogX file entry may be opened multiple for reading by everyone to +==================================== + + The cardlogX file entry may be opened multiple for reading by everyone to get the cards and drivers log data. Card messages always start with the - keyword LOG. All other lines are output from the driver. - The driver log data may be redirected to the syslog by selecting the + keyword LOG. All other lines are output from the driver. + The driver log data may be redirected to the syslog by selecting the appropriate bitmask. The cards log messages will always be send to this interface but never to the syslog. A root user may write a decimal or hex (with 0x) value t this file to select - desired output options. As mentioned above the cards log dat is always + desired output options. As mentioned above the cards log dat is always written to the cardlog file independent of the following options only used to check and debug the driver itself: - For example: - echo "0x34560078" > /proc/net/hysdn/cardlog0 + For example:: + + echo "0x34560078" > /proc/net/hysdn/cardlog0 + to output the hex log mask 34560078 for card 0. - - The written value is regarded as an unsigned 32-Bit value, bit ored for + + The written value is regarded as an unsigned 32-Bit value, bit ored for desired output. The following bits are already assigned: - 0x80000000 All driver log data is alternatively via syslog + ========== ============================================================ + 0x80000000 All driver log data is alternatively via syslog 0x00000001 Log memory allocation errors 0x00000010 Firmware load start and close are logged 0x00000020 Log firmware record parser @@ -171,25 +185,12 @@ Table of contents 0x00100000 Log all open and close actions to /proc/net/hysdn/card files 0x00200000 Log all actions from /proc file entries 0x00010000 Log network interface init and deinit - -6. Where to get additional info and help + ========== ============================================================ - If you have any problems concerning the driver or configuration contact +6. Where to get additional info and help +======================================== + + If you have any problems concerning the driver or configuration contact the Hypercope support team (support@hypercope.de) and or the authors Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or Ulrich Albrecht (ualbrecht@hypercope.de). - - - - - - - - - - - - - - - diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst new file mode 100644 index 000000000000..407e74b78372 --- /dev/null +++ b/Documentation/isdn/index.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +ISDN +==== + +.. toctree:: + :maxdepth: 2 + + interface_capi + + avmb1 + gigaset + hysdn + m_isdn + + credits + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst similarity index 75% rename from Documentation/isdn/INTERFACE.CAPI rename to Documentation/isdn/interface_capi.rst index 021aa9cf139d..01a4b5ade9a4 100644 --- a/Documentation/isdn/INTERFACE.CAPI +++ b/Documentation/isdn/interface_capi.rst @@ -1,7 +1,9 @@ +========================================= Kernel CAPI Interface to Hardware Drivers ------------------------------------------ +========================================= 1. Overview +=========== From the CAPI 2.0 specification: COMMON-ISDN-API (CAPI) is an application programming interface standard used @@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org. 2. Driver and Device Registration +================================= CAPI drivers optionally register themselves with Kernel CAPI by calling the Kernel CAPI function register_capi_driver() with a pointer to a struct @@ -50,6 +53,7 @@ callback functions by Kernel CAPI. 3. Application Registration and Communication +============================================= Kernel CAPI forwards registration requests from applications (calls to CAPI operation CAPI_REGISTER) to an appropriate hardware driver by calling its @@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore. 4. Data Structures +================== 4.1 struct capi_driver +---------------------- This structure describes a Kernel CAPI driver itself. It is used in the register_capi_driver() and unregister_capi_driver() functions, and contains the following non-private fields, all to be set by the driver before calling register_capi_driver(): -char name[32] +``char name[32]`` the name of the driver, as a zero-terminated ASCII string -char revision[32] +``char revision[32]`` the revision number of the driver, as a zero-terminated ASCII string -int (*add_card)(struct capi_driver *driver, capicardparams *data) +``int (*add_card)(struct capi_driver *driver, capicardparams *data)`` a callback function pointer (may be NULL) 4.2 struct capi_ctr +------------------- This structure describes an ISDN device (controller) handled by a Kernel CAPI driver. After registration via the attach_capi_ctr() function it is passed to @@ -96,88 +103,109 @@ identify the controller to operate on. It contains the following non-private fields: -- to be set by the driver before calling attach_capi_ctr(): +to be set by the driver before calling attach_capi_ctr(): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -struct module *owner +``struct module *owner`` pointer to the driver module owning the device -void *driverdata +``void *driverdata`` an opaque pointer to driver specific data, not touched by Kernel CAPI -char name[32] +``char name[32]`` the name of the controller, as a zero-terminated ASCII string -char *driver_name +``char *driver_name`` the name of the driver, as a zero-terminated ASCII string -int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata) +``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)`` (optional) pointer to a callback function for sending firmware and configuration data to the device + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_ready(). + Return value: 0 on success, error code on error Called in process context. -void (*reset_ctr)(struct capi_ctr *ctrlr) +``void (*reset_ctr)(struct capi_ctr *ctrlr)`` (optional) pointer to a callback function for stopping the device, releasing all registered applications + The function may return before the operation has completed. + Completion must be signalled by a call to capi_ctr_down(). + Called in process context. -void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, - capi_register_params *rparam) -void (*release_appl)(struct capi_ctr *ctrlr, u16 applid) - pointers to callback functions for registration and deregistration of +``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)`` + pointers to callback function for registration of applications with the device + Calls to these functions are serialized by Kernel CAPI so that only one call to any of them is active at any time. -u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb) +``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)`` + pointers to callback functions deregistration of + applications with the device + + Calls to these functions are serialized by Kernel CAPI so that only + one call to any of them is active at any time. + +``u16 (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)`` pointer to a callback function for sending a CAPI message to the device + Return value: CAPI error code + If the method returns 0 (CAPI_NOERROR) the driver has taken ownership of the skb and the caller may no longer access it. If it returns a non-zero (error) value then ownership of the skb returns to the caller who may reuse or free it. + The return value should only be used to signal problems with respect to accepting or queueing the message. Errors occurring during the actual processing of the message should be signaled with an appropriate reply message. + May be called in process or interrupt context. + Calls to this function are not serialized by Kernel CAPI, ie. it must be prepared to be re-entered. -char *(*procinfo)(struct capi_ctr *ctrlr) +``char *(*procinfo)(struct capi_ctr *ctrlr)`` pointer to a callback function returning the entry for the device in the CAPI controller info table, /proc/capi/controller -const struct file_operations *proc_fops +``const struct file_operations *proc_fops`` pointers to callback functions for the device's proc file system entry, /proc/capi/controllers/; pointer to the device's capi_ctr structure is available from struct proc_dir_entry::data which is available from struct inode. -Note: Callback functions except send_message() are never called in interrupt -context. +Note: + Callback functions except send_message() are never called in interrupt + context. -- to be filled in before calling capi_ctr_ready(): +to be filled in before calling capi_ctr_ready(): +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -u8 manu[CAPI_MANUFACTURER_LEN] +``u8 manu[CAPI_MANUFACTURER_LEN]`` value to return for CAPI_GET_MANUFACTURER -capi_version version +``capi_version version`` value to return for CAPI_GET_VERSION -capi_profile profile +``capi_profile profile`` value to return for CAPI_GET_PROFILE -u8 serial[CAPI_SERIAL_LEN] +``u8 serial[CAPI_SERIAL_LEN]`` value to return for CAPI_GET_SERIAL 4.3 SKBs +-------- CAPI messages are passed between Kernel CAPI and the driver via send_message() and capi_ctr_handle_message(), stored in the data portion of a socket buffer @@ -192,6 +220,7 @@ instead of 30. 4.4 The _cmsg Structure +----------------------- (declared in ) @@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they represent. See for the exact spelling. Member data types are: +=========== ================================================================= u8 for CAPI parameters of type 'byte' u16 for CAPI parameters of type 'word' @@ -235,6 +265,7 @@ _cmstruct alternative representation for CAPI parameters of type 'struct' CAPI_COMPOSE: The parameter is present. Subparameter values are stored individually in the corresponding _cmsg structure members. +=========== ================================================================= Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert messages between their transport encoding described in the CAPI 2.0 standard @@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message. 5. Lower Layer Interface Functions +================================== (declared in ) -void register_capi_driver(struct capi_driver *drvr) -void unregister_capi_driver(struct capi_driver *drvr) - register/unregister a driver with Kernel CAPI +:: -int attach_capi_ctr(struct capi_ctr *ctrlr) -int detach_capi_ctr(struct capi_ctr *ctrlr) - register/unregister a device (controller) with Kernel CAPI + void register_capi_driver(struct capi_driver *drvr) + void unregister_capi_driver(struct capi_driver *drvr) -void capi_ctr_ready(struct capi_ctr *ctrlr) -void capi_ctr_down(struct capi_ctr *ctrlr) - signal controller ready/not ready +register/unregister a driver with Kernel CAPI -void capi_ctr_suspend_output(struct capi_ctr *ctrlr) -void capi_ctr_resume_output(struct capi_ctr *ctrlr) - signal suspend/resume +:: -void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, - struct sk_buff *skb) - pass a received CAPI message to Kernel CAPI - for forwarding to the specified application + int attach_capi_ctr(struct capi_ctr *ctrlr) + int detach_capi_ctr(struct capi_ctr *ctrlr) + +register/unregister a device (controller) with Kernel CAPI + +:: + + void capi_ctr_ready(struct capi_ctr *ctrlr) + void capi_ctr_down(struct capi_ctr *ctrlr) + +signal controller ready/not ready + +:: + + void capi_ctr_suspend_output(struct capi_ctr *ctrlr) + void capi_ctr_resume_output(struct capi_ctr *ctrlr) + +signal suspend/resume + +:: + + void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid, + struct sk_buff *skb) + +pass a received CAPI message to Kernel CAPI +for forwarding to the specified application 6. Helper Functions and Macros +============================== Library functions (from ): -void capilib_new_ncci(struct list_head *head, u16 applid, +:: + + void capilib_new_ncci(struct list_head *head, u16 applid, u32 ncci, u32 winsize) -void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) -void capilib_release_appl(struct list_head *head, u16 applid) -void capilib_release(struct list_head *head) -void capilib_data_b3_conf(struct list_head *head, u16 applid, + void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci) + void capilib_release_appl(struct list_head *head, u16 applid) + void capilib_release(struct list_head *head) + void capilib_data_b3_conf(struct list_head *head, u16 applid, u32 ncci, u16 msgid) -u16 capilib_data_b3_req(struct list_head *head, u16 applid, + u16 capilib_data_b3_req(struct list_head *head, u16 applid, u32 ncci, u16 msgid) Macros to extract/set element values from/in a CAPI message header (from ): +====================== ============================= ==================== Get Macro Set Macro Element (Type) - +====================== ============================= ==================== CAPIMSG_LEN(m) CAPIMSG_SETLEN(m, len) Total Length (u16) CAPIMSG_APPID(m) CAPIMSG_SETAPPID(m, applid) ApplID (u16) CAPIMSG_COMMAND(m) CAPIMSG_SETCOMMAND(m,cmd) Command (u8) @@ -300,31 +351,31 @@ CAPIMSG_MSGID(m) CAPIMSG_SETMSGID(m, msgid) Message Number (u16) CAPIMSG_CONTROL(m) CAPIMSG_SETCONTROL(m, contr) Controller/PLCI/NCCI (u32) CAPIMSG_DATALEN(m) CAPIMSG_SETDATALEN(m, len) Data Length (u16) +====================== ============================= ==================== Library functions for working with _cmsg structures (from ): -unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg) - Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the - result in *msg. +``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)`` + Assembles a CAPI 2.0 message from the parameters in ``*cmsg``, + storing the result in ``*msg``. -unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg) - Disassembles the CAPI 2.0 message in *msg, storing the parameters in - *cmsg. +``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)`` + Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters + in ``*cmsg``. -unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, - u16 Messagenumber, u32 Controller) - Fills the header part and address field of the _cmsg structure *cmsg +``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)`` + Fills the header part and address field of the _cmsg structure ``*cmsg`` with the given values, zeroing the remainder of the structure so only parameters with non-default values need to be changed before sending the message. -void capi_cmsg_answer(_cmsg *cmsg) - Sets the low bit of the Subcommand field in *cmsg, thereby converting - _REQ to _CONF and _IND to _RESP. +``void capi_cmsg_answer(_cmsg *cmsg)`` + Sets the low bit of the Subcommand field in ``*cmsg``, thereby + converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``. -char *capi_cmd2str(u8 Command, u8 Subcommand) +``char *capi_cmd2str(u8 Command, u8 Subcommand)`` Returns the CAPI 2.0 message name corresponding to the given command and subcommand values, as a static ASCII string. The return value may be NULL if the command/subcommand is not one of those defined in the @@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand) 7. Debugging +============ The module kernelcapi has a module parameter showcapimsgs controlling some debugging output produced by the module. It can only be set when the module is diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst similarity index 89% rename from Documentation/isdn/README.mISDN rename to Documentation/isdn/m_isdn.rst index cd8bf920e77b..9957de349e69 100644 --- a/Documentation/isdn/README.mISDN +++ b/Documentation/isdn/m_isdn.rst @@ -1,6 +1,9 @@ +============ +mISDN Driver +============ + mISDN is a new modular ISDN driver, in the long term it should replace the old I4L driver architecture for passiv ISDN cards. It was designed to allow a broad range of applications and interfaces but only have the basic function in kernel, the interface to the user space is based on sockets with a own address family AF_ISDN. - diff --git a/drivers/staging/isdn/hysdn/Kconfig b/drivers/staging/isdn/hysdn/Kconfig index 1971ef850c9a..4c8a9283b9dd 100644 --- a/drivers/staging/isdn/hysdn/Kconfig +++ b/drivers/staging/isdn/hysdn/Kconfig @@ -5,7 +5,7 @@ config HYSDN help Say Y here if you have one of Hypercope's active PCI ISDN cards Champ, Ergo and Metro. You will then get a module called hysdn. - Please read the file for more + Please read the file for more information. config HYSDN_CAPI From ec23eb54fbc7a07405d416d77e8115e575ce3adc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:27 -0300 Subject: [PATCH 28/67] docs: fs: convert docs without extension to ReST There are 3 remaining files without an extension inside the fs docs dir. Manually convert them to ReST. In the case of the nfs/exporting.rst file, as the nfs docs aren't ported yet, I opted to convert and add a :orphan: there, with should be removed when it gets added into a nfs-specific part of the fs documentation. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- ...irectory-locking => directory-locking.rst} | 40 ++- Documentation/filesystems/index.rst | 2 + .../filesystems/{Locking => locking.rst} | 257 ++++++++++++------ .../nfs/{Exporting => exporting.rst} | 31 ++- Documentation/filesystems/vfs.rst | 2 +- fs/cifs/export.c | 2 +- fs/exportfs/expfs.c | 2 +- fs/isofs/export.c | 2 +- fs/orangefs/file.c | 2 +- include/linux/dcache.h | 2 +- include/linux/exportfs.h | 2 +- 11 files changed, 225 insertions(+), 119 deletions(-) rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%) rename Documentation/filesystems/{Locking => locking.rst} (79%) rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%) diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking.rst similarity index 86% rename from Documentation/filesystems/directory-locking rename to Documentation/filesystems/directory-locking.rst index 4e32cb961e5b..de12016ee419 100644 --- a/Documentation/filesystems/directory-locking +++ b/Documentation/filesystems/directory-locking.rst @@ -1,12 +1,17 @@ - Locking scheme used for directory operations is based on two +================= +Directory Locking +================= + + +Locking scheme used for directory operations is based on two kinds of locks - per-inode (->i_rwsem) and per-filesystem (->s_vfs_rename_mutex). - When taking the i_rwsem on multiple non-directory objects, we +When taking the i_rwsem on multiple non-directory objects, we always acquire the locks in order by increasing address. We'll call that "inode pointer" order in the following. - For our purposes all operations fall in 5 classes: +For our purposes all operations fall in 5 classes: 1) read access. Locking rules: caller locks directory we are accessing. The lock is taken shared. @@ -27,25 +32,29 @@ NB: we might get away with locking the the source (and target in exchange case) shared. 5) link creation. Locking rules: + * lock parent * check that source is not a directory * lock source * call the method. + All locks are exclusive. 6) cross-directory rename. The trickiest in the whole bunch. Locking rules: + * lock the filesystem * lock parents in "ancestors first" order. * find source and target. * if old parent is equal to or is a descendent of target - fail with -ENOTEMPTY + fail with -ENOTEMPTY * if new parent is equal to or is a descendent of source - fail with -ELOOP + fail with -ELOOP * If it's an exchange, lock both the source and the target. * If the target exists, lock it. If the source is a non-directory, lock it. If we need to lock both, do so in inode pointer order. * call the method. + All ->i_rwsem are taken exclusive. Again, we might get away with locking the the source (and target in exchange case) shared. @@ -54,10 +63,11 @@ read, modified or removed by method will be locked by caller. If no directory is its own ancestor, the scheme above is deadlock-free. + Proof: First of all, at any moment we have a partial ordering of the -objects - A < B iff A is an ancestor of B. + objects - A < B iff A is an ancestor of B. That ordering can change. However, the following is true: @@ -77,32 +87,32 @@ objects - A < B iff A is an ancestor of B. non-directory object, except renames, which take locks on source and target in inode pointer order in the case they are not directories.) - Now consider the minimal deadlock. Each process is blocked on +Now consider the minimal deadlock. Each process is blocked on attempt to acquire some lock and already holds at least one lock. Let's consider the set of contended locks. First of all, filesystem lock is not contended, since any process blocked on it is not holding any locks. Thus all processes are blocked on ->i_rwsem. - By (3), any process holding a non-directory lock can only be +By (3), any process holding a non-directory lock can only be waiting on another non-directory lock with a larger address. Therefore the process holding the "largest" such lock can always make progress, and non-directory objects are not included in the set of contended locks. - Thus link creation can't be a part of deadlock - it can't be +Thus link creation can't be a part of deadlock - it can't be blocked on source and it means that it doesn't hold any locks. - Any contended object is either held by cross-directory rename or +Any contended object is either held by cross-directory rename or has a child that is also contended. Indeed, suppose that it is held by operation other than cross-directory rename. Then the lock this operation is blocked on belongs to child of that object due to (1). - It means that one of the operations is cross-directory rename. +It means that one of the operations is cross-directory rename. Otherwise the set of contended objects would be infinite - each of them would have a contended child and we had assumed that no object is its own descendent. Moreover, there is exactly one cross-directory rename (see above). - Consider the object blocking the cross-directory rename. One +Consider the object blocking the cross-directory rename. One of its descendents is locked by cross-directory rename (otherwise we would again have an infinite set of contended objects). But that means that cross-directory rename is taking locks out of order. Due @@ -112,7 +122,7 @@ try to acquire lock on descendent before the lock on ancestor. Contradiction. I.e. deadlock is impossible. Q.E.D. - These operations are guaranteed to avoid loop creation. Indeed, +These operations are guaranteed to avoid loop creation. Indeed, the only operation that could introduce loops is cross-directory rename. Since the only new (parent, child) pair added by rename() is (new parent, source), such loop would have to contain these objects and the rest of it @@ -123,13 +133,13 @@ new parent had been equal to or a descendent of source since the moment when we had acquired filesystem lock and rename() would fail with -ELOOP in that case. - While this locking scheme works for arbitrary DAGs, it relies on +While this locking scheme works for arbitrary DAGs, it relies on ability to check that directory is a descendent of another object. Current implementation assumes that directory graph is a tree. This assumption is also preserved by all operations (cross-directory rename on a tree that would not introduce a cycle will leave it a tree and link() fails for directories). - Notice that "directory" in the above == "anything that might have +Notice that "directory" in the above == "anything that might have children", so if we are going to introduce hybrid objects we will need either to make sure that link(2) doesn't work for them or to make changes in is_subdir() that would make it work even in presence of such beasts. diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 2de2fe2ab078..08320c35d03b 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -20,6 +20,8 @@ algorithms work. path-lookup api-summary splice + locking + directory-locking Filesystem support layers ========================= diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/locking.rst similarity index 79% rename from Documentation/filesystems/Locking rename to Documentation/filesystems/locking.rst index 204dd3ea36bb..fc3a0704553c 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/locking.rst @@ -1,14 +1,22 @@ - The text below describes the locking rules for VFS-related methods. +======= +Locking +======= + +The text below describes the locking rules for VFS-related methods. It is (believed to be) up-to-date. *Please*, if you change anything in prototypes or locking protocols - update this file. And update the relevant instances in the tree, don't leave that to maintainers of filesystems/devices/ etc. At the very least, put the list of dubious cases in the end of this file. Don't turn it into log - maintainers of out-of-the-tree code are supposed to be able to use diff(1). - Thing currently missing here: socket operations. Alexey? ---------------------------- dentry_operations -------------------------- -prototypes: +Thing currently missing here: socket operations. Alexey? + +dentry_operations +================= + +prototypes:: + int (*d_revalidate)(struct dentry *, unsigned int); int (*d_weak_revalidate)(struct dentry *, unsigned int); int (*d_hash)(const struct dentry *, struct qstr *); @@ -24,23 +32,30 @@ prototypes: struct dentry *(*d_real)(struct dentry *, const struct inode *); locking rules: - rename_lock ->d_lock may block rcu-walk -d_revalidate: no no yes (ref-walk) maybe -d_weak_revalidate:no no yes no -d_hash no no no maybe -d_compare: yes no no maybe -d_delete: no yes no no -d_init: no no yes no -d_release: no no yes no -d_prune: no yes no no -d_iput: no no yes no -d_dname: no no no no -d_automount: no no yes no -d_manage: no no yes (ref-walk) maybe -d_real no no yes no ---------------------------- inode_operations --------------------------- -prototypes: +================== =========== ======== ============== ======== +ops rename_lock ->d_lock may block rcu-walk +================== =========== ======== ============== ======== +d_revalidate: no no yes (ref-walk) maybe +d_weak_revalidate: no no yes no +d_hash no no no maybe +d_compare: yes no no maybe +d_delete: no yes no no +d_init: no no yes no +d_release: no no yes no +d_prune: no yes no no +d_iput: no no yes no +d_dname: no no no no +d_automount: no no yes no +d_manage: no no yes (ref-walk) maybe +d_real no no yes no +================== =========== ======== ============== ======== + +inode_operations +================ + +prototypes:: + int (*create) (struct inode *,struct dentry *,umode_t, bool); struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); int (*link) (struct dentry *,struct inode *,struct dentry *); @@ -68,7 +83,10 @@ prototypes: locking rules: all may block - i_rwsem(inode) + +============ ============================================= +ops i_rwsem(inode) +============ ============================================= lookup: shared create: exclusive link: exclusive (both) @@ -89,17 +107,21 @@ fiemap: no update_time: no atomic_open: exclusive tmpfile: no +============ ============================================= Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem exclusive on victim. cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem. -See Documentation/filesystems/directory-locking for more detailed discussion +See Documentation/filesystems/directory-locking.rst for more detailed discussion of the locking scheme for directory operations. ------------------------ xattr_handler operations ----------------------- -prototypes: +xattr_handler operations +======================== + +prototypes:: + bool (*list)(struct dentry *dentry); int (*get)(const struct xattr_handler *handler, struct dentry *dentry, struct inode *inode, const char *name, void *buffer, @@ -110,13 +132,20 @@ prototypes: locking rules: all may block - i_rwsem(inode) + +===== ============== +ops i_rwsem(inode) +===== ============== list: no get: no set: exclusive +===== ============== + +super_operations +================ + +prototypes:: ---------------------------- super_operations --------------------------- -prototypes: struct inode *(*alloc_inode)(struct super_block *sb); void (*free_inode)(struct inode *); void (*destroy_inode)(struct inode *); @@ -138,7 +167,10 @@ prototypes: locking rules: All may block [not true, see below] - s_umount + +====================== ============ ======================== +ops s_umount note +====================== ============ ======================== alloc_inode: free_inode: called from RCU callback destroy_inode: @@ -157,6 +189,7 @@ show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) bdev_try_to_free_page: no (see below) +====================== ============ ======================== ->statfs() has s_umount (shared) when called by ustat(2) (native or compat), but that's an accident of bad API; s_umount is used to pin @@ -164,31 +197,44 @@ the superblock down when we only have dev_t given us by userland to identify the superblock. Everything else (statfs(), fstatfs(), etc.) doesn't hold it when calling ->statfs() - superblock is pinned down by resolving the pathname passed to syscall. + ->quota_read() and ->quota_write() functions are both guaranteed to be the only ones operating on the quota file by the quota code (via dqio_sem) (unless an admin really wants to screw up something and writes to quota files with quotas on). For other details about locking see also dquot_operations section. + ->bdev_try_to_free_page is called from the ->releasepage handler of the block device inode. See there for more details. ---------------------------- file_system_type --------------------------- -prototypes: +file_system_type +================ + +prototypes:: + struct dentry *(*mount) (struct file_system_type *, int, const char *, void *); void (*kill_sb) (struct super_block *); + locking rules: - may block + +======= ========= +ops may block +======= ========= mount yes kill_sb yes +======= ========= ->mount() returns ERR_PTR or the root dentry; its superblock should be locked on return. + ->kill_sb() takes a write-locked superblock, does all shutdown work on it, unlocks and drops the reference. ---------------------------- address_space_operations -------------------------- -prototypes: +address_space_operations +======================== +prototypes:: + int (*writepage)(struct page *page, struct writeback_control *wbc); int (*readpage)(struct file *, struct page *); int (*writepages)(struct address_space *, struct writeback_control *); @@ -218,14 +264,16 @@ prototypes: locking rules: All except set_page_dirty and freepage may block - PageLocked(page) i_rwsem +====================== ======================== ========= +ops PageLocked(page) i_rwsem +====================== ======================== ========= writepage: yes, unlocks (see below) readpage: yes, unlocks writepages: set_page_dirty no readpages: -write_begin: locks the page exclusive -write_end: yes, unlocks exclusive +write_begin: locks the page exclusive +write_end: yes, unlocks exclusive bmap: invalidatepage: yes releasepage: yes @@ -239,17 +287,18 @@ is_partially_uptodate: yes error_remove_page: yes swap_activate: no swap_deactivate: no +====================== ======================== ========= - ->write_begin(), ->write_end() and ->readpage() may be called from +->write_begin(), ->write_end() and ->readpage() may be called from the request handler (/dev/loop). - ->readpage() unlocks the page, either synchronously or via I/O +->readpage() unlocks the page, either synchronously or via I/O completion. - ->readpages() populates the pagecache with the passed pages and starts +->readpages() populates the pagecache with the passed pages and starts I/O against them. They come unlocked upon I/O completion. - ->writepage() is used for two purposes: for "memory cleansing" and for +->writepage() is used for two purposes: for "memory cleansing" and for "sync". These are quite different operations and the behaviour may differ depending upon the mode. @@ -297,70 +346,81 @@ will leave the page itself marked clean but it will be tagged as dirty in the radix tree. This incoherency can lead to all sorts of hard-to-debug problems in the filesystem like having dirty inodes at umount and losing written data. - ->writepages() is used for periodic writeback and for syscall-initiated +->writepages() is used for periodic writeback and for syscall-initiated sync operations. The address_space should start I/O against at least -*nr_to_write pages. *nr_to_write must be decremented for each page which is -written. The address_space implementation may write more (or less) pages -than *nr_to_write asks for, but it should try to be reasonably close. If -nr_to_write is NULL, all dirty pages must be written. +``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page +which is written. The address_space implementation may write more (or less) +pages than ``*nr_to_write`` asks for, but it should try to be reasonably close. +If nr_to_write is NULL, all dirty pages must be written. writepages should _only_ write pages which are present on mapping->io_pages. - ->set_page_dirty() is called from various places in the kernel +->set_page_dirty() is called from various places in the kernel when the target page is marked as needing writeback. It may be called under spinlock (it cannot block) and is sometimes called with the page not locked. - ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some +->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some filesystems and by the swapper. The latter will eventually go away. Please, keep it that way and don't breed new callers. - ->invalidatepage() is called when the filesystem must attempt to drop +->invalidatepage() is called when the filesystem must attempt to drop some or all of the buffers from the page when it is being truncated. It returns zero on success. If ->invalidatepage is zero, the kernel uses block_invalidatepage() instead. - ->releasepage() is called when the kernel is about to try to drop the +->releasepage() is called when the kernel is about to try to drop the buffers from the page in preparation for freeing it. It returns zero to indicate that the buffers are (or may be) freeable. If ->releasepage is zero, the kernel assumes that the fs has no private interest in the buffers. - ->freepage() is called when the kernel is done dropping the page +->freepage() is called when the kernel is done dropping the page from the page cache. - ->launder_page() may be called prior to releasing a page if +->launder_page() may be called prior to releasing a page if it is still found to be dirty. It returns zero if the page was successfully cleaned, or an error value if not. Note that in order to prevent the page getting mapped back in and redirtied, it needs to be kept locked across the entire operation. - ->swap_activate will be called with a non-zero argument on +->swap_activate will be called with a non-zero argument on files backing (non block device backed) swapfiles. A return value of zero indicates success, in which case this file can be used for backing swapspace. The swapspace operations will be proxied to the address space operations. - ->swap_deactivate() will be called in the sys_swapoff() +->swap_deactivate() will be called in the sys_swapoff() path after ->swap_activate() returned success. ------------------------ file_lock_operations ------------------------------ -prototypes: +file_lock_operations +==================== + +prototypes:: + void (*fl_copy_lock)(struct file_lock *, struct file_lock *); void (*fl_release_private)(struct file_lock *); locking rules: - inode->i_lock may block + +=================== ============= ========= +ops inode->i_lock may block +=================== ============= ========= fl_copy_lock: yes no -fl_release_private: maybe maybe[1] +fl_release_private: maybe maybe[1]_ +=================== ============= ========= -[1]: ->fl_release_private for flock or POSIX locks is currently allowed -to block. Leases however can still be freed while the i_lock is held and -so fl_release_private called on a lease should not block. +.. [1]: + ->fl_release_private for flock or POSIX locks is currently allowed + to block. Leases however can still be freed while the i_lock is held and + so fl_release_private called on a lease should not block. + +lock_manager_operations +======================= + +prototypes:: ------------------------ lock_manager_operations --------------------------- -prototypes: void (*lm_notify)(struct file_lock *); /* unblock callback */ int (*lm_grant)(struct file_lock *, struct file_lock *, int); void (*lm_break)(struct file_lock *); /* break_lease callback */ @@ -368,24 +428,33 @@ prototypes: locking rules: - inode->i_lock blocked_lock_lock may block +========== ============= ================= ========= +ops inode->i_lock blocked_lock_lock may block +========== ============= ================= ========= lm_notify: yes yes no lm_grant: no no no lm_break: yes no no lm_change yes no no +========== ============= ================= ========= + +buffer_head +=========== + +prototypes:: ---------------------------- buffer_head ----------------------------------- -prototypes: void (*b_end_io)(struct buffer_head *bh, int uptodate); locking rules: - called from interrupts. In other words, extreme care is needed here. + +called from interrupts. In other words, extreme care is needed here. bh is locked, but that's all warranties we have here. Currently only RAID1, highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices call this method upon the IO completion. ---------------------------- block_device_operations ----------------------- -prototypes: +block_device_operations +======================= +prototypes:: + int (*open) (struct block_device *, fmode_t); int (*release) (struct gendisk *, fmode_t); int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); @@ -399,7 +468,10 @@ prototypes: void (*swap_slot_free_notify) (struct block_device *, unsigned long); locking rules: - bd_mutex + +======================= =================== +ops bd_mutex +======================= =================== open: yes release: yes ioctl: no @@ -410,6 +482,7 @@ unlock_native_capacity: no revalidate_disk: no getgeo: no swap_slot_free_notify: no (see below) +======================= =================== media_changed, unlock_native_capacity and revalidate_disk are called only from check_disk_change(). @@ -418,8 +491,11 @@ swap_slot_free_notify is called with swap_lock and sometimes the page lock held. ---------------------------- file_operations ------------------------------- -prototypes: +file_operations +=============== + +prototypes:: + loff_t (*llseek) (struct file *, loff_t, int); ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); @@ -455,7 +531,6 @@ prototypes: size_t, unsigned int); int (*setlease)(struct file *, long, struct file_lock **, void **); long (*fallocate)(struct file *, int, loff_t, loff_t); -}; locking rules: All may block. @@ -490,8 +565,11 @@ in sys_read() and friends. the lease within the individual filesystem to record the result of the operation ---------------------------- dquot_operations ------------------------------- -prototypes: +dquot_operations +================ + +prototypes:: + int (*write_dquot) (struct dquot *); int (*acquire_dquot) (struct dquot *); int (*release_dquot) (struct dquot *); @@ -503,20 +581,26 @@ a proper locking wrt the filesystem and call the generic quota operations. What filesystem should expect from the generic quota functions: - FS recursion Held locks when called +============== ============ ========================= +ops FS recursion Held locks when called +============== ============ ========================= write_dquot: yes dqonoff_sem or dqptr_sem acquire_dquot: yes dqonoff_sem or dqptr_sem release_dquot: yes dqonoff_sem or dqptr_sem mark_dirty: no - write_info: yes dqonoff_sem +============== ============ ========================= FS recursion means calling ->quota_read() and ->quota_write() from superblock operations. More details about quota locking can be found in fs/dquot.c. ---------------------------- vm_operations_struct ----------------------------- -prototypes: +vm_operations_struct +==================== + +prototypes:: + void (*open)(struct vm_area_struct*); void (*close)(struct vm_area_struct*); vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *); @@ -525,7 +609,10 @@ prototypes: int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); locking rules: - mmap_sem PageLocked(page) + +============= ======== =========================== +ops mmap_sem PageLocked(page) +============= ======== =========================== open: yes close: yes fault: yes can return with page locked @@ -533,8 +620,9 @@ map_pages: yes page_mkwrite: yes can return with page locked pfn_mkwrite: yes access: yes +============= ======== =========================== - ->fault() is called when a previously not present pte is about +->fault() is called when a previously not present pte is about to be faulted in. The filesystem must find and return the page associated with the passed in "pgoff" in the vm_fault structure. If it is possible that the page may be truncated and/or invalidated, then the filesystem must lock @@ -542,7 +630,7 @@ the page, then ensure it is not already truncated (the page lock will block subsequent truncate), and then return with VM_FAULT_LOCKED, and the page locked. The VM will unlock the page. - ->map_pages() is called when VM asks to map easy accessible pages. +->map_pages() is called when VM asks to map easy accessible pages. Filesystem should find and map pages associated with offsets from "start_pgoff" till "end_pgoff". ->map_pages() is called with page table locked and must not block. If it's not possible to reach a page without blocking, @@ -551,25 +639,26 @@ page table entry. Pointer to entry associated with the page is passed in "pte" field in vm_fault structure. Pointers to entries for other offsets should be calculated relative to "pte". - ->page_mkwrite() is called when a previously read-only pte is +->page_mkwrite() is called when a previously read-only pte is about to become writeable. The filesystem again must ensure that there are no truncate/invalidate races, and then return with the page locked. If the page has been truncated, the filesystem should not look up a new page like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which will cause the VM to retry the fault. - ->pfn_mkwrite() is the same as page_mkwrite but when the pte is +->pfn_mkwrite() is the same as page_mkwrite but when the pte is VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior after this call is to make the pte read-write, unless pfn_mkwrite returns an error. - ->access() is called when get_user_pages() fails in +->access() is called when get_user_pages() fails in access_process_vm(), typically used to debug a process through /proc/pid/mem or ptrace. This function is needed only for VM_IO | VM_PFNMAP VMAs. -================================================================================ +-------------------------------------------------------------------------------- + Dubious stuff (if you break something or notice that it is broken and do not fix it yourself diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/exporting.rst similarity index 91% rename from Documentation/filesystems/nfs/Exporting rename to Documentation/filesystems/nfs/exporting.rst index 63889149f532..33d588a01ace 100644 --- a/Documentation/filesystems/nfs/Exporting +++ b/Documentation/filesystems/nfs/exporting.rst @@ -1,3 +1,4 @@ +:orphan: Making Filesystems Exportable ============================= @@ -42,9 +43,9 @@ filehandle fragment, there is no automatic creation of a path prefix for the object. This leads to two related but distinct features of the dcache that are not needed for normal filesystem access. -1/ The dcache must sometimes contain objects that are not part of the +1. The dcache must sometimes contain objects that are not part of the proper prefix. i.e that are not connected to the root. -2/ The dcache must be prepared for a newly found (via ->lookup) directory +2. The dcache must be prepared for a newly found (via ->lookup) directory to already have a (non-connected) dentry, and must be able to move that dentry into place (based on the parent and name in the ->lookup). This is particularly needed for directories as @@ -52,7 +53,7 @@ the dcache that are not needed for normal filesystem access. To implement these features, the dcache has: -a/ A dentry flag DCACHE_DISCONNECTED which is set on +a. A dentry flag DCACHE_DISCONNECTED which is set on any dentry that might not be part of the proper prefix. This is set when anonymous dentries are created, and cleared when a dentry is noticed to be a child of a dentry which is in the proper @@ -71,48 +72,52 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on dentries. That guarantees that we won't need to hunt them down upon umount. -b/ A primitive for creation of secondary roots - d_obtain_root(inode). +b. A primitive for creation of secondary roots - d_obtain_root(inode). Those do _not_ bear DCACHE_DISCONNECTED. They are placed on the per-superblock list (->s_roots), so they can be located at umount time for eviction purposes. -c/ Helper routines to allocate anonymous dentries, and to help attach +c. Helper routines to allocate anonymous dentries, and to help attach loose directory dentries at lookup time. They are: + d_obtain_alias(inode) will return a dentry for the given inode. If the inode already has a dentry, one of those is returned. + If it doesn't, a new anonymous (IS_ROOT and - DCACHE_DISCONNECTED) dentry is allocated and attached. + DCACHE_DISCONNECTED) dentry is allocated and attached. + In the case of a directory, care is taken that only one dentry can ever be attached. + d_splice_alias(inode, dentry) will introduce a new dentry into the tree; either the passed-in dentry or a preexisting alias for the given inode (such as an anonymous one created by d_obtain_alias), if appropriate. It returns NULL when the passed-in dentry is used, following the calling convention of ->lookup. - + Filesystem Issues ----------------- For a filesystem to be exportable it must: - - 1/ provide the filehandle fragment routines described below. - 2/ make sure that d_splice_alias is used rather than d_add + + 1. provide the filehandle fragment routines described below. + 2. make sure that d_splice_alias is used rather than d_add when ->lookup finds an inode for a given parent and name. - If inode is NULL, d_splice_alias(inode, dentry) is equivalent to + If inode is NULL, d_splice_alias(inode, dentry) is equivalent to:: d_add(dentry, inode), NULL Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err) - Typically the ->lookup routine will simply end with a: + Typically the ->lookup routine will simply end with a:: return d_splice_alias(inode, dentry); } - A file system implementation declares that instances of the filesystem +A file system implementation declares that instances of the filesystem are exportable by setting the s_export_op field in the struct super_block. This field must point to a "struct export_operations" struct which has the following members: diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst index 0f85ab21c2ca..7d4d09dd5e6d 100644 --- a/Documentation/filesystems/vfs.rst +++ b/Documentation/filesystems/vfs.rst @@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist. VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on are called from a process context. Filesystem locking is described in -the document Documentation/filesystems/Locking. +the document Documentation/filesystems/locking.rst. Directory Entry Cache (dcache) diff --git a/fs/cifs/export.c b/fs/cifs/export.c index ce8b7f677c58..eb0bb8ca8e63 100644 --- a/fs/cifs/export.c +++ b/fs/cifs/export.c @@ -24,7 +24,7 @@ */ /* - * See Documentation/filesystems/nfs/Exporting + * See Documentation/filesystems/nfs/exporting.rst * and examples in fs/exportfs * * Since cifs is a network file system, an "fsid" must be included for diff --git a/fs/exportfs/expfs.c b/fs/exportfs/expfs.c index f0e549783caf..09bc68708d28 100644 --- a/fs/exportfs/expfs.c +++ b/fs/exportfs/expfs.c @@ -7,7 +7,7 @@ * and for mapping back from file handles to dentries. * * For details on why we do all the strange and hairy things in here - * take a look at Documentation/filesystems/nfs/Exporting. + * take a look at Documentation/filesystems/nfs/exporting.rst. */ #include #include diff --git a/fs/isofs/export.c b/fs/isofs/export.c index 85a9093769a9..35768a63fb1d 100644 --- a/fs/isofs/export.c +++ b/fs/isofs/export.c @@ -10,7 +10,7 @@ * * The following files are helpful: * - * Documentation/filesystems/nfs/Exporting + * Documentation/filesystems/nfs/exporting.rst * fs/exportfs/expfs.c. */ diff --git a/fs/orangefs/file.c b/fs/orangefs/file.c index 960f9a3c012d..a5612abc0936 100644 --- a/fs/orangefs/file.c +++ b/fs/orangefs/file.c @@ -555,7 +555,7 @@ static int orangefs_fsync(struct file *file, * Change the file pointer position for an instance of an open file. * * \note If .llseek is overriden, we must acquire lock as described in - * Documentation/filesystems/Locking. + * Documentation/filesystems/locking.rst. * * Future upgrade could support SEEK_DATA and SEEK_HOLE but would * require much changes to the FS diff --git a/include/linux/dcache.h b/include/linux/dcache.h index 9451011ac014..10090f11ab95 100644 --- a/include/linux/dcache.h +++ b/include/linux/dcache.h @@ -151,7 +151,7 @@ struct dentry_operations { /* * Locking rules for dentry_operations callbacks are to be found in - * Documentation/filesystems/Locking. Keep it updated! + * Documentation/filesystems/locking.rst. Keep it updated! * * FUrther descriptions are found in Documentation/filesystems/vfs.rst. * Keep it updated too! diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h index 0d3037419bc7..cf6571fc9c01 100644 --- a/include/linux/exportfs.h +++ b/include/linux/exportfs.h @@ -139,7 +139,7 @@ struct fid { * @get_parent: find the parent of a given directory * @commit_metadata: commit metadata changes to stable storage * - * See Documentation/filesystems/nfs/Exporting for details on how to use + * See Documentation/filesystems/nfs/exporting.rst for details on how to use * this interface correctly. * * encode_fh: From 25b532cec59ee119bf1c4081fe06fac43722f61f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:28 -0300 Subject: [PATCH 29/67] docs: fs: convert porting to ReST This file has its own proper style, except that, after a while, the coding style gets violated and whitespaces are placed on different ways. As Sphinx and ReST are very sentitive to whitespace differences, I had to opt if each entry after required/mandatory/... fields should start with zero spaces or with a tab. I opted to start them all from the zero position, in order to avoid needing to break lines with more than 80 columns, with would make harder for review. Most of the other changes at porting.rst were made to use an unified notation with works nice as a text file while also produce a good html output after being parsed. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/filesystems/index.rst | 2 + Documentation/filesystems/porting | 686 --------------------- Documentation/filesystems/porting.rst | 852 ++++++++++++++++++++++++++ fs/orangefs/orangefs-kernel.h | 2 +- 4 files changed, 855 insertions(+), 687 deletions(-) delete mode 100644 Documentation/filesystems/porting create mode 100644 Documentation/filesystems/porting.rst diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 08320c35d03b..96653ebefd7e 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -23,6 +23,8 @@ algorithms work. locking directory-locking + porting + Filesystem support layers ========================= diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting deleted file mode 100644 index 6b7a41cfcaed..000000000000 --- a/Documentation/filesystems/porting +++ /dev/null @@ -1,686 +0,0 @@ -Changes since 2.5.0: - ---- -[recommended] - -New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(), - sb_set_blocksize() and sb_min_blocksize(). - -Use them. - -(sb_find_get_block() replaces 2.4's get_hash_table()) - ---- -[recommended] - -New methods: ->alloc_inode() and ->destroy_inode(). - -Remove inode->u.foo_inode_i -Declare - struct foo_inode_info { - /* fs-private stuff */ - struct inode vfs_inode; - }; - static inline struct foo_inode_info *FOO_I(struct inode *inode) - { - return list_entry(inode, struct foo_inode_info, vfs_inode); - } - -Use FOO_I(inode) instead of &inode->u.foo_inode_i; - -Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate -foo_inode_info and return the address of ->vfs_inode, the latter should free -FOO_I(inode) (see in-tree filesystems for examples). - -Make them ->alloc_inode and ->destroy_inode in your super_operations. - -Keep in mind that now you need explicit initialization of private data -typically between calling iget_locked() and unlocking the inode. - -At some point that will become mandatory. - ---- -[mandatory] - -Change of file_system_type method (->read_super to ->get_sb) - -->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV. - -Turn your foo_read_super() into a function that would return 0 in case of -success and negative number in case of error (-EINVAL unless you have more -informative error value to report). Call it foo_fill_super(). Now declare - -int foo_get_sb(struct file_system_type *fs_type, - int flags, const char *dev_name, void *data, struct vfsmount *mnt) -{ - return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super, - mnt); -} - -(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of -filesystem). - -Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as -foo_get_sb. - ---- -[mandatory] - -Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames. -Most likely there is no need to change anything, but if you relied on -global exclusion between renames for some internal purpose - you need to -change your internal locking. Otherwise exclusion warranties remain the -same (i.e. parents and victim are locked, etc.). - ---- -[informational] - -Now we have the exclusion between ->lookup() and directory removal (by -->rmdir() and ->rename()). If you used to need that exclusion and do -it by internal locking (most of filesystems couldn't care less) - you -can relax your locking. - ---- -[mandatory] - -->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(), -->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename() -and ->readdir() are called without BKL now. Grab it on entry, drop upon return -- that will guarantee the same locking you used to have. If your method or its -parts do not need BKL - better yet, now you can shift lock_kernel() and -unlock_kernel() so that they would protect exactly what needs to be -protected. - ---- -[mandatory] - -BKL is also moved from around sb operations. BKL should have been shifted into -individual fs sb_op functions. If you don't need it, remove it. - ---- -[informational] - -check for ->link() target not being a directory is done by callers. Feel -free to drop it... - ---- -[informational] - -->link() callers hold ->i_mutex on the object we are linking to. Some of your -problems might be over... - ---- -[mandatory] - -new file_system_type method - kill_sb(superblock). If you are converting -an existing filesystem, set it according to ->fs_flags: - FS_REQUIRES_DEV - kill_block_super - FS_LITTER - kill_litter_super - neither - kill_anon_super -FS_LITTER is gone - just remove it from fs_flags. - ---- -[mandatory] - - FS_SINGLE is gone (actually, that had happened back when ->get_sb() -went in - and hadn't been documented ;-/). Just remove it from fs_flags -(and see ->get_sb() entry for other actions). - ---- -[mandatory] - -->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so -watch for ->i_mutex-grabbing code that might be used by your ->setattr(). -Callers of notify_change() need ->i_mutex now. - ---- -[recommended] - -New super_block field "struct export_operations *s_export_op" for -explicit support for exporting, e.g. via NFS. The structure is fully -documented at its declaration in include/linux/fs.h, and in -Documentation/filesystems/nfs/Exporting. - -Briefly it allows for the definition of decode_fh and encode_fh operations -to encode and decode filehandles, and allows the filesystem to use -a standard helper function for decode_fh, and provide file-system specific -support for this helper, particularly get_parent. - -It is planned that this will be required for exporting once the code -settles down a bit. - -[mandatory] - -s_export_op is now required for exporting a filesystem. -isofs, ext2, ext3, resierfs, fat -can be used as examples of very different filesystems. - ---- -[mandatory] - -iget4() and the read_inode2 callback have been superseded by iget5_locked() -which has the following prototype, - - struct inode *iget5_locked(struct super_block *sb, unsigned long ino, - int (*test)(struct inode *, void *), - int (*set)(struct inode *, void *), - void *data); - -'test' is an additional function that can be used when the inode -number is not sufficient to identify the actual file object. 'set' -should be a non-blocking function that initializes those parts of a -newly created inode to allow the test function to succeed. 'data' is -passed as an opaque value to both test and set functions. - -When the inode has been created by iget5_locked(), it will be returned with the -I_NEW flag set and will still be locked. The filesystem then needs to finalize -the initialization. Once the inode is initialized it must be unlocked by -calling unlock_new_inode(). - -The filesystem is responsible for setting (and possibly testing) i_ino -when appropriate. There is also a simpler iget_locked function that -just takes the superblock and inode number as arguments and does the -test and set for you. - -e.g. - inode = iget_locked(sb, ino); - if (inode->i_state & I_NEW) { - err = read_inode_from_disk(inode); - if (err < 0) { - iget_failed(inode); - return err; - } - unlock_new_inode(inode); - } - -Note that if the process of setting up a new inode fails, then iget_failed() -should be called on the inode to render it dead, and an appropriate error -should be passed back to the caller. - ---- -[recommended] - -->getattr() finally getting used. See instances in nfs, minix, etc. - ---- -[mandatory] - -->revalidate() is gone. If your filesystem had it - provide ->getattr() -and let it call whatever you had as ->revlidate() + (for symlinks that -had ->revalidate()) add calls in ->follow_link()/->readlink(). - ---- -[mandatory] - -->d_parent changes are not protected by BKL anymore. Read access is safe -if at least one of the following is true: - * filesystem has no cross-directory rename() - * we know that parent had been locked (e.g. we are looking at -->d_parent of ->lookup() argument). - * we are called from ->rename(). - * the child's ->d_lock is held -Audit your code and add locking if needed. Notice that any place that is -not protected by the conditions above is risky even in the old tree - you -had been relying on BKL and that's prone to screwups. Old tree had quite -a few holes of that kind - unprotected access to ->d_parent leading to -anything from oops to silent memory corruption. - ---- -[mandatory] - - FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags -(see rootfs for one kind of solution and bdev/socket/pipe for another). - ---- -[recommended] - - Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter -is still alive, but only because of the mess in drivers/s390/block/dasd.c. -As soon as it gets fixed is_read_only() will die. - ---- -[mandatory] - -->permission() is called without BKL now. Grab it on entry, drop upon -return - that will guarantee the same locking you used to have. If -your method or its parts do not need BKL - better yet, now you can -shift lock_kernel() and unlock_kernel() so that they would protect -exactly what needs to be protected. - ---- -[mandatory] - -->statfs() is now called without BKL held. BKL should have been -shifted into individual fs sb_op functions where it's not clear that -it's safe to remove it. If you don't need it, remove it. - ---- -[mandatory] - - is_read_only() is gone; use bdev_read_only() instead. - ---- -[mandatory] - - destroy_buffers() is gone; use invalidate_bdev(). - ---- -[mandatory] - - fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is -deliberate; as soon as struct block_device * is propagated in a reasonable -way by that code fixing will become trivial; until then nothing can be -done. - -[mandatory] - - block truncatation on error exit from ->write_begin, and ->direct_IO -moved from generic methods (block_write_begin, cont_write_begin, -nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at -ext2_write_failed and callers for an example. - -[mandatory] - - ->truncate is gone. The whole truncate sequence needs to be -implemented in ->setattr, which is now mandatory for filesystems -implementing on-disk size changes. Start with a copy of the old inode_setattr -and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to -be in order of zeroing blocks using block_truncate_page or similar helpers, -size update and on finally on-disk truncation which should not fail. -setattr_prepare (which used to be inode_change_ok) now includes the size checks -for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally. - -[mandatory] - - ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should -be used instead. It gets called whenever the inode is evicted, whether it has -remaining links or not. Caller does *not* evict the pagecache or inode-associated -metadata buffers; the method has to use truncate_inode_pages_final() to get rid -of those. Caller makes sure async writeback cannot be running for the inode while -(or after) ->evict_inode() is called. - - ->drop_inode() returns int now; it's called on final iput() with -inode->i_lock held and it returns true if filesystems wants the inode to be -dropped. As before, generic_drop_inode() is still the default and it's been -updated appropriately. generic_delete_inode() is also alive and it consists -simply of return 1. Note that all actual eviction work is done by caller after -->drop_inode() returns. - - As before, clear_inode() must be called exactly once on each call of -->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike -before, if you are using inode-associated metadata buffers (i.e. -mark_buffer_dirty_inode()), it's your responsibility to call -invalidate_inode_buffers() before clear_inode(). - - NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out -if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput() -may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly -free the on-disk inode, you may end up doing that while ->write_inode() is writing -to it. - ---- -[mandatory] - - .d_delete() now only advises the dcache as to whether or not to cache -unreferenced dentries, and is now only called when the dentry refcount goes to -0. Even on 0 refcount transition, it must be able to tolerate being called 0, -1, or more times (eg. constant, idempotent). - ---- -[mandatory] - - .d_compare() calling convention and locking rules are significantly -changed. Read updated documentation in Documentation/filesystems/vfs.rst (and -look at examples of other filesystems) for guidance. - ---- -[mandatory] - - .d_hash() calling convention and locking rules are significantly -changed. Read updated documentation in Documentation/filesystems/vfs.rst (and -look at examples of other filesystems) for guidance. - ---- -[mandatory] - dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c -for details of what locks to replace dcache_lock with in order to protect -particular things. Most of the time, a filesystem only needs ->d_lock, which -protects *all* the dcache state of a given dentry. - --- -[mandatory] - - Filesystems must RCU-free their inodes, if they can have been accessed -via rcu-walk path walk (basically, if the file can have had a path name in the -vfs namespace). - - Even though i_dentry and i_rcu share storage in a union, we will -initialize the former in inode_init_always(), so just leave it alone in -the callback. It used to be necessary to clean it there, but not anymore -(starting at 3.2). - --- -[recommended] - vfs now tries to do path walking in "rcu-walk mode", which avoids -atomic operations and scalability hazards on dentries and inodes (see -Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes -(above) are examples of the changes required to support this. For more complex -filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so -no changes are required to the filesystem. However, this is costly and loses -the benefits of rcu-walk mode. We will begin to add filesystem callbacks that -are rcu-walk aware, shown below. Filesystems should take advantage of this -where possible. - --- -[mandatory] - d_revalidate is a callback that is made on every path element (if -the filesystem provides it), which requires dropping out of rcu-walk mode. This -may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be -returned if the filesystem cannot handle rcu-walk. See -Documentation/filesystems/vfs.rst for more details. - - permission is an inode permission check that is called on many or all -directory inodes on the way down a path walk (to check for exec permission). It -must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See -Documentation/filesystems/vfs.rst for more details. - --- -[mandatory] - In ->fallocate() you must check the mode option passed in. If your -filesystem does not support hole punching (deallocating space in the middle of a -file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode. -Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set, -so the i_size should not change when hole punching, even when puching the end of -a file off. - --- -[mandatory] - ->get_sb() is gone. Switch to use of ->mount(). Typically it's just -a matter of switching from calling get_sb_... to mount_... and changing the -function type. If you were doing it manually, just switch from setting ->mnt_root -to some pointer to returning that pointer. On errors return ERR_PTR(...). - --- -[mandatory] - ->permission() and generic_permission()have lost flags -argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask. - generic_permission() has also lost the check_acl argument; ACL checking -has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl -to read an ACL from disk. - --- -[mandatory] - If you implement your own ->llseek() you must handle SEEK_HOLE and -SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to -support it in some way. The generic handler assumes that the entire file is -data and there is a virtual hole at the end of the file. So if the provided -offset is less than i_size and SEEK_DATA is specified, return the same offset. -If the above is true for the offset and you are given SEEK_HOLE, return the end -of the file. If the offset is i_size or greater return -ENXIO in either case. - -[mandatory] - If you have your own ->fsync() you must make sure to call -filemap_write_and_wait_range() so that all dirty pages are synced out properly. -You must also keep in mind that ->fsync() is not called with i_mutex held -anymore, so if you require i_mutex locking you must make sure to take it and -release it yourself. - --- -[mandatory] - d_alloc_root() is gone, along with a lot of bugs caused by code -misusing it. Replacement: d_make_root(inode). On success d_make_root(inode) -allocates and returns a new dentry instantiated with the passed in inode. -On failure NULL is returned and the passed in inode is dropped so the reference -to inode is consumed in all cases and failure handling need not do any cleanup -for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL -and also requires no further error handling. Typical usage is: - - inode = foofs_new_inode(....); - s->s_root = d_make_root(inode); - if (!s->s_root) - /* Nothing needed for the inode cleanup */ - return -ENOMEM; - ... - --- -[mandatory] - The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and -->lookup() do *not* take struct nameidata anymore; just the flags. --- -[mandatory] - ->create() doesn't take struct nameidata *; unlike the previous -two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that -local filesystems can ignore tha argument - they are guaranteed that the -object doesn't exist. It's remote/distributed ones that might care... --- -[mandatory] - FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate() -in your dentry operations instead. --- -[mandatory] - vfs_readdir() is gone; switch to iterate_dir() instead --- -[mandatory] - ->readdir() is gone now; switch to ->iterate() -[mandatory] - vfs_follow_link has been removed. Filesystems must use nd_set_link - from ->follow_link for normal symlinks, or nd_jump_link for magic - /proc/ style links. --- -[mandatory] - iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be - called with both ->i_lock and inode_hash_lock held; the former is *not* - taken anymore, so verify that your callbacks do not rely on it (none - of the in-tree instances did). inode_hash_lock is still held, - of course, so they are still serialized wrt removal from inode hash, - as well as wrt set() callback of iget5_locked(). --- -[mandatory] - d_materialise_unique() is gone; d_splice_alias() does everything you - need now. Remember that they have opposite orders of arguments ;-/ --- -[mandatory] - f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid - it entirely. --- -[mandatory] - never call ->read() and ->write() directly; use __vfs_{read,write} or - wrappers; instead of checking for ->write or ->read being NULL, look for - FMODE_CAN_{WRITE,READ} in file->f_mode. --- -[mandatory] - do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL - instead. --- -[mandatory] - ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter. ---- -[recommended] - for embedded ("fast") symlinks just set inode->i_link to wherever the - symlink body is and use simple_follow_link() as ->follow_link(). --- -[mandatory] - calling conventions for ->follow_link() have changed. Instead of returning - cookie and using nd_set_link() to store the body to traverse, we return - the body to traverse and store the cookie using explicit void ** argument. - nameidata isn't passed at all - nd_jump_link() doesn't need it and - nd_[gs]et_link() is gone. --- -[mandatory] - calling conventions for ->put_link() have changed. It gets inode instead of - dentry, it does not get nameidata at all and it gets called only when cookie - is non-NULL. Note that link body isn't available anymore, so if you need it, - store it as cookie. --- -[mandatory] - any symlink that might use page_follow_link_light/page_put_link() must - have inode_nohighmem(inode) called before anything might start playing with - its pagecache. No highmem pages should end up in the pagecache of such - symlinks. That includes any preseeding that might be done during symlink - creation. __page_symlink() will honour the mapping gfp flags, so once - you've done inode_nohighmem() it's safe to use, but if you allocate and - insert the page manually, make sure to use the right gfp flags. --- -[mandatory] - ->follow_link() is replaced with ->get_link(); same API, except that - * ->get_link() gets inode as a separate argument - * ->get_link() may be called in RCU mode - in that case NULL - dentry is passed --- -[mandatory] - ->get_link() gets struct delayed_call *done now, and should do - set_delayed_call() where it used to set *cookie. - ->put_link() is gone - just give the destructor to set_delayed_call() - in ->get_link(). --- -[mandatory] - ->getxattr() and xattr_handler.get() get dentry and inode passed separately. - dentry might be yet to be attached to inode, so do _not_ use its ->d_inode - in the instances. Rationale: !@#!@# security_d_instantiate() needs to be - called before we attach dentry to inode. --- -[mandatory] - symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/ - i_pipe/i_link union zeroed out at inode eviction. As the result, you can't - assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that - it's a symlink. Checking ->i_mode is really needed now. In-tree we had - to fix shmem_destroy_callback() that used to take that kind of shortcut; - watch out, since that shortcut is no longer valid. --- -[mandatory] - ->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as - they used to - they just take it exclusive. However, ->lookup() may be - called with parent locked shared. Its instances must not - * use d_instantiate) and d_rehash() separately - use d_add() or - d_splice_alias() instead. - * use d_rehash() alone - call d_add(new_dentry, NULL) instead. - * in the unlikely case when (read-only) access to filesystem - data structures needs exclusion for some reason, arrange it - yourself. None of the in-tree filesystems needed that. - * rely on ->d_parent and ->d_name not changing after dentry has - been fed to d_add() or d_splice_alias(). Again, none of the - in-tree instances relied upon that. - We are guaranteed that lookups of the same name in the same directory - will not happen in parallel ("same" in the sense of your ->d_compare()). - Lookups on different names in the same directory can and do happen in - parallel now. --- -[recommended] - ->iterate_shared() is added; it's a parallel variant of ->iterate(). - Exclusion on struct file level is still provided (as well as that - between it and lseek on the same struct file), but if your directory - has been opened several times, you can get these called in parallel. - Exclusion between that method and all directory-modifying ones is - still provided, of course. - - Often enough ->iterate() can serve as ->iterate_shared() without any - changes - it is a read-only operation, after all. If you have any - per-inode or per-dentry in-core data structures modified by ->iterate(), - you might need something to serialize the access to them. If you - do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for - that; look for in-tree examples. - - Old method is only used if the new one is absent; eventually it will - be removed. Switch while you still can; the old one won't stay. --- -[mandatory] - ->atomic_open() calls without O_CREAT may happen in parallel. --- -[mandatory] - ->setxattr() and xattr_handler.set() get dentry and inode passed separately. - dentry might be yet to be attached to inode, so do _not_ use its ->d_inode - in the instances. Rationale: !@#!@# security_d_instantiate() needs to be - called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack - ->d_instantiate() uses not just ->getxattr() but ->setxattr() as well. --- -[mandatory] - ->d_compare() doesn't get parent as a separate argument anymore. If you - used it for finding the struct super_block involved, dentry->d_sb will - work just as well; if it's something more complicated, use dentry->d_parent. - Just be careful not to assume that fetching it more than once will yield - the same value - in RCU mode it could change under you. --- -[mandatory] - ->rename() has an added flags argument. Any flags not handled by the - filesystem should result in EINVAL being returned. --- -[recommended] - ->readlink is optional for symlinks. Don't set, unless filesystem needs - to fake something for readlink(2). --- -[mandatory] - ->getattr() is now passed a struct path rather than a vfsmount and - dentry separately, and it now has request_mask and query_flags arguments - to specify the fields and sync type requested by statx. Filesystems not - supporting any statx-specific features may ignore the new arguments. --- -[mandatory] - ->atomic_open() calling conventions have changed. Gone is int *opened, - along with FILE_OPENED/FILE_CREATED. In place of those we have - FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return - value for 'called finish_no_open(), open it yourself' case has become - 0, not 1. Since finish_no_open() itself is returning 0 now, that part - does not need any changes in ->atomic_open() instances. --- -[mandatory] - alloc_file() has become static now; two wrappers are to be used instead. - alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases - when dentry needs to be created; that's the majority of old alloc_file() - users. Calling conventions: on success a reference to new struct file - is returned and callers reference to inode is subsumed by that. On - failure, ERR_PTR() is returned and no caller's references are affected, - so the caller needs to drop the inode reference it held. - alloc_file_clone(file, flags, ops) does not affect any caller's references. - On success you get a new struct file sharing the mount/dentry with the - original, on failure - ERR_PTR(). --- -[mandatory] - ->clone_file_range() and ->dedupe_file_range have been replaced with - ->remap_file_range(). See Documentation/filesystems/vfs.rst for more - information. --- -[recommended] - ->lookup() instances doing an equivalent of - if (IS_ERR(inode)) - return ERR_CAST(inode); - return d_splice_alias(inode, dentry); - don't need to bother with the check - d_splice_alias() will do the - right thing when given ERR_PTR(...) as inode. Moreover, passing NULL - inode to d_splice_alias() will also do the right thing (equivalent of - d_add(dentry, NULL); return NULL;), so that kind of special cases - also doesn't need a separate treatment. --- -[strongly recommended] - take the RCU-delayed parts of ->destroy_inode() into a new method - - ->free_inode(). If ->destroy_inode() becomes empty - all the better, - just get rid of it. Synchronous work (e.g. the stuff that can't - be done from an RCU callback, or any WARN_ON() where we want the - stack trace) *might* be movable to ->evict_inode(); however, - that goes only for the things that are not needed to balance something - done by ->alloc_inode(). IOW, if it's cleaning up the stuff that - might have accumulated over the life of in-core inode, ->evict_inode() - might be a fit. - - Rules for inode destruction: - * if ->destroy_inode() is non-NULL, it gets called - * if ->free_inode() is non-NULL, it gets scheduled by call_rcu() - * combination of NULL ->destroy_inode and NULL ->free_inode is - treated as NULL/free_inode_nonrcu, to preserve the compatibility. - - Note that the callback (be it via ->free_inode() or explicit call_rcu() - in ->destroy_inode()) is *NOT* ordered wrt superblock destruction; - as the matter of fact, the superblock and all associated structures - might be already gone. The filesystem driver is guaranteed to be still - there, but that's it. Freeing memory in the callback is fine; doing - more than that is possible, but requires a lot of care and is best - avoided. --- -[mandatory] - DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the - default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any - business doing so. --- -[mandatory] - d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are - very suspect (and won't work in modules). Such uses are very likely to - be misspelled d_alloc_anon(). diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst new file mode 100644 index 000000000000..66aa521e6376 --- /dev/null +++ b/Documentation/filesystems/porting.rst @@ -0,0 +1,852 @@ +==================== +Changes since 2.5.0: +==================== + +--- + +**recommended** + +New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(), +sb_set_blocksize() and sb_min_blocksize(). + +Use them. + +(sb_find_get_block() replaces 2.4's get_hash_table()) + +--- + +**recommended** + +New methods: ->alloc_inode() and ->destroy_inode(). + +Remove inode->u.foo_inode_i + +Declare:: + + struct foo_inode_info { + /* fs-private stuff */ + struct inode vfs_inode; + }; + static inline struct foo_inode_info *FOO_I(struct inode *inode) + { + return list_entry(inode, struct foo_inode_info, vfs_inode); + } + +Use FOO_I(inode) instead of &inode->u.foo_inode_i; + +Add foo_alloc_inode() and foo_destroy_inode() - the former should allocate +foo_inode_info and return the address of ->vfs_inode, the latter should free +FOO_I(inode) (see in-tree filesystems for examples). + +Make them ->alloc_inode and ->destroy_inode in your super_operations. + +Keep in mind that now you need explicit initialization of private data +typically between calling iget_locked() and unlocking the inode. + +At some point that will become mandatory. + +--- + +**mandatory** + +Change of file_system_type method (->read_super to ->get_sb) + +->read_super() is no more. Ditto for DECLARE_FSTYPE and DECLARE_FSTYPE_DEV. + +Turn your foo_read_super() into a function that would return 0 in case of +success and negative number in case of error (-EINVAL unless you have more +informative error value to report). Call it foo_fill_super(). Now declare:: + + int foo_get_sb(struct file_system_type *fs_type, + int flags, const char *dev_name, void *data, struct vfsmount *mnt) + { + return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super, + mnt); + } + +(or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of +filesystem). + +Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as +foo_get_sb. + +--- + +**mandatory** + +Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames. +Most likely there is no need to change anything, but if you relied on +global exclusion between renames for some internal purpose - you need to +change your internal locking. Otherwise exclusion warranties remain the +same (i.e. parents and victim are locked, etc.). + +--- + +**informational** + +Now we have the exclusion between ->lookup() and directory removal (by +->rmdir() and ->rename()). If you used to need that exclusion and do +it by internal locking (most of filesystems couldn't care less) - you +can relax your locking. + +--- + +**mandatory** + +->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(), +->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename() +and ->readdir() are called without BKL now. Grab it on entry, drop upon return +- that will guarantee the same locking you used to have. If your method or its +parts do not need BKL - better yet, now you can shift lock_kernel() and +unlock_kernel() so that they would protect exactly what needs to be +protected. + +--- + +**mandatory** + +BKL is also moved from around sb operations. BKL should have been shifted into +individual fs sb_op functions. If you don't need it, remove it. + +--- + +**informational** + +check for ->link() target not being a directory is done by callers. Feel +free to drop it... + +--- + +**informational** + +->link() callers hold ->i_mutex on the object we are linking to. Some of your +problems might be over... + +--- + +**mandatory** + +new file_system_type method - kill_sb(superblock). If you are converting +an existing filesystem, set it according to ->fs_flags:: + + FS_REQUIRES_DEV - kill_block_super + FS_LITTER - kill_litter_super + neither - kill_anon_super + +FS_LITTER is gone - just remove it from fs_flags. + +--- + +**mandatory** + +FS_SINGLE is gone (actually, that had happened back when ->get_sb() +went in - and hadn't been documented ;-/). Just remove it from fs_flags +(and see ->get_sb() entry for other actions). + +--- + +**mandatory** + +->setattr() is called without BKL now. Caller _always_ holds ->i_mutex, so +watch for ->i_mutex-grabbing code that might be used by your ->setattr(). +Callers of notify_change() need ->i_mutex now. + +--- + +**recommended** + +New super_block field ``struct export_operations *s_export_op`` for +explicit support for exporting, e.g. via NFS. The structure is fully +documented at its declaration in include/linux/fs.h, and in +Documentation/filesystems/nfs/Exporting. + +Briefly it allows for the definition of decode_fh and encode_fh operations +to encode and decode filehandles, and allows the filesystem to use +a standard helper function for decode_fh, and provide file-system specific +support for this helper, particularly get_parent. + +It is planned that this will be required for exporting once the code +settles down a bit. + +**mandatory** + +s_export_op is now required for exporting a filesystem. +isofs, ext2, ext3, resierfs, fat +can be used as examples of very different filesystems. + +--- + +**mandatory** + +iget4() and the read_inode2 callback have been superseded by iget5_locked() +which has the following prototype:: + + struct inode *iget5_locked(struct super_block *sb, unsigned long ino, + int (*test)(struct inode *, void *), + int (*set)(struct inode *, void *), + void *data); + +'test' is an additional function that can be used when the inode +number is not sufficient to identify the actual file object. 'set' +should be a non-blocking function that initializes those parts of a +newly created inode to allow the test function to succeed. 'data' is +passed as an opaque value to both test and set functions. + +When the inode has been created by iget5_locked(), it will be returned with the +I_NEW flag set and will still be locked. The filesystem then needs to finalize +the initialization. Once the inode is initialized it must be unlocked by +calling unlock_new_inode(). + +The filesystem is responsible for setting (and possibly testing) i_ino +when appropriate. There is also a simpler iget_locked function that +just takes the superblock and inode number as arguments and does the +test and set for you. + +e.g.:: + + inode = iget_locked(sb, ino); + if (inode->i_state & I_NEW) { + err = read_inode_from_disk(inode); + if (err < 0) { + iget_failed(inode); + return err; + } + unlock_new_inode(inode); + } + +Note that if the process of setting up a new inode fails, then iget_failed() +should be called on the inode to render it dead, and an appropriate error +should be passed back to the caller. + +--- + +**recommended** + +->getattr() finally getting used. See instances in nfs, minix, etc. + +--- + +**mandatory** + +->revalidate() is gone. If your filesystem had it - provide ->getattr() +and let it call whatever you had as ->revlidate() + (for symlinks that +had ->revalidate()) add calls in ->follow_link()/->readlink(). + +--- + +**mandatory** + +->d_parent changes are not protected by BKL anymore. Read access is safe +if at least one of the following is true: + + * filesystem has no cross-directory rename() + * we know that parent had been locked (e.g. we are looking at + ->d_parent of ->lookup() argument). + * we are called from ->rename(). + * the child's ->d_lock is held + +Audit your code and add locking if needed. Notice that any place that is +not protected by the conditions above is risky even in the old tree - you +had been relying on BKL and that's prone to screwups. Old tree had quite +a few holes of that kind - unprotected access to ->d_parent leading to +anything from oops to silent memory corruption. + +--- + +**mandatory** + +FS_NOMOUNT is gone. If you use it - just set SB_NOUSER in flags +(see rootfs for one kind of solution and bdev/socket/pipe for another). + +--- + +**recommended** + +Use bdev_read_only(bdev) instead of is_read_only(kdev). The latter +is still alive, but only because of the mess in drivers/s390/block/dasd.c. +As soon as it gets fixed is_read_only() will die. + +--- + +**mandatory** + +->permission() is called without BKL now. Grab it on entry, drop upon +return - that will guarantee the same locking you used to have. If +your method or its parts do not need BKL - better yet, now you can +shift lock_kernel() and unlock_kernel() so that they would protect +exactly what needs to be protected. + +--- + +**mandatory** + +->statfs() is now called without BKL held. BKL should have been +shifted into individual fs sb_op functions where it's not clear that +it's safe to remove it. If you don't need it, remove it. + +--- + +**mandatory** + +is_read_only() is gone; use bdev_read_only() instead. + +--- + +**mandatory** + +destroy_buffers() is gone; use invalidate_bdev(). + +--- + +**mandatory** + +fsync_dev() is gone; use fsync_bdev(). NOTE: lvm breakage is +deliberate; as soon as struct block_device * is propagated in a reasonable +way by that code fixing will become trivial; until then nothing can be +done. + +**mandatory** + +block truncatation on error exit from ->write_begin, and ->direct_IO +moved from generic methods (block_write_begin, cont_write_begin, +nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at +ext2_write_failed and callers for an example. + +**mandatory** + +->truncate is gone. The whole truncate sequence needs to be +implemented in ->setattr, which is now mandatory for filesystems +implementing on-disk size changes. Start with a copy of the old inode_setattr +and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to +be in order of zeroing blocks using block_truncate_page or similar helpers, +size update and on finally on-disk truncation which should not fail. +setattr_prepare (which used to be inode_change_ok) now includes the size checks +for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally. + +**mandatory** + +->clear_inode() and ->delete_inode() are gone; ->evict_inode() should +be used instead. It gets called whenever the inode is evicted, whether it has +remaining links or not. Caller does *not* evict the pagecache or inode-associated +metadata buffers; the method has to use truncate_inode_pages_final() to get rid +of those. Caller makes sure async writeback cannot be running for the inode while +(or after) ->evict_inode() is called. + +->drop_inode() returns int now; it's called on final iput() with +inode->i_lock held and it returns true if filesystems wants the inode to be +dropped. As before, generic_drop_inode() is still the default and it's been +updated appropriately. generic_delete_inode() is also alive and it consists +simply of return 1. Note that all actual eviction work is done by caller after +->drop_inode() returns. + +As before, clear_inode() must be called exactly once on each call of +->evict_inode() (as it used to be for each call of ->delete_inode()). Unlike +before, if you are using inode-associated metadata buffers (i.e. +mark_buffer_dirty_inode()), it's your responsibility to call +invalidate_inode_buffers() before clear_inode(). + +NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out +if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput() +may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly +free the on-disk inode, you may end up doing that while ->write_inode() is writing +to it. + +--- + +**mandatory** + +.d_delete() now only advises the dcache as to whether or not to cache +unreferenced dentries, and is now only called when the dentry refcount goes to +0. Even on 0 refcount transition, it must be able to tolerate being called 0, +1, or more times (eg. constant, idempotent). + +--- + +**mandatory** + +.d_compare() calling convention and locking rules are significantly +changed. Read updated documentation in Documentation/filesystems/vfs.rst (and +look at examples of other filesystems) for guidance. + +--- + +**mandatory** + +.d_hash() calling convention and locking rules are significantly +changed. Read updated documentation in Documentation/filesystems/vfs.rst (and +look at examples of other filesystems) for guidance. + +--- + +**mandatory** + +dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c +for details of what locks to replace dcache_lock with in order to protect +particular things. Most of the time, a filesystem only needs ->d_lock, which +protects *all* the dcache state of a given dentry. + +--- + +**mandatory** + +Filesystems must RCU-free their inodes, if they can have been accessed +via rcu-walk path walk (basically, if the file can have had a path name in the +vfs namespace). + +Even though i_dentry and i_rcu share storage in a union, we will +initialize the former in inode_init_always(), so just leave it alone in +the callback. It used to be necessary to clean it there, but not anymore +(starting at 3.2). + +--- + +**recommended** + +vfs now tries to do path walking in "rcu-walk mode", which avoids +atomic operations and scalability hazards on dentries and inodes (see +Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes +(above) are examples of the changes required to support this. For more complex +filesystem callbacks, the vfs drops out of rcu-walk mode before the fs call, so +no changes are required to the filesystem. However, this is costly and loses +the benefits of rcu-walk mode. We will begin to add filesystem callbacks that +are rcu-walk aware, shown below. Filesystems should take advantage of this +where possible. + +--- + +**mandatory** + +d_revalidate is a callback that is made on every path element (if +the filesystem provides it), which requires dropping out of rcu-walk mode. This +may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be +returned if the filesystem cannot handle rcu-walk. See +Documentation/filesystems/vfs.rst for more details. + +permission is an inode permission check that is called on many or all +directory inodes on the way down a path walk (to check for exec permission). It +must now be rcu-walk aware (mask & MAY_NOT_BLOCK). See +Documentation/filesystems/vfs.rst for more details. + +--- + +**mandatory** + +In ->fallocate() you must check the mode option passed in. If your +filesystem does not support hole punching (deallocating space in the middle of a +file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode. +Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set, +so the i_size should not change when hole punching, even when puching the end of +a file off. + +--- + +**mandatory** + +->get_sb() is gone. Switch to use of ->mount(). Typically it's just +a matter of switching from calling ``get_sb_``... to ``mount_``... and changing +the function type. If you were doing it manually, just switch from setting +->mnt_root to some pointer to returning that pointer. On errors return +ERR_PTR(...). + +--- + +**mandatory** + +->permission() and generic_permission()have lost flags +argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask. + +generic_permission() has also lost the check_acl argument; ACL checking +has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl +to read an ACL from disk. + +--- + +**mandatory** + +If you implement your own ->llseek() you must handle SEEK_HOLE and +SEEK_DATA. You can hanle this by returning -EINVAL, but it would be nicer to +support it in some way. The generic handler assumes that the entire file is +data and there is a virtual hole at the end of the file. So if the provided +offset is less than i_size and SEEK_DATA is specified, return the same offset. +If the above is true for the offset and you are given SEEK_HOLE, return the end +of the file. If the offset is i_size or greater return -ENXIO in either case. + +**mandatory** + +If you have your own ->fsync() you must make sure to call +filemap_write_and_wait_range() so that all dirty pages are synced out properly. +You must also keep in mind that ->fsync() is not called with i_mutex held +anymore, so if you require i_mutex locking you must make sure to take it and +release it yourself. + +--- + +**mandatory** + +d_alloc_root() is gone, along with a lot of bugs caused by code +misusing it. Replacement: d_make_root(inode). On success d_make_root(inode) +allocates and returns a new dentry instantiated with the passed in inode. +On failure NULL is returned and the passed in inode is dropped so the reference +to inode is consumed in all cases and failure handling need not do any cleanup +for the inode. If d_make_root(inode) is passed a NULL inode it returns NULL +and also requires no further error handling. Typical usage is:: + + inode = foofs_new_inode(....); + s->s_root = d_make_root(inode); + if (!s->s_root) + /* Nothing needed for the inode cleanup */ + return -ENOMEM; + ... + +--- + +**mandatory** + +The witch is dead! Well, 2/3 of it, anyway. ->d_revalidate() and +->lookup() do *not* take struct nameidata anymore; just the flags. + +--- + +**mandatory** + +->create() doesn't take ``struct nameidata *``; unlike the previous +two, it gets "is it an O_EXCL or equivalent?" boolean argument. Note that +local filesystems can ignore tha argument - they are guaranteed that the +object doesn't exist. It's remote/distributed ones that might care... + +--- + +**mandatory** + +FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate() +in your dentry operations instead. + +--- + +**mandatory** + +vfs_readdir() is gone; switch to iterate_dir() instead + +--- + +**mandatory** + +->readdir() is gone now; switch to ->iterate() + +**mandatory** + +vfs_follow_link has been removed. Filesystems must use nd_set_link +from ->follow_link for normal symlinks, or nd_jump_link for magic +/proc/ style links. + +--- + +**mandatory** + +iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be +called with both ->i_lock and inode_hash_lock held; the former is *not* +taken anymore, so verify that your callbacks do not rely on it (none +of the in-tree instances did). inode_hash_lock is still held, +of course, so they are still serialized wrt removal from inode hash, +as well as wrt set() callback of iget5_locked(). + +--- + +**mandatory** + +d_materialise_unique() is gone; d_splice_alias() does everything you +need now. Remember that they have opposite orders of arguments ;-/ + +--- + +**mandatory** + +f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid +it entirely. + +--- + +**mandatory** + +never call ->read() and ->write() directly; use __vfs_{read,write} or +wrappers; instead of checking for ->write or ->read being NULL, look for +FMODE_CAN_{WRITE,READ} in file->f_mode. + +--- + +**mandatory** + +do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL +instead. + +--- + +**mandatory** + ->aio_read/->aio_write are gone. Use ->read_iter/->write_iter. + +--- + +**recommended** + +for embedded ("fast") symlinks just set inode->i_link to wherever the +symlink body is and use simple_follow_link() as ->follow_link(). + +--- + +**mandatory** + +calling conventions for ->follow_link() have changed. Instead of returning +cookie and using nd_set_link() to store the body to traverse, we return +the body to traverse and store the cookie using explicit void ** argument. +nameidata isn't passed at all - nd_jump_link() doesn't need it and +nd_[gs]et_link() is gone. + +--- + +**mandatory** + +calling conventions for ->put_link() have changed. It gets inode instead of +dentry, it does not get nameidata at all and it gets called only when cookie +is non-NULL. Note that link body isn't available anymore, so if you need it, +store it as cookie. + +--- + +**mandatory** + +any symlink that might use page_follow_link_light/page_put_link() must +have inode_nohighmem(inode) called before anything might start playing with +its pagecache. No highmem pages should end up in the pagecache of such +symlinks. That includes any preseeding that might be done during symlink +creation. __page_symlink() will honour the mapping gfp flags, so once +you've done inode_nohighmem() it's safe to use, but if you allocate and +insert the page manually, make sure to use the right gfp flags. + +--- + +**mandatory** + +->follow_link() is replaced with ->get_link(); same API, except that + + * ->get_link() gets inode as a separate argument + * ->get_link() may be called in RCU mode - in that case NULL + dentry is passed + +--- + +**mandatory** + +->get_link() gets struct delayed_call ``*done`` now, and should do +set_delayed_call() where it used to set ``*cookie``. + +->put_link() is gone - just give the destructor to set_delayed_call() +in ->get_link(). + +--- + +**mandatory** + +->getxattr() and xattr_handler.get() get dentry and inode passed separately. +dentry might be yet to be attached to inode, so do _not_ use its ->d_inode +in the instances. Rationale: !@#!@# security_d_instantiate() needs to be +called before we attach dentry to inode. + +--- + +**mandatory** + +symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/ +i_pipe/i_link union zeroed out at inode eviction. As the result, you can't +assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that +it's a symlink. Checking ->i_mode is really needed now. In-tree we had +to fix shmem_destroy_callback() that used to take that kind of shortcut; +watch out, since that shortcut is no longer valid. + +--- + +**mandatory** + +->i_mutex is replaced with ->i_rwsem now. inode_lock() et.al. work as +they used to - they just take it exclusive. However, ->lookup() may be +called with parent locked shared. Its instances must not + + * use d_instantiate) and d_rehash() separately - use d_add() or + d_splice_alias() instead. + * use d_rehash() alone - call d_add(new_dentry, NULL) instead. + * in the unlikely case when (read-only) access to filesystem + data structures needs exclusion for some reason, arrange it + yourself. None of the in-tree filesystems needed that. + * rely on ->d_parent and ->d_name not changing after dentry has + been fed to d_add() or d_splice_alias(). Again, none of the + in-tree instances relied upon that. + +We are guaranteed that lookups of the same name in the same directory +will not happen in parallel ("same" in the sense of your ->d_compare()). +Lookups on different names in the same directory can and do happen in +parallel now. + +--- + +**recommended** + +->iterate_shared() is added; it's a parallel variant of ->iterate(). +Exclusion on struct file level is still provided (as well as that +between it and lseek on the same struct file), but if your directory +has been opened several times, you can get these called in parallel. +Exclusion between that method and all directory-modifying ones is +still provided, of course. + +Often enough ->iterate() can serve as ->iterate_shared() without any +changes - it is a read-only operation, after all. If you have any +per-inode or per-dentry in-core data structures modified by ->iterate(), +you might need something to serialize the access to them. If you +do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for +that; look for in-tree examples. + +Old method is only used if the new one is absent; eventually it will +be removed. Switch while you still can; the old one won't stay. + +--- + +**mandatory** + +->atomic_open() calls without O_CREAT may happen in parallel. + +--- + +**mandatory** + +->setxattr() and xattr_handler.set() get dentry and inode passed separately. +dentry might be yet to be attached to inode, so do _not_ use its ->d_inode +in the instances. Rationale: !@#!@# security_d_instantiate() needs to be +called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack +->d_instantiate() uses not just ->getxattr() but ->setxattr() as well. + +--- + +**mandatory** + +->d_compare() doesn't get parent as a separate argument anymore. If you +used it for finding the struct super_block involved, dentry->d_sb will +work just as well; if it's something more complicated, use dentry->d_parent. +Just be careful not to assume that fetching it more than once will yield +the same value - in RCU mode it could change under you. + +--- + +**mandatory** + +->rename() has an added flags argument. Any flags not handled by the +filesystem should result in EINVAL being returned. + +--- + + +**recommended** + +->readlink is optional for symlinks. Don't set, unless filesystem needs +to fake something for readlink(2). + +--- + +**mandatory** + +->getattr() is now passed a struct path rather than a vfsmount and +dentry separately, and it now has request_mask and query_flags arguments +to specify the fields and sync type requested by statx. Filesystems not +supporting any statx-specific features may ignore the new arguments. + +--- + +**mandatory** + +->atomic_open() calling conventions have changed. Gone is ``int *opened``, +along with FILE_OPENED/FILE_CREATED. In place of those we have +FMODE_OPENED/FMODE_CREATED, set in file->f_mode. Additionally, return +value for 'called finish_no_open(), open it yourself' case has become +0, not 1. Since finish_no_open() itself is returning 0 now, that part +does not need any changes in ->atomic_open() instances. + +--- + +**mandatory** + +alloc_file() has become static now; two wrappers are to be used instead. +alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases +when dentry needs to be created; that's the majority of old alloc_file() +users. Calling conventions: on success a reference to new struct file +is returned and callers reference to inode is subsumed by that. On +failure, ERR_PTR() is returned and no caller's references are affected, +so the caller needs to drop the inode reference it held. +alloc_file_clone(file, flags, ops) does not affect any caller's references. +On success you get a new struct file sharing the mount/dentry with the +original, on failure - ERR_PTR(). + +--- + +**mandatory** + +->clone_file_range() and ->dedupe_file_range have been replaced with +->remap_file_range(). See Documentation/filesystems/vfs.rst for more +information. + +--- + +**recommended** + +->lookup() instances doing an equivalent of:: + + if (IS_ERR(inode)) + return ERR_CAST(inode); + return d_splice_alias(inode, dentry); + +don't need to bother with the check - d_splice_alias() will do the +right thing when given ERR_PTR(...) as inode. Moreover, passing NULL +inode to d_splice_alias() will also do the right thing (equivalent of +d_add(dentry, NULL); return NULL;), so that kind of special cases +also doesn't need a separate treatment. + +--- + +**strongly recommended** + +take the RCU-delayed parts of ->destroy_inode() into a new method - +->free_inode(). If ->destroy_inode() becomes empty - all the better, +just get rid of it. Synchronous work (e.g. the stuff that can't +be done from an RCU callback, or any WARN_ON() where we want the +stack trace) *might* be movable to ->evict_inode(); however, +that goes only for the things that are not needed to balance something +done by ->alloc_inode(). IOW, if it's cleaning up the stuff that +might have accumulated over the life of in-core inode, ->evict_inode() +might be a fit. + +Rules for inode destruction: + + * if ->destroy_inode() is non-NULL, it gets called + * if ->free_inode() is non-NULL, it gets scheduled by call_rcu() + * combination of NULL ->destroy_inode and NULL ->free_inode is + treated as NULL/free_inode_nonrcu, to preserve the compatibility. + +Note that the callback (be it via ->free_inode() or explicit call_rcu() +in ->destroy_inode()) is *NOT* ordered wrt superblock destruction; +as the matter of fact, the superblock and all associated structures +might be already gone. The filesystem driver is guaranteed to be still +there, but that's it. Freeing memory in the callback is fine; doing +more than that is possible, but requires a lot of care and is best +avoided. + +--- + +**mandatory** + +DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the +default. DCACHE_NORCU opts out, and only d_alloc_pseudo() has any +business doing so. + +--- + +**mandatory** + +d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are +very suspect (and won't work in modules). Such uses are very likely to +be misspelled d_alloc_anon(). diff --git a/fs/orangefs/orangefs-kernel.h b/fs/orangefs/orangefs-kernel.h index 572dd29fbd54..34a6c99fa29b 100644 --- a/fs/orangefs/orangefs-kernel.h +++ b/fs/orangefs/orangefs-kernel.h @@ -246,7 +246,7 @@ struct orangefs_read_options { extern struct orangefs_stats orangefs_stats; /* - * NOTE: See Documentation/filesystems/porting for information + * NOTE: See Documentation/filesystems/porting.rst for information * on implementing FOO_I and properly accessing fs private data */ static inline struct orangefs_inode_s *ORANGEFS_I(struct inode *inode) From 9c970ab54c336340429fcd2570f3c577610078e2 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:29 -0300 Subject: [PATCH 30/67] docs: index.rst: don't use genindex for pdf output The genindex logic is meant to be used only for html output, as pdf build has its own way to generate indexes. Signed-off-by: Mauro Carvalho Chehab Acked-by: Vinod Koul # dmaengine and soundwire Signed-off-by: Jonathan Corbet --- Documentation/core-api/index.rst | 2 +- Documentation/driver-api/dmaengine/index.rst | 2 +- Documentation/driver-api/soundwire/index.rst | 2 +- Documentation/networking/device_drivers/index.rst | 2 +- Documentation/networking/index.rst | 2 +- Documentation/sound/index.rst | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index dfd8fad1e1ec..fa16a0538dcb 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -49,7 +49,7 @@ Interfaces for kernel debugging debug-objects tracepoint -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst index 3026fa975937..b9df904d0a79 100644 --- a/Documentation/driver-api/dmaengine/index.rst +++ b/Documentation/driver-api/dmaengine/index.rst @@ -47,7 +47,7 @@ This book adds some notes about PXA DMA pxa_dma -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst index 6db026028f27..234911a0db99 100644 --- a/Documentation/driver-api/soundwire/index.rst +++ b/Documentation/driver-api/soundwire/index.rst @@ -10,7 +10,7 @@ SoundWire Documentation error_handling locking -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst index 2b7fefe72351..f724b7c69b9e 100644 --- a/Documentation/networking/device_drivers/index.rst +++ b/Documentation/networking/device_drivers/index.rst @@ -24,7 +24,7 @@ Contents: google/gve mellanox/mlx5 -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index a46fca264bee..6739066acadb 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -31,7 +31,7 @@ Contents: tls tls-offload -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 47b89f014e69..4d7d42acf6df 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation hd-audio/index cards/index -.. only:: subproject +.. only:: subproject and html Indices ======= From ff497db295c8939c4badf9cbaf5f0679af8ada0a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:30 -0300 Subject: [PATCH 31/67] docs: wimax: convert to ReST and add to admin-guide Manually convert wimax documentation to ReST and add theit to the Kernel doc body, inside the admin-guide. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 1 + .../wimax/i2400m.rst} | 145 ++++++++++-------- Documentation/admin-guide/wimax/index.rst | 19 +++ .../wimax/wimax.rst} | 36 +++-- MAINTAINERS | 4 +- 5 files changed, 128 insertions(+), 77 deletions(-) rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%) create mode 100644 Documentation/admin-guide/wimax/index.rst rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 200e47820c37..534373816d7f 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -108,6 +108,7 @@ configure specific aspects of kernel behavior to your liking. pnp rtc svga + wimax/index video-output .. only:: subproject and html diff --git a/Documentation/wimax/README.i2400m b/Documentation/admin-guide/wimax/i2400m.rst similarity index 69% rename from Documentation/wimax/README.i2400m rename to Documentation/admin-guide/wimax/i2400m.rst index 7dffd8919cb0..194388c0c351 100644 --- a/Documentation/wimax/README.i2400m +++ b/Documentation/admin-guide/wimax/i2400m.rst @@ -1,18 +1,23 @@ +.. include:: - Driver for the Intel Wireless Wimax Connection 2400m +==================================================== +Driver for the Intel Wireless Wimax Connection 2400m +==================================================== - (C) 2008 Intel Corporation < linux-wimax@intel.com > +:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com > This provides a driver for the Intel Wireless WiMAX Connection 2400m and a basic Linux kernel WiMAX stack. 1. Requirements +=============== * Linux installation with Linux kernel 2.6.22 or newer (if building from a separate tree) * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel Wireless WiMAX/WiFi Link 5x50 series. * build tools: + + Linux kernel development package for the target kernel; to build against your currently running kernel, you need to have the kernel development package corresponding to the running @@ -22,8 +27,10 @@ + GNU C Compiler, make 2. Compilation and installation +=============================== 2.1. Compilation of the drivers included in the kernel +------------------------------------------------------ Configure the kernel; to enable the WiMAX drivers select Drivers > Networking Drivers > WiMAX device support. Enable all of them as @@ -36,37 +43,39 @@ Compile and install your kernel as usual. 2.2. Compilation of the drivers distributed as an standalone module +------------------------------------------------------------------- - To compile + To compile:: -$ cd source/directory -$ make + $ cd source/directory + $ make Once built you can load and unload using the provided load.sh script; load.sh will load the modules, load.sh u will unload them. To install in the default kernel directories (and enable auto loading - when the device is plugged): + when the device is plugged):: -$ make install -$ depmod -a + $ make install + $ depmod -a If your kernel development files are located in a non standard directory or if you want to build for a kernel that is not the - currently running one, set KDIR to the right location: + currently running one, set KDIR to the right location:: -$ make KDIR=/path/to/kernel/dev/tree + $ make KDIR=/path/to/kernel/dev/tree For more information, please contact linux-wimax@intel.com. 3. Installing the firmware +-------------------------- The firmware can be obtained from http://linuxwimax.org or might have been supplied with your hardware. - It has to be installed in the target system: - * -$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf + It has to be installed in the target system:: + + $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf * NOTE: if your firmware came in an .rpm or .deb file, just install it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg @@ -76,6 +85,7 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf with other types. 4. Design +========= This package contains two major parts: a WiMAX kernel stack and a driver for the Intel i2400m. @@ -102,16 +112,17 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf API calls should be replaced with the target OS's. 5. Usage +======== To load the driver, follow the instructions in the install section; once the driver is loaded, plug in the device (unless it is permanently plugged in). The driver will enumerate the device, upload the firmware and output messages in the kernel log (dmesg, /var/log/messages or - /var/log/kern.log) such as: + /var/log/kern.log) such as:: -... -i2400m_usb 5-4:1.0: firmware interface version 8.0.0 -i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready + ... + i2400m_usb 5-4:1.0: firmware interface version 8.0.0 + i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready At this point the device is ready to work. @@ -120,38 +131,42 @@ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready on how to scan, connect and disconnect. 5.1. Module parameters +---------------------- Module parameters can be set at kernel or module load time or by - echoing values: + echoing values:: -$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME + $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME To make changes permanent, for example, for the i2400m module, you can - also create a file named /etc/modprobe.d/i2400m containing: + also create a file named /etc/modprobe.d/i2400m containing:: -options i2400m idle_mode_disabled=1 + options i2400m idle_mode_disabled=1 - To find which parameters are supported by a module, run: + To find which parameters are supported by a module, run:: -$ modinfo path/to/module.ko + $ modinfo path/to/module.ko During kernel bootup (if the driver is linked in the kernel), specify - the following to the kernel command line: + the following to the kernel command line:: -i2400m.PARAMETER=VALUE + i2400m.PARAMETER=VALUE 5.1.1. i2400m: idle_mode_disabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The i2400m module supports a parameter to disable idle mode. This parameter, once set, will take effect only when the device is reinitialized by the driver (eg: following a reset or a reconnect). 5.2. Debug operations: debugfs entries +-------------------------------------- The driver will register debugfs entries that allow the user to tweak debug settings. There are three main container directories where entries are placed, which correspond to the three blocks a i2400m WiMAX driver has: + * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack controls * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic @@ -163,52 +178,55 @@ i2400m.PARAMETER=VALUE /sys/kernel/debug, those paths will change. 5.2.1. Increasing debug output +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The files named *dl_* indicate knobs for controlling the debug output - of different submodules: - * -# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw -/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb -/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx -/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx -/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill -/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev -/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw -/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs -/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver -/sys/kernel/debug/wimax:wmx0/i2400m/dl_control -/sys/kernel/debug/wimax:wmx0/wimax_dl_stack -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg -/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table -/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs + of different submodules:: + + # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw + /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb + /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx + /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx + /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill + /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev + /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw + /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs + /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver + /sys/kernel/debug/wimax:wmx0/i2400m/dl_control + /sys/kernel/debug/wimax:wmx0/wimax_dl_stack + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg + /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table + /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs By reading the file you can obtain the current value of said debug level; by writing to it, you can set it. To increase the debug level of, for example, the i2400m's generic TX - engine, just write: + engine, just write:: -$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx + $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx Increasing numbers yield increasing debug information; for details of what is printed and the available levels, check the source. The code uses 0 for disabled and increasing values until 8. 5.2.2. RX and TX statistics +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The i2400m/rx_stats and i2400m/tx_stats provide statistics about the - data reception/delivery from the device: + data reception/delivery from the device:: -$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats -45 1 3 34 3104 48 480 + $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats + 45 1 3 34 3104 48 480 + + The numbers reported are: - The numbers reported are * packets/RX-buffer: total, min, max * RX-buffers: total RX buffers received, accumulated RX buffer size in bytes, min size received, max size received @@ -216,9 +234,9 @@ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats Thus, to find the average buffer size received, divide accumulated RX-buffer / total RX-buffers. - To clear the statistics back to 0, write anything to the rx_stats file: + To clear the statistics back to 0, write anything to the rx_stats file:: -$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats + $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats Likewise for TX. @@ -227,14 +245,16 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats to the host. See drivers/net/wimax/i2400m/tx.c. 5.2.3. Tracing messages received from user space +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To echo messages received from user space into the trace pipe that the i2400m driver creates, set the debug file i2400m/trace_msg_from_user to - 1: - * -$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user + 1:: + + $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user 5.2.4. Performing a device reset +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By writing a 0, a 1 or a 2 to the file /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without @@ -242,18 +262,21 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user (bus specific) reset on the device. 5.2.5. Asking the device to enter power saving mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the device will attempt to enter power saving mode. 6. Troubleshooting +================== -6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed' +6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed`` +---------------------------------------------------------------------- If upon connecting the device, the following is output in the kernel - log: + log:: -i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2 + i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2 This means that the driver cannot locate the firmware file named /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in diff --git a/Documentation/admin-guide/wimax/index.rst b/Documentation/admin-guide/wimax/index.rst new file mode 100644 index 000000000000..fdf7c1f99ff5 --- /dev/null +++ b/Documentation/admin-guide/wimax/index.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============== +WiMAX subsystem +=============== + +.. toctree:: + :maxdepth: 2 + + wimax + + i2400m + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/wimax/README.wimax b/Documentation/admin-guide/wimax/wimax.rst similarity index 74% rename from Documentation/wimax/README.wimax rename to Documentation/admin-guide/wimax/wimax.rst index b78c4378084e..817ee8ba2732 100644 --- a/Documentation/wimax/README.wimax +++ b/Documentation/admin-guide/wimax/wimax.rst @@ -1,12 +1,16 @@ +.. include:: - Linux kernel WiMAX stack +======================== +Linux kernel WiMAX stack +======================== - (C) 2008 Intel Corporation < linux-wimax@intel.com > +:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com > This provides a basic Linux kernel WiMAX stack to provide a common control API for WiMAX devices, usable from kernel and user space. 1. Design +========= The WiMAX stack is designed to provide for common WiMAX control services to current and future WiMAX devices from any vendor. @@ -31,6 +35,7 @@ include/linux/wimax.h. 2. Usage +======== For usage in a driver (registration, API, etc) please refer to the instructions in the header file include/linux/wimax.h. @@ -40,6 +45,7 @@ control. 2.1. Obtaining debug information: debugfs entries +------------------------------------------------- The WiMAX stack is compiled, by default, with debug messages that can be used to diagnose issues. By default, said messages are disabled. @@ -52,20 +58,22 @@ create more subentries below it. 2.1.1. Increasing debug output +------------------------------ The files named *dl_* indicate knobs for controlling the debug output - of different submodules of the WiMAX stack: - * -# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* -/sys/kernel/debug/wimax:wmx0/wimax_dl_stack -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset -/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg -/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table -/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs -/sys/kernel/debug/wimax:wmx0/.... # other driver specific files + of different submodules of the WiMAX stack:: - NOTE: Of course, if debugfs is mounted in a directory other than + # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* + /sys/kernel/debug/wimax:wmx0/wimax_dl_stack + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset + /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg + /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table + /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs + /sys/kernel/debug/wimax:wmx0/.... # other driver specific files + + NOTE: + Of course, if debugfs is mounted in a directory other than /sys/kernel/debug, those paths will change. By reading the file you can obtain the current value of said debug @@ -74,7 +82,7 @@ To increase the debug level of, for example, the id-table submodule, just write: -$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table + $ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table Increasing numbers yield increasing debug information; for details of what is printed and the available levels, check the source. The code diff --git a/MAINTAINERS b/MAINTAINERS index a27e36f491b3..6fa76e6a93cd 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -8356,7 +8356,7 @@ M: linux-wimax@intel.com L: wimax@linuxwimax.org (subscribers-only) S: Supported W: http://linuxwimax.org -F: Documentation/wimax/README.i2400m +F: Documentation/admin-guide/wimax/i2400m.rst F: drivers/net/wimax/i2400m/ F: include/uapi/linux/wimax/i2400m.h @@ -17358,7 +17358,7 @@ M: linux-wimax@intel.com L: wimax@linuxwimax.org (subscribers-only) S: Supported W: http://linuxwimax.org -F: Documentation/wimax/README.wimax +F: Documentation/admin-guide/wimax/wimax.rst F: include/linux/wimax/debug.h F: include/net/wimax.h F: include/uapi/linux/wimax.h From 80b1505893b60608e1525fc63caf16fd128f1b4c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:31 -0300 Subject: [PATCH 32/67] docs: mips: add to the documentation body as ReST Manually convert the AU1xxx_IDE.README file to ReST and add to a MIPS book as part of the main documentation body. Signed-off-by: Mauro Carvalho Chehab Acked-by: Paul Burton Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + .../{AU1xxx_IDE.README => au1xxx_ide.rst} | 89 +++++++++++-------- Documentation/mips/index.rst | 17 ++++ 3 files changed, 70 insertions(+), 37 deletions(-) rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%) create mode 100644 Documentation/mips/index.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index cd50e82710e0..633c951f6932 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -148,6 +148,7 @@ implementation. ia64/index m68k/index powerpc/index + mips/index openrisc/index parisc/index riscv/index diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/au1xxx_ide.rst similarity index 67% rename from Documentation/mips/AU1xxx_IDE.README rename to Documentation/mips/au1xxx_ide.rst index ff675a1b1422..2f9c2cff6738 100644 --- a/Documentation/mips/AU1xxx_IDE.README +++ b/Documentation/mips/au1xxx_ide.rst @@ -1,7 +1,14 @@ -README for MIPS AU1XXX IDE driver - Released 2005-07-15 +.. include:: + +====================== +MIPS AU1XXX IDE driver +====================== + +Released 2005-07-15 + +About +===== -ABOUT ------ This file describes the 'drivers/ide/au1xxx-ide.c', related files and the services they provide. @@ -10,17 +17,17 @@ the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST' section. -LICENSE -------- +License +======= -Copyright (c) 2003-2005 AMD, Personal Connectivity Solutions +:Copyright: |copy| 2003-2005 AMD, Personal Connectivity Solutions This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. -THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR @@ -35,31 +42,35 @@ You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE +Note: + for more information, please refer "AMD Alchemy Au1200/Au1550 IDE Interface and Linux Device Driver" Application Note. -FILES, CONFIGS AND COMPATIBILITY --------------------------------- +Files, Configs and Compatibility +================================ Two files are introduced: a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h' contains : struct _auide_hwif - timing parameters for PIO mode 0/1/2/3/4 - timing parameters for MWDMA 0/1/2 + + - timing parameters for PIO mode 0/1/2/3/4 + - timing parameters for MWDMA 0/1/2 b) 'drivers/ide/mips/au1xxx-ide.c' contains the functionality of the AU1XXX IDE driver Following extra configs variables are introduced: - CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA - enable the PIO+DBDMA mode - CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA - enable the MWDMA mode + CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA + - enable the PIO+DBDMA mode + CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA + - enable the MWDMA mode -SUPPORTED IDE MODES -------------------- +Supported IDE Modes +=================== The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode. @@ -69,20 +80,21 @@ To change the PIO mode use the program hdparm with option -p, e.g. -X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0. -PERFORMANCE CONFIGURATIONS --------------------------- +Performance Configurations +========================== -If the used system doesn't need USB support enable the following kernel configs: +If the used system doesn't need USB support enable the following kernel +configs:: -CONFIG_IDE=y -CONFIG_BLK_DEV_IDE=y -CONFIG_IDE_GENERIC=y -CONFIG_BLK_DEV_IDEPCI=y -CONFIG_BLK_DEV_GENERIC=y -CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_BLK_DEV_IDE_AU1XXX=y -CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y -CONFIG_BLK_DEV_IDEDMA=y + CONFIG_IDE=y + CONFIG_BLK_DEV_IDE=y + CONFIG_IDE_GENERIC=y + CONFIG_BLK_DEV_IDEPCI=y + CONFIG_BLK_DEV_GENERIC=y + CONFIG_BLK_DEV_IDEDMA_PCI=y + CONFIG_BLK_DEV_IDE_AU1XXX=y + CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y + CONFIG_BLK_DEV_IDEDMA=y Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable the burst support on DBDMA controller. @@ -90,20 +102,22 @@ the burst support on DBDMA controller. If the used system need the USB support enable the following kernel configs for high IDE to USB throughput. -CONFIG_IDE_GENERIC=y -CONFIG_BLK_DEV_IDEPCI=y -CONFIG_BLK_DEV_GENERIC=y -CONFIG_BLK_DEV_IDEDMA_PCI=y -CONFIG_BLK_DEV_IDE_AU1XXX=y -CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y -CONFIG_BLK_DEV_IDEDMA=y +:: + + CONFIG_IDE_GENERIC=y + CONFIG_BLK_DEV_IDEPCI=y + CONFIG_BLK_DEV_GENERIC=y + CONFIG_BLK_DEV_IDEDMA_PCI=y + CONFIG_BLK_DEV_IDE_AU1XXX=y + CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y + CONFIG_BLK_DEV_IDEDMA=y Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to disable the burst support on DBDMA controller. -ACKNOWLEDGMENTS ---------------- +Acknowledgments +=============== These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX IDE driver from AMD. @@ -112,4 +126,5 @@ Additional input also from: Matthias Lenk Happy hacking! + Enrico Walther diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst new file mode 100644 index 000000000000..fd9023c8a89f --- /dev/null +++ b/Documentation/mips/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +MIPS architecture +================= + +.. toctree:: + :maxdepth: 2 + + au1xxx_ide + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` From bfc8a222d3bca4c09a63de8b321bf7f825fa59ff Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:32 -0300 Subject: [PATCH 33/67] docs: hwmon: pxe1610: convert to ReST format and add to the index This document was recently introduced. Convert it to ReST just like the other hwmon documents, adding it to the hwmon index. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/hwmon/index.rst | 1 + Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +++++++++++++++----- 2 files changed, 26 insertions(+), 8 deletions(-) rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%) diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst index ee090e51653a..4d5f5fec43a3 100644 --- a/Documentation/hwmon/index.rst +++ b/Documentation/hwmon/index.rst @@ -130,6 +130,7 @@ Hardware Monitoring Kernel Drivers pcf8591 pmbus powr1220 + pxe1610 pwm-fan raspberrypi-hwmon sch5627 diff --git a/Documentation/hwmon/pxe1610 b/Documentation/hwmon/pxe1610.rst similarity index 82% rename from Documentation/hwmon/pxe1610 rename to Documentation/hwmon/pxe1610.rst index 211cedeefb44..4f2388840d06 100644 --- a/Documentation/hwmon/pxe1610 +++ b/Documentation/hwmon/pxe1610.rst @@ -2,19 +2,29 @@ Kernel driver pxe1610 ===================== Supported chips: + * Infineon PXE1610 + Prefix: 'pxe1610' + Addresses scanned: - + Datasheet: Datasheet is not publicly available. * Infineon PXE1110 + Prefix: 'pxe1110' + Addresses scanned: - + Datasheet: Datasheet is not publicly available. * Infineon PXM1310 + Prefix: 'pxm1310' + Addresses scanned: - + Datasheet: Datasheet is not publicly available. Author: Vijay Khemka @@ -25,14 +35,19 @@ Description PXE1610/PXE1110 are Multi-rail/Multiphase Digital Controllers and compliant to - -- Intel VR13 DC-DC converter specifications. - -- Intel SVID protocol. + + - Intel VR13 DC-DC converter specifications. + - Intel SVID protocol. + Used for Vcore power regulation for Intel VR13 based microprocessors - -- Servers, Workstations, and High-end desktops + + - Servers, Workstations, and High-end desktops PXM1310 is a Multi-rail Controller and it is compliant to - -- Intel VR13 DC-DC converter specifications. - -- Intel SVID protocol. + + - Intel VR13 DC-DC converter specifications. + - Intel SVID protocol. + Used for DDR3/DDR4 Memory power regulation for Intel VR13 and IMVP8 based systems @@ -44,10 +59,10 @@ This driver does not probe for PMBus devices. You will have to instantiate devices explicitly. Example: the following commands will load the driver for an PXE1610 -at address 0x70 on I2C bus #4: +at address 0x70 on I2C bus #4:: -# modprobe pxe1610 -# echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device + # modprobe pxe1610 + # echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device It can also be instantiated by declaring in device tree @@ -55,6 +70,7 @@ It can also be instantiated by declaring in device tree Sysfs attributes ---------------- +====================== ==================================== curr1_label "iin" curr1_input Measured input current curr1_alarm Current high alarm @@ -88,3 +104,4 @@ temp[1-3]_crit Critical high temperature temp[1-3]_crit_alarm Chip temperature critical high alarm temp[1-3]_max Maximum temperature temp[1-3]_max_alarm Chip temperature high alarm +====================== ==================================== From 47359e5734f1df0301ee3f0c46da9954f15b7bd9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:33 -0300 Subject: [PATCH 34/67] docs: nios2: add it to the main Documentation body Rename and add the nios2 documentation to the documentation body. The nios2 document is already on an ReST compatible format. All it needs is that the title of the document to be promoted one level. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + Documentation/nios2/{README => nios2.rst} | 1 + 2 files changed, 2 insertions(+) rename Documentation/nios2/{README => nios2.rst} (96%) diff --git a/Documentation/index.rst b/Documentation/index.rst index 633c951f6932..6217acab92db 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -149,6 +149,7 @@ implementation. m68k/index powerpc/index mips/index + nios2/nios2 openrisc/index parisc/index riscv/index diff --git a/Documentation/nios2/README b/Documentation/nios2/nios2.rst similarity index 96% rename from Documentation/nios2/README rename to Documentation/nios2/nios2.rst index 054a67d55563..43da3f7cee76 100644 --- a/Documentation/nios2/README +++ b/Documentation/nios2/nios2.rst @@ -1,3 +1,4 @@ +================================= Linux on the Nios II architecture ================================= From e15d5a53ea3239e537d3a0c4bdfce8a4ea4e0da6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 26 Jul 2019 09:51:34 -0300 Subject: [PATCH 35/67] docs: net: convert two README files to ReST format There are two README files there with doesn't have a .txt extension nor are at ReST format. In order to help with the docs conversion to ReST, rename those and manually convert them to ReST format. As there are lot more to be done for networking to be part of the documentation body, for now mark those two files with :orphan:, in order to supress a build warning. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- .../networking/caif/{README => caif.rst} | 92 +++++++++++++------ .../{README => mac80211_hwsim.rst} | 28 ++++-- MAINTAINERS | 2 +- 3 files changed, 83 insertions(+), 39 deletions(-) rename Documentation/networking/caif/{README => caif.rst} (70%) rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%) diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/caif.rst similarity index 70% rename from Documentation/networking/caif/README rename to Documentation/networking/caif/caif.rst index 757ccfaa1385..07afc8063d4d 100644 --- a/Documentation/networking/caif/README +++ b/Documentation/networking/caif/caif.rst @@ -1,18 +1,31 @@ -Copyright (C) ST-Ericsson AB 2010 -Author: Sjur Brendeland/ sjur.brandeland@stericsson.com -License terms: GNU General Public License (GPL) version 2 ---------------------------------------------------------- +:orphan: -=== Start === -If you have compiled CAIF for modules do: - -$modprobe crc_ccitt -$modprobe caif -$modprobe caif_socket -$modprobe chnl_net +.. SPDX-License-Identifier: GPL-2.0 +.. include:: -=== Preparing the setup with a STE modem === +================ +Using Linux CAIF +================ + + +:Copyright: |copy| ST-Ericsson AB 2010 + +:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com + +Start +===== + +If you have compiled CAIF for modules do:: + + $modprobe crc_ccitt + $modprobe caif + $modprobe caif_socket + $modprobe chnl_net + + +Preparing the setup with a STE modem +==================================== If you are working on integration of CAIF you should make sure that the kernel is built with module support. @@ -32,24 +45,30 @@ module parameter "ser_use_stx". Normally Frame Checksum is always used on UART, but this is also provided as a module parameter "ser_use_fcs". -$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes -$ ifconfig caif_ttyS0 up +:: -PLEASE NOTE: There is a limitation in Android shell. + $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes + $ ifconfig caif_ttyS0 up + +PLEASE NOTE: + There is a limitation in Android shell. It only accepts one argument to insmod/modprobe! -=== Trouble shooting === +Trouble shooting +================ There are debugfs parameters provided for serial communication. /sys/kernel/debug/caif_serial// * ser_state: Prints the bit-mask status where + - 0x02 means SENDING, this is a transient state. - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent - and is blocking further send operation. Flow OFF has been propagated - to all CAIF Channels using this TTY. + and is blocking further send operation. Flow OFF has been propagated + to all CAIF Channels using this TTY. * tty_status: Prints the bit-mask tty status information + - 0x01 - tty->warned is on. - 0x02 - tty->low_latency is on. - 0x04 - tty->packed is on. @@ -58,13 +77,17 @@ There are debugfs parameters provided for serial communication. - 0x20 - tty->stopped is on. * last_tx_msg: Binary blob Prints the last transmitted frame. - This can be printed with - $od --format=x1 /sys/kernel/debug/caif_serial//last_rx_msg. - The first two tx messages sent look like this. Note: The initial - byte 02 is start of frame extension (STX) used for re-syncing - upon errors. - - Enumeration: + This can be printed with:: + + $od --format=x1 /sys/kernel/debug/caif_serial//last_rx_msg. + + The first two tx messages sent look like this. Note: The initial + byte 02 is start of frame extension (STX) used for re-syncing + upon errors. + + - Enumeration:: + 0000000 02 05 00 00 03 01 d2 02 | | | | | | STX(1) | | | | @@ -73,7 +96,9 @@ There are debugfs parameters provided for serial communication. Command:Enumeration(1) Link-ID(1) Checksum(2) - - Channel Setup: + + - Channel Setup:: + 0000000 02 07 00 00 00 21 a1 00 48 df | | | | | | | | STX(1) | | | | | | @@ -86,13 +111,18 @@ There are debugfs parameters provided for serial communication. Checksum(2) * last_rx_msg: Prints the last transmitted frame. - The RX messages for LinkSetup look almost identical but they have the - bit 0x20 set in the command bit, and Channel Setup has added one byte - before Checksum containing Channel ID. - NOTE: Several CAIF Messages might be concatenated. The maximum debug + + The RX messages for LinkSetup look almost identical but they have the + bit 0x20 set in the command bit, and Channel Setup has added one byte + before Checksum containing Channel ID. + + NOTE: + Several CAIF Messages might be concatenated. The maximum debug buffer size is 128 bytes. -== Error Scenarios: +Error Scenarios +=============== + - last_tx_msg contains channel setup message and last_rx_msg is empty -> The host seems to be able to send over the UART, at least the CAIF ldisc get notified that sending is completed. @@ -103,7 +133,9 @@ There are debugfs parameters provided for serial communication. - if /sys/kernel/debug/caif_serial//tty_status is non-zero there might be problems transmitting over UART. + E.g. host and modem wiring is not correct you will typically see tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT). + You will probably see the enumeration message in last_tx_message and empty last_rx_message. diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst similarity index 81% rename from Documentation/networking/mac80211_hwsim/README rename to Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst index 3566a725d19c..d2266ce5534e 100644 --- a/Documentation/networking/mac80211_hwsim/README +++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst @@ -1,5 +1,13 @@ +:orphan: + +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=================================================================== mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211 -Copyright (c) 2008, Jouni Malinen +=================================================================== + +:Copyright: |copy| 2008, Jouni Malinen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as @@ -7,6 +15,7 @@ published by the Free Software Foundation. Introduction +============ mac80211_hwsim is a Linux kernel module that can be used to simulate arbitrary number of IEEE 802.11 radios for mac80211. It can be used to @@ -43,6 +52,7 @@ regardless of channel. Simple example +============== This example shows how to use mac80211_hwsim to simulate two radios: one to act as an access point and the other as a station that @@ -50,17 +60,19 @@ associates with the AP. hostapd and wpa_supplicant are used to take care of WPA2-PSK authentication. In addition, hostapd is also processing access point side of association. +:: -# Build mac80211_hwsim as part of kernel configuration -# Load the module -modprobe mac80211_hwsim + # Build mac80211_hwsim as part of kernel configuration -# Run hostapd (AP) for wlan0 -hostapd hostapd.conf + # Load the module + modprobe mac80211_hwsim -# Run wpa_supplicant (station) for wlan1 -wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf + # Run hostapd (AP) for wlan0 + hostapd hostapd.conf + + # Run wpa_supplicant (station) for wlan1 + wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf More test cases are available in hostap.git: diff --git a/MAINTAINERS b/MAINTAINERS index 6fa76e6a93cd..6de82f019a52 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9578,7 +9578,7 @@ F: Documentation/networking/mac80211-injection.txt F: include/net/mac80211.h F: net/mac80211/ F: drivers/net/wireless/mac80211_hwsim.[ch] -F: Documentation/networking/mac80211_hwsim/README +F: Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst MAILBOX API M: Jassi Brar From 2ef5a7f1482c21579d556f31a605a7ca32f251e7 Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Fri, 12 Jul 2019 18:44:32 +0300 Subject: [PATCH 36/67] tpm: Document UEFI event log quirks There are some weird quirks when it comes to UEFI event log. Provide a brief introduction to TPM event log mechanism and describe the quirks and how they can be sorted out. Signed-off-by: Jarkko Sakkinen Signed-off-by: Jonathan Corbet --- Documentation/security/tpm/index.rst | 1 + Documentation/security/tpm/tpm_event_log.rst | 55 ++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 Documentation/security/tpm/tpm_event_log.rst diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst index 3296533e54cf..2bae8e8ca4bc 100644 --- a/Documentation/security/tpm/index.rst +++ b/Documentation/security/tpm/index.rst @@ -4,5 +4,6 @@ Trusted Platform Module documentation .. toctree:: + tpm_event_log tpm_vtpm_proxy xen-tpmfront diff --git a/Documentation/security/tpm/tpm_event_log.rst b/Documentation/security/tpm/tpm_event_log.rst new file mode 100644 index 000000000000..f00f7a1d5e92 --- /dev/null +++ b/Documentation/security/tpm/tpm_event_log.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +TPM Event Log +============= + +This document briefly describes what TPM log is and how it is handed +over from the preboot firmware to the operating system. + +Introduction +============ + +The preboot firmware maintains an event log that gets new entries every +time something gets hashed by it to any of the PCR registers. The events +are segregated by their type and contain the value of the hashed PCR +register. Typically, the preboot firmware will hash the components to +who execution is to be handed over or actions relevant to the boot +process. + +The main application for this is remote attestation and the reason why +it is useful is nicely put in the very first section of [1]: + +"Attestation is used to provide information about the platform’s state +to a challenger. However, PCR contents are difficult to interpret; +therefore, attestation is typically more useful when the PCR contents +are accompanied by a measurement log. While not trusted on their own, +the measurement log contains a richer set of information than do the PCR +contents. The PCR contents are used to provide the validation of the +measurement log." + +UEFI event log +============== + +UEFI provided event log has a few somewhat weird quirks. + +Before calling ExitBootServices() Linux EFI stub copies the event log to +a custom configuration table defined by the stub itself. Unfortunately, +the events generated by ExitBootServices() don't end up in the table. + +The firmware provides so called final events configuration table to sort +out this issue. Events gets mirrored to this table after the first time +EFI_TCG2_PROTOCOL.GetEventLog() gets called. + +This introduces another problem: nothing guarantees that it is not called +before the Linux EFI stub gets to run. Thus, it needs to calculate and save the +final events table size while the stub is still running to the custom +configuration table so that the TPM driver can later on skip these events when +concatenating two halves of the event log from the custom configuration table +and the final events table. + +References +========== + +- [1] https://trustedcomputinggroup.org/resource/pc-client-specific-platform-firmware-profile-specification/ +- [2] The final concatenation is done in drivers/char/tpm/eventlog/efi.c From aa95b4a960ab53234863d4ae0d1a09ad74253104 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:08:48 -0300 Subject: [PATCH 37/67] docs: fix a couple of new broken references Those are due to recent changes. Most of the issues can be automatically fixed with: $ ./scripts/documentation-file-ref-check --fix The only exception was the sound binding with required manual work. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt | 2 +- MAINTAINERS | 4 ++-- drivers/hwtracing/coresight/Kconfig | 2 +- fs/jfs/Kconfig | 2 +- fs/ufs/Kconfig | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt index 2ca3d138528e..7ecf6bd60d27 100644 --- a/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt +++ b/Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt @@ -4,7 +4,7 @@ Allwinner SUN8I audio codec On Sun8i-A33 SoCs, the audio is separated in different parts: - A DAI driver. It uses the "sun4i-i2s" driver which is documented here: - Documentation/devicetree/bindings/sound/sun4i-i2s.txt + Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml - An analog part of the codec which is handled as PRCM registers. See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt - An digital part of the codec which is documented in this current diff --git a/MAINTAINERS b/MAINTAINERS index 6de82f019a52..f109a8bcffda 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -8659,7 +8659,7 @@ L: jfs-discussion@lists.sourceforge.net W: http://jfs.sourceforge.net/ T: git git://github.com/kleikamp/linux-shaggy.git S: Maintained -F: Documentation/filesystems/jfs.txt +F: Documentation/admin-guide/jfs.rst F: fs/jfs/ JME NETWORK DRIVER @@ -16439,7 +16439,7 @@ F: drivers/hid/hid-udraw-ps3.c UFS FILESYSTEM M: Evgeniy Dushistov S: Maintained -F: Documentation/filesystems/ufs.txt +F: Documentation/admin-guide/ufs.rst F: fs/ufs/ UHID USERSPACE HID IO DRIVER: diff --git a/drivers/hwtracing/coresight/Kconfig b/drivers/hwtracing/coresight/Kconfig index 14638db4991d..7a9f5fb08330 100644 --- a/drivers/hwtracing/coresight/Kconfig +++ b/drivers/hwtracing/coresight/Kconfig @@ -106,7 +106,7 @@ config CORESIGHT_CPU_DEBUG can quickly get to know program counter (PC), secure state, exception level, etc. Before use debugging functionality, platform needs to ensure the clock domain and power domain are enabled - properly, please refer Documentation/trace/coresight-cpu-debug.txt + properly, please refer Documentation/trace/coresight-cpu-debug.rst for detailed description and the example for usage. endif diff --git a/fs/jfs/Kconfig b/fs/jfs/Kconfig index 22a273bd4648..05cb0e8e4382 100644 --- a/fs/jfs/Kconfig +++ b/fs/jfs/Kconfig @@ -5,7 +5,7 @@ config JFS_FS select CRC32 help This is a port of IBM's Journaled Filesystem . More information is - available in the file . + available in the file . If you do not intend to use the JFS filesystem, say N. diff --git a/fs/ufs/Kconfig b/fs/ufs/Kconfig index fcb41516ea59..6d30adb6b890 100644 --- a/fs/ufs/Kconfig +++ b/fs/ufs/Kconfig @@ -9,7 +9,7 @@ config UFS_FS this file system as well. Saying Y here will allow you to read from these partitions; if you also want to write to them, say Y to the experimental "UFS file system write support", below. Please read the - file for more information. + file for more information. The recently released UFS2 variant (used in FreeBSD 5.x) is READ-ONLY supported. From d2fd3732e4acd6ab72960e7f8e00845438803f3e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:08:49 -0300 Subject: [PATCH 38/67] docs: writing-schema.md: convert from markdown to ReST The documentation standard is ReST and not markdown. Signed-off-by: Mauro Carvalho Chehab Acked-by: Rob Herring Signed-off-by: Jonathan Corbet --- Documentation/devicetree/writing-schema.md | 130 ----------------- Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++++ 2 files changed, 153 insertions(+), 130 deletions(-) delete mode 100644 Documentation/devicetree/writing-schema.md create mode 100644 Documentation/devicetree/writing-schema.rst diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.md deleted file mode 100644 index dc032db36262..000000000000 --- a/Documentation/devicetree/writing-schema.md +++ /dev/null @@ -1,130 +0,0 @@ -# Writing DeviceTree Bindings in json-schema - -Devicetree bindings are written using json-schema vocabulary. Schema files are -written in a JSON compatible subset of YAML. YAML is used instead of JSON as it -considered more human readable and has some advantages such as allowing -comments (Prefixed with '#'). - -## Schema Contents - -Each schema doc is a structured json-schema which is defined by a set of -top-level properties. Generally, there is one binding defined per file. The -top-level json-schema properties used are: - -- __$id__ - A json-schema unique identifier string. The string must be a valid -URI typically containing the binding's filename and path. For DT schema, it must -begin with "http://devicetree.org/schemas/". The URL is used in constructing -references to other files specified in schema "$ref" properties. A $ref values -with a leading '/' will have the hostname prepended. A $ref value a relative -path or filename only will be prepended with the hostname and path components -of the current schema file's '$id' value. A URL is used even for local files, -but there may not actually be files present at those locations. - -- __$schema__ - Indicates the meta-schema the schema file adheres to. - -- __title__ - A one line description on the contents of the binding schema. - -- __maintainers__ - A DT specific property. Contains a list of email address(es) -for maintainers of this binding. - -- __description__ - Optional. A multi-line text block containing any detailed -information about this binding. It should contain things such as what the block -or device does, standards the device conforms to, and links to datasheets for -more information. - -- __select__ - Optional. A json-schema used to match nodes for applying the -schema. By default without 'select', nodes are matched against their possible -compatible string values or node name. Most bindings should not need select. - -- __allOf__ - Optional. A list of other schemas to include. This is used to -include other schemas the binding conforms to. This may be schemas for a -particular class of devices such as I2C or SPI controllers. - -- __properties__ - A set of sub-schema defining all the DT properties for the -binding. The exact schema syntax depends on whether properties are known, -common properties (e.g. 'interrupts') or are binding/vendor specific properties. - - A property can also define a child DT node with child properties defined -under it. - - For more details on properties sections, see 'Property Schema' section. - -- __patternProperties__ - Optional. Similar to 'properties', but names are regex. - -- __required__ - A list of DT properties from the 'properties' section that -must always be present. - -- __examples__ - Optional. A list of one or more DTS hunks implementing the -binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. - -Unless noted otherwise, all properties are required. - -## Property Schema - -The 'properties' section of the schema contains all the DT properties for a -binding. Each property contains a set of constraints using json-schema -vocabulary for that property. The properties schemas are what is used for -validation of DT files. - -For common properties, only additional constraints not covered by the common -binding schema need to be defined such as how many values are valid or what -possible values are valid. - -Vendor specific properties will typically need more detailed schema. With the -exception of boolean properties, they should have a reference to a type in -schemas/types.yaml. A "description" property is always required. - -The Devicetree schemas don't exactly match the YAML encoded DT data produced by -dtc. They are simplified to make them more compact and avoid a bunch of -boilerplate. The tools process the schema files to produce the final schema for -validation. There are currently 2 transformations the tools perform. - -The default for arrays in json-schema is they are variable sized and allow more -entries than explicitly defined. This can be restricted by defining 'minItems', -'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed -size is desired in most cases, so these properties are added based on the -number of entries in an 'items' list. - -The YAML Devicetree format also makes all string values an array and scalar -values a matrix (in order to define groupings) even when only a single value -is present. Single entries in schemas are fixed up to match this encoding. - -## Testing - -### Dependencies - -The DT schema project must be installed in order to validate the DT schema -binding documents and validate DTS files using the DT schema. The DT schema -project can be installed with pip: - -`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master` - -dtc must also be built with YAML output support enabled. This requires that -libyaml and its headers be installed on the host system. - -### Running checks - -The DT schema binding documents must be validated using the meta-schema (the -schema for the schema) to ensure they are both valid json-schema and valid -binding schema. All of the DT binding documents can be validated using the -`dt_binding_check` target: - -`make dt_binding_check` - -In order to perform validation of DT source files, use the `dtbs_check` target: - -`make dtbs_check` - -This will first run the `dt_binding_check` which generates the processed schema. - -It is also possible to run checks with a single schema file by setting the -'DT_SCHEMA_FILES' variable to a specific schema file. - -`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml` - - -## json-schema Resources - -[JSON-Schema Specifications](http://json-schema.org/) - -[Using JSON Schema Book](http://usingjsonschema.com/) diff --git a/Documentation/devicetree/writing-schema.rst b/Documentation/devicetree/writing-schema.rst new file mode 100644 index 000000000000..8f71d1e2ac52 --- /dev/null +++ b/Documentation/devicetree/writing-schema.rst @@ -0,0 +1,153 @@ +:orphan: + +Writing DeviceTree Bindings in json-schema +========================================== + +Devicetree bindings are written using json-schema vocabulary. Schema files are +written in a JSON compatible subset of YAML. YAML is used instead of JSON as it +considered more human readable and has some advantages such as allowing +comments (Prefixed with '#'). + +Schema Contents +--------------- + +Each schema doc is a structured json-schema which is defined by a set of +top-level properties. Generally, there is one binding defined per file. The +top-level json-schema properties used are: + +$id + A json-schema unique identifier string. The string must be a valid + URI typically containing the binding's filename and path. For DT schema, it must + begin with "http://devicetree.org/schemas/". The URL is used in constructing + references to other files specified in schema "$ref" properties. A $ref values + with a leading '/' will have the hostname prepended. A $ref value a relative + path or filename only will be prepended with the hostname and path components + of the current schema file's '$id' value. A URL is used even for local files, + but there may not actually be files present at those locations. + +$schema + Indicates the meta-schema the schema file adheres to. + +title + A one line description on the contents of the binding schema. + +maintainers + A DT specific property. Contains a list of email address(es) + for maintainers of this binding. + +description + Optional. A multi-line text block containing any detailed + information about this binding. It should contain things such as what the block + or device does, standards the device conforms to, and links to datasheets for + more information. + +select + Optional. A json-schema used to match nodes for applying the + schema. By default without 'select', nodes are matched against their possible + compatible string values or node name. Most bindings should not need select. + + allOf + Optional. A list of other schemas to include. This is used to + include other schemas the binding conforms to. This may be schemas for a + particular class of devices such as I2C or SPI controllers. + + properties + A set of sub-schema defining all the DT properties for the + binding. The exact schema syntax depends on whether properties are known, + common properties (e.g. 'interrupts') or are binding/vendor specific properties. + +A property can also define a child DT node with child properties defined +under it. + +For more details on properties sections, see 'Property Schema' section. + +patternProperties + Optional. Similar to 'properties', but names are regex. + +required + A list of DT properties from the 'properties' section that + must always be present. + +examples + Optional. A list of one or more DTS hunks implementing the + binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead. + +Unless noted otherwise, all properties are required. + +Property Schema +--------------- + +The 'properties' section of the schema contains all the DT properties for a +binding. Each property contains a set of constraints using json-schema +vocabulary for that property. The properties schemas are what is used for +validation of DT files. + +For common properties, only additional constraints not covered by the common +binding schema need to be defined such as how many values are valid or what +possible values are valid. + +Vendor specific properties will typically need more detailed schema. With the +exception of boolean properties, they should have a reference to a type in +schemas/types.yaml. A "description" property is always required. + +The Devicetree schemas don't exactly match the YAML encoded DT data produced by +dtc. They are simplified to make them more compact and avoid a bunch of +boilerplate. The tools process the schema files to produce the final schema for +validation. There are currently 2 transformations the tools perform. + +The default for arrays in json-schema is they are variable sized and allow more +entries than explicitly defined. This can be restricted by defining 'minItems', +'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed +size is desired in most cases, so these properties are added based on the +number of entries in an 'items' list. + +The YAML Devicetree format also makes all string values an array and scalar +values a matrix (in order to define groupings) even when only a single value +is present. Single entries in schemas are fixed up to match this encoding. + +Testing +------- + +Dependencies +~~~~~~~~~~~~ + +The DT schema project must be installed in order to validate the DT schema +binding documents and validate DTS files using the DT schema. The DT schema +project can be installed with pip:: + + pip3 install git+https://github.com/devicetree-org/dt-schema.git@master + +dtc must also be built with YAML output support enabled. This requires that +libyaml and its headers be installed on the host system. + +Running checks +~~~~~~~~~~~~~~ + +The DT schema binding documents must be validated using the meta-schema (the +schema for the schema) to ensure they are both valid json-schema and valid +binding schema. All of the DT binding documents can be validated using the +``dt_binding_check`` target:: + + make dt_binding_check + +In order to perform validation of DT source files, use the `dtbs_check` target:: + + make dtbs_check + +This will first run the `dt_binding_check` which generates the processed schema. + +It is also possible to run checks with a single schema file by setting the +``DT_SCHEMA_FILES`` variable to a specific schema file. + +:: + + make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml + + +json-schema Resources +--------------------- + + +`JSON-Schema Specifications `_ + +`Using JSON Schema Book `_ From 9cdd273e29f3b901712ec3c298b1d506861f48e3 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:08:50 -0300 Subject: [PATCH 39/67] spi: docs: convert to ReST and add it to the kABI bookset While there's one file there with briefily describes the uAPI, the documentation was written just like most subsystems: focused on kernel developers. So, add it together with driver-api books. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jonathan Cameron # for iio Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + .../spi/{butterfly => butterfly.rst} | 44 ++++---- Documentation/spi/index.rst | 22 ++++ Documentation/spi/{pxa2xx => pxa2xx.rst} | 95 ++++++++-------- .../spi/{spi-lm70llp => spi-lm70llp.rst} | 17 ++- .../spi/{spi-sc18is602 => spi-sc18is602.rst} | 3 + .../spi/{spi-summary => spi-summary.rst} | 105 ++++++++++-------- Documentation/spi/{spidev => spidev.rst} | 30 +++-- drivers/iio/dummy/iio_simple_dummy.c | 2 +- drivers/spi/Kconfig | 2 +- drivers/spi/spi-butterfly.c | 2 +- drivers/spi/spi-lm70llp.c | 2 +- include/linux/platform_data/sc18is602.h | 2 +- 13 files changed, 198 insertions(+), 129 deletions(-) rename Documentation/spi/{butterfly => butterfly.rst} (71%) create mode 100644 Documentation/spi/index.rst rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%) rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%) rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%) rename Documentation/spi/{spi-summary => spi-summary.rst} (93%) rename Documentation/spi/{spidev => spidev.rst} (90%) diff --git a/Documentation/index.rst b/Documentation/index.rst index 6217acab92db..472b8abe52e9 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -116,6 +116,7 @@ needed). power/index target/index timers/index + spi/index watchdog/index virtual/index input/index diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst similarity index 71% rename from Documentation/spi/butterfly rename to Documentation/spi/butterfly.rst index 9927af7a629c..e614a589547c 100644 --- a/Documentation/spi/butterfly +++ b/Documentation/spi/butterfly.rst @@ -1,3 +1,4 @@ +=================================================== spi_butterfly - parport-to-butterfly adapter driver =================================================== @@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP" connector pins (used also on non-Butterfly AVR boards). On the parport side this is like "sp12" programming cables. + ====== ============= =================== Signal Butterfly Parport (DB-25) - ------ --------- --------------- - SCK = J403.PB1/SCK = pin 2/D0 - RESET = J403.nRST = pin 3/D1 - VCC = J403.VCC_EXT = pin 8/D6 - MOSI = J403.PB2/MOSI = pin 9/D7 - MISO = J403.PB3/MISO = pin 11/S7,nBUSY - GND = J403.GND = pin 23/GND + ====== ============= =================== + SCK J403.PB1/SCK pin 2/D0 + RESET J403.nRST pin 3/D1 + VCC J403.VCC_EXT pin 8/D6 + MOSI J403.PB2/MOSI pin 9/D7 + MISO J403.PB3/MISO pin 11/S7,nBUSY + GND J403.GND pin 23/GND + ====== ============= =================== Then to let Linux master that bus to talk to the DataFlash chip, you must (a) flash new firmware that disables SPI (set PRR.2, and disable pullups by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and (c) cable in the chipselect. + ====== ============ =================== Signal Butterfly Parport (DB-25) - ------ --------- --------------- - VCC = J400.VCC_EXT = pin 7/D5 - SELECT = J400.PB0/nSS = pin 17/C3,nSELECT - GND = J400.GND = pin 24/GND + ====== ============ =================== + VCC J400.VCC_EXT pin 7/D5 + SELECT J400.PB0/nSS pin 17/C3,nSELECT + GND J400.GND pin 24/GND + ====== ============ =================== Or you could flash firmware making the AVR into an SPI slave (keeping the DataFlash in reset) and tweak the spi_butterfly driver to make it bind to @@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware, while letting either Linux or the AVR use the DataFlash. There are plenty of spare parport pins to wire this one up, such as: + ====== ============= =================== Signal Butterfly Parport (DB-25) - ------ --------- --------------- - SCK = J403.PE4/USCK = pin 5/D3 - MOSI = J403.PE5/DI = pin 6/D4 - MISO = J403.PE6/DO = pin 12/S5,nPAPEROUT - GND = J403.GND = pin 22/GND - - IRQ = J402.PF4 = pin 10/S6,ACK - GND = J402.GND(P2) = pin 25/GND + ====== ============= =================== + SCK J403.PE4/USCK pin 5/D3 + MOSI J403.PE5/DI pin 6/D4 + MISO J403.PE6/DO pin 12/S5,nPAPEROUT + GND J403.GND pin 22/GND + IRQ J402.PF4 pin 10/S6,ACK + GND J402.GND(P2) pin 25/GND + ====== ============= =================== diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst new file mode 100644 index 000000000000..06c34ea11bcf --- /dev/null +++ b/Documentation/spi/index.rst @@ -0,0 +1,22 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================= +Serial Peripheral Interface (SPI) +================================= + +.. toctree:: + :maxdepth: 1 + + spi-summary + spidev + butterfly + pxa2xx + spi-lm70llp + spi-sc18is602 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst similarity index 83% rename from Documentation/spi/pxa2xx rename to Documentation/spi/pxa2xx.rst index 551325b66b23..882d3cc72cc2 100644 --- a/Documentation/spi/pxa2xx +++ b/Documentation/spi/pxa2xx.rst @@ -1,8 +1,10 @@ +============================== PXA2xx SPI on SSP driver HOWTO -=================================================== +============================== + This a mini howto on the pxa2xx_spi driver. The driver turns a PXA2xx synchronous serial port into a SPI master controller -(see Documentation/spi/spi-summary). The driver has the following features +(see Documentation/spi/spi-summary.rst). The driver has the following features - Support for any PXA2xx SSP - SSP PIO and SSP DMA data transfers. @@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers ----------------------------------- Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a "platform device". The master configuration is passed to the driver via a table -found in include/linux/spi/pxa2xx_spi.h: +found in include/linux/spi/pxa2xx_spi.h:: -struct pxa2xx_spi_controller { + struct pxa2xx_spi_controller { u16 num_chipselect; u8 enable_dma; -}; + }; The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of slave device (chips) attached to this SPI master. @@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller". NSSP MASTER SAMPLE ------------------ -Below is a sample configuration using the PXA255 NSSP. +Below is a sample configuration using the PXA255 NSSP:: -static struct resource pxa_spi_nssp_resources[] = { + static struct resource pxa_spi_nssp_resources[] = { [0] = { .start = __PREG(SSCR0_P(2)), /* Start address of NSSP */ .end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */ @@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = { .end = IRQ_NSSP, .flags = IORESOURCE_IRQ, }, -}; + }; -static struct pxa2xx_spi_controller pxa_nssp_master_info = { + static struct pxa2xx_spi_controller pxa_nssp_master_info = { .num_chipselect = 1, /* Matches the number of chips attached to NSSP */ .enable_dma = 1, /* Enables NSSP DMA */ -}; + }; -static struct platform_device pxa_spi_nssp = { + static struct platform_device pxa_spi_nssp = { .name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */ .id = 2, /* Bus number, MUST MATCH SSP number 1..n */ .resource = pxa_spi_nssp_resources, @@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = { .dev = { .platform_data = &pxa_nssp_master_info, /* Passed to driver */ }, -}; + }; -static struct platform_device *devices[] __initdata = { + static struct platform_device *devices[] __initdata = { &pxa_spi_nssp, -}; + }; -static void __init board_init(void) -{ + static void __init board_init(void) + { (void)platform_add_device(devices, ARRAY_SIZE(devices)); -} + } Declaring Slave Devices ----------------------- Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c using the "spi_board_info" structure found in "linux/spi/spi.h". See -"Documentation/spi/spi-summary" for additional information. +"Documentation/spi/spi-summary.rst" for additional information. Each slave device attached to the PXA must provide slave specific configuration information via the structure "pxa2xx_spi_chip" found in @@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in will uses the configuration whenever the driver communicates with the slave device. All fields are optional. -struct pxa2xx_spi_chip { +:: + + struct pxa2xx_spi_chip { u8 tx_threshold; u8 rx_threshold; u8 dma_burst_size; u32 timeout; u8 enable_loopback; void (*cs_control)(u32 command); -}; + }; The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are used to configure the SSP hardware fifo. These fields are critical to the performance of pxa2xx_spi driver and misconfiguration will result in rx -fifo overruns (especially in PIO mode transfers). Good default values are +fifo overruns (especially in PIO mode transfers). Good default values are:: .tx_threshold = 8, .rx_threshold = 8, @@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the "spi_board_info.controller_data" field. Below is a sample configuration using the PXA255 NSSP. -/* Chip Select control for the CS8415A SPI slave device */ -static void cs8415a_cs_control(u32 command) -{ +:: + + /* Chip Select control for the CS8415A SPI slave device */ + static void cs8415a_cs_control(u32 command) + { if (command & PXA2XX_CS_ASSERT) GPCR(2) = GPIO_bit(2); else GPSR(2) = GPIO_bit(2); -} + } -/* Chip Select control for the CS8405A SPI slave device */ -static void cs8405a_cs_control(u32 command) -{ + /* Chip Select control for the CS8405A SPI slave device */ + static void cs8405a_cs_control(u32 command) + { if (command & PXA2XX_CS_ASSERT) GPCR(3) = GPIO_bit(3); else GPSR(3) = GPIO_bit(3); -} + } -static struct pxa2xx_spi_chip cs8415a_chip_info = { + static struct pxa2xx_spi_chip cs8415a_chip_info = { .tx_threshold = 8, /* SSP hardward FIFO threshold */ .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ .cs_control = cs8415a_cs_control, /* Use external chip select */ -}; + }; -static struct pxa2xx_spi_chip cs8405a_chip_info = { + static struct pxa2xx_spi_chip cs8405a_chip_info = { .tx_threshold = 8, /* SSP hardward FIFO threshold */ .rx_threshold = 8, /* SSP hardward FIFO threshold */ .dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */ .timeout = 235, /* See Intel documentation */ .cs_control = cs8405a_cs_control, /* Use external chip select */ -}; + }; -static struct spi_board_info streetracer_spi_board_info[] __initdata = { + static struct spi_board_info streetracer_spi_board_info[] __initdata = { { .modalias = "cs8415a", /* Name of spi_driver for this device */ .max_speed_hz = 3686400, /* Run SSP as fast a possbile */ @@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = { .controller_data = &cs8405a_chip_info, /* Master chip config */ .irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */ }, -}; + }; -static void __init streetracer_init(void) -{ + static void __init streetracer_init(void) + { spi_register_board_info(streetracer_spi_board_info, ARRAY_SIZE(streetracer_spi_board_info)); -} + } DMA and PIO I/O Support @@ -210,26 +216,25 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The mode supports both coherent and stream based DMA mappings. The following logic is used to determine the type of I/O to be used on -a per "spi_transfer" basis: +a per "spi_transfer" basis:: -if !enable_dma then + if !enable_dma then always use PIO transfers -if spi_message.len > 8191 then + if spi_message.len > 8191 then print "rate limited" warning use PIO transfers -if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then + if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then use coherent DMA mode -if rx_buf and tx_buf are aligned on 8 byte boundary then + if rx_buf and tx_buf are aligned on 8 byte boundary then use streaming DMA mode -otherwise + otherwise use PIO transfer THANKS TO --------- David Brownell and others for mentoring the development of this driver. - diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst similarity index 88% rename from Documentation/spi/spi-lm70llp rename to Documentation/spi/spi-lm70llp.rst index 463f6d01fa15..07631aef4343 100644 --- a/Documentation/spi/spi-lm70llp +++ b/Documentation/spi/spi-lm70llp.rst @@ -1,8 +1,11 @@ +============================================== spi_lm70llp : LM70-LLP parport-to-SPI adapter ============================================== Supported board/chip: + * National Semiconductor LM70 LLP evaluation board + Datasheet: http://www.national.com/pf/LM/LM70.html Author: @@ -29,9 +32,10 @@ available (on page 4) here: The hardware interfacing on the LM70 LLP eval board is as follows: + ======== == ========= ========== Parallel LM70 LLP - Port Direction JP2 Header - ----------- --------- ---------------- + Port . Direction JP2 Header + ======== == ========= ========== D0 2 - - D1 3 --> V+ 5 D2 4 --> V+ 5 @@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows: D7 9 --> SI/O 5 GND 25 - GND 7 Select 13 <-- SI/O 1 - ----------- --------- ---------------- + ======== == ========= ========== Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin is connected to both pin D7 (as Master Out) and Select (as Master In) @@ -74,6 +78,7 @@ inverting the value read at pin 13. Thanks to --------- -o David Brownell for mentoring the SPI-side driver development. -o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version. -o Nadir Billimoria for help interpreting the circuit schematic. + +- David Brownell for mentoring the SPI-side driver development. +- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version. +- Nadir Billimoria for help interpreting the circuit schematic. diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst similarity index 97% rename from Documentation/spi/spi-sc18is602 rename to Documentation/spi/spi-sc18is602.rst index 0feffd5af411..2a31dc722321 100644 --- a/Documentation/spi/spi-sc18is602 +++ b/Documentation/spi/spi-sc18is602.rst @@ -1,8 +1,11 @@ +=========================== Kernel driver spi-sc18is602 =========================== Supported chips: + * NXP SI18IS602/602B/603 + Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf Author: diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst similarity index 93% rename from Documentation/spi/spi-summary rename to Documentation/spi/spi-summary.rst index 1a63194b74d7..f1daffe10d78 100644 --- a/Documentation/spi/spi-summary +++ b/Documentation/spi/spi-summary.rst @@ -1,3 +1,4 @@ +==================================== Overview of Linux kernel SPI support ==================================== @@ -139,12 +140,14 @@ a command and then reading its response. There are two types of SPI driver, here called: - Controller drivers ... controllers may be built into System-On-Chip + Controller drivers ... + controllers may be built into System-On-Chip processors, and often support both Master and Slave roles. These drivers touch hardware registers and may use DMA. Or they can be PIO bitbangers, needing just GPIO pins. - Protocol drivers ... these pass messages through the controller + Protocol drivers ... + these pass messages through the controller driver to communicate with a Slave or Master device on the other side of an SPI link. @@ -160,7 +163,7 @@ those two types of drivers. There is a minimal core of SPI programming interfaces, focussing on using the driver model to connect controller and protocol drivers using device tables provided by board specific initialization code. SPI -shows up in sysfs in several locations: +shows up in sysfs in several locations:: /sys/devices/.../CTLR ... physical node for a given SPI controller @@ -168,7 +171,7 @@ shows up in sysfs in several locations: chipselect C, accessed through CTLR. /sys/bus/spi/devices/spiB.C ... symlink to that physical - .../CTLR/spiB.C device + .../CTLR/spiB.C device /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver that should be used with this device (for hotplug/coldplug) @@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices. That information is normally provided by board-specific code, even for chips that do support some of automated discovery/enumeration. -DECLARE CONTROLLERS +Declare Controllers +^^^^^^^^^^^^^^^^^^^ The first kind of information is a list of what SPI controllers exist. For System-on-Chip (SOC) based boards, these will usually be platform @@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several SPI-capable controllers, and only the ones actually usable on a given board should normally be set up and registered. -So for example arch/.../mach-*/board-*.c files might have code like: +So for example arch/.../mach-*/board-*.c files might have code like:: #include /* for mysoc_spi_data */ @@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like: ... } -And SOC-specific utility code might look something like: +And SOC-specific utility code might look something like:: #include @@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use an external clock, where another derives the SPI clock from current settings of some master clock. - -DECLARE SLAVE DEVICES +Declare Slave Devices +^^^^^^^^^^^^^^^^^^^^^ The second kind of information is a list of what SPI slave devices exist on the target board, often with some board-specific data needed for the @@ -278,7 +282,7 @@ driver to work correctly. Normally your arch/.../mach-*/board-*.c files would provide a small table listing the SPI devices on each board. (This would typically be only a -small handful.) That might look like: +small handful.) That might look like:: static struct ads7846_platform_data ads_info = { .vref_delay_usecs = 100, @@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it. Then your board initialization code would register that table with the SPI infrastructure, so that it's available later when the SPI master controller -driver is registered: +driver is registered:: spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info)); @@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those. The widely used "card" style computers bundle memory, cpu, and little else onto a card that's maybe just thirty square centimeters. On such systems, -your arch/.../mach-.../board-*.c file would primarily provide information +your ``arch/.../mach-.../board-*.c`` file would primarily provide information about the devices on the mainboard into which such a card is plugged. That certainly includes SPI devices hooked up through the card connectors! -NON-STATIC CONFIGURATIONS +Non-static Configurations +^^^^^^^^^^^^^^^^^^^^^^^^^ Developer boards often play by different rules than product boards, and one example is the potential need to hotplug SPI devices and/or controllers. @@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"? Most SPI drivers are currently kernel drivers, but there's also support for userspace drivers. Here we talk only about kernel drivers. -SPI protocol drivers somewhat resemble platform device drivers: +SPI protocol drivers somewhat resemble platform device drivers:: static struct spi_driver CHIP_driver = { .driver = { @@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code might look like this unless you're creating a device which is managing a bus (appearing under /sys/class/spi_master). +:: + static int CHIP_probe(struct spi_device *spi) { struct CHIP *chip; @@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master". Use spi_alloc_master() to allocate the master, and spi_master_get_devdata() to get the driver-private data allocated for that device. +:: + struct spi_master *master; struct CONTROLLER *c; @@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master() will reverse the effect of spi_register_master(). -BUS NUMBERING +Bus Numbering +^^^^^^^^^^^^^ Bus numbering is important, since that's how Linux identifies a given SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On @@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat this as a non-static configuration (see above). -SPI MASTER METHODS +SPI Master Methods +^^^^^^^^^^^^^^^^^^ - master->setup(struct spi_device *spi) +``master->setup(struct spi_device *spi)`` This sets up the device clock rate, SPI mode, and word sizes. Drivers may change the defaults provided by board_info, and then call spi_setup(spi) to invoke this routine. It may sleep. @@ -528,37 +539,37 @@ SPI MASTER METHODS change them right away ... otherwise drivers could corrupt I/O that's in progress for other SPI devices. - ** BUG ALERT: for some reason the first version of - ** many spi_master drivers seems to get this wrong. - ** When you code setup(), ASSUME that the controller - ** is actively processing transfers for another device. + .. note:: - master->cleanup(struct spi_device *spi) + BUG ALERT: for some reason the first version of + many spi_master drivers seems to get this wrong. + When you code setup(), ASSUME that the controller + is actively processing transfers for another device. + +``master->cleanup(struct spi_device *spi)`` Your controller driver may use spi_device.controller_state to hold state it dynamically associates with that device. If you do that, be sure to provide the cleanup() method to free that state. - master->prepare_transfer_hardware(struct spi_master *master) +``master->prepare_transfer_hardware(struct spi_master *master)`` This will be called by the queue mechanism to signal to the driver that a message is coming in soon, so the subsystem requests the driver to prepare the transfer hardware by issuing this call. This may sleep. - master->unprepare_transfer_hardware(struct spi_master *master) +``master->unprepare_transfer_hardware(struct spi_master *master)`` This will be called by the queue mechanism to signal to the driver that there are no more messages pending in the queue and it may relax the hardware (e.g. by power management calls). This may sleep. - master->transfer_one_message(struct spi_master *master, - struct spi_message *mesg) +``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)`` The subsystem calls the driver to transfer a single message while queuing transfers that arrive in the meantime. When the driver is finished with this message, it must call spi_finalize_current_message() so the subsystem can issue the next message. This may sleep. - master->transfer_one(struct spi_master *master, struct spi_device *spi, - struct spi_transfer *transfer) +``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)`` The subsystem calls the driver to transfer a single transfer while queuing transfers that arrive in the meantime. When the driver is finished with this transfer, it must call @@ -568,19 +579,20 @@ SPI MASTER METHODS not call your transfer_one callback. Return values: - negative errno: error - 0: transfer is finished - 1: transfer is still in progress - master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, - u8 hold_clk_cycles, u8 inactive_clk_cycles) + * negative errno: error + * 0: transfer is finished + * 1: transfer is still in progress + +``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)`` This method allows SPI client drivers to request SPI master controller for configuring device specific CS setup, hold and inactive timing requirements. - DEPRECATED METHODS +Deprecated Methods +^^^^^^^^^^^^^^^^^^ - master->transfer(struct spi_device *spi, struct spi_message *message) +``master->transfer(struct spi_device *spi, struct spi_message *message)`` This must not sleep. Its responsibility is to arrange that the transfer happens and its complete() callback is issued. The two will normally happen later, after other transfers complete, and @@ -590,7 +602,8 @@ SPI MASTER METHODS implemented. -SPI MESSAGE QUEUE +SPI Message Queue +^^^^^^^^^^^^^^^^^ If you are happy with the standard queueing mechanism provided by the SPI subsystem, just implement the queued methods specified above. Using @@ -619,13 +632,13 @@ THANKS TO Contributors to Linux-SPI discussions include (in alphabetical order, by last name): -Mark Brown -David Brownell -Russell King -Grant Likely -Dmitry Pervushin -Stephen Street -Mark Underwood -Andrew Victor -Linus Walleij -Vitaly Wool +- Mark Brown +- David Brownell +- Russell King +- Grant Likely +- Dmitry Pervushin +- Stephen Street +- Mark Underwood +- Andrew Victor +- Linus Walleij +- Vitaly Wool diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst similarity index 90% rename from Documentation/spi/spidev rename to Documentation/spi/spidev.rst index 3d14035b1766..f05dbc5ccdbc 100644 --- a/Documentation/spi/spidev +++ b/Documentation/spi/spidev.rst @@ -1,7 +1,13 @@ +================= +SPI userspace API +================= + SPI devices have a limited userspace API, supporting basic half-duplex read() and write() access to SPI slave devices. Using ioctl() requests, full duplex transfers and device I/O configuration are also available. +:: + #include #include #include @@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev. busybox; it's less featureful, but often enough.) For a SPI device with chipselect C on bus B, you should see: - /dev/spidevB.C ... character special device, major number 153 with + /dev/spidevB.C ... + character special device, major number 153 with a dynamically chosen minor device number. This is the node that userspace programs will open, created by "udev" or "mdev". - /sys/devices/.../spiB.C ... as usual, the SPI device node will + /sys/devices/.../spiB.C ... + as usual, the SPI device node will be a child of its SPI master controller. - /sys/class/spidev/spidevB.C ... created when the "spidev" driver + /sys/class/spidev/spidevB.C ... + created when the "spidev" driver binds to that device. (Directory or symlink, based on whether or not you enabled the "deprecated sysfs files" Kconfig option.) @@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request. Several ioctl() requests let your driver read or override the device's current settings for data transfer parameters: - SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will + SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... + pass a pointer to a byte which will return (RD) or assign (WR) the SPI transfer mode. Use the constants SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, @@ -88,22 +98,26 @@ settings for data transfer parameters: Note that this request is limited to SPI mode flags that fit in a single byte. - SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t + SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... + pass a pointer to a uin32_t which will return (RD) or assign (WR) the full SPI transfer mode, not limited to the bits that fit in one byte. - SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte + SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... + pass a pointer to a byte which will return (RD) or assign (WR) the bit justification used to transfer SPI words. Zero indicates MSB-first; other values indicate the less common LSB-first encoding. In both cases the specified value is right-justified in each word, so that unused (TX) or undefined (RX) bits are in the MSBs. - SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to + SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... + pass a pointer to a byte which will return (RD) or assign (WR) the number of bits in each SPI transfer word. The value zero signifies eight bits. - SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a + SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... + pass a pointer to a u32 which will return (RD) or assign (WR) the maximum SPI transfer speed, in Hz. The controller can't necessarily assign that specific clock speed. diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c index d28974ad9e0e..6cb02299a215 100644 --- a/drivers/iio/dummy/iio_simple_dummy.c +++ b/drivers/iio/dummy/iio_simple_dummy.c @@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd) * i2c: * Documentation/i2c/writing-clients.rst * spi: - * Documentation/spi/spi-summary + * Documentation/spi/spi-summary.rst */ static const struct iio_sw_device_ops iio_dummy_device_ops = { .probe = iio_dummy_probe, diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig index 3a1d8f1170de..d5a24fe983e7 100644 --- a/drivers/spi/Kconfig +++ b/drivers/spi/Kconfig @@ -543,7 +543,7 @@ config SPI_PXA2XX help This enables using a PXA2xx or Sodaville SSP port as a SPI master controller. The driver can be configured to use any SSP port and - additional documentation can be found a Documentation/spi/pxa2xx. + additional documentation can be found a Documentation/spi/pxa2xx.rst. config SPI_PXA2XX_PCI def_tristate SPI_PXA2XX && PCI && COMMON_CLK diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c index 8c77d1114ad3..7e71a351f3b7 100644 --- a/drivers/spi/spi-butterfly.c +++ b/drivers/spi/spi-butterfly.c @@ -23,7 +23,7 @@ * with a battery powered AVR microcontroller and lots of goodies. You * can use GCC to develop firmware for this. * - * See Documentation/spi/butterfly for information about how to build + * See Documentation/spi/butterfly.rst for information about how to build * and use this custom parallel port cable. */ diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c index f18f912c9dea..174dba29b1dd 100644 --- a/drivers/spi/spi-lm70llp.c +++ b/drivers/spi/spi-lm70llp.c @@ -34,7 +34,7 @@ * available (on page 4) here: * http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf * - * Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is + * Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is * (heavily) based on spi-butterfly by David Brownell. * * The LM70 LLP connects to the PC parallel port in the following manner: diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h index e066d3b0d6d8..0e91489edfe6 100644 --- a/include/linux/platform_data/sc18is602.h +++ b/include/linux/platform_data/sc18is602.h @@ -4,7 +4,7 @@ * * Copyright (C) 2012 Guenter Roeck * - * For further information, see the Documentation/spi/spi-sc18is602 file. + * For further information, see the Documentation/spi/spi-sc18is602.rst file. */ /** From f139291c713069b5fa826ff509190efb5df83860 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:08:51 -0300 Subject: [PATCH 40/67] docs: fs: cifs: convert to ReST and add to admin-guide book The filenames for cifs documentation is not using the same convention as almost all Kernel documents is using. So, rename them to a more appropriate name. Then, manually convert the documentation files for CIFS to ReST. By doing a manual conversion, we can preserve the original author's style, while making it to look more like the other Kernel documents. Most of the conversion here is trivial. The most complex one was the README file (which was renamed to usage.rst). Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- .../AUTHORS => admin-guide/cifs/authors.rst} | 64 +- .../CHANGES => admin-guide/cifs/changes.rst} | 4 + Documentation/admin-guide/cifs/index.rst | 21 + .../cifs/introduction.rst} | 8 + .../cifs/TODO => admin-guide/cifs/todo.rst} | 87 +-- .../README => admin-guide/cifs/usage.rst} | 560 +++++++++++------- .../cifs/winucase_convert.pl | 0 Documentation/admin-guide/index.rst | 1 + MAINTAINERS | 2 +- 9 files changed, 460 insertions(+), 287 deletions(-) rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%) rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%) create mode 100644 Documentation/admin-guide/cifs/index.rst rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%) rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%) rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%) rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%) diff --git a/Documentation/filesystems/cifs/AUTHORS b/Documentation/admin-guide/cifs/authors.rst similarity index 60% rename from Documentation/filesystems/cifs/AUTHORS rename to Documentation/admin-guide/cifs/authors.rst index 75865da2ce14..b02d6dd6c070 100644 --- a/Documentation/filesystems/cifs/AUTHORS +++ b/Documentation/admin-guide/cifs/authors.rst @@ -1,5 +1,10 @@ +======= +Authors +======= + Original Author -=============== +--------------- + Steve French (sfrench@samba.org) The author wishes to express his appreciation and thanks to: @@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client) for proving years ago that very good smb/cifs clients could be done on Unix-like -operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John +operating systems. Volker Lendecke, Andrew Tridgell, Urban Widmark, John Newbigin and others for their work on the Linux smbfs module. Thanks to the other members of the Storage Network Industry Association CIFS Technical Workgroup for their work specifying this highly complex protocol and finally @@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement. Patch Contributors ------------------ -Zwane Mwaikambo -Andi Kleen -Amrut Joshi -Shobhit Dayal -Sergey Vlasov -Richard Hughes -Yury Umanets -Mark Hamzy (for some of the early cifs IPv6 work) -Domen Puncer -Jesper Juhl (in particular for lots of whitespace/formatting cleanup) -Vince Negri and Dave Stahl (for finding an important caching bug) -Adrian Bunk (kcalloc cleanups) -Miklos Szeredi -Kazeon team for various fixes especially for 2.4 version. -Asser Ferno (Change Notify support) -Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup -Gunter Kukkukk (testing and suggestions for support of old servers) -Igor Mammedov (DFS support) -Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code) -Scott Lovenberg -Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features) -Aurelien Aptel (for DFS SMB3 work and some key bug fixes) -Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding) -Shirish Pargaonkar (for many ACL patches over the years) -Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security) -Paulo Alcantara -Long Li (some great work on RDMA, SMB Direct) + +- Zwane Mwaikambo +- Andi Kleen +- Amrut Joshi +- Shobhit Dayal +- Sergey Vlasov +- Richard Hughes +- Yury Umanets +- Mark Hamzy (for some of the early cifs IPv6 work) +- Domen Puncer +- Jesper Juhl (in particular for lots of whitespace/formatting cleanup) +- Vince Negri and Dave Stahl (for finding an important caching bug) +- Adrian Bunk (kcalloc cleanups) +- Miklos Szeredi +- Kazeon team for various fixes especially for 2.4 version. +- Asser Ferno (Change Notify support) +- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup +- Gunter Kukkukk (testing and suggestions for support of old servers) +- Igor Mammedov (DFS support) +- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code) +- Scott Lovenberg +- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features) +- Aurelien Aptel (for DFS SMB3 work and some key bug fixes) +- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding) +- Shirish Pargaonkar (for many ACL patches over the years) +- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security) +- Paulo Alcantara +- Long Li (some great work on RDMA, SMB Direct) Test case and Bug Report contributors diff --git a/Documentation/filesystems/cifs/CHANGES b/Documentation/admin-guide/cifs/changes.rst similarity index 91% rename from Documentation/filesystems/cifs/CHANGES rename to Documentation/admin-guide/cifs/changes.rst index 1df7f4910eb2..71f2ecb62299 100644 --- a/Documentation/filesystems/cifs/CHANGES +++ b/Documentation/admin-guide/cifs/changes.rst @@ -1,3 +1,7 @@ +======= +Changes +======= + See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary information (that may be easier to read than parsing the output of "git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst new file mode 100644 index 000000000000..fad5268635f5 --- /dev/null +++ b/Documentation/admin-guide/cifs/index.rst @@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==== +CIFS +==== + +.. toctree:: + :maxdepth: 2 + + introduction + usage + todo + changes + authors + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/filesystems/cifs/cifs.txt b/Documentation/admin-guide/cifs/introduction.rst similarity index 98% rename from Documentation/filesystems/cifs/cifs.txt rename to Documentation/admin-guide/cifs/introduction.rst index 1be3d21c286e..0b98f672d36f 100644 --- a/Documentation/filesystems/cifs/cifs.txt +++ b/Documentation/admin-guide/cifs/introduction.rst @@ -1,3 +1,7 @@ +============ +Introduction +============ + This is the client VFS module for the SMB3 NAS protocol as well as for older dialects such as the Common Internet File System (CIFS) protocol which was the successor to the Server Message Block @@ -33,7 +37,9 @@ tools (including smbinfo and setcifsacl) that can be obtained from https://git.samba.org/?p=cifs-utils.git + or + git://git.samba.org/cifs-utils.git mount.cifs should be installed in the directory with the other mount helpers. @@ -41,5 +47,7 @@ For more information on the module see the project wiki page at https://wiki.samba.org/index.php/LinuxCIFS + and + https://wiki.samba.org/index.php/LinuxCIFS_utils diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/admin-guide/cifs/todo.rst similarity index 58% rename from Documentation/filesystems/cifs/TODO rename to Documentation/admin-guide/cifs/todo.rst index 9267f3fb131f..95f18e8c9b8a 100644 --- a/Documentation/filesystems/cifs/TODO +++ b/Documentation/admin-guide/cifs/todo.rst @@ -1,3 +1,7 @@ +==== +TODO +==== + Version 2.14 December 21, 2018 A Partial List of Missing Features @@ -8,6 +12,7 @@ for visible, important contributions to this module. Here is a partial list of the known problems and missing features: a) SMB3 (and SMB3.1.1) missing optional features: + - multichannel (started), integration with RDMA - directory leases (improved metadata caching), started (root dir only) - T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl @@ -16,45 +21,46 @@ a) SMB3 (and SMB3.1.1) missing optional features: b) improved sparse file support c) Directory entry caching relies on a 1 second timer, rather than -using Directory Leases, currently only the root file handle is cached longer + using Directory Leases, currently only the root file handle is cached longer d) quota support (needs minor kernel change since quota calls -to make it to network filesystems or deviceless filesystems) + to make it to network filesystems or deviceless filesystems) e) Additional use cases where we use "compoounding" (e.g. open/query/close -and open/setinfo/close) to reduce the number of roundtrips, and also -open to reduce redundant opens (using deferred close and reference counts more). + and open/setinfo/close) to reduce the number of roundtrips, and also + open to reduce redundant opens (using deferred close and reference counts + more). f) Finish inotify support so kde and gnome file list windows -will autorefresh (partially complete by Asser). Needs minor kernel -vfs change to support removing D_NOTIFY on a file. + will autorefresh (partially complete by Asser). Needs minor kernel + vfs change to support removing D_NOTIFY on a file. g) Add GUI tool to configure /proc/fs/cifs settings and for display of -the CIFS statistics (started) + the CIFS statistics (started) h) implement support for security and trusted categories of xattrs -(requires minor protocol extension) to enable better support for SELINUX + (requires minor protocol extension) to enable better support for SELINUX i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol feature (may be especially useful for virtualization). j) Create UID mapping facility so server UIDs can be mapped on a per -mount or a per server basis to client UIDs or nobody if no mapping -exists. Also better integration with winbind for resolving SID owners + mount or a per server basis to client UIDs or nobody if no mapping + exists. Also better integration with winbind for resolving SID owners k) Add tools to take advantage of more smb3 specific ioctls and features -(passthrough ioctl/fsctl for sending various SMB3 fsctls to the server -is in progress, and a passthrough query_info call is already implemented -in cifs.ko to allow smb3 info levels queries to be sent from userspace) + (passthrough ioctl/fsctl for sending various SMB3 fsctls to the server + is in progress, and a passthrough query_info call is already implemented + in cifs.ko to allow smb3 info levels queries to be sent from userspace) l) encrypted file support m) improved stats gathering tools (perhaps integration with nfsometer?) -to extend and make easier to use what is currently in /proc/fs/cifs/Stats + to extend and make easier to use what is currently in /proc/fs/cifs/Stats -n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed -file attribute via chflags) and improve user space tools for managing and -viewing them. +n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to + compressed file attribute via chflags) and improve user space tools for + managing and viewing them. o) mount helper GUI (to simplify the various configuration options on mount) @@ -65,55 +71,56 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space different servers, and the server we are connected to has gone down. q) Allow mount.cifs to be more verbose in reporting errors with dialect -or unsupported feature errors. + or unsupported feature errors. r) updating cifs documentation, and user guide. s) Addressing bugs found by running a broader set of xfstests in standard -file system xfstest suite. + file system xfstest suite. t) split cifs and smb3 support into separate modules so legacy (and less -secure) CIFS dialect can be disabled in environments that don't need it -and simplify the code. + secure) CIFS dialect can be disabled in environments that don't need it + and simplify the code. v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added -so far). + so far). w) Add support for additional strong encryption types, and additional spnego -authentication mechanisms (see MS-SMB2) + authentication mechanisms (see MS-SMB2) + +Known Bugs +========== -KNOWN BUGS -==================================== See http://bugzilla.samba.org - search on product "CifsVFS" for current bug list. Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS) 1) existing symbolic links (Windows reparse points) are recognized but -can not be created remotely. They are implemented for Samba and those that -support the CIFS Unix extensions, although earlier versions of Samba -overly restrict the pathnames. + can not be created remotely. They are implemented for Samba and those that + support the CIFS Unix extensions, although earlier versions of Samba + overly restrict the pathnames. 2) follow_link and readdir code does not follow dfs junctions -but recognizes them + but recognizes them Misc testing to do ================== 1) check out max path names and max path name components against various server -types. Try nested symlinks (8 deep). Return max path name in stat -f information + types. Try nested symlinks (8 deep). Return max path name in stat -f information 2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test -cifs/smb3 better + cifs/smb3 better -3) Additional performance testing and optimization using iozone and similar - -there are some easy changes that can be done to parallelize sequential writes, -and when signing is disabled to request larger read sizes (larger than -negotiated size) and send larger write sizes to modern servers. +3) Additional performance testing and optimization using iozone and similar - + there are some easy changes that can be done to parallelize sequential writes, + and when signing is disabled to request larger read sizes (larger than + negotiated size) and send larger write sizes to modern servers. 4) More exhaustively test against less common servers 5) Continue to extend the smb3 "buildbot" which does automated xfstesting -against Windows, Samba and Azure currently - to add additional tests and -to allow the buildbot to execute the tests faster. The URL for the -buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com + against Windows, Samba and Azure currently - to add additional tests and + to allow the buildbot to execute the tests faster. The URL for the + buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com 6) Address various coverity warnings (most are not bugs per-se, but -the more warnings are addressed, the easier it is to spot real -problems that static analyzers will point out in the future). + the more warnings are addressed, the easier it is to spot real + problems that static analyzers will point out in the future). diff --git a/Documentation/filesystems/cifs/README b/Documentation/admin-guide/cifs/usage.rst similarity index 72% rename from Documentation/filesystems/cifs/README rename to Documentation/admin-guide/cifs/usage.rst index 4a804619cff2..d3fb67b8a976 100644 --- a/Documentation/filesystems/cifs/README +++ b/Documentation/admin-guide/cifs/usage.rst @@ -1,53 +1,61 @@ +===== +Usage +===== + This module supports the SMB3 family of advanced network protocols (as well as older dialects, originally called "CIFS" or SMB1). The CIFS VFS module for Linux supports many advanced network filesystem features such as hierarchical DFS like namespace, hardlinks, locking and more. -It was designed to comply with the SNIA CIFS Technical Reference (which -supersedes the 1992 X/Open SMB Standard) as well as to perform best practice -practical interoperability with Windows 2000, Windows XP, Samba and equivalent +It was designed to comply with the SNIA CIFS Technical Reference (which +supersedes the 1992 X/Open SMB Standard) as well as to perform best practice +practical interoperability with Windows 2000, Windows XP, Samba and equivalent servers. This code was developed in participation with the Protocol Freedom Information Foundation. CIFS and now SMB3 has now become a defacto standard for interoperating between Macs and Windows and major NAS appliances. Please see - MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) - http://protocolfreedom.org/ and - http://samba.org/samba/PFIF/ +MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification) +http://protocolfreedom.org/ and +http://samba.org/samba/PFIF/ for more details. For questions or bug reports please contact: + smfrench@gmail.com See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils -Build instructions: +Build instructions ================== + For Linux: + 1) Download the kernel (e.g. from http://www.kernel.org) -and change directory into the top of the kernel directory tree -(e.g. /usr/src/linux-2.5.73) + and change directory into the top of the kernel directory tree + (e.g. /usr/src/linux-2.5.73) 2) make menuconfig (or make xconfig) 3) select cifs from within the network filesystem choices 4) save and exit 5) make -Installation instructions: +Installation instructions ========================= + If you have built the CIFS vfs as module (successfully) simply -type "make modules_install" (or if you prefer, manually copy the file to +type ``make modules_install`` (or if you prefer, manually copy the file to the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko). If you have built the CIFS vfs into the kernel itself, follow the instructions for your distribution on how to install a new kernel (usually you -would simply type "make install"). +would simply type ``make install``). If you do not have the utility mount.cifs (in the Samba 4.x source tree and on the CIFS VFS web site) copy it to the same directory in which mount helpers reside (usually /sbin). Although the helper software is not -required, mount.cifs is recommended. Most distros include a "cifs-utils" +required, mount.cifs is recommended. Most distros include a ``cifs-utils`` package that includes this utility so it is recommended to install this. Note that running the Winbind pam/nss module (logon service) on all of your @@ -57,13 +65,16 @@ found at cifs-utils.git on git.samba.org If cifs is built as a module, then the size and number of network buffers and maximum number of simultaneous requests to one server can be configured. -Changing these from their defaults is not recommended. By executing modinfo +Changing these from their defaults is not recommended. By executing modinfo:: + modinfo kernel/fs/cifs/cifs.ko + on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made at module initialization time (by running insmod cifs.ko) can be seen. Recommendations =============== + To improve security the SMB2.1 dialect or later (usually will get SMB3) is now the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0" on mount (or vers=2.0 for Windows Vista). Note that the CIFS (vers=1.0) is @@ -72,156 +83,168 @@ many advanced security features such as downgrade attack detection and encrypted shares and stronger signing and authentication algorithms. There are additional mount options that may be helpful for SMB3 to get improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1): - "mfsymlinks" and "cifsacl" and "idsfromsid" + + ``mfsymlinks`` and ``cifsacl`` and ``idsfromsid`` Allowing User Mounts ==================== + To permit users to mount and unmount over directories they own is possible with the cifs vfs. A way to enable such mounting is to mark the mount.cifs -utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to +utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to umount shares they mount requires + 1) mount.cifs version 1.4 or later 2) an entry for the share in /etc/fstab indicating that a user may -unmount it e.g. -//server/usersharename /mnt/username cifs user 0 0 + unmount it e.g.:: -Note that when the mount.cifs utility is run suid (allowing user mounts), -in order to reduce risks, the "nosuid" mount flag is passed in on mount to + //server/usersharename /mnt/username cifs user 0 0 + +Note that when the mount.cifs utility is run suid (allowing user mounts), +in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to disallow execution of an suid program mounted on the remote target. When mount is executed as root, nosuid is not passed in by default, and execution of suid programs on the remote target would be enabled -by default. This can be changed, as with nfs and other filesystems, -by simply specifying "nosuid" among the mount options. For user mounts -though to be able to pass the suid flag to mount requires rebuilding +by default. This can be changed, as with nfs and other filesystems, +by simply specifying ``nosuid`` among the mount options. For user mounts +though to be able to pass the suid flag to mount requires rebuilding mount.cifs with the following flag: CIFS_ALLOW_USR_SUID There is a corresponding manual page for cifs mounting in the Samba 3.0 and -later source tree in docs/manpages/mount.cifs.8 +later source tree in docs/manpages/mount.cifs.8 Allowing User Unmounts ====================== + To permit users to ummount directories that they have user mounted (see above), -the utility umount.cifs may be used. It may be invoked directly, or if +the utility umount.cifs may be used. It may be invoked directly, or if umount.cifs is placed in /sbin, umount can invoke the cifs umount helper (at least for most versions of the umount utility) for umount of cifs mounts, unless umount is invoked with -i (which will avoid invoking a umount helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked -as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions +as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions allow adding entries to a file to the /etc/permissions file to achieve the equivalent suid effect). For this utility to succeed the target path must be a cifs mount, and the uid of the current user must match the uid of the user who mounted the resource. -Also note that the customary way of allowing user mounts and unmounts is +Also note that the customary way of allowing user mounts and unmounts is (instead of using mount.cifs and unmount.cifs as suid) to add a line to the file /etc/fstab for each //server/share you wish to mount, but this can become unwieldy when potential mount targets include many or unpredictable UNC names. -Samba Considerations +Samba Considerations ==================== + Most current servers support SMB2.1 and SMB3 which are more secure, but there are useful protocol extensions for the older less secure CIFS dialect, so to get the maximum benefit if mounting using the older dialect (CIFS/SMB1), we recommend using a server that supports the SNIA CIFS Unix Extensions standard (e.g. almost any version of Samba ie version 2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers. -Note that uid, gid and file permissions will display default values if you do -not have a server that supports the Unix extensions for CIFS (such as Samba -2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add -the line: +Note that uid, gid and file permissions will display default values if you do +not have a server that supports the Unix extensions for CIFS (such as Samba +2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add +the line:: unix extensions = yes - -to your smb.conf file on the server. Note that the following smb.conf settings -are also useful (on the Samba server) when the majority of clients are Unix or -Linux: + +to your smb.conf file on the server. Note that the following smb.conf settings +are also useful (on the Samba server) when the majority of clients are Unix or +Linux:: case sensitive = yes - delete readonly = yes + delete readonly = yes ea support = yes Note that server ea support is required for supporting xattrs from the Linux -cifs client, and that EA support is present in later versions of Samba (e.g. +cifs client, and that EA support is present in later versions of Samba (e.g. 3.0.6 and later (also EA support works in all versions of Windows, at least to shares on NTFS filesystems). Extended Attribute (xattr) support is an optional feature of most Linux filesystems which may require enabling via make menuconfig. Client support for extended attributes (user xattr) can be -disabled on a per-mount basis by specifying "nouser_xattr" on mount. +disabled on a per-mount basis by specifying ``nouser_xattr`` on mount. The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers -version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and +version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and then POSIX support in the CIFS configuration options when building the cifs module. POSIX ACL support can be disabled on a per mount basic by specifying -"noacl" on mount. - -Some administrators may want to change Samba's smb.conf "map archive" and -"create mask" parameters from the default. Unless the create mask is changed +``noacl`` on mount. + +Some administrators may want to change Samba's smb.conf ``map archive`` and +``create mask`` parameters from the default. Unless the create mask is changed newly created files can end up with an unnecessarily restrictive default mode, which may not be what you want, although if the CIFS Unix extensions are enabled on the server and client, subsequent setattr calls (e.g. chmod) can -fix the mode. Note that creating special devices (mknod) remotely -may require specifying a mkdev function to Samba if you are not using +fix the mode. Note that creating special devices (mknod) remotely +may require specifying a mkdev function to Samba if you are not using Samba 3.0.6 or later. For more information on these see the manual pages -("man smb.conf") on the Samba server system. Note that the cifs vfs, -unlike the smbfs vfs, does not read the smb.conf on the client system -(the few optional settings are passed in on mount via -o parameters instead). +(``man smb.conf``) on the Samba server system. Note that the cifs vfs, +unlike the smbfs vfs, does not read the smb.conf on the client system +(the few optional settings are passed in on mount via -o parameters instead). Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete -open files (required for strict POSIX compliance). Windows Servers already +open files (required for strict POSIX compliance). Windows Servers already supported this feature. Samba server does not allow symlinks that refer to files outside of the share, so in Samba versions prior to 3.0.6, most symlinks to -files with absolute paths (ie beginning with slash) such as: +files with absolute paths (ie beginning with slash) such as:: + ln -s /mnt/foo bar -would be forbidden. Samba 3.0.6 server or later includes the ability to create -such symlinks safely by converting unsafe symlinks (ie symlinks to server + +would be forbidden. Samba 3.0.6 server or later includes the ability to create +such symlinks safely by converting unsafe symlinks (ie symlinks to server files that are outside of the share) to a samba specific format on the server that is ignored by local server applications and non-cifs clients and that will not be traversed by the Samba server). This is opaque to the Linux client application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or later, but only for remote clients using the CIFS Unix extensions, and will be invisbile to Windows clients and typically will not affect local -applications running on the same server as Samba. +applications running on the same server as Samba. -Use instructions: +Use instructions ================ -Once the CIFS VFS support is built into the kernel or installed as a module + +Once the CIFS VFS support is built into the kernel or installed as a module (cifs.ko), you can use mount syntax like the following to access Samba or -Mac or Windows servers: +Mac or Windows servers:: mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword Before -o the option -v may be specified to make the mount.cifs -mount helper display the mount steps more verbosely. +mount helper display the mount steps more verbosely. After -o the following commonly used cifs vfs specific options -are supported: +are supported:: username= password= domain= - + Other cifs mount options are described below. Use of TCP names (in addition to ip addresses) is available if the mount helper (mount.cifs) is installed. If you do not trust the server to which are mounted, or if you do not have cifs signing enabled (and the physical network is insecure), consider use -of the standard mount options "noexec" and "nosuid" to reduce the risk of +of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of running an altered binary on your local system (downloaded from a hostile server or altered by a hostile router). Although mounting using format corresponding to the CIFS URL specification is not possible in mount.cifs yet, it is possible to use an alternate format for the server and sharename (which is somewhat similar to NFS style mount -syntax) instead of the more widely used UNC format (i.e. \\server\share): +syntax) instead of the more widely used UNC format (i.e. \\server\share):: + mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd When using the mount helper mount.cifs, passwords may be specified via alternate -mechanisms, instead of specifying it after -o using the normal "pass=" syntax +mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax on the command line: 1) By including it in a credential file. Specify credentials=filename as one -of the mount options. Credential files contain two lines - username=someuser - password=your_password +of the mount options. Credential files contain two lines:: + + username=someuser + password=your_password + 2) By specifying the password in the PASSWD environment variable (similarly -the user name can be taken from the USER environment variable). + the user name can be taken from the USER environment variable). 3) By specifying the password in a file by name via PASSWD_FILE 4) By specifying the password in a file by file descriptor via PASSWD_FD @@ -229,39 +252,47 @@ If no password is provided, mount.cifs will prompt for password entry Restrictions ============ -Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC -1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a + +Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC +1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a problem as most servers support this. Valid filenames differ between Windows and Linux. Windows typically restricts -filenames which contain certain reserved characters (e.g.the character : +filenames which contain certain reserved characters (e.g.the character : which is used to delimit the beginning of a stream name by Windows), while Linux allows a slightly wider set of valid characters in filenames. Windows servers can remap such characters when an explicit mapping is specified in -the Server's registry. Samba starting with version 3.10 will allow such +the Server's registry. Samba starting with version 3.10 will allow such filenames (ie those which contain valid Linux characters, which normally would be forbidden for Windows/CIFS semantics) as long as the server is configured for Unix Extensions (and the client has not disabled /proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option -"mapposix" can be used on CIFS (vers=1.0) to force the mapping of +``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of illegal Windows/NTFS/SMB characters to a remap range (this mount parm -is the default for SMB3). This remap ("mapposix") range is also +is the default for SMB3). This remap (``mapposix``) range is also compatible with Mac (and "Services for Mac" on some older Windows). CIFS VFS Mount Options ====================== A partial list of the supported mount options follows: - username The user name to use when trying to establish + + username + The user name to use when trying to establish the CIFS session. - password The user password. If the mount helper is + password + The user password. If the mount helper is installed, the user will be prompted for password if not supplied. - ip The ip address of the target server - unc The target server Universal Network Name (export) to - mount. - domain Set the SMB/CIFS workgroup name prepended to the + ip + The ip address of the target server + unc + The target server Universal Network Name (export) to + mount. + domain + Set the SMB/CIFS workgroup name prepended to the username during CIFS session establishment - forceuid Set the default uid for inodes to the uid + forceuid + Set the default uid for inodes to the uid passed in on mount. For mounts to servers which do support the CIFS Unix extensions, such as a properly configured Samba server, the server provides @@ -276,32 +307,39 @@ A partial list of the supported mount options follows: extensions, the default uid (and gid) returned on lookup of existing files will be the uid (gid) of the person who executed the mount (root, except when mount.cifs - is configured setuid for user mounts) unless the "uid=" + is configured setuid for user mounts) unless the ``uid=`` (gid) mount option is specified. Also note that permission checks (authorization checks) on accesses to a file occur at the server, but there are cases in which an administrator may want to restrict at the client as well. For those servers which do not report a uid/gid owner (such as Windows), permissions can also be checked at the - client, and a crude form of client side permission checking - can be enabled by specifying file_mode and dir_mode on + client, and a crude form of client side permission checking + can be enabled by specifying file_mode and dir_mode on the client. (default) - forcegid (similar to above but for the groupid instead of uid) (default) - noforceuid Fill in file owner information (uid) by requesting it from + forcegid + (similar to above but for the groupid instead of uid) (default) + noforceuid + Fill in file owner information (uid) by requesting it from the server if possible. With this option, the value given in the uid= option (on mount) will only be used if the server can not support returning uids on inodes. - noforcegid (similar to above but for the group owner, gid, instead of uid) - uid Set the default uid for inodes, and indicate to the + noforcegid + (similar to above but for the group owner, gid, instead of uid) + uid + Set the default uid for inodes, and indicate to the cifs kernel driver which local user mounted. If the server supports the unix extensions the default uid is not used to fill in the owner fields of inodes (files) - unless the "forceuid" parameter is specified. - gid Set the default gid for inodes (similar to above). - file_mode If CIFS Unix extensions are not supported by the server + unless the ``forceuid`` parameter is specified. + gid + Set the default gid for inodes (similar to above). + file_mode + If CIFS Unix extensions are not supported by the server this overrides the default mode for file inodes. - fsc Enable local disk caching using FS-Cache (off by default). This - option could be useful to improve performance on a slow link, + fsc + Enable local disk caching using FS-Cache (off by default). This + option could be useful to improve performance on a slow link, heavily loaded server and/or network where reading from the disk is faster than reading from the server (over the network). This could also impact scalability positively as the @@ -310,18 +348,22 @@ A partial list of the supported mount options follows: type workloads. So, you need to consider carefully your workload/scenario before using this option. Currently, local disk caching is functional for CIFS files opened as read-only. - dir_mode If CIFS Unix extensions are not supported by the server + dir_mode + If CIFS Unix extensions are not supported by the server this overrides the default mode for directory inodes. - port attempt to contact the server on this tcp port, before + port + attempt to contact the server on this tcp port, before trying the usual ports (port 445, then 139). - iocharset Codepage used to convert local path names to and from + iocharset + Codepage used to convert local path names to and from Unicode. Unicode is used by default for network path names if the server supports it. If iocharset is not specified then the nls_default specified during the local client kernel build will be used. If server does not support Unicode, this parameter is unused. - rsize default read size (usually 16K). The client currently + rsize + default read size (usually 16K). The client currently can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize defaults to 16K and may be changed (from 8K to the maximum kmalloc size allowed by your kernel) at module install time @@ -333,10 +375,12 @@ A partial list of the supported mount options follows: newer servers (e.g. Samba 3.0.26 or later) do. rsize can be set from a minimum of 2048 to a maximum of 130048 (127K or CIFSMaxBufSize, whichever is smaller) - wsize default write size (default 57344) + wsize + default write size (default 57344) maximum wsize currently allowed by CIFS is 57344 (fourteen 4096 byte pages) - actimeo=n attribute cache timeout in seconds (default 1 second). + actimeo=n + attribute cache timeout in seconds (default 1 second). After this timeout, the cifs client requests fresh attribute information from the server. This option allows to tune the attribute cache timeout to suit the workload needs. Shorter @@ -345,49 +389,67 @@ A partial list of the supported mount options follows: of calls to the server at the expense of less stricter cache coherency checks (i.e. incorrect attribute cache for a short period of time). - rw mount the network share read-write (note that the + rw + mount the network share read-write (note that the server may still consider the share read-only) - ro mount network share read-only - version used to distinguish different versions of the + ro + mount network share read-only + version + used to distinguish different versions of the mount helper utility (not typically needed) - sep if first mount option (after the -o), overrides + sep + if first mount option (after the -o), overrides the comma as the separator between the mount - parms. e.g. + parms. e.g.:: + -o user=myname,password=mypassword,domain=mydom - could be passed instead with period as the separator by + + could be passed instead with period as the separator by:: + -o sep=.user=myname.password=mypassword.domain=mydom + this might be useful when comma is contained within username or password or domain. This option is less important when the cifs mount helper cifs.mount (version 1.1 or later) is used. - nosuid Do not allow remote executables with the suid bit + nosuid + Do not allow remote executables with the suid bit program to be executed. This is only meaningful for mounts to servers such as Samba which support the CIFS Unix Extensions. If you do not trust the servers in your network (your mount targets) it is recommended that you specify this option for greater security. - exec Permit execution of binaries on the mount. - noexec Do not permit execution of binaries on the mount. - dev Recognize block devices on the remote mount. - nodev Do not recognize devices on the remote mount. - suid Allow remote files on this mountpoint with suid enabled to + exec + Permit execution of binaries on the mount. + noexec + Do not permit execution of binaries on the mount. + dev + Recognize block devices on the remote mount. + nodev + Do not recognize devices on the remote mount. + suid + Allow remote files on this mountpoint with suid enabled to be executed (default for mounts when executed as root, nosuid is default for user mounts). - credentials Although ignored by the cifs kernel component, it is used by + credentials + Although ignored by the cifs kernel component, it is used by the mount helper, mount.cifs. When mount.cifs is installed it - opens and reads the credential file specified in order + opens and reads the credential file specified in order to obtain the userid and password arguments which are passed to the cifs vfs. - guest Although ignored by the kernel component, the mount.cifs + guest + Although ignored by the kernel component, the mount.cifs mount helper will not prompt the user for a password if guest is specified on the mount options. If no password is specified a null password will be used. - perm Client does permission checks (vfs_permission check of uid + perm + Client does permission checks (vfs_permission check of uid and gid of the file against the mode and desired operation), Note that this is in addition to the normal ACL check on the - target machine done by the server software. + target machine done by the server software. Client permission checking is enabled by default. - noperm Client does not do permission checks. This can expose + noperm + Client does not do permission checks. This can expose files on this mount to access by other users on the local client system. It is typically only needed when the server supports the CIFS Unix Extensions but the UIDs/GIDs on the @@ -399,7 +461,8 @@ A partial list of the supported mount options follows: Note that this does not affect the normal ACL check on the target machine done by the server software (of the server ACL against the user name provided at mount time). - serverino Use server's inode numbers instead of generating automatically + serverino + Use server's inode numbers instead of generating automatically incrementing inode numbers on the client. Although this will make it easier to spot hardlinked files (as they will have the same inode numbers) and inode numbers may be persistent, @@ -412,14 +475,16 @@ A partial list of the supported mount options follows: or the CIFS Unix Extensions equivalent and for those this mount option will have no effect. Exporting cifs mounts under nfsd requires this mount option on the cifs mount. - This is now the default if server supports the + This is now the default if server supports the required network operation. - noserverino Client generates inode numbers (rather than using the actual one + noserverino + Client generates inode numbers (rather than using the actual one from the server). These inode numbers will vary after unmount or reboot which can confuse some applications, but not all server filesystems support unique inode numbers. - setuids If the CIFS Unix extensions are negotiated with the server + setuids + If the CIFS Unix extensions are negotiated with the server the client will attempt to set the effective uid and gid of the local process on newly created files, directories, and devices (create, mkdir, mknod). If the CIFS Unix Extensions @@ -427,9 +492,10 @@ A partial list of the supported mount options follows: instead of using the default uid and gid specified on the mount, cache the new file's uid and gid locally which means that the uid for the file can change when the inode is - reloaded (or the user remounts the share). - nosetuids The client will not attempt to set the uid and gid on - on newly created files, directories, and devices (create, + reloaded (or the user remounts the share). + nosetuids + The client will not attempt to set the uid and gid on + on newly created files, directories, and devices (create, mkdir, mknod) which will result in the server setting the uid and gid to the default (usually the server uid of the user who mounted the share). Letting the server (rather than @@ -437,38 +503,49 @@ A partial list of the supported mount options follows: Unix Extensions are not negotiated then the uid and gid for new files will appear to be the uid (gid) of the mounter or the uid (gid) parameter specified on the mount. - netbiosname When mounting to servers via port 139, specifies the RFC1001 - source name to use to represent the client netbios machine + netbiosname + When mounting to servers via port 139, specifies the RFC1001 + source name to use to represent the client netbios machine name when doing the RFC1001 netbios session initialize. - direct Do not do inode data caching on files opened on this mount. + direct + Do not do inode data caching on files opened on this mount. This precludes mmapping files on this mount. In some cases with fast networks and little or no caching benefits on the client (e.g. when the application is doing large sequential - reads bigger than page size without rereading the same data) + reads bigger than page size without rereading the same data) this can provide better performance than the default - behavior which caches reads (readahead) and writes - (writebehind) through the local Linux client pagecache + behavior which caches reads (readahead) and writes + (writebehind) through the local Linux client pagecache if oplock (caching token) is granted and held. Note that direct allows write operations larger than page size to be sent to the server. - strictcache Use for switching on strict cache mode. In this mode the + strictcache + Use for switching on strict cache mode. In this mode the client read from the cache all the time it has Oplock Level II, otherwise - read from the server. All written data are stored in the cache, but if the client doesn't have Exclusive Oplock, it writes the data to the server. - rwpidforward Forward pid of a process who opened a file to any read or write + rwpidforward + Forward pid of a process who opened a file to any read or write operation on that file. This prevent applications like WINE from failing on read and write if we use mandatory brlock style. - acl Allow setfacl and getfacl to manage posix ACLs if server + acl + Allow setfacl and getfacl to manage posix ACLs if server supports them. (default) - noacl Do not allow setfacl and getfacl calls on this mount - user_xattr Allow getting and setting user xattrs (those attributes whose - name begins with "user." or "os2.") as OS/2 EAs (extended + noacl + Do not allow setfacl and getfacl calls on this mount + user_xattr + Allow getting and setting user xattrs (those attributes whose + name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended attributes) to the server. This allows support of the setfattr and getfattr utilities. (default) - nouser_xattr Do not allow getfattr/setfattr to get/set/list xattrs - mapchars Translate six of the seven reserved characters (not backslash) + nouser_xattr + Do not allow getfattr/setfattr to get/set/list xattrs + mapchars + Translate six of the seven reserved characters (not backslash):: + *?<>|: + to the remap range (above 0xF000), which also allows the CIFS client to recognize files created with such characters by Windows's POSIX emulation. This can @@ -477,39 +554,47 @@ A partial list of the supported mount options follows: whose names contain any of these seven characters). This has no effect if the server does not support Unicode on the wire. - nomapchars Do not translate any of these seven characters (default). - nocase Request case insensitive path name matching (case + nomapchars + Do not translate any of these seven characters (default). + nocase + Request case insensitive path name matching (case sensitive is the default if the server supports it). - (mount option "ignorecase" is identical to "nocase") - posixpaths If CIFS Unix extensions are supported, attempt to + (mount option ``ignorecase`` is identical to ``nocase``) + posixpaths + If CIFS Unix extensions are supported, attempt to negotiate posix path name support which allows certain characters forbidden in typical CIFS filenames, without requiring remapping. (default) - noposixpaths If CIFS Unix extensions are supported, do not request + noposixpaths + If CIFS Unix extensions are supported, do not request posix path name support (this may cause servers to reject creatingfile with certain reserved characters). - nounix Disable the CIFS Unix Extensions for this mount (tree + nounix + Disable the CIFS Unix Extensions for this mount (tree connection). This is rarely needed, but it may be useful in order to turn off multiple settings all at once (ie posix acls, posix locks, posix paths, symlink support and retrieving uids/gids/mode from the server) or to work around a bug in server which implement the Unix Extensions. - nobrl Do not send byte range lock requests to the server. + nobrl + Do not send byte range lock requests to the server. This is necessary for certain applications that break with cifs style mandatory byte range locks (and most cifs servers do not yet support requesting advisory byte range locks). - forcemandatorylock Even if the server supports posix (advisory) byte range + forcemandatorylock + Even if the server supports posix (advisory) byte range locking, send only mandatory lock requests. For some (presumably rare) applications, originally coded for DOS/Windows, which require Windows style mandatory byte range locking, they may be able to take advantage of this option, forcing the cifs client to only send mandatory locks even if the cifs server would support posix advisory locks. - "forcemand" is accepted as a shorter form of this mount + ``forcemand`` is accepted as a shorter form of this mount option. - nostrictsync If this mount option is set, when an application does an + nostrictsync + If this mount option is set, when an application does an fsync call then the cifs client does not send an SMB Flush to the server (to force the server to write all dirty data for this file immediately to disk), although cifs still sends @@ -522,41 +607,50 @@ A partial list of the supported mount options follows: crash. If this mount option is not set, by default cifs will send an SMB flush request (and wait for a response) on every fsync call. - nodfs Disable DFS (global name space support) even if the + nodfs + Disable DFS (global name space support) even if the server claims to support it. This can help work around a problem with parsing of DFS paths with Samba server versions 3.0.24 and 3.0.25. - remount remount the share (often used to change from ro to rw mounts - or vice versa) - cifsacl Report mode bits (e.g. on stat) based on the Windows ACL for - the file. (EXPERIMENTAL) - servern Specify the server 's netbios name (RFC1001 name) to use - when attempting to setup a session to the server. + remount + remount the share (often used to change from ro to rw mounts + or vice versa) + cifsacl + Report mode bits (e.g. on stat) based on the Windows ACL for + the file. (EXPERIMENTAL) + servern + Specify the server 's netbios name (RFC1001 name) to use + when attempting to setup a session to the server. This is needed for mounting to some older servers (such as OS/2 or Windows 98 and Windows ME) since they do not support a default server name. A server name can be up to 15 characters long and is usually uppercased. - sfu When the CIFS Unix Extensions are not negotiated, attempt to + sfu + When the CIFS Unix Extensions are not negotiated, attempt to create device files and fifos in a format compatible with Services for Unix (SFU). In addition retrieve bits 10-12 of the mode via the SETFILEBITS extended attribute (as SFU does). In the future the bottom 9 bits of the mode also will be emulated using queries of the security descriptor (ACL). - mfsymlinks Enable support for Minshall+French symlinks + mfsymlinks + Enable support for Minshall+French symlinks (see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks) This option is ignored when specified together with the 'sfu' option. Minshall+French symlinks are used even if the server supports the CIFS Unix Extensions. - sign Must use packet signing (helps avoid unwanted data modification + sign + Must use packet signing (helps avoid unwanted data modification by intermediate systems in the route). Note that signing does not work with lanman or plaintext authentication. - seal Must seal (encrypt) all data on this mounted share before + seal + Must seal (encrypt) all data on this mounted share before sending on the network. Requires support for Unix Extensions. Note that this differs from the sign mount option in that it causes encryption of data sent over this mounted share but other shares mounted to the same server are unaffected. - locallease This option is rarely needed. Fcntl F_SETLEASE is + locallease + This option is rarely needed. Fcntl F_SETLEASE is used by some applications such as Samba and NFSv4 server to check to see whether a file is cacheable. CIFS has no way to explicitly request a lease, but can check whether a file @@ -569,51 +663,73 @@ A partial list of the supported mount options follows: will allow the cifs client to check for leases (only) locally for files which are not oplocked instead of denying leases in that case. (EXPERIMENTAL) - sec Security mode. Allowed values are: - none attempt to connection as a null user (no name) - krb5 Use Kerberos version 5 authentication - krb5i Use Kerberos authentication and packet signing - ntlm Use NTLM password hashing (default) - ntlmi Use NTLM password hashing with signing (if + sec + Security mode. Allowed values are: + + none + attempt to connection as a null user (no name) + krb5 + Use Kerberos version 5 authentication + krb5i + Use Kerberos authentication and packet signing + ntlm + Use NTLM password hashing (default) + ntlmi + Use NTLM password hashing with signing (if /proc/fs/cifs/PacketSigningEnabled on or if - server requires signing also can be the default) - ntlmv2 Use NTLMv2 password hashing - ntlmv2i Use NTLMv2 password hashing with packet signing - lanman (if configured in kernel config) use older + server requires signing also can be the default) + ntlmv2 + Use NTLMv2 password hashing + ntlmv2i + Use NTLMv2 password hashing with packet signing + lanman + (if configured in kernel config) use older lanman hash -hard Retry file operations if server is not responding -soft Limit retries to unresponsive servers (usually only + hard + Retry file operations if server is not responding + soft + Limit retries to unresponsive servers (usually only one retry) before returning an error. (default) The mount.cifs mount helper also accepts a few mount options before -o including: +=============== =============================================================== -S take password from stdin (equivalent to setting the environment - variable "PASSWD_FD=0" + variable ``PASSWD_FD=0`` -V print mount.cifs version -? display simple usage information +=============== =============================================================== With most 2.6 kernel versions of modutils, the version of the cifs kernel module can be displayed via modinfo. Misc /proc/fs/cifs Flags and Debug Info ======================================= + Informational pseudo-files: + +======================= ======================================================= DebugData Displays information about active CIFS sessions and shares, features enabled as well as the cifs.ko version. Stats Lists summary resource usage information as well as per share statistics. +======================= ======================================================= Configuration pseudo-files: + +======================= ======================================================= SecurityFlags Flags which control security negotiation and also packet signing. Authentication (may/must) flags (e.g. for NTLM and/or NTLMv2) may be combined with the signing flags. Specifying two different password - hashing mechanisms (as "must use") on the other hand - does not make much sense. Default flags are - 0x07007 - (NTLM, NTLMv2 and packet signing allowed). The maximum + hashing mechanisms (as "must use") on the other hand + does not make much sense. Default flags are:: + + 0x07007 + + (NTLM, NTLMv2 and packet signing allowed). The maximum allowable flags if you want to allow mounts to servers using weaker password hashes is 0x37037 (lanman, plaintext, ntlm, ntlmv2, signing allowed). Some @@ -626,21 +742,21 @@ SecurityFlags Flags which control security negotiation and laintext passwords using the older lanman dialect form of the session setup SMB. (e.g. for authentication using plain text passwords, set the SecurityFlags - to 0x30030): - - may use packet signing 0x00001 - must use packet signing 0x01001 - may use NTLM (most common password hash) 0x00002 - must use NTLM 0x02002 - may use NTLMv2 0x00004 - must use NTLMv2 0x04004 - may use Kerberos security 0x00008 - must use Kerberos 0x08008 - may use lanman (weak) password hash 0x00010 - must use lanman password hash 0x10010 - may use plaintext passwords 0x00020 - must use plaintext passwords 0x20020 - (reserved for future packet encryption) 0x00040 + to 0x30030):: + + may use packet signing 0x00001 + must use packet signing 0x01001 + may use NTLM (most common password hash) 0x00002 + must use NTLM 0x02002 + may use NTLMv2 0x00004 + must use NTLMv2 0x04004 + may use Kerberos security 0x00008 + must use Kerberos 0x08008 + may use lanman (weak) password hash 0x00010 + must use lanman password hash 0x10010 + may use plaintext passwords 0x00020 + must use plaintext passwords 0x20020 + (reserved for future packet encryption) 0x00040 cifsFYI If set to non-zero value, additional debug information will be logged to the system error log. This field @@ -650,14 +766,19 @@ cifsFYI If set to non-zero value, additional debug information Some debugging statements are not compiled into the cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the kernel configuration. cifsFYI may be set to one or - nore of the following flags (7 sets them all): + nore of the following flags (7 sets them all):: + + +-----------------------------------------------+------+ + | log cifs informational messages | 0x01 | + +-----------------------------------------------+------+ + | log return codes from cifs entry points | 0x02 | + +-----------------------------------------------+------+ + | log slow responses | 0x04 | + | (ie which take longer than 1 second) | | + | | | + | CONFIG_CIFS_STATS2 must be enabled in .config | | + +-----------------------------------------------+------+ - log cifs informational messages 0x01 - log return codes from cifs entry points 0x02 - log slow responses (ie which take longer than 1 second) - CONFIG_CIFS_STATS2 must be enabled in .config 0x04 - - traceSMB If set to one, debug information is logged to the system error log with the start of smb requests and responses (default 0) @@ -671,24 +792,25 @@ LinuxExtensionsEnabled If set to one then the client will attempt to as support symbolic links. If you use servers such as Samba that support the CIFS Unix extensions but do not want to use symbolic link - support and want to map the uid and gid fields - to values supplied at mount (rather than the + support and want to map the uid and gid fields + to values supplied at mount (rather than the actual values, then set this to zero. (default 1) +======================= ======================================================= -These experimental features and tracing can be enabled by changing flags in -/proc/fs/cifs (after the cifs module has been installed or built into the -kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable -tracing to the kernel message log type: +These experimental features and tracing can be enabled by changing flags in +/proc/fs/cifs (after the cifs module has been installed or built into the +kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable +tracing to the kernel message log type:: echo 7 > /proc/fs/cifs/cifsFYI - + cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel logging of various informational messages. 2 enables logging of non-zero SMB return codes while 4 enables logging of requests that take longer -than one second to complete (except for byte range lock requests). +than one second to complete (except for byte range lock requests). Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration (.config). Setting it to seven enables all three. Finally, tracing -the start of smb requests and responses can be enabled via: +the start of smb requests and responses can be enabled via:: echo 1 > /proc/fs/cifs/traceSMB @@ -700,10 +822,10 @@ server) SMB3 (or cifs) requests grouped by request type (read, write, close etc. Also recorded is the total bytes read and bytes written to the server for that share. Note that due to client caching effects this can be less than the number of bytes read and written by the application running on the client. -Statistics can be reset to zero by "echo 0 > /proc/fs/cifs/Stats" which may be +Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be useful if comparing performance of two different scenarios. - -Also note that "cat /proc/fs/cifs/DebugData" will display information about + +Also note that ``cat /proc/fs/cifs/DebugData`` will display information about the active sessions and the shares that are mounted. Enabling Kerberos (extended security) works but requires version 1.2 or later @@ -725,19 +847,23 @@ space to ease network configuration and improve reliability. To use cifs Kerberos and DFS support, the Linux keyutils package should be installed and something like the following lines should be added to the -/etc/request-key.conf file: +/etc/request-key.conf file:: -create cifs.spnego * * /usr/local/sbin/cifs.upcall %k -create dns_resolver * * /usr/local/sbin/cifs.upcall %k + create cifs.spnego * * /usr/local/sbin/cifs.upcall %k + create dns_resolver * * /usr/local/sbin/cifs.upcall %k CIFS kernel module parameters ============================= These module parameters can be specified or modified either during the time of -module loading or during the runtime by using the interface +module loading or during the runtime by using the interface:: + /proc/module/cifs/parameters/ -i.e. echo "value" > /sys/module/cifs/parameters/ +i.e.:: -1. enable_oplocks - Enable or disable oplocks. Oplocks are enabled by default. - [Y/y/1]. To disable use any of [N/n/0]. + echo "value" > /sys/module/cifs/parameters/ +================= ========================================================== +1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default. + [Y/y/1]. To disable use any of [N/n/0]. +================= ========================================================== diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl similarity index 100% rename from Documentation/filesystems/cifs/winucase_convert.pl rename to Documentation/admin-guide/cifs/winucase_convert.pl diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 534373816d7f..34cc20ee7f3a 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking. blockdev/index ext4 binderfs + cifs/index xfs jfs ufs diff --git a/MAINTAINERS b/MAINTAINERS index f109a8bcffda..0abd3b598a1e 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -4099,7 +4099,7 @@ L: samba-technical@lists.samba.org (moderated for non-subscribers) W: http://linux-cifs.samba.org/ T: git git://git.samba.org/sfrench/cifs-2.6.git S: Supported -F: Documentation/filesystems/cifs/ +F: Documentation/admin-guide/cifs/ F: fs/cifs/ COMPACTPCI HOTPLUG CORE From e9bb627561535dd584b43a8c0afe93a67bc6a2c5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:08:53 -0300 Subject: [PATCH 41/67] docs: w1: convert to ReST and add to the kAPI group of docs The 1wire documentation was written with w1 developers in mind, so, it makes sense to add it together with the driver-api set. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/ABI/stable/sysfs-bus-w1 | 2 +- .../ABI/stable/sysfs-driver-w1_ds28e04 | 4 +- .../ABI/stable/sysfs-driver-w1_ds28ea00 | 2 +- Documentation/index.rst | 1 + Documentation/w1/index.rst | 21 +++++ .../w1/masters/{ds2482 => ds2482.rst} | 16 +++- .../w1/masters/{ds2490 => ds2490.rst} | 6 +- Documentation/w1/masters/index.rst | 14 +++ Documentation/w1/masters/mxc-w1 | 12 --- Documentation/w1/masters/mxc-w1.rst | 17 ++++ .../w1/masters/{omap-hdq => omap-hdq.rst} | 12 +-- .../w1/masters/{w1-gpio => w1-gpio.rst} | 21 +++-- Documentation/w1/slaves/index.rst | 16 ++++ .../w1/slaves/{w1_ds2406 => w1_ds2406.rst} | 4 +- .../w1/slaves/{w1_ds2413 => w1_ds2413.rst} | 9 ++ Documentation/w1/slaves/w1_ds2423 | 47 ---------- Documentation/w1/slaves/w1_ds2423.rst | 54 +++++++++++ .../w1/slaves/{w1_ds2438 => w1_ds2438.rst} | 10 ++- .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} | 5 ++ .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} | 16 ++-- .../w1/slaves/{w1_therm => w1_therm.rst} | 11 ++- .../w1/{w1.generic => w1-generic.rst} | 88 ++++++++++-------- .../w1/{w1.netlink => w1-netlink.rst} | 89 +++++++++++-------- 23 files changed, 308 insertions(+), 169 deletions(-) create mode 100644 Documentation/w1/index.rst rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%) rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%) create mode 100644 Documentation/w1/masters/index.rst delete mode 100644 Documentation/w1/masters/mxc-w1 create mode 100644 Documentation/w1/masters/mxc-w1.rst rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%) rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%) create mode 100644 Documentation/w1/slaves/index.rst rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%) rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%) delete mode 100644 Documentation/w1/slaves/w1_ds2423 create mode 100644 Documentation/w1/slaves/w1_ds2423.rst rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%) rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%) rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%) rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%) rename Documentation/w1/{w1.generic => w1-generic.rst} (59%) rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%) diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1 index 140d85b4ae92..992dfb183ed0 100644 --- a/Documentation/ABI/stable/sysfs-bus-w1 +++ b/Documentation/ABI/stable/sysfs-bus-w1 @@ -6,6 +6,6 @@ Description: Bus scanning interval, microseconds component. control systems are attached/generate presence for as short as 100 ms - hence the tens-to-hundreds milliseconds scan intervals are required. - see Documentation/w1/w1.generic for detailed information. + see Documentation/w1/w1-generic.rst for detailed information. Users: any user space application which wants to know bus scanning interval diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 index 26579ee868c9..3e1c1fa8d54d 100644 --- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 +++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 @@ -2,7 +2,7 @@ What: /sys/bus/w1/devices/.../pio Date: May 2012 Contact: Markus Franke Description: read/write the contents of the two PIO's of the DS28E04-100 - see Documentation/w1/slaves/w1_ds28e04 for detailed information + see Documentation/w1/slaves/w1_ds28e04.rst for detailed information Users: any user space application which wants to communicate with DS28E04-100 @@ -11,5 +11,5 @@ What: /sys/bus/w1/devices/.../eeprom Date: May 2012 Contact: Markus Franke Description: read/write the contents of the EEPROM memory of the DS28E04-100 - see Documentation/w1/slaves/w1_ds28e04 for detailed information + see Documentation/w1/slaves/w1_ds28e04.rst for detailed information Users: any user space application which wants to communicate with DS28E04-100 diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 index e928def14f28..534e63731a49 100644 --- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 +++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 @@ -2,5 +2,5 @@ What: /sys/bus/w1/devices/.../w1_seq Date: Apr 2015 Contact: Matt Campbell Description: Support for the DS28EA00 chain sequence function - see Documentation/w1/slaves/w1_therm for detailed information + see Documentation/w1/slaves/w1_therm.rst for detailed information Users: any user space application which wants to communicate with DS28EA00 diff --git a/Documentation/index.rst b/Documentation/index.rst index 472b8abe52e9..0a564f3c336e 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -117,6 +117,7 @@ needed). target/index timers/index spi/index + w1/index watchdog/index virtual/index input/index diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst new file mode 100644 index 000000000000..57cba81865e2 --- /dev/null +++ b/Documentation/w1/index.rst @@ -0,0 +1,21 @@ +. SPDX-License-Identifier: GPL-2.0 + +================ +1-Wire Subsystem +================ + +.. toctree:: + :maxdepth: 1 + + + w1-generic.rst + w1-netlink.rst + masters/index + slaves/index + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst similarity index 71% rename from Documentation/w1/masters/ds2482 rename to Documentation/w1/masters/ds2482.rst index 56f8edace6ac..17ebe8f660cd 100644 --- a/Documentation/w1/masters/ds2482 +++ b/Documentation/w1/masters/ds2482.rst @@ -1,13 +1,19 @@ +==================== Kernel driver ds2482 ==================== Supported chips: + * Maxim DS2482-100, Maxim DS2482-800 + Prefix: 'ds2482' + Addresses scanned: None + Datasheets: - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf + + - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf + - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf Author: Ben Gardner @@ -23,9 +29,11 @@ General Remarks --------------- Valid addresses are 0x18, 0x19, 0x1a, and 0x1b. + However, the device cannot be detected without writing to the i2c bus, so no detection is done. You should instantiate the device explicitly. -$ modprobe ds2482 -$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device +:: + $ modprobe ds2482 + $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst similarity index 98% rename from Documentation/w1/masters/ds2490 rename to Documentation/w1/masters/ds2490.rst index 3e091151dd80..7e5b50f9c0f5 100644 --- a/Documentation/w1/masters/ds2490 +++ b/Documentation/w1/masters/ds2490.rst @@ -1,7 +1,9 @@ +==================== Kernel driver ds2490 ==================== Supported chips: + * Maxim DS2490 based Author: Evgeniy Polyakov @@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490 low-level operational chip. Notes and limitations. + - The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA. - The 5V strong pullup is supported with a minimum of 5.9mA and a maximum of 30.4 mA. (From DS2490.pdf) @@ -65,4 +68,5 @@ Notes and limitations. reattaching would clear the problem. usbmon output in the guest and host did not explain the problem. My guess is a bug in either qemu or the host OS and more likely the host OS. --- 03-06-2008 David Fries + +03-06-2008 David Fries diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst new file mode 100644 index 000000000000..4442a98850ad --- /dev/null +++ b/Documentation/w1/masters/index.rst @@ -0,0 +1,14 @@ +. SPDX-License-Identifier: GPL-2.0 + +===================== +1-wire Master Drivers +===================== + +.. toctree:: + :maxdepth: 1 + + ds2482 + ds2490 + mxc-w1 + omap-hdq + w1-gpio diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1 deleted file mode 100644 index 38be1ad65532..000000000000 --- a/Documentation/w1/masters/mxc-w1 +++ /dev/null @@ -1,12 +0,0 @@ -Kernel driver mxc_w1 -==================== - -Supported chips: - * Freescale MX27, MX31 and probably other i.MX SoCs - Datasheets: - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1 - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE= - Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation - -Author: Originally based on Freescale code, prepared for mainline by - Sascha Hauer diff --git a/Documentation/w1/masters/mxc-w1.rst b/Documentation/w1/masters/mxc-w1.rst new file mode 100644 index 000000000000..334f9893103f --- /dev/null +++ b/Documentation/w1/masters/mxc-w1.rst @@ -0,0 +1,17 @@ +==================== +Kernel driver mxc_w1 +==================== + +Supported chips: + + * Freescale MX27, MX31 and probably other i.MX SoCs + + Datasheets: + + - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1 + - http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation + +Author: + + Originally based on Freescale code, prepared for mainline by + Sascha Hauer diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst similarity index 90% rename from Documentation/w1/masters/omap-hdq rename to Documentation/w1/masters/omap-hdq.rst index 234522709a5f..345298a59e50 100644 --- a/Documentation/w1/masters/omap-hdq +++ b/Documentation/w1/masters/omap-hdq.rst @@ -1,9 +1,10 @@ -Kernel driver for omap HDQ/1-wire module. +======================================== +Kernel driver for omap HDQ/1-wire module ======================================== Supported chips: ================ - HDQ/1-wire controller on the TI OMAP 2430/3430 platforms. +HDQ/1-wire controller on the TI OMAP 2430/3430 platforms. A useful link about HDQ basics: =============================== @@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1. Please note to load both the modules with a different ID if required, but note that the ID used should be same for both master and slave driver loading. -e.g: -insmod omap_hdq.ko W1_ID=2 -inamod w1_bq27000.ko F_ID=2 +e.g:: + + insmod omap_hdq.ko W1_ID=2 + inamod w1_bq27000.ko F_ID=2 The driver also supports 1-wire mode. In this mode, there is no need to pass slave ID as parameter. The driver will auto-detect slaves connected diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst similarity index 75% rename from Documentation/w1/masters/w1-gpio rename to Documentation/w1/masters/w1-gpio.rst index 623961d9e83f..18fdb7366372 100644 --- a/Documentation/w1/masters/w1-gpio +++ b/Documentation/w1/masters/w1-gpio.rst @@ -1,3 +1,4 @@ +===================== Kernel driver w1-gpio ===================== @@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt Example (mach-at91) ------------------- -#include -#include +:: -static struct gpiod_lookup_table foo_w1_gpiod_table = { + #include + #include + + static struct gpiod_lookup_table foo_w1_gpiod_table = { .dev_id = "w1-gpio", .table = { GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0, GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN), }, -}; + }; -static struct w1_gpio_platform_data foo_w1_gpio_pdata = { + static struct w1_gpio_platform_data foo_w1_gpio_pdata = { .ext_pullup_enable_pin = -EINVAL, -}; + }; -static struct platform_device foo_w1_device = { + static struct platform_device foo_w1_device = { .name = "w1-gpio", .id = -1, .dev.platform_data = &foo_w1_gpio_pdata, -}; + }; -... + ... at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1); at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1); gpiod_add_lookup_table(&foo_w1_gpiod_table); diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst new file mode 100644 index 000000000000..d0697b202f09 --- /dev/null +++ b/Documentation/w1/slaves/index.rst @@ -0,0 +1,16 @@ +. SPDX-License-Identifier: GPL-2.0 + +==================== +1-wire Slave Drivers +==================== + +.. toctree:: + :maxdepth: 1 + + w1_ds2406 + w1_ds2413 + w1_ds2423 + w1_ds2438 + w1_ds28e04 + w1_ds28e17 + w1_therm diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst similarity index 96% rename from Documentation/w1/slaves/w1_ds2406 rename to Documentation/w1/slaves/w1_ds2406.rst index 8137fe6f6c3d..d3e68266084f 100644 --- a/Documentation/w1/slaves/w1_ds2406 +++ b/Documentation/w1/slaves/w1_ds2406.rst @@ -1,7 +1,9 @@ +======================= w1_ds2406 kernel driver ======================= Supported chips: + * Maxim DS2406 (and other family 0x12) addressable switches Author: Scott Alfter @@ -9,7 +11,7 @@ Author: Scott Alfter Description ----------- -The w1_ds2406 driver allows connected devices to be switched on and off. +The w1_ds2406 driver allows connected devices to be switched on and off. These chips also provide 128 bytes of OTP EPROM, but reading/writing it is not supported. In TSOC-6 form, the DS2406 provides two switch outputs and can be provided with power on a dedicated input. In TO-92 form, it provides diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst similarity index 81% rename from Documentation/w1/slaves/w1_ds2413 rename to Documentation/w1/slaves/w1_ds2413.rst index 936263a8ccb4..c15bb5b919b7 100644 --- a/Documentation/w1/slaves/w1_ds2413 +++ b/Documentation/w1/slaves/w1_ds2413.rst @@ -1,11 +1,16 @@ +======================= Kernel driver w1_ds2413 ======================= Supported chips: + * Maxim DS2413 1-Wire Dual Channel Addressable Switch supported family codes: + + ================ ==== W1_FAMILY_DS2413 0x3A + ================ ==== Author: Mariusz Bialonczyk @@ -20,11 +25,13 @@ Reading state The "state" file provides one-byte value which is in the same format as for the chip PIO_ACCESS_READ command (refer the datasheet for details): +======== ============================================================= Bit 0: PIOA Pin State Bit 1: PIOA Output Latch State Bit 2: PIOB Pin State Bit 3: PIOB Output Latch State Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module) +======== ============================================================= This file is readonly. @@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file. It is writable, you can write one-byte value to this sysfs file. Similarly the byte format is the same as for the PIO_ACCESS_WRITE command: +======== ====================================== Bit 0: PIOA Bit 1: PIOB Bit 2-7: No matter (driver will set it to "1"s) +======== ====================================== The chip has some kind of basic protection against transmission errors. diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423 deleted file mode 100644 index 3f98b505a0ee..000000000000 --- a/Documentation/w1/slaves/w1_ds2423 +++ /dev/null @@ -1,47 +0,0 @@ -Kernel driver w1_ds2423 -======================= - -Supported chips: - * Maxim DS2423 based counter devices. - -supported family codes: - W1_THERM_DS2423 0x1D - -Author: Mika Laitio - -Description ------------ - -Support is provided through the sysfs w1_slave file. Each opening and -read sequence of w1_slave file initiates the read of counters and ram -available in DS2423 pages 12 - 15. - -Result of each page is provided as an ASCII output where each counter -value and associated ram buffer is outpputed to own line. - -Each lines will contain the values of 42 bytes read from the counter and -memory page along the crc=YES or NO for indicating whether the read operation -was successful and CRC matched. -If the operation was successful, there is also in the end of each line -a counter value expressed as an integer after c= - -Meaning of 42 bytes represented is following: - - 1 byte from ram page - - 4 bytes for the counter value - - 4 zero bytes - - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes - - 31 remaining bytes from the ram page - - crc=YES/NO indicating whether read was ok and crc matched - - c= current counter value - -example from the successful read: -00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761 -00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5 - -example from the read with crc errors: -00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 -00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO -00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO -00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO diff --git a/Documentation/w1/slaves/w1_ds2423.rst b/Documentation/w1/slaves/w1_ds2423.rst new file mode 100644 index 000000000000..755d659ad997 --- /dev/null +++ b/Documentation/w1/slaves/w1_ds2423.rst @@ -0,0 +1,54 @@ +Kernel driver w1_ds2423 +======================= + +Supported chips: + + * Maxim DS2423 based counter devices. + +supported family codes: + + =============== ==== + W1_THERM_DS2423 0x1D + =============== ==== + +Author: Mika Laitio + +Description +----------- + +Support is provided through the sysfs w1_slave file. Each opening and +read sequence of w1_slave file initiates the read of counters and ram +available in DS2423 pages 12 - 15. + +Result of each page is provided as an ASCII output where each counter +value and associated ram buffer is outpputed to own line. + +Each lines will contain the values of 42 bytes read from the counter and +memory page along the crc=YES or NO for indicating whether the read operation +was successful and CRC matched. +If the operation was successful, there is also in the end of each line +a counter value expressed as an integer after c= + +Meaning of 42 bytes represented is following: + + - 1 byte from ram page + - 4 bytes for the counter value + - 4 zero bytes + - 2 bytes for crc16 which was calculated from the data read since the previous crc bytes + - 31 remaining bytes from the ram page + - crc=YES/NO indicating whether read was ok and crc matched + - c= current counter value + +example from the successful read:: + + 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761 + 00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5 + +example from the read with crc errors:: + + 00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2 + 00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO + 00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO + 00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst similarity index 93% rename from Documentation/w1/slaves/w1_ds2438 rename to Documentation/w1/slaves/w1_ds2438.rst index e64f65a09387..a29309a3f8e5 100644 --- a/Documentation/w1/slaves/w1_ds2438 +++ b/Documentation/w1/slaves/w1_ds2438.rst @@ -2,10 +2,13 @@ Kernel driver w1_ds2438 ======================= Supported chips: + * Maxim DS2438 Smart Battery Monitor supported family codes: + ================ ==== W1_FAMILY_DS2438 0x26 + ================ ==== Author: Mariusz Bialonczyk @@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion) command of the chip. Depending on a sysfs filename a different input for the A/D will be selected: -vad: general purpose A/D input (VAD) -vdd: battery input (VDD) + +vad: + general purpose A/D input (VAD) +vdd: + battery input (VDD) After the voltage conversion the value is returned as decimal ASCII. Note: To get a volts the value has to be divided by 100. diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst similarity index 93% rename from Documentation/w1/slaves/w1_ds28e04 rename to Documentation/w1/slaves/w1_ds28e04.rst index 7819b65cfa48..b12b118890d3 100644 --- a/Documentation/w1/slaves/w1_ds28e04 +++ b/Documentation/w1/slaves/w1_ds28e04.rst @@ -1,11 +1,16 @@ +======================== Kernel driver w1_ds28e04 ======================== Supported chips: + * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO supported family codes: + + ================= ==== W1_FAMILY_DS28E04 0x1C + ================= ==== Author: Markus Franke, diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst similarity index 88% rename from Documentation/w1/slaves/w1_ds28e17 rename to Documentation/w1/slaves/w1_ds28e17.rst index 7fcfad5b4a37..e2d9f96d8f2c 100644 --- a/Documentation/w1/slaves/w1_ds28e17 +++ b/Documentation/w1/slaves/w1_ds28e17.rst @@ -1,11 +1,16 @@ +======================== Kernel driver w1_ds28e17 ======================== Supported chips: + * Maxim DS28E17 1-Wire-to-I2C Master Bridge supported family codes: + + ================= ==== W1_FAMILY_DS28E17 0x19 + ================= ==== Author: Jan Kandziora @@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were connected to a "native" I2C bus master. -An udev rule like the following -------------------------------------------------------------------------------- -SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \ - SYMLINK+="i2c-$attr{name}" -------------------------------------------------------------------------------- +An udev rule like the following:: + + SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \ + SYMLINK+="i2c-$attr{name}" + may be used to create stable /dev/i2c- entries based on the unique id of the DS28E17 chip. @@ -65,4 +70,3 @@ structure is created. See https://github.com/ianka/w1_ds28e17 for even more information. - diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst similarity index 95% rename from Documentation/w1/slaves/w1_therm rename to Documentation/w1/slaves/w1_therm.rst index d1f93af36f38..90531c340a07 100644 --- a/Documentation/w1/slaves/w1_therm +++ b/Documentation/w1/slaves/w1_therm.rst @@ -1,7 +1,9 @@ +====================== Kernel driver w1_therm -==================== +====================== Supported chips: + * Maxim ds18*20 based temperature sensors. * Maxim ds1825 based temperature sensors. @@ -13,12 +15,16 @@ Description w1_therm provides basic temperature conversion for ds18*20 devices, and the ds28ea00 device. -supported family codes: + +Supported family codes: + +==================== ==== W1_THERM_DS18S20 0x10 W1_THERM_DS1822 0x22 W1_THERM_DS18B20 0x28 W1_THERM_DS1825 0x3B W1_THERM_DS28EA00 0x42 +==================== ==== Support is provided through the sysfs w1_slave file. Each open and read sequence will initiate a temperature conversion then provide two @@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup. In case the detection of parasite devices using this command fails (seems to be the case with some DS18S20) the strong pullup can be force-enabled. + If the strong pullup is enabled, the master's strong pullup will be driven when the conversion is taking place, provided the master driver does support the strong pullup (or it falls back to a pullup diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst similarity index 59% rename from Documentation/w1/w1.generic rename to Documentation/w1/w1-generic.rst index c51b1ab012d0..da4e8b4e9b01 100644 --- a/Documentation/w1/w1.generic +++ b/Documentation/w1/w1-generic.rst @@ -1,5 +1,7 @@ -The 1-wire (w1) subsystem ------------------------------------------------------------------- +========================================= +Introduction to the 1-wire (w1) subsystem +========================================= + The 1-wire bus is a simple master-slave bus that communicates via a single signal wire (plus ground, so two wires). @@ -12,14 +14,16 @@ communication with slaves. All w1 slave devices must be connected to a w1 bus master device. Example w1 master devices: - DS9490 usb device - W1-over-GPIO - DS2482 (i2c to w1 bridge) - Emulated devices, such as a RS232 converter, parallel port adapter, etc + + - DS9490 usb device + - W1-over-GPIO + - DS2482 (i2c to w1 bridge) + - Emulated devices, such as a RS232 converter, parallel port adapter, etc What does the w1 subsystem do? ------------------------------------------------------------------- +------------------------------ + When a w1 master driver registers with the w1 subsystem, the following occurs: - sysfs entries for that w1 master are created @@ -43,24 +47,28 @@ be read, since no device was selected. W1 device families ------------------------------------------------------------------- +------------------ + Slave devices are handled by a driver written for a family of w1 devices. A family driver populates a struct w1_family_ops (see w1_family.h) and registers with the w1 subsystem. Current family drivers: -w1_therm - (ds18?20 thermal sensor family driver) + +w1_therm + - (ds18?20 thermal sensor family driver) provides temperature reading function which is bound to ->rbin() method of the above w1_family_ops structure. -w1_smem - driver for simple 64bit memory cell provides ID reading method. +w1_smem + - driver for simple 64bit memory cell provides ID reading method. You can call above methods by reading appropriate sysfs files. What does a w1 master driver need to implement? ------------------------------------------------------------------- +----------------------------------------------- The driver for w1 bus master must provide at minimum two functions. @@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details. w1 master sysfs interface ------------------------------------------------------------------- - - A directory for a found device. The format is family-serial -bus - (standard) symlink to the w1 bus -driver - (standard) symlink to the w1 driver -w1_master_add - (rw) manually register a slave device -w1_master_attempts - (ro) the number of times a search was attempted -w1_master_max_slave_count - - (rw) maximum number of slaves to search for at a time -w1_master_name - (ro) the name of the device (w1_bus_masterX) -w1_master_pullup - (rw) 5V strong pullup 0 enabled, 1 disabled -w1_master_remove - (rw) manually remove a slave device -w1_master_search - (rw) the number of searches left to do, - -1=continual (default) -w1_master_slave_count - - (ro) the number of slaves found -w1_master_slaves - (ro) the names of the slaves, one per line -w1_master_timeout - (ro) the delay in seconds between searches -w1_master_timeout_us - - (ro) the delay in microseconds beetwen searches +------------------------- + +========================= ===================================================== + A directory for a found device. The format is + family-serial +bus (standard) symlink to the w1 bus +driver (standard) symlink to the w1 driver +w1_master_add (rw) manually register a slave device +w1_master_attempts (ro) the number of times a search was attempted +w1_master_max_slave_count (rw) maximum number of slaves to search for at a time +w1_master_name (ro) the name of the device (w1_bus_masterX) +w1_master_pullup (rw) 5V strong pullup 0 enabled, 1 disabled +w1_master_remove (rw) manually remove a slave device +w1_master_search (rw) the number of searches left to do, + -1=continual (default) +w1_master_slave_count (ro) the number of slaves found +w1_master_slaves (ro) the names of the slaves, one per line +w1_master_timeout (ro) the delay in seconds between searches +w1_master_timeout_us (ro) the delay in microseconds beetwen searches +========================= ===================================================== If you have a w1 bus that never changes (you don't add or remove devices), you can set the module parameter search_count to a small positive number @@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments w1_master_attempts by 1. w1 slave sysfs interface ------------------------------------------------------------------- -bus - (standard) symlink to the w1 bus -driver - (standard) symlink to the w1 driver -name - the device name, usually the same as the directory name -w1_slave - (optional) a binary file whose meaning depends on the - family driver -rw - (optional) created for slave devices which do not have - appropriate family driver. Allows to read/write binary data. +------------------------ + +=================== ============================================================ +bus (standard) symlink to the w1 bus +driver (standard) symlink to the w1 driver +name the device name, usually the same as the directory name +w1_slave (optional) a binary file whose meaning depends on the + family driver +rw (optional) created for slave devices which do not have + appropriate family driver. Allows to read/write binary data. +=================== ============================================================ diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst similarity index 77% rename from Documentation/w1/w1.netlink rename to Documentation/w1/w1-netlink.rst index 94ad4c420828..aaa13243a5e4 100644 --- a/Documentation/w1/w1.netlink +++ b/Documentation/w1/w1-netlink.rst @@ -1,22 +1,26 @@ -Userspace communication protocol over connector [1]. +=============================================== +Userspace communication protocol over connector +=============================================== - -Message types. +Message types ============= There are three types of messages between w1 core and userspace: + 1. Events. They are generated each time a new master or slave device - is found either due to automatic or requested search. + is found either due to automatic or requested search. 2. Userspace commands. 3. Replies to userspace commands. -Protocol. +Protocol ======== -[struct cn_msg] - connector header. +:: + + [struct cn_msg] - connector header. Its length field is equal to size of the attached data -[struct w1_netlink_msg] - w1 netlink header. + [struct w1_netlink_msg] - w1 netlink header. __u8 type - message type. W1_LIST_MASTERS list current bus masters @@ -40,7 +44,7 @@ Protocol. } mst; } id; -[struct w1_netlink_cmd] - command for given master or slave device. + [struct w1_netlink_cmd] - command for given master or slave device. __u8 cmd - command opcode. W1_CMD_READ - read command W1_CMD_WRITE - write command @@ -71,18 +75,18 @@ when it is added to w1 core. Currently replies to userspace commands are only generated for read command request. One reply is generated exactly for one w1_netlink_cmd read request. Replies are not combined when sent - i.e. typical reply -messages looks like the following: +messages looks like the following:: -[cn_msg][w1_netlink_msg][w1_netlink_cmd] -cn_msg.len = sizeof(struct w1_netlink_msg) + + [cn_msg][w1_netlink_msg][w1_netlink_cmd] + cn_msg.len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + cmd->len; -w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; -w1_netlink_cmd.len = cmd->len; + w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len; + w1_netlink_cmd.len = cmd->len; Replies to W1_LIST_MASTERS should send a message back to the userspace which will contain list of all registered master ids in the following -format: +format:: cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct w1_netlink_msg) plus number of masters multiplied by 4) @@ -90,39 +94,47 @@ format: number of masters multiplied by 4 (u32 size)) id0 ... idN - Each message is at most 4k in size, so if number of master devices - exceeds this, it will be split into several messages. +Each message is at most 4k in size, so if number of master devices +exceeds this, it will be split into several messages. W1 search and alarm search commands. -request: -[cn_msg] - [w1_netlink_msg type = W1_MASTER_CMD - id is equal to the bus master id to use for searching] - [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH] -reply: +request:: + + [cn_msg] + [w1_netlink_msg type = W1_MASTER_CMD + id is equal to the bus master id to use for searching] + [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH] + +reply:: + [cn_msg, ack = 1 and increasing, 0 means the last message, - seq is equal to the request seq] + seq is equal to the request seq] [w1_netlink_msg type = W1_MASTER_CMD] [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH len is equal to number of IDs multiplied by 8] [64bit-id0 ... 64bit-idN] + Length in each header corresponds to the size of the data behind it, so w1_netlink_cmd->len = N * 8; where N is number of IDs in this message. - Can be zero. -w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8; -cn_msg->len = sizeof(struct w1_netlink_msg) + +Can be zero. + +:: + + w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8; + cn_msg->len = sizeof(struct w1_netlink_msg) + sizeof(struct w1_netlink_cmd) + N*8; -W1 reset command. -[cn_msg] - [w1_netlink_msg type = W1_MASTER_CMD - id is equal to the bus master id to use for searching] - [w1_netlink_cmd cmd = W1_CMD_RESET] +W1 reset command:: + + [cn_msg] + [w1_netlink_msg type = W1_MASTER_CMD + id is equal to the bus master id to use for searching] + [w1_netlink_cmd cmd = W1_CMD_RESET] -Command status replies. +Command status replies ====================== Each command (either root, master or slave with or without w1_netlink_cmd @@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg, even if there were errors, only length mismatch interrupts message processing. -Operation steps in w1 core when new command is received. +Operation steps in w1 core when new command is received ======================================================= When new message (w1_netlink_msg) is received w1 core detects if it is @@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked and next w1_netlink_msg header processing started. -Connector [1] specific documentation. +Connector [1] specific documentation ==================================== Each connector message includes two u32 fields as "address". @@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and acknowledge number is set to seq+1. -Additional documantion, source code examples. -============================================ +Additional documentation, source code examples +============================================== 1. Documentation/driver-api/connector.rst 2. http://www.ioremap.net/archive/w1 -This archive includes userspace application w1d.c which uses -read/write/search commands for all master/slave devices found on the bus. + + This archive includes userspace application w1d.c which uses + read/write/search commands for all master/slave devices found on the bus. From 9195c3e8d58a258344a33e0e05359564e8f8e538 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 31 Jul 2019 17:27:56 -0300 Subject: [PATCH 42/67] docs: fs: porting.rst: fix a broken reference to another doc With all those document shifts, references to documents get broken. Fix one such occurrence at porting.rst. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/filesystems/porting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/filesystems/porting.rst b/Documentation/filesystems/porting.rst index 66aa521e6376..f18506083ced 100644 --- a/Documentation/filesystems/porting.rst +++ b/Documentation/filesystems/porting.rst @@ -158,7 +158,7 @@ Callers of notify_change() need ->i_mutex now. New super_block field ``struct export_operations *s_export_op`` for explicit support for exporting, e.g. via NFS. The structure is fully documented at its declaration in include/linux/fs.h, and in -Documentation/filesystems/nfs/Exporting. +Documentation/filesystems/nfs/exporting.rst. Briefly it allows for the definition of decode_fh and encode_fh operations to encode and decode filehandles, and allows the filesystem to use From 95e760cbf62755bd3d8999bee1e6579f0ff1425e Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Mon, 5 Aug 2019 09:29:50 -0700 Subject: [PATCH 43/67] kernel-doc: ignore __printf attribute Ignore __printf() function attributes just as other __attribute__ strings are ignored. Fixes this kernel-doc warning message: include/kunit/kunit-stream.h:58: warning: Function parameter or member '2' not described in '__printf' Reported-by: kbuild test robot Signed-off-by: Randy Dunlap Cc: Brendan Higgins Tested-by: Brendan Higgins Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 6b03012750da..32e793ca5e95 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1580,6 +1580,7 @@ sub dump_function($$) { $prototype =~ s/__must_check +//; $prototype =~ s/__weak +//; $prototype =~ s/__sched +//; + $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//; my $define = $prototype =~ s/^#\s*define\s+//; #ak added $prototype =~ s/__attribute__\s*\(\( (?: From ac862503639ff824e0e1f32fbca220ed75261138 Mon Sep 17 00:00:00 2001 From: Colin Ian King Date: Mon, 5 Aug 2019 11:49:51 +0100 Subject: [PATCH 44/67] Input: docs: fix spelling mistake "potocol" -> "protocol" There is a minor spelling mistake in the documentation, fix it. Signed-off-by: Colin Ian King Signed-off-by: Jonathan Corbet --- Documentation/input/multi-touch-protocol.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/input/multi-touch-protocol.rst b/Documentation/input/multi-touch-protocol.rst index 6be70342e709..307fe22d9668 100644 --- a/Documentation/input/multi-touch-protocol.rst +++ b/Documentation/input/multi-touch-protocol.rst @@ -23,7 +23,7 @@ devices capable of tracking identifiable contacts (type B), the protocol describes how to send updates for individual contacts via event slots. .. note:: - MT potocol type A is obsolete, all kernel drivers have been + MT protocol type A is obsolete, all kernel drivers have been converted to use type B. Protocol Usage From a4a03bdccfd02eda6613a892fb418f15adeb2b21 Mon Sep 17 00:00:00 2001 From: Chao Yu Date: Thu, 1 Aug 2019 11:17:50 +0800 Subject: [PATCH 45/67] mailmap: add entry for Gao Xiang Add entry to connect all Gao Xiang's email addresses. Signed-off-by: Chao Yu Acked-by: Gao Xiang Signed-off-by: Jonathan Corbet --- .mailmap | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.mailmap b/.mailmap index 477debe3d960..c4a780a4dff4 100644 --- a/.mailmap +++ b/.mailmap @@ -79,6 +79,8 @@ Frank Rowand Frank Rowand Frank Rowand Frank Zago +Gao Xiang +Gao Xiang Greg Kroah-Hartman Greg Kroah-Hartman Greg Kroah-Hartman From 758f2512546f70fdb70bd1d752d975a09ad9741b Mon Sep 17 00:00:00 2001 From: Todor Tomov Date: Thu, 1 Aug 2019 20:26:03 +0300 Subject: [PATCH 46/67] mailmap: Add an entry for my email address My @linaro.org email address doesn't exist anymore so add a mailmap entry to map it to my @gmail.com address. Signed-off-by: Todor Tomov Signed-off-by: Jonathan Corbet --- .mailmap | 1 + 1 file changed, 1 insertion(+) diff --git a/.mailmap b/.mailmap index c4a780a4dff4..0e6b0b016c49 100644 --- a/.mailmap +++ b/.mailmap @@ -225,6 +225,7 @@ Sumit Semwal Tejun Heo Thomas Graf Thomas Pedersen +Todor Tomov Tony Luck TripleX Chung TripleX Chung From aa48e31b874774bef42fd2b433474202cbe8ac79 Mon Sep 17 00:00:00 2001 From: Chao Yu Date: Fri, 2 Aug 2019 09:21:35 +0800 Subject: [PATCH 47/67] mailmap: add entry for Jaegeuk Kim Add entry to connect all Jaegeuk's email addresses. Acked-by: Jaegeuk Kim Signed-off-by: Chao Yu Signed-off-by: Jonathan Corbet --- .mailmap | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.mailmap b/.mailmap index 0e6b0b016c49..ea703abcb397 100644 --- a/.mailmap +++ b/.mailmap @@ -91,6 +91,9 @@ Henrik Kretzschmar Henrik Rydberg Herbert Xu Jacob Shin +Jaegeuk Kim +Jaegeuk Kim +Jaegeuk Kim James Bottomley James Bottomley James E Wilson From 11fec009d97e5bd2329ef7d52d71e9f6763f1048 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Mon, 12 Aug 2019 18:07:04 +0200 Subject: [PATCH 48/67] Documentation: sphinx: Add missing comma to list of strings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In Python, like in C, when a comma is omitted in a list of strings, the two strings around the missing comma are concatenated. Cc: stable@vger.kernel.org # v5.2 only Signed-off-by: Jonathan Neuschäfer Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx/automarkup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index 77e89c1956d7..a8798369e8f7 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -25,7 +25,7 @@ RE_function = re.compile(r'([\w_][\w\d_]+\(\))') # to the creation of incorrect and confusing cross references. So # just don't even try with these names. # -Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap' +Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl'] # From 82bf829b692d6bc9c44cd43ddd75a9b04f1bfa8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Mon, 12 Aug 2019 18:07:05 +0200 Subject: [PATCH 49/67] Documentation: sphinx: Don't parse socket() as identifier reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit With the introduction of Documentation/sphinx/automarkup.py, socket() is parsed as a reference to the in-kernel definition of socket. Sphinx then decides that struct socket is a good match, which is usually not intended, when the syscall is meant instead. This was observed in Documentation/networking/af_xdp.rst. Prevent socket() from being misinterpreted by adding it to the Skipfuncs list in automarkup.py. Signed-off-by: Jonathan Neuschäfer Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/sphinx/automarkup.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index a8798369e8f7..5b6119ff69f4 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -26,7 +26,8 @@ RE_function = re.compile(r'([\w_][\w\d_]+\(\))') # just don't even try with these names. # Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', - 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl'] + 'select', 'poll', 'fork', 'execve', 'clone', 'ioctl', + 'socket' ] # # Find all occurrences of function() and try to replace them with From 15e2544ed38a1e39b702277bdcd2bb1275e78925 Mon Sep 17 00:00:00 2001 From: Andy Shevchenko Date: Mon, 12 Aug 2019 19:06:31 +0300 Subject: [PATCH 50/67] kernel-doc: Allow anonymous enum In C is a valid construction to have an anonymous enumerator. Though we have now: drivers/pinctrl/intel/pinctrl-intel.c:240: error: Cannot parse enum! Support it in the kernel-doc script. Signed-off-by: Andy Shevchenko Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 32e793ca5e95..81dc91760b23 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1245,7 +1245,7 @@ sub dump_enum($$) { # strip #define macros inside enums $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos; - if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) { + if ($x =~ /enum\s+(\w*)\s*\{(.*)\}/) { $declaration_name = $1; my $members = $2; my %_members; From 3b2cb439a63fd5bed75bf9e023f4a8ec6623b3c0 Mon Sep 17 00:00:00 2001 From: Marco Villegas Date: Fri, 9 Aug 2019 18:29:07 -0500 Subject: [PATCH 51/67] docs: Fix typo on pull requests guide Signed-off-by: Marco Villegas Signed-off-by: Jonathan Corbet --- Documentation/maintainer/pull-requests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst index 22b271de0304..1a2f99b67d25 100644 --- a/Documentation/maintainer/pull-requests.rst +++ b/Documentation/maintainer/pull-requests.rst @@ -29,7 +29,7 @@ request to. In order to create the pull request you must first tag the branch that you have just created. It is recommended that you choose a meaningful tag name, in a way that you and others can understand, even after some time. A good -practice is to include in the name an indicator of the sybsystem of origin +practice is to include in the name an indicator of the subsystem of origin and the target kernel version. Greg offers the following. A pull request with miscellaneous stuff for From 03d36521f5d22e4bd93246a53fd493f275924593 Mon Sep 17 00:00:00 2001 From: Sheriff Esseson Date: Fri, 9 Aug 2019 14:23:49 +0100 Subject: [PATCH 52/67] Documentation: virt: Fix broken reference to virt tree's index Fix broken reference to virt/index.rst. Fixes: 2f5947dfcaec ("Documentation: move Documentation/virtual to Documentation/virt") Signed-off-by: Sheriff Esseson Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/index.rst b/Documentation/index.rst index 0a564f3c336e..b5fd87e7dbee 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -119,7 +119,7 @@ needed). spi/index w1/index watchdog/index - virtual/index + virt/index input/index hwmon/index gpu/index From 6a241a11f9257e34f64db5e1769c77af72593c20 Mon Sep 17 00:00:00 2001 From: Alex Shi Date: Fri, 9 Aug 2019 20:04:47 +0800 Subject: [PATCH 53/67] docs/zh_CN: update Chinese howto.rst for latexdocs making Mauro Carvalho Chehab found a reference error in Chinese howto.rst. and further more there more infos of latexdocs/epubdocs format doc making in English howto.rst. So I update this part according to latest howto.rst and settled the correct reference. Signed-off-by: Alex Shi Signed-off-by: Jonathan Corbet --- Documentation/translations/zh_CN/process/howto.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index c4ff8356b88d..b244a7190eb6 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -146,14 +146,18 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 :ref:`Documentation/process/applying-patches.rst ` 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍 -内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何 -妥善处理加锁的规则。生成的文档会放在 Documentation/output/目录下。在内 -核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册 -页等不同格式的文档:: +内核还拥有大量从代码自动生成或者从 ReStructuredText(ReST) 标记生成的文档， +比如这个文档，它包含内核内部API的全面介绍以及如何妥善处理加锁的规则。所有 +这些文档都可以通过运行以下命令从内核代码中生成为PDF或HTML文档:: make pdfdocs make htmldocs +ReST格式的文档会生成在 Documentation/output. 目录中。 +它们也可以用下列命令生成 LaTeX 和 ePub 格式文档:: + + make latexdocs + make epubdocs 如何成为内核开发者 ------------------ From 198266af3ab934847c840b2442ed66b255723e8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Thu, 8 Aug 2019 18:58:55 +0200 Subject: [PATCH 54/67] Documentation/arm/sa1100: Remove some obsolete documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The support for the following boards, among others, was removed in 2004 with commit "[ARM] Remove broken SA1100 machine support.": - ADS Bitsy - Brutus - Freebird - ADS GraphicsClient Plus - ADS GraphicsMaster - Höft & Wessel Webpanel - Compaq Itsy - nanoEngine - Pangolin - PLEB - Yopy Tifon support has been removed in 2.4.3.3. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/arm/sa1100/adsbitsy.rst | 51 ---------- Documentation/arm/sa1100/brutus.rst | 69 ------------- Documentation/arm/sa1100/freebird.rst | 25 ----- Documentation/arm/sa1100/graphicsclient.rst | 102 -------------------- Documentation/arm/sa1100/graphicsmaster.rst | 60 ------------ Documentation/arm/sa1100/huw_webpanel.rst | 21 ---- Documentation/arm/sa1100/index.rst | 12 --- Documentation/arm/sa1100/itsy.rst | 47 --------- Documentation/arm/sa1100/nanoengine.rst | 11 --- Documentation/arm/sa1100/pangolin.rst | 29 ------ Documentation/arm/sa1100/pleb.rst | 13 --- Documentation/arm/sa1100/tifon.rst | 7 -- Documentation/arm/sa1100/yopy.rst | 5 - 13 files changed, 452 deletions(-) delete mode 100644 Documentation/arm/sa1100/adsbitsy.rst delete mode 100644 Documentation/arm/sa1100/brutus.rst delete mode 100644 Documentation/arm/sa1100/freebird.rst delete mode 100644 Documentation/arm/sa1100/graphicsclient.rst delete mode 100644 Documentation/arm/sa1100/graphicsmaster.rst delete mode 100644 Documentation/arm/sa1100/huw_webpanel.rst delete mode 100644 Documentation/arm/sa1100/itsy.rst delete mode 100644 Documentation/arm/sa1100/nanoengine.rst delete mode 100644 Documentation/arm/sa1100/pangolin.rst delete mode 100644 Documentation/arm/sa1100/pleb.rst delete mode 100644 Documentation/arm/sa1100/tifon.rst delete mode 100644 Documentation/arm/sa1100/yopy.rst diff --git a/Documentation/arm/sa1100/adsbitsy.rst b/Documentation/arm/sa1100/adsbitsy.rst deleted file mode 100644 index c179cb26b682..000000000000 --- a/Documentation/arm/sa1100/adsbitsy.rst +++ /dev/null @@ -1,51 +0,0 @@ -=============================== -ADS Bitsy Single Board Computer -=============================== - -(It is different from Bitsy(iPAQ) of Compaq) - -For more details, contact Applied Data Systems or see -http://www.applieddata.net/products.html - -The Linux support for this product has been provided by -Woojung Huh - -Use 'make adsbitsy_config' before any 'make config'. -This will set up defaults for ADS Bitsy support. - -The kernel zImage is linked to be loaded and executed at 0xc0400000. - -Linux can be used with the ADS BootLoader that ships with the -newer rev boards. See their documentation on how to load Linux. - -Supported peripherals -===================== - -- SA1100 LCD frame buffer (8/16bpp...sort of) -- SA1111 USB Master -- SA1100 serial port -- pcmcia, compact flash -- touchscreen(ucb1200) -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console - -To do -===== - -- everything else! :-) - -Notes -===== - -- The flash on board is divided into 3 partitions. - You should be careful to use flash on board. - Its partition is different from GraphicsClient Plus and GraphicsMaster - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/brutus.rst b/Documentation/arm/sa1100/brutus.rst deleted file mode 100644 index e1a23bee6d44..000000000000 --- a/Documentation/arm/sa1100/brutus.rst +++ /dev/null @@ -1,69 +0,0 @@ -====== -Brutus -====== - -Brutus is an evaluation platform for the SA1100 manufactured by Intel. -For more details, see: - -http://developer.intel.com - -To compile for Brutus, you must issue the following commands:: - - make brutus_config - make config - [accept all the defaults] - make zImage - -The resulting kernel will end up in linux/arch/arm/boot/zImage. This file -must be loaded at 0xc0008000 in Brutus's memory and execution started at -0xc0008000 as well with the value of registers r0 = 0 and r1 = 16 upon -entry. - -But prior to execute the kernel, a ramdisk image must also be loaded in -memory. Use memory address 0xd8000000 for this. Note that the file -containing the (compressed) ramdisk image must not exceed 4 MB. - -Typically, you'll need angelboot to load the kernel. -The following angelboot.opt file should be used:: - - base 0xc0008000 - entry 0xc0008000 - r0 0x00000000 - r1 0x00000010 - device /dev/ttyS0 - options "9600 8N1" - baud 115200 - otherfile ramdisk_img.gz - otherbase 0xd8000000 - -Then load the kernel and ramdisk with:: - - angelboot -f angelboot.opt zImage - -The first Brutus serial port (assumed to be linked to /dev/ttyS0 on your -host PC) is used by angel to load the kernel and ramdisk image. The serial -console is provided through the second Brutus serial port. To access it, -you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow -control. - -Currently supported -=================== - - - RS232 serial ports - - audio output - - LCD screen - - keyboard - -The actual Brutus support may not be complete without extra patches. -If such patches exist, they should be found from -ftp.netwinder.org/users/n/nico. - -A full PCMCIA support is still missing, although it's possible to hack -some drivers in order to drive already inserted cards at boot time with -little modifications. - -Any contribution is welcome. - -Please send patches to nico@fluxnic.net - -Have Fun ! diff --git a/Documentation/arm/sa1100/freebird.rst b/Documentation/arm/sa1100/freebird.rst deleted file mode 100644 index 81043d0c6d64..000000000000 --- a/Documentation/arm/sa1100/freebird.rst +++ /dev/null @@ -1,25 +0,0 @@ -======== -Freebird -======== - -Freebird-1.1 is produced by Legend(C), Inc. -`http://web.archive.org/web/*/http://www.legend.com.cn` -and software/linux maintained by Coventive(C), Inc. -(http://www.coventive.com) - -Based on the Nicolas's strongarm kernel tree. - -Maintainer: - -Chester Kuo - - - - - -Author: - -- Tim wu -- CIH -- Eric Peng -- Jeff Lee -- Allen Cheng -- Tony Liu diff --git a/Documentation/arm/sa1100/graphicsclient.rst b/Documentation/arm/sa1100/graphicsclient.rst deleted file mode 100644 index a73d61c3ce91..000000000000 --- a/Documentation/arm/sa1100/graphicsclient.rst +++ /dev/null @@ -1,102 +0,0 @@ -============================================= -ADS GraphicsClient Plus Single Board Computer -============================================= - -For more details, contact Applied Data Systems or see -http://www.applieddata.net/products.html - -The original Linux support for this product has been provided by -Nicolas Pitre . Continued development work by -Woojung Huh - -It's currently possible to mount a root filesystem via NFS providing a -complete Linux environment. Otherwise a ramdisk image may be used. The -board supports MTD/JFFS, so you could also mount something on there. - -Use 'make graphicsclient_config' before any 'make config'. This will set up -defaults for GraphicsClient Plus support. - -The kernel zImage is linked to be loaded and executed at 0xc0200000. -Also the following registers should have the specified values upon entry:: - - r0 = 0 - r1 = 29 (this is the GraphicsClient architecture number) - -Linux can be used with the ADS BootLoader that ships with the -newer rev boards. See their documentation on how to load Linux. -Angel is not available for the GraphicsClient Plus AFAIK. - -There is a board known as just the GraphicsClient that ADS used to -produce but has end of lifed. This code will not work on the older -board with the ADS bootloader, but should still work with Angel, -as outlined below. In any case, if you're planning on deploying -something en masse, you should probably get the newer board. - -If using Angel on the older boards, here is a typical angel.opt option file -if the kernel is loaded through the Angel Debug Monitor:: - - base 0xc0200000 - entry 0xc0200000 - r0 0x00000000 - r1 0x0000001d - device /dev/ttyS1 - options "38400 8N1" - baud 115200 - #otherfile ramdisk.gz - #otherbase 0xc0800000 - exec minicom - -Then the kernel (and ramdisk if otherfile/otherbase lines above are -uncommented) would be loaded with:: - - angelboot -f angelboot.opt zImage - -Here it is assumed that the board is connected to ttyS1 on your PC -and that minicom is preconfigured with /dev/ttyS1, 38400 baud, 8N1, no flow -control by default. - -If any other bootloader is used, ensure it accomplish the same, especially -for r0/r1 register values before jumping into the kernel. - - -Supported peripherals -===================== - -- SA1100 LCD frame buffer (8/16bpp...sort of) -- on-board SMC 92C96 ethernet NIC -- SA1100 serial port -- flash memory access (MTD/JFFS) -- pcmcia -- touchscreen(ucb1200) -- ps/2 keyboard -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console -- Smart I/O (ADC, keypad, digital inputs, etc) - See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation - and example user space code. ps/2 keybd is multiplexed through this driver - -To do -===== - -- UCB1200 audio with new ucb_generic layer -- everything else! :-) - -Notes -===== - -- The flash on board is divided into 3 partitions. mtd0 is where - the ADS boot ROM and zImage is stored. It's been marked as - read-only to keep you from blasting over the bootloader. :) mtd1 is - for the ramdisk.gz image. mtd2 is user flash space and can be - utilized for either JFFS or if you're feeling crazy, running ext2 - on top of it. If you're not using the ADS bootloader, you're - welcome to blast over the mtd1 partition also. - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/graphicsmaster.rst b/Documentation/arm/sa1100/graphicsmaster.rst deleted file mode 100644 index e39892514f0c..000000000000 --- a/Documentation/arm/sa1100/graphicsmaster.rst +++ /dev/null @@ -1,60 +0,0 @@ -======================================== -ADS GraphicsMaster Single Board Computer -======================================== - -For more details, contact Applied Data Systems or see -http://www.applieddata.net/products.html - -The original Linux support for this product has been provided by -Nicolas Pitre . Continued development work by -Woojung Huh - -Use 'make graphicsmaster_config' before any 'make config'. -This will set up defaults for GraphicsMaster support. - -The kernel zImage is linked to be loaded and executed at 0xc0400000. - -Linux can be used with the ADS BootLoader that ships with the -newer rev boards. See their documentation on how to load Linux. - -Supported peripherals -===================== - -- SA1100 LCD frame buffer (8/16bpp...sort of) -- SA1111 USB Master -- on-board SMC 92C96 ethernet NIC -- SA1100 serial port -- flash memory access (MTD/JFFS) -- pcmcia, compact flash -- touchscreen(ucb1200) -- ps/2 keyboard -- console on LCD screen -- serial ports (ttyS[0-2]) - - ttyS0 is default for serial console -- Smart I/O (ADC, keypad, digital inputs, etc) - See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation - and example user space code. ps/2 keybd is multiplexed through this driver - -To do -===== - -- everything else! :-) - -Notes -===== - -- The flash on board is divided into 3 partitions. mtd0 is where - the zImage is stored. It's been marked as read-only to keep you - from blasting over the bootloader. :) mtd1 is - for the ramdisk.gz image. mtd2 is user flash space and can be - utilized for either JFFS or if you're feeling crazy, running ext2 - on top of it. If you're not using the ADS bootloader, you're - welcome to blast over the mtd1 partition also. - -- 16bpp mode requires a different cable than what ships with the board. - Contact ADS or look through the manual to wire your own. Currently, - if you compile with 16bit mode support and switch into a lower bpp - mode, the timing is off so the image is corrupted. This will be - fixed soon. - -Any contribution can be sent to nico@fluxnic.net and will be greatly welcome! diff --git a/Documentation/arm/sa1100/huw_webpanel.rst b/Documentation/arm/sa1100/huw_webpanel.rst deleted file mode 100644 index 1dc7ccb165f0..000000000000 --- a/Documentation/arm/sa1100/huw_webpanel.rst +++ /dev/null @@ -1,21 +0,0 @@ -======================= -Hoeft & Wessel Webpanel -======================= - -The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG - -If you want more information, please visit -http://www.hoeft-wessel.de - -To build the kernel:: - - make huw_webpanel_config - make oldconfig - [accept all defaults] - make zImage - -Mostly of the work is done by: -Roman Jordan jor@hoeft-wessel.de -Christoph Schulz schu@hoeft-wessel.de - -2000/12/18/ diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arm/sa1100/index.rst index 68c2a280a745..c9aed43280ff 100644 --- a/Documentation/arm/sa1100/index.rst +++ b/Documentation/arm/sa1100/index.rst @@ -7,19 +7,7 @@ Intel StrongARM 1100 .. toctree:: :maxdepth: 1 - adsbitsy assabet - brutus cerf - freebird - graphicsclient - graphicsmaster - huw_webpanel - itsy lart - nanoengine - pangolin - pleb serial_uart - tifon - yopy diff --git a/Documentation/arm/sa1100/itsy.rst b/Documentation/arm/sa1100/itsy.rst deleted file mode 100644 index f49896ba3ef1..000000000000 --- a/Documentation/arm/sa1100/itsy.rst +++ /dev/null @@ -1,47 +0,0 @@ -==== -Itsy -==== - -Itsy is a research project done by the Western Research Lab, and Systems -Research Center in Palo Alto, CA. The Itsy project is one of several -research projects at Compaq that are related to pocket computing. - -For more information, see: - - http://www.hpl.hp.com/downloads/crl/itsy/ - -Notes on initial 2.4 Itsy support (8/27/2000) : - -The port was done on an Itsy version 1.5 machine with a daughtercard with -64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for -serial console (to see what you're doing). No other devices have been -enabled. - -To build, do a "make menuconfig" (or xmenuconfig) and select Itsy support. -Disable Flash and LCD support. and then do a make zImage. -Finally, you will need to cd to arch/arm/boot/tools and execute a make there -to build the params-itsy program used to boot the kernel. - -In order to install the port of 2.4 to the itsy, You will need to set the -configuration parameters in the monitor as follows:: - - Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0 - -Make sure the start-routine address is set to 0x00060000. - -Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the -flash menu) Flash the kernel in arch/arm/boot/zImage into 0x08340000 -("p 1 0x00340000"). Finally flash an initial ramdisk into 0xC8000000 -("p 2 0x0") We used ramdisk-2-30.gz from the 0.11 version directory on -handhelds.org. - -The serial connection we established was at: - -8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the -params-itsy program, and in the kernel itself. This can be changed, but -not easily. The monitor parameters are easily changed, the params program -setup is assembly outl's, and the kernel is a configuration item specific to -the itsy. (i.e. grep for CONFIG_SA1100_ITSY and you'll find where it is.) - - -This should get you a properly booting 2.4 kernel on the itsy. diff --git a/Documentation/arm/sa1100/nanoengine.rst b/Documentation/arm/sa1100/nanoengine.rst deleted file mode 100644 index 47f1a14cf98a..000000000000 --- a/Documentation/arm/sa1100/nanoengine.rst +++ /dev/null @@ -1,11 +0,0 @@ -========== -nanoEngine -========== - -"nanoEngine" is a SA1110 based single board computer from -Bright Star Engineering Inc. See www.brightstareng.com/arm -for more info. -(Ref: Stuart Adams ) - -Also visit Larry Doolittle's "Linux for the nanoEngine" site: -http://www.brightstareng.com/arm/nanoeng.htm diff --git a/Documentation/arm/sa1100/pangolin.rst b/Documentation/arm/sa1100/pangolin.rst deleted file mode 100644 index f0c5c1618553..000000000000 --- a/Documentation/arm/sa1100/pangolin.rst +++ /dev/null @@ -1,29 +0,0 @@ -======== -Pangolin -======== - -Pangolin is a StrongARM 1110-based evaluation platform produced -by Dialogue Technology (http://www.dialogue.com.tw/). -It has EISA slots for ease of configuration with SDRAM/Flash -memory card, USB/Serial/Audio card, Compact Flash card, -PCMCIA/IDE card and TFT-LCD card. - -To compile for Pangolin, you must issue the following commands:: - - make pangolin_config - make oldconfig - make zImage - -Supported peripherals -===================== - -- SA1110 serial port (UART1/UART2/UART3) -- flash memory access -- compact flash driver -- UDA1341 sound driver -- SA1100 LCD controller for 800x600 16bpp TFT-LCD -- MQ-200 driver for 800x600 16bpp TFT-LCD -- Penmount(touch panel) driver -- PCMCIA driver -- SMC91C94 LAN driver -- IDE driver (experimental) diff --git a/Documentation/arm/sa1100/pleb.rst b/Documentation/arm/sa1100/pleb.rst deleted file mode 100644 index d5b732967aa3..000000000000 --- a/Documentation/arm/sa1100/pleb.rst +++ /dev/null @@ -1,13 +0,0 @@ -==== -PLEB -==== - -The PLEB project was started as a student initiative at the School of -Computer Science and Engineering, University of New South Wales to make a -pocket computer capable of running the Linux Kernel. - -PLEB support has yet to be fully integrated. - -For more information, see: - - http://www.cse.unsw.edu.au diff --git a/Documentation/arm/sa1100/tifon.rst b/Documentation/arm/sa1100/tifon.rst deleted file mode 100644 index c26e910b9ea7..000000000000 --- a/Documentation/arm/sa1100/tifon.rst +++ /dev/null @@ -1,7 +0,0 @@ -===== -Tifon -===== - -More info has to come... - -Contact: Peter Danielsson diff --git a/Documentation/arm/sa1100/yopy.rst b/Documentation/arm/sa1100/yopy.rst deleted file mode 100644 index 5b35a5f61a44..000000000000 --- a/Documentation/arm/sa1100/yopy.rst +++ /dev/null @@ -1,5 +0,0 @@ -==== -Yopy -==== - -See http://www.yopydeveloper.org for more. From 13afbbf49a34c21085dd6c7a48340ed5d2309729 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Thu, 8 Aug 2019 18:58:56 +0200 Subject: [PATCH 55/67] Documentation/arm/sa1100/assabet: Fix 'make assabet_defconfig' command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "make assabet_config" doesn't work. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/arm/sa1100/assabet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/arm/sa1100/assabet.rst b/Documentation/arm/sa1100/assabet.rst index 3e704831c311..a761e128fb08 100644 --- a/Documentation/arm/sa1100/assabet.rst +++ b/Documentation/arm/sa1100/assabet.rst @@ -14,7 +14,7 @@ Building the kernel To build the kernel with current defaults:: - make assabet_config + make assabet_defconfig make oldconfig make zImage From 4514fe8cd96f8147c18c05c7c32271d95d6ab0c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonathan=20Neusch=C3=A4fer?= Date: Thu, 8 Aug 2019 18:48:09 +0200 Subject: [PATCH 56/67] Documentation/arm/samsung-s3c24xx: Remove stray U+FEFF character to fix title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It seems a UTF-8 byte order mark (the least useful kind of BOM...) snuck into the file and broke Sphinx's detection of the title line. Besides making arm/samsung-s3c24xx/index.html look a little better, this patch also confines the non-index pages in arm/samsung-s3c24xx to their own table of contents. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/arm/samsung-s3c24xx/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst index 5b8a7f9398d8..ccb951a0bedb 100644 --- a/Documentation/arm/samsung-s3c24xx/index.rst +++ b/Documentation/arm/samsung-s3c24xx/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 -========================== +========================== Samsung S3C24XX SoC Family ========================== From 5aff7c46172b270af2a9b10eed3a8215c4ba9a87 Mon Sep 17 00:00:00 2001 From: Jacob Huisman Date: Fri, 16 Aug 2019 13:22:09 +0100 Subject: [PATCH 57/67] docs: process: fix broken link http://linux.yyz.us/patch-format.html seems to be down since approximately September 2018. There is a working archive copy on arhive.org. Replaced the links in documenation + translations. Signed-off-by: Jacob Huisman Reviewed-by: Federico Vaga Signed-off-by: Jonathan Corbet --- Documentation/process/howto.rst | 2 +- Documentation/process/submitting-patches.rst | 2 +- Documentation/translations/it_IT/process/howto.rst | 2 +- Documentation/translations/it_IT/process/submitting-patches.rst | 2 +- Documentation/translations/ja_JP/SubmittingPatches | 2 +- Documentation/translations/ja_JP/howto.rst | 2 +- Documentation/translations/ko_KR/howto.rst | 2 +- Documentation/translations/zh_CN/process/howto.rst | 2 +- Documentation/translations/zh_CN/process/submitting-patches.rst | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 6ab75c11d2c3..b6f5a379ad6c 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -123,7 +123,7 @@ required reading: https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst ` This file describes the rationale behind the conscious decision to diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 9c4299293c72..fb56297f70dc 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -844,7 +844,7 @@ Andrew Morton, "The perfect patch" (tpp). Jeff Garzik, "Linux kernel patch submission format". - + Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". diff --git a/Documentation/translations/it_IT/process/howto.rst b/Documentation/translations/it_IT/process/howto.rst index 44e6077730e8..1db5a1082389 100644 --- a/Documentation/translations/it_IT/process/howto.rst +++ b/Documentation/translations/it_IT/process/howto.rst @@ -129,7 +129,7 @@ Di seguito una lista di file che sono presenti nei sorgente del kernel e che https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/translations/it_IT/process/stable-api-nonsense.rst ` diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst index 7d7ea92c5c5a..cba1f8cb61ed 100644 --- a/Documentation/translations/it_IT/process/submitting-patches.rst +++ b/Documentation/translations/it_IT/process/submitting-patches.rst @@ -868,7 +868,7 @@ Andrew Morton, "La patch perfetta" (tpp). Jeff Garzik, "Formato per la sottomissione di patch per il kernel Linux" - + Greg Kroah-Hartman, "Come scocciare un manutentore di un sottosistema" diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches index ad979c3c06a6..dd0c3280ba5a 100644 --- a/Documentation/translations/ja_JP/SubmittingPatches +++ b/Documentation/translations/ja_JP/SubmittingPatches @@ -693,7 +693,7 @@ Andrew Morton, "The perfect patch" (tpp). Jeff Garzik, "Linux kernel patch submission format". - + Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". diff --git a/Documentation/translations/ja_JP/howto.rst b/Documentation/translations/ja_JP/howto.rst index 2621b770a745..73ebdab4ced7 100644 --- a/Documentation/translations/ja_JP/howto.rst +++ b/Documentation/translations/ja_JP/howto.rst @@ -139,7 +139,7 @@ linux-api@vger.kernel.org に送ることを勧めます。 "The Perfect Patch" http://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst ` このファイルはカーネルの中に不変の API を持たないことにした意識的 diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index bcd63731b80a..b3f51b19de7c 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -135,7 +135,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst ` 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 diff --git a/Documentation/translations/zh_CN/process/howto.rst b/Documentation/translations/zh_CN/process/howto.rst index b244a7190eb6..a8e6ab818983 100644 --- a/Documentation/translations/zh_CN/process/howto.rst +++ b/Documentation/translations/zh_CN/process/howto.rst @@ -113,7 +113,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/translations/zh_CN/process/stable-api-nonsense.rst ` 论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特 diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst index 437c23b367bb..1bb4271ab420 100644 --- a/Documentation/translations/zh_CN/process/submitting-patches.rst +++ b/Documentation/translations/zh_CN/process/submitting-patches.rst @@ -652,7 +652,7 @@ Andrew Morton, "The perfect patch" (tpp). Jeff Garzik, "Linux kernel patch submission format". - + Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". From f12fcca65369e87a078ae9d025ab0198421f5934 Mon Sep 17 00:00:00 2001 From: Peter Wu Date: Sat, 31 Aug 2019 16:35:00 +0100 Subject: [PATCH 58/67] docs: ftrace: clarify when tracing is disabled by the trace file The current text could mislead the user into believing that only read() disables tracing. Clarify that any open() call that requests read access disables tracing. Link: https://lkml.kernel.org/r/CAADnVQ+hU6QOC_dPmpjnuv=9g4SQEeaMEMqXOS2WpMj=q=LdiQ@mail.gmail.com Signed-off-by: Peter Wu Acked-by: Steven Rostedt (VMware) Signed-off-by: Jonathan Corbet --- Documentation/trace/ftrace.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst index f60079259669..e3060eedb22d 100644 --- a/Documentation/trace/ftrace.rst +++ b/Documentation/trace/ftrace.rst @@ -125,7 +125,8 @@ of ftrace. Here is a list of some of the key files: This file holds the output of the trace in a human readable format (described below). Note, tracing is temporarily - disabled while this file is being read (opened). + disabled when the file is open for reading. Once all readers + are closed, tracing is re-enabled. trace_pipe: @@ -139,8 +140,9 @@ of ftrace. Here is a list of some of the key files: will not be read again with a sequential read. The "trace" file is static, and if the tracer is not adding more data, it will display the same - information every time it is read. This file will not - disable tracing while being read. + information every time it is read. Unlike the + "trace" file, opening this file for reading will not + temporarily disable tracing. trace_options: @@ -3153,7 +3155,10 @@ different. The trace is live. Note, reading the trace_pipe file will block until more input is -added. +added. This is contrary to the trace file. If any process opened +the trace file for reading, it will actually disable tracing and +prevent new entries from being added. The trace_pipe file does +not have this limitation. trace entries ------------- From c193a3ffc2824a08ebd82973030bd129e13e4983 Mon Sep 17 00:00:00 2001 From: Quentin Perret Date: Mon, 2 Sep 2019 11:50:36 +0100 Subject: [PATCH 59/67] mailmap: Update email address for Quentin Perret My @arm.com email address will stop working in a few weeks, so add an entry to .mailmap so others have a way to reach me if they want to. While at it, move some entries around to keep the file in alphabetical order. Signed-off-by: Quentin Perret Acked-by: Will Deacon Signed-off-by: Jonathan Corbet --- .mailmap | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/.mailmap b/.mailmap index ea703abcb397..afbce4d329a1 100644 --- a/.mailmap +++ b/.mailmap @@ -179,6 +179,11 @@ Mythri P K Nguyen Anh Quynh Nicolas Pitre Nicolas Pitre +Oleksij Rempel +Oleksij Rempel +Oleksij Rempel +Oleksij Rempel +Oleksij Rempel Paolo 'Blaisorblade' Giarrusso Patrick Mochel Paul Burton @@ -189,11 +194,7 @@ Pratyush Anand Praveen BP Punit Agrawal Qais Yousef -Oleksij Rempel -Oleksij Rempel -Oleksij Rempel -Oleksij Rempel -Oleksij Rempel +Quentin Perret Rajesh Shah Ralf Baechle Ralf Wildenhues From 209c3aa7f0df27feb824c179a763ace3e667c8ba Mon Sep 17 00:00:00 2001 From: Adam Borowski Date: Tue, 3 Sep 2019 18:08:40 +0200 Subject: [PATCH 60/67] Documentation: sysrq: don't recommend 'S' 'U' before 'B' This advice is obsolete and slightly harmful for filesystems from this millenium: any modern filesystem can handle unexpected crashes without requiring fsck -- and on the other hand, trying to write to the disk when the kernel is in a bad state risks introducing corruption. For ext2, any unsafe shutdown meant widespread breakage, but it's no longer a reasonable filesystem for any non-special use. Signed-off-by: Adam Borowski Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysrq.rst | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst index 7b9035c01a2e..72b2cfb066f4 100644 --- a/Documentation/admin-guide/sysrq.rst +++ b/Documentation/admin-guide/sysrq.rst @@ -171,22 +171,20 @@ It seems others find it useful as (System Attention Key) which is useful when you want to exit a program that will not let you switch consoles. (For example, X or a svgalib program.) -``reboot(b)`` is good when you're unable to shut down. But you should also -``sync(s)`` and ``umount(u)`` first. +``reboot(b)`` is good when you're unable to shut down, it is an equivalent +of pressing the "reset" button. ``crash(c)`` can be used to manually trigger a crashdump when the system is hung. Note that this just triggers a crash if there is no dump mechanism available. -``sync(s)`` is great when your system is locked up, it allows you to sync your -disks and will certainly lessen the chance of data loss and fscking. Note -that the sync hasn't taken place until you see the "OK" and "Done" appear -on the screen. (If the kernel is really in strife, you may not ever get the -OK or Done message...) +``sync(s)`` is handy before yanking removable medium or after using a rescue +shell that provides no graceful shutdown -- it will ensure your data is +safely written to the disk. Note that the sync hasn't taken place until you see +the "OK" and "Done" appear on the screen. -``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally -``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved -me many a fsck. Again, the unmount (remount read-only) hasn't taken place until -you see the "OK" and "Done" message appear on the screen. +``umount(u)`` can be used to mark filesystems as properly unmounted. From the +running system's point of view, they will be remounted read-only. The remount +isn't complete until you see the "OK" and "Done" message appear on the screen. The loglevels ``0``-``9`` are useful when your console is being flooded with kernel messages you do not want to see. Selecting ``0`` will prevent all but From f145579d8398941bc9a320cab8436c4ca35d9932 Mon Sep 17 00:00:00 2001 From: lixianfa Date: Tue, 3 Sep 2019 11:07:27 +0800 Subject: [PATCH 61/67] doc: arm64: fix grammar dtb placed in no attributes region Fix grammar dtb placed in no attributes region. This makes Chinese translation smooth to read. Signed-off-by: lixinafa Signed-off-by: Jonathan Corbet --- Documentation/translations/zh_CN/arm64/booting.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt index 4e373d128d98..5b0164132c71 100644 --- a/Documentation/translations/zh_CN/arm64/booting.txt +++ b/Documentation/translations/zh_CN/arm64/booting.txt @@ -67,8 +67,8 @@ RAM，或可能使用对这个设备已知的 RAM 信息，还可能是引导装 必要性: 强制 设备树数据块（dtb）必须 8 字节对齐，且大小不能超过 2MB。由于设备树 -数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于带任意 -特定属性被映射的 2MB 区域内。 +数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于必须以特定 +属性映射的2M区域内。 注： v4.2 之前的版本同时要求设备树数据块被置于从内核映像以下 text_offset 字节处算起第一个 512MB 内。 From e62be10350ebcbfe99bd3fc0e15a0e21b1352fde Mon Sep 17 00:00:00 2001 From: John Garry Date: Wed, 7 Aug 2019 00:06:23 +0800 Subject: [PATCH 62/67] docs: mtd: Update spi nor reference driver The reference driver no longer exists since commit 50f1242c6742 ("mtd: fsl-quadspi: Remove the driver as it was replaced by spi-fsl-qspi.c"). Update reference to spi-fsl-qspi.c driver. Signed-off-by: John Garry Signed-off-by: Jonathan Corbet --- Documentation/driver-api/mtd/spi-nor.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst index f5333e3bf486..1f0437676762 100644 --- a/Documentation/driver-api/mtd/spi-nor.rst +++ b/Documentation/driver-api/mtd/spi-nor.rst @@ -59,7 +59,7 @@ Part III - How can drivers use the framework? The main API is spi_nor_scan(). Before you call the hook, a driver should initialize the necessary fields for spi_nor{}. Please see -drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to fsl-quadspi.c +drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c when you want to write a new driver for a SPI NOR controller. Another API is spi_nor_restore(), this is used to restore the status of SPI flash chip such as addressing mode. Call it whenever detach the driver from From d62e8055a596b3d3f11c1643ba18a9cbf093a0b9 Mon Sep 17 00:00:00 2001 From: Ian Abbott Date: Wed, 11 Sep 2019 17:39:41 +0100 Subject: [PATCH 63/67] devices.txt: improve entry for comedi (char major 98) Describe how the comedi minor device numbers are split across comedi devices and comedi subdevices. Replace the current, long dead URL with an official URL for the Comedi project. Signed-off-by: Ian Abbott Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/devices.txt | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt index e56e00655153..1c5d2281efc9 100644 --- a/Documentation/admin-guide/devices.txt +++ b/Documentation/admin-guide/devices.txt @@ -1647,8 +1647,17 @@ 0 = /dev/comedi0 First comedi device 1 = /dev/comedi1 Second comedi device ... + 47 = /dev/comedi47 48th comedi device - See http://stm.lbl.gov/comedi. + Minors 48 to 255 are reserved for comedi subdevices with + pathnames of the form "/dev/comediX_subdY", where "X" is the + minor number of the associated comedi device and "Y" is the + subdevice number. These subdevice minors are assigned + dynamically, so there is no fixed mapping from subdevice + pathnames to minor numbers. + + See http://www.comedi.org/ for information about the Comedi + project. 98 block User-mode virtual block device 0 = /dev/ubda First user-mode block device From 19ad5f79f92e01375070009439c9f3ae22dc6b22 Mon Sep 17 00:00:00 2001 From: Federico Vaga Date: Sun, 8 Sep 2019 08:29:01 +0200 Subject: [PATCH 64/67] doc:lock: remove reference to clever use of read-write lock Remove the clever example about read-write lock because this type of lock is not recommended anymore (according to the very same document). So there is no reason to teach clever things that people should not do. Signed-off-by: Federico Vaga Acked-by: Will Deacon Signed-off-by: Jonathan Corbet --- Documentation/locking/spinlocks.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst index e93ec6645238..66e3792f8a36 100644 --- a/Documentation/locking/spinlocks.rst +++ b/Documentation/locking/spinlocks.rst @@ -139,18 +139,6 @@ on other CPU's, because an interrupt on another CPU doesn't interrupt the CPU that holds the lock, so the lock-holder can continue and eventually releases the lock). -Note that you can be clever with read-write locks and interrupts. For -example, if you know that the interrupt only ever gets a read-lock, then -you can use a non-irq version of read locks everywhere - because they -don't block on each other (and thus there is no dead-lock wrt interrupts. -But when you do the write-lock, you have to use the irq-safe version. - -For an example of being clever with rw-locks, see the "waitqueue_lock" -handling in kernel/sched/core.c - nothing ever _changes_ a wait-queue from -within an interrupt, they only read the queue in order to know whom to -wake up. So read-locks are safe (which is good: they are very common -indeed), while write-locks need to protect themselves against interrupts. - Linus ---- From 82f12ab311fd5ab46d25c9cc51784adf37f33ad5 Mon Sep 17 00:00:00 2001 From: Palmer Dabbelt Date: Fri, 13 Sep 2019 13:38:43 -0700 Subject: [PATCH 65/67] Documentation: Add "earlycon=sbi" to the admin guide This argument is supported on RISC-V systems and widely used, but was not documented here. Signed-off-by: Palmer Dabbelt Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/kernel-parameters.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 46b826fcb5ad..ce3696d8256c 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -1044,6 +1044,10 @@ specified address. The serial port must already be setup and configured. Options are not yet supported. + sbi + Use RISC-V SBI (Supervisor Binary Interface) for early + console. + smh Use ARM semihosting calls for early console. s3c2410, From cbacb5ab0aa04a49030e520523ef9405c9cafa95 Mon Sep 17 00:00:00 2001 From: Joe Perches Date: Fri, 6 Sep 2019 14:11:51 -0700 Subject: [PATCH 66/67] docs: printk-formats: Stop encouraging use of unnecessary %h[xudi] and %hh[xudi] Standard integer promotion is already done and %hx and %hhx is useless so do not encourage the use of %hh[xudi] or %h[xudi]. As Linus said in: https://lore.kernel.org/lkml/CAHk-=wgoxnmsj8GEVFJSvTwdnWm8wVJthefNk2n6+4TC=20e0Q@mail.gmail.com/ It's a pointless warning, making for more complex code, and making people remember esoteric printf format details that have no reason for existing. The "h" and "hh" things should never be used. The only reason for them being used if if you have an "int", but you want to print it out as a "char" (and honestly, that is a really bad reason, you'd be better off just using a proper cast to make the code more obvious). So if what you have a "char" (or unsigned char) you should always just print it out as an "int", knowing that the compiler already did the proper type conversion. Signed-off-by: Joe Perches Reviewed-by: Louis Taylor Signed-off-by: Jonathan Corbet --- Documentation/core-api/printk-formats.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index c6224d039bcb..ecbebf4ca8e7 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -13,10 +13,10 @@ Integer types If variable is of Type, use printk format specifier: ------------------------------------------------------------ - char %hhd or %hhx - unsigned char %hhu or %hhx - short int %hd or %hx - unsigned short int %hu or %hx + char %d or %x + unsigned char %u or %x + short int %d or %x + unsigned short int %u or %x int %d or %x unsigned int %u or %x long %ld or %lx @@ -25,10 +25,10 @@ Integer types unsigned long long %llu or %llx size_t %zu or %zx ssize_t %zd or %zx - s8 %hhd or %hhx - u8 %hhu or %hhx - s16 %hd or %hx - u16 %hu or %hx + s8 %d or %x + u8 %u or %x + s16 %d or %x + u16 %u or %x s32 %d or %x u32 %u or %x s64 %lld or %llx From fe013f8bc160d79c6e33bb66d9bb0cd24949274c Mon Sep 17 00:00:00 2001 From: Ben Hutchings Date: Sat, 14 Sep 2019 12:24:21 +0100 Subject: [PATCH 67/67] Documentation: kbuild: Add document about reproducible builds In the Distribution Kernels track at Linux Plumbers Conference there was some discussion around the difficulty of making kernel builds reproducible. This is a solved problem, but the solutions don't appear to be documented in one place. This document lists the issues I know about and the settings needed to ensure reproducibility. Signed-off-by: Ben Hutchings Acked-by: Masahiro Yamada Signed-off-by: Jonathan Corbet --- Documentation/kbuild/index.rst | 1 + Documentation/kbuild/reproducible-builds.rst | 122 +++++++++++++++++++ 2 files changed, 123 insertions(+) create mode 100644 Documentation/kbuild/reproducible-builds.rst diff --git a/Documentation/kbuild/index.rst b/Documentation/kbuild/index.rst index e323a3f2cc81..0f144fad99a6 100644 --- a/Documentation/kbuild/index.rst +++ b/Documentation/kbuild/index.rst @@ -18,6 +18,7 @@ Kernel Build System headers_install issues + reproducible-builds .. only:: subproject and html diff --git a/Documentation/kbuild/reproducible-builds.rst b/Documentation/kbuild/reproducible-builds.rst new file mode 100644 index 000000000000..ab92e98c89c8 --- /dev/null +++ b/Documentation/kbuild/reproducible-builds.rst @@ -0,0 +1,122 @@ +=================== +Reproducible builds +=================== + +It is generally desirable that building the same source code with +the same set of tools is reproducible, i.e. the output is always +exactly the same. This makes it possible to verify that the build +infrastructure for a binary distribution or embedded system has not +been subverted. This can also make it easier to verify that a source +or tool change does not make any difference to the resulting binaries. + +The `Reproducible Builds project`_ has more information about this +general topic. This document covers the various reasons why building +the kernel may be unreproducible, and how to avoid them. + +Timestamps +---------- + +The kernel embeds a timestamp in two places: + +* The version string exposed by ``uname()`` and included in + ``/proc/version`` + +* File timestamps in the embedded initramfs + +By default the timestamp is the current time. This must be overridden +using the `KBUILD_BUILD_TIMESTAMP`_ variable. If you are building +from a git commit, you could use its commit date. + +The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, +and enables warnings if they are used. If you incorporate external +code that does use these, you must override the timestamp they +correspond to by setting the `SOURCE_DATE_EPOCH`_ environment +variable. + +User, host +---------- + +The kernel embeds the building user and host names in +``/proc/version``. These must be overridden using the +`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are +building from a git commit, you could use its committer address. + +Absolute filenames +------------------ + +When the kernel is built out-of-tree, debug information may include +absolute filenames for the source files. This must be overridden by +including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable. + +Depending on the compiler used, the ``__FILE__`` macro may also expand +to an absolute filename in an out-of-tree build. Kbuild automatically +uses the ``-fmacro-prefix-map`` option to prevent this, if it is +supported. + +The Reproducible Builds web site has more information about these +`prefix-map options`_. + +Generated files in source packages +---------------------------------- + +The build processes for some programs under the ``tools/`` +subdirectory do not completely support out-of-tree builds. This may +cause a later source package build using e.g. ``make rpm-pkg`` to +include generated files. You should ensure the source tree is +pristine by running ``make mrproper`` or ``git clean -d -f -x`` before +building a source package. + +Module signing +-------------- + +If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to +generate a different temporary key for each build, resulting in the +modules being unreproducible. However, including a signing key with +your source would presumably defeat the purpose of signing modules. + +One approach to this is to divide up the build process so that the +unreproducible parts can be treated as sources: + +1. Generate a persistent signing key. Add the certificate for the key + to the kernel source. + +2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the + signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an + empty string, and disable ``CONFIG_MODULE_SIG_ALL``. + Build the kernel and modules. + +3. Create detached signatures for the modules, and publish them as + sources. + +4. Perform a second build that attaches the module signatures. It + can either rebuild the modules or use the output of step 2. + +Structure randomisation +----------------------- + +If you enable ``CONFIG_GCC_PLUGIN_RANDSTRUCT``, you will need to +pre-generate the random seed in +``scripts/gcc-plgins/randomize_layout_seed.h`` so the same value +is used in rebuilds. + +Debug info conflicts +-------------------- + +This is not a problem of unreproducibility, but of generated files +being *too* reproducible. + +Once you set all the necessary variables for a reproducible build, a +vDSO's debug information may be identical even for different kernel +versions. This can result in file conflicts between debug information +packages for the different kernel versions. + +To avoid this, you can make the vDSO different for different +kernel versions by including an arbitrary string of "salt" in it. +This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``. + +.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp +.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host +.. _KCFLAGS: kbuild.html#kcflags +.. _prefix-map options: https://reproducible-builds.org/docs/build-path/ +.. _Reproducible Builds project: https://reproducible-builds.org/ +.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/