Carte Blanche

Notes and Ramblings

                                

The Carte Blanche card is an Apple II peripheral board containing an FPGA, Flash memory chip, SRAM and many connectors to use for such things as a VGA output, IDE devices and an SD card.  About 50 were produced by Steve Howell and Alex Freed and shipped in September 2009.  More information can be found here.

The following is some of what I've learned or think I've learned using the Apple II Carte Blanche card.  The first part is general information about the way I went about using the Carte Blanche and The Xilinx ISE tools.  Later on the information is more specific to a project I've been working on to modify the original JAT (Jack of All Trades) code for the Apple IIgs.  My way of doing things isn't necessarily the right way but I offer it in the hope that it may help someone else get started in what has turned out to be a lot of fun for me.  

When I received my card I felt a little overwhelmed.  I knew nothing about FPGAs (Field Programmable Gate Arrays), Verilog (Hardware Description Language) used to program the FPGA and although I had already downloaded the ISE Webpack tools from Xilinx I had no idea how to use them.  Why did I buy the Carte Blanche card?  I like programming and I like Apple IIs so this seemed like it would be a lot of fun.  So where to begin?  The Carte Blanche came with some sample bitstream files.  A bitstream is a file generated by the Xilinx tools that can be sent directly to the FPGA through a JTAG cable or saved to an SD card and used to write to the onboard flash memory.  It is important to note that a bitstream in the Flash memory is automatically loaded into the FPGA every time the Apple is powered up while a bitstream sent to the FPGA is lost when the power is turned off.  There is a supposed to be a way to program the Flash using the JTAG cable but I have never gotten that to work.  Since the logic to copy a bitstream from the SD card to the flash memory is in the currently operating FPGA it is possible to have a failure flashing and then be unable re-flash.  For this reason don't flash the CB card until you have a known working JTAG cable.  Besides you probably won't want to flash every time you create a bitstream.  For any kind of development you are going to be creating bitstreams often.  It is much more efficient to use the JTAG cable until you've got all the bugs out of your code. 

I use a Digilent parallel JTAG cable connected to the JTAG “flying leads” cable supplied with the CB card.  I used short pieces of bare wire to connect the two cables since they both have female connectors.  Using the Xilinx ISE 11.1 tool (iMPACT) it takes about 4 seconds to send a program (bitstream) to the Carte Blanche.

I like programming and for me the best way to learn a new language is to look at someone else's code.  Alex Freed put the JAT source files online.  You can now download them from sourceforge.  Yep, download them all.  They may not all be needed but it's easier to just grab them all then trying to decide what you need.  Besides there is tarball download link at the bottom of the page to get them all.  Put all the files and folders in a folder on your computer.

Getting started with Xilinx ISE Webpack and JAT:

How to use the files?  I downloaded and installed the Xilinx ISE Webpack which puts a lot of shortcuts on your computer.  The one you will use is labeled Xilinx ISE 11 (The version I have is 11.1 and as of this writing Xilinx is up to version 13.1 so there will be differences).  Clicking on the shortcut opens the ISE Project Navigator.  Nearly everything you do will be from this program.  From the File menu I selected Open Project... and got a pop up dialog like the one below. Navigate to the folder where you saved the JAT files:

Note that the JAT project was created on an earlier version of Xilinx ISE tools so I had to use the drop down menu to select the right file type.

Next I got a window asking me to confirm that I wanted to update the project.

I clicked Yes and the project was opened in the ISE Project Navigator.

  

In the upper left there is a pane labeled Hierarchy.  Each of the items in the treeview under the CarteBlanche item represents something that you can edit.

Double clicking on item:

xc3s500e-5pq208:    Allows you to make major changes to the settings of the project such as the programming language used and the device you are programming.  If you are using the 250 version of the FPGA then you can change the setting here (and the item label will then be changed to xc3s250e-5pq208).

CarteBlanche1 (cb1.v) and any item with the icon:    Opens the Verilog file for editing in the large window pane to the right.  The name in parenthesis is the actual file name.  CarteBlanch1 (cb1.v) is the main (top) module (denoted by the ) for the project.  It must be selected (high-lighted) when you generate a programming file (bitstream).

track_buff - track_buff (track_buff.xco) and any item with the icon:  Opens a core generator wizard for memory blocks in this project.  The data is loaded from .coe files.  In the font0 - font(font.xco) item I made a new file A2ECHRROM.coe which contained mousetext characters.  Here is the .coe file format I used:

memory_initialization_radix=16;
memory_initialization_vector=
1C,22,2A,3A,1A,02,3C,00,08,14,22,22,3E,22,22,00,1E,...... many more .................FF

clock - clk0 (clk0.xaw):  Opens a DCM (Digital Clock Manager) wizard.  The Carte Blanche card has a 14.31818MHz system clock on board and it is used by the DCM to create a 50 MHz clock that is used for much of the project.

z80_scope.cdc (z80_scope.cdc):    I don't have Chipscope so I had to remove this item from the project by right clicking on it and selecting Remove.

cb.ucf (cb.ucf):  Opens the constraints editor if you have already generated a programming file otherwise you can just select cb.ucf (cb.ucf) with a single click and then expand the User Constraints item in the Processes pane directly below the Hierarchy pane.  Finally you double click on the Edit Constraits (Text) item which allows editing in the large pane to the right.  The cb.ucf file contains the labels used for the actual pins on the FPGA.  Verilog code modules reference those labels as inputs/outputs. 

Before I did anything else I tried generating a programming file.  To do that I selected the CarteBlanche1 (cb1.v) item and then double-clicked on the Generate Programming File in the Processes pane directly below the Hierarchy pane.  I got 3 errors; probably because I'm using a newer ISE version than the one used to create the original JAT project.  Errors and warnings can be seen in the Design Summary.

      

Errors are bad.  They stop things cold.  No bitstream is generated.  Clicking on the 3 Errors link produced the second list.  Scroll down till you see the error icon .  Right clicking on the selected error gives you the option to copy the entire error message.  Here it is:

Place:1018 - A clock IOB / clock component pair have been found that are not placed at an optimal clock IOB / clock site pair. The clock component <BUS_PHASE0_IBUF_BUFG> is placed at site <BUFGMUX_X1Y10>. The IO component <BUS_PHASE0> is placed at site <P20>. This will not allow the use of the fast path between the IO and the Clock buffer. If this sub optimal condition is acceptable for this design, you may use the CLOCK_DEDICATED_ROUTE constraint in the .ucf file to demote this message to a WARNING and allow your design to continue. However, the use of this override is highly discouraged as it may lead to very poor timing results. It is recommended that this error condition be corrected in the design. A list of all the COMP.PINs used in this clock placement rule is listed below. These examples can be used directly in the .ucf file to override this clock rule.
< NET "BUS_PHASE0" CLOCK_DEDICATED_ROUTE = FALSE; >

Notice that it gives you a way to get around the error.  I've highlighted the pertinent parts.  What it is saying is that you can edit the cb.ucf file to make the error go away.  In fact all three errors are the same type so we can edit the cb.ucf file for all three.

After adding the three lines above to the cb.ucf file, I saved it and again selected the CarteBlanche1 (cb1.v) item and then double-clicked on the Generate Programming File in the Processes pane and this time no errors and a bitstream (carteblanche1.bit) was saved into our project folder.

Even though I no longer had any errors, all signals were completely routed and I had generated a bitstream file I still had warnings.  Lots of them.  More than 200.  Some of these warnings can be useful when trying to improve your design.  Xilinx however issues warnings for almost anything.  Most can be safely ignored.