Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
user:rion [2024/11/30 15:05] – created rionuser:rion [2026/10/05 12:04] (current) – rion
Line 1: Line 1:
-Work in progress on updated CRT guide... +====== Storage Manager ======
  
 +{{toc>}}
  
-====== Batocera native CRT output ======+> Introduced in **Batocera v43**.
  
-<WRAP center round alert> +Batocera's **Storage Manager** allows you to expand your ROM storage across multiple drives while keeping a single unified game library. 
-[[https://github.com/ZFEbHVUE/Batocera-CRT-Script|An automated script]] has been developed which shall be used to configure and activate CRT capabilities for the latest x86_64 Batocera version. Use it after reading through this guide at least once to understand its usage.+ 
 +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 locally attached drives to be combined into a single ROM library without requiring symbolic links, manual mounts, or custom scripts. 
 + 
 +Advanced network/NAS and manual MergerFS setups are documented later on this page, after the Storage Manager limitations. Most users with locally attached storage do not need that configuration.
 </WRAP> </WRAP>
  
 +{{wiki:use_external_storage_system_settings.png?nolink&576|Storage Manager location in System Settings}}
  
-<WRAP center round info> + 
-This guide only applies to Batocera **v32** on the x86_64. [[:batocera-and-crt-rpi|CRT on Raspberry Pi]] has its own page. For **v30**/**v31** and on x86, refer to the [[:batocera-and-crt-old|legacy guide]]. This article is also not for the faint of heart. Word-count: about 9k.+===== Overview ===== 
 + 
 +    
 + 
 +The Storage Manager can: 
 + 
 +  * 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 
 + 
 +From the user's point of view, there is still only one ROM folder: 
 + 
 +<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 ===== 
 + 
 +For drives detected and managed automatically by the Storage Manager user interface, the 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 user interface currently expects the ''roms'' folder to exist directly in the root of the mounted drive. 
 + 
 +<WRAP info> 
 +This root-level folder requirement applies to automatic Storage Manager detection. Advanced manual MergerFS pools can use other mounted directory paths, including nested local folders and network shares.
 </WRAP> </WRAP>
  
-Batocera has the capability to natively output an analogue signal, should you have the hardware to do so. The specifics are later in this guide, but that basically means you have a VGA/DVI-I port on your graphics card (which is becoming exceedingly rare with modern graphics cards) or on your motherboard (the CPU will need integrated graphics to support it and must not have a DAC altering the signal, probably along with particular BIOS settings). Modern cards with only digital outputs have a minimum bandwidth that's above the acceptable rate that CRTs can interpret, and thus won't be compatible for use in this guide.+==== Existing disk layout and filesystems ==== 
 + 
 +Automatic Storage Manager detection is not limited to disks that have a conventional partition table. The current backend handles both of these cases: 
 + 
 +  * A partitioned disk, where each partition is detected and mounted separately 
 +  * A whole disk containing a filesystem directly, with no partition table, which can be mounted as a raw filesystem 
 + 
 +In either case, automatic merging still requires a ''roms'' directory at the root of the mounted filesystem. 
 + 
 +An existing partition that has no recognizable filesystem is **not** treated the same way as a completely blank disk. The automatic **Format & Merge** prompt is generated by the whole-disk empty-disk path after Batocera has checked for a partition table, partitions and a raw filesystem. Therefore, a disk containing an unusable or unformatted partition may need to be repartitioned or formatted separately before Storage Manager can use it. 
 + 
 +===== 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 ===== 
 + 
 +  
 + 
 +If a blank drive is detected, Batocera can automatically prepare it for game storage. 
 + 
 +{{wiki:use_external_storage_format_new_drive_prompt.png?nolink&576|Format and merge prompt}}
  
-<WRAP center round tip> +<WRAP important> 
-You can however use an active converter ([[#glossary|glossary below]]) to convert a digital signal to an analogue one (this will not be native) to use such digital-only graphics cards with a CRT display, however this guide is solely for running the pure analogue signal from the card to your display and the configurations made in this guide will not be compatible with such converters.+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> </WRAP>
  
-Recommended watching: +
-  * [[https://www.youtube.com/watch?v=zwDPx6hP_4Y|Displaced Gamers' excellent video on the history of 240p]] - This explains the background of the "240p" signal common with early generation consoles and why "scanlines" were a thing.+
  
-Recommended reading: +Selecting **Format & Merge** will format the drive and add it to the Storage Manager.
-  * [[https://www.retrorgb.com/rgbguide.html|RetroRGB's RGB guide]] - This focuses more on the aspect of connecting your physical analogue consoles to modern displays, but it covers much of the terminology used throughout this guide and explains particular details about analogue standards. +
-  * [[https://www.aussiearcade.com/topic/76809-a-guide-to-connecting-your-windows-pc-to-an-sd-crt-tv-pvm-or-arcade-monitor/|buttersoft's AussieArcade forum post: A guide to connecting your Windows PC to an SD CRT TV, PVM or Arcade Monitor]] - This focuses more on connecting Windows computers to CRT displays, but it goes over a lot of the same things we will have to later on. This is a very technical document, more so than this guide is.+
  
-===== Foreword =====+{{wiki:use_external_storage_format_confirmation.png?nolink&576|Format confirmation}}
  
-<WRAP center round alert> +Batocera will: 
-It should go without saying, but unlike digital signals, analogue signals and the devices that receive them tend not to have safety limitations on what they are capable of. This can result in breaking displays, blowing old fuses, overheating ancient capacitors, making things catch fire, etc. You should perform adequate research before attempting any of this with your old equipment. Although this guide has safety precautions built into it, the safety of you and your equipment is solely your own responsibility.+ 
 +  * 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}} 
 + 
 +==== Filesystem choices and what formatting does ==== 
 + 
 +The Storage Manager delegates disk formatting to ''batocera-format''. In the implementation documented here, the available format types are: 
 + 
 +<code> 
 +ext4 
 +btrfs 
 +exfat 
 +</code> 
 + 
 +If no filesystem type is supplied to the backend, ''ext4'' is the default. 
 + 
 +<WRAP important> 
 +Formatting operates on the **whole selected disk**, not only on an existing partition. Batocera erases the beginning of the disk, creates a new GPT partition table, creates one partition using the disk, formats it, and labels the new filesystem ''ROMS''. All existing partitions and data on that disk can therefore be lost.
 </WRAP> </WRAP>
  
-This guide would not have been possible without the following people to name a few: +After formatting, Batocera creates the root-level ''roms'' directory. It then copies the **directory structure only** from the existing ROM library to the new drive before merging it. Existing ROM files are not duplicated to the newly formatted drive by this step.
-  * jfroco's work to output Batocera on a CRTs. +
-  * rtissera's knowledge, enthusiasm and willingness to add 15 KHz patches. +
-  * Calamity for his knowledge, drivers, tools, GroovyMame, Switchres, etc. +
-  * Substring's work on GroovyArcade, SDL, KMS, etc.    +
-  * D0023R Doozer's continued work at adding 15 KHz support to the Linux kernel. +
-  * dmanlcf's work on keeping the 15 Khz patches up to date for Batocera. +
-  * Rion and Atari for compiling this guide.+
  
-===== Glossary =====+Existing drives do not need to use one of the three formatting choices above if Batocera can already mount their filesystem. NTFS, for example, has explicit mount handling in the Storage Manager, but NTFS is not offered by ''batocera-format'' as a format target in this implementation.
  
-The field of analog signals and CRT-related standards is very complex and occasionally misleading. We won't dive into every aspect in this guide but we will explain some relevant terms here (sorted in alphabetical order) to avoid confusion. Feel free to come back to this section at any time throughout this guide:+For an existing NTFS filesystem, Storage Manager currently runs ''ntfsfix -d'' first, then tries the kernel ''ntfs3'' driver. If that mount fails, it falls back to ''ntfs-3g''. Other recognized filesystems are normally mounted using the filesystem detected by ''blkid'' with ''noatime''.
  
-  * **Active converters** Little boxes that convert one signal to another. These use tiny computers with processors and RAM to process the image digitally and send it out the other side as appropriate. Generally undesirable, as they can introduce lag and other artifacts. This is not considered "native". This guide assumes that you are **NOT** using one of these (as they try to handle the entire conversion themselves, removing Batocera's control over the signal).{{ hardware:at-hd420s_1600x742.jpg?nolink&540 |Box-like in shape, usually require powered input as well (but not always).}} +The backend also independently refuses a format request if the selected device resolves to Batocera's system disk. When formatting proceeds, ''batocera-format'' creates one GPT partition beginning at 2 MiB and extending to the end of the disk.
-  * **BNC cables** These are standard aerial coaxial cords that can carry any analogue signal. For our purposes, they will be carrying an RGB video signal. There were not many consumer TVs that utilized this type of connection, but they were common with professional/broadcast reference monitors (PVM/BVM for short). You'll usually need to find a specific passive adapter that has the correct //amount// of BNC cables for your given PVM/BVM.{{ hardware:vga-5bnc-cable.gif?nolink |VGA to 5 BNC passive adapter. Professionals only.}} +
-  * **Component video cables** The three red blue green cable connection. Not to be confused with the similarly spelled composite cable, as it uses three cables instead of one. Not to be confused with RGB signal, as this uses a YPbPr signal. Them being colored red blue and green is purely coincidental and not related to RGB at all.{{ hardware:330px-component-cables.jpg?nolink&300 |The three component cables. A cable spaghetti waiting to happen.}} +
-  * **Composite signal** An //analogue// signal. The act of sending both luminance and color channels down a single wire. Utilized by the composite video cable. +
-  * **Composite video cable** The yellow cable. That's enough, you know what I'm talking about already.{{ hardware:450px-composite-video-cable.jpg?nolink&200 |I miss this little guy like you wouldn't believe.}} +
-  * **DisplayPort** The modern digital video connection port, common on modern graphics cards. Compatible with both DP and HDMI signals. This port cannot be used to send a native analogue signals so it is not recommended for use with CRT, but this can be worked around if you have the right equipment as explained further on in the guide. +
-  * **DVI-I port** This is the 29 pin port in your graphics card, capable of analogue signals. You will typically find this port alongside the VGA port. Newer cards no longer include this port. It is of extreme importance to not confuse this with the identical-looking DVI-**D** port, which is only capable of digital signals. The DVI-I port has additional pins above and below the flat tongue, whereas DVI-D doesn't. DVI-A would also work, but that is exceptionally rare.{{ hardware:459px-dvi_connector_types.svg.png?200 |Diagram showing all the DVI connections.}} +
-  * **EDID** Extended Display Identification Data (EDID) is a //digital// metadata signal used by display devices to describe their capabilities to a video source (in this case, your Batocera computer). Modern digital displays all have this, and Batocera uses that to automatically switch to a compatible resolution. Certain VGA-compatible CRT monitors also use this, but not all of them. This standard was introduced in 1994, so monitors manufactured before then do **not** have EDID. +
-  * **Horizontal scan rate** Usually expressed in kilohertz. This is the number of times per second that a horizontal line is drawn on a display, as opposed to vertical refresh rate which is the number of times per second that an entire screen of image data is displayed. +
-  * **Passive adapter/cables** These are simple cables that adapt one interface to another. They don't involve any circuitry, all the work is done by the machine sending out the signal. Passive cables can only go analogue-to-analogue or digital-to-digital, not analogue-to-digital or digital-to-analogue.{{ hardware:vga-to-component.jpg?nolink&300 |Plain and simple wires.}} +
-  * **RGB video signal** In this context, refers to the //analogue// signal that has an individual channel for each Red, Blue and Green color signal. RGB is not compatible with component/composite/S-video by default, and a transcoder must be used to switch between the signals, but they otherwise are all analogue signals. +
-  * **SCART** This is the 21 pin port that superseded the standard composite video output. Popular in Europe and Japan, but not many other places. Carries both analog video and audio signals. Natively uses an RGB video signal, but is backwards compatible with YPbPr, composite and S-video signals.{{ hardware:450px-scart_20050724_002.jpg?nolink&200 |The fat SCART connector. Most people missed out on its majesty.}} +
-  * **S-video port** A slightly better version of composite video. This separated the color and luminance signals into two separate wires each, reducing color bleed and artifacts, but in practice the difference wasn't that significant. Common with DVD players, but not much else.{{ hardware:450px-close-up_of_s-video_female_connector.jpg?nolink&200 |The 4 pin S-video connector.}} +
-  * **S-video signal** An //analogue// signal. Essentially the exact same signal as a composite signal, but the color and luminance signals are separated. Trivial to switch between this and composite hardware-wise, but ultimately the device needs to understand what type of signal it's receiving to properly display it. +
-  * **RF modulator** This is a device that can translate composite, component or RGB analogue signals into a radio frequency. This is required for CRT displays that only have an RF input. VCRs usually had one of these built-in to them, and make for a fine substitute.{{ hardware:rf_modulator.jpeg?nolink&240 |This RF modulator converts composite to RF.}} +
-  * **Three-pole A/V composite cable** A more modern analogue signal cable which violates standards by running a video signal through a 3.5mm headphone jack splitting into RCA cables. This is specifically designed to be used in the Raspberry Pi in its composite video modes, and will not be compatible with other devices/computers. Is only capable of carrying a composite signal, the other plugs are strictly for audio.{{ :three_pole_cable.jpg?nolink&240 |Could also just use it to play your (old) phone on a hi-fi system.}} +
-  * **Transcoder** A device that can convert an RGB signal into an inferior signal like component/composite/S-video or back. Usually requires its own power source to function, but isn't an active converter (no CPU is involved processing the image).{{ hardware:rgb-to-pybyr-transcoder-back.jpg?nolink&240 |A little square box.}} +
-  * **Vertical refresh rate** The number you're probably more familiar with, typically measured in just hertz. This is the number of full frames drawn per second. Typically this is 60 Hz for all modern displays, but older CRTs were split between 60 Hz and 50 Hz depending on where you lived. +
-  * **VGA port** This is the 15 pin port ubiquitous with old computer video output and classroom projectors. It is important to note the distinction between a VGA signal and the DSUB connector used to carry that signal, as not all DSUB connectors actually send a VGA signal. Refer to this console-related [[http://origin.retrorgb.com/vgaconnector.html|article on RetroRGB]] about it for more info. Essentially, a DSUB port is capable of sending out either an RGB or VGA signal, given the right settings.{{ hardware:vgaconnector-02.jpg?400 |A diagram showing how the pinout of an RGB signal differs from a VGA signal, despite them both using the DSUB 15 pin port.}} +
-  * **VGA signal** A unique hybrid //digital/analogue// signal. This became the standard for computer monitors in the late 80s/early 90s, and became **the** video standard for most devices. Although this signal has slowly begun being phased out, it's still compatible with pretty much every display ever created since its inception (if you can get a port hooked up to the display's interface that is). While the VGA signal itself is analogue, it was designed specifically for computer monitors and relies on digital signalling features absent from most consumer TVs. As such, the signal cannot be transcoded into other analogue video signals without highly specialized hardware. This is outside of the scope of this article, but assuming you can get it all working then you can still apply the later sections of this guide like ES scaling. Unlike other analogue signals, VGA utilizes an EDID to notify the machine of its resolution capabilities, so therefore it cannot be configured in the same manner as described in this guide; instead use the [[:display_issues#how_does_that_work_under_the_hood|general method for changing resolution]]. +
-  * **YPbPr video signal** A lower-bandwidth form of RGB, which has both the green and luminance channels on one wire. Used by component video cables, but can also be sent through a SCART connection.+
  
-===== Prerequisites =====+===== Using Multiple Drives =====
  
-To achieve a native analogue signal on your setup, the following elements are needed:+Multiple drives can be used simultaneously.
  
-  * A network connection (wired is preferred, as it needs no configuration) +Example: 
-  * For x86_64: + 
-    * A graphics card or integrated graphics with RGB analogue output +<code> 
-      * **AMD**/**ATI** graphics cards with **VGA** or **DVI-I** ports (preferred, **Radeon HD 3000** series and up to **Radeon R5**/**R7**/**R9 300**), these cards are: +/media/roms1/roms 
-        * **Radeon RX** up to the **300** series (excluding the **R9 390**) (**R9 380X** is the newest and most powerful AMD card supporting analogue) +/media/roms2/roms 
-        * **Workstation** up to the **FirePro W5000** +</code> 
-      * **Nvidia** graphics cards with **VGA** or **DVI-I** ports (major flaws and limited to Super Resolutions, cards made before 2008 may not have these limitations), these cards are: + 
-        * **GTX** up to the **900** series cards (**980** is the recommended card to use) <WRAP center round tip> +Batocera combines them into a single virtual library: 
-Cards older than the **GTX 600** series may not be supported by the official Nvidia drivers, though performance with 5th gen systems and below is adequate with the nouveau drivers.+ 
 +<code> 
 +/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: 
 + 
 +<code> 
 +/media/roms1/roms 
 +/media/roms2/roms 
 +</code> 
 + 
 +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> </WRAP>
-        * **Titan** cards up to the **Titan X** (but excluding **Titan X Pascal**) (**Titan X** is the most powerful card supporting analogue) 
-        * **Quadro** cards up to the **Quadro K5200** 
-      * **Nvidia** graphics card with **DisplayPort** (no native analog signal, requires disabling low-level driver limitations which are potentially dangerous, requires additional ratnest of cables): 
-        * If opting to go this route, an active converter or the CableDeconn DP to VGA adapter will be required. In general, this is not recommended as it is not a native analogue signal. 
-        * A transcoder will still be required. 
-      * **AMD** APUs with **VGA** or **DVI-I** ports on the motherboard (hit or miss, highly dependent on hardware limitations, older chips have a higher chance of working) 
-      * **Intel** integrated graphics with **VGA** or **DVI-I** ports on the motherboard (has some flaws and limitations, older chips have a higher chance of working) 
-    * If using a TV/PVM/BVM with **SCART**/**BNC** inputs, the appropriate **DVI-I**/**VGA** RGB to **SCART**/**BNC** RGB passive adapter/cable 
-    * If using a computer monitor with **VGA** input, simply a **VGA** cable 
-    * If using a TV with **component**/**composite**/**S-video** inputs, an appropriate **DVI-I**/**VGA** RGB to **component**/**composite**/**S-video** transcoder 
-      * If using a TV that only has **RF** input, you will need a **composite** to **RF** modulator in addition to the transcoder 
-  * A way to [[:access_the_batocera_via_ssh|SSH into the Batocera machine]] (for Windows, PuTTY works fine) 
-  * A way to edit files over the network (for Windows, WinScp and Notepad++ work fine) 
  
-<WRAP center round tip> +==== Automatic detection and safety filtering ==== 
-It is highly recommended using an external editor like [[http://notepad-plus-plus.org/|Notepad++]] and [[https://winscp.net/|WinScp]] for editing, as they are easier to use than command line tools and respect Unix line terminators (unlike Windows Notepad).+ 
 +The Storage Manager backend watches the common Linux block-device families used by Batocera, including ''sdX'', NVMe and MMC devices. Its explicit initial-scan and ignore re-detection loops enumerate those device families, so unusual block-device classes are better handled through the manual storage mechanisms unless they are known to trigger the Storage Manager through another Batocera path. The backend also contains several safety filters intended to avoid treating system, firmware and recovery storage as game disks. 
 + 
 +Among other checks, the current implementation: 
 + 
 +  * Skips the disk backing ''/boot'' or ''/userdata'' 
 +  * Skips EFI System, Microsoft Reserved and Windows Recovery partition GUIDs 
 +  * Skips partitions marked hidden or no-automount 
 +  * Filters many Android/Qualcomm firmware and system partition labels 
 +  * Does not offer the automatic blank-disk format prompt for disks of 4 GiB or smaller 
 +  * Ignores swap partitions 
 +  * Skips local disks already claimed by UUID-based ''sharedevice...'' manual configuration 
 + 
 +These checks are safeguards, not a substitute for verifying the disk shown by a format prompt. Always confirm the device and capacity before formatting. 
 + 
 +<WRAP info> 
 +Some of the protection checks intentionally use broad filesystem-label and partition-label matches. External media using names associated with system partitions, for example ''userdata'', ''recovery'', ''vendor'' or ''persist'', can therefore be skipped by automatic detection. If a perfectly usable external partition does not appear in Storage Manager, its filesystem label and partition label are worth checking in ''/var/log/batocera-storage.log''.
 </WRAP> </WRAP>
  
-If any of that was confusing here's a professional-grade flowchart explaining what is required for each type of display (on PC):+==== Ignoring a drive ====
  
-{{ hardware:tree-diagram-explaining-this.png |Two billion hours in mspaint.exe}}+The Storage Manager backend supports an ''ignore.drives'' list in ''/boot/batocera-boot.conf''. Ignoring a drive disables Storage Manager automation for that drive. It does not necessarily prevent Batocera from mounting a readable partition.
  
-===== Component Transcoders =====+If an ignored drive contains a root-level ''roms'' directory, the drive can remain mounted under ''/media'', but Storage Manager will skip adding it to the ROM pool or prompting to merge it. Blank ignored drives also do not trigger the format prompt.
  
-Some appropriate VGA-to-component adapters:+The ignore entry is based on a persistent **whole-disk** identifier when one is available, rather than only on a temporary ''/dev/sdX'' name. In practice, ignoring a physical disk disables Storage Manager automation for its partitions as well.
  
-RGB VGA to YPbPr Component transcoder/converter by linuxbot3000+The current backend provides an ''ignore'' action but no matching ''unignore'' action. The persistent state is simply the space-separated ''ignore.drives'' value in ''/boot/batocera-boot.conf''. To reverse an ignore, that stored identifier has to be removed from the configuration and the drive re-detected, reconnected or detected again after a reboot.
  
-  * [[https://www.ebay.com/itm/174166352619]] +==== Mount-point naming ====
-  * [[http://wakabavideo.com/|homepage]] +
-{{hardware:rgb-to-pybyr-transcoder.jpg?240}} {{hardware:rgb-to-pybyr-transcoder-back.jpg?240}}+
  
-GreenAntz RGB to component transcoder+For automatically mounted partitions, Storage Manager builds a mount point under ''/media''. If the filesystem has a label, the sanitized label is used; otherwise the partition device name is used. If that mount point already exists, a numeric suffix such as ''_1'' is added.
  
-{{hardware:greenantz-transcoder.jpg?240}} +<WRAP tip> 
-  * [[http://forum.arcadecontrols.com/index.php/topic,164245.0.html]] +Use unique filesystem labels for ROM drives. The Storage Manager configuration stores branch paths such as ''/media/MyDrive/roms''. Duplicate labels can produce suffixed mount points and make path identity less predictable across reconnects. 
-  * [[https://www.facebook.com/groups/444560212348840/permalink/1992573517547494/?mibextid=rS40aB7S9Ucbxw6v]]+</WRAP>
  
-Retrotink RGB2COMP (Scart to Component)+===== Safe Drive Removal =====
  
-{{hardware:rgb2comp.jpg?300|}} +
-  * [[https://www.retrotink.com/product-page/rgb2comp]]+
  
-RGBS VGA SCART to YPBPR Component Transcoder +Drives can be safely removed from:
-   +
-{{hardware:rgbs_vga_scart_to_ypbpr_component_transcoder_1.jpg?240}} +
-{{hardware:rgbs_vga_scart_to_ypbpr_component_transcoder_2.jpg?240}}   +
-  * [[https://www.aliexpress.com/item/502689543.html]]+
  
-<WRAP center round info> +  * **Main Menu** 
-Color coding is a little different on this +  * **System Settings** 
-  * Green -> Pb +  * **Eject an Extra Disk** 
-  * Red -> Y + 
-  * Blue -> Pr+{{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. 
 + 
 +The **Eject an Extra Disk** list is generated from branches saved in ''mergerfs.roms''. It is therefore a list of drives currently managed as Storage Manager pool branches, not a generic eject list for every filesystem mounted under ''/media''. 
 + 
 +<WRAP important> 
 +Prefer the Storage Manager eject action over physically unplugging a drive while Batocera is running. The backend has cleanup logic for an unexpected removal, but active writes cannot be made safe after the device has already disappeared.
 </WRAP> </WRAP>
  
-RGBS / SCART to YCBCR / YPBPR / S-Video converter adapter+==== Missing at boot, safe eject, and live unplug are different ====
  
-{{hardware:rgbs-scart-a-ycbcr-ypbpr-.jpg?240}} +The Storage Manager keeps configured branches in ''mergerfs.roms''. During a pool refresh, a branch whose directory is currently missing is skipped from the live pool rather than automatically deleted from the saved configuration. If that same drive later appears again at the same mount path, Storage Manager can refresh the pool and re-add it automatically.
-Convert VGA to Scart cable to YCBCR & S-Video +
-  * [[https://www.arcadexpress.com/en/video-converters/615-convertidor-de-video-rgbs-scart-a-ycbcr-ypbpr-.html?mot_tcid=75c33dde-5be2-4fc6-ba75-933c02460a9b]] +
-Can also be found by searching AliExpress for "SCART RGBS to YUV YCBCR Video Converter"+
  
-===== Composite/S-Video Transcoders =====+By contrast, using **Eject an Extra Disk** removes that branch from ''mergerfs.roms''. A live unplug event is also routed through the eject/cleanup path when Batocera can identify the removed mount. In those cases, reconnecting the drive requires it to be merged again.
  
-If you need composite/S-video/RF, use these transcoders: +This distinction is useful for systems where a configured drive is sometimes powered off before Batocera boots. Leaving it configured but absent at boot is different from explicitly ejecting it.
-  * [[https://www.ebay.com/itm/174151197805|RGB VGA to NTSC S-video and composite transcoder/encoder by linuxbot3000 (ebay)]] ([[http://wakabavideo.com/|homepage]]) +
-{{hardware:s-l1600.jpg?240}} {{hardware:s-l1600-back.jpg?240}}+
  
-RGB to Composite & S-Video Ver2.0+===== What Gets Merged? =====
  
-{{hardware:rgb-2yc_1.jpg?240}} +The graphical Storage Manager merges only the ROM library:
  
-  * [[https://www.axunworks.com/product-p341706.html]]+<code> 
 +/userdata/roms 
 +</code>
  
-===== DisplayPort to VGA DAC =====+Folders such as:
  
-If you only have a DP connection, use the CableDeconn DP to VGA adapter before sending the signal to the transcoder of your choice: +<code> 
-  * [[http://www.cabledeconn.com/CABLEDECONN-Multi-Function-Displayport-Dp-to-HDMIDVIVGA-Male-to-Female-3-in-1-Adapter-Converter-Cable---M0401_show83.html|Link to official website]] +/userdata/bios 
-  * [[https://www.amazon.com/CableDeconn-Multi-Function-Displayport-Adapter-Converter/dp/B0192Y9XSE|Link to Amazon's store page for the adapter]] +/userdata/saves 
-{{:cabledeconn_dp_to_vga_shell.jpg?230|}} {{:cabledeconn_dp_to_vga.jpg?130|}}+/userdata/screenshots 
 +/userdata/themes 
 +/userdata/music 
 +</code>
  
-<WRAP center round info> +remain on internal storage. 
-If you are in a situation where you must use an active adapter, the CableDeconn DP to VGA adapter is one of the best options. It uses a repurposed Realtek RTD 2168 audio chip for its conversion, which doesn't rely on an oscillating crystal (no out-of-sync timing it has to account for) and no automatic deinterlacer (pretty much standard for all other active adapters, this will ruin your signal's quality).+ 
 +The graphical Storage Manager does not merge BIOS files, save files, screenshots, themes, or music. 
 + 
 +Advanced manual MergerFS pools are separate from the graphical Storage Manager and can technically target other directories, but those pools are not managed by the Storage Manager interface. 
 + 
 +===== Internal ROM Preservation ===== 
 + 
 +When the first additional ROM drive is merged, Batocera preserves the existing internal ROM collection. 
 + 
 +Internally, existing ROMs stored in: 
 + 
 +<code> 
 +/userdata/roms 
 +</code> 
 + 
 +are moved into: 
 + 
 +<code> 
 +/userdata/.roms_base 
 +</code> 
 + 
 +This allows internal ROMs to remain visible alongside ROMs stored on merged drives. 
 + 
 +If all merged drives are later removed, Batocera restores the internal ROM library back to the normal ''/userdata/roms'' location. 
 + 
 +During restoration, the current implementation uses ''rsync --ignore-existing''. Existing destination files are therefore not overwritten by files of the same name from ''.roms_base''. If restoration fails, Batocera keeps ''.roms_base'' instead of deleting it so the preserved data is not discarded. 
 + 
 +===== Limitations ===== 
 + 
 +Automatic detection by the graphical Storage Manager currently requires this layout: 
 + 
 +<code> 
 +<drive>/roms 
 +</code> 
 + 
 +Nested ROM folders are not detected automatically. 
 + 
 +Example: 
 + 
 +<code> 
 +<drive>/Batocera/roms 
 +</code> 
 + 
 +is not automatically merged. 
 + 
 +This limitation does not apply to advanced manual MergerFS branches, where an explicit nested path can be configured. 
 + 
 +The graphical Storage Manager merges only the ROM library. Other userdata folders remain independent unless they are configured separately using advanced manual storage methods. 
 + 
 +<WRAP tip> 
 +For most users adding locally attached USB drives, SSDs, hard drives or SD cards, the Storage Manager sections above are all that is needed. 
 + 
 +The remaining sections are for advanced setups, manual storage configuration, network/NAS integration, implementation details and troubleshooting.
 </WRAP> </WRAP>
  
-===== USB-C to VGA DAC =====+===== Other Storage Methods (Advanced) =====
  
-If you only have a USB-C connection, use the StartTech.com USB type C to VGA, 3m, CDP2VGA3MBNL (Note: this 3m cable has the RTD2166 chip. Shorter versions of the same brand use a different chip that may not be compatible) before sending the signal to the transcoder of your choice: +Batocera has several storage mechanisms that solve different problems. They should not be treated as interchangeable.
-  * [[https://www.startech.com/en-us/audio-video-products/cdp2vga3mbnl|Link to official website]] +
-  * [[https://www.amazon.com/USB-VGA-Cable-Computer-Monitor/dp/B078MS23PL?th=1|Link to Amazon's store page for the adapter]] +
-{{:startech.com_-_cdp2vga3mbnl.jpg?230|}}+
  
-<WRAP center round info> +^ Method ^ Best used for ^ What it does ^ 
-If you are in a situation where you must use an active adapter and only have a USB type C connection the StartTech.com USB type C to VGA adapter is one of the best options. It uses a repurposed Realtek RTD 2166 audio chip for its conversion, which doesn't rely on an oscillating crystal (no out-of-sync timing it has to account for) and no automatic deinterlacer (pretty much standard for all other active adapters, this will ruin your signal's quality).+| **Storage Manager** | Multiple locally attached ROM drives | Builds a MergerFS union at ''/userdata/roms'' and manages it from EmulationStation | 
 +| **sharedevice=DEV / ANYEXTERNAL** | Moving all userdata to one selected device, or to the first suitable external device | Mounts another device as the active userdata storage | 
 +| **sharedevice=DEVICES** | Mounting selected local partitions or subdirectories over specific userdata folders | Bind-mounts selected local storage over individual targets such as ROMS, SAVES or BIOS | 
 +| **sharedevice=NETWORK** | Replacing all or selected userdata folders with SMB/NFS shares | Mounts network storage directly on the requested userdata paths | 
 +| **Manual S12mergerfs pool** | Combining local folders and network/NAS folders in one union | Builds an advanced MergerFS pool from explicitly configured branches | 
 + 
 +<WRAP tip> 
 +If the goal is simply to add a second, third or fourth locally attached ROM drive, use the graphical Storage Manager. If the goal is to combine a NAS with local ROM storage in the same ''/userdata/roms'' namespace, use the advanced manual MergerFS method documented below.
 </WRAP> </WRAP>
  
-===== Connecting the PC to a CRT display =====+===== Network/NAS Storage (Advanced) ===== 
 + 
 +<WRAP important> 
 +This section is **not required for normal Storage Manager use**. If all ROM drives are attached locally, use the graphical Storage Manager described above. 
 +</WRAP> 
 + 
 +The graphical Storage Manager currently focuses on locally attached storage devices. Batocera also includes a separate boot-time MergerFS service that can build manual pools from local storage, removable media and already-mounted network shares. 
 + 
 +This makes it possible to present ROMs from a NAS together with ROMs stored on local drives under the same virtual directory, such as: 
 + 
 +<code> 
 +/userdata/roms 
 +</code> 
 + 
 +<WRAP important> 
 +Manual MergerFS pools are an advanced configuration and are not managed by the Storage Manager user interface. If you create a manual pool for ''/userdata/roms'', do not also use the graphical Storage Manager to manage that same pool. The graphical Storage Manager owns its own ''mergerfs.roms'' configuration and can rebuild the live ROM pool independently. 
 +</WRAP> 
 + 
 +==== Manual MergerFS Syntax ==== 
 + 
 +Manual pools are configured in: 
 + 
 +<code> 
 +/boot/batocera-boot.conf 
 +</code> 
 + 
 +The basic syntax is: 
 + 
 +<code> 
 +mergerfs=<pool>@<branch1>:<branch2>:<branch3> 
 +</code> 
 + 
 +For example: 
 + 
 +<code> 
 +mergerfs=/userdata/roms@/media/BATO_HDD/roms:/media/SDCARD/path/to/roms 
 +</code> 
 + 
 +The path before the ''@'' is the virtual MergerFS mount point. Paths after the ''@'' are the storage branches that are combined into the pool. 
 + 
 +Unlike automatic Storage Manager detection, manual branches do not need to use a root-level ''roms'' directory. Any suitable mounted directory can be used as a branch. 
 + 
 +The manual service accepts more than one pool. Keys beginning with ''mergerfs'' followed by letters, numbers, underscores or hyphens are processed, for example: 
 + 
 +<code> 
 +mergerfs=/userdata/roms@/media/SSD/roms:/media/NAS/roms 
 +mergerfs_bios=/userdata/bios@/media/SSD/bios:/media/NAS/bios=RO 
 +</code> 
 + 
 +<WRAP important> 
 +The manual parser uses ''@'' to separate the pool from its branch list and '':'' to separate branches. Avoid using those characters inside local branch paths. Mount network shares to a simple local path such as ''/media/NAS'' first, then use that local path as the branch. 
 +</WRAP> 
 + 
 +The graphical Storage Manager key is ''mergerfs.roms''. The dot in that key means it is not consumed by the manual ''S12mergerfs'' key parser. They are separate implementations even though both use MergerFS. 
 + 
 +==== Mounting a NAS Before the Pool Is Created ==== 
 + 
 +The manual MergerFS service supports ''premerge'' commands. These commands run before the MergerFS pool is created and can be used to mount a network share first. 
 + 
 +Example using an SMB/CIFS guest share: 
 + 
 +<code> 
 +sharewait=30 
 +premerge1=mkdir -p /media/NAS && mount.cifs //192.168.1.10/Games /media/NAS -o guest 
 +mergerfs=/userdata/roms@/media/BATO_HDD/roms:/media/SDCARD/path/to/roms:/media/NAS/roms=RO 
 +</code> 
 + 
 +In this example: 
 + 
 +  * ''premerge1'' creates the local mount point and mounts the SMB share 
 +  * ''sharewait'' is used by the boot service as the retry budget for ''premerge'' commands 
 +  * ''/media/NAS/roms'' is added as another MergerFS branch 
 +  * ''=RO'' makes only that branch read-only inside the MergerFS pool 
 + 
 +<WRAP info> 
 +The example above uses a guest SMB share for simplicity. Password-protected SMB shares and NFS mounts can also be mounted with normal Linux mount options before being included as a MergerFS branch. See the Batocera NAS documentation for the existing SMB/NFS syntax and network-storage guidance. 
 +</WRAP> 
 + 
 +Multiple ''premerge'' commands are supported. The service processes all keys matching names such as ''premerge1='', ''premerge_nas='', or similar before it processes any manual MergerFS pools. 
 + 
 +If ''sharewait'' is not set, the service uses a default value of 15. ''premerge'' retries are attempted at 4-second intervals and the number of attempts is derived from ''sharewait / 4'' using integer arithmetic. The default value therefore gives three attempts, while ''sharewait=30'' gives seven attempts. Values below 4 result in **zero** ''premerge'' attempts, so do not set ''sharewait'' below 4 when using ''premerge''. The same ''sharewait'' setting is also used by Batocera's normal share service, so changing it can affect both storage mechanisms. 
 + 
 +<WRAP important> 
 +If a ''premerge'' command exhausts its retries, the current ''S12mergerfs'' script logs that it is giving up but then continues to the manual pool-processing stage. A NAS mount failure therefore does not itself guarantee that pool creation will be aborted. When troubleshooting a network-backed pool, verify that the expected path is actually mounted before assuming the MergerFS pool is healthy. 
 + 
 +This matters especially when the local mount-point directory already exists. If the network mount failed but a branch path still exists locally, MergerFS can see the local directory rather than the NAS. Marking a network branch ''=RO'' is a useful additional safeguard when the NAS is intended to be read-only, but it does not replace checking the mount with ''findmnt''. 
 +</WRAP> 
 + 
 +<WRAP warning> 
 +''premerge'' values are executed by the boot service through the shell using ''eval''. Treat every ''premerge'' line as a privileged shell command, not as a restricted mount-only setting. Quote paths/options carefully and do not copy untrusted command text into ''/boot/batocera-boot.conf''. Credentials written directly into a ''mount.cifs'' command will also be stored as plain text in that configuration file. 
 +</WRAP> 
 + 
 +''premerge'' runs at boot. It is not a continuous NAS availability monitor. If a network share disappears later, the graphical Storage Manager does not reconnect or eject that network branch for you. 
 + 
 +==== Branch Access Modes ==== 
 + 
 +The manual MergerFS service accepts branch suffixes such as: 
 + 
 +<code> 
 +=RO 
 +=RW 
 +=NC 
 +</code> 
 + 
 +  * ''RO'' = read-only. The branch is excluded from create and action policies. 
 +  * ''RW'' = read/write. This is normal branch behavior. 
 +  * ''NC'' = no-create. The branch is excluded from create policies, but existing files on that branch can still be changed or deleted. ''NC'' is **not** the same as read-only. 
 + 
 +For example: 
 + 
 +<code> 
 +mergerfs=/userdata/roms@/media/SSD/roms:/media/NAS/roms=RO 
 +</code> 
 + 
 +allows ROMs on both branches to appear under ''/userdata/roms'', while preventing writes to the NAS branch through the MergerFS pool. 
 + 
 +==== Manual Pool File Placement ==== 
 + 
 +The boot-time manual MergerFS service currently uses: 
 + 
 +<code> 
 +category.create=mfs 
 +moveonenospc=true 
 +minfreespace=4G 
 +</code> 
 + 
 +''mfs'' means **Most Free Space**. New files are created on an eligible writable branch with the most available free space. 
 + 
 +The complete option set currently passed by ''S12mergerfs'' is: 
 + 
 +<code> 
 +cache.files=off 
 +dropcacheonclose=false 
 +category.create=mfs 
 +allow_other 
 +use_ino 
 +moveonenospc=true 
 +minfreespace=4G 
 +xattr=passthrough 
 +</code> 
 + 
 +When a manual pool is created, Batocera also creates a hidden local base directory derived from the pool path. For a pool at: 
 + 
 +<code> 
 +/userdata/roms 
 +</code> 
 + 
 +the hidden base is: 
 + 
 +<code> 
 +/userdata/.roms 
 +</code> 
 + 
 +Existing files from the original pool directory are moved into this hidden base before the MergerFS mount is created. The base is then added to the pool with ''=NC'', so new files are not created there by MergerFS. Because ''NC'' is no-create rather than read-only, existing files in this hidden base can still be modified or deleted through the pool. 
 + 
 +The script also **attempts** to remount the hidden base read-only before starting MergerFS, but that command explicitly ignores failure. Do not rely on the underlying hidden base being read-only. The dependable MergerFS-side rule in the command line is ''=NC'', which prevents creation but is not equivalent to ''=RO''. 
 + 
 +The service derives this hidden base path from the final component of the pool path. There is an implementation quirk worth knowing about: the manual pool **key** parser permits digits 0 through 9, but the current hidden-base derivation expression only accepts letters, ''0'', ''1'', underscores and hyphens in the final pool-directory name. Standard names such as ''/userdata/roms'', ''/userdata/bios'' and ''/userdata/saves'' are safe. Until that code is corrected, avoid custom manual pool names whose final directory component contains digits 2 through 9 or other unusual characters. 
 + 
 +<WRAP important> 
 +The manual ''S12mergerfs'' service and the graphical ''batocera-storage-manager'' use different configuration paths and different MergerFS policies. The graphical Storage Manager uses ''mergerfs.roms'' and ''category.create=eplfs''. The manual boot-time service processes keys such as ''mergerfs='', ''mergerfs1='', or other supported ''mergerfs''-prefixed names and currently uses ''category.create=mfs''. 
 +</WRAP> 
 + 
 +<WRAP warning> 
 +There is also a source-level limitation in the current ''S12mergerfs'' stop path: the stop handler checks ''$POOL'' before the configured-pool loop has assigned it. It therefore does not appear to enumerate and unmount every configured manual pool when invoked as a standalone stop action. Treat this as an implementation issue, not as a supported way to manually dismantle all pools. Normal system shutdown/reboot has broader filesystem teardown, or an advanced user can explicitly unmount the pool target they created. 
 +</WRAP> 
 + 
 +==== Relationship to sharedevice=NETWORK and sharedevice=DEVICES ==== 
 + 
 +The existing ''S11share'' mechanism and the manual ''S12mergerfs'' mechanism solve different problems. 
 + 
 +  * ''sharedevice=NETWORK'' mounts SMB/NFS storage **over** selected userdata paths such as ''/userdata/roms''. It does not union that directory with the local ROM directory. 
 +  * ''sharedevice=DEVICES'' similarly mounts selected local partitions or subdirectories over named userdata targets. 
 +  * The normal share service recognizes targets including ''SHARE'', ''ROMS'', ''SAVES'', ''BIOS'', ''MUSIC'', ''DECORATIONS'', ''SCREENSHOTS'', ''THEMES'', ''CHEATS'', ''SOUNDS'', ''LIBRARY'', ''SPLASH'', ''CONFIGS'' and ''RECORDINGS''. 
 +  * ''S11share'' also accepts advanced ''sharenetwork_cmdN='' entries containing arbitrary shell commands. These belong to the older direct-share mechanism and do not create a MergerFS union by themselves. 
 +  * ''S12mergerfs'' combines multiple already-available paths into one union mount. 
 + 
 +''S11share'' runs before ''S12mergerfs'' in the boot sequence. The normal network-share service can therefore be useful for other userdata folders, while a manual MergerFS pool is used for ROMs, but do not configure two different mechanisms to mount directly onto the same target path. 
 + 
 +The Storage Manager also deliberately skips local disks that are already referenced by UUID through manual ''sharedevice...'' entries, which helps prevent it from automatically taking ownership of manually configured local storage. 
 + 
 +The normal ''S11share'' service also runs ''/boot/preshare.sh start'' when that file exists. Batocera's source specifically notes this hook can be used for tasks such as waking a NAS. Because ''S11share'' runs before ''S12mergerfs'', this is another way to prepare infrastructure needed by a later manual MergerFS pool, although ''premerge'' remains the pool-specific mechanism. 
 + 
 +==== Boot ordering and delayed Storage Manager detection ==== 
 + 
 +Storage devices can appear very early during boot, before ''/userdata'' and the normal share configuration are ready. Batocera coordinates this with the ''S11share'' stage instead of blindly rebuilding the ROM pool immediately. 
 + 
 +At the end of ''S11share'', Batocera: 
 + 
 +  * Replays Storage Manager device events that were delayed until the share layer became ready 
 +  * Checks for ''/tmp/mergerfs.pending'' and runs ''batocera-storage-manager refresh_pool'' when required 
 +  * Creates ''/var/run/batocera.share.mounted'' to signal that normal hotplug processing can proceed 
 + 
 +This explains why an already-configured ROM drive detected during early boot can be queued first and only joined to the live pool after the base ''/userdata'' storage has finished mounting. 
 + 
 +===== Advanced Technical Details ===== 
 + 
 +==== Graphical Storage Manager Pool ==== 
 + 
 +Batocera's graphical Storage Manager uses **MergerFS** to combine ROM folders from multiple drives into a single virtual directory. 
 + 
 +The merged library is presented at: 
 + 
 +<code> 
 +/userdata/roms 
 +</code> 
 + 
 +Internally, Batocera maintains a storage pool containing: 
 + 
 +<code> 
 +/userdata/.roms_base 
 +</code> 
 + 
 +plus any merged ROM folders. 
 + 
 +Example: 
 + 
 +<code> 
 +/userdata/.roms_base 
 +/media/roms1/roms 
 +/media/roms2/roms 
 +</code> 
 + 
 +These locations are combined into: 
 + 
 +<code> 
 +/userdata/roms 
 +</code> 
 + 
 +==== Graphical Storage Manager File Placement Policy ==== 
 + 
 +The graphical Storage Manager currently uses these base MergerFS options: 
 + 
 +<code> 
 +cache.files=partial 
 +dropcacheonclose=true 
 +category.create=eplfs 
 +allow_other 
 +inodecalc=path-hash 
 +moveonenospc=true 
 +minfreespace=4G 
 +</code> 
 + 
 +When the ''refresh_pool'' path rebuilds an already configured pool, it appends the MergerFS ''nonempty'' option. The initial merge/rebuild paths use the base option string shown above. This is an implementation detail rather than a user-selectable Storage Manager setting. 
 + 
 +**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. 
 + 
 +The internal ''.roms_base'' directory is a normal writable branch in the graphical pool. It therefore participates in the ''eplfs'' policy too. Expanding storage does **not** mean every future write is forced onto an external drive. The destination depends on which branches already contain the target path and their available space. 
 + 
 +Because ''eplfs'' is an existing-path policy, it prefers branches where the relative parent path already exists. Newly formatted Storage Manager drives receive a copy of the standard ROM directory structure specifically so those system directories are available as placement candidates. 
 + 
 +<WRAP important> 
 +The MergerFS implementation and file placement policy may change between Batocera releases. The ''eplfs'' policy described above applies to the graphical Storage Manager implementation. The manual ''S12mergerfs'' boot service currently uses ''mfs'' instead, as described in the Network/NAS section. 
 +</WRAP> 
 + 
 +==== Important MergerFS behavior ==== 
 + 
 +MergerFS combines directory trees. It does not stripe or split one ROM file across multiple drives. The free space shown for a pool can therefore be larger than the space available for any one file on an eligible branch. Path-preserving policies, branch modes and ''minfreespace'' can also produce a no-space error even when the pool appears to have free capacity. 
 + 
 +''moveonenospc=true'' only helps when a **write to an already created file** fails with a no-space or quota error and MergerFS can move that file to another eligible branch. It does not override every create-policy failure. 
 + 
 +Avoid keeping duplicate files at the exact same relative path on multiple branches. MergerFS deduplicates directory entries, and its default search/action policies can select or act on matching paths across branches in ways that are not obvious from EmulationStation. 
 + 
 +It is possible to access the underlying branch directories directly, for example under ''/media'', while the pool is mounted. However, MergerFS upstream advises against modifying the same file both through a branch path and through the union at the same time, especially when caching is enabled. For the graphical Storage Manager, prefer writing through ''/userdata/roms'' while the pool is active. 
 + 
 +===== Troubleshooting and Diagnostics ===== 
 + 
 +The main **graphical Storage Manager backend** log is: 
 + 
 +<code> 
 +/var/log/batocera-storage.log 
 +</code> 
 + 
 +The manual ''S12mergerfs'' init script does not write its own messages to that file. Its ''echo'' output belongs to the boot/init-service output path, so a clean ''batocera-storage.log'' does not prove that a manual ''premerge'' or ''S12mergerfs'' pool succeeded. 
 + 
 +Useful read-only checks from SSH include: 
 + 
 +<code> 
 +batocera-settings-get -f /boot/batocera-boot.conf mergerfs.roms 
 +batocera-storage-manager list_ejectable 
 +batocera-storage-manager list_disks 
 +batocera-storage-manager list_fstypes 
 +findmnt /userdata/roms 
 +mount | grep mergerfs 
 +</code> 
 + 
 +Storage Manager communicates with EmulationStation through its local HTTP API for merge/format prompts, notifications and game-list reloads. The backend waits for EmulationStation to report that it is idle, retrying once per second for up to 300 attempts. A prompt or reload can therefore be delayed while EmulationStation is busy, and after roughly five minutes the request is abandoned and a timeout is written to the Storage Manager log. 
 + 
 +For the older ''sharedevice=NETWORK'' / ''sharedevice=DEVICES'' mechanism, ''S11share'' writes diagnostic output to: 
 + 
 +<code> 
 +/tmp/mountDevicesOrNetwork.log 
 +/tmp/mountDevicesOrNetwork.err 
 +</code> 
 + 
 +If a manual NAS-backed ''S12mergerfs'' pool is not working, first verify that the ''premerge'' mount actually exists with ''findmnt'' or ''mount'' before debugging MergerFS itself. 
 + 
 +===== 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> 
 + 
 +==== Which filesystems can Storage Manager format? ==== 
 + 
 +The implementation documented here exposes: 
 + 
 +<code> 
 +ext4 
 +btrfs 
 +exfat 
 +</code> 
 + 
 +Existing drives may use other filesystems if Batocera can mount them. NTFS is explicitly handled for existing drives, but it is not one of the Storage Manager format targets. 
 + 
 +==== Why does a small blank drive not produce a format prompt? ==== 
 + 
 +The current safety logic suppresses the automatic blank-disk format prompt for disks of 4 GiB or smaller. This is intended to avoid accidentally offering small firmware/system LUNs for formatting. 
 + 
 +==== Can I stop Storage Manager from trying to use a particular drive? ==== 
 + 
 +Yes. The backend supports an ''ignore.drives'' list. Ignoring a drive disables Storage Manager automation for that physical drive while still allowing readable filesystems on it to remain mounted normally. 
 + 
 +==== How do I remove a drive from the ignore list? ==== 
 + 
 +The current backend has an ''ignore'' action but no separate ''unignore'' action. Ignored drive identifiers are stored in the ''ignore.drives'' setting in ''/boot/batocera-boot.conf''. Remove the relevant identifier from that setting, then reconnect or re-detect the drive (or reboot) so Storage Manager can evaluate it again. 
 + 
 +==== What if a configured drive is missing when Batocera boots? ==== 
 + 
 +A missing configured branch is skipped from the live pool during refresh, but its saved ''mergerfs.roms'' entry is not automatically removed. If the drive later returns at the same mount path, Storage Manager can refresh the pool automatically. Explicitly ejecting the drive is different because eject removes its branch from the saved configuration. 
 + 
 +==== Can I use a network drive or NAS in the same ROM pool? ==== 
 + 
 +Yes, but not through the graphical Storage Manager interface. 
 + 
 +Advanced users can mount a network share with a ''premerge'' command in ''/boot/batocera-boot.conf'' and then include that mounted path in a manual MergerFS pool. 
 + 
 +For example: 
 + 
 +<code> 
 +premerge1=mkdir -p /media/NAS && mount.cifs //192.168.1.10/Games /media/NAS -o guest 
 +mergerfs=/userdata/roms@/media/SSD/roms:/media/NAS/roms=RO 
 +</code> 
 + 
 +See [[#network_nas_storage_advanced|Network/NAS Storage (Advanced)]] for details and limitations. 
 + 
 +==== 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? ==== 
 + 
 +Not by the graphical Storage Manager. It only manages the ROM pool at: 
 + 
 +<code> 
 +/userdata/roms 
 +</code> 
 + 
 +BIOS files normally remain stored in: 
 + 
 +<code> 
 +/userdata/bios 
 +</code> 
 + 
 +Advanced users can separately mount or union BIOS storage with ''sharedevice=NETWORK'', ''sharedevice=DEVICES'', or a manual MergerFS pool, but that is outside the graphical Storage Manager. 
 + 
 +==== Are saves merged? ==== 
 + 
 +Not by the graphical Storage Manager. Save files remain in the normal userdata location, for example: 
 + 
 +<code> 
 +/userdata/saves 
 +</code> 
 + 
 +Advanced ''sharedevice'' or manual MergerFS configurations can target saves separately, but the Storage Manager UI does not manage that. 
 + 
 +==== Can I store ROMs in a different folder? ==== 
 + 
 +For automatic detection through the graphical Storage Manager, no. It currently expects a root-level folder named: 
 + 
 +<code> 
 +roms 
 +</code> 
 + 
 +For an advanced manual MergerFS pool, yes. The branch can point to an explicitly configured nested directory, for example: 
 + 
 +<code> 
 +/media/SDCARD/path/to/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> 
 + 
 +===== References ===== 
 + 
 +  * Batocera TV - ''Batocera 43 - Episode II'' 
 +    * Storage Manager demonstration: 
 +      * https://youtu.be/XpH27Yswe38?t=143 
 + 
 +  * Batocera Storage Manager source code: 
 +    * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-scripts/scripts/batocera-storage-manager 
 + 
 +  * Batocera manual MergerFS boot service: 
 +    * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/utils/mergerfs/S12mergerfs 
 +    * Source snapshot used for the original NAS/MergerFS documentation request: 
 +      * https://github.com/batocera-linux/batocera.linux/blob/7b9aefc9456e5517f0a333bb0caab94938d80c58/package/batocera/utils/mergerfs/S12mergerfs 
 + 
 +  * Batocera share service (NETWORK / DEVICES): 
 +    * https://github.com/batocera-linux/batocera.linux/blob/master/board/batocera/fsoverlay/etc/init.d/S11share 
 + 
 +  * Batocera disk formatter: 
 +    * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-scripts/scripts/batocera-format
  
-The first step is to safely connect your Batocera computer to the CRT display itself. If using a VGA connection with a EDID CRT monitor, it is as simple as connecting the display, turning it on and then turning the Batocera machine on. Keep reading this section for all other displays. If your CRT monitor does not send an EDID (the standard was introduced in 1994, so monitors manufactured before then **do not have EDID**), then you should still follow the following instructions just to be safe.+  * MergerFS documentation: 
 +    * https://trapexit.github.io/mergerfs/latest/
  
-<WRAP center round important> +  * Batocera NAS documentation: 
-During the boot process and resizing of the partition it will boot up in a non-supported resolution. Keep the CRT TV off for the moment or on another AV channel so it doesn't receive <wrap em>dangerous signals</wrap>. **These signals can destroy your CRT TV.**+    * https://wiki.batocera.org/store_games_on_a_nas
  
-Also keep in mind that during the BIOS boot process the same rule applies. Have the CRT TV off or on another input when first booting up.</WRAP>+  * Batocera external storage documentation: 
 +    * https://wiki.batocera.org/store_games_on_a_second_usb_sata_drive
  
-**To solve this we have 4 options:** +  * Batocera changelog: 
-  * Do the aforementioned, leaving the CRT TV off or on another channel. +    * https://batocera.org/changelog
-  * Have a look at gambaman's excellent solution [[http://forum.arcadecontrols.com/index.php/topic,160869.0.html|The ultimate VGA to SCART adapter]] over at Build Your Own Arcade Controls Forum (BYOAC). +
-  * Use buttersoft's passthrough dongle based on gambaman's design in the link above. +
-  * Flash you AMD/ATI card with [[http://example.com|ATOM-15]].+
  
-Once everything is safe, you can turn on your Batocera machine. If you'd like to edit files using the Batocera machine itself, you can hook up a secondary digital display in the meantime. If you have multiple ports and use another port, then you'll not be able to do this once you disable the other port outputs in the upcoming section. If you have a modern digital display that can handle older standard signals over older standards cables without blowing up (such as a LCD monitor with both HDMI and VGA ports), you can use that in place of your CRT until everything is configured correctly for it. 
  • user/rion.1732979125.txt.gz
  • Last modified: 23 months ago
  • by rion