Difference between pages "r7.1.1:Macro LFDS711 PAL ATOMIC DWCAS" and "r7.1.1:Macro LFDS711 PAL ATOMIC EXCHANGE"

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_DWCAS}}
{{DISPLAYTITLE:macro LFDS711_PAL_ATOMIC_EXCHANGE}}
==Source File==
==Source File==
  └───liblfds711
  └───liblfds711
Line 5: Line 5:
         └───liblfds711
         └───liblfds711
                 lfds711_porting_abstraction_layer_compiler.h
                 lfds711_porting_abstraction_layer_compiler.h
==Enums==
enum [[r7.1.1:enum lfds711_misc_cas_strength|lfds711_misc_cas_strength]]
{
  LFDS711_MISC_CAS_WEAK,
  LFDS711_MISC_CAS_STRONG
};


==Macro==
==Macro==
  #define LFDS711_PAL_ATOMIC_DWCAS( pointer_to_destination, pointer_to_compare, pointer_to_new_destination, cas_strength, result )  [compiler atomic DWCAS instrinsic]
  #define LFDS711_PAL_ATOMIC_EXCHANGE( pointer_to_destination, pointer_to_exchange )  [compiler atomic exchange instrinsic]


==Parameters==
==Parameters==
''pointer_to_destination''
''pointer_to_destination''
: A pointer to an array of two ''lfds711_pal_uint_t volatile''.  The value of ''*pointer_to_destination'' is compared to the value of ''*pointer_to_compare'' and if they are equal, ''*new_value'' is written into ''*pointer_to_destination''.
: The address of a ''liblfds711_pal_uint_t volatile'', which ''*pointer_to_exchange'' will be written to.


''pointer_to_compare''
''pointer_to_exchange''
: A pointer to an array of two ''lfds711_pal_uint_t''.  Whether or not the compare is successful (and so whether or not ''*new_value'' is written into ''*pointer_to_destination''), the original value of ''*pointer_to_destination'' is written into ''*pointer_to_compare'', i.e. the compare value is always lost.
: The address of a ''liblfds711_pal_uint_t'' (non-volatile, but volatile works as well of course), which ''*pointer_to_destination'' will be written to.
 
''pointer_to_new_destination''
: A pointer to an array of two ''lfds711_pal_uint_t''.  This value is written into ''*pointer_to_destination'' if ''*pointer_to_destination'' and ''*pointer_to_compare'' are equal.
 
''cas_strength''
: This argument is only meaningful on LL/SC platforms, and if set to ''LFDS711_MISC_CAS_STRONG'' indicates the macro should internally retry if the LL/SC operation aborted.  See Notes.
 
''result''
: A ''char unsigned'', which is set to 1 if the swap occurred, 0 if not.


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


==Example==
==Example==
  #define LFDS711_PAL_ATOMIC_DWCAS( pointer_to_destination, pointer_to_compare, pointer_to_new_destination, cas_strength, result )                             \
  #define LFDS711_PAL_ATOMIC_EXCHANGE( pointer_to_destination, pointer_to_exchange )                                                                                                 \
  {                                                                                                                                                           \
  {                                                                                                                                                                                 \
   (result) = 0;                                                                                                                                             \
   LFDS711_PAL_BARRIER_COMPILER_FULL;                                                                                                                                               \
                                                                                                                                                              \
   *(lfds711_pal_uint_t *) (pointer_to_exchange) = (lfds711_pal_uint_t) _InterlockedExchange( (int long volatile *) (pointer_to_destination), (int long) *(pointer_to_exchange) )\
  __asm__ __volatile__                                                                                                                                      \
   LFDS711_PAL_BARRIER_COMPILER_FULL;                                                                                                                                               \
   (                                                                                                                                                         \
    "lock;"          /* make cmpxchg16b atomic        */                                                                                                    \
    "cmpxchg16b %0;"  /* cmpxchg16b sets ZF on success */                                                                                                    \
    "setz      %4;"  /* if ZF set, set result to 1    */                                                                                                    \
                                                                                                                                                              \
    /* output */                                                                                                                                            \
    : "+m" ((pointer_to_destination)[0]), "+m" ((pointer_to_destination)[1]), "+a" ((pointer_to_compare)[0]), "+d" ((pointer_to_compare)[1]), "=q" (result) \
                                                                                                                                                              \
    /* input */                                                                                                                                              \
    : "b" ((pointer_to_new_destination)[0]), "c" ((pointer_to_new_destination)[1])                                                                          \
                                                                                                                                                              \
    /* clobbered */                                                                                                                                          \
    :                                                                                                                                                        \
   );                                                                                                                                                         \
  }
  }
#endif


==Optionality==
==Optionality==
Line 62: Line 31:


==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 arranged to work doesn't map directly to the atomic intrinsic prototype for that platform).  We see this here in the example.
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).


The actual atomic intrinsic if it does not inherently provide compiler barriers itself MUST be immediately preceeded and followed by ''LFDS711_PAL_BARRIER_COMPILER_FULL''.  This is to prevent compiler re-ordering.
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.
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.
The example here is for a platform (x64 GCC) where the processor supports DWCAS, but where the compiler has no intrinsic for this operation.  As such, it is necessary to directly issue the necessary assembly instructions.


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.
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.

Latest revision as of 18:12, 16 February 2017

Source File

└───liblfds711
    └───inc
        └───liblfds711
                lfds711_porting_abstraction_layer_compiler.h

Macro

#define LFDS711_PAL_ATOMIC_EXCHANGE( pointer_to_destination, pointer_to_exchange )  [compiler atomic exchange instrinsic]

Parameters

pointer_to_destination

The address of a liblfds711_pal_uint_t volatile, which *pointer_to_exchange will be written to.

pointer_to_exchange

The address of a liblfds711_pal_uint_t (non-volatile, but volatile works as well of course), which *pointer_to_destination will be written to.

Return Value

No return value.

Example

#define LFDS711_PAL_ATOMIC_EXCHANGE( pointer_to_destination, pointer_to_exchange )                                                                                                 \
{                                                                                                                                                                                  \
  LFDS711_PAL_BARRIER_COMPILER_FULL;                                                                                                                                               \
  *(lfds711_pal_uint_t *) (pointer_to_exchange) = (lfds711_pal_uint_t) _InterlockedExchange( (int long volatile *) (pointer_to_destination), (int long) *(pointer_to_exchange) );  \
  LFDS711_PAL_BARRIER_COMPILER_FULL;                                                                                                                                               \
}

Optionality

This macro is optional. If it is not given, the macro must be absent, rather than empty.

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).

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.

See Also