X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=readme.md;h=0157b907248af00b7d021a6b9f1a075c9ac37b76;hb=b94e5b2aa6636326b2eaa75a2c562ea074e1535a;hp=62d479ff1dfbdb1242bd394042d3f18c4edb8d4e;hpb=55b8b8477cc6aee82dfe6792eea4e589cac433d5;p=qmk_firmware.git

diff --git a/readme.md b/readme.md
index 62d479ff1..0157b9072 100644
--- a/readme.md
+++ b/readme.md
@@ -241,6 +241,7 @@ You can also add extra options at the end of the make command line, after the ta
 * `make COLOR=false` - turns off color output
 * `make SILENT=true` - turns off output besides errors/warnings
 * `make VERBOSE=true` - outputs all of the gcc stuff (not interesting, unless you need to debug)
+* `make EXTRAFLAGS=-E` - Preprocess the code without doing any compiling (useful if you are trying to debug #define commands)
 
 The make command itself also has some additional options, type `make --help` for more information. The most useful is probably `-jx`, which specifies that you want to compile using more than one CPU, the `x` represents the number of CPUs that you want to use. Setting that can greatly reduce the compile times, especially if you are compiling many keyboards/keymaps. I usually set it to one less than the number of CPUs that I have, so that I have some left for doing other things while it's compiling. Note that not all operating systems and make versions supports that option.
 
@@ -326,8 +327,14 @@ This allows you to send unicode symbols via `UC(<unicode>)` in your keymap. Only
 `UNICODEMAP_ENABLE`
 
 This allows sending unicode symbols using `X(<unicode>)` in your keymap. Codes
-up to 0xFFFFF are supported, including emojis. But you need to maintain a
-separate mapping table in your keymap file.
+up to 0xFFFFFFFF are supported, including emojis. You will need to maintain
+a separate mapping table in your keymap file.
+
+Known limitations:
+- Under Mac OS, only codes up to 0xFFFF are supported.
+- Under Linux ibus, only codes up to 0xFFFFF are supported (but anything important is still under this limit for now).
+
+Characters out of range supported by the OS will be ignored.
 
 `BLUETOOTH_ENABLE`
 
@@ -337,6 +344,10 @@ This allows you to interface with a Bluefruit EZ-key to send keycodes wirelessly
 
 This allows you output audio on the C6 pin (needs abstracting). See the [audio section](#driving-a-speaker---audio-support) for more information.
 
+`VARIABLE_TRACE`
+
+Use this to debug changes to variable values, see the [tracing variables](#tracing-variables) section for more information.
+
 ### Customizing Makefile options on a per-keymap basis
 
 If your keymap directory has a file called `Makefile` (note the filename), any Makefile options you set in that file will take precedence over other Makefile options for your particular keyboard.
@@ -900,7 +911,7 @@ In `quantum/keymap_extras/`, you'll see various language files - these work the
 
 ## Unicode support
 
-You can currently send 4 hex digits with your OS-specific modifier key (RALT for OSX with the "Unicode Hex Input" layout) - this is currently limited to supporting one OS at a time, and requires a recompile for switching. 8 digit hex codes are being worked on. The keycode function is `UC(n)`, where *n* is a 4 digit hexidecimal. Enable from the Makefile.
+You can currently send 4 hex digits with your OS-specific modifier key (RALT for OSX with the "Unicode Hex Input" layout, see [this article](http://www.poynton.com/notes/misc/mac-unicode-hex-input.html) to learn more) - this is currently limited to supporting one OS at a time, and requires a recompile for switching. 8 digit hex codes are being worked on. The keycode function is `UC(n)`, where *n* is a 4 digit hexidecimal. Enable from the Makefile.
 
 ## Backlight Breathing
 
@@ -1146,6 +1157,45 @@ The firmware supports 5 different light effects, and the color (hue, saturation,
 
 Please note the USB port can only supply a limited amount of power to the keyboard (500mA by standard, however, modern computer and most usb hubs can provide 700+mA.). According to the data of NeoPixel from Adafruit, 30 WS2812 LEDs require a 5V 1A power supply, LEDs used in this mod should not more than 20.
 
+## PS/2 Mouse Support
+
+Its possible to hook up a PS/2 mouse (for example touchpads or trackpoints) to your keyboard as a composite device.
+In order to do this you must first enable the option in your Makefile.
+
+    PS2_MOUSE_ENABLE = yes
+
+Then, decide whether to use interrupts (better if your microcontroller supports them) or busywait, and enable the relevant option.
+
+    PS2_USE_INT = yes
+    // PS2_USE_BUSYWAIT = yes
+
+If you're using a teensy and have hooked up the clock on your PS/2 device to D1 and the data to D0, you're all set.
+Otherwise, you will need to update the following defines in your `config.h`:
+    
+    #define PS2_CLOCK_PORT  PORTD
+    #define PS2_CLOCK_PIN   PIND
+    #define PS2_CLOCK_DDR   DDRD
+    #define PS2_CLOCK_BIT   1
+
+    #define PS2_DATA_PORT   PORTD
+    #define PS2_DATA_PIN    PIND
+    #define PS2_DATA_DDR    DDRD
+    #define PS2_DATA_BIT    0
+
+And with `PS2_USE_INT` also define these macros:
+
+    #define PS2_INT_INIT()  do {    \
+        EICRA |= ((1<<ISC11) |      \
+                  (0<<ISC10));      \
+    } while (0)
+    #define PS2_INT_ON()  do {      \
+        EIMSK |= (1<<INT1);         \
+    } while (0)
+    #define PS2_INT_OFF() do {      \
+        EIMSK &= ~(1<<INT1);        \
+    } while (0)
+    #define PS2_INT_VECT    INT1_vect
+
 ## Safety Considerations
 
 You probably don't want to "brick" your keyboard, making it impossible
@@ -1277,3 +1327,22 @@ If there are problems with the tests, you can find the executable in the `./buil
 It's not yet possible to do a full integration test, where you would compile the whole firmware and define a keymap that you are going to test. However there are plans for doing that, because writing tests that way would probably be easier, at least for people that are not used to unit testing.
 
 In that model you would emulate the input, and expect a certain output from the emulated keyboard.
+
+# Tracing variables 
+
+Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both for variables that are changed by the code, and when the variable is changed by some memory corruption.
+
+To take the feature into use add `VARIABLE_TRACE=x` to the end of you make command. `x` represents the number of variables you want to trace, which is usually 1. 
+
+Then at a suitable place in the code, call `ADD_TRACED_VARIABLE`, to begin the tracing. For example to trace all the layer changes, you can do this
+```c
+void matrix_init_user(void) {
+  ADD_TRACED_VARIABLE("layer", &layer_state, sizeof(layer_state));
+}
+```
+
+This will add a traced variable named "layer" (the name is just for your information), which tracks the memory location of `layer_state`. It tracks 4 bytes (the size of `layer_state`), so any modification to the variable will be reported. By default you can not specify a size bigger than 4, but you can change it by adding `MAX_VARIABLE_TRACE_SIZE=x` to the end of the make command line.
+
+In order to actually detect changes to the variables you should call `VERIFY_TRACED_VARIABLES` around the code that you think that modifies the variable. If a variable is modified it will tell you between which two `VERIFY_TRACED_VARIABLES` calls the modification happened. You can then add more calls to track it down further. I don't recommend spamming the codebase with calls. It's better to start with a few, and then keep adding them in a binary search fashion. You can also delete the ones you don't need, as each call need to store the file name and line number in the ROM, so you can run out of memory if you add too many calls.
+
+Also remember to delete all the tracing code ones you have found the bug, as you wouldn't want to create a pull request with tracing code.
\ No newline at end of file