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