Simics User's Guide / II Feature Overview / 7 Moving Data in and out of the Simulation /

7.5 Using SimicsFS with FUSE

SimicsFS with FUSE is a new implementation based on FUSE, Filesystem in Userspace, which is supported by most Linux systems[1]. This is a client-server solution, which is more feature complete and with better performance than the old SimicsFS kernel module and device solution.

The Simics extension, SimicsFS with FUSE, will grant a simulated Linux system access to the file system of the host computer from inside the simulation. This allows more storage space for the target system and may make copying files to and from the target system unnecessary as they can be accessed directly from the host file system.

The SimicsFS client, used for SimicsFS with FUSE, is a regular Linux user-space application that allows non-privileged users to mount and unmount file systems. The FUSE kernel module needs to be included in the Linux kernel and the libfuse userspace library[2] in the Linux distribution.

All accesses to the host filesystem will be made with the privileges of the user starting the Simics session.

Note: [1] FUSE is compatible with all Linux kernels since version 2.4. [2] SimicsFS client is compatible with FUSE 2.6 or later.

Some characteristics/limitations for SimicsFS with FUSE:

The user can only mount on a mountpoint, for which the user has write permission.
The mountpoint is owned by the user.
No other user (including root) can access the contents of the mounted file system (although this can be relaxed by using the allow_other and allow_root mount options).
All file system operations on the host are performed by the user running Simics, indifferent to which user requested the operations in the target system. Therefore even a super user on the target is constrained by the file system permissions of the user running Simics.
SimicsFS does not perform any character set transformation of characters in the file paths, so if different character sets are used on the simulated target and on the host, the characters may be interpreted differently.
SimicsFS is currently not using wide characters on Windows, and valid file path names are therefore limited to ASCII characters.
Read-only files on the target system may not be copied to the mounted file system. See workaround in section 7.5.2.
On Windows, the SimicsFS client only has partial access to the actual permissions of files and directories. Some permissions are not correctly reported, nor configurable by the client. See table below.

Limitations for Windows hosts:

Operation	Restriction
Read	Read accesses cannot be denied, any attempts are silently ignored.
Read	Unreadable files may still appear readable, but reading will fail.
Soft-link	Windows filesystems do not support it.
Add/Remove	Write permission on the directory is ignored.

7.5.1 Installing SimicsFS client

The SimicsFS client is installed on some disk images distributed with Simics. Where there is also a /host directory and definitions in /etc/fstab for mounting SimicsFS with the command mount /host by root. Then the host files become accessible by root alone.

If you run your own Linux distribution you have to compile SimicsFS client yourself. The source code is located in the src/misc/simicsfs-client/ directory and in the src/misc/libmagicpipe/ directory of the Base package (pkg 1000). The Linux kernel must be compiled with FUSE support and the file system must include libfuse.

Example definition in the /etc/fstab for mounting SimicsFS with the command mount /host by root:

    simicsfs-client      /host      fuse     defaults,noauto       0 0

Replace /host with your mount point. The simicsfs-client executable must be located in a directory included in the PATH environment variable, either by placing it there or adding its directory.

With the user option it is also possible to define entries in /etc/fstab for normal users to mount and unmount SimicsFS. Example showing mount of host user home directory on directory <dir>:

    simicsfs-client  <dir>  fuse  
defaults,noauto,user,modules=subdir,subdir=/home/<user>  0 0

The <dir> directory must be empty and have write permission for the user. The user mounts with the command mount <dir> and unmounts with the command fusermount -u <dir>.

See the fstab and fuse documentation ("man fstab", "man fuse") for more information about the available mount options.

7.5.2 Using SimicsFS client

The SimicsFS client requires the SimicsFS server to be started:

 simics> start-simicsfs-server

Example commands showing how to mount SimicsFS with the command simicsfs-client:

Mount host root directory on directory <dir>:
```
~:$ simicsfs-client <dir>
```

Mount host user home directory on directory <dir>:

	~:$ simicsfs-client <dir> -omodules=subdir,subdir=/home/<user>

Example command showing how to unmount SimicsFS:

Unmount SimicsFS on directory <dir>:
```
~:$ fusermount -u <dir>
```

Example commands showing how to mount SimicsFS on /host directory by root with definition in /etc/fstab, see section 7.5.1:

Mount host root directory on /host:
```
~:$ mount /host
```

Mount host user home directory on /host:

	~:$ mount /host -omodules=subdir,subdir=/home/<user>

Example command showing how to mount SimicsFS on <dir> directory by a normal user:

Mount host user home directory on <dir>. A user can not add options to the mount command so the options are added in /etc/fstab, see section 7.5.1.
```
~:$ mount <dir>
```

Workaround for copying read-only files: Read-only files on the target system may not be copied to the mounted file system. A workaround is to first touch the file in the mounted file system, which creates the file with write permission, and then copy the file from the target system to the mounted file system. Finally change permission of the destination file to read-only.

Tip: When running Simics on Windows host, replace all '\' in the mount path with '/' to prevent interpretation of escape character by the simulated target software. Example:

~:$ simicsfs-client dir -omodules=subdir,subdir=D:/home/<user>

7.5.3 SimicsFS Path Substitution

The host directory mounted from a target system is the root directory by default, but that is configurable from the target system. Although, it may not be feasible or desirable to modify the target system configuration when the host system path changes. The path may also be part of a checkpoint and may not be applicable when the checkpoint is restored again. For these cases the host path can be substituted with a replacement path on the host.

To perform a substitution a path rule must be created. These are applied to every operation, with immediate effect. A rule can be general to all clients or specific to just a group of clients. The rule will look for a substring in the requested path and replace that substring with the new destination path. The substring matching is performed from the beginning of the path, but need not match the whole requested path in the mount command on the target.

A client may thus request an existing or non-existing path on the host. This path will be matched against the defined path rules to see if there is a match. Specific rules are checked first, then the general rules. Therefore a specific rule will always override a general one. Otherwise the rules are matched in the order they were added and only the first matching rule will be applied.

EXAMPLES:

One of the main use-cases for this feature is to allow access to a user defined path which is configured at run-time without the need to modify the target configuration. For instance the users may want to access their own home directories, without modifying the generic target image. For this purpose they define a mount-point /mnt/home which is configured to mount /home/user on the host. The host path /home/user may not exist on the host and requires the user to configure a path rule to substitute it for the real home directory of the current user.

    simics> $userhome = (env HOME)
    simics> <simicsfs-server>.add-path-rule /home/user $userhome
    ~:$ mount -t simicsfs-client /mnt/home -osubdir,subdir=/home/user

Another major use-case for this feature is to solve the checkpoint problem, where a user has mounted some path on the local machine. This checkpoint is then shared with a colleague, who has similar files stored in another path. The colleague will then need to replace the requested host path with the actual path to the equivalent folder local to this other machine.

    simics> <simicsfs-server>.add-path-rule /work/simics/proj /my/path/to/proj

Sometimes you may need to differentiate between different clients. When a client registers itself with the simicsfs server, it provides a bit of details on the target that it runs on. Each of these details can be used to select clients for different groups. These groups can then be given as an extra argument to the path rule, which will then only apply to the clients of that group. Once a client is registered, it is assigned a unique magic number.

    simics> <simicsfs-server>.add-client-group a_team magic 0x0103a1245edb31da
    simics> <simicsfs-server>.add-path-rule "/" /proj/area_a a_team

The first line will create a group called a_team which will consist of the client with magic number 0x0103a1245edb31da. Since the magic numbers are unique there can only be one client in this group. The second line will add a path rule that replaces the root directory with /proj/area_a, but only for clients that belong to group a_team.

Path rule limitation: The simicsfs-client is not aware of any changes to the path rules, which means that recently accessed files may appear to still be present even though the path rule has changed to point to another destination. Operations on that file, however, will fail.

7.4 USB disks 7.6 Using TFTP