mNAND Refresh Utility
The mNAND Refresh utility (mnand_rfsh) ensures that eMMC mNAND blocks are refreshed by issuing refresh commands at an appropriate rate.
An mNAND refresh command may take a substantial amount of time to execute, depending on manufacturer implementation and mNAND’s internal state, and so may cause the device’s primary application to “stutter.” For this reason, the utility can operate in three different modes:
• Session Mode: Intended for use when the device is initialized and may be interacting with a user; has a limited impact on device performance.
Once the utility is started it remains loaded and wakes up at a predefined interval. Each time the utility wakes up it determines the actual refresh progress and issues zero or more mNAND refresh commands, as necessary, to make actual refresh progress converge with scheduled refresh progress.
The wake-up interval may be set from chip data (stored in the mNAND supporting library based on part number) or by an argument provided to the utility. It is typically long (e.g., 3600 seconds) to limit the impact of refresh processing on user interaction. The interval between refresh commands sent within a single wake-up session is also long (e.g. 20 seconds) for the same reason.
• Catch-Up Mode: Intended for use when the device is being shut down and is not interacting with a user; can make refresh progress converge much more quickly than in Session Mode, but keeps the mNAND device busy while running, so concurrent read and write access by other applications is not recommended.
The utility determines how many refresh commands are required to make refresh progress converge to the scheduled refresh progress. It then issues the required number of refresh commands with a predefined interval after each command. The interval between refresh commands is typically short (e.g. 100 msec) to provide rapid convergence.
Because a device typically must complete shutdown within a limited amount of time, Catch-Up Mode provides an optional command line switch to limit the utility’s run time. When the run time limit is reached the utility stops running even if it has not issued the required number of refresh commands. Refresh progress must continue catching up the next time the device is turned on.
• Blind Mode: A legacy mode implemented in previous projects. The utility remains loaded, wakes up at a predefined interval, and issues one refresh command each time it wakes up. It does not measure actual refresh progress or try to make actual refresh progress converge with scheduled refresh progress.
Requirements
The following table shows the requirements of each execution mode.
Requirement | Blind Mode | Session Mode | Catch-Up Mode |
History file | N/A | Required; if the file is not present the utility creates it. | Required; if the file is not present the utility creates it. |
Accurate date and time information | N/A | Required. | Required. |
mnand_rfsh Support
Support for the mnand_rfsh utility is available for the following eMMC vendors.
Vendor | Revision |
Hynix Part | 7.3 or later |
Samsung Part | All supported |
Session Mode and Catch-Up Mode
Use one of these modes to refresh all blocks of eMMC within a certain number of days. The refresh period may be specified by the eMMC vendor or the eMMC lifetime usage model. The mnand_rfsh utility must keep track of the percentage of refresh progress of the eMMC. Consult the following table to identify the eMMC refresh requirements by vendor (assumes a certain temperature profile; contact an application engineer for details).
Vendor | Refresh period | How refresh progress is represented |
Hynix | 180 days | Percentage |
Samsung | 90 days | P/E Cycles |
The utility maintains its refresh progress in a history file, represented as a percentage of the mNAND device’s capacity; 100% represents one full refresh cycle, i.e. a refresh of all blocks that contain data. The command line specifies the path to the history file.
The history file stores a maximum of 250 entries. Since the utility stores one entry per day, the file can keep track of more than six months of data without growing larger than a few kilobytes (KB). Assuming that each entry consumes 40 bytes, the file does not exceed 10 KB.
These example entries show the format of the history file:
15072015093054,@1864.960000,495805381
15072015093155,@1865.010000,445735877
20072015093054,@1865.010000,374432690
Each line in the history file represents one wake-up of the utility. If the utility wakes up more than twice on a given day, though, the first and last entries for that day are retained, and the rest are discarded.
The format of each line in the log file is:
• A string containing the date and time as “ddmmyyyyHHMMSS”
• An @ sign followed by the refresh progress percentage
• A checksum for the line
Algorithm for Converging to the Refresh Schedule
To determine the number of refreshes to trigger, the utility finds the history file entry that is dated closest to a specified number of days in the past. It then computes the difference between the refresh progress recorded in that entry and the refresh progress currently reported by the device. It compares that difference to the difference that should have occurred to keep the refresh progress on schedule.
If the history file is not present, the utility estimates the default refresh progress for a period of one hour. For example:
Default Refresh Progress in Days (d) | Current Refresh Progress (p) | Default Desired Progress in 1 hour p + 100%/(d*24) |
90 days | 1936.380000% | 1936.426296% |
Notice that regardless of whether the utility operates in Session Mode or Catch-Up Mode, its calculation of the required number of refresh commands is the same. The only difference is in the way the commands are applied: gradually in Session Mode, to limit the impact on device performance, and rapidly in Catch-Up Mode, to converge quickly with scheduled refresh progress.
Terminating or Limiting Execution in Catch-Up Mode
The utility gracefully exits when you kill the process or press CTRL+C in a console window. This is important because, if the number of blocks to refresh is large, completing the refresh process might require more time than is available.
The utility also allows a parameter to self-limit the execution duration, regardless of how many blocks are pending to refresh.
Recommendations for Using mnand_rfsh
At system boot, the mnand_rfsh utility is started in Session Mode during system initialization. For instance, if parameters -S 20 -s 3600 are used, the utility sends refreshes at intervals of 20 seconds until the target refresh amount is achieved. Once the target is achieved, the utility sleeps for 3600 seconds, then wakes up and does the same thing again. The process repeats as long as the utility is loaded.
At shutdown, terminate the instance of mnand_rfsh that is currently executing in Session Mode and restart the utility in Catch-Up Mode so that refresh progress can be synchronized with the target refresh progress desired for the eMMC device on that day if it is behind schedule.
If the system contains more than one eMMC, run the utility independently for each one.
Building and Running
The SDK includes the source code for the utility and a Makefile.
To build the mnand_rfsh utility
1. On the host system, navigate to the directory containing the script:
cd <
top>/drive-t186ref-linux/samples/tools/mnand_rfsh
2. Enter the following commands:
make clean
make
To run the mnand_rfsh utility on the target
1. Set up the
target to run the mNAND refresh utility.
2. On the target, run the mNAND refresh utility by entering:
mnand_rfsh -d <mnand_path> [<options>]
Where <mnand_path> is the device node of the mNAND device you want to check (required) and <options> is one or more command line options (optional).
mnand_rfsh Command Usage
Run the
mnand_rfsh utility from a terminal window on the
target.
In the following procedures:
• <mnand_path> is the path to the mNAND device.
• <file_path> is the path to the history file in which the utility stores refresh progress data.
• <time> is the maximum time that the utility may run, in seconds.
• <time_sec> is the interval between refresh commands, in seconds (used only in Session Mode and Blind Mode).
• <time_msec> is the interval between refresh commands, in milliseconds (used only in Catch-Up Mode).
• <session_time> is the interval between sessions, in seconds (used only in Session Mode).
• <date_time> is the current date and time in UTC format (DDMMYYYYhhmmss).
• <days> is the number of period, in days, over which the utility is intended to refresh the device.
• <verbosity> specifies the amount of detail that the utility should provide in its displayed output.
To start the utility in Session Mode
• Enter the command:
mnand_rfsh -d <dev_path> -p <file_path> -S <time_sec> -s <session_time> [-t <date_time>] [-y days] [-v verbosity]
The utility attempts to ensure that the mNAND device is refreshed within a given number of days, as described in
Algorithm for Converging to the Refresh Schedule. Each time it wakes up it issues the mNAND refresh command as many times as necessary to converge with the refresh schedule.
To start the utility in Catch-Up Mode
• Enter the command:
mnand_rfsh -d <dev_path> -p <file_path> -C <time_msec> [-t <date_time>] [-m time_sec] [-y days] [-v verbosity]
The utility attempts to ensure that the mNAND device is refreshed within the time specified by the
-m parameter, as described in
Algorithm for Converging to the Refresh Schedule. The utility issues a refresh command every
<time_msec> milliseconds until the desired refresh progress is achieved, or the run time specified by
<time_sec> expires.
To start the utility in Blind Mode
• Enter the command:
mnand_rfsh -d <mnand_path> -R <time_sec> [-v verbosity]
The utility issues one refresh command every <time_sec> seconds.
Supported Options
The mnand_rfsh utility supports the following options.
Options | Description |
-d <mnand_path> | Specifies the path to mNAND device, for example, /dev/mnand<id>. |
-t <date/time> | Specifies the current date and time in UTC format (DDMMYYYYhhmmss). If omitted, the utility uses the current system time. |
-p <file_path> | Specifies the full pathname at which the utility can find or create its persistent file. You must decide the best location for this file. It is recommended to store the persistent file in a medium other than mNAND, so that the file can be recovered for post-mortem analysis in case of failure. |
-y <days> | Specifies the number of days within which the utility should refresh the device. If 0 (zero), the utility uses chip data. |
-C <time_msec> | Applies to: Catch-Up Mode Specifies the delay between refresh commands, in milliseconds. The default is 100 msec. Note: This option must be used with ‑p to specify the location of the persistent file. It cannot be used with the ‑S or ‑R option. |
-m <time> | Applies to: Catch-Up Mode Specifies the maximum time to run the utility, in seconds. The default is 0 (zero), which sets no limit on run time. Note: This option must be used with ‑p to specify the location of the persistent file. It cannot be used with the ‑S or ‑R option. |
-v <verbosity> | Sets the verbosity level for the utility’s display, from 0 (least verbose) to 2 (most verbose). The default is 0. |
-S <time_sec> | Applies to: Session Mode Performs a proactive refresh continuously while monitoring the progress. Delay between the refresh commands, in seconds. If 0 (zero), the utility uses chip data. Note: This option must be used with ‑p to specify the location of the persistent file. It cannot be used with
the ‑m or ‑C option. |
-s <session_time> | Applies to: Session Mode Specifies the delay between sessions, in seconds. If 0 (zero), the utility uses chip data. |
-R <time_sec> | Applies to: Blind Mode Interval between refreshes, in seconds. The default is 0. No persistent file is required. and refresh progress is not monitored. Note: This option cannot be used with the ‑S or ‑C option. |
Example Usage
This section provides examples of using mnand_rfsh.
Running in Session Mode
This command causes mnand_rfsh to issue refreshes every 20 seconds until the target refresh progress is achieved, and then to re-estimate after one hour:
./mnand_rfsh -d /dev/mnand<id> -t 06102011103800 -p ./mnand_rfsh.log -S 20 -s 3600
Where <id> identifies the mNAND device.
The following command is similar except that it produces output:
./mnand_rfsh -d /dev/mnand<id> -t 06102011103800 -p ./mnand_rfsh.log -S 20 -s 3600 -v 2
Refreshing Over Six Months
This command is appropriate for use in the shutdown process on a system that is intended to refresh an mNAND device over a period of six months:
./mnand_rfsh -d /dev/mnand<id> -t 06102011103800 -p ./mnand_rfsh.log -C 100 -m 120 -y 180
Where:
• <id> identifies the MMC/SD device.
• ‑C implies Catch-Up Mode, and specifies a refresh interval of 100 msec.
• ‑y also implies Catch-Up Mode, and specifies a refresh period of 180 days.
• ‑m specifies a maximum run time of 120 seconds to ensure that the utility will stop running before the shutdown process completes.
