detach()

	int detach(dev_info_t *dip, ddi_detach_cmd_t cmd);

To process the DDI_SUSPEND command, detach(9E) must do the following:

• Wait until outstanding operations have completed (or abort them if they can be restarted).

• Block further operations from being initiated until the device is resumed (except for dump(9E) requests).

• Cancel pending callouts.

• Save any volatile hardware state to memory. The state includes the contents of device registers, but may also include downloaded firmware.

If, for some reason, the driver is not able to suspend the device and save its state to memory, then it must return DDI_FAILURE, and the framework aborts the system power management operation.

Dump requests must be honored. The framework uses the dump(9E) entry point to write out the state file containing the contents of memory. See dump(9E) for restrictions imposed on the device driver when using this entry point.

The entry point dump(9E) was previously used only for writing kernel crash dumps to disk. It is now also used to write out the state file containing the information necessary to restore the system to its state prior to a system power management suspend.

If the device implements a power-manageable component zero, the device may already have been suspended and powered off using the command DDI_PM_SUSPEND when its detach(9E) entry point is called with the DDI_SUSPEND command. The additional processing necessary in this case is to cancel pending timeouts and suppress the call to ddi_dev_is_needed(9F) until the device is resumed by a call to attach(9E) with a command of DDI_RESUME. The driver must keep sufficient track of its state to be able to deal appropriately with this possibility.

Example 8-4 shows an example of a detach(9E) routine with the DDI_SUSPEND command implemented.

Example 8-4 detach(9E) Routine Showing the Use of DDI_SUSPEND

int
xxdetach(devinfo_t *dip, ddi_detach_cmd_t cmd)
{
 	struct xxstate *xsp;
	 int	instance;

 	instance = ddi_get_instance(dip);
 	xsp = ddi_get_soft_state(statep, instance);

 	switch (cmd) {
 	case DDI_DETACH:
	   	see chapter 5, Autoconfiguration for discussion

 	case DDI_SUSPEND:
	  	   mutex_enter(&xsp->mu);
	  	   xsp->xx_suspended = 1;	/* stop new operations */
	  	   if (!xsp->xx_pm_suspended) {
			   /*
			    * This code assumes that we'll get a cv_broadcast when
			    * we're no longer busy
			    */
			   while(xsp->xx_busy)	/* wait for pending ops */
					   cv_wait(&xsp->xx_busy_cv, &xsp->mu);
			Save device register contents into xsp->xx_device_state
				/*
				 * If a callback is outstanding which cannot be 
				 * cancelled then either wait for the callback
				 * to complete or fail the suspend request
				 */
			this section is optional, only needed if the driver maintains a running 	
			timeout (but be sure to drop the  mutex in any case)
			   /* cancel timeouts */
			   if (xsp->xx_timeout_id) {
				    timeout_id_t temp_timeout_id = xsp->xx_timeout_id;
				
				    xsp->xx_timeout_id = 0;
				    mutex_exit(&xsp->mu);
				    untimeout(temp_timeout_id);
			   } else {
				    mutex_exit(&xsp->mu);
			   }
	     	} else {
			      mutex_exit(&xsp->mu);
	   	}
	  	  return(DDI_SUCCESS);
 	case DDI_PM_SUSPEND:
	    	see Example 8-2 
 	default:
	    	return(DDI_FAILURE);
 	}
}