Bank Commands

AMCAF contains many commands that are dedicated to AMOS memory banks.
With all these commands it's important to use EVEN addresses, if there are some demanded.
Otherwise you will crash any computer with MC68000 processor.
In addition, the lengths of every bank must be even, or the compiler will report a "Not an AMOS program" error, but this is a problem of AMOS and not of AMCAF.

AMOS Memory Banks

AMOS banks are a linear block of memory (there are two Exceptions). In these chunks various kinds of data is stored. AMOS uses them mostly for packed graphics, sound, music, AMAL programs, menus, resources and other data.

Generally, there are four main types of memory banks:

Banks, that are stored in Chip ram and remain there permanently.
Banks, that are stored in Fast ram and remain there permanently.
Banks, that are stored in Chip ram and remain there temporarily only.
Banks, that are stored in Fast ram and remain there temporarily only.

Permanent and Temporary Memory Banks

BANK PERMANENT
instruction: make a memory bank permanent
Bank Permanent bank number

If you defined a bank as 'Work', but afterwards want this bank to be Permanently in memory and in the program, you could use Bank Permanent.
This will make the bank stay resident in your program until it is erased.
This command also has use on MED-Modules, which were loaded with the Med Load command and on Power and Imploder unpacked banks.

BANK TEMPORARY
instruction: make a memory bank temporary
Bank Temporary bank number

Changes a bank to Temporary-type, i.e it will be erased on the start of your program or when calling the Default-Command.

BANK TO FAST
instruction: move a memory bank to fast ram
Bank To Fast bank number

Moves a bank into Fast ram, if any is available. Naturally, the bank will get a new starting address.
Bank To Fast won't work with Icon and sprite bank.
Warning: Do not try to replay music or sound that exist in fast ram.

BANK TO CHIP
instruction: move a memory bank to chip ram
Bank To Chip bank number

Bank To Chip is the reverse command to Bank To Fast. It moves a bank into Chip ram. Obviously, the starting address will therefore change.

BANK STRETCH
instruction: extend the size of a bank to a new length
Bank Stretch bank number TO length

Extents the bank numbered 'bank' to the given new length 'length'.
During this process, the starting address of the bank is changed. This command does not work on Icon and sprite banks.

BANK COPY
instruction: copy a memory bank
Bank Copy sourcebank TO targetbank
Bank Copy startaddress,endaddress To targetbank

Creates a identical copy of the bank with the number 'sourcebank' in the bank numbered 'targetbank'.
The second version copies a specific part of the source bank into the target bank, creating a temporary bank of same content.

BANK NAME
instruction: rename a memory bank
Bank Name bank number,name$

This command renames a bank to the 8 characters long name 'name$'. Most AMOS commands ignore this ID, but e.g the AMOS Tracker commands require a bank named 'Tracker'.

Encoding and Decoding Memory Banks

Using these commands you can encode banks in many different ways to protect them from unauthorized access and insight. Especially manual copy protections can be made more secure by encoding the specific keyword bank.

Each command comes in two versions, one with the suffix .b and one with .w. By using the .b version the codenumber can range from 1 to 255, the .w version allows codes from 1 to 65535.
However, the rotational commands are an exception as the codes may only reach from 1 to 7 and from 1 to 15 respectively.

Every command has the following syntax

Bank Code xxx.y code,bank
Bank Code xxx.y code,startaddress To endaddress

BANK CODE ADD
instruction: encode or decode a memory bank using addition
Bank Code Add.b code,bank number
Bank Code Add.b code,startaddress To endaddress
Bank Code Add.w code,bank number
Bank Code Add.w code,startaddress To endaddress

Encodes the bank using the key code 'code'. To decode the bank, the same instruction has to be used with the negative key code.

Note: This encoding routine works by adding the value and is therefore very easy to decode.

BANK CODE XOR
instruction: encode or decode a memory bank using xor
Bank Code Xor.b code,bank number
Bank Code Xor.b code,startaddress To endaddress
Bank Code Xor.w code,bank number
Bank Code Xor.w code,startaddress To endaddress

Bank Code Xor encrypts a bank in a similar way to Bank Code Add using another algorithm. Each byte or word of the bank is combined by a 'logical exclusive or'.
To decode the bank simply use the same command along with the same key code.

Note: A Xor encryption is not so easy to crack without the right code. Good codes are $AA and $55.

BANK CODE MIX
instruction: encode or decode a memory bank using mix
Bank Code Mix.b code,bank number
Bank Code Mix.b code,startaddress To endaddress
Bank Code Mix.w code,bank number
Bank Code Mix.w code,startaddress To endaddress

The third possibility to encode a bank, is with Bank Code Mix. So coded banks should be hard to decode.
To decode a bank you should use the same key code as seen with Bank Code Xor.

BANK CODE ROL
instruction: encode or decode a memory bank using rol
Bank Code Rol.b code,bank number
Bank Code Rol.b code,startaddress To endaddress
Bank Code Rol.w code,bank number
Bank Code Rol.w code,startaddress To endaddress

Using this command every bit in each byte or word is rotated by 'code' bits to the left. (Rol=Rotate Left). This results in a restriction of the 'code' parameter from 1 to 7 on '.b' and 1 to 15 on '.w' command version.
To decode a bank either use the negative code with the same instruction or the same key code along with the Bank Code Ror command.

BANK CODE ROR
instruction: encode or decode a memory bank using ror
Bank Code Ror.b code,bank number
Bank Code Ror.b code,startaddress To endaddress
Bank Code Ror.w code,bank number
Bank Code Ror.w code,startaddress To endaddress

Similar to Bank Code Rol, but this time the bits are shifted to the right instead of left.

Delta Encoding and Decoding

BANK DELTA ENCODE
instruction: encode a memory bank using delta algorithm
Bank Delta Encode bank number
Bank Delta Encode startaddress To endaddress

Bank Delta Encode encodes a memory bank with the so-called delta algo.
This is not packing, however, but yields better pack ratios on 8-bit sound samples.
Delta encoding just stores the difference from one byte to the next, so it is certain full curve patterns in samples can be seen more 'clearly' for packing algorithms.

On Protracker Modules, you could use:

Encode samples only:

Pt Bank 3
Bank Delta Encode Pt Instr Address(1) To Start(3)+Length(3)

Decode:

Pt Bank 3
Bank Delta Decode Pt Instr Address(1) To Start(3)+Length(3)

BANK DELTA DECODE
instruction: decode a memory bank using delta algorithm
Bank Delta Decode bank number
Bank Delta Decode startaddress To endaddress

This command decodes a previously delta encoded memory region.
See Bank Delta Encode for more details on delta encoding.

Functions

BANK CHECKSUM
function: calculate the checksum of a memory bank
number=Bank Checksum(bank number)
number=Bank Checksum(startaddress To endaddress)

This function calculates a checksum of a bank with specific contents. Using this checksum you can find out if the contents of a bank has been changed.
The second version of this command calculates the checksum from the memory area from startaddress to endaddress.

BANK NAME$
function: get the name of a memory bank
name$=Bank Name$(bank number)

The function Bank Name$ returns the name of a memory bank.