Yocto BSP One-Stop Shop (Documentation Overview, Getting Started, FAQs, and more)

This page is meant to be the single-source authority on everything you need to know to create and maintain a Yocto BSP, including how to interact with the community.
I try to make sure everything here is accurate and up-to-date, but if you see something that's not, please do change it directly or send me (tom.zanussi@intel.com) the changes you'd like to see and I'll do my best to fix things up.
=== Starting Out ===
Want to know how to start a new Yocto BSP? One way would be to take a look at these documents:
Yocto BSP Tools Documentation
Transcript: Using the Yocto BSP tools to create a qemu BSP
Transcript: Using the Yocto BSP tools to create a meta-intel BSP
Sometimes the best way to get your feet wet is to just mindlessly follow a series of instructions and end up with something useful. Along those lines, you might want to try some of the following 'transcripts'. These two simply take you along the steps needed to build and boot an already-existing BSP.
*This one starts from scratch and gets you something you can boot in the qemu emulator (no target hardware required!): from git checkout to qemu desktop.
*This one starts from scratch and gets you something you can boot on actual hardware: from git checkout to meta-intel BSP.
=== Creating and Submitting Your New BSP and/or Patches ===
Assume you have a set of commits on, say, a meta-intel-contrib branch named tzanussi/meta-newbsp. To create a pull request:
 $ scripts/create-pull-request -u meta-intel-contrib -r meta-intel/master -b tzanussi/meta-newbsp
If your create-pull-request created more patches than your patchset contains, then something is definitely wrong and not only will your patchset be wrong, but the branch you point the maintainer too will also be wrong. Typically, the problem is that you didn't have your repo updated. In any case, you should make sure your local repo is up-to-date and your patches are on the end of that, then push your changes to the contrib repo. Also, it's nice when pushing your branch
to name it starting with your name e.g. tzanussi/meta-newbsp.
Similarly, if creating a pull request for the kernel, make sure you're creating the pull request against the right branch e.g. master when creating a pull request for master, or if the changes are against the meta branch, you should use meta
instead.
OK, so once you've successfully created a new pull-xxxx directory containing only the patches in your patchset, you should edit the 0000-cover-letter.patch so that it contains something informative about the patchset, at least write a minimal description of what the patchset does or about the hardware the new BSP is for.
Also, if you're creating a new BSP and are submitting changes for the meta branch, if you have the corresponding machine branch that actually has patches in it, you should create a separate patchset for that. If not, you should ask Bruce to also create a matching machine branch, and which base branch to base it off of. Finally, you should mention the repo
that you want all this created in e.g. linux-yocto-3.0 and linux-yocto-dev.
Here's an example:
 [PATCH 0/1][KERNEL] meta-intel: new fri2 BSP
 
 From: Tom Zanussi <tom.zanussi at intel.com>
 This is the initial version of a BSP for the Fish River Island II.
 I don't actually have the hardware, but have successfully booted
 a sato image with wired networking and vesa graphics on the closest
 thing I have, the crownbay.
 
 Please pull into linux-yocto-3.0/meta and linux-yocto-dev/meta.
 
 Also, please create a new "yocto/standard/fri2" machine branch in each
 of the above, based on yocto/standard/base.
...and all the rest of the generated cover-letter stuff.
Note that sometimes the pull URL is generated incorrectly - please verify that it's correct
for the pull request.
Note that none of the text in PATCH 0 will make it into the commit history of the repo - it's purely information for submission to the list.
The other patches in the series don't need to be modified, except for one thing - the [KERNEL] string should be added immediately following the patch number e.g.
 [PATCH 1/1][KERNEL] meta/fri2: create initial BSP infrastructure
The one thing to note, though, is that the text contained in each commit is preserved in the commit history, so every commit needs to have meaningful text in the form of a single-line summary and a multi-line or multi-paragraph commit message below it. This is especially important for BSPs e.g. at minimum the initial BSP commits should have something
like this:
 meta/newbsp: create initial BSP infrastructure
 
 A new BSP that uses the n455 processor. Initially we'll base it on
 the n450 bsp, but it will quickly diverge and change ownership, so
 we'll make it a separate bsp.
 
 Signed-off-by: Tom Zanussi <tom.zanussi@intel.com>
Note that every commit must have a Signed-off-by in the commit (this is added automatically when you do a 'git commit -s', assuming you've set up git correctly with your e-mail address, etc.). Any commit that doesn't have this in the body can't be pulled in.
Assuming all is well, you're ready to send your patchset (you might want to try sending it only to yourself first).
 $ scripts/send-pull-request -t yocto@yoctoproject.org -a -p pull-7261
Finally, when you do submit the patches, if these are kernel patches, you should cc bruce.ashfield@windriver.com so he doesn't miss them.
So I think that pretty much covers it - once you do it once, it becomes automatic after that but there is some learning curve to doing it properly.
=== FAQs ===
Q: I'm debugging X/sato in my BSP. How do I stop/start/restart X/sato?
A:
To stop X:
 # /etc/init.d/xserver-nodm stop
To start X:
 # /etc/init.d/xserver-nodm start
To restart X:
 # /etc/init.d/xserver-nodm restart
Q: How do I set kernel config options for my BSP?
A:
See the yocto-kernel section of the Yocto BSP Tools Documentation page or
Transcript: Using the Yocto BSP tools to manage kernel patches and config items or Adding new options and changing kernel code in the Starting a new Yocto BSP article.