TECHNICAL INFORMATION DOCUMENT

TITLE:              PTF158 - drv_mmap/drv_munmap
DOCUMENT ID:        TID300099
DOCUMENT REVISION:  B
DATE:               25JAN95
ALERT STATUS:       Yellow
INFORMATION TYPE:   Symptom Solution
README FOR:         PTF158

PRODUCT and VERSION:
UnixWare 1.1

ABSTRACT:

The ptf158 file contains PTF158 - drv_mmap/drv_munmap. This package 
has mem/Driver.o and drv_mmap.1/drv_munmap.1 MAN pages in pkgadd 
format.  This package implements the drv_mmap and drv_munmap calls 
from UnixWare 2.0. It also supplies new man pages for these calls.  
WARNING:The drv_mmap and drv_munmap calls are intended for Device 
Driver developers ONLY. You should not need this ptf otherwise!!! 
This ptf is intended for use with UnixWare v1.1

SYMPTOM

Additional Man pages needed for device driver developers

SOLUTION

Apply the ptf158 file.


Installation Instructions:

DATATYPE: datastream

1.  Download the ptf158 and ptf158.txt files to the /tmp directory  
    on your machine.

2.  Read the release notes contained in this file.           

3.  Now become root, and add the package to your system using the following
    commands:

     $su
     #pkgadd -d /tmp/ptf158 ptf158

Solution Specifics

1. General Description

PTF158 - drv_mmap/drv_munmap

This package has mem/Driver.o and drv_mmap.1/drv_munmap.1 MAN 
pages in pkgadd format.

2. New Features

This package implements the drv_mmap and drv_munmap calls from 
UnixWare 2.0.  It also supplies new man pages for these calls.

3. Software Notes and Recommendations

WARNING:The drv_mmap and drv_munmap calls are intended for Device Driver
developers ONLY. You should not need this ptf otherwise!!!

The following is taken from the man pages for drv_mmap:

drv_mmap - set up user mapping to kernel virtual or physical addresses

int drv_mmap(ulong_t vaddr, paddr_t paddr, size_t len, ulong_t *uvaddrp,
uint_t prot, uint_t maxprot, uint_t flags)

  Arguments
     vaddr     Kernel address of the  object  to  be  mapped  (if
               present, paddr is ignored).

     paddr     Physical address of the object to be mapped.

     len       Number of bytes to map into user space.

     *uvaddrp  User address at which to map the object.

     prot      Initial protection flags (from mman.h).

     maxprot   Maximum protection.

     flags     Specifies whether the user address is supplied  by
               the driver or the kernel.

DESCRIPTION
drv_mmap provides a convenient interface for  setting  up  a user  
mapping  to a  range  of  kernel  virtual or physical addresses.

Return Values
If the parameters are valid, drv_mmap returns with the user address 
for the object map in *uvaddrp, and returns 0.  Otherwise, a non-zero 
errno is returned.

USAGE
A typical use for drv_mmap is for video frame buffers mapped through  
ioctls [instead of mmap(D2)] for compatibility with pre-SVR4 applications.   
If  the MAP_FIXED  flag  is  used, *uvaddrp  will  be  used as the user 
address at which to map the object and any previous mapping at this 
address will  be replaced;  otherwise,  the  kernel  will  choose a 
currently unused user address and place it into *uvaddrp.  If vaddr 
is non-zero,  it  is  the kernel  address  of the object to be 
mapped (and paddr is ignored); otherwise, paddr is the physical address 
of the object.  Note that the mapping is at a page granularity.  
You can pass  in  addresses  and lengths which are not page-aligned, 
but the user will have access to entire pages.  The parameter prot 
determines  whether  read, write,  execute,  or some combination of 
these accesses are permitted to the pages being mapped. The protection 
options are defined in <sys/mman.h> as:  

Page can be read.  
Page can be written.  
Page can be executed.  
Page cannot be accessed.  

Not  all implementations literally provide all possible combinations.  
For example, PROT_WRITE is often implemented  as PROT_READ|PROT_WRITE  
and PROT_EXEC as PROT_READ|PROT_EXEC.  However, no implementation will 
permit a write to succeed if PROT_WRITE has not been set.  The parameter 
maxprot is similar to prot, but specifies the maximum permissions 
the  user can subsequently  assign through mprotect(2).  To release 
a mapping acquired by drv_mmap, use drv_munmap(D3).

REFERENCES
     drv_munmap(D3)

NOTE: This patch modifies same files as ptf101, ptf605 and update 1.1.1

4. Hardware Notes and Recommendations

see the man pages 

5. Installation Instructions

Depending on the format:

If this ptf was delivered on a diskette

As root, 

     # pkgadd -d diskette1 

should install this driver.

Otherwise if you have a file such as "ptf158" which is in a "stream" format
then as root 

     # pkgadd -d `pwd`/ptf158 

will work.

6. Troubleshooting

Device Driver specific.