Chapter 4 - Module APIs

This service makes the specified request to the resident portion of the application. It is assumed that the request structure is prepared prior to the call. The actual processing of the request takes place in the resident code in the function _txm_module_manager_application_request. By default, this function is left empty and is designed for the resident application developer to modify.

Module threads

This service allocates memory for a module object from memory outside of the module, which helps prevent corruption of the object control block by the module’s code. In memory protected systems, all object control blocks must be allocated with this API before they can be created.

The module manager allocates more than object_size bytes: it keeps a header of its own in front of the memory the module receives, recording the owning module, the size and the links that let the allocation be reclaimed when the module is unloaded. object_size is therefore bounded above by what the object pool holds, less that header, and a size too large to add the header to at all is refused with TXM_MODULE_MATH_OVERFLOW. Pass sizeof the control block being allocated, as in the example below.

Module threads

When a module calls a standard kernel delete service such as tx_timer_delete, tx_semaphore_delete, tx_queue_delete, or any other tx*delete service, the Module Manager dispatch layer automatically releases the associated object pool memory after the kernel cleanup completes. No separate deallocation call is required.

Deallocation is not deletion. Calling txm_module_object_deallocate on a live kernel object — one whose tx*delete service has not yet been called — asks the Module Manager to release memory the kernel is still using as a control block: the object remains on the created list for its type, a thread remains schedulable, and an active timer remains on the timer list, none of which look at whether the memory has been given back. The Module Manager therefore refuses such a request and returns TX_DELETE_ERROR, leaving the object, the allocation and the memory exactly as they were. Delete the object first.

Memory that holds no live object is still released, so a module can still give back storage it allocated for an object it never created, or for one it has since deleted.

Remove any call to txm_module_object_deallocate from your module. Calling the appropriate tx*delete service is sufficient; pool memory deallocation is handled automatically by the Module Manager dispatch layer.

Module threads

Deprecated — see above. This service retrieves the object pointer of a particular type with a particular name. If the object is not found, an error is returned. Otherwise, if the object is found, the address of that object is placed in "object_ptr."

The pointer this service returns grants use of the object, not authority to destroy it. See txm_module_object_pointer_get_extended.

Module threads without memory protection

This service retrieves the object pointer of a particular type with a particular name. If the object is not found, an error is returned. Otherwise, if the object is found, the address of that object is placed in "object_ptr." This pointer can then be used to make system service calls, to interact with the resident code, and/or other loaded modules in the system.

The pointer grants use of the object, not authority to destroy it. A memory-protected module may only delete a kernel object it allocated for itself from the Module Manager’s object pool; passing a pointer obtained here to tx_queue_delete, tx_semaphore_delete or any other tx*delete service returns TXM_MODULE_INVALID_MEMORY and leaves the object created and its waiters undisturbed. Objects a module does not own are shared with it to be used, and the owner remains responsible for deleting them.

A memory-protected module cannot look up a block pool or a byte pool at all: TXM_BLOCK_POOL_OBJECT and TXM_BYTE_POOL_OBJECT return TXM_MODULE_INVALID for such a module, which may use only the pools it created itself.

The search compares the name a character at a time and stops at the terminating null, so it reads name_length + 1 bytes at most: the characters, and the terminator that follows them. For a module loaded with TXM_MODULE_MEMORY_PROTECTION the whole of that range, from name[0] through name[name_length], must be inside memory the module may read — its own data, its own code, or shared memory registered to it. A request whose range is not entirely readable is refused with TXM_MODULE_INVALID_MEMORY before any comparison is made, so a name buffer at the very end of a region must have room for the terminator as well as the characters.

A name_length of UINT_MAX is always refused, because the range it describes cannot be expressed.

Module threads