Editing Development

[[Category:O3X development]]
You should also familiarize yourself with the [[Project_roadmap|project roadmap]] so that you can put the technical details here in context.

== Kernel ==

=== Debugging with GDB ===

Dealing with [[Panic|panics]].

Apple's documentation: https://developer.apple.com/library/mac/documentation/Darwin/Conceptual/KEXTConcept/KEXTConceptDebugger/debug_tutorial.html

Boot target VM with

<syntaxhighlight lang="bash">
$ sudo nvram boot-args="-v keepsyms=1 debug=0x144"
</syntaxhighlight>

Make it panic.

On your development machine, you will need the Kernel Debug Kit. Download it from Apple [https://developer.apple.com/downloads/index.action?q=Kernel%20Debug%20Kit here].

<syntaxhighlight lang="text">
$ gdb /Volumes/Kernelit/mach_kernel
(gdb) source /Volumes/KernelDebugKit/kgmacros
(gdb) target remote-kdp
(gdb) kdp-reattach  192.168.30.133   # obviously use the IP of your target / crashed VM
(gdb) showallkmods
</syntaxhighlight>

Find the addresses for ZFS and SPL modules.

<code>^Z</code> to suspend gdb, or, use another terminal

<syntaxhighlight lang="bash">
^Z
$ sudo kextutil -s /tmp -n \
-k /Volumes/KernelDebugKit/mach_kernel \
-e -r /Volumes/KernelDebugKit module/zfs/zfs.kext/ \
../spl/module/spl/spl.kext/
</syntaxhighlight>

Then resume gdb, or go back to gdb terminal.
<syntaxhighlight lang="text">
$ fg
(gdb) set kext-symbol-file-path /tmp
(gdb) add-kext /tmp/spl.kext 
(gdb) add-kext /tmp/zfs.kext
(gdb) bt
</syntaxhighlight>

=== Debugging with LLDB ===

<syntaxhighlight lang="bash">
$ echo "settings set target.load-script-from-symbol-file true" >> ~/.lldbinit
$ lldb /Volumes/KernelDebugKit/mach_kernel     # From Yosemite, "/Library/Developer/KDKs/KDK_10.10_14B25.kdk/System/Library/Kernels/kernel" 
(lldb) kdp-remote  192.168.30.146
(lldb) showallkmods
(lldb) addkext -F /tmp/spl.kext/Contents/MacOS/spl 0xffffff7f8ebb0000   (Address from showallkmods)
(lldb) addkext -F /tmp/zfs.kext/Contents/MacOS/zfs 0xffffff7f8ebbf000
</syntaxhighlight>

addkext seems broken, now use:

 (lldb) target modules add ../spl/module/spl/spl.kext/Contents/MacOS/spl
 (lldb) target modules load --file spl --slide 0xffffff7f91e63000

Then follow the guide for GDB above.

=== Non-panic ===

If you prefer to work in GDB, you can always panic a kernel with

<syntaxhighlight lang="bash">
$ sudo dtrace -w -n "BEGIN{ panic();}"
</syntaxhighlight>

But this was revealing:

<syntaxhighlight lang="bash">
$ sudo /usr/libexec/stackshot -i -f /tmp/stackshot.log 
$ sudo symstacks.rb -f /tmp/stackshot.log -s -w /tmp/trace.txt
$ less /tmp/trace.txt
</syntaxhighlight>

Note that my hang is here:

<syntaxhighlight lang="text">
PID: 156
    Process: zpool
    Thread ID: 0x4e2
    Thread state: 0x9 == TH_WAIT |TH_UNINT 
    Thread wait_event: 0xffffff8006608a6c
    Kernel stack: 
    machine_switch_context (in mach_kernel) + 366 (0xffffff80002b3d3e)
      0xffffff800022e711 (in mach_kernel) + 1281 (0xffffff800022e711)
        thread_block_reason (in mach_kernel) + 300 (0xffffff800022d9dc)
          lck_mtx_sleep (in mach_kernel) + 78 (0xffffff80002265ce)
            0xffffff8000569ef6 (in mach_kernel) + 246 (0xffffff8000569ef6)
              msleep (in mach_kernel) + 116 (0xffffff800056a2e4)
                0xffffff7f80e52a76 (0xffffff7f80e52a76)
                  0xffffff7f80e53fae (0xffffff7f80e53fae)
                    0xffffff7f80e54173 (0xffffff7f80e54173)
                      0xffffff7f80f1a870 (0xffffff7f80f1a870)
                        0xffffff7f80f2bb4e (0xffffff7f80f2bb4e)
                          0xffffff7f80f1a9b7 (0xffffff7f80f1a9b7)
                            0xffffff7f80f1b65f (0xffffff7f80f1b65f)
                              0xffffff7f80f042ee (0xffffff7f80f042ee)
                                0xffffff7f80f45c5b (0xffffff7f80f45c5b)
                                  0xffffff7f80f4ce92 (0xffffff7f80f4ce92)
                                    spec_ioctl (in mach_kernel) + 157 (0xffffff8000320bfd)
                                      VNOP_IOCTL (in mach_kernel) + 244 (0xffffff8000311e84)
</syntaxhighlight>

It is a shame that it only shows the kernel symbols, and not inside SPL and ZFS, but we can ask it to load another sym file. (Alas, it cannot handle multiple symbols files. Fix this Apple.)

<syntaxhighlight lang="bash">
$ sudo kextstat #grab the addresses of SPL and ZFS again
$ sudo kextutil -s /tmp -n -k /Volumes/KernelDebugKit/mach_kernel -e -r /Volumes/KernelDebugKit module/zfs/zfs.kext/ ../spl/module/spl/spl.kext/ 

symstacks.rb -f /tmp/stackshot.log -s -k /tmp/net.lundman.spl.sym
              0xffffff800056a2e4 (0xffffff800056a2e4)
                spl_cv_wait (in net.lundman.spl.sym) + 54 (0xffffff7f80e52a76)
                  taskq_wait (in net.lundman.spl.sym) + 78 (0xffffff7f80e53fae)
                    taskq_destroy (in net.lundman.spl.sym) + 35 (0xffffff7f80e54173)
                      0xffffff7f80f1a870 (0xffffff7f80f1a870)

symstacks.rb -f /tmp/stackshot.log -s -k /tmp/net.lundman.zfs.sym
                    0xffffff7f80e54173 (0xffffff7f80e54173)
                      vdev_open_children (in net.lundman.zfs.sym) + 336 (0xffffff7f80f1a870)
                        vdev_root_open (in net.lundman.zfs.sym) + 94 (0xffffff7f80f2bb4e)
                          vdev_open (in net.lundman.zfs.sym) + 311 (0xffffff7f80f1a9b7)
                            vdev_create (in net.lundman.zfs.sym) + 31 (0xffffff7f80f1b65f)
                              spa_create (in net.lundman.zfs.sym) + 878 (0xffffff7f80f042ee)
</syntaxhighlight>

Voilà!

=== Memory leaks ===

(Note that this section is only relevant to old O3X implementation that used the zones allocator - we now use our own kmem allocator).

In some cases, you may suspect memory issues, for instance if you saw the following panic:

<syntaxhighlight lang="text">
panic(cpu 1 caller 0xffffff80002438d8): "zalloc: \"kalloc.1024\" (100535 elements) retry fail 3, kfree_nop_count: 0"@/SourceCache/xnu/xnu-2050.7.9/osfmk/kern/zalloc.c:1826
</syntaxhighlight>

To debug this, you can attach GDB and use the zprint command:

<syntaxhighlight lang="text">
(gdb) zprint
ZONE                   COUNT   TOT_SZ   MAX_SZ   ELT_SZ ALLOC_SZ         TOT_ALLOC         TOT_FREE NAME
0xffffff8002a89250   1620133  18c1000  22a3599       16     1000         125203838        123583705 kalloc.16 CX
0xffffff8006306c50    110335   35f000   4ce300       32     1000          13634985         13524650 kalloc.32 CX
0xffffff8006306a00    133584   82a000   e6a900       64     1000          26510120         26376536 kalloc.64 CX
0xffffff80063067b0    610090  4a84000  614f4c0      128     1000          50524515         49914425 kalloc.128 CX
0xffffff8006306560   1070398 121a2000 1b5e4d60      256     1000          72534632         71464234 kalloc.256 CX
0xffffff8006306310    399302  d423000  daf26b0      512     1000          39231204         38831902 kalloc.512 CX
0xffffff80063060c0    100404  6231000  c29e980     1024     1000          22949693         22849289 kalloc.1024 CX
0xffffff8006305e70       292    9a000   200000     2048     1000          77633725         77633433 kalloc.2048 CX
</syntaxhighlight>

In this case, kalloc.256 is suspect.

Reboot kernel with zlog=kalloc.256 on the command line, then we can use

<syntaxhighlight lang="text">
(gdb) findoldest                                                                
oldest record is at log index 393:

--------------- ALLOC  0xffffff803276ec00 : index 393  :  ztime 21643824 -------------
0xffffff800024352e <zalloc_canblock+78>:        mov    %eax,-0xcc(%rbp)
0xffffff80002245bd <get_zone_search+23>:        jmpq   0xffffff80002246d8 <KALLOC_ZINFO_SALLOC+35>
0xffffff8000224c39 <OSMalloc+89>:       mov    %rax,-0x18(%rbp)
0xffffff7f80e847df <zfs_kmem_alloc+15>: mov    %rax,%r15
0xffffff7f80e90649 <arc_buf_alloc+41>:  mov    %rax,-0x28(%rbp)
and indeed, list any index

(gdb) zstack 394

--------------- ALLOC  0xffffff8032d60700 : index 394  :  ztime 21648810 -------------
0xffffff800024352e <zalloc_canblock+78>:        mov    %eax,-0xcc(%rbp)
0xffffff80002245bd <get_zone_search+23>:        jmpq   0xffffff80002246d8 <KALLOC_ZINFO_SALLOC+35>
0xffffff8000224c39 <OSMalloc+89>:       mov    %rax,-0x18(%rbp)
0xffffff7f80e847df <zfs_kmem_alloc+15>: mov    %rax,%r15
0xffffff7f80e90649 <arc_buf_alloc+41>:  mov    %rax,-0x28(%rbp)
How many times was zfs_kmem_alloc involved in the leaked allocs?

(gdb) countpcs 0xffffff7f80e847df
occurred 3999 times in log (100% of records)
</syntaxhighlight>

At least we know it is our fault.

How many times is it arc_buf_alloc?

<syntaxhighlight lang="text">
(gdb) countpcs 0xffffff7f80e90649
occurred 2390 times in log (59% of records)
</syntaxhighlight>

=== Memory Architecture ===

ZFS is designed to aggressively cache filesystem data in main memory. The result of this caching can be significant filesystem performance improvement.

Selection of an allocator has been very challenging on OS X. In the last year we have evolved from:
* Direct call to OSMalloc - a very low level allocator in the kernel - rejected because of slow performance and because the minimum allocation size is one page (4k)
* Direct call to zalloc - the OS X zones allocator - rejected because only 25% of the machines memory can be accessed (50% under some circumstances), and because the result of exceeding this limit is a kernel panic with no other feedback mechanisms available.
* Direct call to bmalloc - bmalloc was a home grown slice allocator that allocated slices of memory from the kernel page allocator, and subdivided into smaller units of allocation to use by ZFS. This was quite successful but very space inefficient. Was used in O3X 1.2.7 and 1.3.0. At this stage we had no real response to memory pressure in the machine, so the total memory allocation to O3X was kept to 50% of the machine.
* Implementation of kmem and vmem allocators using code from Illumos. Provision of a memory pressure monitor mechanism - we are now able to allocate most of the machines memory to ZFS, and scale that back when the machine experiences memory pressure.

O3X has the Solaris Porting Layer (SPL). The SPL has long since provided the Illumos kmem.h API for use by ZFS. In O3X releases up to 1.3.0 the kmem implementation has been a stub that passes allocation requests to an underlying allocator. In O3X 1.3.0 we were still missing some key behaviours in the allocator - efficient lifecycle control of objects, and an effective response to memory pressure in the machine, and the allocator was not very space efficient because of metadata overheads in bmalloc. We were also not convinced that bmalloc represented the state of the art.

Our strategy was to determine how much of the Illumos allocator could be implemented on OS X. After a series of experiments where we implemented significant portions of the kmem code from illumos on top of bmalloc, we had learned enough to take the final step of essentially copying the entire kmem/vmem allocator stack from Illumos. Some portions of the kmem code have been disabled in kmem such as logging, and hot swap CPU support have been disabled due to architectural differences between OS X and Illumos.

By default kmem/vmem require a certain level of performance from the OS page allocator. It is easy to overwhelm the OS X page allocator. We tuned vmem to use a KMEM_QUANTUM of 512Kb chunks of memory from the page allocator rather than the smaller allocations that vmem prefers. This is less than ideal as it reduces the ability for vmem to smoothly release memory to the page allocator when the machine is under pressure. While we have an adequately performing solution now, there will always be a tension between our allocator and OS X itself. OS X only provides minimal mechanisms to observe and respond to memory pressure in the machine, so we are somewhat limited in what can be achieved in this regard.  

As of 1.5.2 we switched the KMEM_QUANTUM to 128k based on feedback from a user. It was believed at the time that some tuning in the allocator had enabled this improvement. Surprisingly this has lead to reduced performance and some stuttering/beachballing on various machines. There is no apparent predictability to which class of machine will suffer from this, i.e. newer fast machines are apparently susceptible to this over the reference machine (a mac mini) around which the 128k opinion was formed. It also seems that allowing wired memory to become very large can (does?) result in performance problems.

There has been further investigation into exactly why we need to gain large blocks of memory from the page allocator, when the kernels own level 2 allocator does not. It turns out that vmem does not return memory to the page allocator in general on Illumos as it is the system wide allocator. In our case we do have to release memory back to the OS under pressure situations. To achieve this we need to configure vmem to act more like libumem does in user space, that is to know that it has an upstream allocator that must be cooperated with. Furthermore it turns out that the "quantum caches" in the heap vmem arena were not active, due to the vmem arena chaining not working at all (this is a bug). While this bug remains, the size of KMEM_QUANTUM is a proxy for frequency of memory allocations/frees via the kernel page allocator. High frequency is not good - the page allocator is slow and heavily impacts operation of the machine (TLB shootdowns etc).

References:

Jeff Bonwicks paper - kmem and vmem implement this design. https://www.usenix.org/legacy/event/usenix01/full_papers/bonwick/bonwick_html/

=== Detecting memory handling errors ===

The kmem allocator has an internal diagnostic mode. In diagnostic mode the allocator instruments heap memory with various features and markers as it is allocated and released by application code. These markers are checked as the program runs, and can determine when an application has exhibited one or more of a set of common memory handling errors. The debugging mode is disabled by default as it carries a significant performance penalty.

The memory handling errors that can be detected include:
* Modify after free
* Write past end of buffer
* Free of memory not managed by kmem
* Double free of memory
* Various other corruptions
* Freed size != allocated size
* Freed address != allocated address

Debug mode is enabled by compiling with the preprocessor symbol DEBUG defined. At a minimum spl-kmem.c and spl-osx.c need to see this define for the debugging features to be completely enabled.

In debugging mode you must choose whether kmem will log the fault and then panic, or just log. If you elect to panic, there is a very high chance that the full log message will not be stored in system.log before the OS halts, and you will have to connect to the machine with lldb and use the "systemlog" command to view the diagnostic message. If you elect to not panic, the program will continue to run despite the memory corruption, with undefined consequences. In spl-kmem.c set kmem_panic=0 to log, kmem_panic=1 to log+panic.

Example:

I modified spl_start() to include the following:

   { 
       ...
       int *p;
       for(int i=0; i<20;i++) {
          p = (int*)spl_kmem_alloc(1024);
          spl_kmem_free(p);
          *p = 0;
       }
   }

With the debug mode enabled the following was logged:
 
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: kernel memory allocator: buffer modified after being freed
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: modification occurred at offset 0x0 (0xdeadbeefdeadbeef replaced by 0xdeadbeef00000000)
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: buffer=0xffffff887a87d980  bufctl=0xffffff887a7ad840  cache: kmem_alloc_1152
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: previous transaction on buffer 0xffffff887a87d980:
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: thread=0  time=T-0.000001383  slab=0xffffff887a5ffe68  cache: kmem_alloc_1152
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: net.lundman.spl : _kmem_cache_free_debug + 0x227
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: net.lundman.spl : _kmem_cache_free + 0x173
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: net.lundman.spl : _zfs_kmem_free + 0x2c4
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: net.lundman.spl : _spl_start + 0x2bb
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZN6OSKext5startEb + 0x40b
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZN6OSKext4loadEhhP7OSArray + 0xdd
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZN6OSKext4loadEhhP7OSArray + 0x3e1
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZN6OSKext22loadKextWithIdentifierEP8OSStringbbhhP7OSArray + 0xf2
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZNK11IOCatalogue14isModuleLoadedEP12OSDictionary + 0xe0
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZN9IOService15probeCandidatesEP12OSOrderedSet + 0x2c4
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZN9IOService14doServiceMatchEj + 0x22a
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : __ZN15_IOConfigThread4mainEPvi + 0x13c
   14/08/2015 5:09:47.000 PM kernel[0]: SPL: mach_kernel : _call_continuation + 0x17

You can clearly see the kind of memory corruption, the actual corrupted data, which kmem cache was involved, the relative time that the last action occurred, and the stack trace for the last action (which was a call to zfs_kmem_free()) - indicating that spl_start() was implicated in the fault. This event would have been logged the next time the modified after free buffer was allocated.

=== Compiling to lower OSX versions ===

If you wish to compile O3X to a specific OSX version, in this case, compiling for 10.9 on a 10.10

SPL:
 ./configure --with-kernel-headers=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/System/Library/Frameworks/Kernel.framework/ CFLAGS=-mmacosx-version-min=10.9

ZFS:
 ./configure --with-kernelsrc=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/System/Library/Frameworks/Kernel.framework/ CFLAGS=-mmacosx-version-min=10.9

== Flamegraphs ==

Huge thanks to [http://www.brendangregg.com/FlameGraphs/cpuflamegraphs.html BrendanGregg] for so much of the dtrace magic.

dtrace the kernel while running a command:

<syntaxhighlight lang="bash">
$ sudo dtrace -x stackframes=100 -n 'profile-997 /arg0/ {
    @[stack()] = count(); } tick-60s { exit(0); }' -o out.stacks
</syntaxhighlight>

It will run for 60 seconds.

Convert it to a flamegraph:

<syntaxhighlight lang="bash">
$ ./stackcollapse.pl out.stacks > out.folded
$ ./flamegraph.pl out.folded > out.svg
</syntaxhighlight>


This is <code>rsync -a /usr/ /BOOM/deletea/</code> running:

[[File:rsyncflamegraph.svg|thumb|rsync flamegraph]]


Or running '''Bonnie++''' in various stages:

<gallery mode="packed-hover">
File:create.svg|Create files in sequential order|alt=[[File:create.svg]]
File:stat.svg|Stat files in sequential order|alt=Stat files in sequential order
File:delete.svg|Delete files in sequential order|alt=Delete files in sequential order
</gallery>


[[File:VX_create.svg|thumb|Create files in sequential order]]

<br>

[[File:iozone.svg|thumb|IOzone flamegraph]]

[[File:iozoneX.svg|thumb|IOzone flamegraph (untrimmed)]]

<br>


------

== Unit Test ==

We have created an initial port of the standard ZFS test suite. It consists of a collection of scripts and miscellaneous utility programs and exercise the complete breadth and depth of the ZFS filesystem. 

The tests are best run in a virtual machine with a baseline configured setup that has been captured in a snapshot. The tests should be run on the VM, and then due to the destructive nature of the tests, the VM should be reverted to the snapshot in preparation for future test runs.  The tests take 2-4 hours to run depending on hardware setup.

=== Setup ===

The user zfs-test needs to be able to run sudo without issuing a password. Add the following to sudoers:

   zfs-tests ALL=(ALL) NOPASSWD: ALL

The sudo root environment must be configured to pass certain enviroment variables from zfs-test through to the root environment. Add the following to sudoers:

   Defaults env_keep += "__ZFS_MAIN_MOUNTPOINT_DIR"

Modify /etc/bashrc to contain

   export __ZFS_MAIN_MOUNTPOINT_DIR="/"

If your development directory is ~you/Developer, clone zfs, spl and bfs-tests into that directory

   # cd ~you/Developer
   # git clone git@github.com:openzfsonosx/zfs-test.git
   # git clone git@github.com:openzfsonosx/zfs.git
   # git clone git@github.com:openzfsonosx/spl.git

Build the ZFS is built using the building from source instructions.

Ensure that /var/tmp has approximately 100GB of free space.

Create theee virtual hard drives of 10-20GB capacity each.

=== Run Test Suite ===

Setup the tests to run

   # cd ~you/Developer/zfs-tests
   # ./autogen.sh
   # ./configure CC=clang CXX=clang++

Edit the generated Makefile, change the recipe for the test_hw target such that your three virtual disks are listed in the DISKS environment variable.

   test_hw: test_verify test/zfs-tests/cmd
           @KEEP="`zpool list -H -oname`" \
            STF_TOOLS=$(abs_top_srcdir)/test/test-runner/stf \
            STF_SUITE=$(abs_top_srcdir)/test/zfs-tests \
            DISKS="/dev/disk3 /dev/disk1 /dev/disk2" \
            su zfs-tests -c "ksh $(abs_top_srcdir)/test/zfs-tests/cmd/scripts/zfstest.ksh $$RUNFILE"

Run the test suite

   sudo make test_hw

=== Results ===

The test suite write summary pass/fail information to the console as they run. On completion of the test run summary statistics are written to the console.

Test log files are stored in /var/tmp/<testrun> (where test run is a unique looking number). In that directory there is a log file, and a directory per test. Within the test directory is detailed log information regarding the specific test.

== Iozone ==


Quick peek at how they compare, just to see how much we should improve it by.

HFS+ and ZFS were created on the same virtual disk in VMware. Of course, this is not ideal testing specs, but should serve as an indicator. 

The pool was created with

<syntaxhighlight lang="bash">
$ sudo zpool create -f -o ashift=12 \
-O atime=off \
-O casesensitivity=insensitive \
-O normalization=formD \
BOOM /dev/disk1
</syntaxhighlight>

and the HFS+ file system was created with the standard OS X Disk Utility.app, with everything default (journaled, case-insensitive).

'''Iozone''' was run with standard automode:

<syntaxhighlight lang="bash">
sudo iozone -a -b outfile.xls
</syntaxhighlight>

[[File:hfs2_read.png|thumb|HFS+ read]]
[[File:hfs2_write.png|thumb|HFS+ write]]
[[File:zfs2_read.png|thumb|ZFS read]]
[[File:zfs2_write.png|thumb|ZFS write]]

As a guess, writes need to double, and reads need to triple.




=== VFS ===

[[VFS]]



== File-based zpools for testing==

* create 2 files (each 100 MB) to be used as block devices:
<syntaxhighlight lang="bash">
$ dd if=/dev/zero bs=1m count=100 of=vdisk1
$ dd if=/dev/zero bs=1m count=100 of=vdisk2
</syntaxhighlight>

* attach files as raw disk images:
<syntaxhighlight lang="bash">
$ hdiutil attach -imagekey diskimage-class=CRawDiskImage -nomount vdisk1
/dev/disk2
$ hdiutil attach -imagekey diskimage-class=CRawDiskImage -nomount vdisk2
/dev/disk3
</syntaxhighlight>

* create mirrored zpool:
<syntaxhighlight lang="bash">
$ sudo zpool create -f -o ashift=12 -O casesensitivity=insensitive -O normalization=formD tank mirror disk2 disk3
</syntaxhighlight>

* show zpool:
<syntaxhighlight lang="bash">
$ sudo zpool status
  pool: tank
 state: ONLINE
  scan: none requested
config:

	NAME        STATE     READ WRITE CKSUM
	tank        ONLINE       0     0     0
	  mirror-0  ONLINE       0     0     0
	    disk2   ONLINE       0     0     0
	    disk3   ONLINE       0     0     0

errors: No known data errors
</syntaxhighlight>

* test ZFS features, find bugs, ...

* export zpool:
<syntaxhighlight lang="bash">
$ sudo zpool export tank
</syntaxhighlight>

* detach raw images:
<syntaxhighlight lang="bash">
$ hdiutil detach disk2
"disk2" unmounted.
"disk2" ejected.
$ hdiutil detach disk3
"disk3" unmounted.
"disk3" ejected.
</syntaxhighlight>


== Platform differences ==

This section is an attempt to outline the differences from ZFS versions of other platforms, as compared to OS X. To assist developers new to the Apple platform, who wishes to assist, or understand, development of the O3X version.

=== VFS nolocks ===

To avoid deadlocking complications, we do not call VFS with any locks, at any time. This means we differ a little bit from original IllumOS code. In particular, the calls that create a znode (zfs_mknode and zfs_znode_alloc)
we do not attach the vnode here, as we are inside that of a dmu_tx. For example, the VNOPs zfs_create, zfs_mkdir, zfs_symlink and zfs_make_xattrdir, have instead been patched to call zfs_znode_getvnode() to attach the vnode '''after'''
the dmu_tx has been completed.  This means there is a small window where another thread can call zget() on the same object, and it does not yet have the vnode. This is detected in zget, and will delay until the vnode is
attached. We should look into a better delay, perhaps a condvar with wakeup.

There is further work in zil_lwb_commit() to ensure we call zfs_get_data without locks, and vnode attached. This this area also differs somewhat from IllumOS. The zget() call has been extended to allow flags to specify if
we should allow zget on unlinked files zil, and zget without attaching vnode (for delayed attachment after locks are released).

=== Fastpath vs Recycle ===

Another interesting aspect is that IllumOS has a delete fastpath. In zfs_remove, if it is detected that the znode can be "deleted_now", it marks the vnode as free and directly calls zfs_znode_delete(), if it can not, adds it to zfs_unlinked_add().

In OS X, there is no way to directly release a vnode. Ie, XNU always has full control of the vnodes. Even if you call vnode_recycle(), the vnode is not released '''until''' vnop_reclaim is called. The vnode can just be marked for later reclaim, but remain active (especially if you are racing against other threads using the same vnode). So in zfs_remove, we attempt to call vnode_recycle(), and only if this returns "1" do we know that vnop_reclaim was called, and we can directly call zfs_znode_delete(). Note that the O3X vnop_reclaim handler then has special code to not do anything with the vnode (zp->z_fastpath) but to only clear out the z_vnode and return.

    zp->z_fastpath = B_TRUE;
    if (vnode_recycle(vp) == 1) {
        /* recycle/reclaim is done, so we can just release now */
        zfs_znode_delete(zp, tx);
    } else {
        /* failed to recycle, so just place it on the unlinked list */
        zp->z_fastpath = B_FALSE;
        zfs_unlinked_add(zp, tx);
    }


There is also a little special lock-handling in zfs_zinactive, since we can call it from inside of a vnode_create() which is called by ZFS with locks held. If this is the case, we do not attempt to acquire locks in zfs_zinactive.

=== snapshot mounts ===

There is no way to cause a mount in XNU kernel. None. At. All. Apple themselves cheated and added a static nfsmount() that we can not call. So instead, we have to jump through a whole bunch of
hoops to get there. We create a fake/virtual /dev/diskX entry for the snapshot.  '''diskarbitrationd''' will wake up due to new disk, it will enter the probe phase, which includes calling
all the /System/Library/Filesystems/ bundles. Eventually, zfs.util is called and we reply affirmative. However, automount is disable here, as there is no way to specify a mountpoint with auto.
zfs.util will call DADiskMount to mount it to the correct directory.

This means we have a few more VNOPs in zfs_ctldir.c, as we have to reply with correct information to make mount successful. The first getattr will cause the mount attempt, the DADiskMount call will cause getattr to be called
and we have to pretend to have said entry.

=== spl_vn_rdwr vs vn_rdwr ===

There are two calls to vn_rdwr() in OSX's SPL. The '''spl_vn_rdwr()''' call needs to be used when zfs_onexit is in use. For example, dmu_send.c (zfs recv/send) and zfs_ioc_diff (zfs diff). The XNU implementation of
zfs_onexit (as in calls to ''' getf ''' and ''' releasef ''' ) need to place the internal XNU ''struct fileproc'' in the wrapper ''struct spl_fileproc'' , so that '''spl_vn_rdwr()''' can use it to do IO.
This is the only way to do IO on a non-file based vnode (ie, pipe or socket). Other places that call vn_rdwr(), for example vdev_file.c, needs to call the regular vn_rdwr.

=== getattr ===

XNU has a whole bunch of items that it can ask for in vnop_getattr, including VA_NAME, which is used heavily by Finder (especially in the vfs_vget path). Care is needed here to return the correct name, 
including for link (hard links) targets. Due to this, O3X caches the name in the znode so that we can return it without cost in vnop_getattr if available, and fall back to using zap_value_search otherwise. 
This value is also set on the vnode in vfs_vget() using the vnode_update_identity() call. This is expected by mds/Spotlight to work correctly.

=== hardlinks ===

There is further complications with hardlinks as well. In posix, hardlinks all share va_fileid, and z_links reference counter is incremented for each target. Finder in OS X requires a new va_linkid to be queried in
vnap_getattr. It also demands va_linkid to be a unique value for each link target (they all share the same va_fileid, but each one has its own va_linkid). And this va_linkid is used
in calls to vfs_vget(), to map va_linkid to the actual znode/fileid in use, and update both name and parent id.

For hardlinks, we then build two AVL trees, zfsvfs->z_hardlinks and zfsvfs->z_hardlinks_linkid in vnop_getattr. The first AVL is indexed by (parent id, file id, name) and the latter by (linkid). This allows us to create new
and unique va_linkid for hardlinks when we come across them (starting at 0x80000000 due to 32bitness, in a weak attempt to avoid collisions). vfs_vget() then checks the AVL tree for va_linkid and if found, can zget the correct
va_fileid, and set the hardlink name and parent id. If the AVL does not contain the va_linkid, it falls back to regular va_fileid lookup. So even if there are collisions, it should be able to cope.

Care is also needed in vnop_remove, to clean out the hardlink AVL node in both trees, as well as in vnop_rename, to update the new source mapping (parent id, file id, name).  The AVL trees are unloaded at unmount.


== Merging with OpenZFS ==

Add upstream OpenZFS repo as a remote source;

  [remote "upstream"]
        url = git@github.com:openzfs/openzfs.git
        fetch = +refs/heads/*:refs/remotes/upstream/*

Set the rename limit really high to make it find our locations

 # git config merge.renameLimit 999999 
 
  [merge]
        renameLimit = 999999


Make sure it is up to date

   # git fetch upstream

Check whats new:

  # git log --stat upstream/master

For each new commit, bring it in, for example f4a6fedc42535abef5f0584fa0c6cb2af46b9ddf

  # git cherry-pick f4a6fedc42535abef5f0584fa0c6cb2af46b9ddf

fix any clashes, if any, make sure it compiles with no new errors or warnings.

Always update the commit message

  # git commit --amend

and delete any lines that are like

  Closes #324

since they do not match our issues.


=== Merging PRs ===

Check out the PR branch, for example PR 124

  # git fetch upstream pull/124/head:pr124
  # git checkout pr124

And view the commits that you want

[[zfs.exports]]