cafediscrun - Boot Cafe and Application

Syntax

$ cafediscrun [<options>] [<application> [<arguments>]

Options

-a "<arg1>,<arg2>,..." Pass command line arguments <arg1>, <arg2>, ... to <app>.rpx.
-b Use DEBUG versions of system libraries (RPLs) instead of NDEBUG versions.
-u Use FDEBUG OS version.
-l <path> Specify an individual RPL or a directory of RPLs that are used by <app>.rpx. More than one -l option may be specified.
-d multi Start the MULTI debugger.
-L Ignore the version mismatch error.
-i With -d multi, debug C++ constructors and initialization code.
-j With -d multi, debug pre-initialization code.
-R With -d multi, do not stop in the debugger at launch, but wait until the application calls OSDebug, OSDebugStr, or encounters a fatal exception.
-p <n> Indicate process to debug (defaults to application process).
-g <n> 32-bit flag to pass along to PPC COS.
-w <n> 32-bit flag to pass along to PPC COS.
-k <elf-file> Find the RPX's corresponding ELF file, at the path <elf-file>, when it is not in the same directory as the RPX file.
-x Enable AHCI/SATA disk access. Deprecated and soon to become the default.
-r Restart the previous RPX application with the same options and arguments.
-s Use soft-launch to launch.
-F Force restart (stop and then boot the hardware).
-t <title-id> Launch title <title-id>. <title-id> begins with 0x.
-e <op> Pass op through to FSEmul or MCP (e.g.: -e sataFSEmul -sata).
-v <level> Filter Cafe OS log messages by severity.
-q Do not display OS warning or informational messages.
-z Suppress mirroring the data to the session data directory.
-h Display help options.

Description

The cafediscrun tool performs the same function as caferun, but executes a master image instead of invoking the application directly from the host PC's file system. The mastered image can be uploaded to the internal HDD on the CAT-DEV using the imageuploader tool.

When executing a master image, the CAT-DEV uses a block-level interface that closely matches the driver behavior of production systems for disc-based games. This is useful for validating master images prior to R-disc testing.

When using the block-level interface, the CAT-DEV can emulate an optical disc with its integrated hard-disk drive, or by generating a disc layout file from the application's directory structure on the host PC.

Examples

Hard-disk Based Emulation

A master archive image can be placed on the CAT-DEV's integrated hard-disk drive, which then emulates a Cafe optical ROM disc. For more information, see the Hard-disk based emulation reference page.

To invoke hard-disk based emulation of an optical drive, issue the following from the Cafe Cygwin shell:

$ cafediscrun -e h:[num] -t [title_id]

Where -e h:[num] specifies one of ten banks (starting from 1) on the hard-disk, and -t [title_id] specifies the title ID of the application.

For example:

$ cafediscrun -e h:1 -t 0x000500001abcde00

This will invoke the application having title ID 0x000500001abcde00 from bank 1 of the integrated hard-disk.

The name of the application RPX can also be used. For example:

$ cafediscrun -e h:1 same_title_id.rpx

Note that the build target of the application must match that of the OS launching the application. That is, if you want to run the DEBUG version of the application, you must use the corresponding DEBUG version of the OS to launch it.

You can perform this with the -b option:

$ cafediscrun -b -e h:1 -t 0x000500001abcde00

The DEBUG version of the application, having title ID 0x000500001abcde00, will be launched using the DEBUG version of the OS, from bank 1 of the integrated hard-disk drive.

Host PC Hard-disk Based Emulation

In addition to running the image from the CAT-DEV's integrated hard-disk described above, it is possible to run a title from a master archive image located in the host PC hard drive, without uploading it to the CAT-DEV.

NOTE:
Unless specified by the user, the system will always attempt to launch the application from the emulated ODD, as if the user-specified -e mcp:launch_hint:odd. The user can override this behavior by specifying their own launch hint, but this is not recommended.

To invoke the host PC hard drive emulation of a master archive image, issue the following command from the Cafe Cygwin shell:

$ cafediscrun -e wumad:[image] <RPX app>

Where -e wumad:[image] specifies either the path in the host PC to the master archive image, or a folder where the master archive image has been extracted. RPX app is optional.

For example:

$ cafediscrun -e wumad:/cygdrive/c/temp/image.wumad

Similarly to the -e h:[num] option, if you want to run the DEBUG version of the application, you must use the corresponding version of the OS to launch it, which is performed with the -b option:

$ cafediscrun -b -e wumad:/cygdrive/c/temp/image.wumad

The following example shows the command to run from a folder where a master image file has been previously extracted:

$ cafediscrun -e wumad:/cygdrive/c/temp/extractedImageDir/ application.rpx

Block-level Emulation Mode

Alternatively, an abstracted master image can be generated on-the-fly and executed from the host PC's file system via block-level emulation interface.

This is a legacy mode maintained from previous console platforms. While it offers some performance advantages over the file-level emulation interface of caferun, this mode prevents write-access to the host PC directories that enclose the application's code, contents, and metadata.

Without any options, cafediscrun operates in Block Emulation mode:

$ cafediscrun app.rpx

The -x option will enable the high-speed SATA interface for block emulation:

$ cafediscrun -x app.rpx

Excluding Files from Block-Level Emulation

The block-level emulation interface derives a static block image - or layout - from the $CAFE_CONTENT_DIR directory on the host PC. The creation of the image occurs only once, when cafediscrun is invoked.

The image is limited in size and is read-only for the duration of the application's execution. These constraints exist because the image is meant to emulate a read-only storage medium, such as an optical disc.

The size limit for the block-level emulation interface is equal to the capacity of the Cafe optical disc.

Because of the size limit, it may be useful to exclude some files from the layout of the image. This can be performed by customizing the Disk Definition File (DDF).

The default DDF file can be found in:

($CAFE_ROOT)/system/bin/tool/mastering/resources/default.ddf

The unique DDF file created by developer can be also set exclusion file list for each application. The DDF file has to be located on the same directory of RPX file and has same file name of RPX. If RPX file name is application.rpx, the unique DDF file location is:

<rpx file path>\application.ddf

Using a text editor, add a [LayoutOff] section and add the files or directories you wish excluded from the layout image. For example:

[LayoutOff]
"*.svn*"
"abc.def"
"axdemo\axart\axartdemo.spd"
"axdemo\stream\*.adpcm"
"pictures\*.bmp"
"texts\*"

Note that the filenames must be enclosed in quotes. Note also that the '*' wildcard can be used.

Adjusting the Disc's Eject State

Using MION, the CAT-DEV can emulate a bootup state where the "disc" has been ejected prior to starting the application. To specify this behavior, use the ejectstate argument to -e. For example:

cafediscrun -e ejectstate:out application.rpx

OR

cafediscrun -e ejectstate:in application.rpx

A state of "out" will emulate the disc being ejected at boot time. Note that unless the user presses the EJECT Button on front of the CAT-DEV unit, the system will generate a fatal error 160-0101 after 60 seconds.

NOTE:
This "ejectstate" persists through reboots. Meaning, if the previous application was launched with ejectstate:out but the EJECT Button was not pressed, subsequent launches will also have an ejectstate of out.

Disc Error Emulation

Overview

While running an application using discrun, the MION can be used to generate certain disc errors after a specified number of read operations. Currently, the two errors that may be generated are a Fatal Error or Dirty Disc error.

Usage

To enable disc error emulation, navigate to your MION's webpage in a browser. The webpage is the IP address of the  MION, and can be retrieved using findbridge. On the MION home page, click the Error Simulation button. Below is a description of each option available.
Option Description
# of disc reads before error This number determines how many reads the disc will perform before triggering the error.
Error Type Choice of either Dirty Disc or Fatal Error.
Error Count How many errors to fire after the number of read operations is met.

See Also

Running Applications Overview
caferun
Hard-disk Based Emulation
Environment Settings
File System Overview
Default System Devices
CAFE LEDs

Revision History

2014/10/02 Placed topic in canonical API format.
2014/06/12 Launching a wumad will auto-mount to ODD unless otherwise specified
2013/10/25 Added See Also link to CAFE LEDs.
2013/07/30 Added ejectstate option
2013/07/29 Improved examples about running directly from a wumad
2013/05/08 Automated cleanup pass.
2013/03/13 Editorial updates.
2012/12/21 Added description about using host PC hard disk based image emulation.
2012/04/13 Noted '-b' option on HDD emulation mode.
2012/02/29 Sections revised. Added "Modes and options" section and description about SATA block emulation option "-x" and HDD emulation mode. Modified and added descriptions due to changing default file system.
2011/07/21 Initial version.


CONFIDENTIAL