reference/machine: added eeprom reference and machine docs

content/docs/concepts/compiler-internals/calling-convention.md

@@ -18,11 +18,11 @@ TinyGo, however, uses a register based calling convention. In fact it is somewha
 
     Note that all native Go data types that are lowered to aggregate types in LLVM are expanded this way: `string`, slices, interfaces, and fat function pointers. This avoids some overhead in the C calling convention and makes the work of the LLVM optimizers easier.
 
-  * The WebAssembly target by default doesn't export or import `i64` (`int64`, `uint64`) parameters. Instead, it replaces them with `i64*`, allocating the value on the stack. In other words, imported functions are called with a 64-bit integer on the stack and exported functions must be called with a pointer to a 64-bit integer somewhere in linear memory.
+  * Some environments don't support `i64` parameters and return values (like old Node.js versions). Therefore, when targeting browsers, TinyGo will use a special ABI where these parameters and return values are returned with `i64`, allocating the value on the C stack. In other words, imported functions are called with a 64-bit integer on the stack and exported functions must be called with a pointer to a 64-bit integer somewhere in linear memory.
 
-    This is a workaround for a limitation in JavaScript, which only deals with doubles and can therefore only work with integers up to 32-bit in size (a 64-bit integer cannot be represented exactly in a double, a 32-bit integer can). It is expected that 64-bit integers will be [added in the near future] (https://github.com/WebAssembly/design/issues/1172) at which point this calling convention workaround may be removed. Also see [this wasm-bindgen issue](https://github.com/rustwasm/wasm-bindgen/issues/35).
+    WASI doesn't have this limitation so it will always use plain `i64` values.
 
-    Currently there are also non-browser WebAssembly execution environments that do not have this limitation. Use the -wasm-abi=generic flag to remove the behavior described above and enable emitting functions with i64 parameters directly.
+    We will eventually remove support for this workaround, as it is only really needed for very old Node.js versions.
 
   * The WebAssembly target does not return variables directly that cannot be handled by JavaScript (see above about `i64`, also `struct`, `i64`, multiple return values, etc). Instead, they are stored into a pointer passed as the first parameter by the caller.
 

content/docs/concepts/peripherals/eeprom.md

@@ -0,0 +1,55 @@
+---
+title: "EEPROM"
+weight: 3
+description: |
+  How to use the internal EEPROM.
+---
+
+For API documentation, see the [machine API](../../../reference/machine#eeprom).
+
+The EEPROM is a form of non-volatile memory that is uusually integrated along side an MCU. EEPROMs allows you to store a relatively small amount of data by allowing bytes to be erased and reprogrammed. For the most part, EEPROMs are not integrated directly onto a board, but in some cases they are provided as a standard peripheral.
+
+Although it may seem useful to have some type of data storage for your applications, the EEPROM is often limited in the amount of write cycles that it contains. This means that after a certain amount of writes, the EEPROM will not writeable, but you may still read data from it.
+
+## Controlling the EEPROM
+
+Control of the EEPROM has been simplified through the `EEPROM` variable that can be accessed through the `machine` package.
+
+Unlike most peripherals within TinyGo, you do not need to configure the EEPROM to use it.
+
+Example usage of the EEPROM can be seen below.
+
+```go
+package main
+
+import (
+    "machine"
+    "time"
+)
+
+// Address of the data to be stored.
+// Addresses can be either in hex or dec.
+const DataAddr = 0x10 
+
+
+func main() {
+    eeprom := machine.EEPROM0 // the onboard EEPROM
+
+    _, err := eeprom.WriteAt([]byte("Hello, World!"), DataAddr)
+    if err != nil{
+        panic(err)
+    }
+
+    // Create a buffer to read the data into
+    // We need to define a buffer with the correct size of the bytes we want to read.
+    buf := make([]byte, len("Hello, World!"))
+    _, err := eeprom.ReadAt(buf, DataAddr)
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Println(buf) // Hello, World!
+}
+```
+
+This example will store a value, `Hello, World!`, into the address `0x10`.

content/docs/reference/machine.md

@@ -222,6 +222,45 @@ func (uart *UART) WriteByte(c byte) error
 Write a single byte to the UART output.
 
 
+## EEPROM
+
+```go
+type EEPROM struct {
+}
+
+var EEPROM0 = EEPROM{}
+```
+
+The `EEPROM` struct contains the collection of methods that can be used to interact with the EEPROM. The `EEPROM` struct can be accessed through the preinitialized variable: `EEPROM0`. Depending on the type of board, you may or may not have an EEPROM built-in.
+
+
+```go
+func (e EEPROM) WriteAt(data []byte, off int64) (int, error)
+```
+
+WriteAt writes len(data) bytes in the EEPROMs at the provided offset. This method implements the `io.WriterAt` interface.
+
+```go
+func (e EEPROM) WriteByteAt(value byte, addr int64) error
+```
+
+WriteByteAt performs the logic to writes a byte into the EEPROM at the given address.
+
+```go
+func (e EEPROM) ReadAt(buf []byte, off int64) (int, error)
+```
+
+ReadAt reads exactly len(buf) into buf at the offset. It will return the amount of bytes copied or an error if one exists.
+The buffer cannot be empty, and an an error is thrown if fewer bytes are read than the size of the buffer.
+This method implements the `io.ReaderAt` interface.
+
+```go
+func (e EEPROM) ReadByteAt(addr int64) (byte, error)
+```
+
+ReadByteAt reads and returns the byte at the specified address. An error is returned if there is a failure to read.
+
+
 ## Other
 
 ```go

content/docs/reference/microcontrollers/esp32-coreboard-v2.md

@@ -64,11 +64,7 @@ The esp32-coreboard-v2 is a development board based on the [Espressif ESP32](htt
 
 ### CLI Flashing on Linux
 
-You need to install the Espressif toolchain for Linux to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/linux-setup.html#standard-setup-of-toolchain-for-linux
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -85,11 +81,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on macOS
 
-You need to install the Espressif toolchain for macOS to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/macos-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -106,11 +98,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on Windows
 
-You need to install the Espressif toolchain for Windows to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/windows-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 

content/docs/reference/microcontrollers/esp32-mini32.md

@@ -64,11 +64,7 @@ The mini32 is a small development board based on the popular [Espressif ESP32](h
 
 ### CLI Flashing on Linux
 
-You need to install the Espressif toolchain for Linux to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/linux-setup.html#standard-setup-of-toolchain-for-linux
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -85,11 +81,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on macOS
 
-You need to install the Espressif toolchain for macOS to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/macos-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -106,11 +98,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on Windows
 
-You need to install the Espressif toolchain for Windows to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/windows-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 

content/docs/reference/microcontrollers/m5stack-core2.md

@@ -103,11 +103,7 @@ The [m5stack-core2](https://shop.m5stack.com/products/m5stack-core2-esp32-iot-de
 
 ### CLI Flashing on Linux
 
-You need to install the Espressif toolchain for Linux to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/linux-setup.html#standard-setup-of-toolchain-for-linux
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -124,11 +120,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on macOS
 
-You need to install the Espressif toolchain for macOS to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/macos-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -145,11 +137,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on Windows
 
-You need to install the Espressif toolchain for Windows to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/windows-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 

content/docs/reference/microcontrollers/m5stack.md

@@ -66,11 +66,7 @@ The [m5stack](https://docs.m5stack.com/en/core/basic) is a development board bas
 
 ### CLI Flashing on Linux
 
-You need to install the Espressif toolchain for Linux to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/linux-setup.html#standard-setup-of-toolchain-for-linux
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -87,11 +83,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on macOS
 
-You need to install the Espressif toolchain for macOS to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/macos-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 
@@ -108,11 +100,7 @@ Now you should be able to flash your board as follows:
 
 ### CLI Flashing on Windows
 
-You need to install the Espressif toolchain for Windows to use TinyGo with the ESP32: 
-
-https://docs.espressif.com/projects/esp-idf/en/release-v3.0/get-started/windows-setup.html
-
-In addition, you must install the `esptool` flashing tool:
+You need to install the `esptool` flashing tool:
 
 https://github.com/espressif/esptool#easy-installation
 

content/docs/reference/microcontrollers/machine/arduino-mega1280.md

@@ -282,6 +282,11 @@ var (
 )
 ```
 
+```go
+var EEPROM0 = EEPROM{}
+```
+
+EEPROM0 is the internal EEPROM on most AVRs.
 
 
 ```go
@@ -371,7 +376,6 @@ var (
 
 
 
-
 ### func CPUFrequency
 
 ```go
@@ -457,6 +461,47 @@ value of each parameter will use the peripheral's default settings.
 
 
 
+## type EEPROM
+
+```go
+type EEPROM struct {
+}
+```
+
+### func (e EEPROM) WriteAt
+```go
+func (e EEPROM) WriteAt(data []byte, off int64) (int, error)
+```
+
+WriteAt writes len(data) bytes in the EEPROMs at the provided offset.
+
+
+### func (e EEPROM) WriteByteAt
+```go
+func (e EEPROM) WriteByteAt(value byte, addr int64) error
+```
+
+WriteByteAt performs the logic to writes a byte into the EEPROM at the given address.
+
+
+### func (e EEPROM) ReadAt
+```go
+func (e EEPROM) ReadAt(buf []byte, off int64) (int, error)
+```
+
+ReadAt reads exactly len(buf) into buf at the offset. It will return the amount of bytes copied or an error if one exists.
+The buffer cannot be empty, and an an error is thrown if fewer bytes are read than the size of the buffer.
+
+
+### func (e EEPROM) ReadByteAt
+```go
+func (e EEPROM) ReadByteAt(addr int64) (byte, error)
+```
+
+ReadByteAt reads and returns the byte at the specified address. An error is returned if there is a failure to read.
+
+
+
 
 ## type I2C