StarfixCoreSpecifications

From OpenRPN

http://media.openrpn.org/Starfix-Logo-Final-2.png

Contents 1 Core Specifications 2 Design objectives 3 UserRPL References 3.1 Language Specification 4 Real Numbers 5 Complex Numbers 6 Strings 7 Arrays 8 Lists 9 Binary Integers 10 Procedure Objects 11 Name Objects 12 Function Execution 13 Conditional Branches 14 Loops and Iteration 15 Standard Errors 16 The Stack 17 Modes and Flags 18 Key Assignments 18.1 *fix Core Architecture 18.2 Interface with The Operating System 18.3 Development Environment 18.4 Testing and Quality Assurance

[edit] Core Specifications

This document represents the current thinking for the core architecture. A prototype application is currently being developed on Linux (but should be largely platform-independent, since it is for now entirely text-based). As more elements become available, the code will be moved on top of eCos and towards the ARMulator and later the real hardware.

[edit] Design objectives

The goal is to implement a *fix interpretor that will run on top of [eCos]. *fix will then be used to develop the user interface for an RPN calculator with a command set similar to that of the [HP-42s]. The purpose of the *fix core is to provide the tools to create calculators from scratch with relative ease. The *fix core will be written in EmbeddedCPP eC++, a subset of ""C++"". The main limitations of which are the lack of exception handling and STL. There will be a clear separation of the core and the math library, in order to switch math libraries at either compile or run-time. *fix will borrow its' command set largely from ""UserRPL"" with the *fix core being a minimal subset of *fix. Additional functions may be added to the core if their performance becomes an issue. We will try to maintain general compatibility with ""UserRPL"" although we will aim for greater simplicity whenever possible (ex. incidental flag/mode changes during command execution will return to their original state following execution). *fix offers prefix, postfix and infix syntaxes. The initial version of *fix core will focus on postfix and infix syntax compatible with User RPL, with some limited prefix additions. Later versions will allow full programs to be written in any style and edited in any other.

[edit] UserRPL References

- HP48 Insights - Part 1: Principles and Programming HP48G/GX Edition, by William Wickes (""MoHPC"" DVD) - [HP48 AUR] - [HP49G+ AUR (pdf)]

[edit] Language Specification

• fix is largely compatible with ""UserRPL"". The syntax is simple. All tokens are separated by white spaces. ""UserRPL"" has some special characters, like the left arrow or the double brackets to indicate the start and end of a program. In *fix, for convenience, we are using ##<<##, ##>>## and ##->## directly.

• • object types**

In order to ensure some compatibility with RPL, *fix defines a ##TYPE## command that returns the type of an object on the stack. The following types are defined:

Type Code	Object type
0	Real number
1	Complex number
2	String
3	Real Array
4	Complex Array
5	List
6	Global name
7	Local name
8	Program
9	Algebraic object
10	Binary integer

We may define an ##SFTYPE## command that would return extended type information, for example for various implementations of Real numbers, or the size of binary integers, etc.

[edit] Real Numbers

We want to use ""eC++"" to abstract Real numbers in the core, in order to allow for different internal representations and speed/accuracy trade-offs. When evaluated, Real numbers are pushed on the stack.

[edit] Complex Numbers

Complex numbers are based on Real numbers, and are part of the arithmetic library that is loaded separately. When evaluated, Complex numbers are pushed on the stack.

[edit] Strings

Strings are implemented as C strings, and provide the usual set of functions: concatenation, comparison, substring extraction. In addition, it is possible to call the parser on a given string with ##STR→##. When evaluated, Strings are pushed on the stack.

[edit] Arrays

Array Creation Single-Element Operations Row and Column Operations Subarray When evaluated, arrays are pushed on the stack.

[edit] Lists

• fix comes from RPL, and since RPL stands for Reverse Polish Lisp, the list is one central element in *fix. Lists are available at the user level, and are also used internally to implement stacks, arrays, functions.

A list contains an ordered sequence of other objects. These objects can be Real or Complex numbers, List, Array, Strings, etc.

• • List Element Commands**

• • List Mathematics**

List mathematics (sum elements of a list, product of elements of a list, etc) can all be implemented in *fix itself. The y are not part of the core.

• • Sublists**

• • Lists as Procedures**

When a list is evaluated, it is considered as a procedure object, and each of its elements are evaluated in sequence. For example, the following two expressions give the same result:

1. 1. { 1 2 + } EVAL##

and

1. 1. << 1 2 + >> EVAL##

[edit] Binary Integers

Binary Integers are 64-bit wide. The core includes the basic 4 operations: add, substract, multiply, divide, along with the various shift left, right, arithmetic shift, and various base representations (hex, octal, decimal, binary). When evaluated, binary integers are pushed on the stack.

[edit] Procedure Objects

When evaluated, execute its elements.

[edit] Name Objects

Global Names Local Names Name Resolution

[edit] Function Execution

When evaluated, execute the binary code that makes up its definition.

[edit] Conditional Branches

The *fix core includes RPL's structures for control: ##IF..THEN..END##, ##IF..THEN..ELSE..END## and their pure postfix equivalents ##IFT## and ##IFTE##. Case statements are there too: ##CASE..END##

[edit] Loops and Iteration

1. 1. DO..UNTIL##
   2. FOR..NEXT##
   3. FOR..STEP##
   4. START..NEXT##
   5. START..STEP##

In addition, ##DOLIST##, ##DOSUBS## allow iterations on Lists.

[edit] Standard Errors

[edit] The Stack

Infinite stack (limited only by the available memory). Basic stack functions are included in the core: ##DUP DUP2 DROP SWAP DEPTH OVER CLEAR ROLL ROLLD ROT##. Some of these functions (e.g. ##DUP2##) are easy to write in *fix itself, but these functions are used a lot, and should be in compiled form.

When an object is duplicated (e.g. ##DUP##) on the stack, the new element contains only the address of the original object.

[edit] Modes and Flags

• fix core includes the basic trigonometric modes: ##DEG RAD GRAD##, and the control of the number of displayed digits: ##STD FIX SCI ENG##.

User and system flags are defined to be compatible with RPL.

[edit] Key Assignments

In RPL, key assignment is used to customize the calculator. With *fix, this becomes a central mechanism for configuring the keyboard. We have to make sure it provides all the necessary mechanisms for allowing total configurability of the machine (except for on/off and enter key, for obvious reasons).

• fix has extended keybinding mechanism, allowing to bind single, double and long key presses. Basic functions are like RPL: ##ASN##, ##STOKEYS##, ##DELKEYS##. ##ASN## can be extended to handle double and long clicks, for example with a format like //rc.pfdl//, which would ensure backward compatibility.

The entire keyboard configuration is defined in *fix (not just user mode), and kept in one init file on the flash filesystem.

[edit] *fix Core Architecture

- Modularity, modularity, modularity. - limit the amount of global variable and make the code reentrant as much as possible. - Memory management: need to define policy for where to do allocation/deallocation, or evaluate garbage collection techniques - Exception handling - compiled library mechanism - Debugger, single-step execution, breakpoints

• • Memory management**

When the stack duplicates an object, it actually creates a pointer to the original object. When objects are stored (with ##STO##) a copy is stored. HP's RPL uses a mark and sweep garbage collector. We want to evaluate also the opportunity for reference counting, as with large memories (1MB) garbage collection may sometimes get in the way and generate longer response time.

A prototype implementation of *fix core exists and can be browsed [here].

Some [tasks ] have been defined in order to bring *fix core to a level where it can be ported on top of eCos.

[edit] Interface with The Operating System

Integrate *fix with [eCos]. Apart from building the application in the eCos environment, we will define the API for the input/outputs: keyboard, LCD, filesystem, timers, etc. The *fix core interpreter is event based and runs as one thread on eCos.

//We need to check if ""eCos""'s development environment has a floating point library. Otherwise, only BCD20 will be used.//

[edit] Development Environment

The development and test environment will be the *fix core running on top of [eCos] using ARMulator. The ""eCos"" development environment is supported on both Linux and Windows. Note that eCos Pro is Eclipse-based and costs $60.

[edit] Testing and Quality Assurance

We need an automated build and test mechanism and unit tests for every command. Regression tests are a critical part of this project: a calculator is something you want to be able to rely on... ""OpenRPN"" machines must set the gold standard for accuracy and reliability in handheld calculators.