9. Keeping Track of Bus Resources

9.1. Theory of Operation

The XFree86 common layer has knowledge of generic access control mechanisms
for devices on certain bus systems (currently the PCI bus) as well as
of methods to enable or disable access to the buses itself. Furthermore
it can access information on resources decoded by these devices and if
necessary modify it.

When first starting the Xserver collects all this information, saves it
for restoration, checks it for consistency, and if necessary, corrects
it. Finally it disables all resources on a generic level prior to
calling any driver function.

When the Probe() function of each driver is called the
device sections are matched against the devices found in the system.
The driver may probe devices at this stage that cannot be identified by
using device independent methods. Access to all resources that can be
controlled in a device independent way is disabled. The
Probe() function should register all non-relocatable
resources at this stage. If a resource conflict is found between
exclusive resources the driver will fail immediately. Optionally the
driver might specify an EntityInit(),
EntityLeave() and EntityEnter() function.

EntityInit() can be used to disable any shared resources
that are not controlled by the generic access control functions. It is
called prior to the PreInit phase regardless if an entity is active or
not. When calling the EntityInit(),
EntityEnter() and EntityLeave() functions
the common level will disable access to all other entities on a generic
level. Since the common level has no knowledge of device specific
methods to disable access to resources it cannot be guaranteed that
certain resources are not decoded by any other entity until the
EntityInit() or EntityEnter() phase is
finished. Device drivers should therefore register all those resources
which they are going to disable. If these resources are never to be
used by any driver function they may be flagged ResInit
so that they can be removed from the resource list after processing all
EntityInit() functions. EntityEnter()
should disable decoding of all resources which are not registered as
exclusive and which are not handled by the generic access control in
the common level. The difference to EntityInit() is
that the latter one is only called once during lifetime of the server.
It can therefore be used to set up variables prior to disabling resources.
EntityLeave() should restore the original state when
exiting the server or switching to a different VT. It also needs to
disable device specific access functions if they need to be disabled on
server exit or VT switch. The default state is to enable them before
giving up the VT.

In PreInit() phase each driver should check if any
sharable resources it has registered during Probe() has
been denied and take appropriate action which could simply be to fail.
If it needs to access resources it has disabled during
EntitySetup() it can do so provided it has registered
these and will disable them before returning from
PreInit(). This also applies to all other driver
functions. Several functions are provided to request resource ranges,
register these, correct PCI config space and add replacements for the
generic access functions. Resources may be marked ``disabled'' or
``unused'' during OPERATING stage. Although these steps could also be
performed in ScreenInit(), this is not desirable.

Following PreInit() phase the common level determines
if resource access control is needed. This is the case if more than
one screen is used. If necessary the RAC wrapper module is loaded. In
ScreenInit() the drivers can decide which operations
need to be placed under RAC. Available are the frame buffer operations,
the pointer operations and the colormap operations. Any operation that
requires resources which might be disabled during OPERATING state should
be set to use RAC. This can be specified separately for memory and IO
resources.

When ScreenInit() phase is done the common level will
determine which shared resources are requested by more than one driver
and set the access functions accordingly. This is done following these
rules:

The sharable resources registered by each entity are compared. If
a resource is registered by more than one entity the entity will be
marked to need to share this resources type (IO or
MEM).

A resource marked ``disabled'' during OPERATING state will be ignored
entirely.

A resource marked ``unused'' will only conflicts with an overlapping
resource of an other entity if the second is actually in use during
OPERATING state.

If an ``unused'' resource was found to conflict however the entity
does not use any other resource of this type the entire resource type
will be disabled for that entity.

The driver has the choice among different ways to control access to
certain resources:

It can rely on the generic access functions. This is probably the
most common case. Here the driver only needs to register any resource
it is going to use.

It can replace the generic access functions by driver specific
ones. This will mostly be used in cases where no generic access
functions are available. In this case the driver has to make sure
these resources are disabled when entering the PreInit()
stage. Since the replacement functions are registered in
PreInit() the driver will have to enable these
resources itself if it needs to access them during this state. The
driver can specify if the replacement functions can control memory
and/or I/O resources separately.

The driver can enable resources itself when it needs them. Each
driver function enabling them needs to disable them before it will
return. This should be used if a resource which can be controlled
in a device dependent way is only required during SETUP state. This
way it can be marked ``unused'' during OPERATING state.

A resource which is decoded during OPERATING state however never accessed
by the driver should be marked unused.

Since access switching latencies are an issue during Xserver operation,
the common level attempts to minimize the number of entities that need
to be placed under RAC control. When a wrapped operation is called,
the EnableAccess() function is called before control is
passed on. EnableAccess() checks if a screen is under
access control. If not it just establishes bus routing and returns.
If the screen needs to be under access control,
EnableAccess() determines which resource types
(MEM, IO) are required. Then it tests
if this access is already established. If so it simply returns. If
not it disables the currently established access, fixes bus routing and
enables access to all entities registered for this screen.

Whenever a mode switch or a VT-switch is performed the common level will
return to SETUP state.

9.2. Resource Types

Resource have certain properties. When registering resources each range
is accompanied by a flag consisting of the ORed flags of the different
properties the resource has. Each resource range may be classified
according to

its physical properties i.e., if it addresses
memory (ResMem) or
I/O space (ResIo),

if it addresses a
block (ResBlock) or
sparse (ResSparse)
range,

its access properties.

There are two known access properties:

ResExclusive
for resources which may not be shared with any other device and

ResShared
for resources which can be disabled and therefore can be shared.

If it is necessary to test a resource against any type a generic access
type ResAny is provided. If this is set the resource
will conflict with any resource of a different entity intersecting its
range. Further it can be specified that a resource is decoded however
never used during any stage (ResUnused) or during
OPERATING state (ResUnusedOpr). A resource only visible
during the init functions (ie. EntityInit(),
EntityEnter() and EntityLeave() should
be registered with the flag ResInit. A resource that
might conflict with background resource ranges may be flagged with
ResBios. This might be useful when registering resources
ranges that were assigned by the system Bios.

Several predefined resource lists are available for VGA and 8514/A
resources in common/xf86Resources.h.

9.3. Available Functions

The functions provided for resource management are listed in their order
of use in the driver.

9.3.1. Probe Phase

In this phase each driver detects those resources it is able to drive,
creates an entity record for each of them, registers non-relocatable
resources and allocates screens and adds the resources to screens.

Two helper functions are provided for matching device sections in the
XF86Config file to the devices:

This function finds matches between PCI cards that a driver supports
and config file device sections. It is intended for use in the
ChipProbe() function of drivers for PCI cards.
Only probed PCI devices with a vendor ID matching
vendorID are considered. devList
and numDevs are typically those found from
calling xf86MatchDevice(), and represent the active
config file device sections relevant to the driver.
PCIchipsets is a table that provides a mapping
between the PCI device IDs, the driver's internal chipset tokens
and a list of fixed resources.

When a device section doesn't have a BusID entry it
can only match the primary video device. Secondary devices are
only matched with device sections that have a matching
BusID entry.

Once the preliminary matches have been found, a final match is
confirmed by checking if the chipset override, ChipID override or
probed PCI chipset type match one of those given in the
chipsets and PCIchipsets lists.
The PCIchipsets list includes a list of the PCI
device IDs supported by the driver. The list should be terminated
with an entry with PCI ID -1". The
chipsets list is a table mapping the driver's
internal chipset tokens to names, and should be terminated with
a NULL entry. Only those entries with a
corresponding entry in the PCIchipsets list are
considered. The order of precedence is: config file chipset,
config file ChipID, probed PCI device ID.

In cases where a driver handles PCI chipsets with more than one
vendor ID, it may set vendorID to
0, and OR each devID in the list with (the
vendor ID << 16).

Entity index numbers for confirmed matches are returned as an
array via foundEntities. The PCI information,
chipset token and device section for each match are found in the
EntityInfoRec referenced by the indices.

The function return value is the number of confirmed matches. A
return value of -1 indicates an internal error.
The returned foundEntities array should be freed
by the driver with xfree() when it is no longer
needed in cases where the return value is greater than zero.

This function finds matches between ISA cards that a driver supports
and config file device sections. It is intended for use in the
ChipProbe() function of drivers for ISA cards.
devList and numDevs are
typically those found from calling xf86MatchDevice(),
and represent the active config file device sections relevant to
the driver. ISAchipsets is a table that provides
a mapping between the driver's internal chipset tokens and the
resource classes. FindIsaDevice is a
driver-provided function that probes the hardware and returns the
chipset token corresponding to what was detected, and
-1 if nothing was detected.

If the config file device section contains a chipset entry, then
it is checked against the chipsets list. When
no chipset entry is present, the FindIsaDevice
function is called instead.

Entity index numbers for confirmed matches are returned as an
array via foundEntities. The chipset token and
device section for each match are found in the
EntityInfoRec referenced by the indices.

The function return value is the number of confirmed matches. A
return value of -1 indicates an internal error.
The returned foundEntities array should be freed
by the driver with xfree() when it is no longer
needed in cases where the return value is greater than zero.

These two helper functions make use of several core functions that are
available at the driver level:

Takes a BusID string, and if it is in the correct
format, returns the PCI bus, device,
func values that it indicates. The format of the
string is expected to be "PCI:bus:device:func" where each of `bus',
`device' and `func' are decimal integers. The ":func" part may
be omitted, and the func value assumed to be zero, but this isn't
encouraged. The "PCI" prefix may also be omitted. The prefix
"AGP" is currently equivalent to the "PCI" prefix. If the string
isn't a valid PCI BusID, the return value is FALSE.

This function is used to claim a PCI slot, allocate the associated
entity record and initialise their data structures. The return
value is the index of the newly allocated entity record, or
-1 if the claim fails. This function should always
succeed if xf86CheckPciSlot() returned
TRUE for the same PCI slot.

Bool xf86IsPrimaryPci(void)

This function returns TRUE if the primary card is
a PCI device, and FALSE otherwise.

These functions are used to register the non-relocatable resources
for an entity, and the optional entity-specific Init, Enter and
Leave functions. Usually the list of fixed resources is obtained
from the Isa/PciChipsets lists. However an additional list of
resources may be passed. Generally this is not required.
For active entities a ScrnInfoRec is allocated
if the pScrn argument is NULL.
The
return value is TRUE when successful. The init, enter, leave
functions are defined as follows:

typedef void (*EntityProc)(int entityIndex,
pointer private)

They are passed the entity index and a pointer to a private scratch
area. This can be set up during Probe() and
its address can be passed to
xf86ConfigIsaEntity() and
xf86ConfigPciEntity() as the last argument.

These two helper functions make use of several core functions that are
available at the driver level:

void xf86ClaimFixedResources(resList list, int entityIndex)

This function registers the non-relocatable resources which cannot
be disabled and which therefore would cause the server to fail
immediately if they were found to conflict. It also records
non-relocatable but sharable resources for processing after the
Probe() phase.

This function registers with an entity the init,
enter, leave functions along
with the pointer to their private area.

void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex)

This function associates the entity referenced by
entityIndex with the screen.

9.3.2. PreInit Phase

During this phase the remaining resources should be registered.
PreInit() should call xf86GetEntityInfo()
to obtain a pointer to an EntityInfoRec for each entity
it is able to drive and check if any resource are listed in its
resources field. If resources registered in the Probe
phase have been rejected in the post-Probe phase
(resources is non-NULL), then the driver should
decide if it can continue without using these or if it should fail.

EntityInfoPtr xf86GetEntityInfo(int entityIndex)

This function returns a pointer to the EntityInfoRec
referenced by entityIndex. The returned
EntityInfoRec should be freed with
xfree() when no longer needed.

Several functions are provided to simplify resource registration:

Bool xf86IsEntityPrimary(int entityIndex)

This function returns TRUE if the entity referenced
by entityIndex is the primary display device (i.e.,
the one initialised at boot time and used in text mode).

Bool xf86IsScreenPrimary(int scrnIndex)

This function returns TRUE if the primary entity
is registered with the screen referenced by
scrnIndex.

pciVideoPtr xf86GetPciInfoForEntity(int entityIndex)

This function returns a pointer to the pciVideoRec
for the specified entity. If the entity is not a PCI device,
NULL is returned.

This function tries to register the resources in
list. If list is NULL it tries
to determine the resources automatically. This only works for
entities that provide a generic way to read out the resource ranges
they decode. So far this is only the case for PCI devices. By
default the PCI resources are registered as shared
(ResShared) if the driver wants to set a different
access type it can do so by specifying the access flags in the
third argument. A value of 0 means to use the
default settings. If for any reason the resource broker is not
able to register some of the requested resources the function will
return a pointer to a list of the failed ones. In this case the
driver may be able to move the resource to different locations.
In case of PCI bus entities this is done by passing the list of
failed resources to xf86ReallocatePciResources().
When the registration succeeds, the return value is
NULL.

resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes)

This function takes a list of PCI resources that need to be
reallocated and returns NULL when all relocations are
successful.
xf86RegisterResources() should be called again to
register the relocated resources with the broker.
If the reallocation fails, a list of the resources that could not be
relocated is returned.

Two functions are provided to obtain a resource range of a given type:

This function tries to find a block range of size
size and type type in a window
bound by window_start and window_end
with the alignment specified in align_mask.
Optionally a list of resource ranges which should be avoided within
the window can be supplied. On failure a zero-length range of
type ResEnd will be returned.

This function is like the previous one, but attempts to find a
sparse range instead of a block range. Here three values have to
be specified: the address_mask which marks all
bits of the mask part of the address, the decode_mask
which masks out the bits which are hardcoded and are therefore
not available for relocation and the values of the fixed bits.
The function tries to find a base that satisfies the given condition.
If the function fails it will return a zero range of type
ResEnd. Optionally it might be passed a list of
resource ranges to avoid.

Some PCI devices are broken in the sense that they return invalid size
information for a certain resource. In this case the driver can supply
the correct size and make sure that the resource range allocated for
the card is large enough to hold the address range decoded by the card.
The function xf86FixPciResource() can be used to do this:

This function fixes a PCI resource allocation. The
prt parameter contains the number of the PCI base
register that needs to be fixed (0-5, and
6 for the BIOS base register). The size is
specified by the alignment. Since PCI resources need to span an
integral range of size 2^n, the alignment also
specifies the number of addresses that will be decoded. If the
driver specifies a type mask it can override the default type for
PCI resources which is ResShared. The resource
broker needs to know that to find a matching resource range. This
function should be called before calling
xf86RegisterResources(). The return value is
TRUE when the function succeeds.

Bool xf86CheckPciMemBase(pciVideoPtr pPci, memType base)

This function checks that the memory base address specified matches
one of the PCI base address register values for the given PCI
device. This is mostly used to check that an externally provided
base address (e.g., from a config file) matches an actual value
allocated to a device.

The driver may replace the generic access control functions for an entity.
This is done with the xf86SetAccessFuncs():

The driver can pass three functions: one for I/O access, one for
memory access and one for combined memory and I/O access. If the
memory access and combined access functions are identical the
common level assumes that the memory access cannot be controlled
independently of I/O access, if the I/O access function and the
combined access functions are the same it is assumed that I/O can
not be controlled independently. If memory and I/O have to be
controlled together all three values should be the same. If a
non NULL value is passed as third argument it is
interpreted as an address where to store the old access record.
If the third argument is NULL it will be assumed
that the generic access should be enabled before replacing the
access functions. Otherwise it will be disabled. The driver may
enable them itself using the returned values. It should do this
from its replacement access functions as the generic access may
be disabled by the common level on certain occasions. If replacement
functions are specified they must control all resources of the
specific type registered for the entity.

To find out if a specific resource range conflicts with another
resource the xf86ChkConflict() function may be used:

memType xf86ChkConflict(resRange *rgp, int entityIndex)

This function checks if the resource range rgp of
for the specified entity conflicts with with another resource.
If a conflict is found, the address of the start of the conflict
is returned. The return value is zero when there is no conflict.

The OPERATING state properties of previously registered fixed resources
can be set with the xf86SetOperatingState() function:

resPtr xf86SetOperatingState(resList list, int entityIndex,
int mask)

This function is used to set the status of a resource during
OPERATING state. list holds a list to which
mask is to be applied. The parameter
mask may have the value ResUnusedOpr
and ResDisableOpr. The first one should be used
if a resource isn't used by the driver during OPERATING state
although it is decoded by the device, while the latter one indicates
that the resource is not decoded during OPERATING state. Note
that the resource ranges have to match those specified during
registration. If a range has been specified starting at
A and ending at B and suppose
C us a value satisfying
A < C < B one may not
specify the resource range (A,B) by splitting it
into two ranges (A,C) and (C,B).

The following two functions are provided for special cases:

void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex)

This function may be used to remove an entity from a screen. This
only makes sense if a screen has more than one entity assigned or
the screen is to be deleted. No test is made if the screen has
any entities left.

void xf86DeallocateResourcesForEntity(int entityIndex, long type)

This function deallocates all resources of a given type registered
for a certain entity from the resource broker list.

9.3.3. ScreenInit Phase

All that is required in this phase is to setup the RAC flags. Note that
it is also permissible to set these flags up in the PreInit phase. The
RAC flags are held in the racIoFlags and racMemFlags fields of the
ScrnInfoRec for each screen. They specify which graphics operations
might require the use of shared resources. This can be specified
separately for memory and I/O resources. The available flags are defined
in rac/xf86RAC.h. They are:

RAC_FB

for framebuffer operations (including hw acceleration)

RAC_CURSOR

for Cursor operations
(??? I'm not sure if we need this for SW cursor it depends
on which level the sw cursor is drawn)