5.4. Running The Patch Generator
The hcu_build_patch.sh patch generator is invoked to produce a dynamic software update patch in source code format. The patch generator compares the old and new versions of a program, identifies their differences, and taking into consideration the dynamic update description provided by the user it produces a patch.
Figure 5-6 shows an example of running the patch generator to produce a dynamic software update patch that can update vsFTPd version 2.0.4 to version 2.0.5. The patch generator requires the following parameters:
The whole-program merged source code of the original version (vsftpd-2.0.4/vsftpd_comb.c from Section 5.1).
The name of the original version (204).
The whole-program merged source code of the new version (vsftpd-2.0.5/vsftpd_comb.c from Section 5.2).
The name of the new version (205).
The file describing the update (2.0.4_to_2.0.5_mappings.c from Section 5.3.3).
A yes/no flag indicating whether the patch should support dynamic stack tracing.
A yes/no flag indicating whether the patch should support blocking system calls.
Figure 5-6. Preparing a dynamic software update patch for vsFTPd from 2.0.4 to 2.0.5.
bash$ hcu_build_patch.sh \
vsftpd-2.0.4/vsftpd_comb.c 204 \
vsftpd-2.0.5/vsftpd_comb.c 205 \
2.0.4_to_2.0.5_mappings.c yes yes
Figure 5-7. Patch generator report to update vsFTPd from 2.0.4 to 2.0.5.
...
variable 's_p_statbuf___6' not found in file 'vsftpd-2.0.4/vsftpd_comb.c.hcudiff.c'. It is an added variable.
variable 'tunable_delay_successful_login' not found in file 'vsftpd-2.0.4/vsftpd_comb.c.hcudiff.c'. It is an added variable.
variable 'envtz' not found in file 'vsftpd-2.0.4/vsftpd_comb.c.hcudiff.c'. It is an added variable.
variable 'tunable_max_login_fails' not found in file 'vsftpd-2.0.4/vsftpd_comb.c.hcudiff.c'. It is an added variable.
variable 'tunable_delay_failed_login' not found in file 'vsftpd-2.0.4/vsftpd_comb.c.hcudiff.c'. It is an added variable.
...
variable 'parseconf_uint_array' has HAD its definition updated. It is an updated variable.
...
function 'str_locate_text_reverse' has HAD its definition updated. It is an updated function.
function 'emit_greeting' has HAD its definition updated. It is an updated function.
function 'handle_login' has HAD its definition updated. It is an updated function.
function 'str_locate_chars' has HAD its definition updated. It is an updated function.
function 'vsf_privop_do_login' has HAD its definition updated. It is an updated function.
function 'vsf_remove_uwtmp' has HAD its definition updated. It is an updated function.
function 'handle_retr' has HAD its definition updated. It is an updated function.
function 'vsf_sysutil_connect_timeout' has HAD its definition updated. It is an updated function.
function 'handle_upload_common' has HAD its definition updated. It is an updated function.
function 'handle_user_command' has HAD its definition updated. It is an updated function.
function 'main' has HAD its definition updated. It is an updated function.
function 'handle_mdtm' has HAD its definition updated. It is an updated function.
function 'handle_size' has HAD its definition updated. It is an updated function.
function 'vsf_insert_uwtmp' has HAD its definition updated. It is an updated function.
function 'handle_feat' has HAD its definition updated. It is an updated function.
function 'str_locate_text' has HAD its definition updated. It is an updated function.
function 'get_unique_filename' has HAD its definition updated. It is an updated function.
function 'vsf_sysutil_chroot' has HAD its definition updated. It is an updated function.
function 'vsf_sysdep_check_auth' has HAD its definition updated. It is an updated function.
function 'vsf_sysutil_tzset' has HAD its definition updated. It is an updated function.
function 'handle_pass_command' has HAD its definition updated. It is an updated function.
function 'vsf_ls_populate_dir_list' has HAD its definition updated. It is an updated function.
function 'calc_num_send' has HAD its definition updated. It is an updated function.
function 'handle_stat' has HAD its definition updated. It is an updated function.
function 'vsf_privop_do_file_chown' has HAD its definition updated. It is an updated function.
Diff Report:
============
Type definitions:
-----------------
Added: 0 0.00
Deleted: 0 0.00
Updated: 1 0.14
Same: 693 99.86
Total: 694 100.00
Variable definitions:
-----------------
Added: 5 2.14
Deleted: 0 0.00
Updated: 1 0.43
Same: 228 97.44
Total: 234 100.00
Function definitions:
---------------------
Added: 0 0.00
Deleted: 0 0.00
Updated: 25 4.82
Same: 494 95.18
Total: 519 100.00
Patch format. The dynamic software update runtime requires that patches contain three special functions. These functions are invoked by the runtime at special points during an update to coordinate its successful application. They are used to apply datatype updates, to apply function updates, and to provide a description of the update. Besides generating these functions, the patch generator also automatically produces datatype and stack-state transformers.
The three special functions expected by the runtime are:
int HCU_update_description_function()
Invoked before the update is attempted to describe to the runtime possible execution continuations and which threads will be updated.
int HCU_datatype_transformations_function()
Invoked after unwinding the old stack and before reconstructing the new stack to transform the datatypes of global variables and to set values for new global variables.
int HCU_function_updates_function()
Invoked after unwinding the old stack and before reconstructing the new stack to update functions to use their new versions.
This capability is used to execute code that will allow updated functions to take control over the program execution of the old version.
These special functions are automatically produced by the patch generator. The functions can be overriden by the user by supplying different definitions in the mappings file (2.0.4_to_2.0.5_mappings.c). If alternate definitions are found in the mappings file, then those definitions are used instead of the ones the patch generator would have produced.
There are two reasons a user may want to provide alternate definitions of these functions. First, if the user wants to manually create patches, or produce them with a patch generator the user writes, and generally experiment with the runtime. Second, if it is identified that the patch generator produces incomplete or incorrect definitions.
 | An effective practice is to use the patch generator to create a patch, identify which transformers may be incomplete, to complement them, and then to copy them in the mappings file. This new mappings file that is now more complete is then used to run the patch generator again. The goal is to produce a mappings file that fully describes the update, so that generating and applying patches becomes a fully automatic process. |
 | The patch generator currently does not automatically produce statements that set the values of new variables, such as the values of the variables tunable_delay_login, tunable_delay_successful_login, and tunable_max_login_fails shown in Figure 5-2. There are plans to implement this feature. |
Datatype transformers. The patch generator produces transformers that automatically transfer the existing values of old variables to the updated variables. This works well when a struct is extended to have an additional field. It also automatically preserves some datatype conversions such as from int to long. Finally, it automatically preserves arrays that have their size increase by producing a transformer that copies all previous array values to the new array variable.
When the patch generator encounters a datatype transformation it cannot reason about, or a new field which should be initialized by the programmer it reports a warning, as shown in Figure 5-8.
Figure 5-8. Patch generator warnings for vsFTPd from 2.0.4 to 2.0.5.
WARNING: HCU_stack_transformer__handle_alarm_timeout():Don't know how to accurately preserve the field 'p_sess' of struct 'hcu_stack_local_handle_alarm_timeout_v204_s' which changed from type 'struct vsf_session_v204 *' to type 'struct vsf_session_v205 *'
WARNING: HCU_stack_transformer__handle_io():Don't know how to accurately preserve the field ' p_sess' of struct 'hcu_stack_local_handle_io_v204_s' which changed from type 'struct vsf_session_v204 *' to type 'struct vsf_session_v205 *'
WARNING: HCU_stack_transformer__handle_sigalrm():Don't know how to accurately preserve the field 'p_sess' of struct 'hcu_stack_local_handle_sigalrm_v204_s' which changed from type 'struct vsf_session_v204 *' to type 'struct vsf_session_v205 *'
WARNING: HCU_stack_transformer__handle_sigurg():Don't know how to accurately preserve the field 'p_sess' of struct 'hcu_stack_local_handle_sigurg_v204_s' which changed from type 'struct vsf_session_v204 *' to type 'struct vsf_session_v205 *'
WARNING: HCU_stack_transformer__handle_upload_common():Don't know how to accurately preserve the field 'tmp___2' of struct 'hcu_stack_local_handle_upload_common_v204_s' which changed from type 'char const *' to type 'int '
WARNING: HCU_stack_transformer__handle_upload_common():Unable to match an int definition 'int ' for the new type 'char const *' of the field 'tmp___3' of struct 'hcu_stack_local_handle_upload_common_v204_s' to prepare a datatype transformer
WARNING: HCU_stack_transformer__handle_upload_common():Field 'tmp___4' of type 'int ' is a new field. It should be initialized by the programmer
WARNING: HCU_datatype_transformation__struct__vsf_session_v204___to_struct__vsf_session_v205__():Field 'login_fails' of type 'unsigned int ' is a new field. It should be initialized by the programmer
WARNING: HCU_stack_transformer__vsf_sysdep_check_auth():Field 'tmp___1' of type 'char const *' is a new field. It should be initialized by the programmer
WARNING: HCU_stack_transformer__vsf_sysutil_tzset():Field 'retval' of type 'int ' is a new field. It should be initialized by the programmer
WARNING: HCU_stack_transformer__vsf_sysutil_tzset():Field 'tzbuf' of type 'char [sizeof("+HHMM!")]' is a new field. It should be initialized by the programmer
WARNING: HCU_stack_transformer__vsf_sysutil_tzset():Field 'tmp' of type 'long ' is a new field. It should be initialized by the programmer
WARNING: HCU_stack_transformer__vsf_sysutil_tzset():Field 'tmp___0' of type 'unsigned int ' is a new field. It should be initialized by the programmer
If the user provides custom datatype transformers in the mappings file, the patch generator produces the custom transformers in the patch.
Stack transformers. For functions that are not modified, the dynamic software update runtime automatically preserves their stack with a memcpy() call. Thus the patch generator does not produce stack transformers for them. For functions that are not modified but have the datatypes of their local variables updated, the patch generator automatically produces stack transformers that invoke the appropriate datatype transformers.
If the user provides custom stack-state transformers in the mappings file, the patch generator produces the custom transformers in the patch.