add disk documentation

doc/doxygen/Makefile.am

@@ -35,6 +35,7 @@ chapters =	\
 	chapters/performance_feedback.doxy \
 	chapters/scheduling_context_hypervisor.doxy \
 	chapters/scheduling_contexts.doxy \
+	chapters/out_of_core.doxy \
 	chapters/socl_opencl_extensions.doxy \
 	chapters/tips_and_tricks.doxy \
 	chapters/environment_variables.doxy \
@@ -58,6 +59,7 @@ chapters =	\
 	chapters/code/vector_scal_cuda.cu \
 	chapters/code/vector_scal_opencl.c \
 	chapters/code/vector_scal_opencl_codelet.cl \
+	chapters/code/disk_copy.c \
 	chapters/api/codelet_and_tasks.doxy \
 	chapters/api/cuda_extensions.doxy \
 	chapters/api/data_interfaces.doxy \
@@ -145,6 +147,7 @@ dox_inputs = $(DOX_CONFIG) 				\
 	$(top_srcdir)/include/starpu.h			\
 	$(top_srcdir)/include/starpu_data_filters.h	\
 	$(top_srcdir)/include/starpu_data_interfaces.h	\
+	$(top_srcdir)/include/starpu_disk.h		\
 	$(top_srcdir)/include/starpu_worker.h		\
 	$(top_srcdir)/include/starpu_task.h		\
 	$(top_srcdir)/include/starpu_task_bundle.h	\

doc/doxygen/chapters/code/disk_copy.c

@@ -0,0 +1,137 @@
+/* StarPU --- Runtime system for heterogeneous multicore architectures.
+ *
+ * Copyright (C) 2013 Corentin Salingue
+ *
+ * StarPU is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2.1 of the License, or (at
+ * your option) any later version.
+ *
+ * StarPU is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ * See the GNU Lesser General Public License in COPYING.LGPL for more details.
+ */
+
+//! [To be included]
+
+/* Try to write into disk memory
+ * Use mechanism to push datas from main ram to disk ram
+ */
+
+#include <starpu.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <math.h>
+
+/* size of one vector */
+#define	NX	(30*1000000/sizeof(double))
+#define FPRINTF(ofile, fmt, ...) do { if (!getenv("STARPU_SSILENT")) {fprintf(ofile, fmt, ## __VA_ARGS__); }} while(0)
+
+
+int main(int argc, char **argv)
+{
+	double * A,*B,*C,*D,*E,*F;
+
+	/* limit main ram to force to push in disk */
+	putenv("STARPU_LIMIT_CPU_MEM=160");
+
+	/* Initialize StarPU with default configuration */
+	int ret = starpu_init(NULL);
+
+	if (ret == -ENODEV) goto enodev;
+
+	/* register a disk */
+	int new_dd = starpu_disk_register(&starpu_disk_stdio_ops, (void *) "/tmp/", 1024*1024*200);
+	/* can't write on /tmp/ */
+	if (new_dd == -ENOENT) goto enoent;
+	
+	unsigned dd = (unsigned) new_dd;
+
+	/* allocate two memory spaces */
+	starpu_malloc_flags((void **)&A, NX*sizeof(double), STARPU_MALLOC_COUNT);
+	starpu_malloc_flags((void **)&F, NX*sizeof(double), STARPU_MALLOC_COUNT);
+
+	FPRINTF(stderr, "TEST DISK MEMORY \n");
+
+	unsigned int j;
+	/* initialization with bad values */
+	for(j = 0; j < NX; ++j)
+	{
+		A[j] = j;
+		F[j] = -j;
+	}
+
+	/* Tell StaPU to associate the "vector" vector with the "vector_handle"
+	 * identifier. When a task needs to access a piece of data, it should
+	 * refer to the handle that is associated to it.
+	 * In the case of the "vector" data interface:
+	 *  - the first argument of the registration method is a pointer to the
+	 *    handle that should describe the data
+	 *  - the second argument is the memory node where the data (ie. "vector")
+	 *    resides initially: 0 stands for an address in main memory, as
+	 *    opposed to an adress on a GPU for instance.
+	 *  - the third argument is the adress of the vector in RAM
+	 *  - the fourth argument is the number of elements in the vector
+	 *  - the fifth argument is the size of each element.
+	 */
+	starpu_data_handle_t vector_handleA, vector_handleB, vector_handleC, vector_handleD, vector_handleE, vector_handleF;
+
+	/* register vector in starpu */
+	starpu_vector_data_register(&vector_handleA, 0, (uintptr_t)A, NX, sizeof(double));
+	starpu_vector_data_register(&vector_handleB, -1, (uintptr_t) NULL, NX, sizeof(double));	
+	starpu_vector_data_register(&vector_handleC, -1, (uintptr_t) NULL, NX, sizeof(double));
+	starpu_vector_data_register(&vector_handleD, -1, (uintptr_t) NULL, NX, sizeof(double));
+	starpu_vector_data_register(&vector_handleE, -1, (uintptr_t) NULL, NX, sizeof(double));
+	starpu_vector_data_register(&vector_handleF, 0, (uintptr_t)F, NX, sizeof(double));
+
+	/* copy vector A->B, B->C... */
+	starpu_data_cpy(vector_handleB, vector_handleA, 0, NULL, NULL);
+	starpu_data_cpy(vector_handleC, vector_handleB, 0, NULL, NULL);
+	starpu_data_cpy(vector_handleD, vector_handleC, 0, NULL, NULL);
+	starpu_data_cpy(vector_handleE, vector_handleD, 0, NULL, NULL);
+	starpu_data_cpy(vector_handleF, vector_handleE, 0, NULL, NULL);
+
+	/* StarPU does not need to manipulate the array anymore so we can stop
+ 	 * monitoring it */
+
+	/* free them */
+	starpu_data_unregister(vector_handleA);
+	starpu_data_unregister(vector_handleB);
+	starpu_data_unregister(vector_handleC);
+	starpu_data_unregister(vector_handleD);
+	starpu_data_unregister(vector_handleE);
+	starpu_data_unregister(vector_handleF);
+
+	starpu_disk_unregister(dd);
+
+	/* check if computation is correct */
+	int try = 1;
+	for (j = 0; j < NX; ++j)
+		if (A[j] != F[j])
+		{
+			printf("Fail A %f != F %f \n", A[j], F[j]);
+			try = 0;
+		}
+
+	/* free last vectors */
+	starpu_free_flags(A, NX*sizeof(double), STARPU_MALLOC_COUNT);
+	starpu_free_flags(F, NX*sizeof(double), STARPU_MALLOC_COUNT);
+
+	/* terminate StarPU, no task can be submitted after */
+	starpu_shutdown();
+
+	if(try)
+		FPRINTF(stderr, "TEST SUCCESS\n");
+	else
+		FPRINTF(stderr, "TEST FAIL\n");
+	return (try ? EXIT_SUCCESS : EXIT_FAILURE);
+
+enodev:
+	return 77;
+enoent:
+	return 77;
+}
+
+//! [To be included]

doc/doxygen/chapters/introduction.doxy

@@ -213,6 +213,7 @@ The documentation chapters include
 <li> \ref HowToOptimizePerformanceWithStarPU
 <li> \ref PerformanceFeedback
 <li> \ref TipsAndTricksToKnowAbout
+<li> \ref OutOfCore
 <li> \ref MPISupport
 <li> \ref FFTSupport
 <li> \ref MICSCCSupport

doc/doxygen/chapters/out_of_core.doxy

@@ -0,0 +1,47 @@
+/*
+ * This file is part of the StarPU Handbook.
+ * Copyright (C) 2013 Corentin Salingue
+ * See the file version.doxy for copying conditions.
+ */
+
+/*! \page OutOfCore Out Of Core
+
+\section Introduction Introduction
+
+When you are using Starpu, you can need more memory than main memory (RAM) is able to receive datas. This part describes the method to add a new memory node on a disk and to use it.
+
+\section UseANewDiskMemory Use a new disk memory
+
+To use a disk memory node, you have to register it with this function:
+
+\code{.c}
+	int new_dd = starpu_disk_register(&starpu_disk_stdio_ops, (void *) "/tmp/", 1024*1024*200);
+\endcode
+
+Here, we use the library called stdio to realize the read/write process. This structure must have a path to make the work and at the end, we give it the maximum size the software can use on the disk. <br />
+Don't forget to check if the result is correct !<br />
+When the register function is called, we benchmark it. You have to know that it can take a few time.
+
+<strong>Warning: the size must be at least 1 MB ! </strong> 
+
+To write or read on the node, you can use the \ref API_Standard_Memory_Library or the \ref API_Data_Interfaces .
+
+At the end, you have to unregister your disk memory:
+
+\code{.c}
+	starpu_disk_unregister(dd);
+\endcode
+
+\section DiskFunctions Disk functions
+
+You have various ways to use a disk memory node. You have, for instance, the starpu_disk_stdio_ops.
+All structures are in... TODO
+
+\section ExampleDiskCopy Example: disk_copy
+
+
+
+\snippet disk_copy.c To be included
+
+
+*/

doc/doxygen/refman.tex

@@ -129,6 +129,13 @@ Documentation License”.
 \hypertarget{TipsAndTricksToKnowAbout}{}
 \input{TipsAndTricksToKnowAbout}
 
+\chapter{Out Of Core}
+\label{OutOfCore}
+\hypertarget{OutOfCore}{}
+\input{OutOfCore}
+
+
+
 \chapter{MPI Support}
 \label{MPISupport}
 \hypertarget{MPISupport}{}