There are two groups of FCode functions - OpenBoot 1 and OpenBoot 2. You will need to keep the differences in mind while writing your FCode program (depending on your intended system market).
The first SBus systems shipped by Sun used only OpenBoot 1 FCodes. Such systems, including SPARCstation1, 1+, 1E, original IPC, have a Open Boot PROM with a version number of 1.x. All later SPARC systems from Sun have an Open Boot PROM with a version number of 2.x. These systems recognize both Open Boot 1 and OpenBoot 2 FCodes. (2.x upgrade PROMs are available for SPARCstation 1, 1+ and IPC.)
Most basic FCode functions are OpenBoot 1. Framebuffer support FCodes are also OpenBoot 1. OpenBoot 2 FCodes support package access, bootable devices, and several other miscellaneous functions. The individual FCode descriptions state whether that FCode is version 2 or not. (See Appendix A, "FCode Reference" for a list of all OpenBoot 2 FCodes.)
Any OpenBoot 2 FCode encountered by a OpenBoot 1 system will not be recognized, causing the FCode program to fail. To deal with this possibility, write your FCode to conform to one of the several styles shown here. The correct choice of style will depend on your FCode requirements, and the intended system targets.
---------------------------
fcode-version1 ... (version 1 FCodes only) ... end0 ---------------------------
This style will operate correctly on either OpenBoot 1 or OpenBoot 2 systems.
-------------------------------------
fcode-version2 ... (version 1 plus version 2 FCodes) ... end0 -------------------------------------
This style operates correctly only on OpenBoot 2 systems. Any such FCode will abort immediately if encountered on a OpenBoot 1 system, as the fcode- version2 header will be rejected. This style is suitable for any device is not intended for operation on any OpenBoot 1 system.
-------------------------------------------------------------------
fcode-version1 ... (version 1 FCodes only) ... : v1-exit ( -- ) version h# 2.0000 < if ['] end0 execute then ; v1-exit ... (version 1 plus version 2 FCodes) ... end0 -------------------------------------------------------------------
This style will operate correctly on either OpenBoot 1 or OpenBoot 2 systems. It is used when OpenBoot 2 functionality is needed, but where a limited OpenBoot 1 functionality is also acceptable on OpenBoot 1 systems. It works by initially restricting usage to OpenBoot 1 FCodes only, and then ending FCode execution on a OpenBoot 1 system. On a OpenBoot 2 system, execution continues with subsequent OpenBoot 1 plus OpenBoot 2 FCodes.
Style 1 is suitable for framebuffers, and for other devices with simple non-boot FCode requirements.
Style 2 or 3 is appropriate for bootable devices, depending on whether an abbreviated non-boot functionality on OpenBoot 1 systems is appropriate or desired.
FCode that will operate on OpenBoot 1 systems must also take into account the following restrictions and limitations:
OpenBoot 1 systems only have about 13K of dictionary space to accomodate all plug-in SBus cards. Combinations of cards each containing FCode exceeding 5K or so in size may fail. (The actual size of the FCode binary can be used as a first estimate of the consumed dictionary space in many instances. For a more precise measure, look at the value in here at the start and end of FCode compilation.)
OpenBoot 2 systems have substantially more available dictionary space.
On OpenBoot 2 systems, the standard technique for device-dependent memory mapping/unmapping is with " xxxx" $call-parent (where " xxxx" could be " map-in", " map-out", " dma-alloc", " dma-free", " dma-map-in", " dma-map-out").
Since $call-parent is not defined on OpenBoot 1 systems, you must use the obsolescent FCode functions dma-alloc, map-sbus, memmap and free- virtual in FCode programs that will run on OpenBoot 1 systems.
On OpenBoot 1 systems, the total available mapping (for all devices) is hex 12.4000, divided into two regions: 10.0000 and 2.4000. The 10.0000 region is typically used up by the active framebuffer.
To ensure correct behavior with multiple devices, Sun recommends:
It is also best to perform a single larger mapping in preference to several smaller mappings, where possible.
On OpenBoot 1 systems, memory allocated with alloc-mem or buffer: uses up limited dictionary space. For general-purpose memory allocations larger than several hundred bytes or so, dma-alloc should be used instead to avoid this limitation. (OpenBoot 2 systems do not have this limitation, so alloc- mem and buffer: may be freely used.)
Memory allocated with alloc-mem, memmap, dma-alloc or map-sbus must be deallocated in a specific sequence on OpenBoot 1 systems. When de- allocating memory on OpenBoot 1 systems, you should de-allocate in the reverse order that the memory was allocated. (OpenBoot 2 systems do not have this restriction.)
On OpenBoot 1 systems, each device is limited to 16 properties total. (OpenBoot 2 systems do not have this restriction.)
OpenBoot 2.
In OpenBoot 1, my-address is a slot offset (200.0000, 400.0000, etc.) and my- space is a magic number representing the SBus address space. In OpenBoot 2, my-address is typically 0 and my-space is typically the SBus slot number. Properly-written FCode programs will operate correctly in both versions.
To do this, make sure that my-address and my-space are not interpreted directly, but are only used as input parameters to mapping functions (map- sbus, memmap, " map-in" $call-parent) or property declarations (reg, xdrphys).
On OpenBoot 1 systems, my-address will change when other slots are probed, so later execution of your routines which use my-address could generate illegal results. The best workaround is to save my-address into a constant or value during the initial probe, and then always use that saved value instead. (This precaution is not necessary on OpenBoot 2 systems.)
Execution of free-virtual on any OpenBoot 2 system will automatically delete an address property with the same virtual address contents.
Nested new-device FCodes will create "children-of-children" on FCode 2.0 systems. This feature is not supported on OpenBoot 1 systems: they will create only sibling children (children of the parent of the nested new-device operations).
finish-device is not implemented on SPARCstation 1 PROM versions 1.0 and 1.1. It is implemented as a NOP in other OpenBoot 1 systems.
OpenBoot 1 systems are limited to a maximum of eight plug-in device nodes per system. Each plug-in device occupies a node, and each new-device call uses up an additional node.