/*

     File: AppleSamplePCI.cpp

 Abstract: This is a tiny driver that attaches to a PCI device and logs information

    about it. It doesn't alter the device in any way. It also supports a

    generic IOUserClient subclass that allows driver-specific client code to

    make various kinds of calls into the driver, and map shared memory

    or portions of hardware memory.

  Version: 1.1

 Disclaimer: IMPORTANT:  This Apple software is supplied to you by Apple

 Inc. ("Apple") in consideration of your agreement to the following

 terms, and your use, installation, modification or redistribution of

 this Apple software constitutes acceptance of these terms.  If you do

 not agree with these terms, please do not use, install, modify or

 redistribute this Apple software.

 In consideration of your agreement to abide by the following terms, and

 subject to these terms, Apple grants you a personal, non-exclusive

 license, under Apple's copyrights in this original Apple software (the

 "Apple Software"), to use, reproduce, modify and redistribute the Apple

 Software, with or without modifications, in source and/or binary forms;

 provided that if you redistribute the Apple Software in its entirety and

 without modifications, you must retain this notice and the following

 text and disclaimers in all such redistributions of the Apple Software.

 Neither the name, trademarks, service marks or logos of Apple Inc. may

 be used to endorse or promote products derived from the Apple Software

 without specific prior written permission from Apple.  Except as

 expressly stated in this notice, no other rights or licenses, express or

 implied, are granted by Apple herein, including but not limited to any

 patent rights that may be infringed by your derivative works or by other

 works in which the Apple Software may be incorporated.

 The Apple Software is provided by Apple on an "AS IS" basis.  APPLE

 MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION

 THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS

 FOR A PARTICULAR PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND

 OPERATION ALONE OR IN COMBINATION WITH YOUR PRODUCTS.

 IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL

 OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

 INTERRUPTION) ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION,

 MODIFICATION AND/OR DISTRIBUTION OF THE APPLE SOFTWARE, HOWEVER CAUSED

 AND WHETHER UNDER THEORY OF CONTRACT, TORT (INCLUDING NEGLIGENCE),

 STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN ADVISED OF THE

 POSSIBILITY OF SUCH DAMAGE.

 Copyright (C) 2013 Apple Inc. All Rights Reserved.

*/

#include <IOKit/IOBufferMemoryDescriptor.h>

#include <IOKit/pci/IOPCIDevice.h>

#include <IOKit/IODMACommand.h>

#include <IOKit/IOLib.h>

#include <IOKit/assert.h>

#include "AppleSamplePCI.h"

/* 

 * Define the metaclass information that is used for runtime

 * typechecking of IOKit objects. We're a subclass of IOService,

 * but usually we would subclass from a family class.

 */

#define super IOService

/*

 * Even though we are defining the convenience macro super for the superclass, you must use the actual class name

 * in the OS*MetaClass macros.

 */

OSDefineMetaClassAndStructors(com_example_apple_samplecode_driver_SamplePCI, IOService)

// This function will be called when the user process calls IORegistryEntrySetCFProperties on

// this driver. You can add your custom functionality to this function.

IOReturn SamplePCIClassName::setProperties(OSObject* properties)

{

    OSDictionary*   dict;

    OSNumber*       number;

    dict = OSDynamicCast(OSDictionary, properties);

    if (!dict) {

        return kIOReturnBadArgument;

    }

    // We're adding the property to the registry here.

    number = OSDynamicCast(OSNumber, dict->getObject(kMyDisplayValueKey));

    if (number != NULL) {

        uint32_t value = number->unsigned32BitValue();

        IOLog("%s[%p]::%s(%p) got value %u\n", getName(), this, __FUNCTION__, properties, value);

        updateRegistry(value);

        return kIOReturnSuccess;

    }

    else {

        return super::setProperties(properties);

    }

}

// updateRegistry does the actual I/O Registry update.

// It is important to note that we work on a copy of the section of the I/O Registry

// until the actual reinsertion into the I/O Registry.

// The setProperty call is serialized for us and is the only safe way to 

// handle this.

void SamplePCIClassName::updateRegistry(UInt32 value)

{

    // Directly changing a collection in the I/O Registry is not supported as it is not protected against

    // multiple writers. So expose a copy and work on that instead.

    OSDictionary* dict = OSDynamicCast(OSDictionary, copyProperty(kMyDisplayParametersKey));

    OSDictionary* copyDict = (OSDictionary*) dict->copyCollection();

    if (copyDict != NULL) {

        OSDictionary* copyBrightnessDict = OSDynamicCast(OSDictionary, copyDict->getObject(kMyDisplayBrightnessKey));

        if (copyBrightnessDict != NULL) {

            OSNumber* num = OSDynamicCast(OSNumber, copyBrightnessDict->getObject(kMyDisplayValueKey));

            if (num != NULL) {

                num->setValue(value);

                // setProperty correctly serializes I/O Registry updates for our protection.

                setProperty(kMyDisplayParametersKey, copyDict);

            }

        }

        copyDict->release();

    }

}

bool SamplePCIClassName::start(IOService* provider)

{

    IOMemoryDescriptor*     mem;

    IOMemoryMap*            map;

    IOLog("%s[%p]::%s(%p)\n", getName(), this, __FUNCTION__, provider);

    if (!super::start(provider)) {

        return false;

    }

    /*

     * Our provider class is specified in the driver property table

     * as IOPCIDevice, so the provider must be of that class.

     * The assert is just to make absolutely sure for debugging.

     */

    assert(OSDynamicCast(IOPCIDevice, provider));

    fPCIDevice = (IOPCIDevice*) provider;

    /*

     * Enable memory response from the card

     */

    fPCIDevice->setMemoryEnable(true);

    /*

     * Log some info about the device

     */

    /* Print all of the device's memory ranges */

    for (uint32_t index = 0; index < fPCIDevice->getDeviceMemoryCount(); index++) {

        mem = fPCIDevice->getDeviceMemoryWithIndex(index);

        assert(mem);

        IOLog("Range[%d] " PhysAddr_FORMAT ":" ByteCount_FORMAT "\n", index,

             mem->getPhysicalAddress(), mem->getLength());

    }

    /* Look up a range based on its config space base address register */

    mem = fPCIDevice->getDeviceMemoryWithRegister(kIOPCIConfigBaseAddress0);

    if (mem != NULL) {

        IOLog("Range@0x%x " PhysAddr_FORMAT ":" ByteCount_FORMAT "\n", kIOPCIConfigBaseAddress0,

             mem->getPhysicalAddress(), mem->getLength());

    }

    /* Map a range based on its config space base address register,

     * This is how the driver gets access to its memory-mapped registers.

     * The getVirtualAddress() method returns a kernel virtual address

     * for the register mapping */

    map = fPCIDevice->mapDeviceMemoryWithRegister(kIOPCIConfigBaseAddress0);

    if (map != NULL) {

        IOLog("Range@0x%x (" PhysAddr_FORMAT ") mapped to kernel virtual address " VirtAddr_FORMAT "\n",

              kIOPCIConfigBaseAddress0,

              map->getPhysicalAddress(),

              map->getVirtualAddress() 

              );

        /* Release the map object, and the mapping itself */

        map->release();

    }

    /* Read a config space register */

    IOLog("Config register@0x%x = " UInt32_FORMAT "\n", kIOPCIConfigCommand,

            fPCIDevice->configRead32(kIOPCIConfigCommand) );

    // Construct a memory descriptor for a buffer below the 4Gb physical line &

    // so addressable by 32-bit DMA. This could be used for a 

    // DMA program buffer, for example.

    IOBufferMemoryDescriptor *bmd = 

        IOBufferMemoryDescriptor::inTaskWithPhysicalMask(

                                                         // task to hold the memory

                                                         kernel_task, 

                                                         // options

                                                         kIOMemoryPhysicallyContiguous, 

                                                         // size

                                                         64*1024, 

                                                         // physicalMask - 32 bit addressable and page aligned

                                                         0x00000000FFFFF000ULL);

    if (bmd != NULL) {

        generateDMAAddresses(bmd);

    } else {

        IOLog("IOBufferMemoryDescriptor::inTaskWithPhysicalMask failed\n");

    }

    fLowMemory = bmd;

    /* Publish ourselves so clients can find us */

    registerService();

    return true;

}

/*

 * We'll come here when the device goes away, or the driver is unloaded.

 */

void SamplePCIClassName::stop(IOService* provider)

{

    IOLog("%s[%p]::%s(%p)\n", getName(), this, __FUNCTION__, provider);

    super::stop(provider);

}

/*

 * Method to supply an IOMemoryDescriptor for the user client to map into

 * the client process. This sample just supplies all of the hardware memory

 * associated with the PCI device's Base Address Register 0.

 * In a real driver mapping hardware memory would only ever be used in some

 * limited high performance scenarios where the device range can be safely

 * accessed by client code with compromising system stability.

 */

IOMemoryDescriptor* SamplePCIClassName::copyGlobalMemory(void)

{

    IOMemoryDescriptor* memory;

    memory = fPCIDevice->getDeviceMemoryWithRegister(kIOPCIConfigBaseAddress0);

    if (memory != NULL) {

        memory->retain();

    }

    return memory;

}

IOReturn SamplePCIClassName::generateDMAAddresses(IOMemoryDescriptor* memDesc)

{

    // Get the physical segment list. These could be used to generate a scatter gather

    // list for hardware.

    IODMACommand*       cmd;

    IOReturn            err = kIOReturnSuccess;

    // 64 bit physical address generation using IODMACommand

    do

    {

        cmd = IODMACommand::withSpecification(

                                              // outSegFunc - Host endian since we read the address data with the cpu

                                              // and 64 bit wide quantities

                                              kIODMACommandOutputHost64, 

                                              // numAddressBits

                                              64, 

                                              // maxSegmentSize - zero for unrestricted physically contiguous chunks

                                              0,

                                              // mappingOptions - kMapped for DMA addresses

                                              IODMACommand::kMapped,

                                              // maxTransferSize - no restriction

                                              0,

                                              // alignment - no restriction

                                              1 );

        if (cmd == NULL) {

            IOLog("IODMACommand::withSpecification failed\n");

            break;

        }

        // Point at the memory descriptor and use the auto prepare option

        // to prepare the entire range

        err = cmd->setMemoryDescriptor(memDesc);

        if (kIOReturnSuccess != err) {

            IOLog("setMemoryDescriptor failed (0x%08x)\n", err);

            break;

        }

        UInt64 offset = 0;

        while ((kIOReturnSuccess == err) && (offset < memDesc->getLength())) {

            // Use the 64 bit variant to match outSegFunc

            IODMACommand::Segment64 segments[1];

            UInt32 numSeg = 1;

            // Use the 64 bit variant to match outSegFunc

            err = cmd->gen64IOVMSegments(&offset, &segments[0], &numSeg);

            IOLog("gen64IOVMSegments(%x) addr 0x%016llx, len %llu, nsegs " UInt32_FORMAT "\n",

                  err, segments[0].fIOVMAddr, segments[0].fLength, numSeg);

        }

        // if we had a DMA controller, kick off the DMA here

        // when the DMA has completed,

        // clear the memory descriptor and use the auto complete option

        // to complete the transaction

        err = cmd->clearMemoryDescriptor();

        if (kIOReturnSuccess != err) {

            IOLog("clearMemoryDescriptor failed (0x%08x)\n", err);

        }

    } while (false);

    if (cmd != NULL) {

        cmd->release();

    }

    // end 64 bit loop

    // 32 bit physical address generation using IODMACommand

    // any memory above 4GiB in the memory descriptor will be bounce-buffered

    // to memory below the 4GiB line on machines without remapping HW support

    do

    {

        cmd = IODMACommand::withSpecification(

                                              // outSegFunc - Host endian since we read the address data with the cpu

                                              // and 32 bit wide quantities

                                              kIODMACommandOutputHost32, 

                                              // numAddressBits

                                              32, 

                                              // maxSegmentSize - zero for unrestricted physically contiguous chunks

                                              0,

                                              // mappingOptions - kMapped for DMA addresses

                                              IODMACommand::kMapped,

                                              // maxTransferSize - no restriction

                                              0,

                                              // alignment - no restriction

                                              1 );

        if (cmd == NULL) {

            IOLog("IODMACommand::withSpecification failed\n");

            break;

        }

        // point at the memory descriptor and use the auto prepare option

        // to prepare the entire range

        err = cmd->setMemoryDescriptor(memDesc);

        if (kIOReturnSuccess != err) {

            IOLog("setMemoryDescriptor failed (0x%08x)\n", err);

            break;

        }

        UInt64 offset = 0;

        while ((kIOReturnSuccess == err) && (offset < memDesc->getLength())) {

            // use the 32 bit variant to match outSegFunc

            IODMACommand::Segment32 segments[1];

            UInt32 numSeg = 1;

            // use the 32 bit variant to match outSegFunc

            err = cmd->gen32IOVMSegments(&offset, &segments[0], &numSeg);

            IOLog("gen32IOVMSegments(%x) addr " UInt32_x_FORMAT ", len " UInt32_FORMAT ", nsegs " UInt32_FORMAT "\n",

                  err, segments[0].fIOVMAddr, segments[0].fLength, numSeg);

        }

        // if we had a DMA controller, kick off the DMA here

        // when the DMA has completed,

        // clear the memory descriptor and use the auto complete option

        // to complete the transaction

        err = cmd->clearMemoryDescriptor();

        if (kIOReturnSuccess != err) {

            IOLog("clearMemoryDescriptor failed (0x%08x)\n", err);

        }

    } while (false);

    if (cmd != NULL) {

        cmd->release();

    }

    // end 32 bit loop

    return err;

}