emumount.txt

How to mount FAT32 devices and files in the Emulator
====================================================

QNICE-FPGA is able to work with (micro)SD Cards that are formatted with the
FAT32 file system and the MBR partition table. Please have a look at
doc/constraints.txt to learn more about that.

IMPORTANT: FAT32 (not FAT16) and MBR is mandatory.

The Emulator is able to mount raw image files that are made from appropriate
media and expose it to QNICE-FPGA via the SD Card interface, so that the
Monitor "thinks" this is a FAT32/MBR formatted SD card. As devices behave like
files on Unix-like systems, on these systems you can also directly mount a
device.

Creating a raw image file from existing folders
-----------------------------------------------

Use the tool that your operating system provides, to generate a raw image
from existing folders of your hard drive.

For macOS:

Here is an example, how you can add the folders "test_programs" and "qbin"
from the QNICE-FPGA root folder to a newly created raw image file.

1. hdiutil create -megabytes 33 -fs MS-DOS -fsargs "-F 32" -volname myimage -srcfolder qbin -srcfolder test_programs -o myimage.dmg

2. hdiutil convert myimage.dmg -format UDTO -o myimage

3. mv myimage.cdr myimage.img

IMPORTANT: hdiutil is only able to create FAT32 images, when the size of the
image (the "-megabytes" parameter) is larger than 32, so we use 33 in the
above-mentioned example.

IMPORTANT: In 2016, above-mentioned step (1) worked on my then current macOS
and machine. In 2020, step (1) strangely enough led to 100% CPU usage without
any file being created. Workaround: Remove the two "-srcfolder" statements,
let hdiutil create an empty DMG and then mount it using Finder. Then manually
copy the files you need. Then unmount and proceed with step (2).

Creating a raw image file from an existing device
-------------------------------------------------

If you have a FAT32 formatted SD Card or USB stick, then on Unix-like systems,
the easiest way is to use the "dd" command on the raw device. Example of how
to do it on a Mac:

1. Find out which disk device is mounted to: diskutil list
   Example: /dev/disk4

2. Use the raw device, by inserting a 'r' in front of the disk name:
   Example: /dev/rdisk4

3. Create a raw dump (you need sudo):
   Example: sudo dd if=/dev/rdisk4 of=mydump.img
   (Takes quite a long time. Can be interrupted by CTRL+C, you then have
   a partial dump, which is often OK and enough to play with.)

4. This image file can be mounted by the Emulator. (Also by your OS. In macOS
   for example, you can just double click such a file to mount it.)

Mounting a raw image file
-------------------------

Use the new command line parameter -a to mount a raw image file:

./qnice -a <raw image file>

Or use the new interactive command attach to mount it:

Q> attach <raw image file>

Directly mount a device
-----------------------

If you have a USB stick or a SD Card that is formatted FAT32/MBR and if you
are working under macOS or Linux and the likes, then you can directly use the
raw device to mount it in the emulator.

Example of how to do it on a Mac:

1. Use "diskutil list" to find out the device, to which your USB stick or your
   SD Card has been mounted.
   Example: /dev/disk4

2. Add the character 'r' to the beginning of the name of the device:
   Example: /dev/rdisk4

3. Compile the Monitor: Go to the folder 'monitor' in the QNICE-FPGA
   directory tree and run
   ./compile_and_distribute.sh
   (You need to be within the 'monitor' folder for the script to work.)

4. Go to the 'emulator' folder.

5. Mount the device and load the Monitor. Depending on your OS and OS version,
   you might need to call the Emulator in the root context using sudo:
   Example: sudo ./qnice -a /dev/rdisk4 ../monitor/monitor.out

6. You are in the emulated QNICE monitor now. Browse the root folder by
   entering "F" then "D"


written by sy2002 in December 2016
latest update by sy2002 in February 2020