Difference between pages "r7.1.1:Macro LFDS711 PAL ATOMIC SET" and "r7.1.1:Function libbenchmark misc pal helper add logical processor node to topology tree"

From liblfds.org
(Difference between pages)
Jump to navigation Jump to search
m (1 revision imported)
 
m (1 revision imported)
 
Line 1: Line 1:
{{DISPLAYTITLE:macro LFDS711_PAL_ATOMIC_SET}}
{{DISPLAYTITLE:function libbenchmark_misc_pal_helper_new_topology_node}}
==Source File==
==Source Files==
  └───liblfds711
  └───test_and_benchmark
     └───inc
     └───libbenchmark
         └───liblfds711
         ├───inc
                lfds711_porting_abstraction_layer_compiler.h
        │  └───libbenchmark
        │          libbenchmark_porting_abstraction_layer.h
        └───src
            └───libbenchmark_misc
                    libbenchmark_misc_pal_helpers.c


==Macro==
==Opaque Structures==
  #define LFDS711_PAL_ATOMIC_SET( pointer_to_destination, exchange ) [compiler atomic exchange (not set - see below) instrinsic]
  struct [[r7.1.1:struct libbenchmark_topology_state|libbenchmark_topology_state]];
 
==Prototype==
void libbenchmark_misc_pal_helper_add_logical_processor_node_to_topology_tree( struct libbenchmark_topology_state *ts,
                                                                                lfds711_pal_uint_t logical_processor_number,
                                                                                enum flag windows_processor_group_inuse_flag,
                                                                                lfds711_pal_uint_t windows_processor_group_number );


==Parameters==
==Parameters==
''pointer_to_destination''
''struct libbenchmark_topology_state *ts''
: The address of a ''liblfds711_pal_uint_t volatile'', which ''*pointer_to_exchange'' will be written to.
: A pointer a ''struct libbenchmark_topology'' obtained from ''libbenchmark_pal_populate_topology''.


''exchange''
''lfds711_pal_uint_t logical_processor_number''
: A ''liblfds711_pal_uint_t'' which will be written into ''*pointer_to_destination''.
: The logical processor number of the logical processor to add to the topology tree pointed to by ''ts''.
 
''enum flag windows_processor_group_inuse_flag''
: An ''enum flag'' which indicates whether or not the ''windows_processor_group_number'' argument contains a valid value (for that field is only meaningful on Windows 7 and greater).
 
''lfds711_pal_uint_t windows_processor_group_number''
: The Windows processor group number of the logical processor to add to the topology tree pointed to by ''ts''.  This value is only meaningful on Windows 7 and greater.  It will only be used if the ''windows_processor_group_inuse_flag'' is set to ''RAISED'', and so if not used, can be set to any value.  Zero is as good a choice as any other.


==Return Value==
==Return Value==
Line 20: Line 36:


==Example==
==Example==
#define LFDS711_PAL_ATOMIC_SET( pointer_to_destination, new_value )        \
{                                                                          \
  LFDS711_PAL_BARRIER_COMPILER_FULL;                                      \
  (void) __sync_lock_test_and_set( pointer_to_destination, (new_value) );  \
  LFDS711_PAL_BARRIER_COMPILER_FULL;                                      \
}
==Optionality==
This macro is optional. If it is not given, the macro must be absent, rather than empty.


==Notes==
==Notes==
All of the atomic operation macros open and close with curley braces as some of them need to declare variables on the stack, so that they can operate in ways which match their 'prototype' (i.e. they may need a bit of temporary storage, as the way in which the macro is prototyped doesn't map directly to the atomic intrinsic prototype for that platform).
This helper function is used by ''libbenchmark_pal_populate_topology'' to add a logical processor node to the topology tree.
 
The actual atomic intrinsic itself MUST be immediately preceeded and followed by ''LFDS711_PAL_BARRIER_COMPILER_FULL''.  This is to prevent compiler re-ordering.
 
Finally, we get to the actual atomic operation itself.  The ''liblfds711_pal_uint_t'' types need to be cast to the types the intrinsic expects, and to the maximum extent possible eschew any memory barriers.  On ARM, for example, memory barriers and atomic operations are wholly seperated and on that platform, the operation is and is only an atomic operation.  The data structures themselves issue memory barriers as and when they must, and any additional barriers issued within the atomic macros are only overhead.  On x86 and x64, sadly, memory barriers are built into the atomic operations and cannot be removed.  On Itanium, it looks like atomic operations must occur with a barrier, but it is possible to choose a load, store or full barrier, and as such on that platform, the load barrier is always used, as it is the lowest cost of the three.
 
If this atomic operaton is not available, the macro must be left undefined, which will lead to a placeholder version automatically being used.  This placeholder version if called first calls ''LFDS711_PAL_ASSERT'' and then, assuming execution has continued (i.e. ''LFDS711_PAL_ASSERT'' is not defined, or is defined but this is a release user-mode build and so asserts are not being checked) will attempt to write 0 into memory location 0, to deliberately crash.
 
The SET operation is really an EXCHANGE but where the original value is thrown away.  This turns out to be useful in terms of C syntax.  As mentioned above, all of the atomic macros are defined with curley braces.  As such they cannot return values - rather, a pointer must be passed in, and the variable pointer to set to the value returned.  Unfortunately, though, in the source code, a number of different variable types are passed to EXCHANGE, and this, combined with strict aliasing, leads to irreconcilable warnings.  Either there's a warning about types, or a warning about breaking strict aliasing.  The SET macro however throws away the return value and so this problem goes away, reducing the use of EXCHANGE to only situations where there are no variable type warnings.
 
There is in ''libtest'' no test for the behaviour of this macro.  This is because it is impossible to test that a SET-style semantic macro is working correctly, as the original value is not available.  It is possible to test an EXCHANGE-style semantic macro, because the original value is returned, and this test exists in ''libtest''.  When implementing this macro, take the EXCHANGE macro, which should be passing its test, and simply throw away the return value.  Some compilers require the return value to be cast to ''(void)'', or they will throw a warning, and this can be seen in the example.


==See Also==
==See Also==
* [[r7.1.1:Porting Guide (liblfds)|Porting Guide (liblfds)]]
* [[r7.1.1:Porting Guide (libbenchmark)|Porting Guide (libbenchmark)]]
* ''[[r7.1.1:function libbenchmark_pal_populate_topology|libbenchmark_pal_populate_topology]]''

Latest revision as of 20:16, 17 February 2017

Source Files

└───test_and_benchmark
    └───libbenchmark
        ├───inc
        │   └───libbenchmark
        │           libbenchmark_porting_abstraction_layer.h
        └───src
            └───libbenchmark_misc
                    libbenchmark_misc_pal_helpers.c

Opaque Structures

struct libbenchmark_topology_state;

Prototype

void libbenchmark_misc_pal_helper_add_logical_processor_node_to_topology_tree( struct libbenchmark_topology_state *ts,
                                                                               lfds711_pal_uint_t logical_processor_number,
                                                                               enum flag windows_processor_group_inuse_flag,
                                                                               lfds711_pal_uint_t windows_processor_group_number );

Parameters

struct libbenchmark_topology_state *ts

A pointer a struct libbenchmark_topology obtained from libbenchmark_pal_populate_topology.

lfds711_pal_uint_t logical_processor_number

The logical processor number of the logical processor to add to the topology tree pointed to by ts.

enum flag windows_processor_group_inuse_flag

An enum flag which indicates whether or not the windows_processor_group_number argument contains a valid value (for that field is only meaningful on Windows 7 and greater).

lfds711_pal_uint_t windows_processor_group_number

The Windows processor group number of the logical processor to add to the topology tree pointed to by ts. This value is only meaningful on Windows 7 and greater. It will only be used if the windows_processor_group_inuse_flag is set to RAISED, and so if not used, can be set to any value. Zero is as good a choice as any other.

Return Value

No return value.

Example

Notes

This helper function is used by libbenchmark_pal_populate_topology to add a logical processor node to the topology tree.

See Also

Retrieved from ‘https://www.liblfds.org/mediawiki/index.php?title=r7.1.1:Macro_LFDS711_PAL_ATOMIC_SET&oldid=1113’