phys(2) phys(2)NAME phys - allow a process to access physical addresses SYNOPSIS int phys(physnum, virtaddr, size, physaddr) int physnum; char *virtaddr; unsigned int size; char *physaddr; DESCRIPTION The phys system call allows the superuser to map a region of physical memory into a process's virtual address space. The calling process chooses physnum to specify the phys re- gion this call references. The maximum number of regions per process is defined by the v_phys field in the var struc- ture returned by uvar(2). physnum must be between zero and v_phys-1, and is only used to identify a particular phys re- gion to the kernel during a phys system call. virtaddr is the base virtual address for the region in the process's virtual address space, and size is the length in bytes of the desired region. The virtual address range of the region must not overlap any of the existing address space of the process, including text, data, stack, shared memory regions (see shmget(2)), and any other active phys regions. All addresses in this range must be valid user virtual addresses (see the example below). Care should also be taken to avoid placing a phys region at a virtual address that the data or stack segments might grow to encompass. If size is zero, any previous phys mapping is cleared for the region specified by physnum. A phys region's virtaddr and size are dependent on the im- plementation decisions for the memory management unit. In particular, the base virtaddr must be on a kernel segment boundary and the size will be rounded up to an integral mul- tiple of the page size. These values may be computed from the v_segshift and v_pageshift fields returned by uvar(2); that is, the segment size is 1 << v_segshift and the page size is 1 << v_pageshift The physaddr argument is the base physical address for the region. physaddr is rounded down to the previous page boun- dary. Also, physaddr to physaddr+size should be inside the April, 1990 1
phys(2) phys(2)range of physical addresses supported by the hardware. phys regions are inherited across fork(2) system calls and disowned across execs. phys may only be executed by a process with an effective user ID of root. As an example, suppose a process wishes to map a piece of memory-mapped hardware into its address space. This hardware has 0x8800 bytes of memory and control registers located at physical address 0xFA000000. By calling uvar(2), the process finds that v_pageshift is 12 and v_segshift is 20; thus, the page size is 0x1000 and the segment size is 0x100000. Also, v_phys is found to be 32, so any number from zero to 31 may be used for physnum. The var structure also contains v_ustart and v_uend, the starting and ending virtual addresses for user processes. For this example, assume v_ustart is zero and v_uend is 0x20000000. The first few segments are used for the running program's text and data and the last are used for the user stack. The process might decide it is unlikely that its data and text segment will exceed 0x4000000, which is an in- tegral multiple of 0x100000 (the segment size). The call: phys(0, 0x4000000, 0x8800, 0xFA000000); will allow the process access to physical locations from 0xFA00000 to 0xFA009000 by referencing virtual addresses 0x4000000 to 0x4009000. The range has been adjusted to 0x9000 bytes because that is the next page boundary. In this example, referencing 0x4008804 (an address in the phys region, but outside of the known hardware memory) will result in unpredictable failures. A useless value may be read off the hardware lines, a write may appear to succeed without affecting anything, the program may get a SIGSEGV (see signal(3)), the hardware may react randomly, or the en- tire system may crash. There may be other possibilities depending on system configuration. If the process wished to add another phys region without deleting the first region, the next available virtaddr would be 0x4100000 (the next segment boundary) and physnum could be any number from one to 31. RETURN VALUES The value zero is returned if the call was successful; oth- erwise -1 is returned. phys will fail if the effective user ID of the calling process is not root, if virtaddr or phy- 2 April, 1990
phys(2) phys(2)saddr is not in the proper range, or if the range of virtual addresses overlaps a portion of the user's virtual address space that is already in use. NOTES phys is hardware and implementation dependent and must be used with extreme caution. The intention is to give the su- peruser complete access to the physical hardware. To insure maximum portability, virtaddr and size should be calculated as described in the example. Different hardware may respond differently to mistakes in addressing. Sometimes all the bits of a physical address are not decoded, making (for example) 0xFD100000 the same as 0xFD000000. If physaddr or size is wrong it is possible to crash the system. Most versions of UNIX do not support this system call. SEE ALSO uvar(2), shmget(2), signal(3). April, 1990 3