doc/README.enetaddr: document proper MAC usage
Signed-off-by: Mike Frysinger <vapier@gentoo.org>
CC: Ben Warren <biggerbadderben@gmail.com>
diff --git a/doc/README.enetaddr b/doc/README.enetaddr
new file mode 100644
index 0000000..1d75aa3
--- /dev/null
+++ b/doc/README.enetaddr
@@ -0,0 +1,99 @@
+---------------------------------
+ Ethernet Address (MAC) Handling
+---------------------------------
+
+There are a variety of places in U-Boot where the MAC address is used, parsed,
+and stored. This document covers proper usage of each location and the moving
+of data between them.
+
+-----------
+ Locations
+-----------
+
+Here are the places where MAC addresses might be stored:
+
+ - board-specific location (eeprom, dedicated flash, ...)
+ Note: only used when mandatory due to hardware design etc...
+
+ - environment ("ethaddr", "eth1addr", ...) (see CONFIG_ETHADDR)
+ Note: this is the preferred way to permanently store MAC addresses
+
+ - ethernet data (struct eth_device -> enetaddr)
+ Note: these are temporary copies of the MAC address which exist only
+ after the respective init steps have run and only to make usage
+ in other places easier (to avoid constant env lookup/parsing)
+
+ - struct bd_info and/or device tree
+ Note: these are temporary copies of the MAC address only for the
+ purpose of passing this information to an OS kernel we are about
+ to boot
+
+-------
+ Usage
+-------
+
+If the hardware design mandates that the MAC address is stored in some special
+place (like EEPROM etc...), then the board specific init code (such as the
+board-specific misc_init_r() function) is responsible for locating the MAC
+address(es) and initializing the respective environment variable(s) from it.
+Note that this shall be done if, and only if, the environment does not already
+contain these environment variables, i.e. existing variable definitions must
+not be overwritten.
+
+During runtime, the ethernet layer will use the environment variables to sync
+the MAC addresses to the ethernet structures. All ethernet driver code should
+then only use the enetaddr member of the eth_device structure. This is done
+on every network command, so the ethernet copies will stay in sync.
+
+Any other code that wishes to access the MAC address should query the
+environment directly. The helper functions documented below should make
+working with this storage much smoother.
+
+---------
+ Helpers
+---------
+
+To assist in the management of these layers, a few helper functions exist. You
+should use these rather than attempt to do any kind of parsing/manipulation
+yourself as many common errors have arisen in the past.
+
+ * void eth_parse_enetaddr(const char *addr, uchar *enetaddr);
+
+Convert a string representation of a MAC address to the binary version.
+char *addr = "00:11:22:33:44:55";
+uchar enetaddr[6];
+eth_parse_enetaddr(addr, enetaddr);
+/* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */
+
+ * int eth_getenv_enetaddr(char *name, uchar *enetaddr);
+
+Look up an environment variable and convert the stored address. If the address
+is valid, then the function returns 1. Otherwise, the function returns 0. In
+all cases, the enetaddr memory is initialized. If the env var is not found,
+then it is set to all zeros. The common function is_valid_ether_addr() is used
+to determine address validity.
+uchar enetaddr[6];
+if (!eth_getenv_enetaddr("ethaddr", enetaddr)) {
+ /* "ethaddr" is not set in the environment */
+ ... try and setup "ethaddr" in the env ...
+}
+/* enetaddr is now set to the value stored in the ethaddr env var */
+
+ * int eth_setenv_enetaddr(char *name, const uchar *enetaddr);
+
+Store the MAC address into the named environment variable. The return value is
+the same as the setenv() function.
+uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
+eth_setenv_enetaddr("ethaddr", enetaddr);
+/* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */
+
+ * the %pM format modifier
+
+The %pM format modifier can be used with any standard printf function to format
+the binary 6 byte array representation of a MAC address.
+uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
+printf("The MAC is %pM\n", enetaddr);
+
+char buf[20];
+sprintf(buf, "%pM", enetaddr);
+/* the buf variable is now set to "00:11:22:33:44:55" */