rmalloc(D3)

NAME
     rmalloc - allocate space from a private space management map

SYNOPSIS
     #include <sys/types.h>
     #include <sys/map.h>
     #include <sys/ddi.h>
     ulong_t rmalloc(struct map *mp, size_t size);

   Arguments
     mp        Pointer to the map from which space is to be allocated.

     size      Number of units of space to allocate.

DESCRIPTION
     rmalloc allocates space from the private space management map pointed to
     by mp.

   Return Values
     Upon successful completion, rmalloc returns the base of the allocated
     space.  If size units cannot be allocated, 0 is returned.

USAGE
     Drivers can use rmalloc to allocate space from a previously allocated and
     initialized private space management map.

     The map must have been allocated by a call to rmallocmap(D3) and the
     space managed by the map must have been added using rmfree(D3) prior to
     the first call to rmalloc for the map.

     size specifies the amount of space to allocate and is in arbitrary units.
     The driver using the map places whatever semantics on the units are
     appropriate for the type of space being managed.  For example, units may
     be byte addresses, pages of memory, or blocks on a device.

     The system allocates space from the memory map on a first-fit basis and
     coalesces adjacent space fragments when space is returned to the map by
     rmfree.

   Level
     Initialization, Base or Interrupt.

   Synchronization Constraints
     Does not sleep.

     Driver-defined basic locks, read/write locks, and sleep locks may be held
     across calls to this function.

   Examples
     The following example is a simple memory map, but it illustrates the
     principles of map management.  A driver declares a map table (line 4) and
     initializes the map table by calling the rmfree function.  There are 35
     entries in the map table, 32 of which can be used to represent space
     allocated.  In the driver's start(D2) routine, we allocate 16 Kbytes of
     memory using rmallocmap(D3) (line 8).  This is the space to be managed.
     Then call rmfree to populate the map with the space it is to manage (line
     10).

     In the driver's read(D2) and write(D2) routines, we use rmalloc to
     allocate buffers for data transfer.  This example illustrates the write
     routine.  Assuming the device can only transfer XX_MAXBUFSZ bytes at a
     time, we calculate the amount of data to copy (line 21) and use rmalloc
     to allocate some space from the map.  The call to rmalloc is protected
     against interrupts (line 22) from the device that may result in freeing
     map space.  This way, if space is freed, we won't miss the corresponding
     wakeup(D3).

      1  #define XX_MAPSIZE   35
      2  #define XX_MEMSIZE   (16*1024)
      3  #define XX_MAXBUFSZ  1024
      4  struct map *xx_map;
         ...
      5  xx_start()
      6  {
      7    caddr_t bp;
      8    if ((mp=rmallocmap(xx_MAPSIZE) == 0
      9         cmn_err (CE_PANIC, "xx_start: could not allocate map");
     10    rmfree(xx_map, XX_MEMSIZE, bp);
     11  }
         ...
     12  xx_write(dev, uiop, crp)
     13    dev_t dev;
     14    uio_t *uiop;
     15    cred_t *crp;
     16  {
     17    caddr_t addr;
     18    size_t size;
     19    int s;
         ...
     20    while (uiop->uio_resid > 0) {
     21        size = min(uiop->uio_resid, XX_MAXBUFSZ);
     22        s = spl4();
     23        while ((addr = (caddr_t)rmalloc(xx_map, size)) == NULL) {
     24            sleep((caddr_t)xx_map, PZERO);
     25        }
     26
     27        splx(s);
               ...
     28    }
         ...

REFERENCES
     rmalloc_wait(D3), rmallocmap(D3), rmfree(D3), rmfreemap(D3),