Every project, whether it is open or closed; hardware or software; electronics or digging a hole in the ground; all follow various processes. These processes ensure that things get tracked, completed, and finished on time. Processes typically save time. A process is just a means to an end - there are lots of good ones, and bad ones. We try to use the simplest/best process we can, while allowing everyone (developers and users) to get the jobs done - whether that be handing in that assignment for school, or release a project to production. (Although we don't like to do homework for people - to this end - we spend very little time on people's questions if they subscribed from a university, gmail, or hotmail - if you are from a real company who is making a commercial product, please register from that address, so we can help you better).
Every different open source project has their own processes, which most times are not well documented. This makes it difficult for occasional users to understand how to ask a question, or where to send a bug report. This section will try to address those questions, and document the processes that are followed on our project site.
If you have a problem/question/bug - please follow the outlined process. If you are feeling ignored, or your bug is not being worked on, please understand that we work on things based on priority set by the impact of the issue. This either means a common bug that effects many people, or an issue that effects someone who is shipping millions of units. We are not unreasonable - if something is stopping you from shipping a product - let us know - we will try to help.
Overall, we are very much in the Bazaar catagory.
All of our documentation for running on the Blackfin processor (whether it be the Linux kernel or user space applications, the Das U-Boot bootloader, or our GNU host tools) is done on this http://docs.blackfin.uclinux.org web site. Although there are many other sources of information for Linux, Das U-Boot, gcc and gdb, and Blackfin information on the internet - if you don't read it on this web site, may work - or it may not. This is especially true of Analog Devices Application Notes, or Engineer to Engineer Notes (EE-Note) about the Blackfin processor. Even though that information may be technically accurate - it may not reflect the way that Linux drivers expect hardware to be connected. This documentation site is the only authoritative place for Blackfin/Linux information, including hardware designs.
Although this is a wiki, write access is restricted to a small group of people. Every time someone makes a change to the documentation, a diff is emailed out to an open mailing list, where it is reviewed for clarity, technical accuracy, grammar and spelling. This ensures that the documentation is of the highest technical accuracy. Documentation is added based on a project member answering the same question multiple times on the forums, or when a developer adds new functionality.
If you would like to help volunteer to edit this wiki, add pages, fix mistakes, or draw better pictures, you can check that your additions will meet the requirements of the copyright information. If you just want to point out bugs in the documentation, we like that too.
Yes - we do have a test process!
Every few hours (at least daily) we checkout all the work in progress svn toolchain, kernel and U-Boot, and run the following tests (over JTAG, serial, and ethernet)
For details check out the specific testing process for each project.
The http://blackfin.uclinux.org website is supported by both an active open source community as well as a small dedicated team from Analog Devices, Inc. If you ask a question, it will be answered (normally within 24 hours).
We provide support for the projects via the Analog Devices Engineer Zone forums:
We do not provide generic Blackfin processor support. This is what Analog Devices does. Please ask them. If you have a question about:
We do not have the right people monitoring these forums to answer these types of questions. If the question is one where the toolchain, or kernel, or OS doesn't matter (like the above examples), it is likely that you will be asked to ask the question somewhere else (where there are the right people watching/answering questions).
If you have a question, about how something works or why it doesn't work, or think you have found a defect/bug, please ask in the Help forum or file a bug report to the bugs tracker linked on the front page.
If you have a question - “How do I do …” - search this on the wiki for the topic, or if there are no topics in the wiki to help (or you can't understand the instructions), please read How to ask a question the smart way by Eric Raymond, and then ask on the help forums. If English is not your first language - that is OK, we can try to answer questions in Chinese, German or English.
Sometimes when we are trying to answer the question, there isn't enough information in the original message, so we will ask for more information. Sometimes we will ask you to load things up in a debugger. If our answer doesn't help, or you think it is bad advice, tell us, and we will try to determine what your problem is, and a solution for it. If we can't help - we will tell you. We may not have all the answers right away, but we do try to get back to you. If we answer, and you don't follow up, we consider the issue closed.
!in subject lines typically do not get read. Every question is answered as soon as possible.
When asking questions on the forums:
The more specific you can be when you ask a question, the more likely we can help you without asking further questions. Be as specific as possible, and when appropriate, include the following information:
Finishing your query with “Please send your reply to… ” makes it unlikely you will get an answer. If you want an e-mail copy when somebody replies in the thread, request that the Web forum send it; this feature is supported if you click “Monitor this forum”.
Analog Devices can be contacted in the following ways (NOTE: Analog Devices can only answer hardware questions about the Blackfin processor. They cannot answer software questions about uClinux or any other program found on the web site):
Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106
Before reporting a bug, please read How to Report Bugs Effectively by Simon Tatham. It is available in over 10 languages. We normally accept bug reports on trunk, and the latest release. If we can not replicate the bug on trunk or the latest release, we will not look at it.
The main purpose of a bug report is to enable us to fix the bug. The most important prerequisite for this is that the report must be complete and self-contained. Before you report a bug, please check:
-Wall(all warnings turned on) and see whether this shows anything wrong with your code that could be the cause instead of a bug in GCC.
We prefer bug reports in English, but can accept bug reports in Chinese and German, too.
If you want to make a bug reports:
After a bug is reported, it will be validated, and assigned to a developer, and the status will be set to “Assigned (Not Started)”. As the status implies, replication does not mean the developer has started working on the bug yet. Once the developer has time to look at the bug, they will change the status to “Under Debugging”, this means the developer is actively working on this bug. Once the developer has solved the bug, they will commit a fix to the source tree and update the tracker, and set the status to “fixed”, and wait for you to tell us it is solved to your satisfaction. If it was not fixed then let us know, and we will continue to work on the problem. We depend on you for timely feedback. If we are unable to reproduce the issue, and you don't provide any feedback - we will have no choice except to close the bug and mark it as “rejected”.
The easier you make it for us to find/fix/patch a bug, the faster it will get looked into, and fixed. The best thing to do is attach a well thought out, upstream acceptable patch. If this is not possible, attach a simple test case allowing us to replicate your bug. If you can't make a test suite, provide detailed steps to replicate your issue. Without these things, it becomes difficult to root cause a problem. If we don't know what is wrong, we can't fix it. Before reporting your first bug, read How to Report Bugs Effectively by Simon Tatham.
We do it this way so we can quickly see: - how many bugs are open - which bugs are being worked on - which bugs have been assigned to someone that has been sitting a long time.
If a bug has been assigned to someone, and they have not started working on it yet, any developer is free to assign that bug to themselves, and start working on it.
Bugs are prioritized from 1 (most severe) to 5 (least severe).
If you fixed a bug, you can submit the bug report, and the fix on the bug trackers mentioned above. We only review patches that can be applied to the svn with the patch command (this means can be applied to svn trunk with zero changes - if hunks fail, the review stops there). If you are not familiar with patches, please review patches and diffs.
If you have a feature enhancement, or want to send your platform information to us, send your patchs to relavant mailing list.
It will then get reviewed, commented on, and either committed or rejected. We can't accept all patches, but we review all patches. We also normally do not accept patches that are not acceptable upstream - for different projects, this means different things. For the toolchain, that means all copyright must be assigned to the Free Software Foundation. For the kernel, ffmpeg, and many other projects, that means meeting a certain coding style. Unfortunately, we do not have the time nor personnel to fix random patches so they are acceptable upstream, so we normally ask the submitter (you) to do it.
For the kernel, it means:
./scripts/checkpatchon things with no errors or warnings.
Often times 3rd parties create their own board and wish to get integrated with the mainline Blackfin tree. In general, we encourage everyone who creates a Blackfin-based board to submit their board resources for inclusion. Doing so benefits everyone involved. For example, when a core change happens that affects boards, we will make the update for you. Having a diverse set of boards also allows us to see the sort of things that people need to accomplish and unify common functions or better architect things to make your life easier. How you specifically get things merged depends on the project.
For the uClinux distribution, we usually just give people commit access to the ADI buildroot project. This way you can manage your vendors directory however you see fit (see vendors for more information). For anything outside of the vendors directory, you should generally go through the normal process of submitting a tracker item, which is submitting something to the uClinux-dist patch tracker.
For the Linux kernel, you should email your patch to our Blackfin kernel development mailing list. There you will get feedback on your changes and eventually be merged. See the Linux kernel porting guide for more information.
For the Das U-Boot bootloader, you should email your patch to the Blackfin U-Boot development mailing list. There you will get feedback on your changes and eventually be merged. See the U-Boot porting guide for more information.
The Linux kernel is not developed with big design documents, feature requests and so on. It evolves over time based on the needs at the moment. When it first started out, it only supported one type of processor, as that's all it needed to. Later, a second architecture was added, and then more and more as time went on. And each time a new architecture was added, the developers figured out only what was needed to support that specific architecture, and did the work for that. They didn't do the work in the very beginning to allow for the incredible flexibility of different processor types that we have now, as they didn't know what was going to be needed.
The kernel only changes when it needs to, in ways that it needs to change. It has been scaled down to tiny little processors when that need came about, and was scaled way up when other people wanted to do that. And every time that happened, the code was merged back into the tree to let everyone else benefit from the changes, as that's the license that the kernel is released under.
From Greg Kroah-Hartman's OLS 2006 Keynote.
As for the Blackfin side of the Linux kernel - we do have a little more (but not much) of a process. We do listen to Kernel feature requests, Toolchain feature requests and Das U-Boot feature requests and even implement some of them. We don't implement all requested features - things that are not within our control, have no broad appeal, will not be acceptable upstream, or ideas that we think will be rejected. That doesn't mean that you shouldn't ask, but the answer may be No. This also does not mean that it is not possible, nor does it mean we would not like to see it happen. Since you have the source - you are free to make the modifications with or without our support or help. After you are done (if you decide to do it yourself, send us a patch, and we will review it).
If you submit a feature request, normally, clarification will be requested (we need to understand the detail of what you are looking for, so we don't spend time working on things that are not valuable), please answer in a timely manner, or the feature request will be closed.
For example, things we have rejected in the past include:
Normally every 6 months, we review the feature requests, and either decide:
After the code has been checked into svn, the developer should let whomever is monitoring the feature request know, that this is complete, and they can test it out on svn trunk. After it is decided everything is working, it will be part of future releases. (This is also the reason why we don't add everything under the sun - we maintain and test all features on new releases, and adding too many random things causes tests to be unstable, or take too long).
Development of any distribution can be quite a complex issue. We manage various projects within the dist, and keep in sync with many outside. Our goal is that any local changes we make are sent upstream to the mainline projects - but this can be pretty large task with the amount of projects that are inside the uClinux distribution now.
The Linux kernel is a integral part of this, but is handled in a more structured manner, due to it's development process.
linux-2.6.x/arch/blackfin, we commit it to the local blackfin.uclinux.org git, and the Blackfin git tree, and during the next merge window, Linus will pull from that, and take all our patches/fixes/updates into his tree.
linux-2.6.x/drivers/serial/bf5xx.c, we commit it to the local blackfin.uclinux.org git, and send the patch to the serial driver maintainer. This is the only person that Linus will take serial driver patches from. It is up to the serial driver maintainer to take our patches, apply it to their tree, and then push the changes to Linus during the next merge window.
linux-2.6.x/kernel, we commit it to the local blackfin.uclinux.org git, and send the patches to the appropriate maintainer, plus Andrew Morton, and Andrew will add it to the -mm tree (which is not a tree, but a collection of patches). During the next merge window, Linus will pull from either Andrew's tree, or from the subsystem maintainer.
This means that the trees on kernel.org and the ones in the local blackfin.uclinux.org git will never be exactly the same. The local blackfin.uclinux.org git will be ahead of the mainline kernel for Blackfin changes and fixes, and behind in terms of general kernel release.
U-Boot is managed in a similar way, where we send patches to the mainline maintainers, and periodically update the local git to become synced with the mainline project.
and the Blackfin/GNU Toolchain, which is managed in a similar way, except for the bits and pieces (like the eclipse plugins, and ldr utils, which we create, and maintain 100%):
When making an actual commit to one of our repositories, here are some general guidelines to keep in mind. These keep the source maintainable and reviewable, and make merging upstream a lot easier. By and large, these are not suggestions.
[#trackerid] subproject: area: one-liner summary Following a blank line, write out an explanation of what this commit is for. It must be complete enough for people to understand what is going on without having to look up bug reports or read mailing lists. Referencing such things is OK, but they should not be a requirement. Simple messages like "fix bug" or "board is broken" is not acceptable with the upstream projects, thus it is not acceptable in our repository. Every time a short commit is made like that, you force a lot of unnecessary busy work on the person responsible for bundling and sending your changes upstream. Also, feel free to credit people, even if they only reported the issue.
Some notes specific to some projects:
drivers/mtd/nand/) and modifies architecture specific pieces (like header files in
arch/blackfin/include/asm/). So you will need to split this.
arch/blackfin/mach-*/boards/*) from other files. Similar to the previous item, you should make commits to boards files (like
arch/blackfin/mach-bf537/boards/stamp.c) separate from the related drivers (like
When we do a major release, the first thing to do is understand the names. For example 2013R1-RC2, is the second version (or release candidate -RC2) of the first release (R1) in 2013 (We are not very innovative when it comes to names). We do not have “Golden” releases, since every time we have made one in the past, we end up finding/fixing more bugs, and have further releases after the final one - which was confusing to developers and users.
The difference between the different release candidates are simple (but sometimes major) bug fixes. Since the bug tracking/fixing/releasing cycle may be longer/shorter for the three main projects (toolchain, Das U-Boot, and uClinux-dist (including kernel)), it should be expected that the release candidate numbers for different projects will be different.
When we discuss/make a release, we normally talk about things as “2013R1”, and do not include the release candidate suffix - after all, you should be using the latest version, which will be different between the toolchain, buildroot/kernel, and U-Boot. Which is the latest, latest version? GIT is always the master. However, git can appear to be a complex labyrinth of master, branches and tags. This describes how git is managed:
This describes the typical development:
-RC1(release candidate 1), and start testing it.
bug fix1), we apply the fix to the release branch and trunk.
-RC2(release candidate 2), and re-start testing.
-RC2, but the severity of the bug is low, and we will not make a
-RC3. For those people who want the bug fix, they can go to the branch, and get the latest and greatest.
What this means:
-RCnthat you can find on the web site.
To learn more about svn, and checking out from a branch, check out blackfin_live_sources.
We support (answer questions, fix bugs, etc) on the latest release. In the above diagram - that means that after 2013R1 branch is made - we normally stop applying bugs fixes to the older branches - since we expect people to keep up with our developments.
Trunk may not always be stable (but we try), and some features may be broken on trunk (sorry - they normally get fixed soon). Developing off the latest release branch is always the best idea.
As you may have noticed - all of our development activity revolves around the web site. It is the center of our world (but we don't get out much). All questions, support, documentation, source code, bugs, patches, feature requests, and planning - all happen on the web site. The more you get comfortable using it, the better experience you will have with it.