Signed-off-by: Mike Frysinger vapier@gentoo.org CC: Ben Warren biggerbadderben@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" */