Skip to contentSkip to conversation

Documentation: networking: device drivers: Remove stray asterisks

PATCH In review Jonathan Corbet 4 participants 8 messages Dec 1, 2019 – Dec 2, 2019

Subsystems (2)
lore
Share & tools
lore

Jonathan Corbet

author maintainer
#0 lore raw

PATCH 1/1 Documentation: networking: device drivers: Remove stray asterisks

Quoted 13 lines · Jonathan Corbet
Quoted 11 lines

So my tooling is "git am", nothing special.

All of the afflicted files arrived in that state as the result of a pair of patches from Jonathan (copied); I have verified that the original patches also had the DOS line endings.

The problem repeats if I apply those patches now, even if I add an explicit "--no-keep-cr" to the "git am" command line. It seems like maybe my version of git is somehow broken? I have git-2.21.0-1.fc30.x86_64, FWIW.

Quoted 8 lines

Hmm. I wonder if the CRLF removal is broken in general, or if the emails are somehow unusual (patches in attachments or MIME-encoded or something)? Maybe the CRLF was removed from the envelope email lines, but if the patch is then decoded from an attachment or something it's not removed again from there?

Can you attach (not forward) one of the (raw) emails that shows the problem and keep the git mailing list cc'd?

Attached. The patch itself was not an attachment, but it was base64-encoded.

jon

These asterisks were once references to a line that said:
"* Other names and brands may be claimed as the property of others."
But now, they serve no purpose; they can only irritate the reader.

Fixes de3edab4276c ("e1000: update README for e1000")
Fixes a3fb65680f65 ("e100.txt: Cleanup license info in kernel doc")
Fixes da8c01c4502a ("e1000e.txt: Add e1000e documentation")
Fixes f12a84a9f650 ("Documentation: fm10k: Add kernel documentation")
Fixes b55c52b1938c ("igb.txt: Add igb documentation")
Fixes c4e9b56e2442 ("igbvf.txt: Add igbvf Documentation")
Fixes d7064f4c192c ("Documentation/networking/: Update Intel wired LAN driver documentation")
Fixes c4b8c01112a1 ("ixgbevf.txt: Update ixgbevf documentation")
Fixes 1e06edcc2f22 ("Documentation: i40e: Prepare documentation for RST conversion")
Fixes 105bf2fe6b32 ("i40evf: add driver to kernel build system")
Fixes 1fae869bcf3d ("Documentation: ice: Prepare documentation for RST conversion")
Fixes df69ba43217d ("ionic: Add basic framework for IONIC Network device driver")
---
 .../networking/device_drivers/intel/e100.rst       | 14 +++++++-------
 .../networking/device_drivers/intel/e1000.rst      | 12 ++++++------
 .../networking/device_drivers/intel/e1000e.rst     | 14 +++++++-------
 .../networking/device_drivers/intel/fm10k.rst      | 10 +++++-----
 .../networking/device_drivers/intel/i40e.rst       |  8 ++++----
 .../networking/device_drivers/intel/iavf.rst       |  8 ++++----
 .../networking/device_drivers/intel/ice.rst        |  6 +++---
 .../networking/device_drivers/intel/igb.rst        | 12 ++++++------
 .../networking/device_drivers/intel/igbvf.rst      |  6 +++---
 .../networking/device_drivers/intel/ixgbe.rst      | 10 +++++-----
 .../networking/device_drivers/intel/ixgbevf.rst    |  6 +++---
 .../networking/device_drivers/pensando/ionic.rst   |  6 +++---
 12 files changed, 56 insertions(+), 56 deletions(-)
Documentation/networking/device_drivers/intel/e100.rst +7 -7
index 2b9f4887beda..caf023cc88de 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-==============================================================
-Linux* Base Driver for the Intel(R) PRO/100 Family of Adapters
-==============================================================
+=============================================================
+Linux Base Driver for the Intel(R) PRO/100 Family of Adapters
+=============================================================
 
 June 1, 2018
 
@@ -21,7 +21,7 @@ Contents
 In This Release
 ===============
 
-This file describes the Linux* Base Driver for the Intel(R) PRO/100 Family of
+This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of
 Adapters. This driver includes support for Itanium(R)2-based systems.
 
 For questions related to hardware requirements, refer to the documentation
@@ -138,9 +138,9 @@ version 1.6 or later is required for this functionality.
 The latest release of ethtool can be found from
 https://www.kernel.org/pub/software/network/ethtool/
 
-Enabling Wake on LAN* (WoL)
----------------------------
-WoL is provided through the ethtool* utility.  For instructions on
+Enabling Wake on LAN (WoL)
+--------------------------
+WoL is provided through the ethtool utility.  For instructions on
 enabling WoL with ethtool, refer to the ethtool man page.  WoL will be
 enabled on the system during the next shut down or reboot.  For this
 driver version, in order to enable WoL, the e100 driver must be loaded
Documentation/networking/device_drivers/intel/e1000.rst +6 -6
index 956560b6e745..4aaae0f7d6ba 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-===========================================================
-Linux* Base Driver for Intel(R) Ethernet Network Connection
-===========================================================
+==========================================================
+Linux Base Driver for Intel(R) Ethernet Network Connection
+==========================================================
 
 Intel Gigabit Linux driver.
 Copyright(c) 1999 - 2013 Intel Corporation.
@@ -438,10 +438,10 @@ ethtool
   The latest release of ethtool can be found from
   https://www.kernel.org/pub/software/network/ethtool/
 
-Enabling Wake on LAN* (WoL)
----------------------------
+Enabling Wake on LAN (WoL)
+--------------------------
 
-  WoL is configured through the ethtool* utility.
+  WoL is configured through the ethtool utility.
 
   WoL will be enabled on the system during the next shut down or reboot.
   For this driver version, in order to enable WoL, the e1000 driver must be
Documentation/networking/device_drivers/intel/e1000e.rst +7 -7
index 01999f05509c..f49cd370e7bf 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-======================================================
-Linux* Driver for Intel(R) Ethernet Network Connection
-======================================================
+=====================================================
+Linux Driver for Intel(R) Ethernet Network Connection
+=====================================================
 
 Intel Gigabit Linux driver.
 Copyright(c) 2008-2018 Intel Corporation.
@@ -338,7 +338,7 @@ and higher cannot be forced. Use the autonegotiation advertising setting to
 manually set devices for 1 Gbps and higher.
 
 Speed, duplex, and autonegotiation advertising are configured through the
-ethtool* utility.
+ethtool utility.
 
 Caution: Only experienced network administrators should force speed and duplex
 or change autonegotiation advertising manually. The settings at the switch must
@@ -351,9 +351,9 @@ will not attempt to auto-negotiate with its link partner since those adapters
 operate only in full duplex and only at their native speed.
 
 
-Enabling Wake on LAN* (WoL)
----------------------------
-WoL is configured through the ethtool* utility.
+Enabling Wake on LAN (WoL)
+--------------------------
+WoL is configured through the ethtool utility.
 
 WoL will be enabled on the system during the next shut down or reboot. For
 this driver version, in order to enable WoL, the e1000e driver must be loaded
Documentation/networking/device_drivers/intel/fm10k.rst +5 -5
index ac3269e34f55..4d279e64e221 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-==============================================================
-Linux* Base Driver for Intel(R) Ethernet Multi-host Controller
-==============================================================
+=============================================================
+Linux Base Driver for Intel(R) Ethernet Multi-host Controller
+=============================================================
 
 August 20, 2018
 Copyright(c) 2015-2018 Intel Corporation.
@@ -120,8 +120,8 @@ rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 m|v|t|s|d|f|n|r
 Known Issues/Troubleshooting
 ============================
 
-Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS under Linux KVM
----------------------------------------------------------------------------------------
+Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM
+-------------------------------------------------------------------------------------
 KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This
 includes traditional PCIe devices, as well as SR-IOV-capable devices based on
 the Intel Ethernet Controller XL710.
Documentation/networking/device_drivers/intel/i40e.rst +4 -4
index 848fd388fa6e..8a9b18573688 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-==================================================================
-Linux* Base Driver for the Intel(R) Ethernet Controller 700 Series
-==================================================================
+=================================================================
+Linux Base Driver for the Intel(R) Ethernet Controller 700 Series
+=================================================================
 
 Intel 40 Gigabit Linux driver.
 Copyright(c) 1999-2018 Intel Corporation.
@@ -384,7 +384,7 @@ NOTE: You cannot set the speed for devices based on the Intel(R) Ethernet
 Network Adapter XXV710 based devices.
 
 Speed, duplex, and autonegotiation advertising are configured through the
-ethtool* utility.
+ethtool utility.
 
 Caution: Only experienced network administrators should force speed and duplex
 or change autonegotiation advertising manually. The settings at the switch must
Documentation/networking/device_drivers/intel/iavf.rst +4 -4
index cfc08842e32c..84ac7e75f363 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-==================================================================
-Linux* Base Driver for Intel(R) Ethernet Adaptive Virtual Function
-==================================================================
+=================================================================
+Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function
+=================================================================
 
 Intel Ethernet Adaptive Virtual Function Linux driver.
 Copyright(c) 2013-2018 Intel Corporation.
@@ -19,7 +19,7 @@ Contents
 Overview
 ========
 
-This file describes the iavf Linux* Base Driver. This driver was formerly
+This file describes the iavf Linux Base Driver. This driver was formerly
 called i40evf.
 
 The iavf driver supports the below mentioned virtual function devices and
Documentation/networking/device_drivers/intel/ice.rst +3 -3
index c220aa2711c6..ee43ea57d443 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-===================================================================
-Linux* Base Driver for the Intel(R) Ethernet Connection E800 Series
-===================================================================
+==================================================================
+Linux Base Driver for the Intel(R) Ethernet Connection E800 Series
+==================================================================
 
 Intel ice Linux driver.
 Copyright(c) 2018 Intel Corporation.
Documentation/networking/device_drivers/intel/igb.rst +6 -6
index fc8cfaa5dcfa..87e560fe5eaa 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-===========================================================
-Linux* Base Driver for Intel(R) Ethernet Network Connection
-===========================================================
+==========================================================
+Linux Base Driver for Intel(R) Ethernet Network Connection
+==========================================================
 
 Intel Gigabit Linux driver.
 Copyright(c) 1999-2018 Intel Corporation.
@@ -129,9 +129,9 @@ version is required for this functionality. Download it at:
 https://www.kernel.org/pub/software/network/ethtool/
 
 
-Enabling Wake on LAN* (WoL)
----------------------------
-WoL is configured through the ethtool* utility.
+Enabling Wake on LAN (WoL)
+--------------------------
+WoL is configured through the ethtool utility.
 
 WoL will be enabled on the system during the next shut down or reboot. For
 this driver version, in order to enable WoL, the igb driver must be loaded
Documentation/networking/device_drivers/intel/igbvf.rst +3 -3
index 9cddabe8108e..557fc020ef31 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-============================================================
-Linux* Base Virtual Function Driver for Intel(R) 1G Ethernet
-============================================================
+===========================================================
+Linux Base Virtual Function Driver for Intel(R) 1G Ethernet
+===========================================================
 
 Intel Gigabit Virtual Function Linux driver.
 Copyright(c) 1999-2018 Intel Corporation.
Documentation/networking/device_drivers/intel/ixgbe.rst +5 -5
index c7d25483fedb..f1d5233e5e51 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-=============================================================================
-Linux* Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters
-=============================================================================
+===========================================================================
+Linux Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters
+===========================================================================
 
 Intel 10 Gigabit Linux driver.
 Copyright(c) 1999-2018 Intel Corporation.
@@ -519,8 +519,8 @@ The offload is also supported for ixgbe's VFs, but the VF must be set as
 Known Issues/Troubleshooting
 ============================
 
-Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS
------------------------------------------------------------------------
+Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS
+---------------------------------------------------------------------
 Linux KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM.
 This includes traditional PCIe devices, as well as SR-IOV-capable devices based
 on the Intel Ethernet Controller XL710.
Documentation/networking/device_drivers/intel/ixgbevf.rst +3 -3
index 5d4977360157..76bbde736f21 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-=============================================================
-Linux* Base Virtual Function Driver for Intel(R) 10G Ethernet
-=============================================================
+============================================================
+Linux Base Virtual Function Driver for Intel(R) 10G Ethernet
+============================================================
 
 Intel 10 Gigabit Virtual Function Linux driver.
 Copyright(c) 1999-2018 Intel Corporation.
Documentation/networking/device_drivers/pensando/ionic.rst +3 -3
index 67b6839d516b..3afe97514d68 100644
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
-==========================================================
-Linux* Driver for the Pensando(R) Ethernet adapter family
-==========================================================
+========================================================
+Linux Driver for the Pensando(R) Ethernet adapter family
+========================================================
 
 Pensando Linux Ethernet driver.
 Copyright(c) 2019 Pensando Systems, Inc
Signature · 1 line
2.20.1
#1 lore raw
Quoted 3 lines · Jonathan Corbet

Attached. The patch itself was not an attachment, but it was base64-encoded.

Ok, so presumably git removed the CRLF from the email, but then the base64 encoded part had another set of CRLF.

And when I try to apply that patch (in a test-tree reset to commit facd86390be2, so I think the patch should apply) I see the CRLF in .git/rebase-apply/patch, but then I get

error: patch failed: Documentation/networking/device_drivers/intel/e100.rst:1
error: Documentation/networking/device_drivers/intel/e100.rst: patch
does not apply

for every hunk. I assume that's because the CR part doesn't match the old code.

But my git version is d9f6f3b619 ("The first batch post 2.24 cycle") and some private patches.

So the problem might be limited to only some versions. I'm surprised, though - when git applies patches, it really wants the surrounding lines to match exactly. The extra CR at the end of the lines should have made that test fail.

Do you use some special options for git? Like --whitespace=nowarn or --3way or something like that?

Linus

author maintainer
#2 lore raw
Quoted 2 lines · On Sat, 30 Nov 2019 17:20:10 -0800 Linus Torvalds…

Do you use some special options for git? Like --whitespace=nowarn or --3way or something like that?

Sigh, that has to be it. I have --ignore-whitespace in my script. When I take that option out, the patch in question no longer applies.

Docs patches often come from relatively new folks, and I've found that I needed that to apply a lot of their patches. But clearly that was not a good choice; among other things, I've lost the opportunity to tell people when their patches have the types of whitespace issues that this option covers over. I've taken it out of the script and will only use it by hand in cases where I'm sure that it won't cause problems.

Sorry for the screwup...

jon

#3 lore raw
Quoted 8 lines · Jonathan Corbet
Quoted 2 lines · On Sat, 30 Nov 2019 17:20:10 -0800 Linus Torvalds…

Do you use some special options for git? Like --whitespace=nowarn or --3way or something like that?

Sigh, that has to be it. I have --ignore-whitespace in my script. When I take that option out, the patch in question no longer applies.

OK, so it appears that the tool is working as documented. The "ignore" stuff kicks in to fuzz the whitespace difference for the ' ' lines and '-' lines, but the option itself does not give "git apply" enough information to decide what to do with the extra whitespace that is CR at the end of the line on the '+' lines.

I would also say it is doubtful that it is working as expected. Perhaps --ignore-whitespace and --whitespace=fix ought to work well together to allow matching preimage (i.e. ' ' and '-') lines, but still fix whitespace-broken material in postimage (i.e. ' ' and '+') lines before replacing the preimage with the postimage, or something along that line?

#4 lore raw
Quoted 2 lines · Junio C Hamano

OK, so it appears that the tool is working as documented.

Well, yes and no.

I think it's a mistake that --no-keep-cr (which is the default) only acts on the outer envelope.

Now, *originally* the outer envelope was all that existed so it makes sense in a historical context of "CR removal happens when splitting emails in an mbox". And that's the behavior we have.

But then git learnt to do MIME decoding and extracting things from base64 etc, and the CR removal wasn't updated to that change.

I guess "documented" is arguable in the sense that the git documentation does talk about "git-mailsplit" as an implementation detail, but still..

Linus

#5 lore raw
Quoted 4 lines · Linus Torvalds
Quoted 2 lines · Junio C Hamano

OK, so it appears that the tool is working as documented.

Quoted 8 lines

Well, yes and no.

I think it's a mistake that --no-keep-cr (which is the default) only acts on the outer envelope.

Now, *originally* the outer envelope was all that existed so it makes sense in a historical context of "CR removal happens when splitting emails in an mbox". And that's the behavior we have.

Hmph, first of all, the one I was referring to as "documented" was about --ignore-whitespace, and not --no-keep-cr.

And I am not as sure as you seem to be about "--no-keep-cr" either.

What was the reason why "--no-keep-cr" was invented and made default? Wasn't it because RFC says that each line of plaintext transfer of an e-mail is terminated with CRLF? It would mean that, whether the payload originally had CRLF terminated or LF terminated, we would not be able to tell---the CR may have been there from the beginning, or it could have been added in transit. And because we (the projects Git was originally designed to serve well) wanted our patches with LF terminated lines most of the time, it made sense to strip CR from CRLF (i.e. assuming that it would be rare that the sender wants to transmit CRLF terminated lines).

If the contents were base64 protected from getting munged during transit, we _know_ CRLF in the payload after we decode MIME is what the sender _meant_ to give us, no? Which leads me to say ...

Quoted 3 lines

But then git learnt to do MIME decoding and extracting things from base64 etc, and the CR removal wasn't updated to that change.

... I do not think it was a wrong decision (well, I do not think we made the conscious decision to do so, though) not to do that update.

I dunno.

#6 lore raw

Is it possible that git complains about everything that has ^M in it and rejects it (that is without trying to fix it, etc.)

Regards,
Amit

Quoted 45 lines · Junio C Hamano
Quoted 4 lines · Linus Torvalds
Quoted 2 lines · Junio C Hamano

OK, so it appears that the tool is working as documented.

Quoted 8 lines

Well, yes and no.

I think it's a mistake that --no-keep-cr (which is the default) only acts on the outer envelope.

Now, *originally* the outer envelope was all that existed so it makes sense in a historical context of "CR removal happens when splitting emails in an mbox". And that's the behavior we have.

Hmph, first of all, the one I was referring to as "documented" was about --ignore-whitespace, and not --no-keep-cr.

And I am not as sure as you seem to be about "--no-keep-cr" either.

What was the reason why "--no-keep-cr" was invented and made default? Wasn't it because RFC says that each line of plaintext transfer of an e-mail is terminated with CRLF? It would mean that, whether the payload originally had CRLF terminated or LF terminated, we would not be able to tell---the CR may have been there from the beginning, or it could have been added in transit. And because we (the projects Git was originally designed to serve well) wanted our patches with LF terminated lines most of the time, it made sense to strip CR from CRLF (i.e. assuming that it would be rare that the sender wants to transmit CRLF terminated lines).

If the contents were base64 protected from getting munged during transit, we _know_ CRLF in the payload after we decode MIME is what the sender _meant_ to give us, no? Which leads me to say ...

Quoted 3 lines

But then git learnt to do MIME decoding and extracting things from base64 etc, and the CR removal wasn't updated to that change.

... I do not think it was a wrong decision (well, I do not think we made the conscious decision to do so, though) not to do that update.

I dunno.

#7 lore raw
Quoted 2 lines · Amit Choudhary

Is it possible that git complains about everything that has ^M in it and rejects it (that is without trying to fix it, etc.)

I am not sure what you mean. Are you asking if there is a mode (e.g. command line switch) to tell "git am" to reject any input with CR in it? I do not think there is, and I do not think it would help all that much. But perhaps the pre-applypatch hook can be used to inspect the current working tree files (and it can compare them with HEAD to learn what are the proposed changes) and reject the patch--- an advantage of such an approach is that the "inspect" step does not have to be limited to "does it contain a carriage-return?"

Or are you asking if the patch (mis)application that triggered this discussion thread was somehow caused by Git that complains a payload with CR in it? I do not think so.