hpci_attach(D3hpci)

hpci_attach -- register the hot plug controller driver (HPCD) with the hot plug controller interface (HPCI)

Synopsis

   #include <sys/types.h>
   #include <sys/hpci.h>
   #include <sys/ddi.h>
   
   int hpci_attach(hpci_hpcd_t *hpcd_info);

Description

hpci_attach( ) registers the hot plug controller driver with the hot plug controller interface (HPCI).

Arguments

hpcd_info: pointer to an hpci_hpcd_t(D4hpci) structure.

Return values

On success, hpci_attach( ) returns a non-negative number that serves as a unique identifier for this instance. If resource allocation fails, the function returns -1.

Usage

hpci_attach( ) is called from the CFG_ADD subfunction of the HPCD driver's config(D2hpci) entry point routine to register the driver instance with HPCI. This enables HPCI to track all the hot plug sockets that are controlled by various HPCD drivers in the system and present them to the user applications to facilitate hot plug operations.

Before calling hpci_attach( ), the HPCD driver allocates all and initializes the data structures representing all hot plug busses, sockets, and any devices connected to hotplug sockets. The data representation of all this hot plug information forms a tree structure that leads from the HPCD information to the function information about each device connected to any hot plug socket that is controlled by this HPCD driver. The structures that represent the data for the hot plug controller, bus, socket, and device function information are documented in the Section D4hpci manual pages in Section D4hpci manual pages.

Context and synchronization

Blockable context

Hardware applicability

All

Version applicability

hpci: 1

References

hpci_detach(D3hpci), hpci_hpcd_t(D4hpci)

``Hotplug devices'' in HDK Technical Reference
``Device instance'' in HDK Technical Reference
``PCI'' in HDK Technical Reference

Examples

The following code example is a portion of a config(D2hpci) entry point routine that illustrates how hpci_attach( ) is called.

    1  typedef struct  _hpcd {
    2  	int			hpcid;
    3  	rm_key_t		key;
    4	hpci_hpcd_t             hpcd_info;
    5  } hpcd_t
   
    6  int
    7  xxx_config(cfg_funct_t func, void *idata, rm_key_t key)
    8  {
    9  	hpcd_t		*hpcdp;
   

   10  	switch(func)
   11  	{
   12  	    case CFG_ADD:
      
   13  		    hpcdp=kmem_zalloc(sizeof(hpcd_t), KM_SLEEP);
   

   		    /* set the resmgr key for this driver instance */
   14  		    hpcdp->key = key;
   

   		    /* save the instance data address for later use */
   15  		    hpcdp->hpcd_info.private = (void *) hpcdp;
   

   		    /* initialize controller; attach and enable interrupts */
   16		    init_controller(hpcdp);
   

   17		    hpcdp->hpcd_info_modify_callback = (hpci_op_t) hpcd_modify_callback;
   18		    hpcdp->hpcd_info.lock_callback= (hpcd_lock_op_t) hpcd_lock_callback;
   19		    hpcdp->hpcd_info.unlock_callback = (hpcd_unlock_op_t) hpcd_unlock_callback;
   

   20		    build_hotplug_info_tree(hpcdp);
   

   21		    if ((hpcdp->hpcid = hpci_attach(&hpcdp->hpcd_info)) <0)
   22                  {
   23			cmn_err(CE_WARN, "hpci_attach() failed \n");
   24			return -1;
   25                  }
   

   26		    *((void**)idata) = hpcdp;
   

   27		    break;

   28  	case CFG_xxx		/* handle other subfunctions */
   29		...
   30		break;
   
   31  	default:
   

   32		cmn_err(CE_WARN, "%s:xxxx_config: unexpected request 0x%x for rm_key=%d\n",
   33		modname,func,key);
   34		return(EINVAL);
   35  	}
   36 	return(0);
   37 }

Line 2: hpcid is the ID returned by the hpci_attach(D3hpci) function. It will later be used by the hpci_detach(D3hpci) function.
Line 3: rm_key_t is the resource manager key for this driver instance. See ``Resource manager database'' in HDK Technical Reference.
Line 4: Pointer to the hpci_hpcd_t(D4hpci) structure.
Line 7: Call the config(D2hpci) entry point routine. The CFG_ADD subfunction is called once for each supported hardware instance.
Line 13: Call the kmem_zalloc(D3) function to allocate memory for the hpcd_info structure.
Line 14: Set the resource manager key for this driver instance.
Line 15: Save the instance data address for later use.
Line 16: Initialize controller.
Lines 17-19: Attach and enable interrupts by populating the hpci_hpcd_t(D4hpci) structure with the names of the callback routines that are implemented by this HPCD driver. See the modify_callback(D2hpci), lock_callback(D2hpci), and unlock_callback(D2hpci) manual pages.
Line 20: Scan busses, sockets, and devices and build hot plug information tree.
Line 21: Call hpci_attach( ) to register this HPCD with HPCI and check the return value for errors.
Line 26: Pass the idata pointer for this driver instance back to the kernel.