[U-Boot] [PATCH 02/27] doc/README.enetaddr: document proper MAC usage

[Mike Frysinger]

Signed-off-by: Mike Frysinger <vapier at gentoo.org>
CC: Ben Warren <biggerbadderben at gmail.com>
---
 doc/README.enetaddr |   96 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 96 insertions(+), 0 deletions(-)
 create mode 100644 doc/README.enetaddr

diff --git a/doc/README.enetaddr b/doc/README.enetaddr
new file mode 100644
index 0000000..dd7c50d
--- /dev/null
+++ b/doc/README.enetaddr
@@ -0,0 +1,96 @@
+---------------------------------
+ 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)
+
+-------
+ 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.
+
+The common environment code will take care of passing environment changes to
+the global data.  This happens automatically whenever setenv() updates the
+relevant ethaddr variables.
+
+Any other common code that wishes to access the MAC address should then query
+the global data directly.  No one should be looking in the environment for any
+addresses.
+
+---------
+ 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 env var
+is not set, then the function returns -1.  Otherwise, the conversion occurs and
+returns 0.
+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" */
+
+	* char *str_enetaddr(char *buf, const uchar *enetaddr);
+
+Print the MAC address into the specified storage.  Caller should make sure the
+storage is sufficient (20 bytes is fine).  The pointer used for storage is
+returned.
+char buf[20];
+uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
+str_enetaddr(buf, enetaddr);
+printf("The MAC is %s\n", buf);
+/* the buf variable is now set to "00:11:22:33:44:55" */
-- 
1.6.1.3