rom/filesys/pfs3/fs/doc/pfs3packets.guide

   1 @database "Professional File System 3 documentation"
   2 @author "Michiel Pelt"
   3 @(c) "Copyright 1999 by Great Effects Development"
   4 @$VER: pfs3packets.guide 1.2 (8/6/1999)
   5 @master pfs3packets.guide
   6
   7 @node "Main" "PFS3 Custom Packets"
   8
   9 @{jcenter}@{b}Professional File System 3
  10 Custom Packet Documentation@{ub}
  11 Copyright (c) 1998 by Great Effects Development
  12
  13 for PFS3 Version 5.1
  14
  15 This document provides information for developers. PFS3 defines some
  16 custom packets to make sleepmode and rollover files possible. All these
  17 packets have as first argument ID_PFS2_DISK which is 0x50465302L as
  18 defined in @{"pfs3.h" link pfs3.h/main}.
  19
  20 These packets are:
  21
  22 @{"ACTION_IS_PFS2" link "ACTION_IS_PFS2"}
  23 @{"ACTION_SLEEP" link "ACTION_SLEEP"}
  24 @{"ACTION_UPDATE_ANODE" link "ACTION_UPDATE_ANODE"}
  25 @{"ACTION_CREATE_ROLLOVER" link "ACTION_CREATE_ROLLOVER"}
  26 @{"ACTION_SET_ROLLOVER" link "ACTION_SET_ROLLOVER"}
  27 @{"ACTION_ADD_IDLE_SIGNAL" link "ACTION_ADD_IDLE_SIGNAL"}
  28 @{"ACTION_REMOVE_DIRENTRY" link "ACTION_REMOVE_DIRENTRY"}
  29 @{"ACTION_SET_DELDIR" link "ACTION_SET_DELDIR"}
  30 @{"ACTION_SET_FNSIZE" link "ACTION_SET_FNSIZE"}
  31
  32 How to use sleepmode is explained in @{"sleepmode" link sleepmode}
  33
  34 @endnode
  35 @rem --------------------------------------------------------------------
  36 @node "ACTION_IS_PFS2" "ACTION_IS_PFS2"
  37 @{jcenter}@{b}ACTION_IS_PFS2@{ub}
  38 @{jleft}
  39
  40 ARG1 = ID_PFS2_DISK (= 'PFS\\02')
  41 RES1 = DOSTRUE if PFS2 or PFS3 volume
  42 RES2 = Version (upper word) and revision (lower word)
  43
  44 Check if partition is a PFS2 or PFS3 partition. If it is, it returns DOSTRUE
  45 in dp_Res1. The version and revision of PFS is returned in dp_Res2.
  46
  47 @endnode
  48 @rem --------------------------------------------------------------------
  49 @node "ACTION_SLEEP" "ACTION_SLEEP"
  50 @{jcenter}@{b}ACTION_SLEEP@{ub}
  51 @{jleft}
  52
  53 ARG1 = ID_PFS2_DISK (= 'PFS\\02')
  54 ARG2 = on/off (DOSTRUE for on, DOSFALSE for off)
  55 ARG3 = ULONG signalnr
  56 ARG4 = struct Task *task
  57 RES1 = struct MsgPort *sleepport or NULL for failure
  58 RES2 = failurecode if RES1==NULL
  59
  60 Enter or leave sleep mode. See @{"sleepmode" link sleepmode} for details.
  61 If sleep mode is entered (dp_Arg2 == DOSTRUE), dp_Arg3 and dp_Arg4 specify
  62 where PFS3 will sent the wakeup signal to if PFS3 needs to regain control of
  63 the disk. If sleep mode is successfully entered, the sleepport will be
  64 returned in dp_Res1.
  65
  66 @endnode
  67 @rem --------------------------------------------------------------------
  68 @node "ACTION_UPDATE_ANODE" "ACTION_UPDATE_ANODE"
  69 @{jcenter}@{b}ACTION_UPDATE_ANODE@{ub}
  70 @{jleft}
  71
  72 ARG1 = ID_PFS2_DISK (= 'PFS\\02')
  73 ARG2 = old anodenr
  74 ARG3 = new anodenr (0 = invalidate references)
  75 RES1 = updatecount or -1 for failure
  76 RES2 = failurecode if Res1 = -1
  77
  78 This packet is only valid during sleepmode. The optimiser has to sent this
  79 packet to the sleepport for each anode it reassigns to another anodenumber.
  80 This packet is necessary because PFS3 identifies objects by anode number.
  81 Only anode numbers are cached during sleepmode, not the anodes themselves.
  82 These cached anode numbers are updated by this function. If dp_Arg3 is 0 all
  83 references to the anode in question are invalidated. This means locks on the
  84 object become invalid. This packet does not access the disk in any way. It
  85 doesn't matter when or in which order the packets are sent, as long as all
  86 changes are passed before the filesystem leaves sleepmode.
  87
  88 @endnode
  89 @rem --------------------------------------------------------------------
  90 @node "ACTION_CREATE_ROLLOVER" "ACTION_CREATE_ROLLOVER"
  91 @{jcenter}@{b}ACTION_CREATE ROLLOVER@{ub}
  92 @{jleft}
  93
  94 ARG1 = ID_PFS2_DISK (= 'PFS\\02')
  95 ARG2 = BPTR LOCK on directory ARG3 is relative to
  96 ARG3 = APTR name of rollover file
  97 ARG4 = WORD desired rollover size in blocks
  98 RES1 = success
  99 RES2 = failure code
 100
 101 Creates a rollover file with the specified size. This packet cannot convert
 102 a normal file to a rollover file. If a file by the specified name already
 103 exists, an ERROR_OBJECT_EXISTS will be returned.
 104
 105 @endnode
 106 @rem --------------------------------------------------------------------
 107 @node "ACTION_SET_ROLLOVER" "ACTION_SET_ROLLOVER"
 108 @{jcenter}@{b}ACTION_SET_ROLLOVER@{ub}
 109 @{jleft}
 110
 111 ARG1 = ID_PFS2_DISK (= 'PFS\\02')
 112 ARG2 = APTR fileentry (filled in by Open())
 113 ARG3 = APTR struct rolloverinfo
 114 RES1 = success
 115 RES2 = failure code
 116
 117 Changes the attributes of a rolloverfile. In dp_Arg2 an APTR to the
 118 rolloverfile is expected. This is can be obtained by converting the BPTR
 119 returned by Open() to an APTR using the macro BADDR(). The rolloverinfo
 120 structure passed in dp_arg3 looks like this:
 121
 122 struct rolloverinfo
 123 {
 124     BOOL set;                   /* 0 -> read; 1 -> write */
 125     ULONG realsize;             /* Space rolloverfile takes on disk */
 126     ULONG virtualsize;          /* How much is stored in file */
 127     ULONG rollpointer;          /* Start of file offset */
 128 };
 129
 130
 131 @endnode
 132 @rem --------------------------------------------------------------------
 133 @node "ACTION_ADD_IDLE_SIGNAL" "ACTION_ADD_IDLE_SIGNAL"
 134 @{jcenter}@{b}ACTION_IDLE_SIGNAL@{ub}
 135 @{jleft}
 136
 137 ARG1 = ID_PFS2_DISK
 138 ARG2 = add/remove (DOSTRUE = add; DOSFALSE = remove)
 139 ARG3 = ULONG signal number (UPPER = read, LOWER = write)
 140        remove: handle to remove
 141 ARG4 = struct Task *task
 142 RES1 = Idlehandle or DOSFALSE for failure
 143 RES2 = errorcode
 144
 145 Add or remove a task from the idle signal chain. All tasks in the idle
 146 signal chain are notified when PFS3 is idle. To add a task, set dp_Arg2 to
 147 DOSTRUE and a pointer to the task in dp_Arg4. Argument dp_Arg3 specifies
 148 which signals PFS3 will set when it becomes idle. If it has written to the
 149 disk it will send the signal specified in the lower word, if it has only
 150 read from the disk it will send the signal specified by the upper word. Your
 151 'idlehandle' is returned in dp_Res1.
 152
 153 To remove a task from the idle signal chain set dp_Arg2 to DOSFALSE and pass
 154 your idlehandle in dp_Arg3.
 155
 156 @endnode
 157 @rem --------------------------------------------------------------------
 158 @node "ACTION_REMOVE_DIRENTRY" "ACTION_REMOVE_DIRENTRY"
 159 @{jcenter}@{b}ACTION_REMOVE_DIRENTRY@{ub}
 160 @{jleft}
 161
 162 ARG1 = ID_PFS2_DISK
 163 ARG2 = Lock to which ARG2 is relative (BPTR)
 164 ARG3 = STRPTR Name of object to be deleted
 165 RES1 = BOOL Success/failure (DOSTRUE/DOSFALSE)
 166 RES2 = failurecode (if res1 = DOSFALSE)
 167
 168 Removes a directory entry (file, directory, link) without taking any action
 169 regarding the object in question. Storage taken by the object is not freed.
 170 This packet is a patch that makes it possible to circumvent an illegal
 171 object.
 172
 173 @endnode
 174 @rem --------------------------------------------------------------------
 175 @node "ACTION_SET_DELDIR" "ACTION_SET_DELDIR"
 176 @{jcenter}@{b}ACTION_SET_DELDIR@{ub}
 177 @{jleft}
 178
 179 ARG1 = MODE_PFS2_DISK
 180 ARG2 = number of deldirblocks wanted (0 = disable, -1 = check)
 181 RES1 = success
 182 RES2 = failure code
 183
 184 Sets the number of deldir blocks. To disable the deldir, set Arg2 to 0.
 185 To get the current number of deldirblocks set Arg2 to -1 and it will
 186 be returned in Res2.
 187
 188 @endnode
 189 @rem --------------------------------------------------------------------
 190 @node "ACTION_SET_FNSIZE" "ACTION_SET_FNSIZE"
 191 @{jcenter}@{b}ACTION_SET_FNSIZE@{ub}
 192 @{jleft}
 193
 194 ARG1 = MODE_PFS2_DISK
 195 ARG2 = New maximum filename size (0 = read)
 196 RES1 = success
 197 RES2 = failure code / current or new fnsize
 198
 199 Set the maximum filename size. If the new size is illegal, an error will
 200 be returned. If operation is successful or Arg2 is NULL, the new filename
 201 size will be returned in Res2.
 202
 203 @endnode
 204 @rem --------------------------------------------------------------------
 205 @node "Sleepmode" "Sleep Mode"
 206 @{jcenter}@{b}Sleep Mode@{ub}
 207 @{jleft}
 208
 209 This document assumes some knowledge of the structure of a PFS volume. See
 210 the supplied include file for details.
 211
 212 Even AFS volumes can get fragmented and therefore can benefit from
 213 occasional optimization by a disk optimiser. It would be ideal if this
 214 reorganisation process could be performed transparently, without the disk
 215 becoming inaccessible while the optimiser is busy. For this purpose AFS has
 216 a special mode of operation, the sleep mode.
 217
 218 In sleep mode the filesystem has no blocks of the volume cached and doesn't
 219 access the volume, like during inhibit mode. The difference with inhibit is
 220 that the filesystem does accept all packets when in sleep mode. If the
 221 filesystem needs access to the disk to perform a packet it will start the
 222 wakeup protocol. After completion of the wakeup protocol the filesystem is
 223 back in normal operating mode and can perform the packet.
 224
 225 @endnode
 226 @rem --------------------------------------------------------------------
 227 @node "SM_Protocol" "Sleep Mode Protocol"
 228 @{jcenter}@{b}Sleep Mode Protocol Overview@{ub}
 229 @{jleft}
 230
 231 Suppose an optimiser process is started. It has to initiate the sleep
 232 protocol to get access to the disk. It does this by requesting the
 233 filesystem to enter sleep mode. If the request is granted it can then access
 234 the disk. The optimiser also gets access to a special messageport, the
 235 @{i}sleepport@{ui}, for communication with the filesystem during sleep mode.
 236 When the optimiser is finished with the disk it has to exit sleep mode by
 237 sending a release message to this messageport.
 238
 239 Sleep mode is not limited to optimisers. Many other applications are
 240 conceivable, like a diskrepair tool or analyser. In the rest of this chapter
 241 the application will be called the @{i}client@{ui}.
 242
 243 During sleep mode the client is allowed to change filesystem structures on
 244 the disk. The filesystem therefore flushes all caches before it grants a
 245 sleep mode request. The filesystem does keep all locks on the volume, since
 246 the volume has to remain accessible by the user. Each file locked is
 247 identified by an anodenumber, which refers to the anodes on disk. If the
 248 client moves anodes around it has to notify the filesystem about this in
 249 order to keep the locks valid.
 250
 251 If the filesystem gets a user request for which it needs access to the disk
 252 it will request the client to finish disk access and release sleep mode.
 253 During this wakeup protocol the client has to clean up the disk during which
 254 it can send messages to the sleepport (like anode update messages). The
 255 client completes the wakeup protocol by sending a release message to the
 256 sleep port. The filesystem is then back in the normal mode of operation and
 257 can perform the user's request.
 258
 259 @endnode
 260 @rem --------------------------------------------------------------------
 261 @node "SM_Enter" "Entering Sleep Mode"
 262 @{jcenter}@{b}Entering Sleep Mode@{ub}
 263 @{jleft}
 264
 265 Sleepmode is requested by sending an ACTION_SLEEP packet with dp_Arg2 ==
 266 DOSTRUE. If the request is granted, the client can begin its work. For every
 267 anodenumber it changes it has to send an ACTION_UPDATE_ANODE to the
 268 sleepport. Changes to anodes themselves, without changing their number,
 269 don't have to be reported.
 270
 271 @endnode
 272 @rem --------------------------------------------------------------------
 273 @node "SM_Wakeup" "The wakeup protocol"
 274 @{jcenter}@{b}The wakeup protocol@{ub}
 275 @{jleft}
 276
 277 Sleep mode is left by using the wakeup protocol. The wakeup protocol can be
 278 initiated by either the client or the filesystem. If the client is finished
 279 with whatever it was doing with the disk it will take the initiative. It
 280 will flush all blocks it has cached and send all outstanding
 281 ACTION_UPDATE_ANODE packets. After that it sends the ACTION_SLEEP message
 282 causing the filesystem to exit sleep mode.
 283
 284 The filesystem will initiate the wakeup protocol if it needs access to the
 285 disk during sleep mode. It will sent a signal to the optimiser, using the
 286 signal number and messageport specified in the original ACTION_SLEEP packet.
 287 The client should respond by finishing disk activity and sending all
 288 outstanding ACTION_UPDATE_ANODE packets to the sleepport. The filesystem
 289 will leave sleep mode and continue normal operation as soon as it receives
 290 the MODE_SLEEP message with dp_Arg2 == DOSFALSE.
 291
 292 @endnode
 293
 294