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", ...) 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. The environment variable will be compared to the driver initialized 36 struct eth_device->enetaddr. If they differ, a warning is printed, and the 37 environment variable will be used unchanged. 38 If the environment variable is not set, it will be initialized from 39 eth_device->enetaddr, and a warning will be printed. 40 If both are invalid and CONFIG_NET_RANDOM_ETHADDR is defined, a random, 41 locally-assigned MAC is written to eth_device->enetaddr. 42 4. Program the address into hardware if the following conditions are met: 43 a) The relevant driver has a 'write_addr' function 44 b) The user hasn't set an 'ethmacskip' environment variable 45 c) The address is valid (unicast, not all-zeros) 46 47 Previous behavior had the MAC address always being programmed into hardware 48 in the device's init() function. 49 50 ------- 51 Usage 52 ------- 53 54 If the hardware design mandates that the MAC address is stored in some special 55 place (like EEPROM etc...), then the board specific init code (such as the 56 board-specific misc_init_r() function) is responsible for locating the MAC 57 address(es) and initializing the respective environment variable(s) from it. 58 Note that this shall be done if, and only if, the environment does not already 59 contain these environment variables, i.e. existing variable definitions must 60 not be overwritten. 61 62 During runtime, the ethernet layer will use the environment variables to sync 63 the MAC addresses to the ethernet structures. All ethernet driver code should 64 then only use the enetaddr member of the eth_device structure. This is done 65 on every network command, so the ethernet copies will stay in sync. 66 67 Any other code that wishes to access the MAC address should query the 68 environment directly. The helper functions documented below should make 69 working with this storage much smoother. 70 71 --------- 72 Helpers 73 --------- 74 75 To assist in the management of these layers, a few helper functions exist. You 76 should use these rather than attempt to do any kind of parsing/manipulation 77 yourself as many common errors have arisen in the past. 78 79 * void eth_parse_enetaddr(const char *addr, uchar *enetaddr); 80 81 Convert a string representation of a MAC address to the binary version. 82 char *addr = "00:11:22:33:44:55"; 83 uchar enetaddr[6]; 84 eth_parse_enetaddr(addr, enetaddr); 85 /* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */ 86 87 * int eth_env_get_enetaddr(char *name, uchar *enetaddr); 88 89 Look up an environment variable and convert the stored address. If the address 90 is valid, then the function returns 1. Otherwise, the function returns 0. In 91 all cases, the enetaddr memory is initialized. If the env var is not found, 92 then it is set to all zeros. The common function is_valid_ethaddr() is used 93 to determine address validity. 94 uchar enetaddr[6]; 95 if (!eth_env_get_enetaddr("ethaddr", enetaddr)) { 96 /* "ethaddr" is not set in the environment */ 97 ... try and setup "ethaddr" in the env ... 98 } 99 /* enetaddr is now set to the value stored in the ethaddr env var */ 100 101 * int eth_env_set_enetaddr(char *name, const uchar *enetaddr); 102 103 Store the MAC address into the named environment variable. The return value is 104 the same as the env_set() function. 105 uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 }; 106 eth_env_set_enetaddr("ethaddr", enetaddr); 107 /* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */ 108 109 * the %pM format modifier 110 111 The %pM format modifier can be used with any standard printf function to format 112 the binary 6 byte array representation of a MAC address. 113 uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 }; 114 printf("The MAC is %pM\n", enetaddr); 115 116 char buf[20]; 117 sprintf(buf, "%pM", enetaddr); 118 /* the buf variable is now set to "00:11:22:33:44:55" */ 119
