Building a Custom RI From Sources

C H A P T E R 11

This chapter only applies if you have the source release. The src folder contains all the files that are only in the source release, including virtual machine (VM) code and all tools. The contents of the src folder are described in Contents of the Source Release.

You can modify the RI by adding or modifying its code. The RI consists of .java and C source files. The core VM is written in the C programming language and the rest of the API and supported implementation is written in the Java programming language.

You can modify or add to these files and build a customized Java Card 3 platform RI according to specific requirements. You might want to build a custom RI for the following reasons:

Add additional classes or packages if a proprietary API or other implementation classes are used.

Fine tune the existing sources.

Update the tools to work with a target platform.

Mask an application into cref.

Steps for Building a Custom RI

Before building a custom RI, the software listed in Prerequisites to Installing the Development Kit must be installed on the system.

The basic steps detailed later in this section to create a custom RI are as follows:

1. Converting your packages using the Converter tool and generating Java Card Assembly files, see Chapter 5.

For example, the output Java Card Assembly (.jca) files could be located at:

.\api_export_files\com\sun\javacard\installer\javacard\installer.jca

JC_CLASSIC_HOME\samples\classic_applets\HelloWorld\applet\build\classes\com\sun\jcclassic\samples\helloworld\javacard\helloworld.jca

2. Adding the location for the Java Card Assembly files for your new packages in these files:

src\vm_16.in

src\vm_32.in

This step is required for new packages. If you are modifying existing packages, this step is not required.

3. Building the cref executable.

See Building the 32-Bit Custom RI, and if necessary Building the 16-Bit Custom RI.

The new cref is built with the new packages masked in. Masked applications can be instantiated without requiring download after the runtime environment starts up.

4. Testing the custom RI.

See Testing the 32-Bit Custom RI and if necessary Building the 16-Bit Custom RI.

Building the 32-Bit Custom RI

Note - The following procedure builds the 32-bit version of the RI. To build the 16-bit version first see Building the 16-Bit Custom RI.

1. Edit the files or add more files.

2. Update the tools source code, if required.

3. From the command line, navigate to the src folder and run the ant all command.

The ant all command creates the JC_CLASSIC_HOME\custom_build folder with a bin and lib folder under it.

The custom_build\bin directory contains the new cref and all of the other .bat files for the tools.

The custom_build\lib folder contains the .jar files and configuration files.

Testing the 32-Bit Custom RI

1. Run the new cref file stored in JC_CLASSIC_HOME\custom_build\bin noting the expected console output in EXAMPLE 11-1 and its specific reference in the content to the 32-bit Address Space.

JC_CLASSIC_HOME\custom_build\bin\cref_tdual.exe [options]

See Chapter 9 for a description of the available options for cref.

Files created as a result of running or building the custom RI are stored in the JC_CLASSIC_HOME\custom_build\bin and JC_CLASSIC_HOME\custom_build\lib directories. These directories are created the first time the custom RI is built and are over-written every time the custom RI is built.

2. Run apdutool in a separate window to send in your apdu scripts to cref.

apdutool -nobanner -noatr filename.scr > filename.scr.cref.out

For information on apdutool, see Running apdutool. If the run is successful, the apdutool.log, filename.scr.cref.out, is identical to the file filename.scr.expected.out.

EXAMPLE 11-1 Expected Console Output When Building 32-Bit Custom RI
Java Card 3.0.3 C Reference Implementation Simulator 32-bit Address Space implementation - with cryptography support T=1 / T=CL Dual interface APDU protocol (ISO 7816-4) Copyright (c) 2010 Oracle Corporation All rights reserved. Use is subject to license terms. Memory configuration Type Base Size Max Addr RAM 0x0 0xc78 0xc77 ROM 0x2000 0xc800 0xe7ff E2P 0x10020 0xffe0 0x1ffff ROM Mask size = 0x8b3e = 35646 bytes Highest ROM address in mask = 0xab3d = 43837 bytes Space available in ROM = 0x3cc2 = 15554 bytes Mask has now been initialized for use

EXAMPLE 11-1 Expected Console Output When Building 32-Bit Custom RI

Java Card 3.0.3 C Reference Implementation Simulator
32-bit Address Space implementation - with cryptography support
T=1 / T=CL Dual interface APDU protocol (ISO 7816-4)
Copyright (c) 2010 Oracle Corporation All rights reserved.
Use is subject to license terms.
 
Memory configuration
        Type    Base    Size    Max Addr
        RAM     0x0     0xc78   0xc77
        ROM     0x2000  0xc800  0xe7ff
        E2P     0x10020 0xffe0  0x1ffff
 
        ROM Mask size =                 0x8b3e =        35646 bytes
        Highest ROM address in mask =   0xab3d =        43837 bytes
        Space available in ROM =        0x3cc2 =        15554 bytes
Mask has now been initialized for use

Building the 16-Bit Custom RI

By default the procedure described in Building the 32-Bit Custom RI builds the 32-bit cref. To build cref with 16-bit support you must modify those steps as follows:

Note - Building the 16-bit version creates only one cref_t0.exe file with no t1 or tdual version, so the resulting cref.bat file executes only cref_t0.exe.

1. Before starting, clean any previous builds by running ant clean.

2. When executing ant all, set this property: for.bit=16, with the following modified command:

ant -Dfor.bit=16 all

3. When testing the 16-bit build, execute cref.bat from the custom_build/bin directory and watch for the expected output depicted in EXAMPLE 11-2 noting its specific reference in the content to the 16-bit Address Space.

EXAMPLE 11-2 Expected Console Output When Building 16-Bit Custom RI
Java Card 3.0.3 C Reference Implementation Simulator 16-bit Address Space implementation - with cryptography support T=0 Extended APDU protocol (ISO 7816-3) Copyright (c) 2010 Oracle Corporation All rights reserved. Use is subject to license terms. Memory configuration Type Base Size Max Addr RAM 0x0 0x600 0x5ff ROM 0x600 0xbc00 0xc1ff E2P 0xc200 0x3be0 0xfddf ROM Mask size = 0x9fb0 = 40880 bytes Highest ROM address in mask = 0xa5af = 42415 bytes Space available in ROM = 0x1c50 = 7248 bytes Mask has now been initialized for use

EXAMPLE 11-2 Expected Console Output When Building 16-Bit Custom RI

Java Card 3.0.3 C Reference Implementation Simulator
16-bit Address Space implementation - with cryptography support
T=0 Extended APDU protocol (ISO 7816-3)
Copyright (c) 2010 Oracle Corporation All rights reserved.
Use is subject to license terms.
 
Memory configuration
        Type    Base    Size    Max Addr
        RAM     0x0     0x600   0x5ff
        ROM     0x600   0xbc00  0xc1ff
        E2P     0xc200  0x3be0  0xfddf
 
        ROM Mask size =                 0x9fb0 =        40880 bytes
        Highest ROM address in mask =   0xa5af =        42415 bytes
        Space available in ROM =        0x1c50 =        7248 bytes
Mask has now been initialized for use