From a4d48780f313a952f286b0526a337b3d67bdd3b8 Mon Sep 17 00:00:00 2001
From: antifallobst <antifallobst@systemausfall.org>
Date: Mon, 1 May 2023 01:28:55 +0200
Subject: [PATCH] noxos (docs): documented PS/2

---
 .../noxos/docs/codebase/drivers/ps2.md        |  4 ++
 .../noxos/docs/codebase/drivers/ps2/_index.md |  6 +++
 .../docs/codebase/drivers/ps2/controller.h.md | 39 +++++++++++++++++++
 .../docs/codebase/drivers/ps2/keyboard.h.md   | 24 ++++++++++++
 .../docs/codebase/drivers/ps2/scancodes.h.md  |  7 ++++
 5 files changed, 80 insertions(+)
 create mode 100644 content/projects/noxos/docs/codebase/drivers/ps2.md
 create mode 100644 content/projects/noxos/docs/codebase/drivers/ps2/_index.md
 create mode 100644 content/projects/noxos/docs/codebase/drivers/ps2/controller.h.md
 create mode 100644 content/projects/noxos/docs/codebase/drivers/ps2/keyboard.h.md
 create mode 100644 content/projects/noxos/docs/codebase/drivers/ps2/scancodes.h.md

diff --git a/content/projects/noxos/docs/codebase/drivers/ps2.md b/content/projects/noxos/docs/codebase/drivers/ps2.md
new file mode 100644
index 0000000..45621eb
--- /dev/null
+++ b/content/projects/noxos/docs/codebase/drivers/ps2.md
@@ -0,0 +1,4 @@
+---
+title: "ps2"
+summary: "The PS/2 standard for communicating with keyboards and mice"
+---
\ No newline at end of file
diff --git a/content/projects/noxos/docs/codebase/drivers/ps2/_index.md b/content/projects/noxos/docs/codebase/drivers/ps2/_index.md
new file mode 100644
index 0000000..d9e0d0e
--- /dev/null
+++ b/content/projects/noxos/docs/codebase/drivers/ps2/_index.md
@@ -0,0 +1,6 @@
+---
+title: "ps2"
+---
+
+The PS/2 standard for communicating with keyboards and mice.
+
diff --git a/content/projects/noxos/docs/codebase/drivers/ps2/controller.h.md b/content/projects/noxos/docs/codebase/drivers/ps2/controller.h.md
new file mode 100644
index 0000000..b8af3eb
--- /dev/null
+++ b/content/projects/noxos/docs/codebase/drivers/ps2/controller.h.md
@@ -0,0 +1,39 @@
+---
+title: "controller.h"
+summary: "Communicates with the PS/2 controller chip"
+---
+
+**Warning:** This whole code needs to be reworked!
+
+# `PS2_CONTROLLER_DATA_PORT` - macro
+The data transmission IO port.
+
+# `PS2_CONTROLLER_STATUS_PORT` - macro
+The Status register IO port.
+
+# `PS2_CONTROLLER_COMMAND_PORT` - macro
+The command transmission IO port.
+
+# `PS2_CONTROLLER_TIMEOUT` - macro
+The amount of cycles the system waits for the controller before cancelling an operation.
+
+# `ps2_controller_init()` - function (void)
+Initializes the PS/2 controller and devices.
+At the moment it trusts very much stuff blindly.
+This needs to be changed.
+The osdev wiki has a list of stuff to do while initializing PS/2.
+
+# `ps2_controller_command(command)` - function (uint8_t)
+Sends the PS/2 controller a command.
+
+# `ps2_controller_command_with_data(command, data)` - function (uint8_t)
+Sends the PS/2 controller a command that needs additional data on the data port.
+
+# `ps2_controller_wait_until_ready_for_input()` - function (bool)
+Halts until the status register says that there can be data read, or the timeout is reached.
+
+# `ps2_controller_wait_until_ready_for_output()` - function (bool)
+Halts until the status register says that there can be data written, or the timeout is reached.
+
+# `ps2_controller_read_data()` - function (uint8_t)
+Reads data from the PS/2 controller.
\ No newline at end of file
diff --git a/content/projects/noxos/docs/codebase/drivers/ps2/keyboard.h.md b/content/projects/noxos/docs/codebase/drivers/ps2/keyboard.h.md
new file mode 100644
index 0000000..66ba304
--- /dev/null
+++ b/content/projects/noxos/docs/codebase/drivers/ps2/keyboard.h.md
@@ -0,0 +1,24 @@
+---
+title: "keyboard.h"
+summary: "The driver for PS/2 keyboards"
+---
+
+# `ps2_keyboard_command_E` - enum
+Commands that can be issued to the keyboard.
+
+# `ps2_keyboard_response_E` - enum
+Responses that a keyboard can reply on a command.
+
+# `ps2_keyboard_command(command, data)` - function (uint8_t)
+Sends a command to the keyboard.
+
+# `ps2_keyboard_init()` - function (void)
+Initializes the keyboard driver.
+This should only be called by the PS/2 controller init function.
+
+# `ps2_keyboard_read()` - function (void)
+Reads a key from the keyboard and writes it to the tty.
+This should be called when IRQ1 is fired.
+
+# `ps2_keyboard_command_to_string(command)` - function (string_t)
+Returns a matching string for **_command_** in `ps2_keyboard_command_E`.
diff --git a/content/projects/noxos/docs/codebase/drivers/ps2/scancodes.h.md b/content/projects/noxos/docs/codebase/drivers/ps2/scancodes.h.md
new file mode 100644
index 0000000..d4bd7c4
--- /dev/null
+++ b/content/projects/noxos/docs/codebase/drivers/ps2/scancodes.h.md
@@ -0,0 +1,7 @@
+---
+title: "scancodes.h"
+summary: "key mapping definitions"
+---
+
+This holds definitions on which key is mapped to which scancode.
+Currently only scancode set 1 is supported.