doc/README.enetaddr

   1 ---------------------------------
   2  Ethernet Address (MAC) Handling
   3 ---------------------------------
   4
   5 There are a variety of places in U-Boot where the MAC address is used, parsed,
   6 and stored.  This document covers proper usage of each location and the moving
   7 of data between them.
   8
   9 -----------
  10  Locations
  11 -----------
  12
  13 Here are the places where MAC addresses might be stored:
  14
  15  - board-specific location (eeprom, dedicated flash, ...)
  16         Note: only used when mandatory due to hardware design etc...
  17
  18  - environment ("ethaddr", "eth1addr", ...) (see CONFIG_ETHADDR)
  19         Note: this is the preferred way to permanently store MAC addresses
  20
  21  - ethernet data (struct eth_device -> enetaddr)
  22         Note: these are temporary copies of the MAC address which exist only
  23               after the respective init steps have run and only to make usage
  24               in other places easier (to avoid constant env lookup/parsing)
  25
  26  - struct bd_info and/or device tree
  27         Note: these are temporary copies of the MAC address only for the
  28               purpose of passing this information to an OS kernel we are about
  29               to boot
  30
  31 Correct flow of setting up the MAC address (summarized):
  32
  33 1. Read from hardware in initialize() function
  34 2. Read from environment in net/eth.c after initialize()
  35 3. Give priority to the value in the environment if a conflict
  36 4. Program hardware in the device's init() function.
  37
  38 If somebody wants to subvert the design philosophy, this can be done
  39 in the board-specific board_eth_init() function by calling eth_init()
  40 after all the NICs have been registered.
  41
  42 -------
  43  Usage
  44 -------
  45
  46 If the hardware design mandates that the MAC address is stored in some special
  47 place (like EEPROM etc...), then the board specific init code (such as the
  48 board-specific misc_init_r() function) is responsible for locating the MAC
  49 address(es) and initializing the respective environment variable(s) from it.
  50 Note that this shall be done if, and only if, the environment does not already
  51 contain these environment variables, i.e. existing variable definitions must
  52 not be overwritten.
  53
  54 During runtime, the ethernet layer will use the environment variables to sync
  55 the MAC addresses to the ethernet structures.  All ethernet driver code should
  56 then only use the enetaddr member of the eth_device structure.  This is done
  57 on every network command, so the ethernet copies will stay in sync.
  58
  59 Any other code that wishes to access the MAC address should query the
  60 environment directly.  The helper functions documented below should make
  61 working with this storage much smoother.
  62
  63 ---------
  64  Helpers
  65 ---------
  66
  67 To assist in the management of these layers, a few helper functions exist.  You
  68 should use these rather than attempt to do any kind of parsing/manipulation
  69 yourself as many common errors have arisen in the past.
  70
  71         * void eth_parse_enetaddr(const char *addr, uchar *enetaddr);
  72
  73 Convert a string representation of a MAC address to the binary version.
  74 char *addr = "00:11:22:33:44:55";
  75 uchar enetaddr[6];
  76 eth_parse_enetaddr(addr, enetaddr);
  77 /* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */
  78
  79         * int eth_getenv_enetaddr(char *name, uchar *enetaddr);
  80
  81 Look up an environment variable and convert the stored address.  If the address
  82 is valid, then the function returns 1.  Otherwise, the function returns 0.  In
  83 all cases, the enetaddr memory is initialized.  If the env var is not found,
  84 then it is set to all zeros.  The common function is_valid_ether_addr() is used
  85 to determine address validity.
  86 uchar enetaddr[6];
  87 if (!eth_getenv_enetaddr("ethaddr", enetaddr)) {
  88         /* "ethaddr" is not set in the environment */
  89         ... try and setup "ethaddr" in the env ...
  90 }
  91 /* enetaddr is now set to the value stored in the ethaddr env var */
  92
  93         * int eth_setenv_enetaddr(char *name, const uchar *enetaddr);
  94
  95 Store the MAC address into the named environment variable.  The return value is
  96 the same as the setenv() function.
  97 uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
  98 eth_setenv_enetaddr("ethaddr", enetaddr);
  99 /* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */
 100
 101         * the %pM format modifier
 102
 103 The %pM format modifier can be used with any standard printf function to format
 104 the binary 6 byte array representation of a MAC address.
 105 uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
 106 printf("The MAC is %pM\n", enetaddr);
 107
 108 char buf[20];
 109 sprintf(buf, "%pM", enetaddr);
 110 /* the buf variable is now set to "00:11:22:33:44:55" */