manojmaurya28 / baremichael Goto Github PK

  BareMichael SCC baremetal framework.
  Copyright (C) 2012.  All rights reserved.
=========================================================
===== BareMichael Baremetal Framework for Intel SCC =====
=========================================================

This is a collection of files intended to help someone get started on writing 
baremetal SCC apps.  Note that this includes no support for message-passing 
(though there is now support for linking in the baremetal RCCE library), just 
the basics to get the cores properly configured and running your C code.  All 
files are taken from Michael Ziwisky's work on Xipx, a port of Embedded Xinu.  
For more info on Embedded Xinu, see http://xinu.mscs.mu.edu/


===== WHAT BAREMICHAEL DOES =====

The included code will initialize the Pentium cores before jumping to main() 
in ./test/main.c.  A subset of the C standard library is included in 
./lib/libxc/ and gets compiled and linked into your code.  Some default 
exception handlers for vectors 0 through 31 are configured to produce a stack 
dump if an exception occurs.


===== HOW IT TALKS TO YOU =====

With this framework, you are unable to send input to the SCC, but you can get 
output from it using the included tool called miketerm.  cd to ./miketerm/ and 
type `make` to compile the tool.  Then run it with `./miketerm`.  Ctrl-C to 
exit.  To print to miketerm from your SCC program, simply use printf().


===== HOW TO MAKE IT WORK =====

Some notes about ./compile/Makefile:
In order to get this environment to build on your marc machine, you must 
modify two variables in the Makefile: COMIPLER_PATH and BIN2OBJ_TOOL.  
COMPILER_PATH must point to the path of the Intel-supplied x86 cross-compiler.  
BIN2OBJ_TOOL must point to the Intel-supplied binary `bin2obj`.  See 
HowtoBuildSCCLinux.pdf at http://communities.intel.com/docs/DOC-5802 for 
instructions on getting these onto your machine.

Without any other modifications besides changing the COMPILER_PATH and 
BIN2OBJ_TOOL variables, you should be able to go to ./compile/ and do `make; 
make run;../miketerm/miketerm` to see a "Hello World!" from five cores.

By default, your single compiled image gets loaded onto all 48 cores.  In 
order to set which cores actually reset and run the code upon calling `make 
run`, simply change the BOOTCORES variable in the Makefile.


===== EXTRAS =====

Some fairly self-explanatory SCC functions and macros (get_my_tileid(), 
get_my_coreid(), etc.) are included in ./system/scc.c and ./system/scc.h.  
Note that these are just functions I've written for my own work that I thought 
others would find useful -- you may want to write these things differently.  
(That's a true statement for every line of code in this entire framework, of 
course!)

This should give you enough to start playing with the baremetal cores 
individually.  To do more interesting things, like message passing, you have 
to code it up yourself.


===== RCCE SUPPORT =====

Note, however, that since v6 of the framework, there is now enough support to 
use the RCCE V2.0 baremetal library.  To do so, compile RCCE as directed in 
its README (making sure to do `./configure SCC_BAREMETAL` when you get to that 
step), then edit the BareMichael Makefile so that the RCCE_PATH variable 
points to the root directory of RCCE and the RCCE_SUPPORT variable is set to 
1.  The functions added to BareMichael v6 to support RCCE are located in 
./system/rccesupport.c.  Note that some of them (such as mmap() and munmap()) 
are tailored only for RCCE support, and are not fully implemented to fulfil 
their intended duties.  These functions are not necessarily safe for use 
outside of the purpose of supporting RCCE V2.0.  A "pingpong" benchmark, taken 
from iRCCE ("improved RCCE" -- see http://communities.intel.com/thread/22921) 
is included as ./test/RCCE_pingpong.c for demonstration purposes.  An 
important thing to note in that source is how to create the argc and argv 
variables to pass to RCCE_init().  (This is a little hacky because we don't 
invoke RCCE programs from a shell like one would with SCC Linux.)


===== SHOULDERS OF GIANTS =====

Acknowledgement is due to Intel developers for most of the SCC-specific defines
in ./include/scc.h, and to Linux developers for the defines in ./include/apic.h.
Furthermore, the ideas for getting a "reset vector" to address 0xfffffff0 were
derived from SCC Linux.  And finally, thank you to several members of the Intel
Many-core Applications Research Community -- in particular Ted Kubaska and Jan-
Arne Sobania -- for their prompt and clear responses to questions arising
during development on the SCC.

Questions?  Ask me on the MARC forums.  My username is mziwisky.  Also, if you 
find this useful, I'd love to hear about it.

================================
==== Listing of directories ====
================================

boot -- contains assembly for platform initialization.

compile -- contains Makefile and other files needed for compilation.

include -- contains header files for the stripped down C lib and some SCC 
functions.

lib -- contains stripped down C library.

miketerm -- tool for reading output from SCC cores.

system -- contains source for interrupt handling, some platform 
initialization, and some SCC functions.

test -- default location for user code.

===================
==== Changelog ====
===================

v7 (June 12, 2012):
-- Updated MikeTerm.  Used to get output from sccDump by using a file in /tmp,
   but now does so via a pipe.  This avoids sharing conflicts on that temporary
   file.
-- Added section headers to this README to make it more readable.

v6 (May 3, 2012):
-- Added support for linking in the baremetal RCCE V2.0 library.
-- A few more #defines in include/scc.h along with additional page mappings in
   boot/initPaging.c to support the special FPGA registers that were new with
   sccKit v1.4.0
-- MPB pages now use PMB flag and not CD (cache disable) flag by default

v5 (Jan 26, 2012):
-- Some comments added in a couple of source files and in this README to
   properly acknowledge a few people who have contributed to this framework.

v4 (Jan 20, 2012):
-- Caching is now enabled.
-- Paging is enabled and configured for a flat address space.  (Paging is a
   prerequisite for caching.)
-- License information has been included in LICENSE file.
-- No longer need to call ack_APIC_irq() at the end of LINT handlers -- it is
   taken care of by setupLINT().

v3 (Dec 20, 2011):
-- Added real-time clock support using the local APIC timer.  Files added:
   system/clock.c, system/clockIRQ.S, include/clock.h, and include/conf.h.
   Disable clock by setting RTCLOCK to FALSE in conf.h.

v2 (Sep 10, 2011):
-- Added this changelog.
-- Fixed miketerm bug where some lines would be missing the core designator at
   the beginning.
-- Added restore() to restore global interrupt state to a saved value.
-- Made acquire_lock() disable global interrupts and release_lock() restore
   global interrupts state to its value before acquire_lock() was called.
   Added this to avoid deadlock -- e.g. if a lock is acquired and an interrupt
   handler runs that also tries to acquire that lock before it was released,
   deadlock occurs.

v1 (Sep 8, 2011):
-- miketerm now works with sccKit 1.4.1 (on my machine, at least!)
-- Changed get_my_coreid() and get_my_tileid() to be more efficient. I.e.,
   each core reads and stores its own coreid and tileid at initialization,
   then those functions simply reference the stored values rather than getting
   them from the MYTILEID register each time.
-- Added enough LAPIC configuration to get inter-core interrupts working.
-- Added interrupt_core() for triggering a LAPIC interrupt pin (LINT0 or
   LINT1) on any core.
-- Added acquire_lock() and release_lock() for acquiring LOCK0 and LOCK1
   test-and-set tile registers.
-- main.c demonstrates setting up LINT0/1 handlers and using one core to
   interrupt another.