Entrek TOOLBOX Evaluation Information
Thank you for your interest in our product. We hope that you'll discover the powerful features built into our toolset and see how those features can be used to quickly find and fix bugs that would otherwise be very difficult to debug, or, worse, go undetected!
The Entrek TOOLBOX Evaluation Edition is intended to help you determine if the product
- Works in your environment, including your desktop operating system and your Windows CE target device.
- Has the necessary features to aid you in your debugging.
The evaluation software is not intended to help you find and fix bugs in your production code. As such, one key feature in the CodeSnitch tool has been limited.
Both the professional and standard editions may be evaluated. However these two editions cannot coexist on the same machine. After evaluating one, you must remove it before evaluating the other.
After installing Entrek TOOLBOX, you must install a patch, which fixes several known issues. Information about the patch, including instructions for downloading and installing, can be found here.
The evaluation period is 14 days. The 14 day period begins the day you install the software. It ends either 14 days after installation or after 30 days of registration, whichever comes first.
If you've previously evaluated Entrek TOOLBOX version 1.4 and would like to extend your evaluation, please send a request to Entrek Support. You will not receive a valid evaluation key by resubmitting the registration form.
If you've previously evaluated an earlier version of Entrek TOOLBOX and wish to evaluate the latest version, then you may resubmit the registration form to receive a valid evaluation key.
CodeSnitch is the tool which will instrument your application so that it can, among other things, keep track of memory and resource allocations made by your application. It can then determine if your application is leaking. When your application makes a call that is tracked by CodeSnitch (for a full list of functions, see the Reference section of the CodeSnitch electronic help file), one or more events will be generated depending on your runtime options. Each event contains an address and a call stack which allows you to trace the path that led to the function call. In the full edition of CodeSnitch, it will use symbolic information to resolve these addresses to the file and line number of the source code that created the event. It will then display the source in the source viewing window. However, in the evaluation edition, the symbolic information is resolved for the first 50 events only. Only the address is given for all other events.
This limitation is removed if the application you are testing is small, generally under 4KB for native Win32 applications and 32KB for MFC applications. That is, for small sample applications, addresses are resolved for all events. You are encouraged to test against sample applications in order to verify that the product gives accurate results.
Entrek TOOLBOX will work with Smartphone. You must, however, follow a few simple instructions before connecting to your target device, whether it is a physical device or the Smartphone emulator.
First, your target device must be unlocked for development. Effectively, this means that you must be able to provision the device with certificates that you generally sign your application with. Before loading an application or a DLL, the operating system will verify that the application is signed with a valid certificate and assign a trust level to the application, depending if the certificate is installed in the "Privileged Certificate Store" or the "Unprivileged Certificate Store".
Unlocked phones can also run unsigned applications. Unsigned applications will run, but in unprivileged mode.
CodeSnitch makes a slight modification to application and DLL files at instrumentation time (it also reverts the changes when uninstrumenting). This modification will cause the signature checking performed by the operating system to fail (it performs a checksum validation), and your application will fail to load. To work around this problem, simply do not sign your application when testing with CodeSnitch. To turn off application signing, go to the Security tab in the eMbedded Visual C++ Project Settings dialog (use the arrows in the tab control to scroll to the Security tab). Uncheck the checkbox labeled "Sign this Application". Then rebuild and redeploy the application to the target device.
ProcMan uses privileged operating system functions. For it to be able to run, then, the binary files ProcMan installs on the target device must first be signed with a certificate which is installed in the "Privileged Certificate Store". You must manually sign these files before connecting ProcMan. You may use the signcode.exe tool which comes with your Smartphone SDK. For Smartphone 2002, signcode.exe can be found in \Windows CE Tools\wce300\Smartphone 2002\tools. For Smartphone 2003, it can be found in \Program Files\Windows CE Tools\wce420\Smartphone 2003\tools.
The binaries that must be signed for ProcMan are toolbox.exe, tbhelp.dll, procmance.dll, and storemance.dll. For Smartphone 2002, these files can be found in \Program Files\Entrek\TOOLBOX\Target\wce300\arm. For Smartphone 2003, the files can be found in \Program Files\Entrek\TOOLBOX\Target\wce400\armv4.
Future version of Entrek TOOLBOX will have support in the user interface to make these steps easier and more seemless.
For more information about Smartphone security, certificates, and other signing issues, please refer to the information provided in your Smartphone SDK.
Review the system requirements and verify that your development environment is properly configured.
Review the Release notes and documentation provided in the electronic help files.
CodeSnitch Tips
- For best results, use a debug build of your applications and DLLs. CodeSnitch can be used against retail builds, but symbolic information is not generated by default. If you do generate symbolic information, CodeSnitch will use it, but because of compiler optimizations, may give incorrect file and line number information. See the CodeSnitch electronic help file for more information.
- Use Microsoft eMbedded Visual C++ or Microsoft Platform Builder to build and deploy your application to your target device or emulator. No special build steps are required.
- Connect CodeSnitch to your target device or emulator and then click the "Run" toolbar button.
- Click the Runtime Options... button to set the level of error detection and reporting you desire.
- Make sure your application as well as all DLLs used by your application are instrumented, including those loaded by an function call such as LoadLibrary or CoCreateInstance. To view and modify the list of DLLs that are instrumented, click the Dependencies... button on the Run dialog. Note that system DLLs cannot be instrumented (and generally do not need to be instrumented).
- Click the Go! button to instrument your application. If the Instrument and Run radio button is selected, CodeSnitch will also launch your application and a new Events window will open, displaying events as they occur. If Instrument Only is selected, the application will be instrumented. You can then start the application by any means (including the Microsoft eMbedded Visual C++ or Platform Builder debugger). Once started, CodeSnitch will open a new Events window (make sure to keep CodeSnitch connected).
- To see the newest events that occur, sort by descending sequence. Click the Sequence column header to change the sort order.
- The first event will be a Process Loaded event. The last event will be a Process Unloaded event. CodeSnitch will calculate leaks once the Process Unloaded event arrives. Note that for Pocket PC, your application may not close when you click the "X" caption bar button. It will only be minimized. You can use ProcMan to verify that the application is still running. If it is, you can use ProcMan to close the main window. Expand the Processes node, then expand your process node, and then expand the Windows node under that. Now right-click on the main window and select Close.
- The CodeSnitch main events window will gray allocation chains for memory and resources that have been freed, allowing you to focus only on those that are still allocated.
- The columns displayed can be altered using the View\Preferences... menu item.
- Debug trace messages show OutputDebugString in the API column. The actual text of the message is in the Description column.
ProcMan Tips
- You can monitor CPU time, percentage, and memory size for all processes by selecting the Processes node, entering a refresh rate in the Refresh toolbar dialog (we suggest two seconds or higher), and then clicking the AutoRefresh toolbar button (the yellow clock with the circle arrow around it).
- You can view/monitor CPU time and percentage on a per-thread basis by expanding a process node and selecting the Threads node.
- Heap usage can be viewed/monitored for a process by expanding that process's node and selecting the Heaps node.
- If you have a windowing problem in your application, you can use trial-and-error debugging to change the windows style bits, z-order, screen coordinates, etc. by finding the window, right-clicking it, and selecting the proper context menu item. You can use the information you gather to modify your source code to fix the problem.
- You can also simulate low memory by posting a WM_HIBERNATE message to your main window. Simply select your main window, right-click it, and select the PostMessage... context menu item.
- If you need to fine tune your application (perhaps you have threads that aren't getting enough time - or any time at all!), you can modify the thread's priority and quantum in real-time. Right click a thread and select Properties. Once you've determined the appropriate priority and quantum, you can modify your source code as necessary.
When connecting, ProcMan and CodeSnitch may install the wrong binaries on the target device.This issue can occur when targeting Windows CE versions 4.0 and higher that have an ARM-based processor, including XScale and TI OMAP. Entrek TOOLBOX ships with binaries built for ARMV4, ARMV4I, and ARMV4T. When connecting, for example, it may install ARMV4 binaries, though the target device is ARMV4I.
There is a workaround for this issue. Both ProcMan and CodeSnitch accept a command line parameter called "targetcpu". You can specifiy this parameter directly, or create a shortcut that contains it. Note that if you target two different CPUs (for example, ARMV4I and X86), you will need a shortcut for each target. The command line parameter must be specified as /targetcpu:<cpu_dir> where <cpu_dir> is the name of the directory that contains the binaries you want the tool to use. Examples are /targetcpu:ARMV4, /targetcpu:ARMV4I, and /targetcpu:ARMV4T.
If you have any questions, comments, or other feedback regarding the tools or Entrek Software, Inc. in general, please send email to Entrek Information.
Copyright © Entrek Software, Inc.