Создание оперативного дампа

Для создания оперативного дампа ядра используются службы ProbeVue и службы ProbeVue, аналогичные соответствующим службам ядра.

Исключением из этой общей похожести является структура ldmp_parms, которая не подвергается воздействию на уровне сценария. Вместо этого встроенная функция ldmp_setupparms имеет личный экземпляр этой структуры, которая выделяется и возвращается инициатору непосредственно как 64-битовый cookie, который должен быть передан последующим службам создания оперативного дампа на его место. Эту личную структуру одновременно может использовать только один сеанс. Можно использовать другие службы создания оперативного дампа взамен синтаксиса этих дубликатов ядра. Из-за этого скрытого выделения (а также скрытых выделений, делаемых самими службами создания оперативного дампа ядра) необходимо вызывать службу ядра либо ldmp_freeparms, либо livedump, если служба ядра ldmp_setupparms была вызвана и возвращена успешно. В противном случае текущий сеанс будет продолжать владеть личной структурой, приводя к неудачам всех будущих вызовов ldmp_setupparms. После освобождения этой личной структуры она больше не сможет быть использована ее предыдущим владельцем без другого вызова ldmp_setupparms. Не используйте флаг LDT_POST со службой ядра ldmp_setupparms, поскольку это подразумевает неподдерживаемую будущую ссылку на скрытую структуру.

Типичное приложение создания оперативного дампа должно владеть скрытой структурой только в течение очень короткого времени, обычно в течение одного блока probevue. Скрытой структурой владеет сеанс, и ее фактически может использовать любой блок Vue в этом сеансе. Среда автоматически освободит личную структуру и другие ресурсы ядра с помощью службы ядра ldmp_freeparms, когда сеанс ProbeVue будет завершен.

Поскольку элементы структуры ldmp_parms не видны ProbeVue, те из них, которые требуют или допускают инициализацию инициатором, настраиваются дополнительными параметрами, передаваемыми версии ProbeVue службы ядра ldmp_setupparms.

long long ldmp_setupparms(строка признаков, требуемая строка признаков
untyped	title,        строка заголовка дампа или NULL
untyped	prefix,  	    строка префикса имени файла дампа или NULL
untyped	func,         строка имени невыполненной функции или NULL
long long errcode,   код ошибки
int flags,           характеристики дампа
int prio )           приоритет дампа

Приведенная функция ldmp_setupparms Vue является интерфейсом службы ядра с тем же именем за исключением того, что структура ldmp_parms не видна вызывающему сценарию Vue. Возвращенное значение должно быть передано другим службам создания оперативного дампа как замена указателя на структуру ldmp_parms, несмотря на то, что оно имеет тип 64-битового целого числа.

Строка признаков является необходимым операндом String, тогда как строки title, prefix и func необязательны. Для этих трех параметров передайте String или NULL. Все значения String должны быть в сценарии Vue. Все параметры flags и prio могут быть нулевыми или значениями из файла заголовков ядра sys/livedump.h. Здесь должны использоваться целочисленные константы, хотя существует альтернатива.

Для параметра flags используются следующие значения:

	LDT_ONEPASS		0x02	ограниченный однопроходный дамп
	LDT_NOADDCOMPS	0x08	компоненты не могут добавляться обратными вызовами
	LDT_NOLOG			0x10	ошибки не должны регистрироваться
	LDT_FORCE			0x20	создать этот дамп

Поскольку дамп будет создаваться из запрещенной ProbeVue’ внутренней среды, это должен быть сериализованный, синхронный, однопроходный дамп.

Для параметра prio допустимы следующие значения:

	LDPP_INFO			1	информационный дамп
	LDPP_CRITICAL	7	критический дамп (по умолчанию)

Если для параметра prio задано значение нуль, LDPP_CRITICAL создается службой ядра ldmp_setupparms по умолчанию. В скрытой структуре ldmp_parms будет храниться только ненулевое значение для его переопределения.

Возвращенным значением в случае успеха будет положительный cookie, представляющий владельца скрытой структуры ldmp_parms.

В случае неудачи возвращенное значение будет отрицательным:

Значение Описание
EINVAL_EVM_ COOKIE Показывает, что личная структура ldmp_parms недоступна.
EINVAL_EVM_ STRING Показывает, что параметр со значением String недопустим.

Все описываемые далее функции Vue возвращают индикации неудачи аналогичным образом с отрицательны номером ошибки ядра:

Значение Описание
EINVAL_EVM_ COOKIE Показывает, что инициатор неправильно задал cookie, представляющий владельца личной структуры ldmp_parms.
EINVAL_EVM_ STRING Показывает, что параметр со значением String недопустим.
EINVAL_EVM_ EXTID Показывает, что параметр extid не поддерживается и должен быть нулевым.

Другие номера ошибок ядра могут возвращаться следующими службами ядра:

long long ldmp_freeparms (long long cookie)
После успешного возврата службы ядра ldmp_setupparms внутренняя структура ldmp_parms может быть выделена для выполнения сценария. Vue. Необходимо освободить этот ресурс, а также другие внутренние ресурсы ядра, выделенные службами, которые добавляют компоненты в дамп, созданием дампа вызовом службы ядра livedump или вызовом службы ядра ldmp_freeparms. При этом внутренняя структура ldmp_parms освобождается для будущего использования.
long long livedump (long long cookie)
После вызова службы ядра ldmp_setupparms и по крайней мере одной из различных служб, которые добавляют компоненты (и псевдокомпоненты) в дамп, создание дампа запрашивается службой livedump. Эта служба создает фактический оперативный дамп в файле /var/adm/ras/livedump согласно спецификациям, предоставленным через службу ядра ldmp_setupparms и другие вызванные службы создания оперативного дампа. Параметр cookie является cookie, возвращенным первоначальным обращением к службе ядра ldmp_setupparms. Возвращенным значением будет нуль, если дамп создан успешно, EINVAL_EVM_COOKIE, если cookie недопустим, и другим номером ошибки ядра, если при обработке livedump ядра произошла ошибка.
long long dmp_compspec(long long flags, DCF_xxx flags определенный в sys/dump.h untyped comp, добавляемый компонент (ras_block_t, name, alias и т. д.) long long cookie, cookie, возвращенный ldmp_setupparms long long extid, не поддерживаемым –, должен быть нулевым untyped p1, первый возможный параметр компонента ... ); дополнительные параметры компонента
Вызовом этой службы можно добавить любой компонент, поддерживающий оперативный дамп, в оперативный дамп; эта служба по функции идентична службе ядра с тем же именем за исключением следующих случаев:
  • Параметр extid, который разрешает возврат dmp_extid_t (long) в среду программирования ядра, не поддерживается и должен быть нулевым. В противном случае будет возвращен EINVAL_EVM_EXTID. Нет способа передачи указателя в память ProbeVue для получения этого значения, которое затем могло бы быть использовано со службой ядра dmp_compext и, поэтому, не поддерживается. Вместо этого можно вызывать службу dmp_compspec несколько раз.
  • Служба ядра допускает любое число параметров p1, p2 и т. д., в которых после последнего фактического параметра должен следовать дополнительный параметр NULL для завершения списка параметров. Только функция Vue принимает максимум четыре параметра p1, p2 и т. д. Последняя также должна быть еще и нулевой для сообщения службе ядра, сколько этих параметров, поэтому на самом деле можно задать только до 3 значимых значений. Для обеспечения выполнения этого правила интерфейс будет автоматически присваивать значение нуль последнему параметру после 3 параметров переменной.
  • Параметр comp может быть длинным (адрес ras_block_t ядра) или String, соответственно. Тип не проверяется.
  • Значения флага #define ядра не являются частью ProbeVue.
long long ras_block_lookup(String path)
Эта функция выполняет поиск ras_block_t, соответствующего параметру имени пути к компоненту. В отсутствие более простого поиска адреса в переменной ядра можно порекомендовать вызов службы ядра dmp_ct, которой требуется такой адрес.

Эта функция возвратит либо адрес ядра запрошенного ras_block_t, либо NULL, если ras_block_t не найден.

Следующие функции являются примерами "сквозных" функций, которые позволяют сценарию Vue непосредственно вызывать соответствующие службы ядра. Некоторые списки содержат неиспользуемые элементы для совместимости с ядром, поэтому можно непосредственно использовать документацию по ядру. Для неиспользуемых параметров должно передаваться значение 0. Эти службы можно использовать так же, как дубликаты их ядра, за исключением того, что адрес структуры ldmp_parms заменяется cookie, возвращаемым из службы ядра ldmp_setupparms.

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

long long dmp_context (флаги long long	flags,DCF_xxx из dump.h 
long long	cookie,	cookie, возвращаемый ldmp_setupparms 
long long	name,		не используется этой функцией 
long long ctx_type,	DMP_CTX_xxx флаги из dump.h untyped p2) 
параметр, зависящий от ctx_type (NULL, mst addr, cpuid, tid)
long long dmp_ct(	long long flags,	DCF_xxx флаги из dump.h
long long	cookie,	cookie, возвращаемый ldmp_setupparms
long long	name,		не используется этой функцией 
untyped	 rasb, 			component’s ras_block_t pointer
long long size) 		объем буфера CT для дампа или 0 для всех
long long dmp_eaddr( long long flags, DCF_xxx флаги из dump.h
long long	cookie,	cookie, возвращаемый ldmp_setupparms
String	name,      имя	cdt
untyped	 addr,      	первый адрес для дампа
long long size)     число байтов в дампе
long long dmp_errbuf(long long flags,	DCF_xxx флаги из dump.h
long long	cookie,	cookie, возвращаемый ldmp_setupparms
long long	name,		не используется этой функцией 
long long	erridx,	 	0 для протокола глобальных ошибок или ИД wpar
long long	p2)      	не используется
long long dmp_mtrc( long long flags, DCF_xxx флаги из dump.h
long long	cookie,	cookie, возвращаемый ldmp_setupparms
long long	name,		не используется этой функцией 
long long	com_size,	объем общих данных LMT для дампа
long long	rare_size)объем данных только LMT для дампа
long long dmp_pid(	long long flags,	DCF_xxx флаги из dump.h
long long	cookie,	cookie, возвращаемый ldmp_setupparms
long long	name,		не используется этой функцией 
long long	pid,			ИД процесса для дампа
long long	p2)      	не используется
long long dmp_systrace(long long flags,	DCF_xxx флаги из dump.h
long long	cookie,	cookie, возвращаемый ldmp_setupparms
long long	name,		не используется этой функцией 
long long	size,		объем для дампа
long long	p2)      	не используется
long long dmp_tid(	long long flags,	DCF_xxx флаги из dump.h
long long	cookie,	cookie, возвращаемый ldmp_setupparms
long long	name,		не используется этой функцией 
long long	tid,			ИД нити для дампа
long long	p2)      	не используется
Прим.: После любой ошибки в приведенных процедурах необходимо вызвать службу ядра ldmp_freeparms; предполагается, что затем дамп будет отменен.

Следующий пример сценария создает очень маленький простой оперативный дамп. Символ ядра c_data экспортирует структуру из ядра, фактические форма и содержимое которой не имеют значения в этом примере.

_kernel struct {int i1; int i2; int i3; int i4;} dc_data;

@@BEGIN
{
	long long ldmp_parms;
	long long rc;

	rc = ldmp_setupparms(	"дамп dc_data",
				"Мой пример дампа",		/* заголовок дампа */
				"pvdump",		/* префикс пути к дампу */
				NULL,			/* без имени функции */
				0x1122334455667788LL,	/* код ошибки */
				0x10,			/* флаг LDT_NOLOG */
				0);			/* prio дампа по умолчанию */
	printf("ldmp_setupparms rc = %016llx\n", rc);
	if (rc < 0) {
		exit();
	}

	ldmp_parms = rc;	/* cookie для других функций оперативного дампа */

	/*
	 * Добавление 16 байтов данных ядра в пример дампа.
	 * Отметим, что "dc_data" передает адрес структуры.
	 */
	rc = dmp_eaddr(0, ldmp_parms, "данные-dc", dc_data, sizeof(dc_data));
	if (rc) {
		printf("неудачный dump_eaddr: %llx\n", rc);
		ldmp_freeparms(ldmp_parms);
		exit();
	}

	/*
	 * Получение примера оперативного дампа.
	 */
	rc = livedump(ldmp_parms);
	if (rc) {
		printf("неудачный livedump: %llx\n", rc);
	}

	exit();
}

Использование символов #define для флагов оперативного дампа

Следующий пример сценария оболочки (probe.dump) можно использовать, если желательно использовать фактические определенные символы для флагов оперативного дампа, а не вручную подставлять их из файлов заголовков. В этом примере соответствующие определения берутся из файлов livedump.h и dump.h и для подстановки значений перед передачей сценария ProbeVue используется препроцессор C. Этот сценарий должен удовлетворять следующим правилам:

  • Не должен начинаться с комментария #!/usr/bin/probevue.
  • Не должен использовать символы, начинающиеся с LDPP_, LDT_, DCF_ или DMP_, конфликтующие с определениями в файлах заголовков.

Не должен создавать файлы с именем pvdump.*, поскольку следующий сценарий переопределит их.

#!/bin/ksh
#
# Сценарий-помощник для сценариев Vue, который должен получать
# значения различных флагов, используемых оперативным дампом.
#
# Сценарий Vue $1 
# не должен содержать комментарий "#!/usr/bin/probevue", поскольку
# препроцессор C не любит его.

sed -n						\
	-e '/(/d'				\
	-e '/^#define LDPP_/p'			\
	-e '/^#define LDT_/p'			\
	-e '/^#define DCF_/p'			\
	-e '/^#define DMP_CTX_/p'		\
      /usr/include/sys/dump.h			\
      /usr/include/sys/livedump.h		\
    > pvdump.h

echo “#include \”pvdump.h\”” > pvdump.c
cat $1 >> pvdump.c
cc -P pvdump.c
/usr/bin/probevue –K pvdump.i
rm pvdump.[cih]