1# About the linux-firmware project 2 3Please be aware that this project is not just a local Android project. 4It is actually intended to (roughly--see NOTES below) match up with the 5upstream git repository hosted at: 6 7<https://gitlab.com/kernel-firmware/linux-firmware.git> 8 9Mirrored at: 10 11<https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/> 12 13See also the [upstream README.md]. 14 15The local Android project is managed with [Copybara], though used in a 16slightly non-standard way. In order to fit into Android's infrastructure 17that tracks licensing and also to let us to update each firmware 18individually, our [Copybara] script doesn't act on the whole repo. Instead it 19acts on smaller groups of upstream files and keeps each group in its own 20directory. 21 22Each group is a logical set of files that someone may want to include in 23an Android product. All files in a given group must share the same license. 24If two files normally go together but share different licenses then they'll 25need separate groups and Android products will simply need to know to include 26both groups. 27 28## How to use this firmware in your Android product 29 30First and foremost, you should **talk to the legal counsel** for your 31Android product and make sure they have no problems with you including 32any firmware that you want. Nearly all firmware here is classified with 33a licnese that is "By Exception Only". That's normal / expected but you 34still need to get approval. 35 36After you've got approval, including this firmware in your Android product 37is as simple as adding to your `PRODUCT_PACKAGES`. For instance, if you 38wanted to include the r8152 firmware: 39 40``` 41PRODUCT_PACKAGES += linux_firmware_r8152 42``` 43 44## How to get your firmware added 45 46In order to get firmware added to this repo, the process is roughly: 47 48* Submit firmware to the upstream linux-firmware repo following 49 instructions in the [upstream README.md]. 50* Add/modify a `firmware_import_workflow` to the [copy.bara.sky] file and 51 land it as an `ANDROID:` change. 52* Run `./run_copybara.sh ${NAME}`. That will generate an `IMPORT` CL for you. 53 54The [Copybara] script should handle parsing the [upstream WHENCE] file 55for you to confirm that you specified the correct licenses. If it gives 56an error it's possible that you may need to improve the [copy.bara.sky] 57script's license grokking logic. 58 59Importing firmware files to this repo is considered a 3rd party import 60and thus needs approval. Details in [go/android-linux-firmware-approval-flow]. 61 62If we have to (due to an urgent bugfix), there's no technical reason 63we couldn't make local changes to firmware here, but this is 64**strongly discouraged** because any of your changes will be lost the 65next time someone runs [Copybara] for your firmware. If there is no 66choice then special approval will be needed. 67 68## Try to install only firmware you need 69 70When thinking about getting firmware installed, remember that disk space 71is at a premium. Products should specify exactly which firmware they need. 72In other words, you'll want to create a group for "Marvell 8897 SDIO WiFi" 73part, probably not "Marvell WiFi" or (even worse) a group of all firmare 74for "Marvell". 75 76## What about files that aren't appropriate for upstream linux-firmware? 77 78If you have firmware that is not appropriate for the upstream 79linux-firmware project then this isn't the repository you're looking for. 80In such a case you should find another place to put your firmware. 81 82Before trying to find another place for your firmware, however, please 83remember that there's a pretty big benefit to getting firmware landed 84in the upstream linux-firmware project. Notably we _want_ upstream to be 85testing / using the same firmware that Android is using. This makes it 86more likely for our systems to keep working across kernel uprevs and also 87more likely that someone upstream will fix a problem and we'll get the fix 88through stable merges. 89 90[Copybara]: https://github.com/google/copybara 91[copy.bara.sky]: ./copy.bara.sky 92[go/android-linux-firmware-approval-flow]: https://goto.google.com/android-linux-firmware-approval-flow 93[upstream README.md]: https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/README.md 94[upstream WHENCE]: https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/WHENCE 95[go/android-linux-firmware]: https://goto.google.com/android-linux-firmware 96