Using the Sysgen Capture Tool (Windows Embedded CE 6.0)

  • Article

1/6/2010

You can use the Sysgen Capture tool to create a new sources file for a modified public driver that you want to rebuild in your OS design directory. For more information on the Sysgen Capture tool, see Sysgen Capture Tool.

The following procedure uses the serial port driver for 16550 UARTs, Com16550.dll, as an example of a target for the Sysgen Capture tool. Use the general process to assist in copying public code to your OS design so that you can make custom modifications.

Using the Sysgen Capture Tool

  1. From a command prompt, in your OS design directory, create two subdirectories for the driver. One is for a library corresponding to your driver and the other is for your driver's binary file, which can be a DLL or EXE.

    For example, to customize Com16550.dll, create a subdirectory named %_TARGETPLATROOT%\Drivers\Com16550\Src for the library and %_TARGETPLATROOT%\Drivers\Com16550\DLL for the binary file.

    Note

    If you were customizing an executable such as Etcha.exe, then you might create %_TARGETPLATROOT%\Apps\Etcha\Src and %_TARGETPLATROOT%\Apps\Etcha\EXE.

  2. Verify that the library name for your driver module is different from the name for your driver's binary file.

    In this example, Com16550.dll is built by linking Com16550_lib.lib. Most DLL Sysgen targets use the *_lib.lib naming convention because if you do not differentiate the library file and binary file names, the driver's import library has the same name as the static library containing its code. This may result in build problems that are difficult to diagnose accurately.

  3. Copy the Public directory that contains code for the module that you want to build into the Src directory that you created. In this example, you would copy the files from Public\Common\OAK\Drivers\Serial\Com16550\*.*.

  4. Navigate to the %_TARGETPLATROOT%\Drivers\Com16550\Src directory. Use a text editor to open the Sources file, and then add the following line.

    RELEASETYPE=PLATFORM

    If a RELEASETYPE line already exists in the Sources file, then change its value to PLATFORM. This tells the build system that output files should be placed in your OS design's Lib or target directories.

  5. Verify that the following line appears in the Sources file, and then save the file and close the text editor.

    WINCEOEM=1

    This tells the build system to include portions of header files that are only available to OEMs who are building run-time images.

  6. Build the library in %_TARGETPLATROOT%\Drivers\Com16550\Src. If there are any errors, resolve them before proceeding. A successful build creates and places the file Com16550_lib.lib in the appropriate subdirectory of %_TARGETPLATROOT%\lib.

  7. Navigate to the directory for your driver's binary file. For example, navigate to %_TARGETPLATROOT%\Drivers\Com16550\DLL.

  8. Run Sysgen_capture with the usual Sysgen parameters. For example, type the following line to execute Sysgen_capture with Com16550 as a target.

    Sysgen_capture com16550

    This creates one or more files, one of which is a Sources file with the name of the driver as the file extension. For example, a file created using Com16550 as a target would be named Sources.com16550. The Sysgen_capture.bat utility creates one such file for each .dll or .exe target created while running your Sysgen command.

  9. Rename the sources file for your driver as Sources. For example, remove the extension .com16550 from the file name Sources.com16550.

  10. Copy one of the selected module's sample Makefiles into your Src directory. At a minimum, you need a Sources file and a Makefile to run Build.exe.

    For example, copy the Makefile located in %_TARGETPLATROOT%\Drivers\Com16550\Src into %_TARGETPLATROOT%\Drivers\Com16550\DLL.

  11. Run Build.exe. This creates the same binary as the standard Sysgen command, and places it in your OS design's target directory, which is a subdirectory of %_TARGETPLATROOT%\target. Examine Build.log to determine where the binary was created.

    Note

    This version of the driver uses the standard version of Com16550_lib.lib, not the version that you created in %_TARGETPLATROOT%\Drivers\Com16550\src.

  12. In %_TARGETPLATROOT%\Drivers\Com16550\Src, open the sources file in a text editor. Remove the TARGETLIBS, or SOURCELIBS, entry for Com16550_lib.lib, and move it to SOURCELIBS, changing the path as appropriate. You may need to replace occurrences of %_PUBLICROOT%\common\oak with %_TARGETPLATROOT%.

  13. Navigate to the directory for your driver's binary file, for example, %_TARGETPLATROOT%\Drivers\Com16550\DLL, and then run Build.exe. Build.exe builds the target binary using your version of Com16550_lib.lib, which you can confirm by examining Build.log.

    Note

    In order to delete all the object files, you may need to run Build.exe with the –c parameter.

  14. In the %_TARGETPLATROOT%\Drivers\Com16550 directory, create a Dirs file that lists, in order, the Src and DLL, or EXE, directories. This enables you to build your modified version of %_TARGETPLATROOT%\Drivers\Com16550\Src and link an executable with one build command.

  15. Run Build.exe with the –c option in the %_PROJECTROOT%\CustomDriver directory and confirm that the contents of both the Src and DLL, or EXE, subdirectories are built, and that the driver links successfully.

Remarks

Sysgen_capture.bat also works on OS functionality that is not a driver. The following table shows commands for other OS functionality.

Command Result 
Sysgen_capture pm

Creates a Sources file for the Power Manager

 
Sysgen_capture etcha

Creates a Sources file for Etcha.exe, a touch driver test program.

 
Sysgen_capture -p wceshellfe cplmain

Creates a Sources file for the control panel.

Both Sysgen_capture.bat and Nmake_capture.bat are located in %_WINCEROOT%\Public\Common\OAK\Bin\I386. If you want to build Nmake_capture.exe, the source code is located in %_WINCEROOT%\Public\Common\OAK\Tools.

In the following procedure, Microsoft assumes that your Platform Builder installation includes support for x86 run-time images.

To build Nmake_capture.exe

  1. Open a command-line build window with an environment that has %_TGTCPU% set to NTANSI and %_TGTPLAT% set to NOPLAT.

  2. From the command prompt, navigate to the %_WINCEROOT%\Public\Common\OAK\Tools\Nmake_capture directory.

  3. Run Build.exe with the -c option, as shown in the following code example.

    Build -c

  4. Copy the new version of Nmake_capture.exe into the execution path ahead of the default version included with Platform Builder.

See Also

Concepts

Sysgen Capture Tool

Other Resources

Sysgen Tool