path: root/usr/src/man/man9f/ddi_soft_state.9f

'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DDI_SOFT_STATE 9F "Jan 16, 2006"
.SH NAME
ddi_soft_state, ddi_get_soft_state, ddi_soft_state_fini, ddi_soft_state_free,
ddi_soft_state_init, ddi_soft_state_zalloc \- driver soft state utility
routines
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBvoid *\fR\fBddi_get_soft_state\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_soft_state_fini\fR(\fBvoid\fR \fI**state_p\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_soft_state_free\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_soft_state_init\fR(\fBvoid\fR \fI**state_p\fR, \fBsize_t\fR \fIsize\fR, \fBsize_t\fR \fIn_items\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_soft_state_zalloc\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIstate_p\fR\fR
.ad
.RS 11n
Address of the opaque state pointer which will be initialized by
\fBddi_soft_state_init()\fR to point to implementation dependent data.
.RE

.sp
.ne 2
.na
\fB\fIsize\fR\fR
.ad
.RS 11n
Size of the item which will be allocated by subsequent calls to
\fBddi_soft_state_zalloc()\fR.
.RE

.sp
.ne 2
.na
\fB\fIn_items\fR\fR
.ad
.RS 11n
A hint of the number of items which will be preallocated; zero is allowed.
.RE

.sp
.ne 2
.na
\fB\fIstate\fR\fR
.ad
.RS 11n
An opaque pointer to implementation-dependent data that describes the soft
state.
.RE

.sp
.ne 2
.na
\fB\fIitem\fR\fR
.ad
.RS 11n
The item number for the state structure; usually the instance number of the
associated devinfo node.
.RE

.SH DESCRIPTION
.sp
.LP
Most device drivers maintain state information with each instance of the device
they control; for example, a soft copy of a device control register, a mutex
that must be held while accessing a piece of hardware, a partition table, or a
unit structure. These utility routines are intended to help device drivers
manage the space used by the driver to hold such state information.
.sp
.LP
For example, if the driver holds the state of each instance in a single state
structure, these routines can be used to dynamically allocate and deallocate a
separate structure for each instance of the driver as the instance is attached
and detached.
.sp
.LP
To use the routines, the driver writer needs to declare a state pointer,
\fIstate_p\fR, which the implementation uses as a place to hang a set of
per-driver structures; everything else is managed by these routines.
.sp
.LP
The routine \fBddi_soft_state_init()\fR is usually called in the driver's
\fB_init\fR(9E) routine to initialize the state pointer, set the size of the
soft state structure, and to allow the driver to pre-allocate a given number of
such structures if required.
.sp
.LP
The routine \fBddi_soft_state_zalloc()\fR is usually called in the driver's
\fBattach\fR(9E) routine.  The routine is passed an item number which is used
to refer to the structure in subsequent calls to \fBddi_get_soft_state()\fR and
\fBddi_soft_state_free()\fR. The item number is usually just the instance
number of the \fBdevinfo\fR node, obtained with \fBddi_get_instance\fR(9F). The
routine attempts to allocate space for the new structure, and if the space
allocation was successful, \fBDDI_SUCCESS\fR is returned to the caller.
Returned memory is zeroed.
.sp
.LP
A pointer to the space previously allocated for a soft state structure can be
obtained by calling \fBddi_get_soft_state()\fR with the appropriate item
number.
.sp
.LP
The space used by a given soft state structure can be returned to the system
using \fBddi_soft_state_free()\fR. This routine is usually called from the
driver's \fBdetach\fR(9E) entry point.
.sp
.LP
The space used by all the soft state structures allocated on a given state
pointer, together with the housekeeping information used by the implementation
can be returned to the system using \fBddi_soft_state_fini()\fR. This routine
can be called from the driver's \fB_fini\fR(9E) routine.
.sp
.LP
The \fBddi_soft_state_zalloc()\fR, \fBddi_soft_state_free()\fR and
\fBddi_get_soft_state()\fR routines coordinate access to the underlying data
structures in an MT-safe fashion, thus no additional locks should be necessary.
.SH RETURN VALUES
.sp
.LP
\fBddi_get_soft_state()\fR
.sp
.ne 2
.na
\fB\fINULL\fR\fR
.ad
.RS 11n
The requested state structure was not allocated at the time of the call.
.RE

.sp
.ne 2
.na
\fB\fIpointer\fR\fR
.ad
.RS 11n
The pointer to the state structure.
.RE

.sp
.LP
\fBddi_soft_state_init()\fR
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 10n
The allocation was successful.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
Either the \fBsize\fR parameter was zero, or the \fIstate_p\fR parameter was
invalid.
.RE

.sp
.LP
\fBddi_soft_state_zalloc()\fR
.sp
.ne 2
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
The allocation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
The routine failed to allocate the storage required; either the \fIstate\fR
parameter was invalid, the item number was negative, or an attempt was made to
allocate an item number that was already allocated.
.RE

.SH CONTEXT
.sp
.LP
The \fBddi_soft_state_init()\fR and \fBddi_soft_state_alloc()\fR functions can
be called from user or kernel context only, since they may internally call
\fBkmem_zalloc\fR(9F) with the \fBKM_SLEEP\fR flag.
.sp
.LP
The \fBddi_soft_state_fini()\fR, \fBddi_soft_state_free()\fR and
\fBddi_get_soft_state()\fR routines can be called from any driver context.
.SH EXAMPLES
.LP
\fBExample 1 \fRCreating and Removing Data Structures
.sp
.LP
The following example shows how the routines described above can be used in
terms of the driver entry points of a character-only driver. The example
concentrates on the portions of the code that deal with creating and removing
the driver's data structures.

.sp
.in +2
.nf
typedef struct {
   volatile caddr_t *csr;        /* device registers */
   kmutex_t         csr_mutex;   /* protects 'csr' field */
   unsigned int     state;
   dev_info_t       *dip;        /* back pointer to devinfo */
} devstate_t;
static void *statep;

int
_init(void)
{
   int error;

   error = ddi_soft_state_init(&statep, sizeof (devstate_t), 0);
   if (error != 0)
		   return (error);
   if ((error = mod_install(&modlinkage)) != 0)
		   ddi_soft_state_fini(&statep);
   return (error);
}

int
_fini(void)
{
   int error;

   if ((error = mod_remove(&modlinkage)) != 0)
		   return (error);
   ddi_soft_state_fini(&statep);
   return (0);
}

static int
xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
   int instance;
   devstate_t *softc;

   switch (cmd) {
   case DDI_ATTACH:
	      instance = ddi_get_instance(dip);
      if (ddi_soft_state_zalloc(statep, instance) != DDI_SUCCESS)
	         return (DDI_FAILURE);
	      softc = ddi_get_soft_state(statep, instance);
	      softc->dip = dip;	
	      ...
	      return (DDI_SUCCESS);
   default:
	      return (DDI_FAILURE);
   }
}

static int
xxdetach(dev_info_t *dip, ddi_detach_cmd_t cmd)
{
   int instance;

   switch (cmd) {

   case DDI_DETACH:
	      instance = ddi_get_instance(dip);
	      ...
      ddi_soft_state_free(statep, instance);
      return (DDI_SUCCESS);

   default:
      return (DDI_FAILURE);
   }
}

static int
xxopen(dev_t *devp, int flag, int otyp, cred_t *cred_p)
{
   devstate_t *softc;
   int   instance;

   instance = getminor(*devp);
   if ((softc = ddi_get_soft_state(statep, instance)) == NULL)
	      return (ENXIO);
   ...
   softc->state |= XX_IN_USE;
   ...
   return (0);
}
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fB_fini\fR(9E), \fB_init\fR(9E), \fBattach\fR(9E), \fBdetach\fR(9E),
\fBddi_get_instance\fR(9F), \fBgetminor\fR(9F), \fBkmem_zalloc\fR(9F)
.sp
.LP
\fIWriting Device Drivers\fR
.SH WARNINGS
.sp
.LP
There is no attempt to validate the \fBitem\fR parameter given to
\fBddi_soft_state_zalloc()\fR other than it must be a positive signed integer.
Therefore very large item numbers may cause the driver to hang forever waiting
for virtual memory resources that can never be satisfied.
.SH NOTES
.sp
.LP
If necessary, a hierarchy of state structures can be constructed by embedding
state pointers in higher order state structures.
.SH DIAGNOSTICS
.sp
.LP
All of the messages described below usually indicate bugs in the driver and
should not appear in normal operation of the system.
.sp
.in +2
.nf
WARNING: ddi_soft_state_zalloc: bad handle
WARNING: ddi_soft_state_free: bad handle
WARNING: ddi_soft_state_fini: bad handle
.fi
.in -2

.sp
.LP
The implementation-dependent information kept in the state variable is corrupt.
.sp
.in +2
.nf
WARNING: ddi_soft_state_free: null handle
WARNING: ddi_soft_state_fini: null handle
.fi
.in -2

.sp
.LP
The routine has been passed a null or corrupt state pointer.  Check that
\fBddi_soft_state_init()\fR has been called.
.sp
.in +2
.nf
WARNING: ddi_soft_state_free: item %d not in range [0..%d]
.fi
.in -2

.sp
.LP
The routine has been asked to free an item which was never allocated. The
message prints out the invalid item number and the acceptable range.