PIC24 tnkernel:ref:mpool

TNKernel : Блоки памяти фиксированного размера

2008-07-21T01:44:40+03:00

TNKernel : Блоки памяти фиксированного размера

Введение

Стандартные функции malloc/free как правило не являются безопасными с точки зрения многозадачности, поэтому необходимо либо отказаться от их применения, либо рассматривать кучу (heap) как разделяемый ресурс (использовать мютекс), либо реализовать менеджер памяти своими силами под конкретную задачу.

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

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

Структура управления пулом блоков памяти

Каждый пул ассоциируется со структурой управления:

typedef struct _TN_FMP_S
{
    CDLL_QUEUE_S        wait_queue;
 
    TN_UWORD            block_size;
    TN_UWORD            num_blocks;
    void              * start_addr;
    void              * free_list;
    TN_UWORD            fblkcnt;
    TN_OBJ_ID           id_fmp;
} TN_FMP_S;

В состав структуры пула входят следующие элементы:

`wait_queue`	Очередь задач, ожидающих освобождение блока
`block_size`	Размер блока памяти в байтах
`num_blocks`	Количество блоков в пуле
`start_addr`	Указатель на область памяти, выделенную для пула
`free_list`	Указатель на список свободных блоков
`fblkcnt`	Количество свободных блоков
`id_fmp`	Поле идентификации объекта как пула блоков памяти

Структура пула доступна только при определении TN_DEBUG. Тем не менее, прямой доступ к элементам структуры пула блоков памяти крайне не рекомендуется, так как это является вмешательством в работу планировщика и других сервисов RTOS.

Сервисы управления пулами блоков памяти

TNKernel имеет следующий набор функций (сервисов) для управления пулами:

Сервис	Описание	Свойства
Создание и удаление пула
tn_fmem_create()	Создание пула
tn_fmem_delete()	Удаление пула
Получение блока памяти
tn_fmem_get()	Получение блока памяти
tn_fmem_get_polling()	Получение блока памяти без блокировки задачи
tn_fmem_get_ipolling()	Получение блока памяти в прерывании
Освобождение блока памяти
tn_fmem_release()	Освобождение блока памяти
tn_fmem_irelease()	Освобождение блока памяти в прерывании

tn_fmem_create()

2008-07-21T00:56:17+03:00

tn_fmem_create()

Функция предназначена для создания пула блоков памяти фиксированного размера. Поле id_fmp структуры fmp должно быть равно нулю до момента создания пула. Таким образом уже созданные пулы защищаются от повторного создания.

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

Для лучшего использования памяти, желательно чтобы размер блока (block_size) был кратным машинному слову: для PIC24/dsPIC это 2, 4, 6 …. байт. Для удобного выделения памяти (автоматического выравнивания) можно использовать макрос MAKE_ALIG:

TN_FMP   my_pool;
TN_UWORD my_pool_mem[NUM_BLOCKS * (MAKE_ALIG(BLOCK_SIZE) / sizeof(TN_UWORD))];
 
tn_fmem_create (&my_pool, my_pool_mem, BLOCK_SIZE, NUM_BLOCKS);

Вызов:

TN_RETVAL tn_fmem_create (TN_FMP   *fmp,
                          void     *start_addr,
                          TN_UWORD  block_size,
                          TN_UWORD  num_blocks
                         );

Разрешен вызов:

В контексте задачи, в обработчике прерывания, в пользовательской критической секции

Параметры функции:

fmp: указатель на структуру пула типа TN_FMP. Структура должна быть создана до момента вызова функции, статически или динамически
start_addr: указатель на память, выделенную для пула. Размер выделенной памяти должен быть не меньше block_size * num_blocks байт
block_size: размер блока памяти в байтах
num_blocks: количество блоков памяти в пуле

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_EXS: попытка создания пула, который уже создан
TERR_NO_ERR: успешное выполнение

Пример вызова:

TN_FMP   my_pool;
TN_UWORD my_pool_mem[NUM_BLOCKS * (MAKE_ALIG(BLOCK_SIZE) / sizeof(TN_UWORD))];
 
tn_fmem_create (&my_pool, my_pool_mem, BLOCK_SIZE, NUM_BLOCKS);

К списку сервисов

¹⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров

tn_fmem_delete()

2008-07-21T00:56:54+03:00

tn_fmem_delete()

Функция предназначена для удаления пула блоков памяти фиксированного размера. Поле id_fmp структуры fmp после выполнения сервиса устанавливается в 0.

Все задачи, ожидающие освобождения блока выходят из сервиса запроса с кодом ошибки TERR_DLT.

Вызов:

TN_RETVAL tn_fmem_delete (TN_FMP *fmp);

Разрешен вызов:

В контексте задачи

Параметры функции:

fmp: указатель на структуру удаляемого пула

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_NOEXS: попытка удаления несуществующего пула
TERR_WCONTEXT: попытка вызова сервиса из обработчика прерывания или из пользовательской критической секции
TERR_NO_ERR: успешное выполнение

Пример вызова:

TN_FMP   my_pool;
 
tn_fmem_delete(&my_pool);

К списку сервисов

¹⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров

tn_fmem_get()

2008-07-21T01:00:24+03:00

tn_fmem_get()

Функция предназначена для получения блока памяти из пула. Указатель на получаемый блок передается в сервис в качестве параметра p_data. Содержимое блока памяти после получения его задачей не определено.

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

Параметр timeout задает время ожидания блока памяти в системных тиках. Если в течении этого времени блок не будет выделен для задачи, она удаляется из очереди ожидающих блок и переводится в состояние готовых к выполнению. Сервис возвращает значение TERR_TIMEOUT.

Вызов:

TN_RETVAL tn_fmem_get (TN_FMP *fmp, void **p_data, TN_TIMEOUT timeout);

Разрешен вызов:

В контексте задачи

Параметры функции:

fmp: указатель на пул из которого будет выделяться блок памяти
p_data: указатель на указатель, который после успешного выполнения сервиса будет содержать адрес выделенного блока
timeout: таймаут в системных тиках, в течении которого задача будет ожидать освобождения блока

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра ¹⁾
TERR_NOEXS: попытка получения блока из несуществующего пула
TERR_WCONTEXT: вызов сервиса из обработчика прерывания или пользовательской критической секции
TERR_TIMEOUT: выход из сервиса по таймауту
TERR_NO_ERR: успешное выполнение

Пример вызова:

#define BLOCK_SIZE    4
 
TN_FMP   my_pool;
TN_UWORD my_pool_mem[NUM_BLOCKS * (MAKE_ALIG(BLOCK_SIZE) / sizeof(TN_UWORD))];
 
TN_UWORD *block_pt;
 
tn_fmem_create (&my_pool, my_pool_mem, BLOCK_SIZE, NUM_BLOCKS);
tn_fmem_get (&my_pool, &block_pt, TN_WAIT_INFINITE);

К списку сервисов

¹⁾ данный код возврата возможен только в случае использования сервисов с проверкой параметров

tn_fmem_get_ipolling()

2008-06-20T12:26:02+03:00

tn_fmem_get_ipolling()

Функция предназначена для получения блока памяти из пула в прерывании. Указатель на получаемый блок передается в сервис в качестве параметра p_data. Содержимое блока памяти после получения его задачей не определено.

Если в пуле есть свободные блоки, то один из них выделяется для задачи, и сервис возвращает код TERR_NO_ERR. Если свободные блоки в пуле отсутствуют, сервис возвращает код ошибки TERR_TIMEOUT.

Вызов:

TN_RETVAL tn_fmem_get_ipolling (TN_FMP *fmp, void **p_data);

Разрешен вызов:

В прерывании

Параметры функции:

fmp: указатель на пул из которого будет выделяться блок памяти
p_data: указатель на указатель, который после успешного выполнения сервиса будет содержать адрес выделенного блока

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_NOEXS: попытка получения блока из несуществующего пула
TERR_WCONTEXT: вызов сервиса из контекста задачи или из пользовательской критической секции
TERR_TIMEOUT: в пуле отсутствуют свободные блоки памяти
TERR_NO_ERR: успешное выполнение

Пример вызова:

extern TN_FMP my_pool;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    TN_UWORD *block;
 
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
    if (tn_fmem_get_ipolling(&my_pool, &block) == TERR_NO_ERR)
    {
        /* ... */
    }
    /* ... */
}

К списку сервисов

tn_fmem_get_polling()

2008-06-20T12:22:11+03:00

tn_fmem_get_polling()

Функция предназначена для получения блока памяти из пула без блокировки задачи. Указатель на получаемый блок передается в сервис в качестве параметра p_data. Содержимое блока памяти после получения его задачей не определено.

Вызов:

TN_RETVAL tn_fmem_get_polling (TN_FMP *fmp, void **p_data);

Разрешен вызов:

В контексте задачи

Параметры функции:

fmp: указатель на пул из которого будет выделяться блок памяти
p_data: указатель на указатель, который после успешного выполнения сервиса будет содержать адрес выделенного блока

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_NOEXS: попытка получения блока из несуществующего пула
TERR_WCONTEXT: вызов сервиса из обработчика прерывания или пользовательской критической секции
TERR_TIMEOUT: в пуле отсутствуют свободные блоки памяти
TERR_NO_ERR: успешное выполнение

Пример вызова:

#define BLOCK_SIZE    4
 
TN_FMP   my_pool;
TN_UWORD my_pool_mem[NUM_BLOCKS * (MAKE_ALIG(BLOCK_SIZE) / sizeof(TN_UWORD))];
 
TN_UWORD *block_pt;
 
tn_fmem_create(&my_pool, my_pool_mem, BLOCK_SIZE, NUM_BLOCKS);
if (tn_fmem_get(&my_pool, &block_pt) == TERR_TIMEOUT)
{
    /* в пуле нет свободных блоков памяти */
}

К списку сервисов

tn_fmem_irelease()

2008-06-20T12:34:49+03:00

tn_fmem_irelease()

Функция предназначена для освобождения выделенного блока памяти в прерывании. Указатель на освобождаемый блок передается в сервис в качестве параметра p_data. Функция не проверяет принадлежность блока p_data к пулу fmp.

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

Вызов:

TN_RETVAL tn_fmem_irelease(TN_FMP *fmp, void  *p_data);

Разрешен вызов:

В прерывании

Параметры функции:

fmp: указатель на пул, блок которого освобождается задачей
p_data: указатель на блок, который будет освобождаться задачей

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_NOEXS: попытка освобождения блока несуществующего пула
TERR_WCONTEXT: вызов сервиса в контексте задачи или из пользовательской критической секции
TERR_NO_ERR: успешное выполнение

Пример вызова:

extern TN_FMP   my_pool;
 
tn_sys_interrupt (_T2Interrupt)        /* прерывание от таймера */
{
    TN_UWORD *block_pt;
 
    IFS0bits.T2IF = 0;                 /* сброс флага прерывания */
 
    if (tn_fmem_get_ipolling(&my_pool, &block) == TERR_NO_ERR)
    {
        /* ... */
        tn_fmem_irelease(&my_pool, block_pt);
    }
}

К списку сервисов

tn_fmem_release()

2008-06-20T12:31:13+03:00

tn_fmem_release()

Функция предназначена для освобождения выделенного блока памяти. Указатель на освобождаемый блок передается в сервис в качестве параметра p_data. Функция не проверяет принадлежность блока p_data к пулу fmp.

Вызов:

TN_RETVAL tn_fmem_release(TN_FMP *fmp, void  *p_data);

Разрешен вызов:

В контексте задачи

Параметры функции:

fmp: указатель на пул, блок которого освобождается задачей
p_data: указатель на блок, который будет освобождаться задачей

Возвращаемые значения:

TERR_WRONG_PARAM: некорректное значение параметра (замечание: данный код возврата возможен только в случае использования сервисов с проверкой параметров)
TERR_NOEXS: попытка освобождения блока несуществующего пула
TERR_WCONTEXT: вызов сервиса из обработчика прерывания или пользовательской критической секции
TERR_NO_ERR: успешное выполнение

Пример вызова:

#define BLOCK_SIZE    4
 
TN_FMP   my_pool;
TN_UWORD my_pool_mem[NUM_BLOCKS * (MAKE_ALIG(BLOCK_SIZE) / sizeof(TN_UWORD))];
 
TN_UWORD *block_pt;
 
tn_fmem_create (&my_pool, my_pool_mem, BLOCK_SIZE, NUM_BLOCKS);
tn_fmem_get (&my_pool, &block_pt, TN_WAIT_INFINITE);
 
/* ... */
 
tn_fmem_release(&my_pool, block_pt);

К списку сервисов