Required Port-Specific Files and Functions

Chapter 4 Required Port-Specific Files and Functions

This section describes those files and functions that must be defined for each port.

4.1 File machine_md.h

Every KVM port must provide a file named VmPort/h/machine_md.h. The purpose of this file is to override the default compile time definitions and declarations provided in VmCommon/h/main.h, and supply any additional definitions and declarations that your specific platform might need. See Chapter 6, “Compilation Flags, Definitions and Macros” for a list of the definitions and declarations that your port will often need to override.

All port-specific declarations, function prototypes, typedef statements, #include statements, and #define statements must appear either in this machine_md.h, in a file included directly or indirectly by machine_md.h, in some file automatically included by your development environment,1 or via compiler switches.2

Port-specific functions can appear in any machine-specific file. Unless otherwise stated, any required port-specific function can also be defined as a macro, provided that its implementation is careful to ensure that each argument is evaluated exactly once.

4.2 File main.c

You will generally need to provide a new version of main.c that is suitable for your target platform. The default implementation provided in directory VmExtra/src/main.c can be used as a starting point for platform-specific implementations. Refer to Chapter 7, “Virtual Machine Startup,” for further information.

4.3 Runtime functions that require porting efforts

Each port must define the functions given below (see VmCommon/h/runtime.h). They may be defined as either macros or as C code. Traditionally, the C code is placed in a file named VmPort/src/runtime_md.c

void AlertUser(const char* message)

Alert the user that something serious has happened. This function call usually precedes a fatal error.

cell *allocateHeap(long *sizeptr, void **realresultptr)

Create a heap whose size (in bytes) is approximately the long value *sizeptr. The heap must begin at an address that is a multiple of 4. The address of the heap is returned as the value of this function. The actual size of the heap (in bytes) is returned in *sizeptr. The value placed into *realresultptr is used as the argument to freeHeap when freeing the heap.

For most ports, *realresultptr will be set to the actual value returned by the native space allocation function. If this value is not a multiple of 4, it is rounded up to the next multiple of 4, and *sizeptr is decreased by 4.

void freeHeap(void *heapPtr)

Free the heap space that was allocated using allocateHeap. See above for the meaning of the heapPtr argument.

void GetAndStoreNextKVMEvent(bool_t forever,

ulong64 waitUntil)

This function serves as an interface between the event handling capabilities of the virtual machine and the host operating system. (Defined in VmCommon/h/events.h.) See Chapter 12 for details.

void InitializeVM()

Initialize the virtual machine in whatever way is necessary. On many of the current ports, this is a macro that does nothing.

void InitializeNativeCode()

Initialize the native code in whatever way is necessary. Ports can use this function (for example) to initialize the window system and to perform other native-code specific initialization.

void InitializeClassLoading()

Initialize the class loader in whatever way is necessary. Ports can use this function (for example) to perform certain file/storage system initialization operations.

void InitalizeAsynchronousIO(void)

Initialize the system to handle asynchronous native methods.

void FinalizeVM()

Perform any cleanup necessary before shutting down the virtual machine.

void FinalizeNativeCode()

Perform any clean up necessary to clean up after the native functions. Many ports use this function to shut down the window system.

long RandomNumber_md()

Return a random number.

void FinalizeClassLoading()

Perform any cleanup necessary before shutting the class loader. Ports can use this function (for example) to perform certain file/storage system finalization operations.

ulong64 CurrentTime_md(void)

Return the time, in milliseconds, since January 1, 1970 UTC. On devices that do not support the concept of time zone, it is acceptable to return the time, in milliseconds, since January 1, 1970 of the current time zone.

unsigned long *Calendar_md(void)

Initializes the calendar fields, which represent the Calendar related attributes of a date.

The functions InitializeNativeCode() and InitializeVM() are called, in that order, before any global variables have been set and before the memory-management system has been initialized.

The function FinalizeVM() is called just before FinalizeNativeCode(). On those ports that have enabled profiling, the profiling information is printed out between the calls to these two functions. This allows the profiler to find out information about the window system, if necessary, and to use the window system for creating its output.

Note – If you want to use the KVM for running additional libraries such as those defined by the Mobile Information Device Profile (MIDP) or PDA Profile, additional porting work will be necessary to port the native functions required by those libraries.

Asynchronous native functions. If your port supports the use of asynchronous native methods, there are additional, port-specific functions that you must define :

yield_md() 
CallAsyncNativeFunction_md() 
enterSystemCriticalSection() 
exitSystemCriticalSection()

Note – The interfaces for functions enterSystemCriticalSection() and exitSystemCriticalSection() are defined in VmCommon/h/thread.h.

These functions are further described in §11.4.

4.4 Required C library functions

The KVM uses the following C library functions:

String manipulation: strcat, strchr, strcmp, strcpy, strncpy, strlen

Moving memory: memcpy, memove, memset, memcmp

Printing: atoi, sprintf, fprintf, putchar

Random number generation: rand

Exception handling: setjmp, longjmp (not absolutely necessary)

If your development environment does not supply definitions for these functions, you must either define them yourself, or use macros to map these names onto equivalent functions recognized by your development environment.3

The function memmove must be able to handle situations in which the source and destination overlap. The function memcpy is used only in those cases in which the source and destination are known not to overlap.

The functions fprintf and sprintf use the following formats: 
   %s, %d, %o, %x, %ld, %lo, %lx, %%

These formats never have options or flags.

There are no calls directly to printf.

Note – The components included in directory VmExtra and the machine-specific ports provided with this release may need additional native functions not listed above.

1Metrowerks CodeWarrior, for example, allows the user to create a prefix file.

2Some compilers allow you to add the switch -Dname=value, which is equivalent to putting
#define name value
at the start of the file.

3Be aware that the order of arguments may be different on different platforms. For example, the function memset takes arguments memset(location, value, count). The corresponding Palm OS function is MemSet(location, count, value).

KVM Porting Guide
, CLDC 1.1