Overview Release Note User Interface Compression Rate Quick Guide Concept How It Works User's Manual Free Trial Pricing Buy Maintenance Contact Us

What is SophiaCompress(BREW) EARTH ?

SophiaCompress(BREW) EARTH is the world's first compression tool for BREW applications that minimizes the size of thier mod files.

System Requirements

Brew MP	Brew MP SDK 1.0
BREW	BREW SDK 4.0 / 3.1 / 2.1 / 2.0 / 1.1 / 1.0
Windows	Windows 7 / XP

Compression Methods

In SophiaCompress(BREW) EARTH, three kinds of compression methods called as "Direct Compression", "Separate Compression", and "Fork Compression" are available.

The BrewMP / BREW version, applet, and extention that each compression method supports are as follows:

• Direct Compression supports the BrewMP 1.0 / BREW 4.0 - 1.0 applet and the BrewMP 1.0 / BREW 4.0 - 1.0 extension.
• Separate Compression supports the BrewMP 1.0 / BREW 4.0 - 1.0 applet and the BrewMP 1.0 / BREW 4.0 - 3.1 extension.
• Fork Compression supports the BrewMP 1.0 / BREW 4.0 - 1.0 applet.

BrewMP / BREW version, applet, and extention that each compression method supports

Compression Method	BrewMP 1.0 / BREW 4.0 - 1.0 Applet	BrewMP 1.0 / BREW 4.0 - 3.1 Extension	BREW 2.1 - 1.0 Extension
Direct Compression	O	O	O
Separate Compression	O	O	X
Fork Compression	O	X	X

 SophiaCompress(BREW) EARTH: How it Works

Direct Compression

This method generates the new Compressed Module(.mod file from the Original Module(mod file). This Compressed Module is ready to be executed on the BREW device.

The compression ratio is 60-75 %.

At the runtime, first, the boot up module inside the Compressed Module is loaded on the device. Then it boots up the compressed module inside the Compressed Module, which then starts the application.

In case of the Direct Compression method, since the Compressed Module needs to be resident on heap at the run time, memory consumption is greater than other methods by this size. In general, it is recommended to use the Separate Compression or Fork Compression method except for the BREW 1.0 - 2.1 extension.

Separate Compression

This method generates the Boot up module(.mod file) and the Compressed mod(.scb file) from the Original Module(mod file). Both files must be installed on the BREW device.

The compression ratio is also 60-75 %.

At the runtime, first, the Boot up module is loaded on the device. Then it boots up the Compressed mod, which then starts the application.

*1. Limitation: The length of the Compressed mod file name must be less than 127 characters.

*2. For BREW 1.x / 2.x extensions, only the Direct Compression is supported.

*3. The file priviledge needs to be set to the mif file.

Separate Compression for the Brew MP 1.0 / BREW 4.0 - 3.1 Extension

mif file settings

When compressing Brew MP 1.0 / BREW 4.0 - 3.1 extension using the Separate Compression method, it is necessary to specify the extension's Class ID.

And it is also necessary to set the extension name.scb's ACL in the mif file's setting.

More specifically, in the mif's Access Control tab, set the followings:

    Path  : ExtensionName.scb
    Right : r (read authority)
    Group : 0x0 (everyone)

The above settings will enable an arbitrary BREW applet or extension to be able to access to the BREW extension compressed by the Separate Compression method.

*1. It is necessary to specify the Class ID (8-hexadecimal numbers) in the GUI or CUI only when compressing Brew MP 1.0 | BREW 4.0 / 3.1 extensions using Separate Compression.

*2. For BREW 1.x / 2.x extensions, the Separate Compression cannot be used. Only the Direct Compression is supported.

Fork Compression

This method generates the Boot up module(.mod file) and the Compressed mod(.scb file) from the Original Module(mod file) and the specified Plug-in module. Both files must be installed on the BREW device.

Different from the Separate Compression method, the Plug-in module will be embedded into the Boot up module. In general, in the Plug-in module, the code to draw the screen before or after booting up the application or when an error occurs will be described.

The Fork Compression method will be effective when an image or a text needs to be displayed since it takes several seconds to boot up the compressed BREW application.

The compression ratio is also 60-75 %.

At the runtime, first, the Boot up module including the content of the Plug-in module is loaded on the device. Then it boots up the the Compressed mod, which then starts the application.

*1. Limitation: The length of the Compressed mod file name must be less than 127 characters.

*2. The Fork Compression method does not support any BREW extension.

*3. The file priviledge needs to be set to the mif file.

*4. The Plug-in module does not need to be installed into the device, since it is embedded into the Boot up module.

License File

A license file called licence.dat, is issued through email by Sophia Cradle Incorporated.

A Host ID is required to inquire for a license file. Please use HostID.exe, in the same folder as SophiaCompress(BREW) EARTH, to obtain a Host ID.

Execute HostID from the SophiaCompress(BREW) EARTH folder.

* The above folder should be located at the following path by default.

• Product Edition: C:\Program Files\Sophia Cradle\SophiaCompressBREW\6.0
• Evaluation Edition: C:\Program Files\Sophia Cradle\SophiaCompressBREW Evaluation\6.0

Press the [Copy] button to copy the Host ID to the clip board.

Fill in the blanks below, and send it to .

Subject SophiaCompress(BREW) EARTH License file

Text:
Please send me license file for SophiaCompress(BREW) EARTH.

1. Host ID:
2. Company:
3. Name:
4. Phone Number:
5. Email Address:

FAQ: What is a license file? / FAQ: What is a host ID?

Startup

Put the license file(licence.dat) published by Sophia Cradle Inc., in the same folder as SophiaCompressBrew.exe.

* The above folder should be located at the following path by default.

• Product Edition : C:\Program Files\Sophia Cradle\SophiaCompressBREW\6.0
• Evaluation Edition : C:\Program Files\Sophia Cradle\SophiaCompressBREW Evaluation\6.0

Once the license file(licence.dat) is saved, double-clicking on SophiaCompressBrew.exe will boot up SophiaCompress(BREW) EARTH.

Using SophiaCompress(BREW) EARTH

Graphical User Interface (GUI)

1. Start up SophiaCompressBREW.exe.
2. Specify the name of the original module file in [Compressed File Name].
3. Select [BREW Version].
4. Select [Endian].
5. Select [Optimization]. If the speed optimization is selected, the boot-up speed will improve about 20% though the size of the compressed application will be a few percentage points of greater than the size optimization is selected.
6. Select [Compression type].
7. Specify [File suffix] for the suffix of the file compressed using the Separate or Fork Compression method. By default, it is "scb".
8. When compressing Brew MP 1.0 | BREW 4.0 / 3.1 extensions using Separate Compression, check the [Extension] check box, and enter the Class ID (8-hexadecimal numbers).
9. If the Fork Compression method is selected, specify the name of the plug-in module file in [Plug-in module], where processing such as displaying an image or a text on the screen while booting up the compressed application will be described.
10. Click the button labelled [Compress].
11. Specify the path to save the compressed file in the [Save As] window.
12. The processing dialog will be displayed during the compression.
13. If compression completes successfully, the module size after compression is displayed in green right next to [Module size]. If the size of the compressed module is greater than that of the original module, the size will be displayed in red right next to [Compression ratio].

The original mod file can also be dragged & dropped into the SophiaCompress(BREW) EARTH icon or to the compression window.

History Window

1. Select [View] -> [History] from the menu, then the History window will appear.
2. The History window shows the following information from the left side.
   • [Module Name]
   • [Plug-In Module Name]
   • [Module size before compression]
   • [Module size after compression]
   • [Compression ratio]
   • [Properties]
   • [Date and time]
   (*)If the module size after compression is smaller than before, the size and ratio will be displayed in green. Otherwise, in red.
3. To clear the history data, select [File] -> [Clear History] from the menu.

Command line User Interface (CUI)

The syntax for compression using SophiaCompress(BREW) EARTH through the CUI is as follows:

SophiaCompressBrew.exe -(direct | file | fork) [-(little | big)] -(brew10 | brew11 | brew2x | brew3x | brew4x | brewmp1x) [-(size | speed)] [-suffix xxx] [-clsid xxxxxxxx] [-plugin yyyyy.mod] [-ov] [-o destination.mod] source.mod

• -(direct | file | fork) selects the compression method. -file means Separate Compression. More than one of these options cannot be used simultaneously.
• [-(little | big)] specifies the endian of the CPU. Both options cannot be used simultaneously. When the option is omitted, it is interpreted as little endian.
• -(brew10 | brew11 | brew2x | brew3x | brew4x | brewmp1x) specifies the version of Brew being used. In the current version, both of the -brew4x and -brewmp1x options will generate the same compressed mod file.
• [-(size | speed)] selects optimization for module size or startup speed. Both options cannot be used simultaneously. When the option is omitted, it is interpreted as optimization for size.
• -suffix specifies the suffix of the file compressed using the Separate or Fork Compression. By default, it is "scb".(-suffix is valid only when -file or -fork are specified).[can be omitted]
• -clsid specifies the extension's Class ID in 8-hexadecimal numbers. (-clsid is valid only when -ext and -brew3x | -brew4x | brewmp1x and -file are specified).[can be omitted]
• [-plugin] sets the name of the plug-in module file. This option cannot be omitted when you choose the Fork Compression method.
• [-ov] allows the output compressed file to overwrite the original file with the same name.
• [-o...] sets the name of the compressed file.
• The order of the above options can be changed.
• source.mod specifies the name of the file to be compressed, and must be set at the end of all command line arguments.

*1 destination.mod is the name of the compressed module file.

*2 If an error occurs, the corresponding error message will be displayed. But no warning message will be displayed even if the compressed module size is bigger than before.

Increase of Heap Usage

Here, increase of heap usage at run time is described for each compression method.

Compressed mod generated by SophiaCompress(BREW) EARTH is extended onto heap of the mobile phone as the same module before compression(Original Module ) at run time.

Other than Original Module, Boot up Code is loaded onto heap too. Therefore, heap usage increases compared with when SophiaCompress(BREW) EARTH is not used.

* It should be noted that Compressed mod will be resident on heap other than Boot up Code and Original Module in the Direct Compression method. In general, except for the BREW 2.1 - 1.0 extension, it is recommended to use the Separate Compression or Fork Compression method where increase of heap usage is only Boot up Code.

Direct Compression

At run time, Boot up Code, Original Module and Compressed mod are allocated on heap.

Different from other methods, Compressed mod is allocated on heap.

* The logical size of the Boot up code is about 3 KB.

e.g. When the BREW application of 300 KB is compressed into 100KB, increase of heap usage will be 103 KB. Strictly speaking, it will be rounded up to the nearest multiple of cluster size. If cluster size is 4 KB, it will be 104 KB exactly.

Separate Compression

At run time, Boot up Code and Original Module are allocated on heap.

* The logical size of the Boot up code is about 3 KB, but the physical size will be 4, 6, or 8 kb depending on cluster size.

Fork Compression

At run time, Boot up Code and Original Module are allocated on heap.

It should be noted that Plug-in module will be embedded into Boot up Code.

(*) The logical size of the Boot up code is about 5 KB + [the size of the plug-in module]. However, the physical size will be rounded up to the nearest multiple of cluster size.

Using a plug-in project

The Fork Compression method requires the plug-in module to be executed before or after booting up the compressed application or when an error occurs, where processing such as drawing an image or a text will be described.

The sample plug-in project is stored into the plugin folder.

Contents of the plugin folder for the sample plug-in module

plugin/
    plugin.h              // header file
    plugin.c              // source file
    plugin.mod            // plug-in mod file
    plugin_rvctb12.mak    // makefile for RVCT for BREW 1.2 
    plugin_rvctb30.mak    // makefile for RVCT for BREW 3.0
    plugin_gnuarm.mak     // makefile for GNUARM 4.1.1
    plugin_yagarto.mak    // makefile for YAGARTO 4.4.2
    elf2mod.x linker      // script for GCC

Contents of the plugin.h

In the plugin.h, the DrawTypeEnum enumeration type, the ForkApplet structure, and the Draw function are defined or declared as follows:

#ifndef _PLUGIN_H
#define _PLUGIN_H

#include <AEEShell.h>
#include <AEEStdLib.h>

// timing when the Draw function is called
enum DrawTypeEnum {
     DRAW_START  = 0, // just before extraction
     DRAW_LOOP,       // [*Reserved] during extraction
     DRAW_FINISH,     // just after extraction
     DRAW_ERROR       // when an error occurs during extraction
};

// * Currently, DRAW_LOOP can NOT be used 
//   and is reserved for future enhancement.


// AEEApplet structure for the boot up module
typedef struct ForkApplet   ForkApplet;
struct ForkApplet {
    DECLARE_VTBL(IApplet)
    AEECLSID id;            // [for internal use] applet class ID 
    uint32 reference;       // [for internal use] reference counter
    IShell* shell;          // pointer to IShell
    IModule* module;        // [for internal use] pointer to IModule
    IDisplay* display;      // pointer to IDisplay
    AEEHelperFuncs* helper; // pointer to helper function
    int32 size;             // size of the ForkApplet structure
    int32 status;           // [for internal use] status
    int32 error;            // error during drawing
    int32 progress;         // [*Reserved] always -1 
    void* userdata;         // pointer to your own data structure
    void* reserved;         // [*Reserved] always NULL
};
// * Currently, the progress  and reserved members 
//   can NOT be used are reserved for future enhancement.

void Draw(ForkApplet* applet, int32 draw_type);

#endif//_PLUGIN_H

• The DrawTypeEnum enumeration type: timing when the "Draw" function will be called.
• The ForkApplet structure: AEEApplet structure for the boot up module.
• The Draw function: entry point of the plug-in module. This function takes two arguments, a pointer to the ForkApplet structure, and a value of the DrawTypeEnum enumeration type and draws something on the screen. The drawing content will depend on the passed value.

*NOTE 1 The variables for internal use such as id, reference, module, or status must not be updated, since it might cause unexpected behavior.

*NOTE 2 Any global variable must not be used in the plug-in module.

*NOTE 3 It is possible to allocate memory area from heap for your own data structure and use it via the userdata variable to be set to the pointer to this memory area. In this case, this memory area must be released by yourself.

Contents of the plugin.c

The plugin.c file implements the sample Draw function as follows:

#include "plugin.h"

void Draw(ForkApplet* applet, int32 draw_type)
{
    static AECHAR const     szText[] = {
        'L', 'o', 'a', 'd', 'i', 'n', 'g', '.', '.', '.', '\0'
    };

    applet->helper->dbgprintf(">> Draw: %d", draw_type);

    switch (draw_type) {
        case DRAW_START:
            IDISPLAY_DrawText(applet->display,
                AEE_FONT_BOLD,
                szText,
                -1,
                0,
                0,
                NULL,
                IDF_ALIGN_CENTER | IDF_ALIGN_MIDDLE
            );
            IDISPLAY_UpdateEx(applet->display, FALSE);
            applet->error = SUCCESS;
            break;
        case DRAW_ERROR:
            break;
        case DRAW_LOOP:
        case DRAW_FINISH:
        default:
            break;
    }

    applet->helper->dbgprintf("<< Draw: %d", draw_type);

    return;
}

The sample code draws the "Loading..." string at the center of the screen just before extraction. Drawing have to be performed by using the display variable of the ForkApplet structure.

When drawing is finished successfully, you should assign the SUCCESS value to the error variable of the ForkApplet structure.

In the Draw function, any BREW helper function macro must not be used. However, you can call the BREW helper function via the helper variable of the ForkApplet structure instead. In this case, the BREW helper function name is usually in lower-case.

For instance, in the above sample code, the dbgprintf function is used via the helper variable of the ForkApplet structure instead of the DBGPRINT macro in order to output a debug string.

Building the plug-in project

To build the plug-in project, install the nmake tool of Microsoft Visual Studio and set the necessary environment variables such as the BREW SDK path or the compiler's bin / include / library folder properly.

The environment variables in the sample makefile, which varies depending on the kind of compiler, are as follows.

[Common environment variable]
BREWDIR            path of the folder of BREW SDK

[RVCT for BREW 1.2]
ARMHOME            path of the home folder of RVCT for BREW 1.2

[RVCT for BREW 3.0]
ARMBIN             path of the bin folder of RVCT for BREW 3.0
ARMINC             path of the include folder of RVCT for BREW 3.0
ARMLIB             path of the library folder of RVCT for BREW 3.0
ELF2MOD_TOOL_PATH  path of the bin folder of BREW Elf2Mod

[GNUARM 4.1.1]
GNUARM41HOME       path of the home folder of GNUARM 4.1.1
ELF2MOD_TOOL_PATH  path of the bin folder of BREW Elf2Mod

[YAGARTO 4.4.2]
YAGARTO44HOME      path of the home folder of YAGARTO 4.4.2
ELF2MOD_TOOL_PATH  path of the bin folder of BREW Elf2Mod

*NOTE* Each of RVCT for BREW 3.0, GNUARM 4.1.1, and YAGARTO 4.4.2 requires BREW Elf2Mod 1.0.2 available at the QUALCOMM's web site. To download this tool, you have to be certified as Brew Developer.

Build

To build the plug-in module, you have only to execute the following command.

nmake /f plugin_xxxxx.mak

The name of the plugin_xxxxx.mak file as the sample makefile varies among the following strings depending on the kind of compiler.

• plugin_rvctb12.mak (in case of RVCT for BREW 1.2)
• plugin_rvctb30.mak (in case of RVCT for BREW 3.0)
• plugin_gnuarm.mak (in case of GNUARM 4.1.1)
• plugin_yagarto.mak (in case of YAGARTO 4.4.2)

The sample makefile will generate the plugin.mod file, which will be specified as the plug-in module in case of the Fork Compression method.

Restrictions

Using the Standard Boot Module of Brew MP SDK or BREW SDK

A module built with AEEModGen.c, the standard boot up module of Brew MP 1.0 | BREW SDK 4.0 / 3.1 / 2.1 / 2.0 / 1.1 / 1.0, can be compressed and executed without problem by SophiaCompress(BREW) EARTH.

SophiaCompress(BREW) EARTH does not support BREW applications developed with boot up modules other than AEEModGen.c, and we do not guarantee performance with non-standard modules.