SPARC Processor Issues

This section describes a number of SPARC processor-specific topics including data alignment, byte ordering, register windows, and availability of floating point instructions. For information on X86 processor-specific topics, see "x86 Processor Issues" on page 17. For information on PowerPC processor-specific topics, see "PowerPC Processor Issues" on page 18

Data Alignment

All quantities must be aligned on their natural boundaries. Using standard C data types:

• short integers are aligned on 16-bit boundaries.
• long integers are aligned on 32-bit boundaries.

• long long integers are aligned on 64-bit boundaries.

Usually, alignment issues are handled by the compiler. Driver writers are more likely to be concerned about alignment as they must use the proper data types to access their device. Since device registers are commonly accessed through a pointer reference, drivers must ensure that pointers are properly aligned when accessing the device. See "Data Access Functions" on page 55 for more information about accessing device registers.

Structure Member Alignment

Because of the data alignment restrictions imposed by the SPARC processor, C structures also have alignment requirements. Structure alignment requirements are imposed by the most strictly-aligned structure component. For example, a structure containing only characters has no alignment restrictions, while a structure containing a long long member must be constructed to guarantee that this member falls on a 64-bit boundary. See "Structure Padding" on page 59 for more information on how this relates to device drivers.

Byte Ordering

The SPARC processor uses big endian byte ordering; in other words, the most significant byte of an integer is stored at the lowest address of the integer.

Register Windows

SPARC processors use register windows. Each register window is comprised of 8 in registers, 8 local registers, and 8 out registers (which are the in registers of the next window). There are also 8 global registers. The number of register windows ranges from 2 to 32 depending on the processor implementation.

Because drivers are normally written in C, the fact that register windows are used is usually hidden by the compiler. However, it may be necessary to use them when debugging the driver. See "Debugging Tools" on page 323 for more information on how register windows are used when debugging.

Floating Point Operations

Drivers should not perform floating point operations, since they are not supported in the kernel.

Multiply and Divide Instructions

The Version 7 SPARC processors do not have multiply or divide instructions. These instructions are emulated in software and should be avoided. Since a driver cannot tell whether it is running on a Version 7 or Version 8 processor, intensive integer multiplication and division should be avoided if possible. Instead, use bitwise left and right shifts to multiply and divide by powers of two.

SPARC Architecture Manual

The SPARC Architecture Manual, Version 8, contains more specific information on the SPARC CPU.

x86 Processor Issues

This section describes a number of x86 processor-specific topics including data alignment, byte ordering and floating point instructions.

Data Alignment

There are no alignment restrictions on data types. However, extra memory cycles may be required for the x86 processor to properly handle misaligned data transfers.

Structure Member Alignment

See "Structure Padding" on page 59 for more information on how this relates to device drivers.

Byte Ordering

The x86 processor uses little endian byte ordering. The least significant byte of an integer is stored at the lowest address of the integer.

Floating Point Operations

Drivers should not perform floating point operations, since they are not supported in the kernel.

x86 Architecture Manuals

Intel Corporation publishes a number of books on the x86 family of processors.

80386 Programmer's Reference Manual, Intel Corporation, 1986. ISBN 1-55512- 022-9.

i486 Microprocessor Hardware Reference Manual, Intel Corporation, 1990. ISBN 1- 55512-112-8.

Pentium Processor User's Manual - Volume 3: Architecture and Programming Manual, Intel corporation, 1993. ISBN 1-55512-195-0.

PowerPC Processor Issues

Data Alignment

All quantities must be aligned on their natural boundaries. Using standard C data types:

• short integers are aligned on 16-bit boundaries.
• long integers are aligned on 32-bit boundaries.
• long long integers are aligned on 64-bit boundaries.

Usually, alignment issues are handled by the compiler. Driver writers are more likely to be concerned about alignment as they must use the proper data types to access their device. Since device registers are commonly accessed through a pointer reference, drivers must ensure that pointers are properly aligned when accessing the device. See "Data Access Functions" on page 55 for more information about accessing device registers.

Structure Member Alignment

Because of the data alignment restrictions imposed by the PowerPC (TM) microprocessor-based system, C structures also have alignment requirements. Structure alignment requirements are imposed by the most strictly-aligned structure component. For example, a structure containing only characters has no alignment restrictions, while a structure containing a long long member must be constructed to guarantee that this member falls on a 64-bit boundary. See "Structure Padding" on page 59 for more information on how this relates to device drivers.

Byte Ordering

The PowerPC processor uses little endian byte ordering. The least significant byte of an integer is stored at the lowest address of the integer.

Floating Point Operations

Drivers should not perform floating point operations, since they are not supported in the kernel.

PowerPC Architecture Manual

The PowerPC(TM) Architecture: A Specification or a New Family of RISC Processors,

Edited by Cathy May, Ed Silha, Rick Simpson, Hank Warren. Morgan Kaufman Publishers, Inc., San Francisco. Second Edition, May, 1994.

Store Buffers

To improve performance, the CPU uses internal store buffers to temporarily store data. This may affect the synchronization of device I/O operations. Therefore, the driver needs to take explicit steps to make sure that writes to registers complete at the proper time.

For example, when access to device space (such as registers or a frame buffer) is synchronized by a lock, the driver needs to make sure that the store to the device space has actually completed before releasing the lock. Releasing the lock does not guarantee the flushing of I/O buffers.

When acknowledging an interrupt, to give another example, the driver usually sets or clears a bit in a device control register. The driver must ensure that the write to the control register has reached the device before the interrupt handler returns. Similarly, if the device requires a delay (the driver busy-waits) after writing a command to the control register, the driver must ensure that the write has reached the device before delaying.

If the device registers can be read without undesirable side effects, verification of a write can be as simple as reading the register immediately after writing to it. If that particular register cannot be read without undesirable side effects, another device register in the same register set can be used.

---

Note - On PowerPC, the SYNC instruction ensures that the effects of any stores are applied in program order before the sync completes. Releasing a lock (a mutex) executes a SYNC instruction, thereby guaranteeing the flushing of stores to I/O buffers.

---

System Memory Model

The system memory model defines the semantics of memory operations such as load and store and specifies how the order in which these operations are issued by a processor is related to the order in which they reach memory. The

memory model applies to both uniprocessors and shared-memory multiprocessors. Two memory models are supported: Total Store Ordering (TSO) and Partial Store Ordering (PSO).

Total Store Ordering (TSO)

TSO guarantees that the sequence in which store, FLUSH, and atomic load-store instructions appear in memory for a given processor is identical to the sequence in which they were issued by the processor.

Both x86 and SPARC processors support TSO.

Partial Store Ordering (PSO)

PSO makes no guarantee that the sequence in which store, FLUSH, and atomic load-store instructions appear in memory for a given processor is identical to the sequence in which they were issued by the processor. The processor can reorder the stores so that the sequence of stores in memory is not the same as the sequence of stores in the CPU.

SPARC and PowerPC processors support PSO; x86 processors do not.

For SPARC processors, conformance between issuing order and memory order is provided by the system framework using the STBAR instruction: if two of the above instructions are separated by a STBAR in the issuing order of a processor, or if they reference the same location, then the memory order of the two instructions is the same as the issuing order.

See Chapter 6, Appendix J, and Appendix K of The SPARC Architecture Manual, Version 8 for more details on the SPARC memory model.

For PowerPC, the EIEIO instruction assures that all memory references issued before the EIEIO become visible to other processors and mechanisms (such as DMA) before any references issued after the EIEIO. The SYNC instruction ensures not only the ordering, but the completion of the references before the SYNC.

Bus Architectures

This section describes a number of bus-specific topics including device identification, device addressing, and interrupts.

Device Identification

Device identification is the process of determining which devices are present in the system.

Self-Identifying Devices

Some devices are self-identifying--the device itself provides information to the system so that it can identify the device driver that needs to be used. The device usually provides additional information to the system in the form of name-value (name=value) pairs that can be retrieved using the property interfaces. See "Properties" on page 69 for more information on properties.

SBus and PCI Local bus devices are examples of self-identifying devices. On SBus, the information is usually derived from a small FORTH program stored in the FCode PROM on the device. PCI devices provide a configuration space containing device configuration information. See sbus(4) and pci(4) for more information.

Non-Self-Identifying Devices

Devices that do not provide information to the system to identify themselves are called non-self-identifying devices. Drivers for these devices must have a probe(9E) routine which determines whether the device is really there. In addition, information about the device must be provided in a hardware configuration file (see driver.conf(4)), so that the system can provide probe(9E) with the information it needs to contact the device. See probe(9E) for more information.

VMEbus, ISA, EISA, and MicroChannel devices are examples of non-self-identifying devices. See vme(4), isa(4), eisa(4), and mca(4) for more information.

Interrupts

SunOS supports polling interrupts and vectored interrupts.The Solaris 2.x DDI/DKI interrupt model is the same for both. See "Types of Interrupts" on page 118," for more information about interrupt handling.

Bus Specifics

This section covers addressing and device configuration issues specific to the buses that SunOS supports.

PCI Local Bus

The PCI Local Bus is a high performance bus designed for high-speed data transfer. The PCI bus usually resides on the system board and operates at speeds close to those of the host processor. The PCI bus is normally used as an interconnect mechanism between highly integrated peripheral components, peripheral add-on boards and process/memory systems. The processor, main memory and the high speed PCI bus itself are connected through a PCI host bridge, as shown in Figure 2-1 on page 24.

A tree structure of interconnected I/O buses is supported through a series of PCI bus bridges. Subordinate PCI bus bridges can be extended underneath the PCI host bridge to allow a single bus system to be expanded into a complex system with multiple secondary buses. PCI devices can be connected to one of these secondary buses. In addition, other bus bridges like SBus, ISA-bus, etc. can be connected.

Every PCI device has a unique vendor ID and device ID. Multiple devices of the same kind are further identified by their unique device numbers on the bus where they reside.

Typical PCI devices include SCSI adaptors, graphics/ display adaptors, network controllers, etc.

Figure 2-1

The PCI host bridge provides an interconnect between the processor and peripheral components. Through the PCI host bridge, the processor can directly access main memory independent of other PCI bus masters. For example, while the CPU is fetching data from the cache controller in the host bridge, other PCI devices can also access the system memory through the host bridge. The advantage of this architecture lies in its separation of the I/O bus from the processor's host bus.

The PCI host bridge also provides data access mappings between the CPU and peripheral I/O devices. It maps every peripheral device to the host address domain so that the processor can access the device through memory mapped I/O or special I/O instructions. On the local bus side, the PCI host bridge maps the

system memory to the PCI address domain so that PCI device can access the host memory as a bus master. The two address domains are shown in Figure 2-2.

Figure 2-2

PCI Address Domain

The PCI address domain consists of three distinct address spaces: Configuration, Memory and I/O space.

Configuration Address Space

Configuration space is defined geographically; in other words, the location of a peripheral device is determined by its physical location within an interconnected tree of PCI bus bridges. A device is usually located by its bus number and device (slot) number. Each peripheral device contains a set of well-defined configuration registers in its PCI configuration space. The registers are used not only to identify devices but also to provide device configuration

through system software. For example, base address registers in the device Configuration space must be allocated before a device can respond to data access. The Configuration space registers are illustrated in Figure 2-3.

Figure 2-3

The method for generating configuration cycles is host dependent. In x86 machines, special I/O ports are used. In other Instruction Set Architectures, the PCI configuration space may be memory-mapped to certain address locations corresponding to the PCI host bridge in the host address domain. When a device configuration register is accessed by the processor, the request will be routed to the PCI host bridge. The bridge then translates the access into proper configuration cycles on the bus.

Configuration Base Address Registers

The PCI Configuration space consists of up to six 32-bit base address registers for each device. These registers provide both size and data type information. System firmware assigns base addresses in the PCI address domain to these registers.

The firmware identifies the size of each addressable region by writing all 1's to the base address register and then reading back the value. The device will return 0's in all don't-care address bits, effectively specifying the size of the address space.

Each addressable region can be either Memory or I/O space. The value contained in bit 0 of the base address register identifies the type. A value of 0 in bit 0 indicates a Memory space and value of 1 indicates an I/O space. Figure 9 shows two base address registers: one for Memory; the other for I/O types.

Figure 2-4

Memory Address Space

PCI supports both 32-bit and 64-bit addresses for Memory space. System firmware assigns regions of Memory space in the PCI address domain to PCI peripherals. The base address of a region is stored in the base address register of the device's PCI configuration space. The size of each region must be a power of two, and the assigned base address must be aligned on a boundary

equal to the size of the region. Device addresses in Memory space are memory-mapped into the host address domain so that data access to any device can be performed by the processor's native load/store instructions.

I/O Address Space

PCI supports 32-bit I/O space. I/O space may be accessed differently in different Instruction Set Architectures. Processors with special I/O instructions, like the Intel processor family, access the I/O space with in and out instructions. Machines with no special I/O instructions are usually memory-mapped to the address locations corresponding to the PCI host bridge in the host address domain. When the processor accesses the memory-mapped addresses, an I/O request will be sent to the PCI host bridge. It then translates the addresses into I/O cycles and puts them on the PCI bus. Memory-mapped I/ O is performed by the native load/store instructions of the processor. For example, reading from or writing to a memory mapped data register can be done by a load or store instruction to that register's I/O address.

Hardware Configuration Files

Hardware configuration files should be unnecessary for PCI Local bus devices. However, on some occasions drivers for PCI devices may need to use hardware configuration files to augment the driver private information. See driver.conf(4) and pci(4) for further details.

SBus

Typical SBus systems consist of a motherboard (containing the CPU and SBus interface logic), a number of SBus devices on the motherboard itself, and a number of SBus expansion slots. An SBus can also be connected to other types of buses through an appropriate bus bridge.

The SBus is geographically addressed; each SBus slot exists at a fixed physical address in the system. An SBus card has a different address depending on which slot it is plugged into. Moving an SBus device to a new slot causes the system to treat it as a new device. See "Persistent Instances" on page 101 for more information.

The SBus uses polling interrupts. When an SBus device interrupts, the system only knows which of several devices might have issued the interrupt. The system interrupt handler must ask the driver for each device whether it is responsible for the interrupt.

Following is a discussion of how the SBus is implemented on various SPARCstations.

Physical Address Space

The physical address space layout of the SPARCstation 20 is shown in Table 2-1. A physical address on the SPARCstation 20 consists of 36 bits. The 36-bit physical address space is further broken down into 16 32-bit address spaces identified by PA(35:32).

Table 2-1

PA(35:32)	32-bit space	Usage
0x0	0x00000000 - 0xFFFFFFFF	Main Memory
0x1-0xD	Not used on SS20	Not used on SS20
0xE	0x00000000 - 0x0FFFFFFF 0x10000000 - 0x1FFFFFFF 0x20000000 - 0x2FFFFFFF 0x30000000 - 0x3FFFFFFF 0xE0000000 - 0xEFFFFFFF 0xF0000000 - 0xFFFFFFFF	SBus Slot 0 SBus Slot 1 SBus Slot 2 SBus Slot 3 SBus Slot E SBus Slot F
0xF	0x00000000 - 0xFFFFFFFF	Control space

Physical SBus Addresses

The SBus has 32 address bits, as described in the SBus Specification. In the SPARCstation 20, the address bits are used as described in Table 2-2:

Table 2-2

Bits	Description
0 - 27	These bits are the SBus address lines used by a SBus card to address the contents of the card.
28 - 31	Used by the CPU to select one of the SBus slots. These bits generate the SlaveSelect lines.

This addressing scheme yields the SPARCstation 20 addresses shown earlier in Table 2-1. Other implementations may use a different number of address bits.

The SPARCstation 20 has six SBus slots, four of which are physical. Slots 0 through 3 are available for SBus cards. Slots 4-13 are reserved. The slots are used in the following way:

• Slots 0--3 are physical slots that have DMA-master capability.
• Slot E and F are not actual physical slots, but refer to the on-board DMA, SCSI, Ethernet and Audio controllers. For convenience, these are viewed as being plugged into Slot E and F.

---

Note - Some SBus slots are slave-only slots, such as slot 3 on the SPARCstation1. Drivers that require DMA capability should use ddi_slaveonly(9F) to determine if their device is in a DMA-capable slot. For an example of this function, see "attach( )" on page 105.

---

Hardware Configuration Files

Hardware configuration files are normally unnecessary for SBus devices. However, on some occasions drivers for SBus devices may need to use hardware configuration files to augment the information provided by the SBus card. See driver.conf(4) and sbus(4) for further details.

VMEbus

The VMEbus supports multiple address spaces. Appropriate entries in the driver.conf(4) file should be made for the address spaces used by the device For DMA devices, the address space that the board uses for its DMA transfers must be known by the driver (this is usually a 32- or 24-bit space).

A VMEbus card has its own address, possibly configurable by jumpers. A VMEbus card has the same address no matter which slot it is plugged into. Changing the address of a VME card causes the system to treat it as a new device.

The VMEbus uses vectored interrupts. When a VMEbus device interrupts, the system can identify which device is interrupting and call the correct device driver directly.

Following is a discussion of how the VMEbus is implemented in the SPARCserver^(TM) 600.

Physical Address Space

The physical address space layout of the SPARCserver 600 is shown in Table 2-3. A physical address on the SPARCserver 600 consists of 36 bits. The 36-bit physical address space is further broken down into 16 32-bit address spaces identified by PA(35:32).

Table 2-3

PA(35:32)	32-bit space	Usage
0x0	0x00000000 - 0xFFFFFFFF	Main Memory
0x1-0x9	Not used on SS600	Not used on SS600
0xA 0xB 0xC 0xD	0x00000000 - 0xFFFFFFFF 0x00000000 - 0xFFFFFFFF 0x00000000 - 0xFFFFFFFF 0x00000000 - 0xFFFFFFFF	VME User 16-bit VME User 32-bit VME Supervisor 16-bit VME Supervisor 32-bit
0xE	0x00000000 - 0xFFFFFFFF	SBus space
0xF	0x00000000 - 0xFFFFFFFF	Control space

Physical VME Addresses

The SPARCserver 600 has a full 32-bit VMEbus. Table 2-4 contains a listing of the VMEbus address types supported by the generic VMEbus.

Table 2-4

VMEbus Space Name	Address Size	Data Transfer Size	Physical Address Range
vme32d16	32 bits	16 bits	0x0 - 0xFFFFFFFF
vme24d16	24 bits	16 bits	0x0 - 0xFFFFFF
vme16d16	16 bits	16 bits	0x0 - 0xFFFF
vme32d32	32 bits	32 bits	0x0 - 0xFFFFFFFF
vme24d32	24 bits	32 bits	0x0 - 0xFFFFFF
vme16d32	16 bits	32 bits	0x0 - 0xFFFF

Not all of these address spaces are commonly used; nevertheless, they are all supported on the SPARCserver 600.

When a smaller VME space overlays a larger VME space, it steals memory from the larger space and is considered by the MMU to be part of the larger address space. There is no way to physically access VMEbus addresses above 0xFF000000 in 32-bit VMEbus space, or above 0xFFFF0000 in 24-bit VMEbus space.

Figure 2-5 illustrates the overlaying of VMEbus address spaces.

Figure 2-5

---

Caution - There are restrictions on device addressing. The lower ranges of the 32-bit and 24-bit VME space are reserved for DMA. For example, devices must not be present in the low megabyte of VME address space or the system will not boot. In addition, there may be devices on the bus with addresses that conflict. These can be determined by examining the hardware configuration files.

---

Hardware Configuration Files

Most VME devices require hardware configuration files to inform the system that the device hardware may be present. The configuration file must specify the device addresses on the VMEbus and any interrupt capabilities that the device has.

Configuration files for VMEbus devices should identify the parent bus driver implicitly using the class key word and specifying class "vme." This removes the dependency on the name of the particular bus driver involved since the driver may be named differently on different platforms. See driver.conf(4) and vme(4) for further details.

ISA Bus

Memory and I/O Space

Two address spaces are provided: memory address space and I/O address space. Depending on the device, registers may appear in one or both of these address spaces.

Table 2-5

ISA Space Name	Address Size	Data Transfer Size	Physical Address Range
Main Memory	24	16	0x0-0xffffff
I/O	--	8/16	0x0-0xfff

Registers can be mapped in memory address space and used by the driver as normal memory (see "Memory Space Access" on page 56).

Registers in I/O space are accessed through I/O port numbers using separate kernel routines. See "I/O Space Access" on page 57 for more information.

Hardware Configuration Files

ISA bus devices require hardware configuration files to inform the system that the hardware may be present. The configuration file must specify any device I/ O port addresses, any interrupt capabilities that the device may have, and any memory-mapped addresses it may occupy.

Configuration files for these devices should normally identify the parent bus driver as "isa". However, since the EISA bus is a super set of the ISA bus, all ISA devices can also be configured to run in an EISA bus slot. In this case, instead of implicitly specifying a particular parent in the configuration file, driver writers can use the class key word and specify the class as "sysbus." This removes the dependency on the name of a particular bus driver. See driver.conf(4) and isa(4) for further details.

EISA Bus

Memory and I/O Space

Two address spaces are provided: memory address space and I/O address space. Depending on the device, registers may appear in one or both of these address spaces.

Table 2-6

EISA Space Name	Address Size	Data Transfer Size	Physical Address Range
Main Memory	32	32	0x0-0xffffffff
I/O	--	8/16/32	0x0-0xffff

Registers can be mapped in memory address space and used by the driver as normal memory (see "Memory Space Access" on page 56).

Registers in I/O space are accessed through I/O port numbers using separate kernel routines. See "I/O Space Access" on page 57) for more information.

Hardware Configuration Files

EISA bus devices require hardware configuration files to inform the system that the hardware may be present. The configuration file must specify any device I/O port addresses, any interrupt capabilities that the device may have, and any memory-mapped addresses it may occupy.

Configuration files for these devices should normally identify the parent bus driver as "eisa". See driver.conf(4) and eisa(4) for further details.

MCA Bus

Memory and I/O Space

Two address spaces are provided: memory address space and I/O address space. Depending on the device, registers may appear in one or both of these address spaces.

Table 2-7

MCA Space Name	Address Size	Data Transfer Size	Physical Address Range
Main Memory	32	32	0x0-0xffffffff
I/O	--	8/16/32	0x0-0xfff

Registers can be mapped in memory address space and used by the driver as normal memory (see "Memory Mapping" on page 51).

Registers in I/O space are accessed through I/O port numbers using separate kernel routines. See "I/O Space Access" on page 57) for more information.

Hardware Configuration Files

MCA bus devices require hardware configuration files to inform the system that the hardware may be present. The configuration file must specify any device I/O port addresses, any interrupt capabilities that the device may have, and any memory-mapped addresses it may occupy.

Configuration files for these devices should normally identify the parent bus driver as "mca". See driver.conf(4) and mca(4) for further details.

Device Issues

Timing-Critical Sections

While most driver operations can be performed without synchronization and protection mechanisms beyond those provided by the locking primitives described in "Locking Primitives" on page 82, some devices require that a sequence of events happen in order without interruption. In conjunction with

the locking primitives, the function ddi_enter_critical(9F) asks the system to guarantee, to the best of its ability, that the current thread will neither be preempted nor interrupted. This stays in effect until a closing call to ddi_exit_critical(9F) is made. See ddi_enter_critical(9F) for details.

Delays

Many chips specify that they can be accessed only at specified intervals. For example, the Zilog Z8530 SCC has a "write recovery time" of 1.6 microseconds. This means that a delay must be enforced with drv_usecwait(9F) when writing characters with an 8530. In some instances, it is unclear what delays are needed; in such cases, they must be determined empirically.

Internal Sequencing Logic

Devices with internal sequencing logic map multiple internal registers to the same external address. There are various kinds of internal sequencing logic:

• The Intel 8251A and the Signetics 2651 alternate the same external register between two internal mode registers. Writing to the first internal register is accomplished by writing to the external register. This write, however, has the side effect of setting up the sequencing logic in the chip so that the next read/write operation refers to the second internal register.
• The NEC PD7201 PCC has multiple internal data registers. To write a byte into a particular register, two steps must be performed. The first step is to write into register zero the number of the register into which the following byte of data will go. The data is then written to the specified data register. The sequencing logic automatically sets up the chip so that the next byte sent will go into data register zero.
• The AMD 9513 timer has a data pointer register that points at the data register into which a data byte will go. When sending a byte to the data register, the pointer is incremented. The current value of the pointer register cannot be read.

Interrupt Issues

The following are some common interrupt-related issues:

• A controller interrupt does not necessarily indicate that both the controller and one of its slave devices are ready. For some controllers, an interrupt may indicate that either the controller is ready or one of its devices is ready, but not both.
• Not all devices power up with interrupts disabled and then start interrupting only when told to do so.
• Some devices do not provide a way to determine that the board has generated an interrupt.
• Not all interrupting boards shut off interrupts when told to do so or after a bus reset.

Byte Ordering

To achieve the goal of multiple platform, multiple Instruction Set Architecture portability, host/bus dependencies were removed from the drivers. The first dependency issue to be addressed was the endian-ness (or byte ordering) of the processor. For example, the x86 processor family is little endian while the SPARC architecture is big endian.

Bus architectures display the same endian-ness types as processors. The PCI local bus, for example, is little endian, the SBus is big endian, the ISA-bus is little endian and so on.

To maintain portability between processors and buses, DDI-compliant drivers must be endian neutral. Although drivers could conceivably manage their endian-ness by runtime checks or by preprocessor directives like #ifdef _LITTLE_ENDIAN or _BIG_ENDIAN statements in the source code, long term maintenance would be troublesome. The Solaris 2.5 DDI solution hides the endian-ness issues from the drivers as illustrated in Figure 2-6 on page 39. In some cases, the DDI framework performs the byte swapping using a software approach. In other cases, where byte swapping can be done by hardware (as in

MMU page-level swapping or by special machine instructions), the DDI framework will take advantage of the hardware features to improve performance.

Figure 2-6

Along with being endian-neutral, portable drivers must also be independent from data ordering of the processor. Under most circumstances, data must be transferred in the sequence instructed by the driver. However, sometimes data can be merged, batched or reordered to streamline the data transfer, as illustrated in Figure 3B (Data Ordering). For example, data merging may be applied to accelerate graphics display on frame buffers. Drivers have the option to advise the DDI environment to use other optimal data transfer mechanisms during the transfer.

Device Component Representations

Device component (or device-related) information may be represented with a name=value pair notation called a property.

For example, a reg property is used to represent device registers and onboard memory. The reg property is a software abstraction that describes device hardware registers; its value encodes the device register address location and size. Drivers use the reg property to access device registers.

An interrupt property is a software abstraction used to represent the device interrupt; its value encodes the device interrupt pin number.

The PROM on SPARC Machines

Some platforms have a PROM monitor that provides support for debugging a device without an operating system. This section describes how to use the PROM on SPARC machines to map device registers so that they can be accessed. Usually, the device can be exercised enough with PROM commands to determine if the device is working correctly.

The PROM has several purposes; it serves to:

• Bring the machine up from power on, or from a hard reset PROM reset command.
• Provide an interactive tool for examining and setting memory, device registers, and memory mappings.
• Boot SunOS or the kernel debugger kadb(1M).

Simply powering up the computer and attempting to use its PROM to examine device registers will likely fail. While the device may be correctly installed, those mappings are SunOS specific and do not become active until SunOS is booted. Upon power up, the PROM maps only essential system devices, such as the keyboard.

Examples in this section use a bwtwo (monochrome) frame buffer on a SPARCstation IPC. Using PROM commands to modify video memory on this frame buffer provides a visual indication that something is happening when PROM commands are executed.

Open Boot PROM 2.x

For complete documentation on the Open Boot PROM, see the Open Boot PROM Toolkit User's Guide and monitor(1M). The examples in this section refer to a Sun-4c; other architectures may require new commands to map memory, among other things.

The Open Boot PROM is currently used on Sun machines with an SBus. The Open Boot PROM uses an "ok" prompt rather than the ">" prompt used by SunMon. However, many Open Boot PROM machines present the old-style interface by default. The 'n' command switches an OBP from the old mode to the new mode.

Type b (boot), c (continue), or n (new command mode) >n Type help for more information ok

---

Note - If the PROM is in secure mode (the security-mode parameter is not set to none) the PROM password may be required (set in the security-password parameter).

---

The printenv command displays all parameters and their values.

Help

Help is available with the help command.

History

EMACS-style command-line history is available. Use Control-N (next) and Control-P (previous) to walk the history list.

Forth Commands

The Open Boot PROM uses the Forth programming language. This is a stack-based language; arguments must be pushed on the stack before running the desired command (called a word), and the result is left on the stack.

To place a number on the stack, type its value.

ok 57 ok 68

To add the two top values on the stack, use the + operator.

ok +

The result is left on the stack. The stack is shown with the .s word.

ok .s bf

The default base is hexadecimal. The hex and decimal words can be used to switch bases.

ok decimal ok .s 191

See the Forth User's Guide for more information.

Walking the PROMs Device Tree

The SunOS-like commands pwd, cd, and ls walk the PROM device tree to get to the device. The cd command must be used to establish a position in the tree before pwd will work. This example is from a SPARCstation IPC.

ok cd /

To see the devices attached to the current node in the tree, use ls.

ok ls ffec8760 options ffec5ce0 fd@1,f7200000 ffebab64 virtual-memory@0,0 ffeba958 memory@0,0 ffeb9084 sbus@1,f8000000 ffeb9020 auxiliary-io@1,f7400003 ffeb8fb8 interrupt-enable@1,f5000000 ffeb8f54 memory-error@1,f4000000 ffeb8ed0 counter-timer@1,f3000000 ffeb8e5c eeprom@1,f2000000 ffeb8de8 audio@1,f7201000 ffeb8cf8 zs@1,f0000000 ffeb8c54 zs@1,f1000000 ffeb8c04 openprom ffeb7b5c packages

The full node name can be used:

ok cd sbus@1,f8000000 ok ls ffecd450 bwtwo@3,0 ffecc2f0 le@0,c00000 ffec9b38 esp@0,800000 ffec9af4 dma@0,400000

Rather than using the full node name in the previous example, you could have used an abbreviation. The abbreviated command line entry looks like this:

ok cd sbus

The name is actually device@slot,offset (for SBus devices). The bwtwo device is in slot 3 and starts at offset 0. If an SBus device shows up in this tree, the device has been recognized by the PROM.

The.attributes command displays the PROM properties of a device. These can be examined to determine what properties the device exports (this is useful later to ensure that the driver is looking for the correct hardware properties). These are the same properties that can be retrieved with ddi_getprop(9F). See sbus(4) and "Properties" on page 69 for related information.

ok cd bwtwo ok .attributes monitor-sense 00 00 00 03 intr 00 00 00 07 00 00 00 00 reg 00 00 00 03 00 00 00 00 01 00 00 00 device_type display model SUNW,501-1561 ...

The reg property defines an array of register description structures, containing the following fields:

u_int   bustype;               /* cookie for related bus type*/
u_int   addr;                  /* address of reg relative to bus */
u_int   size;                  /* size of this register set */

For the bwtwo example, the address is 0.

Mapping the Device

To test the device, it must be mapped into memory. The PROM can then be used to verify proper operation of the device by using data-transfer commands to transfer bytes, words, and long words. If the device can be operated from the PROM, even in a limited way, the driver should also be able to operate the device.

To set up the device for initial testing perform the following three steps:

1. Determine the physical address of the SBus slot the device is in. Table 2-8 displays the physical addresses of various SBus slots on a SPARCstation 1 and SPARCstation 1+:

Table 2-8

SBus Slot Number	Physical Address Space
SBus slot #0	0 (internal slot)
SBus slot #1	0x2000000
SBus slot #2	0x4000000
SBus slot #3	0x6000000

In this example, the bwtwo device is located in slot 3. Consequently, the physical address space for the device is 0x6000000.

2. Determine the offset within the physical address space used by the device.

   The offset used is specific to the device. In the bwtwo example, the video memory happens to start at offset 0x800000 within the bwtwo space. As a result, the actual offset to be mapped is 0x6800000.

3. Use the map-sbus word to map the device in.

   The map-sbus word takes an offset and a size as arguments to map. Like the offset, the size of the byte transfer is specific to the device. In the bwtwo example, the size is set to 20000 bytes.

In the code example below, the offset and size values for the frame buffer are displayed as arguments to the map-sbus word. Notice that the virtual address to use is left on top of the stack. The stack is then shown using the .s word. It can be assigned a name with the constant operation.

ok 6800000 20000 map-sbus ok .s ffe7f000 ok constant fb

Reading and Writing

The PROM provides a variety of 8-bit, 16-bit, and 32-bit operations. In general, a c (character) prefix indicates an 8-bit (one byte) operation; a w (word) prefix indicates a 16-bit (two byte) operation; and an L (longword) prefix indicates a 32-bit (four byte) operation.

A suffix of ! is used to indicate a write operation. The write operation takes the first two items off the stack; the first item is the address, and the second item is the value.

ok 55 ffe8000 c!

A suffix of @ is used to indicate a read operation. The read operation takes one argument (the address) off the stack.

ok ffe80000 c@ ok .s 77

A suffix of ? is used to display the value, without affecting the stack.

ok ffe80000 c? 77

Be careful when trying to query the device. If the mappings are not set up correctly, trying to read or write could cause errors. There are special words provided to handle these cases. cprobe, wprobe, and lprobe, for example, read from the given address but return zero if the location does not respond, or nonzero if it does.

ok ffee0000 c@ Data Access Exception ok ffee0000 cprobe ok .s 0 ok ffe80000 cprobe ok .s 0 ffffffff

A region of memory can be shown with the dump word. This takes an address and a length, and displays the contents of the memory region in bytes.

In the following example the fill word is used to fill video memory with a pattern. fill takes the address, the number of bytes to fill, and the byte to use (there is also a wfill and an Lfill for words and longwords). This causes the bwtwo to display simple patterns based on the byte passed.

ok 6800000 20000 map-sbus ok constant fb ok fb 20000 ff fill ok fb 20000 0 fill ok fb 18000 55 fill ok fb 15000 3 fill ok fb 10000 5 fill ok fb 5000 f9 fill

Interrupts

Certain machine-specific interrupt levels are ignored when the Open Boot PROM controls the machine.