segattach 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168
  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.