Patching Linker Guide

This utility is available only with Rational Apex Embedded for Rational Exec.

---

Using the Patching Linker

An application is initially linked using the normal Apex linking mechanism. After compiling modifications to your application, a patch of the original VOX executable can be made by adding the DIFF option to your linker description file and re-linking. This produces a new VOX executable that is linked so that differences between the two VOX files are minimized.

A diff utility, apex_pl_diff, can be used to generate an S-record file of the differences between the original and the new VOX executables. The patching utility, apex_pl_patch, can then be used on the original VOX file and the file of diffs to produce a patched VOX file that simulates on the host machine the patching that you do on your target. The comparison utility, apex_pl_compare, can now be used to compare the patched VOX file with the new VOX file produced by the patching linker.

Several new options have been added to the linker description file that help subsequent patches work more efficiently. On subsequent patching links, if a subprogram or data object has grown beyond its previous size, the patching linker may be forced to move the object. The PAD options allow the user to specify the amount of padding to be allocated on the initial link between subprogram or data objects. When insufficient space is available in the allocated pad areas, the patching linker creates new groups that contain moved subprograms or data.

The Binary Diff Program - apex_pl_diff

After running the linker in patch mode (using the DIFF old_vox_file option) a new VOX file new_vox_file is created. The binary diff tool, apex_pl_diff, is run as follows:

apex_pl_diff [-p<n>] [-v] <old_vox_file> <new_vox_file> > <diff_file>

It finds the differences between the old and new program images and produces an annotated Motorola S-Record patch file. This file gives instructions about how to modify the most recently created program image to transform it into the new program image. Comments are included in the patch file to help identify the regions of code being patched. The -v option produces greater detail in the comments.

When following the preserve model (described in Preserved Patching Model2) it is useful to invoke apex_pl_diff with the -p option. This option tags the S-records that modify memory used in the original image with a # MODIFY comment, and those that simply initialize memory unused in the original image with a # NEW comment. Additionally suggested MOVE directives are generated in comments when modifications of a subprogram or data section exceed a move threshold of 10%. This move threshold can be modified to be n% by invoking apex_pl_diff with -p<n>.

The Binary Patch and Compare Programs - apex_pl_patch/apex_pl_compare

The patch file generated by apex_pl_diff may be applied to the previous VOX executable by using the binary patch program, apex_pl_patch:

apex_pl_patch <old_vox_file> <diff_file> -o <patched_vox_file>

This facility and the binary compare program, apex_pl_compare, are provided mainly as a way of testing the correctness of the patch file. It is left to you to find a way of applying the S-Record patch file in your application.

patched_vox_file is a generated VOX file that is virtually identical to new_vox_file that was produced by the patching linker. patched_vox_file can be executed on the target but symbolic debugging of it is severely limited; debugging the new_vox_file is preferred because it contains complete debugging information.

The binary comparison program, apex_pl_compare, can be used to compare patched_vox_file and new_vox_file and verify that application of the diff_file patch produces an image on the target that is identical to the new_vox_file. This gives us confidence that new_vox_file can be used as the basis of subsequent patching links.

apex_pl_compare only produces output if there is a difference between the two VOX executables.

---

Options and Features Added To the Syntax Of a Linker Description File

DIFF and PRESERVE Options

The DIFF option is used to put the linker into patch mode. It identifies a previously linked VOX executable to use as a guide when linking the current image. The goal of the patching link is to match up the external symbols of the new image as much as possible with the old image with the expectation that this results in fewer differences when generating a patch of the old VOX file.

The PRESERVE option tells the linker to follow the Preserved Patching model described in Preserved Patching Model.

For example,

OPTIONS
   DIFF /some_path/previous/main;
   PRESERVE;
END OPTIONS;

Note: You can put a local linker description file, main_program.des, in the directory where you link your application and it overrides the global linker description file.

Move a Subprogram

The MOVE option can be used to force a subprogram to be moved even if it doesn't need to be moved. If an address is given with the MOVE option, the subprogram is moved to the given absolute address. Subprograms are moved only when doing a patching link as the MOVE option is ignored when doing a regular link.

The following options in a patching link force BZERO to be moved, __SUBP2 to be moved to the specified address, and the generated exception tables __EXCEPTION_TABLE to be moved.

OPTIONS
        MOVE BZERO;
        MOVE  __CLOSE_ALL 01200000;
        MOVE __EXCEPTION_TABLE;
END OPTIONS

Subprogram Move Efficiency

The Patching Linker efficiently moves subprograms or data objects. The cost of moving an object is its new size plus the size of all of the references made to the object. If an object has grown beyond its previous allocation it may be more efficient to move the next contiguous object to make room for expansion of the first.

Exclude Sections of Memory

You can specify memory that should not be used when linking. The MEMORY directive must follow the OBJECTS directive.

The following defines sections of memory that cannot be used for code or data:

MEMORY
  VOID 080204100 .. 080204200;
  VOID 080208000 .. 080208200;
END MEMORY;

The linker in either regular or patching mode lays out the image to avoid these memory locations. In patching mode, objects previously located in these memory locations are moved.

Control the Padding Between Subprograms

On the initial link of the program, padding can be inserted between text sections (subprograms) or data sections with global padding options or with a padding specification on a particular group's FOR clause. The padding specification can be either be an absolute pad size or a percentage of the corresponding group or section.

Default Global Padding Options

A global padding option can be used to specify padding for all groups of a specified type (Text, Const, Data, Bss). The global padding option is used also when new groups are created for moved subsections.

To pad each subprogram by 50%, and pad all data subsections by 50 bytes:

OPTIONS
     PAD TEXT 50%;-- pad each TEXT subsection by 50%
     PAD DATA 50;-- pad each DATA subsection by 50 bytes 
END OPTIONS;

Pad a Specific Group

Padding can be specified in a group's For clause. This padding specification overrides any global padding option and applies only to the specified group.

GROUP program_text is 
        TEXT; 
END GROUP; 
FOR program_text USE PAD 50% AT *;
-- pad program_text's subsections by 50%

Pad a Specific Subprogram

To identify an individual subprogram and indicate a specific amount of padding to include after that subprogram:

OPTIONS    
    PAD __CALL_0 50%;  -- pad __CALL_0 by 50%
    PAD __CLOSE_ALL 040;  -- pad __CLOSE_ALL by 64 bytes
END OPTIONS;

Pad Implicit Tables

As new groups are generated by the patching linker the internal tables GROUP_TABLE and DATA_INIT_TABLE (for new data imaged groups) may be forced to move. To reduce the likelihood of this happening, you may explicitly pad these tables on the initial link with special padding options.

OPTIONS
      PAD GROUP_TABLE 20%;
      PAD DATA_INIT_TABLE 5%; 
END OPTIONS;

The compacted exception tables, __EXCEPTION_TABLE, change as new text groups are created or new exception handlers are created. The exception tables consist of three subtables. If left unpadded, a change to the first cascades into changes throughout the following tables. The special pad option can be specified to reduce the likelihood of having to patch most of the exception tables or move the entire thing.

OPTIONS 
      PAD __EXCEPTION_TABLE 10%; 
END OPTIONS;

Separation of Default Sections into Distinct Groups

If you can determine that certain parts of the program are less likely to change than others, these sections may need less padding. For example, any parts of the program from the predefined Ada views runtime archives cannot be changed by the user and should require no padding. To allow segregating objects from different program libraries into different groups, it is possible to prefix a default section specification to identify all sections that reside in some subdirectory of the given pathname. For example:

GROUP apex_text is 
     -- identifies all object residing in subdirectories of 
     --/usr/apex/my_target 
     /usr/apex/my_target'TEXT; 
END GROUP; 
FOR apex_text USE PAD 0 AT *;

Preserved Patching Model

One model of using the patching linker that is supported is to always move subprograms or data subsections to new unused memory leaving vacated memory with its former contents. This allows you to fall back to the previous state with a minimum of patching effort. Please note that this requires fairly careful bookkeeping and some additional support that you provide.

• The preserved patching model ensures that old subprograms or data are not modified in place by using MOVE directives to force them to move. When in preserve mode, the linker preserves memory vacated by a move only; significant modifications in place are not detected by the linker if the new subprogram or data fits in the space allocated in the original image.
• You must determine what changes need to be made to a patched image to fall back to its previous state. This entails distinguishing between initialization of unused memory and modification of used memory in the original image. For more information, see the description of apex_pl_diff -p in The Binary Diff Program - apex_pl_diff.

To use the linker in preserve mode, use the PRESERVE option.

• This option always moves a subprogram or data that has outgrown its allocated space in the original image. In particular, it does not move a subprogram or data subsection to make space for another.
• PRESERVE does not reallocate memory that is vacated by a move until the next patching link,
• PRESERVE only reallocates memory for the destination of a move if that memory was unused in the original image,

Annotated Output

The Patching Linker describes the functions that move and why they move in the map file. When invoked with the -v option, the executable diff tool also describes what functions changed:

% apex_pl_diff -v old_hello.vox new_hello.vox

The output of the diff tool is a change file in ASCII. At the top are comments that identify the file, the date, the original image name, and the linked (new) image name. For example,

# OMF diff for user dcn at Mon Dec  1 08:10:25 1997 
# Original executable: old_hello.vox 
#   Last changed Mon Nov 24 15:04:26 1997 
# Modified executable: new_hello.vox 
#   Last changed Mon Dec  1 08:10:24 1997

This is followed by various comment lines to help apex_pl_patch identify structural changes between the old image and the new one. For example,

# 1 New sections needed 
# XS1 
# 
# New section .text of size 070 bytes added at 00120000 
# NS9=112:00120000:0 
# 
# Section .text size changed from 02f50 to 02e38 bytes 
# SS3=11832 
# 
# Section .const size changed from 01a10 to 01a88 bytes 
# SS8=6792

These header sections are followed by a sequence of diff comments for each S-record to help decipher the address range being modified. For example,

# Diff: 00100044 .. 00100047, 04 bytes 
#   < old_hello.vox:PROGRAM_SIGNATURE.main.25652b.2e6a3373.0+0x8 
#   > new_hello.vox:PROGRAM_SIGNATURE.main.25652b.2faa8ad7.0+0x8

In debug mode, the change file is expressed symbolically using the table from the image file.

The apex_pl_diff utility produces either Motorola S-records.

---

Ada Restrictions

The LINK_BLOCK group is special. The Apex Embedded runtime kernel uses this group to initialize the users program. The elements within this group cannot move. The origin cannot be changed without rebuilding the kernel and specifying the new LINK_BLOCK address.

---

Summary of Changes to the Linker Description File

OPTIONS
     --     
     -- The following directive causes the linker to move the     
     -- functions BZERO and __CLOSE_ALL to the end of the     
     -- TEXT group.     
     --     
     MOVE BZERO;     
     MOVE __CLOSE_ALL 0120000;

     --     
     -- The following directive causes the linker to pad all     
     -- text sections with 080 bytes of zeroes.     
     --     
     PAD TEXT PAD 080;
     -- 

     -- The following directive causes the linker to pad all     
     -- data sections by 50%.     
     --     
    
  PAD DATA 50%; 

     -- 
     -- The following directive causes the linker to pad each
     -- of the subtables in the exception tables to be padded
     -- by 10% to minimize number of diffs in future patches 
     --     
  PAD __EXCEPTION_TABLE 10%;

     -- 

     -- The following directives will pad the GROUP_TABLE and
     -- DATA_INIT_TABLE to reduce the likelyhood of having to 
     -- move these tables as the tables grow in subsequent 
     -- patches. 
     --
     PAD GROUP_TABLE 20%; 
     PAD DATA_INIT_TABLE 20%;
     --     

     -- The following directive causes the linker to pad the
     -- function _COMPUTE_TRAJECTORY with 64 bytes of
     -- zeroes.          
     --     
     PAD _COMPUTE_TRAJECTORY 040;

     --     

     -- The following directive causes the linker to pad the     
     -- function _COMPUTE_APOGEE by 50% and align it to at 
     -- least a 32 byte boundary.     
     --     
     PAD _COMPUTE_APOGEE 50%;
END OPTIONS;

---

Example Of a Complete Linker Description File

-- 
-- v_usr_link.opt 
-- 
-- This is a linker description file for building a user's Ada 
-- program to run on the RH32 simulator. 
-- 
-- Note: you will need to replace all occurrences of 
-- $XXX_BOARD with the the name of this directory. 
-- 
-- The following lines must be added to ada.lib in this
-- directory
-- 
-- LINK_BLOCK:INFO:00100000:      
--       --where 00100000 is the same as the origin 
-- OPTIONS:INFO:$XXX_BOARD/v_usr_link.opt: 
--       -- this file 
-- KERNEL_START:INFO:0060000:    
--       -- KERNEL program's entry address, 
--       -- normally its origin 
--
OPTIONS
     MAP;     
     ORIGIN 080200000;   
            -- update to point to start of user program
     PAD TEXT PAD 10%;
END OPTIONS;

OBJECTS     
     -- Board specific user configuration initialization.     
     v_usr_conf;
     v_usr_data;
     v_usr_local;
     handler;
     real_time;
END OBJECTS;

GROUP program_text IS
     text; 
END GROUP; 
FOR program_text USE AT 080204000;

GROUP program_const IS
     const; 
END GROUP; 
FOR program_const USE PAD 10% ALIGN 01000 AT * + 0800;

GROUP program_data IS
     data; 
END GROUP; 
GROUP program_data_image IS IMAGE program_data; 
FOR program_data USE ALIGN 01000 AT * + 0800; 
FOR program_data_image USE ALIGN 01000 AT * + 0800;

GROUP program_bss IS     
  bss; 
END GROUP; 
FOR program_bss USE ALIGN 01000 AT * + 0800;