gdev: Refactor README files

README

@@ -19,13 +19,15 @@
 Gdev is a rich set of open-source GPGPU runtime and driver software.
 Currently it supports NVIDIA GPUs but is also portable to other GPUs.
 The supported API implementaions include:
+
   "Gdev API": A low-level API to manage details of GPUs.
   "CUDA Driver API": A low-level API adovocated by NVIDIA.
   "CUDA Runtime API": A high-level API adovocated by NVIDIA. 
+
 The implementation of CUDA Driver API and CUDA Runtime API is built
 on top of Gdev API. For CUDA Runtime API we make use of GPU Ocelot as
 a front-end implementation. You can add your favorite high-level API
-to Gdev other than CUDA Driver/Runtime APIs, leveraging Gdev API.
+to Gdev other than CUDA Driver/Runtime APIs on top of Gdev API.
 
 Gdev provides runtime support in both the device driver and the user-
 space library. Device-driver runtime support is a unique feature of
@@ -35,6 +37,7 @@ manage GPUs as first-class citizens and execute CUDA programs itself.
 Gdev's user-space runtime support is also unique in a sense that it 
 is available for multiple open-source and proprietary device drivers.
 The supported device drivers include:
+
   "Nouveau": An open-source driver developed by the Linux community.
   "PSCNV": An open-source driver developed by PathScale.
   "NVRM": A proprietary binary driver provided by NVIDIA.
@@ -51,19 +54,27 @@ To summarize, Gdev offers the following advantages:
 # How to download, install, and use Gdev
 #####################################################################
 
-Do you want to employ runtime support in the OS?
- -> See docs/README.gdev
+You can choose one of the following for what driver to be used:
+
+1. Do you want to use runtime support in the OS?
+ -> See docs/README.gdev 
 
-Do you want to use user-space runtime with Nouveau?
+2. Do you want to use user-space runtime with Nouveau?
  -> See docs/README.nouveau
 
-Do you want to use user-space runtime with PSCNV?
+3. Do you want to use user-space runtime with PSCNV?
  -> See docs/README.pscnv
 
-Do you want to use user-space runtime with NVRM (NVIDIA Driver)?
+4. Do you want to use user-space runtime with NVRM (NVIDIA Driver)?
  -> See docs/README.nvrm
 
 
+Once the driver is successfully installed, you can install high-level API:
+
+1. Do you want to use CUDA?
+ -> See docs/README.cuda
+
+
 #####################################################################
 # The publication of the Gdev project 
 #####################################################################

cuda/configure

@@ -3,6 +3,9 @@
 # libucuda or kcuda
 target='libucuda'
 
+# use Runtime API or not
+runtime='1'
+
 # parse the given options.
 for option
 do
@@ -14,17 +17,34 @@ do
   case "$option" in
   --target=*)
     target="$optarg" ;;
+  --disable-runtime)
+    runtime='0'
   esac
 done
 
 if [ $target = 'libucuda' ] ; then
-cp -f ../libucuda/* .
-cp -rf ../driver/* .
-cp -f ../cudump/* .
-cp -rf ../runtime/ .
+	cp -f ../libucuda/* .
+	cp -rf ../driver/* .
+	cp -rf ../runtime/ .
+	cp -f ../cudump/* .
 elif [ $target = 'kcuda' ] ; then
-cp -f ../kcuda/* .
-cp -rf ../driver/* .
+	cp -f ../kcuda/* .
+	cp -rf ../driver/* .
+	# we don't support Runtime API in kernel
+	runtime='0'
 else
-echo "Error: invalid target '$target'"
+	echo "Error: invalid target '$target'"
 fi
+
+# create API.mk
+cat > API.mk << EOF
+#
+# Copyright (C) Shinpei Kato
+# All Rights Reserved
+#
+# This is automatically generated by configure script.
+#
+
+CUDA_RUNTIME_API=$runtime
+EOF
+

cuda/kcuda/Makefile

@@ -1,3 +1,5 @@
+include API.mk
+
 TARGET = kcuda
 $(TARGET)-y := kcuda_drv.o init.o device.o version.o context.o module.o memory.o execution.o stream.o ipc.o event.o gdev_cuda.o dummy.o
 GDEVDIR = /usr/local/gdev

cuda/libucuda/Makefile

@@ -1,23 +1,20 @@
-# Makefile
-
-#enable: 0, disable:1
-WITHOUT_RUNTIME ?= 1
+include API.mk
 
 CC		= gcc
 TARGET		= libucuda
 CUDUMP		= cudump
 GDEVDIR		= /usr/local/gdev
 CFLAGS          = -O3 -Wall -I $(GDEVDIR)/include
-LDFLAGS = -L $(GDEVDIR)/lib64 -lgdev -lrt -Wl,-Bsymbolic
+LDFLAGS 	= -L $(GDEVDIR)/lib64 -lgdev -lrt -Wl,-Bsymbolic
 
-#OBJS 	= $(patsubst %.c,%.o,$(wildcard ./*.c))
-OBJS 	= init.o device.o version.o context.o module.o execution.o memory.o stream.o event.o gdev_cuda.o dummy.o extension/memmap.o extension/ipc.o
-CUDUMP_OBJS = cudump.o gdev_cuda.o
-OCELOT_OBJS = runtime/ocelot/*/*.o
-HYDRAZ_OBJS = runtime/hydrazine/*.o
-ZOMBIE  = $(wildcard ./*~)
+#OBJS 		= $(patsubst %.c,%.o,$(wildcard ./*.c))
+OBJS 		= init.o device.o version.o context.o module.o execution.o memory.o stream.o event.o gdev_cuda.o dummy.o extension/memmap.o extension/ipc.o
+CUDUMP_OBJS 	= cudump.o gdev_cuda.o
+OCELOT_OBJS 	= runtime/ocelot/*/*.o
+HYDRAZ_OBJS 	= runtime/hydrazine/*.o
+ZOMBIE  	= $(wildcard ./*~)
 
-ifeq ($(WITHOUT_RUNTIME),0)
+ifeq ($(CUDA_RUNTIME_API),1)
 	OBJS += $(OCELOT_OBJS) $(HYDRAZ_OBJS)
 	LDFLAGS += -lboost_thread -ldl
 endif
@@ -41,8 +38,7 @@ $(HYDRAZ_OBJS):
 install:
 	@if test ! -d $(DESTDIR)/$(GDEVDIR)/bin ; then mkdir -p $(DESTDIR)/$(GDEVDIR)/bin ; fi ;
 	@if test ! -d $(DESTDIR)/$(GDEVDIR)/lib64 ; then mkdir -p $(DESTDIR)/$(GDEVDIR)/lib64 ; fi ;
-	@if test ! -d $(DESTDIR)/$(GDEVDIR)/include ; then mkdir -p $(DESTDIR)/$(GDEVDIR)/include ; fi ;
-	cp -f ./$(CUDUMP) $(DESTDIR)/$(GDEVDIR)/bin/
+	@if test ! -d $(DESTDIR)/$(GDEVDIR)/include ; then mkdir -p $(DESTDIR)/$(GDEVDIR)/include ; fi ; cp -f ./$(CUDUMP) $(DESTDIR)/$(GDEVDIR)/bin/
 	cp -f ./$(TARGET).so.1.0.0 $(DESTDIR)/$(GDEVDIR)/lib64/
 	ln -sf $(GDEVDIR)/lib64/$(TARGET).so.1.0.0 $(DESTDIR)/$(GDEVDIR)/lib64/$(TARGET).so.1
 	ln -sf $(GDEVDIR)/lib64/$(TARGET).so.1 $(DESTDIR)/$(GDEVDIR)/lib64/$(TARGET).so

docs/README.cuda

@@ -0,0 +1,72 @@
+#####################################################################
+## Gdev: Open-Source GPGPU Runtime and Driver Software
+## 
+## README.gdev
+##
+## Copyright (C) Shinpei Kato
+##
+## Nagoya University
+## Parallel and Distributed Systems Lab (PDSL)
+## http://pdsl.jp
+##
+## University of California, Santa Cruz
+## Systems Research Lab (SRL)
+## http://systems.soe.ucsc.edu
+##
+## All Rights Reserved.
+######################################################################
+
+Follow the instruction below to use Gdev's CUDA. You may be required
+to install additional software packages depending on your environment.
+e.g., bison, flex, boost, boost-devel
+
+$(TOPDIR) represents your top working directory where you installed
+the Gdev repository.
+
+1. Gdev's CUDA installation
+
+Gdev currently supports a limited set of CUDA Driver/Runtime API. 
+It is defined as Micro CUDA (uCUDA) in Gdev.
+
+cd $(TOPDIR)/gdev/cuda
+mkdir build
+cd build
+#if you want to disable Runtime API
+../configure
+#else
+../configure
+#endif
+make
+sudo make install
+
+Gdev also supports CUDA in the operating system. You are required to
+install "kcuda" module to use this functionality.
+ -> See docs/README.gdev
+
+cd $(TOPDIR)/gdev/cuda
+mkdir kbuild
+cd kbuild
+../configure --target=kcuda
+make
+sudo make install
+
+2. CUDA Driver API test (user-space programs)
+
+cd $(TOPDIR)/test/cuda/user/madd
+make
+./user_test 256 # a[256] + b[256] = c[256]
+
+3. CUDA Driver API test (kernel-space programs)
+
+Note that you need 'kcuda' to be installed a priori if you want to
+run CUDA in the OS.
+
+cd $(TOPDIR)/test/cuda/kernel/memcpy
+make
+sudo insmod ./kernel_test.ko size=10000 # copy 0x10000 size
+
+NOTE: Please be careful when doing this test as it runs a program
+in module_init(). If you run a very long program as it is, you may
+crash your system. If you want to run a very long program, you must
+provide a proper module implementation, e.g., using kernel threads.
+

docs/README.gdev

@@ -22,9 +22,9 @@ your environment. $(TOPDIR) represents your top working directory.
 
 1. Download
 
-cd $(TOPDIR)
-git clone git://github.com/CS005/gdev.git
-git clone git://0x04.net/envytools.git
+  cd $(TOPDIR)
+  git clone git://github.com/CS005/gdev.git
+  git clone git://0x04.net/envytools.git
 
 2. envytools
 
@@ -36,93 +36,54 @@ while are not disclosed to the public so far. If you are interested
 in GPU system software development, this is what you should read!
 Please follow the instruction below to install envytools.
 
-cd $(TOPDIR)/envytools
-mkdir build
-cd build
-cmake .. # may require some packages on your distro
-make
-sudo make install # will install tools to /usr/local/{bin,lib}
+  cd $(TOPDIR)/envytools
+  mkdir build
+  cd build
+  cmake .. # may require some packages on your distro
+  make
+  sudo make install # will install tools to /usr/local/{bin,lib}
 
 3. Linux Kernel and Nouveau Device Driver
 
 Gdev disgregates from the device driver. You need to install a native
 GPU device driver to use Gdev. 
 
-cd $(TOPDIR)
-git clone --depth 1 git://anongit.freedesktop.org/nouveau/linux-2.6
-cd linux-2.6
-git remote add nouveau git://anongit.freedesktop.org/nouveau/linux-2.6
-git remote update
-git checkout -b nouveau-master nouveau/master
-patch -p1 < $(TOPDIR)/gdev/mod/linux/patches/gdev-nouveau-X.X.patch 
-make oldconfig
-make 
-sudo make modules_install install
-sudo shutdown -r now # will reboot your machine
-modprobe -r nouveau; modprobe nouveau modeset=1 noaccel=0
+  cd $(TOPDIR)
+  git clone --depth 1 git://anongit.freedesktop.org/nouveau/linux-2.6
+  cd linux-2.6
+  git remote add nouveau git://anongit.freedesktop.org/nouveau/linux-2.6
+  git remote update
+  git checkout -b nouveau-master nouveau/master
+  patch -p1 < $(TOPDIR)/gdev/mod/linux/patches/gdev-nouveau-X.X.patch 
+  make oldconfig
+  make 
+  sudo make modules_install install
+  sudo shutdown -r now # will reboot your machine
+  modprobe -r nouveau; modprobe nouveau modeset=1 noaccel=0
 
 4. Gdev Kernel Module
 
 This is a main module of Gdev providing OS runtime support.
 
-cd $(TOPDIR)/gdev/mod
-mkdir build
-cd build
-../configure
-make
-make install
+  cd $(TOPDIR)/gdev/mod
+  mkdir build
+  cd build
+  ../configure
+  make
+  make install
 
 5. Gdev Library
 
 Since this version of Gdev provides runtime support in the OS, this
 library is just a set of wrapper functions that call the Gdev module
 functions via ioctl.
 
-cd $(TOPDIR)/gdev/lib
-mkdir build
-cd build
-../configure
-make
-sudo make install
-export LD_LIBRARY_PATH="/usr/local/gdev/lib64:$LD_LIBRARY_PATH"
-export PATH="/usr/local/gdev/bin:$PATH"
-
-6. CUDA Runtime
-
-Gdev currently supports a limited set of CUDA Driver/Runtime API. 
-It is defined as Micro CUDA (uCUDA) in Gdev.
-
-cd $(TOPDIR)/gdev/cuda
-mkdir build
-cd build
-../configure
-make
-sudo make install
-
-Gdev also supports CUDA in the operating system. You are required to
-install "kcuda" module to use this functionality.
-
-cd $(TOPDIR)/gdev/cuda
-mkdir kbuild
-cd kbuild
-../configure --target=kcuda
-make
-sudo make install
-
-7. CUDA Driver API test (user-space programs)
-
-cd $(TOPDIR)/test/cuda/user/madd
-make
-./user_test 256 # a[256] + b[256] = c[256]
-
-8. CUDA Driver API test (kernel-space programs)
-
-cd $(TOPDIR)/test/cuda/kernel/memcpy
-make
-sudo insmod ./kernel_test.ko size=10000 # copy 0x10000 size
-
-NOTE: Please be careful when doing this test as it runs a program
-in module_init(). If you run a very long program as it is, you may
-crash your system. If you want to run a very long program, you must
-provide a proper module implementation, e.g., using kernel threads.
+  cd $(TOPDIR)/gdev/lib
+  mkdir build
+  cd build
+  ../configure
+  make
+  sudo make install
+  export LD_LIBRARY_PATH="/usr/local/gdev/lib64:$LD_LIBRARY_PATH"
+  export PATH="/usr/local/gdev/bin:$PATH"