sys/man/9/allocb

   1 .TH ALLOCB 9
   2 .SH NAME
   3 allocb, iallocb, freeb, freeblist, BLEN, BALLOC, blocklen, blockalloclen, readblist, concatblock, copyblock, trimblock, packblock, padblock, pullblock, pullupblock, adjustblock, checkb \- data block management
   4 .SH SYNOPSIS
   5 .ta \w'\fLBlock* 'u
   6 .B
   7 Block*  allocb(int size)
   8 .PP
   9 .B
  10 Block*  iallocb(int size)
  11 .PP
  12 .B
  13 void    freeb(Block *b)
  14 .PP
  15 .B
  16 void    freeblist(Block *b)
  17 .PP
  18 .B
  19 int     blocklen(Block *b)
  20 .PP
  21 .B
  22 int     blockalloclen(Block *b)
  23 .PP
  24 .B
  25 long    readblist(Block *b, uchar *p, long n, ulong offset)
  26 .PP
  27 .B
  28 Block*  concatblock(Block *b)
  29 .PP
  30 .B
  31 Block*  copyblock(Block *b, int n)
  32 .PP
  33 .B
  34 Block*  trimblock(Block *b, int offset, int n)
  35 .PP
  36 .B
  37 Block*  packblock(Block *b)
  38 .PP
  39 .B
  40 Block*  padblock(Block *b, int n)
  41 .PP
  42 .B
  43 int     pullblock(Block **bph, int n)
  44 .PP
  45 .B
  46 Block*  pullupblock(Block *b, int n)
  47 .PP
  48 .B
  49 Block*  adjustblock(Block *b, int n)
  50 .PP
  51 .B
  52 void    checkb(Block *b, char *msg)
  53 .sp 0.1
  54 .PP
  55 .B
  56 #define BLEN(s) ((s)->wp - (s)->rp)
  57 .PP
  58 .B
  59 #define BALLOC(s) ((s)->lim - (s)->base)
  60 .SH DESCRIPTION
  61 A
  62 .B Block
  63 provides a receptacle for data:
  64 .IP
  65 .EX
  66 .DT
  67 typedef
  68 struct Block
  69 {
  70         Block*  next;
  71         Block*  list;
  72         uchar*  rp;             /* first unconsumed byte */
  73         uchar*  wp;             /* first empty byte */
  74         uchar*  lim;            /* 1 past the end of the buffer */
  75         uchar*  base;   /* start of the buffer */
  76         void    (*free)(Block*);
  77         ushort  flag;
  78         ushort  checksum;       /* IP checksum of complete packet */
  79 } Block;
  80 .EE
  81 .PP
  82 Each
  83 .B Block
  84 has an associated buffer, located at
  85 .BR base ,
  86 and accessed via
  87 .B wp
  88 when filling the buffer, or
  89 .B rp
  90 when fetching data from it.
  91 Each pointer should be incremented to reflect the amount of data written or read.
  92 A
  93 .B Block
  94 is empty when
  95 .B rp
  96 reaches
  97 .BR wp .
  98 The pointer
  99 .B lim
 100 bounds the allocated space.
 101 Some operations described below accept lists of
 102 .BR Block s,
 103 which are
 104 chained via their
 105 .B next
 106 pointers, with a null pointer ending the list.
 107 .B Blocks
 108 are usually intended for a
 109 .B Queue
 110 (see
 111 .IR qio (9)),
 112 but can be used independently.
 113 .PP
 114 A
 115 .B Block
 116 and its buffer are normally allocated by one call to
 117 .IR malloc (9)
 118 and aligned on an 8 byte (\fLBY2V\fP) boundary.
 119 Some devices with particular allocation constraints
 120 (eg, requiring certain addresses for DMA) might allocate their own
 121 .B Block
 122 and buffer;
 123 .B free
 124 must then point to a function that can deallocate the specially allocated
 125 .BR Block .
 126 .PP
 127 Many
 128 .B Block
 129 operations cannot be used in interrupt handlers
 130 because they either
 131 .IR sleep (9)
 132 or raise an
 133 .IR error (9).
 134 Of operations that allocate blocks, only
 135 .IR iallocb
 136 is usable.
 137 .PP
 138 .I Allocb
 139 allocates a
 140 .B Block
 141 of at least
 142 .IR size
 143 bytes.
 144 The block
 145 is initially empty:
 146 .B rp
 147 and
 148 .B wp
 149 point to the start of the data.
 150 If it cannot allocate memory,
 151 .I allocb
 152 raises an
 153 .IR error (9);
 154 it cannot be used by an interrupt handler.
 155 .PP
 156 .IR Iallocb
 157 is similar to
 158 .IR allocb
 159 but is intended for use by interrupt handlers,
 160 and returns a null pointer if no memory is available.
 161 It also limits its allocation to a quota allocated at system initialisation to interrupt-time buffering.
 162 .PP
 163 .I Freeb
 164 frees a single
 165 .B Block
 166 (and its buffer).
 167 .PP
 168 .I Freeblist
 169 frees the whole
 170 list of blocks headed by
 171 .IR b .
 172 .PP
 173 .I BLEN
 174 returns the number of unread bytes in a single block.
 175 .PP
 176 .I BALLOC
 177 returns the number of allocated bytes in a single block.
 178 .PP
 179 .I Blocklen
 180 returns the number of bytes of unread data in the whole list of blocks headed by
 181 .IR b .
 182 .PP
 183 .I Blockalloclen
 184 returns the number of total bytes allocated in the whole list of blocks headed by
 185 .IR b .
 186 .PP
 187 .I Readblist
 188 copies
 189 .I n
 190 bytes of data at offset
 191 .I offset
 192 from the list of blocks headed by
 193 .I b
 194 into
 195 .IR p ,
 196 then returns the amount of bytes copied. It leaves the block list intact.
 197 .PP
 198 .I Concatblock
 199 returns
 200 .I b
 201 if it is not a list, and otherwise
 202 returns a single
 203 .B Block
 204 containing all the data in the list of blocks
 205 .IR b ,
 206 which it frees.
 207 .PP
 208 .I Copyblock
 209 by contrast returns a single
 210 .B Block
 211 containing a copy of the first
 212 .I n
 213 bytes of data in the block list
 214 .IR b ,
 215 padding with zeroes if the list contained less than
 216 .I n
 217 bytes.
 218 The list
 219 .I b
 220 is unchanged.
 221 .PP
 222 .I Padblock
 223 can pad a single
 224 .B Block
 225 at either end, to reserve space for protocol headers or trailers.
 226 If
 227 .IR n ≥ 0 ,
 228 it inserts
 229 .I n
 230 bytes at the start of the block,
 231 setting the read pointer
 232 .B rp
 233 to point to the new space.
 234 If
 235 .IR n < 0 ,
 236 it adds
 237 .I n
 238 bytes at the end of the block,
 239 leaving the write pointer
 240 .B wp
 241 pointing at the new space.
 242 In both cases, it allocates a new
 243 .B Block
 244 if necessary, freeing the old, and
 245 it always returns a pointer to the resulting
 246 .BR Block .
 247 .PP
 248 .I Trimblock
 249 trims the list
 250 .I b
 251 to contain no more than
 252 .I n
 253 bytes starting at
 254 .I offset
 255 bytes into the data of the original list.
 256 It returns a new list, freeing unneeded parts of the old.
 257 If no data remains, it returns a null pointer.
 258 .PP
 259 .I Packblock
 260 examines each
 261 .B Block
 262 in the list
 263 .IR b ,
 264 reallocating any block in the list that has four times more available space than actual data.
 265 It returns a pointer to the revised list.
 266 .PP
 267 .I Pullblock
 268 discards up to
 269 .I n
 270 bytes from the start of the list headed by
 271 .BI * bph \f1.\f0
 272 Unneeded blocks are freed.
 273 .I Pullblock
 274 sets
 275 .BI * bph
 276 to point to the new list head
 277 and returns the number of bytes discarded (which might be less than
 278 .IR n ).
 279 It is used by transport protocols to discard ack'd data at
 280 the head of a retransmission queue.
 281 .PP
 282 .I Pullupblock
 283 rearranges the data in the list of blocks
 284 .I b
 285 to ensure that there are at least
 286 .I n
 287 bytes of contiguous data in the first block,
 288 and returns a pointer to the new list head.
 289 It frees any blocks that it empties.
 290 It returns a null pointer if there is not enough data in the list.
 291 .PP
 292 .I Adjustblock
 293 ensures that the block
 294 .I b
 295 has at least
 296 .I n
 297 bytes of data, reallocating or padding with zero if necessary.
 298 It returns a pointer to the new
 299 .BR Block .
 300 (If
 301 .I n
 302 is negative, it frees the block and returns a null pointer.)
 303 .PP
 304 .I Checkb
 305 does some consistency checking of
 306 the state of
 307 .IR b ;
 308 a
 309 .IR panic (9)
 310 results if things look grim.
 311 It is intended for internal use by the queue I/O routines (see
 312 .IR qio (9))
 313 but could be used elsewhere.
 314 .PP
 315 The only functions that can be called at interrupt level are
 316 .IR iallocb ,
 317 .IR freeb ,
 318 .IR freeblist ,
 319 .IR BLEN ,
 320 .IR BALLOC ,
 321 .IR blocklen ,
 322 .IR blockalloclen ,
 323 .IR readblist
 324 and
 325 .IR trimblock .
 326 The others allocate memory and can potentially block.
 327 .SH SOURCE
 328 .B /sys/src/9/port/allocb.c
 329 .br
 330 .B /sys/src/9/port/qio.c
 331 .SH DIAGNOSTICS
 332 Many functions directly or indirectly can raise an
 333 .IR error (9),
 334 and callers must therefore provide for proper error recovery
 335 as described therein to prevent memory leaks and other bugs.
 336 Except for
 337 .IR iallocb ,
 338 any functions that allocate new blocks or lists
 339 are unsuitable for use by interrupt handlers.
 340 .IR Iallocb
 341 returns a null pointer when it runs out of memory.
 342 .SH SEE ALSO
 343 .IR qio (9)