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