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