OMAP Wireless Connectivity Station MAC Change

In newer WL12xx product groups (PGs), the Bluetooth® device address (BD_ADDR) is burned into the fuse ROM. During production, the next two addresses are reserved for WLAN and can be derived automatically from the BD_ADDR at runtime. This application report describes MAC address management for supported  PG versions.

Supported PG versions

Table 1 lists the PG versions containing the device addresses burned in ROM.

Table 1. Supported PG Versions

wl127x		wl128x
MAJOR	MINOR	MAJOR	MINOR
3	1	2	1
3	2	3	0
3	3	Above

Deriving the WLAN Addresses

The WLAN MAC addresses for the supported devices are derived as follows:

• BD_ADDR: 08:00:28:00:00:00
• WLAN 1: 08:00:28:00:00:01
• WLAN 2: 08:00:28:00:00:02

When deriving the WLAN addresses from the BD_ADDR, ensure that the organizational unique identifier (OUI) is not changed. The OUI (first 3 bytes) is pre-assigned by the IEEE to different companies (for example, the TI OUI is 08:00:28). The company that owns the OUI assigns the network identification card (NIC) address (last 3 bytes).

Addresses Assigned by the Customers

Customers can use either the TI MAC addresses assigned to the device or their own addresses, in which case the OUI represents their own company's address. The .nvs file includes a MAC address field to support the assignments. If a MAC address is available in the .nvs file, the address overrides the addresses assigned by TI during production. The MAC address written in the .nvs file represents the first WLAN address (WLAN 1); incrementing this first address derives the second address. Thus, when customers assign their own MAC addresses, they must assign two consecutive MAC addresses per device, writing the first one in the .nvs file.

NOTE: If an overflow occurs while deriving the second MAC address, wrap around the NIC part without changing the OUI in the same way as described in Section 1.2, Deriving the WLAN Addresses.

To use the MAC addresses assigned to the device by TI, the MAC address in the .nvs file must be blank (that is, 00:00:00:00:00:00) as an indication to the driver.

Addresses Unavailable at Probe Time

If the .nvs file does not contain the MAC address and the PG version in use does not contain the BD_ADDR, 00:00:00:00:00:00 is used when registering the interface with the wireless networking stack. In this configuration, a proper address must be assigned from the user space (for example, using the ifconfig command) before the interface is brought up.

Implementation

The feature implementation is split into two main parts: the driver and the calibrator tool. The calibrator tool generates the .nvs file and assigns MAC addresses to it.

Driver Implementation

The WL12xx driver reads the .nvs file and determines whether the MAC address must be derived from the fuse ROM automatically or overridden by the address assigned in the .nvs file. Figure 1 shows a flowchart describing these steps.

Figure 1

If the MAC address in the .nvs file is not blank, the driver uses that address and the subsequent one when registering the interfaces with the wireless networking stack. Nothing must be retrieved from the fuse ROM. If the MAC address in the .nvs file is blank, the driver checks if the PG has the BD_ADDR on it. If the PG version has a BD_ADDR (see Table 2), the BD_ADDR can be read. If the BD_ADDR is not available, 00:00:00:00:00:00 is used when registering the interface and the interface addresses must be changed from the user space before the interface is brought up.

Table 2. PG Version With BD_ADDR

Platform	Memory Address	Bit Index
		2	3	4	5
wl127x	0x50A	Major PG version		Minor PG version
wl128x	0x2152	Minor PG version		Major PG version

The BD_ADDR is retrieved from the device by reading the data from the following addresses in the DPRW partition when available: 0x0eb4 and 0x0eb8 (absolute 0x00310eb4 and 0x00310eb8). The first address contains the last 4 bytes of the BD_ADDR and the second address contains the first 2 bytes.
If successful, the next two addresses are derived and assigned when registering the interface with the kernel wireless stack.

User Space Implementation

A new calibrator application generates the .nvs file. To support the application, the following new features are added:

• The first feature is a simple command to read and print the MAC addresses assigned to the current device.
• The second feature automatically assigns an address to the .nvs file using one of three methods:
  • Custom: The custom address assignment is the simplest method, in which the tool simply writes the specified address to the .nvs file.
  • Default: The default address assignment directs the tool to determine whether the BD_ADDR is available in the current device. If so, this method writes the blank address (00:00:00:00:00:00) to the .nvs file and the driver retrieves the address from the fuse ROM at runtime. If the address is not available (either because the driver does not support this new feature or the hardware PG version does not contain the address in ROM), the tool returns an error. Nevertheless, the user can force the default address to be used by passing as an argument a custom address set to 00:00:00:00:00:00.
  • from_fuse: Similar to the default address assignment, the from_fuse address assignment checks whether the address is available and fails if not. The difference is that instead of writing the default MAC address to the .nvs file, from_fuse writes the actual MAC address derived from the BD_ADDR from the fuse.

Figure 2 shows a flowchart demonstrating the three different methods.

Figure 2

Because a unique .nvs file must be generated for each device, the from_fuse method works in most cases, especially when used by customers for the production of end-user products. The default method works well with R&D and distributions that ship a default .nvs file. In these cases, the same .nvs file can be used in several different devices and the correct MAC address is retrieved automatically from the fuse by the driver at runtime.

Setting a Permanent MAC Address in the NVS File, using the Calibrator

Important: The MAC address is reset when perorming calibration according to the Calibration Process section. Therefore, it is imporatnt to complete the calibration process before modifying the MAC address.

In order to set a permanent MAC address to the station, the calibrator tool is used.
Enter the following sequence:

calibrator set nvs_mac /lib/firmware/ti-connectivity/wl1271-nvs.bin xx:xx:xx:xx:xx:xx
rmmod wl12xx_sdio
modprobe wl12xx_sdio

To verify that the MAC address was properly changed, use the ifconfig function as follows:

root@am37x-evm:~# ifconfig wlan0
wlan0     Link encap:Ethernet  HWaddr 08:20:00:33:65:29
          inet addr:192.168.3.10  Bcast:0.0.0.0  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:14048740 errors:0 dropped:0 overruns:0 frame:0
          TX packets:20805996 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:3296646156 (3.0 GiB)  TX bytes:1748711212 (1.6 GiB)

in case wlan0 does not appears then fix it following the next "Troubleshooting Guide"

Troubleshooting Guide

If you change the MAC address more than once, the linux OS tries to allocate a new wireless interface e.g: wlan1, wlan2... . To avoid this situation and to keep wlan0 interface, update the file /etc/udev/rules.d/70-persistent-net.rules by deleting all the previous info saved in it, as explained below:
Following is an example of the file: /etc/udev/rules.d/70-persistent-net.rules:
perform the following:

root@am180x-evm:/# vi /etc/udev/rules.d/70-persistent-net.rules

and then the file looks like the following:

# This file was automatically generated by the /lib/udev/write_net_rules
# program, run by the persistent-net-generator.rules rules file.
#
# You can modify it, as long as you keep each rule on a single
# line, and change only the value of the NAME= key.

# net device ()
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:12:34:56:60:54", ATTR{type}=="1", KERNEL=="wlan*", NAME="wlan0"

# net device ()
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="01:23:56:78:90:12", ATTR{type}=="1", KERNEL=="wlan*", NAME="wlan1"

To clear the file:

• Delete all the lines containing the following strings:

<SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="00:12:34:56:60:54", ATTR{type}=="1", KERNEL=="wlan*", NAME="wlanX" >
In order to delete single line using VI editor, navigate with the down arrow to the desired line, then type the character 'd' twice, ie: dd
once you finish type the combination :wq in order to save and exit.
The file will look like:

root@am180x-evm:/# cat /etc/udev/rules.d/70-persistent-net.rules
This file was automatically generated by the /lib/udev/write_net_rules
program, run by the persistent-net-generator.rules rules file.
You can modify it, as long as you keep each rule on a single
line, and change only the value of the NAME= key.

net device ()
net device ()

• In command line, type sync in order to save any pending data.
• Perform hard reset to the EVM board

Setting a Temporary MAC Address using ifconfig

In case the MAC address is to be changed temporarily, you may use the ifconfig command, according to the following steps:

1. Perform interafce BringDown.
2. Use ifconfig for temporarily changing the interafce's MAC adress.
3. Perform interface BringUp.

To perform the above, the following sequence is used on the console:

ifconfig wlan0 down
ifconfig wlan0 hw ether xx:xx:xx:xx:xx:xx
ifconfig wlan0 up

Note: after the next board restart, the MAC adress will re-set to the one read from the NVS file.

Verifying that the MAC Address has Changed

To verify that the MAC address was properly changed, use the ifconfig function as follows:

root@am37x-evm:~# ifconfig wlan0
wlan0     Link encap:Ethernet  HWaddr 08:20:00:33:65:29
          inet addr:192.168.3.10  Bcast:0.0.0.0  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:14048740 errors:0 dropped:0 overruns:0 frame:0
          TX packets:20805996 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:3296646156 (3.0 GiB)  TX bytes:1748711212 (1.6 GiB)