sys/man/2/segattach

   1 .TH SEGATTACH 2
   2 .SH NAME
   3 segattach, segdetach, segfree \- map/unmap a segment in virtual memory
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .ta \w'\fLlong 'u
  10 .B
  11 void*   segattach(int attr, char *class, void *va, ulong len)
  12 .PP
  13 .B
  14 int     segdetach(void *addr)
  15 .PP
  16 .B
  17 int     segfree(void *va, ulong len)
  18 .PP
  19 .SH DESCRIPTION
  20 .I Segattach
  21 creates a new memory segment, adds it
  22 to the calling process's address space, and returns its lowest address.
  23 Segments belong to system-dependent classes.
  24 Segment classes
  25 .B memory
  26 (plain memory)
  27 and
  28 .B shared
  29 (shared memory)
  30 are available on all systems.
  31 .PP
  32 Shared segments are inherited by the children of the attaching process
  33 and remain untouched across a
  34 .IR fork (2).
  35 An
  36 .IR exec (2)
  37 will release a shared segment if it overlaps the segments
  38 in the file being
  39 .IR exec'ed ;
  40 otherwise the segment will be inherited.
  41 .PP
  42 Some machines provide a segment class
  43 .BR lock .
  44 Lock segments allow access to special lock hardware provided
  45 by some multiprocessors, in particular the SGI Power Series machines.
  46 .PP
  47 Systems may also provide interfaces to special hardware devices like
  48 frame buffers through the
  49 .I segattach
  50 interface.
  51 Device memory mapped by this method is typically uncached by default.
  52 .PP
  53 If the specified
  54 .I class
  55 is unknown,
  56 .I segattach
  57 draws an error.
  58 .PP
  59 .I Attr
  60 specifies the new segment's attributes.
  61 The only attributes implemented on all classes of segment is
  62 .BR SG_RONLY ,
  63 which allows only read access on the segment, and
  64 .BR SG_CEXEC ,
  65 which causes the segment to be detached when the process does an
  66 .IR exec (2).
  67 Specific devices may implement
  68 attributes to control caching and allocation, but these will vary
  69 between devices.
  70 .PP
  71 .I Va
  72 and
  73 .I len
  74 specify the position of the segment in the process's address space.
  75 .I Va
  76 is rounded down to the nearest page boundary and
  77 .IB va + len
  78 is rounded up.
  79 The system does not permit segments to overlap.
  80 If
  81 .I va
  82 is zero, the system will choose a suitable address.
  83 .PP
  84 .I Segdetach
  85 removes a segment from a process's address space. Memory used by
  86 the segment is freed.
  87 .I Addr
  88 may be any address within the bounds of the segment.
  89 .PP
  90 The system will not permit the initial stack segment to be detached
  91 from the address space.
  92 .PP
  93 .I Segfree
  94 tells the system that it may free any physical memory within the span
  95 .RI [ va ,
  96 .IR va+len ),
  97 but leaves that portion of the process's address space valid.
  98 The system will not free any memory outside that span,
  99 and may not free all or even any of the specified memory.
 100 If free'd memory is later referenced,
 101 it will be initialized as appropriate for the segment type.
 102 For example data and text segments will be read from the executable file,
 103 and bss segments will be filled with zero bytes.
 104 .PP
 105 The MIPS R2000 and R3000 have no hardware instructions
 106 to implement locks.  The following method can be used
 107 to build them from software.
 108 First, try to
 109 .I segattach
 110 a segment of class
 111 .BR lock .
 112 If this succeeds, the machine is an SGI Power Series and
 113 the memory contains hardware locks.
 114 Each 4096-byte page has 64
 115 .B long
 116 words at its beginning; each word implements
 117 a test-and-set semaphore when read; the low bit of the word
 118 is zero on success, one on failure.
 119 If the
 120 .I segattach
 121 fails, there is no hardware support but the operating system
 122 helps:
 123 Any
 124 .B COP3
 125 instruction will be trapped by the kernel and interpreted
 126 as a test-and-set.
 127 In the trap,
 128 .B R1
 129 points to a
 130 .BR long ;
 131 on return,
 132 .B R1
 133 is greater or equal zero on success, negative on failure.
 134 The following assembly language implements such a test-and-set.
 135 .IP
 136 .EX
 137 .ta 8n +8n +8n +8n +8n +8n +8n
 138 /*
 139  *      MIPS test and set
 140  */
 141         TEXT    tas(SB), $0
 142         MOVW    R1, sema+0(FP)  /* save arg on stack */
 143 btas:
 144         MOVW    sema+0(FP), R1
 145         MOVB    R0, 1(R1)
 146         NOR     R0, R0, R0      /* NOP */
 147         WORD    $(023<<26)      /* MFC3 R0, R0 */
 148         BLTZ    R1, btas
 149         RET
 150 .EE
 151 .SH SOURCE
 152 .B /sys/src/libc/9syscall
 153 .SH SEE ALSO
 154 .IR lock (2),
 155 .IR segbrk (2),
 156 .IR segflush (2)
 157 .br
 158 .BR /proc/*/segment
 159 .SH DIAGNOSTICS
 160 These functions set
 161 .IR errstr .
 162 .I Segattach
 163 returns
 164 .B (void*)-1
 165 on error.
 166 .SH BUGS
 167 There is a small fixed limit on the number of segments that may be attached,
 168 as well as a maximum segment size.