# 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