Messages in this thread | | | From | (Larry McVoy) | Subject | Re: mremap() proposal (was Re: malloc and joe) | Date | Mon, 25 Mar 1996 09:49:16 -0800 |
| |
: > : call mremap()..' and get an answer 12 hours later `OK, please try : > : this patch..' Oops, must have been dreaming. [Please insert your : > : workstation vendor for `SGI'.] : > : > Funny you should ask - we have it already, it's called : > : > MAP_AUTOGROW Implicitly grow object : : Question then: Does the SGI API do all we need, and should we copy that : instead ?
Hi Alan, here's the SGI API (and I think the man page is out of date, I think we added a MAP_EXTEND that says to change the mapping by this amount). So it's not clear that we have the API you want, but I would like Linux & IRIX to converge on interfaces, so please tell me what the new API does exactly?
mmap(2) mmap(2)
NAME mmap, mmap64 - map pages of memory
SYNOPSIS #include <sys/types.h> #include <sys/mman.h>
void *mmap(void *addr, size t len, int prot, int flags, int fd, off t off);
void *mmap64(void *addr, size t len, int prot, int flags, int fd, off64 t off);
DESCRIPTION The functions mmap and mmap64 establish a mapping between a process's address space and a virtual memory object. The format of the call is as follows:
pa = mmap(addr, len, prot, flags, fd, off);
mmap establishes a mapping between the process's address space at an address pa for len bytes to the memory object represented by the file descriptor fd at offset off for len bytes. The value of pa is an implementation-dependent function of the parameter addr and values of flags, further described below. A successful mmap call returns pa as its result. The address ranges covered by [pa, pa + len) and [off, off + len) must be legitimate for the possible (not necessarily current) address space of a process and the object in question, respectively.
The only difference between mmap and mmap64 is that in mmap64 the off parameter is 64 bits long, so that the file offset can be greater than 2 gigabytes. This is useful for certain filesystem types that support such file offsets.
The mapping established by mmap replaces any previous mappings for the process's pages in the range [pa, pa + len).
The parameter prot determines whether read (load), write (store), execute, or some combination of accesses are permitted to the pages being mapped. The protection options are defined in <sys/mman.h> as:
PROT READ Page can be read. PROT WRITE Page can be written. PROT EXEC Page can be executed. PROT NONE Page can not be accessed.
Not all implementations literally provide all possible combinations. PROT WRITE is often implemented as PROT READ|PROT WRITE and PROT EXEC as PROT READ|PROT EXEC. This is true for all SGI implementations. However, no implementation will permit a store to succeed where PROT WRITE has not been set. The behavior of PROT WRITE can be influenced by setting MAP PRIVATE in the flags parameter, described below.
Page 1
mmap(2) mmap(2)
The parameter flags provides other information about the handling of the mapped pages. The options are defined in <sys/mman.h> as:
MAP SHARED Share changes MAP PRIVATE Changes are private MAP FIXED Interpret addr exactly MAP AUTOGROW Implicitly grow object MAP LOCAL Do not share with share group MAP AUTORESRV Reserve logical swap on demand
MAP SHARED and MAP PRIVATE describe the disposition of store references to the memory object. If MAP SHARED is specified, store references will change the memory object. If MAP PRIVATE is specified, the initial store reference will create a private copy of the memory object page and redirect the mapping to the copy. Either MAP SHARED or MAP PRIVATE must be specified, but not both. The mapping type is retained across a fork(2).
When MAP SHARED is specified, and initially in all pages when MAP PRIVATE is specified, the contents of the mapped segment change to reflect changes in the underlying memory object. Changes can be caused by other processes that map the same object with MAP SHARED, or by processes using write(2) or ftruncate(2). If the file is shortened, an attempt to access a page of memory that is mapped to a part of the file that no longer exists will cause a Bus Error (SIGBUS) signal.
When MAP PRIVATE is used, a private copy of a page is created only when the process stores into the page. This prevents changes from being seen by other processes that map the same object, and prevents further changes made by other processes from being visible. However, changes that occur before the page is stored into are visible.
To protect the contents of a mapped file from changes or truncation you can either use chmod(2) and lockf(3) to enforce a mandatory file lock, or you can specify MAP PRIVATE and store into every page of the segment in order to create a complete private copy of the data.
MAP FIXED informs the system that the value of pa must be addr, exactly. The use of MAP FIXED is discouraged, as it may prevent an implementation from making the most effective use of system resources.
When MAP FIXED is not set, the system uses addr in an implementation- defined manner to arrive at pa. The pa so chosen will be an area of the address space which the system deems suitable for a mapping of len bytes to the specified object. All implementations interpret an addr value of zero as granting the system complete freedom in selecting pa, subject to constraints described below. A non-zero value of addr is taken to be a suggestion of a process address near which the mapping should be placed. When the system selects a value for pa, it will never place a mapping at address 0, nor will it replace any extant mapping, nor map into areas considered part of the potential data or stack segments.
Page 2
mmap(2) mmap(2)
When MAP FIXED is set, any mappings (including text, heap, data, and stack) in the range [addr, addr + len) will be replaced with the new mapping.
If MAP AUTOGROW is specified with MAP SHARED, the mapped object will be implicitly grown when referenced by a store operation to a page which maps beyond the current end of the object; the object will be grown and zero-filled to fulfill the mapping up to the next page boundary or to the end of the mapping, whichever is less. If used with MAP PRIVATE, MAP AUTOGROW allocates private zero-filled pages for references beyond the end of the object, but does not grow the object.
MAP AUTOGROW requires that the object is mapped with PROT WRITE permission. Load references to mapped pages following the end of a object will result in the delivery of a SIGSEGV signal, as will various filesystem conditions on stores. Whenever a SIGSEGV signal is delivered, the second argument to the signal handler contains a value that indicates the reason for the delivery of the signal; these values are defined in /usr/include/sys/errno.h.
If MAP LOCAL is used and the process does an sproc(2) each process will receive a private copy of the object's mapping. All subsequent load reference of objects mapped MAP PRIVATE will cause private copies of the object to be created. In addition, the share group processes will be able to independently unmap the object from their address spaces.
The system reserves len bytes of logical swap space when MAP PRIVATE mappings of regular files are created, as well as for all mappings of /dev/zero. (See swap(1m) for a discussion of logical swap space.) If insufficient logical swap space is available, mmap fails with EAGAIN. The MAP AUTORESRV flag causes logical swap space to be automatically reserved as each page is first referenced with a store operation instead of when the mapping is created. When this flag is used, no logical swap space is reserved when the mapping is created. Therefore, the system cannot guarantee that space will be available when needed. If all the logical swap space has been taken by other processes when a page in a MAP AUTORESRV mapping is first stored to, then the process will be sent SIGBUS.
The parameter off is constrained to be aligned and sized according to the value returned by getpagesize(2) or sysconf. When MAP FIXED is specified, the parameter addr must also meet these constraints. The system performs mapping operations over whole pages. Thus, while the parameter len need not meet a size or alignment constraint, the system will include, in any mapping operation, any partial page specified by the range [pa, pa + len).
The system will always zero-fill any partial page at the end of an object. Further, the system will never write out any modified portions of the last page of an object which are beyond its end. References to whole pages following the end of an object will result in the delivery of a SIGBUS signal. SIGBUS signals may also be delivered on various file
Page 3
mmap(2) mmap(2)
system conditions, including quota exceeded errors, and for physical device errors (such as unreadable disk blocks). The signal handler may examine the si code and si errno fields of the siginfo structure for information about the nature of the error.
RETURN VALUE On success, mmap returns the address at which the mapping was placed (pa). On failure it returns MAP FAILED and sets errno to indicate an error.
ERRORS Under the following conditions, mmap fails and sets errno to:
EAGAIN The mapping could not be locked in memory.
EAGAIN The amount of logical swap space required is temporarily unavailable.
EBADF fd is not open.
EACCES fd is not open for read, regardless of the protection specified, or fd is not open for write and PROT WRITE was specified for a MAP SHARED type mapping.
EACCES prot has extraneous bits set.
ENXIO Addresses in the range [off, off + len) are invalid for fd.
EINVAL The arguments addr (if MAP FIXED was specified) or off are not multiples of the page size as returned by sysconf.
EINVAL The field in flags is invalid (neither MAP PRIVATE or MAP SHARED).
ENXIO The argument len has a value less than or equal to 0.
EINVAL The argument addr specifies an unmappable address.
ENODEV fd refers to an object for which mmap is meaningless, such as a terminal.
ENOSYS fd refers to an object for which mmap is not permitted.
ENOMEM MAP FIXED was specified and the range [addr, addr + len) is invalid or exceeds that allowed for the address space of a process, or MAP FIXED was not specified and there is insufficient room in the address space to effect the mapping.
NOTES mmap allows access to resources via address space manipulations instead of the read/write interface. Once a file is mapped, all a process has to do to access it is use the data at the address to which the object was mapped. Consider the following pseudo-code:
Page 4
mmap(2) mmap(2)
fd = open(...) lseek(fd, offset) read(fd, buf, len) /* use data in buf */
Here is a rewrite using mmap:
fd = open(...) address = mmap(NULL, len, (PROT READ | PROT WRITE), MAP PRIVATE, fd, offset) /* use data at address */
SEE ALSO fcntl(2), fork(2), lockf(3C), madvise(2), mprotect(2), msync(2), munmap(2), plock(2), sproc(2), sysconf(2).
Page 5
mmap(D2) mmap(D2)
NAME mmap - support virtual mapping for memory-mapped device
SYNOPSIS #include <sys/types.h> #include <sys/param.h> #include <sys/mman.h> #include <sys/ddi.h>
int prefixmmap(dev t dev, off t off, int prot);
Arguments dev Device whose memory is to be mapped.
off Offset within device memory at which mapping begins.
prot Protection flags from mman.h.
DESCRIPTION The mmap entry point provides a way to support character drivers for memory-mapped devices. A memory-mapped device has memory that can be mapped into a process's address space. The mmap(2) system call, when applied to a character special file, allows this device memory to be mapped into user space for direct access by the user application (this way no kernel buffering or system call overhead is incurred).
The mmap routine checks if the offset is within the range of pages supported by the device. For example, a device that has 32K bytes of memory that can be mapped into user space should not support offsets greater than, or equal to, 32K. If the offset does not exist, then NOPAGE is returned. If the offset does exist, the mmap routine returns the physical page ID for the page at offset off in the device's memory; that is, the offset in units of pages.
Return Values If the protection and offset are valid for the device, the driver should return the physical page ID. Otherwise, NOPAGE should be returned.
USAGE This entry point is optional, and valid for memory-mapped character device or character pseudo-device drivers only.
Valid values for prot are:
PROT READ Page can be read.
PROT WRITE Page can be written.
PROT EXEC Page can be executed.
Page 1
mmap(D2) mmap(D2)
PROT ALL All of the above.
Synchronization Constraints The mmap routine has user context and can sleep.
REFERENCES map(D2X), unmap(D2X)
Page 2
| |