1<?xml version="1.0" encoding="utf-8"?> 2<html xml:lang="en-US" lang="en-US"> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 5<meta http-equiv="Content-Style-Type" content="text/css" /> 6<link rel="stylesheet" href="../../../css/page.css" type="text/css" /> 7<title>File System: Access Priorities</title> 8<style type="text/css"> 9<!-- 10 strong { color: red; } 11--> 12</style> 13</head> 14<body> 15<h1>File System: Access Priorities</h1> 16 17<h2>Table of Contents</h2> 18 <ul> 19<li><a href="#Summary">Overview</a></li> 20<li><a href="#PriorityKind">Access Priority Types</a></li> 21<li><a href="#SetPriority">Access Priority Settings</a> 22 <ul> 23<li><a href="#SetPriority_FileSystem">File System Priority</a></li> 24<li><a href="#SetPriority_Archive">Archive Priority</a></li> 25<li><a href="#SetPriority_FileStreamDirectory">File Stream Directory Priority</a></li> 26 </ul> 27 </li> 28<li><a href="#Realtime">File Access Requiring Real-Time Performance</a> 29 <ul> 30<li><a href="#Realtime_Restriction">Limitations of Real-Time Priority</a></li> 31<li><a href="#Realtime_AccessTime">Estimating File Access Time</a></li> 32 </ul> 33 </li> 34<li><a href="#Warning">Important</a> 35 <ul> 36<li><a href="#Warning_ThreadPriority">Priority of Threads Calling FS Functions</a></li> 37<li><a href="#Warning_NoAssuranceOfSequence">Sequence of File Access Not Guaranteed</a></li> 38<li><a href="#Warning_SdPerformance">Performance of Accessing Files on SD Card</a></li> 39 </ul> 40 </li> 41<li><a href="#History">Revision History</a></li> 42 </ul> 43 44<h2><a name="Summary">Overview</a></h2> 45 <div class="section"> 46 <p> 47The CTR system supports access priority for the file system. When multiple threads are accessing multiple files, it coordinates the order of execution, giving precedence to the thread configured with the highest priority. 48 </p> 49 <p> 50You can also minimize the latency of file access by configuring real-time priority. This is good when real-time performance is needed (when you need to perform a specific amount of processing every set period), such as for streaming playback. 51 </p> 52 </div> 53 54<h2><a name="PriorityKind">Access Priority Types</a></h2> 55 <div class="section"> 56 <p> 57Three access priorities can be set. They are as follows, from highest to lowest. 58 </p> 59 <p> 60 <ul> 61<li>Real-time priority (<CODE>nn::fs::PRIORITY_APP_REALTIME</CODE>)</li> 62<li>Normal priority (<CODE>nn::fs::PRIORITY_APP_NORMAL</CODE>)</li> 63<li>Low priority (<CODE>nn::fs::PRIORITY_APP_LOW</CODE>)</li> 64 </ul> 65 </p> 66 <p> 67Use normal priority for general file access, such as loading model data and scene data, and accessing save data. Low priority is lower than normal priority. Use low priority for file access that can wait for execution until file access is at a relatively low level, such as auto-save. Real-time priority is a special priority level. Use it when delays in file access would impact the user experience, such as loading streaming data. However, there are some limitations on the use of real-time priority. 68 </p> 69 </div> 70 71<h2><a name="SetPriority">Access Priority Settings</a></h2> 72 <div class="section"> 73 <p> 74Consider the access priority for the following: 75 </p> 76 <p> 77 <ul> 78<li>The entire file system for the application</li> 79<li>Individual archives</li> 80<li>Open file streams and directories</li> 81 </ul> 82 </p> 83 <p> 84You can set the access priority for these by calling the corresponding <CODE>SetPriority</CODE> functions. 85 </p> 86 <p> 87When calling these functions, pass as a parameter one of the constants specified in the <a href="../../../nn/fs/PriorityForApplication.html"><CODE>nn::fs::PriorityForApplication</CODE></a> enumerated type: <span><CODE>nn::fs::PRIORITY_APP_REALTIME</CODE></span>, <span><CODE>nn::fs::PRIORITY_APP_NORMAL</CODE></span>, or <span><CODE>nn::fs::PRIORITY_APP_LOW</CODE></span>. No values other than these constants can be specified. 88 </p> 89 90<h3><a name="SetPriority_FileSystem">File System Overall Priority</a></h3> 91 <div class="section"> 92 <p> 93Use the <a href="../../../nn/fs/SetPriority.html"><CODE>nn::fs::SetPriority</CODE></a> function to set the priority for the entire file system. <br />The priority settings configured here impact the following: 94 </p> 95 <p> 96 <ul> 97<li>Execution priority of <CODE>fs</CODE> functions that do not take a path name (such as the various mount functions, and the <CODE><a href="../../../nn/fs/FormatSaveData.html">nn::fs::FormatSaveData</a></CODE> and <CODE><a href="../../../nn/fs/CreateExtSaveData.html">nn::fs::CreateExtSaveData</a></CODE> functions).</li> 98<li>Initial priority of mounted archives.</li> 99 </ul> 100 </p> 101 <p> 102 103 </p> 104 <p> 105The file system overall has the "normal" priority set by default. 106 </p> 107 </div> 108 109<h3><a name="SetPriority_Archive">Archive Priority</a></h3> 110 <div class="section"> 111 <p> 112Use the <a href="../../../nn/fs/SetArchivePriority.html"><CODE>nn::fs::SetArchivePriority</CODE></a> function to set the priority for individual archives. If this function is not used to explicitly set the priority of an archive, the priority of the file system as a whole is applied when it is mounted. (Changing the priority of the file system as a whole after the archive is mounted will not change the priority of the archive.) <br />The priority settings configured here impact the following: 113 </p> 114 <p> 115 <ul> 116<li>The execution priority of functions that take a path name including the name of the archive (such as the <CODE><a href="../../../nn/fs/CommitSaveData.html">nn::fs::CommitSaveData</a></CODE> function).</li> 117<li>The initial priority of file streams and directories opened with the archive name.</li> 118 </ul> 119 </p> 120 <p> 121 122 </p> 123 </div> 124 125<h3><a name="SetPriority_FileStreamDirectory">File Stream Directory Priority</a></h3> 126 <div class="section"> 127 <p> 128You can set the access priority of file-stream and directory objects using the <CODE>[Try]SetPriority</CODE> member functions of the <CODE><a href="../../../nn/fs/FileStream/Overview.html">FileStream</a></CODE>, <CODE><a href="../../../nn/fs/FileInputStream/Overview.html">FileInputStream</a></CODE>, <CODE><a href="../../../nn/fs/FileOutputStream/Overview.html">FileOutputStream</a></CODE>, and <CODE><a href="../../../nn/fs/Directory/Overview.html">Directory</a></CODE> classes. If none of these functions is used to explicitly set the priority of an object, then the priority of its parent archive is applied when it is initialized. (Changing the priority of the parent archive after the object is initialized does not change the priority of the object.) The priority set here impacts the execution priority of all member functions of the object. 129 </p> 130 <p> 131If you initialize another stream object using the same file path, the priority settings are handled separately. To read the same file using different priorities for separate uses, open the file multiple times and set a separate priority for each object. 132 </p> 133 </div> 134 135 </div> 136 137<h2><a name="Realtime">File Access Requiring Real-Time Performance</a></h2> 138 <div class="section"> 139 <p> 140Some file access requires real-time performance, such as the streaming playback of sound and movies. Although real-time priority should be used for such file access, there are many limitations to take note of. 141 </p> 142 143<h3><a name="Realtime_Restriction">Limitations of Real-Time Priority</a></h3> 144 <div class="section"> 145 <p> 146The system completes file accesses with real-time priority as soon as possible. When the file-access load is heavy, the system gives highest priority to access having real-time priority. It will suspend any previously requested file accesses having lower priority, and give precedence to the file access having real-time priority. (Normal-priority access may also sometimes temporarily suspend low-priority access.) The system will not begin processing requests for file access having lower priority while it is processing a file access operation having real-time priority. (The system handles the suspension of processing and other actions automatically. There is no need to account for this in the program code.) 147 </p> 148 <p> 149Use real-time priority only for operations, such as streaming, that require real-time performance. Excessive access with real-time priority (more than about 1 MB/s on average) could lower the performance of the system as a whole. Use normal or low priority for file access if a certain level of latency is tolerable, such as when there is a temporary fade to black or a loading screen. One example is when switching scenes. 150 </p> 151 <p> 152If you access two or more files at the same time with real-time priority, the process itself will succeed, but it will not be possible to predict performance, because the accesses will interfere with each other.<br /> <strong>Only access one file at a time with real-time priority.</strong> For example, if you stream a movie and sound while reading them from separate files, do not read them from two threads at the same time. Instead, read them alternately (in a single thread, or in two threads using mutual exclusion). 153 </p> 154 <p> 155Priorities other than real time (normal and low) are general and do not represent absolute priority settings. It is possible that a low-priority file access will be executed even if a request for a normal-priority file access is being processed. When the file-access load is extremely heavy, access using normal priority may take considerable time.<br /> <strong>Use real-time priority if you need file access to complete within a specific time.</strong> 156 </p> 157 </div> 158 159<h3><a name="Realtime_AccessTime">Estimating File Access Time</a></h3> 160 <div class="section"> 161 <p> 162The time required for file access is generally calculated as follows: 163 </p> 164 <p> 165 <ul> 166<li>File-access time = overhead time + number of bytes x time per byte = overhead time + number of bytes ÷ speed (excluding overhead)</li> 167 </ul> 168 </p> 169 <p> 170 171 </p> 172 <p> 173Ordinarily, the overhead is relatively low when access has real-time priority, or when using a priority other than real time and there are no other accesses. As an example, the overhead for reading a ROM file of a card application is only about 10 ms or less on average. Due to the way the system is designed, however, the overhead time can occasionally be much longer than usual. To avoid unnecessary issues in your software, use real-time priority when you need real-time performance (such as streaming playback), and allow for worst-case overhead times.<br /> <strong>Do not base the design of file loading functionality that requires real-time responsiveness on measured performance data. </strong> 174 </p> 175 <p> 176The list below provides a rule of thumb for overheads and speed (excluding overhead) for each archive type. Use these values to determine the buffer size and read period for streaming playback. 177 </p> 178 <ul> 179<li>Loading a ROM for card-based software: 200 ms, 5 MB/s</li> 180<li>Loading a ROM for an application on an SD Card: 1,000 ms, 3 MB/s</li> 181<li>Loading add-on content: 1,000 ms, 3 MB/s</li> 182<li>Loading expanded save data: 1,000 ms, 3 MB/s</li> 183<li>Writing expanded save data: 2,000 ms, 0.5 MB/s</li> 184 </ul> 185 <p> 186<B>Note</B>: Do not perform processing requiring real-time performance using archive types other than those listed above. Types other than those listed above may have unexpected overhead, even when using real-time priority. <br />The values above may change in a future firmware update. 187 </p> 188 <p> 189<B>Note</B>: The values above represent the generally expected worst cases. They are not actual measurements. The average measured speeds are faster than those listed. It is fine to design performance using the values listed in the performance tips or other documentation, or using your own performance measurements, if your file access does not require real-time performance (if occasional slowdowns do not present a problem). One such example is loading scenes. 190 </p> 191 <p> 192For example, assume that you must periodically read a movie file with a bitrate of 1 Mbps (128 KB/s) from a ROM file for card-based software. Assuming a buffer size of 32 KB, it will take about 207 ms to read one buffer's worth of data (200 ms + 32 KB ÷ 5 MB/s). Since you only need to make four reads per second (128 KB ÷ 32 KB), it will take 207 ms × 4, which equals 828 ms. You will thus be able to fit all the required reads within one second. If the bitrate is three times higher (3 Mbps, or 384 KB/s), then you would need to make 12 reads of a 32KB buffer per second, which increases the calculation to greater than 2 seconds. It thus would not be possible to read all of the data in one second. If we increase the size of the buffer four-fold, to 128 KB, then it would take 226 ms to read one buffer's worth of data, and we could read all of the needed data in a second using three read operations. The total time would then be 678 ms, which is less than one second. 193 </p> 194 <p> 195This figures refer to the performance of accessing the file system. To estimate actual performance, you must separately estimate the time for any other processing, such as decoding video and audio. File access generally does not take up a great deal of CPU resources. So as long as you can stay within the figures above, you should be able to avoid most issues using, for example, double buffering for loading and processing. However, <strong>you must fully verify overall performance, even if your requirements fit within the range of file-access performance.</strong> 196 </p> 197 </div> 198 199 </div> 200 201<h2><a name="Warning">Important</a></h2> 202 <div class="section"> 203<h3><a name="Warning_ThreadPriority">Priority of Threads Calling FS Functions</a></h3> 204 <div class="section"> 205 <p> 206File-access priority specifies the priority of file-related access processed by the system. It does not regulate the priority of user threads that call <CODE>fs</CODE> functions. Even if you specify high priority for file access, if the priority of the thread that calls the <CODE>fs</CODE> function is low, then it may take a long time for the thread to issue the processing request to the system, and the end of the process could then be delayed. <strong>The priority of the thread calling the <CODE>fs</CODE> function must therefore be high enough for the purpose of the process.</strong>For example, if you are loading a file for audio streaming, before calling the <CODE>fs</CODE> functions, set the access priority to real-time and set the priority of the thread to roughly that of the sound-processing thread. 207 </p> 208 </div> 209<h3><a name="Warning_NoAssuranceOfSequence">Sequence of File Access Not Guaranteed</a></h3> 210 <div class="section"> 211 <p> 212If there are multiple file accesses at the same time, the order of file accesses is not guaranteed, even if real-time priority is used. When possible, the system will process multiple file accesses in parallel. Consequently, it is possible for a low-priority file access that was started after a high-priority file access to finish before the high-priority one. If you will be performing multiple file accesses in parallel, <strong>ensure that your implementation does not depend on the order in which they finish.</strong> 213 </p> 214 </div> 215<h3><a name="Warning_SdPerformance">Performance of Accessing Files on SD Card</a></h3> 216 <div class="section"> 217 <p> 218The performance (throughput and latency) of SD Cards can vary greatly by manufacturer and model number. Your application's performance specifications must allow for this variation in accessing SD Cards. Although the access performance figures for SD Card data listed in <a href="#Realtime_AccessTime">Estimating File Access Time</a> are extremely conservative, <B>use these values to determine the performance specifications for accessing data on an SD Card (when real-time performance is required)</B>. The SD Cards that come with the system have relatively low overhead, so performance specifications based on these could cause problems with other types of SD Cards. <B>Do not design file loading performance based on measured performance data, when you need real-time responsiveness.</B> 219 </p> 220 </div> 221 </div> 222 223<h2><a name="History">Revision History</a></h2> 224 <div class="section"> 225 <dl class="history"> 226 <dt>2011/11/01</dt> 227<dd>Revised wording.</dd> 228 <dt>2011/10/27</dt> 229<dd>Revised figures in <a href="#Realtime_AccessTime">Estimating File Access Time</a>.</dd> 230 <dt>2011/10/18</dt> 231<dd>Revised figures in <a href="#Realtime_AccessTime">Estimating File Access Time</a>.</dd> 232<dd>Added <a href="#Warning_NoAssuranceOfSequence">Sequence of File Access Not Guaranteed</a> section.</dd> 233<dd>Added <a href="#Warning_SdPerformance">Performance of Accessing Files on SD Card</a> section.</dd> 234<dd>Fixed typos and formatting issues.</dd> 235 <dt>2011/10/13</dt> 236<dd>Initial version.</dd> 237 </dl> 238 </div> 239 240<hr><p>CONFIDENTIAL</p></body> 241</html>