Rename doc/ to docs/

Signed-off-by: Tim Crawford <tcrawford@system76.com>

docs/README.md

@@ -0,0 +1,5 @@
+# System76 EC documetation
+
+## TODO
+
+- Define what functions are required in each board, ec, and arch

docs/adding-a-new-board.md

@@ -0,0 +1,90 @@
+# Adding a new board
+
+## Charger parameters
+
+- `CHARGER_ADAPTER_RSENSE`: The adapter RSENSE value in milliohms.
+- `CHARGER_BATTERY_RSENSE`: The battery RSENSE value in milliohms.
+- `CHARGER_CHARGE_CURRENT`: The desired charge current in milliamps.
+- `CHARGER_CHARGE_VOLTAGE`: On the battery, look for 充电限制电压 (charge limit
+  voltage). Convert this from volts to millivolts.
+- `CHARGER_INPUT_CURRENT`: On the charger, look for DC output. Convert the
+  current from amps to milliamps.
+
+#### Example
+
+The gaze15 battery has:
+
+```
+充电限制电压: 16.8Vdc
+```
+
+Its charger has:
+
+```
+DC OUTPUT (输出/輸出): 19.5V⎓9.23A 180W
+```
+
+The schematics show it uses a 0.005 ohm sense resistor for both the adapter and
+the battery.
+
+This gives:
+
+```
+CFLAGS+=\
+	-DCHARGER_ADAPTER_RSENSE=5 \
+	-DCHARGER_BATTERY_RSENSE=5 \
+	-DCHARGER_CHARGE_CURRENT=3072 \
+	-DCHARGER_CHARGE_VOLTAGE=16800 \
+	-DCHARGER_INPUT_CURRENT=9230
+```
+
+## GPIOs
+
+Use ecsim on the proprietary firmware to generate the configuration. Modify
+`src/main.rs` if the EC needs to be changed from 5570 to 8587. Refer to
+`gpio.sh`, which can automate the process.
+
+Use the EC page in the schematics to label everything.
+
+Not everything will be generated correctly, so check them manually when
+labeling. Examples include the M block not being included in the generated
+output, and `CCD_EN` being configured as `GPIO_IN` instead of `GPIO_OUT`.
+
+## Keyboard backlight
+
+Many models have backlit or RGB keyboards. The EC page in the board schematics
+should be sufficient to determine the method used to control the backlight.
+
+### DAC
+
+One of the DACs is be used for controlling the backlight level.
+
+Examples:
+
+- galp4
+- lemp9
+
+These models use `KBLIGHT_ADJ` to control the backlight level.
+
+### PWM
+
+One PWM line is used for controlling brightness, and three others are used for
+setting the red, green, and blue colors.
+
+Examples:
+
+- addw2
+- gaze15
+- oryp6
+
+These models use `EC_PWM_LEDKB_{R,G,B}` to control the color of the keys.
+
+### I2C
+
+I2C is used to communicate with the MCU that controls the keyboard backlight
+and color.
+
+Examples:
+
+- darp6
+- oryp5

docs/controllers.md

@@ -0,0 +1,41 @@
+# Embedded Controllers
+
+System76 EC is designed to be portable to boards using several 8-bit
+microcontrollers, such as:
+
+Board              | Embedded Controller | Architecture
+------------------ | ------------------- | --------------
+System76 ecsim     | Simulated ITE EC    | 8051
+System76 Laptops   | ITE IT8587E         | 8051
+System76 Laptops   | ITE IT5570E         | 8051
+System76 Thelio Io | Atmel ATMEGA32U4    | AVR
+Arduino Mega 2560  | Atmel ATMEGA2560    | AVR
+
+## Features
+
+Shared features (that can be used across different micro-controllers):
+
+Acronym | Feature                      | Description
+------- | ---------------------------- | -----------
+ADC     | Analog-digital converter     | Reads voltages from batteries and temperature from thermistors
+DAC     | Digital-analog converter     | Brightness control of keyboard backlight
+GPIO    | General purpose input/output | Control of LED's, buttons, and enable lines for other hardware
+KBSC    | Keyboard scan controller     | Detects laptop keyboard presses. Keyboard scanning can be done using GPIOs, the ITE EC has hardware acceleration
+PS/2    | Keyboard and mouse bus       | Interfaces with touchpad. PS/2 can be done using GPIOs, the ITE EC has hardware acceleration
+PWM     | Pulse-width modulation       | Fan control and brightness control of LED's
+SMBUS   | System management bus        | Reads battery information
+SPI     | Serial peripheral interface  | Reads and programs the EC's firmware
+UART    | Universal asynchronous receiver-transmitter | Provides EC console input/output
+
+Features specific to ITE embedded controllers:
+
+Acronym | Feature                      | Description
+------- | ---------------------------- | -----------
+LPC     | Low pin count                | Forwards memory and I/O access to EC. Most EC functions are exposed to the host through this interface. High frequency makes a GPIO implementation not possible. Simulation is provided by System76 ecsim
+PECI    | Platform environment control interface | Reads CPU temperature (relative to throttle point). Proprietary nature means a GPIO implementation is unlikely, though not technically impossible
+
+Features specific to Atmel embedded controllers:
+
+Acronym | Feature                      | Description
+------- | ---------------------------- | -----------
+USB     | Universal serial bus         | Can be used to provide access to EC functions either to the host or to a remote machine

docs/debugging.md

@@ -0,0 +1,112 @@
+# Debugging the EC firmware
+
+Terms used:
+- *target*: The laptop system that has the EC to be tested
+- *host*: The system that will have all devices connected to it and
+    will receive the EC logs
+
+## Parallel port
+
+This method replaces the keyboard with a device used for debug logging.
+An alternate method of interacting with the target is needed; e.g., an
+external USB keyboard or SSH session.
+
+Requirements:
+- Arduino Mega 2560 compatible board
+- 24 pin FPC breakout board and cables
+    - 0.5mm or 1.0mm pitch, depending on target connector
+- USB-C cable
+
+For details on configuring the Mega 2560 and breakout board, see
+[mega2560](./mega2560.md).
+
+### Setup
+
+1. Enable parallel port debugging in the EC firmware
+    - Uncomment `PARALLEL_DEBUG` in `src/board/system76/common/common.mk`
+    - Build and flash the firmware for the target
+2. Power off target
+3. Remove bottom panel
+4. Unplug keyboard cable
+    - May require removing keyboard depending on port location
+5. Ground target to host
+    - Connect USB cable from USB-C port on target to host
+6. Connect Mega 2560 to host
+    - This will create an ACM device at `/dev/ttyACM*`
+7. Connect Mega 2560 to target
+8. Start the console
+```
+make BOARD=system76/<model> console_external
+```
+
+EC logs should now print to the console on the host. This can be tested
+by removing or inserting the AC adapter to trigger a power event.
+
+To return the Mega 2560 to host mode, reset the device.
+
+If logs are corrupted, try power cycling the Mega or reseating the cable.
+
+## I2C connection
+
+**Failure to follow steps in order, or performing steps on an
+unsupported board, may result in damaged board components.**
+
+### Wiring the target
+
+The I2C connection is made through the battery pins. Find the pins marked
+`SMC_BAT` (clock) and `SMD_BAT` (data) in the service manual.
+
+Board       | `SMC_BAT` | `SMD_BAT`
+------------|-----------|-----------
+addw1       | 4         | 5
+addw2       | 4         | 5
+darp5       | 4         | 5
+darp6       | 4         | 5
+galp3       | 4         | 5
+galp3-b     | 4         | 5
+galp3-c     | 4         | 5
+galp4       | 4         | 5
+gaze14      | 4         | 3
+gaze15      | 4         | 3
+lemp9       | 6         | 5
+lemp10      | 6         | 5
+oryp5       | 4         | 5
+oryp6       | 6         | 5
+oryp7       | 6         | 5
+
+1. Power off system
+2. Unplug AC adapter
+3. Remove bottom panel
+4. Disconnect battery
+5. Attach one wire to `SMC_BAT`
+6. Attach one wire to `SMD_BAT`
+7. Route wires through the Kensington lock slot
+    - Secure wires to board with tape
+8. Attach female connector and housing to wires
+9. Reconnect battery
+10. Replace bottom panel
+
+### Setup
+
+Requirements:
+- Target wired for EC debugging
+- Adafruit Trinket M0
+- USB-C cable
+
+1. Enable I2C debugging in the EC firmware for the target
+    - Uncomment `I2C_DEBUGGER` in `src/board/system76/common/common.mk`
+    - Build and flash firmware
+2. Connect Trinket M0 to host
+    - This will create an ACM device at `/dev/ttyACM*`
+3. Connect to ACM device from host
+```
+sudo tio -b 115200 -m INLCRNL /dev/ttyACM0
+```
+4. Ground target to host
+    - Connect USB cable from USB-C port on target to host
+5. Connect target to host
+    - Connect `SMC_BAT` wire to `SCL` on Trinket M0
+    - Connect `SMD_BAT` wire to `SDA` on Trinket M0
+
+EC logs should now print to the console on the host. This can be tested
+by removing or inserting the AC adapter to trigger a power event.

docs/dev-env.md

@@ -0,0 +1,53 @@
+# Development environment
+
+## OS
+
+Linux is the only supported environment. Development is possible on a variety
+of distros. It is recommended to use the latest Pop!\_OS or Ubuntu release.
+
+The build server uses Ubuntu 20.04.
+
+## IDE/Editor
+
+Any editor that has support for [EditorConfig] may be used.
+
+No specific IDE or editor is required or recommended.
+
+## Toolset
+
+EC development depends on using distro-provided packages for the most of the
+toolset.
+
+A complete list of dependencies can be seen in `scripts/deps.sh`.
+
+### Cargo
+
+rustup manages the [Rust] toolchain, which includes cargo. Cargo is required
+for building the tools. It is the only part of the development toolset that is
+not installed through distro packages.
+
+### GNU Make
+
+[GNU Make] is used to automate the build process. It also provides targets for
+using ecflash (for flashing) and ectool (for console).
+
+### SDCC
+
+[SDCC] is the only practical open source toolset on Linux for targeting the
+8051 architecture (among others). It contains a collection of tools comparable
+to what you would expect from GCC for other development targets.
+
+SDCC contains language extensions to support the 8051 architecture. Refer to
+the [SDCC manual] for more information.
+
+Version 4.0.0 or newer should be used.
+
+**Note**: Fedora installs SDCC binaries to a non-standard location. Ensure that
+`PATH` includes `/usr/libexec/sdcc`.
+
+
+[EditorConfig]: https://editorconfig.org/
+[GNU Make]: https://www.gnu.org/software/make/
+[Rust]: https://www.rust-lang.org/
+[SDCC manual]: http://sdcc.sourceforge.net/doc/sdccman.pdf
+[SDCC]: http://sdcc.sourceforge.net/

docs/flashing.md

@@ -0,0 +1,60 @@
+# Flashing firmware
+
+## Internal programmer
+
+Use this method for flashing a system already running System76 EC.
+
+This will trigger a watchdog reset causing the system to **immediately power
+off**. OS data may be lost or corrupted as a result. Save and close all
+applications before flashing.
+
+```
+make BOARD=<vendor>/<model> flash_internal
+```
+
+## External programmer
+
+Use this method for:
+
+- flashing from proprietary firmware to System76 EC firmware
+- flashing without risking loss of OS data
+- flashing a bricked controller
+
+This requires:
+
+- [A configured Mega 2560](./mega2560.md): For programming the EC itself
+- A USB cable: For creating a common ground and providing power
+    - USB-C is recommended, but USB-A will work as well
+- A second computer: For building and flashing the firmware
+
+**The system must not have any power!**
+
+1. Turn off the laptop
+2. Unplug the AC adapter
+3. Remove the bottom panel
+4. Disconnect the battery
+5. Disconnect the keyboard from its port
+6. Replace the bottom panel and flip the laptop back over
+7. Connect the USB cable from the laptop to the host machine
+8. Connect the Mega 2560 to the host machine
+9. Attach the programmer to the keyboard port
+10. Flash the firmware
+
+```
+make BOARD=<vendor>/<model> flash_external
+```
+
+One of the first things it does is read the EC ID and version. If working, the
+ID will be the EC model the machine uses.
+
+```
+ID: 5570 VER: 2
+ID: 8587 VER: 6
+```
+
+Any other values means that the Mega 2560 is misconfigured or the FPC is not
+seated correctly. E.g., this is wrong:
+
+```
+ID: FF7F VER: 127
+```

docs/keyboard-layout-customization.md

@@ -0,0 +1,122 @@
+# Keyboard layout customization
+
+System76 EC firmware suppports using custom keyboard layouts. For example,
+having the physical "Caps Lock" key function as "Escape" when pressed.
+
+This only applies to the internal keyboard. External keyboards are not
+affected.
+
+Advanced functionality, such as macros or QMK's Mod-Tap, are not supported.
+
+You must be able to build and flash firmware. See the [README](../README.md)
+if you have not built the firmware before.
+
+## Firmware version
+
+To ensure compatibility with other system components (e.g. your current BIOS
+version), it's recommended to flash the same firmware version as you're
+currently using.
+
+Determine the BIOS version using dmidecode. The BIOS version is formatted as
+`<date>_<revision>`.
+
+```sh
+sudo dmidecode -t bios | grep Version
+```
+
+From the [firmware-open](https://github.com/system76/firmware-open) repo,
+determine the EC commit used for the BIOS version.
+
+```sh
+git ls-tree <bios_rev> ec
+```
+
+Checkout that commit in the EC repo and update the submodules.
+
+```sh
+git checkout <ec_rev>
+git submodule update --recursive
+```
+
+## Adding a layout file
+
+Determine the keyboard used for your model.
+
+```sh
+grep KEYBOARD src/board/system76/<model>/board.mk
+```
+
+Copy the default layout file for the keyboard to a separate file in the keymap
+directory.
+
+```sh
+cp src/keyboard/system76/<keyboard>/keymap/default.c src/keyboard/system76/<keyboard>/keymap/<custom>.c
+```
+
+The name of the keymap can be anything. Following QMK convention, the file name
+could be your username.
+
+## Modifying the layout
+
+A keymap file is a C file that defines the position of key and its function.
+Only the `LAYOUT`s should be modified.
+
+There are 2 layers in a keymap file.
+
+- `KEYMAP[0]`: The first `LAYOUT` defines the default layer
+- `KEYMAP[1]`: The second `LAYOUT` defines the function layer
+
+A `KT_FN` key must be assigned on the first layer in order to access the second
+layer. The `KT_FN` key must be held to use keys on the second layer.
+
+Change one key at a time to avoid losing your place.
+
+Some related files are:
+
+- `src/common/include/common/keymap.h`: Defines the key scancodes
+- `src/keyboard/system76/<keyboard>/include/board/keymap.h`: Defines the
+    keyboard matrix
+
+## Building with the new layout
+
+Build the firmware specifying the `KEYMAP` you have added.
+
+```sh
+make BOARD=system76/lemp9 KEYMAP=custom
+```
+
+Use a config file to simplify this. In the EC project's root directory, create
+a file named `config.mk`. Define the `BOARD` and `KEYMAP` variables.
+
+```mk
+BOARD?=system76/lemp9
+KEYMAP?=custom
+```
+
+Then building the firmware only requires calling make.
+
+```sh
+# Make will read config.mk to determine which board and keymap to use.
+make
+```
+
+## Flashing the new firmware
+
+See [flashing firmware](./flashing.md) for details.
+
+```sh
+make flash_internal
+```
+
+Do not use the keyboard or touchpad while it is flashing.
+
+The system will power off as part of the flash process. Turn it back on after
+it has powered off.
+
+The keyboard can now be used with your new layout.
+
+## Troubleshooting
+
+If your layout does not work as you intended, only the internal keyboard will
+be affected. An external USB keyboard or SSH session can be used to correct the
+layout and reflash the firmware.

docs/mega2560.md

@@ -0,0 +1,72 @@
+# Mega 2560
+
+The Mega 2560 is the recommended tool for EC flashing and debugging.
+
+The Mega 2560 is an open-source hardware design by [Arduino] based on the 8-bit
+Atmel ATmega2560. Arduino's official model sells for around 40 USD. Multiple
+clones exist, and can be bought for around 15 USD.
+
+## Clone compatibility
+
+Multiple clones of the Arduino Mega 2560 exist. Clones can be used, but must be
+compatible with the Arduino model. Some have replaced the ATmega16U2 chip used
+for USB communication with a CH340G chip. If it does not explicitly state that
+it uses the ATmega16U2, find a different model.
+
+## FPC breakout board
+
+A flexible printed circuit (FPC) breakout board is required. It should have:
+
+- 24 pins with 0.1" (2.54mm) pitch
+- One side with 0.5mm pitch FPC connector (for lemp9, lemp10, lemp11, galp5, and galp6)
+- One side with 1.0mm pitch FPC connector (for all other models)
+
+Depending on the vendor, the connectors may not come soldered to the board (or
+at all). A header block will likely not be provided, so male breakaway
+headers will need to be purchased separately.
+
+### Connecting to the Mega 2560
+
+The FPC board should be assembled so the 1.0mm pitch connector faces up. When
+connected to the Mega 2560, the FPC connector should face away from the Mega
+2560. In this orientation, pin 1 of the FPC connector connects to pin 22 (PA0)
+of the Mega 2560.
+
+### Connecting to the laptop
+
+A 24 pin flexible flat cable (FFC) is used to connect the Mega 2560 to the
+laptop. It may be worth buying both a set of standard cables (traces exposed on
+same side at each end) and reversed cables (traces exposed on opposite sides at
+each end). With both, it will always be possible to have pin 1 of the breakout
+board go to pin 1 of the keyboard port.
+
+The orientation of the FFC traces can be determined by looking at how the
+keyboard connects to its port.
+
+The laptop keyboard may use a 26-pin connection. Ensure that the FFC is aligned
+so the traces line up with pins 1-24 on the keyboard port.
+
+A second cable (typically, USB-C) must be used for grounding the target laptop
+to the host system (what the Mega 2560 is connected to).
+
+## Firmware
+
+`mega2560/parallel.c` must be modified for the mapping of the keyboard pins to
+the GPIO pins.
+
+- [Arduino Mega 2560 pin mapping][PinMapping2560]
+
+Using the orientation described above, pin 1 of the keyboard maps to
+
+- pin 22 (PA0) of the Mega 2560 when using the 1.0mm pitch connector
+- pin 45 (PL4) of the Mega 2560 when using the 0.5mm pitch connector
+
+Once the GPIO mapping is updated, the firmware can be compiled and flashed.
+
+```
+make BOARD=arduino/mega2560
+make BOARD=arduino/mega2560 flash
+```
+
+[Arduino]: https://www.arduino.cc/
+[PinMapping2560]: https://www.arduino.cc/en/Hacking/PinMapping2560

docs/security.md

@@ -0,0 +1,13 @@
+# Firmware security
+
+The firmware security feature can be configured by setting `CONFIG_SECURITY=1`
+in the `src/board/system76/[board]/board.mk` file. This feature prevents
+programming the EC firmware at runtime, unless the EC is unlocked with the
+`system76-ectool security unlock` command. After this, on the next reboot, the
+EC will respond to the SPI and reset commands. On boards where the `ME_WE` GPIO
+exists, it will be set high when the EC security state is unlocked.
+
+Other firmware components can use this state to perform their own locking and
+unlocking primitives. For example, in `coreboot`, flash regions may be locked
+when the EC security state is locked. In `EDK2`, a physical presence dialog may
+be shown when the EC security state is unlocked.