Document PCI driver API
The PCI driver API is now documented, the documentation explains which functions have to exist in a driver for it to be recognized as capable of being used as default PCI driver. Some functions, namely those for interacting with a device, are not documented yet because there is also no code for that yet. The functions that need to be supported may increase, but a a decrease is relatively unlikely.
This commit is contained in:
parent
21c873a8f5
commit
b1c7303b01
|
|
@ -0,0 +1,165 @@
|
||||||
|
# Driver Definition | PCI
|
||||||
|
|
||||||
|
## Functions
|
||||||
|
|
||||||
|
| Category | Function | Function Name |
|
||||||
|
| --------- | --------- | -------------------------------------- |
|
||||||
|
| 0x10 | 0x00 | init_driver |
|
||||||
|
| 0x10 | 0x01 | reset_driver |
|
||||||
|
| 0x10 | 0x02 | cleanup_driver |
|
||||||
|
| 0x10 | 0x05 | count_devices |
|
||||||
|
| 0x10 | 0x06 | create_device_list |
|
||||||
|
| 0x10 | 0x07 | delete_device_list |
|
||||||
|
| 0x10 | 0x08 | next_device_in_list |
|
||||||
|
| 0x10 | 0x09 | rewind_device_list |
|
||||||
|
| 0x10 | 0x0a | run_filter |
|
||||||
|
| 0x10 | 0x10 | set_device_register |
|
||||||
|
| 0x10 | 0x11 | get_device_register |
|
||||||
|
| 0x10 | 0x12 | send_to_device |
|
||||||
|
| 0x10 | 0x13 | receive_from_device |
|
||||||
|
|
||||||
|
> All of these functions have to be implemented for the driver to be
|
||||||
|
> recognized as PCI driver and to make it a viable option as the
|
||||||
|
> default PCI driver for the bootup process.
|
||||||
|
|
||||||
|
### 0x00: init_driver
|
||||||
|
|
||||||
|
Initializes the driver. Only used in the internal procedures of the
|
||||||
|
PCI interaction code.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (Empty) Driver Slot Pointer
|
||||||
|
|
||||||
|
### 0x02: reset_driver
|
||||||
|
|
||||||
|
Sets back the driver to the initial state. This will be called when
|
||||||
|
the driver misbehaves in a way that indicates a bug.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
|
||||||
|
### 0x03: cleanup_driver
|
||||||
|
|
||||||
|
As counterpart to `init_driver`, this function frees the resources of
|
||||||
|
the PCI driver it's called on. The driver shouldn't work after this
|
||||||
|
has been called because all of the items it needs for working should
|
||||||
|
have been deleted.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
|
||||||
|
### 0x05: count_devices
|
||||||
|
|
||||||
|
Retrieves the number of devices that the PCI driver found during the
|
||||||
|
enumeration in the initialization phase.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
|
||||||
|
Result:
|
||||||
|
|
||||||
|
- EAX: Number of devices in the host computer.
|
||||||
|
|
||||||
|
### 0x06: create_device_list
|
||||||
|
|
||||||
|
Creates an opaque structure that contains a filter-able list of
|
||||||
|
devices and is represented by a 4-byte identifier. When using the
|
||||||
|
driver, the 4-byte identifier should be the only thing that is needed
|
||||||
|
for handling device lists.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
|
||||||
|
Result:
|
||||||
|
|
||||||
|
- EAX: Device List Identifier
|
||||||
|
|
||||||
|
|
||||||
|
### 0x07: delete_device_list
|
||||||
|
|
||||||
|
Deletes the driver-internal structure(s) related to the device *list*.
|
||||||
|
The devices should be stored seperately so that they can be accessed
|
||||||
|
and used even if the list they were gotten from has been deleted.
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
1. Device List Identifier
|
||||||
|
|
||||||
|
### 0x08: next_device_in_list
|
||||||
|
|
||||||
|
Goes one device further in the device list and returns another integer
|
||||||
|
identifying the device's (*not* the device *list*'s) opaque structure.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
1. Device List Identifier
|
||||||
|
|
||||||
|
Result:
|
||||||
|
|
||||||
|
- EAX: Next device's identifier
|
||||||
|
|
||||||
|
### 0x09: rewind_device_list
|
||||||
|
|
||||||
|
Goes back some amount of devices in the device list.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
1. Device List Identifier
|
||||||
|
2. Amount of devices to rewind
|
||||||
|
If the amount of devices to rewind is bigger or equal to the amount
|
||||||
|
of devices, the driver should rewind the list back to the start.
|
||||||
|
|
||||||
|
### 0x0a: run_filter
|
||||||
|
|
||||||
|
Runs a filter function that returns either TRUE or FALSE depending on
|
||||||
|
whether the device should stay in the list the filter was run on or
|
||||||
|
if the device should be thrown out the list.
|
||||||
|
|
||||||
|
Inputs:
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
1. Device List Identifier
|
||||||
|
2. Filter-Function Pointer
|
||||||
|
|
||||||
|
Result:
|
||||||
|
|
||||||
|
- EAX: Number of remaining devices in the list
|
||||||
|
|
||||||
|
#### Filter Function
|
||||||
|
|
||||||
|
Every function for which a pointer is given to this function has the
|
||||||
|
following inputs from 0 (nearest to EBP) to 3 (furthest from EBP):
|
||||||
|
|
||||||
|
0. (PCI) Driver Slot Pointer
|
||||||
|
1. Device List Identifier
|
||||||
|
2. Device List index
|
||||||
|
3. Device Identifier
|
||||||
|
|
||||||
|
The call to the function could thus be written in Assembly like in
|
||||||
|
the following code block:
|
||||||
|
|
||||||
|
```x86
|
||||||
|
push ebp
|
||||||
|
mov ebp, esp
|
||||||
|
push ebx
|
||||||
|
push ecx
|
||||||
|
push edi
|
||||||
|
push edx
|
||||||
|
call eax
|
||||||
|
mov esp, ebp
|
||||||
|
pop ebp
|
||||||
|
```
|
||||||
|
|
||||||
|
Assuming that when entering that snippet, the registers contain the
|
||||||
|
following information:
|
||||||
|
- **EAX**: function pointer
|
||||||
|
- **EBX**: driver slot
|
||||||
|
- **ECX**: device list identifier
|
||||||
|
- **EDX**: device identifier
|
||||||
|
- **EDI**: device list index
|
||||||
Loading…
Reference in New Issue