cafex discrun - Boot Cafe and Application

Syntax

cafex discrun [<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.
-d multi Start the MULTI debugger.
-e <value> Specify a special launch option; see below.
-h Print a list of the available options.
-i With -d multi, debug C++ constructors and initialization code.
-j With -d multi, debug pre-initialization code.
-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.
-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.
-L Ignore the version mismatch error.
-r Restart the previous RPX application with the same options and arguments.
-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.
-t <title-id> Launch title <title-id>. <title-id> begins with 0x.
-v <level> Filter Cafe OS log messages by severity.
-K Use kill-restart to quickly relaunch titles

-e Option

The -e option allows you to specify special options that affect how an application may be run. The table below shows some of the available special options. Each special option must be preceded by a -e option:

ejectstate:<value> Set the eject state of the emulated ODD to in or out. For more information, see Adjusting the Disc’s Eject State.
h:<n> Mount HDD bank <n> when launching the application. Valid values for <n> range from 0-10, inclusive by default. If the application cannot be found on the specified HDD bank, error 160-0101 will occur after about 60 seconds.
noCSR Disable the Combined Send/Receive optimization. Not recommended.
noFFIO Disable the Fast File I/O optimization. Not recommended.
nopcfs Allow an application located on the PC to be run on a CAT-DEV that is running in headless mode.
pcfsport:x Use port x instead of the default port (7500) for PCFS over SATA transactions.
wumad:<app>.wumad Launch the mastered title (.wumad) specified by <app>. It is not necessary to specify the RPX application when using this command.

-v Option

The -v option allows you to specify the severity of Cafe OS logging messages to print.

<level> Output
0 Print error messages only.
1 Print error and warning messages. Default.
2 Print error, warning, and informational messages.
7 Print verbose messages.

Return Values

If cafex does not encounter an error, the application's exit code is returned upon application exit.

-25 UPLOAD_IMAGE_OS_MISMATCH
-23 SYSLOG_LEVEL_SET_FAILED
-18 SYNCTOOL_FAILED
-17 RUN_TITLE_ID_REQUIRED
-15 UPDATE_INVALID_OPTION
-14 RUN_NON_MULTI_DEBUGGER
-13 BOOT_RUN_NO_TEMP_VAR
-12 RUN_NO_TEMP_VAR
-11 RUN_INVALID_OPTION
-10 RUN_BAD_H_ARGUMENT
-9 RUN_NO_SDK_VERSION_HEADER
-8 RUN_COULDNT_PARSE_SDK_VERSION_HEADER
-4 BAD_ARGUMENT
-1 UNEXPECTED
0 OK
2 RUN_MEMMAP_NOT_SUPPORTED
2 HOSTCHECKVERSION_NO_HOSTBRIDGE
2 HOSTCHECKVERSION_FSEMUL_FAILED
2 HOSTCHECKVERSION_OLD_VERSIONS
2 RUN_BAD_TITLE_ID
2 RUN_NO_CAFE_DATA_DIR
2 RUN_D_OPTION_USED
2 RUN_RPX_DOESNT_EXIST
5 RUN_HOSTSTOP_RVAL_NON_ZERO
6 RUN_NO_RPX_SPECIFIED
7 RUN_TITLE_ID_NOT_FOUND_IN_MLC
8 RUN_CANT_FIND_OS_DIRECTORY
8 RUN_OS_NOT_PRESENT
9 RUN_DISCRUN_NAND_UNABLE_TO_FIND_APPLICATION
9 RUN_DASH_R_WITH_NO_PREVIOUS_LAUNCH_INFO
9 RUN_DASH_R_CANT_FIND_APPLICATION
11 RUN_UPDATE_ARGLIST_FAILED
12 RUN_CHECKTITLEID_FAILED
12 RUN_UPDATE_APP_XML_FAILED
12 RUN_UPDATE_COS_XML_FAILED
12 RUN_UPDATE_META_XML_FAILED
20 RUN_BAD_DEBUGGER
21 RUN_BAD_DEBUGGER_PORT
30 RUN_PCFSSERVER_SYNC_FAILED
30 BOOTRUN_MAKEBSF_FAILED
31 BOOTRUN_MAKEDLF_FAILED
31 CAFEDEVRUN_MAKECAFEDLF_FAILED
50 CAFEDEVRUN_NO_IMAGE_FILE
53 CAFEDEVRUN_CANT_FIND_APP_XML

Description

The cafex discrun command performs the same function as cafex run, but executes a master image instead of invoking the application directly from the host PC's file system.

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

Block-level Emulation Mode

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 cafex run, this mode prevents write-access to the host PC directories that enclose the application's code, contents, and metadata.

Without any options, cafex discrun operates in Block Emulation mode:

cafex discrun <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 cafex discrun 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\*"

Filenames must be enclosed in quotes. The '*' wildcard can be used.

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 Hard-disk based emulation.

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

cafex discrun -e h:<n> -t <title-id>

Where <n> specifies one of eleven banks (starting from 0) on the hard-disk, and <title-id> specifies the title ID of the application.

For example:

cafex discrun -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:

cafex discrun -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, use the corresponding DEBUG version of the OS to launch it. cafex will throw a warning if the modes mismatch if the master archive was uploaded using Host Bridge 3.2.6.1 and later.

This can be performed with the -b option:

cafex discrun -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 you specify otherwise, the system always attempts to launch the application from the emulated ODD, as if you had specified -e mcp:launch_hint:odd. You can override this behavior by specifying a specific 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 Windows CMD shell:

cafex discrun -e wumad:<image> [<RPX-app>]

Where <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:

cafex discrun -e wumad:C:/temp/image.wumad

Similarly to the -e h:<n> option, if you want to run the DEBUG version of the application, use the corresponding version of the OS to launch it, which is performed with the -b option:

cafex discrun -b -e wumad:C:/temp/image.wumad

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

cafex discrun -e wumad:C:/temp/extractedImageDir/ application.rpx

Debugging a master image archive using the PC

cafex discrun -b -d multi -e wumad:game.wumad -k <path>/game.elf

This command line will debug the master image using the application's .elf file. It is necessary to specify the .elf to debug a wumad by using the -k option. Typically, the .elf file is located in the same directory as the .rpx created during a build. Also see Debug a wumad File for more information on debugging master archive images.

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:

cafex discrun -e ejectstate:out application.rpx

OR

cafex discrun -e ejectstate:in application.rpx

A state of out will emulate the disc being ejected at boot time. Unless you press the EJECT button on front of the CAT-DEV unit, the system will generate a fatal error 160-0101 after 60 seconds.

NOTE:
As of HostBridge software 3.2.6.8 and CAT-DEV firmware version 0.0.14.80, the ejectstate will always be set to in unless otherwise specified. If you have an older version, this ejectstate setting 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
cafex run
Hard-disk Based Emulation
Environment Settings
File System Overview
Default System Devices
Cafe LEDs
Debug a wumad File

Revision History

2015/06/15 Added information on debugging wumads
2014/06/26 Return values added.
2014/06/12 Launching a wumad will auto-mount to ODD unless otherwise specified
2014/03/17 Initial version.


CONFIDENTIAL