Documentation/driver-api/crypto/iaa/iaa-crypto.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================================
   4 IAA Compression Accelerator Crypto Driver
   5 =========================================
   6
   7 Tom Zanussi <tom.zanussi@linux.intel.com>
   8
   9 The IAA crypto driver supports compression/decompression compatible
  10 with the DEFLATE compression standard described in RFC 1951, which is
  11 the compression/decompression algorithm exported by this module.
  12
  13 The IAA hardware spec can be found here:
  14
  15   https://cdrdv2.intel.com/v1/dl/getContent/721858
  16
  17 The iaa_crypto driver is designed to work as a layer underneath
  18 higher-level compression devices such as zswap.
  19
  20 Users can select IAA compress/decompress acceleration by specifying
  21 one of the supported IAA compression algorithms in whatever facility
  22 allows compression algorithms to be selected.
  23
  24 For example, a zswap device can select the IAA 'fixed' mode
  25 represented by selecting the 'deflate-iaa' crypto compression
  26 algorithm::
  27
  28   # echo deflate-iaa > /sys/module/zswap/parameters/compressor
  29
  30 This will tell zswap to use the IAA 'fixed' compression mode for all
  31 compresses and decompresses.
  32
  33 Currently, there is only one compression modes available, 'fixed'
  34 mode.
  35
  36 The 'fixed' compression mode implements the compression scheme
  37 specified by RFC 1951 and is given the crypto algorithm name
  38 'deflate-iaa'.  (Because the IAA hardware has a 4k history-window
  39 limitation, only buffers <= 4k, or that have been compressed using a
  40 <= 4k history window, are technically compliant with the deflate spec,
  41 which allows for a window of up to 32k.  Because of this limitation,
  42 the IAA fixed mode deflate algorithm is given its own algorithm name
  43 rather than simply 'deflate').
  44
  45
  46 Config options and other setup
  47 ==============================
  48
  49 The IAA crypto driver is available via menuconfig using the following
  50 path::
  51
  52   Cryptographic API -> Hardware crypto devices -> Support for Intel(R) IAA Compression Accelerator
  53
  54 In the configuration file the option called CONFIG_CRYPTO_DEV_IAA_CRYPTO.
  55
  56 The IAA crypto driver also supports statistics, which are available
  57 via menuconfig using the following path::
  58
  59   Cryptographic API -> Hardware crypto devices -> Support for Intel(R) IAA Compression -> Enable Intel(R) IAA Compression Accelerator Statistics
  60
  61 In the configuration file the option called CONFIG_CRYPTO_DEV_IAA_CRYPTO_STATS.
  62
  63 The following config options should also be enabled::
  64
  65   CONFIG_IRQ_REMAP=y
  66   CONFIG_INTEL_IOMMU=y
  67   CONFIG_INTEL_IOMMU_SVM=y
  68   CONFIG_PCI_ATS=y
  69   CONFIG_PCI_PRI=y
  70   CONFIG_PCI_PASID=y
  71   CONFIG_INTEL_IDXD=m
  72   CONFIG_INTEL_IDXD_SVM=y
  73
  74 IAA is one of the first Intel accelerator IPs that can work in
  75 conjunction with the Intel IOMMU.  There are multiple modes that exist
  76 for testing. Based on IOMMU configuration, there are 3 modes::
  77
  78   - Scalable
  79   - Legacy
  80   - No IOMMU
  81
  82
  83 Scalable mode
  84 -------------
  85
  86 Scalable mode supports Shared Virtual Memory (SVM or SVA). It is
  87 entered when using the kernel boot commandline::
  88
  89   intel_iommu=on,sm_on
  90
  91 with VT-d turned on in BIOS.
  92
  93 With scalable mode, both shared and dedicated workqueues are available
  94 for use.
  95
  96 For scalable mode, the following BIOS settings should be enabled::
  97
  98   Socket Configuration > IIO Configuration > Intel VT for Directed I/O (VT-d) > Intel VT for Directed I/O
  99
 100   Socket Configuration > IIO Configuration > PCIe ENQCMD > ENQCMDS
 101
 102
 103 Legacy mode
 104 -----------
 105
 106 Legacy mode is entered when using the kernel boot commandline::
 107
 108   intel_iommu=off
 109
 110 or VT-d is not turned on in BIOS.
 111
 112 If you have booted into Linux and not sure if VT-d is on, do a "dmesg
 113 | grep -i dmar". If you don't see a number of DMAR devices enumerated,
 114 most likely VT-d is not on.
 115
 116 With legacy mode, only dedicated workqueues are available for use.
 117
 118
 119 No IOMMU mode
 120 -------------
 121
 122 No IOMMU mode is entered when using the kernel boot commandline::
 123
 124   iommu=off.
 125
 126 With no IOMMU mode, only dedicated workqueues are available for use.
 127
 128
 129 Usage
 130 =====
 131
 132 accel-config
 133 ------------
 134
 135 When loaded, the iaa_crypto driver automatically creates a default
 136 configuration and enables it, and assigns default driver attributes.
 137 If a different configuration or set of driver attributes is required,
 138 the user must first disable the IAA devices and workqueues, reset the
 139 configuration, and then re-register the deflate-iaa algorithm with the
 140 crypto subsystem by removing and reinserting the iaa_crypto module.
 141
 142 The :ref:`iaa_disable_script` in the 'Use Cases'
 143 section below can be used to disable the default configuration.
 144
 145 See :ref:`iaa_default_config` below for details of the default
 146 configuration.
 147
 148 More likely than not, however, and because of the complexity and
 149 configurability of the accelerator devices, the user will want to
 150 configure the device and manually enable the desired devices and
 151 workqueues.
 152
 153 The userspace tool to help doing that is called accel-config.  Using
 154 accel-config to configure device or loading a previously saved config
 155 is highly recommended.  The device can be controlled via sysfs
 156 directly but comes with the warning that you should do this ONLY if
 157 you know exactly what you are doing.  The following sections will not
 158 cover the sysfs interface but assumes you will be using accel-config.
 159
 160 The :ref:`iaa_sysfs_config` section in the appendix below can be
 161 consulted for the sysfs interface details if interested.
 162
 163 The accel-config tool along with instructions for building it can be
 164 found here:
 165
 166   https://github.com/intel/idxd-config/#readme
 167
 168 Typical usage
 169 -------------
 170
 171 In order for the iaa_crypto module to actually do any
 172 compression/decompression work on behalf of a facility, one or more
 173 IAA workqueues need to be bound to the iaa_crypto driver.
 174
 175 For instance, here's an example of configuring an IAA workqueue and
 176 binding it to the iaa_crypto driver (note that device names are
 177 specified as 'iax' rather than 'iaa' - this is because upstream still
 178 has the old 'iax' device naming in place) ::
 179
 180   # configure wq1.0
 181
 182   accel-config config-wq --group-id=0 --mode=dedicated --type=kernel --priority=10 --name="iaa_crypto" --driver-name="crypto" iax1/wq1.0
 183
 184   accel-config config-engine iax1/engine1.0 --group-id=0
 185
 186   # enable IAA device iax1
 187
 188   accel-config enable-device iax1
 189
 190   # enable wq1.0 on IAX device iax1
 191
 192   accel-config enable-wq iax1/wq1.0
 193
 194 Whenever a new workqueue is bound to or unbound from the iaa_crypto
 195 driver, the available workqueues are 'rebalanced' such that work
 196 submitted from a particular CPU is given to the most appropriate
 197 workqueue available.  Current best practice is to configure and bind
 198 at least one workqueue for each IAA device, but as long as there is at
 199 least one workqueue configured and bound to any IAA device in the
 200 system, the iaa_crypto driver will work, albeit most likely not as
 201 efficiently.
 202
 203 The IAA crypto algorigthms is operational and compression and
 204 decompression operations are fully enabled following the successful
 205 binding of the first IAA workqueue to the iaa_crypto driver.
 206
 207 Similarly, the IAA crypto algorithm is not operational and compression
 208 and decompression operations are disabled following the unbinding of
 209 the last IAA worqueue to the iaa_crypto driver.
 210
 211 As a result, the IAA crypto algorithms and thus the IAA hardware are
 212 only available when one or more workques are bound to the iaa_crypto
 213 driver.
 214
 215 When there are no IAA workqueues bound to the driver, the IAA crypto
 216 algorithms can be unregistered by removing the module.
 217
 218
 219 Driver attributes
 220 -----------------
 221
 222 There are a couple user-configurable driver attributes that can be
 223 used to configure various modes of operation.  They're listed below,
 224 along with their default values.  To set any of these attributes, echo
 225 the appropriate values to the attribute file located under
 226 /sys/bus/dsa/drivers/crypto/
 227
 228 The attribute settings at the time the IAA algorithms are registered
 229 are captured in each algorithm's crypto_ctx and used for all compresses
 230 and decompresses when using that algorithm.
 231
 232 The available attributes are:
 233
 234   - verify_compress
 235
 236     Toggle compression verification.  If set, each compress will be
 237     internally decompressed and the contents verified, returning error
 238     codes if unsuccessful.  This can be toggled with 0/1::
 239
 240       echo 0 > /sys/bus/dsa/drivers/crypto/verify_compress
 241
 242     The default setting is '1' - verify all compresses.
 243
 244   - sync_mode
 245
 246     Select mode to be used to wait for completion of each compresses
 247     and decompress operation.
 248
 249     The crypto async interface support implemented by iaa_crypto
 250     provides an implementation that satisfies the interface but does
 251     so in a synchronous manner - it fills and submits the IDXD
 252     descriptor and then loops around waiting for it to complete before
 253     returning.  This isn't a problem at the moment, since all existing
 254     callers (e.g. zswap) wrap any asynchronous callees in a
 255     synchronous wrapper anyway.
 256
 257     The iaa_crypto driver does however provide true asynchronous
 258     support for callers that can make use of it.  In this mode, it
 259     fills and submits the IDXD descriptor, then returns immediately
 260     with -EINPROGRESS.  The caller can then either poll for completion
 261     itself, which requires specific code in the caller which currently
 262     nothing in the upstream kernel implements, or go to sleep and wait
 263     for an interrupt signaling completion.  This latter mode is
 264     supported by current users in the kernel such as zswap via
 265     synchronous wrappers.  Although it is supported this mode is
 266     significantly slower than the synchronous mode that does the
 267     polling in the iaa_crypto driver previously mentioned.
 268
 269     This mode can be enabled by writing 'async_irq' to the sync_mode
 270     iaa_crypto driver attribute::
 271
 272       echo async_irq > /sys/bus/dsa/drivers/crypto/sync_mode
 273
 274     Async mode without interrupts (caller must poll) can be enabled by
 275     writing 'async' to it::
 276
 277       echo async > /sys/bus/dsa/drivers/crypto/sync_mode
 278
 279     The mode that does the polling in the iaa_crypto driver can be
 280     enabled by writing 'sync' to it::
 281
 282       echo sync > /sys/bus/dsa/drivers/crypto/sync_mode
 283
 284     The default mode is 'sync'.
 285
 286 .. _iaa_default_config:
 287
 288 IAA Default Configuration
 289 -------------------------
 290
 291 When the iaa_crypto driver is loaded, each IAA device has a single
 292 work queue configured for it, with the following attributes::
 293
 294           mode              "dedicated"
 295           threshold         0
 296           size              Total WQ Size from WQCAP
 297           priority          10
 298           type              IDXD_WQT_KERNEL
 299           group             0
 300           name              "iaa_crypto"
 301           driver_name       "crypto"
 302
 303 The devices and workqueues are also enabled and therefore the driver
 304 is ready to be used without any additional configuration.
 305
 306 The default driver attributes in effect when the driver is loaded are::
 307
 308           sync_mode         "sync"
 309           verify_compress   1
 310
 311 In order to change either the device/work queue or driver attributes,
 312 the enabled devices and workqueues must first be disabled.  In order
 313 to have the new configuration applied to the deflate-iaa crypto
 314 algorithm, it needs to be re-registered by removing and reinserting
 315 the iaa_crypto module.  The :ref:`iaa_disable_script` in the 'Use
 316 Cases' section below can be used to disable the default configuration.
 317
 318 Statistics
 319 ==========
 320
 321 If the optional debugfs statistics support is enabled, the IAA crypto
 322 driver will generate statistics which can be accessed in debugfs at::
 323
 324   # ls -al /sys/kernel/debug/iaa-crypto/
 325   total 0
 326   drwxr-xr-x  2 root root 0 Mar  3 07:55 .
 327   drwx------ 53 root root 0 Mar  3 07:55 ..
 328   -rw-r--r--  1 root root 0 Mar  3 07:55 global_stats
 329   -rw-r--r--  1 root root 0 Mar  3 07:55 stats_reset
 330   -rw-r--r--  1 root root 0 Mar  3 07:55 wq_stats
 331
 332 The global_stats file shows a set of global statistics collected since
 333 the driver has been loaded or reset::
 334
 335   # cat global_stats
 336   global stats:
 337     total_comp_calls: 4300
 338     total_decomp_calls: 4164
 339     total_sw_decomp_calls: 0
 340     total_comp_bytes_out: 5993989
 341     total_decomp_bytes_in: 5993989
 342     total_completion_einval_errors: 0
 343     total_completion_timeout_errors: 0
 344     total_completion_comp_buf_overflow_errors: 136
 345
 346 The wq_stats file shows per-wq stats, a set for each iaa device and wq
 347 in addition to some global stats::
 348
 349   # cat wq_stats
 350   iaa device:
 351     id: 1
 352     n_wqs: 1
 353     comp_calls: 0
 354     comp_bytes: 0
 355     decomp_calls: 0
 356     decomp_bytes: 0
 357     wqs:
 358       name: iaa_crypto
 359       comp_calls: 0
 360       comp_bytes: 0
 361       decomp_calls: 0
 362       decomp_bytes: 0
 363
 364   iaa device:
 365     id: 3
 366     n_wqs: 1
 367     comp_calls: 0
 368     comp_bytes: 0
 369     decomp_calls: 0
 370     decomp_bytes: 0
 371     wqs:
 372       name: iaa_crypto
 373       comp_calls: 0
 374       comp_bytes: 0
 375       decomp_calls: 0
 376       decomp_bytes: 0
 377
 378   iaa device:
 379     id: 5
 380     n_wqs: 1
 381     comp_calls: 1360
 382     comp_bytes: 1999776
 383     decomp_calls: 0
 384     decomp_bytes: 0
 385     wqs:
 386       name: iaa_crypto
 387       comp_calls: 1360
 388       comp_bytes: 1999776
 389       decomp_calls: 0
 390       decomp_bytes: 0
 391
 392   iaa device:
 393     id: 7
 394     n_wqs: 1
 395     comp_calls: 2940
 396     comp_bytes: 3994213
 397     decomp_calls: 4164
 398     decomp_bytes: 5993989
 399     wqs:
 400       name: iaa_crypto
 401       comp_calls: 2940
 402       comp_bytes: 3994213
 403       decomp_calls: 4164
 404       decomp_bytes: 5993989
 405     ...
 406
 407 Writing to 'stats_reset' resets all the stats, including the
 408 per-device and per-wq stats::
 409
 410   # echo 1 > stats_reset
 411   # cat wq_stats
 412     global stats:
 413     total_comp_calls: 0
 414     total_decomp_calls: 0
 415     total_comp_bytes_out: 0
 416     total_decomp_bytes_in: 0
 417     total_completion_einval_errors: 0
 418     total_completion_timeout_errors: 0
 419     total_completion_comp_buf_overflow_errors: 0
 420     ...
 421
 422
 423 Use cases
 424 =========
 425
 426 Simple zswap test
 427 -----------------
 428
 429 For this example, the kernel should be configured according to the
 430 dedicated mode options described above, and zswap should be enabled as
 431 well::
 432
 433   CONFIG_ZSWAP=y
 434
 435 This is a simple test that uses iaa_compress as the compressor for a
 436 swap (zswap) device.  It sets up the zswap device and then uses the
 437 memory_memadvise program listed below to forcibly swap out and in a
 438 specified number of pages, demonstrating both compress and decompress.
 439
 440 The zswap test expects the work queues for each IAA device on the
 441 system to be configured properly as a kernel workqueue with a
 442 workqueue driver_name of "crypto".
 443
 444 The first step is to make sure the iaa_crypto module is loaded::
 445
 446   modprobe iaa_crypto
 447
 448 If the IAA devices and workqueues haven't previously been disabled and
 449 reconfigured, then the default configuration should be in place and no
 450 further IAA configuration is necessary.  See :ref:`iaa_default_config`
 451 below for details of the default configuration.
 452
 453 If the default configuration is in place, you should see the iaa
 454 devices and wq0s enabled::
 455
 456   # cat /sys/bus/dsa/devices/iax1/state
 457   enabled
 458   # cat /sys/bus/dsa/devices/iax1/wq1.0/state
 459   enabled
 460
 461 To demonstrate that the following steps work as expected, these
 462 commands can be used to enable debug output::
 463
 464   # echo -n 'module iaa_crypto +p' > /sys/kernel/debug/dynamic_debug/control
 465   # echo -n 'module idxd +p' > /sys/kernel/debug/dynamic_debug/control
 466
 467 Use the following commands to enable zswap::
 468
 469   # echo 0 > /sys/module/zswap/parameters/enabled
 470   # echo 50 > /sys/module/zswap/parameters/max_pool_percent
 471   # echo deflate-iaa > /sys/module/zswap/parameters/compressor
 472   # echo zsmalloc > /sys/module/zswap/parameters/zpool
 473   # echo 1 > /sys/module/zswap/parameters/enabled
 474   # echo 100 > /proc/sys/vm/swappiness
 475   # echo never > /sys/kernel/mm/transparent_hugepage/enabled
 476   # echo 1 > /proc/sys/vm/overcommit_memory
 477
 478 Now you can now run the zswap workload you want to measure. For
 479 example, using the memory_memadvise code below, the following command
 480 will swap in and out 100 pages::
 481
 482   ./memory_madvise 100
 483
 484   Allocating 100 pages to swap in/out
 485   Swapping out 100 pages
 486   Swapping in 100 pages
 487   Swapped out and in 100 pages
 488
 489 You should see something like the following in the dmesg output::
 490
 491   [  404.202972] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, src_addr 223925c000, nr_sgs 1, req->src 00000000ee7cb5e6, req->slen 4096, sg_dma_len(sg) 4096
 492   [  404.202973] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, dst_addr 21dadf8000, nr_sgs 1, req->dst 000000008d6acea8, req->dlen 4096, sg_dma_len(sg) 8192
 493   [  404.202975] idxd 0000:e7:02.0: iaa_compress: desc->src1_addr 223925c000, desc->src1_size 4096, desc->dst_addr 21dadf8000, desc->max_dst_size 4096, desc->src2_addr 2203543000, desc->src2_size 1568
 494   [  404.202981] idxd 0000:e7:02.0: iaa_compress_verify: (verify) desc->src1_addr 21dadf8000, desc->src1_size 228, desc->dst_addr 223925c000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0
 495   ...
 496
 497 Now that basic functionality has been demonstrated, the defaults can
 498 be erased and replaced with a different configuration.  To do that,
 499 first disable zswap::
 500
 501   # echo lzo > /sys/module/zswap/parameters/compressor
 502   # swapoff -a
 503   # echo 0 > /sys/module/zswap/parameters/accept_threshold_percent
 504   # echo 0 > /sys/module/zswap/parameters/max_pool_percent
 505   # echo 0 > /sys/module/zswap/parameters/enabled
 506   # echo 0 > /sys/module/zswap/parameters/enabled
 507
 508 Then run the :ref:`iaa_disable_script` in the 'Use Cases' section
 509 below to disable the default configuration.
 510
 511 Finally turn swap back on::
 512
 513   # swapon -a
 514
 515 Following all that the IAA device(s) can now be re-configured and
 516 enabled as desired for further testing.  Below is one example.
 517
 518 The zswap test expects the work queues for each IAA device on the
 519 system to be configured properly as a kernel workqueue with a
 520 workqueue driver_name of "crypto".
 521
 522 The below script automatically does that::
 523
 524   #!/bin/bash
 525
 526   echo "IAA devices:"
 527   lspci -d:0cfe
 528   echo "# IAA devices:"
 529   lspci -d:0cfe | wc -l
 530
 531   #
 532   # count iaa instances
 533   #
 534   iaa_dev_id="0cfe"
 535   num_iaa=$(lspci -d:${iaa_dev_id} | wc -l)
 536   echo "Found ${num_iaa} IAA instances"
 537
 538   #
 539   # disable iaa wqs and devices
 540   #
 541   echo "Disable IAA"
 542
 543   for ((i = 1; i < ${num_iaa} * 2; i += 2)); do
 544       echo disable wq iax${i}/wq${i}.0
 545       accel-config disable-wq iax${i}/wq${i}.0
 546       echo disable iaa iax${i}
 547       accel-config disable-device iax${i}
 548   done
 549
 550   echo "End Disable IAA"
 551
 552   echo "Reload iaa_crypto module"
 553
 554   rmmod iaa_crypto
 555   modprobe iaa_crypto
 556
 557   echo "End Reload iaa_crypto module"
 558
 559   #
 560   # configure iaa wqs and devices
 561   #
 562   echo "Configure IAA"
 563   for ((i = 1; i < ${num_iaa} * 2; i += 2)); do
 564       accel-config config-wq --group-id=0 --mode=dedicated --wq-size=128 --priority=10 --type=kernel --name="iaa_crypto" --driver-name="crypto" iax${i}/wq${i}.0
 565       accel-config config-engine iax${i}/engine${i}.0 --group-id=0
 566   done
 567
 568   echo "End Configure IAA"
 569
 570   #
 571   # enable iaa wqs and devices
 572   #
 573   echo "Enable IAA"
 574
 575   for ((i = 1; i < ${num_iaa} * 2; i += 2)); do
 576       echo enable iaa iax${i}
 577       accel-config enable-device iax${i}
 578       echo enable wq iax${i}/wq${i}.0
 579       accel-config enable-wq iax${i}/wq${i}.0
 580   done
 581
 582   echo "End Enable IAA"
 583
 584 When the workqueues are bound to the iaa_crypto driver, you should
 585 see something similar to the following in dmesg output if you've
 586 enabled debug output (echo -n 'module iaa_crypto +p' >
 587 /sys/kernel/debug/dynamic_debug/control)::
 588
 589   [   60.752344] idxd 0000:f6:02.0: add_iaa_wq: added wq 000000004068d14d to iaa 00000000c9585ba2, n_wq 1
 590   [   60.752346] iaa_crypto: rebalance_wq_table: nr_nodes=2, nr_cpus 160, nr_iaa 8, cpus_per_iaa 20
 591   [   60.752347] iaa_crypto: rebalance_wq_table: iaa=0
 592   [   60.752349] idxd 0000:6a:02.0: request_iaa_wq: getting wq from iaa_device 0000000042d7bc52 (0)
 593   [   60.752350] idxd 0000:6a:02.0: request_iaa_wq: returning unused wq 00000000c8bb4452 (0) from iaa device 0000000042d7bc52 (0)
 594   [   60.752352] iaa_crypto: rebalance_wq_table: assigned wq for cpu=0, node=0 = wq 00000000c8bb4452
 595   [   60.752354] iaa_crypto: rebalance_wq_table: iaa=0
 596   [   60.752355] idxd 0000:6a:02.0: request_iaa_wq: getting wq from iaa_device 0000000042d7bc52 (0)
 597   [   60.752356] idxd 0000:6a:02.0: request_iaa_wq: returning unused wq 00000000c8bb4452 (0) from iaa device 0000000042d7bc52 (0)
 598   [   60.752358] iaa_crypto: rebalance_wq_table: assigned wq for cpu=1, node=0 = wq 00000000c8bb4452
 599   [   60.752359] iaa_crypto: rebalance_wq_table: iaa=0
 600   [   60.752360] idxd 0000:6a:02.0: request_iaa_wq: getting wq from iaa_device 0000000042d7bc52 (0)
 601   [   60.752361] idxd 0000:6a:02.0: request_iaa_wq: returning unused wq 00000000c8bb4452 (0) from iaa device 0000000042d7bc52 (0)
 602   [   60.752362] iaa_crypto: rebalance_wq_table: assigned wq for cpu=2, node=0 = wq 00000000c8bb4452
 603   [   60.752364] iaa_crypto: rebalance_wq_table: iaa=0
 604   .
 605   .
 606   .
 607
 608 Once the workqueues and devices have been enabled, the IAA crypto
 609 algorithms are enabled and available.  When the IAA crypto algorithms
 610 have been successfully enabled, you should see the following dmesg
 611 output::
 612
 613   [   64.893759] iaa_crypto: iaa_crypto_enable: iaa_crypto now ENABLED
 614
 615 Now run the following zswap-specific setup commands to have zswap use
 616 the 'fixed' compression mode::
 617
 618   echo 0 > /sys/module/zswap/parameters/enabled
 619   echo 50 > /sys/module/zswap/parameters/max_pool_percent
 620   echo deflate-iaa > /sys/module/zswap/parameters/compressor
 621   echo zsmalloc > /sys/module/zswap/parameters/zpool
 622   echo 1 > /sys/module/zswap/parameters/enabled
 623
 624   echo 100 > /proc/sys/vm/swappiness
 625   echo never > /sys/kernel/mm/transparent_hugepage/enabled
 626   echo 1 > /proc/sys/vm/overcommit_memory
 627
 628 Finally, you can now run the zswap workload you want to measure. For
 629 example, using the code below, the following command will swap in and
 630 out 100 pages::
 631
 632   ./memory_madvise 100
 633
 634   Allocating 100 pages to swap in/out
 635   Swapping out 100 pages
 636   Swapping in 100 pages
 637   Swapped out and in 100 pages
 638
 639 You should see something like the following in the dmesg output if
 640 you've enabled debug output (echo -n 'module iaa_crypto +p' >
 641 /sys/kernel/debug/dynamic_debug/control)::
 642
 643   [  404.202972] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, src_addr 223925c000, nr_sgs 1, req->src 00000000ee7cb5e6, req->slen 4096, sg_dma_len(sg) 4096
 644   [  404.202973] idxd 0000:e7:02.0: iaa_comp_acompress: dma_map_sg, dst_addr 21dadf8000, nr_sgs 1, req->dst 000000008d6acea8, req->dlen 4096, sg_dma_len(sg) 8192
 645   [  404.202975] idxd 0000:e7:02.0: iaa_compress: desc->src1_addr 223925c000, desc->src1_size 4096, desc->dst_addr 21dadf8000, desc->max_dst_size 4096, desc->src2_addr 2203543000, desc->src2_size 1568
 646   [  404.202981] idxd 0000:e7:02.0: iaa_compress_verify: (verify) desc->src1_addr 21dadf8000, desc->src1_size 228, desc->dst_addr 223925c000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0
 647   [  409.203227] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, src_addr 21ddd8b100, nr_sgs 1, req->src 0000000084adab64, req->slen 228, sg_dma_len(sg) 228
 648   [  409.203235] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, dst_addr 21ee3dc000, nr_sgs 1, req->dst 000000004e2990d0, req->dlen 4096, sg_dma_len(sg) 4096
 649   [  409.203239] idxd 0000:e7:02.0: iaa_decompress: desc->src1_addr 21ddd8b100, desc->src1_size 228, desc->dst_addr 21ee3dc000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0
 650   [  409.203254] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, src_addr 21ddd8b100, nr_sgs 1, req->src 0000000084adab64, req->slen 228, sg_dma_len(sg) 228
 651   [  409.203256] idxd 0000:e7:02.0: iaa_comp_adecompress: dma_map_sg, dst_addr 21f1551000, nr_sgs 1, req->dst 000000004e2990d0, req->dlen 4096, sg_dma_len(sg) 4096
 652   [  409.203257] idxd 0000:e7:02.0: iaa_decompress: desc->src1_addr 21ddd8b100, desc->src1_size 228, desc->dst_addr 21f1551000, desc->max_dst_size 4096, desc->src2_addr 0, desc->src2_size 0
 653
 654 In order to unregister the IAA crypto algorithms, and register new
 655 ones using different parameters, any users of the current algorithm
 656 should be stopped and the IAA workqueues and devices disabled.
 657
 658 In the case of zswap, remove the IAA crypto algorithm as the
 659 compressor and turn off swap (to remove all references to
 660 iaa_crypto)::
 661
 662   echo lzo > /sys/module/zswap/parameters/compressor
 663   swapoff -a
 664
 665   echo 0 > /sys/module/zswap/parameters/accept_threshold_percent
 666   echo 0 > /sys/module/zswap/parameters/max_pool_percent
 667   echo 0 > /sys/module/zswap/parameters/enabled
 668
 669 Once zswap is disabled and no longer using iaa_crypto, the IAA wqs and
 670 devices can be disabled.
 671
 672 .. _iaa_disable_script:
 673
 674 IAA disable script
 675 ------------------
 676
 677 The below script automatically does that::
 678
 679   #!/bin/bash
 680
 681   echo "IAA devices:"
 682   lspci -d:0cfe
 683   echo "# IAA devices:"
 684   lspci -d:0cfe | wc -l
 685
 686   #
 687   # count iaa instances
 688   #
 689   iaa_dev_id="0cfe"
 690   num_iaa=$(lspci -d:${iaa_dev_id} | wc -l)
 691   echo "Found ${num_iaa} IAA instances"
 692
 693   #
 694   # disable iaa wqs and devices
 695   #
 696   echo "Disable IAA"
 697
 698   for ((i = 1; i < ${num_iaa} * 2; i += 2)); do
 699       echo disable wq iax${i}/wq${i}.0
 700       accel-config disable-wq iax${i}/wq${i}.0
 701       echo disable iaa iax${i}
 702       accel-config disable-device iax${i}
 703   done
 704
 705   echo "End Disable IAA"
 706
 707 Finally, at this point the iaa_crypto module can be removed, which
 708 will unregister the current IAA crypto algorithms::
 709
 710   rmmod iaa_crypto
 711
 712
 713 memory_madvise.c (gcc -o memory_memadvise memory_madvise.c)::
 714
 715   #include <stdio.h>
 716   #include <stdlib.h>
 717   #include <string.h>
 718   #include <unistd.h>
 719   #include <sys/mman.h>
 720   #include <linux/mman.h>
 721
 722   #ifndef MADV_PAGEOUT
 723   #define MADV_PAGEOUT    21      /* force pages out immediately */
 724   #endif
 725
 726   #define PG_SZ           4096
 727
 728   int main(int argc, char **argv)
 729   {
 730         int i, nr_pages = 1;
 731         int64_t *dump_ptr;
 732         char *addr, *a;
 733         int loop = 1;
 734
 735         if (argc > 1)
 736                 nr_pages = atoi(argv[1]);
 737
 738         printf("Allocating %d pages to swap in/out\n", nr_pages);
 739
 740         /* allocate pages */
 741         addr = mmap(NULL, nr_pages * PG_SZ, PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0);
 742         *addr = 1;
 743
 744         /* initialize data in page to all '*' chars */
 745         memset(addr, '*', nr_pages * PG_SZ);
 746
 747          printf("Swapping out %d pages\n", nr_pages);
 748
 749         /* Tell kernel to swap it out */
 750         madvise(addr, nr_pages * PG_SZ, MADV_PAGEOUT);
 751
 752         while (loop > 0) {
 753                 /* Wait for swap out to finish */
 754                 sleep(5);
 755
 756                 a = addr;
 757
 758                 printf("Swapping in %d pages\n", nr_pages);
 759
 760                 /* Access the page ... this will swap it back in again */
 761                 for (i = 0; i < nr_pages; i++) {
 762                         if (a[0] != '*') {
 763                                 printf("Bad data from decompress!!!!!\n");
 764
 765                                 dump_ptr = (int64_t *)a;
 766                                  for (int j = 0; j < 100; j++) {
 767                                         printf("  page %d data: %#llx\n", i, *dump_ptr);
 768                                         dump_ptr++;
 769                                 }
 770                         }
 771
 772                         a += PG_SZ;
 773                 }
 774
 775                 loop --;
 776         }
 777
 778        printf("Swapped out and in %d pages\n", nr_pages);
 779
 780 Appendix
 781 ========
 782
 783 .. _iaa_sysfs_config:
 784
 785 IAA sysfs config interface
 786 --------------------------
 787
 788 Below is a description of the IAA sysfs interface, which as mentioned
 789 in the main document, should only be used if you know exactly what you
 790 are doing.  Even then, there's no compelling reason to use it directly
 791 since accel-config can do everything the sysfs interface can and in
 792 fact accel-config is based on it under the covers.
 793
 794 The 'IAA config path' is /sys/bus/dsa/devices and contains
 795 subdirectories representing each IAA device, workqueue, engine, and
 796 group.  Note that in the sysfs interface, the IAA devices are actually
 797 named using iax e.g. iax1, iax3, etc. (Note that IAA devices are the
 798 odd-numbered devices; the even-numbered devices are DSA devices and
 799 can be ignored for IAA).
 800
 801 The 'IAA device bind path' is /sys/bus/dsa/drivers/idxd/bind and is
 802 the file that is written to enable an IAA device.
 803
 804 The 'IAA workqueue bind path' is /sys/bus/dsa/drivers/crypto/bind and
 805 is the file that is written to enable an IAA workqueue.
 806
 807 Similarly /sys/bus/dsa/drivers/idxd/unbind and
 808 /sys/bus/dsa/drivers/crypto/unbind are used to disable IAA devices and
 809 workqueues.
 810
 811 The basic sequence of commands needed to set up the IAA devices and
 812 workqueues is:
 813
 814 For each device::
 815   1) Disable any workqueues enabled on the device.  For example to
 816      disable workques 0 and 1 on IAA device 3::
 817
 818        # echo wq3.0 > /sys/bus/dsa/drivers/crypto/unbind
 819        # echo wq3.1 > /sys/bus/dsa/drivers/crypto/unbind
 820
 821   2) Disable the device. For example to disable IAA device 3::
 822
 823        # echo iax3 > /sys/bus/dsa/drivers/idxd/unbind
 824
 825   3) configure the desired workqueues.  For example, to configure
 826      workqueue 3 on IAA device 3::
 827
 828        # echo dedicated > /sys/bus/dsa/devices/iax3/wq3.3/mode
 829        # echo 128 > /sys/bus/dsa/devices/iax3/wq3.3/size
 830        # echo 0 > /sys/bus/dsa/devices/iax3/wq3.3/group_id
 831        # echo 10 > /sys/bus/dsa/devices/iax3/wq3.3/priority
 832        # echo "kernel" > /sys/bus/dsa/devices/iax3/wq3.3/type
 833        # echo "iaa_crypto" > /sys/bus/dsa/devices/iax3/wq3.3/name
 834        # echo "crypto" > /sys/bus/dsa/devices/iax3/wq3.3/driver_name
 835
 836   4) Enable the device. For example to enable IAA device 3::
 837
 838        # echo iax3 > /sys/bus/dsa/drivers/idxd/bind
 839
 840   5) Enable the desired workqueues on the device.  For example to
 841      enable workques 0 and 1 on IAA device 3::
 842
 843        # echo wq3.0 > /sys/bus/dsa/drivers/crypto/bind
 844        # echo wq3.1 > /sys/bus/dsa/drivers/crypto/bind