This is an old version from the tos.hyp. The new is on GitHub!

HomeXBIOSOverScan XBIOS extensionInterface programming

4.16 PCI-BIOS

• fast_read_config_byte Read configuration byte fast
• fast_read_config_longword Read configuration longword fast
• fast_read_config_word Read configuration word fast
• find_pci_classcode Find PCI class code
• find_pci_device Find PCI device
• get_machine_id Get machine ID
• get_resource Get resource Data
• get_routing Get interrupt routing options
• hook_interrupt Hook interrupt vector
• read_config_byte Read configuration byte
• read_config_longword Read configuration longword
• read_config_word Read configuration word
• set_interrupt Set hardware interrupt
• special_cycle Generates special cycle
• unhook_interrupt Unhook interrupt vector
• write_config_byte Write configuration byte
• write_config_longword Write configuration longword
• write_config_word Write configuration word

See also: PCI-BIOS Error codes   Cookie _PCI   Cookie XPCI

4.16.1 fast_read_config_byte

Name: »Read configuration byte fast«
Opcode: 305
Syntax: int8_t fast_read_config_byte (int32_t handle, uint8_t reg);
Description: This function reads data from the PCI configuration space of a given card. It does only minimal error checking and is meant to be used only when access to configuration space is needed in interrupt handlers.
handle device handle
reg Register number (0,1,2,... for byte access)
Return value:
Availability: PCI-BIOS 2.0
Group: PCI-BIOS
See also: Binding   read_config_byte   read_config_word   fast_read_config_word   read_config_longword   fast_read_config_longword

4.16.1.1 Bindings for fast_read_config_byte

C: #include

int8_t fast_read_config_byte (int32_t handle, uint8_t reg);
Assembler: 
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #305,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #7,sp         ; Correct stack

4.16.2 fast_read_config_longword

Name: »Read configuration longword fast«
Opcode: 307
Syntax: int32_t fast_read_config_longword (int32_t handle, uint8_t reg);
Description: This function reads data from the PCI configuration space of a given card. It does only minimal error checking and is meant to be used only when access to configuration space is needed in interrupt handlers.
handle Device handle
reg Register number (0,4,8,... for longword access)
Return value:
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   read_config_byte   fast_read_config_byte   read_config_word   fast_read_config_word   read_config_longword

4.16.2.1 Bindings for fast_read_config_longword

C: #include

int32_t fast_read_config_longword (int32_t handle, uint8_t reg);
Assembler: 
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #307,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #7,sp         ; Correct stack

4.16.3 fast_read_config_word

Name: »Read configuration word fast«
Opcode: 306
Syntax: int16_t fast_read_config_word (int32_t handle, uint8_t reg);
Description: This function reads data from the PCI configuration space of a given card. It does only minimal error checking and is meant to be used only when access to configuration space is needed in interrupt handlers.
handle Device handle
reg Register number (0,2,4,... for Word access)
Return value:
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   read_config_byte   fast_read_config_byte   read_config_word   read_config_longword   fast_read_config_longword

4.16.3.1 Bindings for fast_read_config_word

C: #include

int16_t fast_read_config_word (int32_t handle, uint8_t reg);
Assembler: 
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #306,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #7,sp         ; Correct stack

4.16.4 find_pci_classcode

Name: »find_pci_classcode« - Returns a device handle for a device that matches the given class code.
Opcode: 301
Syntax: int32_t find_pci_classcode( int32_t classcode, int16_t index );
Description: This functions returns a device handle for a device that matches the given class code.

A driver can query multiple devices with the same class code by starting with index = 0,1,2,... and calling this function until PCI_DEVICE_NOT_FOUND is returned.
   
classcode class code in bits 23..0


Bit 23 ..16 Base class (0 - $FF)
Bit 15 .. 8 Sub class (0 - $FF)
Bit 7 .. 0 Programming Interface (0 - $FF)

Mask in bits 26..24
Bit 26: (0: compare base class, 1: ignore it)
Bit 25: (0: compare sub class, 1: ignore it)
Bit 24: (0: compare Progr. Interface, 1: ignore it)
index index of card (0 - number of cards with these IDs)
Return value: Device handle for a device or PCI_DEVICE_NOT_FOUND.
Availability: PCI-BIOS V2.00
Group: PCI-BIOS
See also: Binding   find_pci_device

4.16.4.1 Bindings for find_pci_classcode

C: #include

int32_t find_pci_classcode( int32_t classcode, int16_t index );
Assembler: 
move.w    index,-(sp)       ; Offset 6
move.l    classcode,-(sp)   ; Offset 2
move.w    #301,-(sp)        ; Offset 0
trap      #14               ; Call XBIOS
addq.l    #8,sp             ; Correct stack

4.16.5 find_pci_device

Name: »find_pci_device« - Returns a device handle for a device that matches the given device and vendor ID.
Opcode: 300
Syntax: int32_t find_pci_device( int32_t id, int16_t index);
Description: This functions returns a device handle for a device that matches the given device and vendor ID. A driver can query multiple devices with the same device and vendor ID by starting with index = 0,1,2,... and calling this function until PCI_DEVICE_NOT_FOUND is returned.

As a special case, Vendor ID $FFFF can be used to query all cards found in the system, the specified Device ID is ignored in that case.
   
id Device ID in bits 31..16 (0 - $FFFF)
Vendor ID in bits 15..0 (0 - $FFFE)
index Index of card (0 - number of cards with these IDs)
Return value: Device handle for a device or PCI_DEVICE_NOT_FOUND.
Availability: PCI-BIOS V2.00
Group: PCI-BIOS
See also: Binding   find_pci_classcode

4.16.5.1 Bindings for find_pci_device

C: #include

int32_t find_pci_device( int32_t id, int16_t index);
Assembler: 
move.w    index,-(sp)  ; Offset 6
move.l    id,-(sp)     ; Offset 2
move.w    #300,-(sp)   ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #8,sp        ; Correct stack

4.16.6 get_machine_id

Name: »Get Machine ID«
Opcode: 337
Syntax: int32_t get_machine_id ( void );
Description: This function can be used to get a unique machine ID for the computer the driver is running on.
Return value: Machine ID, or 0 (no ID available), PCI-BIOS error-codes

Positive, non-zero values are machine IDs. They contain a manufacturer code in bit 24..31 and a unique serial number which is set by the manufacturer during production in bit 0..23.

The following manufacturer codes are defined:

0 Medusa/Hades
1 Milan
2 PAK/Panther 2
3 ARAnyM
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding

4.16.6.1 Bindings for get_machine_id

C: #include

int32_t get_machine_id ( void );
Assembler: 
move.w    #337,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #2,sp         ; Correct stack

4.16.7 get_resource

Name: »Get Resource Data«
Opcode: 316
Syntax: int32_t get_resource ( int32_t handle );
Description:
handle Device handle
Return value: Pointer to array of resource descriptors or PCI-BIOS error-codes.
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding

4.16.7.1 Bindings for get_resource

C: #include

int32_t get_resource ( int32_t handle );
Assembler: 
move.l    handle,-(sp)  ; Offset 2
move.w    #316,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #6,sp         ; Correct stack

4.16.8 get_routing

Name: »Get Interrupt Routing Options«
Opcode: 314
Syntax: int32_t get_routing ( int32_t handle );
Description: To be defined. Not for use by device drivers.
Return value: PCI-BIOS error-codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding

4.16.8.1 Bindings for get_routing

C: #include

int32_t get_routing ( int32_t handle );
Assembler: 
move.l    handle,-(sp)    ; Offset 2
move.w    #314,-(sp)      ; Offset 0
trap      #14             ; Call XBIOS
addq.l    #6,sp           ; Correct stack

4.16.9 hook_interrupt

Name: »Hook Interrupt Vector«
Opcode: 311
Syntax: int32_t hook_interrupt (int32_t handle, uint32_t *routine, uint32_t *parameter);
Description: This function hooks the driver into the interrupt chain to which a specific interrupt on the given card is routed. The interrupt is enabled on the system level, however, it is the drivers responsibility to enable the interrupt on the card as needed.

The driver should first hook into the interrupt chain, and then enable the interrupt on the card, in order not to cause spurious interrupts.
handle Device handle
routine Pointer to interrupt handler
parameter Parameter for interrupt handler

The parameter is passed to the interrupt handler unmodified - its meaning is totally driver dependent.
Return value: PCI-BIOS Error codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   unhook_interrupt

4.16.9.1 Bindings for hook_interrupt

C: #include

int32_t hook_interrupt (int32_t handle, uint32_t *routine, uint32_t *parameter);
Assembler: 
move.l    parameter,-(sp) ; Offset 10
move.l    routine,-(sp)   ; Offset 6
move.l    handle,-(sp)    ; Offset 2
move.w    #311,-(sp)      ; Offset 0
trap      #14             ; Call XBIOS
addq.l    #14,sp          ; Correct stack

4.16.10 read_config_byte

Name: »Read configuration byte«
Opcode: 302
Syntax: int32_t read_config_byte (int32_t handle, uint8_t reg, uint8_t *address);
Description: This function read data from the PCI configuration space of a given card.
handle Device handle
reg Register number (0,1,2,... for Byte access)
address Pointer to space for read data
Return value: PCI-BIOS Error codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   fast_read_config_byte   read_config_word   fast_read_config_word   read_config_longword   fast_read_config_longword

4.16.10.1 Bindings for read_config_byte

C: #include

int32_t fast_read_config_byte (int32_t handle, uint8_t reg, uint8_t *address);
Assembler: 
pea       address,-(sp) ; Offset 8
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #302,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #11,sp        ; Correct stack

4.16.11 read_config_longword

Name: »Read configuration longword«
Opcode: 304
Syntax: int32_t read_config_longword (int32_t handle, uint8_t reg, uint32_t *address);
Description: This function read data from the PCI configuration space of a given card.
handle Device handle
reg Register number (0,4,8,... for Longword access)
address Pointer to space for read data
Return value: PCI-BIOS Error codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   read_config_byte   fast_read_config_byte   read_config_word   fast_read_config_word   fast_read_config_longword

4.16.11.1 Bindings for read_config_longword

C: #include

int32_t read_config_longword (int32_t handle, uint8_t reg, uint32_t *address);
Assembler: 
pea       address,-(sp) ; Offset 8
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #304,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #11,sp        ; Correct stack

4.16.12 read_config_word

Name: »Read configuration word«
Opcode: 303
Syntax: int32_t read_config_word (int32_t handle, uint8_t reg, uint16_t *address);
Description: This function read data from the PCI configuration space of a given card.
handle Device handle of the selected PCI device
reg Address of the configuration register
address Pointer to space for read data
Return value: PCI-BIOS Error codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   read_config_byte   fast_read_config_byte   fast_read_config_word   read_config_longword   fast_read_config_longword

4.16.12.1 Bindings for read_config_word

C: #include

int32_t read_config_word (int32_t handle, uint8_t reg, uint16_t *address);
Assembler: 
pea       address,-(sp) ; Offset 8
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #303,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #11,sp        ; Correct stack

4.16.13 set_interrupt

Name: »Set Hardware Interrupt«
Opcode: 315
Syntax: int32_t set_interrupt ( int32_t handle );
Description: To be defined. Not for use by device drivers.
Return value: PCI-BIOS Error codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding

4.16.13.1 Bindings for set_interrupt

C: #include

int32_t set_interrupt ( int32_t handle );
Assembler: 
move.l    handle,-(sp)    ; Offset 2
move.w    #315,-(sp)      ; Offset 0
trap      #14             ; Call XBIOS
addq.l    #6,sp           ; Correct stack

4.16.14 special_cycle

Name: »Generates special cycle«
Opcode: 313
Syntax: int32_t special_cycle ( unit8_t bus, uint32_t data );
Description: This function generates a special cycle on the PCI bus.
handle Bus number
data Cspecial cycle data
Return value: PCI-BIOS Error codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding

4.16.14.1 Bindings for special_cycle

C: #include

int32_t special_cycle ( unit8_t bus, uint32_t data );
Assembler: 
move.l    data,-(sp)    ; Offset 3
move.b    bus,-(sp)     ; Offset 2
move.w    #313,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #7,sp         ; Correct stack

4.16.15 unhook_interrupt

Name: » «
Opcode: 312
Syntax: int32_t unhook_interrupt (int32_t handle);
Description: This function removes the driver from the interrupt chain to which a specific interrupt on the given card is routed. The driver must turn off interrupt generation on the card before calling this function.
handle Device handle
Return value: PCI-BIOS Error codes
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   hook_interrupt

4.16.15.1 Bindings for unhook_interrupt

C: #include

int32_t unhook_interrupt (int32_t handle);
Assembler: 
move.l    handle,-(sp)  ; Offset 2
move.w    #312,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #6,sp         ; Correct stack

4.16.16 write_config_byte

Name: »Write configuration byte«
Opcode: 308
Syntax: int32_t write_config_byte (int32_t handle, uint8_t reg, uint8_t val);
Description: This function writes data to the PCI configuration space of a given card.

The data is in little endian format, as described in the PCI specification.
handle Device handle
reg Register number (0,1,2,... for byte access)
val Data to write (8 bits)
Return value:
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   write_config_word   write_config_longword   read_config_byte   read_config_word   read_config_longword

4.16.16.1 Bindings for write_config_byte

C: #include

int32_t write_config_byte (int32_t handle, uint8_t reg, uint8_t val);
Assembler: 
move.b    val,-(sp)     ; Offset 7
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #308,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #8,sp         ; Correct stack

4.16.17 write_config_longword

Name: »Write configuration longword«
Opcode: 310
Syntax: int32_t write_config_longword (int32_t handle, uint8_t reg, uint32_t val);
Description: This function writes data to the PCI configuration space of a given card.

The data is in little endian format, as described in the PCI specification.
handle Device handle
reg Register number (0,4,8,... for Longword access)
val Data to write (32 bits)
Return value:
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   write_config_byte   write_config_word   read_config_byte   read_config_word   read_config_longword

4.16.17.1 Bindings for write_config_longword

C: #include

int32_t write_config_longword (int32_t handle, uint8_t reg, uint32_t val);
Assembler: 
move.l    val,-(sp)     ; Offset 7
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #310,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #11,sp        ; Correct stack

4.16.18 write_config_word

Name: »Write configuration word«
Opcode: 309
Syntax: int32_t write_config_word (int32_t handle, uint8_t reg, uint16_t val);
Description: This function writes data to the PCI configuration space of a given card.

The data is in little endian format, as described in the PCI specification.
handle Device handle
reg Register number (0,2,4,... for Word access)
val Data to write (16 bits)
Return value:
Availability: PCI-BIOS
Group: PCI-BIOS
See also: Binding   write_config_byte   write_config_longword   read_config_byte   read_config_word   read_config_longword

4.16.18.1 Bindings for write_config_word

C: #include

int32_t write_config_word (int32_t handle, uint8_t reg, uint16_t val);
Assembler: 
move.w    val,-(sp)     ; Offset 7
move.b    reg,-(sp)     ; Offset 6
move.l    handle,-(sp)  ; Offset 2
move.w    #309,-(sp)    ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #9,sp         ; Correct stack

4.16.19 PCI-BIOS Error codes

The following error codes can be returned by the PCI BIOS functions:

0x00000000 PCI_SUCCESSFUL
0xFFFFFFFE PCI_FUNC_NOT_SUPPORTED
0xFFFFFFFD PCI_BAD_VENDOR_ID
0xFFFFFFFC PCI_DEVICE_NOT_FOUND
0xFFFFFFFB PCI_BAD_REGISTER_NUMBER
0xFFFFFFFA PCI_SET_FAILED
0xFFFFFFF9 PCI_BUFFER_TOO_SMALL
0xFFFFFFF8 PCI_GENERAL_ERROR
0xFFFFFFF7 PCI_BAD_HANDLE

The following error codes are not returned by PCI BIOS functions directly, but are reserved for use by a library which uses these routines.

0xFFFFF001 PCI_BIOS_NOT_INSTALLED
0xFFFFF000 PCI_BIOS_WRONG_VERSION
HomeXBIOSOverScan XBIOS extensionInterface programming