hack-manager [Palm OS Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Palm Hacks  ======
Palm OS had the ability for system functions to be extended by additional programs. Those programs would hook into the system, and provide additional API's for other programs to use. Alternatively, programs could choose to intercept system API's by patching over them, in order to provide different or augmented functions. **Hack Managers** were the standard way to manage this "wild west" of community software development, and they provide a way to enable and disable these patches, which were known as "**hacks**".

Note: Hacks designed for OS 3 an 4 do not generally work on OS 5, and vice-versa.

Not to be confused with [[desk-accessories|Desk Accessories]].

==== Hack Managers ====
  * [[http://yahm.palmoid.com/#4|YAHM]]
  * [[http://www.daggerware.com/hackmstr.htm|HackMaster]] (OS 2/3/4 Only)
  * [[https://web.archive.org/web/20080705214218/http://linkesoft.com/english/xmaster/|X-Master]]  (OS 2/3/4 Only)
  * [[http://www.tealpoint.com/softmstr.htm|TealMaster]] (Paid)
  * [[https://translate.google.com/translate?hl=en&sl=ja&u=http://simple-palm.com/dal50/&prev=search|DA Launcher (OS 5)]]
  * [[https://translate.google.com/translate?hl=en&sl=ja&u=http://simple-palm.com/dal/&prev=search|DA Launcher (OS 4)]]

==== OS 3/4 Hacks ====
  * [[https://ftp.icm.edu.pl/packages/palmpilotware/html/body_hacks.html |PalmPilotWare]]
  * [[https://mobyware.org/palm-tx-device-hacks-tweaks-download-350-all-1-date.html|Mobyware]]
  * [[https://byteswapped.com/palm/|byteswapped]]
  * [[https://people.math.osu.edu/nevai.1/PC/palm/|pToolset]]
  * [[https://translate.google.com/translate?hl=en&sl=ru&u=http://www.mypalm.ru/soft/softlist.phtml%3Fpl167%3Don%26c265%3Don&prev=search|MyPalm.ru]]
  * [[https://web.archive.org/web/20020207010935/http://shiva.di.uminho.pt/~rco/pilot.html|Shiva Pilot Software]]
  * [[http://palmopensource.com/index.php?category=8|PalmOpenSource]]
  * [[http://www.florentpillet.com/symbolhack.html|SymbolHack]]
  * [[https://mikemccollister.com/palm/|McPhling]]
  * [[http://www.sergem.net/index.html|SergeM Hacks]]



==== OS 5 Hacks====
  * [[http://yahm.palmoid.com/#8]]
  * [[https://web.archive.org/web/20180301204443/http://www.palmoid.com/|Palmoid ARM hacks]]
  * [[https://mobyware.org/palm-tx-device-hacks-tweaks-download-350-all-1-date.html|Mobyware]]
  * [[https://people.math.osu.edu/nevai.1/PC/palm/|pToolset]]
  * [[https://translate.google.com/translate?hl=en&sl=ru&u=http://www.mypalm.ru/soft/softlist.phtml%3Fpl167%3Don%26c265%3Don&prev=search|MyPalm.ru]]
  * [[http://palmopensource.com/index.php?category=8|PalmOpenSource]]
  * [[https://mikemccollister.com/palm/|McPhling]]


==== Device Specific Hacks ====
  * [[https://web.archive.org/web/20160428053045/http://www.palmoid.com/SilkMan/|Handera 330 Silk Manager]]

==== More info ====
  * [[https://flylib.com/books/en/2.745.1.77/1/]]
  * [[https://www.oreilly.com/library/view/palm-and-treo/059610054X/ch07s07.html | O'Reilly - Extend Your Palm]]
  * [[https://www.techrepublic.com/article/hack-your-pilot-legally/|Hack your Pilot legally - TechRepublic]]


==== Developer Info ====
  * [[https://web.archive.org/web/20030423184058/http://oasis.palm.com/dev/kb/present/1106.cfm|Palm OS Developer Knowledge Base: Writing Efficient & Reliable Hacks]]
  * [[https://web.archive.org/web/20080524065554/http://linkesoft.com/xmaster/developer.html | X-Master 1.5 Developer Information]]
  * [[https://daggerware.com/hackapi.htm|Hackmaster - How to write a hack]]


==== Everything About Hacks ====
By Daniel Seifert (LinkeSOFT / 79bmedia) [[https://web.archive.org/web/20060519192641/http://www.79bmedia.com/hacks/index.html | Source]]

Hacking, hackers, hacks. Four letters are in the news. And then somebody asks you - 'what hacks do you have installed on your Palm?'. But don't panic, hacks on PalmOS are nice tools to help improve your life. We develop hacks for PalmOS devices - and are often faced with users who do not know what a "hack" is. Today, the media has made the term "hacker" well-known, even to the most computer-illiterate people. Though historically a hacker is a person that enjoys computers, programming and exploring the possibilities modern communication technology has made possible, the term "hacker" (and therefore the term "hack" as well) has often a very negative touch (as it is often associated with people that are called "cracker"). But this article isn't going to be a discussion between the differences between a hacker and a cracker or about the hacker ethics.

The hacks we are talking about have nothing to do with a specific group of people or with getting in your Palm by a backdoor and stealing your data. But some people have exactly this scenario in their mind when somebody asks them "Do you have hacks installed on your Palm?"

This article will try to explain what these "hacks" are. We are trying to be not too technical, but if one or the other paragraph is still too much computer-jiggish talk, you may as well skip and and continue at the next one ;-)

If you are looking for information on why hacks do not work on PalmOS 5 anymore, please read the article [[#everything-about-hacks-on-palmos-5|Hacks under PalmOS 5]].

=== What the heck are hacks? ===

A hack is a small application (or rather a collection of program code snippets) that will improve or extend the PalmOS.

As every other operating system, the PalmOS offers a wide variety of system calls that applications use to display text, graphics or to play sounds, etc.

It is also very common to access these functions indirectly. In case of the PalmOS, there is a large table (the "trap table") that contains pointers to the various system calls. When a programmer wants to call a specific system call, he will look up the "trap number" of this system call (A) and will use it to access the function. The Palm will look at the trap table at the index specified by the trap number, and will call the function that is pointed to in this table entry (B). 

The PalmOS offers two functions to read and to set these pointers (SysGetTrapAddress and SysSetTrapAddress). This allows applications to dynamically change these pointers. This way an application could change certain OS system calls by optimized versions while it is running. Today this approach is used by an application called QuickBits which replaces certain system calls by optimized versions, thus giving a speed increase (for example in graphic output) without overclocking the system.
To go where no hack has gone before

But replacing system calls to optimize program execution is only one example. Soon developers got the idea that it would also be possible to extend or improve the operating system. This is done by either replacing the system call completely and executing code that does the same task but in a different way (more fancy, etc) or by first calling the original system call and then doing additional work on the result (see below).

Another idea was not to only extend the system calls task, but to add other (non-related) functions to it, like having the possiblity to switch between applications by certain strokes (Phlegm Hack, SwitchHack) or to simulate some kind of multitasking for certain tasks (like drivers).

===The early problems===

As system calls are limited and certain ones were very popular to be patched, there were soon conflicts. This is best illustrated by the following example. We want to take a look at a system call that resides at memory position 123. Let's call this function "Alpha".

When there are no hacks patching "Alpha", the trap table will point to the original "Alpha"-function at memory position 123.

Now we want to take a look at application "A". "A" is going to patch the "Alpha" function to extend its features. This will be done by first calling the original "Alpha" function and then doing some additional stuff. Therefore "A" will first retrieve the current pointer to the "Alpha" function. Afterwards it will install itself. The situation looks now as in the next picture:

Okay, everything is working fine. Whenever an application or the operating system calls the "Alpha" function, this is redirected to the patch installed by "A" at memory position 456. "A's patch" will call the original function at 123.

Now you like to install application "B" which is going to patch the "Alpha" function as well, this time adding another extra feature. Okay, no big deal:^

The chain is still working! Calling the "Alpha" function will both have the real "Alpha" function executed as well as the two extensions. So, no problem here. But now we are going to disable one of the two applications. If we would disable "B", it would restore the pointer in the traptable by the previous value (which pointed to 456) and we would have the same situation as two pictures above.

But what will happen when we are going to disable application "A" instead? Similiar to application "B" it would restore the pointer in the traptable by the previous value - which was 123. So the situation now looks like this: 

Now you would note that not only application "A" is not working anymore (as it has been disabled by you) but that application "B" has been disabled as well. This happened because "A" did not know anything about "B".

You think this is frustrating enough? Now it comes even worse: most users who notice that "B" is not running anymore will check why this happened. Most likely they will disable and re-enable it. But strange things could happen because when disabling application "B" it will put the pointer to A back in the trap table (how should it know that you had it disabled?). So the traptable is pointing to 456 again. This either means that you have A enabled (which can be either very frustrating or lead to a crash) or worse, if 456 is not valid anymore because you had A deleted meanwhile, you will execute random code (in best case this will lead to a reset).

There are many other possible conflict situations but the above example is depicting the problems quite well.

===The Keyes-Solution===

In 1996, Edward Keyes developed a program that was meant to solve all these kind of problems. He called it Hackmaster and it is still in heavy use all around the world. Edward Keyes' program allowed developers to concentrate on the patching of the system calls and Hackmaster would take care of the proper installation and enabling/disabling.

The current version of Hackmaster is 0.9 (a 0.91 version exists on several sites as well which you should try to find if you want to move Hackmaster to Flash Rom) and this has not changed for a couple of years. Starting in 1998 there were rumours about a Hackmaster 2.0 application with extended features, but it is not very probable that this version will ever see the light of the Palm community. (For the interested reader: Palm's Knowledge Base contains [[https://web.archive.org/web/20030423184058/http://oasis.palm.com/dev/kb/present/1106.cfm|foils by Edward Keyes]] about the history of Hackmaster and a look on the planned 2.0 release. You need to scroll down about 20% [or search for "Keyes"]).

For years, Hackmaster was the only application addressing the management of hacks and thus it established a quasi-standard - never officially supported by Palm Inc.

In 1998 an Asian software company who had written hackmaster extensions (EvEdit, ...) published their own (freeware) version of a Hackmaster compatible hack manager, called EvPlugBase. In their manager they included additional features that hack programmers could use for more comfort, but there were only very few hacks (mostly their own ones) that took use of these new features as they were incompatible to Hackmaster.

With new OS versions and the manufacturing of the first colour Palm device (IIIc), it became obvious that Hackmaster wasn't the newest application. On the colour screens Hackmaster's configuration panel did not display all buttons properly. There were other bugs that were causing problems, for example Hackmaster would crash if a hack was disabled/enabled 16 times (probably due to an internal overflow).

At the beginning of 2001, two (fully compatible) Hackmaster replacements were published. One is TealMaster (shareware, US$ 9.95), the other one X-Master (freeware).
You can already note that these two applications are not using the "term" hack anymore, but are rather trying to introduce a new synonym: system extension.

Yet Another Hack Manager was released in October 2002 by Igor Nesterov. YAHM is freeware and supposed to be the hack manager that prevents most conflicts.

In the following sections we will use X-Master as hack manager, though YAHM and TealMaster would do the job as well. If you are still using Hackmaster, it is recommended to update to YAHM, X-Master or TealMaster as they are fully compatible to HackMaster but fix a number of bugs and problems.

===Remaining Problems===

With the introduction of Hackmaster or similar applications, many problems with hacks have been resolved, especially the one outlined above. But there are still possible conflicts, mostly as a result how the hacks work. For example some hacks do not call the original function, thus interrupting the execution chain, disabling other hacks patching the same trap (but this is a very rare event).

Another "problem" with hacks should be mentioned as well: as they usually require to retrieve the pointer that was previously set, hacks use so-called "Features" (4-Byte values that can be stored and sorted by application and access number). Accessing these features is quite slow and a hack that patches an often-called trap could slow down the Palm by some percent. But most probably you won't notice the difference. 

===Finding the culprit===

Whether a hack is causing a certain problem is often hard to say as quite a lot of hacks are executing some parts of their code every now and then, mostly regardless of the application you are running.

If you experience strange events (like crashes), regardless of the application that is currently running, it is well likely that a hack is causing the problem. But if only a certain application is affected, it could be a bug in the application, too.

The first step in any case is to disable all hacks. You will have to do this anyway, as some application developers will sometimes neglect support if you mention that you have any hacks running. In general, you should keep in mind that giving support is connected with costs for the developer because it requires time (and time is money). So it is not a good idea to write to a developer saying that his hack has a bug, when in reality the application has a bug. But it is not a good idea either, to write the applications developer if the hack is responsible. It should be a matter of fairness to try to sort out who is causing the problem before starting to send any mails to the wrong support address.

Okay, as said the first step is to disable all hacks. Paranoid users might want to do a soft reset to be sure that they are really disabled. Another possibility is to keep the page-up button pressed at reset-time, this way all hacks (even "hidden hacks", see below), will be disabled. You should make a standard soft reset after you finished your tests.


Advanced users can use X-Master's "List all active" menu item instead, to get a list of all the traps that are patched, including the name of the hack(s) that have patched the traps. This way experienced users can sometimes sort out which hack is causing the problem: an hack patching a trap that is responsible for displaying icons and a Palm that crashes when it wants to display an icon usually indicate who the culprit is.

But usually this won't do the job. So after disabling all hacks, you should try to reproduce the problems. If you were able to find a certain way to trigger the bug or the crash, try to repeat this now. If the problem only happened sporadically, you would have to work with the device (while hacks are disabled) for a while to see if the problem is gone.

If the problem is not gone, it apparently wasn't one of the hacks (but read the next section about hidden hacks!). On the other hand, if the problem is gone, you will now have to sort out which hack is causing the problem. To do this, you need to enable one hack after the other until the problem comes back. This in general means that the latest hack enabled is either the culprit or the one that triggers a conflict with another hack that is already enabled. It is recommended to disable all the other hacks except the suspect one to see if it is really causing the problem or whether another hack has to be enabled at the same time.

Now you should start to write a mail to the developer. Please spent some minutes for this mail. Just sending a mail like

From:  
angry@customer.org 
To: 
hack@author.com 
Subject: Your hack sucks! 

Hey, I  just installed your hack and it crashes my system.

is not very helpful.

Instead, you should describe the problem and your setup in detail:

From: 
friendly@customer.org 
To: 
hack@author.com 
Subject: Problem when  selecting red icons 

Hi, I just installed your hack [hack-name] and it  causes a problem. 
When I have it enabled, tapping on any red icon will  crash my Palm 
with the error message "MemMgr.c, line 1394: error  message".

I am using version 1.23 of your hack. Other hacks installed  and 
enabled are HackA (v. 2.41) and HackB (v. 1.0). I am using a Palm 
Vx with OS 3.5.2. 

This will give the developer probably all of the information that he needs to reproduce the problem and hopefully to fix it. Here's the complete checklist:

    The Palm device you are using including the correct OS version
    The version of the hack you are using (it is recommended to check the developer's website to see if any update has already fixed this bug) and a list of all the other hacks that are running, including their versions.
    A complete and detailed description about what is happening and ideally a description how to reproduce it.

Giving these information is crucial to find the problem, especially for more complex hacks. While small hacks are not so problematic, complex hacks are, well, complex :-) And as hacks are often not executed in a predictable order or time, debugging can become very difficult. The more information you give, the better the developer can help you.

===Hidden hacks===

As already mentioned, "hacks" have a negative association, so many people do not use them. To address these users, some of my applications have a "standalone" version that does not use Hackmaster but will patch the traps itself. These versions will complain if Hackmaster or another hack manager is found.

Other companies sometimes do only release a "standalone" version (i.e. drivers, ...) and it is not obvious for most users that these applications are hacks in reality. Even worse, using one of them can sometimes cause problems when used in conjunction with Hackmaster as the same conflicts as described at the beginning are possible again. I've written a little application called HackFinder that will scan all installed applications whether they include code to install a hack. 



==== Everything About Hacks on PalmOS 5 ====
[[https://web.archive.org/web/20060813141020/http://www.79bmedia.com/hacks/hack5.html|Source]]


After we know about what Hacks are in the first place, and really got to like them on PalmOS 3 and 4, what happened to them on PalmOS 5 (Garnet)?
Preface

If you do not know what hacks are in the first place, please read the article Everything about hacks first.

The following paragraphs will try to explain what happened to hacks on PalmOS 5, how they can be replaced, why the old hacks do not work anymore and what TealMaster's PalmOS 5 support is all about.

As said before, if you do not know what hacks are anyway, please read the Everything about hacks article first (I mean it! ;)).
Architecture

PalmOS 1.0 up to PalmOS 4.1 ran exclusively on processors by Motorola (m68k family). With PalmOS 5 and future versions of the OS, Palm decided to use ARM processors instead. These processors are fast and energy efficient, so there's an exciting future ahead of the PalmOS community.

But, as with most changes, things had to be left behind. One that couldn't be left behind was the ability to execute the already existing mass of applications. That's why Palm included PACE into PalmOS 5 to allow the execution of m68k Palm applications on the new processor. PACE (running silently in the background) is emulating the m68k processor and all applications that are coherent with the programming guidelines for PalmOS will still be running on PalmOS 5.

But, by nature, hacks are not following the programming guidelines. As outlined in the article Everything about hacks, hacks are changing PalmOS system calls and are often interfering with the OS on a somewhat deeper level.

Now, ARM processors use a completely different byte ordering. The m68k CPUs uses big endian (the most significant byte comes first), the ARM processors, as well as the Pentium line, btw, use little endian (least significant bytes come first). Let's take a look at an example. Consider that we would want to store "UNIX" in two words (1 word = 2 bytes). On big endian systems like the m68k CPUs, "UNIX" would be stored as "UNIX". On little endian systems like the ARM CPU or your Pentium III at home it would be stored as "NUXI" (you see, different byte order).

Now, PACE makes sure that our emulated m68k PalmOS applications get all their values in the right order (e.g. swapped). But hacks are working on an entirely different level as they are transparent to the system. So a hack on PalmOS 5 would get the data in the wrong order and would behave most strangely. Also, with an emulation level and the completely different architecture, PalmSource decided to drop the possibility to change the system calls - and thus stopped hacks to run on PalmOS 5 - officially. As a compensation they introduced notifications which will be discussed in the next section.

As sad as the loss of hacks is, there's just been no other sensible way that PalmSource could have gone. So let's not moan too long :-)

Literature on endian order for the interested reader:

  * [[https://web.archive.org/web/20060810185926/http://www.webopedia.com/TERM/B/big_endian.html|Webopedia's definition of big and little endian]]
  * [[https://web.archive.org/web/20060814042044/http://www.cs.umass.edu/~verts/cs32/endian.html|An Essay on Endian Order]]

=== Patching PalmOS 5 ===

Early 2003, PalmOS developers found out how to replace PalmOS 5 system traps, too. This way it was possible to port Crash to PalmOS 5. Unfortunately, this process is more complicated than for hacks on PalmOS 4 and earlier and not officially supported by PalmSource. There is no documentation and usually involves a lot of guess-work. Theoretically it would be possible to port most hacks this way to PalmOS 5, but it would require quite some work. Lately things got a little bit easier with a new hack manager for PalmOS 5: YAHM. YAHM won't be able to support your PalmOS 4 hacks as this is just not possible (see below for a discussion about TealMaster's support of hacks in PalmOS 5).
Notifications

To compensate for the lack of hacks, PalmOS 5 sees a much improved notification manager which is part of the OS since PalmOS 3.5. Basically it's very simple to use and understand.

The PalmOS has a certain set of possible notifications, for example:

  * device has been powered on
  * device is going to sleep
  * etc etc

You can see the complete list in the [[https://web.archive.org/web/20060721234705/http://www.palmos.com/dev/support/docs/palmos/Notifications.html|PalmOS 5 Notification Manager chapter]].

Any application can register for a notification. For example, application A could register for sysNotifyLateWakeupEvent and will be notified when the device has finished waking up. That simple ;)
Porting Hacks to PalmOS 5

The prefered solution on how to get a hack to work on PalmOS 5 is changing it to use the notification manager. See below for comments on using TealMaster 2.0.

Of course, this can be only done when suitable notifications do exist. While there are quite a few notifications, not every patched system call can be changed to use notifications. Hacks relying on patching these system calls may be ported by using the framework supported by YAHM - check with the hack's author if there are plans to port it to PalmOS 5. But keep in mind that even with YAHM this won't be an easy job as patching PalmOS 5 (while made easier by YAHM) is still mostly undocumented.
TealMaster

TealMaster 2.x from www.tealpoint.com states to support selected hacks on PalmOS 5. Many users reading this (or a press overage of it) assume that this means ANY hack can be run using TealMaster. But this isn't correct, only a certain subset can.

What exactly does TealMaster do on PalmOS 5? Well, as can be looked up in their [[https://web.archive.org/web/20070115012635/http://www.robofish.com/download/dev/mstr_os5.txt|Developer Guidelines for hacks on PalmOS 5]], they are mapping the patching of certain system calls to corresponding notifications (which is a valid approach, matter of fact NetSelect does the same to be PalmOS 5 compatible).

Problem with this mapping is that only seven specific system calls can be mapped to notifications (listed in the above document). Now, with far more than 1000 system calls available - and even considering that not all of them are suitable to being patched - this is only a very tiny number.
Should I use TealMaster?

If you want to use a specific hack and wonder whether TealMaster is appropriate to get it to run on PalmOS 5, go through the following list:

  * Check the homepage of the hack to see whether the developer has made available an update that runs on PalmOS 5 without requiring TealMaster. If not, check if there is any statement on PalmOS 5 compatibility.
  * Check at TealPoint's webpage the list of supported hacks. At the moment the list of hacks known to work with TealMaster is quite small. But as quite a lot of hacks are patching the 7 system calls covered by TealMaster, this list will probably grow a bit in the future. If a hack is listed there, it will probably work with TealMaster.
  * If neither the developer has made available a PalmOS 5 version of the hack (which might in several cases be indeed impossible) nor TealPoint lists this hack, you should consider looking for an alternative software application that does this task on PalmOS 5. As most hacks and their tasks cannot be implemented on PalmOS 5, there is only a small chance that this approach succeeds, though.
  * Try TealMaster. Be sure to read the manual.

Generally you can often make a good guess whether a hack will work with TealMaster: if the hack only does simple things at power-on, if the hack brings up a window when you draw a line or press keys. If the hack does more fancy stuff at uncommon situations (at a crash, when a sound is played, when an alarm is displayed, etc), it most likely will not work with TealMaster.