Creating an eMMC image using Storage Image Creator

The Storage Image Creator is a command line utility that can be used to build a single file containing a complete FAT file system including directory structure and files ready to be stored and used without preparation apart from mounting the file system.

The utility operates by executing text commands that perform different operations related to the data stored on the image file such as formatting the storage and copying of files from the file system of the host PC to the file system stored in the image file. The utility can execute the commands either interactively by typing them in the same way as in a command line (interactive mode) or by reading them from a text file (batch mode). A description of all the supported commands can be found in the emFile user manual.

The interactive mode is entered if the utility is started without arguments. The utility enters batch mode if it is started with the file containing the commands to be executed as argument.

The following example shows how to create a FAT file system image for an eMMC device with the capacity of about 8 GB that contains two files an one directory. The example uses the interactive mode for the creation of the file system image. However, the same file system image can be created by saving the commands in a separate text file and by executing them in the batch mode.

We start by creating a folder on the host PC that will serve as work area. For convenience, we make a copy of the Storage Image Creator utility to this folder. This is possible because the Storage Image Creator is a standalone application that does not require any installation and that depends only on the standard system libraries.

Initial work folder contents

Next, we create the file and directory structure that has to be present on the eMMC device mounted on the target hardware. For this purpose we create a folder called RootDir that contains all the files and directories that will be present in the root directory of the FAT file system stored on the eMMC device. The root directory contains a folder named SubDir and a file named File1.txt. The SubDir folder contains a file named File2.txt.

Target root directory

We store some text data in the created files so that we can check later if the files were correctly copied to the image.

Contents of File1.txt]

Contents of File2.txt]

In the next step, we start the Storage Image Creator utility either by double-clicking on the name of the executable or by selecting the executable and pressing the Enter key. At startup, the utility displays some general information such as the emFile version and the build date followed by a prompt that accepts commands from the user. Similarly to a Windows command line prompt, the text of the command can be typed-in and edited. The command is executed only when the Enter key is pressed. The name of the commands is case insensitive. This means that Help and help are interpreted by the Storage Image Creator as the same command.

Startup information

The list of supported commands and a short description of them can be displayed by executing either the Help command or by pressing the ? key.

Brief command information

The first command that has to be executed for the creation of the image is the CreateImage command. The purpose of this command is to configure the name of the file that stores the image on the host PC as well as information about the capacity of the storage device mounted on the target hardware. Generally, all commands will display an error message if the operation fails. Most of the commands will also display information during the execution indicating that the command completed successfully. If a command does not display any information during the execution than this is an indication that the command completed successfully.

The capacity of the storage device is specified via the second and the third command parameter. The second parameter specifies the total number of storage blocks available on the storage device while the third parameter specifies the size of one storage block in bytes. The third parameter is optional and can be omitted. The default value of this parameter is 512 that is the typical block size used by an eMMC device or by an SD card.

The value of the second parameter can be taken either from the data sheet of the eMMC device or by calling the FS_STORAGE_GetDeviceInfo emFile API function in an application on the target hardware. The NumSectors member of the FS_DEV_INFO structure returned via the second parameter stores the value that has to be entered as second parameter of the CreateImage command.

In our case we create an image for an eMMC device of about 8 GB that works with blocks of 512 bytes (15269888 × 512 = 7.818.182.656 bytes about 8 GB). The image is stored to a file with the name eMMC.img. The size of the block is omitted because it equals with the default value used by the Storage Image Creator utility.

Image configuration

After configuring the image parameters we can verify that all the input values are correct by executing the ShowImageInfo command. This command displays information about the name of the image file and about its size.

Image information

The next step is to perform the initialization of the image. The main purpose of this command is to initialize the emFile instance that the Storage Image Creator utility uses for accessing the image. This is done by executing the Init command. The successful execution of the command is confirmed by the Storage Image Creator utility by modifying the prompt text to include the name of the file system partition attached by emFile to the image. Because emFile is configured to use an instance of the Disk File driver for the access the prompt text is expanded by the file:0: text. After the execution of this command the Storage Image Creator will start accepting commands that operate on the data stored on the created image.

Image initialization

The first operation to be executed on a newly created image is to initialize the structure of file system that is stored on it. This can be done by executing the Format command.

File system formatting

The successful completion of the format operation can be verified by checking if a file with the name specified earlier via the CreateImage exists in the work folder. In addition to the actual image file the Storage Image Creator utility creates a second file with the extension .sta. The purpose of this file is to store information about what blocks contain valid data. This information is used in the last step of the image creation process when the data stored on the image is exported to a separate file in Motorola S-record format. The .sta file does not store any file system data.

Work folder with image file

The correct initialization of the file system stored on the image can be verified by executing the DiskInfo command. This command displays information about the amount of total and of the free space available on the storage as well as about the size of the allocation unit (called cluster) used by the file system.

In our particular case, emFile formatted the storage device with a cluster size of 32 KB. The reason why the amount of free space is smaller that the total storage space is that the file system has to allocate storage for the root directory.

File system information

Once the file system is initialized we can start storing to it the files and directories that we prepared earlier. For this purpose we execute the AddFolder command to copy recursively all the files and directories stored in the RootDir folder. The Storage Image Creator utility also provides commands that can be used to individually create directories on the image and explicitly store files to them.

The AddFolder command takes as first parameter the name of the folder on the host PC that contains the files and directories to be copied to the image. The second parameter is the name of the target directory on the image. In our case, we want to store all the files and directories in the root directory of the file system partition. For this reason, we have to specify the name of the file system partition as the second parameter which in this case is file:0:. By default, the AddFolder command displays all the names of the files and directory it creates. This can be suppressed by specifying the /S option as last parameter.

Adding folder contents

After successfully storing the files and directories, we can check that the file structure is correct by executing the Dir command to list all the files and directories stored in the root directory of the created image. The Dir command can take a optional directory name to be listed as parameter. In our case, we execute the command without any parameter. This causes the command to display the contents of the current directory which in this case is the root directory. The current directory can be changed by executing the ChDir command with the name of the new current directory as parameter.

Root directory contents

In addition, we can check that the contents of the stored files is correct by executing the Type command on File1.txt and File2.txt files. As we can see in the following two screen shots the contents of these files matches the text data that we input earlier via the text editor.

Contents of File1.txt

Contents of File2.txt

One last step before completing the creation of the image is to verify that the structure of the file system stored on it is not damaged. This can be done by executing the CheckDisk command.

Checking consistency of file system

The creation of the image is now complete. The eMMC.img can be programmed as-is to the eMMC device mounted on the target hardware. However, the time it takes to program an image of this size is restrictively long. Because the image contains a relatively large amount of free storage space that do not store any data, it should be possible to reduce the programming time by programming only the data blocks that actually contain valid data. The Storage Image Creator has the ability to copy valid data blocks from image to a separate file in different file formats via the ExportImage command.

In our example, we export the valid data blocks in Motorola S-record format to a file named eMMC.srec. The file name has to be specified as first parameter. As second parameter the format of the export file has to be specified. On successful completion, the command displays the number of valid data blocks copied. The reason for the relatively large number of valid data blocks copied in comparison with the relatively small amount of storage space occupied by the files and directories is that some of the copied data blocks contain management data of the file system such as the allocation table that is initialized during the format operation to indicate that the storage space is free.

Exporting valid logical sectors

As it can be seen in the next screen shot, the size of the exported Motorola S-record file is much smaller than that of the actual image file.

Work folder with exported file