Crawly Crypt Collection 1/crawlyvol1.bin/program/books/68k_book/arp_doc/chap_01.doc

Text File | 1985-11-20 | 39KB | 728 lines

     Atari ST Machine Specific Programming In Assembly

Chapter 1: Scope and Concepts


     Beating the Atari ST Into Submission was my first title
for this book.  In order to conduct research in a field of
interest, I had assembled a computer system that I had
judged to be adequate; I had gathered all of the reference
material that I could find for that system; and I had
purchased software which, had the reference materials been
completely competent, should have permitted me to write the
programs I needed.
     But, when I turned to the references for assistance in
designing my programs, I soon judged them to be inadequate
because of documentary errors and information omissions.
Eventually, I had to acknowledge the necessity of becoming
my own ST authority; I would have to write my own reference
book before I could write my software.  To accumulate the
knowledge required to write that book, I had to perform a
personal study of the ST.
     This is my journal of that study, marked, not by
chronologically connected events, but by algorithmic
complexity, in the form of a series of programs which I
designed to gather experimental data about the hardware and
the operating system of the Atari 1040ST.  Using the
available reference material as a guide, I began to write
programs to test and expand the information contained in the
references.  As results were accumulated from the execution
of those programs, I began to write the book.
     As I plodded along, day by day, I learned enough about
the ST to convince me that I should change the book's title;
because I discovered that the computer is not an unwilling
servant.  In fact, it is the machine's propensity to
obedience that has caused me to become so fond of it.
     Yet, in the literature that I have seen, programmers
complain about system software defects, its limitations, its
inadequate documentation and its sluggishness; users
register identical complaints about application software.
My own experiences validate all of these complaints.
However, in spite of that validation, and in spite of the
construction and placement of its obscenity connectors, for
my needs, the Atari ST is the most capable personal computer
available.
     It's not that the machine can't do, it's the way in
which it has been told to perform that prevents it, without
sufficient augmentation, from meeting my expectations.  I am
now convinced that all software produced for the ST can be,
and should be, as efficient, or better, than that of the
finest available for any other personal computer.  As
examples of the exceptionally fine software that can be
written for the ST, I need only point to the programs
TEMPUS, an editor; TURBO ST, an accelerator; Universal Item
Selector II, a replacement for the GEM item selector; and
MultiDesk, a desk accessory expander.  These excellent
programs are models of efficiency and utility because their
authors viewed and contemplated the ST as a unique
instrument, writing algorithms that are machine and
operating system specific to varying, appropriate degrees.
     Most of the software that I have purchased for the ST
fails to satisfy my expectations because it does not perform
at my standards of speed and reliability levels, while
consuming minimum requisite memory.  These are the
attributes that I demand of the software I write.  Should I
expect less from the software I buy?  Some of the software
that I have purchased has failed to meet my expectations
because it has been reworked versions of programs initially
prepared for other machines; some has failed because it is
meant to be compatible with later versions of the ST or of
its operating system; a lot of it has failed because it is
just plain rotten.
     I want programs that work correctly and efficiently on
the machine which I own.  I do not want bastardized versions
of programs that are hampered by the structure of the
machines for which the original versions of the software was
written.  Furthermore, I don't want to finance, by way of
time, money and space, the compatibility of currently
produced software with future Atari machines and/or
operating systems, which may or may not materialize.
     In fact, I think that the software compatibility
between machines and operating systems issue is dead.
However viable it may have once seemed, I know only of the
hard work this concept has generated for programmers and the
inefficient programs that have been produced, in spite of
that hard work.  I am convinced that the proliferation of
computers and their operating systems has surpassed the
ability of programmers to maintain total compatibility.
Anything less than total compatibility is incompatibility,
by definition.
     Personally, I don't care if my software is compatible
with any machine other than my own.  Furthermore, I don't
think it impertinent of me to suggest that consumers should
have learned by now that product satisfaction is relevant at
the time of purchase.  This applies to hardware or attendant
software.  My experience has proven to me that, for any
product purchased, there is no reason to expect that any
product enhancement will take place in the future, nor is
there any reason to expect that any enhancement which does
take place in one area will not be accompanied by
performance degradation in other areas.
     Therefore, I have decided that, when using any
programming language, I want to be able to produce programs
that are as machine specific as possible because I want to
utilize programs that are as efficient in speed and size as
possible, whenever the task to be done warrants the
consideration.  I made a choice when I purchased my
computer; I made that choice based on the machine's hardware
and software as it existed at the time of purchase.  I chose
the Atari ST because I judged it to be the best, after
comparing it to all other personal computers available.
     Choosing the ST is what we have in common, you and I;
and I can assume that you also have decided to explore the
issue of writing software, otherwise you would not be
indulging me this far.  I cannot assume anything about your
experience and notions concerning the subject, but, if you
are able to read this book, I can assure you that you can
write software for the ST.  Your ability is not the
question; you need only decide to invest the time required
to become acquainted with the tools of the trade.  But,
knowing how to use the tools will not make you want to be a
programmer; the decision concerning that desire is a
separate, personal issue.

Decisions

     When I was younger, I had decided that I wanted to be a
doctor.  After studying premed for three years, I realized
that I really did not relish the thought of the intimate
involvement with people, on a daily basis, which the
profession demanded.  I decided that I would rather work
with machines and instruments instead.  Therefore, I became
an engineer.
     Your decision to be, or not to be, a programmer is
probably not as critical as the choice I had to make because
it need not involve daily employment.  You might view your
capacity to write computer programs as an enhancement to
your professional or personal life.  But, whether you decide
to program part time or full time, you should realize that
programming is work.  That's why we must pay for programs
written by others.
     I find the work involved in computer programming to be
emotionally stimulating.  Perhaps it is the challenge of
achieving algorithmic perfection which excites me.  In
reaching for such perfection, I spend a significant amount
of time exploring the capacity of my computer.  I have
learned to regard these explorations as pleasant interludes
between frenzied programming sessions.
     If you can adopt this attitude concerning your own
programming efforts, then the significance of the material
that I present in this book will be enhanced, because, here,
we enter regions of algorithmic activity that is only
scantily documented in the references.  Compounding the
inconvenience of sparse documentation are errors therein.
Nevertheless, I will certainly recommend references, but I
warn you that the bulk of it contains unconfirmed
assertions.  Of course, I will not be able to use such
material to support my own assertions.  Instead, in
conjunction with that which is available, I will have to
rely on the experimental results which have been produced by
the programs that I have used to explore the ST's
capabilities.
     I encourage you to share the task of verifying the
accuracy and reliability of the evidence which I generate.
I will provide algorithms and explanations which seem
reasonable, based on what I assume to be prevalently
understood about the system's hardware and software; then I
will attempt to verify or disprove my suppositions, which
may, or which may not, be congruous with what is in print.
To you, I leave the responsibility of questioning my
activity to the extent that you will be cautious in the
application of my algorithms.
     I expect my computer to do things blazingly fast.  When
my computer is executing a program, I want to see fire and
smoke.  I want my computer to kick ass.  When executing a
properly written, machine specific assembly language
program, the Atari ST does just that.  Furthermore, I
believe that this type of software can be produced by any ST
owner.
     I feel that it is time for every owner to seriously
consider the benefits of tailor made programs.  Doing it
yourself is one way to guarantee that the software you use
performs accurately and reliably, at maximum possible speed,
while consuming only the requisite amount of memory.
     I think that the most compelling issue, when deciding
whether to buy or write programs, is the degree to which the
computer user expects satisfactory performance from the
machine.  I do not even include the ability to program a
computer in the arbitrary list of factors which must be
considered.  Among those factors, however, I do wish to
include the disadvantage of indiscriminately relinquishing
control of machine performance to the producers of
commercial software.
     Anyone that uses computer programs finds themselves in
the position of telling the computer to do things.  That's
all computer programming is; telling the computer to do
something.  The choice of levels at which the computer is
told to accomplish its tasks can be decided, as is proper,
by the ST user.  This choice is not always available to
users of other computers.
     In addition to its compatibility with higher level
languages, the MC68000 microprocessor, by which the machine
is driven, facilitates the production of an assembly
language programming environment that is not much more
intricate than that of the higher level languages.  Also,
even though the ST's operating system is not as efficient as
it could (and should) be, its structure permits access that
enables a programmer to bypass it altogether or to augment
its more mundane routines.
     It is true that, in the past, programming was a much
more difficult chore than it is today.  But the languages
and translators available now permit everyone to become
intimately involved with the generation of programs that
operate at maximum efficiency because they apply to specific
problems that are to be solved on specific machines.  After
all, we purchase personal computers because it permits us to
wield their power personally, so why should we not generate
personal programs that permit the maximum utility of that
power.
     The amount of utility that one can realize from a
computer system is proportional to the amount of effort that
one is willing to invest in becoming intimate with its
hardware, its operating system and a means of communicating
with both.  The more knowledge a user is willing to
accumulate about these three subjects, the more productive
will be the intimate involvement.
     That's what this book is about; obtaining and using
knowledge about the Atari ST; and using that knowledge to
write programs for it.  Programs that exploit the ST's
machine specific hardware, language and operating system.
To take advantage of the ST's powerful hardware and
software, you need not write long and intricate programs.
It is possible to wield a great deal of power simply by
writing smaller utilities and by being able to alter or
control purchased programs which do not meet your
performance expectations.

The Scope of the Book

     Book titles aside, I intend to place various types of
whips at your disposal; do with them what you will.   I will
not begin at the beginning.  Too many other authors have
already done that.  Instead, I shall begin in the middle,
point out the sources that have provided a beginning, and
try to show you a path to the end.  However, I will discuss,
in depth, those aspects of programming the MC68000 and the
ST which I feel have not been adequately presented
elsewhere.
     Although I will discuss some of the basics of
programming, and although the programming medium I shall be
using in the book is assembly language, I will not be trying
to teach you the basics of assembly language programming, so
I'll describe sources for suitable material.  Concerning
programming in assembly language on the ST specifically, I
can say without hesitation that there are not enough books
available,  but there is sufficient elementary material
available concerning the individual subjects: programming in
assembly language and programming on the ST.
     I am fond of assembly language programming because it
keeps one in touch with the capabilities of the processor.
Machine specific programming keeps one in touch with the
capabilities of the other hardware also.  Of course,
familiarity with the processor's language can be avoided,
even while one is "programming in assembly".  The advantages
of assembly language programming is circumvented by
programmers who rely solely on large libraries of routines
which are simply plugged into new programs.  Nevertheless,
the assembler that I will recommend does provide such
libraries.
     I am against this practice because canned subroutines
keep you too far away from the intricacies of the processor
instructions.  It hinders the generation of new ideas about
algorithms.  Furthermore, it does not promote the
memorization of individual commands and patterns of command
groups.  I do advocate, however, the development of proven
routines that can be copied from one program to another.  It
is the concatenating of unreviewed blocks of source or
assembled code to new programs to which I object.
     In general, the reference books for the MC68000 and the
Atari ST are very useful.  There are problems with some, but
none are totally devoid of redeeming qualities.  Some
portions of these books contain critical errors; other
portions completely neglect discussions of pertinent
functions; in my opinion, none of the books present example
programs in a progressively coherent fashion.
     My desire, therefore, is to present material which does
not duplicate that which is already available and to offer
precise examples, beginning with the rudimentary,
progressing to the intricate, that are constructed in a
series of cohesive steps.  At each phase, algorithms will be
used that I have personally developed and tested.  These
algorithms will have been developed while using the
reference books to be mentioned.  You will be able to verify
my results, and you will be able to supplement information
in your references with my annotations.
     I cannot write a book that incorporates details for
manipulating the entire ST operating system and all of the
computer's hardware.  I have restricted my interest to
selected portions of the Centronics interface, the DMA
interface, the video interface, the interrupt structure and
the operating system.  I will get as close to the hardware
as seems reasonable.  In some cases, this means I shall be
programming the hardware directly; in others, it means that
I shall get closer to it than is usual when using the
operating system, but not close enough to dissolve the
advantages of having the operating system in the first
place.
     I will discuss desk accesssories, terminate and stay
resident programs (I prefer the term load and stay
resident.), custom trap installation, the power of self-
modifying code, switching between screens, the file
selector, the initialization of applications, resource files
and subjects related to these areas of interest.  In
addition, I will discuss the use of the AssemPro assembly
language programming system and TEMPUS, a programmer's
editor, filling in some details not provided in their
documentation.  I will also clarify the differences between
programs that are assembled in each of AssemPro's three
assembly modes: PC-relative, Relocatable and Absolute.
     Because the programs which I use require the higher
resolution of a monochrome monitor, I do not use a color
monitor.  Therefore, my examples do not include color
monitor specific code.  However, most of what I discuss is
monitor independent.  Besides, I think you will find that
the references provide adequate color monitor information.

The Attributes of Acceptable Software

     The programming concepts associated with computers have
always been dictated by machine hardware.  Over time, the
concepts of at least some critical portion of programmer
population have always kept pace with hardware development;
but not everyone has been amenable to the required shifts in
philosophy.  At times, some programmers have run amuck.
     Four software attributes have always been desirable:
accuracy, reliability, speed and minimum memory requirement.
At times, the attributes speed and minimum memory
requirement have vied to be the more prominent
consideration.  Then, the fast processor, large memory
computer came along.  Suddenly, programmers were talking
about structured programming and across the board
compatibility.  Many programmers declared that speed and
memory requirements were passé considerations.  Some of them
even threw out the accuracy and reliability attributes for
good measure.
     Then, Kernighan and Ritchie wrote the bible.  In the
beginning there were complaints to be heard from the masses.
Eventually, many programmers began to learn how to use the
language that was faster than fast and somewhat relaxed in
its requirements for structure.  But one group of
programmers insisted that, although C was faster than other
high level languages, it was still not faster than fast;
only assembly language could achieve such distinction.
Furthermore, they declared that C had a voracious appetite,
gobbling up memory like a pac-man.
     But it was much easier to program in C than it was to
program in assembly, so many were converted.  The MC68000
driven Atari ST coupled with the AssemPro assembly language
programming environment has nullified that advantage.  Using
AssemPro, programming in assembly on the Atari ST is as
convenient as programming in C.  And now that the editor
TEMPUS is available, the task is even easier than it had
been.

The Concepts Which Shape the Book

     What programming concepts must be accepted in order
that maximum utility be achieved with the Atari ST?  Machine
specific programming in assembly is the first.  The reason I
insist that this concept be acceptable is that it permits
both the speed and minimum memory requirement attributes to
be incorporated into program design simultaneously.  There
are other advantages to assembly language programming; I
believe that they will become apparent as we go along.
     Compatibility and portability as desirable program
attributes must be dismissed.  Programs that are designed
with emphasis on these criteria are inherently inefficient;
there are too many machines and too many differences between
them.  User satisfaction should supplant those criteria.
Embodied in the concept of user satisfaction are the
accuracy and reliability attributes.
     I know that some people think that a megabyte of memory
is takusan.  Just remember that there was a time when they
thought that 64 kilobytes was a lot.  About memory, I say
that you can't have too much.  The basic law of applications
is that they will expand to fill all corners of available
memory, whether they are heated or not.  About speed, I say
this: if you're not in a hurry, do it by hand and give your
computer a rest.  If you are going to use a computer then
you should always be concerned about accuracy, reliability,
speed and memory requirements.
     Don't be fooled by those who offer you inferior
programs, declaring that one or more of these software
attributes are no longer relevant.  As a user, it is your
right to demand that all software you purchase meets these
criteria.  Actually, I believe that Atari ST users have
already begun to rebel.  Of course, some software producers
find it hard to believe that we are intelligent enough to
decide what it is that we want; they prefer to believe that
users are giving copies to each other.  Hah!  Most of the
software that I have purchased has gone straight to the
trash can because I could not use it myself.
     In presenting my material, I shall use a concept that I
call the minimum code necessary; this means that I will
introduce routines, my own and those of the operating
system, with the minimum amount of code necessary to
illustrate the use of each routine.  Therefore, you will be
able to see what is actually required by an algorithm versus
that which some of the reference books indicate.  I shall
compare certain algorithms that have become "standard" in ST
literature to ones that accomplish identical goals easier,
faster, and with less memory requirements.

Reference Material

     I will now list the reference materials which I
consider to be the best available.  At least some of these
books are indispensable.  I suggest that you look at all of
them and purchase those you find affordable; all are
desirable.  I will indicate those which I feel that I can
recommend without reservation, but which you might not be
able to locate; you may decide to order them through a local
bookstore.

     1. Ford, W. and Topp, W., The MC68000 Assembly
        Language and Systems Programming, D.C. Heath
        and Company, 1988.  This book contains material for
        both beginning and advanced college semesters.  It
        is the most comprehensive MC68000 book available.

     2. Erskine, R., First Steps in Assembly Language for
        the 68000, Bantam Books, Inc., December 1986.  An
        excellent beginner's book.

     3. Skinner, T.P., Assembly Language Programming for the
        68000 Family, John Wiley & Sons, Inc., 1988.

     4. Kelly-Bootle, S., 680x0 Programming by Example,
        Howard W. Sams & Company, 1988.  This book offers
        more detail, especially about the addressing modes,
        than a mere beginner's book.  I strongly recommend
        this book.  The author rates his book as elementary
        to intermediate.  I rate it as elementary+ to
        intermediate+.  I purchased this book while I was
        writing the fifth chapter of mine; I'm sorry that
        his was not available sooner.  It is good reading.

     5. Peel, K.D., Concise Atari 68000 Programmer's
        Reference Guide, Glentop Publishers Ltd, 1986.  An
        excellent book.  It discusses the entire Atari ST
        operating system.  It is, however, somewhat cryptic
        for beginners.  The address of the publisher
        is: Glentop Publishers Ltd, Standfast House, Bath
        Place, High Street Barnet, Herts EN5 5XE. Tel: 01-
        441-4130

     6. Gerits, K., Englisch, L. and Bruckmann, R.,
        Atari ST Internals, A Data Becker Book,
        published by Abacus Software.  You must have
        this book; the 3rd revision, or later if
        possible.

     7. Leemon, S., Atari ST Volume One: VDI, Compute!
        Publications, Inc., 1987.  This book relies mostly
        on the C language, however, it does contain
        pertinent pertinent reference material.

     8. Leemon, S., Atari ST Volume Two: AES, Compute!
        Publications, Inc., 1987.  There is more assembly
        language in this book than there is in the VDI book.
        If I could afford to purchase only one of the Leemon
        books, I would choose this one.

     9. Szczepanowski, N. and Gunther, B., Atari ST GEM, A
        Data Becker Book, published by Abacus Software.,
        1985.

     NOTE: You should have either item 9 or items 7 and 8.
           Personally, I have found the COMPUTE! books and
           the Abacus book to be valuable.

    10. Pollack, L. and Weber, E., Atari ST Application
        Programming, Datatech Publications, 1987.  No
        assembly language here, only C.  But this book is my
        favorite source for information about GEM when I
        program in C, so I had to mention it.

    11. Motorola, M68000 Programmer's Reference Manual, 5th
        edition or later, Prentice-Hall.

Software Needed

     You must have an assembler, an editor and a debugger.
Most assembly language packages contain all three software
tools.  AssemPro is such a package and is, beyond question,
the most convenient, feature ridden assembly language
package that is available for the Atari ST.  The assembler
may not produce code as fast as some, and the response of
the editor is not as quick as I would like, but the debugger
is superb.  I suggest that you use TEMPUS as your primary
editor, resorting to the AssemPro editor for minor
corrections while attempting to assemble.
     The possession of these two tools, AssemPro and TEMPUS,
will put you in the most advantageous position possible for
writing assembly language programs, or for altering existing
programs to suit your preferences.  If you already have an
assembler, you might try to get along with it.  Or a newer
assembler might become available before this book does.  In
that case you may decide to try the newer one.  In any case,
good assemblers are not expensive.  Neither is TEMPUS
expensive.

Telling The Computer To Do Things

     Because the phrase "telling the computer to do things"
is awkward to use, and because it takes up so much room on a
page, I suppose that the conversion to the word
"programming" was inevitable.  But it is worth remembering,
from time to time, that the word programming means just
that.  If one uses a computer at all, one is involved in
programming.  Am I trying to make it all seem much easier
than it is?  Nope.  I'm just trying to get you to look at
the subject from a different perspective than that to which
you might be accustomed.
     Various definitions are applied to the manner in which
we tell a computer to do things.  Input, statements,
algorithms, subprograms, subroutines, macros, code,
programs; it all means the same thing.  We can tell it to do
one thing and stop; we can tell it to do many things, one at
a time, as we intervene at each step; or we can prepare a
list of things for the computer to do, call that list a
program, and submit it as a bulk transaction to the computer
for execution.
     In general, a program is composed of a sequential list
of statements, one or more of which may be perceived as
comprising a single task that we can arbitrarily label a
distinct algorithm.  If the statements which form such an
algorithm are grouped together in a module, separated from
the sequential list, and if that module is called upon to
perform its task by one of the sequential statements, then
we can arbitrarily label the algorithm a function,
subroutine or subprogram.  Since we can apply the word
algorithm to the steps required to accomplish any task,
regardless of the length of the algorithm, much of the above
jargon is superfluous.
     We write a program, or algorithm, for our computer when
we want it to do something that it can do better than we, or
when we feel that what we want to accomplish is too tedious
and/or repetitious to warrant human intervention.
Programming is a difficult chore only to the extent that we
find it difficult to express the things that we want
accomplished, whether to another person or to a computer.
The ability to express oneself is developed with education
and experience, over a period of time.  There are short
cuts; primarily the short cuts are taken by using reference
material.  However, be aware that faulty reference material
can hinder your effort; therefore, be suspicious.  Take
nothing for granted; least of all; another person's
certainty.
     I think that writers have finally realized that the
phrases must do and can't do just do not apply to the Atari
ST.  It seems that every other week or so someone is doing
something that had been a can't do, according to all
available reference material.  I shall certainly try to
avoid the terms myself; but if I do happen to use them
inadvertently, please remember what I have said in this
paragraph.
     The key to success with reference material is to have
as many sources as possible, trust none of them, and verify
every item of information that involves your current task.
If a reference book indicates that you must include a
certain block of code in a program, verify the information
by leaving out the entire block, then, by leaving out
portions of it that seem redundant.  Much of what I say in
this book is designed to assist you in learning how to spot
and eliminate redundant and/or inefficient code.

The Programs in the Book

     I want the programs and algorithms that I present to
flow into my discussions naturally, to fill inquisitive gaps
opened by previous presentations, so that your learning will
not be as haphazard as was mine.  The plan that I developed
is as follows.  I shall begin with the simplest of programs.
That program initiates a debate concerning the various
methods of implementing a simple task.  Conclusions drawn
from the debate require verification.  Verification requires
the use of slightly more complex algorithms.  These
algorithms have universal application, but they also incite
debate, conclusions and verification.
     In order to keep track of a sequence of related
algorithms as they appear, I have chosen to use a program
naming procedure as follows.  The programs that supplement a
current discussion form a set for which the name of each
program in the set shall have the format PRG_nxy, where n is
an integer that follows sequentially from the previous
program set; x is a letter of the alphabet, beginning with A
for the first program in a set, proceeding to B for the
second and so on; y is one of the letters A, P, R or C.
These letters indicate the assembly mode for which a source
file has been prepared and the assembly mode used to
generate the object file.
     The letter A is used to designate a source code file
that has been prepared specifically for assembly in
AssemPro's Absolute mode and to indicate that an object code
file has been assembled in that mode.  The letter P is used
for source code that is prepared specifically for assembly
in AssemPro's PC-relative mode and for the resultant object
code file.  The letter R is used for source code that is
prepared specifically for assembly in AssemPro's Relocatable
mode and for the resultant object code file.  The letter C
is used for source code that is prepared specifically for
assembly in the Combination mode and for the resultant
object code file.  I apply the term combination mode to
programs which use pc-relative addressing, but which are
assembled in the Relocatable mode.
     The source code of all programs in the set shall have
the usual .S assembly language extension.  The assembled
programs shall have the appropriate .PRG, .TOS, .TTP, or
.ACC extension.  For some examples, object code with more
than one extension will be required.  Unrelated programs are
named according to their utility.  For example, a program
named SPEEDTST measures loading and execution times; a
program named LEA_ADDA compares the efficiency of the LEA
instruction to that of the ADDA instruction in a particular
application.

Program Documentation

     I am currently reading a brand new MC68000 assembly
language programming book.  The author of this book
discusses subjects for which I have had a deepening
interest.  I was shocked, however, to read his statements
concerning program documentation.  In essence, his
statements imply a belief that program documentation should
be held to the very minimum necessary.  He speaks of
documentation as if it contaminates the programs in which it
appears.  This type of thinking is definitely not current.
     Storage mediums are inexpensive; time is not.  Trying
to understand sparsely documented code that you have already
written is probably much harder than writing new code.  It's
one of those Murphy's laws with which programmers become all
too familiar.  So take advantage of storage medium space to
save time.  Of course, when you are providing example code
for the perusal of others, all choice is preempted.  For
your own use, I suggest that you have at least two or three
fully documented copies of your algorithms in a safe place.
Then you can use them in programs undocumented, whenever you
choose to do so.

The Science of Programming

     As you probably know, there are those who prefer to
view the programming discipline as an esoteric art.  I
suppose that, to those with that perception, documentation
is as artistic as is programming.  However, I do not place
as much emphasis on the artistic nature of programming as do
others.  Programming is as much a discipline as is
engineering.  I know this to be true because I am both an
engineer (BSEE) and a programmer.
     The list of instructions which comprise a computer
program must be precise.  The ability to issue instructions
precisely depends on knowledge, discipline and dedication to
the scientific method of investigation; it does not depend
on artistic talent.  Using the scientific method to prepare
a computer program that will produce accurate, verifiable
results, one proceeds, with specifications, from a situation
that is characterized by a desire to accomplish a task, to a
situation in which a tool that can be used to accomplish the
task has been assembled.
     Unlike some, I believe that even an algorithm that
provides a correct solution can be unsatisfactory because it
is not the most time and memory efficient algorithm that can
be produced on the machine for which it is written.  I
believe that there is a set of most satisfactory algorithms
which can be written for every machine.  Any algorithm that
is not a constituent of that set is undesirable.
     Yet there is a time and a place for undesirable
algorithms.  They are what you use while you are learning to
develop the set of most desirable algorithms.  Writing the
best possible algorithms for a machine can only be done by
programmers who are committed to a methodically study of the
machine's hardware and software, to scientific methods of
experimentation and to meticulous verification.  In
addition, it involves the most horrific task that can be
contemplated by the owner of expensive machinery; it
requires that one be very familiar the machine's
instructions and with references that support those
instructions.
     I cannot promise to deliver a set of most satisfactory
algorithms for your particular needs, but I can show you how
I go about producing my own set.  I will show you the
deliberate care with which I choose each instruction of each
algorithm.  In developing the algorithms, whenever a choice
can be made from two or more instructions, and when I
conclude that the choice is not trivial, I will show you how
I evaluated the benefits of each, and I will tell you why I
chose that which I felt to be the most correct for the
application involved.  Likewise, when a choice is made from
two or more algorithms or programs, I will provide similar
information.
     I promise to deliver reproducible results and
verifications.  But you must remember that the results were
obtained within my programming environment.  Furthermore,
when I direct your attention to flaws in the ST programming
environment, which includes the hardware, operating system
and purchased programs, remember that these flaws were
evident in my programming environment.  What you see in your
environment may not be identical to what I see in mine.
Therefore, you should use my results and observations as
indicators of what you might experience; but you should not
accept them as conclusive evidence of anything.

Conclusion

     In this chapter, I have tried to convince you that
writing machine specific programs is a viable alternative to
purchasing unsatisfactory software.  Further, I have
emphasized assembly language as the most efficient medium by
which this alternative can be exercised.  I believe that I
can show you how to dissolve the complexity of assembly
language programming by dividing each programming task into
manageable levels, wherein isolated subtasks are reduced to
trivia.  In the chapters ahead, I present my proof that you
can do the job.