SteveJay's Weblog
Sunday June 19, 2005
The 1394 Software Framework - Attach, Detach, and Events 
Continuing my discussion of the Solaris 1394 Software Framework, in this post I'm going to go into some detail on the methods by which a 1394 target driver can register and deregister itself with the core framework. And, in the process, I will also touch on the Solaris event notification mechanisms leveraged by the framework.
t1394_attach()
All 1394 target drivers must register themselves with the framework in order to operate properly. The 1394 framework will make an association with the device driver instance for the target and the corresponding HAL driver instance (called the 'parent') for the adapter to which it is attached.
In addition, the 1394 framework will allocate resources (internally) to track the target driver state (in the target driver 'handle') and return useful information about the current state of the target device on the 1394 bus and DMA and/or interrupt properties of the parent HAL.[1]
/*
* Function: t1394_attach()
* Input(s): dip The dip given to the target driver
* in it's attach() routine
* version The version of the target driver -
* T1394_VERSION_V1
* flags The flags parameter is unused (for now)
*
* Output(s): attachinfo Used to pass info back to target,
* including bus generation, local
* node ID, dma attribute, etc.
* t1394_hdl The target "handle" to be used for
* all subsequent calls into the
* 1394 Software Framework
*
* Description: t1394_attach() registers the target (based on its dip) with
* the 1394 Software Framework. It returns the bus_generation,
* local_nodeID, iblock_cookie and other useful information to
* the target, as well as a handle (t1394_hdl) that will be used
* in all subsequent calls into this framework.
*/
/* ARGSUSED */
int
t1394_attach(
dev_info_t *dip, /* supplied by the target */
int version, /* supplied by the target */
uint_t flags, /* supplied by the target */
t1394_attachinfo_t *attachinfo, /* filled in by the framework */
t1394_handle_t *t1394_hdl) /* returned to the target */
During a target driver's attach processing, it calls t1394_attach() to register with the 1394 Software Framework. The Framework initializes any necessary internal data structures and returns a t1394_hdl which the target driver uses with all other calls into the Framework. The Framework also returns additional information in attachinfo, which is needed by some target driver implementations.
Context:
Should be called only from base kernel context.Parameters:
- dip - Supplied by the target driver. The dip is the dev_info_t pointer for the target driver instance. Solaris provides this pointer to the target driver's own attach(9E) routine.
- version - Supplied by the target driver. Target drivers set this to T1394_VERSION_V1 to indicate this release of the 1394 Software Framework.
- flags - Supplied by the target driver. There are no flags defined in this release for t1394_attach(). Target drivers should specify a flags value of 0.
- attachinfo - The elements of this structure are filled in by the 1394 Framework and returned
to the target driver.
/* * t1394_attachinfo_t * is filled in and returned by the 1394 Framework at attach time * (returned from the call to t1394_attach()). This structure contains * the t1394_localinfo_t structure described above, as well as the * iblock cookie and the attributes necessary for DMA allocations, etc. */ typedef struct t1394_attachinfo_s { ddi_iblock_cookie_t iblock_cookie; ddi_device_acc_attr_t acc_attr; ddi_dma_attr_t dma_attr; t1394_localinfo_t localinfo; } t1394_attachinfo_t;- iblock_cookie - Depending on the implementation, a target driver might acquire a lock (mutex, rw_lock, cond_var, etc.) within a callback from the 1394 Framework. To ensure that the lock is initialized at the 1394 Framework's interrupt level for the callback, the target driver must call the corresponding lock's _init (e.g. mutex_init) with this interrupt block cookie. This way the lock will correctly mask interrupts at the appropriate level. (Failure to do this could result in deadlock or other nasty locking problems.)
- acc_attr - Depending on the implementation, a target driver might allocate and bind memory using the ddi_dma_* interfaces. To ensure that the device access attributes are set properly for use with the host controller hardware (i.e. the parent HAL), the target driver must use this acc_attr when calling ddi_dma_mem_alloc(9F) (See Mark Johnson's recent blog entry - "Solaris x86, Device DMA, and the DDI" if this is a topic that interests you.)[2]
- dma_attr - Depending on the implementation, a target driver might allocate and bind memory using the ddi_dma_* interfaces. To ensure that the device access attributes are set properly for use with the host controller hardware (i.e. the parent HAL), the target driver must use this dma_attr when calling ddi_dma_alloc_handle(9F)
- localinfo - This structure contains general information about the local device node.
A target driver may obtain specific information about its target device by calling t1394_get_targetinfo()
(which I'll talk about more in a later blog entry).
/* * t1394_localinfo_t * is filled in and returned by the 1394 Framework at attach time * (in the t1394_attachinfo_t structure returned from t1394_attach()) * to provide the local host nodeID and the current bus generation. */ typedef struct t1394_localinfo_s { uint_t bus_generation; uint_t local_nodeID; } t1394_localinfo_t; - bus_generation - Returned to the target driver. The 1394 Software Framework updates a counter each time an IEEE 1394 bus reset occurs. The bus_generation field contains the current generation count at the time of attach. A target driver which takes advantage of the Framework's automatic node addressing feature does not use bus_generation. A target driver which specifies the full 64-bit destination address for asynchronous commands uses bus_generation to safeguard against using stale addresses (from before the bus reset). When the generation count is updated, the Framework provides a new value in the DDI_DEVI_BUS_RESET_EVENT event call. (More on this below.)
- local_nodeID - Returned to the target driver. The local_nodeID is the current node ID for the local host hardware interface bus to which the target driver's 1394 device is attached. The high-order 16-bits are 0 and the low-order 16-bits contain the 10-bit bus number and the 6-bit node number. This is used by a target driver whose protocol requires the local host node ID to be embedded within data packets. A Serial Bus Protocol 2 (SBP-2) operation request block (ORB) is an example of a protocol structure that requires the local_nodeID.
- t1394_hdl - Returned to the target driver. A target driver must use this handle for each subsequent call into the 1394 Software Framework.
Return Values:
- DDI_SUCCESS
- DDI_FAILURE - returned if the associated device was removed from the 1394 bus before the registration could complete or if the 1394 Software Framework was unable to acquire the necessary resources of if version is not T1394_VERSION_V1.
t1394_detach()
Of course, for every registration a 1394 target driver should also deregister (when complete and detaching). This gives the Framework the opportunity to reclaim all the internally allocated resources that had been set aside for tracking the target state./* * Function: t1394_detach() * Input(s): t1394_hdl The target "handle" returned by * t1394_attach() * flags The flags parameter is unused (for now) * * Output(s): DDI_SUCCESS Target successfully detached * DDI_FAILURE Target failed to detach * * Description: t1394_detach() unregisters the target from the 1394 Software * Framework. t1394_detach() can fail if the target has any * allocated commands that haven't been freed. */ /* ARGSUSED */ int t1394_detach(t1394_handle_t *t1394_hdl, uint_t flags)
The target driver calls t1394_detach() to deregister from the 1394 Software Framework. Typically the target calls this from its detach(9E) routine.
Context:
Should be called only from base kernel context.Parameters:
- t1394_hdl - The target provides the address of the opaque handle which was assigned during t1394_attach, and the 1394 Framework frees the t1394_hdl.
- flags - Supplied by the target driver. There are no flags defined in this release for t1394_detach(). Target drivers should specify a flags value of 0.[3]
Return Values:
- DDI_SUCCESS
- DDI_FAILURE - returned if the the target driver has not freed all 1394 Framework resources, such as asynchronous command structures.
Events
Target drivers may register callbacks for general 1394 Software Framework events by using the Solaris Event Framework. All calls to the Event Framework must be performed before the call to t1394_attach() is performed. For details about the Solaris Event Framework, see:
- ddi_get_eventcookie(9F)
- ddi_add_event_handler(9F)
- ddi_remove_event_handler(9F)
The following events are supported by the 1394 Framework:
- DDI_DEVI_REMOVE_EVENT - The 1394 Software Framework triggers this event for a dip when the corresponding device is removed from the bus.
- DDI_DEVI_INSERT_EVENT - The 1394 Software Framework triggers this event for a dip when the corresponding device is removed from the bus.
- DDI_DEVI_BUS_RESET_EVENT - After a 1394 bus reset occurs, and after the 1394 Software Framework has determined 1394 node address mappings for devices on the bus, this event is triggered.
void (*handler)(dev_info_t *dip, ddi_eventcookie_t cookie, void *arg,
void *impl_data);
The callback impl_data provided to the eventcalls associated with each of these events is a t1394_localinfo_t *, as described above.
Note: Within an event callback function, a target driver shouldn't invoke any procedure that blocks or sleeps. For example, an event callback function shouldn't issue any outgoing asynch request that has the CMD1394_BLOCKING flag set. (Yep, again... more on this in a later blog entry).
And for next time?
OK. So obviously there's more I could say here about the details of Framework's implementation for tracking and coordinating target drivers and their events, but as I've said before that I want to first go through the Framework at a high-level.
Next time, I'm going to go over the outgoing asynch interfaces: command structure allocation, command completion mechanisms (event-driver, blocking, polling), command types (read, write, lock), quadlet requests, block requests, etc. That's a ton of stuff to cover, so maybe it won't all get into a single blog entry, but anyway that's where I'm headed next.
[1]Both t1394_attach() and t1394_detach() can be found in t1394.c
[2]I've worked with Mark for many years. He's a good guy, very bright, and he was one of us original four designers of the Solaris 1394 Software Framework. His contribution was essentially the entire OpenHCI-compliant HAL driver (hci1394).
[3]OK, so... flags. Why do we have it all over the place even though we don't often use it, you might be asking? Well the cynic among you might quote me some Emerson, but in reality this is more about our desire to be able to accomodate backwards compatibility. This goal of being able to have the design move forward and evolve, while still accomodating older versions of the software is part of Sun culture. It is an imperative of design in Solaris, especially for driver frameworks like theses. Of course, without more than one version of a framework like this (this one is essentially unchanged from when it was initially putback), a designer must consult a crystal ball (or draw on experience if you prefer). And sometimes you're gonna come up with flags that don't do anything (yet!)
(2005-06-19 09:16:00.0) Permalink
Comments are closed for this entry.