HalGetBusDataByOffset-Funktion (ntddk.h)

Artikel
02/07/2025

Warnung

HalGetBusDataByOffset und HalSetBusDataByOffset- werden aus Gründen der Abwärtskompatibilität bereitgestellt, sollten jedoch nur verwendet werden, wenn die in Zugriff auf gerätekonfigurationsraum empfohlenen Methoden nicht verwendet werden können.

Diese Funktion ruft Informationen ab, beginnend beim Offset, über einen Steckplatz oder eine Adresse auf einem E/A-Bus.

Syntax

NTHALAPI ULONG HalGetBusDataByOffset(
  [in] BUS_DATA_TYPE BusDataType,
  [in] ULONG         BusNumber,
  [in] ULONG         SlotNumber,
  [in] PVOID         Buffer,
  [in] ULONG         Offset,
  [in] ULONG         Length
);

Parameter

[in] BusDataType

Busdaten, die abgerufen werden sollen. Die obere Grenze der unterstützten Bustypen ist immer MaximumBusDataType. Der einzige unterstützte BusDataType ist PCIConfiguration Alle anderen Typen sind veraltet.

[in] BusNumber

Nullbasierte und vom System zugewiesene Nummer des Busses in Systemen mit mehreren Bussen desselben BusDataType. Dieses Argument trägt auch die Segmentnummer. Verwenden Sie zum Angeben der Segmentnummer (Segment << 8) | BusNumber

[in] SlotNumber

Logische Steckplatznummer oder Position des Geräts. Wenn Sie PCIConfiguration als BusDataType angeben, handelt es sich bei diesem Wert um einen PCI_SLOT_NUMBER Wert, bei dem es sich um die kombinierten Steckplatz- und Funktionsnummern handelt.

[in] Buffer

Zeiger auf einen vom Aufrufer bereitgestellten Puffer für Konfigurationsinformationen, die für BusDataType spezifisch sind.

Wenn Sie PCIConfiguration angeben, enthält der Puffer die PCI-Konfigurationsrauminformationen für die angegebene SlotNumber und Funktionsnummer. Der angegebene Offset und die Länge bestimmen, wie viele Informationen bereitgestellt werden sollen. Bestimmte Member des PCI-Konfigurationsraums weisen schreibgeschützte Werte auf. Der Aufrufer ist dafür verantwortlich, die vom System bereitgestellten Werte von schreibgeschützten Membern beizubehalten. Beachten Sie, dass halSetBusDataByOffset für ein PCI-Gerät vom Typ 1 verhindert, dass Schreibvorgänge innerhalb des allgemeinen Headers registriert werden (erste 256BYTE des Konfigurationsraums).

[in] Offset

Byteoffset in der PCI_COMMON_CONFIG Struktur, für die die angeforderten Informationen zurückgegeben werden sollen. Anrufer können die vom System definierte Konstante PCI_COMMON_HDR_LENGTH verwenden, um den gerätespezifischen Bereich von PCI_COMMON_CONFIG anzugeben.

[in] Length

Maximale Anzahl von Bytes im Puffer.

Rückgabewert

Der Rückgabewert ist die tatsächliche Länge, die aus dem Konfigurationsbereich gelesen wird.

Bemerkungen

Gerätetreiber rufen diese Funktion während der Initialisierung auf, um ihre Geräte auf einem bestimmten E/A-Bus zu finden. Sie können die zurückgegebenen bustypspezifischen Konfigurationsdaten in späteren Aufrufen anderer Konfigurations- und Initialisierungsfunktionen wie HalTranslateBusAddress verwenden.

Beim Zugriff auf den gerätespezifischen Bereich des PCI-Konfigurationsraums garantiert HalGetBusDataByOffset, dass diese Funktion niemals Daten außerhalb des durch den Eingabeoffset und der Länge angegebenen Bereich liest oder schreibt. Auch wenn die Eingabelänge genau ein 1-Byte- oder 2-Byte-Wort ist, greift diese Funktion niemals auf Daten außerhalb des angeforderten Bereichs zu.