@DATABASE "PCI" @$VER: PCI.guide 1.11 (03.12.2025) @(C) THOR Software @SMARTWRAP @AUTHOR Thomas Richter @INDEX Index @NODE MAIN "PCI Guide" @{CODE} ____ ____ ____ ____ ____ / / / / / /| / / / / / / / / / /___ / | / / / / / / / / / / / | / / / / / /____/ /___/ /____ / |/ /____/ /____ / / / / / © 2024-2025 THOR - Software, Thomas Richter ____________________________________________________________________________ @{BODY} openpci.library Master Guide Guide Version 1.11 openpci Library Version 40.11 @{"The License : Legal restrictions " link Licence} @{"What is it : What is this all about, and what's the openpci.library? " link PCIOverview} @{"Compatibility: The compatibility guideline " link Compatibility} @{"Contents : What's all in this stuff in this archive " link Contents} @{"Installation : How to install the openpci.library and its tools " link Install} @{"FAQ : Frequently asked questions. Did you check these? " link FAQ} @{"Credits : People I want to thank " link Credits} @{"Glossary : What do all these technocratic words mean? " link PCITech} @{"History : What happened before " link History} ____________________________________________________________________________ Even though not based on or related to it, I want to thank Benjamin Vernoux for the original version of openpci, and Stéphane Guillard for porting this original version to AmigaOs 4. This version of the openpci.library is API compatible to Benjamin's original version, though is not based on its code, and also works differently than the original version. ____________________________________________________________________________ An additional note: The openpci.library is published as usual under my "Freeware Licence" because I think the Amiga deserves better software and I hope the library and the tools using this library will give you the power to write this software. It took over a year and endless hours of thinking, writing, debugging to obtain this result. I hope this effort is not wasted, neither for you nor for me. I would highly appreciate some feedback for that reason; in case you're using these tools in software development, or the library itself in your software, consider offering me a license of your program as I offered you all this for free. Thanks a lot, and happy programming, Thomas ____________________________________________________________________________ © THOR-Software Thomas Richter Rühmkorffstraße 10A 12209 Berlin Germany EMail: thomas.richter\@alumni.tu-berlin.de @ENDNODE @NODE Licence "The THOR-Software Licence" The THOR-Software Licence (v3, January 2nd 2021) This License applies to the computer programs known as "openpci.library", the "PCIInit" tool and "lspci". The "Program", below, refers to such program. The "Archive" refers to the package of distribution, as prepared by the author of the Program, Thomas Richter. Each licensee is addressed as "you". The Program and the data in the archive are freely distributable under the restrictions stated below, but are also Copyright (c) Thomas Richter. Distribution of the Program, the Archive and the data in the Archive by a commercial organization without written permission from the author to any third party is prohibited if any payment is made in connection with such distribution, whether directly (as in payment for a copy of the Program) or indirectly (as in payment for some service related to the Program, or payment for some product or service that includes a copy of the Program "without charge"; these are only examples, and not an exhaustive enumeration of prohibited activities). However, the following methods of distribution involving payment shall not in and of themselves be a violation of this restriction: (i) Distributing the Program on a physical data carrier (e.g. CD-ROM, DVD, USB-Stick, Disk...) provided that: a) the Archive is reproduced entirely and verbatim on such data carrier, including especially this license agreement; b) the data carrier is made available to the public for a nominal fee only, i.e. for a fee that covers the costs of the data carrier, and shipment of the data carrier; c) a data carrier with the Program installed is made available to the author for free except for shipment costs, and d) provided further that all information on said data carrier is redistributable for non-commercial purposes without charge. Redistribution of a modified version of the Archive, the Program or the contents of the Archive is prohibited in any way, by any organization, regardless whether commercial or non-commercial. Everything must be kept together, in original and unmodified form. Limitations. THE PROGRAM IS PROVIDED TO YOU "AS IS", WITHOUT WARRANTY. THERE IS NO WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE THE PROGRAM, THE ARCHIVE AND ALL DATA OF THIS ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS LICENCE BY USING OR REDISTRIBUTING THE PROGRAM. Thomas Richter @ENDNODE @NODE PCIOverview "What's the openpci.library?" While the Amiga uses the Zorro bus for extending an Amiga system with third party hardware, PC hardware from the 1990 and 2000s utilized the PCI bus, short for "Peripheral Component Interconnect" bus, to integrate such extensions into a PC system. Both bus systems share some commonalities, namely that such hardware expansions identify themselves to the system and can be used immediately without requiring its owner to set any hardware jumpers; Zorro and PCI are auto-configuring, and the host operating system provide mechanisms to reserve resources for them, and to allow drivers to identify the expansion hardware they interface to. Today, PCI has been supersedes by PCIe ("PCI express"), but only the physical interface layer has been changed, keeping the software protocol for hardware configuration and identification almost identical. As PCI is a very popular bus system, many hardware extensions interfacing to the host system through PCI have been developed, amongst them graphic cards, sound cards, network cards and many more; clearly, PCI is more modern than Zorro and has much broader support. @{B} In short: "PCI is for PC what Zorro is for Amiga". @{UB} It is therefore not unsurprising that several vendors started to offer @{"PCI bridges" link HostBridge} through which an Amiga system can be equipped with a PCI bus, and through which components designed for PC systems can be plugged into an Amiga. Unfortunately, even though the PCI bus is standardized, the way how these bridge cards integrate into the Amiga is not, and thus multiple unfortunately incompatible solutions have been designed over the years, each providing their own logic how to interface to PCI cards. Clearly, this did not turn out to much advantage; with many incompatible systems on the market, users were often stuck with closed undocumented interfaces and depend on the willingness of their vendors to release drivers for their proprietary PCI solution; this not only causes a vendor-lock-in problem where users are forced to use drivers for one particular PCI bridge vendor, users also depend on the willingness of updating and maintaining their drivers; it also lowers the willingness of developers creating drivers for PCI cards as each PCI bridge solution requires its own driver. To address this problem, Benjamin Vernoux started the openpci project with the goal of providing a stable and open (as in "documented") interface for PCI buses, hoping to provide common grounds for driver development. The way how his openpci.library works is that it acts as a translation layer between drivers and the underlying vendor specific bridge libraries such that (hopefully) drivers based on openpci would work through this interface with the vendor specific proprietary solutions. Unfortunately, development on openpci stopped, and such an interface can only provide the smallest common denominator of all proprietary interfaces as it depends by itself on proprietary drivers. Worse, if development of one of these proprietary interfaces stalls, Benjamin's version of openpci is stuck with their deficiencies. The version in this archive is a complete re-implementation of openpci and based on a different design philosophy: Instead of depending on proprietary drivers, it interfaces directly to third party hardware, entirely replacing vendor specific drivers. At the same time, it provides a super-set of services the original openpci.library offered, addressing some of its shortcomings. For Zorro devices, the Amiga "expansion.library" is responsible for configuring hardware expansions. For PCI, this is the role of "openpci". Or in short: @{B} What expansion is for Zorro is openpci for PCI. @{UB} @ENDNODE @NODE Compatibility "Compatibility Guidelines" The openpci.library and its tools are written in a very careful way, to ensure maximal compatibility. At the time of writing, the openpci.library supports the following hardware: @{B}G-Rex@{UB} is an extension board for Blizzard and Cyberstorm CPU boards manufactured by P5 and DCE. Versions for the Amiga 1200 and Amiga 4000 exist, but are, except for their form factor, identical. They can only be used with CPU boards of the same vendor. The CyberVisionPPC and BlizzardVisionPPC boards are essentially cut-down versions of the G-Rex board with a PCI bus connected to a single PCI based graphics chip, the Permedia2. The advantage of the G-Rex PCI bridge is that, due to its direct interface to the CPU board, @{"DMA" link DMAIntro} from PCI to CPU memory is possible. This does not hold for any other PCI bridge. Unfortunately, the G-Rex does not support @{"PCI to PCI bridge chips" link PCIBridge}. @{B}Prometheus@{UB} is a PCI bridge bus by Matay, connected by Zorro III to their Amiga 3000 or Amiga 4000 host. @{B}Firestorm@{UB} is based on the same hardware as the Prometheus PCI bridge, though with a firmware improved by Michael Böhmer. This firmware fixed some flaws of the original Prometheus board and also offers support for DMA and @{"PCI to PCI Bridge chip" link PCIBridge}. The Mediator bridges, and this board, along with its reincarnation as "Firebird" (see below) are the only PCI bridge that offers bridge support. @{B}Firebird@{UB} is a re-implementation of the Firestorm hardware by Hese. This board is functionally equivalent to the Firestorm design; both should work alike. @{B}Mediator@{UB} is a series of PCI bridges by Elbox, available both in variants for the Amiga 4000, then based on Zorro III, or multiple versions for the Amiga 1200. The Amiga 1200 versions are somewhat special as, due to restrictions of the Amiga 1200 bus system, only a 4MB or 8MB window for PCI extensions are possible. To allow a larger address window, the MMU can be used to emulate larger PCI address spaces. This emulation is through the @{"mmu.library" link MMULib} available in Aminet. Usage of the original interface hardware offered by Elbox is discouraged as it integrates badly into the system and does not play well with the MMU. Due to a hardware limitation, the A1200 Mediator bridge boards, except the A1200 TX, suffer from a @{"race condition" link MediatorGlitch} that, under some situations, creates a dead end access error. To allow identification of PCI resources, the openpci.library also creates @{"autoconf entries" link AutoConf} that can be used to identify them by standard system tools such as "ShowConfig" or other system monitors. @ENDNODE @NODE MediatorGlitch "Mediator A1200 Race Condition" @TOC Compatibility All Mediator boards offer the possibility to provide almost 4GB of PCI address space by providing a configurable access window into the PCI domain; this access window can be dynamically reprogrammed under control of the 68K MMU. Unfortunately, this technique of reprogramming an access window has a race condition that prevents its proper function for some members of the 68K processor family. The issue are here non-aligned accesses into PCI memory that cross a window boundary, e.g. a non-aligned long-word access. Such accesses will trigger a first access violation for the lower address, providing access to the lower window, and then restart the instruction. When the instruction is rerun, the instruction can complete the access to the lower window, but not to the higher window, causing another access fault. This will again trigger an access fault, causing to map the higher window in. If the instruction is re-run, it now only sees the upper part of the desired area, but the lower part is not accessible. Thus, rerunning the instruction again causes another access fault, and so on. In other words, non-aligned accesses that cross window bounds are not recoverable because Mediator hardware only offers a single window to PCI space. The MMU access fault handler detects this situation and instead of running into an endless loop of access errors, forwards the access fault to additional handlers, e.g. MuForce. If no such handler exists, the system runs into a non-recoverable software error. The only exception is the A1200TX Mediator which offers two windows instead of one, and thus can handle this situation. Thus, for the A4000 Mediator board, only a single fixed 512MB access window is offered; this window size should be large enough for most purposes, and the above race condition cannot appear. For the A1200 mediator boards, the access window is either 4MB or 8MB, and this is too small to be of practical value. Thus, if the @{"mmu.library" link MMULib} is available, dynamic window remapping is enabled by default, providing a large emulated access window for PCI devices. Unfortunately, all boards but the A1200TX Mediator only offer a single window and thus may cause a dead-end access error on non-aligned read or write operations that cross a window boundary. @ENDNODE @NODE DMAIntro "What is DMA, please?" @TOC PCITech DMA is short for "direct memory access". This is a mechanism for performing fast input/output operations, as reading data from a storage system like a hard-disk. In a "DMA" system, the CPU tells the controller chip which data it should read, and where the controller should put this data into memory. The CPU then just starts the transfer and leaves it to the controller chip to carry out the actual work. In the meantime, the CPU is free to perform other computations. Hence, DMA is usually faster, because it works in parallel to other operations, but it is not without problems. In principle, PCI devices may offer DMA services, bypassing the CPU and depositing data directly into host memory. However, most @{"PCI host bridges" link HostBridge} do not allow PCI devices (an extension sitting in a PCI slot) to transfer data directly to host memory. The only exception to this is are the G-Rex boards by P5 and DCE. Host bridges typically do allow access to memory on the PCI bus. Instead of DMA, a PCI device would then first transmit data into some memory sitting on the PCI bus, and the CPU would in a second step copy from that memory into the main memory. To support this process, the openpci.library manages so called @{"DMA Bounce Buffers" link BounceBuffers}. @ENDNODE @NODE BounceBuffers "What are DMA Bounce Buffers" Unfortunately, PCI devices typically cannot transfer data directly to or from memory connected to the CPU or on the Zorro bus. That is, @{"Direct Memory Access" link DMAIntro} is usually not available across a @{"PCI host bridge" link HostBridge}. Unfortunately, many PCI devices require DMA to buffer data they receive or process. For example, network cards typically deposit received network packets in memory, and audio cards play out samples from memory through DMA. Without memory reachable through DMA, such devices would not be able to operate. To mitigate this problem, the openpci.library allows drivers to allocate "PCI bounce buffers" taken from "some memory that happens to be available on the PCI bus". PCI devices then transfer data into such memory, available on the PCI bus. Once the transfer is complete, the CPU takes over and manually carries data from there to host memory, clearly a tedious and time consuming process. Drivers of PCI devices need to actively announce to the openpci.library that they offer services to allocate such bounce buffers. One known provider is the P96 graphics card software, though at least version 3.5.0 is required for this service. @ENDNODE @NODE PCIBridge "What is a PCI to PCI bridge?" @TOC PCITech A PCI to PCI bridge chip acts on a PCI bus as a PCI device, and forwards any access to its address space area to a second (or even multiple) PCI devices behind it, spawning a second PCI bus. It is as if you had a device in a Zorro slot that offers Zorro slots itself, and thus allows to you to enlarge the number of extensions you could plug into your system. PCI bridge chips are often integrated into hardware expansion cards itself, such as on cards that offer both a graphics card, a sound card and a TV receiver card in one single extensions. Such a multimedia card then contains an (albeit tiny) PCI bus by itself, and forwards all the accesses to the individual chips on this card through a PCI bridge chip on the PCI bus. A second application for PCI bridge chips is that these chips can also transmit data between the (now outdated) PCI bus and the currently active PCIe ("PCI express") bus, for which even more devices are available. Thus, a PCI to PCIe bridge would allow you to make PCIe expansions available to your Amiga. Unfortunately, PCI bridge chips require special configuration cycles to reach out for expansions behind them, and not all PCI bridge boards are able to generate such cycles. At the time of writing, only the Mediator bridges, the Firestorm and the Firebird boards support bridge chips. See also @{"Compatibility" link Compatibility}. PCI to PCI bridges and PCI to PCIe bridges should not be confused with the @{"PCI Host Bridge" link HostBridge} which is the hardware that integrates a PCI bus into the Amiga system. All Amiga PCI boards thus act as PCI host bridge. On modern PCs, such PCI host bridges are already integrated into the CPU, but on the Amiga, a separate bridge card is available. The @{"Compatibility" link Compatibility} section lists the supported bridge cards. @ENDNODE @NODE HostBridge "What is a PCI Host Bridge" @TOC PCITech The PCI host bridge, or also PCI bridge board, is the board that provides a PCI bus to the Amiga. That is, the G-Rex, Prometheus, Firestorm or Mediator boards are all @{B}host bridges@{UB}. They bridge between the host bus, typically Zorro, and the PCI bus, thus the name. @ENDNODE @NODE AutoConf "PCI AutoConf Entries" @TOC PCITech The openpci.library creates for each PCI resource an AutoConfig entry that allows system tools and system monitors to identify PCI devices. The @{B}original@{UB} AutoConf entries of the bridge board and its address space are intentionally @{B}removed@{UB} from the system to ensure that no third party software identifies and grabs them. The following autoconf IDs are created by openpci: @{CODE} Vendor Product Description -------------------------------------------------------------------- 1729 0 An A1200 Mediator bridge 1730 0 An A4000 Mediator bridge 1731 0 A Prometheus bridge (Firestorm or original) 1733 0 A G-Rex bridge (both A1200 and A4000) @{BODY} The product 0 always identifies the bridge resource itself, i.e. the registers that are used to configure the PCI bridge. All resources behind a PCI host bridge are identified by the same vendor code as the bridge, e.g. 1731 for the Prometheus bridge, but a product code that is larger than 0. In particular, the following product codes have been defined: @{CODE} Product Description ------------------------------------------------------------- 1 PCI configuration area 2 PCI memory area (typically video RAM) 3 PCI memory mapped registers 4 PCI I/O area 5 PCI expansion ROM (typically the VESA Bios) 6 PCI legacy I/O area (non-configured I/O) 7 PCI legacy VGA area @{BODY} Thus, for example, an AutoConfig entry of vendor 1731 and product 3 identifies memory mapped registers behind a Prometheus bridge. Unfortunately, the Autoconfig product and vendor ID are not able to carry information on the vendor and the device ID of the PCI device itself. This information is, however, available in @{B}er_SerialNumber@{UB} of the ConfigDev structure if the product code is between 2 and 5. @ENDNODE @NODE Contents "Contents of the Archive" The openpci.library comes not alone, additional tools are provided to integrate it into the Amiga. Here are the contents of the archive: @{CODE} @{B}openpci.readme@{UB} Latest news and changes made to the contents. @{B}Libs/openpci.library@{UB} This is the library what all text is about. Should be copied to the "LIBS:" directory on @{"installation" link Install}. @{B}Libs/mmu/PCIInit@{UB} This @{"tool" link PCIInit} should go into the "LIBS:mmu/" directory and should be run from "ENVARC:MMU-Configuration" to initialize the PCI hardware. It also speeds up the boot process. See also @{"Installation" link Install} and @{"mmu.library" link MMULib}. @{B}C/lspci@{UB} This is a tiny tool that lists all PCI hardware found in the system. If the @{"boards.library" link BoardsLib} is available, it also prints the names of the boards and their vendors. @{"lspci" link lspci} is also discussed in more detail. @{B}Sources/lspci.c@{UB} Source code of the lspci program, as example how to call the openpci.library. @{B}C/DMAMemTest@{UB} This is a tool that tests for the availability of memory for @{"DMA bounce buffers" link BounceBuffers} and diagnoses problems with them. You may want to run them if you have issues with devices on PCI bus that require DMA. @{B}Development/openpci.fd@{UB} A file defining the entry point of the openpci.library. This file is provided to software developers to interface to openpci. @{B}Development/openpci.doc@{UB} Autodocs for openpci.library. @{B}Include@{UB} A directory containing header files for C and assembler, also provided for developers. @{B}Helpers@{UB} Helper binaries for installation that are not needed for openpci and that can be safely deleted after installation. @{BODY} @{B}Where are the includes, autodocs and sources?@{UB} In the @{B}Include@{UB} and @{B}Sources@{UB} directories. They are currently tiny enough to allow distribution along with the user files. @ENDNODE @NODE PCIInit "The PCIInit Tool" @TOC Contents The PCIInit tool is a helper utility for @{"mmu.library" link MMULib} that loads and initializes the PCI bus before MMU tables are composed. It loads openpci.library, let it scan the PCI bus and reports the results to mmu.library such that only those regions are mapped by the MMU which contain PCI resources. As less MMU tables have to be built, this tool helps to speed up the boot process. PCIInit @{B}cannot be run from the command line@{UB}. Instead, the tool should be copied into the @{B}LIBS:mmu@{UB} directory, and should be called from @{"ENVARC:MMU-Configuration" link Configure}. It should appear close to the very end of this file. @ENDNODE @NODE lspci "The lspci Utility" @TOC Contents lspci is a tiny tool that lists all hardware found in the system. Without any further options, its output looks as follows: The first line indicates which type of bus systems have been found active in the system. In principle, more than a single bus could be present, in which case openpci serves all of them. For example, this line could read: @{CODE} G-Rex bus detected. @{BODY} in case a G-Rex PCI bridge was found. The chapter @{"Compatibility" link Compatibility} lists all PCI bridges the library supports. The following lines list the devices found on each bus. The information starts with the bus number, separated by a colon, followed by a device number, followed by a dot, followed by a function number. Behind that, the device class is printed, followed by the vendor and the product name - given the @{"boards.library" link BoardsLib} is installed. For example, the line: 1:02.0 VGA compatible controller: 3Dfx Interactive, Inc.: Voodoo 3 (rev 1) indicates that on bus number 1, a Voodoo 3 card has been found as device 2; If multiple buses exist, for example behind a @{"PCI to PCI bridge" link PCIBridge}, more than a single bus will be listed and the first digit can be different. Bus number 0 is reserved for the Zorro bus whose expansions are @{B}not@{UB} listed by this utility, for this use "ShowConfig" from the workbench. The "02" behind it indicates that a device on slot number 2 of the PCI host bridge has been found. How slots are enumerated depends on the bridge, they typically count from 0 up. However, for the G-Rex bus board in specific slot 0 is reserved for the CVisionPPC, and slot 1 and up are regular PCI slots. The "0" behind the dot indicates a device function on a board. A single PCI chip may implement multiple functions, for example a sound chip may implement one function for playing samples, another function to play MIDI notes, and a third function for a sound mixer. If a device implements more than one function, this digit increases. In this particular example, only a single function 0 is present. Functions count from 0 up. Following the device function enumerator the device class is found. The PCI standard defines multiple device classes such as display controllers, network chips, USB interface chips, network controllers and many more. This string identifies the device class, here a graphics card that implements a VGA compatible register set. In case no driver is available for a specific device, the operating system could use a fall-back driver based on the device class. For example, a VGA fallback driver, if one would exist, would at least be able to display a screen in 640x480 resolution, though without any hardware acceleration. Behind the device function follows the vendor name of the device. This vendor name is only printed if the @{"boards.library" link BoardsLib} is installed in the system, otherwise four hexadecimal digits identify the vendor. In this particular case, the PCI extension comes from "3Dfx", a now defunct vendor of 3D accelerated graphic cards. The device name follows the vendor name, and is again only printed in human readable form if the @{"boards.library" link BoardsLib} is installed. Otherwise, again only four hexadecimal digits are printed. In this particular case, it is a "Voodoo 3" graphics cards. The last entry on the line, in brackets, is the device revision if multiple revisions exist. Here, it is a revision 1 Voodoo 3. In case the keyword @{B}VERBOSE@{UB} is given on the command line, i.e. the command is "lspci verbose", additional information is printed. This information is only relevant for developers and usually not provided. It contains the addresses of the @{"BAR registers" link PCIBar}, the @{"Legacy IO region" link LegacyIO}, the @{"Host offset" link HostOffset} and the @{"Interrupt Line" link InterruptLine} occupied by the device. @ENDNODE @NODE PCITech "PCI Concepts" @TOC Main In this section, multiple concepts of the PCI bus are introduced for the interested reader: @{"PCI BAR registers place devices in the address space " link PCIBar} @{"The legacy IO region is a x86 legacy required by some VGA cards" link LegacyIO} @{"The legacy VGA window " link LegacyVGA} @{"The host offset translates from PCI addresses to 68K addresses " link HostOffset} @{"The Interrupt Line identifies where an interrupt arrives " link InterruptLine} @{"What is a PCI Host Bridge " link HostBridge} @{"What is a PCI to PCI bridge " link PCIBridge} @{"What is DMA, please? " link DMAIntro} @{"What are DMA Bounce Buffers " link BounceBuffers} @ENDNODE @NODE PCIBar "PCI BAR Registers" @TOC PCITech PCI devices, very much like autoconfig devices, have one or multiple address space regions through which they offer their services. These regions either contain registers through which a chip is programmed, e.g. to define the resolution of a graphics mode, or memory like regions that contain data, e.g. the frame buffer of a graphics card. The PCI BAR Registers define where in the Amiga memory map these device functions can be reached such that a driver can interact with a device. The openpci.library fills these BAR registers when starting very much like the expansion.library defines where Zorro expansions sit in the Amiga address space. Each device can offer up to 6 BARs, plus one additional region for a ROM, containing the device configuration and/or an elementary driver, such as a VESA Bios extension used by the PC bios to render a boot screen. On the Amiga, device drivers can make use of this driver ROM to learn about the card configuration such as the timing of the RAM on a graphics card. BARs can indicate to be "prefetchable", indicating that the region on the card behaves like RAM and the order in which data is accessed does not matter. This holds for example for the frame buffer of graphic cards. Non-prefetchable BARs contain device registers where the particular order in which they are read or written matters. BARs can also identify "I/O" space, indicating that they live (logically) in the x86 I/O address space. The x86 processor family uses separate instructions and a separate bus protocol to write to I/O regions, and BARs can indicate whether such instructions are needed. On the Amiga, this does not matter and I/O and data is accessed all alike. @ENDNODE @NODE LegacyIO "Legacy IO Region" @TOC PCITech This region contains I/O registers that would be reachable by x86 processors within the 64K of IO space, without actually going through a @{"BAR Register" link PCIBar}. This region is identical for all cards, but if multiple @{"PCI host bridges" link HostBridge} are installed in a system, different for each bridge. For legacy reasons, VGA chipsets typically offer registers in this area that stem from the pre-PCI area. While most chips offer to move these registers away from this area or lock them, some chips require a special "wake up" sequence in this legacy IO area to enable them. Access to this area should be avoided as it is shared between all devices on the same PCI host bridge. For example, if multiple VGA chips are installed, it is unclear which chip feels responsible to an access to the legacy I/O area. @ENDNODE @NODE LegacyVGA "Legacy VGA Memory Region" @TOC PCITech This region contained the planar VGA frame buffer of the original VGA graphics card of the IBM PC. Unfortunately, some early PCI designs also place memory mapped IO registers there, mostly accelerator registers such as the blitter. It extents from 0xa0000 to 0xc0000 in the PC memory space, and most @{"PCI host bridges" link HostBridge} do not map this memory window at all. The Prometheus and Firebird bridges are the only exception. To keep this region clear of PCI mapped windows, the following line need to be added to the @{"ENVARC:PCI-Configuration" link Configure} file: @{CODE} ReserveMemSpace 0xc0000 @{BODY} Note again that this will only have an effect if the PCI host bridge allows mapping this window. Most will not. See also: @{"ReserveMemSpace" link ReserveMemSpace} for more details on this command. @ENDNODE @NODE HostOffset "PCI Host Offset" @TOC PCITech The PCI host offset defines the offset to be added to an address as seen by a PCI address to get the corresponding address for the Amiga 68K CPU. More specific, PCI addresses as seen by devices on the PCI bus implemented by the @{"PCI host bridge" link HostBridge} do not need to be identical to the addresses the 68K CPU requires to use to access these devices. While this offset typically does not matter, it becomes important if @{"DMA" link DMAIntro} is used to transfer data between PCI devices because a particular buffer address as used by the 68K CPU is not the address a PCI device would need. Even more specific, the 68K address used here is a @{B}logical@{UB} address, that is, an address as it is used by software in a driver program. The 68K @{"MMU" link MMULib} potentially translates this to a physical address as seen on the 68K bus, for example the Zorro bus, and the @{"PCI host bridge" link HostBridge} may again translate this address to a different PCI address as seen by a PCI device. This difference becomes important for PCI bridge boards that offer only a limited physical access window through which PCI access is granted, such as the @{"A1200 Mediator bridge boards" link Compatibility}. Here logical address, physical address and PCI address will be all different, and are moderated by the 68K MMU and the Mediator bridge board. @ENDNODE @NODE InterruptLine "Interrupt Line and Interrupt Pin" @TOC PCITech The interrupt line is the logical signal on which a PCI device is assumed to generate an interrupt, and thus defines through which logical interrupt source the 68K CPU receives an interrupt from a PCI device. For most @{"PCI host bridges" link HostBridge}, this interrupt line does not matter as all lines are connected to the same 68K interrupt anyhow, typically interrupt #3. Some host bridges, however, include an additional interrupt priority logic through which individual interrupts can be detected or blocked, and then the interrupt line @{B}does@{UB} matter. The openpci.library distinguishes four interrupt lines, A to D. If the interrupt line is listed by @{"lspci" link lspci} as "X", then the device is not able to generate interrupts. @{B}Important:@{UB} Just because a device defines an interrupt line, it does not mean that it can actually physically generate an interrupt. It is not too uncommon that, despite having the ability to generate interrupts, the actual interrupt pin (see below) of the device is not physically connected. Device drivers should be aware of this, and offer users the ability to work without interrupt through some kind of configuration mechanism, e.g. a tool type in a driver icon. The @{B}Interrupt Line@{UB} is different from the @{B}Interrupt Pin@{UB}. The latter indicates on which of the four possible PCI pins a card generates an interrupt, but these four lines are interleaved in a "braid-like" fashion on PCI bridge boards and on @{"PCI to PCI bridges" link PCIBridge} to spread interrupts more evenly across the four possible lines. The openpci.library has to follow the braid structure to find from the Interrupt Pin on the device the Interrupt Line on which an interrupt is received. The @{"lspci" link lspci} tool only lists the latter, i.e the line on which an interrupt is received by a PCI bridge board. @ENDNODE @NODE MMULib "The mmu.library" @TOC Main The mmu.library is a system library by the same author as the openpci.library to control the 68K on board memory management unit. This library is available through a separate package from Aminet, namely @{CODE} util/libs/MMULib.lha @{BODY} This library is only strictly necessary for using the @{"Mediator A1200" link Compatibility} PCI bridge boards as these boards need to make the entire PCI address space available through a small window left in the A1200 memory map. For all other @{"PCI host bridges" link HostBridge}, the library is not necessary, but it is still advisable to install it as it also controls proper caching of PCI devices within the 68K address space. @ENDNODE @NODE BoardsLib "The boards.library" @TOC Main The boards.library is a system library by Marcus Gerards that helps to identify system components and convert their numeric identifies to a human-readable name. The boards.library is not only aware of Zorro expansions, but also of PCI cards. It is available from Aminet, namely: @{CODE} util/libs/BoardsLib.lha @{BODY} This library is not strictly necessary, but it helps @{"lspci" link lspci} to generate more readable output. @ENDNODE @NODE Install "Installing OpenPCI" @TOC Main In the simplest case, just run the supplied installer script that will take care of everything, including a backup of existing files that are replaced or updated. If you want to install manually, perform the following steps: First, open a shell and copy the openpci.library to LIBS: such as follows: @{CODE} copy openpci.library to LIBS: @{BODY} The openpci.library included in this archive @{B}does not need@{UB} proprietary PCI driver libraries from third parties. In fact, it conflicts with some. It is better to remove these libraries or move them into a backup directory such that drivers pick the openpci.library or one of its built-in @{"emulations" link Emulate}. For setting up emulation, please edit the @{"ENVARC:PCI-Configuration" link Configure} file. The following steps are recommended to move third party libraries away; first, create a backup directory in case you need them later: @{CODE} makedir LIBS:backup @{BODY} Then move third-party libraries from @{B}LIBS:@{UB} into this backup directory: @{CODE} rename LIBS:pci.library LIBS:backup/ rename LIBS:prometheus.library LIBS:backup/ @{BODY} If you are also using the @{"mmu.library" link MMULib}, the following steps help to reduce the time for booting the system. First, if the directory "LIBS:mmu" does not yet exist, create it: @{CODE} makedir LIBS:mmu @{BODY} Entering the above command if this directory already exists results in an error OBJECT EXISTS which can be safely ignored. Second, copy the file PCIInit from this distribution into the directory just created: @{CODE} copy PCIInit to LIBS:mmu/ @{BODY} Third, edit the file ENVARC:MMU-Configuration, which is the configuration file of the mmu.library. This can be done, for example, with the system editor "Ed": @{CODE} ed ENVARC:MMU-Configuration @{BODY} This will either open the file, or create an empty file if it did not yet exist. If the file is empty, add the following line at its top: @{CODE} ClearTTX @{BODY} At the very bottom of this file, add the following line: @{CODE} PCIInit @{BODY} The purpose of this line is to initialize the openpci.library already at boot time before the mmu.library configures the MMU, thus saving time for creating MMU tables that are replaced by openpci anyhow. Then save the edits. For "Ed", the system editor, press the @{B}Esc@{UB} key, then type @{B}x@{UB}, then press @{B}RETURN@{UB}. Finally, reboot the system - that is all. The openpci.library can also be @{"configured" link Configure} and thus customized. This should not be necessary in general, but the option exists. Configuration is through the file @{"ENVARC:PCI-Configuration" link Configure} which is a text file that can be created and modified by any standard text editor, for example by "Ed". @ENDNODE @NODE Configure "Configuring the openpci.library" @TOC Main The openpci.library parses its preferences, the file "ENV:PCI-Configuration" or "ENVARC:PCI-Configuration", on startup, provided it is available. This file can be used for experts to fine-tune the settings of the PCI devices on the PCI bus, for example to disable certain @{"BAR registers" link PCIBar} that are not needed or not relevant for mapping the device into an Amiga system. @{B}This file should not be touched unless you really, really know what you are doing.@{UB} Modifying this file may easily cause crashes and hangs, and might result in certain "surprise" moments. This is definitely an "advanced feature". The file is a pure ASCII file and can be edited with each text editor. For example, the system editor "Ed" is good enough. The syntax of the file is very much like the syntax of a shell script: All characters behind a semicolon ";" are considered to be a comment and are hence ignored. Everything else is a command and executed by the library. However, unlike the shell, most commands are built into the library, and external commands are not searched in the C: logical device. The library knows currently only a limited set of built-in commands, everything else is considered an external file and tried to be loaded as external module from the "LIBS:pci" directory. In case the library is, too, unable to locate an external command, the command is ignored and no error condition is generated. The syntax of the arguments follows the syntax of the shell, with the restriction that the input and output redirection characters ">" and "<" are not available because there is neither an input nor an output stream. The following internal commands are available: @{"Emulate : Enable emulation wrapper for non-openpci drivers" link Emulate} @{"Ignore : Ignore devices or BAR registers of devices " link Ignore} @{"DisableIO : Disable I/O register access of devices " link DisableIO} @{"ReserveIOSpace : Keep areas of the I/O space clear of openpci " link ReserveIOSpace} @{"ReserveMemSpace : Keep areas of the PCI memory space clear " link ReserveMemSpace} @{"SetCacheLineSize : Define the cache line size of PCI devices " link SetCacheLineSize} @{"SetInterrupt : Define the interrupt line of a device " link SetInterrupt} @{"SetLatency : Limit the maximal bus access time of a device " link SetLatency} @{"SetPri : Define a priority by which space is allocated " link SetPri} @{"VirtualMapping : Enable or disable virtual PCI addressing " link VirtualMapping} @{"WriteIO : Write bytes into the legacy IO area " link WriteIO} @{"Hint : Provide hints for optimized PCI allocation " link Hint} @{"DMAMemSource : Define the board providing DMA memory " link DMAMemSource} @{"Disable2ndBank : Disable a second PCI banking window " link Disable2ndBank} Typically, there is no need to use the above commands and in general, @{B}PCI-Configuration@{UB} may remain empty or absent. @ENDNODE @NODE Emulate "Enable emulation wrapper for non-openpci drivers" @TOC Configure @{CODE} NAME Emulate -- emulate PCI libraries SYNOPSIS Emulate PROMETHEUS/S,MEDIATOR/S,GREX/S FUNCTION This command enables emulation of various third party products and driver libraries to improve interoperability. As a result, re-implementations of such libraries, along with emulated expansion configuration structures will be created. TEMPLATE PROMETHEUS: emulate the Matay Prometheus PCI bridge along with the prometheus.library. MEDIATOR: emulate an Mediator A4000 bridge along with the pci.library. GREX: emulate the G-Rex cybpci.library. EXAMPLE Emulate Prometheus enables emulation of the Matay PCI bridge and driver library. BUGS @{BODY} @ENDNODE @NODE Ignore "Ignore devices or BAR registers of devices" @TOC Configure @{CODE} NAME Ignore -- disable a device or a BAR region of a device SYNOPSIS Ignore DEVICE,CLASS,SLOT,BAR FUNCTION This command disables a device (or function of a device) from being initialized, or a BAR register of the device from getting initialized. Non-configured devices will not appear on the PCI bus and in the library, non-configured BAR registers will not take address space. TEMPLATE DEVICE: provides the device to ignore by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. The asterisk ("*") can be used as a wildcard and matches any vendor, device or function. If multiple devices match, this command applies to all of them. CLASS: provides the class to ignore by by a triple of class, subclass and, optionally, progIF, all separated by colon. SLOT: identifies the device by its location on the PCI bus, by a (hexadecimal) bus number starting from 1 for the host bridge, followed by a (hexadecimal) device number starting from 0 for the first device, optionally followed by a dot and a function number. BAR: if present, only a particular BAR register will not be initialized; if not given, then the entire device will be ignored. The argument to BAR is either a number from 0 to 5, or the keyword ROM, in which case the device ROM, for example the VGA bios, is not mapped. Values are by default in hex, accepting 0x or or $ as prefix. # enforces decimal, % binary and 0 or O octal numbers. EXAMPLE Ignore Device 5333:5631 Bar 1 Ignore BAR region 1 of the S3 Virge. BUGS @{BODY} @ENDNODE @NODE DisableIO "Disable I/O register access of devices" @TOC Configure @{CODE} NAME DisableIO -- disable I/O regions of a device SYNOPSIS DisableIO DEVICE,CLASS,SLOT FUNCTION This command disables a device or function of a device from responding to accesses into an I/O bar or the legacy I/O window. This does not the BAR from being blocked, see the Ignore command, but disables the I/O control bit in the command register to make the device ignore accesses to its I/O mapped BARs or the legacy I/O region. A possible use case for this command is to disable VGA cards from listening to the legacy VGA window, thus potentially allowing multiple VGA cards in the system without conflicting in the legacy I/O region. Note that the corresponding driver need to be aware of this situation and, potentially, map away device resources from the legacy I/O window before enabling the device. TEMPLATE DEVICE: provides the device to ignore by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. The asterisk ("*") can be used as a wildcard and matches any vendor, device or function. If multiple devices match, this command applies to all of them. CLASS: provides the class to ignore by by a triple of class, subclass and, optionally, progIF, all separated by colon. SLOT: identifies the device by its location on the PCI bus, by a (hexadecimal) bus number starting from 1 for the host bridge, followed by a (hexadecimal) device number starting from 0 for the first device, optionally followed by a dot and a function number. Values are by default in hex, accepting 0x or or $ as prefix. # enforces decimal, % binary and 0 or O octal numbers. EXAMPLE DisableIO Device 5333:5631 Disable the S3 Virge from responding to accesses into the legacy I/O window. SEE ALSO Ignore BUGS @{BODY} @ENDNODE @NODE ReserveIOSpace "Keep areas of the I/O space clear of openpci" @TOC Configure @{CODE} NAME ReserveIOSpace -- reserve IO space SYNOPSIS ReserveIOSpace BRIDGE/K,BYTES/A FUNCTION This command reserves a region at the beginning of the PCI IO region to keep PCI BAR registers out of this region. Some devices, most notably VGA cards, react on registers in the legacy IO region. Conflicts arise if BAR regions are mapped into the same area. By default, openpci.library reserves all IO registers below address 0x6000 for legacy IO. TEMPLATE BRIDGE: the name of the PCI bridge on which an IO region shall be reserved. If missing, then all PCI bridge boards will be affected. The following bridge types are currently supported: "Mediator A1200" : any of the A1200 mediator boards "Mediator A4000" : the A4000 mediator board "Prometheus" : the original Prometheus board "Prometheus Firestorm" : the Prometheus Firestorm "G-Rex" : the A4000 or A1200 GRex board If the name contains spaces, it must be enclosed in spaces. BYTES: the number of bytes to reserve at the start of the IO region, given in hex. Values are by default in hex, accepting 0x or or $ as prefix. # enforces decimal, % binary and 0 or O octal numbers. EXAMPLE ReserveIOSpace 0x400 Reserve 1024 IO port bytes at the start of the IO window, thus making additional I/O ports available. BUGS @{BODY} @ENDNODE @NODE ReserveMemSpace "Keep areas of the PCI memory space clear" @TOC Configure @{CODE} NAME ReserveMemSpace -- reserve memory space SYNOPSIS ReserveMemSpace BRIDGE/K,BYTES/A FUNCTION This command reserves a region at the beginning of the PCI memory space to keep PCI BAR registers out of this region. Some devices, most notably VGA cards, react on memory accesses in the legacy VGA area. Conflicts arise if BAR regions are mapped into the same area. This command can be used to keep the legacy VGA region free of BAR regions. TEMPLATE BRIDGE: the name of the PCI bridge on which a memory region shall be reserved. If missing, then all PCI bridge boards will be affected. The following bridge types are currently supported: "Mediator A1200" : any of the A1200 mediator boards "Mediator A4000" : the A4000 mediator board "Prometheus" : the original Prometheus board "Prometheus Firestorm" : the Prometheus Firestorm "G-Rex" : the A4000 or A1200 GRex board If the name contains spaces, it must be enclosed in spaces. BYTES: the number of bytes to reserve at the start of the memory region, given in hex. Values are by default in hex, accepting 0x or or $ as prefix. # enforces decimal, % binary and 0 or O octal numbers. EXAMPLE ReserveMemSpace 0xc0000 Keep BAR regions out of the legacy VGA region. BUGS @{BODY} @ENDNODE @NODE SetCacheLineSize "Define the cache line size of PCI devices" @TOC Configure @{CODE} NAME SetCacheLineSize -- set expected cache line size in bytes SYNOPSIS SetCacheLineSize DEVICE,CLASS,SLOT,SIZE=BYTES/A FUNCTION This command changes the cache line size of a PCI device that can act as bus master, to invalidate parts of the cache of the host CPU by the Memory Write and Invalidate command. This should most likely be 0 to disable this feature, or 16 to match the cache line size of the 68K. TEMPLATE DEVICE: provides the device to configure by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. The asterisk ("*") can be used as a wildcard and matches any vendor, device or function. If multiple devices match, this command applies to all of them. CLASS: provides the class to configure by by a triple of class, subclass and, optionally, progIF, all separated by colon. SLOT: identifies the device by its location on the PCI bus, by a (hexadecimal) bus number starting from 1 for the host bridge, followed by a (hexadecimal) device number starting from 0 for the first device, optionally followed by a dot and a function number. SIZE: The cache line size of the device in bytes, a value between 0 and 1024. The value is rounded down to the next multiple of 4. Values are by default in hex, accepting 0x or or $ as prefix. # enforces decimal, % binary and 0 or O octal numbers. The cache line size is in decimal by default. EXAMPLE SetCacheLine Bytes 0 Disables the Memory Write and Invalidate command for all devices. BUGS @{BODY} @ENDNODE @NODE SetInterrupt "Define the interrupt line of a device" @TOC Configure @{CODE} NAME SetInterrupt -- set the pin on which to expect device interrupts SYNOPSIS SetInterrupt DEVICE,CLASS,SLOT,PIN/A FUNCTION This command changes the interrupt pin on which openpci.library should expect interrupts of the given device to be routed, or it disables the interrupt. Without this function, this information is taken from the PCI configuration area. While it is usually correct, some cards provide false information in its config area, thus requiring fix-up by this command. Note that this command does not change the interrupt routing, it only changes where openpci.library is supposed to expect the interrupt. TEMPLATE DEVICE: provides the device to configure by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. The asterisk ("*") can be used as a wildcard and matches any vendor, device or function. If multiple devices match, this command applies to all of them. CLASS: provides the class to configure by by a triple of class, subclass and, optionally, progIF, all separated by colon. SLOT: identifies the device by its location on the PCI bus, by a (hexadecimal) bus number starting from 1 for the host bridge, followed by a (hexadecimal) device number starting from 0 for the first device, optionally followed by a dot and a function number. PIN: the pin on which the device interrupt appears. Values 1 to 4 correspond to interrupt pins A to D. The value 0 disables the interrupt. Values are by default in hex, accepting 0x or or $ as prefix. # enforces decimal, % binary and 0 or O octal numbers. EXAMPLE SetInterrupt Device 5333:5631 Pin 0 Disables the interrupt of the S3 Virge. BUGS @{BODY} @ENDNODE @NODE SetLatency "Limit the maximal bus access time of a device" @TOC Configure @{CODE} NAME SetLatency -- set latency of the device in PCI cycles SYNOPSIS SetLatency DEVICE,CLASS,SLOT,LATENCY=CYCLES/A FUNCTION This command changes the latency of the device on the PCI bus in cycles. It sets the number of cycles the device is allowed to lock the PCI bus until another device is able to get the bus. TEMPLATE DEVICE: provides the device to configure by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. The asterisk ("*") can be used as a wildcard and matches any vendor, device or function. If multiple devices match, this command applies to all of them. CLASS: provides the class to configure by by a triple of class, subclass and, optionally, progIF, all separated by colon. SLOT: identifies the device by its location on the PCI bus, by a (hexadecimal) bus number starting from 1 for the host bridge, followed by a (hexadecimal) device number starting from 0 for the first device, optionally followed by a dot and a function number. LATENCY: The latency of the device in cycles on the PCI bus, a value between 0 and 255. Values are by default in decimal, accepting 0x or or $ as prefix to force hex input. # enforces decimal, % binary and 0 or O octal numbers. The latency is in decimal by default. EXAMPLE SetLatency Device 5333:5631 Cycles 255 Sets the latency of the S3 Virge to 255 cycles. BUGS @{BODY} @ENDNODE @NODE SetPri "Define a priority in which space is allocated" @TOC Configure @{CODE} NAME SetPri -- set the initialization priority of a device SYNOPSIS SetPri DEVICE,CLASS,SLOT,PRI/A FUNCTION This command adjusts the order in which devices are initialized by assigning a priority to them. Devices of higher priority are initialized first and thus address space is assigned to them first. The default priority is 0. BAR registers of the same priority are assigned in the order of decreasing size. TEMPLATE DEVICE: provides the device to prioritize by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. CLASS: provides the class to prioritize by by a triple of class, subclass and, optionally, progIF, all separated by colon. SLOT: identifies the device by its location on the PCI bus, by a (hexadecimal) bus number starting from 1 for the host bridge, followed by a (hexadecimal) device number starting from 0 for the first device, optionally followed by a dot and a function number. Values are by default in decimal, accepting 0x or or $ as prefix to force hex input. # enforces decimal, % binary and 0 or O octal numbers. EXAMPLE SetPri Device 5333:5631 Pri 20 Allocate BAR registers of the S3 Virge with elevated priority. BUGS @{BODY} @ENDNODE @NODE VirtualMapping "Enable or disable virtual PCI addressing" @TOC Configure @{CODE} NAME VirtualMapping -- enable or disable virtual PCI addressing SYNOPSIS VirtualMapping ON/S,OFF/S FUNCTION This command enables or disables virtual mapping of the PCI address space with the MMU. If enabled, which is the default, the (rather small) PCI address space of some PCI host bridges with a small PCI window is extended by virtually mapping addresses in the 68K to the window accessing a subset of the PCI addresses. This requires dynamic remapping of virtual addresses in 68K space, but enables a relatively large PCI space for PCI host bridges otherwise only offering a very small (typically 4MB or 8MB) address window. Note that tools that require physical addresses in the 68K space such as the MuEVD driver then will not work for virtually mapped devices. Disabling this option maps all PCI addresses physically, though only a small window is available for them, likely only making a fraction of the devices on the PCI bus accessible. TEMPLATE ON: use virtual addresses for PCI host bridges offering only a small address window. This is the default. OFF: only allow physically mapped PCI addresses at the price of only having a small subset of PCI devices accessible. EXAMPLE VirtualMapping OFF disables dynamic remapping of PCI address spaces by the MMU. BUGS @{BODY} @ENDNODE @NODE WriteIO "Write bytes into the legacy IO area" @TOC Configure @{CODE} NAME WriteIO -- write a byte to a legacy IO register SYNOPSIS WriteIO DEVICE,CLASS,SLOT,VALUE/A,ADDRESS=TO/A FUNCTION This command writes a byte to a legacy IO register to initialize a board on the PCI bus. TEMPLATE DEVICE: provides the device to initiate by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. The asterisk ("*") can be used as a wildcard and matches any vendor, device or function. If multiple devices match, this command applies to all of them. CLASS: provides the class to initiate by by a triple of class, subclass and, optionally, progIF, all separated by colon. SLOT: identifies the device by its location on the PCI bus, by a (hexadecimal) bus number starting from 1 for the host bridge, followed by a (hexadecimal) device number starting from 0 for the first device, optionally followed by a dot and a function number. VALUE: the byte value to write ADDRESS=TO: the target address in the legacy IO region Values are by default in hex, accepting 0x or or $ as prefix. # enforces decimal, % binary and 0 or O octal numbers. EXAMPLE WriteIO Device 5333:5631 VALUE 0x01 TO 0x3c3 This initializes the S3 Virge by writing the the value 1 into register 3C3. BUGS @{BODY} @ENDNODE @NODE Hint "Provide hints for optimized PCI allocation" @{CODE} NAME Hint -- provide hints for optimized PCI allocation SYNOPSIS Hint DEVICE,MEMORY/N,MMIO/N,IGNORE/N FUNCTION This command provides hints for optimized PCI address space allocation by providing details on which BAR maps memory and which BAR provides access to memory mapped registers. If such hints are found, then the address space allocation will, in address space restricted environments, only map a subset of the BAR areas, such that only limited video RAM or a subset of the registers are available. While the device mapper will arrange that at least the lowest 4MB of memory mapped registers will be visible, the accessible memory window may be somewhere in the middle of the available total memory size, depending on allocation constraints of the PCI address space. This hinting is only effective if VirtualMapping is OFF or no MMU is present, and thus if the MMU is not or cannot be used to creating a large continuous PCI access window for the CPU. At most one device can be hinted in a given setup. TEMPLATE DEVICE: provides the device to configure by a triple of vendor and device ID separated by colon, optionally followed by the device function separated by a dot. Hinting DOES NOT work by device class or slot as the BAR mapping is vendor and model specific. The asterisk ("*") can be used as a wildcard and matches any vendor, device or function. If multiple devices match, this command applies to all of them. MEMORY: BAR number containing video memory. This is a number between 0 and 5. MMIO: BAR number containing memory mapped IO registers. This is a number between 0 and 5. IGNORE: BAR number that can be potentially ignored on tight PCI constraints such as a second aperture. EXAMPLE Hint DEVICE 121a:5 MEMORY 1 MMIO 0 hints OpenPCI on the device region assignment of the Voodoo 2/3 as identified by vendor 121a product 5, which has its memory region mapped by BAR 1 and its IO registers mapped by BAR 0. The ROM is mapped, but not directly accessible from the 68K side. BUGS @{BODY} @ENDNODE @NODE DMAMemSource "Define the board providing DMA memory" @{CODE} NAME DMAMemSource -- set the default bridge providing DMA memory SYNOPSIS DMAMemSource BRIDGE/A FUNCTION This command selects the bridge from which DMA memory is allocated through the pci_allocdma_mem() function that does not take an argument for the target board. If no board is defined, the library allocates DMA memory from the first board found. If multiple PCI bridges are present in the system, then the bridge to which DMA memory requiring cards are connected should be selected. This applies, for example, to PCI sound cards. TEMPLATE BRIDGE: the name of the PCI bridge from which the DMA memory is taken. The following bridge types are currently supported: "Mediator A1200" : any of the A1200 mediator boards "Mediator A4000" : the A4000 mediator board "Prometheus" : the original Prometheus board "Prometheus Firestorm": the Prometheus Firestorm "G-Rex" : the A4000 or A1200 GRex board If the name contains spaces, it shall be enclosed in spaces. EXAMPLE DMAMemSource G-Rex Defines the G-Rex as DMA memory source, for example because a sound card is connected to G-Rex. BUGS @{BODY} @ENDNODE @NODE Disable2ndBank "Disable a second PCI banking window" @{CODE} NAME Disable2ndBank -- disable the 2nd PCI window on some boards SYNOPSIS Disable2ndBank FUNCTION This command disables the second PCI window in the Amiga address space that is, unfortunately, simply not working on some configurations, even though this window is identified and announced through AutoConfig. This command can be used to work around hardware issues on some boards, even though the flexibility of the configuration is then limited. TEMPLATE This command does not take any arguments. EXAMPLE Disable2ndBank Removes the second 4MB DMA window on a A1200 Mediator board. BUGS @ENDNODE @NODE Credits "Credits" @TOC Main The openpci.library is a complex project, and it would not be possible without the help of many people. In particular, I want to thank: Tim Schattkowsky, Torsten 'torsti76' Kurbad, Steen Lund, Harald Meinzer and many others. I also want to thank Benjamin Vernoux for the original version of openpci, and Stéphane Guillard for porting this original version to AmigaOs 4. @ENDNODE @NODE Contact "Contacting the author" @TOC Main In case you want to report a defect of the openpci.library, you can reach its author here: Thomas Richter Please also include the following information in your report: - The type of PCI bridge board in your system - The Amiga model the PCI bridge is installed on - The CPU model, and whether the mmu.library is running - The output of "ShowConfig" - The output of "lspci", if possible Please describe the problem as close as possible, and provide instructions how to reproduce it. @ENDNODE @NODE FAQ "Frequently asked questions, did you check these?" Here's the collection of some questions that I have been asked quite frequently, so in case you encounter a problem, it's a good idea to check this list first. ____________________________________________________________________________ Q: my PCI based hardware driver refuses to work A: First check for which PCI system the driver was written. Historically, four systems exist: The G-Rex system, the Prometheus system, the Mediator system and OpenPCI. The OpenPCI library supports natively only the latter, but can emulate the other three systems. To enable emulation, open the file "ENVARC:PCI-Configuration" with an editor of your choice - or create the file if it does not yet exist. Then, insert an @{"Emulate" link Emulate} command to enable emulation of particular PCI subsystem components, that is, insert Emulate GRex to emulate GRex support, or Emulate Prometheus to enable Prometheus emulation, or Emulate Mediator to emulate Mediator support. The options can also be combined to emulate multiple systems, i.e. Emulate Prometheus Mediator GRex enables all emulation features of the library. OpenPCI support is always present and does not need to be enabled. Emulation costs additional resources in terms of system memory, and for Mediator emulation, also graphics (RTG, video RAM) memory. ____________________________________________________________________________ Q: I enabled emulation, but the driver still refuses to work. A: Some PCI drivers require "bounce buffers" on the PCI bus they can reach by DMA. This is necessary because most PCI bridge designs do not allow to reach Amiga memory from the PCI bus. In such a case, you need a PCI based graphics card and a relatively recent version of P96 (version 3.5.0 or better). The graphics card driver, i.e the "Monitor Icon" need to be loaded before the remaining PCI drivers, and the P96 driver need to be instructed to grant direct access to the video RAM. For this, select the monitor icon with the mouse, right click on the workbench "Icon" menu on "Information", and edit the tool types. There, either add or modify the tooltype "GRANTDIRECTACCESS" such that it says GRANTDIRECTACCESS=Yes Then save the modifications, and reboot the machine. Ensure that the graphics card is started and running, then try again. The drawback of direct access is that, depending on the graphics cards, some video modes may not be available, such as planar modes or big- endian high- and true-color modes. ____________________________________________________________________________ Q: ...but my driver still does not work. A: If this is a driver for a G-Rex system, and you do not own a G-Rex, and you already enabled G-Rex emulation, then there is unfortunately nothing that can be done. G-Rex allowed DMA access into Amiga-sided RAM, and G-Rex drivers therefore assume that it is sufficient to allocate buffers for their drivers on the Amiga side. Unfortunately, this is not the case for all other PCI bridge boards, and thus, in general, some G-Rex drivers will simply not work. ____________________________________________________________________________ Q: ...but my driver still does not work, and it is not a G-Rex driver. A: Please check whether OpenPCI actually does see your PCI hardware. For this, open a shell and enter the command @{"lspci" link lspci}. It lists all PCI resources on your system. To see the PCI resources by clear name instead of numerical ID, also install the "boards.library" available on Aminet. You may also want to run the DMAMemTest program in the distribution as it allows to detect common problems with @{"DMA bounce buffer" link BounceBuffers} availability. ____________________________________________________________________________ Q: my PCI card is not found or not seen by OpenPCI. A: PCI bridge boards only offer a limited window to map PCI resources. If this window is used up, then OpenPCI may be unable to map your hardware into this window. Typically, this window is around 512MB in size, but may be even more limited if you disable MMU usage on A1200 mediators in which case only two 4MB windows remain available. MMU usage is controlled by the @{"VirtualMapping" link VirtualMapping} command in the PCI-Configuration file. To enable a full 512MB window, ensure that the file ENVARC:PCI-Configuration contains the command VirtualMapping On and no other "VirtualMapping" command. If this still does not help, you can use the @{"SetPri" link SetPri} command to enlarge the priority of those devices you absolutely need to see, at the price of potentially disabling others. The easiest solution is certainly to remove all but only the necessary PCI cards to make some room in the PCI space. ____________________________________________________________________________ Q: MuEVD tells me that it cannot open the screen for ShapeShifter. A: The A1200 Mediator emulation requires the MMU to enable direct addressing of the video RAM, but so does MuEVD. Direct access to the graphics card video RAM is therefore not possible, and only the refreshed mode is available for MuEVD on the A1200 mediator. To enable it, open the file ENVARC:MuEVD.prefs and add there at the top of the file the line REFRESHED=Yes or modify the first line such that it includes the above. Then save the file and try again. The configuration can be fine tuned a bit, for this see the MuEVD.guide. Another alternative is to disable MMU usage of OpenPCI. This only works for certain graphics cards, reduces the amount of video RAM to 4MB and typically also disables most other cards on the PCI bus. For this, make sure that you installed the PCI-Configuration file that comes with the OpenPCI distribution as it contains a series of @{"Hint" link Hint} commands that provide information on how certain graphics cards map their memory, and then add to ENVARC:PCI-Configuration the line VirtualMapping Off This reduces the available video RAM to 4MB, but allows MuEVD to map the video RAM directly to where MacOs expects it. Note that currently this trick only works for S3Virge, Voodoo and Matrox cards, i.e. cards that are officially supported by P96. The trick may not work for third party drivers. ____________________________________________________________________________ Q: openpci crashes on my system. A: Without further information, it is hard to say what happens. Please first check the @{"installation" link Install} whether you have still third-party libraries in your system and drivers using them. If a third-party driver configures and claims PCI resources, and openpci.library re-configures a PCI device again, then the corresponding driver crashes. Instead, check whether the @{"emulation layer" link Emulate} of openpci is sufficient to run such driver. This layer is @{"configured" link Configure} through the "ENVARC:PCI-Configuration" file. In case this does not solve the problem, @{"contact the author" link Contact}. ____________________________________________________________________________ Q: openpci does not work on my Mediator A1200 system. A: Note that the Amiga A1200 bus structure only allows an 8MB window for mapping PCI resources. That is a bit slim, but sufficient for sound and network cards. For graphic cards, it is insufficient. Therefore, openpci.library uses the services of @{"mmu.library" link MMULib} to emulate a large PCI window, provided this library is available. While its installation is generally recommended, it is particularly important on A1200 systems. ____________________________________________________________________________ Q: With openpci loaded, I suddenly see a lot of strange system expansions in ShowConfig and other hardware diagnostic tools. A: These @{"autoconfig" link AutoConf} entries are, actually, PCI resources openpci adds to your system to make other system components aware of PCI extensions. They include both @{"PCI host bridge" link HostBridge} resources as well as all @{"BAR registers" link PCIBar} of all installed PCI bridges. ____________________________________________________________________________ Q: When I boot my system, SetPatch takes a long time to run. A: PCI bridge boards require a huge amount of address space in the Amiga memory map, and setting up MMU tables for this address space takes quite a while. To address this problem, please install the @{"PCIInit" link PCIInit} tool in LIBS:mmu and run it from the @{"ENVARC:MMU-Configuration" link Install} file interpreted by the @{"mmu.library" link MMULib}. With this tool, only the MMU pages necessary for PCI resources actually present will be built, thus speeding up the boot process dramatically. ____________________________________________________________________________ Q: On my A1200 mediator, I occasionally see a deadend 0000 0002 software alert which I cannot recover. I then have to reboot the system. Could you please fix this issue? A: Unfortunately, this problem is not fixable by software. It is a @{"hardware design fault" link MediatorGlitch} of the A1200 mediator boards that cannot be worked around. There are two options: Either, get an A1200TX board which does not suffer from the problem, or downgrade to an 68030 processor which can restart instructions from the middle and does not need to rerun them. ____________________________________________________________________________ Q: I own an A1200 mediator, but now all at a sudden, a A4000 mediator is found by ShowConfig. A: This is expected, and a result of the Mediator emulation. This dummy board is placed there to make Mediator specific drivers happy that, despite having the pci.library available, also test for the presence of a Mediator board in the hardware configuration. Thus, whenever you enable Mediator emulation, the dummy board will be present, regardless of what your actual PCI bridge is. ____________________________________________________________________________ @ENDNODE @NODE History "History: What happened before?" @{CODE} Changes since release 2.0: - Fixed defects in the list management of PCI boards. - Forgot to map the legacy IO window through via the MMU. - Added a preferences file ("ENVARC:PCI-Configuration"). - Fixed code if run on an MMU-less system. - Tested successfully on a Firestorm and A4000 Mediator, more tests welcome. - Apparently, the PCIInit tool that came with the previous version was broken. This got fixed as well. ----------------------------------------------------------------------------- Changes for release 2.2: - Added functions for allocating, releasing and announcing PCI memory for DMA bounce buffers. - Added an emulation of the prometheus.library. - Added commands to reserve IO space and memory space. ----------------------------------------------------------------------------- Changes for release 3.2: - The functions for bounce buffer allocation have been debugged. - Added two new tags for FindBoardTagList() to find a board by a memory range. This allows P96 to identify an OpenPCI handled board from the frame buffer address. - Added development files such as the .fd file and the includes. ----------------------------------------------------------------------------- Changes for release 4.2: - This release adds support for PCI-2-PCI or PCI-2-PCIe bridges. However, such bridges require additional hardware support to allow accessing devices behind such bridges. At the time of writing, only the Firestorm PCI bridge is able to generate such extended PCI configuration cycles and thus, this is the only bridge that supports bridges. Support is currently limited to bridges that offer a single PCI bus behind the bridge. This should apply to the majority of PCI plug-in cards. - Added functionality to remove the cybpci.library from the system to stop interfering with the openpci.library. ----------------------------------------------------------------------------- Changes for release 4.3: - The PCI scanning functions were broken and could not continue correctly from a middle of a scan, i.e. if the previous device passed in was non-NULL. - The Grex detection algorithm was a bit uncareful can could have hung machines. It now tests for the presence of the ID tags of the corresponding boards. - The Grex interrupt server did not test all flags necessary to ensure that an interrupt was triggered. - Grex boars board detection now also includes the CVisionPPC if it is present, and the early PCI bridges. - Grex detection now also includes the PCI reset sequence that might have been missing if the PCI firmware was not initialized. - PCIInit no longer fails with an Alert if no PCI bridge boards were detected. ----------------------------------------------------------------------------- Changes for release 4.7: - A new command SetCacheLineSize was added to the PCI-Configuration file. This command sets the cache line size field in the PCI config area. Typically, it should be set to 0. - Support for G-Rex was finalized. The G-Rex board is now fully initialized and PCI configuration cycles now also generate parity correctly. - The G-Rex PCI configuration code now also detects the legacy PCI bridge which connects to the CVisionPPC. This potentially requires an update of the CVisionPPC graphics card driver as it may now use the openpci.library as an optional component. - The G-Rex interrupt handler is now fully debugged and working. - Mediator A1200 device detection has been verified on real hardware. Still missing confirmation that the MMU window handling works not only under emulation. ----------------------------------------------------------------------------- Changes for release 5.2: - A couple of new tags to GetBoardAttrs() allow to retrieve the interrupt line, the legacy IO space or the offset from the PCI address space to 68K virtual addresses. - The G-Rex support functions did not fill in the device number correctly. - Includes for assembler developers were included. - Added sources and binaries for an lspci example binary that lists the devices on the PCI bus(es). ----------------------------------------------------------------------------- Changes for release 5.3: - FindBoardTagList() had a defect and crashed if it was called. This got fixed. - The cybpci.library is now removed immediately after detecting a G-Rex, avoiding a conflict when the PCI configuration is changed under the feed of cybpci. - The include files still misdocumented one field ("master") incorrectly as 32-bit whereas it is just 16 bit, also under the version 1 of openpci. - Forgot to include an assembler lvo file defining the library offsets. ----------------------------------------------------------------------------- Changes for release 5.4: - The Grex board installs now its own DMA memory provider which allocates RAM from the board RAM. This should work as PCI devices on the GRex can do DMA into the CPU RAM, unlike other boards. - Fixed a wrong pointer reference when removing cybpci. ----------------------------------------------------------------------------- Changes for release 5.5: - The code now also removes the P5 PCI ConfigDevs from autoconf as they should not be used anymore. Instead, PCI access should be routed through the openpci.library and its expansion nodes. ----------------------------------------------------------------------------- Changes for release 6.2: - Due to a defect in a header file, creating MMU tables for the A1200 mediator boards did not work. - In case the MMU table setup did not work, the code did not clear device flags requesting MMU window processing. - Creating expansion library ConfigDevs did not check whether some of the BARs have not been initialized. ----------------------------------------------------------------------------- Changes for release 6.3: - During preferences parsing, a structure to hold the parsed arguments was not released, causing a mild memory loss. - A new command was added to the PCI-Configuration file, namely "EMULATE". This command allows to enable emulation of third party libraries, for example "Emulate Prometheus" will enable the prometheus emulation layer, including a "fake" configDev structure pointing to the legacy IO region. This works regardless of the actual PCI board installed. Note that while previous releases always enabled the Prometheus emulation, this emulation now requires explicit user interaction by editing "ENVARC:PCI-Configuration". - When initializing PCI devices for one of the 1200 Mediators, the code overwrote parts of the device structure, implicitly allocating the device. This got fixed. - The SetBoardAttrs() function now expects a "struct Node *" as argument to PRM_BoardOwner, and GetBoardAttrs() returns one. Unfortunately, the prometheus library documentation was not very clear on what the expected argument should be. Similarly, the library stores now its own base address (and thus a struct Node *) as owner on pci_obtain_card(). ----------------------------------------------------------------------------- Changes for release 6.5: - This version now fixes the interrupt routing through PCI bridges and also configures the InterruptLine PCI configuration register to include the interrupt the device is actually generating. ----------------------------------------------------------------------------- Changes for release 6.6: - Interrupt enabling and disabling now not only happens at bridge level, but also at PCI device level through the device command register. ----------------------------------------------------------------------------- Changes for release 6.7: - Interrupt management has been improved further by disabling the interrupt at bridge level only if there is no additional interrupt server queued to listen to the interrupt. This prevents problems if multiple interrupt servers for multiple devices are installed, but one of the servers is removed. - Fixed the include files, the arguments should be TagItem *, not TagList *, and the FindBoard() function follows now the convention of the remaining tag based calls by using an A as appendix for the regular function, and the function name without the appendix for the varadic function. ----------------------------------------------------------------------------- Changes for release 7.2: - Memory and IO base and limit generation for PCI-to-PCI bridges was wrong because it set the upper limit to the exclusive, not the inclusive largest address, thus requesting the bridge to map more than the absolute minimum address range through the bridge. - Bridge memory and IO limits were not rounded correctly to the granularity of the bridge registers. - The bridge subordinate bus configuration byte was set incorrectly in case more than a single bus was behind the bridge; in fact, bridges could not detect more than a single bus behind them at all. This was fixed. - Installation of the interrupt line on the Mediator A1200 closed the PCI configuration bank and thus prevented configuration of any but the first PCI device. - In case a VGA device is found behind the bridge, the code now ensures that access to the legacy VGA registers is mapped through the bridge. - This release disables memory prefetching at the bridge level. There is probably little to be gained as the 68K and the Zorro bus dominates the access time, and prefetching may interact badly with memory mapped IO registers. ----------------------------------------------------------------------------- Changes for release 7.2.1: - The library remained unchanged, but the archive got reorganized a bit. This version includes an installer script and also a guide. ----------------------------------------------------------------------------- Changes for release 7.2.2: - This release fixed the default source directory of the installer. ----------------------------------------------------------------------------- Changes for release 8.2: - The emulate command in PCI-Configuration was extended. ----------------------------------------------------------------------------- Changes for release 9.2: - The built-in DMA memory provider for the G-Rex host bridge now also allocates cache-disabled memory by going through the PCI library, and resets the caching mode as soon as the memory is released. - This version adds experimental support for PCI to PCI bridges on the A4000 Mediator. Note that the A1200 mediator cards cannot possibly support bridges because the address space reserved for PCI configuration is not sufficiently large. ----------------------------------------------------------------------------- Changes for release 9.3: - The PCI device scanner for the mediator bridges bypassed PCI bridges early and thus could have never supported bridges in first place. Nevertheless, most mediator boards are not capable to support bridges, unfortunately. - The IO and memory regions for PCI devices are now only enabled after BAR registers have been loaded with the final addresses. ----------------------------------------------------------------------------- Changes for release 10.2: - Preferences are now parsed before BAR registers are sized. This has the effect that the IGNORE command for BARs will also prevent that the ignored BARs are even written to. - Matching a PCI by class code in PCI-configuration could have trashed memory. - The SetInterrupt command in PCI-Configuration failed to reroute interrupts and thus was mostly useless. - SetInterrupt and SetPri may have failed to configure PCI devices correctly on the A1200 mediator. - In PCI-Configuration, the device function is now separated by a dot from the device ID to mirror the syntax of lspci. - Added a new SLOT keyword to most commands for PCI-Configuration to identify a device by its bus number, slot number and (optionally) function number. ----------------------------------------------------------------------------- Changes for release 10.3: - Bridge configuration was refactored again. Bridge and parent device are now passed already into the constructor of a PCI device, and not only when it is added. - Fixed a trashed register in the Mediator board scan. - The Mediator scan did not pass the parent device correctly into the device creator, thus giving devices behind bridges wrong bus IDs. - For some strange reason, the Mediator does not seem to decode the address bits for selecting a device behind a PCI bridge correctly; it seems to ignore them. Therefore, the Mediator currently supports only a single device behind a bridge. - Some bridges take apparently several milliseconds to accept a configuration. Now the library inserts a 50ms delay after having installed the target busses after setting up a PCI bridge. - The time delay function was broken and passed in the wrong command to the timer.device. ----------------------------------------------------------------------------- Changes for release 10.4: - The algorithm for finding an address space window for the A1200 mediators has been changed. It no longer looks behind the last memory segment, but uses the largest hole from the 24bit limit up. - The installer script has been updated. It now checks whether the archive is corrupt, and also backs up the PCI-Configuration file if it existed. - PCIInit no longer checks whether the version of openpci is larger or equal than its own version. Version 3 of openpci is now sufficient since that version introduced the MMU initialization API. ----------------------------------------------------------------------------- Changes for release 10.5: - When tearing down the library due to an Expunge, the code trashed memory due to an incorrectly loaded memory. - When scanning for devices, the scan no longer stops after the first device of a multi-function device that claims not be of multi-function type. ----------------------------------------------------------------------------- Changes for release 11.2: - GetBoardAttrs() and SetBoardAttrs() could loop forever on unknown tags, the end marker for the known tags was incorrect. - The PCI BAR register parser did not compute the parity correctly for some boards. - Two new tags were added for GetBoardAttr(), namely PRM_PCIMemWindowLow and PRM_PCIMemWindowHigh, which provides the PCI address range available for a device at config time, or the PCI address range a device is mapped into later. These are PCI addresses, not 68K addresses. - SetBoardAttr() can now write PRM_MemorySizeX and PRM_MemoryFlagsX at config time to dynamically size PCI devices. This is useful for tools called from within the PCI-Configuration file. - Fixed a missing register initialization when unloading tools from LIBS:PCI. - Added example source code for an init tool for sizing PCI devices dynamically. - Fixed the description of the autoconf vendor IDs in the autodoc file. ----------------------------------------------------------------------------- Changes for release 12.2: - The "lspci" program accepts now an additional argument, namely "NUMERIC". If set, then it does not attempt to resolve the PCI vendor and device ID to human-readable numbers but rather prints their hex values. - Dynamic PCI initialization through external segments was augmented. Init functions receive now one additional argument in a1, and may return a (non-NULL) pointer. Initially, Init functions are called with this argument set to NULL, and receive in register a0 a pointer to a RDArgs structure for command line parsing. If they return a non-NULL pointer and not a small number as error code, they are called *once again* the PCI environment is completely setup. They then receive NULL as RDArgs in a0, but its own (previous) return code in a1 to complete a potential initialization of a device. ----------------------------------------------------------------------------- Changes for release 12.3: - lspci sources included the wrong header, is BSD-only, should be which is POSIX. - Fixed a defect in the mediator emulation setup. ----------------------------------------------------------------------------- Changes for release 12.4: - This version fixes a race condition in initializing the emulated library bases. - As side effect, emulated libraries are now already showing within exec once openpci has been loaded. MMU initialization is now also performed by opening one of the emulated pci libraries. ----------------------------------------------------------------------------- Changes for release 12.5: - The GetPhysicalAddress() and GetVirtualAddress() of the prometheus emulation library expected the input address in register a0 instead of d0. This got fixed. ----------------------------------------------------------------------------- Changes for release 12.6: - When PCI BAR sizes are defined through SetBoardAttrs(), the library no longer attempts to read back the corresponding BAR as it assumes that the corresponding BAR is non-standard and does not allow read-access. Instead, the defined BAR size is assumed to be correct. ----------------------------------------------------------------------------- Changes for release 12.7: - The ReserveMemSpace function in PCI-Configuration could hang forever if a bridge does not support access to the low memory PCI area and reservation failed. - In case address space allocation for a BAR fails, the corresponding device is disabled, excluded from further reservations and removed from the listed device list now. - Translation between 68K addresses and PCI addresses is now aware of the memory region reserved by ReserveMemSpace and maps addresses below the reservation limit through, regardless whether any BAR actually uses the region. ----------------------------------------------------------------------------- Changes for release 12.8: - The legacy VGA window, made accessible by ReserveMemSpace was not properly mapped by the MMU, and neither received an Expansion ConfigDev node. This has now been fixed. The product ID for this region is now 7 (see also openpci.doc). - The PCI address space algorithm was updated to make better use of a non-aligned upper PCI memory window. Now, smaller PCI BARs are placed there first to make best use of the available address space. - The guide was updated to describe the legacy VGA window. ----------------------------------------------------------------------------- Changes for release 12.9: - The pci_logic_to_physic_addr() and related functions were actually broken because one of the used instructions did not (as expected) generate condition codes for determine error conditions. This has been fixed. ----------------------------------------------------------------------------- Changes for release 13.2: - Added the "VirtualMapping" command for PCI-Configuration. If this is enabled - which is the default - the PCI address space of the A1200 mediator boards is enlarged by dynamically (virtually) mapping addresses of the 68K to the small PCI window. Can be turned off to always have physically mapped PCI addresses, though only few devices then fit into the relatively small address space. - Flushing the library now restores the original ConfigDev structures. - If the emulation code was flushed, the code forgot to remove the emulated expansion structures and thus could have crashed the machines. - If the PCI bus was rescanned after flushing the library, the MMU blocked access to non-existing devices and thus caused the code to trigger MuForce hits - for devices that are not present. The library now bypasses the MMU for scanning. It already did for Firestorm and G-Rex. ----------------------------------------------------------------------------- Changes for release 13.3: - The mediator emulation code did not pass the device/function offset correctly to the lower level config space accessor functions and therefore failed to read or write configuration registers at all. - DMA memory handling for mediator emulation was unfortunately broken. While this is fixed, DMA memory is only available through the emulation if the underlying bridge maps 68K addresses directly to PCI addresses, without any offset. ----------------------------------------------------------------------------- Changes for release 13.4: - The alloc_dma_mem() function returned nonsense instead of NULL if no DMA memory provider is available. - The emulation functions now call (as much as possible) through the openpci API. ----------------------------------------------------------------------------- Changes for release 14.2: - The PCI address space/BAR allocation algorithm was revisited again. It is now some kind of "buddy" allocation scheme that should be (nearly) optimal and should be able to squeeze in BARs even if top and bottom end of the window are not allocated. - The lower PCI memory area end for the Prometheus was not properly indicated, thus potentially causing BARs to leak into the I/O or config areas. - The upper end of the PCI memory area for the firestorm was extended a little bit to make more room. This requires testing whether real hardware behaves as documented. - Added two new functions to the API, ObtainPCIRegion() and ReleasePCIRegion() which temporarily can provide access to any area in the PCI config space. The typical use case for these functions is to write to legacy VGA space. Not all PCI host adapters will support such accesses. Included are currently the firestorm and the Mediators (potentially). Example source is included (ObtainExample.c) to demonstrate the API. - As the API is extended, pragmas and headers have been regenerated. ----------------------------------------------------------------------------- Changes for release 14.3: - Fixed bridge allocation (again, hopefully). ----------------------------------------------------------------------------- Changes for release 14.4: - The granularity of which bridge limits are allocated now also depends on the devices behind the bridge (and, recursively, behind bridges behind the bridge). This should also make bridge limit allocation almost optimal. - Enlarged the delay to move out of reset to 100ms, and the delay to start scanning behind a bridge to 100ms. ----------------------------------------------------------------------------- Changes for release 14.5: - openpci now installs a patch into AllocMem if one of the emulated libraries is opened and by that provides DMA memory to drivers that ask for DMA memory this way. The allocation then goes directly down to P96 without requiring a memory pool in exec. This method has the advantage that DMA memory cannot be allocated "by accident" if the system runs low on memory because such memory might be incompatible to forms of Zorro DMA as it may be virtually mapped. The patch is removed again once the emulation is closed again. ----------------------------------------------------------------------------- Changes for release 14.6: - This release fixes a crash when attempting to remove one of the emulation libraries. ----------------------------------------------------------------------------- Changes for release 15.2: - The PCI-Configuration file offers a new command, namely "Hint". With this command, openpci can be hinted which BARs of a PCI device contain memory-mapped registers and which contain video RAM. The purpose of this command is that it allows openpci to support VGA graphics cards even in restricted configurations with only two small PCI windows accessible from the 68K side without using a virtual MMU mapping window. If such a hint is found, openpci makes the first 4MB of the IO window and another 4MB window into vdeo RAM accessible to the 68K side. This makes some graphics cards such as the Voodoo workable without MMU tricks in such limited environments, but also restricts the usable video RAM to 4MB. Driver developers need to take care that they clamp the video RAM to the size delivered from the pci_dev structure and do not attemp to read them from hardware. Furthermore, MMIO registers are in such setups not reachable by DMA - this should hopefully be not a restriction. - lspci received a new command line option "PCIADDRS" to print the addresses of the PCI bar registers as seen from the PCI space. The default is to print the addresses as used by the 68K side. - The DMA memory provider is now more careful and checks whether PCI and 68K addresses differ for memory allocated for some emulation modules that cannot handle such translations. ----------------------------------------------------------------------------- Changes for release 16.2: - When allocating DMA memory from a G-Rex, and no suitable memory was found, the previous release crashed with a bad memory alert. The fixed code just does not deliver any memory. - The emulation code now also accepts G-Rex memory as DMA memory and provides it as such under emulation. - The memory allocation patch for the emulation will now also request G-Rex memory if DMA memory is desired through AllocMem(). - A new command was added to PCI-Configuration, namely DMAMemSource. This command allows to select the board from which DMA memory is taken if requested through the (old) openpci interface that does not take a target board for which the memory is desired. For example "DMAMemSource G-Rex" designates the G-Rex board in a multi- PCI setup as source board for DMA memory, asuming that DMA-requesting devices are plugged into this board. ----------------------------------------------------------------------------- Changes for release 17.2: - Added a command to disable the second PCI window on some boards as it is not always working, in some configurations. Alternatively, the board should be jumpered to 4MB only. ----------------------------------------------------------------------------- Changes for release 17.3: - Due to a left-over debugging switch, the 17.2 version always handled mediator bridge boards as if they had an 8MB window. ----------------------------------------------------------------------------- Changes for release 17.4: - Interrupt handling on the mediator bridges improved and should now be able to handle multiple simultaneous interrupts at once. ----------------------------------------------------------------------------- Changes for release 17.5: - At most 512MB are reserved for the MMU window of the small mediators as the window management of the hardware cannot handle larger windows. ----------------------------------------------------------------------------- Changes for release 17.6: - When reading BAR registers, the scanner now disregards those registers that are not negatives of powers of 2 and thus likely corrupt. - One mediator emulation function had to keep CPU registers intact. - Fixed computation of the announced Mediator window mask. ----------------------------------------------------------------------------- Changes for release 17.7: - The algorithm for determining whether devices of a bridge fit into an MMU window was a bit too conservative and did not attempt to place BARs ideally, i.e. failed to mirror the actual generic allocation algorithm of the bridge. This could have caused failure to allocate devices within an MMU window at all. ----------------------------------------------------------------------------- Changes for release 17.8: - Due to an oversight, the G-Rex emulation was always enabled, even if not requested. This has been fixed. ----------------------------------------------------------------------------- Changes for release 17.9: - Interrupt handling was reworked. Even if an interrupt handler signaled that it was responsible for an interrupt, the interrupt is passed on as the server cannot exclude that another device triggered an interrupt simultaenously. - Fixed the algorithm to determine invalid BARs. ----------------------------------------------------------------------------- Changes for release 17.10: - Interrupt handling for mediator was reworked again. Interrupts are now acknowledged by writing into the interrupt enable register once the interrupt source has been detected. - The "find PCI device by class" function in the mediator emulation was broken and got fixed. ----------------------------------------------------------------------------- Changes for release 17.11: - The mediator interrupt mask computation was still not correct. ----------------------------------------------------------------------------- Changes for release 17.12: - The logic to refuse invalid BAR registers unfortunately also refused to accept 16 bit I/O registers. This was fixed. ----------------------------------------------------------------------------- Changes for release 17.13: - Window allocation changed; a supervisor allocated window takes now priority and is not mapped out unless an overlapping window access requires so. ----------------------------------------------------------------------------- Changes for release 17.14: - Added support for emulation of interrupt probing. ----------------------------------------------------------------------------- Changes for release 40.2: - Added a workaround for a defect in PatchControl. This program is, however, not recommended due to defects when patching the exec memory allocation functions. It is recommended to replace it by TRSaferPtch.lha. ----------------------------------------------------------------------------- Changes for release 40.3: - The PCI preferences did not scan the device list properly for matching devices and could have caused a crash if the first device did not match as it might. Also, if no function is given in a PCI-ID related match, then any function matches, and not (implicitly) only function 0. ----------------------------------------------------------------------------- Changes for release 40.4: - The function comparision introduced in 40.3 was unfortuntaly still buggy and compared the wrong structure offset. ----------------------------------------------------------------------------- Changes for release 40.5: - The er_SerialNumber of the board ConfigDev (vendor 1726 and following, product 0) contains now the original vendor and product ID of the bridge. The vendor is in the topmost 16 bits, the product ID in the LSB. Note that you can also derive this information from the product ID of the ConfigDev itself. ----------------------------------------------------------------------------- Changes for release 40.6: - The cyppci emulation layer did not deliver the BAR sizes correctly. ----------------------------------------------------------------------------- Changes for release 40.7: - The function that released MMU resources in case preparing the MMU magic on A1200 failed did not save all registers. This never did any harm because the calling function saved the same registers anyhow, and it also only happened in failure cases. Thus, from the user perspective, nothing changed. ----------------------------------------------------------------------------- Changes for release 40.8: - This version fixes another defect when restoring the system if the MMU setup did not work. It applies only to the Mediator 1200 boards. Everything else remained unchanged. ----------------------------------------------------------------------------- Changes for release 40.9: - Unfortunately, the 40.8 fix broke more than it helped if openpci was started with PCIInit in the MMU-Configuration. Fixed! ----------------------------------------------------------------------------- Changes for release 40.10: - Previous releases of the library set the "global" flag in the MMU tables prepared by the window handler. This is unnecessary, but also triggered a bug in the 68040 exception handler of the mmu.library. This defect will be fixed independently. The consequence of this defect was that previous releases did not work reliably on 68040 based 1200 mediator boards. ----------------------------------------------------------------------------- Changes for release 40.11: - This release adds one new command to PCI-Configuration, namely "DisableIO". With this command, you can disable of selected cards access to IO registers, for example because legacy VGA registers would all conflict. VGA card drivers, e.g. P96 drivers, would need to manually enable the IO region, remap the registers and turn them on again. - If multiple cards match now one of the commands in the PCI-configuration file, previous versions would only act on the first matching device. Starting with this release, all commands act on all matching devices. ----------------------------------------------------------------------------- @{BODY} @ENDNODE @NODE INDEX "Index" @{CODE} A... @{"AutoConf Entries" link AUTOCONF} B... @{"BAR Registers" link PCIBAR} @{"Boards.library" link BOARDSLIB} @{"Bounce Buffers" link BOUNCEBUFFERS} @{"Bridge (Host)" link HOSTBRIDGE} @{"Bridge (PCI to PCI)" link PCIBRIDGE} C... @{"Compatibility Guidelines" link COMPATIBILITY} @{"Concepts" link PCITECH} @{"Configuring the openpci.library" link CONFIGURE} @{"Contacting the author" link CONTACT} @{"Contents of the Archive" link CONTENTS} @{"Credits" link CREDITS} D... @{"Define a priority in which space is allocated" link SETPRI} @{"Define the board providing DMA memory" link DMAMEMSOURCE} @{"Define the cache line size of PCI devices" link SETCACHELINESIZE} @{"Define the interrupt line of a device" link SETINTERRUPT} @{"Disable a second PCI banking window " link Disable2ndBank} @{"Disable I/O register access of devices" link DisableIO} @{"DMA" link DMAINTRO} @{"DMA Bounce Buffers" link BOUNCEBUFFERS} @{"DMAMemSource" link DMAMEMSOURCE} E... @{"Enable emulation wrapper for non-openpci drivers" link EMULATE} F... @{"Frequently asked questions, did you check these?" link FAQ} H... @{"Hint: Provide hints for optimized PCI allocation" link Hint} @{"History: What happened before?" link HISTORY} @{"Host Bridge" link HOSTBRIDGE} @{"Host Offset" link HOSTOFFSET} I... @{"Ignore devices or BAR registers of devices" link IGNORE} @{"Installing OpenPCI" link INSTALL} @{"Interrupt Line" link INTERRUPTLINE} K... @{"Keep areas of the I/O space clear of openpci" link RESERVEIOSPACE} @{"Keep areas of the PCI memory space clear" link RESERVEMEMSPACE} L... @{"Legacy IO region" link LEGACYIO} @{"Legacy VGA window" link LEGACYVGA} @{"Licence conditions" link LICENCE} @{"Limit the maximal bus access time of a device" link SETLATENCY} @{"lspci utility" link LSPCI} M... @{"Mediator A1200 Race Condition" link MEDIATORGLITCH} @{"mmu.library" link MMULIB} P... @{"PCI AutoConf Entries" link AUTOCONF} @{"PCI BAR Registers" link PCIBAR} @{"PCI Concepts" link PCITECH} @{"PCI Host Bridge" link HOSTBRIDGE} @{"PCI Host Offset" link HOSTOFFSET} @{"PCI to PCI bridge?" link PCIBRIDGE} @{"PCIInit Tool" link PCIINIT} @{"Provide hints for optimized PCI allocation" link Hint} R... @{"Reserve I/O space" link RESERVEIOSPACE} @{"Reserve memory" link RESERVEMEMSPACE} S... @{"Set PCI cache line size" link SETCACHELINESIZE} @{"Set PCI interrupt line" link SETINTERRUPT} @{"Set PCI latency" link SETLATENCY} @{"Set PCI priority" link SETPRI} V... @{"VGA window" link LEGACYVGA} W... @{"Write bytes into the legacy IO area" link WRITEIO} @{BODY} @ENDNODE