System Devices, File Systems, and Volumes

Sections

Introduction

Cafe FS supports a standard set of devices and file systems. Important volumes are mounted by default at application startup. This topic describes those set of supported devices and file systems.

System Devices and File Systems

The following devices and file systems are supported by the Cafe system. These devices appear under the /dev/ system directory.

Device File System(s) Remarks
odd0x ATFS Optical Disc Drive, or emulation device for optical disc (PC block emulation using SATA, CAT-DEV HDD).
slc01 ISFS Internal system storage (System only).
slccmpt01 ISFS Internal system storage (System only).
mlc01 WFS Internal application storage.

Note that some file systems and device drivers are still under development. This list is subject to change.

Some devices and file systems are available only on development systems:

Device File System(s) Remarks
sd01 ATFS (Emulated) Block-level optical drive emulation (using SDIO). Read-only. Will be deprecated in future SDKs.
odd01 ATFS (Emulated) Block-level optical drive emulation (using SATA). Read-only. Faster than SDIO block emulation.
hfio01 PCFS Native host PC file system. Read/write access.

Optical Disc

Total size of Cafe optical disc is 23,866 MB (25,025,314,816 bytes). Some amount of blocks on disc will be reserved for metadata and system use. The application size will be checked when you run the program in block emulation mode or you master the disc image.

Disc image consists of one or more partitions, including system partition and application partitions. Each partition is also often referred to as "volume" or "logical volume".

Cluster size is 32 KB. Address and size of each partition is aligned with the cluster size.

Disc data structure

Figure 1 Disc data layout

Figure 1 depicts the structure of whole disc image. Mastering tools generate virtual disc image in this format. It also depicts typical layout of partition data structure.

Game application is contained in application partition. It will be supported to create multiple application partitions in one disc image in forthcoming SDKs.

System partitions contain system use files such as system update packages.

Some regions have reserved size on image so there is upper limit for application code and content files:

Region Item Size
Disc header - 128 KB
System partitions System update data and so on. 3 GB in total with Disc header
Application partition Volume header 32 KB
FST ~ 2.75 MB
meta/ directory 16 MB
e-manual Max 128 MB
Hashes for content/ directory 338,284,032 bytes 1
Available for app's code and content 21,311,894,016 bytes

1 It depends on the content/ directory data size for the application. 1 KB hash is added to each 63 KB of data under content/ directory.

For information, see Application data directory.

FST

FST (File symbol table) is an entry table for entire volume. Its size depends on number of files/directories in application data and total length of their names. The size of FST itself is limited below 2,883,584 bytes. It can be calculated using the following formula based on the number of files, the number of directories, file names, and directory names.

FST size = 32 * [number of sections] + 16 * ([number of files & directories] + 1)
	   + [total length of file names & directory names (each includes '\0')]

File data sections

More than 1 file data sections follow FST. These sections contain file data indexed on the FST. File data within the section, except for padding attributed to alignment, is arranged in a continuous manner. Padding may be implemented between FST and a file data section, or between file data sections in such a way that the encryption for each section and hash context are not affected by it.

The closer to the outer circumference a file is located, the faster it is to access the file. Therefore, content files used in applications are generally placed from the outer circumference toward the inner sequentially. In that case, padding will be applied from the top to the file location. Main RPX file and meta files are located from the outer toward inner.

Emulation Devices


Host File IO Device

In the devkit environment, the /vol/save/ and /vol/content/ volumes are emulated by the host PC.

Host File IO device /dev/hfio01 is a high-level file emulation service that uses the native file system of the host PC.

When using the Host File IO device, the application can read and write to its content files. Conversely, applications running on the host PC can also read and write files in the emulation directory. Note that developers are responsible for preventing read and write conflicts between the target and host. New functions to facilitate this are forthcoming.

This volume can support sizes more than 25 GB. Developers are encouraged to use this volume and mount point for general development.

Block Emulation Device

The block-level emulation device /dev/sd01 or /dev/odd01 poses the following restrictions:

This device is useful for testing mastered application images. Because the device interface is abstracted at the block-level, master images can be read from storage devices other than optical discs.

The block emulation device also offers a slight speed advantage over Host File IO, especially for certain transactions like FSOpenFile.

As of this writing, block emulation is provided via 2 interfaces: SDIO or SATA. SDIO is the default interface but SATA interface is faster than SDIO. You can try SATA interface using an option with cafediscrun. In future SDKs, SATA will be default and SDIO will be deprecated.

Note that this volume is deprecated and may be removed altogether from general SDK releases in the near future.

CAUTION:
If block emulation is the default device, the Host File IO device must NOT write to the $CAFE_CONTENT_DIR emulation directory. Attempting to do so results in undefined behaviors.

Changing the Default Content Device

Developers may change the default content device of the application's file system. This means changing the device to which /vol/content/ is mapped.

/vol/content/ is mapped to the Host File IO device during caferun. /vol/content/ is mapped to the block-level emulation device during cafediscrun.

Note that this cannot be changed during runtime; the settings are applied during caferun and cafediscrun.

Using the Host File IO Device with ATFS Block Emulation

If the application is using the block emulation device as the default emulation device, developers can still use the Host File IO device at /dev/hfio01 by mounting it manually:

FSGetMountSource(*client, *block, FS_SOURCETYPE_HFIO, *source, FS_RET_NO_ERROR);
FSMount(*client, *block, *source, *target, sizeof(*target), FS_RET_NO_ERROR);

This will mount the File IO device of the Host Bridge to /vol/pc/. Programmers can then access the file system of their host PC via FS. For example:

/vol/pc/c/Users/jane/Desktop/myfile.txt

This path references "myfile.txt" on the desktop of user jane, located on the C: drive of the host PC.

If the host PC has mapped a network drive (for example, K:\), that drive can be mounted as well. Any drive that is mapped on the host PC can be mounted.

The network path can be accessed by using magic word. For example:

/vol/pc/%NETWORK/Filer/Users/jane/Desktop/myfile.txt

At this point, Filer is network desktop name.

See the ENVGetEnvironmentVariable function, which can retrieve environment variables from the PC. This function can be useful for developers who want to specify the directory that will be accessed via Host File IO.

IMPORTANT:
Many of the file system features and devices are under development. For the latest information regarding file system emulation as it relates to the CAT-DEV environment, see Environment Settings.

See Also

Developer Environment Settings
Application Mastering
ENVGetEnvironmentVariable

Revision History

2013/05/08 Automated cleanup pass.
2013/04/16 Fixed FST's size calculation formula.
2012/08/21 Removed a footnote about FST's old information.
2012/08/07 Updated FST's Size info.
2012/07/27 Removed information about FSA.
2012/04/12 Moved some HFIO description from "Caveats and Cautions" page.
2011/09/16 Added cafediscrun specific.
2011/07/20 Disc emulation setting now set in new system.xml.
2010/09/30 Initial version.


CONFIDENTIAL