cafex run - Run Specified Application

Syntax

cafex run [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.
-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.
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 run command boots Cafe and runs the specified application (RPX or RPL).

Examples

Run an RPX Application

To run an RPX application that does not acquire and load RPL dynamic libraries, use the following call:

cafex run app.rpx

NOTE:
  • If there are two or more applications with the same Title ID and Title Version, cafex run <app>.rpx runs the installed application.
  • If two or more applications have the same Title ID, but the Title Version is different, cafex run <app>.rpx runs the application with the highest Title Version.

To run an application that is NOT the installed version but has the same Title ID and Title Version, use the -e option as follows:

cafex run -e mcp:launch_hint:hfiodisc <app>.rpx

Debug a Simple RPX Application

Specify DEBUG or NDEBUG System Libraries

System libraries are provided in two flavors of RPLs:

NDEBUG Debugging ASSERT calls are disabled in the NDEBUG versions. By default, cafex run loads and runs the NDEBUG versions of the system libraries.
DEBUG Debugging ASSERT calls are enabled in the DEBUG versions. Use the -b option to select the DEBUG version.

To receive ASSERT checks in the system libraries, run your application with -b option:

cafex run -b app.rpx

Pass Command-line Arguments

Command-line arguments can be passed to the application's main function via argc and argv. There are two methods:

IMPORTANT:
  • The following characters are not allowed in argument strings: ? | < > +
  • A maximum of 32 arguments is supported, including the name of the application.
  • The total length of all arguments, including string terminators, must not exceed 4095 characters.

Run an RPX Application with RPLs

When running an RPX application that uses RPLs, cafex run must know the location of all dependent RPLs.

By default, cafex run assumes that all necessary RPL files are located in the same directory as the RPX application.

To specify other locations, use the -l option:

-l [ <dir> | <dir>/<file>.rpl ]

Multiple -l options may be specified on the same command line.

Restart an RPX Application

To reboot the CAT-DEV and re-execute the previous RPX application (with the same options and arguments), call:

cafex run -r

Specify Special Runtime Options

You may use the -e option to specify special runtime options. For example, to view the contents of bank 3 on the internal HDD in System Config Tool:

cafex run -e h:3 %CAFE_ROOT%/system/bin/ghs/cafe/app/system_config_tool/base/NDEBUG/system_config_tool.rpx

Since cafex on launches the System Config Tool, this command is equivalent to:

cafex on -e h:3

Filter Cafe OS Log Messages by Severity

To control the quantity of Cafe OS log output from the Cafe shell, use the -v option:

cafex run -v <level>

These settings can also be controlled in the Other Setting submenu of the System Config Tool. For more information about filtering the log messages in other ways, see Filtering Log Output.

-K option

The -K option to run allows applications to be restarted in approximately four seconds, saving a tremendous amount of time.

To use -K (case sensitive) option follow the below steps. A built motionBlur demo, located in the demo patch, is required to follow this example exactly. Substituting any non-terminating application will also suffice.

  1. First run the RPX normally using cafex run. Example:
    cafex run $CAFE_ROOT/system/bin/ghs/cafe/demo/gx2/garden/motionBlur/NDEBUG/motionBlur.rpx
    
  2. Press CTRL+C in the command prompt to get the control back. Note that Cafe is still running at this time.
  3. The following command will kill and restart the application that was started in step 1. Note that it will neither reboot the system nor restart the OS and is a faster way to reload the application.
    cafex run -K
    
NOTE:
The kill-restart functionality only works for non-terminating applications. Attempting to use the command with terminating applications (such as the helloworld demo) will have a slower restart time.

See Also

cafex
Running Applications Overview
cafex discrun
Environment Settings
File System Overview
Default System Devices

Revision History

2014/08/22 Minor corrections to kill-restart information.
2014/06/26 Return values added.
2014/03/17 Initial version.


CONFIDENTIAL