aboutsummaryrefslogtreecommitdiff
path: root/xorg-server/hw/xfree86/doc/devel
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2009-09-15 10:39:59 +0000
committermarha <marha@users.sourceforge.net>2009-09-15 10:39:59 +0000
commita233ed27754bb0d373d63569d9a28aeb8fee5b82 (patch)
tree2732a9434bbc102653dc22df9887d94e19570836 /xorg-server/hw/xfree86/doc/devel
parenta915739887477b28d924ecc8417ee107d125bd6c (diff)
downloadvcxsrv-a233ed27754bb0d373d63569d9a28aeb8fee5b82.tar.gz
vcxsrv-a233ed27754bb0d373d63569d9a28aeb8fee5b82.tar.bz2
vcxsrv-a233ed27754bb0d373d63569d9a28aeb8fee5b82.zip
Checked in xorg-server-1.6.99.901
Diffstat (limited to 'xorg-server/hw/xfree86/doc/devel')
-rw-r--r--xorg-server/hw/xfree86/doc/devel/Domain.note159
-rw-r--r--xorg-server/hw/xfree86/doc/devel/Makefile.in9
-rw-r--r--xorg-server/hw/xfree86/doc/devel/RAC.Notes696
3 files changed, 8 insertions, 856 deletions
diff --git a/xorg-server/hw/xfree86/doc/devel/Domain.note b/xorg-server/hw/xfree86/doc/devel/Domain.note
deleted file mode 100644
index ce0812b22..000000000
--- a/xorg-server/hw/xfree86/doc/devel/Domain.note
+++ /dev/null
@@ -1,159 +0,0 @@
-The purpose of the changes described here is to implement a more general
-framework for multi-head on systems with more than one host-to-PCI bridge.
-The changes also implement a basic port of XFree86 to SPARC Solaris.
-
-These changes are derived from David S. Miller's submission #4653 to the
-patch list. David Andrew of Sun Microsystems was also kind enough to
-arrange for a hardware loan for development of these changes.
-
-These changes are known to work on several SPARC SunOS and UltraSPARC
-Linux configurations. Linux kernel work is in progress to port these
-changes to Linux/PowerPC.
-
-Several loose ends still need to be addressed before these changes can be
-considered stable. The bulk of this note is devoted to enumerating what
-remains to be done, along with other notes, broken down into various broad
-categories.
-
-SPARC SunOS (aka Solaris)
--------------------------
-- An overview of this XFree86 port is available in README.Solaris.
-- The keyboard map code in hw/xfree86/os-support/sunos/sun_kbdEv.c needs
- to be extended to handle more than only the sun5 keyboard I targeted it
- for. Even for the sun5, the map is incomplete as several keys are not
- mapped. What is there is just barely usable.
-- On exit, the server will zero out /dev/fb, but that might not be the
- right thing to do for all primary adapters. This does however
- appear to emulate the behaviour of Sun's commercial servers. It also
- eliminates the need for output drivers to save and restore video memory
- contents. (They still need to save/restore the mode timing however.)
- This also chimes into a long-standing XFree86 policy to not save/restore
- video memory contents if the mode on entry is found to be non-VGA, a
- policy several existing drivers comply with.
-- The SBUS drivers (sunbw2, suncg14, suncg3, suncg6, sunffb, sunleo and
- suntcx), the common layer's SBUS code and the fbdev driver have all
- only been compile tested. There are likely to be Linux'isms within
- them that remain to be dealt with.
-- It still needs to be verified whether or not this work adversely
- affected support for ix86 Solaris.
-
-UltraSPARC Linux
-----------------
-- Although this code can be compiled using any Linux/SPARC64 kernel, it
- can only run successfully using 2.4.12 or later.
-- I haven't had time to sufficiently dig into XKB to properly configure it
- for sun5 keyboards. Given XFree86 on Linux/SPARC has been around for a
- while, it's likely someone has already done this, and I'd appreciate
- receiving a copy of a working XF86Config input section.
-
-PowerPC Linux
--------------
-- As mentioned above, kernel work is in progress to port this PCI scheme
- to Linux/PowerPC.
-- Aside from kernel work, the inX() and outX() definitions in compiler.h
- will need to be changed to do something akin to their SPARC definitions,
- i.e. consider their port argument to be a virtual address.
-
-Other Linux ports to multi-domain architectures
------------------------------------------------
-- Comments in os-support/bus/linuxPci.c document the kernel interface
- required to port these changes. In short, Linux ports, such as Alpha
- and mips, should follow SPARC and PowerPC's lead in providing support to
- mmap() PCI devices through their /proc/bus/pci pseudo-files and to treat
- such requests for host bridges as requests to mmap() space provided by
- these bridges.
-
-Other OS's
-----------
-- In the right hands, either linuxPci.c or sparcPci.c can be used as a
- guide for what would need to be done to port this scheme to other OS's.
- Perhaps the largest difference between the two (in terms of interface to
- the common layer) is that the SunOS port includes internally generated
- domain numbers in PCITAG's, whereas the Linux port doesn't need to. The
- remainder of the PCI code (which is OS-independent) can handle either
- scheme.
-- Required entry points are xf86GetPciDomain(), xf86MapDomainMemory(),
- xf86MapDomainIO() and xf86ReadDomainMemory(). Replacements for
- xf86BusAccWindowsFromOS(), xf86PciBusAccWindowsFromOS() and
- xf86AccResFromOS() might also be required.
-- Development of these changes has detected the fact that the XFree86 port
- to the PowerMax OS is broken, and has been for some time, i.e. since
- shortly after its introduction, back in the 3.9* days.
-
-SPARC PCI (OS-independent)
---------------------------
-- The "Simba" PCI-to-PCI bridge used in SPARC's does not implement VGA
- routing, as defined in the PCI specs. Fortunately, OpenPROM seems to
- always route VGA resources to the bus with PCI connectors, but this also
- causes the common layer to not mark any PCI adapter as primary.
-
-Multiple PCI domains (architecture- and OS-independent)
--------------------------------------------------------
-- This implementation assumes every host-to-PCI bridge provides access to
- a separate PCI domain. Each such domain provides three different
- "address" spaces: PCI configuration, I/O and memory. The
- implementation can also deal with situations where more than one PCI
- domain share (different subsets of) the same PCI configuration space. I
- have unconfirmed information that suggests it might be necessary to also
- allow the sharing of PCI memory spaces.
-- This implementation also assumes the CPU's physical address space
- includes the entirety of each domain's I/O and memory spaces. I know
- this'll need to be changed to deal with the so-called UniNorth bridge,
- found on PowerPC's, which allows access to only a subset of the memory
- space behind it.
-- Ideally, the common layer should mark as primary up to one PCI adapter
- per domain. This has yet to be done.
-- Something needs to be done about PCI master aborts on primary buses.
- For details on this, see my long-winded diatribe in sparcPci.c, and
- related comments in linuxPci.c. Suffice it to say here that I see the
- eventual implementation of host bridge drivers within XFree86 as
- unavoidable at this point.
-- DGA is broken on multi-domain platforms. The information passed to the
- client to locate the framebuffer still needs to be revised. The best way
- to deal with this is to change all drivers' OpenFramebuffer() function to
- call a common layer routine to set the device name and displacements to be
- returned to the DGA client.
-
-Output drivers
---------------
-Most drivers currently used on ix86 need(ed) source code changes.
-- Calls to xf86ReadBIOS() and xf86MapVidMem() were replaced with calls to
- xf86ReadDomainMemory() and xf86MapDomainMemory() respectively. Except
- for the "ati" and "atimisc" modules, this has already been done.
-- All ix86-style I/O port numbers need to be declared as an IOADDRESS, a
- type defined in xf86Pci.h as "unsigned long". Such port numbers also
- need to be offset by a displacement which is also defined as an
- IOADDRESS. Before a driver's PreInit() is called, the common layer
- makes this displacement available in ScrnInfoRec.domainIOBase. For
- single-domain architectures, such as ix86, domainIOBase will always be
- zero. Current use of vgaHWRec.PIOOffset has also been adjusted
- accordingly. Some drivers have been changed to keep a copy of this
- displacement in their private structure. Internally, an IOADDRESS is
- actually a pointer that has been recasted to an unsigned long, but the
- common layer "hides" this fact from the driver ABI, which means that I/O
- port numbers, as seen by drivers, remain as integers rather than
- addresses. Aside from the ati and atimisc modules, s3, sis and tseng
- are the only modules left whose I/O still needs to be converted (I've
- temporarily run out of steam).
-- Note that these conversions are not necessarily sufficient to produce
- drivers that will work on any given multi-domain architecture. A driver
- that, for example, had endianness problems, still does. But, at least,
- these conversions, along with the supporting common layer changes, make
- PCI drivers more widely amenable to porting.
-- rdinx(), wrinx(), modinx(), testrg(), testinx() and testinx2() are not
- given enough information to allow for the relocation of their I/O. They
- are consequently being deleted. The apm and ark drivers, the only
- remaining callers of the first three, have been changed to use local
- definitions instead. The last three (test*()) were already unused.
-- As a temporary measure, these changes completely disable ISA-style
- probing on SPARC's and PowerPC's. This means that driver calls to
- xf86MatchIsaInstances(), while still valid, will always return detection
- failure on SPARC's and PowerPC's. This will be dealt with when a more
- general master abort handling scheme is implemented.
-- I need to make a decision about the master abort issues mentionned above
- before I can convert the "ati" and "atimisc" modules. Consequently,
- these modules still need to be compiled with -DAVOID_CPIO on
- multi-domain architectures, and support for Mach64 variants as
- non-primary heads is not yet available.
-
-$XFree86$
diff --git a/xorg-server/hw/xfree86/doc/devel/Makefile.in b/xorg-server/hw/xfree86/doc/devel/Makefile.in
index 390803a89..0071531af 100644
--- a/xorg-server/hw/xfree86/doc/devel/Makefile.in
+++ b/xorg-server/hw/xfree86/doc/devel/Makefile.in
@@ -57,6 +57,12 @@ CONFIG_HEADER = $(top_builddir)/include/do-not-use-config.h \
$(top_builddir)/include/version-config.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
+AM_V_GEN = $(am__v_GEN_$(V))
+am__v_GEN_ = $(am__v_GEN_$(AM_DEFAULT_VERBOSITY))
+am__v_GEN_0 = @echo " GEN " $@;
+AM_V_at = $(am__v_at_$(V))
+am__v_at_ = $(am__v_at_$(AM_DEFAULT_VERBOSITY))
+am__v_at_0 = @
SOURCES =
DIST_SOURCES =
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
@@ -65,9 +71,9 @@ ADMIN_MAN_DIR = @ADMIN_MAN_DIR@
ADMIN_MAN_SUFFIX = @ADMIN_MAN_SUFFIX@
ALLOCA = @ALLOCA@
AMTAR = @AMTAR@
+AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
AM_MAKEFLAGS = @AM_MAKEFLAGS@
APPLE_APPLICATIONS_DIR = @APPLE_APPLICATIONS_DIR@
-APPLE_APPLICATION_ID = @APPLE_APPLICATION_ID@
APPLE_APPLICATION_NAME = @APPLE_APPLICATION_NAME@
APP_MAN_DIR = @APP_MAN_DIR@
APP_MAN_SUFFIX = @APP_MAN_SUFFIX@
@@ -156,6 +162,7 @@ KDRIVE_LIBS = @KDRIVE_LIBS@
KDRIVE_LOCAL_LIBS = @KDRIVE_LOCAL_LIBS@
KDRIVE_PURE_INCS = @KDRIVE_PURE_INCS@
KDRIVE_PURE_LIBS = @KDRIVE_PURE_LIBS@
+LAUNCHD_ID_PREFIX = @LAUNCHD_ID_PREFIX@
LD = @LD@
LDFLAGS = @LDFLAGS@
LD_EXPORT_SYMBOLS_FLAG = @LD_EXPORT_SYMBOLS_FLAG@
diff --git a/xorg-server/hw/xfree86/doc/devel/RAC.Notes b/xorg-server/hw/xfree86/doc/devel/RAC.Notes
deleted file mode 100644
index 0aec9d795..000000000
--- a/xorg-server/hw/xfree86/doc/devel/RAC.Notes
+++ /dev/null
@@ -1,696 +0,0 @@
-I. Abstract
-===========
-
-Graphics devices are accessed thru ranges in I/O or memory space. While
-most modern graphics devices allow relocation of such ranges many of
-them still require the use of well established interfaces such as VGA
-memory and IO ranges or 8514/A IO ranges. Up to version 3.3 of
-XFree86 only a single graphics device could be driven. Therfore there
-was no need to address the issue of sharing such memory or I/O ranges
-among several devices. Starting with version 4.0 XFree86 is capable of
-driving more than one graphics interface in a multi-head environment.
-Therefore a mechanism needed to be designed which was capable of
-controlling the sharing the access to memory and I/O ranges. In this
-document we describe to use of the RAC (Resource Access Control)
-system in the XFree86 server which provides the service of controlling
-access to interface resources.
-
-II. Introduction
-================
-
-Terms and definitions:
-
-II.1. Bus
----------
-
-'Bus' is ambiguous as it is used for different things: It may refer to
-physical incompatible extension connectors in a computer system. The
-RAC system knows two such systems: The ISA bus and the PCI bus. (On
-the software level EISA, MC and VL buses are currently treated like
-ISA buses). 'Bus' may always refer to logically different entities on
-a single bus system which are connected via bridges. A PCI system may
-have several distinct PCI buses connecting each other by PCI-PCI
-bridges or to the host CPU by HOST-PCI bridges.
-
-Systems that host more than one bus system link these together using
-bridges. Bridges are a concern to RAC as they might block or pass
-specific resources. PCI-PCI bridges may be set up to pass VGA
-resources to the secondary bus. PCI-ISA buses pass any resources not
-decoded on the primary PCI bus to the ISA bus. This way VGA resources
-(although exclusive on the ISA bus) can be shared by ISA and PCI
-cards. Currently HOST-PCI bridges are not yet handled by RACY as they
-require specific drivers.
-
-II.2. Entity
-------------
-
-The smallest independently addressable unit on a system bus is
-referred to as an entity. So far we know ISA and PCI entities. PCI
-entities can be located on the PCI bus by an unique ID consisting of
-the bus, card and function number.
-
-II.3. Resource
---------------
-
- 'Resource' refers to a range of memory or I/O addresses an entity
-can decode.
-
-If a device is capable of disabling this decoding the resource is
-called sharable. For PCI devices a generic method is provided to
-control resource decoding. Other devices will have to provide a device
-specific function to control decoding.
-
-If the entity is capable of decoding this range at a different
-location this resource is considered relocatable. Resource which start
-at a specific address and occupy a single continuous range are called
-block resources.
-
-Alternatively resource addresses can be decoded in a way that they
-satisfy the condition:
-
- address & mask == base
-
-with base & mask == base. Resources addressed in such a way are
-considered sparse resources.
-
-
-II.4. Server States
-------------------
-
-The resource access control system knows two server states: the SETUP
-and the OPERATING state. The setup state is entered whenever a mode
-change takes place or the server exits or does VT switching. During
-this state any entity resource is under resource access control.
-During OPERATING state only those entities are controlled which
-actually have shared resources that conflict with others. The
-determination which entity is to be placed under RAC during OPERATING
-state takes place after ScreenInit() during the first server
-generation. This doesn't apply if only one screen is active: in this
-case no RAC is needed and the screen is simply left enabled while the
-server is active.
-
-
-III. Theory of operation
-========================
-
-III.1. General
---------------
-
-The common level 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.
-
- The user should provide a device section in XF86Config for each
-graphics device installed in his system. Each such entity which is
-never to be used as X display device might be marked as inactive by
-adding the keyword "Inactive" to the device section.
-
-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:
-
-a. 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).
-
-b. A resource marked 'disabled' during OPERATING state will be ignored
- entirely.
-
-c. 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.
-
-d. 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:
-
-a. It can relay 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.
-
-b. 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.
-
-c. 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.
-
-III.3. Resource Types
----------------------
-
-Resource have certain properties. When registering resources each
-range is accompanied by a flag consisting of the or'ed flags of the
-different properties the resource has. Each resource range may be
-classified according to
-
-- its physical properties ie. 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 desirable 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/sf86Resources.h.
-
-IV. Available Functions
-=======================
-
-The functions provided for resource management will be listed in order
-of use in the driver.
-
-IV.1. Probe phase
------------------
-
-In this stage 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:
-
- int xf86MatchPciInstances(const char *driverName, int vendorID,
- SymTabPtr chipsets, PciChipsets *PCIchipsets,
- GDevPtr *devList, int numDevs, DriverPtr drvp,
- int **foundEntities);
-
- int xf86MatchIsaInstances(const char *driverName, SymTabPtr chipsets,
- IsaChipsets *ISAchipsets, DriverPtr drvp,
- FindIsaDevProc FindIsaDevice, GDevPtr *devList,
- int numDevs, int **foundEntities);
-
-Both functions return the number of matched entities and their indices
-in foundEntities list.
-
-They make use of several sub functions which are also available on the
-driver level:
-
- Bool xf86ComparePciBusString(const char *busID, int bus,
- int device, int func);
-
-and
-
- Bool xf86ParseIsaBusString(const char *busID);
-
-are called to interpret the busID in the device section. The functions:
-
- int xf86ClaimPciSlot(int bus, int device, int func, DriverPtr drvp,
- int chipset, GDevPtr dev, Bool active);
-
- int xf86ClaimIsaSlot(DriverPtr drvp, int chipset, GDevPtr dev, Bool
- active);
-
-are used to allocate the entities and initialize their data
-structures. Both functions return the index of the newly allocated
-entity record or (-1) should the function fail. Before probing an ISA
-card
-
- Bool xf86IsPrimaryIsa();
-
-gets called to determine if the primary card was not detected on the
-PCI bus.
-
-Two helper functions are provided to aid configuring entities:
-
- Bool xf86ConfigActivePciEntity(ScrnInfoPtr pScrn, int entityIndex,
- PciChipsets *p_chip, resList res,
- EntityProc init, EntityProc enter,
- EntityProc leave, pointer private);
- Bool xf86ConfigActiveIsaEntity(ScrnInfoPtr pScrn, int entityIndex,
- IsaChipsets *i_chip, resList res,
- EntityProc init, EntityProc enter,
- EntityProc leave, pointer private);
-
-They are used to register the init/enter/leave functions described
-above as well as the non-relocatable resources. Generally 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. The init/enter/leave functions have to be of type
-
- typedef void (*EntityProc)(int entityIndex,pointer private);
-
-They are passed the entity index and a pointer to a private scratch
-area. This are can be set up during Probe() and its address can be
-passed to xf86ConfigActiveIsaEntity() xf86ConfigActivePciEntity() as
-the last argument.
-
-These helper functions use:
-
- void xf86ClaimFixedResources(resList list, int entityIndex);
-
- To register 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.
-
- Bool xf86SetEntityFuncs(int entityIndex, EntityProc init,
- EntityProc enter, EntityProc leave, pointer);
-
- This function registers the init/enter/leave() functions along with
- the pointer to their private area to the entity.
-
- void xf86AddEntityToScreen(ScrnInfoPtr pScrn, int entityIndex);
-
- adds the entity to the screen.
-
-These functions are also available on the driver level. A detailed
-Probe() function is listed below. For most drivers this can be used
-with little change.
-
-Please note that VGA resources have to be claimed in Probe()
-phase. Otherwise they are not routed to the bus.
-
-IV.2. PreInit() phase
----------------------
-
-During this phase the remaining resource should be registered.
-PreInit() should call
-
- EntityInfoPtr xf86GetEntityInfo(int entityIndex);
-
-To obtain a pointer to an EntityInfoRec for each entity it is able to
-drive and check if any resource are listed in 'resources'. These have
-been rejected in the post-Probe() phase. The driver should decide if
-it can continue without using these or if it should fail. The pointer
-to the EntityInfoRec should be freed if not needed any more.
-
-Several functions are provided to simplify resource registration:
-
- Bool xf86IsEntityPrimary(int entityIndex);
-
-is used to determine if the entity is the display device that is used
-during boot-up and text mode.
-
- Bool xf86IsScreenPrimary(int scrnIndex);
-
-finds out if the primary entity is registered for the screen with
-specified index.
-
- pciVideoPtr xf86GetPciInfoForEntity(int entityIndex);
-
-returns a pointer to the pciVideoRec of the specified entity. If the
-entity is not a PCI device NULL is returned.
-
-The primary function for registration of resources is
-
- resPtr xf86RegisterResources(int entityIndex, resList list, int access);
-
-it 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 move
-the resource to different locations. In case of PCI bus entities this
-is done by passing the list of failed resources to
-
- resPtr xf86ReallocatePciResources(int entityIndex, resPtr pRes);
-
-this function returns a list of reallocated resource. This list needs
-to be passed to xf86RegisterResources() again to be registered with
-the broker.
-
-Two functions are provided to obtain a resource range of a given type:
-
- resRange xf86GetBlock(long type, memType size,
- memType window_start, memType window_end,
- memType align_mask, resPtr avoid);
- resRange xf86GetSparse(long type, unsigned long fixed_bits,
- unsigned long decode_mask, unsigned long address_mask,
- resPtr avoid);
-
-The first one 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 alignment mask. Optionally a list of resource
-ranges which should be avoided inside this window can be passed. On
-failure it will return a zero range of type 'ResEnd'.
-
-The latter function does the same for sparse resources. A spares range
-is determined by to parameters: the mask and the base value. An
-address satisfying
-
- mask & address == base
-
-belongs to the specific spares range. 'mask' and 'base' themselves
-have to satisfy:
-
- mask & base == base.
-
-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 hard coded 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.
-
-Certain 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:
-
- Bool xf86FixPciResource(int entityIndex, unsigned int prt, CARD32 alignment,
- long type);
-
-is used for that. The parameter prt contains the number of the PCI
-base register that needs to be modified. A value of 6 refers to the
-BIOS base register. The size is specified in the alignment
-register. Since PCI resources need to span an integral range of the
-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().
-
- Bool xf86CheckPciMemBase(pciVideoPtr pPci, unsigned long base);
-
-checks that the memory base value specified in base matches one of the
-PCI base address register values for the given PCI device.
-
-The driver may replace the generic access control functions for an
-entity by it's own ones.
-
- void xf86SetAccessFuncs(EntityInfoPtr pEnt, xf86SetAccessFuncPtr funcs,
- xf86SetAccessFuncPtr oldFuncs);
-
- with:
-
- typedef struct {
- xf86AccessPtr mem;
- xf86AccessPtr io;
- xf86AccessPtr io_mem;
- } xf86SetAccessFuncRec, *xf86SetAccessFuncPtr;
-
-is used for that. 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 records. 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 his 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 specific resource range is conflicting with another
-resource
-
- memType xf86ChkConflict(resRange *rgp, int entityIndex);
-
-may be called. If a non-zero value is returned a conflict is found.
-
- resPtr xf86SetOperatingState(resList list, int entityIndex, int mask);
-
-is used to set the state 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 during OPERATING state however
-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).
-
-Two functions are provided for special cases:
-
- void xf86RemoveEntityFromScreen(ScrnInfoPtr pScrn, int entityIndex);
-
-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);
-
-deallocates all resources of a given type registered for a certain
-entity from the resource broker list.
-
-IV.3. ScreenInit() phase
-------------------------
-
-Setting up the rac flags is all that remains to do in ScreenInit()
-phase (Note that these flags might also be set up in PreInit() phase).
-The ScrnInfoRec has separate flags for memory and PIO access:
-racIoFlags and racMemFlags. They specifies which graphics operations
-might require the use of resources which might be disabled for some
-reason. Note that even exclusive resources might be disabled if they
-are disabled along with shared resources. For example if a driver has
-registered the VGA PIO resources and lets the common level disable
-these by disabling PIO access in PCI config space (the standard way),
-exclusive PCI PIO ranges will also be disabled. Therefore the driver
-has to flag any operations requiring PCI PIO resources in racIoFlags.
-The avaliable flags are defined in rac/xf86RAC.h. Available 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)
- RAC_COLORMAP for colormap operations
- RAC_VIEWPORT for the call to RACAdjustFrame()
-
-The flags are or'ed.
-
-V. Appendix
-===========
-
-A. Sample Probe() Function
---------------------------
-
-static Bool
-XXXProbe(DriverPtr drv, int flags)
-{
- Bool foundScreen = FALSE;
- int numDevSections, numUsed;
- GDevPtr *devSections;
- int *usedChips;
- int i;
-
- /*
- * Find the config file Device sections that match this
- * driver, and return if there are none.
- */
- if ((numDevSections = xf86MatchDevice(CHIPS_DRIVER_NAME,
- &devSections)) <= 0) {
- return FALSE;
- }
- /* PCI BUS */
- /* test if PCI bus present */
- if (xf86GetPciVideoInfo() ) {
- /* match PCI instances with ones supported by the driver */
- numUsed = xf86MatchPciInstances(XXX_NAME, PCI_VENDOR_XXX,
- XXXChipsets, XXXPCIchipsets,
- devSections,numDevSections, drv,
- &usedChips);
- if (numUsed > 0) {
- for (i = 0; i < numUsed; i++) {
- /* Allocate a ScrnInfoRec */
- ScrnInfoPtr pScrn = xf86AllocateScreen(drv,0);
- pScrn->driverVersion = VERSION;
- pScrn->driverName = XXX_DRIVER_NAME;
- pScrn->name = XXX_NAME;
- pScrn->Probe = XXXProbe;
- pScrn->PreInit = XXXPreInit;
- pScrn->ScreenInit = XXXScreenInit;
- pScrn->SwitchMode = XXXSwitchMode;
- pScrn->AdjustFrame = XXXAdjustFrame;
- pScrn->EnterVT = XXXEnterVT;
- pScrn->LeaveVT = XXXLeaveVT;
- pScrn->FreeScreen = XXXFreeScreen;
- pScrn->ValidMode = XXXValidMode;
- foundScreen = TRUE;
- /* add screen to entity */
- xf86ConfigActivePciEntity(pScrn,usedChips[i],XXXPCIchipsets,
- NULL,NULL,NULL,NULL,NULL);
- }
- }
- }
-
- /* Isa Bus */
- numUsed = xf86MatchIsaInstances(XXX_NAME,XXXChipsets,XXXISAchipsets,
- drv,chipsFindIsaDevice,devSections,
- numDevSections,&usedChips);
- if(numUsed >= 0)
- for (i = 0; i < numUsed; i++) {
- ScrnInfoPtr pScrn = xf86AllocateScreen(drv,0);
-
- pScrn->driverVersion = VERSION;
- pScrn->driverName = XXX_DRIVER_NAME;
- pScrn->name = XXX_NAME;
- pScrn->Probe = XXXProbe;
- pScrn->PreInit = XXXPreInit;
- pScrn->ScreenInit = XXXScreenInit;
- pScrn->SwitchMode = XXXSwitchMode;
- pScrn->AdjustFrame = XXXAdjustFrame;
- pScrn->EnterVT = XXXEnterVT;
- pScrn->LeaveVT = XXXLeaveVT;
- pScrn->FreeScreen = XXXFreeScreen;
- pScrn->ValidMode = XXXValidMode;
- foundScreen = TRUE;
- xf86ConfigActiveIsaEntity(pScrn,usedChips[i],XXXISAchipsets,
- NULL,NULL,NULL,NULL,NULL);
- }
- xfree(devSections);
- return foundScreen;
-}
-
-B. Porting Issues
------------------
-
-Here are some hints on porting code developed for RAC 1 to RAC 2.
-
-1. a. Initialization of RAC is now entirely done on the common level.
- Therefore the call to xf86RACInit() can be removed.
-
- b. Also there is no need for the racSymbols list.
-
- c. LoadSubModule(..,rac) should be removed.
-
- d. racSymbols should be removed from LoaderRequestSymList(racSymbols,..)
-
-2. a. if the driver uses the predefined resource lists xf86Resources.h
- needs to be included.
-
- b. RES_VGA should be changed to RES_EXCLUSIVE_VGA
-
-3. The device list now belongs to the EntityInfoRec.
- Change pScrn->device to xxx->pEnt->device.
-
-4. Rewrite the Probe() function. The example given above should work
- as a guideline.
-
-5. Register all necessary resources in PreInit() by calling
- xf86RegisterResources().
-
-6. If applicable set the operating state of the registered resources
- by calling xf86SetOperatingState(). This should be done during
- PreInit(). If necessary it might still be done in ScreenInit()
-
-7. Set up the racIoFlags and racMemFlags.
-
-
- LocalWords: ISA