Manual Pages for UNIX Operating System command usage for man rmalloc

Kernel Functions for Drivers                          rmalloc(9F)



NAME
     rmalloc - allocate space from a resource map

SYNOPSIS
     #include 
     #include 



     unsigned long rmalloc(struct map *mp, size_t size);


INTERFACE LEVEL
     Architecture independent level 1 (DDI/DKI).

PARAMETERS
     mp      Resource map from where the resource is drawn.


     size    Number of units of the resource.


DESCRIPTION
     The rmalloc() function is used by a driver to allocate space
     from  a previously defined and initialized resource map. The
     map  itself   is   allocated   by   calling   the   function
     rmallocmap(9F).  rmalloc() is one of five functions used for
     resource map management. The other functions include:

     rmalloc_wait(9F)    Allocate space from a resource map, wait
                         if necessary.


     rmfree(9F)          Return previously allocated space  to  a
                         map.


     rmallocmap(9F)      Allocate a resource map  and  initialize
                         it.


     rmfreemap(9F)       Deallocate a resource map.



     The rmalloc() function allocates space from a  resource  map
     in  terms  of  arbitrary  units.  The  system  maintains the
     resource map by size and index, computed in units  appropri-
     ate  for  the   resource.  For  example,  units  may be byte
     addresses, pages of memory, or  blocks.  The  normal  return
     value  is  an  unsigned  long  set to the value of the index
     where sufficient free space in the resource was found.



SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                          rmalloc(9F)



RETURN VALUES
     Under normal conditions, rmalloc() returns the base index of
     the allocated space. Otherwise, rmalloc() returns a 0 if all
     resource map entries are already allocated.

CONTEXT
     The rmalloc() function can be called from  user,  interrupt,
     or kernel context.

EXAMPLES
     Example 1 Illustrating the principles of map management


     The following example is a simple memory map, but it  illus-
     trates  the principles of map management. A driver allocates
     and initializes the map by calling both  the  rmallocmap(9F)
     and rmfree(9F) functions. rmallocmap(9F) is called to estab-
     lish the  number  of  slots  or  entries  in  the  map,  and
     rmfree(9F)  to  initialize  the  resource area the map is to
     manage. The following example is a fragment from a hypothet-
     ical start routine and illustrates the following procedures:


         o    Panics the system if the required amount of  memory
              can not be allocated (lines 11-15).

         o    Uses rmallocmap(9F) to configure the  total  number
              of entries in the map, and rmfree(9F) to initialize
              the total resource area.

       1   #define XX_MAPSIZE   12
       2   #define XX_BUFSIZE  2560
       3   static struct map *xx_mp;         /* Private buffer space map */
           ...
       4   xxstart()
       5        /*
       6         *  Allocate private buffer.  If insufficient memory,
       7         *  display message and halt system.
       8         */
       9   {
       10    register caddr_t bp;
           ...
       11    if ((bp = kmem_alloc(XX_BUFSIZE, KM_NOSLEEP) == 0)  {
       12
       13        cmn_err(CE_PANIC, "xxstart: kmem_alloc failed before %d buffer"
       14                  "allocation", XX_BUFSIZE);
       15    }
       16
       17    /*
       18     * Initialize the resource map with number
       19     * of slots in map.
       20     */



SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                          rmalloc(9F)



       21    xx_mp = rmallocmap(XX_MAPSIZE);
       22
       24    /*
       25     * Initialize space management map with total
       26     * buffer area it is to manage.
       27     */
       28    rmfree(xx_mp, XX_BUFSIZE, bp);
             ...


     Example 2 Allocating buffers


     The rmalloc() function is then used by the driver's read  or
     write   routine   to  allocate  buffers  for  specific  data
     transfers. The uiomove(9F) function is used to move the data
     between  user space and local driver memory. The device then
     moves data between itself and local  driver  memory  through
     DMA.



     The next example illustrates the following procedures:


         o    The size of  the  I/O  request  is  calculated  and
              stored in the size variable (line 10).

         o    Buffers are allocated through the  rmalloc()  func-
              tion using the size value (line 15). If the alloca-
              tion fails the system will panic.

         o    The uiomove(9F) function is used to  move  data  to
              the allocated buffer (line 23).

         o    If the address passed to  uiomove(9F)  is  invalid,
              rmfree(9F)  is  called  to  release  the previously
              allocated buffer, and an EFAULT error is returned.

       1   #define XX_BUFSIZE  2560
       2   #define XX_MAXSIZE  (XX_BUFSIZE / 4)
       3
       4   static struct map *xx_mp;         /* Private buffer space map */
           ...
       5   xxread(dev_t dev, uio_t *uiop, cred_t *credp)
       6   {
       7
       8   register caddr_t addr;
       9   register int     size;
       10      size = min(COUNT, XX_MAXSIZE);  /* Break large I/O  */
       11                                          /* request into small ones */
       12     /*



SunOS 5.11          Last change: 16 Jan 2006                    3






Kernel Functions for Drivers                          rmalloc(9F)



       13      * Get buffer.
       14      */
       15    if ((addr = (caddr_t)rmalloc(xx_mp, size)) == 0)
       16        cmn_err(CE_PANIC, "read: rmalloc failed allocation of size %d",
       17                size);
       18
       19     /*
       20      * Move data to buffer.  If invalid address is found,
       21      * return buffer to map and return error code.
       22      */
       23    if (uiomove(addr, size, UIO_READ, uiop) == -1)  {
       24        rmfree(xx_mp, size, addr);
       25        return(EFAULT);
       26    }
       27  }


SEE ALSO
     kmem_alloc(9F),      rmalloc_wait(9F),       rmallocmap(9F),
     rmfree(9F), rmfreemap(9F), uiomove(9F)


     Writing Device Drivers
































SunOS 5.11          Last change: 16 Jan 2006                    4