[PATCH] MCI: Add some doc how to handle MCI cards

[Juergen Beisert]

From: Juergen Beisert <juergen at kreuzholzen.de>
Subject: [PATCH] MCI: Add some doc how to handle MCI cards

Signed-off-by: Juergen Beisert <juergen at kreuzholzen.de>

---
 Documentation/developers_manual.dox |    1 
 Documentation/users_manual.dox      |    1 
 drivers/mci/mci-core.c              |  117 ++++++++++++++++++++++++++++++++++++
 3 files changed, 119 insertions(+)

Index: barebox-2010.10.0/Documentation/developers_manual.dox
===================================================================
--- barebox-2010.10.0.orig/Documentation/developers_manual.dox
+++ barebox-2010.10.0/Documentation/developers_manual.dox
@@ -18,6 +18,7 @@ This part of the documentation is intend
 @li @subpage how_mount_works
 @li @subpage boot_preparation
 @li @subpage barebox_simul
+ at li @subpage mci_for_developers
 @li @subpage io_access_functions
 @li @subpage mcfv4e_MCDlib
 
Index: barebox-2010.10.0/Documentation/users_manual.dox
===================================================================
--- barebox-2010.10.0.orig/Documentation/users_manual.dox
+++ barebox-2010.10.0/Documentation/users_manual.dox
@@ -9,6 +9,7 @@ work easier.
 @li @subpage shell_notes
 @li @subpage readline_parser
 @li @subpage command_reference
+ at li @subpage mci_for_users
 @li @subpage x86_bootloader
 @li @subpage net_netconsole
 
Index: barebox-2010.10.0/drivers/mci/mci-core.c
===================================================================
--- barebox-2010.10.0.orig/drivers/mci/mci-core.c
+++ barebox-2010.10.0/drivers/mci/mci-core.c
@@ -1358,3 +1358,120 @@ int mci_register(struct mci_host *host)
 
 	return register_device(mci_dev);
 }
+
+/**
+ * @page mci_for_developers MCI information for developers
+ *
+ * Pay attention
+ * - Provide a MCI clock to let the card do its reset
+ * - Provide power supply to the socket. There is no callback in the generic
+ *   driver to do so
+ *
+ * If your MCI host hardware is slow, you should avoid the card probing at system
+ * startup. Do it on demand only in this case. This can be achieved by disabling
+ * the MCI_STARTUP menu entry.
+ */
+
+/**
+ at page mci_for_users MCI cards for users
+
+MCI cards are handled like regular disks in @b barebox. When a card is detected,
+access gets added to the system as @b /dev/disk0. If @b barebox detects a partition
+table in the first sector, it also adds these partitions as @b /dev/disk0.0,
+ at b dev/disk0.1 and so on.
+
+All these disk devices can be used with the command @b md, @b mw, @b cp,
+ at b bootm in a regular manner.
+
+ at verbatim
+barebox:/ devinfo
+devices:
+|----s3c24x0_serial0
+|----cs0
+|----ramfs0
+|----devfs0
+|----mem0 (defaultenv)
+|----mem1 (mem)
+|----s3c_mci0
+|----disk0 (disk0, disk0.0)
+|----s3cfb0
+|----framebuffer0 (fb0)
+|----s3c24x0_nand0
+|----nand0 (nand0, nand_oob0, self_raw, env_raw, nand0.uboot, nand0.ubootenv, nand0.kernel, nand0.root)
+|----mem2 (ram0)
+|----cs89000
+|----eth0
+
+drivers:
+s3c24x0_serial
+     ramfs
+     devfs
+    cs8900
+s3c24x0_nand
+      disk
+framebuffer
+     s3cfb
+   s3c_mci
+       mem
+ at endverbatim
+
+The device in question is the @b mci0. Run the @b devinfo command again on this device.
+
+ at verbatim
+barebox:/ devinfo mci0
+base  : 0x00000000
+size  : 0x3d600000
+driver: mci
+
+ Card:
+  Attached is an SD Card (Version: 2.0)
+  Capacity: 982 MiB
+   CID: 1C535653-44432020-10000000-1800849F
+   CSD: 005E0032-5F5983D5-EDB7FF9F-964000C1
+  Max. transfer speed: 25000000 Hz
+  Manufacturer ID: 1C
+  OEM/Application ID: 5356
+  Product name: 'SDC  '
+  Product revision: 1.0
+  Serial no: 24
+  Manufacturing date: 4.2008
+no parameters available
+ at endverbatim
+
+In this case probing the MCI card has successfully happen at system startup. Probing
+at this early point of time can be necessary for systems that depends on data from
+this kind of storage (for example if the persistant environment is stored on the
+MCI card).
+
+As probing an MCI card may take some seconds, it could be useful to do this
+on demand only (if not otherwise required). In this case the @b devinfo
+shows different information about the MCI card prior probing:
+
+ at verbatim
+barebox:/ devinfo mci0
+base  : 0x00000000
+size  : 0x00000000
+driver: mci
+
+ Card:
+   Not probed yet.
+
+parameters
+     probe = 0
+ at endverbatim
+
+ at note The MCI card should already be inserted when powering the system, as
+ at b barebox does not support runtime power supply switching.
+
+To do the MCI card probing right now, just enter:
+ at verbatim
+barebox:/ mci0.probe=1
+ at endverbatim
+
+ at note @b barebox currently cannot really cope with hot plug (its a bootloader only,
+not an operating system...). So, unplugging the already probed card and replacing
+it by another one and also probing this new card may crash your system (and might
+also destroy the MCI card, as unplugging and plugging happens while the socket is
+"hot").
+
+*/

-- 
Pengutronix e.K.                              | Juergen Beisert             |
Linux Solutions for Science and Industry      | Phone: +49-8766-939 228     |
Vertretung Sued/Muenchen, Germany             | Fax:   +49-5121-206917-5555 |
Amtsgericht Hildesheim, HRA 2686              | http://www.pengutronix.de/  |