home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / math / classdoc / howtopgm.txt < prev    next >
Encoding:
Text File  |  1993-07-28  |  5.2 KB  |  159 lines
  1.  
  2. How to write a machine-language program for the HP48sx using CLASS
  3. ------------------------------------------------------------------
  4. (C)1991 Lutz Vieweg
  5.  
  6. The easiest way to write a machine-program for the HP48sx is to create
  7. directly a binary file that can then be transferred to the HP48sx using
  8. a common KERMIT program or similar.
  9.  
  10. There are only two problems:
  11. The HP48sx works nibble-orientated, but serial transmission is based
  12. on bytes. The HP48sx seems to swap the low and the high nibble in
  13. every byte it passes through it's UART. Generally it's not the task
  14. of an assembler to compensate such nasty things, but I did feel a
  15. touch of human sympathy and create an assembler-option to do this (-rn).
  16. The second problem is that you have to know a little about the structure
  17. of a HP48sx binary file. This is what follows...
  18.  
  19. 1.0 The binary-file header
  20. --------------------------
  21.  
  22. The binary-file header consists of the following 8 byte
  23.  
  24.  
  25. "H" "P" "H" "P" "4" "8" "-" Version ( "A" to "E" by now)
  26. $48 $50 $48 $50 $38 $38 $2d $4x 
  27.  
  28. Please set the version-indicator according to the one you use.
  29.  
  30. 1.1 After the header...
  31. -----------------------
  32.  
  33. The nibbles after the header directly represents the memory-image
  34. that can be found later in your handheld - but think of the nibble
  35. swapping for transmission once again.
  36. There's no control information or anything mysterious else. The
  37. HP48sx allocates memory for the file that is transmitted, and creates
  38. a hash-table entry for it that is "connected" to the name of the
  39. variable that was defined in the KERMIT-file-header during transmission.
  40.  
  41. 1.2 Why does the HP48sx not accept any memory-image?
  42. ----------------------------------------------------
  43.  
  44. The HP48sx performs a simple test on any file it receives:
  45. Everything, it does not identify, is assumed to be an "external",
  46. an unknown 5-nibble RPL-adress.
  47. Everything that can be identified by the HP is taken for itself...
  48. but when the file ends, there has to be an identifyable instruction
  49. the last one.
  50.  
  51. If you transmit an invalid binary to your 48sx, you will either get
  52. a string object with the memory image in it (binary-mode) or a
  53. "syntax-error" (ASCII-mode).
  54.  
  55. 1.3 What's the correct format of a HP48sx object?
  56. -------------------------------------------------
  57.  
  58. The first five nibbles of an object are always assumed to be a RPL-code.
  59. You'll have no trouble if you are setting these first five nibbles
  60. to $02d9d (Type_pgm), the last five to $0312b (End) and whithin
  61. only valid RPL-commands, for example $02dcc (Type_code) which allows
  62. you to include any data-nibbles into the object which are assumed to
  63. be an executable machine-program while evaluation of the object.
  64.  
  65. A typical program torso may look like this:
  66.  
  67. main             
  68.                  textr     "HPHP48-E"
  69.                  
  70.                  dcr.5     $02d9d
  71.                  dcr.5     $02dcc
  72. pgmbeg           
  73.                  dcr.5     pgmend-pgmbeg ; lenght of machine-pgm 
  74.                  
  75.                  jsr       $0679b        ; save_regs
  76.                  
  77.                  ; here comes the code
  78.  
  79.                  jsr       $067d2        ; restore_regs
  80.  
  81.                  move.a    (d0),a        ; jump to next RPL-code
  82.                  add.a     #5,d0
  83.                  jmp       (a)
  84.                  
  85. pgmend           
  86.                  
  87.                  dcr.5     $0312b 
  88.  
  89. 1.4 Using absolute adresses...
  90. ------------------------------
  91.  
  92. ... is not that easy on HP48sx. You cannot know where in memory your
  93. program is placed when it is executed. There are three possible solutions
  94. to this problem:
  95.  
  96. 1. Only write relative code. This one is nice when creating up-to-100-byte
  97.    programs. But at larger projects this becomes very nasty.
  98. 2. Kick-ass the OS and do what you want to do. Seems nice when using
  99.    the 48sx as arcade-machine (SHAME-BOY), but isn't that funny when
  100.    you want to do calculations later without having the chance to 
  101.    reload a backup from your stationary computer.
  102. 3. Write relocatable code! You do not know, how?
  103.    Well, this is not a solution that has been offically presented by HP
  104.    to all the guys who want to get into their machine. This is just an
  105.    idea I tried successfully (QED was written that way):
  106.  
  107. The CLASS-assembler supports a pseudo-ob to create a simple relocation-table.
  108. Please read the instructions there for more information.
  109. The needed routines are included in this package. They are both
  110. assembler-sources to be "INCLUDE"d into your program.
  111.  
  112. Here comes a simple-sample program using these includes:
  113.  
  114. main    include    "class.mac"
  115.     textr    "HPHP48-E"
  116.     
  117.     dcr.5    Type_pgm
  118.     
  119.     include    "relocpgm.a"
  120.     
  121.     dcr.5    $02dcc
  122. pgmbeg    
  123.     dcr.5    pgmend-pgmbeg
  124.     
  125.     jsr    save_regs
  126.     
  127.     move.ao    #outvar,d0
  128.     move.ao    #outvar,c
  129.     move.a    c,(d0)
  130.     
  131.     jsr    restore_regs
  132.     move.a    (d0),a
  133.     add.a    #5,d0
  134.     jmp    (a)
  135.     
  136. reloc_tab    reltab
  137.     
  138. pgmend    
  139.     include    "rerelpgm.a"
  140.     
  141. outvar    binint    16,0
  142.     
  143.     dcr.5    $0312b
  144.     
  145.     include    class.sym
  146.  
  147. 1.5 to be continued...
  148. ----------------------
  149.  
  150. I do not get a penny for the assembler at all - so it depends heavily
  151. on my actual motivation whether I improve it or it's manual.
  152. This one may be continued later.
  153.  
  154. Lutz Vieweg
  155.  
  156. UseNet:  lv@muffel.hotb.sub.org
  157. FidoNet: 2:247/30.20
  158.  
  159.