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