ConvertBot: Low level drivers for ICE-DSP cards

2020-04-27T18:32:58Z

Low level drivers for ICE-DSP cards

New page

<div style="background-color: #eef9ff; border: 1px solid #999; padding: 10px;">[[ICE_Help|↑ ''Go to the full list of ICE Help pages'']].</div>
<onlyinclude>

'''Summary:''' Low level drivers for ICE-DSP cards


This file covers the general operation and installation of low level drivers
for the supported Operating Systems.

=== GENERAL - Overview of driver functions ===

The following discussions refer to any of the ICE cards on the PCI bus.
The ICE-PIC, ICE-MBT, and ICE-SLimpIC all look the same to the driver.
Note that in this document, only the ICE-PIC is referenced.

This section describes the functions and responsibilities of the ICE-PIC
device driver:

1. Provide a logical handle to each device on the system. This is a device
file in UNIX and a device name in VMS or Windows.

2. Read and Write registers on the PCI interface chip.

3. Lock a user buffer in memory and map its pages to the PCI bus
for PCI bus DMA mastering by the ICE-PIC.

To achieve high sustained DMA rates, the driver does not implement the standard
read and write interfaces. Instead, the driver is responsible for locking a
user buffer in memory and mapping these pages to the PCI bus. The SHARC then
takes control of the PCI-IF chip to arbitrate input/output DMAs between the host
memory and the SHARC's internal memory.

Data is written into (or read from) the ICE-PIC using a circular buffer.
The application polls the ICE-PIC for the current buffer pointer to find out
if new data has been written or read from the host buffer. There are no host
interrupts or other host CPU activity involved with the data transfer. The
SHARC processor handles all of the DMA sequencing, and the PCI-IF handles the
bus arbitration at the hardware level with the PCI bus controller.

In PCI compliant systems, a card is allowed to specify a minimum time that
it will have the bus for a burst transfer, and a maximum time that it can be
denied control of the bus. By tuning these parameters, it is possible to get
extremely high transfer rates with relatively small buffers on the card to
cover the PCI bus sharing latencies. The dual-ported memory in the SHARC chip
supports 100/120Mby DMA to the host, and 100/120Mby to its link ports
simultaneously. The FIFO (circular buffer) size in the SHARC can be adjusted
from 4KBy to 128kBy and is used to absorb hardware level latencies. The SHARC
can run special purpose C or assembly language code to implement other transfer
schemes if necessary.

While the circular DMAs are in progress, the application code can query the
card for the current DMA pointer allowing continuous access to real-time data
with resolution to a 4-byte word. The card can simultaneously process 32 DMA
channels to different host buffers, and possibly for different processes.
Since a process must be able to hold a lock on a card for multiple driver
calls, system level locks are called by the library functions. The DMAs
are not affected by process locks, only actions performed on the host.

The main security function of the driver is to make sure that the SHARC chip
does not perform a DMA to a non-mapped memory address. This is possible if
the application code unmaps the user buffer while a DMA is still in progress
or unmaps the buffer during a crash. The first case is handled by checks in
the run-time libraries. The driver must implement a procedure to check that
all buffers for a process are unmapped cleanly before the process exits. If
this is not the case, the driver assumes a process has crashed and shuts down
the SHARC chip.

The following ioctl() method calls must be implemented by the driver:

IOCTL_READ - read a register on the PCI-IF chip
IOCTL_WRITE - write a register on the PCI-IF chip
IOCTL_ACMD - execute command packet on the SHARC
IOCTL_MAP - map a user buffer into PCI space
IOCTL_UNMAP - unmaps a user buffer from PCI space

The driver must also implement an open(), close(), and cancel() method.

=== VMS - VMS ICE-DSP Driver Installation Notes ===

Load the ICE software tree onto the system. The logical ICEROOT should be
defined pointing to root of this tree.

$assign/trans=conc DKA100:[ICExxx.] ICEROOT

The higher level driver utilities, located in the ICELIB.C file, operate in
the user's context. These functions are shared between VMS, OSF, SUN, Linux,
and WNT. The user will be making all calls to the driver through this
interface.

The driver is located in the [.DRV.VMS] area of the ICE option tree.
It should be left in this area to insure that it is in sync with the higher
level driver routines in the ICELIB.C file. The driver uses IOC$ routines
to access the PCI bus to insure hardware independence and should run on all
DEC AXP platforms.

The command procedures BUILD.COM, CONFIG.COM, and CONNECT.COM are provided
to automate the building and installation of the driver.

To build the driver and utilities, type:

> set default ICEROOT:[drv.vms]
> @build

To see if any cards are recognized on this system (without connecting), you
must enable CMKRNL and PHYS_IO privileges. Then, type:

> @config

To connect all of the recognized devices, you must enable CMKRNL and PHYS_IO
privileges. Then, type:

> @connect

The devices will be installed with the names ICA0, ICB0, ICC0, ...

On clustered systems, it may be desirable to specify unique device names
for each node in the cluster. If you wish to change the sequence of the
device names, specify the list as the first argument to the @connect
procedure. Only the <nowiki>#</nowiki> in IC<nowiki>#</nowiki>0 may be changed.

> @connect "ICF0,ICG0,ICE0"

The devices will be installed with the names ICF0, ICG0, ICE0, ...

To exercise the cards, use the mid-level driver libraries in the LIB area of
this software tree. A small test program in the TEST area may be used to run
a series of tests on the card. To build and run the test routine:

> set default ICEROOT:[TEST]
> @build.vms
> test

An X-Midas macro and primitive are also available to run diagnostic tests on
each card.

X-Midas users should enter this name in the device name slot in the
hardware config table as shown in the examples below:

PIC1==ICEPIC,DEVNO=0,IOM=xxx,
PIC2==ICEPIC,DEVNO=1,IOM=xxx,
PIC3==ICEPIC,DEVNO=2,IOM=xxx,
or
PIC1==ICEPIC,PCI-DEV,ICA0:,,,IOM=xxx,
PIC2==ICEPIC,PCI-DEV,ICB0:,,,IOM=xxx,
PIC3==ICEPIC,PCI-DEV,ICC0:,,,IOM=xxx,

[[ICE_Help_ICELIB#PIC_OPEN|See HELP PIC_OPEN]] for hardware file setup details.

VMS 7.3 ISSUES: TBD

=== OSF - OSF ICE-DSP Driver Installation Notes ===

Load the ICE software tree onto the system. The environment symbol ICEROOT
should be defined pointing to root of this tree.

The driver source files are in the $ICEROOT/drv/osf directory.
To install the driver, follow these steps:

You should be in the $ICEROOT/drv/osf directory to run the config script.

1. To uninstall a previous driver, type:

./icepic remove

This removes the module from the system startup.
Then REBOOT the system. This is very important.

2. To make and install the new driver, type:

./icepic install

The script adds the path to the driver area to the file
/usr/sys/conf/BINARY.list and then throws it up in a vi editor
for you to delete any old icepic entries. There should only
be one line with the word icepic in it.

If successful, the driver is now installed, started and added to
the system startup for autostarting when the system is rebooted.

3. To start the driver without rebooting, type:

./icepic start

The driver is now installed. At boot time, the system will scan the PCI bus
and start the driver for each ICE-PIC card it finds. They will show up in the
/dev filesystem as /dev/ice/pic0[a-z], /dev/ice/pic1[a-z] ...

The multiple minor devices allow the driver to call a very important cleanup
routine when a process exits without cleaning up in a multi-user environment.

To address a device, the pic_open call needs only the major device number.
The pic_open call finds the next available minor device slot and opens the
appropriate /dev/ice/pic<nowiki>#</nowiki>* device. To specify the major device number,
the syntax DEVNO=<nowiki>#</nowiki> is preferred, but for backwards compatibility reasons,
the standard syntax like /dev/icepic<nowiki>#</nowiki> can also be used. In this case, the
major device number is the trailing character. The /dev/icepic<nowiki>#</nowiki> device will
not really exist.

To exercise the cards, use the mid-level driver libraries in the ./lib area of
this software tree. A small test program in the ./test area may be used to run
a series of tests on the card. An X-Midas macro and primitive are also
available to run more diagnostic tests on each card. See test/readme.txt.

X-Midas users should enter this name in the device name slot in the
hardware configuration table as shown in the examples below:

PIC1==ICEPIC,DEVNO=0,IOM=xxx,
PIC2==ICEPIC,DEVNO=1,IOM=xxx,
PIC3==ICEPIC,DEVNO=2,IOM=xxx,
or
PIC1==ICEPIC,PCI-DEV,/dev/icepic0,,,IOM=xxx,
PIC2==ICEPIC,PCI-DEV,/dev/icepic1,,,IOM=xxx,
PIC3==ICEPIC,PCI-DEV,/dev/icepic2,,,IOM=xxx,

[[ICE_Help_ICELIB#PIC_OPEN|See HELP PIC_OPEN]] for hardware file setup details.

=== LNX - Linux ICE-DSP Driver Installation Notes ===

Load the ICE software tree onto the system. The environment symbol ICEROOT
should be defined pointing to root of this tree.

'''NOTE: The environment symbol XMAREA_ICE overrides ICEROOT for X-Midas users.'''
The driver source files are in the $ICEROOT/drv/lnx directory.
To install the driver, follow these steps:

1. Edit the $ICEROOT/drv/lnx/icepic file to set the RAM allocation
parameters as described below. Follow the notes in this file to
set other installation specific flags as well.

ram_alloc = DMA RAM allocator {0=Manual, 1=Kernel<4G, 2=Kernel>4G, 3=Kernel>ram_start, 4=PreKernel}
ram_start = IceDisk RAM Start in Mbytes (-1 or AUTO for top of the OS ram set by mem=xxxM in boot cmdline)
ram_sized = IceDisk RAM in Mbytes (-1 or AUTO for all memory available above mem=xxxM)
ram_sizem = Mappable RAM in Mbytes (at least 24 for PIC self tests)
ram_nodes = Number of NUMA nodes to cover (allocation is duplicated for each node) (ram_alloc must be >0)

RAMdisk memory of ram_sized MBytes starts at ram_start.
RAMdisk memory is followed directly by the Dynamically Mappable memory
of ram_sizem Mbytes. Insure ram_sizem >= 4 to run the system self tests.

These parameters can be over-ridden on the kernel command line as:
ice.ra=X - ram_alloc
ice.rs=X - ram_start
ice.rd=X - ram_sized
ice.rm=X - ram_sizem
ice.rn=X - ram_nodes

For example:
kernel /vmlinuz-2.6.32-358.6.2.el6.x86_64 ro root=LABEL=ICESYS nomodeset ... ice.ra=2 ice.rn=2 ice.rd=8192 ice.rm=1024 ...

See the section below on Special RAM Handling for details.

2. cd to the $ICEROOT/drv/lnx directory and type:

./icepic make

to make the driver and the setram utility.

3. To install the driver, type:

./icepic install

This drops the kernel module start and stop scripts into the
appropriate /etc/rc.d directories for auto initialization and
cleanup with the rest of the system device driver modules.

To load the driver without rebooting the system type:

./icepic start

This script can also be used to stop or restart the driver.

The driver is now installed. At boot time, the system will scan the PCI bus
and start the driver for each ICE-PIC card it finds. They will show up in the
/dev filesystem as /dev/icepic0, /dev/icepic1 ...

To change the RAM allocation without reloading the driver, use the setram
routine in this driver directory.

To exercise the cards, use the mid-level driver libraries in the ./lib area of
this software tree. A small test program in the ./test area may be used to run
a series of tests on the card. An X-Midas macro and primitive are also
available to run more diagnostic tests on each card. See test/readme.txt.

X-Midas users should enter this name in the device name slot in the
hardware configuration table as shown in the examples below:

PIC1==ICEPIC,DEVNO=0,IOM=xxx,
PIC2==ICEPIC,DEVNO=1,IOM=xxx,
PIC3==ICEPIC,DEVNO=2,IOM=xxx,
or
PIC1==ICEPIC,PCI-DEV,/dev/icepic0,,,IOM=xxx,
PIC2==ICEPIC,PCI-DEV,/dev/icepic1,,,IOM=xxx,
PIC3==ICEPIC,PCI-DEV,/dev/icepic2,,,IOM=xxx,

[[ICE_Help_ICELIB#PIC_OPEN|See HELP PIC_OPEN]] for hardware file setup details.

----
'''Sizing the RAM areas
'''
----

Applications typically need a 1 or 2 second buffer for each input/output being used
by each card in the system. Thus, the necessary size for the ICE-PIC DMA memory
is largely application specific. Normally 512M, or 5 seconds at 100Mby/sec, will
suffice.

Midas applications should use the ICE ramdisk so that allocation problems can
be handled at the Midas file system level rather than at the driver level.
This allows fixing allocation problems without disturbing other applications.
Using the MAPPABLE area, to fix an allocation problem, all applications must
be stopped and the driver restarted. The RAMDISK also allows other primitives
like DATALIST and PLOT to look at the RAM buffers while in use.

Non-Midas applications will need to use the MAPPABLE area. If you have a mix of
Midas/NonMidas apps, both can use the MAPPABLE area.

----
'''Special RAM Handling in Linux
'''
----

Since Intel machines cannot map contiguous PCI address space into contiguous
virtual address space, it is necessary to allocate contiguous physically
addressable RAM buffers to support high speed dma and mmap() them to virtual
addresses for user programs to access the data.

In Linux, this can be done by allocating a piece of physical memory for the high
speed DMA by the ICE-PIC. This physical memory can be mapped to a ramdisk for
allocation management and convenient access, or for on-demand mappable memory
from the ICEPIC driver, or both. The ramdisk is not a Linux ramdisk device,
but a Midas specific filesystem.

Beginning in ICE-398, the ICE ram can be dynamically allocated at system boot by
specifying ram_alloc > 0. This uses Kernel Allocated Memory (KAM) that is known to
the system and can be used for direct IO and other advanced DMA handlers. The kernel
will look for the largest continuous block of memory available <= ram_sized+ram_sizem.
The operational framework must use the mappable section of ram_sizem or have a
Midas Ramdisk of ram_sized that is auto-configured from the /proc/driver/icepic text.
This /proc/driver/icepic file shows the start address of the KAM that may be different
each time the system boots. '''Note:''' The KAM allocation is not guaranteed, depending on
other system allocations that may fracture the kernel memory before the ICE driver loads.
However, on most systems with >= 16G of memory, finding <= 2G is a pretty safe request.

If you need to guarantee a large allocation and do not need advanced DMA options,
the contiguous block of memory can be reserved at boot time by specifying the memory
parameters on the kernel command line.

The simplest way to reserve large amounts of contiguous RAM is to confine the
OS to the lower part of memory using the mem=xxM kernel parameter.
This leaves everything above this for the DMA RAM buffers.

If you are using LILO for the boot loader, add the append= line to an entry
in /etc/lilo.conf as shown in the example below:

default=icedisk

image=/boot/vmlinuz-2.0.34-0.6
label=icedisk
root=/dev/hda2
append="mem=32M" <-- this line added
read-only

'''NOTE:''' Don't forget to run lilo after editing lilo.conf !!!!
This can be made the default boot label by adding the default=<label> line.

If you are using GRUB for the boot loader, edit /boot/grub/menu.lst and add
the icedisk title with the mem=xxM addition as shown in the example below:

color white/blue black/light-gray
default 2
gfxmenu (hd0,1)/boot/message
timeout 8

title icedisk
kernel (hd0,1)/boot/vmlinuz root=/dev/hdb2 vga=0x314 ... showopts mem=32M
initrd (hd0,1)/boot/initrd

This can be made the default boot label by changing the default=N line, where
N is the zero-based title number.

In the above cases, if the system has 128Mby of memory, 32Mby will be used by
the operating system, and the rest (96Mby starting at 32M) will be reserved
for the ICE driver.

If you have memory above 4G in your system and a 5+ series card, it is best to use
the space above 4G. Most systems with 8G of memory will leave a hole between 3G
and 4G for devices. The physical memory will be split from 0G-3G and 4G-9G.
For instance, to use the last 2G for the ice card,

append="mem=7186M" <-- this line added

If you are using a 64 bit kernel and PIC5 or newer cards, the mapmem=addr$size is
the prefered approach to statically reserving a block of memory for the ICE driver.
The following is used in GRUB to reserve 2G starting at 4G for the ICE driver and
leaving the rest (above and below) for system use.

kernel (hd0,1)/boot/vmlinuz root=/dev/hdb2 vga=0x314 ... showopts memmap=2048M$4096M

OLDER SYSTEMS:

For SlimPics, PIC4s and earlier cards, or on systems with < 4G of memory, it
gets complicated. See below for a number of case examples.

On laptops, the hot-plug PCI allocator may try to assign hardware to actual
physical memory above mem=XX instead of above physical memory. The kernel will
not put devices below 256M. If you have more memory than this, you should add
a system page near the top of memory to the system's list of useable memory.
The system will not assign hardware anywhere below the last useable page.
So a laptop with 512M may want to use:

append="mem=254M mem=1M@510M" <-- this line added (pre 2.6 kernels)
or
append="mem=254M memmap=1M@510M" <-- this line added (2.6+ kernels)

and be able to have 256M of ram available starting at 254M. Why not use
1M@511 ? We found many platforms want to put other stuff just below the top
of physical memory, in this case (512M-~128K).

Kernels 2.6 and higher only parse mem= for the mem=X form. The mem=X@Y or mem=X$Y
must be in a memmap= argument. Pre 2.6 kernels do NOT support memmap= arg and 2.6+
kernels will treat mem=1M@510M the same as mem=1M so there is no universal form.
For the rest of this help, we will show mem[map]= where the 'map' is for 2.6+ kernels.

In some laptop/linux/memory combinations, this does not stop the Card Services
driver from placing the card in physical memory. A more on /proc/pci will show
where it put the card. To stop it from doing this, we need to reserve the
memory region for the ice card. The syntax is:

append="mem=254M mem[map]=256M$254M mem[map]=1M@510M"

where the amount of reserve is first, a $ sign, and the start of reserve.

By similar argument, a machine with more than 4G of memory is only allowed
to use the region below 4G for the pre 5 series ice cards. This syntax allows
the system to still use the memory region above 4G. For example:

append="mem=2048M mem[map]=4096M@4096M" <-- this line added

This system will have 2048M of ICE ram available starting at 2048M.
The system may have also mapped PCI devices under the 4G region as well.

Type
prompt> more /var/log/boot.msg
or
prompt> more /var/log/dmesg
or
prompt> more /proc/iomem

to see the kernels use of memory and make sure to stay away from the
regions that are (reserved). Often, the last 256M before 4G is reserved
for PCI devices. In that case, for a system with 8G of memory,

append="mem=1792M mem[map]=4096M@4096M" <-- this line added

would be necessary to leave 2048M (2G) for the ice driver, and 6G-256M for the system.

Some kernels do not support the memmap= keyword, so the ice card must use the top
of memory or some will be wasted. The 5+ series ice cards support 64bit PCI
addressing so the ICE ram can be put above 4G. The 4- series ice cards will not
run using memory above 4G.

If you have memory above 4G in your system and a 5+ series card, just
use the space above 4G which is usually free of other driver clutter.
Most systems with 8G of memory will leave a hole between 3G and 4G for devices.
The physical memory will be split from 0G-3G and 4G-9G.
To use the last 2G for the ice card,

append="mem=7186M" <-- this line added

'''NOTE:''' The driver cannot handle different maps for mixed card systems at the same time.
'''NOTE:''' The driver cannot handle maps that span the 4G address boundary.
The ICE ramdisk and mappable area must be all above 4G or all below 4G.

----
'''Midas ICEDISK configuration
'''
----

To configure a ramdisk in X-Midas, include the following entry in the file
diskunx.cfg in the X-Midas CFG area. Make sure to also have an entry in
midas.cfg for a disk auxiliary that matches the entry in diskunx.cfg.
You must create the /???/icedisk/ directory on a real disk to contain the
Midas headers. The detached portion holds the pointers to physical memory.
'''NOTE:''' This is NOT a Linux ramdrive, it's just physical memory that we told
Linux to leave alone. The book-keeping is all internal to the X-Midas code.

Example diskunx.cfg:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Special disk handing table for UNIX systems
! mount_point type raw_device raw_offset raw_size
!
/midas/icedisk/ RAM /dev/mem 32M 92M
/sam/ CFS /dev/rspc0 0 128M

Example midas.cfg disk aux entry:

M_aux_list(9) /midas/icedisk/

Including the statement:

PIC AUX 9

in the %xmstartup macro will then allow the PIC CREATE verbs to create files
on the ramdisk for DMAs using PICDRIVER, SOURCEPIC, and SINKPIC.

To configure a ramdisk in NeXtMidas, include the following qualifiers in nmstartup.mm
where the auxiliary is being defined:

if env.ostype eqs "UNIX"
set U:AUX.1 "/midas/data1/+/" ! normal aux
set U:AUX.9 "ramd:/midas/icedisk/,RAM,500M,512M" ! ramdisk aux - specific
set U:AUX.9 "ramd:/midas/icedisk/,RAM,AUTO," ! ramdisk aux - automatically detect from loaded driver
elseif env.ostype eqs "DOS"
set U:AUX.9 "ramd:\midas\icedisk\,RAM,500M,512M"
endif

where the comma-seperated attributes are the identifier 'RAM' followed by the
start and size of the ramdisk.

=== SOL - SUN Solaris ICE-DSP Driver Installation Notes ===

Load the ICE software tree onto the system. The environment symbol ICEROOT
should be defined pointing to root of this tree.

'''NOTE: The environment symbol XMAREA_ICE overrides ICEROOT for X-Midas users.'''
The driver source files are in the $ICEROOT/drv/sol directory.
To install the driver, follow these steps:

'''NOTE: you must be in the /bin/csh to run this '''

1. Edit the $ICEROOT/drv/sol/picdrv.conf file to set the card
configuration parameters. Follow the instructions in this file.
If the device does not show up in the /devices directory, reboot
the system with "boot -r" to reconfigure the /devices area. On
Solaris 8 you need to type "dev" at the boot promp to get to the
devices tree (cd to /devices does not work).

Add the contents of $ICEROOT/drv/sol/devlink.tab to /etc/devlink.tab
file. This causes Solaris to create a soft link, "/dev/icepic0", to
the character device in the /devices tree

2. cd to the $ICEROOT/drv/sol directory. If you are using Solaris 2.6,
you will need to edit the icepic script to set the correct compiler
flags. The default is for a Solaris 2.7 64-bit driver. Then type:

./icepic make

to make the driver.

3. To install the driver, type:

./icepic install

This drops the kernel module into the system area.

To load the driver without rebooting the system type:

./icepic start

This script can also be used to stop or restart the driver.

The driver is now installed. At boot time, the system will attach the cards
listed in the picdrv.conf at the address or slot specified. They will show
up in the /dev filesystem as /dev/icepic0, /dev/icepic1 ...

'''NOTE:''' if you add or remove cards, the picdrv.conf file will need to be updated
and the driver reloaded. So much for plug-and play on the SUN architecture...

To exercise the cards, use the mid-level driver libraries in the ./lib area of
this software tree. A small test program in the ./test area may be used to run
a series of tests on the card. An X-Midas macro and primitive are also
available to run more diagnostic tests on each card. See test/readme.txt.

X-Midas users should enter this name in the device name slot in the
hardware configuration table as shown in the examples below:

PIC1==ICEPIC,DEVNO=0,IOM=xxx,
PIC2==ICEPIC,DEVNO=1,IOM=xxx,
PIC3==ICEPIC,DEVNO=2,IOM=xxx,
or
PIC1==ICEPIC,PCI-DEV,/dev/icepic0,,,IOM=xxx,
PIC2==ICEPIC,PCI-DEV,/dev/icepic1,,,IOM=xxx,
PIC3==ICEPIC,PCI-DEV,/dev/icepic2,,,IOM=xxx,

[[ICE_Help_ICELIB#PIC_OPEN|See HELP PIC_OPEN]] for hardware file setup details.

=== SGI - Silicon Graphics ICE-DSP Driver Installation Notes ===

Load the ICE software tree onto the system. The environment symbol ICEROOT
should be defined pointing to root of this tree.

'''NOTE: The environment symbol XMAREA_ICE overrides ICEROOT for X-Midas users.'''
The driver source files are in the $ICEROOT/drv/sgi directory.
To install the driver, follow these steps:

1. cd to the $ICEROOT/drv/sgi directory

2. To dynamically load the driver, type "make install". This will
lboot the driver into the kernel.

3. To rebuild /unix with the driver, type "make kernel" this will build a
/unix.install file, then reboot the system to load the driver, Once
this is done, the driver will load automatically each time the system
is booted.

Check out /var/adm/SYSLOG for driver print statements (or the console)

To exercise the cards, use the mid-level driver libraries in the ./lib area of
this software tree. A small test program in the ./test area may be used to run
a series of tests on the card. An X-Midas macro and primitive are also
available to run more diagnostic tests on each card. See test/readme.txt.

X-Midas users should enter this name in the device name slot in the
hardware configuration table as shown in the examples below:

PIC1==ICEPIC,DEVNO=0,IOM=xxx,
PIC2==ICEPIC,DEVNO=1,IOM=xxx,
PIC3==ICEPIC,DEVNO=2,IOM=xxx,
or
PIC1==ICEPIC,PCI-DEV,/dev/icepic0,,,IOM=xxx,
PIC2==ICEPIC,PCI-DEV,/dev/icepic1,,,IOM=xxx,
PIC3==ICEPIC,PCI-DEV,/dev/icepic2,,,IOM=xxx,

[[ICE_Help_ICELIB#PIC_OPEN|See HELP PIC_OPEN]] for hardware file setup details.

=== WIN - Windows ICE-DSP Driver Installation Notes ===

Load the ICE software tree onto the system. The environment symbol ICEROOT
should be defined pointing to root of this tree.

The driver files are in the %ICEROOT%\drv\w2k, \wnt, or \w9x directories.

This driver uses the WDM generic driver model supporting Win98 and Win2000
platforms. A non-PnP version was developed to support older NT4 platforms.
Windows-NT users are advised to upgrade to Windows-2000.

If this is your first time, read the special RAM handling section below.

To install the driver on Win98 or Win2000:

1. Edit the BOOT.INI file to reserve physical RAM for high speed DMA.
2. Edit the Icepic.inf file in the %ICEROOT%\drv\w2k or \w9x directory
to setup the RAM allocation parameters for your platform.
3. Reboot the system.
4. If the system does not automatically detect the new hardware,
select 'Add Hardware' from the Control Panel and let it find the new
Plug-n-Play PCI devices.
5. Select 'Browse for new driver files' and find the %ICEROOT%\drv\w2k
or \w9x area depending on your platform.

To install the driver on WinNT:

1. Edit the BOOT.INI file to reserve physical RAM for high speed DMA.
2. Edit the icepic.reg file in the %ICEROOT%\drv\wnt directory
to setup the RAM allocation parameters for your platform.
3. Run icepic.reg and reboot the system.

That's all there is to it. The device names are Icepic0, Icepic1, ... IcepicN.

NeXtMidas users should enter this name in the device name slot in the
hardware configuration table as shown in the examples below:

PIC1==ICEPIC,DEVNO=0,IOM=xxx,
PIC2==ICEPIC,DEVNO=1,IOM=xxx,
PIC3==ICEPIC,DEVNO=2,IOM=xxx,
or
PIC1==ICEPIC,PCI-DEV,Icepic0,,,IOM=xxx,
PIC2==ICEPIC,PCI-DEV,Icepic1,,,IOM=xxx,
PIC3==ICEPIC,PCI-DEV,Icepic2,,,IOM=xxx,

[[ICE_Help_ICELIB#PIC_OPEN|See HELP PIC_OPEN]] for hardware file setup details.

To exercise the cards, use the mid-level driver libraries in the ./lib area of
this software tree. A small test program in the ./test area may be used to run
a series of tests on the card. An NeXtMidas macro and primitive are also
available to run more diagnostic tests on each card. See test/readme.txt.

----
'''Special RAM Handling in Windows
'''
----

Since Intel machines cannot map contiguous PCI address space into contiguous
virtual address space, it is necessary to allocate contiguous physically
addressable RAM buffers to support high speed dma and mmap() them to virtual
addresses for user programs to access the data.

In Win2000, this is done by reserving a piece of physical memory for the
ICE-PICs high speed DMA. This physical memory can be mapped to a ramdisk, as
in NeXtMidas, for allocation management and convenient access.

To reserve the upper part of memory, add the /maxmem=n switch in the BOOT.INI
file which sits on the boot drive root directory, normally c:\boot.ini .
This tells the operating system to not use any of the memory above this value.
The following shows an example BOOT.INI file for Windows-2000 with the mods:

[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINNT
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Microsoft Windows 2000 Professional" /fastdetect /maxmem=112

The Icepic.inf file also needs to be modified to reflect your system. The
[Strings] section at the top of the icepic.inf file has the following entries:

Ram.Start="112"
Ram.SizeDisk="4"
Ram.SizeMap="12"

In this example, the system has 128Mby of memory: 112Mby will be used
by the operating system, and the rest (16Mby) will be reserved for a
4Mby ramdisk (starting at 112M) and 12Mby mappable (starting at 112+4M).

=== MAC - MAC-G3 ICE-DSP Driver Installation Notes ===

This driver was written by General Dynamics Corp.
Call Jim Crumley at 301-497-2040 for information.

</onlyinclude>
[[Category:ICE_Help]]

ICE Help DRIVERS - Revision history

ConvertBot: Low level drivers for ICE-DSP cards