.CR     CRoss Overlay load

Syntax:

        .CR  filename[.ext]

Function:

The .CR directive loads a Cross Overlay into memory.

See also:

Cross Overlays

Boundary Sync:

In Version 3 of the SB-Assembler this directive will perform a boundary sync.

Explanation:

This is one of the most powerful directives of the SB-Assembler and yet you normally use it only once per project. It loads a Cross Overlay into memory. This allows the SB-Assembler to assemble programs for almost any type of processor. It can even be used more than once in one program to switch between different Cross Overlays in one assembly run to create a program for different processors at same the time.

In Version 2 of the SB-Assembler the .CR directive must be followed by a filename which may be preceded by a drive letter and/or path name.
The extension .ext is optional and if it is omitted the default extension .SBA is used.
If no drive letter and/or path name are given the overlay is searched for in the current directory. If it can't be found there the search continues in the parent directory of the SB-Assembler which is the directory from which the program sbasm.com was started. So normally it is not necessary to include drive and path names. It's even better not to include them at all.
If the requested Cross Overlay is already resident in memory it will not be loaded again. This is usually the case at the start of the second pass of the assembler.

In Version 3 of the SB-Assembler the .CR directive must be followed by the cross overlay name. Cross overlays are always stored in the sbapack directive of the SB-Assembler package. All cross overlay files have a name like cr*.py, where * is the actual name of the cross overlay to be used by the .CR directive. So you only specify this * part as cross name behind the .CR directive, like for example .CR Z80 (this will use the file crz80.py).
Please note that the * part is always changed to lower case letters, so it doesn't really matter what case you use for the overlay name.
Some cross names are longer than 8 characters, including the leading 'cr'. This may cause some problems on DOS only systems. You may rename the affected crosses to your preference and use the new name instead of the original one.

In any case, the cross overlay be initialized by the .CR directive, even when the cross overlay was already in memory. This means that some default values are set, like the endian model (the order in which multiple byte values are stored in memory). Also Cross Overlay specific settings are set to their default value, e.g. the .DP value for the 6809 Cross Overlay will be reset to $00.
Please note that this initializing is also done if the Cross Overlay was already resident in memory!

In Version 3 of the SB-Assembler a previously loaded cross overlay is allowed to clean up first, before the new overlay is loaded. This allows the system to finish pending operations. One example is the AVR assembler, which is able to write bytes to the otherwise word sized memory. Should the last write to code memory end up on an odd location, the clean-up would add a padding byte to make it end on an even location.

It is even possible to have more than one Cross Overlay loaded during one assembly run. This enables you to create programs for mixed processor types.
One of the best examples for such a situation was the Apple ][ computer which had a native 6502 processor and could have an optional Z80 or 6809 processor installed. The 6502 should initialize the system and handle all I/O while the Z80 might be doing the number crunching. Please note that both processors were sharing the same memory buses. To write programs for such a system requires an assembler that can handle more than one processor type at the same time. The SB-Assembler is such an assembler!
Another example could be a programming device to program Motorola processors. These processors need a little bootstrap loader to be uploaded before they can accept the code that must be written into EEPROM. The programmer itself can be made with any type of processor, e.g. an 8052. But the little bootstrap loader code must be written in the target processor's language. The 8052 treats that piece of code as data while the target processor accepts it as executable code.
There is no limit to the number of Cross Overlay switches in an assembly run to the SB-Assembler's point of view. Practically it may be difficult to implement the resulting code in most cases though ;-)

Also note that the SB-Assembler doesn't know any mnemonics of any processor type until a Cross Overlay is loaded into memory. The .CR is to be used before any code or data is generated by the assembler because the Cross Overlay determines the endian model, which is the order in which multiple byte values are stored in memory.

Examples:

        .CR    Z80            Load the Z80 Cross Overlay
        .CR    6502           Load the 6502 Cross Overlay

In Version 3 of the SB-Assembler the .CR directive has a hidden feature. This hidden debug feature is enabled when the .CRD directive is used instead of the normal .CR directive. Normally you would only need this hidden feature when you are writing your own cross overlays. If you don't enable the debug function the assembler will only complain that it can't load the overlay when you make a programming error, without telling you where the error occurred.
More information can be found on the DIY page.