IOReportLegend.cpp   [plain text]

/*
 * Copyright (c) 2012-2013 Apple Computer, Inc.  All Rights Reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#include <IOKit/IOKernelReportStructs.h>
#include <IOKit/IOKernelReporters.h>


//#define IORDEBUG_LEGEND 1

#ifdef IORDEBUG_LEGEND
    #define IORLEGENDLOG(fmt, args...)      \
    do {                                    \
	IOLog("IOReportLegend | ");         \
	IOLog(fmt, ##args);                 \
	IOLog("\n");                        \
    } while(0)
#else
    #define IORLEGENDLOG(fmt, args...)
#endif


#define super OSObject
OSDefineMetaClassAndStructors(IOReportLegend, OSObject);

IOReportLegend*
IOReportLegend::with(OSArray *legend)
{
	IOReportLegend *iorLegend = new IOReportLegend;

	if (iorLegend) {
		if (legend != NULL) {
			if (iorLegend->initWith(legend) != kIOReturnSuccess) {
				OSSafeReleaseNULL(iorLegend);
				return NULL;
			}
		}

		return iorLegend;
	} else {
		return NULL;
	}
}

/* must clean up everything if it fails */
IOReturn
IOReportLegend::initWith(OSArray *legend)
{
	if (legend) {
		_reportLegend = OSArray::withArray(legend);
	}

	if (_reportLegend == NULL) {
		return kIOReturnError;
	} else {
		return kIOReturnSuccess;
	}
}


void
IOReportLegend::free(void)
{
	if (_reportLegend) {
		_reportLegend->release();
	}
	super::free();
}


OSArray*
IOReportLegend::getLegend(void)
{
	return _reportLegend;
}

IOReturn
IOReportLegend::addReporterLegend(IOService *reportingService,
    IOReporter *reporter,
    const char *groupName,
    const char *subGroupName)
{
	IOReturn res = kIOReturnError;
	IOReportLegend *legend = NULL;
	OSObject *curLegend = NULL;

	// No need to check groupName and subGroupName because optional params
	if (!reportingService || !reporter) {
		goto finish;
	}

	// It's fine if the legend doesn't exist (IOReportLegend::with(NULL)
	// is how you make an empty legend).  If it's not an array, then
	// we're just going to replace it.
	curLegend = reportingService->copyProperty(kIOReportLegendKey);
	legend = IOReportLegend::with(OSDynamicCast(OSArray, curLegend));
	if (!legend) {
		goto finish;
	}

	// Add the reporter's entries and update the service property.
	// The overwrite triggers a release of the old legend array.
	legend->addReporterLegend(reporter, groupName, subGroupName);
	reportingService->setProperty(kIOReportLegendKey, legend->getLegend());
	reportingService->setProperty(kIOReportLegendPublicKey, true);

	res = kIOReturnSuccess;

finish:
	if (legend) {
		legend->release();
	}
	if (curLegend) {
		curLegend->release();
	}

	return res;
}


IOReturn
IOReportLegend::addLegendEntry(IOReportLegendEntry *legendEntry,
    const char *groupName,
    const char *subGroupName)
{
	kern_return_t res = kIOReturnError;
	const OSSymbol *tmpGroupName = NULL;
	const OSSymbol *tmpSubGroupName = NULL;

	if (!legendEntry) {
		goto finish;
	}

	if (groupName) {
		tmpGroupName = OSSymbol::withCString(groupName);
	}

	if (subGroupName) {
		tmpSubGroupName = OSSymbol::withCString(subGroupName);
	}

	// It is ok to call appendLegendWith() if tmpGroups are NULL
	if (legendEntry) {
		res = organizeLegend(legendEntry, tmpGroupName, tmpSubGroupName);

		if (tmpGroupName) {
			tmpGroupName->release();
		}
		if (tmpSubGroupName) {
			tmpSubGroupName->release();
		}
	}

finish:
	return res;
}


IOReturn
IOReportLegend::addReporterLegend(IOReporter *reporter,
    const char *groupName,
    const char *subGroupName)
{
	IOReturn res = kIOReturnError;
	IOReportLegendEntry *legendEntry = NULL;

	if (reporter) {
		legendEntry = reporter->createLegend();

		if (legendEntry) {
			res = addLegendEntry(legendEntry, groupName, subGroupName);
			legendEntry->release();
		}
	}

	return res;
}


IOReturn
IOReportLegend::organizeLegend(IOReportLegendEntry *legendEntry,
    const OSSymbol *groupName,
    const OSSymbol *subGroupName)
{
	IOReturn res = kIOReturnError;

	if (!legendEntry) {
		return res = kIOReturnBadArgument;
	}

	if (!groupName && subGroupName) {
		return res = kIOReturnBadArgument;
	}

	IORLEGENDLOG("IOReportLegend::organizeLegend");
	// Legend is empty, enter first node
	if (_reportLegend == NULL) {
		IORLEGENDLOG("IOReportLegend::new legend creation");
		_reportLegend = OSArray::withCapacity(1);

		if (!_reportLegend) {
			return kIOReturnNoMemory;
		}
	}

	if (groupName) {
		legendEntry->setObject(kIOReportLegendGroupNameKey, groupName);
	}

	if (subGroupName) {
		legendEntry->setObject(kIOReportLegendSubGroupNameKey, subGroupName);
	}

	_reportLegend->setObject(legendEntry);

	// callers can now safely release legendEntry (it is part of _reportLegend)

	return res = kIOReturnSuccess;
}