8e64d6efd8
As this seems unclear, document how the flow of setting up the MAC address is correct. Signed-off-by: Heiko Schocher <hs@denx.de> Text changed slightly, adding input from Mike Frysinger. Signed-off-by: Wolfgang Denk <wd@denx.de>
111 lines
4.3 KiB
Plaintext
111 lines
4.3 KiB
Plaintext
---------------------------------
|
|
Ethernet Address (MAC) Handling
|
|
---------------------------------
|
|
|
|
There are a variety of places in U-Boot where the MAC address is used, parsed,
|
|
and stored. This document covers proper usage of each location and the moving
|
|
of data between them.
|
|
|
|
-----------
|
|
Locations
|
|
-----------
|
|
|
|
Here are the places where MAC addresses might be stored:
|
|
|
|
- board-specific location (eeprom, dedicated flash, ...)
|
|
Note: only used when mandatory due to hardware design etc...
|
|
|
|
- environment ("ethaddr", "eth1addr", ...) (see CONFIG_ETHADDR)
|
|
Note: this is the preferred way to permanently store MAC addresses
|
|
|
|
- ethernet data (struct eth_device -> enetaddr)
|
|
Note: these are temporary copies of the MAC address which exist only
|
|
after the respective init steps have run and only to make usage
|
|
in other places easier (to avoid constant env lookup/parsing)
|
|
|
|
- struct bd_info and/or device tree
|
|
Note: these are temporary copies of the MAC address only for the
|
|
purpose of passing this information to an OS kernel we are about
|
|
to boot
|
|
|
|
Correct flow of setting up the MAC address (summarized):
|
|
|
|
1. Read from hardware in initialize() function
|
|
2. Read from environment in net/eth.c after initialize()
|
|
3. Give priority to the value in the environment if a conflict
|
|
4. Program hardware in the device's init() function.
|
|
|
|
If somebody wants to subvert the design philosophy, this can be done
|
|
in the board-specific board_eth_init() function by calling eth_init()
|
|
after all the NICs have been registered.
|
|
|
|
-------
|
|
Usage
|
|
-------
|
|
|
|
If the hardware design mandates that the MAC address is stored in some special
|
|
place (like EEPROM etc...), then the board specific init code (such as the
|
|
board-specific misc_init_r() function) is responsible for locating the MAC
|
|
address(es) and initializing the respective environment variable(s) from it.
|
|
Note that this shall be done if, and only if, the environment does not already
|
|
contain these environment variables, i.e. existing variable definitions must
|
|
not be overwritten.
|
|
|
|
During runtime, the ethernet layer will use the environment variables to sync
|
|
the MAC addresses to the ethernet structures. All ethernet driver code should
|
|
then only use the enetaddr member of the eth_device structure. This is done
|
|
on every network command, so the ethernet copies will stay in sync.
|
|
|
|
Any other code that wishes to access the MAC address should query the
|
|
environment directly. The helper functions documented below should make
|
|
working with this storage much smoother.
|
|
|
|
---------
|
|
Helpers
|
|
---------
|
|
|
|
To assist in the management of these layers, a few helper functions exist. You
|
|
should use these rather than attempt to do any kind of parsing/manipulation
|
|
yourself as many common errors have arisen in the past.
|
|
|
|
* void eth_parse_enetaddr(const char *addr, uchar *enetaddr);
|
|
|
|
Convert a string representation of a MAC address to the binary version.
|
|
char *addr = "00:11:22:33:44:55";
|
|
uchar enetaddr[6];
|
|
eth_parse_enetaddr(addr, enetaddr);
|
|
/* enetaddr now equals { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 } */
|
|
|
|
* int eth_getenv_enetaddr(char *name, uchar *enetaddr);
|
|
|
|
Look up an environment variable and convert the stored address. If the address
|
|
is valid, then the function returns 1. Otherwise, the function returns 0. In
|
|
all cases, the enetaddr memory is initialized. If the env var is not found,
|
|
then it is set to all zeros. The common function is_valid_ether_addr() is used
|
|
to determine address validity.
|
|
uchar enetaddr[6];
|
|
if (!eth_getenv_enetaddr("ethaddr", enetaddr)) {
|
|
/* "ethaddr" is not set in the environment */
|
|
... try and setup "ethaddr" in the env ...
|
|
}
|
|
/* enetaddr is now set to the value stored in the ethaddr env var */
|
|
|
|
* int eth_setenv_enetaddr(char *name, const uchar *enetaddr);
|
|
|
|
Store the MAC address into the named environment variable. The return value is
|
|
the same as the setenv() function.
|
|
uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
|
|
eth_setenv_enetaddr("ethaddr", enetaddr);
|
|
/* the "ethaddr" env var should now be set to "00:11:22:33:44:55" */
|
|
|
|
* the %pM format modifier
|
|
|
|
The %pM format modifier can be used with any standard printf function to format
|
|
the binary 6 byte array representation of a MAC address.
|
|
uchar enetaddr[6] = { 0x00, 0x11, 0x22, 0x33, 0x44, 0x55 };
|
|
printf("The MAC is %pM\n", enetaddr);
|
|
|
|
char buf[20];
|
|
sprintf(buf, "%pM", enetaddr);
|
|
/* the buf variable is now set to "00:11:22:33:44:55" */
|