ChorusOS man pages section 9DRV: Driver Implementations

raven(9DRV)

NAME

raven- Motorola pci host bridge, pci bus driver

Synopsis

drv_f/src/pci/raven/raven.h           - RAVEN hardware related constants
drv_f/src/pci/raven/raven.c           - driver code
drv_f/src/pci/raven/ravenProp.h    - driver specific properties

FEATURES

DRV

DESCRIPTION

The raven bridge driver implements:

The common bus driver interface,
The pci bus driver interface.

The driver works on a Motorola raven pci host bridge and uses the PowerPC specific dki interface provided by the kernel.

Thus, the driver is designed to work only with PowerPC family products.

The raven driver does not provide the drv_probe() routine. In other words, the raven driver does not enumerate the pci bus, nor does it detect a raven device or create an associated device node. When the raven driver is used, associated device nodes should be created either statically by a boot program or dynamically by a separate pci bus enumerator driver.

The raven driver provides the drv_bind() routine. This routine examines the device node properties and thus, identifies a raven compatible device. The routine checks for the pci vendor and device identifiers matching a raven compatible device. If the check is positive, the drv_bind() routine binds the driver to the device node, attaching a PROP_DRIVER property to the device node. The property value specifies the raven driver name. The parent bus driver uses such a property to determine the name of drivers servicing the device. Via the PROP_DRIVER property, the driver gives its name to the parent bus driver, asking it to invoke the drv_init() routine on that device. The drv_bind() routine does nothing if the PROP_DRIVER property is already present in the device node. In other words, the drv_bind() routine will not override existing driver-to-device binding.

The driver does not implement drv_unload(). This means that the driver component cannot be unloaded even if it has been dynamically loaded at run time.

The driver supports the DKI_SYS_SHUTDOWN event specified by the common dki interface.

The Table below summarizes characteristics of the raven pci bus driver:

driver name:	"sun:powerpc-raven-(bus,pci)"
hardware:	Motorola RAVEN PCI host bridge
exported interface:	"bus,pci" (BUS_CLASS,PCI_CLASS)
exported interface version:	0 (PCI_VERSION_INITIAL)
imported parent interface:	"powerpc" (FDKI_CLASS)
minimal parent interface version:	0 (FDKI_VERSION_INITIAL)
device probing (auto-detection):	not supported
driver-to-device binding:	supported (on PCI dev/vend id basis)
driver unloading:	not supported
system (emergency) shut-down:	supported
normal device shut-down:	not supported
hot-plug (surprise) device removal:	not supported

The Table below lists device node properties used by the raven driver. Note that the column "m/o" specifies whether a given property is mandatory or optional. For optional properties, the column "default value" shows a default value which is used by the driver when a given property is not specified.

Name	Alias	Type	m/o	Default Value
"vend-id"	PCI_PROP_VEND_ID	PciPropVendId	m
"dev-id"	PCI_PROP_DEV_ID	PciPropDevId	m
"bus-num"	PCI_PROP_BUS_NUM	PciPropBusNum	m
"dev-num"	PCI_PROP_DEV_NUM	PciPropDevNum	m
"func-num"	PCI_PROP_FUNC_NUM	PciPropFuncNum	m
"io-regs"	PCI_PROP_IO_REGS	PciPropIoRegs	m
"mem-rgn"	PCI_PROP_MEM_RGN	PciPropMemRgn	m
"pci-map"	RAVEN_PROP_PCI_MAP	RavenPropPciMap	m
"ppc-map"	RAVEN_PROP_PPC_MAP	RavenPropPpcMap	m
"intr-map"	RAVEN_PROP_INTR_MAP	RavenPropIntrMap	m
"mpic-intr"	RAVEN_PROP_MPIC_INTR	RavenPropMpicIntr	o	see below
"ppc-timeout"	RAVEN_PROP_PPC_TIMEOUT	RavenPropMpicIntr	o	256 us

The PCI_PROP_VEND_ID property specifies the Motorola pci vendor identifier (must be 0x1057).

The PCI_PROP_DEV_ID property specifies the raven pci device identifier (must be 0x4801).

The PCI_PROP_BUS_NUM, PCI_PROP_DEV_NUM, and PCI_PROP_FUNC_NUM properties specify the configuration space address of the device. That is the pci bus, device and function numbers to which the device is connected (these should be all zero).

The PCI_PROP_IO_REGS property specifies the RAVEN's MPIC I/O registers range.

The PCI_PROP_MEM_RGN and RAVEN_PROP_PCI_MAP properties specify the raven configuration for pci bus slave map decoders. These properties are arrays which must be used to configure the 4 pci slave map decoders in the raven.

Each index (#0 to #3) of PCI_PROP_MEM_RGN defines a pci memory address range that will be translated into PowerPC bus cycles by the raven.

Each index (#0 to #3) of RAVEN_PROP_PCI_MAP defines:

The PowerPC bus address into which the associated pci region start address must be translated.
The attributes to be set in the PSATTx RAVEN register for this pci slave map decoder.

The RAVEN_PROP_PPC_MAP property specifies the raven configuration for PowerPC bus slave map decoders. This property is an array which must be used to configure the 4 PowerPC slave map decoders in the raven.

Each index from #0 to #3 defines a PowerPC bus address range that will be translated into pci bus cycles by the raven, with the following elements:

The PowerPC bus range is defined by its start address and size.
The pci bus address into which the PowerPC start address must be translated.
The attributes to be set in the MSATTx RAVEN register for this PowerPC slave map decoder.

The index 5# defines the location of the RAVEN's MPC registers from the PowerPC bus (only the PowerPC bus range is used) (should be at 0xFEFE0000 or 0xFEFF0000 with a size of 0x80).

The RAVEN_PROP_INTR_MAP property specifies, for each pci device number, a mapping of pci interrupt pins (INTA#, INTB#, INTC#, INTD#) into a RAVEN MPIC interrupt line (ranging from 0# to 25#). This property allows the raven to take into account the various pci interrupt routings for different platforms.

The RAVEN_PROP_MPIC_INTR property specifies the configuration for each interrupt source of the raven MPIC. For each MPIC interrupt source, this property indicates:

The type of the interrupt (low/high level, or positive/negative edge) .

Note that this field is used only for external interrupt sources.

The default value is OPIC_INTR_LOW_LEVEL.
The relative priority of the interrupt ranging from 0 (disabled) to 15 (highest).

An interrupt can be interrupted only by an interrupt of higher priority.

The default value is 1.

The RAVEN_PROP_PPC_TIMEOUT property specifies the configuration of the raven PowerPC bus timeout value to be set in the raven GCSR register.

The default value is 256 microseconds.

RESTRICTIONS

The current version of the raven driver does not support dynamic assignment of PCI bus resources.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving