dscr_ctl Subroutine

Purpose

Syntax

#include <sys/machine.h>

int dscr_ctl(int operation, void * buf_p, int size);

Description

The firmware provides a platform default value for the DSCR register. When the prefetch depth is set to 0 in the DSCR register, the processor uses this default value implicitly.

The dscr_ctl system call allows a privileged application to set an operating system default value for the DSCR, which overrides the platform default.

The dscr_ctl system call allows any application to set a per-process value for the DSCR register, which overrides the operating system default value for this process.

When a thread issues the dscr_ctl system call to change the prefetch depth for the process, the new value is written into the AIX® process context and the DSCR of the thread that runs the system call. If another thread in the process is simultaneously running on another processor, it starts using the new DSCR value only after the new value is reloaded from the process context.

When a thread starts running on a processor, the value of the DSCR for the owning process is written in the DSCR register. If the process has not set its DSCR value with the dscr_ctl system call, the operating system default value is used.

When the fork subroutine is called, the new process inherits the DSCR value from its parent process. This value gets reset to the system default value when the exec subroutine is called.

On systems which support programmatic setting of the DSCR through problem-state (user) access, such as POWER8, the value set by such access is thread-specific and overrides any other values, even the ones that are written through this service. In other words, problem-state manipulation of the DSCR provides for the finest granularity of access (per-thread) to the hardware streams functionality.

DPFD_DEFAULT            0
DPFD_NONE               1
DPFD_SHALLOWEST         2
DPFD_SHALLOW            3
DPFD_MEDIUM             4
DPFD_DEEP               5
DPFD_DEEPER             6
DPFD_DEEPEST            7

DSCR_SSE                1<<3
DSCR_SNSE               1<<4
DSCR_LSD                1<<5

URG_DEFAULT             0<<6
URG_NOT_URGENT          1<<6
URG_LEAST_URGENT        2<<6
URG_LEAST_URGENT        3<<6
URG_LESS_URGENT         4<<6
URG_MEDIUM              5<<6
URG_MORE_URGENT         6<<6
URG_MOST_URGENT         7<<6

DSCR_HWUE (1<<19)
DSCR_SWUE (1<<20)
DSCR_LTE  (1<<21)
DSCR_STE  (1<<22)
DSCR_HWTE (1<<23)
DSCR_SWTE (1<<24)

The following is the description of the dscr_properties structure in the <sys/machine.h> file:

struct dscr_properties {
      uint        version;             /* Properties struct version                   */
      uint        number_of_streams;   /* Number of hardware streams                  */
      long long   platform_default_pd; /* PFW default DSCR value                      */
      long long   os_default_pd;       /* AIX default DSCR value                      */
      int         dscr_version;        /* Architecture version, such as PowerISA 2.07 */
      uint        dscr_control;        /* System-wide DSCR control (read only)        */
      long long   dscr_smt[5];         /* DSCR/SMT Matrix                             */
      long long   dscr_mask;           /* Mask of valid bits per architecture version */
};

Depending on the version of the Instruction Set Architecture (ISA) for Power Systems servers supported by a specific AIX level on a specified hardware platform, only a subset of the bits previously shown might be supported.

Refer to the <sys/machine.h> header file for the definitions for the dscr_version field and the corresponding bits supported for each version.

#include <sys/machine.h>
int rc;
long long dscr = DSCR_SSE | DPFD_DEEPER;
rc = dscr_ctl(DSCR_WRITE, &dscr);

Parameters

Return Values

Error Codes

When the dscr_ctl subroutine fails, errno is set to one of the following values: