xref: /openbmc/u-boot/doc/README.enetaddr (revision a89c33db)
1---------------------------------
2 Ethernet Address (MAC) Handling
3---------------------------------
4
5There are a variety of places in U-Boot where the MAC address is used, parsed,
6and stored.  This document covers proper usage of each location and the moving
7of data between them.
8
9-----------
10 Locations
11-----------
12
13Here 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-------
32 Usage
33-------
34
35If the hardware design mandates that the MAC address is stored in some special
36place (like EEPROM etc...), then the board specific init code (such as the
37board-specific misc_init_r() function) is responsible for locating the MAC
38address(es) and initializing the respective environment variable(s) from it.
39Note that this shall be done if, and only if, the environment does not already
40contain these environment variables, i.e. existing variable definitions must
41not be overwritten.
42
43During runtime, the ethernet layer will use the environment variables to sync
44the MAC addresses to the ethernet structures.  All ethernet driver code should
45then only use the enetaddr member of the eth_device structure.  This is done
46on every network command, so the ethernet copies will stay in sync.
47
48Any other code that wishes to access the MAC address should query the
49environment directly.  The helper functions documented below should make
50working with this storage much smoother.
51
52---------
53 Helpers
54---------
55
56To assist in the management of these layers, a few helper functions exist.  You
57should use these rather than attempt to do any kind of parsing/manipulation
58yourself as many common errors have arisen in the past.
59
60	* void eth_parse_enetaddr(const char *addr, uchar *enetaddr);
61
62Convert a string representation of a MAC address to the binary version.
63char *addr = "00:11:22:33:44:55";
64uchar enetaddr[6];
65eth_parse_enetaddr(addr, enetaddr);
66/* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */
67
68	* int eth_getenv_enetaddr(char *name, uchar *enetaddr);
69
70Look up an environment variable and convert the stored address.  If the address
71is valid, then the function returns 1.  Otherwise, the function returns 0.  In
72all cases, the enetaddr memory is initialized.  If the env var is not found,
73then it is set to all zeros.  The common function is_valid_ether_addr() is used
74to determine address validity.
75uchar enetaddr[6];
76if (!eth_getenv_enetaddr("ethaddr", enetaddr)) {
77	/* "ethaddr" is not set in the environment */
78	... try and setup "ethaddr" in the env ...
79}
80/* enetaddr is now set to the value stored in the ethaddr env var */
81
82	* int eth_setenv_enetaddr(char *name, const uchar *enetaddr);
83
84Store the MAC address into the named environment variable.  The return value is
85the same as the setenv() function.
86uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
87eth_setenv_enetaddr("ethaddr", enetaddr);
88/* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */
89
90	* the %pM format modifier
91
92The %pM format modifier can be used with any standard printf function to format
93the binary 6 byte array representation of a MAC address.
94uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
95printf("The MAC is %pM\n", enetaddr);
96
97char buf[20];
98sprintf(buf, "%pM", enetaddr);
99/* the buf variable is now set to "00:11:22:33:44:55" */
100