Intel® Communications Chipset 8900 to 8920 Series Software Programmer's Guide March 2015 Order No.: 330753-003 You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Intel products described herein. You agree to grant Intel a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein. No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document. All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest Intel product specifications and roadmaps. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Copies of documents which have an order number and are referenced in this document may be obtained by calling 1-800-548-4725 or visit http:// www.intel.com/design/literature.htm. Any software source code reprinted in this document is furnished for informational purposes only and may only be used or copied and no license, express or implied, by estoppel or otherwise, to any of the reprinted source code is granted by this document. Basis, Basis Peak, BlueMoon, BunnyPeople, Celeron, Centrino, Cilk, Curie, Flexpipe, Intel, the Intel logo, the Intel Anti-Theft technology logo, Intel AppUp, the Intel AppUp logo, Intel Atom, Intel CoFluent, Intel Core, Intel Inside, the Intel Inside logo, Intel Insider, Intel RealSense, Intel SingleDriver, Intel SpeedStep, Intel vPro, Intel Xeon Phi, Intel XScale, InTru, the InTru logo, the InTru Inside logo, InTru soundmark, Iris, Itanium, Kno, Look Inside., the Look Inside. logo, Mashery, MCS, MMX, Pentium, picoArray, Picochip, picoXcell, Puma, Quark, SMARTi, smartSignaling, Sound Mark, Stay With It, the Engineering Stay With It logo, The Creators Project, The Journey Inside, Thunderbolt, the Thunderbolt logo, Transcede, Ultrabook, VTune, Xeon, X-GOLD, XMM, X-PMU and XPOSYS are trademarks of Intel Corporation in the U.S. and/or other countries. *Other names and brands may be claimed as the property of others. Copyright © 2010–2015, Intel Corporation. All rights reserved. Intel® Communications Chipset 8900 to 8920 Series Software Programmer's Guide March 2015 2 Order No.: 330753-003 Revision History—Intel® Communications Chipset 8900 to 8920 Series Software Revision History Date Revision Description March 2015 003 Updates include: • Added Intel QuickAssist Technology Entries in the /proc Filesystem on page 41 • Added How to Call the Heartbeat Query on page 46 • Updated Build Flag Summary on page 61 • Added Acceleration Driver Return Codes on page 66 • Updated Dynamic Instance Configuration Example on page 76 • Updated Maximum Number of Process Calculations on page 78 and Resubmitting After Getting an Overflow Error on page 99 December 002 Updates include: 2014 • Added Intel QuickAssist Technology Compression API Errors on page 52 • Updated Intel QuickAssist Technology API Limitations on page 97 • Added Resubmitting After Getting an Overflow Error on page 99 • Added new APIs to Dynamic Instance Allocation Functions on page 106 • Updated Reset Device Function on page 131 • Added Thread-less APIs on page 132 • Other general updates. July 2014 001 Updates include: • First “public” version of the document. Based on “Intel Confidential” document number 441782-1.8 with the revision history of that document retained for reference purposes. May 2014 1.8 Updates include: • Added Compiling with Debug Symbols on page 65 March 2014 1.7 Updates include: • Added new information to "direct user space access" bullet in Acceleration Drivers Overview on page 27 • Added further detail to note in Hardware Assisted Rings on page 27 • Updated Linux* Software Context for Acceleration Drivers on page 29 • Added Stateless Compression Level Details on page 58 • Added support for the PF/VF concurrency for SRIOV_Enabled in General Parameters on page 69 • Added Dynamic Compression for Data Compression Service on page 100, Maximal Expansion with Auto Select Best Feature for Data Compression Service on page 100, and Maximal Expansion and Destination Buffer Size December 1.6 Updates include: 2013 • Added new information to Intel QuickAssist Technology API Limitations on page 97 • Added Running Applications as Non-Root User on page 63 • Added Compiling Acceleration Software on Older Kernels on page 65 • Changed document and software title to specify chipset SKU range. • Other minor updates. August 2013 1.5 Updates include: • Added #unique_27 continued... Intel® Communications Chipset 8900 to 8920 Series Software March 2015 Programmer's Guide Order No.: 330753-003 3 Intel® Communications Chipset 8900 to 8920 Series Software—Revision History Date Revision Description • Removed two stateful compression/decompression limitations from Intel QuickAssist Technology API Limitations on page 97 • Added new NRBG and DRBG support information to Random Number Generation Functions on page 120 June 2013 1.4 Updates for software release 1.3.0: • Added Support for Multiple Acceleration Hardware Generations on page 24 • Added Compression Status Codes on page 52 • Updated Stateful Compression - Dealing with Error Code CPA_DC_BAD_LITLEN_CODES (-7) on page 53 and subsections • Added Stateful Compression Level Details on page 57 • Updated Build Flag Summary on page 61 to add ICP_TRACE option • Updated icp_sal_CyPollInstance on page 117 • Updated icp_sal_DcPollInstance on page 118 March 2013 1.3 Updates for software release 1.2.0: • In General Parameters, added SRIOV_Enable and PF_bundle_offset • Added [DYN] Section • Updated Sample Configuration File (V2) • Added Driver Threading Model • Added Stateful Compression - Dealing with Error Code CPA_DC_BAD_LITLEN_CODES (-7) • Added Acceleration Driver Error Scenarios • Added Build Flag Summary • Added Dynamic Instance Allocation Functions • Added IOMMU Remapping Functions December 1.2 Updates for software release 1.1.0: 2012 • Updated Heartbeat Feature and Recovery from Hardware Errors • Added User Proc Entry Read (not Enabled by Default) • Added User Application Heartbeat APIs (not Enabled by Default) • Updated Intel QuickAssist Technology API Limitations to better clarify autoSelectBest behavior for static compression service • Added GbE Watchdog Service • Added Special Considerations When Using the Heartbeat Feature and GbE • Added icp_sal_drbgGetInstance • Updated DRBG Health Test and cpaCyDrbgSessionInit Implementation Detail • Added User Space Heartbeat Functions October 2012 1.1 Updates for software release 1.0.1: • Added Heartbeat Feature and Recovery from Hardware Errors • Updated General Parameters • Updated Cryptographic Logical Instance Parameters • Updated Data Compression Logical Instance Parameters • Added DRBG HealthTest and cpaCyDrbgSessionInit Implemenation Detail September 1.0 Corresponds with software release 1.0.0 2012 Intel® Communications Chipset 8900 to 8920 Series Software Programmer's Guide March 2015 4 Order No.: 330753-003 Contents—Intel® Communications Chipset 8900 to 8920 Series Software Contents Revision History..................................................................................................................3 Part 1: Overview............................................................................12 1.0 Introduction................................................................................................................13 1.1 Terminology.........................................................................................................13 1.2 Document Organization......................................................................................... 13 1.3 Product Documentation......................................................................................... 13 1.4 Typographical Conventions.....................................................................................14 2.0 Platform Overview...................................................................................................... 15 2.1 Platform Synopsis................................................................................................. 15 2.2 Determining the PCH SKU Type.............................................................................. 17 2.3 Determining the PCH Device Stepping..................................................................... 19 3.0 Software Overview..................................................................................................... 20 3.1 High-Level Software Architecture Overview.............................................................. 20 3.2 Logical Instances.................................................................................................. 22 3.2.1 Response Processing................................................................................. 22 3.2.1.1 Interrupt Mode............................................................................. 22 3.2.1.2 Polled Mode..................................................................................23 3.3 Operating System Support..................................................................................... 24 3.4 OpenSSL* Library Inclusion and Usage.................................................................... 24 3.5 Support for Multiple Acceleration Hardware Generations.............................................24 Part 2: