path: root/test/tx/module_manager/threadx_module_manager_live_object_deallocation_test.c

/***************************************************************************
 * Copyright (c) 2026 Eclipse ThreadX contributors
 * 
 * This program and the accompanying materials are made available under the
 * terms of the MIT License which is available at
 * https://opensource.org/licenses/MIT.
 * 
 * AI Disclosure: This file was largely AI-generated by Claude Code (Opus 5).
 * The AI-generated portions may be considered public domain (CC0-1.0)
 * and not subject to the project's licence. The human contributor has
 * reviewed and verified that the code is correct.
 * 
 * SPDX-License-Identifier: MIT and CC0-1.0
 **************************************************************************/


/**************************************************************************/
/**************************************************************************/
/**                                                                       */
/** ThreadX Test                                                          */
/**                                                                       */
/**   Module Manager live kernel object deallocation                      */
/**                                                                       */
/**************************************************************************/
/**************************************************************************/

/* A module allocates the memory for its kernel objects from the Module Manager's
   object pool, and can ask for that memory back by address. The manager gave that
   memory back whatever was in it, including a control block the kernel was still
   using: the object stays on the created list for its type, a thread stays on the
   ready or suspension list it was on and stays schedulable, and an active timer
   stays on the timer list. None of those consult a control block ID, so nothing
   about the freed memory stops the kernel reading a name pointer out of it,
   writing through the created links in it, restoring a context from the stack
   pointer in it, or calling the timeout function pointer in it -- while the byte
   pool is free to have handed those same bytes to the next allocation.

   The manager now refuses to release the memory of an object that is still
   created, and answers the question from the kernel's created lists rather than
   from the control block, because a control block is not evidence: an allocation
   that was never made into an object can carry the value of an ID, and objects of
   distinct types share a size.

   This test drives that refusal on the host. The object pool behind it is
   modelled -- a bump allocator that hands back the block it most recently
   released, so that the address of a freed object can be seen to come back -- but
   the two records the manager consults are built the way the system builds them:
   the module allocation list by running the real
   _txm_module_manager_object_allocate, and the kernel created lists the way the
   create and delete services maintain them.

   What the test asserts is that memory is given back when, and only when, no live
   kernel object is in it: refused for every one of the eight object types, and
   still released for storage that was never created, for storage carrying nothing
   but a plausible ID, and for an object that has been deleted -- which is the
   release the delete dispatchers perform, and the one this must not break.  */

#include <stdio.h>

#include "threadx_module_manager_host_test_port.h"

#include "tx_thread.h"
#include "tx_timer.h"
#include "tx_queue.h"
#include "tx_event_flags.h"
#include "tx_semaphore.h"
#include "tx_mutex.h"
#include "tx_block_pool.h"
#include "tx_byte_pool.h"
#include "txm_module.h"
#include "txm_module_manager_util.h"


/* Define the stand-in interrupt lock the port shim counts through.  */

unsigned int    test_interrupt_disable_depth;
unsigned int    test_interrupt_disable_max_depth;
unsigned int    test_interrupt_restore_underflows;


/* Define the modelled object pool.  */

#define TEST_POOL_BYTES             ((ULONG) 8192)
#define TEST_MODULE_MEMORY_BYTES    512U

static union
{
    ALIGN_TYPE  test_pool_alignment;
    UCHAR       test_pool_bytes[TEST_POOL_BYTES];
} test_pool_arena;

static ULONG    test_pool_offset;


/* Define the memory that stands for the calling module's own code and data.  */

static union
{
    ALIGN_TYPE  test_data_alignment;
    UCHAR       test_data_bytes[TEST_MODULE_MEMORY_BYTES];
} test_module_data;

static union
{
    ALIGN_TYPE  test_code_alignment;
    UCHAR       test_code_bytes[TEST_MODULE_MEMORY_BYTES];
} test_module_code;


/* Define an object that stands for one the application owns and shared with a
   module. It lives outside the pool, so the manager has no allocation record of
   it and the kernel created list is the only record of it there is.  */

static TX_QUEUE     test_host_queue;


/* Define the thread that stands for the module thread making the request. The
   manager takes the calling module from it.  */

static TX_THREAD    test_current_thread;


/* Define the block the modelled pool most recently released, so that a later
   allocation of the same size lands on the address a freed object had, and so
   that a case can see whether anything was released at all.  */

static UCHAR    *test_released_start;
static ULONG    test_released_bytes;
static ULONG    test_releases;


/* Define the manager state the code under test reaches for.  */

TX_BYTE_POOL    _txm_module_manager_object_pool;
UINT            _txm_module_manager_object_pool_created;
TX_MUTEX        _txm_module_manager_mutex;
TX_THREAD       *_tx_thread_current_ptr;


/* Define the kernel created lists the liveness check walks.  */

TX_BLOCK_POOL           *_tx_block_pool_created_ptr;
ULONG                   _tx_block_pool_created_count;
TX_BYTE_POOL            *_tx_byte_pool_created_ptr;
ULONG                   _tx_byte_pool_created_count;
TX_EVENT_FLAGS_GROUP    *_tx_event_flags_created_ptr;
ULONG                   _tx_event_flags_created_count;
TX_MUTEX                *_tx_mutex_created_ptr;
ULONG                   _tx_mutex_created_count;
TX_QUEUE                *_tx_queue_created_ptr;
ULONG                   _tx_queue_created_count;
TX_SEMAPHORE            *_tx_semaphore_created_ptr;
ULONG                   _tx_semaphore_created_count;
TX_THREAD               *_tx_thread_created_ptr;
ULONG                   _tx_thread_created_count;
TX_TIMER                *_tx_timer_created_ptr;
ULONG                   _tx_timer_created_count;


static UINT     test_failures;
static ULONG    test_checks;


/* Record the outcome of one expectation.  */
static VOID  test_expect(const char *description, ULONG actual, ULONG expected)
{
    test_checks++;

    if (actual != expected)
    {
        printf("FAIL: %s (expected %lu, got %lu)\n", description, (unsigned long) expected, (unsigned long) actual);
        test_failures++;
    }
}


/* Report every module object type the manager knows, and the name, control block
   size and control block ID of each, so that the cases below can be written once
   and run against all of them.  */

typedef struct TEST_OBJECT_KIND_STRUCT
{
    UINT        test_kind_type;
    const char  *test_kind_name;
    ULONG       test_kind_size;
    ULONG       test_kind_id;
} TEST_OBJECT_KIND;

static const TEST_OBJECT_KIND test_object_kinds[] =
{
    { TXM_BLOCK_POOL_OBJECT,  "block pool",  (ULONG) sizeof(TX_BLOCK_POOL),        TX_BLOCK_POOL_ID },
    { TXM_BYTE_POOL_OBJECT,   "byte pool",   (ULONG) sizeof(TX_BYTE_POOL),         TX_BYTE_POOL_ID },
    { TXM_EVENT_FLAGS_OBJECT, "event flags", (ULONG) sizeof(TX_EVENT_FLAGS_GROUP), TX_EVENT_FLAGS_ID },
    { TXM_MUTEX_OBJECT,       "mutex",       (ULONG) sizeof(TX_MUTEX),             TX_MUTEX_ID },
    { TXM_QUEUE_OBJECT,       "queue",       (ULONG) sizeof(TX_QUEUE),             TX_QUEUE_ID },
    { TXM_SEMAPHORE_OBJECT,   "semaphore",   (ULONG) sizeof(TX_SEMAPHORE),         TX_SEMAPHORE_ID },
    { TXM_THREAD_OBJECT,      "thread",      (ULONG) sizeof(TX_THREAD),            TX_THREAD_ID },
    { TXM_TIMER_OBJECT,       "timer",       (ULONG) sizeof(TX_TIMER),             TX_TIMER_ID }
};

#define TEST_OBJECT_KIND_COUNT  (sizeof(test_object_kinds) / sizeof(test_object_kinds[0]))


/* Round a request up the way _tx_byte_allocate does.  */
static ULONG  test_round_up(ULONG memory_size)
{
    return((((memory_size + ((ULONG) sizeof(ALIGN_TYPE))) - ((ULONG) 1)) / ((ULONG) sizeof(ALIGN_TYPE))) * ((ULONG) sizeof(ALIGN_TYPE)));
}


/* Stand in for the byte pool the manager allocates object memory from.

   The two size bounds are the real ones. The placement is a bump allocator with
   one refinement: a request that exactly fits the block most recently released is
   given that block back. A first-fit byte pool reuses freed memory, and the cases
   about an address that has been released need the address to actually come back.  */
UINT  _txe_byte_allocate(TX_BYTE_POOL *pool_ptr, VOID **memory_ptr, ULONG memory_size, ULONG wait_option)
{

ULONG   rounded_size;
UCHAR   *block_start;


    (VOID) wait_option;

    if ((pool_ptr != &_txm_module_manager_object_pool) || (memory_ptr == TX_NULL))
    {
        return(TX_POOL_ERROR);
    }

    if (memory_size == ((ULONG) 0))
    {
        return(TX_SIZE_ERROR);
    }

    if (memory_size > pool_ptr -> tx_byte_pool_size)
    {
        return(TX_SIZE_ERROR);
    }

    rounded_size =  test_round_up(memory_size);

    if ((test_released_start != TX_NULL) && (test_released_bytes == rounded_size))
    {
        block_start =           test_released_start;
        test_released_start =   TX_NULL;
        test_released_bytes =   ((ULONG) 0);
    }
    else
    {
        if ((test_pool_offset + rounded_size) > TEST_POOL_BYTES)
        {
            return(TX_NO_MEMORY);
        }

        block_start =       &test_pool_arena.test_pool_bytes[test_pool_offset];
        test_pool_offset =  test_pool_offset + rounded_size;
    }

    pool_ptr -> tx_byte_pool_available =  pool_ptr -> tx_byte_pool_available - rounded_size;

    *memory_ptr =  (VOID *) block_start;

    return(TX_SUCCESS);
}


/* Stand in for the release side, remembering the block so it can come back, and
   counting releases so that a case can see whether one happened.  */
UINT  _txe_byte_release(VOID *memory_ptr)
{

UCHAR   *block_start;


    block_start =  (UCHAR *) memory_ptr;

    if ((block_start < test_pool_arena.test_pool_bytes) ||
        (block_start >= &test_pool_arena.test_pool_bytes[TEST_POOL_BYTES]))
    {
        return(TX_PTR_ERROR);
    }

    test_releases++;

    /* The model does not track block lengths, and the only released block a case
       needs to come back is the one it just released, whose length it knows. The
       length is recorded by the caller through test_release_size.  */
    test_released_start =  block_start;

    return(TX_SUCCESS);
}


/* Tell the model how long the block just released was.  */
static VOID  test_release_size(ULONG object_size)
{
    test_released_bytes =  test_round_up(object_size + ((ULONG) sizeof(TXM_MODULE_ALLOCATED_OBJECT)));
}


/* Stand in for the protection mutex.  */
UINT  _txe_mutex_get(TX_MUTEX *mutex_ptr, ULONG wait_option)
{
    (VOID) mutex_ptr;
    (VOID) wait_option;

    return(TX_SUCCESS);
}


UINT  _txe_mutex_put(TX_MUTEX *mutex_ptr)
{
    (VOID) mutex_ptr;

    return(TX_SUCCESS);
}


/* Stand in for the module port's data range check.  */
UINT  _txm_module_manager_inside_data_check(TXM_MODULE_INSTANCE *module_instance, ALIGN_TYPE obj_ptr,
                                            ULONG obj_size, UINT write_request)
{

ULONG   data_start;
ULONG   data_end;


    (VOID) module_instance;
    (VOID) write_request;

    data_start =  (ULONG) (ALIGN_TYPE) test_module_data.test_data_bytes;
    data_end =    data_start + ((ULONG) TEST_MODULE_MEMORY_BYTES);

    /* The whole range has to lie inside the module's data, not just its first
       address, and the subtraction is done on the end rather than the start so that
       a size which would carry the range past the top of the address space cannot
       wrap into an accepting answer.  */
    if (((ULONG) obj_ptr >= data_start) && (obj_size <= (data_end - (ULONG) obj_ptr)))
    {
        return(TX_TRUE);
    }

    return(TX_FALSE);
}


/* Outside is not the negation of inside: a range that only partly reaches into the
   module's data is neither. It has to end before that data begins or begin after it
   ends, and a size that would carry the end past the top of the address space is
   refused rather than allowed to compare as though it had not.  */
UINT  _txm_module_manager_outside_data_check(TXM_MODULE_INSTANCE *module_instance, ALIGN_TYPE obj_ptr,
                                             ULONG obj_size)
{

ULONG   data_start;
ULONG   data_end;


    (VOID) module_instance;

    data_start =  (ULONG) (ALIGN_TYPE) test_module_data.test_data_bytes;
    data_end =    data_start + ((ULONG) TEST_MODULE_MEMORY_BYTES);

    if (obj_size > (~((ULONG) 0) - (ULONG) obj_ptr))
    {
        return(TX_FALSE);
    }

    if ((((ULONG) obj_ptr + obj_size) <= data_start) || ((ULONG) obj_ptr >= data_end))
    {
        return(TX_TRUE);
    }

    return(TX_FALSE);
}


/* Stand in for the port primitive a manager source under test refers to but that
   no case here exercises.  */
VOID  _txm_module_manager_alignment_adjust(TXM_MODULE_PREAMBLE *module_preamble, ULONG *code_size,
                                           ULONG *code_alignment, ULONG *data_size, ULONG *data_alignment)
{
    (VOID) module_preamble;
    (VOID) code_size;
    (VOID) code_alignment;
    (VOID) data_size;
    (VOID) data_alignment;
}


/* Do to an object what the kernel's create service does: write the control block
   ID, and link the object onto the created list for its type.

   The chain each list is built as ends in a self-link on its oldest member rather
   than closing back on the head, so that a walk bounded by the created count
   visits every member and a walk that ignored the count would not run off the
   end. What is being tested is the bound, not the model.  */
static VOID  test_object_create(VOID *object_ptr, UINT object_type)
{
    switch (object_type)
    {

    case TXM_BLOCK_POOL_OBJECT:
    {
        TX_BLOCK_POOL   *block_pool_ptr =  (TX_BLOCK_POOL *) object_ptr;

        block_pool_ptr -> tx_block_pool_id =            TX_BLOCK_POOL_ID;
        block_pool_ptr -> tx_block_pool_created_next =  (_tx_block_pool_created_ptr == TX_NULL) ? block_pool_ptr : _tx_block_pool_created_ptr;
        _tx_block_pool_created_ptr =                    block_pool_ptr;
        _tx_block_pool_created_count++;
        break;
    }

    case TXM_BYTE_POOL_OBJECT:
    {
        TX_BYTE_POOL    *byte_pool_ptr =  (TX_BYTE_POOL *) object_ptr;

        byte_pool_ptr -> tx_byte_pool_id =            TX_BYTE_POOL_ID;
        byte_pool_ptr -> tx_byte_pool_created_next =  (_tx_byte_pool_created_ptr == TX_NULL) ? byte_pool_ptr : _tx_byte_pool_created_ptr;
        _tx_byte_pool_created_ptr =                   byte_pool_ptr;
        _tx_byte_pool_created_count++;
        break;
    }

    case TXM_EVENT_FLAGS_OBJECT:
    {
        TX_EVENT_FLAGS_GROUP    *event_flags_ptr =  (TX_EVENT_FLAGS_GROUP *) object_ptr;

        event_flags_ptr -> tx_event_flags_group_id =            TX_EVENT_FLAGS_ID;
        event_flags_ptr -> tx_event_flags_group_created_next =  (_tx_event_flags_created_ptr == TX_NULL) ? event_flags_ptr : _tx_event_flags_created_ptr;
        _tx_event_flags_created_ptr =                           event_flags_ptr;
        _tx_event_flags_created_count++;
        break;
    }

    case TXM_MUTEX_OBJECT:
    {
        TX_MUTEX    *mutex_ptr =  (TX_MUTEX *) object_ptr;

        mutex_ptr -> tx_mutex_id =            TX_MUTEX_ID;
        mutex_ptr -> tx_mutex_created_next =  (_tx_mutex_created_ptr == TX_NULL) ? mutex_ptr : _tx_mutex_created_ptr;
        _tx_mutex_created_ptr =               mutex_ptr;
        _tx_mutex_created_count++;
        break;
    }

    case TXM_QUEUE_OBJECT:
    {
        TX_QUEUE    *queue_ptr =  (TX_QUEUE *) object_ptr;

        queue_ptr -> tx_queue_id =            TX_QUEUE_ID;
        queue_ptr -> tx_queue_created_next =  (_tx_queue_created_ptr == TX_NULL) ? queue_ptr : _tx_queue_created_ptr;
        _tx_queue_created_ptr =               queue_ptr;
        _tx_queue_created_count++;
        break;
    }

    case TXM_SEMAPHORE_OBJECT:
    {
        TX_SEMAPHORE    *semaphore_ptr =  (TX_SEMAPHORE *) object_ptr;

        semaphore_ptr -> tx_semaphore_id =            TX_SEMAPHORE_ID;
        semaphore_ptr -> tx_semaphore_created_next =  (_tx_semaphore_created_ptr == TX_NULL) ? semaphore_ptr : _tx_semaphore_created_ptr;
        _tx_semaphore_created_ptr =                   semaphore_ptr;
        _tx_semaphore_created_count++;
        break;
    }

    case TXM_THREAD_OBJECT:
    {
        TX_THREAD   *thread_ptr =  (TX_THREAD *) object_ptr;

        thread_ptr -> tx_thread_id =            TX_THREAD_ID;
        thread_ptr -> tx_thread_created_next =  (_tx_thread_created_ptr == TX_NULL) ? thread_ptr : _tx_thread_created_ptr;
        _tx_thread_created_ptr =                thread_ptr;
        _tx_thread_created_count++;
        break;
    }

    case TXM_TIMER_OBJECT:
    default:
    {
        TX_TIMER    *timer_ptr =  (TX_TIMER *) object_ptr;

        timer_ptr -> tx_timer_id =            TX_TIMER_ID;
        timer_ptr -> tx_timer_created_next =  (_tx_timer_created_ptr == TX_NULL) ? timer_ptr : _tx_timer_created_ptr;
        _tx_timer_created_ptr =               timer_ptr;
        _tx_timer_created_count++;
        break;
    }
    }
}


/* Do to an object what the kernel's delete service does: clear the control block
   ID, and take the object off the created list for its type.

   Every case that deletes has one object of that type on the list, which is the
   shape that matters here, so the model empties the list rather than unlinking a
   member of a longer one.  */
static VOID  test_object_delete(VOID *object_ptr, UINT object_type)
{
    switch (object_type)
    {

    case TXM_BLOCK_POOL_OBJECT:

        ((TX_BLOCK_POOL *) object_ptr) -> tx_block_pool_id =  TX_CLEAR_ID;
        _tx_block_pool_created_ptr =                          TX_NULL;
        _tx_block_pool_created_count =                        ((ULONG) 0);
        break;

    case TXM_BYTE_POOL_OBJECT:

        ((TX_BYTE_POOL *) object_ptr) -> tx_byte_pool_id =  TX_CLEAR_ID;
        _tx_byte_pool_created_ptr =                         TX_NULL;
        _tx_byte_pool_created_count =                       ((ULONG) 0);
        break;

    case TXM_EVENT_FLAGS_OBJECT:

        ((TX_EVENT_FLAGS_GROUP *) object_ptr) -> tx_event_flags_group_id =  TX_CLEAR_ID;
        _tx_event_flags_created_ptr =                                       TX_NULL;
        _tx_event_flags_created_count =                                     ((ULONG) 0);
        break;

    case TXM_MUTEX_OBJECT:

        ((TX_MUTEX *) object_ptr) -> tx_mutex_id =  TX_CLEAR_ID;
        _tx_mutex_created_ptr =                     TX_NULL;
        _tx_mutex_created_count =                   ((ULONG) 0);
        break;

    case TXM_QUEUE_OBJECT:

        ((TX_QUEUE *) object_ptr) -> tx_queue_id =  TX_CLEAR_ID;
        _tx_queue_created_ptr =                     TX_NULL;
        _tx_queue_created_count =                   ((ULONG) 0);
        break;

    case TXM_SEMAPHORE_OBJECT:

        ((TX_SEMAPHORE *) object_ptr) -> tx_semaphore_id =  TX_CLEAR_ID;
        _tx_semaphore_created_ptr =                         TX_NULL;
        _tx_semaphore_created_count =                       ((ULONG) 0);
        break;

    case TXM_THREAD_OBJECT:

        ((TX_THREAD *) object_ptr) -> tx_thread_id =  TX_CLEAR_ID;
        _tx_thread_created_ptr =                      TX_NULL;
        _tx_thread_created_count =                    ((ULONG) 0);
        break;

    case TXM_TIMER_OBJECT:
    default:

        ((TX_TIMER *) object_ptr) -> tx_timer_id =  TX_CLEAR_ID;
        _tx_timer_created_ptr =                     TX_NULL;
        _tx_timer_created_count =                   ((ULONG) 0);
        break;
    }
}


/* Break the created list for a type after its first member, and tell the kernel it
   is longer than it is. A search bounded only by the count would run off the end of
   the chain; this is what makes the second bound observable for every type.  */
static VOID  test_object_orphan(VOID *object_ptr, UINT object_type)
{
    switch (object_type)
    {

    case TXM_BLOCK_POOL_OBJECT:

        ((TX_BLOCK_POOL *) object_ptr) -> tx_block_pool_created_next =  TX_NULL;
        _tx_block_pool_created_count =                                  ((ULONG) 64);
        break;

    case TXM_BYTE_POOL_OBJECT:

        ((TX_BYTE_POOL *) object_ptr) -> tx_byte_pool_created_next =  TX_NULL;
        _tx_byte_pool_created_count =                                 ((ULONG) 64);
        break;

    case TXM_EVENT_FLAGS_OBJECT:

        ((TX_EVENT_FLAGS_GROUP *) object_ptr) -> tx_event_flags_group_created_next =  TX_NULL;
        _tx_event_flags_created_count =                                               ((ULONG) 64);
        break;

    case TXM_MUTEX_OBJECT:

        ((TX_MUTEX *) object_ptr) -> tx_mutex_created_next =  TX_NULL;
        _tx_mutex_created_count =                             ((ULONG) 64);
        break;

    case TXM_QUEUE_OBJECT:

        ((TX_QUEUE *) object_ptr) -> tx_queue_created_next =  TX_NULL;
        _tx_queue_created_count =                             ((ULONG) 64);
        break;

    case TXM_SEMAPHORE_OBJECT:

        ((TX_SEMAPHORE *) object_ptr) -> tx_semaphore_created_next =  TX_NULL;
        _tx_semaphore_created_count =                                 ((ULONG) 64);
        break;

    case TXM_THREAD_OBJECT:

        ((TX_THREAD *) object_ptr) -> tx_thread_created_next =  TX_NULL;
        _tx_thread_created_count =                              ((ULONG) 64);
        break;

    case TXM_TIMER_OBJECT:
    default:

        ((TX_TIMER *) object_ptr) -> tx_timer_created_next =  TX_NULL;
        _tx_timer_created_count =                             ((ULONG) 64);
        break;
    }
}


/* Read the control block ID word of an object.  */
static ULONG  test_object_id(VOID *object_ptr)
{
    return(*((ULONG *) object_ptr));
}


/* Plant a value at an offset into an allocation, and report what was there.  */
static ULONG  test_plant(VOID *object_ptr, ULONG offset, ULONG value)
{

ULONG   *word_ptr;
ULONG   previous;


    word_ptr =  (ULONG *) (VOID *) (((UCHAR *) object_ptr) + offset);
    previous =  *word_ptr;
    *word_ptr = value;

    return(previous);
}


/* Bring the pool, the created lists and the modules back to a known state.

   Everything is reset together deliberately. The allocation lists point into the
   pool and the created lists point at objects in it, so a case that left either
   behind would have the next case reading the wreckage of an earlier one rather
   than what it was written to check.  */
static VOID  test_reset(TXM_MODULE_INSTANCE *module_a, TXM_MODULE_INSTANCE *module_b)
{

UINT    index;


    for (index = 0U; index < (UINT) TEST_POOL_BYTES; index++)
    {
        test_pool_arena.test_pool_bytes[index] =  (UCHAR) 0;
    }

    for (index = 0U; index < TEST_MODULE_MEMORY_BYTES; index++)
    {
        test_module_data.test_data_bytes[index] =  (UCHAR) 0;
        test_module_code.test_code_bytes[index] =  (UCHAR) 0;
    }

    test_pool_offset =      ((ULONG) 0);
    test_released_start =   TX_NULL;
    test_released_bytes =   ((ULONG) 0);
    test_releases =         ((ULONG) 0);

    _txm_module_manager_object_pool.tx_byte_pool_id =         TX_BYTE_POOL_ID;
    _txm_module_manager_object_pool.tx_byte_pool_start =      test_pool_arena.test_pool_bytes;
    _txm_module_manager_object_pool.tx_byte_pool_size =       TEST_POOL_BYTES;
    _txm_module_manager_object_pool.tx_byte_pool_available =  TEST_POOL_BYTES;
    _txm_module_manager_object_pool_created =                 TX_TRUE;

    _tx_block_pool_created_ptr =    TX_NULL;
    _tx_block_pool_created_count =  ((ULONG) 0);
    _tx_byte_pool_created_ptr =     TX_NULL;
    _tx_byte_pool_created_count =   ((ULONG) 0);
    _tx_event_flags_created_ptr =   TX_NULL;
    _tx_event_flags_created_count = ((ULONG) 0);
    _tx_mutex_created_ptr =         TX_NULL;
    _tx_mutex_created_count =       ((ULONG) 0);
    _tx_queue_created_ptr =         TX_NULL;
    _tx_queue_created_count =       ((ULONG) 0);
    _tx_semaphore_created_ptr =     TX_NULL;
    _tx_semaphore_created_count =   ((ULONG) 0);
    _tx_thread_created_ptr =        TX_NULL;
    _tx_thread_created_count =      ((ULONG) 0);
    _tx_timer_created_ptr =         TX_NULL;
    _tx_timer_created_count =       ((ULONG) 0);

    module_a -> txm_module_instance_object_list_count =  ((ULONG) 0);
    module_a -> txm_module_instance_object_list_head =   TX_NULL;
    module_b -> txm_module_instance_object_list_count =  ((ULONG) 0);
    module_b -> txm_module_instance_object_list_head =   TX_NULL;

    /* The requesting thread belongs to module A throughout. It is not in the pool
       and not on a created list, so it is nothing the cases below can find.  */
    test_current_thread.tx_thread_module_instance_ptr =  module_a;
    _tx_thread_current_ptr =                             &test_current_thread;
}


/* Allocate object memory for a module through the real manager path.  */
static VOID  *test_allocate(TXM_MODULE_INSTANCE *module_instance, ULONG object_size)
{

VOID    *object_ptr;
UINT    status;


    object_ptr =  TX_NULL;
    status =      _txm_module_manager_object_allocate(&object_ptr, object_size, module_instance);

    if (status != TX_SUCCESS)
    {
        printf("FAIL: the modelled pool refused an allocation of %lu bytes (status %u)\n",
               (unsigned long) object_size, status);
        test_failures++;

        return(TX_NULL);
    }

    return(object_ptr);
}


/* Allocate and create one object of a type, the way a module does.  */
static VOID  *test_allocate_and_create(TXM_MODULE_INSTANCE *module_instance, const TEST_OBJECT_KIND *kind)
{

VOID    *object_ptr;


    object_ptr =  test_allocate(module_instance, kind -> test_kind_size);

    if (object_ptr != TX_NULL)
    {
        test_object_create(object_ptr, kind -> test_kind_type);
    }

    return(object_ptr);
}


/* Ask the manager to give an address back, and report what it said. Whatever it
   decided, it must have left the interrupt lock as it found it.  */
static ULONG  test_deallocate(VOID *object_ptr)
{

ULONG   status;


    test_interrupt_disable_depth =        0U;
    test_interrupt_disable_max_depth =    0U;
    test_interrupt_restore_underflows =   0U;

    status =  (ULONG) _txm_module_manager_object_deallocate(object_ptr);

    if ((test_interrupt_disable_depth != 0U) || (test_interrupt_restore_underflows != 0U))
    {
        printf("FAIL: deallocation left the interrupt lock unbalanced (depth %u, underflows %u)\n",
               test_interrupt_disable_depth, test_interrupt_restore_underflows);
        test_failures++;
    }

    return(status);
}


/* Ask the manager whether a live kernel object is at an address, with the same
   accounting.  */
static ULONG  test_live_check(VOID *object_ptr)
{

ULONG   status;


    test_interrupt_disable_depth =        0U;
    test_interrupt_disable_max_depth =    0U;
    test_interrupt_restore_underflows =   0U;

    status =  (ULONG) _txm_module_manager_live_object_check((ALIGN_TYPE) object_ptr);

    if ((test_interrupt_disable_depth != 0U) || (test_interrupt_restore_underflows != 0U))
    {
        printf("FAIL: the liveness check left the interrupt lock unbalanced (depth %u, underflows %u)\n",
               test_interrupt_disable_depth, test_interrupt_restore_underflows);
        test_failures++;
    }

    return(status);
}


int  main(void)
{

TXM_MODULE_INSTANCE     module_a;
TXM_MODULE_INSTANCE     module_b;
const TEST_OBJECT_KIND  *kind;
const TEST_OBJECT_KIND  *other_kind;
VOID                    *object;
VOID                    *other_object;
VOID                    *raw_object;
VOID                    *reused_object;
ULONG                   index;
ULONG                   other_index;
ULONG                   saved;
ULONG                   status;
char                    description[160];


    /* Report expectations before anything can crash, so that a case that brings
       the process down is still preceded by everything that passed.  */
    setvbuf(stdout, TX_NULL, _IONBF, 0);

    test_failures =  0U;
    test_checks =    ((ULONG) 0);

    /* Set up two memory-protected modules. Module A does the asking throughout;
       module B is there to own allocations A did not make.  */
    module_a.txm_module_instance_property_flags =  TXM_MODULE_MEMORY_PROTECTION;
    module_a.txm_module_instance_code_start =      (VOID *) test_module_code.test_code_bytes;
    module_a.txm_module_instance_code_end =        (VOID *) &test_module_code.test_code_bytes[TEST_MODULE_MEMORY_BYTES - 1U];
    module_a.txm_module_instance_data_start =      (VOID *) test_module_data.test_data_bytes;
    module_a.txm_module_instance_data_end =        (VOID *) &test_module_data.test_data_bytes[TEST_MODULE_MEMORY_BYTES - 1U];

    module_b =  module_a;

    /**********************************************************************/
    /* The reported call: giving back the memory of a live object.         */
    /**********************************************************************/

    for (index = ((ULONG) 0); index < (ULONG) TEST_OBJECT_KIND_COUNT; index++)
    {
        kind =  &test_object_kinds[index];

        test_reset(&module_a, &module_b);

        object =  test_allocate_and_create(&module_a, kind);

        (void) snprintf(description, sizeof(description),
                        "a live %s is on the created list before anything is asked", kind -> test_kind_name);
        test_expect(description, test_live_check(object), (ULONG) TX_TRUE);

        /* The scan has to have run with interrupts disabled, which is the
           protection the created lists are maintained under.  */
        test_expect("...found with interrupts disabled, one deep",
                    (ULONG) test_interrupt_disable_max_depth, ((ULONG) 1));

        status =  test_deallocate(object);

        (void) snprintf(description, sizeof(description),
                        "the memory of a live %s is not given back", kind -> test_kind_name);
        test_expect(description, status, (ULONG) TX_DELETE_ERROR);

        test_expect("...nothing was released to the pool", test_releases, ((ULONG) 0));

        test_expect("...the allocation is still on the module's list",
                    module_a.txm_module_instance_object_list_count, ((ULONG) 1));

        test_expect("...at the head of it",
                    (ULONG) (module_a.txm_module_instance_object_list_head == (((TXM_MODULE_ALLOCATED_OBJECT *) object) - 1)),
                    (ULONG) TX_TRUE);

        (void) snprintf(description, sizeof(description),
                        "...the %s still carries its control block ID", kind -> test_kind_name);
        test_expect(description, test_object_id(object), kind -> test_kind_id);

        (void) snprintf(description, sizeof(description),
                        "...and is still a live %s", kind -> test_kind_name);
        test_expect(description, test_live_check(object), (ULONG) TX_TRUE);

        /* Deleting it is what makes the memory releasable, and the release the
           delete dispatchers perform after a successful delete then goes through.  */
        test_object_delete(object, kind -> test_kind_type);

        (void) snprintf(description, sizeof(description),
                        "a deleted %s is no longer live", kind -> test_kind_name);
        test_expect(description, test_live_check(object), (ULONG) TX_FALSE);

        test_release_size(kind -> test_kind_size);
        status =  test_deallocate(object);

        test_expect("and its memory is given back", status, (ULONG) TX_SUCCESS);

        test_expect("...leaving the module's allocation list empty",
                    module_a.txm_module_instance_object_list_count, ((ULONG) 0));

        /* The address is free to come back now, which is what the kernel would
           have been sharing with the next owner had the live object been freed.  */
        reused_object =  test_allocate(&module_a, kind -> test_kind_size);

        test_expect("...and the address free to be handed out again",
                    (ULONG) (reused_object == object), (ULONG) TX_TRUE);
    }

    /**********************************************************************/
    /* Storage that is not an object is still released.                   */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    /* An allocation that was never made into an object. This is what a module has
       after a create that failed or was abandoned, and releasing it is the reason
       the request exists at all.  */
    raw_object =  test_allocate(&module_a, (ULONG) sizeof(TX_QUEUE));

    test_expect("an uncreated allocation holds no live object",
                test_live_check(raw_object), (ULONG) TX_FALSE);

    test_release_size((ULONG) sizeof(TX_QUEUE));
    test_expect("and its memory is given back",
                test_deallocate(raw_object), (ULONG) TX_SUCCESS);
    test_expect("...leaving the module's allocation list empty",
                module_a.txm_module_instance_object_list_count, ((ULONG) 0));

    /* An allocation carrying nothing but the value of a control block ID. A
       control block ID is not evidence that an object is there, and refusing on
       one would strand memory a module is entitled to have back.  */
    for (index = ((ULONG) 0); index < (ULONG) TEST_OBJECT_KIND_COUNT; index++)
    {
        kind =  &test_object_kinds[index];

        test_reset(&module_a, &module_b);

        raw_object =  test_allocate(&module_a, kind -> test_kind_size);
        (VOID) test_plant(raw_object, ((ULONG) 0), kind -> test_kind_id);

        (void) snprintf(description, sizeof(description),
                        "an uncreated allocation carrying a %s ID holds no live object", kind -> test_kind_name);
        test_expect(description, test_live_check(raw_object), (ULONG) TX_FALSE);

        test_release_size(kind -> test_kind_size);

        test_expect("...and its memory is given back",
                    test_deallocate(raw_object), (ULONG) TX_SUCCESS);
    }

    /**********************************************************************/
    /* The allocation size is not what decides it.                        */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    /* A module running without memory protection creates objects through no
       size-checked path, so an object can be at the start of an allocation far
       larger than its control block. Deciding which created lists to search from
       the size of the allocation would miss it.  */
    object =  test_allocate(&module_a, (ULONG) sizeof(TX_THREAD));
    test_object_create(object, TXM_QUEUE_OBJECT);

    test_expect("a queue at the start of a thread-sized allocation is live",
                test_live_check(object), (ULONG) TX_TRUE);
    test_expect("and the memory is not given back",
                test_deallocate(object), (ULONG) TX_DELETE_ERROR);
    test_expect("...with nothing released to the pool", test_releases, ((ULONG) 0));

    /**********************************************************************/
    /* Only the exact address of an object counts.                        */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    kind =    &test_object_kinds[6];
    object =  test_allocate_and_create(&module_a, kind);

    /* Every aligned interior offset of a live object, with that object's own ID
       planted at the offset. None of them is the address of an object.  */
    for (index = (ULONG) sizeof(ULONG); index < kind -> test_kind_size; index = index + ((ULONG) sizeof(ULONG)))
    {
        saved =  test_plant(object, index, kind -> test_kind_id);

        (void) snprintf(description, sizeof(description),
                        "an address %lu bytes into a live thread holds no live object", (unsigned long) index);
        test_expect(description, test_live_check((VOID *) (((UCHAR *) object) + index)), (ULONG) TX_FALSE);

        (VOID) test_plant(object, index, saved);
    }

    test_expect("the address one past a live thread holds no live object",
                test_live_check((VOID *) (((UCHAR *) object) + kind -> test_kind_size)), (ULONG) TX_FALSE);

    /**********************************************************************/
    /* Every type is searched, and each type only finds its own.          */
    /**********************************************************************/

    for (index = ((ULONG) 0); index < (ULONG) TEST_OBJECT_KIND_COUNT; index++)
    {
        kind =  &test_object_kinds[index];

        test_reset(&module_a, &module_b);

        /* One object of this type, and one allocation of every other type's size
           that was never created. Only the created one is found, whatever ID the
           others are carrying.  */
        object =  test_allocate_and_create(&module_a, kind);

        for (other_index = ((ULONG) 0); other_index < (ULONG) TEST_OBJECT_KIND_COUNT; other_index++)
        {
            if (other_index == index)
            {
                continue;
            }

            other_kind =    &test_object_kinds[other_index];
            other_object =  test_allocate(&module_a, other_kind -> test_kind_size);
            (VOID) test_plant(other_object, ((ULONG) 0), other_kind -> test_kind_id);

            (void) snprintf(description, sizeof(description),
                            "with a live %s created, an uncreated %s is not found",
                            kind -> test_kind_name, other_kind -> test_kind_name);
            test_expect(description, test_live_check(other_object), (ULONG) TX_FALSE);
        }

        (void) snprintf(description, sizeof(description),
                        "and the live %s is", kind -> test_kind_name);
        test_expect(description, test_live_check(object), (ULONG) TX_TRUE);
    }

    /**********************************************************************/
    /* Liveness is the kernel's record, not the pool's.                   */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    /* An object the application created lives outside the pool, and the manager
       has no allocation record of it. The kernel created list is the only record
       there is, and it is the record this consults.  */
    test_object_create(&test_host_queue, TXM_QUEUE_OBJECT);

    test_expect("an application-owned queue outside the pool is live",
                test_live_check(&test_host_queue), (ULONG) TX_TRUE);

    test_object_delete(&test_host_queue, TXM_QUEUE_OBJECT);

    test_expect("and is not once it has been deleted",
                test_live_check(&test_host_queue), (ULONG) TX_FALSE);

    /**********************************************************************/
    /* The bounds on the search.                                          */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    /* Three queues, and a created count that says one. A list whose links have
       been damaged must not make the scan run past the count the kernel keeps
       beside it.  */
    object =        test_allocate_and_create(&module_a, &test_object_kinds[4]);
    other_object =  test_allocate_and_create(&module_a, &test_object_kinds[4]);
    raw_object =    test_allocate_and_create(&module_a, &test_object_kinds[4]);

    test_expect("all three queues are on the list", _tx_queue_created_count, ((ULONG) 3));
    test_expect("the newest is found", test_live_check(raw_object), (ULONG) TX_TRUE);
    test_expect("the oldest is found too", test_live_check(object), (ULONG) TX_TRUE);

    _tx_queue_created_count =  ((ULONG) 1);

    test_expect("with the count saying one, the head is still found",
                test_live_check(raw_object), (ULONG) TX_TRUE);
    test_expect("...but the second member is not walked to",
                test_live_check(other_object), (ULONG) TX_FALSE);
    test_expect("...nor the third",
                test_live_check(object), (ULONG) TX_FALSE);

    /* A count larger than the list. The walk has to stop at the end of the chain
       as well as at the count.  */
    _tx_queue_created_count =                          ((ULONG) 64);
    ((TX_QUEUE *) raw_object) -> tx_queue_created_next =  TX_NULL;

    test_expect("a count larger than the list does not run the scan off the end",
                test_live_check(&test_host_queue), (ULONG) TX_FALSE);

    /* An empty list is the ordinary state of most types on most systems.  */
    _tx_queue_created_ptr =    TX_NULL;
    _tx_queue_created_count =  ((ULONG) 0);

    test_expect("nothing is live once every list is empty",
                test_live_check(raw_object), (ULONG) TX_FALSE);

    /* The same bound, for every type: a chain that ends before the count does.  */
    for (index = ((ULONG) 0); index < (ULONG) TEST_OBJECT_KIND_COUNT; index++)
    {
        kind =  &test_object_kinds[index];

        test_reset(&module_a, &module_b);

        object =  test_allocate_and_create(&module_a, kind);
        test_object_orphan(object, kind -> test_kind_type);

        (void) snprintf(description, sizeof(description),
                        "a %s list that ends before its count does not run the scan off the end",
                        kind -> test_kind_name);
        test_expect(description, test_live_check(&test_host_queue), (ULONG) TX_FALSE);

        (void) snprintf(description, sizeof(description),
                        "...and the %s at its head is still found", kind -> test_kind_name);
        test_expect(description, test_live_check(object), (ULONG) TX_TRUE);
    }

    /**********************************************************************/
    /* Allocations belonging to another module.                           */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    /* Module B's live object. Module A is refused, and the refusal is the
       ownership one: whether A may operate on B's objects at all is a separate
       question, and this request never reaches the liveness one.  */
    object =  test_allocate_and_create(&module_b, &test_object_kinds[5]);

    test_expect("module A cannot give back module B's live allocation",
                test_deallocate(object), (ULONG) TX_PTR_ERROR);
    test_expect("...and B's allocation list is untouched",
                module_b.txm_module_instance_object_list_count, ((ULONG) 1));
    test_expect("...with nothing released to the pool", test_releases, ((ULONG) 0));

    /* And B's uncreated storage, which A is refused for the same reason.  */
    raw_object =  test_allocate(&module_b, (ULONG) sizeof(TX_QUEUE));

    test_expect("module A cannot give back module B's uncreated allocation",
                test_deallocate(raw_object), (ULONG) TX_PTR_ERROR);
    test_expect("...and B's allocation list still holds both",
                module_b.txm_module_instance_object_list_count, ((ULONG) 2));

    /* B can give its own uncreated storage back, so the ownership test has not
       been turned into a refusal of everything.  */
    test_current_thread.tx_thread_module_instance_ptr =  &module_b;

    test_release_size((ULONG) sizeof(TX_QUEUE));
    test_expect("module B can give back its own uncreated allocation",
                test_deallocate(raw_object), (ULONG) TX_SUCCESS);
    test_expect("...but not its own live object",
                test_deallocate(object), (ULONG) TX_DELETE_ERROR);

    test_current_thread.tx_thread_module_instance_ptr =  &module_a;

    /**********************************************************************/
    /* An address that is not the start of one of this module's allocations.*/
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    object =  test_allocate(&module_a, (ULONG) sizeof(TX_QUEUE));

    /* An address inside an allocation names none of this module's allocations.
       The search establishes that without reading the words in front of the
       address, so an interior address is refused rather than taken for a header.  */
    test_expect("an address inside an allocation is refused as naming no allocation",
                test_deallocate((VOID *) (((UCHAR *) object) + sizeof(ULONG))), (ULONG) TX_PTR_ERROR);

    test_expect("...leaving the module's allocation list as it was",
                module_a.txm_module_instance_object_list_count, ((ULONG) 1));

    /**********************************************************************/
    /* Types the manager does not know.                                   */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    object =  test_allocate_and_create(&module_a, &test_object_kinds[4]);

    /* The per-type check is asked directly here, because the search over the
       types the manager knows can never present it with one it does not. A
       kernel stack allocation is the case that exists: the manager allocates it
       from the same pool and gives it a type of its own, and there is no created
       list for it.  */
    test_expect("a kernel stack is not a type with a created list",
                (ULONG) _txm_module_manager_created_object_type_check((ALIGN_TYPE) object,
                                                                      (UINT) TXM_THREAD_KERNEL_STACK_OBJECT),
                (ULONG) TX_FALSE);

    test_expect("nor is a type of zero",
                (ULONG) _txm_module_manager_created_object_type_check((ALIGN_TYPE) object, 0U),
                (ULONG) TX_FALSE);

    test_expect("and the live queue is still found by the search",
                test_live_check(object), (ULONG) TX_TRUE);

    /**********************************************************************/
    /* Releasing one allocation out of several.                           */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    /* Allocations are appended behind the head, so the first one made is the
       head. Releasing it has to move the head on rather than leave it pointing
       at memory that has gone back to the pool.  */
    object =        test_allocate(&module_a, (ULONG) sizeof(TX_QUEUE));
    other_object =  test_allocate(&module_a, (ULONG) sizeof(TX_QUEUE));

    test_expect("the first allocation is the list head",
                (ULONG) (module_a.txm_module_instance_object_list_head == (((TXM_MODULE_ALLOCATED_OBJECT *) object) - 1)),
                (ULONG) TX_TRUE);

    test_release_size((ULONG) sizeof(TX_QUEUE));
    test_expect("releasing the head allocation succeeds",
                test_deallocate(object), (ULONG) TX_SUCCESS);
    test_expect("...leaving one allocation on the list",
                module_a.txm_module_instance_object_list_count, ((ULONG) 1));
    test_expect("...and the head moved on to it",
                (ULONG) (module_a.txm_module_instance_object_list_head == (((TXM_MODULE_ALLOCATED_OBJECT *) other_object) - 1)),
                (ULONG) TX_TRUE);

    test_release_size((ULONG) sizeof(TX_QUEUE));
    test_expect("releasing the last allocation succeeds",
                test_deallocate(other_object), (ULONG) TX_SUCCESS);
    test_expect("...emptying the list",
                module_a.txm_module_instance_object_list_count, ((ULONG) 0));
    test_expect("...and clearing its head",
                (ULONG) (module_a.txm_module_instance_object_list_head == TX_NULL), (ULONG) TX_TRUE);

    /* Asking for the same address again. The header in front of it still names this
       module, because nothing has overwritten it, so the empty allocation list is
       what has to refuse the second release rather than the owner test.  */
    test_expect("releasing the same address a second time is refused",
                test_deallocate(other_object), (ULONG) TX_PTR_ERROR);

    /* An address with no room for a header in front of it anywhere in the address
       space. The header pointer is null, and the address itself is never read.  */
    test_expect("an address whose header would be at zero is refused",
                test_deallocate((VOID *) ((ALIGN_TYPE) sizeof(TXM_MODULE_ALLOCATED_OBJECT))),
                (ULONG) TX_PTR_ERROR);

    /**********************************************************************/
    /* An object pool that was never created.                             */
    /**********************************************************************/

    test_reset(&module_a, &module_b);

    _txm_module_manager_object_pool_created =  TX_FALSE;

    test_expect("and the deallocation reports the feature is not available",
                test_deallocate((VOID *) test_pool_arena.test_pool_bytes), (ULONG) TX_NOT_AVAILABLE);

    _txm_module_manager_object_pool_created =  TX_TRUE;

    /**********************************************************************/
    /* What the whole run has to have held.                               */
    /**********************************************************************/

    test_expect("every case ran", (ULONG) (test_checks > ((ULONG) 100)), (ULONG) TX_TRUE);

    if (test_failures == 0U)
    {
        printf("SUCCESS! %lu expectations\n", (unsigned long) test_checks);
        return(0);
    }

    printf("ERROR: %u expectation(s) failed of %lu\n", test_failures, (unsigned long) test_checks);
    return(1);
}