Инфраструктура библиотек ускоренных вычислений для Cell Broadband Engine : Часть 4. Справочник по функциям

Страница 3 из 7  Опции документа Обсудить Выскажите мнение об этом учебном пособии Помогите нам улучшить содержание

Глава 21. API основного процессора

API основного процессора включает следующее:

• «Базовые API среды ALF», стр. 62
• «API вычислительного задания», стр. 70
• «API для операций с рабочими блоками», стр. 86
• «API для операций с наборам данных», стр. 93

Базовые API среды ALF

Нижеприведенные определения API относятся к базовым функциям вычислительной среды.

alf_handle_t

ИМЯ

alf_handle_t — Эта структура данных используется в качестве ссылки на один экземпляр среды исполнения ALF.

ОПИСАНИЕ

Эта структура данных используется в качестве ссылки на один экземпляр среды исполнения ALF. Структура данных инициализируется посредством вызова функции alf_init и аннулируется с помощью функции alf_exit.

alf_init

ИМЯ

alf_init — Инициализирует среду исполнения ALF.

СИНОПСИС

int alf_init(void* p_sys_config_info, alf_handle_t* p_alf_handle);

Параметры

typedef struct {
char* library_path;
} alf_sys_config_t_CBEA_t;

ОПИСАНИЕ

Эта функция инициализирует среду исполнения ALF. Она выделяет для последней необходимые ресурсы и глобальные данные, а также производит все необходимые платформно-зависимые настройки.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

ДОПОЛНИТЕЛЬНЫЕ ПАРАМЕТРЫ

alf_query_system_info

ИМЯ

alf_query_system_info — Запрос базовой конфигурационной информации.

СИНОПСИС

int alf_query_system_info(alf_handle_t alf_handle, ALF_QUERY_SYS_INFO_T query_info, 
			ALF_ACCEL_TYPE_T accel_type, unsigned int * p_query_result);

Параметры

ОПИСАНИЕ

Функция запрашивает базовую конфигурационную информацию той системы, на которой функционирует ALF.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_num_instances_set

ИМЯ

alf_num_instances_set — Устанавливает максимальное число параллельных экземпляров задания, которые ALF может обрабатывать одновременно.

СИНОПСИС

int alf_num_instances_set(alf_handle_t alf_handle, unsigned int number_of_instances);

Параметры

ОПИСАНИЕ

Функция устанавливает максимальное число параллельных экземпляров задания, которые ALF может обрабатывать одновременно. Если параметр number_of_instances равен нулю, это означает отсутствие ограничений со стороны приложения. В этом случае ALF вернет ошибку, если не сможет обработать запрос на создание задания с большим числом экземпляров.

Примечание. В SDK 3.0 эта функция вызывается один раз в начале, после alf_init и до первого обращения к alf_task_create. Вторичный вызов этой функции (чтобы изменить число экземпляров задания) не допускается, при попытке такого вызова возникает ошибка ALF_ERR_PERM.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_exit

ИМЯ

alf_exit — Завершает работу среды ALF.

СИНОПСИС

int alf_exit(alf_handle_t alf_handle, ALF_EXIT_POLICY_T policy, int timeout);

Параметры

ОПИСАНИЕ

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_error_handler_register

ИМЯ

alf_error_handler_register — Регистрирует глобальную функцию обработки ошибок для исполняемого кода среды ALF.

СИНОПСИС

int alf_error_handler_register(alf_handle_t alf_handle,
			alf_error_handler_t error_handler_function, void *p_context)

Параметры

ОПИСАНИЕ

Функция регистрирует глобальную функцию обработки ошибок для исполняемого кода ALF. Если такая функция уже была зарегистрирована, она будет замещена новой функцией.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

ALF_ERR_POLICY_T

ИМЯ

ALF_ERR_POLICY_T — Прототип функции обратного вызова, которую можно зарегистрировать в среде исполнения ALF для пользовательской обработки ошибок.

СИНОПСИС

ALF_ERR_POLICY_T(*alf_error_handler_t)(void *p_context_data, 
			int error_type, int error_code, char *error_string)

Параметры

ОПИСАНИЕ

Прототип функции обратного вызова, который можно зарегистрировать в среде ALF для реализации собственного алгоритма обработки ошибок.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

API вычислительного задания

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

alf_task_handle_t

ИМЯ

alf_task_handle_t — Структура данных — ссылка на конкретное вычислительное задание, выполняющееся на акселераторах.

ОПИСАНИЕ

Структура данных создается посредством вызова функции alf_task_create и уничтожается при вызове функций alf_task_destroy function или alf_exit. Для завершения обработки всех помещенных в очередь рабочих блоков следует пользоваться функцией alf_task_wait. С помощью функции alf_task_finalize можно также сообщить среде ALF о том, что в очередь соответствующего задания больше не будет добавляться новых рабочих блоков.

alf_task_desc_handle_t

ИМЯ

alf_task_desc_handle_t — Эта структура данных является ссылкой на дескриптор задания.

ОПИСАНИЕ

Эта структура данных используется для доступа и изменения информации дескриптора задания. Она создается посредством вызова alf_task_desc_create и уничтожается с помощью alf_task_desc_destroy.

alf_task_desc_create

ИМЯ

alf_task_desc_create — Создает дескриптор задания.

СИНОПСИС

int alf_task_desc_create (alf_handle_t alf_handle, ALF_ACCEL_TYPE_T 
accel_type, alf_task_desc_handle_t * p_desc_info_handle);

Параметры

ОПИСАНИЕ

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_desc_destroy

ИМЯ

alf_task_desc_destroy — Уничтожает указанный дескриптор задания и высвобождает связанные с ним ресурсы.

СИНОПСИС

int alf_task_desc_destroy (alf_task_desc_handle_t task_desc_handle);

Параметры

ОПИСАНИЕ

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_desc_ctx_entry_add

ИМЯ

alf_task_desc_ctx_entry_add — Добавляет описание элемента в контекст задания, ассоциированный с дескриптором этого задания.

СИНОПСИС

int alf_task_desc_ctx_entry_add (alf_task_desc_handle_t 
			task_desc_handle, ALF_DATA_TYPE_T data_type, unsigned int size);

Параметры

ОПИСАНИЕ

Функция добавляет описание элемента в контекст задания, ассоциированный с дескриптором этого задания.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_desc_set_int32

ИМЯ

alf_task_desc_set_int32 — Присваивает значение указанному 32-разрядному целочисленному полю дескриптора задания.

СИНОПСИС

int alf_task_desc_set_int32 (alf_task_desc_handle_t task_desc_handle, 
			ALF_TASK_DESC_FIELD_T field, unsigned int value);

Параметры

ОПИСАНИЕ

Эта функция присваивает значение указанному 32-разрядному целочисленному полю дескриптора задания. По умолчанию все поля имеют значение 0.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_desc_set_int64

ИМЯ

alf_task_desc_set_int64 — Присваивает значение указанному 64-разрядному целочисленному полю дескриптора задания.

СИНОПСИС

int alf_task_desc_set_int64(alf_task_desc_handle_t task_desc_handle, 
			ALF_TASK_DESC_FIELD_T field, unsigned long long value);

Параметры

ОПИСАНИЕ

Функция присваивает значение указанному 64-разрядному целочисленному полю дескриптора задания. Длина всех строковых констант не должна превышать значения ALF_STRING_TOKEN_MAX.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_create

ИМЯ

alf_task_create — Создает задание и позволяет приступить к добавлению в очередь рабочих блоков.

СИНОПСИС

int alf_task_create(alf_task_desc_handle_t task_desc_handle, void* p_task_context_data,
			unsigned int num_instances, unsigned int tsk_attr, 
			unsigned int wb_dist_size, alf_task_handle_t *p_task_handle);

Параметры

ОПИСАНИЕ

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

Когда условия выполнены, задание готово к исполнению. Фактический момент запуска задания зависит от доступности акселераторов и плана запуска среды ALF. Если ресурсов акселераторов достаточно, несколько независимых заданий могут выполняться одновременно. После запуска задание выполняется до тех пор, пока не будет выполнено одно из следующих условий:

• была выдана команда завершения задания alf_task_finalize, все помещенные в очередь рабочие блоки обработаны, выполнено слияние и обратная запись контекста задания;
• была выдана команда отмены задания alf_task_destroy.

Примечание. Задание, получившее команду завершения, но не обрабатывавшее ни одного рабочего блока, не загружается в память акселератора. Среда ALF считает такое задание законченным, как только разрешены все зависимости.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_finalize

ИМЯ

alf_task_finalize — Завершает очередь рабочих блоков указанного задания.

СИНОПСИС

int alf_task_finalize (alf_task_handle_t task_handle)

Параметры

ОПИСАНИЕ

Эта функция завершает задание. После того как задание завершено, последующие вызовы функций alf_wb_create, alf_task_depends_on и alf_task_event_handler_register приводят к ошибке.

Примечание. Выдача команды на завершение задания является обязательным условием для его нормального выполнения.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_wait

ИМЯ

alf_task_wait — Ожидает, пока указанное задание не завершит обработку всех рабочих блоков на запланированных акселераторах.

СИНОПСИС

int alf_task_wait(alf_task_handle_t task_handle, int time_out);

Параметры

ОПИСАНИЕ

Функция ожидает, пока указанное задание не закончит обработку всех рабочих блоков на всех запланированных акселераторах. Перед обращением к функции задание должно быть завершено посредством вызова alf_task_finalize. В противном случае возникает ошибка ALF_ERR_PERM. Данные, на которые ссылались рабочие блоки указанного задания, можно использовать только по завершении работы этой функции. Если приложение на основном процессоре обновляет буферы данных, на которые ссылаются рабочие блоки, или буфер контекста задания в ходе его выполнения, результат может быть непредсказуемым. Если необходимо обновить содержимое буфера, это следует сделать до обработки события ALF_TASK_EVENT_READY обработчиком, зарегистрированным посредством функции alf_task_event_handler_register.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_query

ИМЯ

alf_task_query — запрашивает текущее состояние задания.

СИНОПСИС

int alf_task_query( alf_task_handle_t task_handle, unsigned int *p_unfinished_wbs, 
			unsigned int *p_total_wbs);

Параметры

ОПИСАНИЕ

Функция запрашивает текущее состояние задания.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_destroy

ИМЯ

alf_task_destroy — отменяет задание.

СИНОПСИС

int alf_task_destroy(alf_task_handle_t* p_task_handle)

Параметры

ОПИСАНИЕ

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

Эту функцию следует использовать только для отмены задания в случае такой нужды.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_depends_on

ИМЯ

alf_task_depends_on — описывает взаимоотношение двух заданий.

СИНОПСИС

int alf_task_depends_on (alf_task_handle_t task_handle_dependent, 
			alf_task_handle_t task_handle);

Параметры

ОПИСАНИЕ

Эта функция описывает взаимоотношение двух заданий. Задание, обозначенное как task_handle_dependent, не может быть принято к исполнению до тех пор, пока задание, обозначенное как task_handle, не завершится нормально. Поэтому нельзя вызывать данную функцию, если задание task_handle было отменено, в этом случае будет возвращена ошибка. Если задание, обозначенное как task_handle, было отменено, задание task_handle_dependent также будет отменено, поскольку его зависимость уже нельзя разрешить.

Если задание A зависит от задания B, вызов alf_task_wait (A_handle) будет ожидать также и завершения выполнения задания B. Двойная зависимость обрабатывается без выдачи каких-либо сообщений и не рассматривается как ошибка.

Дополнительная информация о зависимости заданий и ограничений относительно установки зависимостей приведена в разделе «Зависимости и планирование заданий» на стр. 13.

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

В случае недопустимой ситуации функция возвращает ошибку ALF_ERR_PERM.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_event_handler_register

ИМЯ

alf_task_event_handler_register — позволяет регистрировать и отменять регистрацию обработчика событий для указанного задания.

СИНОПСИС

int alf_task_event_handler_register (alf_task_handle_t task_handle, 
			int (*task_event_handler)( alf_task_handle_t task_handle, 
			ALF_TASK_EVENT_TYPE_T event, void* p_data), void* p_data,
			unsigned int data_size, unsigned int event_mask);

Параметры

ОПИСАНИЕ

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

Если параметр task_event_handler имеет значение NULL, функция удаляет имеющийся обработчик событий. Если обработчик не был зарегистрирован, функция не совершает никаких действий.

Примечание. Если обработчик событий зарегистрирован после того, как задание начало выполняться, некоторые из событий могут быть пропущены.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

API рабочих блоков

Следующие функции относятся к операциям с рабочими блоками.

Структуры данных

alf_wb_handle_t

ИМЯ

alf_wb_handle_t — Эта структура данных ссылается на рабочий блок, создаваемый управляющим узлом.

alf_wb_create

ИМЯ

alf_wb_create — Создает новый рабочий блок для указанного вычислительного задания.

СИНОПСИС

int alf_wb_create(alf_task_handle_t task_handle, ALF_WORK_BLOCK_TYPE_T
work_block_type, unsigned int repeat_count, alf_wb_handle_t *p_wb_handle);

Параметры

ОПИСАНИЕ

Эта функция создает новый рабочий блок для указанного вычислительного задания. Рабочий блок добавляется в рабочую очередь задания, и после его обработки среда исполнения высвобождает выделенные ресурсы. Вызывающая программа может обновить содержимое рабочего блока лишь перед его добавлением в рабочую очередь. После того как блок добавлен в очередь, время его существования определяется средой ALF. За высвобождение всех ресурсов, выделенных для блока, также отвечает ALF. Данная функция может быть вызвана лишь до вызова alf_task_finalize.

После того как была вызвана функция alf_task_finalize, обращения к данной функции будут приводить к ошибке.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_wb_enqueue

ИМЯ

alf_wb_enqueue — Добавляет рабочий блок в очередь соответствующего задания.

СИНОПСИС

int alf_wb_enqueue(alf_wb_handle_t wb_handle)

Параметры

ОПИСАНИЕ

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_wb_parm_add

ИМЯ

alf_wb_parm_add — Добавляет указанный параметр к буферу параметров и контекста рабочего блока в порядке вызова функции.

СИНОПСИС

int alf_wb_parm_add(alf_wb_handle_t wb_handle, void *pdata, 
			unsigned int size_of_data, ALF_DATA_TYPE_T data_type, 
			unsigned int address_alignment)

Параметры

ОПИСАНИЕ

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_wb_dtl_begin

ИМЯ

alf_wb_dtl_begin — Помечает начало списка пересылки данных для указанного целевого буфера buffer_type.

СИНОПСИС

int alf_wb_dtl_begin (alf_wb_handle_t wb_handle, ALF_BUF_TYPE_T
buffer_type, unsigned int offset_to_accel_buf);

Параметры

ОПИСАНИЕ

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_wb_dtl_entry_add

ИМЯ

alf_wb_dtl_entry_add — Добавляет элемент к входному или выходному списку пересылки данных рабочего блока однократного использования.

СИНОПСИС

int alf_wb_dtl_entry_add (alf_wb_handle_t wb_handle, 
			void* host_addr, unsigned int size, ALF_DATA_TYPE_T data_type);

Параметры

ОПИСАНИЕ

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

Если задание, соответствующее рабочему блоку, связано с набором данных, то набор данных должен содержать указанный буфер с параметрами host_addr и size. Попытка добавления в список пересылки данных элемента, описывающего буфер, находящийся вне связанного набора данных, приводит к ошибке ALF_ERR_PERM.

Эта функция может быть вызвана только в случае, если дескриптор задания, к которому относится данный рабочий блок, был создан с атрибутом ALF_TASK_DESC_PARTITION_ON_ACCEL в значении «ложь».

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_wb_dtl_end

ИМЯ

alf_wb_dtl_end — Данная функция помечает конец списка пересылки данных.

СИНОПСИС

int alf_wb_dtl_end (alf_wb_handle_t wb_handle);

Параметры

ОПИСАНИЕ

Данная функция помечает конец списка пересылки данных.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

API управления наборами данных

Следующие определения API относятся к функциям управления наборами данных.

alf_dataset_handle_t

ИМЯ

alf_dataset_handle_t — Эта структура данных является ссылкой на набор данных.

alf_dataset_create

ИМЯ

alf_dataset_create — Создает набор данных.

СИНОПСИС

int alf_dataset_create(alf_handle_t alf_handle, alf_dataset_handle_t *
p_dataset_handle);

Параметры

ОПИСАНИЕ

Эта функция создает набор данных.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_dataset_buffer_add

ИМЯ

alf_dataset_buffer_add — Добавляет буфер к набору данных.

СИНОПСИС

int alf_dataset_buffer_add(alf_dataset_handle_t dataset, 
			void *buffer, unsigned long long size, 
			ALF_CACHE_DATASET_ACCESS_MODE_T access_mode);

Параметры

ОПИСАНИЕ

Данная функция добавляет буфер к набору данных.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_dataset_destroy

ИМЯ

alf_dataset_destroy — Уничтожает указанный набор данных.

СИНОПСИС

int alf_dataset_destroy(alf_dataset_handle_t dataset_handle);

Параметры

ОПИСАНИЕ

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

alf_task_dataset_associate

ИМЯ

alf_task_dataset_associate — Связывает указанное задание с набором данных.

СИНОПСИС

int alf_task_dataset_associate(alf_task_handle_t task, alf_dataset_handle_t dataset);

Параметры

ОПИСАНИЕ

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

После того как задание связано с набором данных, вызов функции alf_data_buffer_add приводит к ошибке.

После того как задание связано с набором данных, прикладная программа на основном процессоре может использовать данные лишь после вызова и отработки функции alf_task_wait.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

В начало

	Страница 3 из 7