diff --git a/doc/l2.md b/doc/l2.md
new file mode 100644
index 0000000..bd77360
--- /dev/null
+++ b/doc/l2.md
@@ -0,0 +1,50 @@
+# L2
+
+The RTL827x provides access and configuration options to an L2 table that
+is used to associate device-MACs with ports on which those devices can
+be reached in the LAN. The code so far configures automatic learning and
+uses a default for aging of the learned addresses.
+
+## L2 Tables
+Access to the tables is done using table access registers. The same access
+registers also provide access to the VLAN configuration tables. An idea of how
+the table works can be gained from the [RTL8369 Datasheet](http://realtek.info/pdf/rtl8366_8369_datasheet_1-1.pdf)
+section 8.17 and in particular table 20.
+
+The central table register is RTL837X_TBL_CTRL(0x5cac).
+```
+Register RTL837X_TBL_CTRL bytes: EE EE TT CC
+EE: Entry
+TT: Table type
+CC: Command (Bit 0: Execute, Bit 1: Write)
+TT: 04: TBL_L2_UNICAST, 03: TBL_VLAN
+```
+
+An entry is retrieved from the tables by setting the data in registers to the
+desired entry filter, then executing a table command by writing to RTL837X_TBL_CTRL
+with execute bit 0 set, table type set and entry identifier (VLAN-Id or hash for L2).
+
+Data then is in the output data registers
+
+```
+#define RTL837x_L2_DATA_OUT_A	0x5ccc
+#define RTL837x_L2_DATA_OUT_B	0x5cd0
+#define RTL837x_L2_DATA_OUT_C	0x5cd4
+```
+The next entry can be now found in RTL837x_TBL_DATA_0 (entry = RTL837x_TBL_DATA_0_bits(0-11) + 1),
+which can be used to get the next entry by writing this value to RTL837X_TBL_CTRL.
+
+Deleting the entire L2 table is done by checking and setting 0x53dc to 0x0, then writing
+0x00010000 to register RTL837x_L2_TBL_CTRL and waiting until the bit 16 that was
+set has cleared.
+
+
+## API support in the code
+The RTLPlayground code provides support for reading the L2 tables from the
+ASIC and flushing the table in order to quickly forget the learned entries.
+```
+> l2
+        MAC       VLAN    type    port
+3c:18:a0:7e:11:ea 0x0001  learned 5
+1c:2a:a3:23:00:02 0x0001  learned 7
+```