refactor README.md for brevity

move branch descriptions and vendor diffs to docs/

README.md

@@ -27,97 +27,21 @@ This repo aims to:
 
 The older TN3020-D (Luxor) processor already has a mainline Linux driver, but that driver doesn't support the TN40xx (Bordeaux) devices.
 
+# Install
+
+While upstreaming is the ultimate goal of this project, some systems already rely on this driver. For such systems, DKMS provides a convenient way to install and update the driver, [See DKMS instructions](docs/dkms.md).
+
 # Branches
 
 This repo makes extensive use of branches to organise the changes to the vendor driver. For example,
-- `release/tn40xx-001-linux-4.13`
+- `release/tn40xx-001`
 - `vendor-drop/v0.3.6.14.3`
 - `cleanup/v0.3.6.14.3`
-- `topic/remove-linux-2.6-support`
-
-A description of the purpose of each type of branch follows.
-
-## Release branches
-
-When a new combination of (vendor release + cleanups + topic work) is ready, a release branch will be made for it. The release branch name indicates the upstream version of Linux it applies to and a simple monotonically increasing counter of the release number.
-
-For example:
-- `release/tn40xx-001-linux-4.13` would be the first release of the forked driver and applies to linux-4.13.
-- `release/tn40xx-002-linux-4.4` would be the second release of the forked driver and applies to linux-4.4.
-
-Use the largest release number that applies to the kernel version you're building.
-
-
-## Vendor drop branches
-
-Vendor releases are imported from their distributed tarball into `vendor-drop/` branches. These branches are used for easy access to the unmodified driver, as well as reference between vendor branches.
-
-
-## Cleanup branches
-
-The intention of the `cleanup/` git branches is to transform the vendor code into a better format that addresses the problems with the code style used by the vendor.
+- `topic/topic/feature/add-Promise-SANLink3-T1`
 
-Some specific problems are:
-- mixed tabs and spaces look horrible unless tab-width is 4
-- trailing whitespace
-- mixed C-style and C++ style comments
-- single lines of commented code smells
-- long lines
-- ignoring Linux kernel style
-
-
-The cleanup transformation MUST:
-- be logically equivalent to the vendor code
-- follow an automatable, repeatable process
-- involve low human effort
-- make progress towards an 'upstreamable' driver
-
-
-To apply the cleanup changes, run: `cleanup.sh`
-
-
-## Topic branches
-
-Features, bugfixes and improvements towards mainline inclusion are contained on these branches. For example, mainline Linux drivers do not have support for different kernel versions than the one that they ship with, so that support has to be removed.
-
-Topic branches are always based on cleanup branches.
+The branching strategy is [described in the documentation](docs/branching.md).
 
 # Changes between vendor releases
 
-This is a summary of changes between vendor releases. It is included here, because the `release_notes` file provided by the vendor is not guaranteed to be completely accurate.
-
-To generate the diff, use something like this:
-```
-git diff -D cleanup/v0.3.6.14.1 cleanup/v0.3.6.14.3
-```
-
-## vendor-drop/v0.3.6.15
-- The Marvell PHY control that was removed in 0.3.6.14.3 has reappeared (without the required firmware/initialisation data blobs!) and the 'Marvell' name has been replaced with 'Pele' for what could only be trademark lawyer nonsense.
-- Added support for "Mustang-200 10GbE Ethernet Adapter"
-- More magical _Mike fix_ copy pasta
-- Some timer cruft was removed
-
-Plus vendor's release_notes:
-- New build method for Marvell PHYs. Please consult the Readme file
-- Improved startup procudure for "Phyless" CX4 mode
-- Dynamic advertising of MACA for RX flow control
-- Support for IEI SVID/SDID added
-- Improved memory allocation for memory limited or fragmented applications
-
-## vendor-drop/v0.3.6.14.3
-- Removed support for Marvell PHYs, which removes support for the following NICs:
- - "TN9210 10GBase-T Ethernet Adapter"
- - "TN9710P 10GBase-T/NBASE-T Ethernet Adapter"
- - "TN9710Q 5GBase-T/NBASE-T Ethernet Adapter"
- - "Edimax 10 Gigabit Ethernet PCI Express Adapter"
- - "Buffalo LGY-PCIE-MG Ethernet Adapter"
-
-Plus the following claims from the vendors release_notes:
-- Fix RX Flow Control
-- Fix ethtool mtu on Ubuntu 17.04
-- Improve single PHY build code
-- Fix compilation error for CentOS 7.4
-- Fix missing PCP bits in VLAN tag
+See  [vendor-diffs.md](docs/vendor-diffs.md).
 
-## vendor-drop/v0.3.6.14.1
-- First import; see release_notes for history.

docs/branches.md

+# Branches
+
+This repo makes extensive use of branches to organise the changes to the vendor driver. For example,
+- `vendor-drop/v0.3.6.14.3`
+- `cleanup/v0.3.6.14.3`
+- `topic/remove-linux-2.6-support`
+
+A description of the purpose of each type of branch follows.
+
+## Release branches
+
+A release branch is a combination of (vendor release + cleanups + topic work). The release branch name is a simple monotonically increasing counter of the release number.
+
+
+## Vendor drop branches
+
+Vendor releases are imported from their distributed tarball into `vendor-drop/` branches. These branches are used for easy access to the unmodified driver, as well as reference between vendor branches.
+
+
+## Cleanup branches
+
+Ignoring the Linux kernel style prevents this driver from being included in the mainline kernel.
+
+The intention of the `cleanup/` branches is to transform the vendor code into a better format that addresses the problems with the code style used by the vendor.
+
+Some specific problems are:
+- mixed tabs and spaces look horrible unless tab-width is 4
+- trailing whitespace
+- mixed C-style and C++ style comments
+- single lines of commented code smells
+- long lines
+
+
+The cleanup transformation MUST:
+- be logically equivalent to the vendor code
+- follow an automatable, repeatable process
+- involve low human effort
+- make progress towards an 'upstreamable' driver
+
+
+To apply the cleanup changes, run: `cleanup.sh`
+
+
+## Topic branches
+
+Features, bugfixes and improvements towards mainline inclusion are contained on these branches. For example, mainline Linux drivers do not have support for different kernel versions than the one that they ship with, so that support has to be removed.
+
+Topic branches are always based on cleanup branches.
+

docs/vendor-diffs.md

+
+# Changes between vendor releases
+
+The vendor provides [release_notes](release_notes), Sometimes additional information comes to light when comparing the cleaned-up branches - that's where these review notes may help.
+
+To generate the diff, use something like this:
+```
+git diff -D cleanup/v0.3.6.15 cleanup/v0.3.6.16.1
+```
+
+## vendor-drop/v0.3.6.16-startech
+- Startech OEM driver contains Marvell firmware files missing from vendor-drop/v0.3.6.16.
+
+## vendor-drop/v0.3.6.16
+- AQR105 PHY firmware updated from XXX to 2.b.e2
+- Add SVID/SDID for [IOI GE10-PCIE4XG202](http://www.ioi.com.tw/products/prodcat_device.aspx?CatID=106&DeviceID=3035&HostID=2069) OEM products. They're using _Marvell MV88X3310 PHYs_, so Linux support may be a challenge.
+
+## vendor-drop/v0.3.6.15
+- The Marvell PHY control that was removed in 0.3.6.14.3 has reappeared (without the required firmware/initialisation data blobs!) and the 'Marvell' name has been replaced with 'Pele' for what could only be trademark lawyer nonsense.
+- Added support for "Mustang-200 10GbE Ethernet Adapter"
+- More magical _Mike fix_ copy pasta
+- Some timer cruft was removed
+
+Plus vendor's release_notes:
+- New build method for Marvell PHYs. Please consult the Readme file
+- Improved startup procudure for "Phyless" CX4 mode
+- Dynamic advertising of MACA for RX flow control
+- Support for IEI SVID/SDID added
+- Improved memory allocation for memory limited or fragmented applications
+
+## vendor-drop/v0.3.6.14.3
+- Removed support for Marvell PHYs, which removes support for the following NICs:
+ - "TN9210 10GBase-T Ethernet Adapter"
+ - "TN9710P 10GBase-T/NBASE-T Ethernet Adapter"
+ - "TN9710Q 5GBase-T/NBASE-T Ethernet Adapter"
+ - "Edimax 10 Gigabit Ethernet PCI Express Adapter"
+ - "Buffalo LGY-PCIE-MG Ethernet Adapter"
+
+Plus the following claims from the vendors release_notes:
+- Fix RX Flow Control
+- Fix ethtool mtu on Ubuntu 17.04
+- Improve single PHY build code
+- Fix compilation error for CentOS 7.4
+- Fix missing PCP bits in VLAN tag
+
+## vendor-drop/v0.3.6.14.1
+- First import; see release_notes for history.