packages/devs/disk/generic/mmc/v2_0/doc/disk_mmc.sgml

   1 <!-- DOCTYPE refentry  PUBLIC "-//OASIS//DTD DocBook V3.1//EN" -->
   2
   3 <!-- {{{ Banner                         -->
   4
   5 <!-- =============================================================== -->
   6 <!--                                                                 -->
   7 <!--     disk_mmc.sgml                                               -->
   8 <!--                                                                 -->
   9 <!--     Documentation for the MMC disk device driver                -->
  10 <!--                                                                 -->
  11 <!-- =============================================================== -->
  12 <!-- ####COPYRIGHTBEGIN####                                          -->
  13 <!--                                                                 -->
  14 <!-- =============================================================== -->
  15 <!-- Copyright (C) 2004 eCosCentric Limited                          -->
  16 <!-- This material may be distributed only subject to the terms      -->
  17 <!-- and conditions set forth in the Open Publication License, v1.0  -->
  18 <!-- or later (the latest version is presently available at          -->
  19 <!-- http://www.opencontent.org/openpub/)                            -->
  20 <!-- Distribution of the work or derivative of the work in any       -->
  21 <!-- standard (paper) book form is prohibited unless prior           -->
  22 <!-- permission obtained from the copyright holder                   -->
  23 <!-- =============================================================== -->
  24 <!--                                                                 -->
  25 <!-- ####COPYRIGHTEND####                                            -->
  26 <!-- =============================================================== -->
  27 <!-- =============================================================== -->
  28 <!-- #####DESCRIPTIONBEGIN####                                       -->
  29 <!--                                                                 -->
  30 <!-- Author(s):   bartv                                              -->
  31 <!-- Contact(s):  bartv                                              -->
  32 <!-- Date:        2004/04/25                                         -->
  33 <!-- Version:     0.01                                               -->
  34 <!--                                                                 -->
  35 <!-- ####DESCRIPTIONEND####                                          -->
  36 <!-- =============================================================== -->
  37
  38 <!-- }}} -->
  39
  40 <part id="devs-disk-mmc-part"><title>MMC MultiMedia Card Disk Driver</title>
  41
  42 <refentry id="devs-disk-mmc">
  43   <refmeta>
  44     <refentrytitle>Device Driver for MMC MultiMedia Cards</refentrytitle>
  45   </refmeta>
  46   <refnamediv>
  47     <refname><varname>CYGPKG_DEVS_DISK_MMC</varname></refname>
  48     <refpurpose>eCos Support for MMC MultiMedia Cards</refpurpose>
  49   </refnamediv>
  50
  51   <refsect1 id="devs-disk-mmc-description"><title>Description</title>
  52     <para>
  53 This package provides a disk device driver for MultiMediaCards (MMC).
  54 A MultiMediaCard provides non-volatile storage in a small footprint
  55 (24mm &ast; 32mm &ast; 1.4mm), and weighing less than 2 grams. Typical
  56 card sizes are 16MB to 128MB, with an upper limit of 4GB. It
  57 should be noted that these sizes are measured in millions of bytes,
  58 not 2^20. The <ulink url="http://www.mmca.org">MultiMediaCard
  59 Association</ulink> defines the standard for these cards.
  60     </para>
  61     <para>
  62 At the hardware level there are two ways of accessing an MMC card,
  63 either using a custom interface or via an SPI bus. A card will detect
  64 the interface in use at run-time. The custom interface allows for
  65 better performance but requires additional hardware. Currently only
  66 SPI mode is supported by this package.
  67     </para>
  68     <para>
  69 Theoretically an MMC card can be used with any file system. In
  70 practice all cards are formatted for PC compatibility, with a
  71 partition table in the first block and a single FAT file system on the
  72 rest of the card. Currently this package checks the format of the MMC
  73 card and will only allow access to a card if it is formatted this way.
  74     </para>
  75     <para>
  76 An MMC socket allows cards to be removed and inserted at any time. The
  77 device driver will detect removal events when the next I/O operation
  78 happens and will report them to higher-level code via an error code
  79 <literal>ENODEV</literal>. However there are no guarantees that the
  80 higher-level code will be able to recover from this error. The
  81 expected usage is that application code will explicitly
  82 <function>mount</function> the card before attempting any file I/O,
  83 and will <function>umount</function> the card before it is removed.
  84 Between these operations the system is likely to keep some disk blocks
  85 cached, for performance reasons. If the card is removed before the
  86 <function>umount</function> then it may end up with a corrupted file
  87 system, and the disk subsystem may be left in an inconsistent state.
  88 Regular uses of <function>sync</function> will reduce the risk
  89 of file system corruption.
  90     </para>
  91   </refsect1>
  92
  93   <refsect1 id="devs-disk-mmc-config"><title>Configuration Options</title>
  94     <para>
  95 <varname>CYGPKG_DEVS_DISK_MMC</varname> is a hardware package which
  96 should get loaded automatically when you configure for a suitable eCos
  97 target platform. In this case suitable means that the hardware has an
  98 MMC socket connected to an SPI bus, that an SPI bus driver package
  99 exists and is also automatically loaded, and that the platform HAL
 100 provides <link linkend="devs-disk-mmc-porting">information</link>
 101 on how the card is connected to the SPI bus.
 102     </para>
 103     <para>
 104 The package depends on support from the generic disk package
 105 <varname>CYGPKG_IO_DISK</varname>. That will not be loaded
 106 automatically: the presence of an MMC socket on the board does not
 107 mean that the application has any need for a file system. Hence by
 108 default <varname>CYGPKG_DEVS_DISK_MMC</varname> will be inactive and
 109 will not contribute any code or data to the application's memory
 110 footprint. To activate the driver it will be necessary to add one or
 111 more packages to the configuration using
 112 <command>ecosconfig&nbsp;add</command> or the graphical configuration
 113 tool: the generic disk support <varname>CYGPKG_IO_DISK</varname>;
 114 usually a file system, <varname>CYGPKG_FS_FAT</varname>; support for
 115 the file I/O API <varname>CYGPKG_IO_FILEIO</varname>; and possibly
 116 additional support packages that may be needed by the file system, for
 117 example <varname>CYGPKG_LINUX_COMPAT</varname>. Depending on the
 118 template used to create the initial configuration some of these may be
 119 loaded already.
 120     </para>
 121     <para>
 122 The package provides two main configuration options.
 123 <varname>CYGDAT_DEVS_DISK_MMC_SPI_DISK0_NAME</varname> specifies the
 124 name of the raw disk device, for example <literal>/dev/hd0</literal>.
 125 Allowing for partition tables that makes <literal>/dev/hd0/1</literal>
 126 the first argument that shoul be passed to a
 127 <function>mount</function> call. If the hardware has multiple disk
 128 devices then each one will need a unique name.
 129 <varname>CYGIMP_DEVS_DISK_MMC_SPI_POLLED</varname> controls whether
 130 the SPI bus will be accessed in interrupt-driven or polled mode. It
 131 will default to interrupt-driven if the application is multi-threaded,
 132 which is assumed to be the case if the kernel is present. If the
 133 kernel is absent, for example in a RedBoot configuration, then the
 134 driver will default to polled mode. With some hardware polled mode may
 135 significantly increase disk throughput even in a multi-threaded
 136 application, but will consume cpu cycles that could be used by other
 137 threads.
 138     </para>
 139   </refsect1>
 140
 141   <refsect1 id="devs-disk-mmc-extra"><title>Additional Functionality</title>
 142     <para>
 143 The disk driver package exports a variable
 144 <varname>cyg_mmc_spi_polled</varname>. This defaults to true or false
 145 depending on the configuration option
 146 <varname>CYGIMP_DEVS_DISK_MMC_SPI_POLLED</varname>. If the default
 147 mode is interrupt-driven then file I/O, including mount operations,
 148 are only allowed when the scheduler has started and interrupts have
 149 been enabled. Any attempts at file I/O earlier during system
 150 initialization, for example inside a C++ static constructor, will lock
 151 up. If it is necessary to perform file I/O at this time then the
 152 driver can be temporarily switched to polling mode before the I/O
 153 operation by setting <varname>cyg_mmc_spi_polled</varname>, and
 154 clearing it again after the I/O. Alternatively the default mode can be
 155 changed to polling by editing the configuration, and then the
 156 <function>main()</function> thread can change the mode to
 157 interrupt-driven once the scheduler has started.
 158     </para>
 159   </refsect1>
 160
 161   <refsect1 id="devs-disk-mmc-porting"><title>Porting to New Hardware</title>
 162     <para>
 163 Assuming that the MMC connector is hooked up to a standard SPI bus and
 164 that there is already an eCos SPI bus driver, porting the MMC disk
 165 driver package should be straightforward. Some other package, usually
 166 the platform HAL, should provide a <type>cyg_spi_device</type>
 167 structure <varname>cyg_spi_mmc_dev0</varname>. That structure contains
 168 the information needed by this package to interact with the MMC card
 169 via the usual SPI interface, for example how to activate the
 170 appropriate chip select. The platform HAL should also implement the
 171 CDL interface <varname>CYGINT_DEVS_DISK_MMC_SPI_CONNECTORS</varname>.
 172     </para>
 173     <para>
 174 When defining <varname>cyg_spi_mmc_dev0</varname> special care must be
 175 taken with the chip select. The MMC protocol is transaction-oriented.
 176 For example a read operation involves an initial command sent to the
 177 card, then a reply, then the actual data, and finally a checksum. The
 178 card's chip select must be kept asserted for the entire operation, and
 179 there can be no interactions with other devices on the same SPI bus
 180 during this time.
 181     </para>
 182     <para>
 183 Optionally the platform HAL may define a macro
 184 <function>HAL_MMC_SPI_INIT</function> which will be invoked during a
 185 mount operation. This can take any hardware-specific actions that may
 186 be necessary, for example manipulating GPIO pins. Usually no such
 187 macro is needed because the hardware is set up during platform
 188 initialization.
 189     </para>
 190     <para>
 191 Currently the package does not provide any support for accessing MMC
 192 cards using an interface other than SPI. On some targets there may be
 193 additional hardware to detect events such as card insertion or
 194 removal, but there is no support for exploiting such hardware at
 195 present.
 196     </para>
 197     <para>
 198 Only a single MMC socket is supported. Extending the package to
 199 support multiple sockets would be straightforward but it seems
 200 unlikely that any hardware would come with multiple MMC sockets. Given
 201 the nature of SPI buses there is a problem if the MMC socket is hooked
 202 up via an expansion connector rather than being attached to the main
 203 board. The platform HAL would not know about the socket so would not
 204 implement the CDL interface
 205 <varname>CYGINT_DEVS_DISK_MMC_SPI_CONNECTORS</varname>, and the
 206 <database>ecos.db</database> target entry would not include
 207 <varname>CYGPKG_DEVS_DISK_MMC</varname>. Because this is a hardware
 208 package it cannot easily be added by hand. Instead this scenario would
 209 require some editing of the existing platform HAL and target entry.
 210     </para>
 211   </refsect1>
 212
 213 </refentry>
 214 </part>