dr_reconfig System Call

Purpose

Determines the nature of the DLPAR request.

Syntax

#include <sys/dr.h>

int dr_reconfig (flags, dr_info)
int flags;
dr_info_t *dr_info;

Description

The dr_reconfig system call is used by DLPAR-aware applications to adjust their use of resources in relation to a DLPAR request. Applications are notified about the usage through the SIGRECONFIG signal, which is generated three times for each DLPAR event.

The first time is to check with the application whether the DLPAR event should be continued. Using the DR_EVENT_FAIL flag, an application can indicate that the operation should be aborted, if it is not DLPAR-safe and its operation is considered vital to the system.

The application is notified the second time before the resource is added or removed, and the third time afterwards. Applications must attempt to control their scheduling priority and policy to guarantee timely delivery of signals. The system does not guarantee that every signal that is sent is delivered before advancing to the next step in the algorithm.

The dr_reconfig system call can also be used to notify applications about the changes to the workload partition that they are running. Applications are notified about changes to the CPU, memory capacity, and resources set.

The dr_reconfig interface is signal-handler safe and can be used by multi-threaded programs.

The dr_info structure is declared within the address space of the application. The kernel fills out data in this structure relative to the current DLPAR request. The user passes this structure identifying the current DLPAR request, as a parameter to the kernel when the DR_RECONFIG_DONE flag is used. The DR_RECONFIG_DONE flag is used by the application to notify the kernel that necessary action to adjust their use of resources has been taken in response to the SIGRECONFIG signal sent to them. It is expected that the signal handler associated with the SIGRECONFIG signal calls the interface with the DR_QUERY flag to identify the phase of the DLPAR event, takes the appropriate action, and calls the interface with the DR_RECONFIG_DONE flag to indicate to the kernel that the signal has been handled. This type of acknowledgment to the kernel in each of the DLPAR phases enables a DLPAR event to perform efficiently.

With the addition of new fields to the dr_info structure, DR-aware applications can support the Micro-Partitioning® feature.

The plock and pshm bits are only set, if the request is to remove memory and the process has plock memory or is attached to a pinned shared memory segment. If the plock bit is set, the process callsplock to unpin itself. If the pshm bit is set, the application has pinned shared memory segments, which may need to be detached. The memory remove request can succeed in any case, if there is enough pinnable memory in the system, so an action in this case is not necessarily required. The field sys_pinnable_frames provides this information, however, this value and other statistical values are just approximations. They reflect the state of the system at the time of the request. They are not updated during the request. The current size of physical memory can be determined by referencing the _system_configuration.physmem field.

To provide support for virtual real memory related DR operations, a new field, dr_op, has been added to the dr_info structure. The dr_op field provides information about the current DR operation. Additionally, all future DR operations use this field and the previously used resource bits will no longer be extended.

dr_wlm_info Structure

typedef struct dr_wlm_info {
		unsigned int cpu_add : 1; // cpu wlm resource add for the WPAR
		unsigned int cpu_rem : 1; // cpu wlm resource remove for the WPAR
		unsigned int mem_add : 1; // memory wlm resource add for the WPAR
		unsigned int mem_rem : 1; // memory wlm resource remove for the WPAR
		unsigned int rs_cpu  : 1; // wlm cpu rset change for the WPAR
		unsigned int rs_mem  : 1; // wlm memory rset change for the WPAR
		unsigned int pad1    : 2; // un-used 
		unsigned int cpu_cap : 8; // percentage of cpu capacity of the WPAR
		unsigned int mem_cap : 8; // percentage of the memory capacity of the WPAR
		unsigned int pad2    : 8; // un-used 
} dr_wlm_info_t;

dr_info Structure

typedef struct dr_info {
	 unsigned int add : 1;	// add request
	              rem : 1;	// remove request
	              cpu : 1;	// target resource is a cpu
	              mem : 1;	// target resource is memory
	            check : 1;	// check phase in effect
	              pre : 1;	// pre phase in effect
	             post : 1;	// post phase in effect
	        posterror : 1;	// post error phase in effect
	            force : 1;	// force option is in effect
	         bindproc : 1;	// process has bindprocessor dependency
	         softpset : 1;	// process has WLM software partition dependency
	         hardpset : 1;	// process has processor set API dependency
	            plock : 1;	// process has plock'd memory
	             pshm : 1;	// process has pinned shared memory
	          ent_cap : 1;	// target resource:entitled capacity
	          var_wgt : 1;	// target resource:variable weight
	   splpar_capable : 1;	// 1/0 partition is/not splpar capable
	    splpar_shared : 1;	// 1/0 partition shared/dedicated mode
	    splpar_capped : 1;	// 1/0 partition capped/uncapped mode
       splpar_constrained : 1;  // Set to 1 if requested capacity
	                           update is constrained by PHYP to
	                           be within partition capacity bounds.
	                        // 

    unsigned int migrate : 1;    // migration operation
    unsigned int hibernate : 1;    // hibernation operation
    unsigned int partition : 1;    // resource is partition
    unsigned int topology_update : 1;	// topology update

    // The following fields are filled out for cpu based requests
    int lcpu;			// logical cpu ID being added or removed
    int bcpu;			// bind cpu ID being added or removed

    // The following fields are filled out for memory based requests
    size64_t  req_memsz_change;     // User request size in bytes            
    size64_t  sys_memsz;            // System Memory size at time of request 
    rpn64_t   sys_free_frames;      // Number of free frames in the system
    rpn64_t   sys_pinnable_frames;  // Number of pinnable frames in system
    rpn64_t   sys_total_frames;     // Total number of frames in system 


    // SPLPAR parameters.
    uint64_t  capacity;			// partition current entitled capacity
                                           if ent_cap bit is set, partition's
                                           current variable capacity weight
                                           if var_wgt bit is set.
                                        // 

    int	  delta_cap;		   	// delta capacity added/removed to
                                           current value depending on add/rem
                                           bit flag value above
                                        // 
    dr_wlm_info_t   dr_wlm;     // DR info for the WPAR    
    ushort	    dr_op;	 // type of DR operation

    ushort	    dr_pad;     // reserved pad field
    size64_t	    mem_capacity; // partition’s entitled 
I/O memory or variable capacity.
    ssize64_t   delta_mem_capacity; // amount of I/O being added/removed

    int  reserved[2];

} dr_info_t;

Parameters

Return Values

Upon success, the dr_reconfig system call returns a zero. If unsuccessful, it returns negative one and sets the errno variable to the appropriate error value.

Error Codes