projects / z180-stamp.git / blame
| Commit | Line | Data |
|---|---|---|
| 53668523 L |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r |
| 2 | <html lang="en">\r | |
| 3 | <head>\r | |
| 289f6a14 | 4 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8">\r |
| 53668523 L |
5 | <meta http-equiv="Content-Style-Type" content="text/css">\r |
| 6 | <link rel="up" title="FatFs" href="../00index_e.html">\r | |
| 7 | <link rel="alternate" hreflang="ja" title="Japanese" href="../ja/dread.html">\r | |
| 8 | <link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r | |
| 9 | <title>FatFs - disk_read</title>\r | |
| 10 | </head>\r | |
| 11 | \r | |
| 12 | <body>\r | |
| 13 | \r | |
| 14 | <div class="para func">\r | |
| 15 | <h2>disk_read</h2>\r | |
| 5630b930 | 16 | <p>The disk_read function is called to read data from the storage device.</p>\r |
| 53668523 L |
17 | <pre>\r |
| 18 | DRESULT disk_read (\r | |
| 19 | BYTE <span class="arg">pdrv</span>, <span class="c">/* [IN] Physical drive number */</span>\r | |
| 20 | BYTE* <span class="arg">buff</span>, <span class="c">/* [OUT] Pointer to the read data buffer */</span>\r | |
| 5630b930 | 21 | LBA_t <span class="arg">sector</span>, <span class="c">/* [IN] Start sector number */</span>\r |
| 53668523 L |
22 | UINT <span class="arg">count</span> <span class="c">/* [IN] Number of sectros to read */</span>\r |
| 23 | );\r | |
| 24 | </pre>\r | |
| 25 | </div>\r | |
| 26 | \r | |
| 27 | <div class="para arg">\r | |
| 28 | <h4>Parameters</h4>\r | |
| 29 | <dl class="par">\r | |
| 30 | <dt>pdrv</dt>\r | |
| 31 | <dd>Physical drive number to identify the target device.</dd>\r | |
| 32 | <dt>buff</dt>\r | |
| 289f6a14 | 33 | <dd>Pointer to the first item of the <em>byte array</em> to store read data. Size of read data will be the sector size * <tt class="arg">count</tt> bytes.</dd>\r |
| 53668523 | 34 | <dt>sector</dt>\r |
| 5630b930 | 35 | <dd>Start sector number in LBA. The data type <tt>LBA_t</tt> is an alias of <tt>DWORD</tt> or <tt>QWORD</tt> depends on the configuration option.</dd>\r |
| 53668523 | 36 | <dt>count</dt>\r |
| 70702af1 | 37 | <dd>Number of sectors to read.</dd>\r |
| 53668523 L |
38 | </dl>\r |
| 39 | </div>\r | |
| 40 | \r | |
| 41 | \r | |
| 42 | <div class="para ret">\r | |
| 43 | <h4>Return Value</h4>\r | |
| 44 | <dl class="ret">\r | |
| 45 | <dt>RES_OK (0)</dt>\r | |
| 46 | <dd>The function succeeded.</dd>\r | |
| 47 | <dt>RES_ERROR</dt>\r | |
| 289f6a14 | 48 | <dd>An unrecoverable hard error occured during the read operation.</dd>\r |
| 53668523 L |
49 | <dt>RES_PARERR</dt>\r |
| 50 | <dd>Invalid parameter.</dd>\r | |
| 51 | <dt>RES_NOTRDY</dt>\r | |
| 52 | <dd>The device has not been initialized.</dd>\r | |
| 53 | </dl>\r | |
| 54 | </div>\r | |
| 55 | \r | |
| 56 | \r | |
| 57 | <div class="para desc">\r | |
| 58 | <h4>Description</h4>\r | |
| 5630b930 L |
59 | <p>Read/write operation to the generic storage devices, such as memory card, hadddisk and optical disk, is done in unit of block of data bytes called <em>sector</em>. FatFs supports the sector size in range of 512 to 4096 bytes. When FatFs is configured for fixed sector size (<tt>FF_MIN_SS == FF_MAX_SS</tt>, this is the most case), the generic read/write function must work at this sector size only. When FatFs is configured for variable sector size (<tt>FF_MIN_SS < FF_MAX_SS</tt>), the sector size of medium is inquired with <tt>disk_ioctl</tt> function after <tt>disk_initialize</tt> function succeeds.</p>\r |
| 60 | <p>There are some considerations about the memory addres passed via <tt class="arg">buff</tt>. It is not that always aligned with the word boundary, because the argument is defined as <tt>BYTE*</tt>. The unaligned transfer request can occure at <a href="appnote.html#fs1">direct transfer</a>. If the bus architecture, especially DMA controller, does not allow unaligned memory access, it should be solved in this function. If it is the case, there are some workarounds described below to avoid this issue.</p>\r | |
| 53668523 | 61 | <ul>\r |
| 5630b930 | 62 | <li>Convert word transfer to byte transfer with some trick in this function. - Recommended.</li>\r |
| 289f6a14 | 63 | <li>On the <tt>f_read()</tt> calls, avoid long read request that includes a whole of sector. - Any direct transfer never occures.</li>\r |
| 5630b930 | 64 | <li>On the <tt>f_read(fp, data, btw, bw)</tt> calls, make sure that <tt>(((UINT)data & 3) == (f_tell(fp) & 3))</tt> is true. - Word alignment of <tt class="arg">buff</tt> is guaranteed.</li>\r |
| 53668523 | 65 | </ul>\r |
| 5630b930 | 66 | <p>Also the memory area may be out of reach in DMA. This is the case if it is located on the tightly coupled memory which is usually used for stack. Use double buffered transfer, or avoid to define file I/O buffer, <tt>FATFS</tt> and <tt>FIL</tt> structure as local variables where on the stack.</p>\r |
| 289f6a14 | 67 | <p>Generally, a multiple sector read request must not be split into single sector transactions to the storage device, or read throughput gets worse.</p>\r |
| 53668523 L |
68 | </div>\r |
| 69 | \r | |
| 70 | \r | |
| 71 | <p class="foot"><a href="../00index_e.html">Return</a></p>\r | |
| 72 | </body>\r | |
| 73 | </html>\r |