[PATCH RFC] media: admin-guide: improve cardlist.rst documentation

[PATCH RFC] media: admin-guide: improve cardlist.rst documentation

[Mauro Carvalho Chehab]

The cardlist section is important for some boards, because they
may require extra modprobe parameters.

Improve the docs to mention that.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/media/cardlist.rst | 76 ++++++++++++++++++--
 1 file changed, 71 insertions(+), 5 deletions(-)

diff --git a/Documentation/admin-guide/media/cardlist.rst b/Documentation/admin-guide/media/cardlist.rst
index 527188ee9697..4beef18fc46d 100644
--- a/Documentation/admin-guide/media/cardlist.rst
+++ b/Documentation/admin-guide/media/cardlist.rst
@@ -1,22 +1,88 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+==========
 Cards List
 ==========
 
+The media subsystem provide support for lots of PCI and USB drivers, plus
+platform-specific drivers. It also contains several ancillary I²C drivers.
+
+This section contains a list of some of those supported drivers.
+
+USB drivers
+===========
+
+The USB boards are identified by an identification called USB ID.
+
+The ``lsusb`` command allows identifying the USB IDs::
+
+    $ lsusb
+    ...
+    Bus 001 Device 015: ID 046d:082d Logitech, Inc. HD Pro Webcam C920
+    Bus 001 Device 074: ID 2040:b131 Hauppauge
+    Bus 001 Device 075: ID 2013:024f PCTV Systems nanoStick T2 290e
+    ...
+
+Unfortunately, sometimes the same USB ID is used by different products.
+So, several media drivers allow passing a ``card=`` parameter, in order
+to setup a card number that would match the correct settings for an
+specific board.
+
 .. toctree::
 	:maxdepth: 1
 
 	au0828-cardlist
+	cx231xx-cardlist
+	em28xx-cardlist
+	tm6000-cardlist
+	usbvision-cardlist
+	gspca-cardlist
+
+PCI drivers
+===========
+
+The PCI boards are identified by an identification called PCI ID.
+
+The ``lspci`` command allows identifying the PCI IDs::
+
+    $ lspci -nn
+    ...
+    00:0b.0 Multimedia video controller: Brooktree Corporation Bt878 Video Capture [1822:0026] (rev 11)
+    ...
+
+Unfortunately, sometimes the same PCI ID is used by different products.
+So, several media drivers allow passing a ``card=`` parameter, in order
+to setup a card number that would match the correct settings for an
+specific board.
+
+.. toctree::
+	:maxdepth: 1
+
 	bttv-cardlist
 	cx18-cardlist
-	cx231xx-cardlist
 	cx23885-cardlist
 	cx88-cardlist
-	em28xx-cardlist
 	ivtv-cardlist
 	saa7134-cardlist
 	saa7164-cardlist
-	tm6000-cardlist
+
+I²C drivers
+===========
+
+The I²C (Inter-Integrated Circuit) bus is a three-wires bus used internally
+at the media cards for communication between different chips. While the bus
+is not visible to the Linux Kernel, drivers need to send and receive
+commands via the bus. The Linux Kernel driver abstraction has support to
+implement different drivers for each component inside an I²C bus, as if
+the bus were visible to the main system board.
+
+One of the problems with I²C devices is that sometimes the same device may
+work with different I²C hardware. This is common, for example, on devices
+that comes with a tuner for North America market, and another one for
+Europe. Some drivers have a ``tuner=`` modprobe parameter to allow using a
+different tuner number in order to address such issue.
+
+.. toctree::
+	:maxdepth: 1
+
 	tuner-cardlist
-	usbvision-cardlist
-	gspca-cardlist
-- 
2.25.2