From 6e710426a4cf7020b3649e5a1b43d37e607fbcc6 Mon Sep 17 00:00:00 2001
From: Joel Challis <git@zvecr.com>
Date: Sat, 18 Jan 2020 01:56:33 +0000
Subject: [PATCH] Add docs for 'CUSTOM_MATRIX = lite' (#7906)

* Add some docs to cover 'CUSTOM_MATRIX = lite'

* Apply suggestions from code review

Co-Authored-By: fauxpark <fauxpark@gmail.com>

* Add 'SRC += matrix.c' docs

* Update docs/custom_matrix.md

Co-Authored-By: fauxpark <fauxpark@gmail.com>

Co-authored-by: fauxpark <fauxpark@gmail.com>
---
 docs/_summary.md                   |   1 +
 docs/custom_matrix.md              | 108 +++++++++++++++++++++++++++++
 docs/getting_started_make_guide.md |   2 +-
 3 files changed, 110 insertions(+), 1 deletion(-)
 create mode 100644 docs/custom_matrix.md

diff --git a/docs/_summary.md b/docs/_summary.md
index f6b03867fc..de81481382 100644
--- a/docs/_summary.md
+++ b/docs/_summary.md
@@ -105,6 +105,7 @@
   * [I2C Driver](i2c_driver.md)
   * [WS2812 Driver](ws2812_driver.md)
   * [GPIO Controls](internals_gpio_control.md)
+  * [Custom Matrix](custom_matrix.md)
   * [Proton C Conversion](proton_c_conversion.md)
 
 * For a Deeper Understanding
diff --git a/docs/custom_matrix.md b/docs/custom_matrix.md
new file mode 100644
index 0000000000..cfa900a33d
--- /dev/null
+++ b/docs/custom_matrix.md
@@ -0,0 +1,108 @@
+# Custom Matrix
+
+QMK provides a mechanism to supplement or replace the default matrix scanning routine with your own code.
+
+The reasons to use this feature include:
+
+* Extra hardware between the keyboard's switches and MCU pins
+  * I/O multiplexer
+  * Line decoder
+* Irregular switch matrix
+  * Simultaneous use of `COL2ROW` and `ROW2COL`
+
+## Prerequisites
+
+Implementing custom matrix usually involves compilation of an additional source file. It is recommended that for consistency, this file is called `matrix.c`.
+
+Add a new file to your keyboard directory:
+```text
+keyboards/<keyboard>/matrix.c
+```
+
+And to configure compilation for the new file, add this to your `rules.mk`:
+```make
+SRC += matrix.c
+```
+
+## 'lite'
+
+Provides a default implementation for various scanning functions, reducing the boilerplate code when implementing custom matrix.
+To configure it, add this to your `rules.mk`:
+
+```make
+CUSTOM_MATRIX = lite
+```
+
+And implement the following functions in a `matrix.c` file in your keyboard folder:
+
+```c
+void matrix_init_custom(void) {
+    // TODO: initialize hardware here
+}
+
+bool matrix_scan_custom(matrix_row_t current_matrix[]) {
+    bool matrix_has_changed = false;
+
+    // TODO: add matrix scanning routine here
+
+    return matrix_has_changed;
+}
+```
+
+
+## Full Replacement
+
+When more control over the scanning routine is required, you can choose to implement the full scanning routine.
+To configure it, add this to your rules.mk:
+
+```make
+CUSTOM_MATRIX = yes
+```
+
+And implement the following functions in a `matrix.c` file in your keyboard folder:
+
+```c
+matrix_row_t matrix_get_row(uint8_t row) {
+    // TODO: return the requested row data
+}
+
+void matrix_print(void) {
+    // TODO: use print() to dump the current matrix state to console
+}
+
+void matrix_init(void) {
+    // TODO: initialize hardware and global matrix state here
+
+    // Unless hardware debouncing - Init the configured debounce routine
+    debounce_init(MATRIX_ROWS);
+
+    // This *must* be called for correct keyboard behavior
+    matrix_init_quantum();
+}
+
+uint8_t matrix_scan(void) {
+    bool matrix_has_changed = false;
+
+    // TODO: add matrix scanning routine here
+
+    // Unless hardware debouncing - use the configured debounce routine
+    debounce(raw_matrix, matrix, MATRIX_ROWS, changed);
+
+    // This *must* be called for correct keyboard behavior
+    matrix_scan_quantum();
+
+    return matrix_has_changed;
+}
+```
+
+And also provide defaults for the following callbacks:
+
+```c
+__attribute__((weak)) void matrix_init_kb(void) { matrix_init_user(); }
+
+__attribute__((weak)) void matrix_scan_kb(void) { matrix_scan_user(); }
+
+__attribute__((weak)) void matrix_init_user(void) {}
+
+__attribute__((weak)) void matrix_scan_user(void) {}
+```
diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md
index bf8d472d0e..df82a001f0 100644
--- a/docs/getting_started_make_guide.md
+++ b/docs/getting_started_make_guide.md
@@ -135,7 +135,7 @@ As there is no standard split communication driver for ARM-based split keyboards
 
 `CUSTOM_MATRIX`
 
-Lets you replace the default matrix scanning routine with your own code. You will need to provide your own implementations of matrix_init() and matrix_scan().
+Lets you replace the default matrix scanning routine with your own code. For further details, see the [Custom Matrix page](custom_matrix.md).
 
 `DEBOUNCE_TYPE`