tools/tests/perf_index/README

   1 perf_index - This is a tool for gather performance data. perf_index can run in
   2 two modes. In regulular (offline mode) the usage is:
   3 pref_index type threads size [args]
   4 where type is one of the test types explained below, threads is the number of
   5 userland threads that should preform the task, size is the size of the task and
   6 args are arguments to pass to the test. Currently only the iperf test requires
   7 these arguments. For example if run with the following arguments:
   8 ./perf_index cpu 2 100000000
   9
  10 iperf will run the cpu workload on two threads with a total work load size of
  11 100000000. Since the workload is distributed over 2 threads, on a perfectly
  12 parallel system, this would take half the time relative to if 1 was specified
  13 for the threads parameter. When finished running perf_index will write the
  14 number of seconds it took to standard out as a decimal number. Some of the test
  15 types have initialization and teardown steps, and these steps are not counted
  16 towards the time.  The workload and the time it takes to be performed differs
  17 quite drastically between test type, so you may need to play around with the
  18 size argument to find a value that will complete in a reasonable amount of time.
  19
  20 In online mode, perf_index is invoked like so:
  21 perf_index remote server
  22 where remote is exactly the string "remote" and server is the control host to
  23 connect to.  This tells the program to connect to the specified server and wait
  24 for instructions. The server is run by running the test_controller.py python
  25 script with the following arguments:
  26 test_controller.py num_clients type threads size
  27 The server will wait for num_client to connect. It will then pass type, threads,
  28 and size to each of those clients, who will run the initialization code and
  29 report back to the server. Once the initialization is run by every client, the
  30 server will give the OK to every client to run the workload and begin timing.
  31 When done, each client reports back to the server. Once the server hears back
  32 from every client, it will stop timing and output the elapsed time.
  33
  34
  35 Test Types:
  36 Note this implementations are subject to change, for an authoritative source,
  37 see the source code
  38 cpu - calculates n md5 sums
  39 memory - initializes by allocating memory equal to half the RAM on the machine,
  40 then writes a byte to every page to ensure it is paged in. Then copies n bytes
  41 from the first half of memory to the second. If the allocated space is less than
  42 n/2, it keeps repeating the copies until n bytes are copied.
  43 syscall - calls the getppid(2) system call n times
  44 fault - performs n page faults by mmaping a large chunk of memory, toggling the
  45 write protection bit, and writing to each page
  46 zfod - performs n zero fill on demands, by mmaping a large chunk of memory and
  47 writing to each page
  48 file_create - creates n files (in the same directory) with the open(2) system
  49 call
  50 file_write - writes n bytes to files on disk. There is one file per each thread.
  51 file_read - initializes by creating one large file on disk per each thread.
  52 Then reads n bytes total from all the files. If there are less than n bytes in
  53 the files, repeats reading from the beginning.
  54 ram_file_create - same as file_create but on a ram disk
  55 ram_file_read - same as file_read but on a ram disk
  56 ram_file_write - same as file_write but on a ram disk
  57 iperf - uses iperf to send n bytes over the network to the designated host
  58 specified as args
  59 compile - compiles xnu using make. This currently does a single compile and
  60 ignores the size argument
  61
  62 Building:
  63 perf_index is built automatically by BNI for both Mac (10.9 and later), and iOS
  64 (7 and later) trains, and is delivered on AppleInternal builds in
  65 /AppleInternal/CoreOS/perf_index. It is built as part of the xnu_quick_test
  66 build alias, so you can also find a copy on ~rc at:
  67 ~rc/Software/$RELEASE/Updates/$RELEASEVERSION/Roots/xnu_quick_test/AppleInternal/CoreOS/perf_index.
  68
  69 Alternatively you can build it yourself using make like so:
  70 SDKROOT=/path/to/sdk make
  71
  72 For example:
  73 # build for Mac, current OS
  74 SDKROOT=/ make
  75 # build for iOS
  76 SDKROOT=`xcodebuild -sdk iphoneos.internal -version Path` make
  77
  78 By default xnu builds all-way fat, but you can restrict this by explicitly
  79 specifying architectures like so:
  80 # build for only armv7 and armv7s
  81 SDKROOT=`xcodebuild -sdk iphoneos.internal -version Path` make ARCH="armv7 armv7s"