Punix Files

Readme for Punix (beta)
by Christopher Williams

Getting started
===============

Download one of the xxu files (such as punix-9x-beta5.9xu) and open
it as a ROM or basecode in your favorite TI-92+ emulator (I use TiEmu).
Start the calculator if it is turned off, and Punix should start right
away.

Starting with beta 5, you can also install Punix on a real TI-89 or
TI-92+. See the section "What is new in Beta 5?" for more details.

What does Punix do?
===================

First of all, please keep in mind that these are all beta versions. Many
features are missing or incomplete, or just plain buggy.

Currently, Punix doesn't do much from a user's perspective. Here is a
short list of things that it can do:

* Run a small number of (simplified) Unix utilities (sh, top, cat,
  true, false, clear, uname, env, id, date)
* Play sound! (Run "tests audio" from the shell)

Here is a longer list of things that it can't do:

* Run real programs
* Anything else

As of beta 3, Punix can do full multi-tasking. That said, you can't run
any real programs because there is no file system yet. This is one of
the last pieces to develop before the system becomes useful.

What you can do
===============

Test Punix as much as you can. While the kernel is yet incomplete, I
would like to be sure that the parts that do work are bug-free.

Play with the console. The keyboard input and screen text output should
work flawlessly. The console is a fairly complete VT100 terminal
emulator, so go ahead and test as many escape codes as you can.

Try all of the different commands available from the shell (type "help"
from the shell for a complete list). There are very few commands, so
this won't take much time.

Run the "tests" command from the shell. This runs a few tests on some
device files (/dev/random, /dev/link, and /dev/audio). The /dev/random
file returns random bytes generated inside the kernel, and the test
prints out a sample of those bytes as 16-bit unsigned integers. The
/dev/link test will receive a variable through the link port (it
displays the contents to the screen as of beta 3). Last, the /dev/audio
test plays stereo sound through the link port; TiEmu lets you play this
sound with the "Emulate Sound" option. These tests are rudimentary but
they can give you a small sense of what devices Punix supports.

If you're a programmer and feeling somewhat adventurous, try adding a
few commands to the shell! Download a ZIP containing the source code, or
checkout code from the SourceForge SVN repository. The shell and all
user programs are found in usermain.c. This file is essentially a
playground to test the functionality of the kernel until the kernel
supports loading programs from a file system. Look for the "applets"
array in usermain.c and add another applet to that array following the
example of the other applets. In particular, try adding commands that
exercise various system calls*. For example, test out the setitimer()
and getitimer() system calls with different parameters, including
invalid parameters to test the error handling in Punix.

*The C entry points for system calls are found in userstart.s. If a
system call that you want to test is not in there already, look up the
system call number in the file include/syscall.h, and then add a
constant (such as "SYS_exit = 1") and use the "mkstart" macro to add the
entry point (such as "mksyscall exit").

What is new in Beta 5?
=====================

This is the first beta to run on real hardware! I am currently running
Punix on my TI-92+. It's still highly incomplete, but the hardware
drivers have been proven to work correctly on the Real Thing. As a real
calculator has limited power (batteries), this release now supports
power-off with the key combinations 2nd-ON or Diamond-ON.

This beta also includes a short clip from The Blue Danube Waltz (to
demonstrate the audio capabilities) as well as preliminary grayscale
support. The console font has been anti-aliased to take advantage of
this new grayscale support.

For those who are interested in running this release on their own
calculator, here are some quick installation instructions. First make
sure that you have a GraphLink cable (or a homemade variant) and TiLP
installed on your computer. TI-Connect might work as an alternative to
TiLP, but I've never used it so I can't say whether it works.

1) Start TiLP and navigate to the directory that contains the .9xu/.89u
   file.
2) Pull out one of the calculator's batteries.
3) Reinsert the battery while holding the APPS key until the bootloader
   screen appears (It will say "Press I to install product code...").
4) Press "I". The bootloader should say "Waiting to receive..."
5) In TiLP, drag the appropriate .xxu file from the computer side to the
   calculator side. If you have a TI-92+, drag the .9xu file. If you
   have a TI-89, drag the .89u file. (Sorry, only these calculators are
   supported currently.)
6) Wait for the transfer to complete. This should take a couple minutes.
7) Punix will automatically boot after installation.

If the transfer fails, you may have to repeat step 5, or possibly steps
2 through 5.

Please be aware that Punix does not have an "Auto Power Down" (APD)
feature yet, so you will have to power down the calculator with 2nd-ON
when it is not in use.

What is new in Beta 4?
======================

This beta release now includes a user login! This is done in the same
way as it is done in a real *nix system: the init process spawns a
"getty" process for each console and serial line, which prompt for a
login on each line. When the user types in a username, getty executes
the "login" program with the username as an argument. The login process
prompts for a password, and upon the user typing in the correct username
and password combination, login executes the user's shell.

Of course, the getty and login programs in this release are extremely
simplified versions and are mostly for show. User "root" for the
username and a blank password to login.

The next feature in this beta is a (admittedly stupid) terminal program.
Use it to connect to another calculator over the I/O data link cable.
Here is how to use this feature:

1) Run punix-9x-server-beta4.tib* on one calculator in TiEmu and
   punix-9x-beta4.tib on another in TiEmu.
2) Set the link settings to "Cable: TiEmu" and "Port: #1" on one
   calculator, and set the port to #2 on the other.
3) Also disable "Listen for files" on both calculators.
4) On punix-9x-beta4.tib, log in (username: root, password: (blank))
   and run the uterm program.

After you follow these steps, you should receive a "server login"
prompt. This prompt is coming from the calculator with the hostname of
"server". If you receive the message "/dev/link: Device or resource
busy", then you probably tried to run uterm *from* the server. Try again
with the other calculator.

From uterm you can run all of the same commands as you would normally.
There may be lag in the display, but this is normal (all data is being
sent over a relatively slow serial link, after all). One command that
will prove that you actually are connected to the other calculator is
"poweroff". Run "poweroff" in uterm and watch the other calculator shut
off! Press the ON key on the calculator that shut off to resume.

If you play with uterm long enough, you will see its limitations. For
one, uterm does not run in raw tty mode, so it cannot send special
characters (eg, ^D or ^C) to the remote host. Second, /dev/link on the
remote host does not act as a tty, so it would not interpret special
characters correctly anyway. The tty driver code is one component that
will need improvement before a full release.

This release also includes a couple added commands: time and times. The
time command will run the given program and then print the real, user,
and system time used by the program. The times command prints the user
and system time used by the shell and cumulative time used by the
shell's children.

Next, this beta can now run on the TI-89! The smaller screen and
different keyboard layout are the only practical differences from the
TI-92+ version. This version can be compiled by changing the CALC
variable in the Makefile from TI92P to TI89 and then running "make
scratch". The make steps for the 89 version have not been finished yet,
it's best to make from scratch each time.

Last, this release includes a few bug fixes and reduced memory
footprint, but you probably will not notice any of these changes.

*Note: to build the "server" version, just change UNAME_NODENAME from
"timmy" to "server" in the Makefile, then run "make" as usual.

What is new in Beta 3?
======================

First and foremost, the vfork() system call now works! This means full
multitasking. There are still many other pieces missing to make a usable
multitasking system, but the foundation is nearly completed.

Beta 3 includes a few more commands in the shell:

* poweroff. This simply powers off the calculator. It does not reboot
  the OS as the same command does in Linux.
* pid. This displays the process id of the current shell. In this
  beta release, each shell starts in its own process, and you can find
  out the process id of the shell with this command.
* status. This displays the exit status code of the previous
  command. This is analogous to "echo $?" in a full Bourne shell.

The "/dev/link" test (accessible with the "tests" command) now displays
an image file that you send to the calculator. Just send a .92i or .9xi
file to the calculator when the test says "Receiving variable...". This
code assumes that the image is the full width of the screen, so if you
send it a narrower image it will look funky on the screen (but it
shouldn't crash the system or anything).

Another addition is the "CPU busy" indicator. A small hourglass is
displayed in the status line whenever a user process is actively
running. This is similar to the "BUSY" indicator in TI-AMS.

Here is something to try: run a shell within a shell within a shell...
by running "sh" many times. With the current stack sizes you can run up
to 36 concurrent shells! The "pid" command will display 37 or higher in
the last shell if you do this. If you try to run more than 36 shells, it
will tell you that the system is out of memory (don't worry: memory will
be freed as you exit the shells). Type "exit" or Ctrl-D to leave each
shell.

The last added feature of Beta 3 is that it maintains the time across
resets. Previous versions would clear all RAM at boot time, which would
also clear the current time. The time will also be preserved across
Punix updates (as long as the time stays at the same memory address,
which it probably will from now on).

Other changes include a few small performance enhancements. These are
not all visible from userspace, but they should decrease power draw
slightly when playing audio or when the calculator is off, for example.

Feedback
========

Do you have comments or questions? I would love to hear about your
experience with Punix so I can fix whatever is broken or otherwise
improve existing features.

Email: abbrev+punix@gmail.com
Web Site: http://punix-os.blogspot.com/

Thank you!