From 4350937f730de6ea213be3bf1764df6d26e5d8b7 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 29 Aug 2020 10:23:42 +0200 Subject: Documentation/kokr: bring process docs up to date Translate this commit to Korean: fb0e0ffe7fc8 ("Documentation: bring process docs up to date") Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20200829082343.2979-2-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/translations/ko_KR/howto.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index 71d4823e41e1..6731378bd842 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -286,7 +286,8 @@ Andrew Morton의 글이 있다. 3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 해당 메이저 메인라인 릴리즈에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 -수정들을 포함하며, 앞의 두 버전 넘버는 같은 기반 버전을 의미한다. +수정들을 포함한다. 주요 stable 시리즈 릴리즈는 세번째 버전 넘버를 증가시키며 +앞의 두 버전 넘버는 그대로 유지한다. 이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며, 개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다. -- cgit v1.2.3 From b21b8da456c8df180277e67a88e977f9c46c707b Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 29 Aug 2020 10:23:43 +0200 Subject: Documentation/kokr/howto: Wordsmith The sentence regarding version numbers of '-stable' kernels is quite ambiguous. This commit makes the sentence more clear and fix inconsistent uses of the terms for 'version'. Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20200829082343.2979-3-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/translations/ko_KR/howto.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index 6731378bd842..240d29be38f2 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -284,10 +284,10 @@ Andrew Morton의 글이 있다. 여러 메이저 넘버를 갖는 다양한 안정된 커널 트리들 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 해당 메이저 -메인라인 릴리즈에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 -수정들을 포함한다. 주요 stable 시리즈 릴리즈는 세번째 버전 넘버를 증가시키며 -앞의 두 버전 넘버는 그대로 유지한다. +세개의 버젼 넘버로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 해당 +메이저 메인라인 릴리즈에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 +중요한 수정들을 포함한다. 주요 stable 시리즈 릴리즈는 세번째 버젼 넘버를 +증가시키며 앞의 두 버젼 넘버는 그대로 유지한다. 이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며, 개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다. @@ -317,7 +317,7 @@ Andrew Morton의 글이 있다. 제안된 패치는 서브시스템 트리에 커밋되기 전에 메일링 리스트를 통해 리뷰된다(아래의 관련 섹션을 참고하기 바란다). 일부 커널 서브시스템의 경우, 이 리뷰 프로세스는 patchwork라는 도구를 통해 추적된다. patchwork은 등록된 패치와 -패치에 대한 코멘트, 패치의 버전을 볼 수 있는 웹 인터페이스를 제공하고, +패치에 대한 코멘트, 패치의 버젼을 볼 수 있는 웹 인터페이스를 제공하고, 메인테이너는 패치를 리뷰 중, 리뷰 통과, 또는 반려됨으로 표시할 수 있다. 대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 에 나열되어 있다. -- cgit v1.2.3 From 537f3a7cf48e9c33734273eada3b23c6b21e5687 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 29 Aug 2020 10:26:05 +0200 Subject: docs/memory-barriers.txt: Fix references for DMA*.txt files Commit 985098a05eee ("docs: fix references for DMA*.txt files") missed fixing memory-barriers.txt file. This commit applies the change to the file. Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20200829082607.3146-2-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/memory-barriers.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 96186332e5f4..17c8e0c2deb4 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -546,8 +546,8 @@ There are certain things that the Linux kernel memory barriers do not guarantee: [*] For information on bus mastering DMA and coherency please read: Documentation/driver-api/pci/pci.rst - Documentation/DMA-API-HOWTO.txt - Documentation/DMA-API.txt + Documentation/core-api/dma-api-howto.rst + Documentation/core-api/dma-api.rst DATA DEPENDENCY BARRIERS (HISTORICAL) @@ -1932,8 +1932,8 @@ There are some more advanced barrier functions: here. See the subsection "Kernel I/O barrier effects" for more information on - relaxed I/O accessors and the Documentation/DMA-API.txt file for more - information on consistent memory. + relaxed I/O accessors and the Documentation/core-api/dma-api.rst file for + more information on consistent memory. (*) pmem_wmb(); -- cgit v1.2.3 From 20aa600aee63c95cde2203dabc82faeab7594019 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 29 Aug 2020 10:26:06 +0200 Subject: docs/memory-barriers.txt/kokr: Remove remaining references to mmiowb() Translate this commit to Korean: a897b13d1b77 ("docs/memory-barriers.txt: Remove remaining references to mmiowb()") Signed-off-by: SeongJae Park Reviewed-by: Yunjae Lee Link: https://lore.kernel.org/r/20200829082607.3146-3-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/translations/ko_KR/memory-barriers.txt | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index 9dcc7c9d52e6..291039d77694 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -91,7 +91,6 @@ Documentation/memory-barriers.txt - 컴파일러 배리어. - CPU 메모리 배리어. - - MMIO 쓰기 배리어. (*) 암묵적 커널 메모리 배리어. @@ -103,7 +102,6 @@ Documentation/memory-barriers.txt (*) CPU 간 ACQUIRING 배리어의 효과. - Acquire vs 메모리 액세스. - - Acquire vs I/O 액세스. (*) 메모리 배리어가 필요한 곳 @@ -515,14 +513,13 @@ CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니 완료되기 전에 행해진 것처럼 보일 수 있습니다. ACQUIRE 와 RELEASE 오퍼레이션의 사용은 일반적으로 다른 메모리 배리어의 - 필요성을 없앱니다 (하지만 "MMIO 쓰기 배리어" 서브섹션에서 설명되는 예외를 - 알아두세요). 또한, RELEASE+ACQUIRE 조합은 범용 메모리 배리어처럼 동작할 - 것을 보장하지 -않습니다-. 하지만, 어떤 변수에 대한 RELEASE 오퍼레이션을 - 앞서는 메모리 액세스들의 수행 결과는 이 RELEASE 오퍼레이션을 뒤이어 같은 - 변수에 대해 수행된 ACQUIRE 오퍼레이션을 뒤따르는 메모리 액세스에는 보여질 - 것이 보장됩니다. 다르게 말하자면, 주어진 변수의 크리티컬 섹션에서는, 해당 - 변수에 대한 앞의 크리티컬 섹션에서의 모든 액세스들이 완료되었을 것을 - 보장합니다. + 필요성을 없앱니다. 또한, RELEASE+ACQUIRE 조합은 범용 메모리 배리어처럼 + 동작할 것을 보장하지 -않습니다-. 하지만, 어떤 변수에 대한 RELEASE + 오퍼레이션을 앞서는 메모리 액세스들의 수행 결과는 이 RELEASE 오퍼레이션을 + 뒤이어 같은 변수에 대해 수행된 ACQUIRE 오퍼레이션을 뒤따르는 메모리 + 액세스에는 보여질 것이 보장됩니다. 다르게 말하자면, 주어진 변수의 + 크리티컬 섹션에서는, 해당 변수에 대한 앞의 크리티컬 섹션에서의 모든 + 액세스들이 완료되었을 것을 보장합니다. 즉, ACQUIRE 는 최소한의 "취득" 동작처럼, 그리고 RELEASE 는 최소한의 "공개" 처럼 동작한다는 의미입니다. @@ -1501,8 +1498,6 @@ u 로의 스토어를 cpu1() 의 v 로부터의 로드 뒤에 일어난 것으 (*) CPU 메모리 배리어. - (*) MMIO 쓰기 배리어. - 컴파일러 배리어 --------------- -- cgit v1.2.3 From 33afda77a783b91950f82fddcb04e0aabf83a402 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Sat, 29 Aug 2020 10:40:27 +0200 Subject: docs/memory-barriers.txt/kokr: Allow architecture to override the flush barrier Translate this commit to Korean: 3e79f082ebfc ("libnvdimm/nvdimm/flush: Allow architecture to override the flush barrier") Signed-off-by: SeongJae Park Reviewed-by: Yunjae Lee Link: https://lore.kernel.org/r/20200829084027.4591-1-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/translations/ko_KR/memory-barriers.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index 291039d77694..64d932f5dc77 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -1904,6 +1904,19 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효 "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을 위해선 Documentation/core-api/dma-api.rst 문서를 참고하세요. + (*) pmem_wmb(); + + 이것은 persistent memory 를 위한 것으로, persistent 저장소에 가해진 변경 + 사항이 플랫폼 연속성 도메인에 도달했을 것을 보장하기 위한 것입니다. + + 예를 들어, 임시적이지 않은 pmem 영역으로의 쓰기 후, 우리는 쓰기가 플랫폼 + 연속성 도메인에 도달했을 것을 보장하기 위해 pmem_wmb() 를 사용합니다. + 이는 쓰기가 뒤따르는 instruction 들이 유발하는 어떠한 데이터 액세스나 + 데이터 전송의 시작 전에 persistent 저장소를 업데이트 했을 것을 보장합니다. + 이는 wmb() 에 의해 이뤄지는 순서 규칙을 포함합니다. + + Persistent memory 에서의 로드를 위해선 현재의 읽기 메모리 배리어로도 읽기 + 순서를 보장하는데 충분합니다. ========================= 암묵적 커널 메모리 배리어 -- cgit v1.2.3 From 4680af672bc0ac4c751ea36cef22322c49ca7172 Mon Sep 17 00:00:00 2001 From: Andrew Cooper Date: Thu, 27 Aug 2020 18:54:05 +0100 Subject: docs/ia64: Drop obsolete Xen documentation While the xensource.com URLs referenced still exist, neither the Xen or Linux 2.6.18 fork have been touched since 2009, 11 years ago. Other URLs are dead. IA64 support was removed in Xen 4.2, in 2012. Relegate this piece of documentation to source history. Signed-off-by: Andrew Cooper Link: https://lore.kernel.org/r/20200827175405.24344-1-andrew.cooper3@citrix.com Signed-off-by: Jonathan Corbet --- Documentation/ia64/index.rst | 1 - Documentation/ia64/xen.rst | 206 ------------------------------------------- 2 files changed, 207 deletions(-) delete mode 100644 Documentation/ia64/xen.rst diff --git a/Documentation/ia64/index.rst b/Documentation/ia64/index.rst index 0436e1034115..4bdfe28067ee 100644 --- a/Documentation/ia64/index.rst +++ b/Documentation/ia64/index.rst @@ -15,4 +15,3 @@ IA-64 Architecture irq-redir mca serial - xen diff --git a/Documentation/ia64/xen.rst b/Documentation/ia64/xen.rst deleted file mode 100644 index 831339c74441..000000000000 --- a/Documentation/ia64/xen.rst +++ /dev/null @@ -1,206 +0,0 @@ -******************************************************** -Recipe for getting/building/running Xen/ia64 with pv_ops -******************************************************** -This recipe describes how to get xen-ia64 source and build it, -and run domU with pv_ops. - -Requirements -============ - - - python - - mercurial - it (aka "hg") is an open-source source code - management software. See the below. - http://www.selenic.com/mercurial/wiki/ - - git - - bridge-utils - -Getting and Building Xen and Dom0 -================================= - - My environment is: - - - Machine : Tiger4 - - Domain0 OS : RHEL5 - - DomainU OS : RHEL5 - - 1. Download source:: - - # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg - # cd xen-unstable.hg - # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg - - 2. # make world - - 3. # make install-tools - - 4. copy kernels and xen:: - - # cp xen/xen.gz /boot/efi/efi/redhat/ - # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \ - /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen - - 5. make initrd for Dom0/DomU:: - - # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \ - O=$(pwd)/build-linux-2.6.18-xen_ia64 - # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \ - 2.6.18.8-xen --builtin mptspi --builtin mptbase \ - --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \ - --builtin ehci-hcd - -Making a disk image for guest OS -================================ - - 1. make file:: - - # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0 - # mke2fs -F -j /root/rhel5.img - # mount -o loop /root/rhel5.img /mnt - # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt - # mkdir /mnt/{root,proc,sys,home,tmp} - - Note: You may miss some device files. If so, please create them - with mknod. Or you can use tar instead of cp. - - 2. modify DomU's fstab:: - - # vi /mnt/etc/fstab - /dev/xvda1 / ext3 defaults 1 1 - none /dev/pts devpts gid=5,mode=620 0 0 - none /dev/shm tmpfs defaults 0 0 - none /proc proc defaults 0 0 - none /sys sysfs defaults 0 0 - - 3. modify inittab - - set runlevel to 3 to avoid X trying to start:: - - # vi /mnt/etc/inittab - id:3:initdefault: - - Start a getty on the hvc0 console:: - - X0:2345:respawn:/sbin/mingetty hvc0 - - tty1-6 mingetty can be commented out - - 4. add hvc0 into /etc/securetty:: - - # vi /mnt/etc/securetty (add hvc0) - - 5. umount:: - - # umount /mnt - -FYI, virt-manager can also make a disk image for guest OS. -It's GUI tools and easy to make it. - -Boot Xen & Domain0 -================== - - 1. replace elilo - elilo of RHEL5 can boot Xen and Dom0. - If you use old elilo (e.g RHEL4), please download from the below - http://elilo.sourceforge.net/cgi-bin/blosxom - and copy into /boot/efi/efi/redhat/:: - - # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi - - 2. modify elilo.conf (like the below):: - - # vi /boot/efi/efi/redhat/elilo.conf - prompt - timeout=20 - default=xen - relocatable - - image=vmlinuz-2.6.18.8-xen - label=xen - vmm=xen.gz - initrd=initrd-2.6.18.8-xen.img - read-only - append=" -- rhgb root=/dev/sda2" - -The append options before "--" are for xen hypervisor, -the options after "--" are for dom0. - -FYI, your machine may need console options like -"com1=19200,8n1 console=vga,com1". For example, -append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \ -console=ttyS0 root=/dev/sda2" - -Getting and Building domU with pv_ops -===================================== - - 1. get pv_ops tree:: - - # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/ - - 2. git branch (if necessary):: - - # cd linux-2.6-xen-ia64/ - # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19 - - Note: - The current branch is xen-ia64-domu-minimal-2008may19. - But you would find the new branch. You can see with - "git branch -r" to get the branch lists. - - http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/ - - is also available. - - The tree is based on - - git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test) - - 3. copy .config for pv_ops of domU:: - - # cp arch/ia64/configs/xen_domu_wip_defconfig .config - - 4. make kernel with pv_ops:: - - # make oldconfig - # make - - 5. install the kernel and initrd:: - - # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU - # make modules_install - # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \ - 2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \ - --builtin mptbase --builtin mptscsih --builtin uhci-hcd \ - --builtin ohci-hcd --builtin ehci-hcd - -Boot DomainU with pv_ops -======================== - - 1. make config of DomU:: - - # vi /etc/xen/rhel5 - kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU" - ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img" - vcpus = 1 - memory = 512 - name = "rhel5" - disk = [ 'file:/root/rhel5.img,xvda1,w' ] - root = "/dev/xvda1 ro" - extra= "rhgb console=hvc0" - - 2. After boot xen and dom0, start xend:: - - # /etc/init.d/xend start - - ( In the debugging case, `# XEND_DEBUG=1 xend trace_start` ) - - 3. start domU:: - - # xm create -c rhel5 - -Reference -========= -- Wiki of Xen/IA64 upstream merge - http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge - -Written by Akio Takebe on 28 May 2008 -- cgit v1.2.3 From eb45fb2fb16df0050b9ae28f06095d72278959d9 Mon Sep 17 00:00:00 2001 From: Krzysztof Kozlowski Date: Thu, 27 Aug 2020 12:53:18 +0200 Subject: docs: process: Add cross-link to security-bugs The submitting patches mentions criteria for a fix to be called "security fix". Add a link to document explaining the entire process of handling security bugs. Signed-off-by: Krzysztof Kozlowski Reviewed-by: Greg Kroah-Hartman Reviewed-by: Felipe Balbi Cc: Linus Torvalds Cc: Kees Cook Link: https://lore.kernel.org/r/20200827105319.9734-1-krzk@kernel.org Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-patches.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 5219bf3cddfc..d5b3c5a74d5d 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -299,7 +299,8 @@ sending him e-mail. If you have a patch that fixes an exploitable security bug, send that patch to security@kernel.org. For severe bugs, a short embargo may be considered to allow distributors to get the patch out to users; in such cases, -obviously, the patch should not be sent to any public lists. +obviously, the patch should not be sent to any public lists. See also +:ref:`Documentation/admin-guide/security-bugs.rst `. Patches that fix a severe bug in a released kernel should be directed toward the stable maintainers by putting a line like this:: -- cgit v1.2.3 From 3519c4d6e08ea695658b961829d4a603acf8e28a Mon Sep 17 00:00:00 2001 From: Nick Desaulniers Date: Wed, 26 Aug 2020 12:15:55 -0700 Subject: Documentation: add minimum clang/llvm version Based on a vote at the LLVM BoF at Plumbers 2020, we decided to start small, supporting just one formal upstream release of LLVM for now. We can probably widen the support window of supported versions over time. Also, note that LLVM's release process is different than GCC's. GCC tends to have 1 major release per year while releasing minor updates to the past 3 major versions. LLVM tends to support one major release and one minor release every six months. Signed-off-by: Nick Desaulniers Tested-by: Gustavo A. R. Silva Tested-by: Nathan Chancellor Reviewed-by: Kees Cook Reviewed-by: Nathan Chancellor Reviewed-by: Masahiro Yamada Acked-by: Will Deacon Link: https://lore.kernel.org/r/20200826191555.3350406-1-ndesaulniers@google.com Signed-off-by: Jonathan Corbet --- Documentation/kbuild/llvm.rst | 4 ++++ Documentation/process/changes.rst | 15 +++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index 2aac50b97921..3f10a9c47551 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -1,3 +1,5 @@ +.. _kbuild_llvm: + ============================== Building Linux with Clang/LLVM ============================== @@ -73,6 +75,8 @@ Getting Help - `Wiki `_ - `Beginner Bugs `_ +.. _getting_llvm: + Getting LLVM ------------- diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index ee741763a3fc..dac17711dc11 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -30,6 +30,7 @@ you probably needn't concern yourself with pcmciautils. Program Minimal version Command to check the version ====================== =============== ======================================== GNU C 4.9 gcc --version +Clang/LLVM (optional) 10.0.1 clang --version GNU make 3.81 make --version binutils 2.23 ld -v flex 2.5.35 flex --version @@ -68,6 +69,15 @@ GCC The gcc version requirements may vary depending on the type of CPU in your computer. +Clang/LLVM (optional) +--------------------- + +The latest formal release of clang and LLVM utils (according to +`releases.llvm.org `_) are supported for building +kernels. Older releases aren't guaranteed to work, and we may drop workarounds +from the kernel that were used to support older versions. Please see additional +docs on :ref:`Building Linux with Clang/LLVM `. + Make ---- @@ -331,6 +341,11 @@ gcc - +Clang/LLVM +---------- + +- :ref:`Getting LLVM `. + Make ---- -- cgit v1.2.3 From 3942ea7a10c93a379cf33710ece8fe0775950368 Mon Sep 17 00:00:00 2001 From: Joe Perches Date: Wed, 26 Aug 2020 20:12:01 -0700 Subject: deprecated.rst: Remove now removed uninitialized_var It's now gone from the kernel so remove it from the deprecated API text. Signed-off-by: Joe Perches Reviewed-by: Nick Desaulniers Link: https://lore.kernel.org/r/5e10c1645dd8f735215cf54a74db0f8dd3f6cbd5.camel@perches.com Signed-off-by: Jonathan Corbet --- Documentation/process/deprecated.rst | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst index 918e32d76fc4..70720f00b9aa 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -51,24 +51,6 @@ to make sure their systems do not continue running in the face of "unreachable" conditions. (For example, see commits like `this one `_.) -uninitialized_var() -------------------- -For any compiler warnings about uninitialized variables, just add -an initializer. Using the uninitialized_var() macro (or similar -warning-silencing tricks) is dangerous as it papers over `real bugs -`_ -(or can in the future), and suppresses unrelated compiler warnings -(e.g. "unused variable"). If the compiler thinks it is uninitialized, -either simply initialize the variable or make compiler changes. Keep in -mind that in most cases, if an initialization is obviously redundant, -the compiler's dead-store elimination pass will make sure there are no -needless variable writes. - -As Linus has said, this macro -`must `_ -`be `_ -`removed `_. - open-coded arithmetic in allocator arguments -------------------------------------------- Dynamic size calculations (especially multiplication) should not be -- cgit v1.2.3 From 755a2f180c91836ab001ae785d71ebb24250acdf Mon Sep 17 00:00:00 2001 From: Dave Hansen Date: Fri, 14 Aug 2020 07:56:25 -0700 Subject: Documentation: clarify driver licensing rules Greg has challenged some recent driver submitters on their license choices. He was correct to do so, as the choices in these instances did not always advance the aims of the submitters. But, this left submitters (and the folks who help them pick licenses) a bit confused. They have read things like Documentation/process/license-rules.rst which says: individual source files can have a different license which is required to be compatible with the GPL-2.0 and Documentation/process/submitting-drivers.rst: We don't insist on any kind of exclusive GPL licensing, and if you wish ... you may well wish to release under multiple licenses. As written, these appear a _bit_ more laissez faire than we've been in practice lately. It sounds like we at least expect submitters to make a well-reasoned license choice and to explain their rationale. It does not appear that we blindly accept anything that is simply GPLv2-compatible. Drivers appear to be the most acute source of misunderstanding, so fix the driver documentation first. Update it to clarify expectations. Signed-off-by: Dave Hansen Cc: Dan Williams Cc: H. Peter Anvin Cc: Thomas Gleixner Reviewed-by: Greg Kroah-Hartman Link: https://lore.kernel.org/r/20200814145625.8B708079@viggo.jf.intel.com Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-drivers.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 74b35bfc6623..3861887e0ca5 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -60,10 +60,11 @@ What Criteria Determine Acceptance Licensing: The code must be released to us under the - GNU General Public License. We don't insist on any kind - of exclusive GPL licensing, and if you wish the driver - to be useful to other communities such as BSD you may well - wish to release under multiple licenses. + GNU General Public License. If you wish the driver to be + useful to other communities such as BSD you may release + under multiple licenses. If you choose to release under + licenses other than the GPL, you should include your + rationale for your license choices in your cover letter. See accepted licenses at include/linux/module.h Copyright: -- cgit v1.2.3 From f67281a72b30024b376ec3c2780bdfb777395c09 Mon Sep 17 00:00:00 2001 From: Javier Garcia Date: Tue, 1 Sep 2020 11:09:49 +0200 Subject: Documentation: process: step 2: Link to email list fixed. In the past, these email lists where located at lists.redhat.com. This is not longer the case and they are now at redhat.com/mailman/listinfo Signed-off-by: Javier Garcia Link: https://lore.kernel.org/r/20200901090949.14514-1-javier@beren.dev Signed-off-by: Jonathan Corbet --- Documentation/process/2.Process.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst index 4ae1e0f600c1..e05fb1b8f8b6 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -405,7 +405,7 @@ be found at: http://vger.kernel.org/vger-lists.html There are lists hosted elsewhere, though; a number of them are at -lists.redhat.com. +redhat.com/mailman/listinfo. The core mailing list for kernel development is, of course, linux-kernel. This list is an intimidating place to be; volume can reach 500 messages per -- cgit v1.2.3 From d82b1e833e7cf4265b88287f469454a66afe95d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=ADcolas=20F=2E=20R=2E=20A=2E=20Prado?= Date: Thu, 3 Sep 2020 00:58:19 +0000 Subject: docs: Add automatic cross-reference for C types MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In order to cross-reference C types in the documentation, Sphinx requires the syntax :c:type:`type_name`, or even :c:type:`struct type_name ` in order to have the link text different from the target text. Extend automarkup to enable automatic cross-reference of C types by matching any "struct|union|enum|typedef type_name" expression. This makes the documentation's plain text cleaner and adds cross-reference to types without any additional effort by the author. Signed-off-by: Nícolas F. R. A. Prado Link: https://lore.kernel.org/r/20200903005747.3900333-2-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet --- Documentation/sphinx/automarkup.py | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py index b18236370742..272eb2bdfab1 100644 --- a/Documentation/sphinx/automarkup.py +++ b/Documentation/sphinx/automarkup.py @@ -13,6 +13,7 @@ if sphinx.version_info[0] < 2 or \ else: from sphinx.errors import NoUri import re +from itertools import chain # # Regex nastiness. Of course. @@ -21,7 +22,8 @@ import re # :c:func: block (i.e. ":c:func:`mmap()`s" flakes out), so the last # bit tries to restrict matches to things that won't create trouble. # -RE_function = re.compile(r'([\w_][\w\d_]+\(\))') +RE_function = re.compile(r'(([\w_][\w\d_]+)\(\))') +RE_type = re.compile(r'(struct|union|enum|typedef)\s+([\w_][\w\d_]+)') # # Many places in the docs refer to common system calls. It is @@ -35,31 +37,39 @@ Skipfuncs = [ 'open', 'close', 'read', 'write', 'fcntl', 'mmap', 'socket' ] # -# Find all occurrences of function() and try to replace them with -# appropriate cross references. +# Find all occurrences of C references (function() and struct/union/enum/typedef +# type_name) and try to replace them with appropriate cross references. # -def markup_funcs(docname, app, node): +def markup_c_refs(docname, app, node): + class_str = {RE_function: 'c-func', RE_type: 'c-type'} + reftype_str = {RE_function: 'function', RE_type: 'type'} + cdom = app.env.domains['c'] t = node.astext() done = 0 repl = [ ] - for m in RE_function.finditer(t): + # + # Sort all C references by the starting position in text + # + sorted_matches = sorted(chain(RE_type.finditer(t), RE_function.finditer(t)), + key=lambda m: m.start()) + for m in sorted_matches: # - # Include any text prior to function() as a normal text node. + # Include any text prior to match as a normal text node. # if m.start() > done: repl.append(nodes.Text(t[done:m.start()])) # # Go through the dance of getting an xref out of the C domain # - target = m.group(1)[:-2] - target_text = nodes.Text(target + '()') + target = m.group(2) + target_text = nodes.Text(m.group(0)) xref = None - if target not in Skipfuncs: - lit_text = nodes.literal(classes=['xref', 'c', 'c-func']) + if not (m.re == RE_function and target in Skipfuncs): + lit_text = nodes.literal(classes=['xref', 'c', class_str[m.re]]) lit_text += target_text pxref = addnodes.pending_xref('', refdomain = 'c', - reftype = 'function', + reftype = reftype_str[m.re], reftarget = target, modname = None, classname = None) # @@ -68,7 +78,8 @@ def markup_funcs(docname, app, node): # try: xref = cdom.resolve_xref(app.env, docname, app.builder, - 'function', target, pxref, lit_text) + reftype_str[m.re], target, pxref, + lit_text) except NoUri: xref = None # @@ -97,7 +108,7 @@ def auto_markup(app, doctree, name): for para in doctree.traverse(nodes.paragraph): for node in para.traverse(nodes.Text): if not isinstance(node.parent, nodes.literal): - node.parent.replace(node, markup_funcs(name, app, node)) + node.parent.replace(node, markup_c_refs(name, app, node)) def setup(app): app.connect('doctree-resolved', auto_markup) -- cgit v1.2.3 From 7c8b9e3000f82de68373db23819f9585e54186bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?N=C3=ADcolas=20F=2E=20R=2E=20A=2E=20Prado?= Date: Thu, 3 Sep 2020 00:58:26 +0000 Subject: kernel-doc: Update "cross-referencing from rST" section to use automarkup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update text and examples in the "Cross-referencing from reStructuredText" section to reflect that no additional syntax is needed anymore. Signed-off-by: Nícolas F. R. A. Prado Link: https://lore.kernel.org/r/20200903005747.3900333-3-nfraprado@protonmail.com Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index fff6604631ea..4fd86c21397b 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -387,22 +387,23 @@ Domain`_ references. Cross-referencing from reStructuredText ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To cross-reference the functions and types defined in the kernel-doc comments -from reStructuredText documents, please use the `Sphinx C Domain`_ -references. For example:: - - See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`. - -While the type reference works with just the type name, without the -struct/union/enum/typedef part in front, you may want to use:: - - See :c:type:`struct foo `. - See :c:type:`union bar `. - See :c:type:`enum baz `. - See :c:type:`typedef meh `. - -This will produce prettier links, and is in line with how kernel-doc does the -cross-references. +No additional syntax is needed to cross-reference the functions and types +defined in the kernel-doc comments from reStructuredText documents. +Just end function names with ``()`` and write ``struct``, ``union``, ``enum`` +or ``typedef`` before types. +For example:: + + See foo(). + See struct foo. + See union bar. + See enum baz. + See typedef meh. + +However, if you want custom text in the cross-reference link, that can be done +through the following syntax:: + + See :c:func:`my custom link text for function foo `. + See :c:type:`my custom link text for struct bar `. For further details, please refer to the `Sphinx C Domain`_ documentation. -- cgit v1.2.3 From ef227c39b6f70d9ad83f6bda1914070211f8795b Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Thu, 3 Sep 2020 12:05:42 -0400 Subject: submitting-patches.rst: remove heading numbering This follows similar changes throughout Documentation; these numbers tend to get outdated and are not especially useful. Signed-off-by: Drew DeVault Link: https://lore.kernel.org/r/20200903160545.83185-2-sir@cmpwn.com Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-patches.rst | 68 ++++++++++++++-------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index d5b3c5a74d5d..ad25585a518a 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -24,8 +24,8 @@ of the mechanical work done for you, though you'll still need to prepare and document a sensible set of patches. In general, use of ``git`` will make your life as a kernel developer easier. -0) Obtain a current source tree -------------------------------- +Obtain a current source tree +---------------------------- If you do not have a repository with the current kernel source handy, use ``git`` to obtain one. You'll want to start with the mainline repository, @@ -99,8 +99,8 @@ is another popular alternative. .. _describe_changes: -2) Describe your changes ------------------------- +Describe your changes +--------------------- Describe your problem. Whether your patch is a one-line bug fix or 5000 lines of a new feature, there must be an underlying problem that @@ -203,8 +203,8 @@ An example call:: .. _split_changes: -3) Separate your changes ------------------------- +Separate your changes +--------------------- Separate each **logical change** into a separate patch. @@ -236,8 +236,8 @@ then only post say 15 or so at a time and wait for review and integration. -4) Style-check your changes ---------------------------- +Style-check your changes +------------------------ Check your patch for basic style violations, details of which can be found in @@ -267,8 +267,8 @@ You should be able to justify all violations that remain in your patch. -5) Select the recipients for your patch ---------------------------------------- +Select the recipients for your patch +------------------------------------ You should always copy the appropriate subsystem maintainer(s) on any patch to code that they maintain; look through the MAINTAINERS file and the @@ -343,8 +343,8 @@ Trivial patches must qualify for one of the following rules: -6) No MIME, no links, no compression, no attachments. Just plain text ----------------------------------------------------------------------- +No MIME, no links, no compression, no attachments. Just plain text +------------------------------------------------------------------- Linus and other kernel developers need to be able to read and comment on the changes you are submitting. It is important for a kernel @@ -371,8 +371,8 @@ See :ref:`Documentation/process/email-clients.rst ` for hints about configuring your e-mail client so that it sends your patches untouched. -7) E-mail size --------------- +E-mail size +----------- Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 300 kB in size, @@ -381,8 +381,8 @@ server, and provide instead a URL (link) pointing to your patch. But note that if your patch exceeds 300 kB, it almost certainly needs to be broken up anyway. -8) Respond to review comments ------------------------------ +Respond to review comments +-------------------------- Your patch will almost certainly get comments from reviewers on ways in which the patch can be improved. You must respond to those comments; @@ -397,8 +397,8 @@ reviewers sometimes get grumpy. Even in that case, though, respond politely and address the problems they have pointed out. -9) Don't get discouraged - or impatient ---------------------------------------- +Don't get discouraged - or impatient +------------------------------------ After you have submitted your change, be patient and wait. Reviewers are busy people and may not get to your patch right away. @@ -411,8 +411,8 @@ one week before resubmitting or pinging reviewers - possibly longer during busy times like merge windows. -10) Include PATCH in the subject --------------------------------- +Include PATCH in the subject +----------------------------- Due to high e-mail traffic to Linus, and to linux-kernel, it is common convention to prefix your subject line with [PATCH]. This lets Linus @@ -421,8 +421,8 @@ e-mail discussions. -11) Sign your work - the Developer's Certificate of Origin ----------------------------------------------------------- +Sign your work - the Developer's Certificate of Origin +------------------------------------------------------ To improve tracking of who did what, especially with patches that can percolate to their final resting place in the kernel through several @@ -518,8 +518,8 @@ tracking your trees, and to people trying to troubleshoot bugs in your tree. -12) When to use Acked-by:, Cc:, and Co-developed-by: -------------------------------------------------------- +When to use Acked-by:, Cc:, and Co-developed-by: +------------------------------------------------ The Signed-off-by: tag indicates that the signer was involved in the development of the patch, or that he/she was in the patch's delivery path. @@ -587,8 +587,8 @@ Example of a patch submitted by a Co-developed-by: author:: Signed-off-by: Submitting Co-Author -13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: --------------------------------------------------------------------------- +Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: +---------------------------------------------------------------------- The Reported-by tag gives credit to people who find bugs and report them and it hopefully inspires them to help us again in the future. Please note that if @@ -651,8 +651,8 @@ for more details. .. _the_canonical_patch_format: -14) The canonical patch format ------------------------------- +The canonical patch format +-------------------------- This section describes how the patch itself should be formatted. Note that, if you have your patches stored in a ``git`` repository, proper patch @@ -774,8 +774,8 @@ references. .. _explicit_in_reply_to: -15) Explicit In-Reply-To headers --------------------------------- +Explicit In-Reply-To headers +---------------------------- It can be helpful to manually add In-Reply-To: headers to a patch (e.g., when using ``git send-email``) to associate the patch with @@ -788,8 +788,8 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in the cover email text) to link to an earlier version of the patch series. -16) Providing base tree information ------------------------------------ +Providing base tree information +------------------------------- When other developers receive your patches and start the review process, it is often useful for them to know where in the tree history they @@ -839,8 +839,8 @@ either below the ``---`` line or at the very bottom of all other content, right before your email signature. -17) Sending ``git pull`` requests ---------------------------------- +Sending ``git pull`` requests +----------------------------- If you have a series of patches, it may be most convenient to have the maintainer pull them directly into the subsystem repository with a -- cgit v1.2.3 From 7433ff33e8baa5ceafae3d99d639d5ace2458798 Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Thu, 3 Sep 2020 12:05:43 -0400 Subject: Documentation/process: expand plain-text advice This adds a link to https://useplaintext.email to email-clients.rst, which is a more exhaustive resource on configuring various mail clients for plain text use. submitting-patches.rst is also updated to direct readers to email-clients.rst to equip new contributors with the requisite knowledge to become a good participant on the mailing lists. Signed-off-by: Drew DeVault Reviewed-by: Randy Dunlap Link: https://lore.kernel.org/r/20200903160545.83185-3-sir@cmpwn.com Signed-off-by: Jonathan Corbet --- Documentation/process/email-clients.rst | 5 +++++ Documentation/process/submitting-patches.rst | 3 +++ 2 files changed, 8 insertions(+) diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst index c9e4ce2613c0..16586f6cc888 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -25,6 +25,11 @@ attachments, but then the attachments should have content-type it makes quoting portions of the patch more difficult in the patch review process. +It's also strongly recommended that you use plain text in your email body, +for patches and other emails alike. https://useplaintext.email may be useful +for information on how to configure your preferred email client, as well as +listing recommended email clients should you not already have a preference. + Email clients that are used for Linux kernel patches should send the patch text untouched. For example, they should not modify or delete tabs or spaces, even at the beginning or end of lines. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index ad25585a518a..9387d2eead23 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -396,6 +396,9 @@ for their time. Code review is a tiring and time-consuming process, and reviewers sometimes get grumpy. Even in that case, though, respond politely and address the problems they have pointed out. +See :ref:`Documentation/process/email-clients.rst` for recommendations on email +clients and mailing list etiquette. + Don't get discouraged - or impatient ------------------------------------ -- cgit v1.2.3 From 4ebdf7be21d627cd36026e4fe366a784bdde377a Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Thu, 3 Sep 2020 12:05:44 -0400 Subject: Documentation/maintainer: rehome sign-off process The repeated sign-offs necessary when a subsystem maintainer modifies an incoming patch has been moved from submitting-patches.rst to Documentation/maintainer, since the affairs of a subsystem maintainer are not especially relevant to someone reading a guide for how to submit their first patch. Signed-off-by: Drew DeVault Link: https://lore.kernel.org/r/20200903160545.83185-4-sir@cmpwn.com Signed-off-by: Jonathan Corbet --- Documentation/maintainer/index.rst | 1 + Documentation/maintainer/modifying-patches.rst | 50 ++++++++++++++++++++++++++ Documentation/process/submitting-patches.rst | 46 ------------------------ 3 files changed, 51 insertions(+), 46 deletions(-) create mode 100644 Documentation/maintainer/modifying-patches.rst diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index d904e74e1159..f0a60435b124 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -13,4 +13,5 @@ additions to this manual. rebasing-and-merging pull-requests maintainer-entry-profile + modifying-patches diff --git a/Documentation/maintainer/modifying-patches.rst b/Documentation/maintainer/modifying-patches.rst new file mode 100644 index 000000000000..58385d2e8065 --- /dev/null +++ b/Documentation/maintainer/modifying-patches.rst @@ -0,0 +1,50 @@ +.. _modifyingpatches: + +Modifying Patches +================= + +If you are a subsystem or branch maintainer, sometimes you need to slightly +modify patches you receive in order to merge them, because the code is not +exactly the same in your tree and the submitters'. If you stick strictly to +rule (c) of the developers certificate of origin, you should ask the submitter +to rediff, but this is a totally counter-productive waste of time and energy. +Rule (b) allows you to adjust the code, but then it is very impolite to change +one submitters code and make him endorse your bugs. To solve this problem, it +is recommended that you add a line between the last Signed-off-by header and +yours, indicating the nature of your changes. While there is nothing mandatory +about this, it seems like prepending the description with your mail and/or +name, all enclosed in square brackets, is noticeable enough to make it obvious +that you are responsible for last-minute changes. Example:: + + Signed-off-by: Random J Developer + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer + +This practice is particularly helpful if you maintain a stable branch and +want at the same time to credit the author, track changes, merge the fix, +and protect the submitter from complaints. Note that under no circumstances +can you change the author's identity (the From header), as it is the one +which appears in the changelog. + +Special note to back-porters: It seems to be a common and useful practice +to insert an indication of the origin of a patch at the top of the commit +message (just after the subject line) to facilitate tracking. For instance, +here's what we see in a 3.x-stable release:: + + Date: Tue Oct 7 07:26:38 2014 -0400 + + libata: Un-break ATA blacklist + + commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. + +And here's what might appear in an older kernel once a patch is backported:: + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +Whatever the format, this information provides a valuable help to people +tracking your trees, and to people trying to troubleshoot bugs in your +tree. diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 9387d2eead23..2cacec13780d 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -474,52 +474,6 @@ Some people also put extra tags at the end. They'll just be ignored for now, but you can do this to mark internal company procedures or just point out some special detail about the sign-off. -If you are a subsystem or branch maintainer, sometimes you need to slightly -modify patches you receive in order to merge them, because the code is not -exactly the same in your tree and the submitters'. If you stick strictly to -rule (c), you should ask the submitter to rediff, but this is a totally -counter-productive waste of time and energy. Rule (b) allows you to adjust -the code, but then it is very impolite to change one submitter's code and -make him endorse your bugs. To solve this problem, it is recommended that -you add a line between the last Signed-off-by header and yours, indicating -the nature of your changes. While there is nothing mandatory about this, it -seems like prepending the description with your mail and/or name, all -enclosed in square brackets, is noticeable enough to make it obvious that -you are responsible for last-minute changes. Example:: - - Signed-off-by: Random J Developer - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer - -This practice is particularly helpful if you maintain a stable branch and -want at the same time to credit the author, track changes, merge the fix, -and protect the submitter from complaints. Note that under no circumstances -can you change the author's identity (the From header), as it is the one -which appears in the changelog. - -Special note to back-porters: It seems to be a common and useful practice -to insert an indication of the origin of a patch at the top of the commit -message (just after the subject line) to facilitate tracking. For instance, -here's what we see in a 3.x-stable release:: - - Date: Tue Oct 7 07:26:38 2014 -0400 - - libata: Un-break ATA blacklist - - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. - -And here's what might appear in an older kernel once a patch is backported:: - - Date: Tue May 13 22:12:27 2008 +0200 - - wireless, airo: waitbusy() won't delay - - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] - -Whatever the format, this information provides a valuable help to people -tracking your trees, and to people trying to troubleshoot bugs in your -tree. - When to use Acked-by:, Cc:, and Co-developed-by: ------------------------------------------------ -- cgit v1.2.3 From 9f364b605f34e1c0b9847943f55db061d5a26bcb Mon Sep 17 00:00:00 2001 From: Drew DeVault Date: Thu, 3 Sep 2020 12:05:45 -0400 Subject: submitting-patches.rst: presume git will be used Git is fairly ubiquitous these days, and the additional information in this documentation for preparing patches without it is not especially relevant anymore and may serve to confuse new contributors. The git request-pull comments were also removed, given that it is not a tool well-suited to novice contributors, nor do maintainers especially appreciate receiving unexpected request-pulls from new contributors. Signed-off-by: Drew DeVault Link: https://lore.kernel.org/r/20200903160545.83185-5-sir@cmpwn.com Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-patches.rst | 148 +++------------------------ 1 file changed, 16 insertions(+), 132 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 2cacec13780d..04cd41567186 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -18,11 +18,10 @@ submitting code. If you are submitting a driver, also read for device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.rst. -Many of these steps describe the default behavior of the ``git`` version -control system; if you use ``git`` to prepare your patches, you'll find much -of the mechanical work done for you, though you'll still need to prepare -and document a sensible set of patches. In general, use of ``git`` will make -your life as a kernel developer easier. +This documentation assumes that you're using ``git`` to prepare your patches. +If you're unfamiliar with ``git``, you would be well-advised to learn how to +use it, it will make your life as a kernel developer and in general much +easier. Obtain a current source tree ---------------------------- @@ -39,64 +38,6 @@ patches prepared against those trees. See the **T:** entry for the subsystem in the MAINTAINERS file to find that tree, or simply ask the maintainer if the tree is not listed there. -It is still possible to download kernel releases via tarballs (as described -in the next section), but that is the hard way to do kernel development. - -1) ``diff -up`` ---------------- - -If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` -to create patches. Git generates patches in this form by default; if -you're using ``git``, you can skip this section entirely. - -All changes to the Linux kernel occur in the form of patches, as -generated by :manpage:`diff(1)`. When creating your patch, make sure to -create it in "unified diff" format, as supplied by the ``-u`` argument -to :manpage:`diff(1)`. -Also, please use the ``-p`` argument which shows which C function each -change is in - that makes the resultant ``diff`` a lot easier to read. -Patches should be based in the root kernel source directory, -not in any lower subdirectory. - -To create a patch for a single file, it is often sufficient to do:: - - SRCTREE=linux - MYFILE=drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -To create a patch for multiple files, you should unpack a "vanilla", -or unmodified kernel source tree, and generate a ``diff`` against your -own source tree. For example:: - - MYSRC=/devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -``dontdiff`` is a list of files which are generated by the kernel during -the build process, and should be ignored in any :manpage:`diff(1)`-generated -patch. - -Make sure your patch does not include any extra files which do not -belong in a patch submission. Make sure to review your patch -after- -generating it with :manpage:`diff(1)`, to ensure accuracy. - -If your changes produce a lot of deltas, you need to split them into -individual patches which modify things in logical stages; see -:ref:`split_changes`. This will facilitate review by other kernel developers, -very important if you want your patch accepted. - -If you're using ``git``, ``git rebase -i`` can help you with this process. If -you're not using ``git``, ``quilt`` -is another popular alternative. - .. _describe_changes: Describe your changes @@ -351,7 +292,12 @@ on the changes you are submitting. It is important for a kernel developer to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of your code. -For this reason, all patches should be submitted by e-mail "inline". +For this reason, all patches should be submitted by e-mail "inline". The +easiest way to do this is with ``git send-email``, which is strongly +recommended. An interactive tutorial for ``git send-email`` is available at +https://git-send-email.io. + +If you choose not to use ``git send-email``: .. warning:: @@ -371,23 +317,14 @@ See :ref:`Documentation/process/email-clients.rst ` for hints about configuring your e-mail client so that it sends your patches untouched. -E-mail size ------------ - -Large changes are not appropriate for mailing lists, and some -maintainers. If your patch, uncompressed, exceeds 300 kB in size, -it is preferred that you store your patch on an Internet-accessible -server, and provide instead a URL (link) pointing to your patch. But note -that if your patch exceeds 300 kB, it almost certainly needs to be broken up -anyway. - Respond to review comments -------------------------- Your patch will almost certainly get comments from reviewers on ways in -which the patch can be improved. You must respond to those comments; -ignoring reviewers is a good way to get ignored in return. Review comments -or questions that do not lead to a code change should almost certainly +which the patch can be improved, in the form of a reply to your email. You must +respond to those comments; ignoring reviewers is a good way to get ignored in +return. You can simply reply to their emails to answer their comments. Review +comments or questions that do not lead to a code change should almost certainly bring about a comment or changelog entry so that the next reviewer better understands what is going on. @@ -422,6 +359,7 @@ convention to prefix your subject line with [PATCH]. This lets Linus and other kernel developers more easily distinguish patches from other e-mail discussions. +``git send-email`` will do this for you automatically. Sign your work - the Developer's Certificate of Origin @@ -469,6 +407,7 @@ then you just add a line saying:: Signed-off-by: Random J Developer using your real name (sorry, no pseudonyms or anonymous contributions.) +This will be done for you automatically if you use ``git commit -s``. Some people also put extra tags at the end. They'll just be ignored for now, but you can do this to mark internal company procedures or just @@ -796,61 +735,6 @@ either below the ``---`` line or at the very bottom of all other content, right before your email signature. -Sending ``git pull`` requests ------------------------------ - -If you have a series of patches, it may be most convenient to have the -maintainer pull them directly into the subsystem repository with a -``git pull`` operation. Note, however, that pulling patches from a developer -requires a higher degree of trust than taking patches from a mailing list. -As a result, many subsystem maintainers are reluctant to take pull -requests, especially from new, unknown developers. If in doubt you can use -the pull request as the cover letter for a normal posting of the patch -series, giving the maintainer the option of using either. - -A pull request should have [GIT PULL] in the subject line. The -request itself should include the repository name and the branch of -interest on a single line; it should look something like:: - - Please pull from - - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus - - to get these changes: - -A pull request should also include an overall message saying what will be -included in the request, a ``git shortlog`` listing of the patches -themselves, and a ``diffstat`` showing the overall effect of the patch series. -The easiest way to get all this information together is, of course, to let -``git`` do it for you with the ``git request-pull`` command. - -Some maintainers (including Linus) want to see pull requests from signed -commits; that increases their confidence that the request actually came -from you. Linus, in particular, will not pull from public hosting sites -like GitHub in the absence of a signed tag. - -The first step toward creating such tags is to make a GNUPG key and get it -signed by one or more core kernel developers. This step can be hard for -new developers, but there is no way around it. Attending conferences can -be a good way to find developers who can sign your key. - -Once you have prepared a patch series in ``git`` that you wish to have somebody -pull, create a signed tag with ``git tag -s``. This will create a new tag -identifying the last commit in the series and containing a signature -created with your private key. You will also have the opportunity to add a -changelog-style message to the tag; this is an ideal place to describe the -effects of the pull request as a whole. - -If the tree the maintainer will be pulling from is not the repository you -are working from, don't forget to push the signed tag explicitly to the -public tree. - -When generating your pull request, use the signed tag as the target. A -command like this will do the trick:: - - git request-pull master git://my.public.tree/linux.git my-signed-tag - - References ---------- -- cgit v1.2.3 From afde706afde2fea8a1dff84acaedac4f8dfe84b9 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 4 Sep 2020 10:13:45 -0600 Subject: Make the docs build "work" with Sphinx 3.x The Sphinx 3.x upgrade broke a number of things in our special "cdomain" module that are not easy to fix. For now, just disable tha