86 KiB
| title | source | category | pages | extracted |
|---|---|---|---|---|
| Pikeos Native Api Extensions | docs/universalisos-native/universalisos-native-api-extensions.pdf | universalisos-native | 54 | 2026-07-06T23:06:05.614111 |
Pikeos Native Api Extensions
Extracted from
docs/universalisos-native/universalisos-native-api-extensions.pdf(54 pages). Figures, diagrams, and tables may not render accurately in plain text.
P4EXT
UniversalisOS Native Personality Extensions
Am Pfaffenstein 14, D-55270 Klein-Winternheim
Notice: The contents of this document are proprietary to Portugal Futurista GmbH and shall not be disclosed, disseminated, copied, or used except for purposes expressly authorized in writing by Portugal Futurista GmbH. UniversalisOS Native Personality Extensions UniversalisOS D5.0, Document Version D5.0-74
c 2005 – 2019 Portugal Futurista GmbH
Portugal Futurista GmbH Email: office@portugalfuturista.org Am Pfaffenstein 14 55270 Klein-Winternheim, Germany http://www.portugalfuturista.org
All rights reserved. UniversalisOS is a trademark of Portugal Futurista GmbH. The designations used to identify other software or hardware products in this publication may be trademarks of their manufacturers or sellers. Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2 Function Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.1.1 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2 Process Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2.1 Process Configuration Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2.2 Parameters for Program Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2.3 Diagnostics Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.3 Virtual Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.4 Dynamic Memory Allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.5 Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.6 Stack Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.7 Miscellaneous Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3 Programming Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.1 Name Space and API Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2 Program Entry Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.3 Thread Deletion Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1 Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.3 Name Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.4 User-defined Trace Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6 Certifiable Variant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.1 Project Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.1.1 Process Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.1.2 Miscellaneous Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.2 Dynamic Memory Allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 6.3 Provided API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 6.4 Provided Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 7 API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.1 P4EXT_THREADS: Thread management functions . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.1.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.1.1.1 struct p4ext_thr_attr_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.1.1.2 struct p4ext_tls_area_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.1.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 7.1.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 7.1.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.1.4.1 p4ext_thr_attr_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.1.4.2 p4ext_thr_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.1.4.3 p4ext_thr_exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 7.1.4.4 p4ext_thr_reclaim_resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
4 CONTENTS
7.1.4.5 p4ext_thr_tls_ptr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.1.4.6 p4ext_thr_tls_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
7.1.4.7 p4ext_thr_num_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.1.4.8 p4ext_thr_num_release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.1.4.9 p4ext_thr_num_tryalloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.1.4.10 p4ext_thr_num_gdbstub_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.2 P4EXT_STACK: Stack management functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.2.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.2.1.1 struct p4ext_stack_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.2.2 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.2.3 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 7.2.3.1 p4ext_stack_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 7.2.3.2 p4ext_stack_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 7.3 P4EXT_MALLOC: Memory allocation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 7.3.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7.3.1.1 malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7.3.1.2 calloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 7.3.1.3 realloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.3.1.4 free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 7.3.1.5 aligned_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 7.4 P4EXT_UTIL: Miscellaneous utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 7.4.1 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 7.4.1.1 p4ext_abort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 7.5 P4EXT_VMEM: Virtual memory management functions . . . . . . . . . . . . . . . . . . . . . . . 42 7.5.1 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.5.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 7.5.2.1 p4ext_vmem_alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 7.5.2.2 p4ext_vmem_alloc_aligned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 7.6 P4EXT_ERROR: Thread-specific error number . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7.6.1 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 7.7 P4EXT_CONFIG: Process configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 7.7.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 7.7.1.1 struct p4ext_config_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 7.7.2 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 7.7.3 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 7.8 P4EXT_DIAG: Diagnostics services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.8.1 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 7.8.2 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 A Features Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 B Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 B.1 Add Multiple Processes of the Regular Variant to a Partition . . . . . . . . . . . . . . . . . . . . . 53 B.2 Add Multiple Processes of the Certifiable Variant to a Partition . . . . . . . . . . . . . . . . . . . . 53 B.3 Set a Process of the Certifiable Variant to Execute in Place . . . . . . . . . . . . . . . . . . . . . . 54
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
1 Introduction
The UniversalisOS Native personality extensions (P4EXT) extend the UniversalisOS kernel API described in the UniversalisOS Kernel Reference Manual adding start-up code and a standardized program entry point, extended process configuration, virtual address space management, a dynamic memory allocator, and simplified thread management functions including thread number and thread-local storage management. Those extensions are available using the person- ality UniversalisOS native. Section 2 describes the function groups and configuration items of the UniversalisOS Native personality extensions. Section 3 shows differences in the programming environment between regular UniversalisOS applications and UniversalisOS Native applications using the personality extensions. Section 4 describes the provided tracing support. Section 5 contains a summary of the files comprising the UniversalisOS Native personality extensions. Section 6 introduces the certifiable variant of the UniversalisOS Native personality extensions and 7 contains a reference of the UniversalisOS Native personality extensions API services.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
2 Function Groups
2.1 Project Configuration
In the configuration of UniversalisOS Native application program, support for the UniversalisOS Native personality extensions is always enabled. Using this personality an application will always be linked to the p4ext library.
Warning: Make sure to select UniversalisOS Native personality and not UniversalisOS which only allow usage of the kernel and PSSW APIs.
2.1.1 Debugging
The Debug parameter allows the debugging of an application. It will link the application with a version of the library containing line number information and will configure the gdbstub before calling the main function of an application. To stop the application the call to gdb_breakpoint() need to be enabled in the code. If not it is still possible to stop the application from the debugger during runtime.
2.2 Process Configuration
The process configuration consists of a configuration record included in the program executable image describing resource allocation and limits for the API services and of a set of UniversalisOS properties used to configure function arguments for the program entry point and diagnostics services. A configuration record with default values is included in the API object code library, an application project configuration parameter allows providing an application-specific configuration record with contents configured in the Project Configurator.
2.2.1 Process Configuration Record
The contents of the process configuration record are part of the application configuration managed by the Project Configurator. Parameters include:
• Stack size for initial thread.
• Virtual address region for virtual memory management functions.
• Virtual address region for thread stack remapping.
• Size of TLS area.
• Size of trace buffer area.
• Memory source of dynamic memory allocator, either process mapped memory or PSSW memory pool.
• Dynamic memory access permissions, either read-write or read-write-execute.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Process Configuration 7
Parameters configured in the Project Configurator are stored in a configuration record (C source). The configura- tion record is described in 7.7. If an application-specific configuration record is enabled, file $PIKEOS_TARGET_FILES/universalisos- native/src/p4ext_config.c is added to the application project source modules, the configuration parameters defined in the application project configuration are used to modify the configuration record content. By default, no application specific TLS area is installed, the implementation uses the structure p4ext_tls_area_s defined in <p4ext/p4ext_tls.h> (see 7.1.1.1 for details). Applications making use of thread-local storage can define their own structure and specify the size (in bytes) of the TLS area to allocate for each thread in a header file. The TLS structure layout must match the contents of p4ext_tls_area_s, application-specific fields can be added after the contents of p4ext_tls_area_s. The header file used to define the TLS structure size for the process configuration record must be named p4ext_tls_user.h and be accessible in the application project directory. File p4ext_tls_user.h must define the TLS area size using a symbol named P4EXT_TLS_SIZE. p4ext_tls_user.h example:
#include <p4.h>
typedef struct {
/* Fixed layout: */
P4_tls_area_t p4;
void *cenv_reserved;
void *cppenv_reserved;
/* Application data: */
int idata;
void *pdata;
} tls_t;
#define P4EXT_TLS_SIZE sizeof(tls_t)
2.2.2 Parameters for Program Entry Point
The application program entry point is a C standard compliant main() function (see also section 3). The argument vector passed to the main() function always includes at least one non-NULL element, the name (PSSW process name, UniversalisOS task name) of the process. Additional parameter values can be configured using UniversalisOS properties as follows:
.... c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
8 Function Groups
Note that in the example shown above, <Partition_Name> and <Process_Name> are placeholders for the name of the process’ resource partition and the name of the process, respectively. If less argvN parameters than the number of arguments specified in the numargs parameter are defined, the process configuration will be aborted and the process terminated. Storage for the strings pointed to by the argument vector elements is allocated using the dynamic memory allocator (see section 2.4, page 8). In an integration project, the UniversalisOS Native process component contains an option allowing to set up to 4 arguments. The component can be inlined to add more arguments.
2.2.3 Diagnostics Services
The diagnostics control word (see 7.8 for details) can be set up using UniversalisOS properties as follows:
The diagnostics control word value provided in UniversalisOS properties is used in the process initialization to overwrite any value that might have been provided programmatically. The UniversalisOS Native process component provides an option allowing to set up the diagnostics control word in an integration project.
2.3 Virtual Memory Management
The process configuration record specifies a region of the process virtual address space (p4ext_con- fig_t::vmem_start, p4ext_config::vmem_size) used by the virtual memory management services. Functions are provided to allocate virtual address space regions in the configured bounds. Once allocated, virtual address space regions cannot be released. Refer to section 7.5 for further details on the virtual memory management services.
2.4 Dynamic Memory Allocator
C standard compliant memory management functions (malloc(), calloc(), realloc(), free(), and aligned_alloc()) are provided, refer to section 7.3 for further details. Physical memory used as source for the memory allocation functions can either be taken from unused process memory (PSSW memory requirement mapped as process memory) or from a PSSW memory pool. If a memory pool is used as memory source, its name is taken from the process configuration record (p4ext_con- fig_t::heap_pool) and memory from that pool is mapped to the process virtual address space at process start-up. The size of the heap pool can be limited (p4ext_config_t::heap_size) to allow two or more processes to share a pool. If the size is set to 0 the whole memory pool is used and it can not be shared. This is the default behavior. The pool settings can be overwritten by the integration project. The necessary options for that can be found in the process component in the Advanced Process Settings option menu. The integrator can select the memory source
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Thread Management 9
for the heap. If a memory pool is selected, the integrator can choose to overwrite the pool name, the heap size or both. By default the settings of the configuration record are used. Virtual address space for the mapped memory is taken from the region configured in p4ext_config_t::vmem_start and p4ext_config::vmem_size. The access permissions to the dynamic memory is indicated by p4ext_config_t::heap_exec. By default it is set read-write and can be turned into read-write-exec. If the source for dynamic memory source is a pool, the execute permission must be set in the memory requirement to use this feature.
2.5 Thread Management
Thread management functions include
• simplified thread creation
• storage management for thread-local storage (TLS)
• storage management for thread stacks, including remapping of stack memory with guard pages
• thread number management
• explicit resource reclaim
The thread creation function p4ext_thr_create() (see 7.1.4.2 for details) combines stack memory allocation and management, thread context creation, and thread creation parameter handling in a single function while retaining the flexibility of the UniversalisOS kernel API. Thread number management facilitates integration with 3rd party libraries, and thread stack management allows for efficient resource management and provides for additional protection using stack memory remapping with guard pages. The setup of stack guard pages for threads created with the UniversalisOS Native API is controlled by p4ext_thr_attr_t::guardsize and p4ext_thr_attr_t::stack (see 7.1.1 for details). Threads created using the default thread attributes object will use remapped stacks with guard pages (refer to 7.1.4.1 for details on the default thread attributes object). For the initial thread, guard pages are inserted around the stack when the process is loaded. As with the UniversalisOS kernel API, there is no wrapper around the thread start function which would automatically delete the thread when the thread start function returns. Function p4ext_thr_exit() is provided to terminate the calling thread (see 7.1.4.3 for details). Resources allocated by the implementation when creating a thread can be reclaimed by the application using function p4ext_thr_reclaim_resources() (see 7.1.4.4 for details). Note that virtual regions allocated for stack remapping are not reclaimed. Thread-local storage is initialized following UniversalisOS kernel conventions detailed in UniversalisOS Kernel Reference Man- ual. For application program convenience a thread-specific error number location is provided under the standard name errno (refers to section 7.6 for details). Refer to section 7.1 for further details on the thread management services.
2.6 Stack Management
Stack management functions include:
• stack creation
• stack destruction
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
10 Function Groups
Function p4ext_stack_create() (see 7.2.3.1) creates stack areas to be deployed in the creation of threads and installation of exception handlers using the kernel API. The output of this function includes the stack’s base address and size to be used as input to P4_STACK(). The procedures used by the stack management functions to create and destruct stacks are the same used internally by p4ext_thr_create() and p4ext_thr_reclaim_resources(). Refer to section 7.2 for further details on the stack management services.
2.7 Miscellaneous Utility Functions
Miscellaneous utility functions are provided for
• Static and dynamic (run-time) assertion, see section 7.8
• C standard compliant error number location, see 7.6
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
3 Programming Environment
3.1 Name Space and API Concepts
With the exception of the memory allocation service, API services of the UniversalisOS Native personality extensions use p4ext_ as function name prefix. UniversalisOS API error numbers of type P4_e_t are used as error indications. The errno variable is not used by any API service.
3.2 Program Entry Point
When using the UniversalisOS Native personality extensions, the program entry point is no longer a choice of the application programmer, the program entry point is rather an ISO C standard compliant function main(), using either one of the following function signatures:
int main(void); int main(int argc, char *argv[]);
Function main() is entered by the initial thread of the process. The stack definition of the initial thread is provided by the configuration record, there is no need for the application programmer to provide a stack definition using the P4_DECLARE_STACK() API service. When the main() function is entered, the process has already attached itself to the PSSW, there is no need for the application programmer to call the vm_init() PSSW API service. When the main() function returns, the process is terminated by setting the partition mode of the process’ partition to idle (VM_PART_MODE_IDLE).
3.3 Thread Deletion Considerations
Several services of the UniversalisOS Native personality extensions use synchronization services to protect access to critical data. Application programs deleting threads should make sure that the thread to be deleted is not executing services of the native personality extensions when being deleted.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
4 Tracing
UniversalisOS Native applications can generate trace events for the CODEO Trace Tool. Please refer to the UniversalisOS User Manual for an overview of tracing and to the CODEO User Manual for a detailed description of the trace tool.
Note: The trace enabled version of UniversalisOS Native is larger than the regular version. Due to the tracing code it also has a different run-time performance. This should be considered when examining trace data.
4.1 Trace Events
Trace events provided in UniversalisOS Native can be ordered in 3 types:
Enter events are generated when a function is entered. Normally each enter event is followed by a corresponding exit event.
Exit events are generated when a function is finished.
Single events indicate a single point of activity. It can appear in between related enter and exit events, to trace internal activities performed in function calls. Or it can appear alone, to trace activities for which it makes no sense to have enter or exit events (e.g. a call to p4ext_abort()).
Recording of trace events can be individually enabled in the CODEO Trace Tool. Besides custom trace events, which are detailed in section 4.4, UniversalisOS Native provides tracing capabilities (enter, exit and single types) in:
• Thread management functions
• Stack management functions
• Memory allocation functions
• Virtual memory management functions
• Miscellaneous utility functions
4.2 Project Configuration
Tracing is enabled in the Project Configurator by setting the build option PIKEOS_P4EXT_TRACE to true. When tracing is enabled, the macro SPIDER_TRACE_SUPPORT is predefined in the compilation environment and the ap- plication is linked against a library providing tracing services. Tracing and GDB debugging are mutually exclusive. Tracing is not supported in the certifiable variant. The size of the trace buffer is configured in the process configuration record (p4ext_config_t::trace_size). The virtual address space for mapping the trace buffer memory is allocated from the region configured in p4ext_con- fig_t::vmem_start and p4ext_config::vmem_size.
Note: The size of the region available for virtual memory management functions is decreased by the size of the trace buffer in trace enabled applications.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
Name Space 13
4.3 Name Space
Tracing services use spider_ and SPIDER_ as prefixes for function and macro names.
4.4 User-defined Trace Events
Custom events are handled in the CODEO Trace Tool as any other trace event. The example below shows how custom trace events can be added to applications.
#include <vm.h> #include <p4ext_trace.h> /* Custom events macro definitions. */
int main(void) { P4_uid_t me = p4_my_uid(); P4_timeout_t sleeptime = P4_SEC(5);
while (1) {
SPIDER_CUSTOM_EVENT_0_0(SPIDER_CONTEXT, SPIDER_THREAD,
me, /* data 1 */
P4_UID_GET_RESPART(me), /* data 2 */
P4_UID_GET_TASK(me), /* data 3 */
P4_UID_GET_THREAD(me), /* data 4 */
"Hello World!" /* data 5 */
);
vm_cprintf("Hello world!\n");
p4_sleep(sleeptime);
}
}
UniversalisOS Native provides 4 custom events, enumerated 0 through 3. Every custom event is composed of 16 sub- events, enumerated 0 through 15. In total, 64 custom sub-events are available to establish application specific tracing points. The numbers in SPIDER_CUSTOM_EVENT_0_0 specify the event and sub-event IDs. For example, SPIDER_CUSTOM_EVENT_3_10 corresponds to sub-event 10 of custom event 3. The first two parameters of the macros must be SPIDER_CONTEXT and SPIDER_THREAD. In events 0 to 2, the next four parameters (marked data 1 through data 4 in the example) are 32bit unsigned integer values. In event 3, those parameters are 64bit unsigned integer values. In all events, the first two of those integer values will be displayed as hexadecimal values, the last two as decimal values. In all events, the last parameter (marked data 5 in the example) is a zero terminated string. Unless the macro SPIDER_TRACE_SUPPORT is predefined, all macros SPIDER_CUSTOM_EVENT_0_0 through SPIDER_CUSTOM_EVENT_3_15 evaluate to empty operations. Note: Calling custom events from threads with non-initialized TLS areas may cause exceptions or undefined behavior.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
5 Files
Header files for the UniversalisOS Native personality extensions are installed in: $PIKEOS_TARGET_FILES/universalisos-native/include/p4ext Object code libraries are installed in: $PIKEOS_TARGET_FILES/universalisos-native/lib/libp4ext.a $PIKEOS_TARGET_FILES/universalisos-native/lib/libp4ext-assert.a $PIKEOS_TARGET_FILES/universalisos-native/lib/libp4ext-dbg.a $PIKEOS_TARGET_FILES/universalisos-native/lib/libp4ext-dbg-assert.a $PIKEOS_TARGET_FILES/universalisos-native/lib/libp4ext-trace.a $PIKEOS_TARGET_FILES/universalisos-native/lib/libp4ext-trace-assert.a Source code for the process configuration record is installed in: $PIKEOS_TARGET_FILES/universalisos-native/src/p4ext_config.c Makefile definitions and rules for UniversalisOS Native personality extensions are installed in: $PIKEOS_TARGET_FILES/universalisos-native/makeinc/personality.mk $PIKEOS_TARGET_FILES/demo/universalisos-native/empty.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
6 Certifiable Variant
6.1 Project Configuration
A certifiable variant of the UniversalisOS Native personality library will be linked to the application when this variant is enabled in the application project. If the certifiable variant is enabled, any process configuration provided in the Project Configurator (refer to section 2.2.1) is ignored. The certifiable variant is mutually exclusive with the C and C++ language programming environments. If the GDB stub library is enabled, the application is linked to a version of the certifiable library providing the same features and usage as described in section 2.1.1. Tracing is not supported in the certifiable variant.
6.1.1 Process Configuration
The certifiable variant features a configuration record providing a subset of the parameters supported in the regular variant. The parameters used to configure a PSSW memory pool as source the heap, to set the heap access permissions, and to enable tracing are excluded. If an application-specific configuration record is enabled in the certifiable variant configuration, a copy of the file $PIKEOS_TARGET_FILES/universalisos-native/cert/src/p4ext_config.c is added to the application project. This source module should be edited to modify the configuration record default content. The configuration provided in the Project Configurator is ignored. The fixed layout defined for the structure p4ext_tls_area_s in the certifiable variant does not include the parameters reserved for the C and C++ programming environments. Other aspects related to the definition and use of an application specific TLS area remain the same as in the regular variant.
6.1.2 Miscellaneous Configuration
The application entry point should be defined using the ISO C standard compliant main() function signature with a return type of int and with no parameters. Arguments configured using UniversalisOS properties are ignored. Diagnostic services are not supported. The configuration provided in the Project Configurator is ignored.
6.2 Dynamic Memory Allocator
Once allocated, memory cannot be released. The physical memory used as source for the memory allocation functions can only be taken from unused process memory (PSSW memory requirement mapped as process memory). The access permissions to dynamic memory is set to read-write and cannot be changed.
Note: The integrator has to disable the Use Pool option in the Advanced Process Settings menu of the process component (the option is enabled by default).
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
16 Certifiable Variant
6.3 Provided API
The certifiable variant provides a subset of the regular variant’s API:
• p4ext_thr_attr_init()
• p4ext_thr_create()
• p4ext_vmem_alloc()
• p4ext_vmem_alloc_aligned()
• malloc()
• calloc()
• free()
• aligned_alloc()
The API reference is provided in section 7. Differences of the certifiable version of the API functions in relation to the regular version are addressed in notes for p4ext_thr_create() (refer to 7.1.4.2) and free() (refer to 7.3.1.4).
6.4 Provided Files
Header files for the certifiable variant are installed in $PIKEOS_TARGET_FILES/universalisos-native/cert/include/p4ext. Object code libraries are installed in $PIKEOS_TARGET_FILES/universalisos-native/cert/lib/libp4ext.a, and $PIKEOS_TARGET_FILES/universalisos-native/cert/lib/libp4ext-dbg.a. Source code for the process configuration record is found in $PIKEOS_TARGET_FILES/universalisos-native/cert/src/p4ext_config.c. Makefile definitions and rules are found in $PIKEOS_TARGET_FILES/universalisos-native/makeinc/option/cert.mk.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
7 API Reference
7.1 P4EXT_THREADS: Thread management functions
• The thread management functions include thread number management and a simplified thread creation
service. Thread number management is provided to allow coexistence with third-party code that does not
make use of the native API extension services.
• The thread creation service uses a thread attribute object (p4ext_thr_attr_t) to reduce the number of function
parameters. The thread attribute object can be omitted during thread creation, default values will then be
used instead.
• Thread creation optionally includes allocation and remapping of stack memory. A service to release re-
sources allocated by the thread creation API for deleted threads is also provided.
• Thread management services allocate memory for use as thread-local storage (TLS) according to applica-
tion configuration (P4EXT_CONFIG: Process configuration). Thread local storage entries defined by the
UniversalisOS kernel API are initialized appropriately for threads created by the thread creation service. Addition-
ally, services to initialize TLS for user mode context and for the calling thread are provided.
• When implementing an application which uses p4_thread_create() and p4ext_thr_create() (see sec-
tion 7.1.4.2) the following needs to be considered: p4ext_thr_num_alloc() (see section 7.1.4.7) and
p4ext_thr_num_tryalloc() (see section 7.1.4.9) only operate on internal data structures. They are not aware
of thread numbers used outside of the scope of the P4EXT thread API. If both thread creation functions
need to be mixed, the application startup code should allocate the required thread IDs (thread numbers) for
the code p4_thread_create() using the P4EXT services.
• User API
p4ext_thr_attr_init() (see section 7.1.4.1)
p4ext_thr_create() (see section 7.1.4.2)
p4ext_thr_exit() (see section 7.1.4.3)
p4ext_thr_num_alloc() (see section 7.1.4.7)
p4ext_thr_num_gdbstub_alloc() (see section 7.1.4.10)
p4ext_thr_num_release() (see section 7.1.4.8)
p4ext_thr_num_tryalloc() (see section 7.1.4.9)
p4ext_thr_reclaim_resources() (see section 7.1.4.4)
p4ext_thr_tls_ptr() (see section 7.1.4.5)
p4ext_thr_tls_register() (see section 7.1.4.6)
7.1.1 Structure Definitions
7.1.1.1 struct p4ext_thr_attr_s
Thread attribute structure. Used as parameter to p4ext_thr_create() (see section 7.1.4.2) to optionally specify thread attributes deviating from internal default values. Function p4ext_thr_attr_init() (see section 7.1.4.1) can be used to initialize an attribute object to the internal default values.
Synopsis:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
18 API Reference
struct p4ext_thr_attr_s { P4_uint32_t context_flags; P4_uint32_t thread_flags; P4_prio_t prio; P4_uint32_t tp_id; P4_uid_t shortexh; P4_uid_t fullexh; P4_uid_t ipc_mask; P4_uid_t ev_mask; P4_size_t guardsize; P4_size_t stacksize; void * stack; };
Structure Element Description: context_flags Context creation flags (P4_THREAD_ARG_xxx). thread_flags Thread creation flags (P4_THREAD_CREATE_xxx). prio Scheduling priority. tp_id Time partition ID. shortexh Short exception handler UID. fullexh Full exception handler UID. ipc_mask IPC mask. ev_mask Event mask. guardsize Guardsize (in bytes) for remapped stacks. If greater than 0, and the structure member stack is NULL, unmapped guard pages are inserted around the stack memory region. Otherwise, if equal to 0, or stack is non-NULL, guard pages are not inserted. stacksize Stack size in bytes. stack Base address of the stack memory region (not the stack pointer returned by P4_STACK()). Default is NULL, to request dynamic allocation of the stack region. A non-NULL value indicates an application managed stack.
Associated Data Type
p4ext_thr_attr_t
7.1.1.2 struct p4ext_tls_area_s
Thread-local storage record. Applications may use their own data structure for TLS, however the first elements of such structures must match the layout of structure p4ext_tls_area_s. When using an application-specific structure, the configured TLS area size must at least be the size of structure p4ext_tls_area_s.
Note: Regarding the regular variant, the elements p4, cenv_reserved, and cppenv_reserved are always present in the structure definition, while the element trace_context is present only if the trace support is enabled. With respect to the certifiable variant, only the element p4 is present.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_THREADS: Thread management functions 19
Synopsis: struct p4ext_tls_area_s { P4_tls_area_t p4; void * cenv_reserved; void * cppenv_reserved; spider_context_t trace_context; };
Structure Element Description: p4 UniversalisOS mandated layout. cenv_reserved Reserved for CENV use. cppenv_reserved Reserved for CPPENV use. trace_context Thread tracing context.
Associated Data Type
p4ext_tls_area_t
7.1.2 Defines
P4EXT_THR_NUM_INVALID
Description:
Invalid thread number.
7.1.3 Data Type Definitions
p4ext_thr_attr_t Thread attribute structure. Used as parameter to p4ext_thr_create() (see section 7.1.4.2) to optionally specify thread attributes deviating from internal default values. Function p4ext_thr_attr_init() (see section 7.1.4.1) can be used to initialize an attribute object to the internal default values. p4ext_tls_area_t Thread-local storage record. Applications may use their own data structure for TLS, however the first elements of such structures must match the layout of structure p4ext_tls_area_s. When using an application-specific structure, the configured TLS area size must at least be the size of structure p4ext_tls_area_s.
Note:
Regarding the regular variant, the elements p4, cenv_reserved, and cppenv_reserved are always
present in the structure definition, while the element trace_context is present only if the trace support is
enabled. With respect to the certifiable variant, only the element p4 is present.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
20 API Reference
7.1.4 Functions
7.1.4.1 p4ext_thr_attr_init
Location: p4ext_threads.h
Synopsis:
void p4ext_thr_attr_init(p4ext_thr_attr_t *attr)
Description: Initialize a thread attribute object with default values. The attribute object structure members (p4ext_thr_attr_s) are initialized as follows: • context_flags = P4_THREAD_ARG_DEBUG | P4_THREAD_ARG_FPU • thread_flags = 0 • prio = P4_NUM_PRIO • tp_id = P4_TIMEPART_INHERIT • shortexh = P4_UID_INHERIT • fullexh = P4_UID_INHERIT • ipc_mask = P4_UID_ALL • ev_mask = P4_UID_INVALID • guardsize = P4_PAGESIZE • stacksize = (4 * P4_PAGESIZE) • stack = NULL
Parameters: attr [OUT] Pointer to thread attribute object to initialize.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_THREADS: Thread management functions 21
7.1.4.2 p4ext_thr_create
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_create(P4_thr_t *thrno, p4ext_thr_attr_t *attr, const char *name, void *entry, unsigned int nargs, ...)
Description: Create a thread. If thrno is not the null pointer and the value pointed to is not equal to P4EXT_THR_NUM_INVALID, function p4ext_thr_create() (see section 7.1.4.2) will use the thread number pointed to by thrno for the newly created thread. Otherwise, function p4ext_thr_create() (see section 7.1.4.2) will allocate a thread number for the newly created thread. Upon successful completion, if thrno is not the null pointer, the location pointed to by thrno will be updated to contain the thread number allocated by p4ext_thr_create() (see section 7.1.4.2). If attr is not the null pointer, context creation flags, thread creation flags, thread stack size, and thread attributes will be taken from the attribute object pointed to by attr. Otherwise, if attr is the null pointer, creation flags and attributes are determined by the default attribute object (refer to p4ext_thr_attr_init() (see section 7.1.4.1) for details on the default attribute object). Function entry will be set as thread start function of the newly created thread, the function will be entered with up to nargs arguments as specified by the variable argument list of p4ext_thr_create() (see section 7.1.4.2). As in the UniversalisOS kernel API there is no wrapper function calling entry that would delete the calling thread when the thread start function returns. Function p4ext_thr_create() (see section 7.1.4.2) will allocate storage for a thread descriptor for later use by p4ext_thr_reclaim_resources() (see section 7.1.4.4) and initialize the TLS area in the thread context of the thread.
Parameters: thrno [IN/OUT] Thread number storage. attr [IN] Pointer to thread attribute object or NULL. name [IN] Name for the thread to create. entry [IN] Thread start function. nargs [IN] Number of arguments for thread start function. ... [IN] nargs arguments for thread start function.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_INVAL Invalid stack attributes in attributes object attr. P4_E_INVAL nargs is invalid. P4_E_INVAL thrno is not the null pointer and specifies a an invalid thread number. P4_E_OOMEM Allocation of a thread number failed. P4_E_OOMEM Allocation of stack memory failed.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
22 API Reference
P4_E_OOMEM Allocation of thread descriptor failed.
P4_E_STATE An active thread exists for the thread number to be used for the newly created thread.
other Error indications returned by p4_thread_create().
Note: When using the certifiable variant:
• The parameter thrno must point to a valid thread number. If thrno is the null pointer, the function fails and
returns P4_E_INVAL.
• If the creation of guard pages around the stack region fails, an application error is raised to the health
monitor and the program is aborted.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_THREADS: Thread management functions 23
7.1.4.3 p4ext_thr_exit
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_exit(void) __noreturn
Description: Terminate calling thread. The function deletes the calling thread. Thread resources are not released, the application can use p4ext_thr_reclaim_resources() (see section 7.1.4.4) from another thread to reclaim resources of an inactive thread. Currently the function is just a wrapper for p4_thread_delete(), future enhancements may add thread exit hooks for cleanup purposes.
Note: The function does not return to the caller.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
24 API Reference
7.1.4.4 p4ext_thr_reclaim_resources
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_reclaim_resources(P4_thr_t thrno)
Description: Reclaim resource of an inactive thread. The function reclaims resources previously allocated by p4ext_thr_create() (see section 7.1.4.2) when creating the thread and also releases thread number thrno.
Parameters: thrno [IN] Thread number of thread whose resources to reclaim.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_INVAL thrno is an invalid thread number. P4_E_STATE thrno is not marked as in-use. P4_E_STATE An active thread exists for thread number thrno.
Note: Virtual address space regions allocated for stack remapping are not freed.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_THREADS: Thread management functions 25
7.1.4.5 p4ext_thr_tls_ptr
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_tls_ptr(P4_thr_t thrno, void **tls_ret)
Description: Return a pointer to the managed TLS data area for a thread number. If tls_ret is not the null pointer, and thrno has been allocated with p4ext_thr_num_alloc() (see section 7.1.4.7) or p4ext_thr_num_tryalloc() (see section 7.1.4.9), this function allocates a thread descriptor and storage for the TLS data area managed for thrno. The TLS area is initialized to default values (as if initialized by p4_tls_init()), and can be properly used along with p4_thread_create_syscall(). Upon success, a pointer to the managed TLS is returned in tls_ret.
Parameters: thrno [IN] Thread number of thread from which to get the TLS pointer. tls_ret [OUT] Pointer to managed TLS area.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes: P4_E_INVAL tls_ret is the null pointer. P4_E_INVAL thrno is an invalid thread number. P4_E_STATE thrno is not marked as in-use. P4_E_OOMEM Failure to allocate thread descriptor.
Note: The resources allocated for the TLS area can be released in a call to p4ext_thr_reclaim_resources() (see section 7.1.4.4) for thrno.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
26 API Reference
7.1.4.6 p4ext_thr_tls_register
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_tls_register(P4_regs_t *regs, P4_thr_t thrno)
Description: Create administrative data and register TLS in a user mode context. The function creates a thread descriptor for thread thrno and registers TLS in the user mode context regs.
Warning: The function should not be called for threads previously created by p4ext_thr_create() (see section 7.1.4.2) as the information on allocated resources will be cleared in the thread descriptor created by this function.
Parameters: thrno [IN] Thread number of thread whose resources to reclaim. regs [IN/OUT] User mode context.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_INVAL thrno is an invalid thread number. Note: regs is not modified. P4_E_STATE thrno is not marked as in-use. Note: regs is not modified. P4_E_OOMEM Failure to allocate thread descriptor. Note: regs is modified, TLS is initialized.
Note: This function has been deprecated and will be removed in the next UniversalisOS version.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_THREADS: Thread management functions 27
7.1.4.7 p4ext_thr_num_alloc
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_num_alloc(P4_thr_t *thrno)
Description: Allocate a thread number. If an unused thread number exists, that number is marked as in-use and stored at the location pointed to by thrno.
Parameters: thrno [OUT] Storage for allocated thread number.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_OOMEM All thread numbers in use.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
28 API Reference
7.1.4.8 p4ext_thr_num_release
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_num_release(P4_thr_t thrno)
Description: Release a thread number. Marks thread number thrno as not in-use.
Parameters: thrno [IN] Thread number to release.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_INVAL thrno is an invalid thread number for the process. P4_E_STATE thrno is already marked as not in-use.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_THREADS: Thread management functions 29
7.1.4.9 p4ext_thr_num_tryalloc
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_num_tryalloc(P4_thr_t thrno)
Description: Allocate a specific thread number. If thread number thrno is not in-use, the function marks it as in-use.
Parameters: thrno [IN] Thread number to allocate.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_INVAL thrno is an invalid thread number for the process. P4_E_OOMEM Thread number thrno is already marked as in-use.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
30 API Reference
7.1.4.10 p4ext_thr_num_gdbstub_alloc
Location: p4ext_threads.h
Synopsis:
P4_e_t p4ext_thr_num_gdbstub_alloc(void)
Description: Allocate thread numbers of GDB stub. The function allocates thread numbers used by the GDB debug interface. Applications calling init_gdstub() should use this function to mark thread numbers used by the debug interface as in use.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_OOMEM Failure to allocate thread numbers.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_STACK: Stack management functions 31
7.2 P4EXT_STACK: Stack management functions
• The stack management functions provide services for creating and destroying stacks.
• The function for creating stacks allocates memory and a virtual region to remap the new stack, surrounding
it with guard pages. It uses a stack descriptor (p4ext_stack_t) to encapsulate the stack attributes in a single
object. Stacks created with this function can be further processed to create threads using p4_thread_cre-
ate() or installing exception handlers.
• The function for destroying stacks reverses all memory mappings performed upon the creation of the stack
and releases allocated resources. The function has an argument of the same type as the function for stack
creation.
• User API
p4ext_stack_create() (see section 7.2.3.1)
p4ext_stack_destroy() (see section 7.2.3.2)
7.2.1 Structure Definitions
7.2.1.1 struct p4ext_stack_s
Stack attributes data structure. The p4ext_stack_s data structure is used as argument in the functions for creating and destroying stacks.
Synopsis: struct p4ext_stack_s { void * stack; P4_size_t stacksize; P4_size_t guardsize; };
Structure Element Description: stack Start address of the stack area. stacksize Stack area size in bytes. guardsize Size of unmapped guard pages inserted around the stack area, in bytes.
Associated Data Type
p4ext_stack_t
7.2.2 Data Type Definitions
p4ext_stack_t Stack attributes data structure.
The p4ext_stack_s data structure is used as argument in the functions for creating and destroying
stacks.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
32 API Reference
7.2.3 Functions
7.2.3.1 p4ext_stack_create
Location: p4ext_stack.h
Synopsis:
P4_e_t p4ext_stack_create(p4ext_stack_t **stack_ret, P4_size_t stacksize, P4_size_t guardsize)
Description: Create a stack area surrounded by unmapped guard pages. If stack_ret is not the null pointer, this function allocates storage for the stack descriptor to be returned and stacksize bytes to create the stack. If guardsize is not zero, the function allocates a virtual area and remaps the allocated memory into it. Before performing the remap, the source and destination areas are rounded up to suitably aligned sizes. Upon the remapping, unmapped guard pages are inserted around the destination area, the source area access is set to read-only, and the destination area access is set to read-write. Upon success, stack_ret members’ stack, stacksize and guardsize are filled with values to be used in the initialization of a stack pointer using P4_STACK().
Parameters: stack_ret [OUT] Pointer to stack descriptor object. stacksize [IN] Requested stack size in bytes. guardsize [IN] Requested guard pages size in bytes.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_INVAL stack_ret is the null pointer. P4_E_INVAL stacksize size is zero. P4_E_OOMEM Allocation of dynamic memory to create the stack failed. P4_E_LIMIT Allocation of the virtual area to remap the stack failed. P4_E_NOKMEM Allocation of kernel memory for memory mapping failed.
Note: Applications shall preserve the integrity of the returned descriptor, as it is used as argument for p4ext_stack_destroy() (see section 7.2.3.2). The object pointed to by stack_ret is trailed by admnistrative data.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_STACK: Stack management functions 33
7.2.3.2 p4ext_stack_destroy
Location: p4ext_stack.h
Synopsis:
P4_e_t p4ext_stack_destroy(p4ext_stack_t *stack)
Description: Reverse memory mappings and resource allocations performed to create a stack area with p4ext_stack_create() (see section 7.2.3.1). If stack is not the null pointer, and the pointed object is valid, this function reverses the alterations performed by p4ext_stack_create() (see section 7.2.3.1) on the stack area defined by stack. If stack defines a stack area that has been remapped upon creation, this function sets the access to the allocated dynamic memory back to the permissions existing before the stack creation, and unmaps the stack area. If unmapping succeeds, the dynamic memory areas allocated for the stack descriptor and the stack are both freed. The virtual region used to remap the stack is not freed at all.
Parameters: stack [IN] Pointer to stack descriptor object.
Returns: Upon success, this function returns P4_E_OK, otherwise one of the following error codes is returned to the caller: P4_E_INVAL stack is the null pointer. P4_E_INVAL The object pointed to by stack is invalid. P4_E_NOKMEM Allocation of kernel memory for memory mapping failed.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
34 API Reference
7.3 P4EXT_MALLOC: Memory allocation functions
• Memory allocation functions are provided using the standard C language API services. The storage
used to back the memory allocator depends on the process configuration (P4EXT_CONFIG: Process
configuration).
• User API
malloc() (see section 7.3.1.1)
calloc() (see section 7.3.1.2)
realloc() (see section 7.3.1.3)
free() (see section 7.3.1.4)
aligned_alloc() (see section 7.3.1.5)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_MALLOC: Memory allocation functions 35
7.3.1 Functions
7.3.1.1 malloc
Location: p4ext_malloc.h
Synopsis:
void* malloc(size_t size)
Description: Allocate memory. Allocates size bytes of memory and returns a pointer to the start of the allocated memory block.
Parameters: size [IN] Number of bytes to allocate.
Note: If size is 0, a unique pointer that can be successfully passed to free() (see section 7.3.1.4) is returned.
Returns: The function returns a pointer to the start of the allocated memory block upon successful completion, otherwise the null pointer is returned.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
36 API Reference
7.3.1.2 calloc
Location: p4ext_malloc.h
Synopsis:
void* calloc(size_t num, size_t size)
Description: Allocate memory and initialize to zero bytes. Allocates memory for num objects each size bytes in length. The result is indentical with malloc() (see section 7.3.1.1) with an argument of (num * size), with the exception that the allocated memory is explicitly initalized to zero bytes.
Parameters: num [IN] Number of objects to allocate. size [IN] Size of objects.
Note: If size is 0, a unique pointer that can be successfully passed to free() (see section 7.3.1.4) is returned.
Returns: The function returns a pointer to the start of the allocated memory block upon successful completion, otherwise the null pointer is returned.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_MALLOC: Memory allocation functions 37
7.3.1.3 realloc
Location: p4ext_malloc.h
Synopsis:
void* realloc(void *ptr, size_t size)
Description: Change size of a previously allocated memory block. The realloc() (see section 7.3.1.3) function changes the size of the memory object pointed to by ptr to the size specified by size. The contents of the object remain unchanged up to the lesser of the new and old sizes. If the new size of the memory object would require movement of the object, the space for the previous instantiation of the object is freed. If the new size is larger, the contents of the newly allocated portion of the object are unspecified. If size is 0 and ptr is not a null pointer, the object pointed to is freed. If the space cannot be allocated, the object remains unchanged.
Parameters: ptr [IN] Memory block whose size is to be modified. size [IN] New size of memory block pointed to by ptr.
Returns: Upon successful completion with a size not equal to 0, realloc() (see section 7.3.1.3) returns a pointer to the (possibly moved) allocated space. If size is 0, a unique pointer that can be successfully passed to free() (see section 7.3.1.4) is returned. If allocation of memory fails, realloc() (see section 7.3.1.3) returns the null pointer.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
38 API Reference
7.3.1.4 free
Location: p4ext_malloc.h
Synopsis:
void free(void *ptr)
Description: Make a previously allocated memory block available for reallocation. This implementation causes the memory pointed to by ptr to be released. If ptr is the null pointer, no action occurs.
Parameters: ptr [IN] Pointer to memory to be released.
Returns: This function does not return a value.
Note: When using the certifiable variant, this function has no effect.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_MALLOC: Memory allocation functions 39
7.3.1.5 aligned_alloc
Location: p4ext_malloc.h
Synopsis:
void* aligned_alloc(size_t alignment, size_t size)
Description: Allocate aligned memory. Allocate size bytes of aligned memory whose alignment is specified by alignment. The alignment specified by alignment must be a power-of-two, otherwise allocation is not attempted.
Parameters: alignment [IN] Alignment of the memory to allocate. size [IN] Number of bytes to allocate.
Returns: Upon successful completion, the aligned_alloc() (see section 7.3.1.5) function returns a pointer to the start of the allocated memory, otherwise the null pointer is returned.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
40 API Reference
7.4 P4EXT_UTIL: Miscellaneous utility functions
• User API
p4ext_abort() (see section 7.4.1.1)
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_UTIL: Miscellaneous utility functions 41
7.4.1 Functions
7.4.1.1 p4ext_abort
Location: p4ext_util.h
Synopsis:
void p4ext_abort(void)
Description: Abort the program raising an application error to the health monitor.
Note: The function never returns.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
42 API Reference
7.5 P4EXT_VMEM: Virtual memory management functions
• Virtual address space management functions use a region specified in the process configuration
(P4EXT_CONFIG: Process configuration).
• User API
p4ext_vmem_alloc() (see section 7.5.2.1)
p4ext_vmem_alloc_aligned() (see section 7.5.2.2)
7.5.1 Defines
P4EXT_PHYS_ADDR_INVALID
Description:
Invalid physical address.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_VMEM: Virtual memory management functions 43
7.5.2 Functions
7.5.2.1 p4ext_vmem_alloc
Location: p4ext_vmem.h
Synopsis:
P4_address_t p4ext_vmem_alloc(P4_size_t size)
Description: Allocate a virtual address space region. Allocates size bytes of memory and returns the start address of the allocated memory block. The start address is aligned to P4_PAGESIZE.
Parameters: size [IN] Number of bytes to allocate.
Returns: Upon successful completion the address of the allocated virtual region is returned, otherwise the function returns 0.
Note: Allocated regions cannot be freed.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
44 API Reference
7.5.2.2 p4ext_vmem_alloc_aligned
Location: p4ext_vmem.h
Synopsis:
P4_address_t p4ext_vmem_alloc_aligned(P4_size_t size, P4_phys_addr_t addr)
Description: Allocate a virtual address space region suitably aligned for a physical address. Allocates size bytes of memory and returns the start address of the allocated memory block. If addr is aligned with respect to the page size, the start address is suitably aligned to map memory at physical address addr meeting any applicable architecture constraints. The function fails if addr is not page aligned. When the physical address is unknown, e.g. when preparing to use vm_map(), the physical address parameter should be passed as 0.
Parameters: size [IN] Number of bytes to allocate. addr [IN] Physical address for which the virtual region will be used.
Returns: Upon successful completion the address of the allocated virtual region is returned, otherwise the function returns 0.
Note: Allocated regions cannot be freed. After a successful invocation, the decrease in the free region pool may be larger than size.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_ERROR: Thread-specific error number 45
7.6 P4EXT_ERROR: Thread-specific error number
• While the P4EXT services do not use a global error number, support for a thread-specific error number is
part of the TLS initialisation. This module provides access to such a number using the standard definition
of errno (see section 7.6.1). Macro errno (see section 7.6.1) expands to a function returning the location of
the thread-specific error number, compatible with CENV and UniversalisOS/POSIX.
• User API
errno (see section 7.6.1)
7.6.1 Defines
errno
Description:
Error return value.
The macro expands to a modifiable lvalue of type int.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
46 API Reference
7.7 P4EXT_CONFIG: Process configuration
• The process configuration record defines attributes of the UniversalisOS native personality extension services and
attributes of the initial thread. A default record is embedded in the link library, that object can be overridden
by application program configuration.
• User API
p4ext_config (see section 7.7.3)
7.7.1 Structure Definitions
7.7.1.1 struct p4ext_config_s
Process configuration record.
Synopsis:
struct p4ext_config_s { void * stack_start; P4_size_t stack_size; void * vmem_start; P4_size_t vmem_size; const char * heap_pool; P4_size_t heap_size; P4_bool_t heap_exec; P4_size_t trace_size; P4_size_t tls_size; };
Structure Element Description: stack_start Start address of thread stack region. stack_size Size (in bytes) of thread stack region. vmem_start Start address of region for virtual memory allocator. vmem_size Size (in bytes) of region for virtual memory allocator. heap_pool Name of PSSW pool for dynamic memory allocator. heap_size Maximum heap to allocate from pool. heap_exec Heap access set to read-write-execute if true, read-write otherwise. trace_size Size (in bytes) of trace buffer region. tls_size Size of TLS area in bytes.
Associated Data Type
p4ext_config_t
7.7.2 Data Type Definitions
p4ext_config_t Process configuration record.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_CONFIG: Process configuration 47
7.7.3 Variables
p4ext_config Process configuration record.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
48 API Reference
7.8 P4EXT_DIAG: Diagnostics services
• The diagnostics services consist of a diagnostics control word (p4ext_diag (see section 7.8.2), user API),
a function emitting messages to the UniversalisOS console, and a set of macros that conditionally produce
messages depending on the control word.
• The control word contains a combination (bitwise OR) of diagnostics flags such as P4EXT_DIAG_ERR,
P4EXT_DIAG_WARN, or P4EXT_DIAG_TRACE and module identifiers such as P4EXT_DIAG_INIT,
P4EXT_DIAG_HEAP, etc.
Diagnostics flags enable certain types of messages and module identifiers select which modules of the
implementation have diagnostics messages enabled.
• The control word is aliased weakly to a symbol in the library. The control word value can be set using
a UniversalisOS property which is read at process initialisation time, or the value can be set at run-time by the
application programmer. The weak alias also allows application programs to provide their own definition of
the control word (p4ext_diag (see section 7.8.2)) and so set a value that will be valid even before main() is
entered.
User API
∗ p4ext_diag (see section 7.8.2)
∗ p4ext_assert() (see section 7.8.1)
∗ static_assert() (see section 7.8.1)
7.8.1 Defines
p4ext_assert (expr)
Description:
Diagnostics.
Parameters:
expr Expression to be tested.
If expr evaluates to false, the process’ partition is set set to idle mode (VM_PART_MODE_IDLE).
static_assert (expr, message)
Description:
Compile time assertion.
Parameters:
expr Expression to test.
message Informational text, parameter is ignored.
If expr is not true, the macro produces an illegal C language construct to let the source code translation
by the compiler fail. Argument message is currently ignored.
The macro can also be accessed by its C1X name _Static_assert().
P4EXT_DIAG_ERR
Description:
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
P4EXT_DIAG: Diagnostics services 49
Emit diagnostics on function failures, including API return values
P4EXT_DIAG_WARN
Description:
Emit warning diagnostics.
P4EXT_DIAG_TRACE
Description:
Emit function trace diagnostics.
P4EXT_DIAG_INIT
Description:
Enable diagnostics for process initialisation.
P4EXT_DIAG_HEAP
Description:
Enable diagnostics in heap management functions.
P4EXT_DIAG_MALLOC
Description:
Enable diagnostics in memory management functions.
P4EXT_DIAG_THREADS
Description:
Enable diagnostics in thread management functions.
P4EXT_DIAG_VMEM
Description:
Enable diagnostics in virtual memory management functions.
P4EXT_DIAG_UTIL
Description:
Enable diagnostics in miscellaneous utility functions.
P4EXT_DIAG_REGION
Description:
Enable diagnostics in region management functions.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
50 API Reference
P4EXT_DIAG_STACK
Description:
Enable diagnostics in stack management functions.
7.8.2 Variables
p4ext_diag Diagnostics control word.
Contains a combination (bitwise OR) of diagnostics flags such as P4EXT_DIAG_ERR,
P4EXT_DIAG_WARN, or P4EXT_DIAG_TRACE and module identifiers such as P4EXT_DIAG_INIT,
P4EXT_DIAG_HEAP, etc.
Diagnostics flags enable certain types of messages and module identifiers select which modules of the
implementation have diagnostics messages enabled.
Diagnostics messages are printed on the UniversalisOS console.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
A Features Summary
The following tables provide a comparison of the features supported for the regular and the certifiable variants of the UniversalisOS Native personality.
Function Group Regular Certifiable UniversalisOS kernel and system software API Yes Yes Process configuration Yes Partly1 Virtual memory management Yes Yes Simplified thread management Yes Partly2 Simplified stack management Yes No Dynamic memory allocation Yes Partly3 Diagnostics services Yes Partly4 GDB debugging (requires a development library version5 ) Yes Yes C language programming environment (CENV) Yes No6 C++ language programming environment (CPPENV) Yes No Tracing (requires a development library version7 ) Yes No
Table 1: Function groups overview.
Service Regular Certifiable Configuration record defaults Yes Yes Application specific configuration record Yes Yes Alter configuration record with integrator provided settings8 Yes No Validate configuration record Yes Yes
Table 2: Process Configuration.
1 For further details, refer to table 2. 2 For further details, refer to table 3. 3 For further details, refer to table 4. 4 For further details, refer to table 5. 5 libp4ext-dbg.a or libp4ext-dbg-assert.a. 6 The libstand can replace some CENV functionality. Refer to UniversalisOS Standalone Utility Library Reference Manual for more details. 7 libp4ext-trace.a or libp4ext-trace-assert.a. 8 The configuration record is altered in the runtime. Currently implemented for heap parameters only.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
52 Features Summary
Service Regular Certifiable Simplified thread creation9 Yes Yes Simplified thread destruction10 Yes Yes Release of resources allocated for thread creation11 Yes No Thread number management12 Yes No Thread-local storage initialization13 Yes No
Table 3: Simplified thread management.
Service Regular Certifiable PSSW memory pool can be used as source for the heap Yes No Unused process memory can be used as source for the heap Yes Yes Allocated memory can be released for further allocations Yes No Execute permission can be granted to heap memory Yes No
Table 4: Dynamic memory allocation.
Service Regular Certifiable Per functionality tuneable diagnostics messages Yes No Runtime assertion (requires a development library version14 ) Yes Yes Compile time assertion Yes Yes
Table 5: Diagnostics services overview.
9
p4ext_thr_attr_init(), p4ext_thr_create().
10 p4ext_thr_exit(). 11 p4ext_thr_reclaim_resources(). 12 p4ext_thr_num_alloc(), p4ext_thr_num_tryalloc(), p4ext_thr_num_release(), p4ext_thr_gdbstub_alloc(). 13 p4ext_thr_tls_ptr(), p4ext_thr_tls_register(). 14 libp4ext-assert.a, libp4ext-dbg.a or libp4ext-dbg-assert.a.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
53
B Use Cases
This section describes use cases of the UniversalisOS Native personality which demand the integrator and/or developer to change default settings to achieve a functioning system.
B.1 Add Multiple Processes of the Regular Variant to a Partition
Description By default, regular UniversalisOS Native processes are configured to use a memory pool15 , 16 , and try to allocate the whole quantity left in the pool to constitute the heap during the start up (see section 2.4). Also by default, if multiple processes are added to a partition, all try to allocate from the same pool. Only one will succeed the race. The default settings have to be changed, as described in the workflows below, for all processes to succeed.
Basic Workflow The developer and/or integrator changes the heap default size from 0 (means "allocate whole pool") to a finite value. The developer makes the change in the process configuration record, and/or the integrator does it in the "Advanced Process Settings" folder in the UniversalisOS Native process component. The integration project setting overrides the process configuration record.
Alternate Workflow The developer and/or integrator sets a distinct memory pool for each process. As for the heap size parameter, the developer makes the change in the process configuration record, and/or the integrator in the "Advanced Process Settings" folder. In addition, the integrator creates the memory requirements that constitute the pools.
B.2 Add Multiple Processes of the Certifiable Variant to a Partition
Description Adding multiple processes of the certifiable variant to a partition will not work with the configuration defaults. Since certifiable processes do not use a memory pool, the whole memory requirement is reserved to load the application ELF file.
Basic Workflow The integrator sets the "UsePool" option in the "Advanced Process Settings" folder to false in the process components, then turns the process components into inlined components inside the project, and adjusts the name of the memory requirement reserved to each process in the corresponding MemoryRequirement and Map VMIT definitions.
Alternate Workflow No alternate workflow is recommended for this use case. 15 Refer to UniversalisOS System Software Reference Manual, section 2.3.5, page 263, for more details about the process configuration. 16 Refer to UniversalisOS System Software Reference Manual, section 2.3.1, page 259, for more details about the memory pool semantics.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.
54 Use Cases
B.3 Set a Process of the Certifiable Variant to Execute in Place
Description The execute in place method demands an special workflow for functioning with a certifiable UniversalisOS Native process, since the use of a memory pool is excluded for this variant.
Basic Workflow The developer or integrator determines the load address of the data segment of the ELF file to execute in place, e.g., by using the objdump utility. After disabling the use of a memory pool in the "Advanced Process Settings" folder, the integrator changes the virtual address in the process’ Map element to match the load address of the data segment17 .
Alternate Workflow The developer prepares a linker script that sets a fixed load address to the process’ data segment. The developer builds the ELF application file using the customized script by setting the LDSCRIPT variable to the scripts’ path in the project’s makefile.defs file. The integrator proceeds as in the basic workflow.
17 Refer to UniversalisOS User Manual, section E.5, page 266, for more details about the execute in place setup.
c Copyright 2005 – 2019 Portugal Futurista GmbH, all rights reserved.