au-ts · TristanCM347 · Dec 13, 2024 · Feb 23, 2025 · Mar 25, 2025 · Mar 25, 2025
diff --git a/drivers/gpio/README.md b/drivers/gpio/README.md
@@ -0,0 +1,70 @@
+<!--
+    Copyright 2024, UNSW
+
+    SPDX-License-Identifier: BSD-2-Clause
+-->
+
+
+# sddf-gpio-driver
+
+This repo contains a gpio (general purpose input and output) driver for the ODROID C4 Single Board Computer built over the seL4 Device Driver Framework. This class is structured to be as generic as possible for future extension to other devices.
+
+When a digtial I/O pin is not being used for any specific purpose (i2c, uart) it is implicitly converted to a GPIO pin.
+
+# USAGE!!!!!!!!!!! (IMPORTANT)
+There must be a configuration file that contains gpio_channel_mappings.
+
+Some registers have undefined permissions so it is the clients responsibility to check with a GET request after each SET request to make sure what they are trying to do actually is reflected in the register!
+
+Or check the datasheet (its wrong though sometimes).
+
+We could make the driver check on each set request as well and return an error if its writes arent showing up. **unimplemented**
+
+## Design
+- There is a single driver that controls all of both GPIO functionality and IRQ control.
+- No virtualiser and instead everything is assigned in the system file and config file.
+
+### Security
+Security is currently enforced by the system designer.
+There is no virtualiser to claim GPIO pins or IRQ channels.
+Instead each channel from the client to the driver is assigned to either one GPIO pin and optionally an IRQ channel.
+There is a gpio_config file where these details are specified.
+
+### Clients
+Clients PPC to the Driver in the channel associated with the GPIO or IRQ they want to configure.
+More details later in PPC Communication Section.
+
+### Driver
+The driver is responsible for hardware interaction. It directly interacts with the gpio hardware.
+It is also responsible for translating the requests from the client to perform the correct hardware interaction before returning if it was a success or failure.
+It also forwards IRQs to the correct client as well.
+
+### Transport
+All requests (both SET and GET) transport is done through PPCs.
+In the case where a client has subscribed to a certain IRQ,  when the device sends an IRQ to the driver, it is forwarded from driver to client.
+
+### Communication
+
+#### PPC
+Note: The exact capabilities of GPIOs vary between systems.
+Hence there is a common interface of labels, arguements, and formats that all GPIO drivers must understand.
+Then there are platform specific interfaces in a seperate per-platform header.
+
+Requests:
+
+Label = either GET_GPIO, SET_GPIO, GET_IRQ or SET_IRQ.
+Message Register 0 = The function we want to configure.
+Message Register 1 = The value we want to set the function to (only used in SETs)
+
+Responses
+Label = either SUCCESS or FAILURE
+Message Register 0 = either the Error that occured or the Value requested.
+
+Then set the arguements of the PPC to specifically describe what you want to do
+(outlined in include/sddf/gpio/gpio.h or include/sddf/gpio/{platform}/gpio.h depending on if its a common function or platform specific).
+
+Where to actually place the arguements in the ppcs is the same for every platform gpio driver
+(outlined in include/sddf/gpio/gpio.h).
+
+#### IRQ
+Irqs are recieved by driver and forwarded to associated client based on the config file.
diff --git a/drivers/gpio/imx/README.md b/drivers/gpio/imx/README.md
@@ -0,0 +1,67 @@
+<!--
+    Copyright 2024, UNSW
+
+    SPDX-License-Identifier: BSD-2-Clause
+-->
+
+# IMX8MDQLQRM GPIO Specifications
+
+## GPIO Output, Input and Configuration
+
+### GPIO Instances
+There are 5 GPIO instances each with varying amounts of ports(pins):
+- GPIO_1 : 0 - 29
+- GPIO_2 : 0 - 20
+- GPIO_3 : 0 - 25
+- GPIO_4 : 0 - 31
+- GPIO_5 : 0 - 29
+
+### Hardware Registers
+Each instance has an associated register to configure the respective functionality for any of its pins:
+- GPIO_DR is used to control the output of the pad, and read the input if direction is input.
+- GPIO_GDIR is used to change the direction.
+- GPIO_PSR is used to store the value of the corresponding input signal (if SION functionality is configured this will read the value of the pad even if mode is output or not GPIO).
+
+The are for special gpio functionalities which are controlled via other registers associated with IOXMUXC. **unimplemented**
+
+## GPIO IRQ Control
+
+### IRQ sources
+
+## IRQ sources
+There are 8 single interupt sources that can be configured only to GPIO1's 8 low order interrupt sources (i.e. GPIO1 interrupt n, for n = 0 – 7).
+
+- 56  : Active HIGH Interrupt from INT7 from GPIO
+- 57  : Active HIGH Interrupt from INT6 from GPIO
+- 58  : Active HIGH Interrupt from INT5 from GPIO
+- 59  : Active HIGH Interrupt from INT4 from GPIO
+- 60  : Active HIGH Interrupt from INT3 from GPIO
+- 61  : Active HIGH Interrupt from INT2 from GPIO
+- 62  : Active HIGH Interrupt from INT1 from GPIO
+- 63  : Active HIGH Interrupt from INT0 from GPIO
+
+There are also 10 combined interupt sources that can be configured to pins in the specified range for a specified instance.
+
+- 64  : Combined interrupt indication for GPIO1 signal 0 throughout 15
+- 65  : Combined interrupt indication for GPIO1 signal 16 throughout 31
+- 66  : Combined interrupt indication for GPIO2 signal 0 throughout 15
+- 67  : Combined interrupt indication for GPIO2 signal 16 throughout 31O
+- 68  : Combined interrupt indication for GPIO3 signal 0 throughout 15
+- 69  : Combined interrupt indication for GPIO3 signal 16 throughout 31
+- 70  : Combined interrupt indication for GPIO4 signal 0 throughout 15O
+- 71  : Combined interrupt indication for GPIO4 signal 16 throughout 31
+- 72  : Combined interrupt indication for GPIO5 signal 0 throughout 15
+- 73  : Combined interrupt indication for GPIO5 signal 16 throughout 31
+
+### Hardware Registers
+The 8 single interupt sources are active high and cannot be configured.
+
+The 10 combined interrupt sources are configured directly through the pins that are on that line:
+- GPIOx_ICR1 is used to configure interrupt configuration on the corresponding input signal.
+- GPIOx_ICR2 is used to configure interrupt configuration on the corresponding input signal.
+- GPIOx_IMR is used to mask(disable) the interupt on the corresponding input signal.
+- GPIOx_EDGE_SEL is used to configure any edge on the corresponding input signal.
+
+## SPECIAL NOTES
+
+