Documentation/ABI/testing/sysfs-driver-qat_rl

   1 What:           /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
   2 Date:           January 2024
   3 KernelVersion:  6.7
   4 Contact:        qat-linux@intel.com
   5 Description:
   6                 (WO) This attribute is used to perform an operation on an SLA.
   7                 The supported operations are: add, update, rm, rm_all, and get.
   8
   9                 Input values must be filled through the associated attribute in
  10                 this group before a write to this file.
  11                 If the operation completes successfully, the associated
  12                 attributes will be updated.
  13                 The associated attributes are: cir, pir, srv, rp, and id.
  14
  15                 Supported operations:
  16
  17                 * add: Creates a new SLA with the provided inputs from user.
  18                         * Inputs: cir, pir, srv, and rp
  19                         * Output: id
  20
  21                 * get: Returns the configuration of the specified SLA in id attribute
  22                         * Inputs: id
  23                         * Outputs: cir, pir, srv, and rp
  24
  25                 * update: Updates the SLA with new values set in the following attributes
  26                         * Inputs: id, cir, and pir
  27
  28                 * rm: Removes the specified SLA in the id attribute.
  29                         * Inputs: id
  30
  31                 * rm_all: Removes all the configured SLAs.
  32                         * Inputs: None
  33
  34                 This attribute is only available for qat_4xxx devices.
  35
  36 What:           /sys/bus/pci/devices/<BDF>/qat_rl/rp
  37 Date:           January 2024
  38 KernelVersion:  6.7
  39 Contact:        qat-linux@intel.com
  40 Description:
  41                 (RW) When read, reports the current assigned ring pairs for the
  42                 queried SLA.
  43                 When wrote to, configures the ring pairs associated to a new SLA.
  44
  45                 The value is a 64-bit bit mask and is written/displayed in hex.
  46                 Each bit of this mask represents a single ring pair i.e.,
  47                 bit 1 == ring pair id 0; bit 3 == ring pair id 2.
  48
  49                 Selected ring pairs must to be assigned to a single service,
  50                 i.e. the one provided with the srv attribute. The service
  51                 assigned to a certain ring pair can be checked by querying
  52                 the attribute qat/rp2srv.
  53
  54                 The maximum number of ring pairs is 4 per SLA.
  55
  56                 Applicability in sla_op:
  57
  58                 * WRITE: add operation
  59                 * READ: get operation
  60
  61                 Example usage::
  62
  63                         ## Read
  64                         # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
  65                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp
  66                         0x5
  67
  68                         ## Write
  69                         # echo 0x5 > /sys/bus/pci/devices/<BDF>/qat_rl/rp
  70
  71                 This attribute is only available for qat_4xxx devices.
  72
  73 What:           /sys/bus/pci/devices/<BDF>/qat_rl/id
  74 Date:           January 2024
  75 KernelVersion:  6.7
  76 Contact:        qat-linux@intel.com
  77 Description:
  78                 (RW) If written to, the value is used to retrieve a particular
  79                 SLA and operate on it.
  80                 This is valid only for the following operations: update, rm,
  81                 and get.
  82                 A read of this attribute is only guaranteed to have correct data
  83                 after creation of an SLA.
  84
  85                 Applicability in sla_op:
  86
  87                 * WRITE: rm and update operations
  88                 * READ: add and get operations
  89
  90                 Example usage::
  91
  92                         ## Read
  93                         ## Set attributes e.g. cir, pir, srv, etc
  94                         # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
  95                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/id
  96                         4
  97
  98                         ## Write
  99                         # echo 7 > /sys/bus/pci/devices/<BDF>/qat_rl/id
 100                         # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 101                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/rp
 102                         0x5  ## ring pair ID 0 and ring pair ID 2
 103
 104                 This attribute is only available for qat_4xxx devices.
 105
 106 What:           /sys/bus/pci/devices/<BDF>/qat_rl/cir
 107 Date:           January 2024
 108 KernelVersion:  6.7
 109 Contact:        qat-linux@intel.com
 110 Description:
 111                 (RW) Committed information rate (CIR). Rate guaranteed to be
 112                 achieved by a particular SLA. The value is expressed in
 113                 permille scale, i.e. 1000 refers to the maximum device
 114                 throughput for a selected service.
 115
 116                 After sending a "get" to sla_op, this will be populated with the
 117                 CIR for that queried SLA.
 118                 Write to this file before sending an "add/update" sla_op, to set
 119                 the SLA to the specified value.
 120
 121                 Applicability in sla_op:
 122
 123                 * WRITE: add and update operations
 124                 * READ: get operation
 125
 126                 Example usage::
 127
 128                         ## Write
 129                         # echo 500 > /sys/bus/pci/devices/<BDF>/qat_rl/cir
 130                         # echo "add" /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 131
 132                         ## Read
 133                         # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
 134                         # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 135                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/cir
 136                         500
 137
 138                 This attribute is only available for qat_4xxx devices.
 139
 140 What:           /sys/bus/pci/devices/<BDF>/qat_rl/pir
 141 Date:           January 2024
 142 KernelVersion:  6.7
 143 Contact:        qat-linux@intel.com
 144 Description:
 145                 (RW) Peak information rate (PIR). The maximum rate that can be
 146                 achieved by that particular SLA. An SLA can reach a value
 147                 between CIR and PIR when the device is not fully utilized by
 148                 requests from other users (assigned to different SLAs).
 149
 150                 After sending a "get" to sla_op, this will be populated with the
 151                 PIR for that queried SLA.
 152                 Write to this file before sending an "add/update" sla_op, to set
 153                 the SLA to the specified value.
 154
 155                 Applicability in sla_op:
 156
 157                 * WRITE: add and update operations
 158                 * READ: get operation
 159
 160                 Example usage::
 161
 162                         ## Write
 163                         # echo 750 > /sys/bus/pci/devices/<BDF>/qat_rl/pir
 164                         # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 165
 166                         ## Read
 167                         # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
 168                         # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 169                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/pir
 170                         750
 171
 172                 This attribute is only available for qat_4xxx devices.
 173
 174 What:           /sys/bus/pci/devices/<BDF>/qat_rl/srv
 175 Date:           January 2024
 176 KernelVersion:  6.7
 177 Contact:        qat-linux@intel.com
 178 Description:
 179                 (RW) Service (SRV). Represents the service (sym, asym, dc)
 180                 associated to an SLA.
 181                 Can be written to or queried to set/show the SRV type for an SLA.
 182                 The SRV attribute is used to specify the SRV type before adding
 183                 an SLA. After an SLA is configured, reports the service
 184                 associated to that SLA.
 185
 186                 Applicability in sla_op:
 187
 188                 * WRITE: add and update operations
 189                 * READ: get operation
 190
 191                 Example usage::
 192
 193                         ## Write
 194                         # echo "dc" > /sys/bus/pci/devices/<BDF>/qat_rl/srv
 195                         # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 196                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/id
 197                         4
 198
 199                         ## Read
 200                         # echo 4 > /sys/bus/pci/devices/<BDF>/qat_rl/id
 201                         # echo "get" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 202                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/srv
 203                         dc
 204
 205                 This attribute is only available for qat_4xxx devices.
 206
 207 What:           /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
 208 Date:           January 2024
 209 KernelVersion:  6.7
 210 Contact:        qat-linux@intel.com
 211 Description:
 212                 (RW) This file will return the remaining capability for a
 213                 particular service/sla. This is the remaining value that a new
 214                 SLA can be set to or a current SLA can be increased with.
 215
 216                 Example usage::
 217
 218                         # echo "asym" > /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
 219                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
 220                         250
 221                         # echo 250 > /sys/bus/pci/devices/<BDF>/qat_rl/cir
 222                         # echo "add" > /sys/bus/pci/devices/<BDF>/qat_rl/sla_op
 223                         # cat /sys/bus/pci/devices/<BDF>/qat_rl/cap_rem
 224                         0
 225
 226                 This attribute is only available for qat_4xxx devices.