Contributing to wpa_supplicant in CrOS

This documents how to develop, test, and submit code to wpa_supplicant in ChromeOS.

Build and deploy

This follows the standard ChromeOS development flow:

cros-workon-${BOARD} wpa_supplicant-cros
emerge-${BOARD} wpa_supplicant-cros
cros deploy ${DUT} wpa_supplicant-cros

Note that wpa_supplicant-cros/current and wpa_supplicant-cros/next are identical. This is a vestige of how we used to uprevs, but now that we've converted to automated merges, we no longer regularly use both directories other than for the occasional rollout of a new feature flag. Please develop in wpa_supplicant-cros/current.

To restart wpa_supplicant after deploying:

(DUT) # restart wpasupplicant

Testing

1. If applicable, implement the appropriate shill hooks (e.g. supplicant_interface_proxy_interface.h) and execute the appropriate shill flow. See go/shill-cheatsheet for shill development tips.
2. Use the wpa_supplicant command line interface wpa_cli:

sudo -u wpa -g wpa wpa_cli

3. Use dbus-send:

dbus-send --system --print-reply --dest=fi.w1.wpa_supplicant1 \
	/fi/w1/wpa_supplicant1/Interfaces/0 \
        fi.w1.wpa_supplicant1.Interface.AddNetwork \
	...

or gdbus:

gdbus call --system --dest fi.w1.wpa_supplicant1 --object-path \
	/fi/w1/wpa_supplicant1/Interfaces/0 --method \
	fi.w1.wpa_supplicant1.Interface.AddNetwork \
	...

4. Use hostap_hwsim
5. Run matfunc tests

Uploading to Gerrit

We try to follow kernel conventions detailed here. For trivial changes, feel free to send them upstream without internal review (see below for more details). Otherwise, upload them with a WIP: prefix to indicate that you'd like internal feedback first. After getting a +1 from relevant reviewers, you should send the patch upstream. For time-sensitive changes, we allow landing the change as FROMLIST with an UPSTREAM-TASK tag at the end specifying a bug number to track the task of upstreaming the change. Please also add the CrOSWiFi-PendingUpstreamReview hotlist to the task and add the patch to go/cros_supplicant_patches. For other changes, we prefer landing the change as UPSTREAM or BACKPORT to avoid accruing technical debt.

If you‘ve landed your change as FROMLIST, make sure to monitor the hostap mailing list so you can revise your patch if necessary. After it has been accepted upstream, revert the original FROMLIST patch and land it as UPSTREAM (or BACKPORT) to update the change to its latest version if necessary. There’s no need to do this if there is no diff between the UPSTREAM and FROMLIST patches. An easy way to do this is to run the following command:

diff <(git show ${FROMLIST_HASH}) <(git show ${UPSTREAM_HASH})

Note that there will always be diffs, but you can skip relanding as long as these diffs are part of the patch itself. Remember to close the task that was opened to track upstreaming, and remove the patch from go/cros_supplicant_patches.

Contributing upstream

For convenience, we suggest subscribing to the hostap mailing list so that your patches will be automatically posted to the list without approval. Note that DMARC restrictions may prevent subscribing to the mailing list with your @google.com email. Sending changes upstream is fairly similar to the kernel process. Follow those instructions to set up your git configuration and for best practices with respect to patch titling and formatting. Note that our wpa_supplicant repository already contains an upstream/main branch that you can use to make sure the patch applies cleanly upstream. Once you are ready to send your patch(es), you can send them to j@w1.fi (Jouni Malinen, the maintainer) and hostap@lists.infradead.org (the mailing list).