Merge pull request #10 from fourstix/b_name_update

Change name of MemoryHog to malloc, add mfree and xtrim utilities

README.md

@@ -8,45 +8,57 @@ These commands were written to run on a [Pico/Elf](http://www.elf-emulation.com/
 
 Miscellaneous Elf/OS Utility Commands
 -------------------------------------
+
+## cmd
+**Usage:** cmd [-e] [*filename*, default = start.cmd]    
+Run commands from the file *filename*, or the file start.cmd if not specified. Each
+line of the file contains a separate command. The option -e will echo the commands before they are executed.
+
+**Note:** 
+To use *cmd* as the ELf/OS init program, copy this file as an executable file named *init* in the /bin directory. The Elf/OS will then execute the commands contained in the start.cmd file in the root / directory when the Elf/OS boots. *Press and hold Input /EF4 to skip the execution of start.cmd and auto-baud during boot-up.* 
+
+**Note:**
+The cmd program occupies memory from $5000 to $6000.  Programs up to 12K in size that load at $2000 can be run from a command file.  If a program allocates memory so that the heap goes below $6000, the command interpreter will exit with an 'Out of Memory' error. 
+
+## cls
+**Usage:** cls    
+Clear the screen. *Clears both ANSI and non-ANSI displays.*
+
 ## input
 **Usage:** input  
 Input and display data read from Port 4
 
+## malloc
+**Usage:** malloc [-f *hh*] *size*    
+Allocate a block of memory of *size* bytes on the heap. The -f option will fill the memory with the *hh* hex byte value. *Useful for testing low memory conditions.*
+
+## mfree
+**Usage:** mfree *hhhh*    
+Free a block of memory allocated at the hex address *hhhh* on the heap.
+
 ## output
 **Usage:** output *hh*     
 Send the hex value *hh* out to Port 4 *(where hh ranges in value from 00 to FF)*
 
 ## nop
 **Usage:** nop    
-No Operation, a simple program that does nothing.
+No Operation, a simple program that does nothing. *Can be renamed to 'rem' and used for comments in command files*
 
 ## pwd
 **Usage:** pwd    
 Print Working Directory, write the current directory to the output.
 
 ## say
 **Usage:** say *text*      
-Print the string *text* to the output.
+Print the string *text* to the output. *Useful for printing text output in command files*
 
 ## stack
 **Usage:** stack    
 Print the value of the Elf/OS stack pointer.
 
-## cmd
-**Usage:** cmd [-e] [*filename*, default = start.cmd]    
-Run commands from the file *filename*, or the file start.cmd if not specified. Each
-line of the file contains a separate command. The option -e will echo the commands before they are executed.
-
-**Note:** 
-To use *cmd* as the ELf/OS init program, copy this file as an executable file named *init* in the /bin directory. The Elf/OS will then execute the commands contained in the start.cmd file in the root / directory when the Elf/OS boots. *Press and hold Input /EF4 to skip the execution of start.cmd and auto-baud during boot-up.* 
-
-## cls
-**Usage:** cls    
-Clear the screen. *Clears both ANSI and non-ANSI displays.*
-
-## MemoryHog
-**Usage:** MemoryHog *size*    
-Allocate a block of memory of *size* bytes on the heap. *Used for testing low memory conditions.*
+## xtrim
+**Usage:** xtrim *filename*, where *filename* is an executable file.  
+Trim the executable file *filename* to the runtime size in its header, and save with the .tr extension.  *Useful to remove padding bytes added by an XMODEM transfer* 
 
 STG NVR/RTC/UART and STG EPROM Utility Commands  
 -----------------------------------------------
@@ -94,23 +106,25 @@ is useful when debugging or writing pixie video programs to turn off a 1861 vide
 Library Files
 -------------
 The command files are grouped into three Elf/OS library files that can be unpacked with the Elf/OS lbr command using the e option to *extract* files.
-* misc_utils.lbr - Library file for miscellaneous Elf/OS utilities contains the cmd, cls, input, output, nop, pwd, say, stack and MemoryHog commands. Extract these files with the Elf/OS command *lbr e misc_utils*
+* misc_utils.lbr - Library file for miscellaneous Elf/OS utilities contains the cmd, cls, input, malloc, mfree, output, nop, pwd, say, stack and xtrim commands. Extract these files with the Elf/OS command *lbr e misc_utils*
 * stg_utils.lbr - Library file  for STG NVR/RTC/UART and STG EPROM utilities contains the stg, videostg,  xsb, seq and req commands. Extract these files with the Elf/OS command *lbr e stg_utils*
 * video_utils.lbr - Library file for ELf/OS 1861 Pixie Video utilities contains the spaceship, dma_test, tvclock and voff commands. Extract these files with the Elf/OS command *lbr e video_utils*
 
 
 Repository Contents
 -------------------
 * **/src/**  -- Source files for miscellaneous Elf/OS utilities.
+  * cmd.asm - Run commands from a file.
+  * cls.asm - Clear the screen
   * input.asm - Input and display data read from Port 4
+  * malloc.asm - Allocate block of memory on the heap.
+  * mfree.asm - Free a block of memory on the heap.
   * output.asm - Output hh - send the hex value 'hh' out to Port 4
   * nop.asm - No Operation - simple program that does nothing.
   * pwd.asm - Print Working Directory - prints the current directory
   * say.asm - Say 'text' - write the text string back to the output
   * stack.asm - Print the value of the Elf/OS stack pointer
-  * cmd.asm - Run commands from a file.
-  * cls.asm - Clear the screen
-  * MemoryHog.asm - Allocate block of memory from heap for testing.
+  * xtrim.asm - Trim an executable file to its runtime size.
   * asm.bat - Windows batch file to assemble source file with Asm/02 to create binary file. Use the command *asm xxx.asm* to assemble the xxx.asm file.
   * bios.inc - Bios definitions from Elf/OS
   * kernel.inc - Kernel definitions from Elf/OS

src/malloc.asm

@@ -0,0 +1,150 @@
+; *******************************************************************************************
+; malloc - Allocate a block of memory on the heap for testing low memory conditions.
+; Copyright (c) 2021 by Gaston Williams
+; *******************************************************************************************
+
+include bios.inc
+include kernel.inc
+                                                 
+; ************************************************************
+; This block generates the Execution header
+; It occurs 6 bytes before the program start.
+; ************************************************************
+              ORG     02000h-6  ; Header starts at 01ffah
+          dw  02000h            ; Program load address
+          dw  endrom-2000h      ; Program size
+          dw  02000h            ; Program execution address
+
+              ORG     02000h    ; code starts here
+          br  start             ; Jump past build info to code
+
+; Build information
+binfo:    db  80H+8             ; Month, 80H offset means extended info
+          db  21                ; Day
+          dw  2021              ; Year
+
+          ; Current build number
+build:    dw  4
+
+          ; Must end with 0 (null)
+          db  'Copyright 2021 Gaston Williams',0
+
+; =========================================================================================
+; Main
+; =========================================================================================
+
+start:    lda     ra          ; move past any spaces
+          smi     ' '
+          lbz     start
+          dec     ra          ; move back to non-space character
+          ldn     ra          ; check for nonzero byte
+          lbnz    good        ; jump if non-zero
+          lbr     usage       ; no size or opt, show usage message                    
+       
+good:     smi     '-'         ; was it a dash to indicate option?
+          lbnz    getsize     ; if not a dash, get size
+
+          inc     ra          ; move to next character
+          lda     ra          ; check for fill option 
+          smi     'f'
+          lbnz    usage       ; bad option, show usage message
+       
+sp_1:     lda     ra          ; move past any spaces
+          smi     ' '
+          lbz     sp_1        
+            
+          dec     ra          ; back up to non-space character
+          ldn     ra          ; check for nonzero byte
+          lbz     usage       ; show message if end of string
+          
+          mov     rf, fill    ; set flag to fill memory block
+          ldi     0FFh        
+          str     rf          
+
+          ghi     ra          ; point rf to hex value in argument string
+          phi     rf
+          glo     ra
+          plo     rf
+        
+          sep     scall       ; convert input to hex value
+          dw      f_hexin
+          
+          ghi     rf          ; point ra to end of hex value in argument string
+          phi     ra
+          glo     rf
+          plo     ra        
+
+          mov     rf, padding ; point rf to the padding value
+          glo     rd          ; get the hexadecimal byte value
+          str     rf          ; put in the padding value
+                    
+sp_2:     lda     ra          ; move past any spaces
+          smi     ' '
+          lbz     sp_2
+          
+          dec     ra          ; back up to non-space character
+          ldn     ra          ; check for zero
+          lbz     usage       ; missing size, show usage message
+
+getsize:  ghi     ra          ; copy argument address to rf
+          phi     rf
+          glo     ra
+          plo     rf
+          sep     scall       ; convert input to integer value
+          dw      f_atoi
+
+          ghi     rd          ; RD contains the block size in bytes
+          phi     rc          ; Move size into RC for allocate
+          glo     rd
+          plo     rc          ; load block size
+           
+          ldi     00H         ; no alignment 
+
+          phi     r7
+          ldi     04H         ; permanent allocation
+          plo     r7
+
+          sep     scall       ; allocate a block of memory
+          dw      o_alloc
+          lbdf    bad_blk     ; DF = 1 means allocation failed
+
+          
+          ghi     rf          ; point rd to block, rc contains size
+          phi     rd
+          glo     rf
+          plo     rd
+          
+          mov     rf, fill    ; check fill byte
+          lda     rf          ; get fill flag, advance pointer to padding byte
+          lbz     goodbye     ; if no fill, then we are done 
+          
+fillmem:  ldn     rf          ; get the padding byte 
+          str     rd          ; put into memory block 
+          inc     rd          ; advance to next byte 
+          dec     rc          ; bump counter 
+          ghi     rc          ; check high byte of counter 
+          lbnz    fillmem     ; repeat if not zero
+          glo     rc          ; check low byte
+          lbnz    fillmem     ; repeat until count is zero
+          lbr     goodbye     ; Once block is filled, we are done 
+          
+bad_blk:  sep     scall       ; display test message
+          dw      o_inmsg
+          db      'Allocation failed.',13,10,0
+          lbr     goodbye
+
+usage:    sep     scall       ; display usage information
+          dw      o_inmsg
+          db      'Usage: malloc [-f hh] <size>, allocate a memory block of <size> oon the heap.',13,10,0
+          sep     scall
+          dw      o_inmsg
+          db      'Option: -f hh, fill memory block with byte hh',13,10,0
+          ; falls through to exit 
+          
+goodbye:  lbr     o_wrmboot   ; return to Elf/OS       
+;----------------------------------------------------------------------------------------
+fill:     db 0
+padding:  db 0                    
+
+; define end of execution block
+endrom:   EQU     $

src/MemoryHog.asm → src/mfree.asm

@@ -1,5 +1,5 @@
 ; *******************************************************************************************
-; MemoryHog - Allocate a block of memory on the heap for testing low memory conditions.
+; mfree - De-allocate a block of memory from the heap.
 ; Copyright (c) 2021 by Gaston Williams
 ; *******************************************************************************************
 
@@ -41,34 +41,25 @@ start: lda     ra          ; move past any spaces
        lbnz    good        ; jump if non-zero
        sep     scall       ; otherwise display usage
        dw      o_inmsg
-       db      'Usage: MemoryHog size, allocate memory block of <size> in the heap.',13,10,0
-       lbr     o_wrmboot   ; return to Elf/OS     
+       db      'Usage: mfree hhhh, deallocate memory block at hex address <hhhh> from the heap.',13,10,0
+       lbr     bye         ; return to Elf/OS     
 
 good:  ghi     ra          ; copy argument address to rf
        phi     rf
        glo     ra
        plo     rf
-       sep     scall       ; convert input to integer value
-       dw      f_atoi
+       sep     scall       ; convert input to hexadecimal value
+       dw      f_hexin
 
-       ghi     rd          ; RD contains the block size in bytes
-       phi     rc          ; Move size into RC for allocate
+       ghi     rd          ; RD contains the block address
+       phi     rf          ; Move address into RF to de-allocate
        glo     rd
-       plo     rc          ; load block size
-           
-       ldi     00H         ; no alignment 
-
-       phi     r7
-       ldi     04H         ; permanent allocation
-       plo     r7
-       sep     scall       ; allocate a block of memory
-       dw      o_alloc
-       bnf     okay        ; DF = 1 means allocation failed
+       plo     rf          ; load block address
        
-       sep     scall       ; display test message
-       dw      o_inmsg
-       db      'Allocation failed.',13,10,0
-okay:  lbr     o_wrmboot   ; return to Elf/OS       
+       sep     scall 
+       dw      o_dealloc
+           
+bye:   lbr     o_wrmboot   ; return to Elf/OS       
 ;----------------------------------------------------------------------------------------
                     
 ; define end of execution block