Abstract:
A utility program develops and updates an API-translation layer of an emulator for running programs written for one platform on another platform. The utility builds a module for each API from a set of templates to execute the API&#39;s function on the other platform. Generalized function templates iterates through API functions. Exception templates can override the generalized templates in specific cases. Types templates convert individual arguments of the API. Code templates contain code for incorporation into a number of other templates.

Description:
This application is a Continuation of U.S. application Ser. No. 09/461,860 filed Dec. 15, 1999, now U.S. Pat. No. 6,233,731, which is a Continuation of U.S. application Ser. No. 08/912,454 filed Aug. 18, 1997, now issued as U.S. Pat. No. 6,026,238. 
    
    
     FIELD OF THE INVENTION 
     The present invention relates to electronic data processing, and more specifically concerns a software tool for generating a set of translation-code modules for translating application-program interfaces (APIs) from one platform to another, for use with an emulator which allows application programs written for one platform to be executed on a different platform. 
     BACKGROUND OF THE INVENTION 
     Present-day application programs almost never interface directly to the hardware of the computer system in which they execute. Instead, application program interfaces (APIs) call code modules which control the hardware, or which call programmed interfaces at yet lower levels. Most API code modules reside in an operating system (OS), although others may exist in a basic input/output system (BIOS), or in other places. Code modules for API functions typically reside in freestanding dynamic link library (DLL) files each containing routines for carrying out dozens or even hundreds of API functions. 
     Executing an application program written for one computer processor, operating system, or other platform on another platform requires a program, variously known as an emulator, simulator, interpreter, or translator, to convert instructions, data formats, application-program interfaces (APIs), and other characteristics of the application from those of its original platform to those of the native platform in which the emulator runs. Sometimes the original platform has been replaced, but the old application must still be run on the new platform. Sometimes programs are written to an abstract platform, so that the same application can be executed on numerous different platforms merely by writing an emulator for each native platform that is to host the abstract platform. 
     An emulator subsystem generally has two major components. The emulator itself converts the original processor instructions from the application into instructions or groups of instructions appropriate to the processor of the new platform, and executes them. An API translation layer “thunks” API calls from the original platform being emulated into calls to APIs written for the native platform; that is, it intercepts API calls made by an application written for the emulated platform, converts their arguments from the calling convention of the original platform to that of the native platform, then calls an appropriate native-platform module for executing the API function. A translation module or “API thunk” is a piece of program code in the translation layer which executes between a particular original API and the operating system running on the native platform. 
     Conventional practice involves hand-writing thunk code for each new and modified API. However, an API set may change daily during the development of an operating system. Also, the number of APIs can be very large. The Microsoft® Windows® NT®-operating system, for example, contains more than 3,500 APIs in 42 different DLL modules. Therefore, manual production of individual API translation code becomes increasingly impractical. Increasingly shorter product cycles compounds this problem. 
     Some interface modules or thunks have been generated from hand-written descriptors for each separate API. However these must be maintained separately from the APIs themselves, and thus involve costly additional effort. They also suffer from synchronization problems: if one or more modules inadvertently escape an update between one development iteration and the next, their down-level code may mistranslate an API, or may crash the system. Such problems can be difficult to find, thus forcing the entire development effort to wait. 
     Alternatively, a software tool has been employed to create a set of skeleton API thunks as C-language source files which were then hand-modified. This approach is impractical, in that rerunning the tool destroys all the hand edits. 
     SUMMARY OF THE INVENTION 
     A utility program according to the present invention creates and automatically updates code modules for translating APIs written for one platform so that they will execute properly on a different platform. The utility, executed for every new development iteration of an operating system or other software environment, uses a set of templates for constructing source code for the translation modules, based upon the functions performed by the APIs. Special translation requirements are handled by exception templates containing personalized translation code. Another kind of template performs type conversions from the original APIs&#39; parameters or arguments into those of the different platform. 
     Automatic code generation in this manner enables much faster development iterations by providing an automated method of synchronizing the translation modules with changes made to the new operating system or environment. The code generator ensures that all translation modules are at the current updated level, which prevents system crashes caused by incompatible modules. It also greatly reduces errors within individual code modules resulting from prior hand generation methods, and eliminates errors across modules caused from different people working independently on different modules. 
     Other features and advantages, as well as modifications and additions within the scope of the invention, will appear to those skilled in the art from the following description. 
    
    
     DESCRIPTION OF THE DRAWINGS 
     FIG. 1 is a block diagram of a computer system in which the invention may be practiced. 
     FIG. 2 is a high-level block diagram of a multiple-platform emulation environment in which the invention finds utility. 
     FIG. 3 is a high-level block diagram of a translator utility according to the invention, along with its inputs and outputs. 
     FIG. 4 is a flow diagram showing the operation of the translator of FIG.  3 . 
    
    
     DETAILED DESCRIPTION 
     FIG. 1 provides a brief, general description of a suitable computing environment in which the invention may be implemented. Hardware and software environments will first be discussed, followed by a detailed description of the invention comprising a tool for creating and automatically updating code modules for translating APIs written for one platform so that they will execute properly on a different platform. The invention will hereinafter be described in the general context of computer-executable instructions such as program modules, executed by a personal computer (PC); however, other environments are possible. Program modules include routines, programs, objects, components, data structures, etc. that perform particular tasks or implement particular abstract data types. Those skilled in the art will appreciate that the invention may be practiced with other computer-system configurations, including hand-held devices, multiprocessor systems, microprocessor-based programmable consumer electronics, network PCs, minicomputers, mainframe computers, and the like. The invention may also be practiced in distributed computing environments where tasks are performed by remote processing devices linked through a communications network. In a distributed computing environment, program modules may be located in both local and remote memory storage devices. 
     FIG. 1 shows an exemplary system for implementing the invention. It employs a general-purpose computing device in the form of a conventional personal computer  20 , which includes processing unit  21 , system memory  22 , and system bus  23  that couples the system memory and other system components to processing unit  21 . System bus  23  may be any of several types, including a memory bus or memory controller, a peripheral bus, and a local bus, and may use any of a variety of bus structures. System memory  22  includes read-only memory (ROM)  24  and random-access memory (RAM)  25 . A basic input/output system (BIOS)  26 , stored in ROM  24 , contains the basic routines that transfer information between components of personal computer  20 . BIOS  24  also contains start-up routines for the system. Personal computer  20  further includes hard disk drive  27  for reading from and writing to a hard disk (not shown), magnetic disk drive  28  for reading from and writing to a removable magnetic disk  29 , and optical disk drive  30  for reading from and writing to a removable optical disk  31  such as a CD-ROM or other optical medium. Hard disk drive  27 , magnetic disk drive  28 , and optical disk drive  30  are connected to system bus  23  by a hard-disk drive interface  32 , a magnetic-disk drive interface  33 , and an optical-drive interface  34 , respectively. The drives and their associated computer-readable media provide nonvolatile storage of computer-readable instructions, data structures, program modules and other data for personal computer  20 . Although the exemplary environment described herein employs a hard disk, a removable magnetic disk  29  and a removable optical disk  31 , those skilled in the art will appreciate that other types of computer-readable media which can store data accessible by a computer may also be used in the exemplary operating environment. Such media may include magnetic cassettes, flash-memory cards, digital versatile disks, Bernoulli cartridges, RAMs, ROMs, and the like. 
     Program modules may be stored on the hard disk, magnetic disk  29 , optical disk  31 , ROM  24  and RAM  25 . Program modules may include operating system  35 , one or more application programs  36 , other program modules  37 , and program data  38 . A user may enter commands and information into personal computer  20  through input devices such as a keyboard  40  and a pointing device  42 . Other input devices (not shown) may include a microphone, joystick, game pad, satellite dish, scanner, or the like. These and other input devices are often connected to the processing unit  21  through a serial-port interface  46  coupled to system bus  23 ; but they may be connected through other interfaces not shown in FIG. 1, such as a parallel port, a game port, or a universal serial bus (USB). A monitor  47  or other display device also connects to system bus  23  via an interface such as a video adapter  48 . In addition to the monitor, personal computers typically include other peripheral output devices (not shown) such as speakers and printers. 
     Personal computer  20  may operate in a networked environment using logical connections to one or more remote computers such as remote computer  49 . Remote computer  49  may be another personal computer, a server, a router, a network PC, a peer device, or other common network node. It typically includes many or all of the components described above in connection with personal computer  20 ; however, only a storage device  50  is illustrated in FIG.  1 . The logical connections depicted in FIG. 1 include local-area network (LAN)  51  and a wide-area network (WAN)  52 . Such networking environments are commonplace in offices, enterprise-wide computer networks, intranets and the Internet. 
     When placed in a LAN networking environment, PC  20  connects to local network  51  through a network interface or adapter  53 . When used in a WAN networking environment such as the Internet, PC  20  typically includes modem  54  or other means for establishing communications over network  52 . Modem  54  may be internal or external to PC  20 , and connects to system bus  23  via serial-port interface  46 . In a networked environment, program modules depicted as residing within 20 or portions thereof may be stored in remote storage device  50 . Of course, the network connections shown are illustrative, and other means of establishing a communications link between the computers may be substituted. 
     FIG. 2 shows a software environment  200  for running an application program  210  for one platform on a processor  220  representing a different platform. The elements enclosed in dashed line  201  are elements designed to be executed on a first platform such as a processor  21 , FIG. 1, of the Intel AX 86 ” familyXfor example an Intel 80386, 80486, or Pentium microprocessor. The other elements execute on a second platform, such as a Digital Equipment Corp. AAlpha” or an IBM APowerPC” microprocessor serving as processor  21 . This description refers to the first and second platforms as the AX 86 ” and Anative” platforms, respectively. For purposes of illustration, a native-platform version  230  of the -Microsoft® Windows® NT®- operating system serves as OS  35 , FIG.  1 . 
     Conventional emulator program  240  translates the instructions, data, and interfaces (APIs) of an X 86 -platform application program such as  36 , FIGS. 1 and 2, from those of the X 86  platforms to equivalent operations in the native platform. The APIs of an application program are actually calls to a set  250  of API modules  251 - 253 , only a very few of which are shown in FIG.  2 . API modules are commonly grouped into dynamic link libraries such as  254 . As noted previously, OS  230  has thousands of APIs in more than forty DLLs; this set, collectively known as AWin 32 ,” is recompiled into a new Abuild” almost daily during a development effort. When application  210  calls an API written for the X 86  platform, such as API  251 , a conventional API translation layer  241  in emulator  240  retrieves the proper API module  251 , and calls an associated translation-code module, or Athunk,”  261  to convert any API arguments and data to the correct format for the native platform, and to perform functions which emulate those the API would have performed on the original X 86  platform. The set of thunks  260  includes a separate module  261 - 262  for each X 86  API  251 - 252 . APIs such as  253  written for the native platform execute directly when called from OS  230 , and do not require thunks. 
     FIG. 3 is a high-level block diagram  300  showing a translator utility according to the invention, along with its inputs and outputs. Some of the elements shown in FIG. 2 have different labels in FIG. 3, to denote that the corresponding elements are in compiled object-code form in FIG. 2, but exist as source-code files in FIG.  3 . 
     In its source-code form, each DLL  254 , FIG. 2, is a collection  310  of files  311  each containing instructions in a language such as C for an API  250 , FIG.  2 . Each file represents one or more functions  312  to be performed by one of the APIs  251 - 252 . (Some terminology: a dynamic link library is generated from three source files, viz a C source-code file, a C header file, and a .DEF file. The compiler converts these into two object files, a .DLL code file and an import .LIB file.) 
     A module-definition file (.DEF) file  322  specifies the list of functions which are to be exported from DLL  320  as APIs. The .DEF file compiled into an import library (.LIB) file  321 . The .LIB file is significant because the API name exported from the DLL may differ from the function name in source file  311 ; for example, an entry FOO=BAR@4 in a .DEF file instructs the linker to export the function known internally as FOO from the DLL as BAR. Thunk generator  330  uses .LIB file  321  to associate an internal function name with an exported API name. C-language files have associated header (.H) files  313  that specify the external interface of their code file  311 , such as data types and external variable names. In particular, header files include type information  315  for functions  312  in code files  311 . 
     For example, a .H header file could contain a type definition such as: 
     
       
         
               
               
             
               
               
             
               
               
             
           
               
                   
                   
               
             
             
               
                   
                 Typedef struct tagFoo  { 
               
             
          
           
               
                   
                 int member1; 
               
               
                   
                 int member2; 
               
             
          
           
               
                   
                 } *PFOO 
               
               
                   
                   
               
             
          
         
       
     
     and a function declaration: 
     int AnApi (PFOO arg 1 , char*); 
     Generator  330  stores this information for all APIs. The entries for the above example might be: 
     
       
         
               
               
             
               
               
             
               
               
               
             
               
               
             
               
               
             
               
               
             
               
               
               
             
           
               
                   
                   
               
             
             
               
                   
                 TYPENAME  struct tagFoo 
               
             
          
           
               
                   
                 MEMBER LIST 
               
             
          
           
               
                   
                 MEMBER NAME 
                 member1 
               
               
                   
                 MEMBER TYPE 
                 int 
               
               
                   
                 MEMBER OFFSET 
                 0 
               
               
                   
                 MEMBER NAME 
                 member2 
               
               
                   
                 MEMBER TYPE 
                 int 
               
               
                   
                 MEMBER OFFSET 
                 4 
               
             
          
           
               
                   
                 TYPENAME  PFOO 
               
             
          
           
               
                   
                 INDIRECTION  1 
               
               
                   
                 BASETYPE  struct tagFoo 
               
             
          
           
               
                   
                 APINAME  AnApi 
               
             
          
           
               
                   
                 RETURN TYPE 
                 int 
               
               
                   
                 ARG NAME 
                 argl 
               
               
                   
                 ARG TYPE 
                 PFOO 
               
               
                   
                 ARG NAME 
                 &lt;noname&gt; 
               
               
                   
                 ARG TYPE 
                 char * 
               
               
                   
                   
               
             
          
         
       
     
     Finally, a conventional definitions (.DEF) file  322  may instruct a conventional linker (not shown) in OS  230  to export an internal API name from DLL  320  as a different name. 
     Translation generator  330  uses information from files  311 ,  313 , and  321  to build C-language source-code files  340  which can be compiled into the translation-code modules  260  in FIG.  2 . The invention provides a novel set of template files  350  for this purpose. Template (.TPL) files are descriptions of how to generate translation-code modules (Athunks≅). They comprise small amounts of hand-generated C code which implement generalized forms for iterating over API functions and their arguments, and for handling special cases which may arise in particular APIs. Each template has the following syntax: 
     
       
         
               
               
             
               
               
             
               
               
             
           
               
                   
                   
               
             
             
               
                   
                 [Type_of_Template] 
               
               
                   
                 TemplateName = Name_Of_Template 
               
               
                   
                 CGenBegin= 
               
             
          
           
               
                   
                 &lt;code to generate when this template is expanded&gt; 
               
             
          
           
               
                   
                 CGenEnd= 
               
               
                   
                   
               
             
          
         
       
     
     There are four types of template  350 . 
     The iterated-function (IFunc) template  351  iterates over API functions. Generator  330  expands one of these for each exported function in an API. The IFunc template  351  is the default expansion for APIs. The following example template will generate a skeleton thunk  340 . 
     
       
         
               
             
               
               
             
               
               
             
               
             
               
               
             
               
             
           
               
                   
               
             
             
               
                 [IFunc] 
               
               
                 TemplateName = HostFuncs 
               
               
                 CGenBegin= 
               
               
                 void 
               
               
                 wh@ApiName (PULONG BaseArgs, ULONG RetVal) 
               
               
                 { 
               
             
          
           
               
                   
                 @ApiFnRet *pRetVal = (@ApiFnRet *) RetVal; 
               
               
                   
                 @Types (Locals) 
               
               
                   
                 @Types (Body) 
               
               
                   
                 @IfApiRet (*pRetVal = ) @ApiName (@IfArgs (@ArgList (*((@ArgType 
               
             
          
           
               
                   
                 *) 
               
             
          
           
               
                 (@ArgAddr (BaseArgs))) @ArgMore(,)))); 
               
             
          
           
               
                   
                 @Types (Return) 
               
             
          
           
               
                 } 
               
               
                 CGenEnd= 
               
               
                   
               
             
          
         
       
     
     Generator  330  expands each of the &gt;@’-prefixed keywords in template  351  from the data collected from files  313  and  321  for a particular API  310  as follows: 
     
       
         
               
               
             
           
               
                   
               
             
             
               
                 @ApiName 
                 Internal name of the API 
               
               
                 @ApiFnRet 
                 Return type of the API 
               
               
                 @Types(x) 
                 Expands Type templates of the form &gt; x, ≠ 
               
               
                 @IfApiRet(x) 
                 Expands &gt; x, ≠ if the return type of the API is 
               
               
                   
                 non-void 
               
               
                 @IfArgs(x) 
                 Expands &gt; x, ≠ if the API has arguments 
               
               
                 @ArgList(x) 
                 Iterates over all arguments, expanding &gt; x, ≠ 
               
               
                   
                 for each argument 
               
               
                 @ArgType 
                 Type of argument 
               
               
                 @ArgAddr(x) 
                 Address of the argument, relative to &gt; x, ≠ 
               
               
                 @ArgMore(x) 
                 Expands if there are more arguments after the current 
               
               
                   
                 one 
               
               
                   
               
             
          
         
       
     
     For example, an API with prototype &gt;HWND FindWindowA(LPSTR  1 pClass, LPSTR  1 pWindow)=expands to: 
     
       
         
               
             
               
               
             
               
             
           
               
                   
               
             
             
               
                 whFindWindowA (PULONG pBaseArgs, ULONG RetVal) 
               
               
                 { 
               
             
          
           
               
                   
                 HWND *pRetVal = (HWND *) RetVal; 
               
               
                   
                 *pRetVal = FindWindowA( *(LPSTR *) (pBaseArgs + 0), * (LPSTR *) 
               
             
          
           
               
                 (pBaseArgs + 1) ); 
               
               
                 } 
               
               
                   
               
             
          
         
       
     
     An exception-function (EFunc) template  352  recognizes a particular API name, and overrides the default IFunc template  351  for that API. The following example template  352  produces fixed code for the particular API named &gt;SetErrorMode’. 
     
       
         
               
               
             
               
               
             
               
               
             
               
               
             
               
               
             
           
               
                   
                   
               
             
             
               
                   
                 [EFunc] 
               
               
                   
                 TemplateName = SetErrorMode 
               
               
                   
                 CGenBegin= 
               
               
                   
                 void 
               
               
                   
                 wh@ApiName (PULONG BaseArgs, ULONG RetVal) 
               
               
                   
                 { 
               
             
          
           
               
                   
                 @ApiFnRet *pRetVal = (@ApiFnRet *) RetVal; 
               
               
                   
                 *pRetVal = SetErrorMode ((*(UINT *) pBaseArgs) * 
               
             
          
           
               
                   
                 SEM_NOALIGNMENTFAULTEXCEPT) 
               
             
          
           
               
                   
                 *pRetVal &amp; = −SEM_NOALIGNMENTFAULTEXCEPT; 
               
             
          
           
               
                   
                 } 
               
               
                   
                 CGenEnd= 
               
               
                   
                   
               
             
          
         
       
     
     EFunc templates provides a facility for custom-writing code for an API, while preserving robustness against API changes. Of course, the code for such an API can always be rewritten merely by rewriting its EFunc template. 
     A types (Types) template  353  creates a thunk  340  for each parameter, or argument, of each API file  311  which matches a specified type name. Types templates are powerful in that generator  330  applies them automatically to new APIs, providing correct thunking without manual intervention. Consider the following examples: 
     
       
         
               
               
             
               
               
             
               
               
             
           
               
                   
                   
               
             
             
               
                   
                 [Types] 
               
               
                   
                 TemplateName = Locals 
               
               
                   
                 TypeName = LPSTR 
               
               
                   
                 IndLevel = 0 
               
               
                   
                 CGenBegin= 
               
             
          
           
               
                   
                 @ArgLocal = * ((@ArgType *) (pBaseArgs + ArgOff)); 
               
             
          
           
               
                   
                 CGenEnd= 
               
               
                   
                 [Types] 
               
               
                   
                 TemplateName = Body 
               
               
                   
                 TypeName = Body 
               
               
                   
                 IndLevel = 0 
               
               
                   
                 CGenBegin= 
               
               
                   
                 VALIDATE_LPSTR (@ArgNameLocal); 
               
               
                   
                 CGenEnd= 
               
               
                   
                   
               
             
          
         
       
     
     With these two templates, any API  311  which takes the C-language LPSTR data type automatically receives the special-purpose Types code in addition to the IFunc code for the default IFunc template. For example, the &gt;FindWindowA’ API described above now expands to: 
     
       
         
               
               
             
               
               
             
               
               
             
           
               
                   
                   
               
             
             
               
                   
                 { 
               
             
          
           
               
                   
                 HWND *pRetVal = (HWND *) RetVal; 
               
               
                   
                 LPSTR lpClass = *((LPSTR *) (pBaseArgs + 0); 
               
               
                   
                 LPSTR lpWindow = *((LPSTR *) (pBaseArgs + 1); 
               
               
                   
                 VALIDATE_LPSTR (lpClass); 
               
               
                   
                 VALIDATE_LPSTR (lpWindow); 
               
               
                   
                 *pRetVal = FindWindowA ( lpClass, lpWindow ); 
               
             
          
           
               
                   
                 } 
               
               
                   
                   
               
             
          
         
       
     
     A code template  354  operates like a macro. It contains code which may be common to a number of other templates, and is referred to by name in those templates. For example, if the line 
     *pRetVal=SetErrorMode ((*(UINT*) pBaseArgs)* 
     occurs many times in many different templates  351 ,  352 , or  353 , then that line could be placed in a code template such as one named, Aserrm.’ The referring templates, such as the example above, then merely replace that line with the name of the macro, for example A[@serrm]≅. The conventional C macro facility then replaces the name with the code; C macros can, of course, be much more complex than this simple example. 
     Although the above templates are shown as written in the C language, they are language-independent. Templates  350  may generate code in C++, in assembler language, or in any other desired form. 
     FIG. 4 describes the steps  400  carried out by translation-code generator  330 , FIG.  3 . The generator is run at  401  for every build of the operating system  230  or other entity whose APIs require regeneration. At its conclusion  402 , the entire set of API translation-module source-code files  340  has been synchronized at the same level, and can be compiled in a conventional manner into the set of object-code modules  260 , FIG. 2 which together form an API-translation portion (the Athunk layer≅) of emulator  240 . 
     Block  410  scans all the DLLs  254  belonging to the OS  230  to identify the set of APIs ( 261 ,  262 , . . . in FIG. 2) which require regeneration. The names of these APIs are in the export table  314  and in the import .LIB file  321  of each DLL, as previously described. (As a technical aside, the raw exports come from the import .LIB. However, many of them may be unnamed ordinals or renamed C functions. In order to obtain type information, generator  330  must reconstruct the name of the original function that implements each API. Thus, it must sometimes unmap the export name back to the function name.) Step  403  then sequentially selects a current API in the set for processing. 
     Step  420  may identify the current API as having an exception template  352 , by a conventional table-lookup in a list of the exception-template names. If such a template exists, step  421  accesses the associated EFunc template, and step  422  places its source code into a thunk file  340  for that API. 
     If the current API is a normal API, step  430  reads export table  314  of its header file  313  to extract the names of all its exported functions. Step expands the IFunc template  351  for those functions, as described above. When step  431  has iterated through all the exported functions of the current API, exit  432  progresses to the next step. 
     Step  440  cycles through the parameters (arguments) of the current API, sequentially selecting one as a current parameter. If step  441  determines that a Types template  353  exists for this parameter type, then step  442  places the template” source code in the module  340 , so that the API will process that argument type correctly. Most Types templates substitute a different value for a parameter. However, a Types template may perform other functions, such as validating the range of a parameter. Control passes to exit  443  when all Types templates have been processed. 
     Step  450  processes Code templates  354 , FIG.  3 . Whenever the name of a code template appears (as a macro name) in template-processing step  422 ,  432 , or  442 , dashed lines  451  call step  450  to expand a particular named code template and return the code to the calling template. Step  450  may actually occur later, when the thunk source-code files  340  are conventionally compiled into object-code modules  260 . 
     It is to be understood that the above description is intended to be illustrative, and not restrictive. The invention may be used to provide for execution of interfaces from multiple prior platforms as opposed to just one. Further, template matching can be done in many different manners, such as by having a field in an interface which directly identifies a desired template. Many other embodiments will be apparent to those skilled in the art upon reviewing the above description. The scope of the invention should, therefore, be determined with reference to the appended claims, along with the full scope of equivalents to which such claims are entitled.