Differences

This shows you the differences between two versions of the page.

--- user:rion [2021/09/16 10:46] – [AMD Troubleshooting Tearfree and Freezes] rion
+++ user:rion [2026/06/10 14:45] (current) – rion
@@ Line 1: / Line 1: @@
-<WRAP center round important 90%>
+====== Storage Manager ======
-Under Construction!</WRAP>
-===== Switchres - minimum dot clock =====
+{{toc>}}
-<WRAP center round info 60%>
+> Introduced in **Batocera v43**.
-Most of this information has been gathered from [[https://gitlab.com/groovyarcade/support/-/wikis/3-Post-Installation-and-Maintenance/3.9-Configure-System-Wide-Switchres#minimum-dot-clock|GroovyMame's wiki]].
+Batocera's **Storage Manager** allows you to expand your ROM storage across multiple drives while keeping a single unified game library.
+USB drives, external hard drives, SSDs, SD cards, and additional internal drives can all be used.
+<WRAP tip>
+The Storage Manager introduced in Batocera v43 allows multiple drives to be combined into a single ROM library without requiring symbolic links, manual mounts, or custom scripts.
 </WRAP>
-Fun fact about CRTs: they receive more data than they actually display and keep those extra bits outside of the frame at the top and the bottom. This will be relevant for the next paragraph.
+{{wiki:use_external_storage_system_settings.png?nolink&576|Storage Manager location in System Settings}}
-The dot clock. Essentially, the amount of pixels drawn per second. You can work this out by multiplying your width, your amount of horizontal lines (this is your height, but a bit larger than it) and frames per second. For example, a theoretical resolution of 320x240 at 60 FPS would be calculated by 320x262.5x60, which equals 5,040,000 pixels per second. This is typically measured in MHz (dot clock), but that's confusing so I'm just going to stick with pixels per second (p/s) for the unit and "bandwidth" for the noun.
-The issue with modern graphics cards is that they have a **minimum** required bandwidth to function, anything below that will simply not render (or in some cases, lock up the hardware). Typical minimum bandwidths for these cards are 8 p/s, 12 p/s and 25 p/s. Sometimes the minimum bandwidths will differ depending on which ports are used, digital ports tend to have an even higher minimum bandwidth.
+===== Overview =====
-So what can we do about this? The answer is simple:
-=== Super resolutions ===
+The Storage Manager can:
-CRTs are beautiful in the sense that they don't think in pixels, only lines. So essentially, what we can do is send a **BLOODY HUGE** amount of pixels per line to overcome the minimum required bandwidth for our graphics card. These are what super resolutions are.
+  * Detect compatible storage devices automatically
+  * Merge existing ROM drives
+  * Format and prepare new drives
+  * Use multiple drives simultaneously
+  * Present all ROMs as a single library under ''/userdata/roms''
+  * Safely eject drives
+  * Automatically refresh game lists
-It's typically good practice to use a //multiple// of what the native width of the original system was in order to not have pixels overlapping into other pixels when shrunk down by our CRT. However, we need to practice a bit of caution, as the transistors and other components in a CRT can only handle so much p/s before becoming overloaded and unresponsive, or possibly even damaged!
+From the user's point of view, there is still only one ROM folder:
-So therefore, we will let Switchres calculate the appropriate super resolution for us. It will work out the super resolution that is both a multiple of the original system's width and that satisfies the minimum required bandwidth for our card. A good starting point is 8 million p/s, increasing if that doesn't work for your hardware.
+<code>
+/userdata/roms
+</code>
+Batocera handles the storage pool in the background.
+{{wiki:use_external_storage_storage_overview_diagram.png?nolink&576|Storage Manager overview}}
+A simplified overview:
+<code>
+Internal ROMs
+     │
+Drive 1 /roms
+     │
+Drive 2 /roms
+     │
+  MergerFS
+     │
+/userdata/roms
+</code>
+===== Requirements =====
+A drive must contain a root-level folder named:
+<code>
+roms
+</code>
+Supported:
+<code>
+Drive
+└── roms
+    ├── nes
+    ├── snes
+    └── psx
+</code>
+Not supported:
+<code>
+Drive
+└── Batocera
+    └── roms
+</code>
+Not supported:
+<code>
+Drive
+├── nes
+├── snes
+└── psx
+</code>
+The Storage Manager currently expects the ''roms'' folder to exist directly in the root of the mounted drive.
+===== Using Existing Drives =====
+When Batocera detects a mounted drive containing a compatible root-level ''roms'' folder, it offers to merge the drive into the Storage Manager.
+{{wiki:use_external_storage_merge_existing_drive_prompt.png?nolink&576|Merge existing drive prompt}}
+After accepting the prompt, Batocera adds the drive to the storage pool.
+{{wiki:use_external_storage_merge_existing_drive_complete.png?nolink&576|Merge complete}}
+After the merge completes, the ROMs stored on the drive become available alongside your existing collection.
+===== Formatting a New Drive =====
-Here's an example: let's say you're playing a game that runs at a native 640x480 at 60 FPS. Our graphics card has a minimum required bandwidth of 25 Mp/s. The bandwidth of that is calculated by 640x480x60 = 18,432,000 p/s. This is close to the required 25 Mp/s but not quite. Switchres calculates our super resolution as 1280x480, as 1280 is a //multiple// of 640 and the total bandwidth is 1280x480x60 = 36,864,000 p/s. This is well above our required minimum, and thus suited for our purposes.
+If a blank drive is detected, Batocera can automatically prepare it for game storage.
-Same goes for any other modeline, like for 256x224 it would calculate 512x224x60, 768x224x60 and so on until it meets the minimum required bandwidth (dot clock) set in the INI.
+{{wiki:use_external_storage_format_new_drive_prompt.png?nolink&576|Format and merge prompt}}
-<WRAP center round tip 60%>
+<WRAP important>
-Super resolutions are only supported by MAME and Libretro cores.
+Formatting a drive will permanently erase all existing data stored on that drive. Make sure any important files have been backed up before proceeding.
 </WRAP>
-===== Testing modelines =====
-{{:user:crt_switchres_grid_test_example.jpg?200|}}
+Selecting **Format & Merge** will format the drive and add it to the Storage Manager.
-configure switchres.ini to your monitor (WinScp)
+{{wiki:use_external_storage_format_confirmation.png?nolink&576|Format confirmation}}
-Connect to Batocera via SSH
+Batocera will:
-Have a keyboard connected
+  * Format the drive
+  * Create a root-level ''roms'' folder
+  * Generate the standard ROM directory structure
+  * Merge the drive into the Storage Manager
+  * Refresh the game lists
+{{wiki:use_external_storage_formatting_drive.png?nolink&576|Formatting drive}}
+===== Using Multiple Drives =====
+Multiple drives can be used simultaneously.
+Example:
-Exit Emulation Station
 <code>
-/etc/init.d/S31emulationstation stop
+/media/roms1/roms
+/media/roms2/roms
 </code>
-or
+Batocera combines them into a single virtual library:
-Exit to terminal
+<code>
-''ctrl+alt+f3''
+/userdata/roms
+</code>
+Games can be distributed across multiple drives while still appearing as one collection inside EmulationStation.
+===== Internal Drives =====
+The Storage Manager is not limited to removable USB devices.
+Additional internal drives can also be used.
+For example:
-From putty type for this to test modeline 640x480@60 with configured monitor profile
 <code>
-DISPLAY=:0 switchres 640 480 60 -i switchres.ini -s -l grid
+/media/roms1/roms
+/media/roms2/roms
 </code>
-You can change between 2 types of grids with Tab.
-Exit pressing Escape from keyboard to try a new modeline
+As long as the drive is mounted by Batocera and contains a root-level ''roms'' folder, it can be merged into the Storage Manager.
+This includes:
+  * SATA hard drives
+  * SATA SSDs
+  * NVMe SSDs
+  * USB storage devices
+  * SD cards
+<WRAP info>
+The drive name does not matter. What matters is that the mounted drive contains a root-level ''roms'' folder.
+</WRAP>
+===== Safe Drive Removal =====
+Drives can be safely removed from:
+  * **Main Menu**
+  * **System Settings**
+  * **Eject an Extra Disk**
+{{wiki:use_external_storage_safe_eject_menu.png?nolink&576|Safe eject menu}}
+After selecting the drive, Batocera asks for confirmation before removing it from the storage pool.
+{{wiki:use_external_storage_safe_eject_confirmation.png?nolink&576|Eject confirmation}}
+Batocera automatically updates the storage pool and refreshes the game lists.
+{{wiki:use_external_storage_drive_ejected.png?nolink&576|Drive ejected}}
+Games stored only on the removed drive will disappear from the library until that drive is connected and merged again.
+===== What Gets Merged? =====
+Only the ROM library is merged:
-Go back to Es with command
 <code>
-/etc/init.d/S31emulationstation start
+/userdata/roms
 </code>
-or restart with
+Folders such as:
 <code>
-reboot
+/userdata/bios
+/userdata/saves
+/userdata/screenshots
+/userdata/themes
+/userdata/music
 </code>
-Modelines to test your switchres.ini settings with
-<code>dotclock_min 0 (Default) 0-25 with decimal support 1.1, 8.3, 10.5 and so on</code>
-[[https://gitlab.com/groovyarcade/support/-/wikis/4-Issues-and-Troubleshooting/4.4-Video-Mode-Troubleshooting/15kHz-Horizontal-Arcade-Games|Arcade Modelines]]
+remain on internal storage.
+The Storage Manager does not merge BIOS files, save files, screenshots, themes, or music.
+===== Internal ROM Preservation =====
+When the first additional ROM drive is merged, Batocera preserves the existing internal ROM collection.
+Internally, existing ROMs stored in:
-For example the Arcade game Dottori Kun ([[http://adb.arcadeitalia.net/dettaglio_mame.php?game_name=dotrikun&arcade_only=0&autosearch=1|dotrikun]])
 <code>
-DISPLAY=:0 switchres 128 192 61.035156 -i switchres.ini -s -l grid
+/userdata/roms
 </code>
-===== AMD Troubleshooting Tearfree and Freezes =====
+are moved into:
+<code>
+/userdata/.roms_base
+</code>
-If you get uneven frame-pacing and microstutters in Mame and/or Retroarch we need to disable the option **TearFree** in the driver configuration file located at
+This allows internal ROMs to remain visible alongside ROMs stored on merged drives.
-''/etc/X11/xorg.conf.d''
+If all merged drives are later removed, Batocera restores the internal ROM library back to the normal ''/userdata/roms'' location.
+===== Limitations =====
+The Storage Manager currently requires this layout:
-  * 20-amdgpu.conf (GCN 3, GCN 4, GCN 5, RDNA & RDNA 2) or download an already fixed [[https://drive.google.com/file/d/1pzJYwK1uUv-eXdOXmkwAW36iVnNVsVnV/view?usp=sharing|20-amdgpu.conf]]
 <code>
-Section "OutputClass"
+<drive>/roms
-     Identifier "Fix AMD Tearing"
-     Driver "amdgpu"
-     MatchDriver "amdgpu"
-     Option "TearFree" "false"
-EndSection
 </code>
-  * 20-radeon.conf (TeraScale and older, GCN 1 & GCN 2) or download an already fixed [[https://drive.google.com/file/d/1iMUUNk6z8i9tPAxHgRFTax4_9OlG6leG/view?usp=sharing|20-radeon.conf]]
+Nested ROM folders are not detected automatically.
+Example:
 <code>
-Section "OutputClass"
+<drive>/Batocera/roms
-     Identifier "Fix AMD Radeon Tearing"
-     Driver "radeon"
-     MatchDriver "radeon"
-     Option "TearFree" "false"
-EndSection
 </code>
-Don't forget to ''batocera-save-overlay'' and reboot.
+is not automatically merged.
-**Games freeze or EmulationStation freeze.**
+Only the ROM library is merged. Other userdata folders remain independent.
-This has been reported by some users and myself included.
+===== Advanced Technical Details =====
-It's not know yet what is the underlying reason. It could be a driver or kernel issue.
-We need to add **Option "DRI" "2" & 3** in the driver configuration file located  at
+Batocera uses **MergerFS** to combine ROM folders from multiple drives into a single virtual directory.
-''/etc/X11/xorg.conf.d''
-  * 20-amdgpu.conf (GCN 3, GCN 4, GCN 5, RDNA & RDNA 2) or download an already fixed [[https://drive.google.com/file/d/1HkysjCg8eq-_Dk6rmPxutRDDtiBOJXhD/view?usp=sharing|20-amdgpu.conf]]
+The merged library is presented at:
 <code>
-Section "OutputClass"
+/userdata/roms
-     Identifier "Fix AMD Tearing"
-     Driver "amdgpu"
-     MatchDriver "amdgpu"
-     Option "TearFree" "false"
-     Option "DRI" "3"
-EndSection
 </code>
-  * 20-radeon.conf (TeraScale and older, GCN 1 & GCN 2) or download an already fixed [[https://drive.google.com/file/d/1-201t3Q0WLrS4iij_FOzGkQXJT0XEJBx/view?usp=sharing|20-radeon.conf]]
+Internally, Batocera maintains a storage pool containing:
 <code>
-Section "OutputClass"
+/userdata/.roms_base
-     Identifier "Fix AMD Radeon Tearing"
-     Driver "radeon"
-     MatchDriver "radeon"
-     Option "TearFree" "false"
-     Option "DRI" "2"
-EndSection
 </code>
-Don't forget to ''batocera-save-overlay'' and reboot.
+plus any merged ROM folders.
-  * Short explanation of expression mentioned here
+Example:
+<code>
+/userdata/.roms_base
+/media/roms1/roms
+/media/roms2/roms
+</code>
+These locations are combined into:
+<code>
+/userdata/roms
+</code>
+==== MergerFS File Placement Policy ====
+Batocera currently uses the following MergerFS create policy:
+<code>
+category.create=eplfs
+moveonenospc=true
+minfreespace=4G
+</code>
+**eplfs** means:
+<code>
+Existing Path, Least Free Space
+</code>
+When writing a new file:
+  * MergerFS looks for branches where the target folder already exists
+  * Among those branches, the branch with the least free space is preferred
+  * Branches with less than 4 GB free are ignored
+  * If a drive becomes full during a write operation, the file can automatically move to another branch
+Example:
+<code>
+/media/roms1/roms/nes   900 GB free
+/media/roms2/roms/nes   200 GB free
+</code>
+A new ROM copied into:
+<code>
+/userdata/roms/nes
+</code>
+would be stored on:
+<code>
+/media/roms2/roms/nes
+</code>
+because it has the least free space while still meeting the minimum free space requirement.
+<WRAP important>
+The MergerFS implementation and file placement policy may change between Batocera releases. This section reflects the behavior introduced with Batocera v43.
+</WRAP>
+===== Frequently Asked Questions =====
+==== Can I use internal drives? ====
+Yes. Any drive mounted by Batocera containing a root-level ''roms'' folder can be merged into the Storage Manager.
+Example:
+<code>
+/media/roms1/roms
+/media/roms2/roms
+</code>
+==== What happens if I unplug a merged drive? ====
+Batocera updates the storage pool and refreshes the game lists.
+Games stored only on the disconnected drive will temporarily disappear until the drive is connected again.
+==== Are BIOS files merged? ====
+No.
+Only:
+<code>
+/userdata/roms
+</code>
+is merged.
+BIOS files remain stored in:
+<code>
+/userdata/bios
+</code>
+==== Are saves merged? ====
+No.
+Save files remain stored in the normal userdata location, for example:
+<code>
+/userdata/saves
+</code>
+==== Can I store ROMs in a different folder? ====
+No.
+The Storage Manager currently expects a root-level folder named:
+<code>
+roms
+</code>
+==== Does the drive name matter? ====
+No.
+For example, both of these are valid if they contain a root-level ''roms'' folder:
+<code>
+/media/roms1/roms
+/media/MyGamesDrive/roms
+</code>
-//TearFree is a tearing prevention option which prevents tearing by using the hardware page flipping mechanism//
+===== References =====
-//Microstutter short irregular frame dips//
+  * Batocera TV — ''Batocera 43 - Episode II''
+    * Storage Manager demonstration:
+      * https://youtu.be/XpH27Yswe38?t=143
-//Frame-pacing uneven distribution of frames//
+  * Batocera Storage Manager source code:
+    * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-scripts/scripts/batocera-storage-manager