Content for PMDK Summit Workshop

.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.jpg binary
+*.png binary
+*.gif binary
+*.pdf binary

.gitignore

@@ -0,0 +1,3 @@
+*.o
+core
+a.out

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020, pmemhackathon
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.txt

@@ -0,0 +1,95 @@
+This is the workshop repo.  If you're reading this through a webhackathon
+window or a workshop SSH session, then you're probably looking at your
+own private copy of the repo.
+
+This repo contains the slides and examples used during the virtual
+PMDK Summit workshop on June 25, 2020.
+
+It is provided permanently for reference on GitHub:
+
+	https://github.com/pmemhackathon/2020-06-25
+
+The PDF files at the top level contain slides:
+
+	slides.pdf         -- essential hackathon background
+	slides-llpl.pdf    -- llpl background
+	pmdk-overview.pdf  -- overview of Persistent Memory Development Kit
+	libpmemobj.pdf     -- overview of libpmemobj (C API)
+	libpmemobj-cpp.pdf -- overview of libpmemobj (C++ API)
+
+The examples are in examples/A, exmamples/B, etc.  Each example is meant
+to show a persistent memory programming concept, like transactions,
+support for a specific language, and API, etc.	The idea is to use
+the first few examples (A through C) to gain some essential background
+knowledge, then pick examples that are interesting to you.  Use them as a
+starting point, or a reference as you develop your own persistent memory
+aware programs.  There's a README.txt file in each example directory
+that explains what the example is all about.
+
+For more information, contact [email protected] or post your question
+to the "pmem" google group on groups.google.com.
+
+
+The containers used during the hackathons have all the necessary libraries
+installed in them.  You can access the container directly on DockerHub
+in the "pmemhackathon" area.  Here are the steps taken to install the
+libraries on a Linux machine.  These steps assume you have a machine
+with persistent memory installed and a recent Linux distro that supports
+persistent memory.
+
+We don't show the ipmctl and ndctl commands used to configure the
+persistent memory.  These examples assume persistent memory is available
+as a DAX mounted filesystem at "/pmem" on your system.  The following link
+provides more details about the steps to configure persistent memory:
+
+	https://docs.pmem.io/getting-started-guide
+
+#
+# To clone this repo, use something like the command below.
+# (Examples assume cloning in your home directory, hence the "cd")
+#
+
+cd
+git clone https://github.com/pmemhackathon/2020-06-25
+
+#
+# Some of the examples use PMDK.  Many distros include PMDK, but
+# it takes some time for the latest version to flow intro the distros
+# so here are the steps to build the latest source and install it in
+# the usual locations on Fedora 30.
+#
+
+cd
+# ubuntu: sudo apt-get install autoconf pkg-config libndctl-dev libdaxctl-dev
+sudo dnf install autoconf pkg-config ndctl-devel daxctl-devel
+git clone https://github.com/pmem/pmdk
+cd pmdk
+make
+sudo make install prefix=/usr
+
+#
+# Also install the C++ bindings for libpmemobj for the C++ example.
+#
+cd
+# ubuntu: sudo apt-get install cmake
+sudo dnf install cmake
+git clone https://github.com/pmem/libpmemobj-cpp
+cd libpmemobj-cpp
+mkdir build
+cd build
+cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
+make
+sudo make install
+
+#
+# Also install libpmemkv for the key-value example.
+#
+
+cd
+git clone https://github.com/pmem/pmemkv
+cd pmemkv
+mkdir build
+cd build
+cmake .. -DCMAKE_INSTALL_PREFIX=/usr
+make
+sudo make install

examples/A/.gitignore

@@ -0,0 +1 @@
+basic_mmap

examples/A/Makefile

@@ -0,0 +1,18 @@
+#
+# Makefile for basic_mmap example
+#
+PROGS = basic_mmap
+CFLAGS = -g -Wall -Werror -std=gnu99
+
+all: $(PROGS)
+
+basic_mmap: basic_mmap.o
+	$(CC) -o $@ $(CFLAGS) $^ $(LIBS)
+
+clean:
+	$(RM) *.o a.out core
+
+clobber: clean
+	$(RM) $(PROGS) basic_mmap
+
+.PHONY: all clean clobber

examples/A/README.txt

@@ -0,0 +1,33 @@
+Mapping Persistent Memory
+
+This example shows how persistent memory is mapped into an application
+using the mmap() system call on Linux.  This example is recommended
+reading for everyone since all the other examples in this hackathon
+build on this basic concept.
+
+If your C coding skills are rusty -- don't worry!  We tell you everything
+you need to know to get a basic mmap() program running.
+
+This is example consists of these files:
+
+basic_mmap.c -- the bare minimum mmap() code to map persistent memory
+Makefile     -- rules for building this example
+fs.out       -- sample output of "df" showing pmem on your system
+run.sh       -- one way to run this example to illustrate what it does
+windows.c    -- the windows version of basic_mmap.c, for reference
+
+To build this example run: make
+To run it and see what it illustrates run: ./run.sh
+
+Modifying the code and run steps is a great way to learn from this example.
+
+This example shows the bare-minumum, raw mmap() access using POSIX
+calls.  This includes using the POSIX msync() to flush stores to
+persistence.  This illustrates that POSIX interfaces work as expected,
+but this isn't the fastest way to use persistent memory.  See Example F
+for faster ways to flush changes from user space and details on libpmem
+which makes the low-level raw access to persistent memory easier.
+
+Now that you've seen the basic memory mapped of persistent memory,
+continue on to more examples to see more programmer-friendly APIs
+that build on this basic memory mapping mechanism.

examples/A/basic_mmap.c

@@ -0,0 +1,38 @@
+#include <sys/mman.h>
+#include <err.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+int
+main(int argc, char *argv[])
+{
+	int fd;
+	char *pmaddr;
+
+	if (argc != 2) {
+		fprintf(stderr, "Usage: %s filename\n", argv[0]);
+		exit(1);
+	}
+
+	if ((fd = open(argv[1], O_RDWR)) < 0)
+		err(1, "open: %s", argv[1]);
+
+	if ((pmaddr = (char *)mmap(NULL, 4096, PROT_READ|PROT_WRITE,
+					MAP_SHARED, fd, 0)) == MAP_FAILED)
+		err(1, "mmap: %s", argv[1]);
+
+	close(fd);
+
+	/* write to persistent memory... */
+	strcpy(pmaddr, "Hello, persistent memory!");
+
+	/* flush the changes... */
+	if (msync((void *)pmaddr, 4096, MS_SYNC) < 0)
+		err(1, "msync: %s", argv[1]);
+
+	printf("done.\n");
+	exit(0);
+}

examples/A/fs.out

@@ -0,0 +1,6 @@
+$ df -h /pmem
+Filesystem      Size  Used Avail Use% Mounted on
+/dev/pmem0      290G  872M  275G   1% /pmem
+
+$ mount | grep pmem
+/dev/pmem0 on /pmem type ext4 (rw,relatime,seclabel,dax)

examples/A/run.sh

@@ -0,0 +1,17 @@
+#!/bin/bash -ex
+#
+# shell commands to run this example
+#
+
+# create a one megabyte pmem file full of zeros
+rm -f /pmem/myfile
+truncate --size=1M /pmem/myfile
+
+# dump the file to show initial contents
+hexdump -C /pmem/myfile
+
+# run the example program
+./basic_mmap /pmem/myfile
+
+# dump the file to show new contents
+hexdump -C /pmem/myfile

examples/A/windows.c

@@ -0,0 +1,95 @@
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <Windows.h>
+
+int
+main(int argc, char *argv[])
+{
+	if (argc != 2) {
+		fprintf(stderr, "Usage: %s filename\n", argv[0]);
+		exit(1);
+	}
+
+	/* Create the file or open if the file already exists */
+	HANDLE fh = CreateFile(argv[1],
+		GENERIC_READ|GENERIC_WRITE,
+		0,
+		NULL,
+		OPEN_EXISTING,
+		FILE_ATTRIBUTE_NORMAL,
+		NULL);
+
+	if (fh == INVALID_HANDLE_VALUE) {
+		fprintf(stderr, "CreateFile, gle: 0x%08x", GetLastError());
+		exit(1);
+	}
+
+	/* Get the file length for use when memory mapping later */
+	DWORD filelen = GetFileSize(fh, NULL);
+	if (filelen == 0) {
+		fprintf(stderr, "GetFileSize, gle: 0x%08x", GetLastError());
+		exit(1);
+	}
+
+	/* Create a file mapping object */
+	HANDLE fmh = CreateFileMapping(fh,
+		NULL, /* security attributes */
+		PAGE_READWRITE,
+		0,
+		0,
+		NULL);
+
+	if (fmh == NULL) {
+		fprintf(stderr, "CreateFileMapping, gle: 0x%08x",
+			GetLastError());
+		exit(1);
+	}
+
+	/* Map into our address space and get a pointer to the beginning */
+	char *pmaddr = (char *)MapViewOfFileEx(fmh,
+		FILE_MAP_ALL_ACCESS,
+		0,
+		0,
+		filelen,
+		NULL); /* hint address */
+
+	if (pmaddr == NULL) {
+		fprintf(stderr, "MapViewOfFileEx, gle: 0x%08x",
+			GetLastError());
+		exit(1);
+	}
+
+	/* write to persistent memory... */
+	strcpy(pmaddr, "Hello, persistent memory!");
+
+	/* Flush this page with length rounded up to 4k page size */
+	if (FlushViewOfFile(pmaddr, 4096) == FALSE) {
+		fprintf(stderr, "FlushViewOfFile, gle: 0x%08x",
+			GetLastError());
+		exit(1);
+	}
+
+	/* Now flush the complete file to backing storage */
+	if (FlushFileBuffers(fh) == FALSE) {
+		fprintf(stderr, "FlushFileBuffers, gle: 0x%08x",
+			GetLastError());
+		exit(1);
+	}
+
+	/* Explicitly unmap before closing the file */
+	if (UnmapViewOfFile(pmaddr) == FALSE) {
+		fprintf(stderr, "UnmapViewOfFile, gle: 0x%08x",
+			GetLastError());
+		exit(1);
+	}
+
+	CloseHandle(fmh);
+	CloseHandle(fh);
+
+	printf("done.\n");
+	exit(0);
+}

examples/B/.gitignore

@@ -0,0 +1 @@
+pmemkv

examples/B/Makefile

@@ -0,0 +1,19 @@
+#
+# Makefile for simple pmemkv C++ example
+#
+OBJS = pmemkv.o kvinit.o
+CXXFLAGS = -std=c++17
+LIBS = -lpmemkv
+
+all: pmemkv
+
+pmemkv: $(OBJS)
+	$(CXX) $(CXXFLAGS) -o $@ $(OBJS) $(LIBS)
+
+clean:
+	$(RM) *.o core a.out
+
+clobber: clean
+	$(RM) pmemkv
+
+.PHONY: all clean clobber