Overall Project Structure

Blueshell has gone through a phase of rapid development over the last couple of years, with barely any documentation covering the newer features. This page attempts to give an overview of the various components of the Blueshell platform.


  • AxiConn/AxiDeviceConn.bsv - These components are for bridging Bluetree onto a standard AXI bus. Please note that these files are never contained within Bluespec top-level files except in special cases. These are build by the "setup_dir" script, which then builds these files and copies them into an XPS pcore. They then become part of the bluetree2axi and memorydevicebridge pcores.
  • Bluetree.bsv - The core Bluetree routers. This defines the Bluetree Client/Server interfaces and gives an implementation of a very simple Bluetree router.
  • BluetreeCommit.bsv - Creates "commit" interfaces. These allow for full handshaking and acks over a Bluetree connection. Based off the Bluespec CommitIfc.bsv.
  • Bluetree*Arbiter.bsv - These are Bluetree monolithic arbiters. They contain a single-cycle demultiplexer into many processor queues, which are then arbitrated and multiplexed back onto memory. Of course, these suffer from the typical problems of monolithic arbiters; they are large, cannot be clocked fast (due to the multiplexing) and unwieldy to use. They exist purely for design-space experimentation.
  • Bluetree*RateLImiter.bsv - These are Bluetree rate limiters. These are in-line rate limiters (in that they have a single client and server port) and are intended for distributed Bluetree arbitration.
  • BluetreeRateLimiterRoot.bsv - This is used to notify the rate limiters when a packet has been accepted.
  • BluetreeRateLimiter.bsv - This simply provides some standard interfaces to the actual rate limiters.
  • Bluetree*MuxN.bsv - These are Bluetree multiplexors with arbitrary sizes. In addition, there are variants which also support explicit arbitration (e.g. TDM) over the input ports. These are mainly again for design-space experimentation. Note that an arbitrary-width mux will route a packet in a single packet, so large multiplexors will have a large timing latency.
  • BluetreePrefetcherBase.bsv - The base of the prefetcher. This connects to a prefetcher logic block, and handles squash detection and the actual dispatching of prefetches.
  • BluetreePrefetcherBase2.bsv - The badly named second iteration of the prefetcher base. This maintains compatibility on the logic interface, but exposes a "Commit" interface from the top. This allows prefetches to be cancelled.
  • BluetreePrefetcherBase3.bsv - This uses a set of output registers instead of a FIFO to log prefetches, which allows prefetches to be overwritten. This doesn't have a timeout like Base2, but simply only uses the most recent prefetch.
  • BluetreeSlotPrefetcherBase.bsv - This is a prefetcher which instead uses the concept of a prefetch slot, which allows the logic to tell the prefetcher when there is dead time which can be used for prefetching. This prefetcher base wasn't used much, and was superseeded by the second iteration rather quickly.
  • BluetreeSlotPrefetcherBase2.bsv - This is another iteration of the BluetreeSlotPrefetcherBase. This uses a set of output buffers instead of queues, so that prefetches can be invalidated. It also allows for a non-dispatched prefetch to be invalidated by a demand miss arriving and getting service first. This also uses the task_id field to determine whether a read was a squash or not, for different handling by a downstream cache. There are a multitude of changes.
  • Bluetree*Prefetcher.bsv - The actual prefetcher logic. BluetreeOptimisedPrefetcher.bsv is the main example of this.
  • BluetreeAutoBurst.bsv - This is a prefetcher which when it observes a hit, blasts out as many prefetches as possible from that address until the next miss for that CPU.
  • BluetreePerfectPrefetcher.bsv - This has a BlockRAM containing the addresses to fetch and the lengths. This fetches n of these, then moves on when it gets hit feedback.
  • BluetreeRTASCache.bsv - This is a cache with a set of "streams" in it to log prefetches, used in the RTAS paper. This does not support writes, but does provide hit feedback.
  • BluetreeRTASCache2.bsv - This is an evolution of the previous cache which only gives hit feedback if the hit is the first in the stream, and allows the prefetcher to dictate which stream to use. This is used in the post-RTAS work.
  • BluetreeProxy.bsv - A CDC for Bluetree. This is typically located at the top of Bluetree and crosses into the memory domain of the ISE/Vivado top-level.
  • BluetreeTrafficGenerators.bsv - A collection of synthetic traffic generators for Bluetree. These are used since they can fire requests with better timing predictability than a processor, and without the limitations of processors (i.e. they can have multiple in-flight reads).
  • BootROMClient.bsv - The boot ROM. The contents are copied to memory on bootup.
  • BRAMServer.bsv - A blockRAM based RAM.


  • BluetilesAxiProbe.bsv - Exposes a Bluetiles probe onto Bluetree. This is used to interrogate the Axi bridge for statistics. This could not be done by adding a Bluetiles interface to the AXI bridge (easily) since the AXI bridge typically sits outside of the Bluespec side of the project.
  • Bluetiles.bsv - Simple helpers and interface definitions for Bluetiles.
  • BluetilesRouter.bsv - The standard Bluetiles router.
  • TilePingPong.bsv - Simple ping-pong core. Any incoming packets are reflected.
  • TileVlab.bsv - the interface to the VLab scripts. Also exposes the serial port to the outside world.
  • MutexManager.bsv - provides hardware mutex support onto Bluetiles. This is required for mutual exclusion due to the lack of another hardware test-and-set facility.


  • Microblaze.bsv - This is the actual top-level wrapper around a Microblaze processor. This exposes mkMicroblaze().
  • MicroblazeL0.bsv - This is the hardware interface to the Microblaze code. This is mainly a BVI wrapper in order to connect the actual processor in, and the communications with the SPM and cache. This must have a cache interface provided to it to communicate with the caches.
  • MicroblazeL1Cache.bsv - This is the cache to connect to Microblaze.
  • MicroblazeNoCache.bsv - This is to create a Microblaze without cache.
  • Patmos.bsv - This is the top-level Patmos connection. This instantiates a Patmos processor and connects it to its Bluetree bridge and Bluetiles bridge.
  • PatmosL0.bsv - This connects to the actual Patmos Verilog core. As with MicroblazeL0.bsv, this is basically just a BVI wrapper.


  • Todo. Misc stuff is typically left over from other experiments.