User:Doruletz72/ONBA/Overview

INTRODUCTION

Older Palm OS devices are equipped with Motorola DragonBall 68k processors. The newer Palm OS/Garnet OS devices are equipped with better ARM series processors. All ARM devices can run any application written in 68k assembly language, because in fact the Palm OS/Garnet OS allows an emulation for this type of applications.

Palm OS memory

Even if Palm OS devices can handle external memory devices, they are mainly designed to use internal memory for either purposes: to store data and to run application. The main difference between the internal memory and external memory cards is how they are powered. Usually external devices are not powered in contrast with internal memory which are permanently powered. For a desktop PC or a laptop, we usually refer to the internal memory as RAM (used to run applications) and the storage memory as hard-disks, floppy-disks, optical-disks or pen drives to store data such as files. For Palm devices both parts of memory, RAM and storage are parts of the internal memory. Because of this and because of low size of internal memory, the files from storage area are accessed and modified in place, without creation of streams in memory.
The basic element of the internal memory is the chunk. A chunk is a portion of contiguous memory (without gaps). The size of a chunk can be between 0 and 64 kilobytes, and can be dynamically modified. Because of "limited size memory" policy, these chunks are not fixed (at fixed address), they can be moved as situation requires. After the creation, the OS return a handle variable to refer the chunk. But for effectively read/write of the data from/to the chunk you must signal the OS to stop juggling the chunks. So you need to lock the movable chunk, addressed by a handle, into a fixed chunk, addressed by a pointer. After you finish with data read/write of the chunk, you must unlock the chunk. This policy of movable memory chunks is found in many other devices. Is not 100% specific to Palm OS devices.

Palm OS files

Because the files are stored with the running application in the internal memory, for fast and easy access, Palm OS has designed the structure of files like a collection of chunks, like a database of chunks. I.e. a chunk of memory allocated to a variable (in RAM area) can be easy translated to a chunk of a file (in storage area). There are two types of files: PDB and PRC.

• PDB - palm database is the Palm generic file. Here you can write any sort or kind of data. It's depend only of you, how to write and then how to read the data from a PDB file.
• PRC - palm resource collection is a special database Palm file who holds resources such as icons, bitmaps, strings, forms etc.

Both type of files have a header which are stored information regarding type (pdb or prc), unique identifier, name (they don't store an extension), size etc. After the header follows the contents of the file, organized as a collection of records. Each record have a header which are stored information regarding unique identifier, contents and size of the record. Depends on OS version, contents of a record can refer one or more chunks of memory.
Note: The "contents" not contains the effective data, only the references to the memory chunks.

PRC executable files

PRC files can contain specially records, which allow the file to be executed. These type of records are:

• DATA - here are stored information about the contents of the globally variables of an application
• CODE - here are stored the binary code of an application

Application can have one or more DATA and CODE records, indexed by a value. Using the information stored in these records an application will build in RAM corresponding segments of memory, named in same manner. To avoid confusion we will refer the memory from RAM area with "segments" and the memory from storage area with "records".
Note: Any executable PRC file must have a DATA, a CODE 0 and a CODE 1 records. CODE 0 is not in fact a code record, but a specially data record where is stored the size of so called "A5 world". Will talk later about this.

RUNNING AN APPLICATION

When an application is running, it will create and access 4 portions of memory, called segments:

• GLOBAL SEGMENT - here are stored your global variables (outside of the routines), visible to entire application; this segment is referred by A5 register, which contains the base address of the global segment; the GLOBAL SEGMENT are built at the initialization time, using information stored in DATA record.
• STACK SEGMENT - here are stored your local variables (visible only inside of the routines); it is referred by A7 register; additionally inside of the routines it can be referred by A6 register; the STACK SEGMENT are built at the initialization time, and is no fixed in size; it can be dynamically increased or decreased while application is running; the only matter is the maximum value size of this segment specified in CODE 0 record; if the size exceed this value, an overflow will occur, usually signaled with strange behaviors of your application; this because the next portion of memory will be overwritten, the GLOBAL SEGMENT and your global variables will be compromised.
• CODE SEGMENT - here is stored your application code, a lot of instructions, binary coded; under Palm OS for this segment there is no memory allocation, just a simple "lock" of the corresponding CODE record; this segment is referred by PC register; additionally inside the CODE segment can be stored data constants; the CODE SEGMENT is read-only (i.e. you cannot overwrite the application file contents).
• DYNAMICALLY SEGMENT - this is a pseudo-segment; while application is running it can dynamically allocate memory (WinCreateOffscreenWindow, MemNewHandle, MemNewPtr etc); the references returned can be stored in both global and local variables.

Onba01

So at the moment of initialization, application creates the GLOBAL SEGMENT (A5 reference), based on size and values of global variables stored in DATA record. Then creates the STACK SEGMENT, based on maximum size stored in CODE 0 record. After that, application locks the CODE 1 record and starts to execute the first instruction of it. The CODE record is not needed to be loaded into memory because the access speed to its data is the same; as I said before both portions of RAM area and storage area are parts of the same internal memory. While application is running - meaning the instructions from CODE record is loaded and executed one by one, and the PC register contains the address of the current instruction - all local variables which can appear at one time are stored/discarded on/from the stack (STACK SEGMENT), the address of the top of stack being referred by A7 register. When you call a routine/procedure/function, inside the stack is created a frame stack referred by A6 register. In case of multi-segment applications, on demands, the current CODE record can be unlocked and a new CODE record is selected and locked. The value of PC register is updated to reflect the changes. This is called segment jump.
You was a spectator of creating and running of a so called A5 world. Term comes from Mac OS, because Palm OS is based on it. A5 register refers the main segment of an application, GLOBAL SEGMENT. So if there is no GLOBAL SEGMENT, there is no application, there is no A5 world. In fact Palm OS by itself it is an A5 world, the primary world.

INSIDE 68k PROCESSOR

We will try to take a close look inside of the DragonBall 68k embedded processor. If you want to know more details about 68k processor, I recommend you to consult the original 68000 Motorola Data Sheet, available at http://www.freescale.com/files/archives/doc/ref_manual/M68000PRM.pdf. Besides many others functions, our interests here will be the registers, address modes and the instructions set. For an easy understanding we can assimilate the processor with our brain. If the brain have a job to do, it will access its basic cognitive functions (the instructions set), configures a proper synapses constellation (the address modes) of its neurons (the registers). When the situation demands to store some information, it will write it to an external memos, book or whatever (internal memory, external memory card). To do this the brain need to access/command the pen or the pencil through the hand to write the information (I/O ports).

The registers

Question: Which type of memory are faster? The cache or the RAM? Wrong question, correct answer: the registers. They are the fastest pieces of the memory for the processor. The processor by itself is designed to work directly with its neurons, the registers. So as often as you can use the register variables instead of other variables to maximize speed of your program. DragonBall has 8 data registers, 8 address registers, one status register and one program counter register.

Onba01

• Data registers (Dn) (32 bits each) are numbered D0 to D7. They are identically in use, in contrast with Intel data registers AX/AL/AH, BX/.... which have special purposes. However, D0 has a special purpose. It is commonly used as return placeholder for the procedures which return values. You can use any Dn register to do this, it is only up to you where/from write/read the return value. But keep in mind, the Palm OS system functions will use only the register D0 to return a value. Data registers can hold byte/word/long word values, signed or unsigned.
• Address registers (An) (32 bits each) are numbered A0 to A7. They are identically in use, but not like data registers. A0 is commonly used as return placeholder for the procedures which return address/pointers. You can use others An register to do this, it is only up to you where/from write/read the return value. But keep in mind, the Palm OS system functions will use only the register A0 to return an address/pointer. A7 or SP (stack pointer) has only a purpose, to keep the current program stack pointer (point to the top of the program stack). A6 is commonly used to keep local pointer stack or the frame stack (inside the procedures). A5 is used to keep the base address of the GLOBAL SEGMENT and to refer the global variables. When working with address registers, keep in mind the followings:

• check for even values, because this is a source of hard to handle errors; the memory is word aligned and it start at an even address; so when you work with arrays of bytes or when you access an element of a string, pad with an additional null terminator '\0' to keep the even memory alignment or you will get an evil memory error; fortunately, in most cases the OnbA will do this automatically for you
• always, the values held by address registers are signed, because at any moment you must be able to refer memory in both direction backward (-) or forward (+) regarding your current position; so the range of the values stored by address register is from -2³¹ to +2³¹

• Status register (SR/CCR) it is a 16 bits register. The lower byte is known as flags byte or condition code register (CCR). It contains 5 flags (1 bit/flag) to reflect the result of an instruction:

Onba01

• X - extended bit; it is set to the value of C bit for arithmetic operations; otherwise not affected or set to a specified result.
• N - negative bit; it is set if the most significant bit of the result is set; otherwise is cleared.
• Z - zero bit; it is set if the result equals zero; otherwise is cleared.
• V - overflow bit; it is set if an arithmetic overflow occurs; that means the result cannot be represented in the operand size; otherwise is cleared.
• C - carry bit; it is set if a carry out of the most significant bit of the operand occurs for an addition, or if a borrow occurs in a subtraction; otherwise is cleared.

Note: - set means 1, cleared 0
The upper byte is known as system byte and is accessible along with flags byte. In this case we will use SR mnemonic instead of CCR. It is called privileged access. To access the whole SR we must set the S-bit (bit 13) first.

• T1,T0 - trace mode
• S - supervisor/user state
• M - master/interrupt state
• I2,I1,I0 - interrupt priority mask

• Program counter (PC) - it refers the current instruction to be executed from the currently locked CODE SEGMENT. During instruction execution and exception processing, the processor automatically increments the contents or places a new value in the PC. For some addressing modes, the PC can be used as a pointer for PC relative addressing.

Address modes

If you are not familiar with assembly programming, this part will be a little bit difficult than you meet by now. If fact 50% of the time, you will spend it to make a proper address of your variables. Classic high level language, like C, don't bother you too much regarding the concept of address mode. Simply you use the names of your variables and only concern for you is: it is a value or a pointer? Perhaps the arrays or structure types can challenge you a bit. But not too much.
When you disassemble an executable file you will have the surprise to find no variables, routines or operators names. Perhaps some useful numbered labels put in place by the disassemble software to help a bit. On the other hand the OnbA directives are not so rich regarding names of variables. So the only way to deal with this is to understand where are your variables and how to address them. There are 5 types of address modes:

• Direct
• Indirect
• Absolute
• Immediate
• Implied

We will not insist here too much because you can find all information in chapter Address Modes of this book.

Instructions set

What is an instruction? Hard to define. Many of your "high-level" usage of various concepts , by example the operators, here in fact are instructions: addition (+) ADD, subtraction (-) SUB, multiplication (*) MUL, division (/) DIV. Why? Well arithmetically speaking the operators are operations. In fact, the "operator" term has an algebraic use. But this is another point of discussion. Anyway instructions are not they seem to be.
More information can be found in chapter Instructions Set of this book. But for now I strongly recommend you to read the next chapter Assembly Language Elements.