;
; xfer.xload.sh
;
; Simplified loading with coroutines
;
; © 1994-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;----- Overview -------------------------------------------------------------
;
; Functions provided:
;
;  xload_file
;  xload_initBuf
;  xload_killBuf
;  xload_extend
;  xload_doneBuf
;  xload_done
;  xload_failed
;  xload_byte
;  xload_word
;  xload_block

		[	:LNOT::DEF:xload__dfn
		GBLL	xload__dfn

; --- xload_file ---
;
; On entry:	R0 == pointer to loader routine
;		R1 == R10 value to pass to loader
;		R2 == R12 value to pass to loader
;		R3 == pointer to leafname of file (passed to loader in R0)
;		R4 == pointer to filename to load from
;		R5 == whether the file is safe (passed to loader in R1)
;
; On exit:	May return an error
;
; Use:		Calls a generalised loader routine to read data from a file.

		IMPORT	xload_file

; --- xload_initBuf ---
;
; On entry:	R0 == pointer to loader routine
;		R1 == R10 value to pass to loader
;		R2 == R12 value to pass to loader
;		R3 == pointer to leafname of file (passed to loader in R0)
;
; On exit:	R0 == pointer to load buffer
;		R1 == size of load buffer
;		May return an error
;
; Use:		Starts a RAM transfer and starts up a generalised load
;		routine.

		IMPORT	xload_initBuf

; --- xload_killBuf ---
;
; On entry:	--
;
; On exit:	--
;
; Use:		Does a buffer destroy for a failed load operation.

		IMPORT	xload_killBuf

; --- xload_extend ---
;
; On entry:	R1 == size of last buffer used for receiving
;
; On exit:	R0 == pointer to new buffer
;		R1 == size of new buffer
;		May return an error
;
; Use:		Performs a buffer extent operation during an xload RAM
;		transfer.

		IMPORT	xload_extend

; --- xload_doneBuf ---
;
; On entry:	R1 == total size of data received
;
; On exit:	R0 corrupted
;		May return an error
;
; Use:		Handles the last bufferful of a RAM load.

		IMPORT	xload_doneBuf

; --- xload_done ---
;
; On entry:	--
;
; On exit:	--
;
; Use:		Tidies up after a successful load job.

		IMPORT	xload_done

; --- xload_failed ---
;
; On entry:	R0 == pointer to error block
;
; On exit:	--
;
; Use:		Tidies up a RAM transfer after an error.

		IMPORT	xload_failed

; --- xload_byte ---
;
; On entry:	--
;
; On exit:	CC if data read OK, and
;		  R0 == byte read
;		else CC if end-of-file, and
;		  R0 corrupted
;		May return an error
;
; Use:		Reads a byte from the current input.

		IMPORT	xload_byte

; --- xload_word ---
;
; On entry:	--
;
; On exit:	CC if data read OK, and
;		  R0 == word read
;		else CS if end-of-file and
;		  R0 corrupted
;		May return an error
;
; Use:		Reads a word from the current input.

		IMPORT	xload_word

; --- xload_block ---
;
; On entry:	R0 == pointer to buffer to read
;		R1 == size of buffer to read
;
; On exit:	R0, R1 preserved
;		R2 == number of bytes read
;		CC if more data available, CS for end-of-file
;		May return an error
;
; Use:		Reads in a block of data.  Data is buffered, so this is
;		fairly quick for reading small objects.  Large data blocks
;		are read directly to avoid buffering overhead.

		IMPORT	xload_block

		]

;----- That's all, folks ----------------------------------------------------

		END