iokit/Kernel/IOMultiMemoryDescriptor.cpp

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License.  The rights granted to you under the
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30
  31 #include <IOKit/IOLib.h>
  32 #include <IOKit/IOMultiMemoryDescriptor.h>
  33
  34 #define super IOMemoryDescriptor
  35 OSDefineMetaClassAndStructors(IOMultiMemoryDescriptor, IOMemoryDescriptor)
  36
  37 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  38
  39 bool IOMultiMemoryDescriptor::initWithAddress(
  40                                   void *      /* address       */ ,
  41                                   IOByteCount /* withLength    */ ,
  42                                   IODirection /* withDirection */ )
  43 {
  44     return false;
  45 }
  46
  47 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  48
  49 bool IOMultiMemoryDescriptor::initWithAddress(
  50                                   vm_address_t /* address       */ ,
  51                                   IOByteCount  /* withLength    */ ,
  52                                   IODirection  /* withDirection */ ,
  53                                   task_t       /* withTask      */ )
  54 {
  55     return false;
  56 }
  57
  58 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  59
  60 bool IOMultiMemoryDescriptor::initWithPhysicalAddress(
  61                                   IOPhysicalAddress /* address       */ ,
  62                                   IOByteCount       /* withLength    */ ,
  63                                   IODirection       /* withDirection */ )
  64 {
  65     return false;
  66 }
  67
  68
  69 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  70
  71 bool IOMultiMemoryDescriptor::initWithPhysicalRanges(
  72                                   IOPhysicalRange * /* ranges        */ ,
  73                                   UInt32            /* withCount     */ ,
  74                                   IODirection       /* withDirection */ ,
  75                                   bool              /* asReference   */ )
  76 {
  77     return false;
  78 }
  79
  80 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  81
  82 bool IOMultiMemoryDescriptor::initWithRanges(
  83                                   IOVirtualRange * /* ranges        */ ,
  84                                   UInt32           /* withCount     */ ,
  85                                   IODirection      /* withDirection */ ,
  86                                   task_t           /* withTask      */ ,
  87                                   bool             /* asReference   */ )
  88 {
  89     return false;
  90 }
  91
  92 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  93
  94 IOMultiMemoryDescriptor * IOMultiMemoryDescriptor::withDescriptors(
  95                                   IOMemoryDescriptor ** descriptors,
  96                                   UInt32                withCount,
  97                                   IODirection           withDirection,
  98                                   bool                  asReference )
  99 {
 100     //
 101     // Create a new IOMultiMemoryDescriptor.  The "buffer" is made up of several
 102     // memory descriptors, that are to be chained end-to-end to make up a single
 103     // memory descriptor.
 104     //
 105     // Passing the ranges as a reference will avoid an extra allocation.
 106     //
 107
 108     IOMultiMemoryDescriptor * me = new IOMultiMemoryDescriptor;
 109
 110     if ( me && me->initWithDescriptors(
 111                                   /* descriptors   */ descriptors,
 112                                   /* withCount     */ withCount,
 113                                   /* withDirection */ withDirection,
 114                                   /* asReference   */ asReference ) == false )
 115     {
 116             me->release();
 117             me = 0;
 118     }
 119
 120     return me;
 121 }
 122
 123 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 124
 125 bool IOMultiMemoryDescriptor::initWithDescriptors(
 126                                   IOMemoryDescriptor ** descriptors,
 127                                   UInt32                withCount,
 128                                   IODirection           withDirection,
 129                                   bool                  asReference )
 130 {
 131     //
 132     // Initialize an IOMultiMemoryDescriptor. The "buffer" is made up of several
 133     // memory descriptors, that are to be chained end-to-end to make up a single
 134     // memory descriptor.
 135     //
 136     // Passing the ranges as a reference will avoid an extra allocation.
 137     //
 138
 139     assert(descriptors);
 140     assert(withCount);
 141
 142     // Release existing descriptors, if any
 143     if ( _descriptors )
 144     {
 145         for ( unsigned index = 0; index < _descriptorsCount; index++ )
 146             _descriptors[index]->release();
 147
 148         if ( _descriptorsIsAllocated )
 149             IODelete(_descriptors, IOMemoryDescriptor *, _descriptorsCount);
 150     } else {
 151         // Ask our superclass' opinion.
 152         if ( super::init() == false )  return false;
 153     }
 154
 155     // Initialize our minimal state.
 156
 157     _descriptors            = 0;
 158     _descriptorsCount       = withCount;
 159     _descriptorsIsAllocated = asReference ? false : true;
 160     _direction              = withDirection;
 161     _length                 = 0;
 162     _mappings               = 0;
 163     _tag                    = 0;
 164
 165     if ( asReference )
 166     {
 167         _descriptors = descriptors;
 168     }
 169     else
 170     {
 171         _descriptors = IONew(IOMemoryDescriptor *, withCount);
 172         if ( _descriptors == 0 )  return false;
 173
 174         bcopy( /* from  */ descriptors,
 175                /* to    */ _descriptors,
 176                /* bytes */ withCount * sizeof(IOMemoryDescriptor *) );
 177     }
 178
 179     for ( unsigned index = 0; index < withCount; index++ )
 180     {
 181         descriptors[index]->retain();
 182         _length += descriptors[index]->getLength();
 183         if ( _tag == 0 )  _tag = descriptors[index]->getTag();
 184         assert(descriptors[index]->getDirection() == withDirection);
 185     }
 186
 187     return true;
 188 }
 189
 190 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 191
 192 void IOMultiMemoryDescriptor::free()
 193 {
 194     //
 195     // Free all of this object's outstanding resources.
 196     //
 197
 198     if ( _descriptors )
 199     {
 200         for ( unsigned index = 0; index < _descriptorsCount; index++ )
 201             _descriptors[index]->release();
 202
 203         if ( _descriptorsIsAllocated )
 204             IODelete(_descriptors, IOMemoryDescriptor *, _descriptorsCount);
 205     }
 206
 207     super::free();
 208 }
 209
 210 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 211
 212 IOReturn IOMultiMemoryDescriptor::prepare(IODirection forDirection)
 213 {
 214     //
 215     // Prepare the memory for an I/O transfer.
 216     //
 217     // This involves paging in the memory and wiring it down for the duration
 218     // of the transfer.  The complete() method finishes the processing of the
 219     // memory after the I/O transfer finishes.
 220     //
 221
 222     unsigned index;
 223     IOReturn status = kIOReturnInternalError;
 224     IOReturn statusUndo;
 225
 226     if ( forDirection == kIODirectionNone )
 227     {
 228         forDirection = _direction;
 229     }
 230
 231     for ( index = 0; index < _descriptorsCount; index++ )
 232     {
 233         status = _descriptors[index]->prepare(forDirection);
 234         if ( status != kIOReturnSuccess )  break;
 235     }
 236
 237     if ( status != kIOReturnSuccess )
 238     {
 239         for ( unsigned indexUndo = 0; indexUndo <= index; indexUndo++ )
 240         {
 241             statusUndo = _descriptors[index]->complete(forDirection);
 242             assert(statusUndo == kIOReturnSuccess);
 243         }
 244     }
 245
 246     return status;
 247 }
 248
 249 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 250
 251 IOReturn IOMultiMemoryDescriptor::complete(IODirection forDirection)
 252 {
 253     //
 254     // Complete processing of the memory after an I/O transfer finishes.
 255     //
 256     // This method shouldn't be called unless a prepare() was previously issued;
 257     // the prepare() and complete() must occur in pairs, before and after an I/O
 258     // transfer.
 259     //
 260
 261     IOReturn status;
 262     IOReturn statusFinal = kIOReturnSuccess;
 263
 264     if ( forDirection == kIODirectionNone )
 265     {
 266         forDirection = _direction;
 267     }
 268
 269     for ( unsigned index = 0; index < _descriptorsCount; index++ )
 270     {
 271         status = _descriptors[index]->complete(forDirection);
 272         if ( status != kIOReturnSuccess )  statusFinal = status;
 273         assert(status == kIOReturnSuccess);
 274     }
 275
 276     return statusFinal;
 277 }
 278
 279 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 280
 281 IOPhysicalAddress IOMultiMemoryDescriptor::getPhysicalSegment(
 282                                                        IOByteCount   offset,
 283                                                        IOByteCount * length )
 284 {
 285     //
 286     // This method returns the physical address of the byte at the given offset
 287     // into the memory,  and optionally the length of the physically contiguous
 288     // segment from that offset.
 289     //
 290
 291     assert(offset <= _length);
 292
 293     for ( unsigned index = 0; index < _descriptorsCount; index++ )
 294     {
 295         if ( offset < _descriptors[index]->getLength() )
 296         {
 297             return _descriptors[index]->getPhysicalSegment(offset, length);
 298         }
 299         offset -= _descriptors[index]->getLength();
 300     }
 301
 302     if ( length )  *length = 0;
 303
 304     return 0;
 305 }
 306
 307 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 308
 309 IOPhysicalAddress IOMultiMemoryDescriptor::getSourceSegment(
 310                                                        IOByteCount   offset,
 311                                                        IOByteCount * length )
 312 {
 313     //
 314     // This method returns the physical address of the byte at the given offset
 315     // into the memory,  and optionally the length of the physically contiguous
 316     // segment from that offset.
 317     //
 318
 319     assert(offset <= _length);
 320
 321     for ( unsigned index = 0; index < _descriptorsCount; index++ )
 322     {
 323         if ( offset < _descriptors[index]->getLength() )
 324         {
 325             return _descriptors[index]->getSourceSegment(offset, length);
 326         }
 327         offset -= _descriptors[index]->getLength();
 328     }
 329
 330     if ( length )  *length = 0;
 331
 332     return 0;
 333 }
 334
 335 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 336
 337 void * IOMultiMemoryDescriptor::getVirtualSegment( IOByteCount   /* offset */ ,
 338                                                    IOByteCount * /* length */ )
 339 {
 340     return 0;
 341 }
 342
 343 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 344
 345 IOByteCount IOMultiMemoryDescriptor::readBytes( IOByteCount offset,
 346                                                 void *      bytes,
 347                                                 IOByteCount withLength )
 348 {
 349     //
 350     // Copies data from the memory descriptor's buffer at the given offset, to
 351     // the specified buffer.  Returns the number of bytes copied.
 352     //
 353
 354     IOByteCount bytesCopied = 0;
 355     unsigned    index;
 356
 357     for ( index = 0; index < _descriptorsCount; index++ )
 358     {
 359         if ( offset < _descriptors[index]->getLength() )  break;
 360         offset -= _descriptors[index]->getLength();
 361     }
 362
 363     for ( ; index < _descriptorsCount && withLength; index++)
 364     {
 365         IOByteCount copy   = min(_descriptors[index]->getLength(), withLength);
 366         IOByteCount copied = _descriptors[index]->readBytes(offset,bytes,copy);
 367
 368         bytesCopied += copied;
 369         if ( copied != copy )  break;
 370
 371         bytes = ((UInt8 *) bytes) + copied;
 372         withLength -= copied;
 373         offset = 0;
 374     }
 375
 376     return bytesCopied;
 377 }
 378
 379 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 380
 381 IOByteCount IOMultiMemoryDescriptor::writeBytes( IOByteCount  offset,
 382                                                  const void * bytes,
 383                                                  IOByteCount  withLength )
 384 {
 385     //
 386     // Copies data to the memory descriptor's buffer at the given offset, from
 387     // the specified buffer.  Returns the number of bytes copied.
 388     //
 389
 390     IOByteCount bytesCopied = 0;
 391     unsigned    index;
 392
 393     for ( index = 0; index < _descriptorsCount; index++ )
 394     {
 395         if ( offset < _descriptors[index]->getLength() )  break;
 396         offset -= _descriptors[index]->getLength();
 397     }
 398
 399     for ( ; index < _descriptorsCount && withLength; index++)
 400     {
 401         IOByteCount copy   = min(_descriptors[index]->getLength(), withLength);
 402         IOByteCount copied = _descriptors[index]->writeBytes(offset,bytes,copy);
 403
 404         bytesCopied += copied;
 405         if ( copied != copy )  break;
 406
 407         bytes = ((UInt8 *) bytes) + copied;
 408         withLength -= copied;
 409         offset = 0;
 410     }
 411
 412     return bytesCopied;
 413 }