sys/man/3/segment

   1 .TH SEGMENT 3
   2 .SH NAME
   3 segment \- long lived memory segments
   4 .SH SYNOPSIS
   5 .nf
   6 .B bind -c '#g' /mnt/segment
   7
   8 .BI #g/ seg1
   9 .BI #g/ seg1 /ctl
  10 .BI #g/ seg1 /data
  11 .BI #g/ seg2
  12 .BI #g/ seg2 /ctl
  13 .BI #g/ seg2 /data
  14  ...
  15 .fi
  16 .SH DESCRIPTION
  17 .PP
  18 The
  19 .I segment
  20 device provides a 2-level file system representing
  21 long-lived sharable segments that processes may
  22 .IR segattach (2).
  23 The name of the directory is the
  24 .I class
  25 argument to
  26 .IR segattach .
  27 .PP
  28 New segments are created under the top level
  29 using
  30 .B create
  31 (see
  32 .IR open (2)).
  33 The
  34 .B DMDIR
  35 bit must be set in the permissions.
  36 .IR Remove (2)'ing
  37 the directory makes the segment no longer
  38 available for
  39 .IR segattach .
  40 However, the segment will continue to exist until all
  41 processes using it either exit or
  42 .I segdetach
  43 it.
  44 .PP
  45 Within each segment directory are two files,
  46 .B data
  47 and
  48 .BR ctl .
  49 Reading and writing
  50 .B data
  51 affects the contents of the segment.
  52 Reading and writing
  53 .B ctl
  54 retrieves and sets the segment's properties.
  55 .PP
  56 There is only one control message, which sets the segment's
  57 virtual address and length in bytes:
  58 .EX
  59         va \fIaddress length type\fP
  60 .EE
  61 .I Address
  62 is automatically rounded down to a page boundary and
  63 .I length
  64 is rounded up to end the segment at a page boundary.
  65 The segment will reside at the same virtual address in
  66 all processes sharing it.
  67 Optionally,
  68 .I type
  69 can be specified as
  70 .B fixed
  71 or
  72 .BR sticky .
  73 Fixed segments are uncached and physically continuous
  74 with a fixed physical base address suitable for hardware
  75 DMA access.
  76 Sticky segments are like normal shared segments but
  77 preallocated at creation time and never swapped out.
  78 Only the hostower is allowed to create
  79 .B fixed
  80 or
  81 .B sticky
  82 segments.
  83 .PP
  84 .IR segattach,
  85 the address and length arguments are ignored in the call;
  86 they are defined only by the
  87 .B va
  88 control message.
  89 Once the address and length are set, they cannot be reset.
  90 .PP
  91 Reading the control file
  92 returns a message of the same format with the segment's actual
  93 start address and length. For
  94 .B fixed
  95 segments, the type and physical base address are appended.
  96 .PP
  97 Opening
  98 .B data
  99 or reading
 100 .B ctl
 101 before setting the virtual address yields the error
 102 ``segment not yet allocated''.
 103 .PP
 104 The permissions check when
 105 .IR segattach ing
 106 is equivalent to the one performed when opening
 107 .B data
 108 with mode ORDWR.
 109 .SH EXAMPLE
 110 .PP
 111 Create a one megabyte segment at address 0x10000000:
 112 .EX
 113         % bind -c '#g' /mnt/segment
 114         % mkdir /mnt/segment/example
 115         % echo 'va 0x10000000 0x100000' > /mnt/segment/example/ctl
 116 .EE
 117 .PP
 118 Put the string ``hi mom'' at the start of the segment:
 119 .EX
 120         % echo -n hi mom > /mnt/segment/example/data
 121 .EE
 122 .PP
 123 Attach the segment to a process:
 124 .EX
 125 {
 126         ulong va;
 127
 128         va = segattach(0, "example", 0, 0);
 129 }
 130 .EE
 131 .SH "SEE ALSO
 132 .IR segattach (2)
 133 .SH SOURCE
 134 .B /sys/src/9/port/devsegment.c