Beginning a MIDP Port

This chapter describes the first steps in porting MIDP. By the end of the chapter, you will have a quick port of the MIDP Reference Implementation that compiles and should run the Hello MIDlet, but may not be fully functional. You will need to do additional work to complete the port and to tailor it for your device. The chapters after this one discuss those possibilities.

This chapter assumes familiarity with the MIDP overview described in the previous chapter and the MIDP 2.0 Specification. The MIDP specification is at http://jcp.org/jsr/detail/118.jsp.

2.1 Preparing to Port MIDP

Create source and build subdirectories for your device in the MIDP tree.

The directories to create are:

midpInstallDir\build\newPlatform

midpInstallDir\src\newPlatform

where newPlatform is the name for the directory that hold the files for your device. For example, if midpInstallDir was c:\midp2.0fcs and your device was deviceX, you would execute the commands:

    c:\midp2.0fcs\build> mkdir deviceX 
    c:\midp2.0fcs\build> cd ..\src 
    c:\midp2.0fcs\src> mkdir deviceX 
    c:\midp2.0fcs\src> cd deviceX 
    c:\midp2.0fcs\src\deviceX> mkdir native

Copy the code from the existing midpInstallDir\src subdirectory that most closely matches your system into your midpInstallDir\build\newPlatform directory.

For example, you could copy the files from midpInstallDir\src\solaris:

c:\midp2.0fcs\src> cp -r solaris/* deviceX

Copy the makefiles for an existing architecture into your midpInstallDir\build\newPlatform directory.

Copy:

GNUmakefile

platform.gmk

The makefiles directory and its contents

For example, you could copy the files from midpInstallDir\build\solaris:

c:\midp2.0fcs\build> cp solaris/GNUmakefile deviceX 
c:\midp2.0fcs\build> cp solaris/platform.gmk deviceX 
c:\midp2.0fcs\build> cp -r solaris/makefiles deviceX

Set configuration options in your platform’s makefiles.

See Appendix B, “Configuration Options” configuration options that you might need to set for porting. Typical options that need updating are:

Compiler flags

GCC

PLATFORM

MIDP_EXCLUDE_CLASSES

MIDP_INCLUDE_SRC

_BOOTDIR

Configurable build parameters, such as DEBUG

For example, to make the value of the PLATFORM option deviceX, you would update the PLATFORM definition in the c:\midp2.0fcs\build\deviceX\platform.gmk file to:

PLATFORM = deviceX

If you have already ported CLDC, use those makefiles as a guide.

Set targets in your platform’s makefiles.

The makefile targets have the MIDP executable run inside the device emulator with debugging symbols, without debugging symbols, with profiling code, and so on. See Appendix A, “Build Targets” for a list of existing targets. You might want to add targets that include or exclude device-specific features, such as optional communication protocols.

2.2 Porting Device-Specific Configuration Code

Implement the heap allocation macros.

There are five allocation macros for managing the memory of the native heap:

midpMalloc

midpCalloc

midpRealloc

midpStrdup

midpFree

The macros are defined in midpInstallDir\src\share\native\midpMalloc.h. Change the definitions of these macros, if necessary, to work with your device.

Note – Always use these macros to manage memory from the heap in any native code you write.

Update native calls.

The files with native calls are in the following directories:

midpInstallDir\src\share\native

midpInstallDir\src\newPlatform\native

For example, if your system does not support a native call, substitute in a call that has the same functionality, or create a stub for it. To create a stub, comment out or remove the function body that contains the call, and substitute a print statement. One way to find these calls is by trying to build MIDP to see which calls prompt errors. (For instructions on building MIDP, see Using MIDP.) The errors could look something like this:

/tmp/ccTk6mVS.o(.text+0x7): undefined reference to `LCDUIdrawLine'

The stub that you create for the call could look something like this:

LCDUIdrawLine(...){ printf("in LCDUIdrawLine stub\n"); }

This step enables you to quickly get your port compiling. As you go through the chapters that follow, you will fill in the stubs as you port each module.

Update the destination of debugging output, if necessary.

Ensure that the printf function sends its output to a location from which it is easy for you to collect information. For example, one such destination might be the debug port of your emulator. (If you have already ported CLDC, this step should already be done.)

2.3 Trying It Out

Build a ROMized version of MIDP.

In the MIDP Reference Implementation, the midp target in the build environment builds a ROMized version of MIDP. If you have not changed this aspect of the makefiles, then you would be able to use a command such as this:

c:\midp2.0beta\build\deviceX> make midp

For instructions on building MIDP, see Chapter 12, “Building Your Port.”

Create the following simple version of the Hello MIDlet to run on the device.

The following version of the HelloMIDlet does not use any graphics. It prints simple messages to the serial port of the device:

import javax.microedition.midlet.*; 
  
public class HelloWorld extends MIDlet { 
    public HelloWorld() { 
        system.out.println(“In HelloWorld constructor”); 
    } 
  
    public void startApp() { 
        System.out.println(“In HelloWorld startapp”); 
    } 
  
    public void pauseApp() { 
    } 
  
    public void destroyApp(boolean unconditional) { 
    } 
  
}

Build and package the MIDlet as described in Creating MIDlet Suites.

Run the MIDlet as described in Using MIDP.

Chapter 2