Thin firmware spec

This documents the thin firmware commands as found on the XO-1. For the XO-1.5 libertas_tf driver and firmware, we will follow this spec. Any deviations and changes will be marked below as we progress.

Command summary

The following table summaries the commands found in libertas_tf, and details where they are used.

To determine the above matrix, we started with the command definitions defined in libertastf.h. We then did searches to collate these commands with where they appeared in libertastf and in both the XO1 Thin Firmware and the XO 1.5 Full Firmware. As expected, several commands that were added to the XO1 Thin Firmware were not present in the XO 1.5 Full Firmware. A big surprise however, was the command CMD_802_11_RF_TX_POWER which was defined in the header, supported by both firmwares, yet never implemented in libertastf.

Command cross-reference

CMD ID	lbtf Command
0x0003	CMD_GET_HW_SPEC
0x0005	CMD_802_11_RESET
0x0010	CMD_MAC_MULTICAST_ADR
0x001c	CMD_802_11_RADIO_CONTROL
0x001d	CMD_802_11_RF_CHANNEL
0x001e	CMD_802_11_RF_TX_POWER
0x0028	CMD_MAC_CONTROL
0x004d	CMD_802_11_MAC_ADDRESS
0x00a5	CMD_SET_BOOT2_VER
0x00b0	CMD_802_11_BEACON_CTRL
0x00cb	CMD_802_11_BEACON_SET
0x00cc	CMD_802_11_SET_MODE
0x00cd	CMD_802_11_SET_BSSID

Command details

Common

Each command packet starts with an 8 byte header, struct cmd_header which contains the basic information such as the command, the size of the packet, seqnum and result. The result code is not used in sending a command to the firmware, it should be set to 0.

       struct cmd_header {
       	__le16 command;
       	__le16 size;
       	__le16 seqnum;
       	__le16 result;
       } __attribute__ ((packed));

All fields that are 16 or 32 bit are stored in little endian. cpu_to_le16() is typically used.

It is unfortunately common for unused values to not be properly zeroed out by the driver before sending commands to the firmware. Unused fields are generally ignored, but we still shouldn't be sending garbage data in those fields, especially in cases where the Marvell documentation states to set fields to a specific value (typically 0). This should be fixed.

CMD_GET_HW_SPEC

• 0x0003

Description

This command queries hardware and other configuration data from the WLAN SoC, including the MAC address, multicast address list size, and hardware version number. In query, set all values to 0. The reply will return the information as per Marvell specification

Sample

 03 00 2e 00 02 00 00 00 00 00 00 00 00 00 00 00 
 ff ff ff ff ff ff 00 00 00 00 00 00 00 00 00 00 
 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Structure

struct cmd_ds_get_hw_spec {
 	struct cmd_header hdr;

 	/* HW Interface version number */
 	__le16 hwifversion;
 	/* HW version number */
 	__le16 version;
 	/* Max number of TxPD FW can handle */
 	__le16 nr_txpd;
 	/* Max no of Multicast address */
 	__le16 nr_mcast_adr;
 	/* MAC address */
 	u8 permanentaddr[6];

 	/* region Code */
 	__le16 regioncode;

 	/* Number of antenna used */
 	__le16 nr_antenna;

 	/* FW release number, example 0x01030304 = 2.3.4p1 */
 	__le32 fwrelease;

 	/* Base Address of TxPD queue */
 	__le32 wcb_base;
 	/* Read Pointer of RxPd queue */
 	__le32 rxpd_rdptr;

 	/* Write Pointer of RxPd queue */
 	__le32 rxpd_wrptr;

 	/*FW/HW capability */
 	__le32 fwcapinfo;
} __attribute__ ((packed));

Use in libertas_tf

• Used in the 80211 ops .start

CMD_802_11_RESET

• 0x0005

Description

Reboots the SoC. Note that this is not documented in the Marvell documentation.

• action is set to CMD_ACT_HALT (0x0003). However, the firmware seems to do a direct reboot call on receiving the RESET command and doesn't look at the action.

Structure

struct cmd_ds_802_11_reset {
 	struct cmd_header hdr;

 	__le16 action;
};

Use in libertas_tf

• Used by if_usb_reset_device()

CMD_MAC_MULTICAST_ADR

• 0x0010

Description

This command is used to program multicast MAC address into the hardware filter table in the WLAN SoC. The packets sent from these multicast MAC addresses are accepted.

• action is either CMD_ACT_GET (0x0000) or CMD_ACT_SET (0x0001)
• The 8388 may have a maximum of 32 multicast addresses set.
• The driver only ever sets the multicast addresses, it never reads the table.

Structure

struct cmd_ds_mac_multicast_addr {
 	struct cmd_header hdr;

 	__le16 action;
 	__le16 nr_of_adrs;
 	u8 maclist[ETH_ALEN * MRVDRV_MAX_MULTICAST_LIST_SIZE];
};

Use in libertas_tf

• Used in the 80211 ops .configure_filter

CMD_802_11_RADIO_CONTROL

• 0x001c

Description

This command is used to control the PHY.

• action may be either CMD_ACT_GET (0x0000) or CMD_ACT_SET (0x0001)
• control may either be RADIO_ON (0x0001) or RADIO_OFF (0x0000)
• While the documentation specifies that control bits [15:1] as reserved and set to 0, I saw the driver set control to 0x0005. The driver seems to have a series of constants that it ORs with this parameter: SET_AUTO_PREAMBLE, SET_SHORT_PREAMBLE, SET_LONG_PREAMBLE. These may no longer be required, require a different command to set, or are customizations in the Firmware.

Sample

1c 00 0c 00 08 00 00 00 01 00 01 00

Structure

struct cmd_ds_802_11_radio_control {
 	struct cmd_header hdr;

 	__le16 action;
 	__le16 control;
};

Use in libertas_tf

• Used in the 80211 ops .start
• Used in the 80211 ops .stop
• Used in 802.11 ops .bss_info_changed

CMD_802_11_RF_CHANNEL

• 0x001d

Description

This command gets or sets the current channel value.

• action may be either CMD_ACT_GET (0x0000) or CMD_ACT_SET (0x0001)
• channel is the current channel number to set or get.
• rftype, reserved and channellist are all listed as reserved or not used and should be set to 0.

The driver doesn't properly clear out the memory used by the structure, hence command dumps of this command show random data in rftype, reserved, and channellist fields.

Sample

1d 00 30 00 09 00 00 00 01 00 01 00 00 00 00 00 
01 00 00 00 8c 2b 18 cc 22 18 60 c0 00 38 17 cc 
00 00 00 00 00 38 17 cc 20 34 f8 c7 00 00 00 00

Structure

struct cmd_ds_802_11_rf_channel {
 	struct cmd_header hdr;

 	__le16 action;
 	__le16 channel;
 	__le16 rftype;      /* unused */
 	__le16 reserved;    /* unused */
 	u8 channellist[32]; /* unused */
};

Use in libertas_tf

• Used in the 80211 ops .config

CMD_802_11_RF_TX_POWER

• 0x001e

Description

This command gets or sets the transmit power level.

• action may be either CMD_ACT_GET (0x0000) or CMD_ACT_SET (0x0001)
• CurrentLevel defines the power level. See Marvell documentation for details.

This command is unused in the current libertas_tf driver.

CMD_MAC_CONTROL

• 0x0028

Description

This command is used to control the hardware MAC.

• action is a set of bitfields. It may be any combination of the following:
  • CMD_ACT_MAC_RX_ON - Turn on RX
  • CMD_ACT_MAC_TX_ON - Turn on TX
  • CMD_ACT_MAC_MULTICAST_ENABLE - Enable reception of packets from multicast address in table
  • CMD_ACT_MAC_BROADCAST_ENABLE - Enable reception of broadcast packets
  • CMD_ACT_MAC_PROMISCUOUS_ENABLE - Enable promiscuous reception
  • CMD_ACT_MAC_ALL_MULTICAST_ENABLE - Enable reception of packets from all multicast addresses (not just those in table).

Sample

28 00 0c 00 03 00 00 00 03 00 00 00

Structure

struct cmd_ds_mac_control {
 	struct cmd_header hdr;
 	__le16 action;
 	u16 reserved;
};

Use in libertas_tf

• Used in lbtf_setup_firmware, called from 80211 ops .start
• Used in the 80211 ops .configure_filter

CMD_802_11_MAC_ADDRESS

• 0x004d

Description

Set or get the MAC address.

• action may be either CMD_ACT_GET (0x0000) or CMD_ACT_SET (0x0001)
• macadd is the MAC address to set.

Sample

4d 00 10 00 06 00 00 00 01 00 00 17 c4 14 68 7a

Structure

struct cmd_ds_802_11_mac_address {
 	struct cmd_header hdr;

 	__le16 action;
 	uint8_t macadd[ETH_ALEN];
};

Use in libertas_tf

• Used in the 80211 ops .add_interface

CMD_SET_BOOT2_VER

• 0x00a5

Description

Set the boot2 version id.

This command was added for the libertas_tf. It simply sets a version id in the firmware, I am unsure of exactly why it's necessary or what its purpose is.

• action is 0.
• version is the boot2 version to set. Note that this is not converted into little endian.

wmb: The Linux driver sets the version field to the value from the "revision" field from the "vendor ID" portion of the USB device descriptor. It is unnecessary to do an endian conversion when copying known-little-endian source data (revision field of USB descriptor) to a known-little-endian destination (version field of command packet). The CPU does not interpret the data during the copy, so the CPU's endianness is irrelevant for the copy case. CPU endianness would be relevant for displaying the version as a 16-bit number. In the example below, the 16-bit interpretation of the version data is 0x3107.

Sample

a5 00 0c 00 01 00 00 00 00 00 07 31

Structure

struct cmd_ds_set_boot2_ver {
 	struct cmd_header hdr;

 	__le16 action;
 	__le16 version;
};

Use in libertas_tf

• Called during firmware loading.

CMD_802_11_BEACON_CTRL

• 0x00b0

Description

Enable or disable the beacon, and set the interval.

• action may be either CMD_ACT_GET (0x0000) or CMD_ACT_SET (0x0001). It looks like only SET is implemented in the thin firmware.
• beacon_enable may either be 0 to disable, or non-0 to enable.
• period is the beacon interval to set.

Structure

struct cmd_ds_802_11_beacon_control {
 	struct cmd_header hdr;

 	__le16 action;
 	__le16 beacon_enable;
 	__le16 beacon_period;
};

Use in libertas_tf

• Used in the 80211 ops .config_interface
• Used in the 80211 ops .remove_interface

CMD_802_11_BEACON_SET

• 0x00cb

Description

Set the beacon.

• len is the length of the data in beacon.
• beacon is the beacon to set.

Structure

struct cmd_ds_802_11_beacon_set {
 	struct cmd_header hdr;

 	__le16 len;
 	u8 beacon[MRVL_MAX_BCN_SIZE];
};

Use in libertas_tf

• Used in the 80211 ops .config_interface
• Used in the 80211 ops .set_tim

CMD_802_11_SET_MODE

• 0x00cc

Description

Set the mode.

• mode may be one of LBTF_PASSIVE_MODE, LBTF_STA_MODE, LBTF_AP_MODE.
  • LBTF_FULLMAC_MODE: Firmware operates in fullmac mode as required by the libertas driver. This is the default mode.
  • LBTF_PASSIVE_MODE: Firmware operates in passive promiscuous monitoring mode.
  • LBTF_STA_MODE: Thin firmware operates in infrastructure client station mode In this mode, only frames in this BSSID (set with CMD_802_11_SET_BSSID) sent from the AP will be passed to the host.
  • LBTF_AP_MODE: Thin firmware operates in AP mode. In this mode firmware will pass frames from STAs in this BSSID as well as frames with wildcard/broadcast SSID (i.e. probe requests).

Sample

cc 00 0a 00 05 00 00 00 01 00

Structure

struct cmd_ds_set_mode {
 	struct cmd_header hdr;

 	__le16 mode;
};

Use in libertas_tf

• Used in the 80211 ops .add_interface
• Used in the 80211 ops .remove_interface

CMD_802_11_SET_BSSID

• 0x00cd

Description

Set the bssid.

• bssid is the bssid to set.
• activate is non-zero to activate.

Sample

cd 00 0f 00 07 00 00 00 00 00 00 00 00 00 01

Structure

struct cmd_ds_set_bssid {
 	struct cmd_header hdr;

 	u8 bssid[6];
 	u8 activate;
};

Use in libertas_tf

• Called during device startup.
• Used in the 80211 ops .config_interface (to activate and set bssid)
• Used in the 80211 ops .remove_interface (to deactivate)

VIF implementation

libertas_tf and thin firmware supports a dual virtual-interface with mesh and infrastructure mode.

Limitations

• The 8686 doesn't support multiple MAC addresses, so it is unable to do a true vif implementation. We get around this by setting the-one-and-only MAC address on transmitted packets and using heuristics on received packets to set the vif MAC address before passing it to the driver. This part is done in firmware and allows the libertas_tf driver to work with vifs as mac80211 expects.
• The vif implmenation only supports two vifs, one must be mesh and one must be infrastructure mode.
• In bringing up the interfaces, mesh must be brought up first. This is because we don't have to adjust the MAC addresses on the beacons.

Start up commands

The below commands should be used to bring up the two interfaces:

#!/bin/bash                                                       

iw phy phy0 interface add mesh0 type mesh mesh_id XOmesh
iw phy phy0 set channel 6
ifconfig mesh0 up 192.168.78.63
ifconfig wlan0 hw ether 00:50:43:28:26:47
ifconfig wlan0 up 192.168.77.63

Driver to firmware interface

ifconfig mesh0 up

Bringing up the mesh interface.

lbtf_op_start() 
 
	lbtf_update_hw_spec() 
	[  141.172462] libertas_tf cmd: DNLD_CMD: command 0x0003, seq 1, size 46 
	[  141.172476] DNLD_CMD 03 00 2e 00 01 00 00 00 00 00 00 00 00 00 00 00  ................ 
	[  141.172489] DNLD_CMD ff ff ff ff ff ff 00 00 00 00 00 00 00 00 00 00  ................ 
	[  141.172500] DNLD_CMD 00 00 00 00 00 00 00 00 00 00 00 00 00 00        .............. 
	 
	lbtf_set_mac_control() 
	[  141.173440] libertas_tf cmd: DNLD_CMD: command 0x0028, seq 2, size 12 
	[  141.173452] DNLD_CMD 28 00 0c 00 02 00 00 00 03 00 00 00              (........... 
	 
	lbtf_set_radio_control() 
	[  141.174051] libertas_tf cmd: DNLD_CMD: command 0x001c, seq 3, size 12 
	[  141.174063] DNLD_CMD 1c 00 0c 00 03 00 00 00 01 00 05 00              ............ 
	 
	lbtf_set_mode(PASSIVE) 
	[  141.174834] libertas_tf cmd: DNLD_CMD: command 0x00cc, seq 4, size 10 
	[  141.174845] DNLD_CMD cc 00 0a 00 04 00 00 00 00 00                    .......... 
	 
	_lbtf_change_mac_address() 
 
 
lbtf_op_add_interface() 
 
	lbtf_set_mode(AP) 
	[  141.175287] libertas_tf cmd: DNLD_CMD: command 0x00cc, seq 5, size 10 
	[  141.175299] DNLD_CMD cc 00 0a 00 05 00 00 00 02 00                    .......... 
 
 
	lbtf_set_mac_address() 
	[  141.175841] libertas_tf cmd: DNLD_CMD: command 0x004d, seq 6, size 16 
	[  141.175853] DNLD_CMD 4d 00 10 00 06 00 00 00 01 00 00 50 43 28 26 41  M..........PC(&A 
	 
lbtf_op_configure_filter() 
 
	lbtf_set_mac_control() 
	[  141.176631] libertas_tf cmd: DNLD_CMD: command 0x0028, seq 7, size 12 
	[  141.176643] DNLD_CMD 28 00 0c 00 07 00 00 00 03 01 00 00              (........... 
 
lbtf_op_bss_info_changed() 
 
	lbtf_beacon_set() 
	[  141.177247] libertas_tf cmd: DNLD_CMD: command 0x00cb, seq 8, size 84 
	[  141.177259] DNLD_CMD cb 00 54 00 08 00 00 00 4a 00 80 00 00 00 ff ff  ..T.....J....... 
	[  141.177272] DNLD_CMD ff ff ff ff 00 50 43 28 26 41 00 50 43 28 26 41  .....PC(&A.PC(&A 
	[  141.177284] DNLD_CMD 00 00 00 00 00 00 00 00 00 00 e8 03 00 00 00 00  ................ 
	[  141.177296] DNLD_CMD 01 08 02 04 0b 16 0c 12 18 24 32 04 30 48 60 6c  .........$2.0H`l 
	[  141.177308] DNLD_CMD 03 01 06 34 06 58 4f 6d 65 73 68 33 07 00 00 00  ...4.XOmesh3.... 
	[  141.177319] DNLD_CMD 00 00 00 09                                      .... 
	 
	lbtf_beacon_ctrl() 
	[  141.177908] DNLD_CMD b0 00 0e 00 09 00 00 00 01 00 01 00 e8 03        .............. 
	[  141.178535] libertas_tf cmd: DNLD_CMD: command 0x00b0, seq 10, size 14 
 
lbtf_op_bss_info_changed() 
	lbtf_set_radio_control() 
	[  141.179166] libertas_tf cmd: DNLD_CMD: command 0x001c, seq 11, size 12 
	[  141.179178] DNLD_CMD 1c 00 0c 00 0b 00 00 00 01 00 01 00              ............ 
 
lbtf_op_config() 
	lbtf_set_channel() 
	[  141.179820] libertas_tf cmd: DNLD_CMD: command 0x001d, seq 12, size 48 
	[  141.179832] DNLD_CMD 1d 00 30 00 0c 00 00 00 01 00 06 00 8d bf ab f0  ..0............. 
	[  141.179845] DNLD_CMD 20 4b 9b e9 80 42 9b e9 00 00 00 00 ec 0d 96 e9   K...B.......... 
	[  141.179857] DNLD_CMD 61 fb 70 b0 36 e2 ab f0 f8 0d 96 e9 08 0e 96 e9  a.p.6........... 
 
lbtf_op_prepare_multicast() x6 

ifconfig wlan0 up

Bringing up the wlan interface.

lbtf_op_add_interface() 
 
	_lbtf_change_mac_address() 
	[  141.214056] libertas_tf cmd: DNLD_CMD: command 0x004d, seq 13, size 16 
	[  141.214070] DNLD_CMD 4d 00 10 00 0d 00 00 00 02 00 00 50 43 28 26 47  M..........PC(&G 
 
 
lbtf_op_bss_info_changed() 
	lbtf_set_radio_control() 
	[  141.214744] libertas_tf cmd: DNLD_CMD: command 0x001c, seq 14, size 12 
	[  141.214756] DNLD_CMD 1c 00 0c 00 0e 00 00 00 01 00 01 00              ............ 
 
lbtf_op_prepare_multicast() x6 

ifconfig wlan0 down

Bringing down the wlan interface.

lbtf_op_remove_interface() 
	lbtf_set_mode(AP) 
	[  237.712441] libertas_tf cmd: DNLD_CMD: command 0x00cc, seq 42, size 10 
	[  237.712456] DNLD_CMD cc 00 0a 00 2a 00 00 00 02 00                    ....*..... 
 
	lbtf_set_bssid() 
	[  237.712948] libertas_tf cmd: DNLD_CMD: command 0x00cd, seq 43, size 15 
	[  237.712960] DNLD_CMD cd 00 0f 00 2b 00 00 00 e2 ab f0 0a 00 c4 00     ....+.......... 
 
	_lbtf_change_mac_address() 
	[  237.713469] libertas_tf cmd: DNLD_CMD: command 0x004d, seq 44, size 16 
	[  237.713482] DNLD_CMD 4d 00 10 00 2c 00 00 00 04 00 00 50 43 28 26 47  M...,......PC(&G 
 
lbtf_op_configure_filter() 
	lbtf_cmd_set_mac_multicast_addr() 
	[  240.642255] libertas_tf cmd: DNLD_CMD: command 0x0010, seq 45, size 204 
	[  240.642269] DNLD_CMD 10 00 cc 00 2d 00 00 00 01 00 00 00 46 00 00 00  ....-.......F... 
	[  240.642282] DNLD_CMD f0 04 83 b0 03 3d 01 00 7d 3e 71 b0 18 bd 94 e9  .....=..}>q..... 
	[  240.642294] DNLD_CMD 41 1a 71 b0 f0 04 83 b0 7d 3e 71 b0 28 bd 94 e9  A.q.....}>q.(... 
	[  240.642306] DNLD_CMD 41 1a 71 b0 04 3d 01 00 48 bd 94 e9 45 1f 42 b0  A.q..=..H...E.B. 
	[  240.642318] DNLD_CMD 94 fd ff ff ff ff 01 00 46 00 00 00 36 00 00 00  ........F...6... 
	[  240.642331] DNLD_CMD 01 00 00 00 7d 3e 71 b0 ac bd 94 e9 5a 24 42 b0  ....}>q.....Z$B. 
	[  240.642343] DNLD_CMD 28 13 47 26 0f 00 00 00 37 00 00 00 13 02 00 00  (.G&....7....... 
	[  240.642355] DNLD_CMD 00 00 00 00 7d bd 94 e9 00 00 00 00 37 00 5b 20  ....}.......7.[  
	[  240.642367] DNLD_CMD 20 32 34 30 2e 36 34 32 31 39 32 5d 20 00 00 00   240.642192] ... 
	[  240.642379] DNLD_CMD 20 32 5b 20 20 32 34 30 2e 36 34 32 31 37 33 5d   2[  240.642173] 
	[  240.642391] DNLD_CMD 20 00 94 e9 c1 43 49 b0 86 31 68 b0 20 4b 9b e9   ....CI..1h. K.. 
	[  240.642403] DNLD_CMD 20 4b 9b e9 08 be 94 e9 03 01 10 00 bc bd 94 e9   K.............. 
	[  240.642415] DNLD_CMD 61 fb 70 b0 ff e3 ab f0 c8 bd 94 e9              a.p......... 
	 
	lbtf_set_mac_control() 
	[  240.643227] libertas_tf cmd: DNLD_CMD: command 0x0028, seq 46, size 12 
	[  240.643240] DNLD_CMD 28 00 0c 00 2e 00 00 00 03 00 00 00              (........... 
 
lbtf_op_bss_info_changed() 
	lbtf_beacon_set() 
	[  240.660242] libertas_tf cmd: DNLD_CMD: command 0x00cb, seq 47, size 84 
	[  240.660257] DNLD_CMD cb 00 54 00 2f 00 00 00 4a 00 80 00 00 00 ff ff  ..T./...J....... 
	[  240.660269] DNLD_CMD ff ff ff ff 00 50 43 28 26 41 00 50 43 28 26 41  .....PC(&A.PC(&A 
	[  240.660281] DNLD_CMD 00 00 00 00 00 00 00 00 00 00 e8 03 00 00 00 00  ................ 
	[  240.660293] DNLD_CMD 01 08 02 04 0b 16 0c 12 18 24 32 04 30 48 60 6c  .........$2.0H`l 
	[  240.660306] DNLD_CMD 03 01 06 34 06 58 4f 6d 65 73 68 33 07 00 00 00  ...4.XOmesh3.... 
	[  240.660317] DNLD_CMD 00 00 00 09                                      .... 
 
	lbtf_beacon_ctrl() 
	[  240.660851] libertas_tf cmd: DNLD_CMD: command 0x00b0, seq 48, size 14 
	[  240.660863] DNLD_CMD b0 00 0e 00 30 00 00 00 01 00 00 00 e8 03        ....0......... 
 

ifconfig mesh0 down

Bringing down the mesh interface.

lbtf_op_remove_interface() 
	lbtf_set_mode(PASSIVE) 
	[  240.663156] libertas_tf cmd: DNLD_CMD: command 0x00cc, seq 51, size 10 
	[  240.663168] DNLD_CMD cc 00 0a 00 33 00 00 00 00 00                    ....3..... 
 
	lbtf_set_bssid() 
	[  240.664177] libertas_tf cmd: DNLD_CMD: command 0x00cd, seq 52, size 15 
	[  240.664189] DNLD_CMD cd 00 0f 00 34 00 00 00 e2 01 00 0a 00 00 00     ....4.......... 
 
lbtf_op_stop() 
	lbtf_set_radio_control() 
	[  240.664922] libertas_tf cmd: DNLD_CMD: command 0x001c, seq 53, size 12 
	[  240.664934] DNLD_CMD 1c 00 0c 00 35 00 00 00 01 00 00 00              ....5.......