Charlie's Stuff

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 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:

Open project screenshot

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.

Project update confirmation screenshot

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

Project Navigator screenshot

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.

Project status screenshot showing errors Project messages screenshot showing errors

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.

screenshot of added constraints

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.

Programming the FPGA:

Next I wanted to make sure I could program the FPGA on the Carte Blanche card. For that I selected iMPACT... from the Tools menu. The AppleLogic website has information on using iMPACT. I used a slightly different approach because my version of iMPACT acted a little different from theirs. NOTE: The Carte Blanche card must be installed in the Apple II, the JTAG cable connected and the Apple II must be powered on.

When I ran iMPACT The first thing I got was:

Warning. No impact file exists. Click okay to open impact for configuration.

Clicking OK I got the following:

ISE iMPACT screenshot with list of iMPACT Flows. Boundary Scan, SlaveSerial, Direct SPI Configuration, SystemACE and PROM File Formatter

Selecting New Project from the File menu brought up this window:

iMPACT screenshot with Configure devices using Boundary-Scan (JTAG) selected.

Clicking OK finds and connects iMPACT to the FPGA via the JTAG cable and pops up a navigation window:

screenshot of Project Navigator, iMPACT - Boundary Scan and Assign New Configuration File window with cartblanche1.bit file selected

Once you find the bitstream file (cartblanche1.bit) that you just generated and open it you get yet another window:

This device supports attached Flash PROMS. Do you want to attache an SPI or BPI PROM to this device? Yes No

This one is important. If you click Yes it guides you through another series of steps to send the bitstream data to the Flash PROM and then optionally program the FPGA. These steps actually require you to create another file and enter chip information, etc. All of this would be great but unfortunately I've never gotten it to work.

Note: The flashing function seems to be broken in iMPACT version 11.1. In 2013 I started using version 11.4 and the flashing function was fixed.

So for now I just click No. Next you get:

screenshot of Device Programming Properties

Just click OK.

screenshot iMPACT - Boundary Scan with dropdown list of options. Program is at top of list

Right click on the little FPGA symbol and select program.

screenshot iMPACT - Boundary Scan showing Program Succeeded

If everything went well you should see the Program Succeeded message. If you see a red failure message check your connections and again right click on the little FPGA symbol and select program.

Once you have succeeded in programming the FPGA save the configuration so that you don't have to go through all the windows and clicks. You can do that from the File menu by selecting Save Project As...

Now I was ready to dig into the code...

Well, almost.

At this point you should be able to edit the JAT code making little changes to see how things work. That's what I did but it wouldn't hurt for me to mention a couple of other features of the Xilinx ISE Webpack that I found useful.

Schematic Viewer:

After generating a program file you may want to know what the code would look like in a schematic. For instance if you open the video_module in the editor window and scroll down to line 109 you'll see:

wire allow_shift7 = mode_80COL ? 1 : h_count[0];

To see what a hardware schematic of that line looks like select Schematic Viewer from the Tools menu:

screenshot of Project Navigator with Tools - Schematic Viewer - RTL... selected. In editor section wire allow_shift7 = mode_80COL ? 1 : h_count[0]; is selected

Notice that I picked RTL... which displays a schematic of the pre-optimized design independent of the target device (FPGA). The RTL schematic is displayed as gates, counters, adders, etc. If you choose the Technology... function the schematic is of the design optimized for the targeted FPGA. The Technology schematic is displayed as LUTs (Look Up Tables), I/O buffers and other components specific to the target device. Both views are accessed in the same way but I've found that the RTL view is easier to understand although the Technology schematics do include truth tables and Karnaugh maps.

From the resulting screen scroll down the list of elements to video_module, expand it and scroll down to and select allow_shift7_imp. Then click the Add button and then the Create Schematic button:

Create RTL Schematic screenshot with Allow_shift7_imp added

Now you see...

block schematic of allow_shift7_imp showing inputs h_count(0) and mode_80COL. Output is allow_shift7

Nice but not all that interesting. By right clicking on the selected object (red) and selecting Show Block Contents (or just double clicking the object) you get a better view.

schematic of allow_shift7_imp:1 showing inputs h_count(0) and mode_80COL. Internal gates are also shown. Output is allow_shift7

You can put as many components into the schematic as you want and there are commands to show everything upstream (Add Input Cone...) and downstream of the (Add Output Cone...).

Language Templates:

If you are new to Verilog and/or the usage of the UCF file then selecting Language Templates... from the Edit menu will bring up treeview where you can navigate to examples of the syntax and usage.

screenshot of project navigator Language Templates example

While the Schematic View and the Language Templates are not necessary to programming the CarteBlanche they make it easier and more fun.

As I've mentioned I like to learn from digging into existing code. Really studying it until I think I understand what's going on. Then I play with the code by changing things to see what results. Xilinx ISE allows you to program in either Verilog or VHDL. I chose Verilog because the JAT code was written in Verilog. I also felt at the time that I had an advantage because I know how to program in C and Verilog has a similar syntax. That may be true but for someone like me whose hobby is programming and not hardware the biggest hurdle was accepting the concept that everything is happening at once instead of the nice sequential nature of normal computer languages like C.

One of the first things I noticed when I powered up with Carte Blanche installed was that the JAT menu screen had colored text. When I mounted an image from the menu and booted it the text reverted to the normal Apple II white text. Neat! How was that done? At first I looked in the video_module. Trying to understand what the code was doing, I was soon overwhelmed but by the time I got to the end I was pretty sure there was nothing there that changed the text color. Next I searched the Carte Blanche module, the main module for the project, and there I found something:

wire active; // visible portion
wire [7:0] video_ram_data = z80mode ? {1'b1, z80_video_data_out[6:0]} : ram_data;
wire [10:0] lin_address;
wire [5:0] RGB_from_module;
wire hl = (text_line == highlite) && active;

// make text amber in z80 mode
assign RGB = z80mode ? {RGB_from_module[5:2], hl, hl} : RGB_from_module;

I found that RGB is a 6 bit (6 wires) output of the Carte Blanche module by looking at the input/output labels at the beginning of the file. RGB usually stands for Red-Green-Blue. I assumed that z80mode meant the z80 processor was running. RGB_from_module turned out to be the 6 bit RGB output of the video_module. I found that (RGB) in the code following the suspect line (see video_module instantiation below). In Verilog (and in C) the ? and : are used to create an if-then-else statement. So that line would mean:
If z80mode is true then the leftmost four RGB bits equal the leftmost four RGB_from_module bits and rightmost two RGB bits each equal hl else all the RGB bits equal the RGB_from_module bits. This had to be the right line. Of course the comment // make text amber in z80 mode was also a pretty good clue ☺

vga_video // video_module instantiation
video_module (
.clk50(clk50),
.char_data(char_data),
.ram_data(video_ram_data),
.bus_addr(BUS_A),
.ph1(ph1),
.Q3(BUS_Q3),
.rw(BUS_R_W),
.reset_n(~reset),
.auxmem(auxmem),
.mem_available(mem_available),
.update_time(update_time),
.video_read(video_read),
.v_sync(v_sync),
.h_sync(h_sync),
.rom_addr(rom_addr),
.ram_address(ram_address),
.lin_address(lin_address),
.RGB( RGB_from_module),
.text_line(text_line),
.active(active),
.hgr(hgr),
.clk25(clk25)
);

I decided to play with this line by changing it to:

assign RGB = z80mode ? {hl, hl, RGB_from_module[3:0]} : RGB_from_module;

And as I suspected it turned the text in the JAT menu to a blue-green color. Not only had I learned how to easily change the text color but I'd also learned that the JAT menu was running under the z80 processor. This little example I've given may not seem like much but it was the first step towards implementing the Apple IIgs color text mode (also border and background).

I have both and Apple //e and an Apple IIgs. Most of time the Carte Blanche card is in the Apple IIgs which is my favorite machine. The JAT code was written more for the Apple //e. For notes about my modifications for the Apple IIgs click here. For information about my modifications for the Apple //e click here.

Super High Resolution

graphics on an Apple //e

While programming the Carte Blanche card in my Apple IIgs to display super hires graphics (SHR), it occurred to me that there didn't seem to be any reason that this function couldn't be added to an Apple //e. In fact I wonder if the designers at Apple Computer originally intended to add SHR to a //e. On an Apple IIgs all the video data resides in bank 01 which is the same as the auxiliary bank on a //e. This is true even though the IIgs supports up to 8 MB of RAM. Of course a //e doesn't have the circuitry to handle SHR but if you add a Carte Blanche card you can add your own circuitry. The 12 bit color mod is necessary as well so that all the SHR colors are available. So basically I took the SHR code I'd written for the IIgs and with a few minor changes made it work in my Apple //e.

Why would anyone want SHR on their //e? After all there are few, if any, 8 bit programs designed to work with SHR. Here are three reasons:

1. If you enjoy programming you can write your own programs that use SHR. There won't be many others to share the programs with but since the Apple //e SHR has been implemented to be nearly the same as the Apple IIgs SHR, a program written for the //e should also work in a IIgs.

2. View pictures created for the IIgs. I see this as the most likely reason most people would want SHR.

3. Its just plain neat seeing your Apple //e doing Super High Resolution Graphics. Here are some pictures taken of Super High Resolution graphics screen images on an old 17" Dell LCD monitor, model E172FPt connected to my Apple //e. My camera doesn't do them justice. They are much better live. Click on each to enlarge.

The resulting bitstream is a big departure from the from original JAT bitstream and my earlier //e modifications. It resembles my IIgs bitstream version 9.20 in that it has all the JAT functions removed except the VGA video. My previous JAT bitstream modification had the ability to set the colors of text, background & border. That ability remains with the added feature that a program can now read the softswitch $C022 for text & background color and $C034 for the border (before you could only write to them). Text, both 40 & 80 column and LORES graphics remain the same and DHR is the same as on the IIgs bitstream (which isn't very good). I have added a IIgs type setting to allow Grayscale DHR for what it's worth. I have slightly modified the HIRES graphics to output every color pixel in a line instead of every other pixel.

The main video difference of course is the addition of SHR (Super High Resolution) graphics. From the user's point of view SHR functions in virtually the same way as on an Apple IIgs. The video memory area is the same and controlled by softswitch $C029. 640 and 320 horizontal resolution modes are the same although the number of lines is doubled to 400. Fill mode is there as well. At this time the only SHR thing not supported is scan line interrupts. Video modes supported:

TEXT 40 Column	Super High Resolution Graphics 640 - 4 colors per line
TEXT 80 Column	Super High Resolution Graphics 320 - 16 colors per line
Low Resolution Graphics	Super High Resolution Graphics 320 - 15 colors per line with color Fill
Double Low Resolution Graphics ¹
High Resolution Graphics
Double High Resolution Graphics	Double High Resolution - Grayscale
Mixed mode (Graphics & Text)

¹ has not been tested.

Another addition is the ability to save settings and retrieve them on startup. This is similar to the battery RAM on an Apple IIgs only without the need for a battery. With this bitstream version there are four settings that can be saved; Text color, background color, border color & DHR Grayscale (enable/disable). An Applesoft BASIC control (CBCONFIG) is included to set and/or save these settings.

Finally, the ability to flash the Carte Blanche onboard non-volatile RAM chip from the Apple //e is embedded in the bitstream. This is needed because the original JAT flashing function has been removed. An Applesoft BASIC program (FASTFLASH) is included to handle the Apple //e end of the procedure.

Requirements:

An 128K Apple //e (enhanced).

A Carte Blanche card (250 version).

The 12 bit color mod (cable or board). ²

A VGA monitor.

An Apple //e storage device large enough to hold the 170K bitstream file. ³

A way to get the bitstream and related utilities into the storage device.

² SHR will work with the Carte Blanche 6 bit color but you will only have 64 colors.

³ Only needed if you don't have another way to program the Carte Blanche card (JTAG).

General information on Super High Resolution graphics

Super High Resolution (SHR) graphics modes are normally found on the Apple IIgs. Bitstream version 3.00 allows you to display, on an Apple //e, both 640 x 200 and 320 x 200 pixels. In both cases the number of lines is doubled to 400 (each line is duplicated) so that it fits better on the screen.

Detailed information on SHR graphics can be found in Apple IIgs references but I have included the basic information below:

Softswitch $C029:

            Bit 7 = 1 disables //e video (on the VGA output) and enables SHR
            Bit 6 = 1 linearize SHR (always linear on the Carte Blanche)
            Bit 5 = 0 color double hi-res - 1 for Grayscale DHR
            Bits 4 to 1 should be set to zero
            Bit 0 = 1 enables bank 1 latch on a IIgs (not used on a //e)

SHR video memory:

            All the video data is located in the auxiliary bank of the //e.
            $2000 - $9CFF contains the pixel data.
            $9D00 - $9DC7 contains 200 scan line control bytes.
            $9E00 - $9FFF contains 16 palettes

Pixel Data:

            Pixel data is contained in bytes in a linear order (unlike //e modes).
            Located in the auxiliary bank at $2000 to $9CFF.
            Each byte contains pixel data for either 640 or 320 mode.

Bits in byte

640 mode

Pixel 1

Pixel 2

Pixel 3

Pixel 4

320 mode

Pixel 1

Pixel 2

The pixel data does not refer to a color but to a position (two bytes wide) in a palette that holds a twelve bit color. In the 320 mode this is pretty straightforward since there are 16 palette positions and four bits can represent any one of those. In 640 mode there are only two bits per pixel so only four positions can be represented.

So in 640 mode:

            Pixel 1 uses positions $8 - $B in the palette.
            Pixel 2 uses positions $C - $F in the palette.
            Pixel 3 uses positions $0 - $3 in the palette.
            Pixel 4 uses positions $4 - $7 in the palette.

Scan line control bytes:

There are 200 bytes (one for each scan line) that determine how each line is to be displayed.
Located in the auxiliary bank at $9D00 to $9DC7.

Bit 7 = 1 enables 640 pixels for the line (0 = 320).
Bit 6 = 1 interrupt enabled at the beginning of the line (0 = interrupt disabled).
Bit 5 = 1 fill mode enabled for 320 mode only (0 = fill mode disabled).
Bit 4 = 0 not used.
Bits 3 to 0 = the number of the palette to use for the line.

Palettes:

There are 16 palettes each containing 16 x 12 bit colors.
Located at $9E00 to $9FFF in the auxiliary bank.

Colors:

Each color is 12 bits long and takes up two bytes in a palette.
Even bytes:

Bits 7 - 4 green
Bits 3 - 0 blue

Odd bytes:

Bits 7 - 4 not used
Bits 3 - 0 red

12 bits allows 4096 possible colors.
With 16 palettes of up to 16 colors the screen can have up to 256 colors at one time.

If you want to write SHR 8-bit programs that run on both the Apple IIgs and the Apple //e using the Carte Blanche card you need to be sure that "shadowing" is turned on for SHR and turned off for any graphics mode that could interfere with the SHR, for instance the auxiliary page of Double Hires. The IIgs has a Shadow register that can be used for these settings:

Shadow Register $C035:

Bit 7 = 0 always.
Bit 6 = 1 to inhibit I/O and language card operation.
Bit 5 = 0 always.
Bit 4 = 1 to inhibit shadowing aux hi-res page.
Bit 3 = 1 to inhibit shadowing SHR 32K video page.
Bit 2 = 1 to inhibit shadowing hi-res page 2.
Bit 1 = 1 to inhibit shadowing hi-res page 1.
Bit 0 = 1 to inhibit shadowing text pages.

On the //e with SHR there is no shadowing or shadow register but code written to use them will have no effect. You also need to set bit 6 of $C029 on an Apple IIgs to ensure that the graphics will be linear before writing any data to the video area.

CBCONFIG

CBconfig is an Apple II program to allow a user to easily control several features on the CB (Carte Blanche) card that is using a compatible bitstream.

USING CBCONFIG

The purpose of CBconfig is to change and optionally save certain settings to the Carte Blanche flash memory. CBconfig is an Applesoft BASIC program which is started by typing RUN CBCONFIG and pressing the Return key.

The first thing CBconfig does is check for a Carte Blanche card running a bitstream that is compatible. If it does not find one it will quit with an appropriate message.

Assuming it finds a Carte Blanche card with suitable bitstream it then attempts to load settings data from the card's flash memory. If it doesn't find data CBconfig creates default settings. In any case it displays a control panel screen.

screenshot of cbconfig

It is important to realize that the values displayed are the ones that were previously saved. If you have changed the settings they will revert back to those last saved.

To change a value use the up/down arrow keys to highlight the setting you want to change. Use the left/right arrow keys to change the value.

For Text, Background and Border there are 16 colors and they are immediately changed each time you press the left or right arrow key. CBCONFIG will not let you enter the same color for text and background (although you can poke them in if you really want to). Grayscale DHR is set (checkmark) or un-set with left/right arrow keys as well and it too is immediate although nothing apparent happens. Grayscale DHR means that all Double High Resolution pictures will be displayed without color.

All the settings last only until the Apple II is shutdown unless they are saved.

Once you are satisfied with the values you do not need to run CBCONFIG again. Your settings will be there the next time you run the Apple.

You save your settings by pressing the S key while holding down the open-apple key. The open-apple symbol becomes solid until it finishes saving when it flickers back to the original open-apple.

Pressing the Esc key exits cbconfig.

FASTFLASH

Since the other JAT functions are no longer available, the built in ability to flash a new bitstream from the SD card is lost. To avoid being "painted into a corner" version c302 has the ability to flash a bitstream directly from the Apple. I've included an Applesoft program (FASTFLASH) that will allow you flash another bitstream.

BEFORE USING FASTFLASH

Before you flash, read everything below and be sure you understand what you are doing. A mistake could leave you with a Carte Blanche card that won't work and may be hard to get working again.

The FPGA on the Carte Blanche card is programmed from a flash memory chip each time the Apple is powered up. The other way to program the FPGA is through a JTAG cable connecting the Carte Blanche to a PC. If you have this cable and understand how to use it then you can't get stuck in a situation where you have no way to flash the Carte Blanche. You simply program the FPGA through the JTAG cable with a JAT bitstream and then flash the bitstream you want from the SD card. FASTFLASH is for someone who doesn't have a JTAG cable or doesn't know how to use it and has already flashed a FASTFLASH compatible bitstream to the Carte Blanche card.

USING FASTFLASH

FASTFLASH needs the included binary file GETFILELEN to be in the same folder. It is also a good idea to have the bitstream file in the same folder.
FASTFLASH is an Applesoft BASIC program that you run by navigating to the folder where FASTFLASH is located and typing RUN FASTFLASH.

If all goes well FASTFLASH will prompt to enter the letter Q to exit the program or enter the filename of the bitstream you want to flash and press return. This is your last chance to stop the process. Once you enter a filename and press return you must NOT turn off the computer until the flash is complete.
If FASTFLASH is terminated for some reason before it has completed the flash, immediately re-run it. Do not turn off the computer until you have a finished flash.

If you enter a file name or pathname that doesn't exist, FASTFLASH will tell you that it couldn't find the file or path and prompt you to Try again? (Y/N):.

Several other input errors will prompt you to try again.

FASTFLASH does limited checking based on file size to determine if the file is actually a bitstream.

While flashing, FASTFLASH will keep you informed of the progress. It first tells you it is erasing the area where the bitstream is to be flashed. It then displays the page number being flashed, any errors and the percentage of the flash completed. A page is 256 bytes and the bitstream has about 662 (numbered 0 to 661) pages.

If you get any errors while flashing do not shut down the computer. ^*
Instead run FASTFLASH again. If you get errors early on in the flash you can press Control - C and re-run FASTFLASH.

Once you have a successful flash you must restart the Apple to let the Carte Blanche card use the newly flashed bitstream.

MORE ABOUT FASTFLASH

When you first run FASTFLASH it looks for the slot that the Carte Blanche is in and the installed FPGA firmware (bitstream) version. If FASTFLASH can't find the Carte Blanche card it terminates with the message:

PROGRAM NOT SUPPORTED BY THIS BITSTREAM.

If the FPGA firmware version is not 3.xx FASTFLASH will terminate with the message:

NEEDS VERSION 3.00 OR HIGHERER.

FASTFLASH is intended for this bitstream (or possible future bitstreams) already loaded in the Carte Blanche FPGA. However, you can use it to flash any bitstream meant for the 250 version Carte Blanche. The bitstreams for the Carte Blanche 500 version are larger and need more space on the flash memory chip. FASTFLASH only erases three sectors of the sixteen on the chip. It would have to be modified to erase more sectors for the 500 version.

Of course if you have a JTAG cable connected between a PC and the CB card, you can use the Xilinx iMPACT program to load a JAT bitstream and then use that to flash.

The speed of the flash is mostly determined by the disk I/O on the Apple //e system. If the bitstream file is on a CFFA hard drive it will take about 5 minutes and 15 seconds to flash. If the bitstream is on a 3.5" floppy disk, the flash will take much longer. The flashing function in the original JAT bitstreams is much faster. You may be wondering then why this program is called FASTFLASH even though it is slow compared to the JAT flashing function. I called it FASTFLASH because it is at least ten times faster than the original flashing program method I distributed with the Apple IIgs bitstream version c920. That method took nearly an hour to flash the CB on an accelerated (8 MHz) Apple IIgs with the bitstream located on a SCSI hard drive.

^*I occasionally get errors while flashing. I'm unsure why but I strongly suspect they are from electrical noise on the system. It may be best to remove unused cards from the Apple //e while flashing. If you are using an Uthernet card remove it while flashing or at least disconnect the Ethernet cable. Move any sources of noise away from the //e such as fluorescent lights, CRT monitors or TVs.

Carte Blanche

Notes and Ramblings (IIgs)

Part 1

Carte Blanche bitstream modified for a ROM 01 Apple IIgs.

The following includes some information I have learned from playing with the code for a Carte Blanche (CB) bitstream modified for a ROM 01 Apple IIgs. It should not be considered as gospel and is offered here only in the interest of explaining where I'm at with this project and maybe helping someone who is trying to do the same (or better yet maybe you can help me). You should also note that the vast majority of the work was done by Alex Freed and Steve Howell. I have only modified their code. Most of my modifications are to the video module.

Added Mousetext, color text, background and border:

Click on them to enlarge.

Characters

AppleWorks 3.0

Samsung Syncmaster940MW 19" LCD TV/Monitor using the 4:3 aspect ratio mode.
The colors set in the control panel were: Text & Border - Light Blue and Background - Medium Blue.

BYE bug fix:

While testing the //e mousetext version bitstream, Bill Garber noticed that when the jumper is removed from the IDE connector on the Carte Blanche card and the ProDOS "BYE" command is invoked the computer hangs. This can be fixed by adding one line (see high-lighted line below) in the cb1.v module. When the jumper is removed the CB card functions only as a VGA card.

always @(clk50, wr_clk, mem2k_data, disk_mode, N_BUS_IO_SEL, bus_a_s)
    begin
    if(wr_clk)
        begin
        if (~jumper) // added to fix BYE bug
            begin
            mem2k_data_reg <= mem2k_data;
            BRAM_addr <= (disk_mode[7] || N_BUS_IO_SEL ) ?
            { ~bus_a_s[10], bus_a_s[9:0]}:
            { disk_mode[2:0], bus_a_s[7:0]};
            end
        end
    end

Spurious Characters:

From the beginning I had a curious instability in the 80 column text mode. I would get spurious characters on the screen or occasional dropped (missing) characters. The 40 column screen was stable. This was much less a problem on the //e.

This problem dogged me for a long time. Some things I would do while working with some seemingly unrelated part of the code would suddenly stabilize it, only to have something else cause it to de-stabilize again. Baffled, I took the tried and true tactic of just ignoring it. Eventually, though I couldn't take it anymore. I found I could fix the problem by synchronizing all the signals from the Apple IIgs to the 50MHz FPGA clock. After that everything was rock solid. Here is a Verilog example of synchronizing the Apple Q3 clock to the 50 MHz clock used in the Carte Blanche code:

input clk50
input Q3
reg Q3_s; // Q3 synchronized
reg Q3_1;
always @(posedge clk50)
    begin
    Q3_1 <= Q3;
    Q3_s <= Q3_1;
    end

Resulting synthesized hardware:

schematic of 2 flip-flops sychronizing the Q3 signal with the 50 MHx clock

Disabled /INH:

The Apple IIgs maps the logical RAM addresses to physical RAM in an interleaving scheme that is different than that in an Apple //e. The result of this is that a card that is designed for a //e and brings the /INH line low can cause a bus contention when used on a IIgs. This is potentially damaging to the Mega II (see Apple IIgs Tech note #32). The original bitstream code for the Carte Blanche card has a line in the code that can pull the /INH line low. To avoid any problems on the IIgs I changed the following line in cb1.v from:

assign BUS_INH = breakpoint_hit ? 1'b0 :1'bz;

to:

assign BUS_INH = 1'bz;

This fix is ugly because it simply removes the function without any regard for what it does instead of using a mask as is recommended in the Apple IIgs Tech note #32.

Super Hires Graphics (SHR):

To test the possibility of having the CarteBlanche card support SHR graphics, I've added some SHR code. It doesn't faithfully represent what you see on the IIgs monitor. The main differences are:

It uses only 16 colors. The Carte Blanche card can display 64 colors. It wouldn't be hard to change the code to use all 64. I just took the easy way out by using the same colors as lores graphics. Still even 64 colors is a long way from the 4096 available from a IIgs. To get 4096 colors you would need a hardware change on the CB. I believe it wouldn't be too hard to do this by using the peripheral board pins or even the IDE connector pins and a few resistors.

I used a Fixed palette which means 16 colors is all we've got, not any 16 of the 64 the CB card is capable of. The code doesn't even look at the GS palettes. With the real IIgs video each line can have a palette (up to 16 palettes per screen) and each palette has 16 of 4096 colors in 320 mode or 4 of 4096 in 640 mode. Even if you made a 12 bit (4096 colors) output on the CB card you would still have to make four reads to the on-board SRAM to figure what color dot to output (1 for the pixel data, 1 for the palette and 2 for the color itself). The video output frequency is 25 MHz and the CB's main clock is 50 MHz so you might be able to make two reads to the SRAM but not four. You could increase the CB's clock beyond 50 MHz but I believe the SRAM won't work over 66 MHz or so. Clearly not enough. One way around this may be to use the FPGA RAM for the palette data. Unfortunately at this time the RAM is full.

There are no side borders if you are using a monitor that doesn't over scan. I've tested it on two LCD monitors and one CRT monitor. The CRT was the only one that showed the side borders. The Carte Blanche video output has a resolution of 640 x 480. Plenty for the //e that it was intended for but not enough width for the IIgs SHR mode and the side borders. To get the side borders you could have a faster second clock for the SHR that would give you 800 x 600 resolution or you could use a single fast clock and scale the non-SHR modes accordingly.

Colors don't dither correctly. Dithering is a technique of placing two different colors next to each other so that the eye perceives them as a third color. Dithering is used in the 640 mode desktop to obtain colors that would not normally be available. If it works correctly you should not see vertical lines of different colors when a dithered area is displayed. Whether it is the limited colors used or the large size and sharpness of the output, dithering (on the CarteBlanche) doesn't work well. The vertical lines are clearly visible. Check out the color areas on the picture below. Please note that some browsers make the picture worse than it really is, making some vertical lines darker than they should be. The actual output from the Carte Blanche has every other dithered line of identical brightness as it should be. The best viewing of the picture below is at the picture's full size. Also note that my Finder desktop has a gray background, not the normal periwinkle blue one.

The SHR 320 mode not implemented yet, so when 320 mode is enabled my code just continues to output 640. Ugly...

No fill mode.

Still you do get a usable desktop and I was just trying to prove to myself that SHR would work.

Finder desktop

Note the lack of side borders, poor dithering and un-colorful apple in menu bar.

Click here to see screen shots with a IIGS to SCART cable for comparison.

One more thing to note about the SHR code, it is slot dependent. The code for SHR relies on the M2B0 signal. This signal is found only on pin 35 of slot #3 on a ROM 01 Apple IIgs and slots # 1 to 6 on a ROM 03. I'm not sure if it is available on a ROM 00. Slot # 7 has a different signal on pin 35. This leads to a problem if you have a ROM 01 and want both the VGA video and the Carte Blanche functions that require the slot memory since the 80 column firmware uses that slot. As I see it you have three choices if you have a ROM 01:

   1. Put the Carte Blanche card in Slot #3, remove the IDE jumper and leave the slot set to the default "Built-in Text Display".
       Of course you will then only have a VGA card.
   2. Solder wires connecting pin 35 on slot # 3 to an un-used slot (not slot # 7). I soldered wires to slots# 1, 2, 4, 5 & 6.
   3. Get a ROM 03 IIgs. ☺

Known Bugs:

Some garbage appears on the "Welcome to the IIgs" screen.

Returning to ProDOS 80 column text mode results in 40 column text (as if slot 3 ROM disabled).

The inverse line cursor used to select disk images in the JAT menu moves two lines at a time in the up direction. This does not happen in an Apple //e.

There is some minor "artifacts" in the mixed mode text area.

Double-hires graphics (DHR) does not work. The DHR can be "turned on" but the display is wrong. Switching to the CDA menu from DHR (or double-lores) displays an incorrectly formatted 80 column screen when 40 column is selected as default in the control panel.

If no legal disk image (.nib) is selected in the JAT menu the Finder hangs when trying to read the Carte Blanche slot.

The mousetext is the "running man" style. It shouldn't be on an Apple IIgs.

In some video modes there is some "snow-like" effects. This bug was introduced by me while fixing several other bugs. For now this bug is preferable to the other bugs. ☺

Next some information about a different approach to solving the video problems above.

Carte Blanche

Notes and Ramblings (IIgs)

Part 2

The problems I've had getting a stable video output for both the Apple IIGS specific modes and older Apple II and //e modes seem to be caused by the Carte Blanche video buffer RAM being unable to keep up with both the writing data from the Apple slot bus and the reading needed for the VGA output. More likely it's my inability to write efficient code to handle it. At any rate after trying for some time to get it to work I decided to try a different approach to buffering the video data. In this new approach I decided to use the BRAM in the FPGA chip to do some of the buffering. Up till now all of the buffering was done in the SRAM included on the Carte Blanche card. This is a reasonable way to do it since we have 256KBytes of SRAM and less than 28KBytes of BRAM. But the BRAM is theoretically much faster. The reason I have been reluctant to use the BRAM is that it's already being used. Pretty much all of it. The character ROM uses up about 2KBytes and the Z80 and disk code uses up the rest. My interest has been mainly in the video so the rest had to go.

I stripped out all the Z80 and related modules, the DMA, SPI and Disk modules, etc. from the project. Only the main module (cb1.v), the write_clk module and the video module (with its sub modules) were left. Only the character ROM data was now using BRAM and that was untouchable. The main module had to be stripped of all the code relating to the modules removed but the others remained pretty much the same. I also had to rewrite the code to switch between SRAM and BRAM.

Since the main problem I've had (dash-like flickers which I called snow previously) was most objectionable on the text screens I decided to buffer all the text data (both pages and both banks) on the BRAM. The result was completely stable flicker free text. This was even true on the worst cases such as Merlin 16+ (which runs under GS/OS and presumably uses the text tools). Since the low resolution graphics mode is the same (as far as memory location) as text it too was stable. SHR never had the problem so that left high resolution (HGR) and double high resolution (DHR) modes and they still had the flickers.

There simply isn't enough BRAM left to buffer all the remaining data so I settled on buffering all HGR data (both pages) and the main RAM portion of the DHR since they use the same memory locations. This meant that the DHR which switches back and forth between the main RAM and Auxiliary RAM on the Apple now also had to switch between SRAM and BRAM with each byte written and read. However, this doesn't seem to be a problem and it eliminated the flickers from both HGR and DHR.

Of course with this code the Carte Blanche becomes just a VGA video card. Once this bitstream is written to the flash memory from an SD card the Carte Blanche no longer has the ability to write a new bitstream to the flash memory. So DO NOT use this bitstream if you don't have another way to write to the Carte Blanche card such as a JTAG cable.

Some other changes:

1. Fixed a bug that caused the text, background and border colors to interfere with each other (on some monitors) so that wrong colors were displayed. Thanks to Bill Garber for pointing this one out. The monitors I was using at the time didn't have that problem.

2. Fixed a bug in my HGR code (when used in an 80 column program) that displayed graphics that were slightly different than the original (40 column) ones.

3. DHR now works (sort of). The colors are not always right. I haven't figured out an algorithm for doing it right.

4. Added monochrome support for DHR. Again it's not exactly right but it works well in some programs such as TimeOut Paint an Appleworks add-on.

5. Fixed a bug that caused the CDA display (when accessed from DHR) to be incorrectly formatted as an 80 column screen when 40 column is selected as default in the control panel.

6. Mouse-text now uses the correct Apple IIgs characters. Thanks to Marc S. Ressl for pointing me to the character ROM file.

7. Fixed a bug that put spurious dots and junk on the Welcome to the IIGS startup screen.

8. Fixed a bug that occasionally put a random dot on the Finder desktop.

Bugs:

As mentioned above, the DHR graphics mode needs work.

Still some minor "artifacts" in the mixed mode text area.

An extra vertical line is sometimes present at the right-most position of the HGR (80 column) display.

Double low-res doesn't work at all.

Strange mouse cursor display and action in MouseDesk program after returning from CDA menu. MouseDesk is a DHR graphics program. This problem does not appear in TimeOut Paint.

If SHR mode is turned on (without loading any new SHR data) after a DHR image has been loaded, the screen does not match what is seen with the Apple IIgs RGB output. Only the top half of the screen contains the DHR data. Should be the whole screen.

To do:

The bugs are a priority.

Non-fixed palettes in SHR. There is enough BRAM left free that I could put the palettes and scan line control data there. Then it might be possible to access that data without interfering with the video data accessed from SRAM. Since the Carte Blanche has only 6 bits of RGB output there would be very little gain from this (well the Apple in the menu bar would be correctly colored) but if I or someone comes up with a 12 bit add on to the Carte Blanche then the code would be there. To see what I came up with, select //e & IIgs 12 bit mod in the Carte Blanche menu.

Improved HGR. At the present the HGR code draws filled objects as a series of vertical lines with every other line as black. Only white is drawn as a solid.

Support double low resolution graphics mode.

Carte Blanche

12 bit color output - a simple modification

The Carte Blanche card outputs VGA which is only 6 bits wide. Good for 64 colors. That's plenty for the Apple //e which uses at most 16 colors. Same for any other version of the Apple II except the Apple IIgs which has a Super Hires Graphics mode that supports up to 4096 colors (12 bit output). To get 4096 colors you would need a hardware change on the Carte Blanche. In one of my earlier ramblings I said that I didn't think it would be too hard to do this by using the peripheral board pins or even the IDE connector pins and a few resistors.

Recently (December, 2011) I decided to give it a try by repurposing the IDE connector. Since I was using the Carte Blanche for just a VGA video card the IDE connector wasn't being used. It turns out to be an easy and inexpensive modification. I just took an old IDE hard drive ribbon cable, cut off the one end, spliced a dozen resistors in groups of four with the output ends of each group tied together and fed them (along with wires for H-sync, V-sync and Ground) into an old PC serial port ribbon cable connector which is the same as the Carte Blanche supplied connector. I plugged that into the supplied VGA connector. Basically that's all you need to do hardware-wise for 12 bit color VGA output. I have to admit that the cable is ugly and takes up a lot of room in the IIgs case. If you decide to make the cable please test each wire with an Ohm meter to make sure they are wired correctly. Test between each wire for shorts and test each resistor for proper resistance.

Disclaimer: The cable I've described works well for me but I don't guarantee yours will work for you. Wiring it incorrectly could damage your Carte Blanche card, your Apple IIgs or your monitor.


Cable parts	Re-purposed IDE connector on Carte Blanche card	Resistor Diagram & 10 pin socket	Finished Cable - Ugly but works well

Of course nothing comes out the connector until you write FPGA code for it. That was pretty easy as well.

The original JAT code doesn't define some of the IDE pin to FPGA connections because it doesn't use them so I added the following to the cb.ucf file. D[8] to D[11] are used for 4 bits (RED) of the 12. D[0] to D[3] (BLUE) and D[4] to D[7] (GREEN) are already defined in the cb.ucf file. D[12] is used for HSYNC and D[13] for VSYNC.

NET "IDE_D[8]" IOSTANDARD = LVCMOS33;
NET "IDE_D[8]" LOC = P151;
NET "IDE_D[9]" IOSTANDARD = LVCMOS33;
NET "IDE_D[9]" LOC = P115;
NET "IDE_D[10]" IOSTANDARD = LVCMOS33;
NET "IDE_D[10]" LOC = P152;
NET "IDE_D[11]" IOSTANDARD = LVCMOS33;
NET "IDE_D[11]" LOC = P160;
NET "IDE_D[12]" IOSTANDARD = LVCMOS33;
NET "IDE_D[12]" LOC = P162;
NET "IDE_D[13]" IOSTANDARD = LVCMOS33;
NET "IDE_D[13]" LOC = P96;

The rest of the code is similar to the 6 bit code. At least for the non-SHR graphics modes and text. But those non-SHR modes don't need 12 bit color or look any different with it. SHR was more of a challenge. On previous bitstream versions I just used a fixed 16 color palette (the one used for low res graphics). This looked pretty good with the desktop but one of the things you would notice right away was the striped color Apple icon in the upper left corner was solid dark red. That was because the Finder uses several different palettes to get all the Apple icon colors. For the Carte Blanche to do the palettes properly takes four reads to memory to draw a pixel. One read is for the scan line control data which among other things contains the number of the palette to use, two reads for the actual color data in the palette and one more for the pixel data that contains the color number in the palette. The older non-SHR modes take only one read. I don't believe the on-board SRAM is fast enough to do four reads and keep up with the VGA output, so I tried two approaches. The palettes were buffered in the FPGA BRAM which is fast and can run simultaneously with the SRAM containing the pixel data. Another advantage of using the BRAM was that I could set it up to read 12 bits at a time so that only one read was needed for the color data per pixel instead of two. That left only the scan line control bytes and I was running out of BRAM. To solve this problem I created an array of 8 bit registers. Two hundred of them. Ugh!

Bottom line; after some playing around with the timing I had a usable desktop, much like I had with the fixed palette but now I was using all the palettes correctly and the Apple had it's colored stripes back.

Next I added some code to support the SHR 320 mode, something the fixed palette code couldn't do. Many if not most Apple IIgs programs use the 320 mode so this modification significantly increases the number of graphics based programs that can be used. I also added code to handle the SHR Fill mode.

So far most programs look good on my Samsung 940MW LCD monitor and also my HP CRT monitor.


Finder on LCD monitor	Zany Golf on LCD monitor	Zany Golf on CRT monitor

Grayscale picture on CRT monitor	320 mode picture on CRT monitor	Warlock on CRT monitor

There are several programs though that don't do well.

1. Programs that display "3200 color" pictures. These are really messed up with rolling garbage on the screen.

2. Programs that use Fill mode for fast motion. While Fill mode works, when animated there is a rolling band through the filled part of the screen.

3. Programs that do tricks like over scanning into the borders.

And speaking of borders there are still no side borders. This isn't really a bug since the code isn't even trying to do them. I haven't gotten around to attempting this yet.

With the first version of the 12-bit color bitstream (9.0) I advised that you not use it if you didn't have a setup to JTAG a bitstream into the FPGA. Without the JTAG interface, flashing the bitstream was irreversible. This is still the recommended way to do things but now with version 9.20 I've added an interface so that flashing can be done from the Apple II. An Applesoft BASIC program is included with the bitstream for flashing. This method has worked for me and one other tester but it is very slow.
There are also a couple of minor bug fixes in version 9.20.

Two newer versions are available. A 12-bit VGA version (9.31) and a HDMI version (9.31hdmi). For more information click here.

I did all the testing on an Apple IIgs ROM 01 with 4 MB of RAM, an 8 MHz ZipGS, a 3.5" floppy drive in the smartport and an Apple High Speed SCSI card in slot #7 with a 100 MB SCSI hard drive. The Carte Blanche card was in slot #1 (the mother board was modified by soldering a wire connecting pin #35 of slot #3 to pin #35 of slot #1). If you don't want to make this modification you must have the Carte Blanche card in slot #3. On a ROM 03 you can use any slot except slot #7.

Carte Blanche

HDMI

The Carte Blanche has a connector for peripheral boards. In 2012 Steven Howell designed and produced a board for the Carte Blanche that allows HDMI - DVI - Audio output. Steve also wrote bitstreams for the board. For more information click here.

I decided to write my own Apple IIgs bitstream for the HDMI board based on my 12-bit code for the Apple IIgs (version 9.20) with some improvements from my latest //e code (version 3.02). My bitstream is for the 250 version of the Carte Blanche. The video code for HDMI / DVI is very similar to my 12-bit code. One difference is that the HDMI board can output either 12 or 24 bit color. The Super Hires Graphics modes use 12 bit color but I decided to use the 24 bit color mode. To do that I set the lower 4 bits of each 8 bit color (Red, Green & Blue) to the corresponding 4 bits produced by the 12 bit code. The higher 4 bits are a duplicate of the lower bits.

assign RED = {hdmi2[11],hdmi2[10],hdmi2[9],hdmi2[8],hdmi2[11],hdmi2[10],hdmi2[9],hdmi2[8]};
assign GREEN = {hdmi2[7],hdmi2[6],hdmi2[5],hdmi2[4],hdmi2[7],hdmi2[6],hdmi2[5],hdmi2[4]};
assign BLUE = {hdmi2[3],hdmi2[2],hdmi2[1],hdmi2[0],hdmi2[3],hdmi2[2],hdmi2[1],hdmi2[0]};

This seems to produce the correct colors.

Another difference is the HDMI board needs a frame enable signal so that it can create its own horizontal and vertical blanking. In the old code the horizontal and vertical blanking are created in the FPGA code. The HDMI frame enable signal is high when the color data is being sent to the HDMI board and low when it isn't. To get a stable output I had to register the frame enable signal.

reg frame_enable_reg = 0;

always @(posedge clk50)
    begin
    if (clk1)    // 25MHz clock (pixel clock)
        begin
        frame_enable_reg <= ~((h_count > 639) | (v_count > 479));
        end
    end

wire h_blank = (h_count > 639); // horz blanking
wire v_blank = (v_count > 479); // vertical blanking

The pixel clock, horizontal sync and vertical sync, which are also needed for the HDMI board, are the same for both 6-bit VGA and the 24-bit HDMI.

The picture quality for the HDMI is similar to the previous released //e version (c302) and slightly better than the IIgs version (c920) so it has the same limitations and most of the same bugs. The 6-bit VGA output is more like that in the //e version c302 which supported SHR, so it has a better looking SHR 640 mode. The faster flashing available on //e version c302 is now available on this Apple IIgs version (c931hdmi). You should not use the cbconfig program that came with the //e version. It would cause a bus conflict and anyway it is not needed with the Apple IIgs since the settings are kept in the battery RAM.

If you are lucky enough to own one of the HDMI boards for your Carte Blanche card you now have another option for your Apple IIgs video.

Note: The HDMI version should not be used with the 12-bit VGA connector in place. The peripheral board connector and the IDE connector used by the 12-bit mod share several pins. I have created a separate version for the VGA 12-bit mod. In either case you still have the original 6-bit VGA output.

The HDMI output was sent to my Samsung SyncMaster 940MW via an HDMI cable and an HDMI to DVI adapter.

I did all the testing on an Apple IIgs ROM 01 with 4 MB of RAM, an 8 MHz ZipGS, a 3.5" floppy drive in the smartport and a CFFA3000 card. The Carte Blanche card was in slot #1 (the mother board was modified by soldering a wire connecting pin #35 of slot #3 to pin #35 of slot #1). If you don't want to make this modification you must have the Carte Blanche card in slot #3. On a ROM 03 you can use any slot except slot #7.

A newer HDMI version (c933hdmi) is available with higher resolution and SHR 640 with solid colors. For more information see below:

Side Borders

One of the things that has bothered me about the Super High Resolution (SHR) output on the Carte Blanche is the lack of side borders. All the previous Carte Blanche video has been using 640 x 480 resolution and of course the SHR 640 mode takes up the entire screen width. Even the 320 mode takes up 640 since I double each pixel. Hence no room for side borders.

Recently Bill Garber pointed out to me that there is a 720 x 480 "standard" VGA and he wondered if we could get it to work with the Carte Blanche. The pixel clock frequency would have to be increased from 25.175 MHz to 28.3 MHz but that was well inside the capability of the SRAM where the video data is buffered. To get 720 pixels per line the horizontal counter would have to be increased. With 640 the horizontal counter counts 800 increments for each line. About 900 counts per line was used for the 720 width. Bill and I experimented to find good horizontal sync points and I later increased the horizontal counter to 910 to account for a slightly higher frequency than the specifications called for.

The outcome was that both the VGA and HDMI showed borders in SHR graphics mode on two of my LCD monitors; a Samsung Syncmaster 940MW 19" widescreen and a lenovo ThinkVision 19" wide screen. However the VGA and HDMI outputs were different. The VGA produced an image that was still 640 wide according to the monitors screen information on both monitors. The active part of the screen between the side borders was "squeezed" into a smaller width producing objectionable vertical banding. The HDMI actually produced the correct 720 width and the active part of the screen was correctly displayed.

Finder Desktop showing side borders with 720 x 480 resolution

Finder Desktop with borders.

HDMI Screen Resolution is 720 x 480 pixels.

Click picture to enlarge.

Finder Desktop with side borders 640 x 480 resolution and 6bit color

Finder Desktop with borders.

VGA (6 bit) Screen Resolution is 640 x 480 pixels.

Click picture to enlarge.

Unfortunately, the 720 x 480 resolution seems to be a little unstable. When I move a window around with the mouse it sometimes causes the image to shake and occasionally the screen even goes black for a second. This also can happen when holding the mouse button down in the scroll bar to make it scroll fast.

Solid Colors

Another bothersome thing about my SHR 640 output is the alternating vertical lines for the background on programs like the Finder. On the IIgs RGB output the finder has a solid background that Apple calls periwinkle blue. That's how it should look, but on the Carte Blanche output each pixel is clearly seen resulting in the offending vertical lines. In the case of the Finder background the lines are white and blue. When blue and white are side by side on an RGB output the colors are "blurred" together and look like one color, periwinkle blue. In fact with the six colors (red, green, blue, yellow, black and white) that are used as the standard colors for 640 mode you can create 16 colors by a technique that the IIgs documentation calls dithering.
This is not the dithering where the eye blends two colors together but refers to the blurring of two colors.
So how to do that with a VGA/HDMI output?
We can't blur two colors together but Apple IIgs technote # 63 gave me an idea how we could simulate the dithering. Table 2 in the technote shows that the standard RGB colors are either full on or off.

                   Color Table    Color       Master Color
	             Offset       Name           Value 
		  ---------------------------------------
		       $0         Black          $0000
                       $1         Red            $0F00
                       $2         Green          $00F0
                       $3         White          $0FFF
                       $4         Black          $0000
                       $5         Blue           $000F
                       $6         Yellow-green   $0FF0
                       $7         White          $0FFF
                       $8         Black          $0000
                       $9         Red            $0F00
                       $A         Green          $00F0
                       $B         White          $0FFF
                       $C         Black          $0000
                       $D         Blue           $000F
                       $E         Yellow-green   $0FF0
                       $F         White          $0FFF
		  ---------------------------------------

		   Table 2-Standard 640-mode Color Table

The colors are 12 bits so the high 4 bits are always zero.

Table 3 shows close approximations of the dithered color values.

                   Color Table    Color       Master Color
	             Offset       Name            Value 
		  ----------------------------------------
		       $0         Black           $0000
                       $1         Deep Blue       $0008
                       $2         Yellow-brown    $0880
                       $3         Gray            $0888
                       $4         Red             $0800
                       $5         Purple          $0808
                       $6         Orange          $0F80
                       $7         Pink            $0F88
                       $8         Dark Green      $0080
                       $9         Aqua            $0088
                       $A         Bright Green    $08F0
                       $B         Pale Green      $08F8
                       $C         Gray            $0888
                       $D         Periwinkle Blue $088F
                       $E         Yellow          $0FF8
                       $F         White           $0FFF
		  ----------------------------------------

		   Table 3-Standard 640-mode Color Table

I noticed that the numbers in table 3 were created by averaging the red, green and blue values separately. For instance when white ($0FFF) and blue ($000F) pixels alternate the red values are $F and $0. Averaging the two numbers (and rounding up since these values are integers) we get $8. We get $8 for green as well and blues is $F in both colors so the average is $F. The result is $088F which is the value for Periwinkle Blue.

The pictures shown below used a simple algorithm that just compared each pixel pair's individual color values (red, blue & green) and if the values were not equal it gave both pixels the value $8 for that color. This has the advantage of being easy, but it only works for the standard 640 mode colors.

Well as the title says this is a work in progress so after I took these pictures I decided to change the algorithm so that it would work on all colors instead of just the standard ones. This new method did an actual averaging of each pixel's colors and that resulted in the standard colors having $7 instead of $8. This looks pretty much the same to my eye.

This version (c933hdmi) defaults to non-dithered 640 SHR. Pressing the control and ] keys together toggles between dithered and non-dithered mode.

While we're talking about colors. The pictures displayed here are not quite the same as what you really see on the monitor due to my camera. Specifically, the white looks "off-white" in the pictures but is a much more pure white on the monitor. Some other colors look a little different but much less so than the white.

Finder Desktop with borders and dithered colors.

Close-up of dithering.

Close-up without dithering.

There is a bug in the dithered mode. It's hard to see in the full desktop picture above but the entire desktop is shifted right by one pixel.

Another problem with the dithered mode is the screen is blurry on a ROM 3 IIgs. There is a slight fuzziness on my ROM 01 as can be seen in the dithered close up above, but it is barely noticeable.

Carte Blanche II

Old to New

On June 8, 2015 I received my new Carte Blanche II card. This card has many more resources than the old Carte Blanche card. Please visit Steve Howell's page, http://www.applelogic.org/CarteBlancheII.html if you haven't already, to read about it.

Most of what I've written about the Carte Blanche I card applies to the Carte Blanche II as well, but there are some programming differences.

Here are a few things I've learned about Carte Blanche II programming:

The CBII has a pin that is used to enable/disable the Apple II slot bus to the CBII. You must set that pin to zero if you want to use the Apple II slot bus.

Assuming that pin is labeled ABUS_EN then:

assign ABUS_EN = 1'b0; // enables Apple II slot bus

The COLOR_LEVEL used to switch between 24 and 12 bit mode for HDMI is no longer needed. On the CBII the 24 bit mode is fixed.

VGA output must be enabled by:

assign DAC_EN = FRAME_ENABLE; // enables VGA (digital to analog)

Where FRAME_ENABLE is when the screen is actively drawing pixels.

and the sync on green pin should be grounded:

assign DAC_SONG = 1'b0; // grounds sync on green

The CBII has a user LED which is handy for testing a signal especially when there is no video output. The user LED is on when low.

assign USER_LED = 1'b0; // turns blue LED on

The Carte Blanche II has more SRAM than the original Carte Blanche.

assign SRAM_NCS = 1'b0; // selects SRAM chip

There is no second SRAM chip so no need for SRAM_NCS1 found on the original CB.
SRAM on the CBII supports 16 bit read/write. For 8 bit:

assign SRAM_NBE0 = 1'b0; // enable low byte
assign SRAM_NBE1 = 1'b1; // disable high byte

SRAM write enable & output enable are the same as the CB1, both are active low:

assign SRAM_NOE = 1'b0; // output enabled
assign SRAM_NWE = 1'b0; // write enabled

The Spartan 3AN 400's DCMs (digital clock managers) do not seem to work well with low output frequencies. I ended up doubling the output frequency from the DCM and then dividing it in half in the FPGA code.

Projects

Two of the things I'm most interested in are the onboard 24bit HDMI and 24bit VGA. Steve has written a CB II port of my Carte Blanche I c933hdmi code (which is based on Alex Freed's video code in JAT). This code works well giving 720x480 resolution on an HDMI monitor. The VGA output on the old Carte Blanche had two problems. One, it was only 6 bit color, which was good for all the non-IIgs modes but not good for the Super HiRes Modes. The second problem was that some monitors don't support 720x480 resolution in VGA. Mine don't. The VGA picture is awful.

640x480 Video Card Project (IIgs)

Version c2000

So I decided to write a 640x480 port for those who don't have an HDMI / DVI monitor. This was a good excuse for me to learn some of the new features of the Carte Blanche II as well. My CB II version is c2000 and it has a few changes:

The SHR 640 dither mode is now the default mode, but you can still toggle it on/off with the control - ] keys.

The pixel offset bug in the c933hdmi code is fixed.

Both the VGA and HDMI work well but Steve's port is better for the HDMI for two reasons it is 720 wide giving you the side borders in SHR and my version has a second of black screen when switching to or from SHR.

800x600 Video Card Project (IIgs)

Version c2001

I wasn't really satisfied with the 640x480 project. I really like the side borders in SHR. So I made another version, c2001 that has a screen resolution of 800 x 600 including the borders. The good thing about this version, it has borders on the sides in SHR, but the borders are large and therefore the actual display area is smaller than the 640x480. Still I like it better, especially when I set my widescreen monitor to display in normal, not wide, mode.

VGA and HDMI look nearly identical. There is no more 'second of black screen' when switching to or from SHR.

720x480 Video Card Project (IIgs)

Version b2000

Bill Garber has written a modified version of the c2000 for the Carte Blanche II. It uses the 720x480 resolution. His version is b2000.

Download it directly from my Downloads page.

640x480 Video Card Project (//e)

Version c3000

The Carte Blanche II card uses a different external flash memory than the Carte Blanche I so I wrote a port, c3000, of the old c302 video card code that supports flashing the Carte Blanche II external memory from the Apple //e. Included are Applesoft BASIC utilities to do the flash as well as configure the video (cbconfig). There is also a manual.