Just the FAQs ma'am

1. What is MicroBlaze?
   MicroBlaze is a soft-core 32 bit RISC microprocessor designed specifically to for Xilinx FPGAs.  It is part of the Xilinx Embedded Development Kit (EDK).
   
   More info at http://www.xilinx.com/MicroBlaze
    
2. What is uClinux?
   uClinux is a port of regular Linux to microprocessors that lack a memory management unit (MMU).  The implications of this on uClinux are primarily that there is no memory protection (processes can write anywhere in memory), and no virtual memory (swapping etc).  For most user applications the only implication is that the fork() system call is unavailable, and vfork() must be used instead.

   uClinux is a stable, operationally deployed operating system.  Ports exist for several MMU-less processors, including the Motorola ColdFire, NEC v850, and now, MicroBlaze.  The current distribution release is Linux kernel version 2.4.20, and there is active work on the 2.5/2.6 development tree as well.  SnapGear are the "champions" of uClinux, particularly on Motorola ColdFire processors.

   Lots of info at http://www.uclinux.org
    

3. How do I port uClinux to {insert platform/board name here}?
   First, please subscribe to the mailing list, and browse /search the list archive.  There may already be a port available, or in progress.
   
   Please send your questions to the mailing list, not directly to me.  The reason is simple - if I answer you privately, I help one person.  If I answer on the mailing list, it potentially helps many people.  Also, there are well over 100 list subscribers  - by asking there you have access to a much wider pool of talent.  We are available for paid commercial consulting if that is what you want.

   The approach is not so much to port the kernel, but rather to port the standard MicroBlaze uClinux platform (mbvanilla) to your board.  Then, you make the necessary kernel changes.
   
   It is essential to think clearly and carefully, and read all error messages!  Feel free to post on the mailing list, but try to be specific.  Saying "How do I port it to my board?" but providing no information, is unlikely to get you very far.  Similarly, if you get an error, don't just say "It doesn't work".  Instead, explain what you were doing and include the error messages. Basically, help us to help you.
   
   The basic steps are:

   1. Read the documentation!  It's not all directly related to porting uClinux and mbvanilla, but it will help you understand how the pieces fit together.
   2. Download an mbvanilla hardware target.  If your board has an ethernet PHY on it, mbvanilla_net is probably the most appropriate, otherwise use mbvanilla_ddr
   3. Modify mbvanilla to work on your board.  This usually means at least changing the UCF pin constraints, and often the memory controller parameters to suit your board's external memory devices.
   4. At this stage, do not modify the peripheral/memory address map, or the interrupts signals and IRQ assignments.
   5. Verify your mbvanilla is working, by writing some small MicroBlaze programs for it, or use some of the ones in the /code subdirectory in the platform distribution.
   6. Build the bootloader - it shouldn't require any changes if you have followed the instructions above
   7. Download the demo package, it contains a pre-built kernel image that you can test
   8. Follow the instructions to load the kernel image onto your board, with your new mbvanilla target
   9. By this stage, you are ready to start customising the platform and kernel to suit your needs.  This is beyond the scope of a FAQ - get active on the mailing list!
       
4. I've made some changes to the kernel to support my board, how do I get it into the uClinux CVS?
   Prepare a patch based on your modified kernel sources.  Usually, you do this by running
   
               cvs diff -u
   
   from within your kernel tree.  Post the output to the mailing list.  We will have a quick check to make sure your patch doesn't break any existing code or platforms, and might suggest some small changes if there are problems.  We can then submit it to the uClinux CVS maintainers, and they will apply the patches to the central repository.
    
5. I've successfully modified mbvanilla to work on my board, what do I do with it?
   I'm happy to host the project files (platform) on this website.  Please package it up like the mbvanilla platform (easy, if that was your starting point), and send a .zip or .tar.gz archive to the mailing list. 
    
6. This is for commercial work, I {can't|don't want to} share my platform/kernel changes/...
   Short answer:  Please do the Right Thing - you'll know it if you're doing it.
   
   Long answer:  The uClinux kernel and uClinux-dist userland are licensed under the GPL.  Basically, this means that if you distribute a binary containing the kernel and/or these GPL'd user programs, you must make the sources available.  If you have modified these in any way, those modifications must made available in the sources.
   
   The mbvanilla platforms are a little different.  I have made them available as a service to the MicroBlaze uClinux community, to help promote the development of the project as a whole.  I haven't yet decided what license to apply to the mbvanilla design (suggestions are welcome). 
   
   If you substantially base your MicroBlaze system design/platform on the mbvanilla target, then I believe you have a moral responsibility to contribute it back to the community.  That's just my opinion, I'm not a lawyer, nor can I afford one.  If you receive help on the list to port mbvanilla and uClinux to your board, then decide not to contribute back, that's your business.  You probably won't get sued, but you definitely won't get any more free help!
    
7. What is the "dist"?
   The dist (distribution), or more correctly uClinux-dist, is everything that goes into a full uClinux system apart from the kernel itself.  This includes the userland applications in /user, the C libraries (glibc, uClibc), the vendor configurations (board definitions etc) in /vendors, as well as the configuration tools and other useful bits and pieces.
    
8. I keep getting errors when I apply one of your patches.  What's going wrong?
   Sometimes saving a patch from a windows-based email client (like MS Outlook) causes CR/LF codes to be inserted in the file.  This usually causes failures when you apply the patch.  To work around it, either use a decent email client or run the dos2unix utility over the patch, once you get it onto your Linux box.
    
9. I've ported mbvanilla to my platform, but it still won't boot the kernel!
   Experience shows that a common cause of this, after you've done all the obvious things, is the lack of hardware multipliers on some Xilinx FPGA families.  Try disabling the hardware multipliers in both your hardware project, and in the kernel configuration (under kernel config -> processor type and features).
    
10. I run mb-gcc test.c and get the error "mb-ld.real: cannot find -lxil".  What's wrong?
    Running gcc without the '-c' option will compile and attempt to link, and by default mb-gcc will try to link against the xilinx library libxil.a. It provides functions like print, putnum, xil_printf to name a few.
    
    If you look at the makefiles created by XPS, you can see how they provide the path to the libxil.a file.
    
    The solution depends on what you are trying to do. If you are trying to make a uClinux executable, you need to either integrate your application into uClinux-dist (see uClinux-dist/Documentation/Adding-User-Apps-HOWTO),  or see the Wiki and follow Yashi's advice on doing an out-of-tree app build.
    
    If you are trying to build standalone MicroBlaze code (non-uClinux), then take a look at a Makefile generated by XPS, to see the command line they use. There will be a -L parameter passed to mb-gcc - that specifies the directory in which to find the libxil.a file.