r6.1.1:Porting Guide (test)

Introduction

There are four issues when it comes to porting the test program;

1. The test program needs to run multiple concurrent threads and the API for thread management varies by platform.
2. The number of threads issued is a multiple of the number of CPUs and the API for determining the number of CPUs varies by platform.
3. To test atomic instructions, threads must not be running on the same CPU, so the test programmes needs to indicate thread affinity
4. The prototype for a thread function varies by platform.

In response to these issues, the test program implements an abstraction layer. The abstraction layer provides to the test program a standard API for these platform dependent functions. Porting consists of implementing these functions on your platform.

Detailed Platform Requirements

To port the test program, the target platform must provide;

• a function to start a thread which pins the thread to a given CPU
• a function to wait for a thread to terminate
• the type of the value returned by the thread function prototype
• the type used for thread state

The Abstraction Layer

At this point in the guide, you should briefly open the abstraction layer API page, abstraction (test), to get an overview of the API function prototypes, defines and typedefs.

Each function, define and typedef has a wiki page and those pages contain detailed information and examples specifically written with implementation in mind.

Implementing the Abstraction Layer

Implementing the abstraction layer requires;

• implementing the three abstraction layer functions;
  • a function for finding the number of CPUs
  • a function for starting a thread and pinning it to a gievn CPU
  • a function for waiting for a thread to terminate
• providing the necessary set of typedefs and defines in lfds611_abstraction.h;
  • a type for lfds611_thread_state_t
  • a type for lfds611_thread_return_t
  • #including any header files needed for your platform

The location of the functions and typedefs in the source files is as follows;

File	Function
/test/src/lfds611_abstraction_cpu_count.c	lfds611_abstraction_cpu_count
/test/src/lfds611_abstraction_thread_start.c	lfds611_abstraction_thread_start
/test/src/lfds611_abstraction_thread_wait.c	lfds611_abstraction_thread_wait
/test/src/lfds611_abstraction.h	the typedefs and includes

When you come to implement, you will be adding your code alongside other existing implementations for other platforms. You must guard each function by an #if, such that it is only seen by platforms which can use that implementation. The typedefs in abstraction.h are similarly guarded by an identical #if.

So for example, lfds611_abstraction_cpu_count in lfds611_abstraction_cpu_count.c, on Windows looks like this;

 /****************************************************************************/
 #if (defined _WIN32 && defined _MSC_VER && !defined WIN_KERNEL_BUILD)
 
   /* TRD : any Windows (user-mode) on any CPU with the Microsoft C compiler
 
            _WIN32             indicates 64-bit or 32-bit Windows
            _MSC_VER           indicates Microsoft C compiler
            !WIN_KERNEL_BUILD  indicates Windows user-mode
   */
 
   unsigned int abstraction_cpu_count()
   {
     SYSTEM_INFO
       si;
 
     GetNativeSystemInfo( &si );
 
     return( (unsigned int) si.dwNumberOfProcessors );
   }
 
 #endif

And the typedefs in lfds611_abstraction.h on Windows look like this;

 #if (defined _WIN32 && defined _MSC_VER && !defined WIN_KERNEL_BUILD)
   /* TRD : any Windows (user-mode) on any CPU with the Microsoft C compiler
 
            _WIN32             indicates 64-bit or 32-bit Windows
            _MSC_VER           indicates Microsoft C compiler
            !WIN_KERNEL_BUILD  indicates Windows user-mode
   */
 
   #include <windows.h>
   typedef HANDLE              thread_state_t;
   typedef DWORD               thread_return_t;
   #define CALLING_CONVENTION  WINAPI
 #endif

(Note that CALLING_CONVENTION is a Windows-only concept and can always be left empty on other platforms).

The abstraction layer API root document page is abstraction (test).

Each abstraction layer function and typedef has a wiki page. Those pages contain detailed information and examples specifically written with implementation in mind. Refer to those pages for the information you need when you come to implement.

See Also

• abstraction (test)