Introduction

Description

TealMemBrain is a simple but invaluable utility for monitoring and tuning the memory usage on your Palm handheld, identifying potential conflicts and greatly improving stability running multiple hacks and drivers.

Contents

This archive contains the following files:

Program Files:
TEALMEMB.PRC The "TealMemBrain" program file

TEALMSTR.PRC The TealMaster System Extensions Manager (demo)

TPSETUP.EXE Windows quick installer

Manual files:
TEALMEMB.PDF This manual in Adobe PDF format

TEALMEMB.HTM This manual in HTML format

MEMBDOC.PRC This manual in TealDoc Palm-readable format

REGISTER.TXT TealPoint Registration form in text format

REGISTER.HTM TealPoint Registration form in HTML format

Installing

TealMemBrain uses the Hackmaster-compatible Palm System Extensions standard. This is a safe and standard way to add and manage extended system functionality on the PalmPilot. We’ve included the non-expiring trial version of our own extensions manager TealMaster, but you may use Hackmaster (also shareware) or X-Master (freeware) as well.

Use the Palm Install Tool to install the program file TEALMEMB.PRC and TEALMSTR.PRC, if you do not already have the latter or another extensions manager on your device. The Palm install tool can be found as an icon on the left hand side of the Palm Desktop. Instructions on how to use the Palm Install Tool are in the Palm handbook that came with your organizer.

You may also optionally install MEMBDOC.PRC, which is this manual in Palm-readable format, which can be read on a Palm handheld with our program TealDoc.

Under Windows, you can optionally use the Windows easy installer TPSETUP.EXE. Double-click on it and follow the on-screen instructions.

TealMemBrain will not appear as a standard program of it's own, but instead is activated through the extensions manager control panel. To enable TealMemBrain, simply tap on the TealMaster (or Hackmaster) icon in the applications launcher, and tap on the checkmark next to the TealMemBrain entry in the list of Hacks.

Important note: Before updating or deleting any TealMaster/Hackmaster system extension (or “Hack”), be sure to uncheck the item first in the TealMaster/HackMaster control screen, or your Palm may get confused and crash.

Chapter 1 – Background

Palm organizers come with relatively simple memory management and monitoring tools, originally designed for a simple device running one application at a time. Today, however, it’s common for one to run applications along with multiple system extensions (“hacks”), pop-up programs, and hardware drivers simultaneously. In this environment, a more sophisticated memory tool can be useful in diagnosing problems and maintaining stability and compatibility.

TealMemBrain provides two functions to help aid in memory management. The first, a pop-up information window, can be used to provide a snapshot of the current memory state of the device from within any program. This is a handy tool for diagnosing conflicts or problems due to adverse memory conditions.

The second tool, the stack booster, allows one to increase the amount of memory allocated to a special function of the operating system known as the application memory stack. As exhaustion of stack memory is a leading cause of seemingly unexplained crashes when running multiple hacks, the stack booster can greatly increase the stability of a PalmOS handheld running more that the basic applications.

Chapter 2 – Using the Program

Program Activation

To activate TealMemBrain, launch your system extensions manager (e.g. TealMaster or HackMaster) by tapping on its icon in the applications launcher. TealMaster will list all currently installed system extensions, or “hacks” present on your handheld.

Click on the checkbox next to TealMemBrain in the "hacks" list to activate it, hooking it up to PalmOS. If you wish to later deactivate TealMemBrain, uncheck this same checkbox. Remember to deactivate TealMemBrain before deleting it or installing a newer version of the program, as overwriting or deleting a system extension while it is still hooked up to the operating system will almost certainly cause a crash or other unwanted behavior.

Setting TealMemBrain Preferences

The TealMemBrain preferences window is accessed from inside the extensions manager. Start the manager (TealMaster or HackMaster) by clicking on its icon in the applications launcher. Click on the ‘+’ (plus) button to the right of “TealMemBrain” in the list of installed "Hacks" to bring up the preferences screen.

Information Window Options

At the top of the window are four checkboxes corresponding to corners of the Graffiti writing area which can be selected as triggers for bringing up the pop-up information window. When checked, tapping on one of these locations will bring up a window showing the current memory state of the device. You can also bring up the popup window (new in 1.10) by stroking the pen along the left edge of the device up to the top corner of the display, which is handy for devices with nonstandard or no Graffiti areas.

Stack Boost Options

At the bottom of the window are options for the TealMemBrain stack booster. Due to restrictions in PalmOS, stack boosting only works on devices running PalmOS3 or PalmOS4. A boost value specifies the number of bytes to add to the current application’s memory stack. An optional limit value caps the maximum size of the stack that can be created using the stack booster. See the ‘Stack Booster’ section for more information on how to use these options.

Pop-up Information Window

The TealMemBrain pop-up information window can be brought up from within any program to show a snapshot of memory usage. The amounts of total and free memory are shown in three different categories used by PalmOS: file memory, the dynamic heap, and application stack space.

To bring up the window, perform a pen stroke upwards along the left edge of the display up to the top left corner of the screen. You can also tap on a selected region in the Graffitti area according to your preferences settings.

File Memory

The vast majority of the RAM (random access memory) on a Palm handheld is reserved for storage of programs and data files. This storage space is not used by programs as memory in the conventional desktop PC sense, but acts more like a virtual hard drive for the device. The memory usage shown in the system Launcher “Delete” screen is this “file” memory, which can be freed as necessary by selectively deleting files and programs.

Dynamic Heap

The dynamic heap, shown as the data heap in the pop-up window, represents the working memory made available to the operating system and running programs. The dynamic heap corresponds to the “memory” on a desktop PC, and is used for temporary storage space for text, data, and graphics. The total amount available cannot be adjusted, but varies as follows depending on the operating system version and total amount of memory on the device:

PalmOS 2.0:

64k

PalmOS 3.0:

96k

PalmOS 3.5+:

64k for devices with less than 2Mb memory

128k for devices with less than 4Mb memory

256k for devices with 4Mb or more memory

Application Stack Space

The application memory stack is a special part of the dynamic heap. While typically only a few kilobytes in size, the use of this stack is tied tightly to the operation of the processing chip and is used to store temporary values and assist in system and application function calls. The total amount of stack space is adjustable on an application-by-application basis. Applications can specify the amount of stack space they need on startup, or accept the default value of about 4 kilobytes. The TealMemBrain stack boost option can be used to increase this amount globally; useful as hacks and drivers may need to use more stack memory than is allocated by a particular app.

Stack Boost

The stack boost option allows one to supplement the amount of total stack memory available beyond the amount each app requests. The default value is about 4 kilobytes (4096 bytes) plus about 200 bytes of system overhead. While the additional stack memory is taken from the dynamic heap, it is a relatively small amount, so adding a boost of one or two kilobytes can significantly increase the stack with little relative impact on the dynamic heap.

While not necessary in most cases, a stack boost limit value can be set to cap the maximum stack size that can be created using the boost option. While TealMemBrain will always create a stack at least as large as that requested by an application, this option will keep the boost option from increasing a stack larger than the specified limit value plus about 200 bytes of system overhead. This limits the effect the boost has on the dynamic heap in cases where the application’s requested stack size is already sufficient.

The Exclude button on the config screen brings up a file selection window which lets you select up to six application for whom you do not want stack boosting to be active within. This option is necessary for a few older applications that were written before a PalmOS supported a variable system stack. Some of these apps create their own stack and use it to replace the default system stack, an action that will trigger a “Stack Overflow” error running on newer OS versions with stack boosting on. Apps which exhibit this behavior are typically computationally-intensive programs like some chess programs.

Chapter 3 – Recommended Usage

Use TealMemBrain to both diagnose possible app misbehaviors due to memory situations and fix problems and increase stability due to exhaustion of stack memory.

Pop-Up Information

The pop-up information window shows a snapshot of memory usage in the device when a trigger point is tapped. Use it to see if any type of memory is getting low in suspect circumstances. Generally, when the handheld is performing more tasks, or has more simultaneous windows active, it is also putting a higher drain on system resources and may be prone to problems.

It is important to note, however, that the amounts shown in the pop-up reflect the instant the input tap is processed, and may not reflect additional memory usage by functions and routines in-between the processing of input events. Typically, the file RAM numbers are representative, and the dynamic heap values largely so, but total stack usage in between input event processing can be much greater than what’s reflected in the pop-up window. Still, stack usage by popup dialog windows and pop-up programs (such as Palm desk accessories) are usually reflected in the stack space numbers and can help indicate when the stack boost option is necessary.

File Memory

While file memory is typically used for storing applications and databases, applications also use this space for temporary storage of tables, graphics, and other data that won’t fit in the dynamic heap. Thus, it’s usually a good idea to leave some file RAM free for proper operation of your handheld applications. We recommend leaving at least 128k free, corresponding to two full-sized database records. Unlike programs on a desktop PC, however, Palm applications do not benefit from having more free RAM than they need, so don’t expect to, say, improve performance by freeing up lots of file RAM.

Dynamic Heap

The dynamic heap is shared by the current application, the operating system, and any hacks, drivers, or desk accessories that are running concurrently. When a program uses a lot of dynamic memory, it may not run properly with some combinations of hacks and/or drivers. The pop-up information window should always show a good safety margin of free dynamic heap memory. Unfortunately, when this memory runs out, one cannot simply reallocate file memory to create more dynamic heap under current versions of PalmOS. It may be possible to free up more heap space by adjusting options, reducing the screen color depth (using a program such as Screen Prefs), or upgrading the operating system. If not, one might simply have to turn off some unneeded hacks or use the “profile-mapping” feature of TealMaster to do so automatically when in certain programs.

Application Stack Space

Exhausting (overflowing) the application memory stack is a major cause of seemingly mysterious crashes on heavily-loaded Palm handhelds. Sometimes, when the stack is overflowed, system data structures get overwritten, giving the telltale sign of failing to come up after a soft reset. Fortunately, stack space is only type of memory whose size TealMemBrain can directly increase.

Most hacks are designed to run in the few hundred bytes of extra stack space unused by most applications. Just because hacks and drivers are installed and activated doesn’t mean that they are all consuming resources at the same time. Thus, we’ve found that adding just one or two kilobytes (one kilobyte=1024 bytes) of stack boost can greatly increase stability with hacks, drivers, and add-on program. The stack limit feature is usually not necessary, but may help if the stack boost reduces the dynamic heap enough to be a problem in cases where an application already requests a large stack.

Chapter 4 – Compatibility

As we cannot control the style and robustness of other products, we cannot guarantee compatibility with PalmOS applications beyond those included from Palm Computing. However, we try to resolve compatibility issues as best we can.

In general, when encountering any unexpected behavior with the program, the first thing to check is a possible conflict with another system extension (hacks). Always try diagnosing the problem first by turning off any other active hacks and trying to reproduce the problem. By their very nature, hacks must share precious system resources to run, and it may not always be possible to run a desired combination of hacks due to limited system resources.

Stack Overflow Errors

Applications that swap the system stack to their own buffers will generate a stack overflow when using the variable stack system stack boosting employs. These, mostly older, apps were sometimes written to do this to expand the stack size before PalmOS provided a supported way to vary the stack size. When the newer stack system is activated, PalmOS assumably detects the modifed stack pointer and detects it (incorrectly) as an overflowed stack condition.

For these applications, you must use TealMemBrain’s app-exclude feature to turn off stack boosting for that particular application. You may be able to detect a swapped stack by running TealMemBrain with stack boost off, and bringing up the pop-up window. The stack value will read “custom or invalid” if the stack pointer has been switched in the main loop of the program. Stack-intensive applications that might be problematical include older chess programs, fractal generators, and graphics programs with flood-fill routines.

Appendix A – Revision History

Version 1.11 – May 10, 2005

· Updated to auto-activate text field on registration screen on Tungsten T5/Treo

· Updated bundled TealMaster demo to NVFS-compatible version

Version 1.10 – January 5, 2005

· Added option to activate using left-edge up stroke

Version 1.01 – October 22, 2001

· Updated to correctly display heap size on Sony CLIE organizers

Version 1.00 – October 12, 2001

· Initial release

Appendix B – Credits

Manual by Vince Lee, Tex Tennison, and Sara Houseman

Appendix C – Contact Info

TealMemBrain by TealPoint Software

©2001-2005 All Rights Reserved.

TealPoint Software

TealMemBrain Registration

454 Las Gallinas Ave #318

San Rafael, CA 94903-3618

We look forward to hearing from you.

Please visit us at www.tealpoint.com, or email us at contact@tealpoint.com.

Appendix D – Registering

Registering allows you to use the program past the 30 day expiration period and turns off registration reminders.

Currently, you may register by snail mail or online with a credit card and a secured server from the store where you downloaded the software. For the first option, send the following information on a sheet of paper separate from your payment.

· Product Name

· E-Mail Address

· HotSync User ID (Pilot Name Required for Passkey generation. It can be found on the main screen of the HotSync application on the Pilot as "Welcome ________" or in the corner on a PalmIII or higher)

· Check (drawn off a US Bank) or Money Order for ($14.95 US). No international checks or money orders please.

Appendix E – Products

Visit us online for our complete product line, including:

TEALAGENT ( http://www.tealpoint.com/softagnt.htm )

Get news, movie times, stock quotes, driving directions, web pages and more without need for a wireless connection. TealAgent fetches and formats web-based content for offline viewing.

TEALALIAS ( http://www.tealpoint.com/softalia.htm )

Free up memory and make the most of external expansion cards. Placeholder 'Alias' shortcut files automatically find, load, and launch apps and data from external SD cards, increasing free main memory.

TEALAUTO ( http://www.tealpoint.com/softauto.htm )

Track and graph automobile mileage, service, and expenses with TealAuto, the complete log book for your car or any vehicle. Extensive customization options and unmatched in features and functionality.

TEALBACKUP ( http://www.tealpoint.com/softback.htm )

Backup your valuable data with TealBackup, supporting manual and automatic backups to SD/MMC/CF cards and Memory Stick, backups through HotSync, and optional compression and encryption.

TEALDOC ( http://www.tealpoint.com/softdoc.htm )

Read, edit, and browse documents, Doc files, eBooks and text files with TealDoc, the enhanced doc reader. Extensive display and customization options; TealDoc is unmatched in features and usability.

TEALECHO ( http://www.tealpoint.com/softecho.htm )

Improve your Graffiti text input speed and accuracy, seeing what you write with TealEcho digital "ink". No more writing blind!

TEALGLANCE ( http://www.tealpoint.com/softglnc.htm )

See the time, date, upcoming appointments and todo items at power-up with TealGlance. The TealGlance pop-up utility comes up when you power up your handheld letting you see your day "at a glance."

TEALINFO ( http://www.tealpoint.com/softinfo.htm )

Lookup postal rates, area codes, tip tables, schedules, airports, and info from hundreds of free TealInfo databases. Create you own mini-apps; a handheld reference library.

TEALLAUNCH ( http://www.tealpoint.com/softlnch.htm )

Launch applications instantly with the TealLaunch pop-up launcher and button/stroke-mapping utility. Map applications to button presses and pen swipes so you can get to your apps quickly.

TEALLOCK ( http://www.tealpoint.com/softlock.htm )

Secure and protect your handheld with TealLock, the automatic locking program with encryption and card support. TealLock has unmatched features and customization options for personal or corporate use.

TEALMAGNIFY ( http://www.tealpoint.com/softlens.htm )

Save your eyesight with TealMagnify, an ever-ready magnifying glass that works with most any program. TealMagnify lets you enlarge the screen for those times the text is too small to read.

TEALMASTER ( http://www.tealpoint.com/softmstr.htm )

Replace Hackmaster with TealMaster, the supercharged 100%-compatible system extensions manager. TealMaster adds enhanced stability, configuration and diagnostic features and PalmOS 5.0 hack emulation.

TEALMEAL ( http://www.tealpoint.com/softmeal.htm )

Save and recall your favorite restaurants with TealMeal, the personal restaurant database. With TealMeal's handy sorting and selection options, never ask "where to eat" again.

TEALMEMBRAIN ( http://www.tealpoint.com/softmemb.htm )

Stop crashes and monitor your memory use with TealMemBrain, the application stack stabilizer. TealMemBrain boosts your stack space on OS3 and OS4 handhelds, eliminating the major cause of system instability.

TEALMOVER ( http://www.tealpoint.com/softmovr.htm )

Beam, delete, rename, and copy files with TealMover, the file management utility for SD/CF/MS cards. TealMover lets you see, move, modify, hex edit, and delete individual files.

TEALMOVIE ( http://www.tealpoint.com/softmovi.htm )

Play and convert high-quality video and synchronized sound with the TealMovie multimedia system. TealMovie includes a handheld audio/movie player and a Windows AVI/Quicktime converter program.

TEALNOTES ( http://www.tealpoint.com/softnote.htm )

Insert freehand graphics anywhere with TealNotes "sticky notes" for Palm OS. TealNotes can be inserted into memos, to-do lists, address book entries--almost anywhere you currently have editable text.

TEALPAINT ( http://www.tealpoint.com/softpnt.htm )

Paint, sketch, or draw with TealPaint, the all-in-one graphics paint program for PalmOS. Highlights include 20 tools, 16 patterns, 24 brushes, zoom, hires, layers, multi-undo, and a desktop converter.

TEALPHONE ( http://www.tealpoint.com/softphon.htm )

Supercharge the address book with TealPhone, the contacts replacement with superior interface and options. Highlights include enhanced display, search, phone-dialing, groups, and linking.

TEALPRINT ( http://www.tealpoint.com/softprnt.htm )

Print text and graphics to IR, serial, and Windows printers with TealPrint. With numerous connection options, TealPrint, is the all-in-one text and graphic printing solution.

TEALSAFE ( http://www.tealpoint.com/softsafe.htm )

Store your passwords, credit cards, PIN numbers, and bank accounts in the TealSafe data wallet. With maximum security and encryption, TealSafe is a must for features and security.

TEALSCRIPT ( http://www.tealpoint.com/softscrp.htm )

Replace Graffiti 1 or Graffiti 2 with TealScript, the text recognition system you can customize. Unlike other systems, you can make or change your own strokes for better speed and accuracy.

TEALTOOLS ( http://www.tealpoint.com/softtool.htm )

Improve productivity with TealTools pop-up Palm Desk Accessories. TealTools includes a popup calculator, clock/stopwatch, preferences panel, editing panel, memopad, and a file/backup manager.

SHORTCIRCUIT ( http://www.tealpoint.com/softshrt.htm )

A new twist on gameplay fused from your all time action puzzle favorites, connect falling conduit pieces into explosive loops in this frantic race against the clock.

Appendix F – Legal Notice

We at TealPoint Software are committed to providing quality, easy-to-use software. However, this product is provided without warranty and the user accepts full responsibility for any damages, consequential or otherwise, resulting from its use.

This archive is freely redistributable, provided it is made available only in its complete, unmodified form with no additional files and for noncommercial purposes only. Any other use must have prior written authorization from TealPoint Software.

Unauthorized commercial use includes, but is not limited to:

§ A product for sale.

§ Accompanying a product for sale.

§ Accompanying a magazine, book or other publication for sale.

§ Distribution with "Media", "Copying" or other incidental costs.

§ Available for download with access or download fees.

This program may be used on a trial basis for 30 days. The program will continue to function afterwards. However, if after this time you wish to continue using it, please register with us for the nominal fee listed in the program.

CUSTOMER LICENSE AGREEMENT

YOU ARE ABOUT TO DOWNLOAD, INSTALL, OPEN OR USE PROPRIETARY SOFTWARE OWNED BY TEALPOINT SOFTWARE, INC. CAREFULLY READ THE TERMS AND CONDITIONS OF THIS END USER LICENSE BEFORE DOING SO, AND CLICK BELOW THAT YOU ACCEPT THESE TERMS.

1. License. You are authorized to use the Software Product owned and developed by TealPoint Software, Inc. on a single hand-held computing device on a trial basis for thirty (30) days. If after 30 days you wish to continue using it, you are required to register with TealPoint and pay the specified fee. This license is not exclusive and may not be transferred. You may make one copy of the Software for back-up and archival purposes only.

2. Ownership. You acknowledge that the Software Product is the exclusive property of TealPoint Software, Inc, which owns all copyright, trade secret, patent and other proprietary rights in the Software Product.

3. Restrictions. You may NOT: (a) decompile or reverse engineer the Software Product; (b) copy (except as provided in 1 above) sell, distribute or commercially exploit the Software product; or (c) transfer, assign or sublicense this license.

4. Disclaimer of Warranty and Liability. TEALPOINT MAKES NO WARRANTY, EXPRESS OR IMPLIED, AS TO THE ACCURACY, COMPLETENESS OR FUNCTIONING OF THE LICENSED SOFTWARE, INCLUDING WITHOUT LIMITATION, WARRANTIES OF MERCHANTABILITY OR OF FITNESS FOR A PARTICULAR PURPOSE, ALL OF WHICH TEALPOINT DISCLAIMS. ALL LIABILITY IS DISCLAIMED AND TEALPOINT ASSUMES NO RESPONSIBILITY OR LIABILITY FOR LOSS OR DAMAGES OF ANY KIND, DIRECT OR INDIRECT, INCIDENTIAL, CONSEQUENTIAL OR SPECIAL, ARISING OUT OF YOUR USE OF THE LICENSED SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

5. Termination. You may terminate this Agreement at any time by destroying your copy(ies) of the Software Product. The Agreement will also terminate if you do not comply with any of its terms and conditions, at which time you are required to destroy your copy(ies) of the Software Product and cease all use.

6. Applicable Law. This Agreement is governed by the laws of the State of California.