BREW Overview

Hello all,


Some Acronyms:

1. BREW - Binary Runtime Environment For Wireless.
2. AEE - Application Execution Environment.
3. MIF - Module Information File.
4. BRI - Binary Resource Intermediate.
5. BAR - BREW Applet Resources.
6. BAM - BREW Application Manager.
7. BCI - Binary Compressed Image.
8. DLL - Dynamic Link Libraries. 
9. BID - BREW ClassID.

Some important header files usage:

1. AEEAppGen.h : Contains declerations that AEEClsCreateInstance() needs in order to instantiate our module and applet.
2. AEEShell.h : Contains support for the IShell services that the application will need throught out its life cycle.
3. AEEFile.h : To provide file support.

About BREW:
BREW - Binary Runtime Environment For Wireless.Qualcomm's BREW is hardware platform, originally intended as internal library for developing software on their own custom handsets.


Components that are available in BREW SDK:

1. BREW Application Execution Environment : Provides the foundation for BREW applications.
2. Set of tools : MIF editor, Resource Editor, Emulator, and Device Configurator.
3. BREW header files.
4. BREW Utilities : PureVoice Converter,2Bit Tool,NMEA Logger.
5. Add-ins to microsoft Visual Studio : Application Wizard, Automated ARM compiling, BREW Integrated Help.
6. Some example apps.
7. Online help.

Contents of BREW Tools:

1. Resource Editor.
2. MIF editor.
3. BCI Authoring Tool.
4. AppLoader.
5. AppLogger.
6. AppSigner.

BREW simulator:
It simulates a selected hand held device.


BREW application wizard:

It is included in 1.1 on and this does not exists in 1.0.This application wizard sets most of the applicable project options and produces the minimal skeliton code for a BREW application, assuming you are intended to develop in C.
Brew Application Wizard is an add on to Microsoft Visual Studio which creates following file:

1. Project File(appname.dsp).
2. Workspace File(appname.dsw).
3. Application source file(appname.c).
4. AEEAppGen.c and AEEModGen.c that are included with the BREW SDK.

About MIF:
MIF(Module Information File) that is created with MIF editor.
It contains information about the contents of the module:

1. Supported classes.
2. Supported applications.
3. Application privileges.
4. Application details.
5. Author of the application

Note : Without MIF, BREW will act like your application does not exists.


About resource editor:

The resource editor is made up of two integrated parts : The Resource Editor, Resource Compiler.Serves as a repository for the application's strings, images and dialog resources.The resource editor stores all of the entered resources in BREW Resource Intermediate(.bri) file.BRI is resource editors native format.

The Resource editor compiles the resource contained in the .bri into a binary BREW Applet Resource(.bar) file.The application will programatically load resources at runtime.
Usage : Resources files are useful for storing language-specific strings, dialogs, and bitmaps.If you need to localize your application for use in a target device in a different language, you simply need to translate the resources in the resource file.It is not necessary to recompile the MOD or DLL file.

Development Environment:
Any development environment  which can generate window's compliant dynamic link libraries is suitable for developing BREW applications which will execute on the simulator.

About BREW application:
In BREW, an application is a class that can only have one instance(singleton). BREW loads and creats a module only once - regardless how many times it required, because loading a module is expensive process.
Loading a module requires  

1. Updates to system tables about "what classes are available".
2. Brings executable from disk and allocates ancillary support structures.

BREW Applications are entirely event driven.

The basic elements of BREW application are :-

1. BREW classes.
2. BREW shell.
3. Module.
4. Applet.
5. Event handler.
6. Class IDs.
7. Resources.
8. Module Information Files(MIF).

BREW API:

Represents a group of interface classes with their own set of functions to use in your applications.BREW interface are initialized and memory is allocated only when the interface is needed.Each inteface has a unique ClassID, and the name of each interface in the BREW API begins with the letter I.

Application Execution Environment (AEE):

AEE foundation of BREW,which is responsible to load and execute BREW applications.

BREW Shell (IShell):

The BREW shell(IShell) is an interface,whcih is loaded when your application first runs.IShell permits access to a wide variety of lower-level services provided by the device.

About BREW Module:
A BREW  Module is a container for all of the applications functionality.
A BREW Module is a binary file containing the code for applications or extensions.
A BREW Module - as applications and extentions - are the fundamental units of code loading / contains implementation of multiple classes. It is a unique instance of IModule interface, to create a module one have to implement IModule interface.
This is accompanied by a module information file.This provides info regarding the classes your module contain.
But normally we dont do this, because Qualcomm provides a helper file AEEModGen.c. Which does this for us.

The module is loaded by the BREW shell.Fundamentally this module exports single entry point so that the BREW shell can call into your application's CreateInstance function.
CreateInstance - creates an event handler, allocates application memory and creates an instance of the IDisplay interface etc.

Event Handler:

Since BREW application model is event-driven programming model,this must contain an event handling  function.After application is loaded , the BREW layer passes all input to this function as events.In BREW, substantial delays in processing events may result in the application being shutdown to safeguard the device.

BREW Class IDs:

Class IDs are a unique 32-bit ID identidying BREW applications, BREW extensions, privilege levels, or BREW interfaces.This ClassID is stored in a BREW ClassID(BID) file.

About Applet:
Terms "Application" and "Applet" are interchangeable.
An "Applet" is a discrete unit of functionality that the module loads and the AEE executes.

About AEEApplet:

AEEApplet is a typedef for a struct.This structure contains key information about the applet.

1. m_pIShell : IShell pointer that provides access to the applet with shell services. 
2. m_pIModule : IModule pointer that keeps track of the module that "owns" the applet.
3. m_pIDisplay : IDisplay pointerthat gives the applet the ability to write to the screen.
4. pAppHandleEvent : A pointer to the applet's event handling function.
5. pFreeData : A pointer to a function that frees all of the applets dynamically allocated data  

Difference between Applet and Module:

A module may consists more than one applet, but only one applet can be active at a time(because BREW is single - threaded ). For example single module can have two applets in it with different class ids.

BREW Application entry points:
When the user selects the application icon in the BREW Application Manager, the AEE kicks off the entire process by calling AEEMod_Load() and AEEMod_CreateInstance().

NOTE:

1. In the emulator, AEEMod_Load is exported from the modules DLL.
2. In some production environments internal to QUALCOMM, the entry point is module_main.
3. In all other cases, for OTA configuration, the entry point is AEEMod_Load, and its declared the enttry point during the link process.

About  AEEModGen.c file provided by Qualcomm:

AEEModGen.c contains reference source code for modules.

AEEModGen.c also implements four methods of IModule interface.

1. CreateInstance : BREWinvokes this method when it needs an instance of a class provided by the module.From here we will call AEEClsCreateInstance method.
2. FreeResources : This method frees additional resources consumed by the module prior to its destruction.
3. AddRef : This method increments modules ref count.
4. Release : This method decrements ref count and when it reaches to 0 it frees the module.

In AEEModGen.c AEEMod_Load is really just wrapper function for AEEStaticMod_New, which is the function static builds invoke when creating static modules.This function is much like AEEClsCreateInstance for any class, with two key differences - it must accept pointers to creation and destruction functions when invoked during static builds.

About  AEEModGen.c file provided by Qualcomm:

In our code after the class ID check is done then AEEApplet_New() method will be called, whcih is defined in AEEAppGen.c. Its main function is to allocate memory for, and populate, the AEEApplet instance and then add it to the module by calling AEEMod_ListAdd().

Creating sub class of IModule:

The data structure that represents the IModule subclass instance:
typedef struct _SSingletonModule
{
//Declaring the virtual table for this class,whcih implements IModule.
DECLARE_VTABL(IModule)
//Ref count
uint32      nRefs;
//Pointr to the system shell.
IShell      *pIShell;
//Required for static extentions and are unused for OTA applications.
PFNMODCREATEINST  pfnModCrInst;
PFNFREEMODDATA    pfnModFreeData;
//Our singleton pointer.
SSingletonModule *pInstance;
}SSingletonModule;


Diff between static application and dynamic application:
Static applications:
1. Built into the OEM software build.
2. Can not be deleted but can be upgraded.

Dynamic applications:
1. Downloaded OTA or preloaded at the factory.
2. Have dynamically loaded MOD file.
3. Can be upgraded, deleted, recalled.