Config

This document details how to install the ICE Toolkit software and NeXtMidas for the operation of ICE-PIC6/7/8 series DSP cards on RHEL/CentOS 6/7/8.

Note: Many configurations are possible and the installation may need to be tailored to fit your specific needs. This guide aims to cover the vast majority of use cases.

Prerequisites

As root, install prerequisite packages:

• gcc
• gcc-c++
• glibc-devel
• libstdc++-devel
• kernel-headers
• kernel-devel
• tcsh

You will also need a Java Development Kit (JDK). We recommend downloading the Oracle JDK for your distribution, usually as a tar.gz file, either version 1.7 or 1.8.

ICE Operating User

Create ICE operating user 'iceman':

useradd iceman
passwd iceman
<enter password>

Change iceman's shell to TC-Shell:

usermod -s /bin/tcsh iceman

Directory Structure

Create the following directory structure:

/
|-- ...
|-- mnt
|   |-- data01
|   |-- data11
|   |-- icedisk
|   `-- ramdisk
|-- opt
|   `-- ice
|   |   |-- aux
|   |   |   |-- data01 -> /mnt/data01
|   |   |   |-- data11 -> /mnt/data11
|   |   |   |-- icedisk -> /mnt/icedisk
|   |   |   `-- ramdisk -> /mnt/ramdisk
|   |   |-- pkg
|-- ...

Note that /opt/ice/aux only contains links. This is a matter of convenience so that all of the AUXes can be referenced from within the ICE tree. They can be create as such:

cd /opt/ice/aux
ln -s /mnt/data01 data01
ln -s /mnt/data11 data11
ln -s /mnt/icedisk icedisk
ln -s /mnt/ramdisk ramdisk

The entire /opt/ice directory should be owned by iceman, as well as /mnt/icedisk:

chown -R iceman:iceman /opt/ice /mnt/icedisk

Download Software

Download the latest stable ICE tree and NeXtMidas release from http://www.ice-online.com/software/downloads/stable/

Copy the ICE tree software ZIP archive, the NeXtMidas ZIP archive, and the JDK archive into /opt/ice/pkg and make sure they are owned by iceman:

cp <source path>/iceXXX.zip /opt/ice/pkg
cp <source path>/nxmXXX.zip /opt/ice/pkg
cp <source path>jdkXXX.tar.gz /opt/ice/pkg
chown iceman:iceman /opt/ice/pkg/*

Now switch users to iceman:

su - iceman

Dearchive the software packages and make symbolic links, which makes the paths more manageable and later software upgrades considerably easier:

cd /opt/ice/pkg
unzip iceXXX.zip
ln -s iceXXX icexxx
unzip nxmXXX.zip
ln -s nxmXXX nmxxx
tar -xzf jdkXXX.tar.gz
ln -s jdkXXX jdk

Temporary Files Directory

As iceman, create directory for temporary NeXtMidas files:

mkdir ~/tmp

Configuration Files

Modify /opt/ice/pkg/nmxxx/nxm/sys/cfg/nmstartup.mm to include the following (use this as a complete example):

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Macro to initialize system specific settings.
! @author Jeff Schoen
! @version $Id: nmstartup.mm,v 1.37 2011/11/10 20:58:41 ntn Exp $
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
startmacro

info "DEPRECATION warnings ON, to turn off edit nmstartup.mm in SYS->CFG"
debug on DEPRECATE

! portable way to define normal auxes (1 = /opt/ice/aux/data01/+/, etc.)
file name u:aux.1  (opt,ice,aux,data01,+)
file name u:aux.2  (opt,ice,aux,ramdisk)
file name u:aux.11 (opt,ice,aux,data11,+)

! define OS specific AUXes
if env.ostype eqs "UNIX"
  sedit AUX.9 AUX.9 append ",RAM,AUTO"
! sedit AUX.9 AUX.9 append ",RAM,<start>M,<sized>M"
elseif env.ostype eqs "DOS"
  sedit AUX.9 AUX.9 append ",RAM,<start>M,<sized>M"
elseif env.ostype eqs "VMS"
  ! nothing specific for VMS
endif

! set write AUX and read AUX list
aux 1 1 cwd dat ram

path set dsp hwc

env set "HWFILE" "nxm.sys.dat.hwconfig"
res t:km "nxm.sys.cfg.keyMap.tbl"
env set KEYMAP ^km

endmacro

Create the following NeXtMidas macro /home/iceman/nmstartup.mm

startmacro

option ice /opt/ice/pkg/icexxx
if "/proc/driver/icepic" fexists then
  pic aux 9
endif
hw file nxm.ice.dat.hwconfig
aux 1 1|2|9|DAT|11|CWD|RAM|HOME

endmacro

Add the following lines to /home/iceman/.cshrc, creating the file if it does not already exist:

#!/bin/csh
#
# Red-Hat System csh.cshrc
if ( -f /etc/csh.cshrc ) source /etc/csh.cshrc
#
# Set environment variables
if ( "${?HOMEDIR}" == 0 ) then
  setenv HOMEDIR /home/iceman
endif
if ( "${?TMPDIR}" == 0 ) then
  setenv TMPDIR $HOMEDIR/tmp
endif
if ( "${?USERPATH}" == 0 ) then
  setenv USERPATH /bin:/sbin:/usr/bin:/usr/sbin:${HOMEDIR}/bin
  setenv PATH ${PATH}:${USERPATH}
endif
if ( "${?ICEPKG}" == 0 ) then
  if ( -e /opt/ice/pkg ) then
    setenv ICEPKG  /opt/ice/pkg
    setenv ICEROOT $ICEPKG/icexxx
    setenv NMROOT  $ICEPKG/nmxxx
    setenv NM_USER_JVM_FLAGS "-Xmx1024m -Xms1024m"
    setenv NMHISTORY_DIR $TMPDIR
    setenv JAVAHOME $ICEPKG/jdk  
    if ( -e $JAVAHOME/bin ) then
      setenv PATH ${PATH}:$JAVAHOME/bin
    endif
    if ( -e $JAVAHOME/jre/bin ) then
      setenv PATH ${PATH}:$JAVAHOME/jre/bin
    endif
    if ( -e /opt/ice/bin ) then
      setenv PATH ${PATH}:/opt/ice/bin
    endif
  endif
endif
#
# Set C-Shell/TCSH environment
if ( "${?LINES}" == 0 ) then
  setenv LINES   
endif
if ( "${?COLUMNS}" == 0 ) then
  setenv COLUMNS   
endif
#
# Aliases
alias ice      ${ICEROOT}/jre/ice
alias nms      source ${NMROOT}/os/unix/nmstart
alias nmstart  source ${NMROOT}/os/unix/nmstart

Now load the environment from the .cshrc file, either logout and log back in as iceman, or

source ~/.cshrc

Compile the Software

Compile NeXtMidas and the ICE tree:

nms
nm make all
nm make all ice
nmend

Try starting NeXtMidas and test the configuration:

nms
nm
nM> plot apenny

If a window with a penny appears, NextMidas is working correctly.

Also check to make sure that all AUXes are configured properly:

nM> aux
Write AUX     = 1 (overwrite existing files, where applicable)
Read AUX List = 1|2|9|11|DAT|CWD|RAM|HOME

CWD           = /root/                                             <Type=File>
HOME          = /root/                                             <Type=File>
HOMEPATH      = /root/                                             <Type=File>
DAT           = /opt/ice/pkg/nmxxx/nxm/sys/dat/                    <Type=File>
RAM           = ram:                                               <Type=Ram>
1             = /opt/ice/aux/data01/+/                             <Type=File>
2             = /opt/ice/aux/ramdisk/                              <Type=File>
11            = /opt/ice/aux/data11/+/                             <Type=File>
9             = ramd:/opt/ice/aux/icedisk/,RAM,6144M,8000M,        <Type=RamDisk>

nM> files
Auxiliary [1] = /opt/ice/aux/data01/iceman/   (0 files)
Auxiliary [2] = /opt/ice/aux/ramdisk/   (0 files)
Auxiliary [9] = ramd:/opt/ice/aux/icedisk/   (0 files)
Auxiliary [11] = /opt/ice/aux/data11/iceman/   (0 files)
Auxiliary [DAT] = /opt/ice/pkg/nmxxx/nxm/sys/dat/   (31 files)
...
Auxiliary [CWD] = /home/iceman/   (2 files)
...
Auxiliary [RAM] = ram:   (0 files)
Auxiliary [HOME] = /home/iceman/ matches Auxiliary [CWD] (skipping)

You should see all the AUXes as configured in the sys/cfg/nmstartup.mm and none should say "not a directory". If something is missing, check to make sure that all the directories and/or symlinks listed here actually exist.

Build and Install the ICE-PIC Driver

As root,

cd /opt/ice/pkg/icexxx/drv/lnx
./icepic make
./icepic install
./icepic start

Note: If you are upgrading the driver from a previous version, first stop and remove the old driver:

./icepic stop
./icepic remove

Configure Memory Allocation

There are three memory options to consider:

RamDisk	The size of the circular memory buffer for main ICE-PIC I/O
RamStart	The start point for the memory buffer
RamMapped	Amount of memory used for self-tests and available for other applications

This memory can be allocated using two mechanisms: kernel allocated memory (recommended) and manually mapped memory. Whereas manually allocating memory requires the RamStart parameter to be explicitly specified, kernel allocated memory allows the kernel to handle where in memory the RamDisk buffer is placed.

Kernel Allocated Memory

Configure the kernel line parameters in /etc/default/grub:

...
GRUB_CMDLINE_LINUX="... ice.ra=2 ice.rd=8000M ice.rm=64M"

The following kernel line options are recommended with RHEL/CentOS 6/7/8 running on Intel x86_64 processors:

... elevator=deadline idle=poll processor.max_cstate=0 intel_idle.max_cstate=1 intel_pstate=disable

Manually Mapped Memory

Please note that the '$' must be escaped with '\' under RHEL 7/8):

memmap=<icedisk+mappable>M\$<start>M ice.rs=<start>M ice.rd=<icedisk>M ice.rm=<mappable>M

So an example might be the following:

memmap=8064M\$6144M ice.rs=6144M ice.rd=8000M ice.rm=64M

Remake GRUB2 Configuration

On Legacy/BIOS systems:

grub2-mkconfig -o /boot/grub2/grub.cfg

On UEFI systems:

grub2-mkconfig -o /boot/efi/EFI/redhat/grub.cfg

Verify Configuration

Reboot the machine.

Once rebooted, log into a graphical session as iceman.

Check the that the driver loaded and verify that the requested memory buffer size was obtained:

cat /proc/driver/icepic

You should see

RamStart  : XXXX Mby
RamDisk   : 8000 Mby
RamMapped : 64 Mby
...

Test the ICE-PIC Card

Now from within the NeXtMidas shell, detect any ICE-PIC cards that might be installed:

nM> pic detect

Note the PCI-e width and generation.