emfile NAND Image Creator User & Reference Guide Document: UM02003 Software version: 1.03 Revision: 0 Date: November 16, 2016

Transcription

1 emfile NAND Image Creator User & Reference Guide Document: UM02003 Software version: 1.03 Revision: 0 Date: November 16, 2016 A product of SEGGER Microcontroller GmbH & Co. KG

2 2 Disclaimer Specifications written in this document are believed to be accurate, but are not guaranteed to be entirely free of error. The information in this manual is subject to change for functional or performance improvements without notice. Please make sure your manual is the latest edition. While the information herein is assumed to be accurate, SEGGER Microcontroller GmbH & Co. KG (the manufacturer) assumes no responsibility for any errors or omissions. The manufacturer makes and you receive no warranties or conditions, express, implied, statutory or in any communication with you. The manufacturer specifically disclaims any implied warranty of merchantability or fitness for a particular purpose. Copyright notice You may not extract portions of this manual or modify the PDF file in any way without the prior written permission of the manufacturer. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license., Hilden / Germany Trademarks Names mentioned in this manual may be trademarks of their respective companies. Brand and product names are trademarks or registered trademarks of their respective holders. Contact address SEGGER Microcontroller GmbH & Co. KG In den Weiden 11 D Hilden Germany Tel Fax support@segger.com Internet: Manual versions This manual describes the latest software version. If any error occurs, please inform us and we will try to assist you as soon as possible. For further information on topics or routines not yet specified, please contact us. Software Revision Date By MD Added new commands: addpartition, setecclevel, copysectors, creatembr, and listvolumes MD Changes to document format MD Initial version.

3 3 About this document How to use this manual This manual explains all the functions that the product offers. Knowledge of the C language or assembly programming is not required. Typographic conventions for syntax This manual uses the following typographic conventions: Style Used for Body Keyword Sample Reference GUIElement Body text. Text that you enter at the command-prompt or that appears on the display (that is system functions, file- or pathnames). s in API functions. Sample code in program examples. Reference to chapters, sections, tables and figures or other documents. Buttons, dialog boxes, menu names, menu commands. Emphasis Very important sections Table 1.1: Typographic conventions

4 4 SEGGER Microcontroller GmbH & Co. KG develops and distributes software development tools and ANSI C software components (middleware) for embedded systems in several industries such as telecom, medical technology, consumer electronics, automotive industry and industrial automation. SEGGER s intention is to cut software development time for embedded applications by offering compact flexible and easy to use middleware, allowing developers to concentrate on their application. Our most popular products are emwin, a universal graphic software package for embedded applications, and embos, a small yet efficient real-time kernel. emwin, written entirely in ANSI C, can easily be used on any CPU and most any display. It is complemented by the available PC tools: Bitmap Converter, Font Converter, Simulator and Viewer. embos supports most 8/16/32-bit CPUs. Its small memory footprint makes it suitable for single-chip applications. Apart from its main focus on software tools, SEGGER develops and produces programming tools for flash microcontrollers, as well as J-Link, a JTAG emulator to assist in development, debugging and production, which has rapidly become the industry standard for debug access to ARM cores. Corporate Office: United States Office: EMBEDDED SOFTWARE (Middleware) emwin Graphics software and GUI emwin is designed to provide an efficient, processor- and display controller-independent graphical user interface (GUI) for any application that operates with a graphical display. Starterkits, eval- and trial-versions are available. embos Real Time Operating System embos is an RTOS designed to offer the benefits of a complete multitasking system for hard real time applications with minimal resources. The profiling PC tool embosview is included. emfile File system emfile is an embedded file system with FAT12, FAT16 and FAT32 support. emfile has been optimized for minimum memory consumption in RAM and ROM while maintaining high speed. Various Device drivers, e.g. for NAND and NOR flashes, SD/MMC and CompactFlash cards, are available. SEGGER TOOLS Flasher Flash programmer Flash Programming tool primarily for microcontrollers. J-Link JTAG emulator for ARM cores USB driven JTAG interface for ARM cores. J-Trace JTAG emulator with trace USB driven JTAG interface for ARM cores with Trace memory. supporting the ARM ETM (Embedded Trace Macrocell). J-Link / J-Trace Related Software Add-on software to be used with SEGGER s industry standard JTAG emulator, this includes flash programming software and flash breakpoints. USB-Stack USB device stack A USB stack designed to work on any embedded system with a USB client controller. Bulk communication and most standard device classes are supported.

5 5 Table of Contents 1 Introduction About this manual What is the purpose of the NAND Image Creator? The NAND Image Creator Interface of the NAND Image Creator List of commands Flash image related functions File and directory functions Sector related functions Image specific functions...43

6 SEGGER Microcontroller GmbH & Co. KG

7 7 Chapter 1 Introduction This chapter explains the purpose of this manual.

8 8 CHAPTER 1 Introduction 1.1 About this manual The purpose of this document is to describe the functions and abilities of the emfile NAND Image Creator.

9 1.2 What is the purpose of the NAND Image Creator? The NAND Image Creator is a command line tool which gives the customer the ability to build a file containing 1-to-1 representation of NAND flash device (image) with preselected files and directories found on the host PC How is the image created? Files and directories from the host PC are copied to the image file using emfile API function creating the file structure which is required on the target device How is the NAND flash image transferred to the target? The image file created by the NAND Image Creator is a standard bin file which can be flashed directly into the NAND flash of the target via third party tools. 9 UM02002 User & Reference Guide of NAND Image Creator

10 10 CHAPTER 1 Introduction

11 11 Chapter 2 The NAND Image Creator This chapter describes the NAND Image Creator, its functions and how it is used.

12 12 CHAPTER 2 The NAND Image Creator 2.1 Interface of the NAND Image Creator The interface of the NAND Image Creator is used like any other command line based program. For the ease of usage many commands are kept similar to their DOS counterparts. By entering "?" or just pressing the Enter key an overview of the commands is printed on the screen and it should look like the screenshot below SEGGER Microcontroller GmbH & Co. KG

13 13 The NAND Image Creator can work in two modes: interactive and script. The interactive mode is entered when the utility is started with no arguments. In this mode the user is prompted to type in the commands. The script mode is entered when the utility is started with an argument which specifies the name of a file containing the commands to be executed, one command per line.

14 14 CHAPTER 2 The NAND Image Creator Script file sample The following sample shows a simple script file which does the following: Creates a 128MB NAND flash image file "C:\flash.bin" Sets the type of NAND driver which will be used on the target to access the NAND flash to Universal. This command is optional since the default driver type is the Universal NAND driver. Writes the file system information to the image Low-level formats the image High-level formats the image Copies the "Test.txt" file from drive "C:" on host PC to root directory on the image. Copies recursively the contents of "Data" directory on host PC to "Data" directory on the image. script file createimage C:\flash.bin setdrivertype uni init formatlow format addfile C:\Test.txt addfolder C:\Data\ q SEGGER Microcontroller GmbH & Co. KG

15 List of commands The NAND Image Creator can process a NAND flash image by using built in commands. All commands that are usable are listed below. File(s) Flash image related functions createimage setdrivertype setsectorsize addpartition setecclevel showimageinfo init exportimage Creates/opens a new/existing NAND flash image file. Sets the type of NAND driver which will be used on the target to access the NAND flash. Sets the size of a file system sector. Configures a new logical partition. Configures the error correction type. Shows information about NAND flash image. Initializes the NAND image with the specified parameters. Saves to a file the NAND blocks which contain valid data. File and directory functions cd md rd addfile addfolder type del dir ren move attr copy Changes the directory or displays the name of the current directory. Recursively creates a directory. Removes (deletes) a directory. Copies a file from the HOST to the image. Copies a folder and its subfolders and files from the HOST to the image. Shows the content of a file on the screen. Deletes one file. Lists the content of the directory. Renames a file or directory. Moves a file or directory. Shows/changes the file/directory attributes. Copies a file to another location. Sector related functions storesectors dumpsector copysectors Copies sector data from a file on the host to image. Shows the contents of a sector. Copies sector data on the image. Image specific functions formatlow Low-level formats the volume. format High-level formats the volume. df Shows the available free space on the volume. diskinfo Shows the disk information about the volume. getdevinfo Shows the low level disk information about the volume. checkdisk Performs disk checking operation on the volume. creatembr Writes partition table to master boot record (MBR). listvolumes Shows the names of all available volumes. Table 2.1: List of commands

16 16 CHAPTER 2 The NAND Image Creator 2.3 Flash image related functions The following section describes functions required to create a NAND flash image SEGGER Microcontroller GmbH & Co. KG

17 createimage Creates/opens a new/existing NAND flash image file on the host PC. createimage <ImageFileName> <NumBlocks> <PagesPerBlock> <PageSize> [<SpareAreaSize>] ImageFileName Filename of the NAND flash image file that will be created/ opened. NumBlocks Number of blocks in the NAND flash device PagesPerBlock Number of pages in a NAND block (Typ. 64) PageSize Number of user bytes which can be saved in a page (Typ bytes, must be a power of 2 value) Optional number of add. bytes in a page reserved for management SpareAreaSize information. When not specified the value is computed as 1/32 of PageSize Table 2.2: createimage parameter list Additional information The size of the image file will be NumBlocks * PagesPerBlock * (PageSize + SpareAreaSize) bytes large. If the image file already exists but the size of the file does not match it will be silently overwritten. The example shows how to create 128MByte image file. createimage C:\nand.bin

18 18 CHAPTER 2 The NAND Image Creator setdrivertype Configures the type of NAND driver which will be used to access the NAND flash on the target. setdrivertype <DriverType> Additional information This command is optional. If not executed an image is created which can be accessed using the Universal NAND driver. The examples shows how to specify that the SLC1 NAND driver is used on the target to access the NAND flash. setdrivertype slc1 The type of NAND driver used to access the files on the target. DriverType "slc1" - SLC1 NAND driver (FS_NAND_Driver) "uni" - Universal NAND driver (FS_NAND_UNI_Driver) Table 2.3: setdrivertype parameter list SEGGER Microcontroller GmbH & Co. KG

19 setsectorsize Configures the error correction type. setsectorsize <SectorSize> Additional information This command is optional. It can be used to set the size of the logical sector when the SLC1 NAND driver type is selected. Any power of 2 value between 512 bytes and the number of bytes in a NAND page size can be used. When this command is not executed the size of the logical sector is set automatically to the configured page size of NAND flash image. This example shows how to set the logical sector size to 512 bytes. setsectorsize 512 Number of bytes in a logical sector (Typ bytes, must be SectorSize a power of 2 value) Table 2.4: setsectorsize parameter list

20 20 CHAPTER 2 The NAND Image Creator addpartition Configures a new logical partition. addpartition <SectorStart> <NumSectors> [<PartType>] Index of the first sector in the partition relative to the beginning of the storage device. StartSector NumSectors Number of sectors in the partition. Type of the partition to create. Permitted values are: "normal" - The entire partition space can be used by the file system as storage (default). PartType "raid1" - The file system can use only half of the partition space as storage. The other half is used as mirror. Table 2.5: addpartition parameter list Additional information This command is optional. It allows the creation of logical partitions on the image. The command fails if the defined sector range overlaps the range of an already defined logical partition. A maximum of four logical partitions can be created. The partition list has to be stored to image after initialization of the image using the creatembr command. The data on the created logical partitions can be accessed using the DISKPART logical driver. For more details refer to UM02001 emfile User and Reference Guide available from here: The logical partitions can be formatted using the format command. This example shows how to configure 2 logical partitions. The sector 0 is reserved for Master Boot Record where the partition list is stored. addpartition addpartition A possible emfile configuration that allows the application to access the logical partitions looks like this: SEGGER Microcontroller GmbH & Co. KG

21 21 /********************************************************************* * * FS_X_AddDevices * * Function description * This function is called by the FS during FS_Init(). * It is supposed to add all devices, using primarily FS_AddDevice(). * * Note * (1) Other API functions * Other API functions may NOT be called, since this function is called * during initialization. The devices are not yet ready at this point. */ void FS_X_AddDevices(void) { FS_AssignMemory(&_aMemBlock[0], sizeof(_amemblock)); FS_SetMaxSectorSize(2048); // // Add and configure the NAND partition. Volume name: "nand:0:" // FS_AddDevice(&FS_NAND_UNI_Driver); FS_NAND_UNI_SetPhyType(0, &FS_NAND_PHY_2048x8); FS_NAND_UNI_SetECCHook(0, &FS_NAND_ECC_HW_NULL); // // Add and configure the first logical volume. Volume name: "diskpart:0" // FS_AddDevice(&FS_DISKPART_Driver); FS_DISKPART_Configure(0, &FS_NAND_UNI_Driver, 0, 0); // // Add and configure the second non-raid volume. Volume name: "diskpart:1" // FS_AddDevice(&FS_DISKPART_Driver); FS_DISKPART_Configure(1, &FS_NAND_UNI_Driver, 0, 1); }

22 22 CHAPTER 2 The NAND Image Creator setecclevel Configures bit error correction type. setecclevel <NumBitErrors> Additional information This command is optional. If not executed 1-bit software calculated ECC is stored to spare area. If NumBitErrors 0 is set to 0 the bytes in the spare area reserved to ECC are set to 0xFF. This example shows how to set the correction level to hardware ECC. setecclevel 0 Number of bit errors the ECC stored to spare area should be able to correct. Permitted values: NumBitErrors 0 - hardware ECC 1-1-bit software ECC Table 2.6: setecclevel parameter list SEGGER Microcontroller GmbH & Co. KG

23 showimageinfo Shows information about the created image. showimageinfo showimageinfo Name: nand.bin Driver type: Universal Num blocks: 1024 Pages per block: 64 Page size: 2048 bytes Spare area size: 64 bytes Bytes per sector: 2048 bytes

24 24 CHAPTER 2 The NAND Image Creator init Initialize the NAND flash image and emfile. init Additional information This command must be executed before any other command which operates on files and directories. init SEGGER Microcontroller GmbH & Co. KG

25 exportimage Saves to a file the NAND blocks which contain valid data. exportimage <FilePathOnHost> Additional information This command can be used to create an image file that can be directly programmed to NAND flash device. Typically, the created image file is smaller than the original image file which helps reduce the programming time. exportimage C:\NAND.bin

26 26 CHAPTER 2 The NAND Image Creator 2.4 File and directory functions The following section describes functions which can be used for file and directory operations SEGGER Microcontroller GmbH & Co. KG

27 cd Changes or displays the name of a directory. cd <DirPathOnImage> cd Test cd.. Path to new directory to change to. Can be ".." to change to DirPathOnImage the parent directory. Table 2.7: cd parameter list

28 28 CHAPTER 2 The NAND Image Creator md Creates recursively a directory. md <DirPathOnImage> DirPathOnImage Path of the directory which shall be created. Table 2.8: md parameter list Additional information This command will also create any missing directories in the path. md Test\Dir\ SEGGER Microcontroller GmbH & Co. KG

29 rd Removes (deletes) a directory. rd <DirPathOnImage> DirPathOnImage Path of the directory which shall be deleted. Table 2.9: rd parameter list Additional information The directory to be deleted must be empty. rd Test

30 30 CHAPTER 2 The NAND Image Creator addfile Copies a file from the host PC to the image. addfile <FilePathOnHost> [<FilePathOnImage>] FilePathOnHost Path to source file on the host file system. FilePathOnImage Path to destination file on the image. If not specified the name of the source file is used. Table 2.10: addfile parameter list The following command copies the contents of the "Test.txt" file from host PC to "Dest.txt" file on image. addfile C:\Test.txt Dest.txt The following command copies the contents of "Test.txt" to the file with the same name of the image. addfile C:\Test.txt SEGGER Microcontroller GmbH & Co. KG

31 addfolder Copies a folder and its subfolders and files from the host PC to the image. addfolder <DirPathOnHost> [<DirPathOnImage>] DirPathOnHost Path to source directory on the host files system. DirPathOnImage Path to destination directory on the image. If not specified the source folder name will be used. Table 2.11: addfolder parameter list The following command copies the contents of the "Data" directory on PC to "Dest" directory on the image. addfolder C:\Data Dest The following command copies the contents of the "Data" directory on PC to a directory with the same name on the image. addfolder C:\Data

32 32 CHAPTER 2 The NAND Image Creator type Shows the content of a file. type <FilePathOnImage> FilePathOnImage Path to the file on image to be shown. Table 2.12: type parameter list type Test.txt SEGGER Microcontroller GmbH & Co. KG

33 del Deletes one file. del <FilePathOnImage> del Test.txt <FilePathOnImage> Path to the file on image to be deleted. Table 2.13: del parameter list

34 34 CHAPTER 2 The NAND Image Creator dir Lists the contents of the directory. dir <DirPathOnImage> DirPathOnImage Path to directory on image to be listed. Table 2.14: dir parameter list dir Test SEGGER Microcontroller GmbH & Co. KG

35 ren Renames a file or directory. ren <FilePathOnImage> <NewFileName> FilePathOnImage Path to file or directory on the image to be renamed. NewFileName New name for the file or directory. Table 2.15: ren parameter list ren Test Test2

36 36 CHAPTER 2 The NAND Image Creator move Moves a file or directory. move <OldFilePathOnImage> <NewFilePathOnImage> OldFilePathOnImage Path to file or directory to be moved. NewFilePathOnImage Path to new file or directory on the image. Table 2.16: move parameter list move Test\Test.txt New.txt SEGGER Microcontroller GmbH & Co. KG

37 attr Shows/changes the file/directory attributes. attr <PathOnImage> <Operation> <Attributes> PathOnImage Path to file or directory. Operation to be executed on attributes Operation "+" sets the attributes "-" clear the attributes The following attributes are supported: "a" Archive Attributes "h" Hidden "r" Read-only "s" System Table 2.17: attrib parameter list In the following example the archive and read-only attributes are cleared. attr Test.txt -ar

38 38 CHAPTER 2 The NAND Image Creator copy Copies a file. copy <SrcFilePathOnImage> <DestFilePathOnImage> SrcFilePathOnImage Path to the file to be copied on image. DestFilePathOnImage Path destination file on image. Table 2.18: copy parameter list copy Test.txt Test2.txt SEGGER Microcontroller GmbH & Co. KG

39 Sector related functions This section describes functions which can be used to operate on logical sectors.

40 40 CHAPTER 2 The NAND Image Creator storesectors Copies sector data from a file on the host to image. storesectors <FilePathOnImage> [<StartSector>] FilePathOnImage Path to the file on host which contains sector data. StartSector Index of the first sector to be written. If not specified sector index 0 is assumed. Table 2.19: storesectors parameter list Additional information The sector data should be stored sequentially in the file. For example if the sector size is 2048 bytes and the data is stored starting from sector index 100 the byte at offset 0 in the file stores the first byte of sector 100, the byte at offset 2048 in the file stores the first byte of sector 101 and so on. The size of the file should be a multiple of sector size. The size of the sector is the size specified as the argument to setsectorsize command. If this command is not called the size of the sector is equal to page size. The page size is the 4th argument of the createimage command. This example reads sector data from the file "SectorData.bin" and writes it starting from sector index 100. storesectors SectorData.bin SEGGER Microcontroller GmbH & Co. KG

41 dumpsector Shows the contents of a sector. dumpsector <SectorIndex> StartSector Index of the sector to be shown. Table 2.20: dumpsector parameter list dumpsector D 0A D 0A D 0A A B C D 0A D E F D 0A D 0A D 0A D 0A A B C0 0D 0A D E F D 0A

42 42 CHAPTER 2 The NAND Image Creator copysectors Copies sector data on the image. copysectors <SrcSector> <DestSector> <NumSectors> SrcSector Index of the first source sector. DestSector Index of the first destination sector. NumSectors Number of sectors to copy. Table 2.21: copysectors parameter list Additional information This command operates only on the "nand:0:" volume. The command returns with an error if the source and destination range overlap. This example copies sectors from sector index 0 to sector index copysectors SEGGER Microcontroller GmbH & Co. KG

43 2.6 Image specific functions The following section describes functions which can be used for image editing operations. 43

44 44 CHAPTER 2 The NAND Image Creator df Shows the available free space on the volume. df [VolumeName] VolumeName Name of the volume to query. Table 2.22: df parameter list df Available free space is bytes SEGGER Microcontroller GmbH & Co. KG

45 diskinfo Shows the disk information about the volume. diskinfo [VolumeName] VolumeName Name of the volume to query. Table 2.23: diskinfo parameter list diskinfo bytes total disk space bytes available free space 8192 bytes per cluster cluster available on volume 2163 free cluster available on volume

46 46 CHAPTER 2 The NAND Image Creator getdevinfo Shows the low-level disk information about the volume. getdevinfo [VolumeName] VolumeName Name of the volume to query. Table 2.24: getdevinfo parameter list getdevinfo available sectors 2048 bytes per sector SEGGER Microcontroller GmbH & Co. KG

47 format Performs a high-level format of the volume. format [VolumeName] VolumeName Name of the volume which has to be formatted. Table 2.25: format parameter list format High-level format...ok

48 48 CHAPTER 2 The NAND Image Creator formatlow Performs a low-level format of the volume. formatlow [VolumeName] VolumeName Name of the volume which has to be formatted. Table 2.26: formatlow parameter list formatlow Low-level format...ok SEGGER Microcontroller GmbH & Co. KG

49 checkdisk Checks the volume for errors. checkdisk [VolumeName] VolumeName Name of the volume which has to be checked. Table 2.27: checkdisk parameter list checkdisk

50 50 CHAPTER 2 The NAND Image Creator creatembr Writes partition table to Master Boot Record (MBR). creatembr [VolumeName] VolumeName Name of the volume on which the MBR should be stored. Table 2.28: creatembr parameter list Additional information This command stores the partition table configured via addpartition command to the MBR of the specified volume. If the volume name is omitted the partition table is written to the current volume. The command has to be executed after the low-level format and before any high-level format operation. Typ. the partition table is located on "nand:0:" volume. This example stores the MBR to the sector 0 of the "nand:0:" volume. creatembr "nand:0:" SEGGER Microcontroller GmbH & Co. KG

51 listvolumes Shows the names of all available volumes. listvolumes Shows the names of the volumes of a configuration using four logical volumes. listvolumes Available volumes: nand:0: diskpart:0: diskpart:1: diskpart:2: diskpart:3:

52 52 CHAPTER 2 The NAND Image Creator SEGGER Microcontroller GmbH & Co. KG

53 53 Index C Commands addfile...30 addfolder...31 attrib...37 cd...27 checkdisk...49 copy...38 createimage...17 del...33 df...44 dir...34 diskinfo...45 format...47 formatlow...48 getdevinfo...46 init...24 listvol...44 md...28 move...36 rd...29 ren...35 showimageinfo...23 type...32 L List of command...15 S, conventions used... 3

54 54 Index