Используя макросы конструктора OSMetaClass

При создании класса C++ на основе OSObject код должен вызвать соответствующую пару макросов, основанных на классе OSMetaClass. Вызовы должны быть среди первых операторов и в определении и в реализации класса. Они макросы критически важны по отношению к Вашему классу, потому что они вводят информацию о метаклассе об этом в libkern средство ввода времени выполнения и определяют статического конструктора и деструктор для Вашего класса.

Для бетона (т.е. некраткий обзор) классы, первый макрос, OSDeclareDefaultStructors объявляет конструкторов C++; условно Вы вставляете этот макрос как первый элемент объявления класса в заголовочном файле. Например:

class com_MyCompany_driver_MyDriver : public IOService

{

    OSDeclareDefaultStructors(com_MyCompany_driver_MyDriver);

    /* ... */

};

Ваша реализация класса должна включать компаньона, «определяют» макрос, OSDefineMetaClassAndStructors. Этот макрос определяет конструктора и деструктор, реализует функцию членства выделения OSMetaClass (alloc) для класса, и предоставляет информацию метакласса для системы типов во время выполнения. OSDefineMetaClassAndStructors берет в качестве параметров имя Вашего водительского класса и имя его базового класса. Это использует их для генерации кода, позволяющего классу драйвера быть загруженным и инстанцированным, в то время как работает ядро. Это обычно происходит как один из первых операторов реализации класса. Например, MyDriver.cpp мог бы начаться как это:

#include "MyDriver.h"

// This convention makes it easy to invoke base class member functions.

#define super    IOService

// You cannot use the "super" macro here, however, with the

//  OSDefineMetaClassAndStructors macro.

OSDefineMetaClassAndStructors(com_MyCompany_driver_MyDriver, IOService);

Если класс абстрактным классом, предназначенным только, чтобы быть наследованным от, использовать, который Вы определяете является OSDeclareAbstractStructors и OSDefineMetaClassAndAbstractStructors макросы вместо этого. Они макросы делают те же вещи как их неабстрактные дубликаты за исключением того, что они делают основного конструктора частным и определяют alloc функция членства для возврата нуля.

OSDefineMetaClassAndStructors и OSDefineMetaClassAndAbstractStructorsмакросы основываются на двух других макросах OSMetaClass: OSDefineMetaClassAndStructorsWithInit и OSDefineMetaClassAndAbstractStructorsWithInit, соответственно. Эти последние два макросы осуждаются и не должны использоваться непосредственно.

Выделение объектов динамично

OSMetaClass играет важную роль в libkern время выполнения C++ путем выделения объектов, основанных на типе класса. Производные классы OSMetaClass могут сделать это динамично путем реализации allocфункция; тип класса предоставляется самим производным классом OSMetaClass. Как упомянуто в предыдущем разделе, Области объекта и Вызове конструктора, конструкторах, создаваемых реализацией макросов OSMetaClass alloc автоматически для Вашего класса.

Контейнерные классы libkern и семьи Набора I/O обеспечивают различные функции членства помощника для создания (выделения) объекты, и это то, что Вы используете большую часть времени. Но можно также непосредственно выделить экземпляр любого libkern или класса Набора I/O с помощью двух видов вызовов OSMetaClass:

• Путем вызова одного из OSMetaClass allocClassWithNameфункции, предоставляя идентификацию типа класса (как OSSymbol, OSString или струна до)

• Путем вызова макроса OSTypeAlloc (определенный в классе OSMetaClassBase)

Оба allocClassWithName и OSTypeAlloc макрос подобен в этом, они берут некоторую индикацию относительно типа как единственный параметр. Однако существует важное различие. Из-за артефакта препроцессора макрос берет аргумент типа, который является символом времени компиляции и не строкой; таким образом макрос более эффективен, чем динамическое выделение, выполняемое allocClassWithName функции членства, но это не действительно динамично. Функции членства выделения задерживают привязку до времени выполнения, тогда как макрос генерирует разовую ссылкой ошибку, если расширение ядра должным образом не укажет зависимости аргумента типа. Кроме того, макрос, в отличие от функций, бросает результат к надлежащему типу для Вас.

OSTypeAlloc макрос предназначается для замены C++ new оператор, когда Вы создаете объекты, полученные из OSObject. Причиной позади этого изменения является совместимость на уровне двоичных кодов: new оператор хрупок, если Вы создаете объект, не существующий в том же расширении ядра как Ваш код. Путем передачи размера класса как параметр malloc, C++ компилирует значение размера в двоичный файл вызова. Но если существуют какие-либо зависимости от того размера, и класс позже становится больше, двоичный файл мог бы прервать различные тонкие пути, такой как путем переписывания последующих блоков выделения. OSTypeAlloc макрос, с другой стороны, позволяет классу, делающему выделение определять свой собственный размер.

Недавно выделенные объекты, создаваемые с макросом выделения или функциями, имеют сохранить количество одного как их единственный элемент данных и являются иначе неинициализированными. После выделения необходимо сразу вызвать функцию членства инициализации объекта (обычно init или некоторый вариант init). Код инициализации таким образом имеет возможность протестировать, допустим ли объект и возвратить надлежащий код ошибки, если это не.

Глобальные инициализаторы

Глобальные конструкторы — иногда называемый глобальными инициализаторами — являются полезной функцией языка C++. Для драйверов они разрешают безопасную инициализацию и выделение ресурсов, которые должны быть доступными, прежде чем драйвер начнет передавать данные. Для надлежащего понимания, что глобальные конструкторы и почему они полезны давайте сначала рассмотрим, когда объекты C++ с различными видами объема создаются и уничтожаются.

class IOSerialBSDClientGlobals {

private:

    unsigned int fMajor;

    unsigned int fLastMinor;

    IOSerialBSDClient **fClients;

    OSDictionary *fNames;

public:

    IOSerialBSDClientGlobals();

    ~IOSerialBSDClientGlobals();

    inline bool isValid();

    inline IOSerialBSDClient *getClient(dev_t dev);

    dev_t assign_dev_t();

    bool registerTTY(dev_t dev, IOSerialBSDClient *tty);

    const OSSymbol *getUniqueTTYSuffix

        (const OSSymbol *inName, const OSSymbol *suffix, dev_t dev);

    void releaseUniqueTTYSuffix(const OSSymbol *inName, const OSSymbol *suffix);

};

static IOSerialBSDClientGlobals sBSDGlobals;

#define OSSYM(str) OSSymbol::withCStringNoCopy(str)

IOSerialBSDClientGlobals::IOSerialBSDClientGlobals()

{

    gIOSerialBSDServiceValue = OSSYM(kIOSerialBSDServiceValue);

    gIOSerialBSDTypeKey      = OSSYM(kIOSerialBSDTypeKey);

    gIOSerialBSDAllTypes     = OSSYM(kIOSerialBSDAllTypes);

    gIOSerialBSDModemType    = OSSYM(kIOSerialBSDModemType);

    gIOSerialBSDRS232Type    = OSSYM(kIOSerialBSDRS232Type);

    gIOTTYDeviceKey          = OSSYM(kIOTTYDeviceKey);

    gIOTTYBaseNameKey        = OSSYM(kIOTTYBaseNameKey);

    gIOTTYSuffixKey          = OSSYM(kIOTTYSuffixKey);

    gIOCalloutDeviceKey      = OSSYM(kIOCalloutDeviceKey);

    gIODialinDeviceKey       = OSSYM(kIODialinDeviceKey);

    gIOTTYWaitForIdleKey     = OSSYM(kIOTTYWaitForIdleKey);

    fMajor = (unsigned int) -1;

    fNames = OSDictionary::withCapacity(4);

    fLastMinor = 4;

    fClients = (IOSerialBSDClient **)

                IOMalloc(fLastMinor * sizeof(fClients[0]));

    if (fClients && fNames) {

        bzero(fClients, fLastMinor * sizeof(fClients[0]));

        fMajor = cdevsw_add(-1, &IOSerialBSDClient::devsw);

    }

    if (!isValid())

        IOLog("IOSerialBSDClient didn't initialize");

}

#undef OSSYM

IOSerialBSDClientGlobals::~IOSerialBSDClientGlobals()

{

    SAFE_RELEASE(gIOSerialBSDServiceValue);

    SAFE_RELEASE(gIOSerialBSDTypeKey);

    SAFE_RELEASE(gIOSerialBSDAllTypes);

    SAFE_RELEASE(gIOSerialBSDModemType);

    SAFE_RELEASE(gIOSerialBSDRS232Type);

    SAFE_RELEASE(gIOTTYDeviceKey);

    SAFE_RELEASE(gIOTTYBaseNameKey);

    SAFE_RELEASE(gIOTTYSuffixKey);

    SAFE_RELEASE(gIOCalloutDeviceKey);

    SAFE_RELEASE(gIODialinDeviceKey);

    SAFE_RELEASE(gIOTTYWaitForIdleKey);

    SAFE_RELEASE(fNames);

    if (fMajor != (unsigned int) -1)

        cdevsw_remove(fMajor, &IOSerialBSDClient::devsw);

    if (fClients)

        IOFree(fClients, fLastMinor * sizeof(fClients[0]));

}

Проблема хрупкого базового класса

Проблема хрупкого базового класса влияет только на нелистовые классы, и затем только, когда те классы определяются в различном KEXTs. Таким образом, если Вы никогда не предназначите свой libkern или класс Набора I/O, чтобы быть базовым классом, то тогда хрупкие базовые классы не будут проблемой (и у Вас нет потребности читать далее). Но если Ваш класс мог бы быть базовым классом к некоторому другому классу, и Вы позже изменяете свой класс определенными способами, все внешние KEXTs с зависимостями от Вашего класса, вероятно, испытают проблемы, которые заставят их повреждаться.

Не все изменения в нелистовом классе делают его хрупким базовым классом. Например, можно добавить невиртуальные функции или даже новые классы расширения ядра без опасности. Если у Вас будет функция, которая является полипревращенной версией виртуальной функции базового класса, то у Вас не будет проблемы также. И можно всегда повторно реализовывать функцию членства, виртуальную или невиртуальную. Но существуют определенные дополнения и модификации, которые почти наверняка вызовут проблемы совместимости на уровне двоичных кодов:

• Новые виртуальные функции членства

• Изменения в порядке объявлений виртуальной функции

• Новые переменные экземпляра (элементы данных)

• Изменения в типе или размере переменных экземпляра (например, изменяясь a short к a long или увеличение максимального размера массива)

Причина эти модификации к нелистовому классу представляют хрупкость, состоит в том, что KEXTs, содержащие производные классы того класса, включают знание характеристик базового класса, таких как:

• Размер объекта

• Смещения к защищенным или общедоступным данным

• Размер виртуальной (vtable) таблицы Вашего класса, а также смещения в нем

Код, зависящий от этих размеров и смещений, повредится, если размер или сместит впоследствии изменения. Для рассмотрения его иначе каждый скомпилированный класс C++ является, внутренне, двумя структурами. Одна структура содержит элементы агрегированных данных в цепочке наследования; другая структура содержит совокупные виртуальные таблицы той же цепочки наследования. (Экземпляр класса содержит все элементы агрегированных данных и содержит указатель на один экземпляр совокупных виртуальных таблиц.) Время выполнения C++ использует размеры и смещает создаваемый этими связанными структурами для определения местоположения элементов данных и функций членства. Рисунок 1-2 иллюстрирует абстрактным способом, как эти структуры могли бы быть размечены внутренне.

libkern библиотека C++ имеет механизмы, смягчающие проблему хрупкого базового класса. В основном эти методы позволяют Вам создать “слоты клавиатуры” (т.е. зарезервированные поля) и для элементов данных и для виртуальных функций, ожидаемых для будущего расширения. Следующие разделы объясняют, как дополнить класс, и затем как скорректировать дополнение каждый раз, когда Вы добавляете новые элементы данных или виртуальные функции.

Резервирование будущих элементов данных

Для подготовки нелистового класса к любому будущему добавлению элементов данных укажите пустое ExpansionData структура и a reserved указатель на ту структуру. Затем когда Вы добавляете поле к этой структуре, выделяете эти дополнительные данные в функции членства инициализации для класса (обычно init).

Введите строки в Перечисление 1-5 в Ваш заголовочный файл класса в разделе с защищенным объемом (как обозначено).

  Объявления Начальной буквы перечисления 1-5 ExpansionData структура и reserved указатель

protected:

/*! @struct ExpansionData

    @discussion This structure helps to expand the capabilities of

    this class in the future.

    */

    struct ExpansionData { };

/*! @var reserved

    Reserved for future use.  (Internal use only)  */

    ExpansionData *reserved;

Позже, когда необходимо добавить новые элементы данных к классу, добавьте поле или поля к ExpansionData структура и определяет символ препроцессора для поля, как ссылается reserved указатель. Перечисление 1-6 показывает, как Вы могли бы сделать это.

Перечисление 1-6  , Добавляющее новое поле к ExpansionData структура

struct ExpansionData { int eBlastIForgot; };

ExpansionData *reserved;

#define fBlastIForgot ((com_acme_driver_MyDriverClass::ExpansionData *)

            com_acme_driver_MyDriverClass::reserved)->eBlastIForgot)

Наконец, во время инициализации, выделите недавно расширенную структуру.

Дополнение виртуальной таблицы

Первый шаг к дополнению виртуальной таблицы Вашего класса должен оценить, в каком количестве слотов клавиатуры Вы будете нуждаться — т.е. сколько виртуальных функций могло бы быть добавлено к Вашему классу в будущем. Вы не хотите добавлять слишком многих, поскольку это могло излишне чрезмерно увеличить размер объема потребляемой памяти Вашего кода, и Вы не хотите добавлять лишь немногих по очевидным причинам. Хороший метод оценки является следующим:

1. Считайте виртуальные функции в своем классе, которые являются просто полипревращенными версиями виртуальной функции базового класса.

2. Вычтите то значение из общего количества виртуальных функций в Вашем классе.

3. Выберите число между результатом вычитания и общим количеством виртуальных функций. Ваш выбор, конечно, должен быть под влиянием Вашего смысла того, какому количеству обновление API могло бы подвергнуться в будущем.

Когда Вы определили, в каком количестве зарезервированных слотов Вы будете нуждаться для будущего расширения, укажите OSMetaClassDeclareReservedUnused макрос в Вашем заголовочном файле класса для каждого слота. Этот макрос берет два параметра: имя класса и индекс слота клавиатуры. Перечисление 1-7 показывает, как класс IOHIDDevice указывает OSMetaClassDeclareReservedUnused макрос.

Перечисление 1-7  начальное дополнение класса виртуальная таблица (заголовочный файл)

public:

    // ...

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  0);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  1);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  2);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  3);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  4);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  5);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  6);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  7);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  8);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  9);

    OSMetaClassDeclareReservedUnused(IOHIDDevice, 10);

    // ...

В Вашем файле реализации класса введите соответствие OSMetaClassDefineReservedUnused макросы. Они макросы также берут имя класса и индекс слота клавиатуры как параметры. Перечисление 1-8 показывает им макросы, поскольку они появляются в IOHIDDevice.cpp файл

Перечисление 1-8  начальное дополнение класса виртуальная таблица (файл реализации)

// at end of function implementations

OSMetaClassDefineReservedUnused(IOHIDDevice,  0);

OSMetaClassDefineReservedUnused(IOHIDDevice,  1);

OSMetaClassDefineReservedUnused(IOHIDDevice,  2);

OSMetaClassDefineReservedUnused(IOHIDDevice,  3);

OSMetaClassDefineReservedUnused(IOHIDDevice,  4);

OSMetaClassDefineReservedUnused(IOHIDDevice,  5);

OSMetaClassDefineReservedUnused(IOHIDDevice,  6);

OSMetaClassDefineReservedUnused(IOHIDDevice,  7);

OSMetaClassDefineReservedUnused(IOHIDDevice,  8);

OSMetaClassDefineReservedUnused(IOHIDDevice,  9);

OSMetaClassDefineReservedUnused(IOHIDDevice, 10);

// ...

Когда Вы впоследствии добавляете виртуальную функцию к своему классу, заменяете OSMetaClassDeclareReservedUnused макрос, имеющий самый низкий индекс в Вашем заголовочном файле класса с OSMetaClassDeclareReservedUsed макрос; обязательно используйте тот же индекс. Для документирования замены имейте макрос, сразу предшествуют объявлению функции. Класс IOHIDDevice делает это как показано в Перечислении 1-9.

Перечисление 1-9  , Корректирующееся слоты клавиатуры при добавлении новых виртуальных функций — заголовочный файл

public:

// ...

    OSMetaClassDeclareReservedUsed(IOHIDDevice,  0);

    virtual IOReturn updateElementValues(IOHIDElementCookie * cookies,

                                        UInt32 cookieCount = 1);

protected:

    OSMetaClassDeclareReservedUsed(IOHIDDevice,  1);

    virtual IOReturn postElementValues(IOHIDElementCookie * cookies,

                                        UInt32 cookieCount = 1);

public:

    OSMetaClassDeclareReservedUsed(IOHIDDevice,  2);

    virtual OSString * newSerialNumberString() const;

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  3);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  4);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  5);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  6);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  7);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  8);

    OSMetaClassDeclareReservedUnused(IOHIDDevice,  9);

    OSMetaClassDeclareReservedUnused(IOHIDDevice, 10);

// ...

В файле реализации замените индексированный самым низким образом OSMetaClassDefineReservedUnused макрос с a OSMetaClassDefineReservedUsed макрос для каждой новой виртуальной функции. Снова, для пользы ясности, рассмотрите помещение макроса сразу перед реализацией функции. См. Перечисление 1-10 для примера.

Перечисление 1-10  , Корректирующееся слоты клавиатуры при добавлении новых виртуальных функций — файл реализации

OSMetaClassDefineReservedUsed(IOHIDDevice,  0);

IOReturn IOHIDDevice::updateElementValues(IOHIDElementCookie *cookies,

                                        UInt32 cookieCount) {

    // implementation code...

}

OSMetaClassDefineReservedUsed(IOHIDDevice,  1);

IOReturn IOHIDDevice::postElementValues(IOHIDElementCookie * cookies,

                                        UInt32 cookieCount) {

    // implementation code...

}

OSMetaClassDefineReservedUsed(IOHIDDevice,  2);

OSString * IOHIDDevice::newSerialNumberString() const

{    // implementation code ...

}

OSMetaClassDefineReservedUnused(IOHIDDevice,  3);

OSMetaClassDefineReservedUnused(IOHIDDevice,  4);

OSMetaClassDefineReservedUnused(IOHIDDevice,  5);

OSMetaClassDefineReservedUnused(IOHIDDevice,  6);

OSMetaClassDefineReservedUnused(IOHIDDevice,  7);

OSMetaClassDefineReservedUnused(IOHIDDevice,  8);

OSMetaClassDefineReservedUnused(IOHIDDevice,  9);

OSMetaClassDefineReservedUnused(IOHIDDevice, 10);

// ...