Copyright (C) 2004, 2005, 2006, 2007 AJA Video Systems, Inc.  Proprietary and
Confidential information.

AJA OEM (including KSD, KHD and XENA2) LINUX KERNEL 2.6 DEVICE DRIVER 
and SDK Version 4.1.0

Authors: Bill Bowen, Shaun Case and Jeff Coffin


. Support

For support please contact:
Jeff Coffin, Shaun Case or Bill Bowen
AJA Video Inc.
530.274.2048
sdksupport@aja.com

. Licence and Legal Stuff 

Currently this software is only available to people who have signed
AJA Video Systems' SDK NDA.


. Introduction

This software package is a Linux device driver and SDK software to
allow control of the AJA PCI, PCI-X and PCI Express SDI video IO
cards.  The current OEM series of boards are the OEM LS, LSe, LH, LHe,
2K and 2Ke.  The OEM-LS and OEM-LSe use the "KSD" driver and build.
The OEM-HS, OEM-HS2, OEM-LH and the OEM-LHe use the "KHD" driver and
build.  The OEM2K uses the "XENA2" driver and build.

"KSD", "KHD" and "XENA2" are historical names.  The OEM cards are now
unbranded, sold as OEM cards (OEM-2K, OEM-SD22, etc.).  However, the
KSD, KHD and XENA2/XENA2K names are scattered throughout the
documentation, code and scripts.  You can read "KSD" as meaning
"standard definition cards" and "KHD" as meaning "High definition
cards".  "XENA2/XENA2K" is the OEM version of retail-branded Kona2 and
Kona3 (aka Xena2K) and will eventually be called OEM2K throughout the
code and documentation.  Collectively the cards and software
technology are referred to as NTV2, another historical name.


. Installation Overview

Installing consists of compiling the device driver kernel module,
inserting it into your kernel, then compiling the SDK code, tools and
test apps.  Once things are compiled you can test out the device with
some of the test apps.  If you are not familiar with compiling
software and linux kernels or make, gcc and modprobe do not mean
anything to you, consider finding somene who is more comfortable with
Linux before you try and build the driver and apps.

In general, the closer your kernel is to either RHEL4, Fedora Core 5
or 6 or a vanilla kernel.org kernel, the less tweaking you may need to
do and the better chance of success you will have.  If you use other
distributions, we will try to help - and it may just work - but know
that our support resources are limited and we are not able to fully
test and support every combination of kernel, distribution and
hardware.


. SDK Distribution Overview

This version of the SDK consists of the device driver and a set of
portable C++ classes providing programatic access to NTV2 drivers in a
consistent fashion on Linux, Windows, and Macintosh platforms.  This
distribution includes the source code to the driver, Linux sppecific C
code, the cross platform C++ code, documentation and sample
applications.

The contents of this distribution and subject to change without
notice.  Feedback and bug reports are welcome.  Please send them to
sdksupport@aja.com.

The current SDK distribution contains the following:

changes-linux.txt-> Changelog for each version of the SDK
bin/			 -> Driver, scripts, test & demo apps.  See bin/readme.txt
classes/		 -> Portable C++ classes that provide access to Xena(TM) drivers
commonapps/      -> Test applications that compile on Linux and Windows.
docs/			 -> Register descriptions, bigphysarea howto, autocirculate, etc.
fltk/            -> Fast Light Tool Kit required for XenaCables program (OEM2K),
		 	        procamp and the new FLTK based watcher
includes/		 -> Header files for C++ classes above
linuxapps/		 -> Test and demo applications that get built to bin/ above
linuxbigphystest/-> Sample module to test kernel with bigphysarea patch 
linuxclasses/	 -> Linux-specific classes; combined with classes, comprise SDK
linuxdriver/	 -> Linux device driver src, in C for AJA OEM cards
Makefile		 -> Top level makefile.  To make everything, just type "make"
testpics/		 -> A small number of images that the qtcontrolpanel can load
xilinx/			 -> Firmware for OEM boards, used by the bin/program* apps



. Kernel Version Support

We develop for and support the 2.6 kernel series, primarily 2.6.9 and
later.  We no longer activly support the 2.4 kernel series.  The last
SDK to support 2.4.x kernels was 2.2 which is available on the
website.  Should you need 2.4 support (and are buying a lot of cards
:-) contact sdksupport@aja.com and we may be able to work something
out.

With the advent of 64 bit PC hardware, PCI, PCI-X and PCIe interfaces,
the task of supporting and testing the myriad kernel versions and
distributions is even more difficult.  We try to keep up with new
kernel releases as best we can and when practical use less patched
kernels.  At the moment, our primary development platforms are RedHat
Enterprise Linux 4, Update 3 and Update 4, SuSE 9.3, 10 and 10.1,
Fedora Core 5 and 6 and Mandrake 10.1.  We have OEMs who have
successfully used Ubuntu and Linux From Scratch as well.

Kernel.org versions 2.6.11 through 2.6.19 should work.  Versions
2.6.19 and later require 2 small patches against the 4.1.0 AJA release
to work.


. Lots of RAM and 32 / 64 bit System Issues

Now that 64 bit PC systems and platforms are common, our support
challenges are more complex.  The good news is that with a current 64
bit system install and kernel (RHEL 2.6.9 or 2.6.16 and later) the
card and SDK work well without much - if any - special kernel options
or re-compiles.  Furthermore, as of 2.6.15, 32 bit systems can take
advantage of the new VMSPLIT kernel config options and use
scatter/gather DMA where once they needed the bigphysarea patch to be
able to do DMA at all.  64 bit systems generally do not need either
the bigphysarea patch or the other tinkering discussed below.

On 32 bit systems with 1 GB or more of RAM, the size of the in-kernel
data structures needed to map virtual pages to physical memory grows
to the point where the kerenel can run out of allocatable memory to
create the maps needed for the driver and APIs to work.  The first
symptom occurs when you try and load the kernel module and get a
message in the kernel logs (/var/log/messages) about the driver being
unable to ioremap BAR1Address.  This means your system has
insufficient vmalloc pool resources, which is a Linux kernel
limitation.

As of 2.6.15, there is a new virtual memory option available, the
2G/2G split which enables 32 bit kernels to fully use 2 Gigs of RAM
without the bigphyarea patch and successfully do scatter/gather DMA.
Under "General setup" check "Configure standard kernel features (for
small systems" (CONFIG_EMBEDDED) and then in the "Processor type and
features" -> "Memory split" enable 2G/2G user/kernel split
(CONFIG_VMSPLIT_2G).

Since this is a relatively new option, we are looking for users'
experiences with is.  It seems to work well here (2.6.17, FC5 with 2G
RAM), and for others, however YMMV (Your Mileage May Vary).

You can also try the Bigphysarea patch, the detail of which are here:
docs/ bigphysareapatch-howto.txt.  If you have a kernel with the
bigphysarea patch applied, you can use the vmalloc=<size> boot
parameter.  The default is 128M.  For 1KSD card you should use at
least vmalloc=256M.  For one KHD card, you should use at least
vmalloc=384M.  If you are using multiple cards in the same system you
will have to experiment to determine the the required vmalloc pool
size for your configuration.  It will vary with the other cards and
program requirements of your application.  NOTE: Using mem= in
conjunction with bigphysarea= is known to cause issues.  Fortunately
when using bigphysarea= there is little reason to use mem=.

If you have a stock kernel (no bigphysarea patch), you can increase it
by freeing up some physical address space by reducing the amount of
RAM in your system, either by changing the amount of physical memory
in the computer, or by specifying the mem=xxxM boot option (where xxx
is the number of megabytes of RAM for the kernel to use) in your boot
loader configuration.  Having 1 GB of RAM or more in your machine will
typically cause this problem.  The exact maximum amount of RAM that
can be used in conjunction with various Xena board configurations
varies with how many Xena cards and what other devices are installed
in the PC; here is a rough guide:

512MB or less: 1 KSD AND (1 KHD or 1 OEM2K) can be remapped simultaneously
640MB or less: 1 KSD OR (1 KHD or 1 OEM2K) can be remapped
768MB or less: 1 KSD can be remapped. 0 KHDs/0 OEM2Ks can be remapped 
1 GB or more: No OEM cards be remapped. 

RAM requirements for other multi-NTV2 card configurations may be
forthcoming.  Send feedback what works for you (or doesn't) to
sdksupport@aja.com

Alternately, if you don't need the framebuffers memory mapped into
user space (for PIO access) and will do only driverbuffer DMA, you can
instruct the driver to skip the memory mapping phase of its
initialization by giving the correct argument to the driver when it is
loaded.  Examples:

/sbin/insmod KHD.ko KHD_MapFrameBuffers=0
/sbin/insmod KSD.ko KSD_MapFrameBuffers=0
/sbin/insmod XENA2.ko XENA2_MapFrameBuffers=0

All of the above are in the driver loading scripts in the bin
directory, commented out.

This will allow your system to take advantage of large amounts of RAM
if they are installed.

Note that some of the test applications, such as draw, and autocirc,
which use PIO to write directly to the frame buffers, will not work if
the buffers are not mapped.  The OEM2K does not support PIO and thus
the draw app will not run on it in either case.


. GRUB Versus vmalloc=

If you use grub and a vmalloc= argument you may find that you system
will no longer boot.  A large vmalloc pool can make then initrd
inaccessible and the kernel is not able to mount that initial
filesystem.  The fix for this is to add the following incantation to
the GRUB /boot/grub/menu.lst stanza for that kernel:

uppermem 524288

This tells grub to load the initrd into a memory region where the
kernel can find it despite the increased memory pressure caused by the
large vmalloc pool.

