This is the third part, of a multi-part series about the system libraries. The previous post was about using the DOS library to read and write files.
We are still looking at Letter X of the Amiga Machine Code course, and as always, make sure to read the letter, since I won’t go through all the details.
In this post, and the next one, we will take at how to use the DOS library to interact with the command line interface of the AmigaOS.
CLI Arguments and Output
The Amiga ships with a command line interface, called CLI. In this section we’ll take a look at how I/O from, and to, the CLI works.
Letter X starts by explaining only the most just about enough about the CLI, to get you going with the first example program mc1004.
When the CLI runs a program, it allocates a stack for that program, and puts the pointer to the argument line into register a0. The pointer to the argument line is on the CLI stack and remains valid during program execution. The CLI also also puts the length of the argument line into d0. Note that the last character is typically a return, which we will ignore in the mc1004 program.
The mc1004 program will take an argument from the command line and echo it back. To do this, we need a file handle to the output. The Dos library function Output by will return a file handle, that typically refers to the CLI terminal, unless the output was redirected on the command line, by “>” and “<” like we know from unix.
Output Description: finds the program´s initial output filehandle Library: dos.library Offset: -$3C (-60) Syntax: fh = Output() ML: d0 = Output() Arguments: none Result: fh = program´s output filehandle
The Output function is also described in the autodocs, where we are told to never close the filehandle. The filehandle was opened for us by the CLI, and should also be closed by the CLI.
Let’s take a look at mc1004, which also can be found on disk1. The program will read an argument from the command line and echo it back into the same command line.
cmp.w #1,d0 ; compare 1 with d0 (argument length from CLI) ble noarg ; if d0 <= 1, then goto noarg lea.l argbuffer,a1 ; move argbuffer address into a1 move.l d0,d7 ; move d0 into d7 copyarg: ; copy argument move.b (a0)+,(a1)+ ; move value pointed to by a0 into argbuffer and post increment both subq.w #1,d0 ; subtract 1 from argument length cmp.w #0,d0 ; compare d0 with zero - we leave the last argument character since it's just a return bne copyarg ; if d0 != 0 then goto copyarg bsr opendos ; branch to subroutine opendos move.l d7,d0 ; move d7 into d0 (restore argument length) lea.l argbuffer,a0 ; move argbuffer address into a0 bsr writechar ; branch to subroutine writechar rts ; return from subroutine noarg: ; handling that no arguments was entered in CLI rts ; return from subroutine argbuffer: blk.b 80,0 ; allocate 80 bytes to argbuffer writechar: ; writechar subroutine. writechar(a0,d0) movem.l d1-d7/a0-a6,-(a7) ; push register values onto the stack move.l a0,a5 ; move a0 (argbuffer) into a5 move.l d0,d5 ; move d0 (arg length) into d5 lea.l txt_dosbase,a0 ; move txt_dosbase address into a0 (contains base address of dos.library) move.l (a0),a6 ; move base address of dos.library into a6 jsr -60(a6) ; call Output in dos.library. d0 = output() move.l d0,d1 ; move d0 (filehandle) into d1 move.l a5,d2 ; move a5 (argbuffer) into d2 move.l d5,d3 ; mvoe d5 (arg length) into d3 jsr -48(a6) ; call Write in dos.library. d0 = Write(d1,d2,d3) movem.l (a7)+,d1-d7/a0-a6 ; pop values from the stack into the registers rts ; return from subroutine opendos: ; opendos subroutine. opendos() movem.l d0-d7/a0-a6,-(a7) ; push register values onto the stack clr.l d0 ; clear d0 move.l $4,a6 ; move base pointer of exec.library into a6 lea.l txt_dosname,a1 ; move pointer to library name into a1 jsr -408(a6) ; call OpenLibrary in the exec.library. d0 = OpenLibrary(a1,d0) lea.l txt_dosbase,a5 ; move address of txt_dosbase into a5 move.l d0,(a5) ; move dos.library base address into txt_dosbase movem.l (a7)+,d0-d7/a0-a6 ; pop values from the stack into the registers rts ; return from subroutine txt_dosname: dc.b "dos.library",0 ; library name terminated by zero txt_dosbase: dc.l $0 ; allocation for holding the base address of dos.library
It’s important to run this program from the CLI, otherwise it won’t work. To compile the program and make an executable, write the following in Seka.
SEKA>a OPTIONS> No Errors SEKA>W FILENAME>mc1004
Then go into the CLI and run the program and see it echo back the arguments
1.amigahd:DISK1/BREV10>mc1004 cheers mate cheers mate 1.amigahd:DISK1/BREV10>
It works! Cheers! 🍺
Next we’ll tie it all together in a larger program.
Now it’s time to combine the subroutines, so that the scroller program we took a look at back in a previous post, can be upgraded to take advantage of our new knowledge.
The mc1005 program upgrades mc0701, so that it now is expected to run from the CLI taking a filename as argument. The file will contain the text that should be scrolled across the screen. No more recompilation because of spelling mistakes - yay 🚀
I won’t comment all of the code. Much of it has been described before. For the orignal scroller, check out mc0701 described in this letter VII post.
Here’s the code for mc1005 with my comments added, where the code differs from mc0701. The code is also found on disk1.
cmp.w #1,d0 ; compare d0 (CLI argument lenght) with 1 bgt argok ; if d0 > 1 then go to argok (we ignore carriage return) rts ; return from subroutine (no arguments) argok: ; arguments present lea.l filename,a1 ; move filename address into a1 copyargloop: ; copy arguments to a1 (filename) move.b (a0)+,(a1)+ ; move arguments that a0 points at, to what a1 points at, then post increment subq.w #1,d0 ; subtract d0 (argumnent length) by 1 cmp.w #1,d0 ; compare d0 with 1 (have we reached the end?) bne copyargloop ; if d0 > 1 go to copyargloop move.l #50000,d0 ; move 50000 to d0 (number of bytes to allocate) bsr allocdef ; branch to subroutine allocdef. d0 = allocdef(d0) cmp.l #0,d0 ; compare d0 with 0 (check return value from allocdef) bne memok ; if d0 != 0 then goto memok rts ; return from subroutine (memory error) memok: ; memory ok lea.l buffer,a1 ; move buffer address into a1 move.l d0,(a1) ; move d0 (points to allocated memory) into address pointed to by a1 (buffer) lea.l filename,a0 ; move filename address into a0 move.l d0,a1 ; move d0 (points to allcoated memory) into a1 move.l #50000,d0 ; move 50000 into d0 bsr readfile ; branch to subroutine readfile. d0 = readfile(a0,a1,d0) cmp.l #0,d0 ; compare d0 with 0 (check return value from readfile) beq freeup ; if d0 = 0 then goto freeup (no bytes were read) move.w #$4000,$dff09a or.b #%10000000,$bfd100 and.b #%10000111,$bfd100 move.w #$01a0,$dff096 move.w #$1200,$dff100 move.w #0,$dff102 move.w #0,$dff104 move.w #2,$dff108 move.w #2,$dff10a move.w #$2c71,$dff08e move.w #$f4d1,$dff090 move.w #$38d1,$dff090 move.w #$0030,$dff092 move.w #$00d8,$dff094 lea.l screen,a1 lea.l bplcop,a2 move.l a1,d1 swap d1 move.w d1,2(a2) swap d1 move.w d1,6(a2) lea.l copper,a1 move.l a1,$dff080 move.w #$8180,$dff096 mainloop: move.l $dff004,d0 asr.l #8,d0 and.l #$1ff,d0 cmp.w #300,d0 bne mainloop bsr scroll btst #6,$bfe001 bne mainloop freeup: ; free memory move.l #50000,d0 ; move 50000 into d0 (50000 bytes) lea.l buffer,a0 ; move buffer address into a0 move.l (a0),a0 ; move value in a0 (points to allocated memory) into a0 bsr freemem ; branch to subroutine freemem. freemem(a1,d0) move.w #$0080,$dff096 move.l $04,a6 move.l 156(a6),a1 move.l 38(a1),$dff080 move.w #$80a0,$dff096 move.w #$c000,$dff09a rts scrollcnt: dc.w $0000 charcnt: dc.w $0000 scroll: lea.l scrollcnt,a1 cmp.w #8,(a1) bne nochar clr.w (a1) lea.l charcnt,a1 move.w (a1),d1 addq.w #1,(a1) lea.l buffer,a2 ; move buffer address into a2 move.l (a2),a2 ; move value in a2 (points to allocated memory) into a2 clr.l d2 move.b (a2,d1.w),d2 cmp.b #42,d2 bne notend clr.w (a1) move.b #32,d2 notend: lea.l convtab,a1 move.b (a1,d2.b),d2 asl.w #1,d2 lea.l font,a1 add.l d2,a1 lea.l screen,a2 add.l #6944,a2 moveq #19,d0 putcharloop: move.w (a1),(a2) add.l #64,a1 add.l #46,a2 dbra d0,putcharloop nochar: btst #6,$dff002 bne nochar lea.l screen,a1 add.l #7820,a1 move.l a1,$dff050 move.l a1,$dff054 move.w #0,$dff064 move.w #0,$dff066 move.l #$ffffffff,$dff044 move.w #$29f0,$dff040 move.w #$0002,$dff042 move.w #$0517,$dff058 ; changed from #$0523 to #$0517 by me (I suspect an error) lea.l scrollcnt,a1 addq.w #1,(a1) rts readfile: ; the readfile subroutine (described elsewhere) movem.l d1-d7/a0-a6,-(a7) move.l a0,a4 move.l a1,a5 move.l d0,d5 move.l $4,a6 lea.l r_dosname,a1 jsr -408(a6) move.l d0,a6 move.l #1005,d2 move.l a4,d1 jsr -30(a6) cmp.l #0,d0 beq r_error move.l d0,d1 move.l d0,d7 move.l a5,d2 move.l d5,d3 jsr -42(a6) move.l d7,d1 move.l d0,d7 jsr -36(a6) move.l d7,d0 movem.l (a7)+,d1-d7/a0-a6 rts r_error: ; handle readfile error clr.l d0 ; clear d0 movem.l (a7)+,d1-d7/a0-a6 ; pop values from the stack into the registers rts ; return from subroutine r_dosname: dc.b "dos.library",0 ; library name terminated by zero allocdef: ; the allocdef subroutine (described elsewhere) movem.l d1-d7/a0-a6,-(a7) moveq #1,d1 swap d1 move.l $4,a6 jsr -198(a6) movem.l (a7)+,d1-d7/a0-a6 rts freemem: ; the freemem subroutine (described elsewhere) movem.l d0-d7/a0-a6,-(a7) move.l a0,a1 move.l $4,a6 jsr -210(a6) movem.l (a7)+,d0-d7/a0-a6 rts copper: dc.w $2c01,$fffe dc.w $0100,$1200 bplcop: dc.w $00e0,$0000 dc.w $00e2,$0000 dc.w $0180,$0000 dc.w $0182,$0ff0 dc.w $ffdf,$fffe dc.w $2c01,$fffe dc.w $0100,$0200 dc.w $ffff,$fffe screen: blk.l $b80,0 font: blk.l $140,0 convtab: dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $1f ;" " dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $1f ;" " dc.b $00 dc.b $00 dc.b $1b ;Ø dc.b $1c ;Å dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $1d ;, dc.b $00 ;- dc.b $1e ;. dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $00 dc.b $1a ;Æ dc.b $00 ;A dc.b $01 ;B dc.b $02 ;C dc.b $03 ;... dc.b $04 dc.b $05 dc.b $06 dc.b $07 dc.b $08 dc.b $09 dc.b $0a dc.b $0b dc.b $0c dc.b $0d dc.b $0e dc.b $0f dc.b $10 dc.b $11 dc.b $12 dc.b $13 dc.b $14 dc.b $15 dc.b $16 ;.... dc.b $17 ;X dc.b $18 ;Y dc.b $19 ;Z dc.b $00 dc.b $00 dc.b $00 buffer: dc.l 0 ; holds the pointer to the allocated buffer (holds contents of file) filename: blk.b 50,0 ; the filename
To compile the program and make an executable, write the following in Seka.
SEKA>a OPTIONS> No Errors SEKA>ri FILENAME>font BEGIN>font END> SEKA>wo MODE>c FILENAME>scroll SEKA>
Notice that the mode is set to c, which I think is for chip ram. I also tried f, which I guess is for fast RAM, but that won’t work since we have a screen buffer in the program, that needs to reside in chip ram.
I have called the executable for scroll. Now use it in the CLI like this:
You should now see some nice scrolling text 😃. Remember that hitting the left mouse button quits the program.
Something Odd About the Size
When looking at the BREV10 folder in disk1, I noticed that the mc1005 executable was only 2.304 bytes, while my scroll executable was a whopping 14.076 bytes.
I think the folks, that prepared disk1 had to conserve the scarce 880 kB space, there is on an Amiga disk. It looks like they did not allocate the screen buffer in the program, but just used e.g. the allocchip subroutine.
screen: blk.l $b80,0
This allocation of the screen buffer within the program is 11.776 bytes. From the letter VII post, we know that the screen is 23 words times 256 lines, and that’s exaclty the size of the screen buffer. $$23 words * 2 * 256 lines = 11.776 bytes$$
Funny enough, that’s almost the difference between the sizes of the executables. $$14076 bytes - 2304 bytes = 11.772 bytes $$
I would not have expected it to match exactly, since we need some extra calls to allocate memory for the screen.
Since it’s so easy to allocate memory, we should really not allocate large buffers within the program, since it only creates bloated executables. Another benefit, is that we can place our program in fast ram, while allocating buffers in chip ram, that can be accessed by the custom chips. In this way we save some of the scarce chip ram.
Previous post: Amiga Machine Code Letter X - Files.
Next post: Amiga Machine Code Letter X - More CLI.