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 When the segment is attached using
  85 .IR segattach,
  86 the address and length arguments are ignored in the call;
  87 they are defined only by the
  88 .B va
  89 control message.
  90 Once the address and length are set, they cannot be reset.
  91 .PP
  92 Reading the control file
  93 returns a message of the same format with the segment's actual
  94 start address and length. For
  95 .B fixed
  96 segments, the type and physical base address are appended.
  97 .PP
  98 Opening
  99 .B data
 100 or reading
 101 .B ctl
 102 before setting the virtual address yields the error
 103 ``segment not yet allocated''.
 104 .PP
 105 The permissions check when
 106 .IR segattach ing
 107 is equivalent to the one performed when opening
 108 .B data
 109 with mode ORDWR.
 110 .SH EXAMPLE
 111 .PP
 112 Create a one megabyte segment at address 0x10000000:
 113 .EX
 114         % bind -c '#g' /mnt/segment
 115         % mkdir /mnt/segment/example
 116         % echo 'va 0x10000000 0x100000' > /mnt/segment/example/ctl
 117 .EE
 118 .PP
 119 Put the string ``hi mom'' at the start of the segment:
 120 .EX
 121         % echo -n hi mom > /mnt/segment/example/data
 122 .EE
 123 .PP
 124 Attach the segment to a process:
 125 .EX
 126 {
 127         ulong va;
 128
 129         va = segattach(0, "example", 0, 0);
 130 }
 131 .EE
 132 .SH "SEE ALSO
 133 .IR segattach (2)
 134 .SH SOURCE
 135 .B /sys/src/9/port/devsegment.c