LIBPAF-DSC(2)

NAME
libpaf-dsc - The Power Architecture Facilities Data Stream Control Library

SYNOPSIS
#include <paf/dsc.h>

uint64_t paf_dsc_check_support(void);

int paf_dsc_get(uint64_t *dscr);

int paf_dsc_set(uint64_t dscr);

Compile and link with -lpaf-dsc.

DESCRIPTION
The Power Architecture® Facilities Data Stream Control Library (libpaf-dsc) is a part of the Power Architecture Facilities Library (PAFLib) The Data Stream Control Library provides a mechanism to interact with the Data Stream Control Register (DSCR) available on Power Architecture. This register follows the layout specified in the corresponding Power ISA, with the following defined flags. These are features supported by Power ISA 2.05:

•   DSCR_SSE Store Stream Enable.

These features were added on Power ISA 2.06:

•   DSCR_SNSE Stride-N Stream Enable.

These features were added on Power ISA 2.06+:

•   DSCR_LSD Load Stream Disable.

These are supported only on Power ISA 2.07:

•   DSCR_HWUE Hardware Unit count Enable.

•   DSCR_SWUE Software Unit count Enable.

•   DSCR_LTE Load Transient Enable.

•   DSCR_STE Software Transient Enable.

•   DSCR_HTE Hardware Transient Enable.

•   DSCR_SWTE Software Transient Enable.

There are also other settings whose variable value can be accessed using the following macros:

DSCR_DPFD_GET(dscr)

DSCR_DPFD_SET(dscr,value)
    Default Prefetch Depth. This field supplies a prefetch depth for hardware-detected streams and for software-defined streams. The possible values for this field are the following:

•   0 default

•   1 none

•   2 shallowest

•   3 shallow

•   4 medium

•   5 deep

•   6 deeper

•   7 deepest

    This setting was introduced on Power ISA 2.05.

DSCR_URG_GET(dscr)

DSCR_URG_SET(dscr,value)
    Depth Attainment Urgency. This field indicates how quickly the prefetch depth should be reached for hardware-detected streams. These are the following possible values:

•   0 default

•   1 not urgent

•   2 least urgent

•   3 less urgent

•   4 medium

•   5 urgent

•   6 more urgent

•   7 most urgent

    This setting was added on Power ISA 2.06+.

DSCR_UNITCNT_GET(dscr)

DSCR_UNITCNT_SET(dscr,value)
    Number of units in data stream. This field can have a value between 0 and 1023. This setting was added on Power ISA 2.07.

For tips about how to use the macros above, see the section EXAMPLES.

The function paf_dsc_check_support() checks the available DSCR features, returning the bit flags and fields supported by the processor.

The function paf_dsc_get() retrieves the current DSCR content and copies to *dscr The function paf_dsc_set() sets the current DSCR content to dscr

RETURN VALUE
paf_dsc_check_support() returns a bitmask with the value of Data Stream Control Register or 0 if unsupported. paf_dsc_get() return 0 in case of success or -1 otherwise. paf_dsc_set() return 0 in case of success or -1 otherwise.

ERRORS

ENOSYS
    if the system does not support DSCR facility.

EXAMPLES

  Program source
#include <inttypes.h>
#include <paf/dsc.h>
#include <assert.h>
int main(void)
{
  uint64_t dscr, dscr_support;
  int dpfd_value;
  assert((dscr_support = paf_dsc_check_support()) > 0);
  /* Check if the system supports DSCR_SSE */
  if ((dscr_support | DSCR_SSE) == dscr_support)
    {
      assert(paf_dsc_get(&dscr) == 0);
      assert(paf_dsc_set(dscr | DSCR_SSE) == 0);
    }
  assert(paf_dsc_get(&dscr) == 0);
  /* Retrieve the current Default Prefetch Depth value */
  dpfd_value = DSCR_DPFD_GET(dscr);
  /* Check if the system supports DSCR_UNITCNT */
  if ((dscr_support | DSCR_UNITCNT_SET(dscr, 256)) == dscr_support)
    {
       dscr = DSCR_UNITCNT_SET(dscr, 256);
       assert(paf_dsc_set(dscr) == 0);
    }
  return 0;
}

NOTES
In order to check if the DSCR instructions are supported by the kernel, the library uses a signal handler for SIGILL during its initialization.

VERSIONS
The Data Stream Control Register (DSCR) [Category: Stream] is a Power Architecture hardware facility available since Power ISA 2.05 as privileged-state, and ISA 2.07 as problem-state, that affects how the processor handles hardware-detected and software-defined data streams. DSCR emulation on pre-ISA 2.07 hardware is provided in Linux Kernel 3.10-cr1. DSCR problem-state availability is exported in Linux Kernel 3.10-rc1.

REFERENCES

Power ISA™ Version 2.05

Power ISA™ Version 2.06

Power ISA™ Version 2.06+

Power ISA™ Version 2.07

REPORTING BUGS

Email bug reports to Edjunior B. Machado <emachado@linux.vnet.ibm.com>.

AUTHORS
This manual page was written by Edjunior B. Machado <emachado@linux.vnet.ibm.com> and Adhemerval Zanella <azanella@linux.vnet.ibm.com>.