Squash

Introduction and Overview

This module provides general compression and decompression facilities of a lossless nature through a SWI interface. The algorithm is 12-bit LZW, however, this may change in future releases.

The interface is designed to be restartable, so that compression or decompression can occur from a variety of locations. Operations involving file I/O can easily be constructed from the operations provided.

This module is not available in RISC OS 2.

The module is used by the Squash application to generate files of type Squash (&FCA). The format of these files is documented in the chapter entitled FILEFORMATS.HTML#27821.

Errors

The following errors can be returned by the Squash module:

Error numberError text
&921Bad address for module Squash
&922Bad input for module Squash
&923Bad workspace for module Squash
&924Bad parameters for module Squash

SWI calls

Squash_CompressSWI &42700
Provides general compression of a lossless nature
R0=flags:
Bit(s)Meaning
0Start new operation; otherwise continue existing operation (using existing workspace contents)
1End of the input; otherwise more input exists after this
2Reserved, must be zero
3Return the work space size required and the maximum output size in bytes (all other bits must be 0); otherwise perform compression
4-31Reserved, must be zero
R1=input size (-1 to not return maximum output size) - if bit 3 of R0 is set; or workspace pointer - if bit 3 of R0 is clear
R2=input pointer, word aligned - if bit 3 of R0 is clear
R3=number of bytes of input available - if bit 3 of R0 is clear
R4=output pointer, word aligned - if bit 3 of R0 is clear
R5=number of bytes of output space available - if bit 3 of R0 is clear
R0=required work space size - if bit 3 of R0 set on input; else output status - if bit 3 of R0 clear on input:
ValueMeaning
0Operation completed
1Operation ran out of input data (R3 = 0)
2Operation ran out of output space (R5 < 12)
R1=Maximum output size (-1 if we don't know or wasn't asked) - if bit 3 of R0 set on input; else preserved - if bit 3 of R0 clear on input
R2=Updated to show first unused input byte - if bit 3 of R0 clear on input
R3=Updated to show number of input bytes not used - if bit 3 of R0 clear on input
R4=Updated to show first unused output byte - if bit 3 of R0 clear on input
R5=Updated to show number of output bytes not used - if bit 3 of R0 clear on input
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant

This call provides general compression of a lossless nature. It acts as a filter on a stream of data. The call returns if either the input or the output is exhausted.

It is recommended that you use the following facility to determine the maximum output size rather than attempting to calculate it yourself:

Call the SWI first with bit 3 of R0 set and the input size placed in R1. The maximum output size is then calculated and returned on exit in R1. You can use this value to allocate the required amount of space and call the SWI again setting the registers as appropriate.

The algorithm used by this module is 12-bit LZW, as used by the UNIX 'compress' command (with -b 12 specified). If future versions of the module use different algorithms, they will still be able to decompress existing compressed data.

If bits 0 and 1 of R0 are clear, and the output is definitely big enough, a fast algorithm will be used.

The performance of compression on an 8Mhz A420 with ARM2 is approximately as follows:

OperationSpeed
Store to store24 Kbytes per second
Fast case68 Kbytes per second

where 'Fast case' is store to store, with all input present, and with an output buffer large enough to hold all output.

Squash_DecompressSWI &42701
Provides general decompression of a lossless nature
R0=flags:
Bit(s)Meaning
0Start new operation; otherwise continue existing operation (using existing workspace contents)
1End of the input; otherwise more input exists after this
2You may assume that the output will all fit in this buffer (allows a faster algorithm to be used, if bits 0 and 1 are both 0)
3Return the work space size required and the maximum output size in bytes (all other bits must be 0); otherwise perform compression
4-31Reserved, must be zero
R1=input size (-1 to do not return maximum output size) - if bit 3 of R0 is set; or workspace pointer - if bit 3 of R0 is clear
R2=input pointer - if bit 3 of R0 is clear
R3=number of bytes of input available - if bit 3 of R0 is clear
R4=output pointer - if bit 3 of R0 is clear
R5=number of bytes of output space available - if bit 3 of R0 is clear
R0=required work space size - if bit 3 of R0 set on input; else output status - if bit 3 of R0 clear on input:
ValueMeaning
0Operation completed
1Operation ran out of input data (R3 < 12)
2Operation ran out of output space (R5 = 0)
R1=Maximum output size (-1 if we don't know or wasn't asked) - if bit 3 of R0 set on input; else preserved - if bit 3 of R0 clear on input
R2=Updated to show first unused input byte - if bit 3 of R0 clear on input
R3=Updated to show number of input bytes not used - if bit 3 of R0 clear on input
R4=Updated to show first unused output byte - if bit 3 of R0 clear on input
R5=Updated to show number of output bytes not used - if bit 3 of R0 clear on input
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is re-entrant

This SWI provides general decompression of a lossless nature.

Note: The current algorithm cannot predict what the size of the decompressed output will be. This means that, currently, -1 is always returned on exit in R1. In future releases this may change; it is therefore recommended that you call the SWI first with bit 3 of R0 set and the input size placed in R1.

In the case where R3 < 12, the unused input must be resupplied.

The performance of decompression on an 8Mhz A420 with ARM2 is approximately as follows:

OperationSpeed
Store to store48 Kbytes per second
Fast case280 Kbytes per second

where 'Fast case' is store to store, with all input present, and with an output buffer large enough to hold all output.