From b1c7303b0181b7de392bff0827321927338741f4 Mon Sep 17 00:00:00 2001 From: Eric-Paul Ickhorn Date: Fri, 23 Aug 2024 18:10:32 +0200 Subject: [PATCH] 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. --- i386/docs/drivers/interfaces/pci.md | 165 ++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 i386/docs/drivers/interfaces/pci.md diff --git a/i386/docs/drivers/interfaces/pci.md b/i386/docs/drivers/interfaces/pci.md new file mode 100644 index 0000000..e2bc0bd --- /dev/null +++ b/i386/docs/drivers/interfaces/pci.md @@ -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