caferun - Load and Run Application on CAT-DEV

Syntax

$ caferun [<option>...] [<app>.rpx] [<arg>...]

Options

-a "<arg1>,<arg1>,..." Pass command line arguments <arg1>, <arg1>, ... 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.
-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.

-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 Toggle the eject state of the emulated ODD between DISC_IN and DISC_OUT. For more information, see Adjusting the Disc’s Eject State in cafediscrun.
h:<n> Mount HDD bank <n> when launching the application. Valid values for <n> range from 0-10, inclusive.
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.

Description

caferun is a host PC tool that loads and executes a Cafe application on the CAT-DEV.

The tool is invoked from the command line of a Cafe Cygwin shell.

NOTE:
The caferun command may choose any title instance to run when multiple titles with the same titleID are installed.
  • The search order depends on a number of factors that are not necessarily repeatable, including storage device attachment order.
  • To run a specific instance of a title, include the following option to the caferun command, selecting the desired device:
    -e mcp:launch_hint:{hfiomlc,hfiodisc,mlc,odd,sddisc,sdio,usb}
    

Examples

Run an RPX Application

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

$ caferun app.rpx

NOTE:
  • If there are two or more applications with the same Title ID and Title Version, caferun <app>.rpx runs the installed application.
  • If two or more applications have the same Title ID, but the Title Version is different, caferun <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:

$ caferun -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, caferun 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:

$ caferun -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, caferun must know the location of all dependent RPLs.

By default, caferun 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 re-execute the previous RPX application (with the same options and arguments), call:

$ caferun -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:

$ caferun -e h:3 $CAFE_ROOT/system/bin/ghs/cafe/app/system_config_tool/base/NDEBUG/system_config_tool.rpx

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

$ cafeon -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:

$ caferun -v <level>

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

See Also

Running Applications Overview
cafediscrun
Environment Settings
File System Overview
Default System Devices

Revision History

2014/09/24 Added additional launch hints.
2014/03/18 Added -k option details.
2014/02/12 Added -v argument details.
2014/01/02 Added list of -e arguments
2013/05/08 Automated cleanup pass.
2013/03/13 Editorial updates.
2011/07/21 Initial version.


CONFIDENTIAL