mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-11-28 07:31:15 +00:00
doc/README.enetaddr: document proper MAC usage
Signed-off-by: Mike Frysinger <vapier@gentoo.org> CC: Ben Warren <biggerbadderben@gmail.com>
This commit is contained in:
parent
3f6e6993e9
commit
6ff4137f2a
1 changed files with 99 additions and 0 deletions
99
doc/README.enetaddr
Normal file
99
doc/README.enetaddr
Normal file
|
@ -0,0 +1,99 @@
|
|||
---------------------------------
|
||||
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
|
||||
|
||||
-------
|
||||
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" */
|
Loading…
Reference in a new issue