1*4882a593Smuzhiyun--------------------------------- 2*4882a593Smuzhiyun Ethernet Address (MAC) Handling 3*4882a593Smuzhiyun--------------------------------- 4*4882a593Smuzhiyun 5*4882a593SmuzhiyunThere are a variety of places in U-Boot where the MAC address is used, parsed, 6*4882a593Smuzhiyunand stored. This document covers proper usage of each location and the moving 7*4882a593Smuzhiyunof data between them. 8*4882a593Smuzhiyun 9*4882a593Smuzhiyun----------- 10*4882a593Smuzhiyun Locations 11*4882a593Smuzhiyun----------- 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunHere are the places where MAC addresses might be stored: 14*4882a593Smuzhiyun 15*4882a593Smuzhiyun - board-specific location (eeprom, dedicated flash, ...) 16*4882a593Smuzhiyun Note: only used when mandatory due to hardware design etc... 17*4882a593Smuzhiyun 18*4882a593Smuzhiyun - environment ("ethaddr", "eth1addr", ...) 19*4882a593Smuzhiyun Note: this is the preferred way to permanently store MAC addresses 20*4882a593Smuzhiyun 21*4882a593Smuzhiyun - ethernet data (struct eth_device -> enetaddr) 22*4882a593Smuzhiyun Note: these are temporary copies of the MAC address which exist only 23*4882a593Smuzhiyun after the respective init steps have run and only to make usage 24*4882a593Smuzhiyun in other places easier (to avoid constant env lookup/parsing) 25*4882a593Smuzhiyun 26*4882a593Smuzhiyun - struct bd_info and/or device tree 27*4882a593Smuzhiyun Note: these are temporary copies of the MAC address only for the 28*4882a593Smuzhiyun purpose of passing this information to an OS kernel we are about 29*4882a593Smuzhiyun to boot 30*4882a593Smuzhiyun 31*4882a593SmuzhiyunCorrect flow of setting up the MAC address (summarized): 32*4882a593Smuzhiyun 33*4882a593Smuzhiyun1. Read from hardware in initialize() function 34*4882a593Smuzhiyun2. Read from environment in net/eth.c after initialize() 35*4882a593Smuzhiyun3. The environment variable will be compared to the driver initialized 36*4882a593Smuzhiyun struct eth_device->enetaddr. If they differ, a warning is printed, and the 37*4882a593Smuzhiyun environment variable will be used unchanged. 38*4882a593Smuzhiyun If the environment variable is not set, it will be initialized from 39*4882a593Smuzhiyun eth_device->enetaddr, and a warning will be printed. 40*4882a593Smuzhiyun If both are invalid and CONFIG_NET_RANDOM_ETHADDR is defined, a random, 41*4882a593Smuzhiyun locally-assigned MAC is written to eth_device->enetaddr. 42*4882a593Smuzhiyun4. Program the address into hardware if the following conditions are met: 43*4882a593Smuzhiyun a) The relevant driver has a 'write_addr' function 44*4882a593Smuzhiyun b) The user hasn't set an 'ethmacskip' environment variable 45*4882a593Smuzhiyun c) The address is valid (unicast, not all-zeros) 46*4882a593Smuzhiyun 47*4882a593SmuzhiyunPrevious behavior had the MAC address always being programmed into hardware 48*4882a593Smuzhiyunin the device's init() function. 49*4882a593Smuzhiyun 50*4882a593Smuzhiyun------- 51*4882a593Smuzhiyun Usage 52*4882a593Smuzhiyun------- 53*4882a593Smuzhiyun 54*4882a593SmuzhiyunIf the hardware design mandates that the MAC address is stored in some special 55*4882a593Smuzhiyunplace (like EEPROM etc...), then the board specific init code (such as the 56*4882a593Smuzhiyunboard-specific misc_init_r() function) is responsible for locating the MAC 57*4882a593Smuzhiyunaddress(es) and initializing the respective environment variable(s) from it. 58*4882a593SmuzhiyunNote that this shall be done if, and only if, the environment does not already 59*4882a593Smuzhiyuncontain these environment variables, i.e. existing variable definitions must 60*4882a593Smuzhiyunnot be overwritten. 61*4882a593Smuzhiyun 62*4882a593SmuzhiyunDuring runtime, the ethernet layer will use the environment variables to sync 63*4882a593Smuzhiyunthe MAC addresses to the ethernet structures. All ethernet driver code should 64*4882a593Smuzhiyunthen only use the enetaddr member of the eth_device structure. This is done 65*4882a593Smuzhiyunon every network command, so the ethernet copies will stay in sync. 66*4882a593Smuzhiyun 67*4882a593SmuzhiyunAny other code that wishes to access the MAC address should query the 68*4882a593Smuzhiyunenvironment directly. The helper functions documented below should make 69*4882a593Smuzhiyunworking with this storage much smoother. 70*4882a593Smuzhiyun 71*4882a593Smuzhiyun--------- 72*4882a593Smuzhiyun Helpers 73*4882a593Smuzhiyun--------- 74*4882a593Smuzhiyun 75*4882a593SmuzhiyunTo assist in the management of these layers, a few helper functions exist. You 76*4882a593Smuzhiyunshould use these rather than attempt to do any kind of parsing/manipulation 77*4882a593Smuzhiyunyourself as many common errors have arisen in the past. 78*4882a593Smuzhiyun 79*4882a593Smuzhiyun * void eth_parse_enetaddr(const char *addr, uchar *enetaddr); 80*4882a593Smuzhiyun 81*4882a593SmuzhiyunConvert a string representation of a MAC address to the binary version. 82*4882a593Smuzhiyunchar *addr = "00:11:22:33:44:55"; 83*4882a593Smuzhiyunuchar enetaddr[6]; 84*4882a593Smuzhiyuneth_parse_enetaddr(addr, enetaddr); 85*4882a593Smuzhiyun/* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */ 86*4882a593Smuzhiyun 87*4882a593Smuzhiyun * int eth_env_get_enetaddr(char *name, uchar *enetaddr); 88*4882a593Smuzhiyun 89*4882a593SmuzhiyunLook up an environment variable and convert the stored address. If the address 90*4882a593Smuzhiyunis valid, then the function returns 1. Otherwise, the function returns 0. In 91*4882a593Smuzhiyunall cases, the enetaddr memory is initialized. If the env var is not found, 92*4882a593Smuzhiyunthen it is set to all zeros. The common function is_valid_ethaddr() is used 93*4882a593Smuzhiyunto determine address validity. 94*4882a593Smuzhiyunuchar enetaddr[6]; 95*4882a593Smuzhiyunif (!eth_env_get_enetaddr("ethaddr", enetaddr)) { 96*4882a593Smuzhiyun /* "ethaddr" is not set in the environment */ 97*4882a593Smuzhiyun ... try and setup "ethaddr" in the env ... 98*4882a593Smuzhiyun} 99*4882a593Smuzhiyun/* enetaddr is now set to the value stored in the ethaddr env var */ 100*4882a593Smuzhiyun 101*4882a593Smuzhiyun * int eth_env_set_enetaddr(char *name, const uchar *enetaddr); 102*4882a593Smuzhiyun 103*4882a593SmuzhiyunStore the MAC address into the named environment variable. The return value is 104*4882a593Smuzhiyunthe same as the env_set() function. 105*4882a593Smuzhiyunuchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 }; 106*4882a593Smuzhiyuneth_env_set_enetaddr("ethaddr", enetaddr); 107*4882a593Smuzhiyun/* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */ 108*4882a593Smuzhiyun 109*4882a593Smuzhiyun * the %pM format modifier 110*4882a593Smuzhiyun 111*4882a593SmuzhiyunThe %pM format modifier can be used with any standard printf function to format 112*4882a593Smuzhiyunthe binary 6 byte array representation of a MAC address. 113*4882a593Smuzhiyunuchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 }; 114*4882a593Smuzhiyunprintf("The MAC is %pM\n", enetaddr); 115*4882a593Smuzhiyun 116*4882a593Smuzhiyunchar buf[20]; 117*4882a593Smuzhiyunsprintf(buf, "%pM", enetaddr); 118*4882a593Smuzhiyun/* the buf variable is now set to "00:11:22:33:44:55" */ 119