SEGATTACH(2)                                         SEGATTACH(2)

     NAME
          segattach, segdetach, segfree - map/unmap a segment in
          virtual memory

     SYNOPSIS
          #include <u.h>
          #include <libc.h>

          void*segattach(int attr, char *class, void *va, ulong len)

          int  segdetach(void *addr)

          int  segfree(void *va, ulong len)

     DESCRIPTION
          Segattach creates a new memory segment, adds it to the call-
          ing process's address space, and returns its lowest address.
          Segments belong to system-dependent classes.  Segment
          classes memory (plain memory) and shared (shared memory) are
          available on all systems.

          Shared segments are inherited by the children of the attach-
          ing process and remain untouched across a fork(2). An
          exec(2) will release a shared segment if it overlaps the
          segments in the file being exec'ed; otherwise the segment
          will be inherited.

          Some machines provide a segment class lock.  Lock segments
          allow access to special lock hardware provided by some mul-
          tiprocessors, in particular the SGI Power Series machines.

          Systems may also provide interfaces to special hardware
          devices like frame buffers through the segattach interface.
          Device memory mapped by this method is typically uncached by
          default.

          If the specified class is unknown, segattach draws an error.

          Attr specifies the new segment's attributes.  The only
          attributes implemented on all classes of segment is
          SG_RONLY, which allows only read access on the segment, and
          SG_CEXEC, which causes the segment to be detached when the
          process does an exec(2). Specific devices may implement
          attributes to control caching and allocation, but these will
          vary between devices.

          Va and len specify the position of the segment in the
          process's address space.  Va is rounded down to the nearest
          page boundary and va+len is rounded up.  The system does not
          permit segments to overlap.  If va is zero, the system will

     SEGATTACH(2)                                         SEGATTACH(2)

          choose a suitable address.

          Segdetach removes a segment from a process's address space.
          Memory used by the segment is freed.  Addr may be any
          address within the bounds of the segment.

          The system will not permit the initial stack segment to be
          detached from the address space.

          Segfree tells the system that it may free any physical mem-
          ory within the span [va, va+len), but leaves that portion of
          the process's address space valid.  The system will not free
          any memory outside that span, and may not free all or even
          any of the specified memory.  If free'd memory is later ref-
          erenced, it will be initialized as appropriate for the seg-
          ment type.  For example data and text segments will be read
          from the executable file, and bss segments will be filled
          with zero bytes.

          The MIPS R2000 and R3000 have no hardware instructions to
          implement locks.  The following method can be used to build
          them from software.  First, try to segattach a segment of
          class lock.  If this succeeds, the machine is an SGI Power
          Series and the memory contains hardware locks.  Each 4096-
          byte page has 64 long words at its beginning; each word
          implements a test-and-set semaphore when read; the low bit
          of the word is zero on success, one on failure.  If the
          segattach fails, there is no hardware support but the oper-
          ating system helps: Any COP3 instruction will be trapped by
          the kernel and interpreted as a test-and-set.  In the trap,
          R1 points to a long; on return, R1 is greater or equal zero
          on success, negative on failure.  The following assembly
          language implements such a test-and-set.

               /*
                *      MIPS test and set
                */
                       TEXT    tas(SB), $0
                       MOVW    R1, sema+0(FP)  /* save arg on stack */
               btas:
                       MOVW    sema+0(FP), R1
                       MOVB    R0, 1(R1)
                       NOR     R0, R0, R0      /* NOP */
                       WORD    $(023<<26)      /* MFC3 R0, R0 */
                       BLTZ    R1, btas
                       RET

     SOURCE
          /sys/src/libc/9syscall

     SEE ALSO
          lock(2), segbrk(2), segflush(2)

     SEGATTACH(2)                                         SEGATTACH(2)

          /proc/*/segment

     DIAGNOSTICS
          These functions set errstr. Segattach returns (void*)-1 on
          error.

     BUGS
          There is a small fixed limit on the number of segments that
          may be attached, as well as a maximum segment size.