INSTALL

================================================================================

To build SIMD test framework on Linux, open terminal window,
go to UniSIMD's "test" subfolder,
make sure necessary tools and libraries are installed
    sudo apt-get update
for native builds (binary ABI matches host: x64, RISCs):
    sudo apt-get install make g++
for multilib builds (if libs are available: 32-bit x86):
    sudo apt-get install make g++-multilib
run for x64 architecture:
    make -f simd_make_x64.mk -j4
    ./simd_test.x64f32
run for x86 architecture:
    make -f simd_make_x86.mk -j4
    ./simd_test.x86
run for *** architectures (on native host or QEMU linux-user mode):
    make -f simd_make_***.mk -j4
    ./simd_test.***
Prerequisites for building/emulating guest non-x86 architectures as well as
configurations for particular hardware platforms are given in the makefiles.
By default, DEB-based distributions (Mint, Ubuntu, Debian) are implied,
refer to the AArch64 Linux on RPi3 section down below for RPM-based options.

To build SIMD test framework on macOS, open terminal window,
go to UniSIMD's "test" subfolder,
make sure necessary tools and libraries are installed:
    clang
it will prompt to install Command Line Tools (will make alias to g++)
run for x64 architecture:
    make -f simd_make_x64.mk -j4
    ./simd_test.x64f32
run for a64 architecture:
    make -f simd_make_a64.mk clang -j4
    ./simd_test.a64f32
Alternatively, use clang option for x64 (make -f simd_make_x64.mk clang -j4).

To build SIMD test framework on Windows using Visual Studio,
download and install Visual Studio 2022 or later (with clang option enabled),
then open UniSIMD's "test" subfolder and click on VS2022 solution file:
    simd_test_x64.sln
from within the Visual Studio press F5 key to build and run the binary.

For maximum compatibility, always copy the binaries to *.sln's subfolder.

To build SIMD test framework on Windows using TDM64-GCC,
download and install TDM64-GCC toolchain (tdm64-gcc-10.3.0-2.exe) from github,
then open UniSIMD's "test" subfolder and run from "cmd" or Windows Explorer:
    simd_make_w64.bat
produced simd_test_w64f32.exe binary file will launch upon build completion.

================================================================================

To build QEMU emulator from source on Linux, download the latest version from:
    http://wiki.qemu.org/Download
unpack the archive, open terminal window, go to QEMU's root folder,
make sure necessary tools and libraries are installed:
    sudo apt-get update
    sudo apt-get install make g++ ninja-build
    sudo apt-get install pkg-config libglib2.0-dev libpixman-1-dev zlib1g-dev
when building QEMU on RPM-based systems like openSUSE:
    sudo zypper install make gcc-c++ ninja
    sudo zypper install patch glib2-devel libpixman-1-0-devel zlib-devel
to build a reduced set of targets for linux-user mode emulation only, use:
    ./configure --target-list=arm-linux-user,aarch64-linux-user,\
mips-linux-user,mipsel-linux-user,mips64-linux-user,mips64el-linux-user,\
ppc-linux-user,ppc64-linux-user,ppc64le-linux-user,\
i386-linux-user,x86_64-linux-user
    (copy the whole multi-line command above without leading or trailing spaces)
    (paste into terminal and run after or instead of plain ./configure script)
run multithreaded make (use -j8 or -j16 on machines with higher core count):
    make -j4
run installation script:
    sudo make install

When building QEMU from source isn't necessary install full binary package:
    sudo apt-get install qemu-user
on RPM-based systems like openSUSE:
    sudo zypper install qemu

QEMU 5.2.0 and beyond may require ninja-build package to build from source.
Starting from QEMU 5.2.0 POWER9 lxvwsx instruction is supported properly.
From QEMU 5.2.0 through QEMU 6.2.0 ppc64abi32 targets are marked as deprecated
and will be removed in the following releases (Ubuntu 22.04 should have 6.2.0).
QEMU 6.2.0 contains some MIPS regressions and POWER bugs (exposed by gcc 11.3),
consider an update: https://bugs.launchpad.net/ubuntu/+source/qemu/+bug/2011832
or build QEMU 7.2.0 from source (contains all the fixes, also in Ubuntu 23.04).
All QEMU versions since 6.0.0 including 8.0.0 have MIPS bug reported here:
https://gitlab.com/qemu-project/qemu/-/issues/1624
Note that using standalone MIPS cross-compiler masks the issue with local QEMU.

Ubuntu 20.04 is the first release where MIPS cross-compilers have caught up
with the rest of the pack (standalone 2020.06-01 and mipsisa64r6* are 9.3.0).
It is the only release which has full support for all the targets (ppc64abi32).

================================================================================

To emulate future x86 targets (AVX-512) on modern x86 Linux hosts use Intel SDE:
    https://software.intel.com/content/www/us/en/develop/articles/
                                       /intel-software-development-emulator.html
download and unpack the archive.

In terminal window for 32-bit x86 run:
    path-to-kit/sde   -snb -- ./simd_test.x86avx -c 1
    path-to-kit/sde   -knl -- ./simd_test.x86avx512 -c 1
for AVX (Sandy Bridge) and AVX512F (Knights Landing) respectively.

In terminal window for 64-bit x64 run:
    path-to-kit/sde64 -hsw -- ./simd_test.x64f32avx -c 1
    path-to-kit/sde64 -skx -- ./simd_test.x64f32avx512 -c 1
for AVX2 (Haswell) and AVX512DQ (Skylake-X) respectively.

Intel's AVX512 fp16 subset (in Sapphire Rapids and in some Alder Lake configs)
is now supported in Intel SDE 9.0 (with -spr option) and can be tested within
the assembler by substituting regular 32/64-bit cmdps with 16-bit cmdms aliases
and using direct ASM section output comparison method (with ARMv8.2 fp16).

Use "-c 1" option to reduce test time when emulating with Intel SDE.

================================================================================

To experiment with Linux in little-endian mode on POWER8 server consider:

1) Ubuntu Server 16.04.06 Xenial Xerus (ppc64el) from 27-Feb-2019:
    https://cdimage.ubuntu.com/releases/16.04/release/
    ubuntu-16.04.6-server-ppc64el.iso
    (install most recent HWE kernel version)

2) Ubuntu Server 18.04.05 Bionic Beaver (ppc64el) from 10-Aug-2020:
    https://cdimage.ubuntu.com/releases/18.04/release/
    ubuntu-18.04.5-server-ppc64el.iso
    (install the original kernel version, no HWE)

3) Ubuntu Server 20.04.02 Focal Fossa (ppc64el) from 01-Feb-2021:
    https://cdimage.ubuntu.com/releases/20.04/release/
    ubuntu-20.04.2-live-server-ppc64el.iso
    (system installs, but won't boot, features new installer)

The images were tested on Tyan Habanero TN71-BP012 10-core POWER8 server
with installation instructions described here:
https://www.phoronix.com/scan.php?page=article&item=tyan-power8-server&num=1

Boot the system from USB flash drive without any ethernet cables attached,
otherwise the boot menu won't allow any boot options to be activated properly.
When presented with a blank screen and a cursor, read the next paragraph.

Before an installation can proceed the following steps may need to be performed
on the first boot. Switch to tty2 with Alt-F2, activate the tty as the message
requests by pressing <enter>, run /sbin/debian-installer (first two images).

To setup networking on a freshly installed Ubuntu Server with ethernet cable
use the farmost ethernet socket among the main four as seen from the PSU.

On Ubuntu Server 16.04 use ifconfig to configure the network:
    sudo nano /etc/network/interfaces
Edit the file above to add the next two lines at the bottom:
    auto enP1p3s0
    iface enP1p3s0 inet dhcp
Press Ctrl-O <enter> to save the changes and Ctrl-X to exit from the editor.
    sudo /etc/init.d/networking restart
or
    sudo systemctl restart networking.service

On Ubuntu Server 18.04 use netplan to configure the network:
    sudo nano /etc/netplan/01-netcfg.yaml
Edit the file above so that it looks like this:
network:
    ethernets:
        enP1p3s0:
            dhcp4: yes
    version: 2
    renderer: networkd
Press Ctrl-O <enter> to save the changes and Ctrl-X to exit from the editor.
    sudo netplan apply

When booting Ubuntu Server offline after the networking has been set up
the login prompt is not immediately shown and a few minutes time
needs to be taken before SSH authorization becomes workable.

To install XFCE once the system is up and running:
    sudo apt-get update
    sudo apt-get install xfce4
    startx (choose "Use default config" on first start)
    (launch terminal window in XFCE from the bottom panel)
    sudo apt-get install firefox unzip leafpad
    sudo apt-get install make g++ clang
Alternatively install Xubuntu desktop for more integrated experience:
    sudo apt-get update
    sudo apt-get install xubuntu-desktop
    sudo apt-get install make g++ clang
    reboot

After installing XFCE Ubuntu may start ureadahead process which loads the CPU
preventing normal user workflow for a few minutes until the process
is complete and the system is back to normal (use top command to monitor).

================================================================================

To experiment with Linux in AArch64 mode on Raspberry Pi 3 consider:

1) Devuan ASCII 2.0.0 plain (arm64 raspi3) image from 06-Jun-2018:
    https://devuan.org/
    https://files.devuan.org/devuan_ascii/embedded/
    devuan_ascii_2.0.0_arm64_raspi3.img.xz
image boot credentials:
    login: root
    password: toor

2) openSUSE Leap15.0 XFCE (aarch64 raspi3) image from 02-Jul-2018:
    https://en.opensuse.org/HCL:Raspberry_Pi3
    http://download.opensuse.org/ports/aarch64/distribution/leap/15.0/appliances
    openSUSE-...-ARM-XFCE-raspberrypi3.aarch64-2018.07.02-Buildlp150.1.1.raw.xz
image boot credentials:
    login: root
    password: linux

Flashing images above to an SD card is similar to a Raspbian installation:
http://www.raspberrypi.org/documentation/installation/installing-images/linux.md
    lsblk (before inserting SD card)
    lsblk (after inserting SD card to see its device ID, mmcblk0 in this case)
    sudo su
    umount /dev/mmcblk0p1 (if exists and mounted, unmount partition: p1)
    umount /dev/mmcblk0p2 (if exists and mounted, unmount partition: p2)
    (change to Downloads directory where image file is unpacked)
    dcfldd bs=4M if=devuan_ascii_2.0.0_arm64_raspi3.img of=/dev/mmcblk0
    sync (before extracting SD card from the slot)
    exit (from super-user mode)

Devuan image requires partition resizing once booted (credentials above):
http://elinux.org/RPi_Resize_Flash_Partitions (performed on RPi using fdisk)
    fdisk /dev/mmcblk0
    p (to see the current partition table)
    d (answer: 2, to delete partition 2)
    (for swap leave some space at the end by subtracting 1M from default sector)
    n (answer: p, for primary; answer: 2, for new partition 2; <enter>; <enter>)
    (when fdisk asks to remove ext4 signature at the end, answer: N, to keep it)
    (create new partition 3 as 2, from the space left at the end of the SD card)
    (t 3, to change partition type from 83 "Linux" to 82 "Linux-swap / Solaris")
    w (writes the changes and quits fdisk)
    shutdown -r now (login again after reboot)
    resize2fs /dev/mmcblk0p2
    df -h (to check the new partition size)
    (mkswap /dev/mmcblk0p3)
    (add "/dev/mmcblk0p3 none swap sw 0 0" to /etc/fstab to auto-swapon at boot)
to install XFCE once the partition is resized:
    (commands below are not prefixed with "sudo" as image is booted into "root")
    (using "apt" command instead of "apt-get" allows to save space on SD card)
    apt-get update
    apt install xfce4 (choose keyboard layout)
    reboot (for XFCE to honour chosen keyboard layout)
    startx (choose "Use default config" on first start)
    (launch terminal window in XFCE from the bottom panel)
    apt install firefox-esr unzip
    reboot (login again and "startx" into XFCE)
    (firefox is now available under "Internet" section of the main menu)
    apt install make g++ clang
to setup ARM Instruction Emulator for SVE on AArch64 hosts install modules:
    apt install environment-modules
    reboot (login again and "startx" into XFCE)
    (modules only work outside of XFCE, use "Log Out" to configure modules)
    (once armie module is loaded, use startx again to work with it in XFCE)

openSUSE image is RPM-based & boots directly to XFCE (credentials above):
    (commands below are not prefixed with "sudo" as image is booted into "root")
    (Raspberry Pi 3 Model B+ doesn't have networking with openSUSE, use old one)
    zypper install MozillaFirefox
    reboot (and login again)
    (firefox is now available under "Internet" section of the main menu)
    zypper install make gcc-c++ clang
to setup ARM Instruction Emulator for SVE on AArch64 hosts, install modules:
    zypper install Modules
    reboot (and login again)
adjust UniSIMD's makefiles to use g++ instead of triplet name, remove -static
    leafpad simd_make_a64.mk & (once archive is downloaded as shown below)

Download the archive from github and unpack it (in terminal window):
    cd Downloads
    (alternatively to using a browser for downloading, use wget from terminal)
    (wget https://github.com/VectorChief/UniSIMD-assembler/archive/master.zip)
    (mv master.zip UniSIMD-assembler-master.zip)
    unzip UniSIMD-assembler-master.zip
    cd UniSIMD-assembler-master/test
    make -f simd_make_a64.mk -j4
    ./simd_test.a64f32

Download the ARM IE and install it (Ubuntu_16.04 for Devuan, SUSE_12 for SUSE):
https://developer.arm.com/tools-and-software/server-and-hpc/
                       /compile/arm-instruction-emulator/get-software/download
    cd Downloads
    tar -xvzf ARM-Instruction-Emulator_20.1_AArch64_***_aarch64.tar.gz
    cd ARM-Instruction-Emulator_20.1_AArch64_***_aarch64
    ./arm-instruction-emulator-20.1_Generic-AArch64_***_aarch64-linux-***.sh
    (scroll down and type: yes <enter>, when license shows up on the screen)
    reboot (and login again)
    module use /opt/arm/modulefiles
    module avail
    module load Generic-AArch64/***/arm-instruction-emulator/20.1
    (armie should now be available in the PATH variable, check vector lengths)
    armie -mlist-vector-lengths

To test SVE targets with ARM Instruction Emulator run:
    armie -msve-vector-bits=512 -- ./simd_test.a64f32sve -c 1

Use "-c 1" option to reduce test time when emulating with ARM IE.

Devuan ASCII 2.0.0 image has USB flash drives automount, but older clang 3.8.1,
it also allows setting CPU frequency scaling governor for maximum performance:
echo "performance" | tee /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
Current frequency (600Mhz min-level, 1200Mhz max-level) can be monitored using:
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq

openSUSE Leap15.0 image has newer clang, but no automount for USB flash drives,
it offers min-level CPU frequency by default and it lacks CPU scaling governor.
It also doesn't support networking on newer Raspberry Pi 3 Model B+ from 2018.
On the bonus side, modules can be configured from within XFCE as they should be.

Both images feature modern set of compilers sufficient for the build:
g++ 6.3.0, clang 3.8.1 (Devuan ASCII 2.0.0, clang prior to 3.8 was much slower)
g++ 7.3.1, clang 5.0.1 (openSUSE Leap15.0)
fresh Firefox 60.2.2esr browser and a 32bpp display output.

================================================================================

To install Ubuntu MATE 20.04 LTS on Raspberry Pi 4 consider:

1) Ubuntu MATE 20.04.1 desktop (arm64 raspi) image from 29-Oct-2020:
    https://ubuntu-mate.org/download/arm64/focal/
    https://releases.ubuntu-mate.org/focal/arm64/
    ubuntu-mate-20.04.1-desktop-arm64+raspi.img.xz

Flash image to an SD card using "Disks -> Restore Disk Image" utility with GUI
from a regular Ubuntu desktop. It will unpack *.xz internally in the process.

Once booted the image will automatically resize the root partition to fully
utilize all space available on an SD card and proceed to install the system.

When online Ubuntu may start unattended-upgr process which holds the lock
preventing installation of other packages potentially for a few hours.
Install the system offline to postpone this process for a later time.

To emulate SVE instruction subset install QEMU 4.2.1 from the repository:
    sudo apt-get update
    sudo apt-get install qemu-user

================================================================================

To experiment with Ubuntu Server on Raspberry Pi 4 consider:

1) Ubuntu Server 20.04.2 preinstalled (arm64 raspi) image from 01-Feb-2021:
    http://cdimage.ubuntu.com/releases/20.04/release/
    ubuntu-20.04.2-preinstalled-server-arm64+raspi.img.xz
image boot credentials:
    login: ubuntu
    password: ubuntu

Flash image to an SD card using "Disks -> Restore Disk Image" utility with GUI
from a regular Ubuntu desktop. It will unpack *.xz internally in the process.

When booting Ubuntu Server offline for the first time the login prompt
is often presented too early in the process and a few minutes time
needs to be taken before SSH authorization becomes workable.

Once booted the image will automatically resize the root partition to fully
utilize all space available on an SD card and request to change the password.

When online Ubuntu may start unattended-upgr process which holds the lock
preventing installation of other packages for a few minutes until the process
is complete and the lock is released (run top to monitor, q to quit monitoring).

To test SVE targets with ARM Instruction Emulator run:
    sudo apt-get update
    sudo apt-get install environment-modules
    reboot
Download ARM-Instruction-Emulator_21.0_AArch64_Ubuntu-18.04_aarch64.tar.gz from:
https://developer.arm.com/tools-and-software/server-and-hpc/
                       /compile/arm-instruction-emulator/get-software/download
and follow installation instructions as presented here:
https://developer.arm.com/documentation/102190/2100/Get-started/
                                             /Install-Arm-Instruction-Emulator
Note that module command is only available before installing the desktop.

To setup networking on a freshly installed Ubuntu Server without ethernet cable
consider using "USB tethering" from an Android phone or an iPhone.

Plug in phone's USB cable to Raspberry Pi 4's USB slot and select
"USB tethering" option from phone's menu or in "Settings -> Personal Hotspot".

On Raspberry Pi 4 run the following command in the terminal:
    ip -c a
to list all the network interfaces. USB tethered option should be called:
    usb0
or
    eth1
In any case it shows up on the list once tethering is activated on the phone.

To complete setting up USB networking add interface names to the netplan:
    sudo nano /etc/netplan/50-cloud-init.yaml
Edit the file above so that it looks like this:
network:
    ethernets:
        eth0:
            dhcp4: true
            optional: true
        eth1:
            dhcp4: true
        usb0:
            dhcp4: true
    version: 2
Press Ctrl-O <enter> to save the changes and Ctrl-X to exit from the editor.

Apply the changes by typing:
    sudo netplan apply
Check the connection with:
    ping google.com
Press Ctrl-C to stop.

Once the networking is set up (only needs to be done once) install the desktop:
    sudo apt-get update
    sudo apt-get install ubuntu-mate-desktop
    (if MATE is not yet available the command installs GNOME 3 desktop instead)
    (select lightdm when prompted for more familiar MATE-themed login screen)
    reboot
Alternatively install Xubuntu desktop on a clean system:
    sudo apt-get update
    sudo apt-get install xubuntu-desktop
    (if XFCE is not yet available the command installs GNOME 3 desktop instead)
    (select lightdm when prompted for more familiar XFCE-themed login screen)
    reboot

================================================================================